@agentproto/worktree 0.5.2 → 0.5.5

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { worktreeProvider } from './provider/index.js';
 import { z } from 'zod';
 import http from 'node:http';
 import { RuntimeWorkflow, AgentSessionHost } from '@agentproto/workflow-runtime';
-import { StartAgentArgs, SessionDescriptor, TurnEvent, TurnResult, HarnessClient, ConnectHarnessOptions } from '@agentproto/harness';
+import { StartAgentArgs, SessionDescriptor, TurnEvent, TurnResult, SessionUsageSnapshot, HarnessClient, ConnectHarnessOptions } from '@agentproto/harness';
 import '@agentproto/tool';
 import '@agentproto/driver';
 
@@ -996,6 +996,15 @@ type LivenessState = {
  * `daemon-unreachable` fires only when the sessions snapshot itself is
  * present but unreadable (corrupt/permission-denied), not merely absent —
  * "no daemon has ever run" is a legitimate empty registry, not an error.
+ *
+ * `options.sessionsPath` is passed straight to `readSessionsRegistry`
+ * un-defaulted — same as `computeProvenance` — so an omitted path resolves
+ * to the bucket-union-plus-legacy read (AIP-46 §State partitioning,
+ * `provenance.ts`'s header), not just the frozen legacy file. Defaulting to
+ * `SESSIONS_FILE_PATH()` here used to silently blind this check to every
+ * session living in a per-workspace bucket — i.e. every session created
+ * after the AIP-46 partitioning shipped — which is how a running session's
+ * own cwd got classified `reclaim` by `gc` in production.
  */
 declare function computeLiveness(worktreePath: string, options?: ComputeProvenanceOptions): Promise<LivenessState>;
 type GateState = {
@@ -1074,7 +1083,11 @@ interface ListWorktreeStatusesInput {
 declare function listWorktreeStatuses(input: ListWorktreeStatusesInput): Promise<WorktreeStatusEntry[]>;
 
 /** The subset of `HarnessClient` the host drives — narrowed for fake-client tests. */
-type DaemonClient = Pick<HarnessClient, "start" | "prompt" | "output" | "kill" | "waitForAny" | "close">;
+type DaemonClient = Pick<HarnessClient, "start" | "prompt" | "output" | "kill" | "waitForAny" | "currentEventsCursor" | "close"> & {
+    /** `session_usage` — optional so pre-existing fakes/clients without it still
+     *  satisfy the type; the host simply exposes no `usage` then. */
+    usage?: HarnessClient["usage"];
+};
 interface DaemonAgentSessionHost extends AgentSessionHost {
     close(): Promise<void>;
     /** Full `agent_start`, returning the raw descriptor and forwarding every
@@ -1099,7 +1112,16 @@ interface DaemonAgentSessionHost extends AgentSessionHost {
     waitForAny(sessionIds: string[], opts?: {
         timeoutMs?: number;
         event?: TurnEvent;
+        since?: number;
     }): Promise<TurnResult>;
+    /** Race-free cursor for a subsequent `waitForAny({ since })` — see
+     *  `HarnessClient.currentEventsCursor`. */
+    currentEventsCursor(): Promise<number>;
+    /** Usage accounting for a session on this daemon (`session_usage`) — present
+     *  when the underlying client can answer it. `@agentproto/sandbox`'s host
+     *  inherits it, which is how a sandboxed session's cost/tokens/model reach
+     *  the HOST daemon's descriptor (the proxy's text stream carries none). */
+    usage?(sessionId: string): Promise<SessionUsageSnapshot>;
 }
 /**
  * Connect to the agentproto daemon's MCP endpoint and return a real,
@@ -1173,8 +1195,18 @@ interface ClassifyForGcOptions {
  * also depends on.
  */
 declare function classifyForGc(tree: TreeState, integration: IntegrationState, liveness: LivenessState, options?: ClassifyForGcOptions): GcClass;
-/** The only reclaim reason this module can attach today. */
-type GcReclaimReason = "dep-bump";
+/**
+ * The reclaim reasons this module can attach. `dep-bump` promotes a `hold`
+ * to `reclaim` (see above). `orphan` is different in kind — it never starts
+ * from a `hold` verdict at all, because an orphan was never classified in
+ * the first place (see the "orphan reclaim" section below): a directory
+ * physically present under the repo's worktree pool that `git worktree
+ * list` no longer knows about, so none of `classify`'s three axes can be
+ * computed for it.
+ */
+type GcReclaimReason = "dep-bump" | "orphan";
+/** The hold reasons this module can attach, distinct from `classify`'s snapshot-based holds. */
+type GcHoldReason = "live-session-cwd";
 /**
  * Layer 3+4 of the exemption: EVERY commit ahead of `baseRef` must have a
  * dep-bump subject (`git log --format=%s`, two-dot range — exactly the
@@ -1214,13 +1246,30 @@ interface GcPlanEntry {
     path: string;
     branch: string | null;
     head: string;
-    tree: TreeState;
-    integration: IntegrationState;
-    liveness: LivenessState;
+    /**
+     * Absent only for an orphan entry (`orphan: true`) — git itself cannot
+     * answer the tree/integration/liveness questions for a directory it no
+     * longer recognizes as a worktree, so this module never fabricates a
+     * value for them rather than reporting a fact it can't actually check.
+     */
+    tree?: TreeState;
+    integration?: IntegrationState;
+    liveness?: LivenessState;
     /** Classification per PLAN.md §5.1, after `--include-detached` (if set). */
     class: GcClass;
-    /** Set only when `class === "reclaim"` via the dep-bump exemption — see `resolveGcClass`. */
+    /** Set only when `class === "reclaim"` via the dep-bump exemption or the orphan reclaim path — see `resolveGcClass` / `scanOrphanWorktreePaths`. */
     reclaimReason?: GcReclaimReason;
+    /** Set only when `class === "hold"` via `protectedPaths` (`isProtectedPath`) — distinguishes this from an ordinary snapshot-based hold. */
+    holdReason?: GcHoldReason;
+    /**
+     * `true` only for a directory the orphan scan found: physically present
+     * under the repo's worktree pool, but absent from `git worktree list`
+     * (even after `git worktree prune`) — the interrupted-`worktree remove`
+     * shape (module docblock's §5 note). Always paired with `class: "reclaim"`
+     * and `reclaimReason: "orphan"`. Never set for a linked worktree, however
+     * it classifies.
+     */
+    orphan?: boolean;
 }
 interface PlanGcInput {
     repoRoot: string;
@@ -1233,6 +1282,23 @@ interface PlanGcInput {
     now?: () => string;
     /** See `ComputeWorktreeStatusInput.nowMs` (status.ts) — kept separate from `now`. Defaults to `Date.now()`. */
     nowMs?: number;
+    /**
+     * The bucket directory this repo's worktrees are provisioned under — e.g.
+     * `<worktrees.root>/<repoLabel>` (see `resolveWorktreesRoot` / `repoLabel`,
+     * both resolved by the caller; this module does no root resolution of its
+     * own, see the orphan-reclaim section below). When omitted, orphan
+     * scanning is skipped entirely and `planGc`/`applyGc` behave exactly as
+     * before — every existing caller that doesn't pass this sees zero change.
+     */
+    worktreesRoot?: string;
+    /**
+     * Absolute paths (typically live session cwds) that must never be
+     * classified `reclaim`/`salvage`, exact-or-subdirectory (`isProtectedPath`)
+     * — see the "live-session-cwd protection" section above. Applies to both
+     * linked worktrees and orphan-scan entries. Omitted ⇒ no additional
+     * protection beyond `classify`'s own snapshot-based liveness axis.
+     */
+    protectedPaths?: string[];
 }
 /**
  * The dry-run plan (PLAN.md §5.2 layer 1): classify every linked worktree,
@@ -1255,6 +1321,8 @@ interface ApplyGcOptions {
     nowMs?: number;
     /** Override for `~/.agentproto/worktree-salvage` — tests use a temp dir. */
     salvageRoot?: string;
+    /** See `PlanGcInput.protectedPaths` — re-checked here at apply time (layer 2), independent of what the plan entry says, so a stale plan can never remove a now-protected path. */
+    protectedPaths?: string[];
 }
 type GcApplyOutcome = {
     path: string;
@@ -1270,6 +1338,7 @@ type GcApplyOutcome = {
     path: string;
     branch: string | null;
     result: "held";
+    holdReason?: GcHoldReason;
 }
 /** Salvage-class, but `--salvage-dirty` was not passed: left untouched by design. */
  | {
@@ -1284,6 +1353,7 @@ type GcApplyOutcome = {
     result: "aborted-reclassified";
     from: GcClass;
     to: GcClass;
+    holdReason?: GcHoldReason;
 }
 /** The worktree named in the plan no longer exists (already removed by something else since the plan was made). */
  | {
@@ -1306,5 +1376,20 @@ type GcApplyOutcome = {
  * `git worktree remove`.
  */
 declare function applyGc(plan: readonly GcPlanEntry[], options: ApplyGcOptions): Promise<GcApplyOutcome[]>;
+/**
+ * Attempt to reclaim exactly one worktree by path — the exit-time auto-
+ * reclaim primitive `sessions.ts` calls (via the injected
+ * `WorktreeAutoReclaimer` port) when a policy-provisioned session reaches a
+ * terminal state. Classifies it fresh (never trusts a caller-supplied
+ * verdict) and only ever removes it when that classification is `reclaim`
+ * (merged-or-fresh, clean, idle) — a dirty or held worktree is returned
+ * as-is, exactly like any other `gc` outcome, still visible via
+ * `worktree_status` and still manually reclaimable. Returns `null` when the
+ * path no longer names a linked worktree at all (already removed by
+ * something else — nothing to do, not an error).
+ */
+declare function reclaimOneWorktree(worktreePath: string, options: ApplyGcOptions & {
+    includeDetached?: boolean;
+}): Promise<GcApplyOutcome | null>;
 
-export { type AgentprotoConfig, type ApplyGcOptions, CONFIG_FILENAME, type Classification, type ClassifyForGcOptions, type ComputeProvenanceOptions, type ComputeWorktreeStatusInput, ConfigError, DEFAULT_PROXY_PORT, type DaemonAgentSessionHost, type DaemonClient, ENV_VARS, type ExecOptions, type ExecResult, FileVerdictMemoStore, type ForgeClient, type ForgePullRequestRef, ForgeUnavailableError, type GateState, type GcApplyOutcome, type GcClass, type GcPlanEntry, type GcReclaimReason, GhCliForgeClient, type GitWorktreeRef, HookError, type HookRun, type HostnameParts, InMemoryVerdictMemoStore, type IntegrationState, type ListWorktreeStatusesInput, type LivenessState, type NamedScript, type PeerService, type PlanGcInput, type ProvenanceConfidence, type ProvenanceInfo, ProxyTable, type ReconcileIntegrationInput, type ResolveGcClassOptions, type ResolveSupervisorInput, type ResolvedGcClass, type ResolvedWorktreeRuntime, RestForgeClient, type RunningProxy, SALVAGE_ROOT, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, type SalvageManifest, type SalvageResult, type SalvageWorktreeInput, type ScriptConfig, type ServiceRuntime, type ServiceStatus, ServiceSupervisor, type SessionRef, type SupervisorOptions, type TreeState, UnreachableForgeClient, VERDICT_MEMO_PATH, type VerdictMemoRecord, type VerdictMemoStore, WORKTREES_TURBO_CACHE_DIR_ENV, type WorktreeAgentInput, type WorktreeClass, type WorktreeEnvContext, type WorktreeMarker, WorktreeNotRemovableError, type WorktreeStatusEntry, allocatePort, applyGc, classify, classifyForGc, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, connectDaemonAgentSessionHost, createForgeClient, createProxyServer, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isMechanicalDepBumpRange, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, makeDaemonAgentSessionHost, normalizeHook, parseConfig, parseGithubOwnerRepo, peerEnv, peerEnvKey, planGc, readSessionsRegistry, readWorktreeMarker, reconcileIntegration, repoLabel, resolveGcClass, resolveSupervisor, resolveWorktreesTurboCacheDir, runSetup, runTeardown, salvageWorktree, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, startProxy, stripPort, worktreeAgentInputSchema, worktreeAgentWorkflow, writeWorktreeMarker };
+export { type AgentprotoConfig, type ApplyGcOptions, CONFIG_FILENAME, type Classification, type ClassifyForGcOptions, type ComputeProvenanceOptions, type ComputeWorktreeStatusInput, ConfigError, DEFAULT_PROXY_PORT, type DaemonAgentSessionHost, type DaemonClient, ENV_VARS, type ExecOptions, type ExecResult, FileVerdictMemoStore, type ForgeClient, type ForgePullRequestRef, ForgeUnavailableError, type GateState, type GcApplyOutcome, type GcClass, type GcHoldReason, type GcPlanEntry, type GcReclaimReason, GhCliForgeClient, type GitWorktreeRef, HookError, type HookRun, type HostnameParts, InMemoryVerdictMemoStore, type IntegrationState, type ListWorktreeStatusesInput, type LivenessState, type NamedScript, type PeerService, type PlanGcInput, type ProvenanceConfidence, type ProvenanceInfo, ProxyTable, type ReconcileIntegrationInput, type ResolveGcClassOptions, type ResolveSupervisorInput, type ResolvedGcClass, type ResolvedWorktreeRuntime, RestForgeClient, type RunningProxy, SALVAGE_ROOT, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, type SalvageManifest, type SalvageResult, type SalvageWorktreeInput, type ScriptConfig, type ServiceRuntime, type ServiceStatus, ServiceSupervisor, type SessionRef, type SupervisorOptions, type TreeState, UnreachableForgeClient, VERDICT_MEMO_PATH, type VerdictMemoRecord, type VerdictMemoStore, WORKTREES_TURBO_CACHE_DIR_ENV, type WorktreeAgentInput, type WorktreeClass, type WorktreeEnvContext, type WorktreeMarker, WorktreeNotRemovableError, type WorktreeStatusEntry, allocatePort, applyGc, classify, classifyForGc, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, connectDaemonAgentSessionHost, createForgeClient, createProxyServer, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isMechanicalDepBumpRange, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, makeDaemonAgentSessionHost, normalizeHook, parseConfig, parseGithubOwnerRepo, peerEnv, peerEnvKey, planGc, readSessionsRegistry, readWorktreeMarker, reclaimOneWorktree, reconcileIntegration, repoLabel, resolveGcClass, resolveSupervisor, resolveWorktreesTurboCacheDir, runSetup, runTeardown, salvageWorktree, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, startProxy, stripPort, worktreeAgentInputSchema, worktreeAgentWorkflow, writeWorktreeMarker };

package/dist/index.mjs

@@ -1,12 +1,12 @@
-export { connectDaemonAgentSessionHost, makeDaemonAgentSessionHost, worktreeAgentInputSchema, worktreeAgentWorkflow } from './chunk-PSNNWGAF.mjs';
+export { connectDaemonAgentSessionHost, makeDaemonAgentSessionHost, worktreeAgentInputSchema, worktreeAgentWorkflow } from './chunk-R6UERXV4.mjs';
 import './chunk-E3EM24BS.mjs';
-import { computeProvenance, execArgv, classify, computeWorktreeStatus, listGitWorktrees, worktreeProvider } from './chunk-S5ARFUTK.mjs';
-export { CONFIG_FILENAME, ConfigError, DEFAULT_PROXY_PORT, ENV_VARS, FileVerdictMemoStore, HookError, InMemoryVerdictMemoStore, ProxyTable, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, ServiceSupervisor, VERDICT_MEMO_PATH, WORKTREES_TURBO_CACHE_DIR_ENV, WorktreeNotRemovableError, allocatePort, classify, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, normalizeHook, parseConfig, peerEnv, peerEnvKey, readSessionsRegistry, readWorktreeMarker, reconcileIntegration, repoLabel, resolveSupervisor, resolveWorktreesTurboCacheDir, runSetup, runTeardown, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, stripPort, worktreeProvider, writeWorktreeMarker } from './chunk-S5ARFUTK.mjs';
+import { computeProvenance, execArgv, classify, computeWorktreeStatus, listGitWorktrees, worktreeProvider } from './chunk-Y2TW7PBC.mjs';
+export { CONFIG_FILENAME, ConfigError, DEFAULT_PROXY_PORT, ENV_VARS, FileVerdictMemoStore, HookError, InMemoryVerdictMemoStore, ProxyTable, SESSIONS_BUCKETS_ROOT, SESSIONS_FILE_PATH, ServiceSupervisor, VERDICT_MEMO_PATH, WORKTREES_TURBO_CACHE_DIR_ENV, WorktreeNotRemovableError, allocatePort, classify, computeLiveness, computeProvenance, computeTreeState, computeWorktreeStatus, detectDefaultBranch, disposeSupervisor, ephemeralPort, execArgv, execGit, execShell, expandGlob, getScript, getSupervisor, globToRegExp, hookEnv, isPortFree, listGitWorktrees, listScripts, listServices, listWorktreeStatuses, loadConfigFromBase, normalizeHook, parseConfig, peerEnv, peerEnvKey, readSessionsRegistry, readWorktreeMarker, reconcileIntegration, repoLabel, resolveSupervisor, resolveWorktreesTurboCacheDir, runSetup, runTeardown, serviceEnv, serviceEnvToken, serviceHostname, serviceUrl, sessionInWorktree, sharedProxyTable, slugify, stripPort, worktreeProvider, writeWorktreeMarker } from './chunk-Y2TW7PBC.mjs';
 import { cleanupWorktreeTool } from './chunk-CM3XGWTY.mjs';
 export { cleanupWorktreeTool, listServicesTool, provisionWorktreeTool, runGateTool, runScriptTool, serviceStatusSchema, startServiceTool, stopServiceTool } from './chunk-CM3XGWTY.mjs';
-import { mkdir, copyFile, writeFile, open } from 'fs/promises';
+import { mkdir, copyFile, writeFile, open, readdir, realpath, rm, readFile, stat } from 'fs/promises';
 import { homedir } from 'os';
-import { resolve, join, dirname, basename } from 'path';
+import { resolve, join, dirname, basename, sep, relative, isAbsolute } from 'path';
 import http from 'http';
 import { connect } from 'net';
 import { z } from 'zod';
@@ -149,12 +149,12 @@ function startProxy(table, port = 0) {
     sockets.add(socket);
     socket.once("close", () => sockets.delete(socket));
   });
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     server.once("error", reject);
     server.listen(port, () => {
       const address = server.address();
       const boundPort = address && typeof address === "object" ? address.port : port;
-      resolve2({
+      resolve3({
         port: boundPort,
         server,
         close: () => new Promise((res) => {
@@ -428,6 +428,10 @@ function classifyForGc(tree, integration, liveness, options = {}) {
   }
   return classify(tree, integration, liveness, options.nowMs).class;
 }
+function isProtectedPath(worktreePath, protectedPaths) {
+  if (!protectedPaths || protectedPaths.length === 0) return false;
+  return protectedPaths.some((p) => p === worktreePath || p.startsWith(worktreePath + sep));
+}
 var DEP_BUMP_SUBJECT_RE = /^(?:chore|fix)\(deps[\w-]*\):\s/;
 function isDepBumpSubject(subject) {
   return DEP_BUMP_SUBJECT_RE.test(subject);
@@ -462,7 +466,116 @@ async function linkedWorktreesOf(repoRoot) {
   const worktrees = await listGitWorktrees(repoRoot);
   return worktrees.filter((w) => w.path !== repoRoot);
 }
-async function toPlanEntry(repoRoot, defaultBranchRef, worktree, status, includeDetached, nowMs) {
+async function gitWorktreesDir(repoRoot) {
+  const res = await execArgv("git", ["-C", repoRoot, "rev-parse", "--git-common-dir"], repoRoot);
+  if (res.exitCode !== 0) {
+    throw new Error(
+      `git rev-parse --git-common-dir failed in ${repoRoot} (exit ${res.exitCode}): ${res.stderr.trim()}`
+    );
+  }
+  return join(resolve(repoRoot, res.stdout.trim()), "worktrees");
+}
+async function readGitdirPointer(worktreePath) {
+  let raw;
+  try {
+    raw = await readFile(join(worktreePath, ".git"), "utf8");
+  } catch {
+    return null;
+  }
+  const match = raw.match(/^gitdir:\s*(.+?)\s*$/m);
+  const target = match?.[1];
+  if (!target) return null;
+  return resolve(worktreePath, target);
+}
+async function belongsToRepo(repoRoot, worktreePath) {
+  const pointer = await readGitdirPointer(worktreePath);
+  if (!pointer) return false;
+  let worktreesDir;
+  try {
+    worktreesDir = await gitWorktreesDir(repoRoot);
+  } catch {
+    return false;
+  }
+  const rel = relative(worktreesDir, pointer);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function realOrResolved(path) {
+  try {
+    return await realpath(path);
+  } catch {
+    return resolve(path);
+  }
+}
+async function scanOrphanWorktreePaths(repoRoot, worktreesRoot) {
+  await execArgv("git", ["-C", repoRoot, "worktree", "prune"], repoRoot).catch(() => null);
+  const linkedRefs = await linkedWorktreesOf(repoRoot);
+  const linked = new Set(await Promise.all(linkedRefs.map((w) => realOrResolved(w.path))));
+  const entries = await readdir(worktreesRoot, { withFileTypes: true }).catch(() => []);
+  const orphans = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const candidate = resolve(worktreesRoot, entry.name);
+    if (linked.has(await realOrResolved(candidate))) continue;
+    if (await belongsToRepo(repoRoot, candidate)) orphans.push(candidate);
+  }
+  return orphans;
+}
+function makeOrphanPlanEntry(path, protectedPaths) {
+  if (isProtectedPath(path, protectedPaths)) {
+    return { path, branch: null, head: "", class: "hold", holdReason: "live-session-cwd" };
+  }
+  return { path, branch: null, head: "", class: "reclaim", reclaimReason: "orphan", orphan: true };
+}
+async function verifyOrphan(repoRoot, worktreePath) {
+  if (!await pathExists(worktreePath)) return "gone";
+  await execArgv("git", ["-C", repoRoot, "worktree", "prune"], repoRoot).catch(() => null);
+  const linked = await linkedWorktreesOf(repoRoot);
+  const realWorktreePath = await realOrResolved(worktreePath);
+  for (const w of linked) {
+    if (await realOrResolved(w.path) === realWorktreePath) return "not-orphan";
+  }
+  return await belongsToRepo(repoRoot, worktreePath) ? "confirmed" : "not-orphan";
+}
+async function reclaimOrphan(entry, options) {
+  const state = await verifyOrphan(options.repoRoot, entry.path);
+  if (state === "not-orphan") {
+    return { path: entry.path, branch: null, result: "aborted-reclassified", from: "reclaim", to: "hold" };
+  }
+  if (state === "confirmed") {
+    try {
+      await rm(entry.path, { recursive: true, force: true });
+    } catch (err) {
+      return {
+        path: entry.path,
+        branch: null,
+        result: "failed",
+        message: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  return { path: entry.path, branch: null, result: "reclaimed", reclaimReason: "orphan" };
+}
+async function toPlanEntry(repoRoot, defaultBranchRef, worktree, status, includeDetached, nowMs, protectedPaths) {
+  if (isProtectedPath(worktree.path, protectedPaths)) {
+    return {
+      path: worktree.path,
+      branch: worktree.branch,
+      head: worktree.head,
+      tree: status.tree,
+      integration: status.integration,
+      liveness: status.liveness,
+      class: "hold",
+      holdReason: "live-session-cwd"
+    };
+  }
   const resolved = await resolveGcClass(status.tree, status.integration, status.liveness, {
     repoRoot,
     tipSha: worktree.head,
@@ -497,7 +610,21 @@ async function planGc(input) {
       sessionsPath: input.sessionsPath,
       now: input.now
     });
-    entries.push(await toPlanEntry(input.repoRoot, input.defaultBranchRef, worktree, status, includeDetached, nowMs));
+    entries.push(
+      await toPlanEntry(
+        input.repoRoot,
+        input.defaultBranchRef,
+        worktree,
+        status,
+        includeDetached,
+        nowMs,
+        input.protectedPaths
+      )
+    );
+  }
+  if (input.worktreesRoot) {
+    const orphanPaths = await scanOrphanWorktreePaths(input.repoRoot, input.worktreesRoot);
+    for (const path of orphanPaths) entries.push(makeOrphanPlanEntry(path, input.protectedPaths));
   }
   return entries;
 }
@@ -592,6 +719,22 @@ async function salvageOne(options, worktree) {
   return { path: worktree.path, branch: worktree.branch, result: "salvaged", salvageDir };
 }
 async function applyOne(entry, options) {
+  if (isProtectedPath(entry.path, options.protectedPaths)) {
+    if (entry.class === "hold") {
+      return { path: entry.path, branch: entry.branch, result: "held", holdReason: "live-session-cwd" };
+    }
+    return {
+      path: entry.path,
+      branch: entry.branch,
+      result: "aborted-reclassified",
+      from: entry.class,
+      to: "hold",
+      holdReason: "live-session-cwd"
+    };
+  }
+  if (entry.orphan) {
+    return reclaimOrphan(entry, options);
+  }
   if (entry.class === "hold") {
     return { path: entry.path, branch: entry.branch, result: "held" };
   }
@@ -638,7 +781,31 @@ async function applyGc(plan, options) {
   }
   return outcomes;
 }
+async function reclaimOneWorktree(worktreePath, options) {
+  const worktree = await findWorktree(options.repoRoot, worktreePath);
+  if (!worktree) return null;
+  const status = await computeWorktreeStatus({
+    repoRoot: options.repoRoot,
+    repoName: options.repoName,
+    worktree,
+    forge: options.forge,
+    memo: options.memo,
+    defaultBranchRef: options.defaultBranchRef,
+    sessionsPath: options.sessionsPath,
+    now: options.now
+  });
+  const entry = await toPlanEntry(
+    options.repoRoot,
+    options.defaultBranchRef,
+    worktree,
+    status,
+    Boolean(options.includeDetached),
+    options.nowMs ?? Date.now(),
+    options.protectedPaths
+  );
+  return applyOne(entry, options);
+}
 
-export { ForgeUnavailableError, GhCliForgeClient, RestForgeClient, SALVAGE_ROOT, UnreachableForgeClient, applyGc, classifyForGc, createForgeClient, createProxyServer, isMechanicalDepBumpRange, parseGithubOwnerRepo, planGc, resolveGcClass, salvageWorktree, startProxy };
+export { ForgeUnavailableError, GhCliForgeClient, RestForgeClient, SALVAGE_ROOT, UnreachableForgeClient, applyGc, classifyForGc, createForgeClient, createProxyServer, isMechanicalDepBumpRange, parseGithubOwnerRepo, planGc, reclaimOneWorktree, resolveGcClass, salvageWorktree, startProxy };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map