opencode2-cow-worktree 0.1.1 → 0.2.0

package/README.md

@@ -206,7 +206,9 @@ If the requested name already belongs to a cow worktree, the call attaches: a
 new session binds to the existing directory and `attached: true` comes back —
 nothing is cloned. Attach only happens for worktrees this strategy
 materialized; anything else already at that path (a `git` worktree, an unknown
-directory) is refused before anything changes.
+directory) is refused before anything changes. If the worktree's recorded
+session still shows activity, the attach is refused and the error names the
+occupying session and the ways to recover.
 
 A create whose target path already exists is refused before the first write:
 `cow` never merges into, or deletes, a directory it did not create. Resolve

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode2-cow-worktree",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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/occupancy.ts

@@ -0,0 +1,251 @@
+/**
+ * The occupancy guard for `spawn_workspace` (issue #15): a cow worktree carries
+ * a marker naming the session that holds it, and an attach refuses while that
+ * session is still alive.
+ *
+ * The decision half is pure and table-driven, in the style of `dirty.ts`, so
+ * the refusal table is testable without a filesystem or opencode2. The probe
+ * half classifies one session lookup; the file half owns the marker file and
+ * the git exclude entry that keeps it out of `git status`.
+ *
+ * opencode2 sessions persist after completion and carry no status field — the
+ * record's `time.updated` (epoch milliseconds) is the only liveness signal a
+ * probe gets (verified against 0.0.0-next-20260912.3). Dormancy is therefore a
+ * time judgement, not a state read, and the guard fails closed wherever that
+ * judgement cannot be made: a probe that errors, and a record whose
+ * `time.updated` is missing or unusable, both refuse.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/** The worktree-root file naming the session that holds the worktree. */
+export const MARKER_NAME = ".cow-session.json";
+
+/**
+ * How long a session may stay silent before it no longer counts as holding a
+ * worktree. `time.updated` advances at message writes only (probe 2026-09-14:
+ * exactly 2 distinct values across a completed sim turn), so a turn silent
+ * longer than this window false-clears; false clearance is the worse
+ * direction, so the window is set to the generous end.
+ */
+export const OCCUPIED_AFTER_MS = 60 * 60 * 1000;
+
+/**
+ * The marker payload. `startedAt` is informational, written for a human
+ * reading the file: decisions never compare it against the server's
+ * `time.updated` — the two come from different clocks.
+ */
+export interface OccupancyMarker {
+  readonly sessionID: string;
+  readonly startedAt?: string;
+}
+
+/** A marker file read's three answers: a marker, no marker, or an unusable one. */
+export type ParsedMarker = OccupancyMarker | undefined | "malformed";
+
+/** What one probe of the marker's session reported. */
+export type ProbeResult =
+  | { readonly kind: "absent" }
+  | { readonly kind: "live"; readonly updated: number }
+  | { readonly kind: "error" };
+
+/** Whether the attach may proceed, and why not when it may not. */
+export type OccupancyDecision =
+  | { readonly action: "refuse"; readonly reason: string }
+  | { readonly action: "proceed"; readonly rewrite: boolean };
+
+/**
+ * The three ways out of an occupancy refusal, spelled out in full because the
+ * refusal is the only place the guard explains itself. Exactly three, in the
+ * order a blocked caller reaches for them.
+ */
+export const RECOVERIES =
+  "Pick another worktree name; delete the occupying session out of band " +
+  "(DELETE /api/session/<sessionID> against this server); or remove the " +
+  `occupancy marker (${MARKER_NAME}) from the worktree root if you know it is stale.`;
+
+/**
+ * Parses a marker file's raw content. An absent file is `undefined`; anything
+ * that does not parse as JSON, or that names no session, is `"malformed"` —
+ * the guard cannot tell who holds the worktree, so it will not guess.
+ */
+export function parseMarker(raw: string | undefined): ParsedMarker {
+  if (raw === undefined) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return "malformed";
+  }
+  if (typeof parsed !== "object" || parsed === null) return "malformed";
+  const sessionID = (parsed as { sessionID?: unknown }).sessionID;
+  if (typeof sessionID !== "string" || sessionID.length === 0) return "malformed";
+  const startedAt = (parsed as { startedAt?: unknown }).startedAt;
+  return typeof startedAt === "string" ? { sessionID, startedAt } : { sessionID };
+}
+
+/**
+ * Classifies one `sessionGet` probe of the session a marker names.
+ *
+ * The verified server contract: an absent id makes the lookup throw with
+ * `_tag: "SessionNotFoundError"` (HTTP 404), which is a *positive* absence —
+ * the one answer that proves the worktree free. A resolved `null` or
+ * `undefined` counts as absent too. Anything else is an unanswerable probe: a
+ * throw with any other tag, a non-object body, or a body without a string id
+ * all refuse rather than guess, and so does a body whose `time.updated` is not
+ * a usable epoch-milliseconds number — a malformed 200 must never become
+ * dormancy, because naive `now - updated` arithmetic over a missing or
+ * non-numeric value would read as endlessly idle.
+ */
+export async function probeOccupyingSession(
+  sessionGet: (id: string) => Promise<unknown>,
+  sessionID: string,
+): Promise<ProbeResult> {
+  let answer: unknown;
+  try {
+    answer = await sessionGet(sessionID);
+  } catch (cause) {
+    return isSessionNotFound(cause) ? { kind: "absent" } : { kind: "error" };
+  }
+  if (answer === null || answer === undefined) return { kind: "absent" };
+  if (typeof answer !== "object") return { kind: "error" };
+  const record = answer as { id?: unknown; time?: { updated?: unknown } };
+  if (typeof record.id !== "string") return { kind: "error" };
+  const updated = record.time?.updated;
+  return typeof updated === "number" && Number.isFinite(updated) && updated >= 0
+    ? { kind: "live", updated }
+    : { kind: "error" };
+}
+
+function isSessionNotFound(cause: unknown): boolean {
+  // The only positive-absence signals from a throw, both verified: the HTTP
+  // payload tags the 404 `SessionNotFoundError`, while the error the
+  // plugin-side lookup throws is `Session.NotFoundError` with an empty
+  // message. No message matching: a substring is not a tag, and an unrelated
+  // gateway error that happens to phrase itself like a 404 must refuse, not
+  // clear the worktree.
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    ((cause as { _tag?: unknown })._tag === "SessionNotFoundError" ||
+      (cause as { _tag?: unknown })._tag === "Session.NotFoundError")
+  );
+}
+
+/**
+ * The occupancy decision table.
+ *
+ * Refusals, in the order checked: a malformed marker (the holder is unknown),
+ * a probe error (a failed lookup is not a positive absence), a live record
+ * whose `time.updated` is unusable (fail closed — the naive arithmetic would
+ * call it dormant), and a live record still inside the occupancy window.
+ * Otherwise the attach proceeds; `rewrite` says whether an old marker is being
+ * replaced — a stale one the probe proved dead, or a dormant one past the
+ * window — as opposed to a first marker for a worktree that never had one.
+ */
+export function occupancyDecision(input: {
+  readonly marker: ParsedMarker;
+  readonly probe: ProbeResult;
+  readonly now: number;
+}): OccupancyDecision {
+  if (input.marker === "malformed") {
+    return {
+      action: "refuse",
+      reason: `the occupancy marker is unparsable or names no session, so the holder is unknown. ${RECOVERIES}`,
+    };
+  }
+  if (input.probe.kind === "error") {
+    return {
+      action: "refuse",
+      reason: `the session holding this worktree could not be checked, and a failed lookup is not proof it is gone. ${RECOVERIES}`,
+    };
+  }
+  if (input.probe.kind === "live") {
+    const updated = input.probe.updated;
+    // Deliberate defense-in-depth, not dead code: the classifier already maps
+    // an unusable `updated` to a probe error, so this row only fires if that
+    // classification ever drifts.
+    if (!Number.isFinite(updated) || updated < 0) {
+      return {
+        action: "refuse",
+        reason: `the session holding this worktree reports no usable last-activity time. ${RECOVERIES}`,
+      };
+    }
+    const idle = input.now - updated;
+    if (!Number.isFinite(idle) || idle <= OCCUPIED_AFTER_MS) {
+      const holder = input.marker === undefined ? "A session" : `Session ${input.marker.sessionID}`;
+      return { action: "refuse", reason: occupiedMessage(holder, idle) };
+    }
+  }
+  return { action: "proceed", rewrite: input.marker !== undefined };
+}
+
+function occupiedMessage(holder: string, idleMs: number): string {
+  return `${holder} appears to still be using it — its last activity was ${humanAge(idleMs)} ago. ${RECOVERIES}`;
+}
+
+/** A last-active age in human form; an unanswerable age never reads as fresh. */
+function humanAge(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "an unknown amount of time";
+  if (ms < 60_000) return "less than a minute";
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes} minute(s)`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour(s)`;
+  return `${Math.floor(hours / 24)} day(s)`;
+}
+
+// The file half: the marker file and its git exclude entry. Read failures
+// other than "not there" propagate — an unreadable marker is not evidence of a
+// free worktree — and write failures propagate to the caller's warning path.
+
+const EXCLUDE_APPEND = `\n# opencode2-cow-worktree occupancy marker\n${MARKER_NAME}\n`;
+
+/**
+ * The raw marker file's content, or `undefined` when there is none. Any other
+ * read failure (permissions, an obstacle in the path) propagates.
+ */
+export async function readMarkerFile(directory: string): Promise<string | undefined> {
+  try {
+    return await readFile(join(directory, MARKER_NAME), "utf8");
+  } catch (cause) {
+    if (isNotFound(cause)) return undefined;
+    throw cause;
+  }
+}
+
+/**
+ * Writes the marker naming `sessionID`, first ensuring the worktree's
+ * `.git/info/exclude` ignores the marker file — the exclude line goes in
+ * before the marker exists, so `git status` never sees it, not even in the
+ * moment between the two writes. Both steps are idempotent, and both
+ * propagate their failures: the caller demotes them to a warning, never a
+ * failed spawn.
+ */
+export async function writeMarkerFile(directory: string, sessionID: string): Promise<void> {
+  await ensureGitExclude(directory);
+  const marker: OccupancyMarker = { sessionID, startedAt: new Date().toISOString() };
+  await writeFile(join(directory, MARKER_NAME), `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+}
+
+async function ensureGitExclude(directory: string): Promise<void> {
+  const excludePath = join(directory, ".git", "info", "exclude");
+  const current = await readFile(excludePath, "utf8").catch((cause) => {
+    if (isNotFound(cause)) return undefined;
+    throw cause;
+  });
+  if (current !== undefined && hasExcludeEntry(current)) return;
+  await mkdir(dirname(excludePath), { recursive: true });
+  await writeFile(excludePath, (current ?? "") + EXCLUDE_APPEND, "utf8");
+}
+
+/** Whether the exclude already carries the marker entry as its own line. */
+function hasExcludeEntry(content: string): boolean {
+  return content.split("\n").some((line) => line.trim() === MARKER_NAME);
+}
+
+function isNotFound(cause: unknown): boolean {
+  return (
+    typeof cause === "object" && cause !== null && (cause as { code?: unknown }).code === "ENOENT"
+  );
+}

package/src/plugin.ts

@@ -3,6 +3,7 @@ import { stat } from "node:fs/promises";
 import { probeCowCapability } from "./capability";
 import { fallbackPolicy, postCreateHooks, targetRoot } from "./config";
 import { deviceOf, isDirectory } from "./device";
+import { readMarkerFile, writeMarkerFile } from "./occupancy";
 import { listCowWorktrees, spawnWorkspace } from "./tool";
 import type {
   FallbackPolicy,
@@ -60,6 +61,11 @@ const spawnWorkspaceOutput = {
       description:
         "True when the session was attached to an existing worktree instead of a new clone.",
     },
+    markerWarning: {
+      type: "string",
+      description:
+        "Set when the occupancy marker could not be written after a successful session start.",
+    },
   },
   required: ["sessionID", "directory", "mechanism"],
   additionalProperties: false,
@@ -155,6 +161,14 @@ function liveDeps(
     },
     removeWorktree: (directory) =>
       ctx.worktree.remove({ 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
+    // guard reads.
+    sessionGet: (id) => ctx.session.get({ sessionID: id }),
+    readMarker: readMarkerFile,
+    writeMarker: writeMarkerFile,
+    now: Date.now,
     fallback,
     targetRoot: worktreeRoot,
   };
@@ -192,7 +206,9 @@ export default {
         description:
           "Create a worktree and start a session in it, reporting the mechanism that produced the directory. " +
           "When a worktree with the requested name already exists and was produced by the cow strategy, the " +
-          "session is attached to it instead of creating a new directory; anything else at that name is refused.",
+          "session is attached to it instead of creating a new directory; anything else at that name is refused. " +
+          "If the worktree's recorded session still shows activity, the attach is refused and the error names " +
+          "the occupying session and the ways to recover.",
         input: spawnWorkspaceInput,
         output: spawnWorkspaceOutput,
         // A tool defaults into CodeMode, which advertises it to the model only
@@ -203,10 +219,13 @@ export default {
           const result = await spawnWorkspace(input, liveDeps(ctx, fallback, worktreeRoot));
           // The text is what tells attach from create: on attach `mechanism`
           // reports the found directory's mechanism, and the caller must never
-          // read that as a fresh clone having happened.
-          const content = result.attached
-            ? `Attached to existing cow worktree at ${result.directory} (session ${result.sessionID}); no new worktree was created.`
-            : `Created ${result.mechanism} worktree at ${result.directory} (session ${result.sessionID}).`;
+          // read that as a fresh clone having happened. A marker-write failure
+          // never fails the call; it rides along as a warning line.
+          const content =
+            (result.attached
+              ? `Attached to existing cow worktree at ${result.directory} (session ${result.sessionID}); no new worktree was created.`
+              : `Created ${result.mechanism} worktree at ${result.directory} (session ${result.sessionID}).`) +
+            (result.markerWarning === undefined ? "" : `\nwarning: ${result.markerWarning}`);
           return {
             output: result,
             content,

package/src/tool.ts

@@ -3,7 +3,8 @@ import { basename, join, resolve } from "node:path";
 import { assertSameDevice } from "./device";
 import type { CowCapability } from "./capability";
 import type { Mechanism } from "./mechanism";
-import type { WorktreeInventoryEntry } from "../types/opencode2-worktree";
+import { MARKER_NAME, RECOVERIES, occupancyDecision, parseMarker, probeOccupyingSession } from "./occupancy";
+import type { SessionGetResult, WorktreeInventoryEntry } from "../types/opencode2-worktree";
 
 /** What a successful `spawnWorkspace` produced. */
 export interface SpawnWorkspaceResult {
@@ -17,6 +18,13 @@ export interface SpawnWorkspaceResult {
    * directory that was found, not of a clone this call performed.
    */
   readonly attached?: boolean;
+  /**
+   * Set when the occupancy marker could not be written after a successful
+   * session start. The session is live either way — the marker only arms the
+   * occupancy guard for the next spawn — so the failure rides along as a
+   * warning instead of failing the call.
+   */
+  readonly markerWarning?: string;
 }
 
 /** Whether a caller who asked for a CoW clone may be given a Shallow worktree. */
@@ -69,6 +77,23 @@ export interface SpawnWorkspaceDeps {
    * without a filesystem.
    */
   readonly isDirectory: (path: string) => Promise<boolean>;
+  /**
+   * Reads one session by id — the occupancy guard probes the session a marker
+   * names. Declared total because the classifier treats every throw and every
+   * odd shape as an answer (see `probeOccupyingSession`); the live binding's
+   * 404 arrives as a thrown `SessionNotFoundError`.
+   */
+  readonly sessionGet: (id: string) => Promise<SessionGetResult>;
+  /** The raw occupancy marker file's content, or `undefined` when there is none. */
+  readonly readMarker: (directory: string) => Promise<string | undefined>;
+  /**
+   * Writes the occupancy marker for a fresh session, git-excluding it first.
+   * A failure here is demoted to the result's `markerWarning`, never a failed
+   * spawn: an unmarked worktree is the pre-guard status quo, not an error.
+   */
+  readonly writeMarker: (directory: string, sessionID: string) => Promise<void>;
+  /** Wall-clock milliseconds. Injected so dormancy is testable. */
+  readonly now: () => number;
   /** Defaults to `"none"`: a request for `cow` is a statement about what you get. */
   readonly fallback?: FallbackPolicy;
   /** Worktree parent. Defaults to a same-filesystem sibling of the source. */
@@ -155,7 +180,17 @@ export async function spawnWorkspace(
 
   try {
     const sessionID = await deps.createSession(worktree.directory, input.name);
-    return { sessionID, directory: worktree.directory, mechanism };
+    // Cow only: a git worktree's `.git` is a file, so the exclude the marker
+    // needs has no place to live — no marker, no exclude; the guard is a
+    // cow-worktree contract.
+    const markerWarning =
+      mechanism === "cow" ? await markerWarningOf(worktree.directory, sessionID, deps) : undefined;
+    return {
+      sessionID,
+      directory: worktree.directory,
+      mechanism,
+      ...(markerWarning === undefined ? {} : { markerWarning }),
+    };
   } catch (cause) {
     // The cleanup is best-effort: it must never replace the failure that
     // triggered it. `removeWorktree` goes through opencode2's DELETE route,
@@ -277,7 +312,9 @@ async function tryAttach(
  * The attach decision for a path that already exists. The inventory is the
  * source of truth for "ours" (ADR 0003): an entry recorded with `cow` plus the
  * Deep-clone signature (`.git` is a directory) means the `cow` strategy
- * materialized this directory, so a new session may bind to it. Every other
+ * materialized this directory, so a new session may bind to it — and the
+ * occupancy marker then decides whether it may, while the session the marker
+ * names is still alive (`assertOccupancyFree`). Every other
  * answer is refused loudly — before any session is created and with no
  * filesystem change — because a Foreign worktree, another strategy's Worktree,
  * or a `cow` row that lost its Deep-clone shape is not this tool's to attach
@@ -296,9 +333,19 @@ async function attachToExisting(
   if (!(await deps.isDirectory(join(target, ".git")))) {
     throw notDeepCloneError(target);
   }
+  await assertOccupancyFree(target, deps);
   try {
     const sessionID = await deps.createSession(target, name);
-    return { sessionID, directory: target, mechanism: "cow", attached: true };
+    // Written even when no marker existed (a legacy worktree): from the next
+    // spawn onward, this guard is what protects the directory.
+    const markerWarning = await markerWarningOf(target, sessionID, deps);
+    return {
+      sessionID,
+      directory: target,
+      mechanism: "cow",
+      attached: true,
+      ...(markerWarning === undefined ? {} : { markerWarning }),
+    };
   } catch (cause) {
     // No removeWorktree here, unlike the create flow: the directory existed
     // before this call, so a failed session start must leave it untouched.
@@ -306,6 +353,78 @@ async function attachToExisting(
   }
 }
 
+/**
+ * The occupancy half of attach (issue #15), run after the Deep-clone signature
+ * check: the marker decides whether the worktree is free to attach. No marker
+ * is a legacy worktree — it attaches, and the marker is written on the way
+ * out. A marker naming a live session refuses, naming the holder and the way
+ * out; a marker whose session is gone (a 404) or past the occupancy window is
+ * stale, and the attach proceeds to rewrite it.
+ */
+async function assertOccupancyFree(target: string, deps: SpawnWorkspaceDeps): Promise<void> {
+  let raw: string | undefined;
+  try {
+    raw = await deps.readMarker(target);
+  } catch (cause) {
+    // readMarker's live binding answers `undefined` for a marker that is not
+    // there, so a throw here is EACCES-class: an unreadable marker is not
+    // evidence of a free worktree.
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    throw markerReadError(target, reason);
+  }
+  const marker = parseMarker(raw);
+  if (marker === "malformed") throw malformedMarkerError(target);
+  const probe =
+    marker === undefined
+      ? { kind: "absent" as const }
+      : await probeOccupyingSession(deps.sessionGet, marker.sessionID);
+  const decision = occupancyDecision({ marker, probe, now: deps.now() });
+  if (decision.action === "refuse") {
+    throw new Error(`refusing to attach to ${target}: ${decision.reason}`);
+  }
+}
+
+/**
+ * The refusal for a marker that cannot be read: the guard cannot tell who
+ * holds the worktree, so it will not hand it out.
+ */
+function markerReadError(target: string, reason: string): Error {
+  return new Error(
+    `refusing to attach to ${target}: the occupancy marker at ` +
+      `${join(target, MARKER_NAME)} could not be read (${reason}). ${RECOVERIES}`,
+  );
+}
+
+/**
+ * The refusal for a marker that cannot be parsed: the guard cannot tell who
+ * holds the worktree, so it will not hand it out.
+ */
+function malformedMarkerError(target: string): Error {
+  return new Error(
+    `refusing to attach to ${target}: ${join(target, MARKER_NAME)} is malformed — ` +
+      `it does not parse as JSON or names no session, so the holder is unknown. ${RECOVERIES}`,
+  );
+}
+
+/**
+ * Writes the occupancy marker through the injected seam, demoting a failure to
+ * the warning string the result carries. The session is live either way; the
+ * marker only arms the guard for the next spawn.
+ */
+async function markerWarningOf(
+  directory: string,
+  sessionID: string,
+  deps: Pick<SpawnWorkspaceDeps, "writeMarker">,
+): Promise<string | undefined> {
+  try {
+    await deps.writeMarker(directory, sessionID);
+    return undefined;
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return `the occupancy marker could not be written to ${directory}: ${reason}`;
+  }
+}
+
 /**
  * The inventory entry recorded for a directory, when the inventory knows it.
  *