@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/dist/daemon/worktree-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-manager.d.ts","sourceRoot":"","sources":["../../src/daemon/worktree-manager.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomInt } from \"node:crypto\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { mkdir, readdir, realpath, rename } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from \"node:path\";\nimport type { IrohRemoteAuditLogger } from \"../core/remote/iroh/audit.ts\";\nimport { IROH_REMOTE_WORKTREE_ID_PATTERN } from \"../core/remote/iroh/protocol.ts\";\nimport type { IrohRemoteWorkspace, IrohRemoteWorkspaceWorktree } from \"../core/remote/iroh/state.ts\";\nimport {\n\ttype IrohRemoteHostStateManager,\n\tisIrohRemoteWorktreeParentWorkspaceNotFoundError,\n\tisIrohRemoteWorktreePersistenceError,\n} from \"../core/remote/iroh/state-manager.ts\";\nimport { spawnProcess, waitForChildProcess } from \"../utils/child-process.ts\";\nimport type { ControlRequest, ControlWorktreeStatus } from \"./control-protocol.ts\";\nimport type { ControlConnection } from \"./control-server.ts\";\nimport { resolveWorkspaceDirectory, type WorkspaceDirectoryResolution } from \"./workspace-directory.ts\";\n\n/** join(agentDir, \"worktrees\") — sibling of sessions/, daemon/, trust.json. */\nexport function getWorktreesRoot(agentDir: string): string {\n\treturn join(resolve(agentDir), \"worktrees\");\n}\n\nexport const WORKTREE_ID_PATTERN = IROH_REMOTE_WORKTREE_ID_PATTERN;\n\n/**\n * Encode a workspace path into the per-workspace worktrees directory segment,\n * reusing the `--<encoded-cwd>--` scheme from the session dirs so the layout\n * survives workspace renames. Long encodings are shortened with a hash suffix\n * to stay clear of Windows MAX_PATH limits.\n */\nfunction getWorkspaceWorktreesSegment(workspacePath: string): string {\n\tconst encoded = resolve(workspacePath)\n\t\t.replace(/^[/\\\\]/, \"\")\n\t\t.replace(/[/\\\\:]/g, \"-\");\n\tif (encoded.length <= 80) {\n\t\treturn `--${encoded}--`;\n\t}\n\tconst digest = createHash(\"sha1\").update(encoded).digest(\"hex\").slice(0, 8);\n\treturn `--${encoded.slice(0, 72)}-${digest}--`;\n}\n\n/** Per-workspace directory holding that workspace's worktree checkouts. */\nexport function getWorkspaceWorktreesDir(agentDir: string, workspacePath: string): string {\n\treturn join(getWorktreesRoot(agentDir), getWorkspaceWorktreesSegment(workspacePath));\n}\n\n/**\n * Deterministic checkout path; the ONLY producer of checkout paths. Validates\n * the id and asserts the resolved path stays under the worktrees root — never\n * accepts a caller-supplied path.\n */\nexport function getWorktreeCheckoutPath(agentDir: string, workspacePath: string, worktreeId: string): string {\n\tif (!WORKTREE_ID_PATTERN.test(worktreeId)) {\n\t\tthrow new Error(`invalid worktree id: ${worktreeId}`);\n\t}\n\tconst root = resolve(getWorktreesRoot(agentDir));\n\tconst checkoutPath = resolve(join(getWorkspaceWorktreesDir(agentDir, workspacePath), worktreeId));\n\tconst rootPrefix = `${root}${sep}`;\n\tconst contained =\n\t\tprocess.platform === \"win32\"\n\t\t\t? checkoutPath.toLowerCase().startsWith(rootPrefix.toLowerCase())\n\t\t\t: checkoutPath.startsWith(rootPrefix);\n\tif (!contained) {\n\t\tthrow new Error(\"worktree checkout path escapes the worktrees root\");\n\t}\n\treturn checkoutPath;\n}\n\n/**\n * Convert a path relative to a daemon-managed worktree checkout back into the\n * registered-workspace-relative path used on the remote protocol. Nested repo\n * worktrees store sourceRootRelativePath (e.g. `Volt`), so a worktree cwd of\n * `packages/coding-agent` displays as `Volt/packages/coding-agent`.\n */\nexport function getRegisteredWorkingDirectoryForWorktree(\n\tworktree: Pick<IrohRemoteWorkspaceWorktree, \"sourceRootRelativePath\">,\n\tworktreeRelativePath?: string,\n): string | undefined {\n\tif (worktree.sourceRootRelativePath === undefined) {\n\t\treturn worktreeRelativePath;\n\t}\n\treturn worktreeRelativePath === undefined\n\t\t? worktree.sourceRootRelativePath\n\t\t: posix.join(worktree.sourceRootRelativePath, worktreeRelativePath);\n}\n\n/** win32-aware \"path is inside root\" prefix check on resolved paths. */\nfunction isPathContained(root: string, path: string): boolean {\n\tconst resolvedRoot = resolve(root);\n\tconst resolvedPath = resolve(path);\n\tconst rootPrefix = `${resolvedRoot}${sep}`;\n\tif (process.platform === \"win32\") {\n\t\tconst lowerPath = resolvedPath.toLowerCase();\n\t\treturn lowerPath === resolvedRoot.toLowerCase() || lowerPath.startsWith(rootPrefix.toLowerCase());\n\t}\n\treturn resolvedPath === resolvedRoot || resolvedPath.startsWith(rootPrefix);\n}\n\n/** True when path is inside the daemon's worktrees root (a daemon-managed checkout or below). */\nexport function isPathUnderWorktreesRoot(agentDir: string, path: string): boolean {\n\tconst root = resolve(getWorktreesRoot(agentDir));\n\tconst resolved = resolve(path);\n\treturn resolved !== root && isPathContained(root, resolved);\n}\n\n/**\n * Resolve the PARENT checkout of a daemon-managed worktree from the checkout's\n * `.git` gitdir pointer (`gitdir: <parent>/.git/worktrees/<id>`), without a\n * daemon round-trip or a git subprocess. Returns undefined when the path is\n * not under the worktrees root or the pointer cannot be parsed. Used by the\n * TUI to pin trust decisions to the parent workspace path — trust entries are\n * never prompted for or persisted on worktree paths (design §5.1.9/§5.2.1).\n */\nexport function resolveWorktreeParentCheckout(agentDir: string, path: string): string | undefined {\n\tif (!isPathUnderWorktreesRoot(agentDir, path)) {\n\t\treturn undefined;\n\t}\n\tconst root = resolve(getWorktreesRoot(agentDir));\n\tconst relativeSegments = resolve(path)\n\t\t.slice(root.length + 1)\n\t\t.split(sep)\n\t\t.filter((segment) => segment.length > 0);\n\tif (relativeSegments.length < 2) {\n\t\treturn undefined;\n\t}\n\t// Layout: <root>/<encoded-workspace-segment>/<worktreeId>/...\n\tconst checkoutPath = join(root, relativeSegments[0] ?? \"\", relativeSegments[1] ?? \"\");\n\tlet gitFileContents: string;\n\ttry {\n\t\tgitFileContents = readFileSync(join(checkoutPath, \".git\"), \"utf8\");\n\t} catch {\n\t\treturn undefined;\n\t}\n\tconst match = gitFileContents.match(/^gitdir:\\s*(.+)\\s*$/m);\n\tif (!match?.[1]) {\n\t\treturn undefined;\n\t}\n\tconst gitDir = match[1].trim();\n\tif (!isAbsolute(gitDir)) {\n\t\treturn undefined;\n\t}\n\t// gitDir is <parent>/.git/worktrees/<name>; the parent checkout is three levels up.\n\tconst worktreesDir = dirname(resolve(gitDir));\n\tconst dotGitDir = dirname(worktreesDir);\n\tif (worktreesDir.split(sep).pop() !== \"worktrees\" || dotGitDir.split(sep).pop() !== \".git\") {\n\t\treturn undefined;\n\t}\n\treturn dirname(dotGitDir);\n}\n\nexport type WorktreeRelayGate = { ok: true } | { ok: false; reason: \"checkout_missing\" | \"tui_not_capable\" };\n\n/**\n * Gate a worktree-bound conversation relay: the checkout must exist and the\n * owning TUI must have advertised the worktrees control capability. Old TUIs\n * (no capability) are never offered worktree-session relays (design §5.2.3).\n */\nexport function evaluateWorktreeRelayGate(\n\tworktree: { path: string } | undefined,\n\ttuiCapabilities: ReadonlySet<string> | undefined,\n\tworktreesCapability: string,\n): WorktreeRelayGate {\n\tif (worktree === undefined) {\n\t\treturn { ok: true };\n\t}\n\tif (!existsSync(worktree.path)) {\n\t\treturn { ok: false, reason: \"checkout_missing\" };\n\t}\n\tif (tuiCapabilities === undefined || !tuiCapabilities.has(worktreesCapability)) {\n\t\treturn { ok: false, reason: \"tui_not_capable\" };\n\t}\n\treturn { ok: true };\n}\n\nexport type WorktreeError =\n\t| \"not_a_git_repository\"\n\t| \"worktree_exists\"\n\t| \"worktree_branch_conflict\"\n\t| \"worktree_not_found\"\n\t| \"worktree_dirty\"\n\t| \"worktree_busy\"\n\t| \"worktree_limit_reached\"\n\t| \"worktree_source_unregistered\"\n\t| \"invalid_worktree_id\"\n\t| \"invalid_working_directory\"\n\t| \"nested_git_repository_unsupported\"\n\t| \"git_failed\";\n\nexport type WorktreeGitRunner = (\n\targs: string[],\n\tcwd: string,\n) => Promise<{ ok: boolean; code: number | null; stdout: string; stderr: string }>;\n\nexport interface WorktreeManagerOptions {\n\tagentDir: string;\n\tstateManager: IrohRemoteHostStateManager;\n\tauditLogger: IrohRemoteAuditLogger;\n\t/** Injectable for tests; defaults to a spawnProcess/waitForChildProcess wrapper. */\n\trunGit?: WorktreeGitRunner;\n\t/** Max worktrees per workspace (default 16). */\n\tmaxWorktreesPerWorkspace?: number;\n\t/** Seam for \"is a runtime using this worktree\" (wired to IntegratedRuntimeRegistry). */\n\thasActiveRuntimeForSession?: (workspaceName: string, sessionId: string) => boolean;\n\t/** Durable-write seam (VoltdStateStore.flush); records must survive a crash the moment they exist. */\n\tflushState?: () => Promise<void>;\n\tnow?: () => number;\n}\n\nexport interface WorktreeStatus extends IrohRemoteWorkspaceWorktree {\n\t/** Checkout directory exists and `git worktree list` still knows it. */\n\tavailable: boolean;\n\t/** `git status --porcelain` non-empty, i.e. has uncommitted work (best-effort; undefined when unavailable). */\n\tdirty?: boolean;\n\t/** Branch commits vs the base ref (`git rev-list --left-right --count`); undefined when unavailable. */\n\taheadBehind?: { ahead: number; behind: number };\n}\n\nexport type WorktreeResult<T> = ({ ok: true } & T) | { ok: false; error: WorktreeError; detail?: string };\n\ninterface WorktreeSourceResolution {\n\t/** Selected directory under the registered workspace, preserving the remote relative path. */\n\tworkspaceDirectory: WorkspaceDirectoryResolution;\n\t/** Git repository root used as `git worktree add` cwd. Host-local; never sent on the wire. */\n\tsourceRootPath: string;\n\t/** Registered-workspace-relative git repository root. Undefined means the registered workspace root. */\n\tsourceRootRelativePath?: string;\n\t/** Selected cwd relative to the git repository root. Undefined means the repo root. */\n\tworkingDirectoryRelativePath?: string;\n}\n\nconst DEFAULT_MAX_WORKTREES_PER_WORKSPACE = 16;\n\nconst SLUG_ADJECTIVES = [\"amber\", \"brisk\", \"calm\", \"dusky\", \"eager\", \"fresh\", \"keen\", \"lucid\", \"quiet\", \"swift\"];\nconst SLUG_NOUNS = [\"basin\", \"cedar\", \"delta\", \"ember\", \"grove\", \"harbor\", \"mesa\", \"ridge\", \"summit\", \"vale\"];\n\nfunction generateWorktreeIdSlug(): string {\n\tconst adjective = SLUG_ADJECTIVES[randomInt(SLUG_ADJECTIVES.length)];\n\tconst noun = SLUG_NOUNS[randomInt(SLUG_NOUNS.length)];\n\treturn `${adjective}-${noun}-${String(randomInt(100)).padStart(2, \"0\")}`;\n}\n\n/** Default runner: no shell, argv only, captured stdio. */\nexport function createDefaultWorktreeGitRunner(): WorktreeGitRunner {\n\treturn async (args, cwd) => {\n\t\ttry {\n\t\t\tconst child = spawnProcess(\"git\", args, { cwd, stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\t\tlet stdout = \"\";\n\t\t\tlet stderr = \"\";\n\t\t\tchild.stdout?.setEncoding(\"utf8\");\n\t\t\tchild.stderr?.setEncoding(\"utf8\");\n\t\t\tchild.stdout?.on(\"data\", (chunk: string) => {\n\t\t\t\tstdout += chunk;\n\t\t\t});\n\t\t\tchild.stderr?.on(\"data\", (chunk: string) => {\n\t\t\t\tstderr += chunk;\n\t\t\t});\n\t\t\tconst code = await waitForChildProcess(child);\n\t\t\treturn { ok: code === 0, code, stdout, stderr };\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tconst detail = message.includes(\"ENOENT\") ? \"git not found on daemon PATH; see docs/daemon.md\" : message;\n\t\t\treturn { ok: false, code: null, stdout: \"\", stderr: detail };\n\t\t}\n\t};\n}\n\n/**\n * Basic `git check-ref-format`-equivalent syntax gate for branch/baseRef\n * values. Rejects option injection (leading '-') and git-invalid ref\n * sequences; values are always passed as separate argv entries.\n */\nexport function isValidGitRefSyntax(ref: string): boolean {\n\tif (ref.length === 0 || ref.length > 255 || ref.startsWith(\"-\")) {\n\t\treturn false;\n\t}\n\tif (/[\\s~^:?*[\\\\\\x00-\\x1f\\x7f]/.test(ref)) {\n\t\treturn false;\n\t}\n\tif (ref.includes(\"..\") || ref.includes(\"@{\") || ref.includes(\"//\")) {\n\t\treturn false;\n\t}\n\tif (ref.startsWith(\"/\") || ref.endsWith(\"/\") || ref.endsWith(\".\") || ref.endsWith(\".lock\")) {\n\t\treturn false;\n\t}\n\treturn true;\n}\n\nexport class WorktreeManager {\n\tprivate readonly agentDir: string;\n\tprivate readonly stateManager: IrohRemoteHostStateManager;\n\tprivate readonly auditLogger: IrohRemoteAuditLogger;\n\tprivate readonly runGit: WorktreeGitRunner;\n\tprivate readonly maxWorktreesPerWorkspace: number;\n\tprivate readonly hasActiveRuntimeForSession: ((workspaceName: string, sessionId: string) => boolean) | undefined;\n\tprivate readonly flushState: (() => Promise<void>) | undefined;\n\tprivate readonly now: () => number;\n\n\tconstructor(options: WorktreeManagerOptions) {\n\t\tthis.agentDir = options.agentDir;\n\t\tthis.stateManager = options.stateManager;\n\t\tthis.auditLogger = options.auditLogger;\n\t\tthis.runGit = options.runGit ?? createDefaultWorktreeGitRunner();\n\t\tthis.maxWorktreesPerWorkspace = options.maxWorktreesPerWorkspace ?? DEFAULT_MAX_WORKTREES_PER_WORKSPACE;\n\t\tthis.hasActiveRuntimeForSession = options.hasActiveRuntimeForSession;\n\t\tthis.flushState = options.flushState;\n\t\tthis.now = options.now ?? Date.now;\n\t}\n\n\t/** git worktree add; persists the record durably after git succeeds. */\n\tasync create(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\toptions: { id?: string; branch?: string; baseRef?: string; workingDirectory?: string } = {},\n\t): Promise<WorktreeResult<{ worktree: IrohRemoteWorkspaceWorktree }>> {\n\t\tconst id = options.id ?? generateWorktreeIdSlug();\n\t\tif (!WORKTREE_ID_PATTERN.test(id)) {\n\t\t\treturn { ok: false, error: \"invalid_worktree_id\" };\n\t\t}\n\t\tconst branch = options.branch ?? `volt/${id}`;\n\t\tconst baseRef = options.baseRef ?? \"HEAD\";\n\t\tif (!isValidGitRefSyntax(branch)) {\n\t\t\treturn { ok: false, error: \"git_failed\", detail: \"invalid branch ref syntax\" };\n\t\t}\n\t\tif (!isValidGitRefSyntax(baseRef)) {\n\t\t\treturn { ok: false, error: \"git_failed\", detail: \"invalid baseRef ref syntax\" };\n\t\t}\n\n\t\ttry {\n\t\t\tconst result = await this.stateManager.runWorkspaceWorktreeLifecycle<\n\t\t\t\tWorktreeResult<{ worktree: IrohRemoteWorkspaceWorktree }>\n\t\t\t>(workspace.name, async ({ workspace: registeredWorkspace, worktrees: existing }) => {\n\t\t\t\tif (existing.length >= this.maxWorktreesPerWorkspace) {\n\t\t\t\t\treturn { result: { ok: false, error: \"worktree_limit_reached\" } };\n\t\t\t\t}\n\t\t\t\tconst checkoutPath = getWorktreeCheckoutPath(this.agentDir, registeredWorkspace.path, id);\n\t\t\t\tif (existing.some((entry) => entry.id === id) || existsSync(checkoutPath)) {\n\t\t\t\t\treturn { result: { ok: false, error: \"worktree_exists\" } };\n\t\t\t\t}\n\n\t\t\t\tconst source = await this.resolveCreateSource(registeredWorkspace, options.workingDirectory);\n\t\t\t\tif (!source.ok) {\n\t\t\t\t\treturn { result: source };\n\t\t\t\t}\n\t\t\t\tconst repoCheck = await this.runGit([\"rev-parse\", \"--git-common-dir\"], source.source.sourceRootPath);\n\t\t\t\tif (!repoCheck.ok) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: this.mapGitFailure(repoCheck.stderr, registeredWorkspace, checkoutPath, [\n\t\t\t\t\t\t\tsource.source.sourceRootPath,\n\t\t\t\t\t\t]),\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\t// Resolve a defaulted base to a concrete ref (the source checkout's branch,\n\t\t\t\t// falling back to its commit sha) so merge-back guidance — aheadBehind,\n\t\t\t\t// retention merge checks, `worktree diff` — has a stable base later.\n\t\t\t\tconst recordedBaseRef = options.baseRef ?? (await this.resolveDefaultBaseRef(source.source.sourceRootPath));\n\n\t\t\t\tawait mkdir(getWorkspaceWorktreesDir(this.agentDir, registeredWorkspace.path), {\n\t\t\t\t\trecursive: true,\n\t\t\t\t\tmode: 0o700,\n\t\t\t\t});\n\t\t\t\tconst added = await this.runGit(\n\t\t\t\t\t[\"worktree\", \"add\", checkoutPath, \"-b\", branch, baseRef],\n\t\t\t\t\tsource.source.sourceRootPath,\n\t\t\t\t);\n\t\t\t\tif (!added.ok) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: this.mapGitFailure(added.stderr, registeredWorkspace, checkoutPath, [\n\t\t\t\t\t\t\tsource.source.sourceRootPath,\n\t\t\t\t\t\t]),\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tconst worktree: IrohRemoteWorkspaceWorktree = {\n\t\t\t\t\tid,\n\t\t\t\t\tworkspaceName: registeredWorkspace.name,\n\t\t\t\t\tpath: checkoutPath,\n\t\t\t\t\t...(source.source.sourceRootRelativePath === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { sourceRootRelativePath: source.source.sourceRootRelativePath }),\n\t\t\t\t\tbranch,\n\t\t\t\t\t...(recordedBaseRef === undefined ? {} : { baseRef: recordedBaseRef }),\n\t\t\t\t\tcreatedAt: this.now(),\n\t\t\t\t\tsessionIds: [],\n\t\t\t\t};\n\t\t\t\treturn { result: { ok: true, worktree }, worktree };\n\t\t\t});\n\t\t\tif (result.ok) {\n\t\t\t\ttry {\n\t\t\t\t\tawait this.flushState?.();\n\t\t\t\t} catch {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\terror: \"git_failed\",\n\t\t\t\t\t\tdetail: \"worktree state could not be flushed; the checkout and daemon record were preserved\",\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\tif (isIrohRemoteWorktreeParentWorkspaceNotFoundError(error)) {\n\t\t\t\treturn { ok: false, error: \"worktree_source_unregistered\" };\n\t\t\t}\n\t\t\tif (isIrohRemoteWorktreePersistenceError(error)) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\terror: \"git_failed\",\n\t\t\t\t\tdetail: \"worktree state could not be persisted; the created checkout was preserved for recovery\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\t/** Adopt an existing git worktree checkout into daemon state; local control socket only. */\n\tasync adopt(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\toptions: { path: string; id?: string; baseRef?: string },\n\t): Promise<WorktreeResult<{ worktree: IrohRemoteWorkspaceWorktree }>> {\n\t\tconst requestedPath = resolve(options.path);\n\t\tif (options.id !== undefined && !WORKTREE_ID_PATTERN.test(options.id)) {\n\t\t\treturn { ok: false, error: \"invalid_worktree_id\" };\n\t\t}\n\t\tif (options.baseRef !== undefined && !isValidGitRefSyntax(options.baseRef)) {\n\t\t\treturn { ok: false, error: \"git_failed\", detail: \"invalid baseRef ref syntax\" };\n\t\t}\n\t\tif (!existsSync(requestedPath)) {\n\t\t\treturn { ok: false, error: \"worktree_not_found\", detail: \"checkout path does not exist\" };\n\t\t}\n\n\t\ttry {\n\t\t\tconst result = await this.stateManager.runWorkspaceWorktreeLifecycle<\n\t\t\t\tWorktreeResult<{ worktree: IrohRemoteWorkspaceWorktree }>\n\t\t\t>(workspace.name, async ({ workspace: registeredWorkspace, worktrees: existing }) => {\n\t\t\t\tif (existing.length >= this.maxWorktreesPerWorkspace) {\n\t\t\t\t\treturn { result: { ok: false, error: \"worktree_limit_reached\" } };\n\t\t\t\t}\n\n\t\t\t\tconst topLevel = await this.runGit([\"rev-parse\", \"--show-toplevel\"], requestedPath);\n\t\t\t\tif (!topLevel.ok) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: this.mapGitFailure(topLevel.stderr, registeredWorkspace, requestedPath, [requestedPath]),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tconst targetRootPath = await realpathOrResolve(topLevel.stdout.trim());\n\t\t\t\tif (existing.some((entry) => entry.id === options.id || isSamePath(entry.path, targetRootPath))) {\n\t\t\t\t\treturn { result: { ok: false, error: \"worktree_exists\" } };\n\t\t\t\t}\n\t\t\t\tconst id =\n\t\t\t\t\toptions.id ?? deriveAdoptedWorktreeId(targetRootPath, new Set(existing.map((entry) => entry.id)));\n\t\t\t\tif (!WORKTREE_ID_PATTERN.test(id)) {\n\t\t\t\t\treturn { result: { ok: false, error: \"invalid_worktree_id\" } };\n\t\t\t\t}\n\n\t\t\t\tconst gitList = await this.runGit([\"worktree\", \"list\", \"--porcelain\"], targetRootPath);\n\t\t\t\tif (!gitList.ok) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: this.mapGitFailure(gitList.stderr, registeredWorkspace, targetRootPath, [\n\t\t\t\t\t\t\trequestedPath,\n\t\t\t\t\t\t\ttargetRootPath,\n\t\t\t\t\t\t]),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tconst entries = parseWorktreeListEntries(gitList.stdout);\n\t\t\t\tconst targetEntry = await findWorktreeListEntryByPath(entries, targetRootPath);\n\t\t\t\tif (targetEntry === undefined) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: {\n\t\t\t\t\t\t\tok: false,\n\t\t\t\t\t\t\terror: \"worktree_not_found\",\n\t\t\t\t\t\t\tdetail: \"checkout is not listed by git worktree\",\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tconst workspaceRootPath = await realpathOrResolve(registeredWorkspace.path);\n\t\t\t\tconst sourceRootPath = await findAdoptSourceRootPath(entries, workspaceRootPath, targetRootPath);\n\t\t\t\tif (sourceRootPath === undefined) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: {\n\t\t\t\t\t\t\tok: false,\n\t\t\t\t\t\t\terror: \"worktree_source_unregistered\",\n\t\t\t\t\t\t\tdetail: \"worktree source checkout is not inside the registered workspace\",\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tconst sourceRootRelativePath = await findWorkspaceRelativePathForRealpath(\n\t\t\t\t\tworkspaceRootPath,\n\t\t\t\t\tundefined,\n\t\t\t\t\tsourceRootPath,\n\t\t\t\t);\n\t\t\t\tif (sourceRootRelativePath === null) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: {\n\t\t\t\t\t\t\tok: false,\n\t\t\t\t\t\t\terror: \"worktree_source_unregistered\",\n\t\t\t\t\t\t\tdetail: \"worktree source checkout is not inside the registered workspace\",\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tconst branch = targetEntry.branch ?? targetEntry.detached ?? \"HEAD\";\n\t\t\t\tif (!isValidGitRefSyntax(branch)) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: { ok: false, error: \"git_failed\", detail: \"invalid worktree branch ref syntax\" },\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tconst baseRef = options.baseRef ?? (await this.resolveDefaultBaseRef(sourceRootPath));\n\n\t\t\t\tconst worktree: IrohRemoteWorkspaceWorktree = {\n\t\t\t\t\tid,\n\t\t\t\t\tworkspaceName: registeredWorkspace.name,\n\t\t\t\t\tpath: targetRootPath,\n\t\t\t\t\t...(sourceRootRelativePath === undefined ? {} : { sourceRootRelativePath }),\n\t\t\t\t\tbranch,\n\t\t\t\t\t...(baseRef === undefined ? {} : { baseRef }),\n\t\t\t\t\tcreatedAt: this.now(),\n\t\t\t\t\tsessionIds: [],\n\t\t\t\t};\n\t\t\t\treturn { result: { ok: true, worktree }, worktree };\n\t\t\t});\n\t\t\tif (result.ok) {\n\t\t\t\ttry {\n\t\t\t\t\tawait this.flushState?.();\n\t\t\t\t} catch {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\terror: \"git_failed\",\n\t\t\t\t\t\tdetail: \"worktree state could not be flushed; the existing checkout and daemon record were preserved\",\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\tif (isIrohRemoteWorktreeParentWorkspaceNotFoundError(error)) {\n\t\t\t\treturn { ok: false, error: \"worktree_source_unregistered\" };\n\t\t\t}\n\t\t\tif (isIrohRemoteWorktreePersistenceError(error)) {\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\terror: \"git_failed\",\n\t\t\t\t\tdetail: \"worktree state could not be persisted; the existing checkout was left unchanged\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tasync validateWorkingDirectory(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tworkingDirectory?: string,\n\t): Promise<WorktreeResult<{ directory: WorkspaceDirectoryResolution }>> {\n\t\tconst resolved = await resolveWorkspaceDirectory(workspace.path, workingDirectory);\n\t\tif (!resolved.ok) {\n\t\t\treturn { ok: false, error: \"invalid_working_directory\", detail: resolved.error };\n\t\t}\n\t\treturn { ok: true, directory: resolved.value };\n\t}\n\n\tasync resolveWorktreeWorkingDirectory(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tworktree: IrohRemoteWorkspaceWorktree,\n\t\tworkingDirectory?: string,\n\t): Promise<WorktreeResult<{ directory: WorkspaceDirectoryResolution }>> {\n\t\tif (workingDirectory === undefined) {\n\t\t\tconst rootDirectory = await resolveWorkspaceDirectory(worktree.path);\n\t\t\treturn rootDirectory.ok\n\t\t\t\t? { ok: true, directory: rootDirectory.value }\n\t\t\t\t: { ok: false, error: \"invalid_working_directory\", detail: rootDirectory.error };\n\t\t}\n\t\tconst parentDirectory = await this.validateWorkingDirectory(workspace, workingDirectory);\n\t\tif (!parentDirectory.ok) {\n\t\t\treturn parentDirectory;\n\t\t}\n\t\tconst sourceRootPath = await this.resolveRecordSourceRootPath(workspace, worktree);\n\t\tif (sourceRootPath === undefined || !isPathContained(sourceRootPath, parentDirectory.directory.absolutePath)) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_working_directory\",\n\t\t\t\tdetail: \"workingDirectory is outside the worktree source repository\",\n\t\t\t};\n\t\t}\n\t\tconst worktreeRelativePath = getContainedRelativePath(sourceRootPath, parentDirectory.directory.absolutePath);\n\t\tif (worktreeRelativePath === null) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_working_directory\",\n\t\t\t\tdetail: \"workingDirectory is outside the worktree source repository\",\n\t\t\t};\n\t\t}\n\t\tconst worktreeDirectory = await resolveWorkspaceDirectory(worktree.path, worktreeRelativePath);\n\t\treturn worktreeDirectory.ok\n\t\t\t? { ok: true, directory: worktreeDirectory.value }\n\t\t\t: { ok: false, error: \"invalid_working_directory\", detail: worktreeDirectory.error };\n\t}\n\n\tprivate async resolveCreateSource(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tworkingDirectory?: string,\n\t): Promise<WorktreeResult<{ source: WorktreeSourceResolution }>> {\n\t\tconst workspaceDirectory = await this.validateWorkingDirectory(workspace, workingDirectory);\n\t\tif (!workspaceDirectory.ok) {\n\t\t\treturn workspaceDirectory;\n\t\t}\n\t\tconst topLevel = await this.runGit(\n\t\t\t[\"-C\", workspaceDirectory.directory.absolutePath, \"rev-parse\", \"--show-toplevel\"],\n\t\t\tworkspace.path,\n\t\t);\n\t\tif (!topLevel.ok) {\n\t\t\tconst detail = sanitizeGitDetail(topLevel.stderr, [\n\t\t\t\tworkspace.path,\n\t\t\t\tworkspaceDirectory.directory.absolutePath,\n\t\t\t\tgetWorktreesRoot(this.agentDir),\n\t\t\t]);\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: topLevel.stderr.toLowerCase().includes(\"not a git repository\")\n\t\t\t\t\t? \"not_a_git_repository\"\n\t\t\t\t\t: \"git_failed\",\n\t\t\t\t...(detail.length === 0 ? {} : { detail }),\n\t\t\t};\n\t\t}\n\t\tconst workspaceRootPath = await realpathOrResolve(workspace.path);\n\t\tconst sourceRootPath = await realpathOrResolve(topLevel.stdout.trim());\n\t\tif (!isPathContained(workspaceRootPath, sourceRootPath)) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_working_directory\",\n\t\t\t\tdetail: \"git repository is outside the registered workspace\",\n\t\t\t};\n\t\t}\n\t\tconst sourceRootRelativePath = await findWorkspaceRelativePathForRealpath(\n\t\t\tworkspaceRootPath,\n\t\t\tworkspaceDirectory.directory.relativePath,\n\t\t\tsourceRootPath,\n\t\t);\n\t\tif (sourceRootRelativePath === null) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_working_directory\",\n\t\t\t\tdetail: \"git repository is outside the registered workspace\",\n\t\t\t};\n\t\t}\n\t\tconst workingDirectoryRelativePath = getContainedRelativePath(\n\t\t\tsourceRootPath,\n\t\t\tworkspaceDirectory.directory.absolutePath,\n\t\t);\n\t\tif (workingDirectoryRelativePath === null) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"invalid_working_directory\",\n\t\t\t\tdetail: \"workingDirectory is outside the source repository\",\n\t\t\t};\n\t\t}\n\t\treturn {\n\t\t\tok: true,\n\t\t\tsource: {\n\t\t\t\tworkspaceDirectory: workspaceDirectory.directory,\n\t\t\t\tsourceRootPath,\n\t\t\t\t...(sourceRootRelativePath === undefined ? {} : { sourceRootRelativePath }),\n\t\t\t\t...(workingDirectoryRelativePath === undefined ? {} : { workingDirectoryRelativePath }),\n\t\t\t},\n\t\t};\n\t}\n\n\tasync list(workspace: IrohRemoteWorkspace): Promise<WorktreeStatus[]> {\n\t\tconst records = await this.stateManager.listWorktrees(workspace.name);\n\t\tconst gitListBySourceRoot = new Map<string, Set<string> | undefined>();\n\t\tconst statuses: WorktreeStatus[] = [];\n\t\tfor (const record of records) {\n\t\t\tconst sourceRootPath = await this.resolveRecordSourceRootPath(workspace, record);\n\t\t\tconst knownCheckouts =\n\t\t\t\tsourceRootPath === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: await this.getKnownWorktreeCheckouts(sourceRootPath, gitListBySourceRoot);\n\t\t\tconst onDisk = existsSync(record.path);\n\t\t\tconst available =\n\t\t\t\tonDisk &&\n\t\t\t\tsourceRootPath !== undefined &&\n\t\t\t\t(knownCheckouts === undefined || knownCheckouts.has(resolve(record.path)));\n\t\t\tlet dirty: boolean | undefined;\n\t\t\tlet aheadBehind: { ahead: number; behind: number } | undefined;\n\t\t\tif (available) {\n\t\t\t\t// --no-optional-locks is a git-level option and must precede the subcommand.\n\t\t\t\tconst status = await this.runGit(\n\t\t\t\t\t[\"-C\", record.path, \"--no-optional-locks\", \"status\", \"--porcelain\"],\n\t\t\t\t\tsourceRootPath,\n\t\t\t\t);\n\t\t\t\tdirty = status.ok ? status.stdout.trim().length > 0 : undefined;\n\t\t\t\taheadBehind = await this.computeAheadBehind(sourceRootPath, record);\n\t\t\t}\n\t\t\tstatuses.push({\n\t\t\t\t...record,\n\t\t\t\tavailable,\n\t\t\t\t...(dirty === undefined ? {} : { dirty }),\n\t\t\t\t...(aheadBehind === undefined ? {} : { aheadBehind }),\n\t\t\t});\n\t\t}\n\t\treturn statuses;\n\t}\n\n\tprivate async getKnownWorktreeCheckouts(\n\t\tsourceRootPath: string,\n\t\tcache: Map<string, Set<string> | undefined>,\n\t): Promise<Set<string> | undefined> {\n\t\tconst key = resolve(sourceRootPath);\n\t\tif (cache.has(key)) {\n\t\t\treturn cache.get(key);\n\t\t}\n\t\tconst gitList = await this.runGit([\"worktree\", \"list\", \"--porcelain\"], sourceRootPath);\n\t\tconst knownCheckouts = gitList.ok ? parseWorktreeListCheckouts(gitList.stdout) : undefined;\n\t\tcache.set(key, knownCheckouts);\n\t\treturn knownCheckouts;\n\t}\n\n\tprivate async resolveRecordSourceRootPath(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\trecord: IrohRemoteWorkspaceWorktree,\n\t): Promise<string | undefined> {\n\t\tconst resolved = await resolveWorkspaceDirectory(workspace.path, record.sourceRootRelativePath);\n\t\treturn resolved.ok ? resolved.value.absolutePath : undefined;\n\t}\n\n\t/** Concrete base for a defaulted create: current branch name, else commit sha. */\n\tprivate async resolveDefaultBaseRef(sourceRootPath: string): Promise<string | undefined> {\n\t\tconst symbolic = await this.runGit([\"symbolic-ref\", \"--short\", \"-q\", \"HEAD\"], sourceRootPath);\n\t\tconst shortRef = symbolic.ok ? symbolic.stdout.trim() : \"\";\n\t\tif (shortRef.length > 0 && isValidGitRefSyntax(shortRef)) {\n\t\t\treturn shortRef;\n\t\t}\n\t\tconst sha = await this.runGit([\"rev-parse\", \"HEAD\"], sourceRootPath);\n\t\tconst shaValue = sha.ok ? sha.stdout.trim() : \"\";\n\t\treturn /^[0-9a-f]{4,64}$/i.test(shaValue) ? shaValue : undefined;\n\t}\n\n\t/**\n\t * Merge-back guidance (design §5.3): branch commits relative to the base\n\t * ref, computed read-only in the source checkout. `left...right` with\n\t * left = base and right = branch yields \"behind<TAB>ahead\".\n\t */\n\tprivate async computeAheadBehind(\n\t\tsourceRootPath: string,\n\t\trecord: IrohRemoteWorkspaceWorktree,\n\t): Promise<{ ahead: number; behind: number } | undefined> {\n\t\tconst baseRef = record.baseRef ?? \"HEAD\";\n\t\tconst counted = await this.runGit(\n\t\t\t[\"rev-list\", \"--left-right\", \"--count\", `${baseRef}...${record.branch}`],\n\t\t\tsourceRootPath,\n\t\t);\n\t\tif (!counted.ok) {\n\t\t\treturn undefined;\n\t\t}\n\t\tconst match = counted.stdout.trim().match(/^(\\d+)\\s+(\\d+)$/);\n\t\tif (!match?.[1] || !match[2]) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn { behind: Number.parseInt(match[1], 10), ahead: Number.parseInt(match[2], 10) };\n\t}\n\n\t/** Refuses dirty/busy unless force; `git worktree remove [--force]`, then drops the record. */\n\tasync remove(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tworktreeId: string,\n\t\toptions: { force?: boolean } = {},\n\t): Promise<WorktreeResult<Record<never, never>>> {\n\t\tconst force = options.force === true;\n\t\tconst records = await this.stateManager.listWorktrees(workspace.name);\n\t\tconst record = records.find((entry) => entry.id === worktreeId);\n\t\tif (!record) {\n\t\t\treturn { ok: false, error: \"worktree_not_found\" };\n\t\t}\n\t\tif (!force && this.hasActiveRuntimeForSession) {\n\t\t\tconst busy = record.sessionIds.some((sessionId) =>\n\t\t\t\tthis.hasActiveRuntimeForSession?.(workspace.name, sessionId),\n\t\t\t);\n\t\t\tif (busy) {\n\t\t\t\treturn { ok: false, error: \"worktree_busy\" };\n\t\t\t}\n\t\t}\n\t\tconst sourceRootPath = await this.resolveRecordSourceRootPath(workspace, record);\n\t\tif (existsSync(record.path)) {\n\t\t\tif (sourceRootPath === undefined) {\n\t\t\t\treturn { ok: false, error: \"not_a_git_repository\", detail: \"worktree source repository is unavailable\" };\n\t\t\t}\n\t\t\tif (!force) {\n\t\t\t\tconst status = await this.runGit(\n\t\t\t\t\t[\"-C\", record.path, \"--no-optional-locks\", \"status\", \"--porcelain\"],\n\t\t\t\t\tsourceRootPath,\n\t\t\t\t);\n\t\t\t\tif (status.ok && status.stdout.trim().length > 0) {\n\t\t\t\t\treturn { ok: false, error: \"worktree_dirty\", detail: \"dirty\" };\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst args = force ? [\"worktree\", \"remove\", \"--force\", record.path] : [\"worktree\", \"remove\", record.path];\n\t\t\tconst removed = await this.runGit(args, sourceRootPath);\n\t\t\tif (!removed.ok) {\n\t\t\t\treturn this.mapGitFailure(removed.stderr, workspace, record.path, [sourceRootPath]);\n\t\t\t}\n\t\t} else {\n\t\t\t// Checkout vanished out-of-band: clear the stale gitdir entry best-effort.\n\t\t\tif (sourceRootPath !== undefined) {\n\t\t\t\tawait this.runGit([\"worktree\", \"prune\"], sourceRootPath).catch(() => undefined);\n\t\t\t}\n\t\t}\n\t\tawait this.stateManager.removeWorktree(workspace.name, worktreeId);\n\t\tawait this.flushState?.();\n\t\treturn { ok: true };\n\t}\n\n\t/**\n\t * Reconcile persisted records vs filesystem vs `git worktree list`. Drops\n\t * records without checkouts, quarantines unrecognized checkout directories\n\t * (rename, never delete), and runs `git worktree prune` in each known source checkout.\n\t */\n\tasync prune(workspace: IrohRemoteWorkspace): Promise<{ removedRecords: string[]; orphanCheckouts: string[] }> {\n\t\tconst records = await this.stateManager.listWorktrees(workspace.name);\n\t\tconst removedRecords: string[] = [];\n\t\tconst sourceRootPaths = new Set<string>();\n\t\tfor (const record of records) {\n\t\t\tconst sourceRootPath = await this.resolveRecordSourceRootPath(workspace, record);\n\t\t\tif (sourceRootPath !== undefined) {\n\t\t\t\tsourceRootPaths.add(sourceRootPath);\n\t\t\t}\n\t\t\tif (!existsSync(record.path)) {\n\t\t\t\tawait this.stateManager.removeWorktree(workspace.name, record.id);\n\t\t\t\tremovedRecords.push(record.id);\n\t\t\t}\n\t\t}\n\t\tconst parentSourceRootPath = await this.resolveRecordSourceRootPath(workspace, {\n\t\t\tid: \"root\",\n\t\t\tworkspaceName: workspace.name,\n\t\t\tpath: workspace.path,\n\t\t\tbranch: \"HEAD\",\n\t\t\tcreatedAt: 0,\n\t\t\tsessionIds: [],\n\t\t});\n\t\tif (parentSourceRootPath !== undefined) {\n\t\t\tsourceRootPaths.add(parentSourceRootPath);\n\t\t}\n\t\tconst orphanCheckouts: string[] = [];\n\t\tconst workspaceDir = getWorkspaceWorktreesDir(this.agentDir, workspace.path);\n\t\tconst recordedPaths = new Set(records.map((record) => resolve(record.path)));\n\t\tif (existsSync(workspaceDir)) {\n\t\t\tfor (const entry of await readdir(workspaceDir, { withFileTypes: true })) {\n\t\t\t\tif (!entry.isDirectory() || entry.name.includes(\".orphan-\")) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst entryPath = resolve(join(workspaceDir, entry.name));\n\t\t\t\tif (recordedPaths.has(entryPath)) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst quarantinePath = `${entryPath}.orphan-${this.now()}`;\n\t\t\t\ttry {\n\t\t\t\t\tawait rename(entryPath, quarantinePath);\n\t\t\t\t\torphanCheckouts.push(entry.name);\n\t\t\t\t} catch {\n\t\t\t\t\t// Quarantine is best-effort; a busy directory stays put for the next prune.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tfor (const sourceRootPath of sourceRootPaths) {\n\t\t\tawait this.runGit([\"worktree\", \"prune\"], sourceRootPath).catch(() => undefined);\n\t\t}\n\t\tif (removedRecords.length > 0) {\n\t\t\tawait this.flushState?.();\n\t\t}\n\t\tawait this.logAudit({\n\t\t\ttype: \"worktree_pruned\",\n\t\t\tworkspace: workspace.name,\n\t\t\tsuccess: true,\n\t\t\tdetails: { removedRecords, orphanCheckouts },\n\t\t});\n\t\treturn { removedRecords, orphanCheckouts };\n\t}\n\n\t/**\n\t * Retention removal (design §5.3): remove a worktree ONLY when it is not\n\t * busy, has no uncommitted work, and its branch is fully merged into the\n\t * base ref. Never forces; a skip returns the reason for the audit trail.\n\t */\n\tasync removeIfCleanAndMerged(\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tworktreeId: string,\n\t): Promise<{ removed: true } | { removed: false; reason: string }> {\n\t\tconst record = (await this.stateManager.listWorktrees(workspace.name)).find((entry) => entry.id === worktreeId);\n\t\tif (!record) {\n\t\t\treturn { removed: false, reason: \"worktree_not_found\" };\n\t\t}\n\t\tif (\n\t\t\tthis.hasActiveRuntimeForSession &&\n\t\t\trecord.sessionIds.some((sessionId) => this.hasActiveRuntimeForSession?.(workspace.name, sessionId))\n\t\t) {\n\t\t\treturn { removed: false, reason: \"busy\" };\n\t\t}\n\t\tif (!existsSync(record.path)) {\n\t\t\treturn { removed: false, reason: \"checkout_missing\" };\n\t\t}\n\t\tconst sourceRootPath = await this.resolveRecordSourceRootPath(workspace, record);\n\t\tif (sourceRootPath === undefined) {\n\t\t\treturn { removed: false, reason: \"source_unavailable\" };\n\t\t}\n\t\tconst status = await this.runGit(\n\t\t\t[\"-C\", record.path, \"--no-optional-locks\", \"status\", \"--porcelain\"],\n\t\t\tsourceRootPath,\n\t\t);\n\t\tif (!status.ok || status.stdout.trim().length > 0) {\n\t\t\treturn { removed: false, reason: \"dirty\" };\n\t\t}\n\t\tconst merged = await this.runGit(\n\t\t\t[\"merge-base\", \"--is-ancestor\", record.branch, record.baseRef ?? \"HEAD\"],\n\t\t\tsourceRootPath,\n\t\t);\n\t\tif (!merged.ok) {\n\t\t\treturn { removed: false, reason: \"unmerged\" };\n\t\t}\n\t\tconst removedResult = await this.remove(workspace, worktreeId, { force: false });\n\t\tif (!removedResult.ok) {\n\t\t\treturn { removed: false, reason: removedResult.error };\n\t\t}\n\t\treturn { removed: true };\n\t}\n\n\t/** Lookup used by conversation open/resume and relay preamble resolution. */\n\tasync resolveSessionWorktree(\n\t\tworkspaceName: string,\n\t\tsessionId: string,\n\t): Promise<IrohRemoteWorkspaceWorktree | undefined> {\n\t\treturn this.stateManager.findWorktreeForSession(workspaceName, sessionId);\n\t}\n\n\tasync bindSession(workspaceName: string, worktreeId: string, sessionId: string): Promise<void> {\n\t\tawait this.stateManager.bindWorktreeSession(workspaceName, worktreeId, sessionId);\n\t\tawait this.flushState?.();\n\t}\n\n\tasync findWorktree(workspaceName: string, worktreeId: string): Promise<IrohRemoteWorkspaceWorktree | undefined> {\n\t\tconst records = await this.stateManager.listWorktrees(workspaceName);\n\t\treturn records.find((entry) => entry.id === worktreeId);\n\t}\n\n\t/**\n\t * Compatibility guard for post-unregister callers. Workspace unregister is\n\t * deliberately non-destructive: persisted worktrees block the state mutation,\n\t * and unknown checkout directories are preserved for manual reconciliation.\n\t */\n\tasync cleanupUnregisteredWorkspace(workspace: IrohRemoteWorkspace): Promise<void> {\n\t\tconst workspaceDir = getWorkspaceWorktreesDir(this.agentDir, workspace.path);\n\t\tif (!existsSync(workspaceDir)) {\n\t\t\treturn;\n\t\t}\n\t\tlet preservedEntryCount = 0;\n\t\ttry {\n\t\t\tpreservedEntryCount = (await readdir(workspaceDir)).length;\n\t\t} catch {\n\t\t\t// Inspection is best-effort. Failure still leaves every path untouched.\n\t\t}\n\t\tconst persistedWorktreeIds = (await this.stateManager.listWorktrees(workspace.name))\n\t\t\t.map((worktree) => worktree.id)\n\t\t\t.sort();\n\t\tawait this.logAudit({\n\t\t\ttype: \"worktree_unregister_cleanup_skipped\",\n\t\t\tworkspace: workspace.name,\n\t\t\tsuccess: false,\n\t\t\terror: \"workspace unregister never removes worktree checkouts\",\n\t\t\tdetails: {\n\t\t\t\tpersistedWorktreeIds,\n\t\t\t\tpreservedEntryCount,\n\t\t\t\treason: \"non_destructive_workspace_unregister\",\n\t\t\t},\n\t\t});\n\t}\n\n\tprivate mapGitFailure(\n\t\tstderr: string,\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tcheckoutPath: string,\n\t\textraPaths: string[] = [],\n\t): { ok: false; error: WorktreeError; detail: string } {\n\t\tconst detail = sanitizeGitDetail(stderr, [\n\t\t\tcheckoutPath,\n\t\t\tworkspace.path,\n\t\t\t...extraPaths,\n\t\t\tgetWorktreesRoot(this.agentDir),\n\t\t]);\n\t\tconst lower = stderr.toLowerCase();\n\t\tif (lower.includes(\"not a git repository\")) {\n\t\t\treturn { ok: false, error: \"not_a_git_repository\", detail };\n\t\t}\n\t\tif (lower.includes(\"already exists\")) {\n\t\t\treturn lower.includes(\"branch\") || lower.includes(\"-b\")\n\t\t\t\t? { ok: false, error: \"worktree_branch_conflict\", detail }\n\t\t\t\t: { ok: false, error: \"worktree_exists\", detail };\n\t\t}\n\t\tif (lower.includes(\"contains modified or untracked files\")) {\n\t\t\treturn { ok: false, error: \"worktree_dirty\", detail };\n\t\t}\n\t\treturn { ok: false, error: \"git_failed\", detail };\n\t}\n\n\tprivate async logAudit(event: Parameters<IrohRemoteAuditLogger[\"log\"]>[0]): Promise<void> {\n\t\ttry {\n\t\t\tawait this.auditLogger.log(event);\n\t\t} catch {\n\t\t\t// Audit logging is best-effort.\n\t\t}\n\t}\n}\n\nasync function realpathOrResolve(path: string): Promise<string> {\n\ttry {\n\t\treturn await realpath(path);\n\t} catch {\n\t\treturn resolve(path);\n\t}\n}\n\nfunction getContainedRelativePath(root: string, child: string): string | null | undefined {\n\tconst relativePath = relative(resolve(root), resolve(child));\n\tif (relativePath.length === 0 || relativePath === \".\") {\n\t\treturn undefined;\n\t}\n\tif (relativePath === \"..\" || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {\n\t\treturn null;\n\t}\n\treturn relativePath.split(sep).join(\"/\");\n}\n\nasync function findWorkspaceRelativePathForRealpath(\n\tworkspaceRootPath: string,\n\tselectedRelativePath: string | undefined,\n\ttargetRealpath: string,\n): Promise<string | null | undefined> {\n\tconst selectedSegments = selectedRelativePath?.split(\"/\") ?? [];\n\tfor (let count = selectedSegments.length; count >= 0; count -= 1) {\n\t\tconst candidateRelativePath = count === 0 ? undefined : selectedSegments.slice(0, count).join(\"/\");\n\t\tconst candidatePath =\n\t\t\tcandidateRelativePath === undefined ? workspaceRootPath : resolve(workspaceRootPath, candidateRelativePath);\n\t\ttry {\n\t\t\tconst candidateRealpath = await realpath(candidatePath);\n\t\t\tif (isSamePath(candidateRealpath, targetRealpath)) {\n\t\t\t\treturn candidateRelativePath;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Ignore missing ancestors and fall back to the canonical realpath-relative form below.\n\t\t}\n\t}\n\treturn getContainedRelativePath(workspaceRootPath, targetRealpath);\n}\n\nfunction isSamePath(left: string, right: string): boolean {\n\tconst resolvedLeft = resolve(left);\n\tconst resolvedRight = resolve(right);\n\treturn process.platform === \"win32\"\n\t\t? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase()\n\t\t: resolvedLeft === resolvedRight;\n}\n\ninterface GitWorktreeListEntry {\n\tpath: string;\n\tbranch?: string;\n\tdetached?: string;\n}\n\nfunction parseWorktreeListEntries(porcelainOutput: string): GitWorktreeListEntry[] {\n\tconst entries: GitWorktreeListEntry[] = [];\n\tlet current: GitWorktreeListEntry | undefined;\n\tconst pushCurrent = () => {\n\t\tif (current !== undefined) {\n\t\t\tentries.push(current);\n\t\t\tcurrent = undefined;\n\t\t}\n\t};\n\tfor (const line of porcelainOutput.split(\"\\n\")) {\n\t\tif (line.length === 0) {\n\t\t\tpushCurrent();\n\t\t\tcontinue;\n\t\t}\n\t\tif (line.startsWith(\"worktree \")) {\n\t\t\tpushCurrent();\n\t\t\tcurrent = { path: line.slice(\"worktree \".length).trim() };\n\t\t\tcontinue;\n\t\t}\n\t\tif (current === undefined) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (line.startsWith(\"branch \")) {\n\t\t\tconst ref = line.slice(\"branch \".length).trim();\n\t\t\tcurrent.branch = ref.startsWith(\"refs/heads/\") ? ref.slice(\"refs/heads/\".length) : ref;\n\t\t\tcontinue;\n\t\t}\n\t\tif (line.startsWith(\"detached \")) {\n\t\t\tcurrent.detached = line.slice(\"detached \".length).trim();\n\t\t}\n\t}\n\tpushCurrent();\n\treturn entries;\n}\n\nfunction parseWorktreeListCheckouts(porcelainOutput: string): Set<string> {\n\treturn new Set(parseWorktreeListEntries(porcelainOutput).map((entry) => resolve(entry.path)));\n}\n\nasync function findWorktreeListEntryByPath(\n\tentries: readonly GitWorktreeListEntry[],\n\tpath: string,\n): Promise<GitWorktreeListEntry | undefined> {\n\tfor (const entry of entries) {\n\t\tif (isSamePath(await realpathOrResolve(entry.path), path)) {\n\t\t\treturn entry;\n\t\t}\n\t}\n\treturn undefined;\n}\n\nasync function findAdoptSourceRootPath(\n\tentries: readonly GitWorktreeListEntry[],\n\tworkspaceRootPath: string,\n\ttargetRootPath: string,\n): Promise<string | undefined> {\n\tfor (const entry of entries) {\n\t\tconst entryPath = await realpathOrResolve(entry.path);\n\t\tif (!isSamePath(entryPath, targetRootPath) && isPathContained(workspaceRootPath, entryPath)) {\n\t\t\treturn entryPath;\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction deriveAdoptedWorktreeId(path: string, usedIds: ReadonlySet<string>): string {\n\tconst baseName = basename(path)\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9._-]+/g, \"-\")\n\t\t.replace(/^[^a-z0-9]+/, \"\")\n\t\t.slice(0, 64);\n\tconst base = WORKTREE_ID_PATTERN.test(baseName) ? baseName : \"adopted\";\n\tfor (let index = 0; index < 100; index++) {\n\t\tconst suffix = index === 0 ? \"\" : `-${index}`;\n\t\tconst candidate = `${base.slice(0, 64 - suffix.length)}${suffix}`;\n\t\tif (WORKTREE_ID_PATTERN.test(candidate) && !usedIds.has(candidate)) {\n\t\t\treturn candidate;\n\t\t}\n\t}\n\treturn generateWorktreeIdSlug();\n}\n\n/** Strip host paths from git stderr before it lands in an RPC detail field. */\nfunction sanitizeGitDetail(stderr: string, paths: string[]): string {\n\tlet detail = stderr.trim();\n\tfor (const path of paths) {\n\t\twhile (detail.includes(path)) {\n\t\t\tdetail = detail.replace(path, \"<redacted>\");\n\t\t}\n\t}\n\treturn detail;\n}\n\nexport interface WorktreeRetentionSweeperOptions {\n\tmanager: WorktreeManager;\n\tstateManager: IrohRemoteHostStateManager;\n\tauditLogger: IrohRemoteAuditLogger;\n\t/** Resolved at sweep time so settings changes apply without a restart. */\n\tgetRetentionPolicy: () => { enabled: boolean; ttlMs: number } | undefined;\n\t/** Injectable timers (tests). */\n\tsetTimer?: (callback: () => void, ttlMs: number) => NodeJS.Timeout;\n\tclearTimer?: (timer: NodeJS.Timeout) => void;\n}\n\n/**\n * Opt-in worktree retention (design §5.3): when a worktree-bound runtime is\n * disposed, schedule a TTL sweep that removes the worktree ONLY when it is\n * clean and fully merged into its base ref; otherwise the skip is audited as\n * worktree_retention_skipped_dirty and the checkout stays put.\n */\nexport class WorktreeRetentionSweeper {\n\tprivate readonly options: WorktreeRetentionSweeperOptions;\n\tprivate readonly timers = new Map<string, NodeJS.Timeout>();\n\tprivate disposed = false;\n\n\tconstructor(options: WorktreeRetentionSweeperOptions) {\n\t\tthis.options = options;\n\t}\n\n\t/** Hooked to IntegratedRuntimeRegistry.onRuntimeDisposed for worktree-bound entries. */\n\tonRuntimeDisposed(workspaceName: string, worktreeId: string): void {\n\t\tif (this.disposed) {\n\t\t\treturn;\n\t\t}\n\t\tconst policy = this.options.getRetentionPolicy();\n\t\tif (policy === undefined || !policy.enabled) {\n\t\t\treturn;\n\t\t}\n\t\tconst key = `${workspaceName}\\0${worktreeId}`;\n\t\tconst existing = this.timers.get(key);\n\t\tif (existing !== undefined) {\n\t\t\t(this.options.clearTimer ?? clearTimeout)(existing);\n\t\t}\n\t\tconst timer = (this.options.setTimer ?? setTimeout)(() => {\n\t\t\tthis.timers.delete(key);\n\t\t\tvoid this.sweep(workspaceName, worktreeId);\n\t\t}, policy.ttlMs);\n\t\ttimer.unref?.();\n\t\tthis.timers.set(key, timer);\n\t}\n\n\tprivate async sweep(workspaceName: string, worktreeId: string): Promise<void> {\n\t\tif (this.disposed) {\n\t\t\treturn;\n\t\t}\n\t\ttry {\n\t\t\tconst state = await this.options.stateManager.getState();\n\t\t\tconst workspace = state.workspaces.find((entry) => entry.name === workspaceName);\n\t\t\tif (!workspace) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst result = await this.options.manager.removeIfCleanAndMerged(workspace, worktreeId);\n\t\t\tif (result.removed) {\n\t\t\t\tawait this.options.auditLogger.log({\n\t\t\t\t\ttype: \"worktree_retention_removed\",\n\t\t\t\t\tworkspace: workspaceName,\n\t\t\t\t\tsuccess: true,\n\t\t\t\t\tdetails: { worktreeId },\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (result.reason === \"worktree_not_found\") {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tawait this.options.auditLogger.log({\n\t\t\t\ttype: \"worktree_retention_skipped_dirty\",\n\t\t\t\tworkspace: workspaceName,\n\t\t\t\tsuccess: false,\n\t\t\t\tdetails: { worktreeId, reason: result.reason },\n\t\t\t});\n\t\t} catch {\n\t\t\t// Retention is best-effort; the next disposal reschedules.\n\t\t}\n\t}\n\n\tdispose(): void {\n\t\tthis.disposed = true;\n\t\tfor (const timer of this.timers.values()) {\n\t\t\t(this.options.clearTimer ?? clearTimeout)(timer);\n\t\t}\n\t\tthis.timers.clear();\n\t}\n}\n\nexport type WorktreeControlRequest = Extract<\n\tControlRequest,\n\t{\n\t\ttype:\n\t\t\t| \"worktree_create\"\n\t\t\t| \"worktree_adopt\"\n\t\t\t| \"worktree_list\"\n\t\t\t| \"worktree_remove\"\n\t\t\t| \"worktree_prune\"\n\t\t\t| \"worktree_resolve\"\n\t\t\t| \"worktree_bind\";\n\t}\n>;\n\nexport interface WorktreeControlRequestHooks {\n\tmanager: WorktreeManager;\n\tstateManager: IrohRemoteHostStateManager;\n\t/** Force-remove hook that stops bound runtimes first (wired by the iroh service). */\n\tremoveWorktree?: (\n\t\tworkspace: IrohRemoteWorkspace,\n\t\tworktreeId: string,\n\t\tforce: boolean,\n\t) => Promise<WorktreeResult<Record<never, never>>>;\n}\n\nexport function isWorktreeControlRequest(request: ControlRequest): request is WorktreeControlRequest {\n\treturn (\n\t\trequest.type === \"worktree_create\" ||\n\t\trequest.type === \"worktree_adopt\" ||\n\t\trequest.type === \"worktree_list\" ||\n\t\trequest.type === \"worktree_remove\" ||\n\t\trequest.type === \"worktree_prune\" ||\n\t\trequest.type === \"worktree_resolve\" ||\n\t\trequest.type === \"worktree_bind\"\n\t);\n}\n\n/**\n * Shared `worktree_*` control-socket handler: used by the daemon skeleton\n * (main.ts fallback) and the iroh service (which layers runtime-aware remove\n * on top via hooks.removeWorktree). Control responses MAY include checkout\n * paths — the no-paths rule applies to the iroh wire, not the local socket.\n */\nexport async function handleWorktreeControlRequest(\n\tconnection: ControlConnection,\n\trequest: WorktreeControlRequest,\n\thooks: WorktreeControlRequestHooks,\n): Promise<void> {\n\tconst state = await hooks.stateManager.getState();\n\tconst findWorkspace = (name: string): IrohRemoteWorkspace | undefined =>\n\t\tstate.workspaces.find((workspace) => workspace.name === name);\n\tconst sendWorkspaceNotFound = (name: string) => {\n\t\tconnection.send({\n\t\t\ttype: \"error\",\n\t\t\tid: request.id,\n\t\t\tcode: \"not_found\",\n\t\t\tmessage: `No registered workspace named ${name}`,\n\t\t});\n\t};\n\n\tif (request.type === \"worktree_create\") {\n\t\tconst workspace = findWorkspace(request.workspaceName);\n\t\tif (!workspace) {\n\t\t\tsendWorkspaceNotFound(request.workspaceName);\n\t\t\treturn;\n\t\t}\n\t\tconst created = await hooks.manager.create(workspace, {\n\t\t\t...(request.worktreeName === undefined ? {} : { id: request.worktreeName }),\n\t\t\t...(request.branch === undefined ? {} : { branch: request.branch }),\n\t\t\t...(request.baseRef === undefined ? {} : { baseRef: request.baseRef }),\n\t\t});\n\t\tif (!created.ok) {\n\t\t\tconnection.send({\n\t\t\t\ttype: \"error\",\n\t\t\t\tid: request.id,\n\t\t\t\tcode: created.error,\n\t\t\t\tmessage: created.detail ?? created.error,\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tconnection.send({\n\t\t\ttype: \"worktree_result\",\n\t\t\tid: request.id,\n\t\t\tworktree: toControlWorktreeStatus(created.worktree, true),\n\t\t});\n\t\treturn;\n\t}\n\n\tif (request.type === \"worktree_adopt\") {\n\t\tconst workspace = findWorkspace(request.workspaceName);\n\t\tif (!workspace) {\n\t\t\tsendWorkspaceNotFound(request.workspaceName);\n\t\t\treturn;\n\t\t}\n\t\tconst adopted = await hooks.manager.adopt(workspace, {\n\t\t\tpath: request.path,\n\t\t\t...(request.worktreeName === undefined ? {} : { id: request.worktreeName }),\n\t\t\t...(request.baseRef === undefined ? {} : { baseRef: request.baseRef }),\n\t\t});\n\t\tif (!adopted.ok) {\n\t\t\tconnection.send({\n\t\t\t\ttype: \"error\",\n\t\t\t\tid: request.id,\n\t\t\t\tcode: adopted.error,\n\t\t\t\tmessage: adopted.detail ?? adopted.error,\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tconnection.send({\n\t\t\ttype: \"worktree_result\",\n\t\t\tid: request.id,\n\t\t\tworktree: toControlWorktreeStatus(adopted.worktree, true),\n\t\t});\n\t\treturn;\n\t}\n\n\tif (request.type === \"worktree_list\") {\n\t\tconst workspaces = resolveRequestWorkspaces(state.workspaces, request.workspaceName);\n\t\tif (!workspaces.ok) {\n\t\t\tsendWorkspaceNotFound(workspaces.missing);\n\t\t\treturn;\n\t\t}\n\t\tconst worktrees: ControlWorktreeStatus[] = [];\n\t\tfor (const workspace of workspaces.workspaces) {\n\t\t\tfor (const status of await hooks.manager.list(workspace)) {\n\t\t\t\tworktrees.push(toControlWorktreeStatus(status, status.available, status.dirty));\n\t\t\t}\n\t\t}\n\t\tconnection.send({ type: \"worktrees_result\", id: request.id, worktrees });\n\t\treturn;\n\t}\n\n\tif (request.type === \"worktree_resolve\") {\n\t\tconst worktrees = await hooks.stateManager.listWorktrees();\n\t\tconst match = worktrees.find((worktree) => isPathContained(worktree.path, request.path));\n\t\tconst workspace = match ? findWorkspace(match.workspaceName) : undefined;\n\t\tif (!match || !workspace) {\n\t\t\tconnection.send({\n\t\t\t\ttype: \"error\",\n\t\t\t\tid: request.id,\n\t\t\t\tcode: \"not_found\",\n\t\t\t\tmessage: \"path is not inside a daemon-managed worktree\",\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tconnection.send({\n\t\t\ttype: \"worktree_resolve_result\",\n\t\t\tid: request.id,\n\t\t\tworkspaceName: workspace.name,\n\t\t\tworkspacePath: workspace.path,\n\t\t\tworktreeId: match.id,\n\t\t\tworktreePath: match.path,\n\t\t});\n\t\treturn;\n\t}\n\n\tif (request.type === \"worktree_bind\") {\n\t\tconst workspace = findWorkspace(request.workspaceName);\n\t\tif (!workspace) {\n\t\t\tsendWorkspaceNotFound(request.workspaceName);\n\t\t\treturn;\n\t\t}\n\t\tconst record = await hooks.manager.findWorktree(request.workspaceName, request.worktreeId);\n\t\tif (!record) {\n\t\t\tconnection.send({\n\t\t\t\ttype: \"error\",\n\t\t\t\tid: request.id,\n\t\t\t\tcode: \"worktree_not_found\",\n\t\t\t\tmessage: `No worktree ${request.worktreeId} in workspace ${request.workspaceName}`,\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tawait hooks.manager.bindSession(request.workspaceName, request.worktreeId, request.sessionId);\n\t\tconnection.send({ type: \"ok\", id: request.id });\n\t\treturn;\n\t}\n\n\tif (request.type === \"worktree_remove\") {\n\t\tconst workspace = findWorkspace(request.workspaceName);\n\t\tif (!workspace) {\n\t\t\tsendWorkspaceNotFound(request.workspaceName);\n\t\t\treturn;\n\t\t}\n\t\tconst force = request.force === true;\n\t\tconst removed = hooks.removeWorktree\n\t\t\t? await hooks.removeWorktree(workspace, request.worktreeId, force)\n\t\t\t: await hooks.manager.remove(workspace, request.worktreeId, { force });\n\t\tif (!removed.ok) {\n\t\t\tconnection.send({\n\t\t\t\ttype: \"error\",\n\t\t\t\tid: request.id,\n\t\t\t\tcode: removed.error,\n\t\t\t\tmessage: removed.detail ?? removed.error,\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tconnection.send({ type: \"ok\", id: request.id });\n\t\treturn;\n\t}\n\n\tconst workspaces = resolveRequestWorkspaces(state.workspaces, request.workspaceName);\n\tif (!workspaces.ok) {\n\t\tsendWorkspaceNotFound(workspaces.missing);\n\t\treturn;\n\t}\n\tconst results: Array<{ workspaceName: string; removedRecords: string[]; orphanCheckouts: string[] }> = [];\n\tfor (const workspace of workspaces.workspaces) {\n\t\tconst pruned = await hooks.manager.prune(workspace);\n\t\tresults.push({ workspaceName: workspace.name, ...pruned });\n\t}\n\tconnection.send({ type: \"worktree_prune_result\", id: request.id, results });\n}\n\nfunction resolveRequestWorkspaces(\n\tworkspaces: IrohRemoteWorkspace[],\n\tworkspaceName: string | undefined,\n): { ok: true; workspaces: IrohRemoteWorkspace[] } | { ok: false; missing: string } {\n\tif (workspaceName === undefined) {\n\t\treturn { ok: true, workspaces };\n\t}\n\tconst workspace = workspaces.find((entry) => entry.name === workspaceName);\n\treturn workspace ? { ok: true, workspaces: [workspace] } : { ok: false, missing: workspaceName };\n}\n\nfunction toControlWorktreeStatus(\n\tworktree: IrohRemoteWorkspaceWorktree & Partial<Pick<WorktreeStatus, \"aheadBehind\">>,\n\tavailable?: boolean,\n\tdirty?: boolean,\n): ControlWorktreeStatus {\n\treturn {\n\t\tid: worktree.id,\n\t\tworkspaceName: worktree.workspaceName,\n\t\tpath: worktree.path,\n\t\tbranch: worktree.branch,\n\t\t...(worktree.baseRef === undefined ? {} : { baseRef: worktree.baseRef }),\n\t\tcreatedAt: worktree.createdAt,\n\t\tsessionIds: [...worktree.sessionIds],\n\t\t...(available === undefined ? {} : { available }),\n\t\t...(dirty === undefined ? {} : { dirty }),\n\t\t...(worktree.aheadBehind === undefined ? {} : { aheadBehind: worktree.aheadBehind }),\n\t};\n}\n"]}