{"record":{"id":"c1ee576b3350addb","repo":"gastownhall/beads","slug":"resolve-workspace-identity-w","errorCode":null,"errorMessage":"resolve workspace identity: %w","messagePattern":"resolve workspace identity: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/proxy/shutdown.go","lineNumber":377,"sourceCode":"\t\ttime.Sleep(shutdownConfirmPoll)\n\t}\n}\n\nfunc validateKillRecord(\n\trootDir string,\n\tpf *pidfile.PidFile,\n\twantKind string,\n\tchecks killRecordChecks,\n) error {\n\tif err := pf.ValidateV2(wantKind); err != nil {\n\t\treturn err\n\t}\n\tif !checks.VerifyRoot {\n\t\treturn nil\n\t}\n\trootID, err := identity.RootID(rootDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"resolve workspace identity: %w\", err)\n\t}\n\tif pf.RootID != rootID {\n\t\treturn fmt.Errorf(\"root identity mismatch (record has %q, workspace has %q)\", pf.RootID, rootID)\n\t}\n\treturn nil\n}\n\nfunc classifyInvalidKillRecord(pf *pidfile.PidFile, validationErr error) (dead bool, live bool, err error) {\n\tif !isPIDFileValidationError(validationErr) {\n\t\treturn false, false, nil\n\t}\n\treturn probeUnverifiablePID(pf.Pid)\n}\n\nfunc isPIDFileValidationError(err error) bool {\n\treturn errors.Is(err, pidfile.ErrLegacySchema) ||\n\t\terrors.Is(err, pidfile.ErrBadPid) ||\n\t\terrors.Is(err, pidfile.ErrBadPort) ||","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/proxy/shutdown.go#L359-L395","documentation":"This error wraps a failure from identity.RootID() while validating a pidfile kill-record during proxy shutdown. The proxy records the workspace root identity (derived from the root directory) in its pidfile and re-checks it before force-stopping a stale daemon. If the workspace root ID cannot be resolved (e.g. the directory is unreadable or has no stable identity), validation aborts with this wrapped error rather than killing a process with unknown ownership.","triggerScenarios":"stopAndAcquire -> validateKillRecord calls identity.RootID(rootDir), which returns an error (unreadable root dir, missing temp/lock artifacts the identity derivation depends on, permission issues).","commonSituations":"Running `bd` in a directory that was moved/renamed after the daemon started; running with insufficient permissions on the workspace root; deleting parts of the workspace (e.g. .beads metadata) that identity.RootID uses to derive a stable ID.","solutions":["Re-create the workspace metadata so identity.RootID can resolve the root directory (run bd doctor or reinitialize the project in place).","Verify the root directory exists, is readable by the current user, and was not renamed since the daemon started.","Stop any stale daemon by hand (kill the recorded PID) and remove the stale pidfile, then restart.","Check file permissions on the workspace root (ls -ld) and re-run with correct ownership."],"exampleFix":"// before: root dir moved, pidfile references old identity\n$ bd doctor\n// after: restore/reinit workspace then retry\n$ cd /correct/workspace && bd doctor && bd ...","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(rootDir); err != nil {\n    return fmt.Errorf(\"workspace root unreadable before proxy stop: %w\", err)\n}\nif _, err := identity.RootID(rootDir); err != nil {\n    // resolve identity up front so validateKillRecord cannot fail\n    return err\n}","typeGuard":null,"tryCatchPattern":"if _, err := stopAndAcquire(ctx); err != nil {\n    if errors.Is(err, errIdentityUnresolvable) || strings.Contains(err.Error(), \"resolve workspace identity\") {\n        // fall back to manual pidfile cleanup\n    }\n}","preventionTips":["Do not rename or move a workspace directory while a bd daemon is running.","Keep the workspace root readable by every user/account that runs bd commands.","Do not delete workspace metadata directories (.beads) while daemons hold pidfiles.","Run bd doctor periodically to catch identity/pidfile drift early."],"tags":["go","filesystem","workspace-identity","pidfile"],"backgroundTag":"workspace-identity-mismatch","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}