opencode2-cow-worktree 0.2.0 → 0.4.1

package/README.md

@@ -148,7 +148,11 @@ clone (default `"none"`):
 - `"none"`: a request for `cow` produces a Deep clone or fails. Never a
   shallow worktree.
 - `"git"`: on a non-CoW filesystem the tool may build a regular `git`
-  worktree instead and report `mechanism: "git"`.
+  worktree instead and report `mechanism: "git"`. This works on opencode2
+  builds whose worktree create still accepts a `strategy` request
+  (2.0.2-era). From the projectID-era API onward (20260915 nightlies,
+  v2.0.3+) the create always runs the selected strategy and ignores the
+  field, so the non-CoW refusal surfaces and the fallback cannot engage.
 
 **`targetRoot`** — where `spawn_workspace` places the worktree. Unset (the
 default) means a sibling of the source, on the source's filesystem by
@@ -237,8 +241,10 @@ regardless of `fallback`. Only `spawn_workspace` consults the policy.
 - **"the target is on a different filesystem"** — set `worktree.directory` as
   shown above, or point `targetRoot` at the source's filesystem.
 - **`cow` fails on an ext4 or tmpfs project** — expected: that filesystem
-  cannot clone. Use the `git` fallback for tool calls, or let the project use
-  the built-in strategy.
+  cannot clone. On opencode2 builds from the projectID era (20260915
+  nightlies, v2.0.3+) the `git` fallback cannot be requested through the
+  create API, so the refusal is final; on 2.0.2-era builds the `fallback:
+  "git"` option produces a regular git worktree for tool calls.
 - **The plugin is stuck on an old version** — opencode2 caches the package
   under `~/.cache/opencode/node_modules/`. Remove the plugin's cache
   directory and restart: `rm -rf ~/.cache/opencode/node_modules/opencode2-cow-worktree`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode2-cow-worktree",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Copy-on-write worktree strategy for opencode2: a Deep clone of the whole working directory, ignored files included, so parallel agents start ready to run",
   "type": "module",
   "exports": {

package/src/clone.ts

@@ -108,6 +108,13 @@ async function cloneInto(source: string, target: string, skip: string): Promise<
       await cloneInto(from, to, skip);
     } else if (kind === "symlink") {
       await symlink(await readlink(from), to);
+    } else if (kind === "special") {
+      // A socket, FIFO, or device node (e.g. a live daemon socket at a
+      // project root) cannot be reflinked — FICLONE fails with EOPNOTSUPP
+      // and would abort the whole clone. It is runtime state, not tree
+      // content, so the clone omits it; whatever created it in the source
+      // creates its own in the clone.
+      continue;
     } else {
       await reflinkFile(from, to);
     }

package/src/entry-kind.ts

@@ -10,27 +10,47 @@
  */
 
 /** How a directory entry is materialised by the clone walker. */
-export type EntryKind = "file" | "directory" | "symlink";
+export type EntryKind = "file" | "directory" | "symlink" | "special";
 
 /** The slice of a `readdir` Dirent this decision reads. */
 export interface EntryLike {
   isSymbolicLink(): boolean;
   isDirectory(): boolean;
   isFile(): boolean;
+  isSocket(): boolean;
+  isFIFO(): boolean;
+  isBlockDevice(): boolean;
+  isCharacterDevice(): boolean;
 }
 
 /** The slice of `lstat` this decision reads; `lstat` never follows a symlink. */
 export interface StatLike {
   isSymbolicLink(): boolean;
   isDirectory(): boolean;
+  isSocket(): boolean;
+  isFIFO(): boolean;
+  isBlockDevice(): boolean;
+  isCharacterDevice(): boolean;
 }
 
 export async function entryKind(entry: EntryLike, stat: () => Promise<StatLike>): Promise<EntryKind> {
   if (entry.isSymbolicLink()) return "symlink";
   if (entry.isDirectory()) return "directory";
   if (entry.isFile()) return "file";
+  if (isSpecial(entry)) return "special";
   const stats = await stat();
   if (stats.isSymbolicLink()) return "symlink";
   if (stats.isDirectory()) return "directory";
+  if (isSpecial(stats)) return "special";
   return "file";
 }
+
+/** Sockets, FIFOs, and devices: runtime artifacts, never tree content. */
+function isSpecial(s: {
+  isSocket(): boolean;
+  isFIFO(): boolean;
+  isBlockDevice(): boolean;
+  isCharacterDevice(): boolean;
+}): boolean {
+  return s.isSocket() || s.isFIFO() || s.isBlockDevice() || s.isCharacterDevice();
+}

package/src/plugin.ts

@@ -4,6 +4,12 @@ import { probeCowCapability } from "./capability";
 import { fallbackPolicy, postCreateHooks, targetRoot } from "./config";
 import { deviceOf, isDirectory } from "./device";
 import { readMarkerFile, writeMarkerFile } from "./occupancy";
+import { probeUncommitted } from "./uncommitted";
+import { removeWorktree, runGit } from "./remove-tool";
+import type {
+  RemoveWorktreeDeps,
+  RemoveWorktreeInput,
+} from "./remove-tool";
 import { listCowWorktrees, spawnWorkspace } from "./tool";
 import type {
   FallbackPolicy,
@@ -78,7 +84,20 @@ const spawnWorkspaceOutput = {
  */
 const listWorktreesInput = {
   type: "object",
-  properties: {},
+  properties: {
+    missing: {
+      type: "string",
+      enum: ["fail", "report", "prune"],
+      description:
+        "Policy for an inventory row whose directory is gone (stat ENOENT — a dangling " +
+        'reference). "fail" (default) keeps the ADR 0003 contract: the list fails loudly. ' +
+        '"report" lists the row with missing: true and no createdAt. "prune" de-registers ' +
+        "the row through the worktree remove API and drops it from the listing; until " +
+        "upstream candidate 8 lands, a gone directory cannot be de-registered, so prune " +
+        "fails loudly naming candidate 8. A stat failure that is not ENOENT fails in " +
+        "every mode: it is a real anomaly, not a dangling row.",
+    },
+  },
   additionalProperties: false,
 } as const;
 
@@ -113,10 +132,17 @@ const listWorktreesOutput = {
             type: "string",
             description:
               "ISO 8601 timestamp of the directory's birthtime, falling back to its " +
-              "mtime when the filesystem reports no birthtime.",
+              "mtime when the filesystem reports no birthtime. Absent on an entry " +
+              "reported with missing: true — there is no directory to stat.",
+          },
+          missing: {
+            type: "boolean",
+            description:
+              "Present and true only under missing: \"report\", for an inventory row " +
+              "whose directory no longer exists.",
           },
         },
-        required: ["name", "directory", "strategy", "createdAt"],
+        required: ["name", "directory", "strategy"],
         additionalProperties: false,
       },
     },
@@ -125,6 +151,51 @@ const listWorktreesOutput = {
   additionalProperties: false,
 } as const;
 
+/**
+ * `remove_worktree`'s input: exactly one of `name` or `directory` (validated
+ * in the execute path — the JSON Schema cannot express "exactly one of" two
+ * properties, so the schema leaves both optional and the tool refuses
+ * anything else). `force` is the same confirmation the TUI's remove carries:
+ * proceed despite unlanded or uncommitted work.
+ */
+const removeWorktreeInput = {
+  type: "object",
+  properties: {
+    name: {
+      type: "string",
+      description: "The worktree's basename, as list_worktrees reports it.",
+    },
+    directory: {
+      type: "string",
+      description: "The worktree directory, as the worktree inventory records it.",
+    },
+    force: {
+      type: "boolean",
+      description:
+        "Remove even when the worktree holds unlanded commits or uncommitted files.",
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+/**
+ * `remove_worktree`'s declared output, under the same rule as the other two
+ * tools: a returned `output` field must have a declared schema. Whether force
+ * was used is reported in the text content only — the structured result is
+ * the one fact every caller needs, the directory that is gone.
+ */
+const removeWorktreeOutput = {
+  type: "object",
+  properties: {
+    directory: {
+      type: "string",
+      description: "The removed worktree directory, as the inventory recorded it.",
+    },
+  },
+  required: ["directory"],
+  additionalProperties: false,
+} as const;
+
 /**
  * Binds `spawnWorkspace`'s seams to the live opencode2 context. The tool is
  * the layer that owns the strategy choice, so the capability probe and the
@@ -146,21 +217,27 @@ function liveDeps(
   return {
     probe: probeCowCapability,
     probeDevice: deviceOf,
-    listWorktrees: () => ctx.worktree.list(),
+    // The projectID-era API (20260915 nightlies onward) requires the project
+    // id on every worktree call and no longer accepts a `location` query, so
+    // all three seams derive it from the plugin's own location context.
+    listWorktrees: () => ctx.worktree.list({ projectID: ctx.location.project.id }),
     isDirectory,
     createWorktree: (input) =>
       ctx.worktree.create({
-        strategy: input.strategy,
-        name: input.name,
-        location: { directory: input.sourceDirectory },
+        projectID: ctx.location.project.id,
+        from: input.sourceDirectory,
         directory: input.parentDirectory,
+        name: input.name,
+        // Ignored by projectID-era binaries (the selected strategy wins);
+        // honored by the 2.0.2-era API, where the git fallback needs it.
+        strategy: input.strategy,
       }),
     createSession: async (directory, name) => {
       const session = await ctx.session.create({ title: name, location: { directory } });
       return session.id;
     },
     removeWorktree: (directory) =>
-      ctx.worktree.remove({ directory, force: true }),
+      ctx.worktree.remove({ projectID: ctx.location.project.id, directory, force: true }),
     // `ctx.session.get` exists on the v2 runtime but is untyped in the
     // installed beta; types/opencode2-worktree.d.ts declares the verified
     // `{ sessionID }` shape and the structural record slice the occupancy
@@ -174,14 +251,32 @@ function liveDeps(
   };
 }
 
+/**
+ * Whether a path exists — the dangling-row pre-check's live binding. ENOENT
+ * answers "no"; any other stat failure (a permission problem, an I/O error)
+ * propagates, because an unreadable directory is a real anomaly the caller
+ * must see, not a dangling row.
+ */
+async function directoryPresent(directory: string): Promise<boolean> {
+  try {
+    await stat(directory);
+    return true;
+  } catch (cause) {
+    if ((cause as { code?: unknown }).code === "ENOENT") return false;
+    throw cause;
+  }
+}
+
 /**
  * The opencode2 plugin module.
  *
  * `setup` registers the `cow` Strategy through the worktree seam, and the
  * `spawn_workspace` and `list_worktrees` tools through the tool seam.
- * Registering the Strategy also selects it as the Location default; opencode2's
- * registry still lets a caller name the built-in `git` strategy explicitly, so
- * this module does not touch that behavior.
+ * Registering the Strategy also selects it as the default; the projectID-era
+ * create API has no per-request strategy field, so the selected strategy is
+ * what every create uses. The create call still carries `strategy` for
+ * 2.0.2-era binaries, where it is what lets the tool's opt-in `git` fallback
+ * name the built-in git strategy.
  */
 export default {
   id: "opencode2-cow-worktree",
@@ -240,20 +335,29 @@ export default {
           "(birthtime, falling back to mtime when the filesystem reports none). Derived from " +
           "opencode2's worktree inventory alone — there is no sessions field, because server " +
           "plugins cannot enumerate sessions (ADR 0003). The list fails rather than skipping " +
-          "when an inventory row's directory cannot be read: the inventory is truth.",
+          "when an inventory row's directory cannot be read: the inventory is truth. Pass " +
+          "missing: \"report\" or \"prune\" to opt out for dangling rows (a row whose " +
+          "directory is gone); see the missing knob's description for the exact policy.",
         input: listWorktreesInput,
         output: listWorktreesOutput,
         // Same reason as spawn_workspace above: callable by name, not routed
         // through CodeMode.
         options: { codemode: false },
-        execute: async () => {
+        execute: async (input: { readonly missing?: "fail" | "report" | "prune" }) => {
           const worktrees = await listCowWorktrees({
-            // Own minimal deps, not liveDeps: this read-only call touches only
-            // the inventory and one stat per row, none of spawn_workspace's
-            // other seams. (Option validation happens once in setup, so there
-            // is no validation side effect to dodge either way.)
-            listWorktrees: () => ctx.worktree.list(),
+            // Own minimal deps, not liveDeps: this call touches the inventory,
+            // one stat per row, and — in prune mode only — the remove API.
+            // None of spawn_workspace's other seams. (Option validation happens
+            // once in setup, so there is no validation side effect to dodge
+            // either way.)
+            listWorktrees: () => ctx.worktree.list({ projectID: ctx.location.project.id }),
             statEntry: stat,
+            missing: input.missing,
+            // The prune seam goes through the same DELETE route every other
+            // removal uses, forced: a dangling row's directory is already gone,
+            // so the strategy's dirty probe has nothing to protect.
+            removeEntry: (directory) =>
+              ctx.worktree.remove({ projectID: ctx.location.project.id, directory, force: true }),
           });
           const summary =
             worktrees.length === 0 ? "0 cow worktree(s)" : `${worktrees.length} cow worktree(s):`;
@@ -263,6 +367,47 @@ export default {
           };
         },
       });
+      editor.add({
+        name: "remove_worktree",
+        description:
+          "Remove a finished cow worktree so its directory and inventory row are cleaned up " +
+          "together — no rm -rf, no hand-editing opencode's SQLite. Takes exactly one of name " +
+          "(a basename from list_worktrees) or directory (a row's directory). A guard refuses " +
+          "while the worktree still holds unlanded work — commits not on the landing ref " +
+          "(origin/HEAD, else main, else master) or uncommitted files — naming the counts; " +
+          "an undetectable landing ref also refuses. force: true removes anyway. Only worktrees " +
+          "the cow strategy created are removable; rows whose directory is already gone cannot " +
+          "be cleared through the API yet (upstream candidate 8) and are refused.",
+        input: removeWorktreeInput,
+        output: removeWorktreeOutput,
+        // Same reason as spawn_workspace above: callable by name, not routed
+        // through CodeMode.
+        options: { codemode: false },
+        execute: async (input: RemoveWorktreeInput) => {
+          const result = await removeWorktree(input, {
+            listWorktrees: () => ctx.worktree.list({ projectID: ctx.location.project.id }),
+            // Force passes through verbatim: on the guard-passed clean path
+            // `false` lets the strategy's own dirty probe run (and pass); at
+            // `true` the strategy skips it. The quarantine mechanics stay in
+            // the strategy.
+            removeWorktree: (directory, force) =>
+              ctx.worktree.remove({ projectID: ctx.location.project.id, directory, force }),
+            directoryExists: directoryPresent,
+            runGit,
+            probeUncommitted,
+          } satisfies RemoveWorktreeDeps);
+          // The text is what carries the force story: the structured output is
+          // only the directory, so a caller reading `output` alone still learns
+          // the one fact that matters — this directory is gone.
+          const content =
+            `Removed cow worktree ${result.directory}.` +
+            (result.forced ? " Force was used: the landed-ness guard was bypassed." : "");
+          return {
+            output: { directory: result.directory },
+            content,
+          };
+        },
+      });
     });
   },
 };

package/src/remove-tool.ts

@@ -0,0 +1,520 @@
+/**
+ * The `remove_worktree` tool's decision logic: clean up a finished cow lane —
+ * its directory *and* its inventory row together — without `rm -rf` and
+ * without hand-editing opencode's SQLite.
+ *
+ * WHY the landed-ness guard lives here and not in `strategy.remove`: the
+ * strategy's `remove` is also what opencode2's TUI drives, and its contract
+ * there is only the dirty probe (issue #13). Changing what the TUI's remove
+ * button does is not this tool's business, so the "has the lane's work
+ * landed?" question is asked one layer up, where only agents are affected.
+ * The strategy keeps its own dirty probe; this module adds the commit-level
+ * question on top.
+ *
+ * The allow rule: a worktree may be removed when its HEAD has **landed** — it
+ * is an ancestor of the landing ref (`origin/HEAD`, else `main`, else
+ * `master`) — or when it is clean *and* holds no commits the landing ref
+ * lacks. Anything else refuses, naming exactly what is unlanded, because an
+ * agent cleaning up a lane must not destroy the only copy of finished-but-
+ * unpushed work. A cow lane is a separate clone whose `origin/*` refs freeze
+ * at clone time, so a would-be refusal first runs one `git fetch origin` and
+ * re-judges on the fresh refs (issue #16); a pass on stale refs is already
+ * sound, so the happy path never fetches, and a failed fetch keeps the
+ * refusal while saying the verdict is stale-limited. An undetectable landing
+ * ref also refuses: "cannot judge" is not "landed". `force: true` bypasses
+ * the guard entirely — the human's confirmation, same meaning the TUI's
+ * remove confirmation carries.
+ *
+ * `force` is then passed through **verbatim** to opencode2's
+ * `ctx.worktree.remove`. When the guard passed because the tree is clean and
+ * holds no unique commits, `force: false` lets the strategy run its own dirty
+ * probe (which passes); at `force: true` the strategy skips it. Existing-
+ * clone semantics — the quarantine dance, the identity capture — stay in the
+ * strategy (`removal.ts`); none of that is re-implemented here.
+ *
+ * Identity and membership come from opencode2's worktree inventory (ADR 0003)
+ * through the same matcher attach uses (`inventoryEntryFor`): a directory the
+ * inventory does not know, or knows under another strategy, is not this
+ * tool's to delete. A row whose directory is already gone is refused before
+ * the guard: opencode2's DELETE route answers 400 "Worktree directory
+ * unavailable" even at `force:true` until upstream candidate 8 lands
+ * (`docs/research/upstream-issues.md`), so de-registering a dangling row is
+ * impossible through the API and the tool must say so instead of failing with
+ * a message that implies `force` would help.
+ *
+ * Every impure contact — the inventory, the removal, the directory check, git
+ * itself — is injected (`RemoveWorktreeDeps`), so the decision table is
+ * testable without opencode2 and without a git repository, exactly like
+ * `SpawnWorkspaceDeps` in `./tool`.
+ */
+import { execFile } from "node:child_process";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import type { UncommittedChanges } from "./dirty";
+import { inventoryEntryFor } from "./tool";
+import type { WorktreeInventoryEntry } from "../types/opencode2-worktree";
+
+/** How long one git invocation may run before the live binding gives up. */
+const GIT_TIMEOUT_MS = 5_000;
+
+const run = promisify(execFile);
+
+/** The outcome of one git invocation the guard ran through the seam. */
+export interface GitRun {
+  /** The process exit code: 0 means the command answered affirmatively. */
+  readonly code: number;
+  /** Standard output, when the command produced any. */
+  readonly stdout: string;
+}
+
+/**
+ * The seams `removeWorktree` drives. Injected like `SpawnWorkspaceDeps` so the
+ * refusal table is testable without opencode2, a filesystem, or git.
+ */
+export interface RemoveWorktreeDeps {
+  /**
+   * The worktree inventory (`ctx.worktree.list()`), the same seam attach and
+   * `list_worktrees` read. The inventory, not a plugin-owned registry, is the
+   * source of truth for "ours" (ADR 0003).
+   */
+  readonly listWorktrees: () => Promise<readonly WorktreeInventoryEntry[]>;
+  /**
+   * Removes a Worktree through opencode2's DELETE route
+   * (`ctx.worktree.remove`). `force` is passed verbatim: `false` lets the
+   * strategy's dirty probe run and pass on a clean tree, `true` skips it.
+   */
+  readonly removeWorktree: (directory: string, force: boolean) => Promise<void>;
+  /**
+   * Whether the worktree directory exists. The dangling-row pre-check asks
+   * exactly one question — is the directory there — before any guard work.
+   */
+  readonly directoryExists: (directory: string) => Promise<boolean>;
+  /**
+   * Runs one git command inside the worktree. The landed-ness guard's only
+   * contact with git: `symbolic-ref`, `rev-parse --verify --quiet`,
+   * `merge-base --is-ancestor`, `rev-list --count`, and the refusal path's
+   * `fetch origin` refresh. A non-zero exit is an answer ("no", "cannot"),
+   * never an exception.
+   */
+  readonly runGit: (args: string[], cwd: string) => Promise<GitRun>;
+  /**
+   * Reports a worktree's uncommitted paths, or `undefined` when that cannot
+   * be determined. The same probe the strategy's dirty guard uses
+   * (`probeUncommitted` from `./uncommitted`); an unknown is treated as
+   * dirty, exactly as `mayRemove` treats it.
+   */
+  readonly probeUncommitted: (directory: string) => Promise<UncommittedChanges>;
+}
+
+/** The tool's input, exactly as the JSON Schema declares it. */
+export interface RemoveWorktreeInput {
+  /** The worktree's basename, as `list_worktrees` reports it. */
+  readonly name?: string;
+  /** The worktree directory, as the inventory records it. */
+  readonly directory?: string;
+  /** Remove even when the worktree holds unlanded or uncommitted work. */
+  readonly force?: boolean;
+}
+
+/** What a successful removal produced: the directory, and whether force ran. */
+export interface RemoveWorktreeResult {
+  /** The removed directory, verbatim as the inventory recorded it. */
+  readonly directory: string;
+  /** True when `force: true` bypassed the landed-ness guard. */
+  readonly forced: boolean;
+}
+
+/**
+ * Removes one cow worktree by name or directory, guarded against destroying
+ * unlanded work. See the module doc for the why of each refusal.
+ *
+ * Order matters: the exactly-one-of selector check comes first (it is about
+ * the input, not the world), then the inventory resolution (which decides
+ * whether the target is ours at all), then the dangling-row pre-check (which
+ * must precede the guard — the guard would run git in a directory that is not
+ * there), then the landed-ness guard, and only then the removal itself.
+ */
+export async function removeWorktree(
+  input: RemoveWorktreeInput,
+  deps: RemoveWorktreeDeps,
+): Promise<RemoveWorktreeResult> {
+  const directory = await resolveTarget(input, deps);
+  await assertDirectoryPresent(directory, deps);
+  const forced = input.force === true;
+  if (!forced) await assertLanded(directory, deps);
+  await deps.removeWorktree(directory, forced);
+  return { directory, forced };
+}
+
+/** One of the two selector shapes, after the exactly-one-of check. */
+type Selector =
+  | { readonly kind: "directory"; readonly directory: string }
+  | { readonly kind: "name"; readonly name: string };
+
+/**
+ * Reads the input's selector: exactly one of `name`/`directory`, both
+ * non-empty. An empty string is not a selector — the same rule attach applies
+ * to `name` — so `{ name: "" }` refuses as "neither given" instead of
+ * resolving to nothing surprising.
+ */
+function selectorOf(input: RemoveWorktreeInput): Selector {
+  const name = typeof input.name === "string" && input.name.length > 0 ? input.name : undefined;
+  const directory =
+    typeof input.directory === "string" && input.directory.length > 0
+      ? input.directory
+      : undefined;
+  if (name !== undefined && directory !== undefined) {
+    throw new Error(
+      'remove_worktree takes exactly one of "name" or "directory", not both: pass the ' +
+        "worktree's basename from list_worktrees, or its directory as the inventory " +
+        "records it — both were given.",
+    );
+  }
+  if (name === undefined && directory === undefined) {
+    throw new Error(
+      'remove_worktree takes exactly one of "name" or "directory": pass the worktree\'s ' +
+        "basename from list_worktrees, or its directory as the inventory records it — " +
+        "neither was given.",
+    );
+  }
+  return name !== undefined
+    ? { kind: "name", name }
+    : { kind: "directory", directory: directory! };
+}
+
+/**
+ * Resolves the input's selector to the directory the inventory records, or
+ * refuses: an unknown directory as Foreign, a non-cow row as foreign
+ * strategy, an unknown or ambiguous name as a listing/ambiguity error.
+ */
+async function resolveTarget(
+  input: RemoveWorktreeInput,
+  deps: RemoveWorktreeDeps,
+): Promise<string> {
+  const selector = selectorOf(input);
+  const entries = await deps.listWorktrees();
+  return selector.kind === "directory"
+    ? resolveByDirectory(entries, selector.directory)
+    : resolveByName(entries, selector.name);
+}
+
+/**
+ * The directory selector: the same identity matcher attach uses
+ * (`inventoryEntryFor` — basename, exact string, then realpath/lexical
+ * normalization), so a worktree list_worktrees reports is removable under the
+ * spelling that report used. The removal targets the inventory-recorded
+ * spelling: that is the path opencode2's record holds.
+ */
+async function resolveByDirectory(
+  entries: readonly WorktreeInventoryEntry[],
+  directory: string,
+): Promise<string> {
+  const entry = await inventoryEntryFor(entries, directory);
+  if (entry === undefined) throw foreignWorktreeRemovalError(directory);
+  if (entry.strategy !== "cow") {
+    throw foreignStrategyRemovalError(directory, entry.strategy);
+  }
+  return entry.directory;
+}
+
+/**
+ * The name selector: the basename of a `cow` inventory row. Non-cow rows are
+ * filtered out first — a name can only ever resolve to a cow worktree, so a
+ * `git`-strategy row under the same basename is invisible to name lookups,
+ * not a foreign-strategy refusal. Zero matches lists what does exist; more
+ * than one names every candidate and asks for the directory.
+ */
+function resolveByName(
+  entries: readonly WorktreeInventoryEntry[],
+  name: string,
+): string {
+  const cow = entries.filter((entry) => entry.strategy === "cow");
+  const matches = cow.filter((entry) => basename(entry.directory) === name);
+  if (matches.length === 0) throw unknownNameError(name, cow);
+  if (matches.length > 1) throw ambiguousNameError(name, matches);
+  return matches[0]!.directory;
+}
+
+/**
+ * The dangling-row pre-check: a row whose directory is gone cannot be
+ * de-registered through the API at all — opencode2's DELETE route answers
+ * 400 "Worktree directory unavailable" even at `force:true` until upstream
+ * candidate 8 lands. Refusing here names the real obstacle; letting the call
+ * reach the API would surface that 400 as if `force` had not been tried.
+ */
+async function assertDirectoryPresent(
+  directory: string,
+  deps: RemoveWorktreeDeps,
+): Promise<void> {
+  if (await deps.directoryExists(directory)) return;
+  throw danglingRowError(directory);
+}
+
+/**
+ * The landed-ness guard, applied only when the caller did not force. It
+ * refuses while the worktree holds unlanded work and otherwise lets the
+ * removal proceed. Every sub-answer is fail-closed: an undetectable landing
+ * ref and an undeterminable dirty state both refuse, because "cannot judge"
+ * must never mean "safe to delete".
+ */
+async function assertLanded(
+  directory: string,
+  deps: RemoveWorktreeDeps,
+): Promise<void> {
+  const landingRef = await detectLandingRef(directory, deps);
+  if (landingRef === undefined) throw landingRefUnknownError(directory);
+  let check = await landingCheck(directory, landingRef, deps);
+  let refreshFailed = false;
+  if (!landed(check)) {
+    // A cow lane is a separate clone whose origin/<branch> refs freeze at
+    // clone time, so work that landed on the remote afterwards (a merged
+    // PR) looks unlanded here (issue #16). Refresh once and re-judge before
+    // refusing; a pass on stale refs is already sound, so the fetch only
+    // ever runs on the refusal path.
+    const fetched = await deps.runGit(["fetch", "origin"], directory);
+    if (fetched.code === 0) {
+      check = await landingCheck(directory, landingRef, deps);
+    } else {
+      refreshFailed = true;
+    }
+  }
+  if (landed(check)) return;
+  throw unlandedError(directory, landingRef, check, refreshFailed);
+}
+
+/** The guard's allow rule over one probe set. */
+function landed(check: LandingCheck): boolean {
+  const clean = check.uncommitted !== undefined && check.uncommitted.length === 0;
+  return check.landed || (clean && check.uniqueCommits === 0);
+}
+
+/** What the guard learned about one worktree's landed-ness. */
+interface LandingCheck {
+  /** `git merge-base --is-ancestor HEAD <ref>` exited 0. */
+  readonly landed: boolean;
+  /** `git rev-list --count <ref>..HEAD`, or `undefined` when it failed. */
+  readonly uniqueCommits: number | undefined;
+  /** The dirty probe's answer; `undefined` means it could not tell. */
+  readonly uncommitted: UncommittedChanges;
+}
+
+/** Runs the guard's three probes — ancestry, unique-commit count, dirty state. */
+async function landingCheck(
+  directory: string,
+  landingRef: string,
+  deps: RemoveWorktreeDeps,
+): Promise<LandingCheck> {
+  const ancestor = await deps.runGit(
+    ["merge-base", "--is-ancestor", "HEAD", landingRef],
+    directory,
+  );
+  const counted = await deps.runGit(
+    ["rev-list", "--count", `${landingRef}..HEAD`],
+    directory,
+  );
+  const uncommitted = await deps.probeUncommitted(directory);
+  return {
+    landed: ancestor.code === 0,
+    uniqueCommits: counted.code === 0 ? parseCount(counted.stdout) : undefined,
+    uncommitted,
+  };
+}
+
+/** A `rev-list --count` answer, or `undefined` when it is not a number. */
+function parseCount(stdout: string): number | undefined {
+  const count = Number.parseInt(stdout.trim(), 10);
+  return Number.isNaN(count) ? undefined : count;
+}
+
+/**
+ * The worktree's landing ref: the first of `origin/HEAD` (resolved through
+ * `git symbolic-ref`, trimmed to `origin/<branch>`), `main`, and `master`
+ * that `git rev-parse --verify --quiet` confirms. `undefined` when none
+ * resolves — which refuses, because landed-ness cannot be judged.
+ */
+async function detectLandingRef(
+  directory: string,
+  deps: RemoveWorktreeDeps,
+): Promise<string | undefined> {
+  const fromOriginHead = await originHeadRef(directory, deps);
+  if (fromOriginHead !== undefined && (await refResolves(fromOriginHead, directory, deps))) {
+    return fromOriginHead;
+  }
+  for (const candidate of ["main", "master"]) {
+    if (await refResolves(candidate, directory, deps)) return candidate;
+  }
+  return undefined;
+}
+
+/** The `origin/<branch>` ref `origin/HEAD` points at, when it answers one. */
+async function originHeadRef(
+  directory: string,
+  deps: RemoveWorktreeDeps,
+): Promise<string | undefined> {
+  const answer = await deps.runGit(
+    ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"],
+    directory,
+  );
+  if (answer.code !== 0) return undefined;
+  const ref = answer.stdout.trim();
+  // A symbolic-ref answer outside refs/remotes/ is not a remote branch this
+  // guard can name; treat it as no answer rather than passing it on.
+  return ref.startsWith("refs/remotes/") ? ref.slice("refs/remotes/".length) : undefined;
+}
+
+/** Whether `git rev-parse --verify --quiet <ref>` confirms the ref exists. */
+async function refResolves(
+  ref: string,
+  directory: string,
+  deps: RemoveWorktreeDeps,
+): Promise<boolean> {
+  const answer = await deps.runGit(["rev-parse", "--verify", "--quiet", ref], directory);
+  return answer.code === 0;
+}
+
+/**
+ * The unlanded refusal, naming exactly what has not landed. A failed
+ * `fetch` refresh is named too, so the operator knows the counts came from
+ * the refs frozen at clone time.
+ */
+function unlandedError(
+  directory: string,
+  landingRef: string,
+  check: LandingCheck,
+  refreshFailed: boolean,
+): Error {
+  const stale =
+    "A `git fetch origin` refresh failed, so this verdict used the remote " +
+    "refs frozen at clone time. ";
+  return new Error(
+    `refusing to remove ${directory}: it holds work that has not landed on ` +
+      `${landingRef} — ${describeUnlanded(check.uniqueCommits, check.uncommitted)}. ` +
+      (refreshFailed ? stale : "") +
+      "Re-run with force to remove anyway.",
+  );
+}
+
+/** The counts half of the unlanded refusal; unknowns are named as unknown. */
+function describeUnlanded(
+  uniqueCommits: number | undefined,
+  uncommitted: UncommittedChanges,
+): string {
+  const commits =
+    uniqueCommits === undefined
+      ? "an unknown number of unique commit(s) (the git probe failed)"
+      : `${uniqueCommits} unique commit(s)`;
+  const files =
+    uncommitted === undefined
+      ? "an unknown number of uncommitted file(s) (the probe could not answer)"
+      : `${uncommitted.length} uncommitted file(s)`;
+  return `${commits} and ${files}`;
+}
+
+/** The refusal for an undetectable landing ref; force still overrides. */
+function landingRefUnknownError(directory: string): Error {
+  return new Error(
+    `refusing to remove ${directory}: the landing ref could not be determined — ` +
+      "none of refs/remotes/origin/HEAD (via git symbolic-ref), main, or master " +
+      "resolves in this worktree, so landed-ness cannot be judged. " +
+      "Re-run with force to remove anyway.",
+  );
+}
+
+/** The refusal for a directory the inventory does not know at all. */
+function foreignWorktreeRemovalError(directory: string): Error {
+  return new Error(
+    `refusing to remove ${directory}: opencode2's worktree inventory has no entry ` +
+      "for it, so it is not a worktree this strategy materialized (a Foreign " +
+      "worktree). remove_worktree removes only worktrees its cow strategy " +
+      "created; if nothing needs what is inside, remove the directory by hand.",
+  );
+}
+
+/** The refusal for an inventory entry naming a strategy other than `cow`. */
+function foreignStrategyRemovalError(
+  directory: string,
+  strategy: string | undefined,
+): Error {
+  const described = strategy === undefined ? "no strategy" : `"${strategy}"`;
+  return new Error(
+    `refusing to remove ${directory}: the worktree inventory records it with ` +
+      `${described}, not "cow" — remove_worktree will not remove a Worktree ` +
+      "another strategy materialized. Remove it through opencode2 or by hand.",
+  );
+}
+
+/**
+ * The refusal for a row whose directory is gone: the API cannot clear it
+ * until upstream candidate 8 ("Worktree.remove resolves the real path before
+ * reading the record") lands, so the refusal names that instead of letting a
+ * 400 "Worktree directory unavailable" imply that `force` was not tried.
+ */
+function danglingRowError(directory: string): Error {
+  return new Error(
+    `refusing to remove ${directory}: the worktree directory no longer exists, so ` +
+      "the inventory row is dangling and cannot be de-registered through the API " +
+      'until upstream candidate 8 ("Worktree.remove resolves the real path before ' +
+      'reading the record") lands — the DELETE route answers 400 "Worktree directory ' +
+      "unavailable\" even at force:true. See docs/research/upstream-issues.md; " +
+      "until then, clearing the row means editing opencode.db by hand.",
+  );
+}
+
+/** The refusal for a name no cow row carries, listing the rows that exist. */
+function unknownNameError(
+  name: string,
+  cow: readonly WorktreeInventoryEntry[],
+): Error {
+  const known =
+    cow.length === 0
+      ? "this location's inventory has no cow worktrees"
+      : `known cow worktree(s): ${cow.map((entry) => basename(entry.directory)).join(", ")}`;
+  return new Error(
+    `no cow worktree named ${JSON.stringify(name)}: ${known}. ` +
+      "Run list_worktrees to see this location's cow worktrees.",
+  );
+}
+
+/** The refusal for a name several cow rows carry; the directory disambiguates. */
+function ambiguousNameError(
+  name: string,
+  matches: readonly WorktreeInventoryEntry[],
+): Error {
+  return new Error(
+    `the name ${JSON.stringify(name)} is ambiguous: ${matches.length} cow worktrees ` +
+      `share that basename — ${matches.map((entry) => entry.directory).join(", ")}. ` +
+      "Pass the full directory instead.",
+  );
+}
+
+/**
+ * The live `runGit` binding: one git invocation via `execFile` — no shell, no
+ * inherited prompt — with the same hygiene `probeUncommitted` uses. Declared
+ * total like the guard's other answers: every failure (non-zero exit,
+ * timeout, no git on the machine) resolves to a non-zero code, which each
+ * caller reads as "no"/"cannot". An exit code the error object carries is
+ * kept so a signal kill and a plain refusal are at least distinguishable in
+ * principle; anything unreadable is 1.
+ */
+export async function runGit(args: string[], cwd: string): Promise<GitRun> {
+  try {
+    const { stdout } = await run("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUT_MS,
+      env: { ...process.env, GIT_PAGER: "cat", GIT_EDITOR: "true", CI: "1" },
+    });
+    return { code: 0, stdout };
+  } catch (cause) {
+    return { code: exitCodeOf(cause), stdout: "" };
+  }
+}
+
+/** The exit code an execFile failure carries, when it carries one. */
+function exitCodeOf(cause: unknown): number {
+  if (typeof cause === "object" && cause !== null && "code" in cause) {
+    const code = (cause as { code: unknown }).code;
+    if (typeof code === "number") return code;
+  }
+  return 1;
+}

package/src/tool.ts

@@ -525,8 +525,17 @@ export interface CowWorktreeEntry {
   /** The worktree directory, verbatim as the inventory records it. */
   readonly directory: string;
   readonly strategy: "cow";
-  /** ISO 8601; derived from a directory stat. See `createdAtOf`. */
-  readonly createdAt: string;
+  /**
+   * ISO 8601; derived from a directory stat. See `createdAtOf`. Absent on a
+   * `missing` entry: with no directory to stat there is no timestamp to derive.
+   */
+  readonly createdAt?: string;
+  /**
+   * Set only under `missing: "report"`: the inventory still lists the row, but
+   * its directory is gone (the stat answered ENOENT). The directory stays
+   * verbatim from the inventory and `createdAt` is absent.
+   */
+  readonly missing?: true;
 }
 
 /**
@@ -548,11 +557,29 @@ export interface ListWorktreesDeps {
    */
   readonly listWorktrees: () => Promise<readonly WorktreeInventoryEntry[]>;
   /**
-   * Stats one inventory-listed directory. A failure here is not absorbed: the
-   * inventory is truth, so an unreadable row is a real anomaly and the list
-   * fails loudly instead of silently dropping the entry.
+   * Stats one inventory-listed directory, for `createdAt`. An ENOENT here is a
+   * dangling inventory row — a directory deleted out from under the inventory —
+   * handled per the `missing` policy. Any other failure is a real anomaly and
+   * fails the list in every mode.
    */
   readonly statEntry: (path: string) => Promise<StatTimes>;
+  /**
+   * What a dangling inventory row (its directory stats ENOENT) costs the call.
+   * `"fail"` — the default — keeps ADR 0003's fail-loud contract. `"report"`
+   * lists the row flagged `missing: true`, without `createdAt`. `"prune"`
+   * de-registers the row through `removeEntry` and drops it from the listing.
+   */
+  readonly missing?: "fail" | "report" | "prune";
+  /**
+   * De-registers one inventory row; the seam behind `missing: "prune"`, wired
+   * by the plugin to `ctx.worktree.remove` with force, so a gone directory is
+   * accepted as an already-completed deletion. A rejection is never absorbed:
+   * upstream candidate 8 ("Worktree.remove resolves the real path before
+   * reading the record", docs/research/upstream-issues.md) makes the delete
+   * answer 400 for a gone directory, so the caller must learn the row is
+   * still there.
+   */
+  readonly removeEntry?: (directory: string) => Promise<void>;
 }
 
 /**
@@ -564,22 +591,47 @@ export interface ListWorktreesDeps {
  * for CoW capability: per ADR 0003 the inventory is the source of truth, and
  * the only filesystem contact is one stat per surviving entry, for
  * `createdAt`.
+ *
+ * A row whose directory stats ENOENT is a dangling reference — deleted out
+ * from under the inventory, not a worktree to preserve. The default
+ * (`missing: "fail"`) keeps ADR 0003's fail-loud contract; `"report"` returns
+ * the row flagged `missing: true` and without `createdAt`; `"prune"`
+ * de-registers the row through `removeEntry` and drops it. Any non-ENOENT
+ * stat failure fails the list in every mode — that is a real anomaly. The
+ * return shape stays the bare listing, so a prune is visible to callers only
+ * through `removeEntry`'s effect on the inventory or its rejection.
  */
 export async function listCowWorktrees(deps: ListWorktreesDeps): Promise<CowWorktreeEntry[]> {
   const entries = await deps.listWorktrees();
   const cow = entries.filter((entry) => entry.strategy === "cow");
-  return Promise.all(cow.map((entry) => cowEntryOf(entry, deps.statEntry)));
+  // Rows are resolved one at a time: prune mode mutates the inventory through
+  // `removeEntry`, and concurrent removes racing the same inventory file buy
+  // nothing for a listing of a handful of rows.
+  const listed: CowWorktreeEntry[] = [];
+  for (const entry of cow) {
+    const resolved = await cowEntryOf(entry, deps);
+    if (resolved !== undefined) listed.push(resolved);
+  }
+  return listed;
 }
 
-/** Derives one listing entry: the basename, the verbatim directory, and the stat. */
+/**
+ * Derives one listing entry — the basename, the verbatim directory, and the
+ * stat — or `undefined` when the row was pruned. The stat failure itself is
+ * classified, not absorbed: ENOENT goes to the `missing` policy, and every
+ * other failure propagates untouched, exactly as before the knob existed.
+ */
 async function cowEntryOf(
   entry: WorktreeInventoryEntry,
-  statEntry: ListWorktreesDeps["statEntry"],
-): Promise<CowWorktreeEntry> {
-  // Fail loud, by design: the inventory is truth, and a row it lists but whose
-  // directory cannot be stat'd is a real anomaly. Skipping it would report an
-  // incomplete list as a complete one.
-  const times = await statEntry(entry.directory);
+  deps: ListWorktreesDeps,
+): Promise<CowWorktreeEntry | undefined> {
+  let times: StatTimes;
+  try {
+    times = await deps.statEntry(entry.directory);
+  } catch (cause) {
+    if (!isEnoent(cause)) throw cause;
+    return missingEntryOf(entry, deps);
+  }
   return {
     name: basename(entry.directory),
     directory: entry.directory,
@@ -588,6 +640,96 @@ async function cowEntryOf(
   };
 }
 
+/**
+ * The `missing` policy applied to a dangling row. `"report"` keeps the row,
+ * flagged; `"prune"` de-registers it and answers `undefined` so the row leaves
+ * the listing; the default `"fail"` throws the shaped dangling-row refusal.
+ */
+async function missingEntryOf(
+  entry: WorktreeInventoryEntry,
+  deps: ListWorktreesDeps,
+): Promise<CowWorktreeEntry | undefined> {
+  switch (deps.missing ?? "fail") {
+    case "report":
+      return {
+        name: basename(entry.directory),
+        directory: entry.directory,
+        strategy: "cow",
+        missing: true,
+      };
+    case "prune": {
+      if (deps.removeEntry === undefined) throw pruneWithoutSeamError();
+      try {
+        await deps.removeEntry(entry.directory);
+      } catch (cause) {
+        throw pruneBlockedError(entry.directory, cause);
+      }
+      return undefined;
+    }
+    default:
+      throw danglingRowError(entry.directory);
+  }
+}
+
+/**
+ * The shaped refusal for a dangling row under the default `"fail"` policy: the
+ * raw ENOENT rides as the cause, and the message names the two opt-outs.
+ */
+function danglingRowError(directory: string): Error {
+  return new Error(
+    `the worktree inventory lists ${directory}, but stat answers ENOENT: the ` +
+      "directory was deleted while the inventory still records it — a dangling " +
+      "row, and the default fails loudly rather than report an incomplete list " +
+      'as complete. Pass missing: "report" to list the row flagged missing, or ' +
+      'missing: "prune" to de-register it.',
+  );
+}
+
+/**
+ * The refusal for `missing: "prune"` without a wired `removeEntry`: the policy
+ * asked for a de-registration the call has no seam to perform.
+ */
+function pruneWithoutSeamError(): Error {
+  return new Error(
+    'missing: "prune" was requested but no removeEntry seam is wired, so a ' +
+      "dangling inventory row cannot be de-registered.",
+  );
+}
+
+/**
+ * The refusal when the prune itself fails: never swallowed, because the row
+ * the caller wanted gone is still in the inventory. The message names the row,
+ * the raw failure, and the upstream blocker (candidate 8) that makes a gone
+ * directory refuse deletion even at force.
+ */
+function pruneBlockedError(directory: string, cause: unknown): Error {
+  const reason = cause instanceof Error ? cause.message : String(cause);
+  return new Error(
+    `cow could not prune the dangling inventory row ${directory}: the removal ` +
+      `failed (${reason}). Upstream candidate 8 ("Worktree.remove resolves the ` +
+      "real path before reading the record\", docs/research/upstream-issues.md) " +
+      "makes DELETE /api/worktree answer 400 for a gone directory even at " +
+      "force:true, so the row cannot be de-registered until that lands. Re-run " +
+      'with missing: "report" to see the row flagged instead.',
+    { cause },
+  );
+}
+
+/**
+ * Whether an error is a plain ENOENT — "the path is not there", which for an
+ * inventory row means a dangling reference rather than an anomaly. Node's
+ * filesystem errors carry the code; anything else is not an absence answer.
+ * (Mirrors the classifier in `./removal`, which is module-private there.)
+ */
+function isEnoent(cause: unknown): boolean {
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT"
+  );
+}
+
 /**
  * Birthtime first, mtime when the filesystem reports none. btrfs and other
  * filesystems leave birthtime at zero/epoch, where mtime is the