opencode2-cow-worktree 0.1.0 → 0.2.0

package/README.md

@@ -7,8 +7,9 @@ milliseconds at almost no disk cost. Where a `git worktree` carries tracked
 files only, a **Deep clone** here carries everything, so the agent can run the
 test suite immediately.
 
-In daily use, and published to npm. Install from a local checkout (form A
-below) or from the npm registry.
+Current release: [v0.1.0](https://github.com/rbelem/opencode2-cow-worktree/releases/tag/v0.1.0),
+also on [npm](https://www.npmjs.com/package/opencode2-cow-worktree). Install
+from a local checkout (form A below) or from the npm registry.
 
 ## Requirements
 
@@ -28,59 +29,45 @@ capability gate on that default: on a filesystem that cannot reflink (ext4,
 tmpfs), worktree creation fails loudly until you remove the plugin. Install
 it only on machines whose projects meet the Requirements above. opencode2
 Desktop cannot select plugin strategies today, so it ignores the plugin
-entirely (`docs/research/desktop-strategy-hardcode.md`).
+entirely
+([`docs/research/desktop-strategy-hardcode.md`](https://github.com/rbelem/opencode2-cow-worktree/blob/main/docs/research/desktop-strategy-hardcode.md)).
 
-Two forms. Pick one. Having both makes opencode2 load the tree twice, and the
-duplicate load fails.
+### The short version
 
-### Form A: directory discovery
+opencode2 installs the plugin itself from npm. Add the package to the
+`plugins` array of your `opencode.json`:
 
-1. Clone this repository somewhere permanent, e.g. `/path/to/opencode2-cow-worktree`.
-2. Create the plugin directory and its `node_modules`:
-
-   ```sh
-   mkdir -p ~/.config/opencode/plugins/opencode2-cow-worktree/node_modules
-   ```
-
-3. Create two one-line seam files in the plugin directory. The first loads
-   the server plugin; the second loads its TUI half, which shows a small
-   `cow` marker in the sidebar footer while a session runs in a cow
-   worktree:
-
-   ```ts
-   // ~/.config/opencode/plugins/opencode2-cow-worktree/index.ts
-   export { default } from "opencode2-cow-worktree";
-   ```
-
-   ```tsx
-   // ~/.config/opencode/plugins/opencode2-cow-worktree/tui.tsx
-   export { default } from "opencode2-cow-worktree/tui";
-   ```
-
-   The server works without the second file; skip it if you do not want the
-   marker.
+```json
+{
+  "plugins": [{ "package": "opencode2-cow-worktree@latest" }]
+}
+```
 
-4. Symlink the checkout into `node_modules` so the bare specifiers resolve:
+Or let the CLI write that entry:
 
-   ```sh
-   ln -sfn /path/to/opencode2-cow-worktree \
-     ~/.config/opencode/plugins/opencode2-cow-worktree/node_modules/opencode2-cow-worktree
-   ```
+```sh
+opencode2 plugin add opencode2-cow-worktree
+```
 
-Because opencode2's runtime is Bun and the symlink points at the working tree,
-tracked edits are live with no build step.
+On the next startup opencode2 downloads the package into its own cache
+(`~/.cache/opencode/node_modules/`) and loads it. That is the whole install:
+the `cow` marker in the TUI sidebar ships in the same package and loads with
+it — no seam files, no checkout, no symlink. The first startup waits for the
+download, so give it a few extra seconds.
 
-This form runs with default options. To set options, use form B.
+Declare the plugin exactly once. A duplicate declaration (registry entry plus
+local path, or a discovered plugin directory plus the array) makes one of the
+two loads fail with `Plugin failed to load`.
 
-### Form B: the `plugins` array (required for options)
+### Options
 
-Point a `plugins` entry at the checkout itself — no symlink, no seam files:
+Options ride in the same entry:
 
 ```json
 {
   "plugins": [
     {
-      "package": "/path/to/opencode2-cow-worktree",
+      "package": "opencode2-cow-worktree@latest",
       "options": {
         "hooks": { "postCreate": ["corepack use pnpm@latest"] }
       }
@@ -92,16 +79,40 @@ Point a `plugins` entry at the checkout itself — no symlink, no seam files:
 `hooks`, `fallback`, and `targetRoot` are all optional; anything omitted takes
 its default. Each is described below.
 
+### Development install
+
+To work on the plugin itself, point the entry at a checkout instead of the
+registry. Because opencode2's runtime is Bun and the path points at the
+working tree, tracked edits are live with no build step:
+
+```json
+{
+  "plugins": [{ "package": "/path/to/opencode2-cow-worktree" }]
+}
+```
+
 ### Verify
 
+Confirm the plugin loaded:
+
+```sh
+opencode2 plugin list
+```
+
+`opencode2-cow-worktree` should appear with state `active`.
+
+For a deeper check — that a worktree create with no `strategy` field
+materializes a Deep clone, proving `cow` became the default — the repository
+ships a script:
+
 ```sh
 bun scripts/dogfood-install-check.ts
 ```
 
-This boots a throwaway server against the installed plugin and asserts that it
-activates (`GET /api/plugin` reports `state.status: "active"`) and that a
-worktree create with no `strategy` field produces a Deep clone, which proves
-`cow` became the default strategy.
+Run it from a repository checkout; the script ships with the repo, not the
+npm package. It boots a throwaway server against the installed plugin and
+asserts that the plugin activates and that the default create is a Deep
+clone.
 
 Two gotchas when checking by hand: `GET /api/plugin` does not await
 activation, so a list taken right after boot can look empty — resolve
@@ -195,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
@@ -226,6 +239,9 @@ regardless of `fallback`. Only `spawn_workspace` consults the policy.
 - **`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.
+- **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`.
 - **Plugin looks absent right after boot** — resolve
   `POST /api/plugin/await-activation` before reading `GET /api/plugin`.
 - **`Plugin failed to load`** — the plugin is declared twice (discovered
@@ -238,13 +254,15 @@ regardless of `fallback`. Only `spawn_workspace` consults the policy.
 
 The unit suite (`bun test`), typecheck (`bun run typecheck`), coverage gate
 (`bun run test:coverage`), and the e2e harness (`bun scripts/e2e/harness.ts`)
-are described in [`docs/development.md`](docs/development.md), along with the
-recorded live runs and the parallel-lane tooling this repository is developed
-with.
+are described in
+[`docs/development.md`](https://github.com/rbelem/opencode2-cow-worktree/blob/main/docs/development.md),
+along with the recorded live runs and the parallel-lane tooling this
+repository is developed with.
 
 Terms the output uses: a **Workspace** is a logical handle, a **Location** is
 where a session runs, and a **Worktree** is a directory materialized by a
-**Strategy** — more in [CONTEXT.md](CONTEXT.md).
+**Strategy** — more in
+[CONTEXT.md](https://github.com/rbelem/opencode2-cow-worktree/blob/main/CONTEXT.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode2-cow-worktree",
-  "version": "0.1.0",
+  "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.
  *