@rallycry/conveyor-skills 1.0.12 → 1.0.13

package/README.md

@@ -80,6 +80,33 @@ and safe:
 - `conveyor-skills link --check` verifies the links without changing anything
   (exit 1 when out of date) — useful in CI.
 
+## Taking turns on one checkout
+
+Local agent sessions that share one git checkout take turns on it.
+`/conveyor-build`, `/conveyor-local-loop` and local `/conveyor-review` fixes
+hold a **checkout claim** while they use the working tree; a second session
+that finds it held says so and waits instead of switching branches underneath
+the first. Cloud pods have their own checkout and skip this.
+
+The claim is one file in the git dir (`.git/conveyor-checkout-claim.json`, or
+the per-worktree git dir), so it is never committed and never shows in
+`git status`. The skills drive it through the same bin:
+
+```bash
+conveyor-skills checkout acquire --card <slug> [--branch <b>]  # take / refresh
+conveyor-skills checkout verify  --card <slug>                 # still mine? (heartbeat)
+conveyor-skills checkout release --card <slug>                 # give it back
+conveyor-skills checkout status                                # who holds it
+conveyor-skills checkout wait --timeout 1740                   # block until free
+```
+
+Each command prints one JSON line. A claim goes stale when its holder's
+process is dead, when the same process started a new session, or when its
+heartbeat is older than two hours (`CONVEYOR_CHECKOUT_CLAIM_TTL_SECONDS`).
+`conveyor-skills checkout release --force` is the human override for a wedged
+claim. The full protocol lives in
+[`skills/conveyor-build/references/checkout-claim.md`](skills/conveyor-build/references/checkout-claim.md).
+
 ## Versioning
 
 Versions are cut automatically from git tags on the Conveyor repo's `main`

package/bin/checkout-claim.mjs

@@ -0,0 +1,524 @@
+// conveyor-skills checkout — make local agent sessions that share one git
+// checkout take turns on it. A session holds the claim while it uses the
+// working tree; any other session that finds the claim held waits instead of
+// switching branches underneath the holder.
+//
+// The claim is one JSON file in the per-worktree git dir
+// (`git rev-parse --absolute-git-dir`), so it is never committed, never shows
+// in `git status`, survives branch switches, and linked worktrees get
+// independent claims. Pods have their own checkout and never call this.
+//
+// Every command prints exactly ONE JSON line on stdout; hints go to stderr.
+// Node built-ins only — this ships in the published package next to cli.mjs.
+
+import { spawnSync } from "node:child_process";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname as osHostname } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+export const CLAIM_FILE = "conveyor-checkout-claim.json";
+export const MUTEX_DIR = "conveyor-checkout-claim.mutex";
+export const SCHEMA = 1;
+export const DEFAULT_TTL_SECONDS = 7200;
+export const DEFAULT_WAIT_TIMEOUT_SECONDS = 1740;
+export const DEFAULT_WAIT_INTERVAL_SECONDS = 5;
+const MUTEX_RETRY_MS = 2000;
+const MUTEX_STALE_MS = 30_000;
+
+export const EXIT = { ok: 0, error: 1, held: 3, branchMoved: 4, dirty: 5 };
+
+const USAGE = `Usage: conveyor-skills checkout <command> [options]
+
+Commands:
+  acquire --card <slug> [--branch <b>]   take or refresh the checkout claim
+  verify  --card <slug> [--branch <b>]   confirm the claim is still yours (also a heartbeat)
+  release --card <slug> [--force]        drop the claim (--force: drop someone else's)
+  status                                 show the claim; always exits 0
+  wait [--timeout 1740] [--interval 5]   block until the claim is free, stale, or yours
+
+Options:
+  --session <id>   session identity (default: CONVEYOR_SESSION_ID, then
+                   CLAUDE_CODE_SESSION_ID, then card:<slug>)
+  --ttl <secs>     heartbeat age after which a claim is stale
+                   (default: CONVEYOR_CHECKOUT_CLAIM_TTL_SECONDS or ${DEFAULT_TTL_SECONDS})
+
+Exit codes: 0 ok, 1 usage error or not a git repo, 3 held by another session
+(or lost), 4 branch moved under the claim, 5 dirty tree.
+`;
+
+/** Marker for a claim file that exists but does not parse as a claim. */
+export const CORRUPT = Object.freeze({ corrupt: true });
+
+/**
+ * Who is asking. The session id is what owns a claim; the pid (the Claude Code
+ * process, when the harness exports it) is what lets a same-host caller prove
+ * a holder is dead instead of waiting out the TTL.
+ */
+export function resolveIdentity({ session, card, env = process.env } = {}) {
+  const resolved =
+    session ||
+    env.CONVEYOR_SESSION_ID ||
+    env.CLAUDE_CODE_SESSION_ID ||
+    (card ? `card:${card}` : null);
+  const pid = Number.parseInt(env.CLAUDE_PID ?? "", 10);
+  return { session: resolved, pid: Number.isInteger(pid) && pid > 0 ? pid : null };
+}
+
+export function defaultPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists but belongs to someone else — alive.
+    return err?.code === "EPERM";
+  }
+}
+
+function isClaimRecord(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof value.session === "string" &&
+    typeof value.host === "string" &&
+    !Number.isNaN(Date.parse(value.heartbeatAt))
+  );
+}
+
+/**
+ * Classify an existing claim relative to the caller.
+ * kind: none | own | live | stale | corrupt. `reason` explains a stale verdict.
+ */
+export function classifyClaim(claim, { identity, now, hostname, pidAlive, ttlSeconds }) {
+  if (claim === null || claim === undefined) return { kind: "none" };
+  if (!isClaimRecord(claim)) return { kind: "corrupt" };
+  const ageSeconds = Math.max(0, Math.round((now - Date.parse(claim.heartbeatAt)) / 1000));
+  if (identity.session && claim.session === identity.session) return { kind: "own", ageSeconds };
+  if (claim.host === hostname && Number.isInteger(claim.pid)) {
+    if (!pidAlive(claim.pid)) return { kind: "stale", reason: "pid-dead", ageSeconds };
+    // Same live process, new session id: the holder ran /clear and moved on.
+    if (identity.pid === claim.pid)
+      return { kind: "stale", reason: "same-pid-new-session", ageSeconds };
+  }
+  if (ageSeconds > ttlSeconds) return { kind: "stale", reason: "ttl-expired", ageSeconds };
+  return { kind: "live", ageSeconds };
+}
+
+/**
+ * What `acquire` does with a classified claim.
+ * A stale claim is only taken over on a clean tree, or when it names the same
+ * card (the tree is that card's own unfinished work). No claim + dirty tree is
+ * refused: someone who never took a claim is mid-change.
+ */
+export function decideAcquire({ classification, claim, card, dirty }) {
+  switch (classification.kind) {
+    case "own":
+      return { write: true, state: "refreshed" };
+    case "none":
+      return dirty ? { write: false, state: "dirty" } : { write: true, state: "acquired" };
+    case "stale":
+      return !dirty || claim.card === card
+        ? { write: true, state: "took-over" }
+        : { write: false, state: "dirty" };
+    default:
+      // live, corrupt
+      return { write: false, state: "held" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// git + filesystem
+
+function git(cwd, args, env) {
+  const result = spawnSync("git", args, { cwd, env, encoding: "utf8" });
+  return {
+    ok: result.status === 0,
+    out: (result.stdout ?? "").trim(),
+    err: (result.stderr ?? "").trim(),
+  };
+}
+
+function readRepo(cwd, env) {
+  const gitDir = git(cwd, ["rev-parse", "--absolute-git-dir"], env);
+  if (!gitDir.ok) return null;
+  const head = git(cwd, ["symbolic-ref", "--short", "-q", "HEAD"], env);
+  // --no-optional-locks: never take index.lock, so a status read cannot
+  // collide with the holder's own git commands.
+  const status = git(cwd, ["--no-optional-locks", "status", "--porcelain"], env);
+  return {
+    gitDir: gitDir.out,
+    head: head.ok && head.out ? head.out : null,
+    dirty: status.out.length > 0,
+  };
+}
+
+function readClaim(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return isClaimRecord(parsed) ? parsed : CORRUPT;
+  } catch {
+    return CORRUPT;
+  }
+}
+
+function writeClaim(path, record) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+function removeClaim(path) {
+  try {
+    unlinkSync(path);
+  } catch (err) {
+    if (err?.code !== "ENOENT") throw err;
+  }
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Run `fn` inside a mkdir-based critical section; mkdir is atomic everywhere. */
+function withMutex(gitDir, fn) {
+  const mutex = join(gitDir, MUTEX_DIR);
+  const deadline = Date.now() + MUTEX_RETRY_MS;
+  for (;;) {
+    try {
+      mkdirSync(mutex);
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      try {
+        if (Date.now() - statSync(mutex).mtimeMs > MUTEX_STALE_MS) {
+          rmSync(mutex, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        // Vanished between mkdir and stat — retry.
+        continue;
+      }
+      if (Date.now() > deadline) return { busy: true };
+      sleepSync(25 + Math.floor(Math.random() * 25));
+    }
+  }
+  try {
+    return { value: fn() };
+  } finally {
+    rmSync(mutex, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  const valued = new Set(["card", "branch", "session", "ttl", "timeout", "interval"]);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      opts._.push(arg);
+      continue;
+    }
+    const [key, inline] = arg.slice(2).split(/=(.*)/s, 2);
+    if (valued.has(key)) {
+      const value = inline ?? argv[(i += 1)];
+      if (value === undefined || value === "") throw new Error(`--${key} needs a value`);
+      opts[key] = value;
+    } else if (key === "force" || key === "help") {
+      opts[key] = true;
+    } else {
+      throw new Error(`unknown option --${key}`);
+    }
+  }
+  return opts;
+}
+
+function positiveNumber(raw, name) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`--${name} must be a positive number`);
+  return n;
+}
+
+function describeHolder(claim, classification) {
+  if (claim === CORRUPT) return { corrupt: true };
+  return {
+    ...claim,
+    ageSeconds: classification.ageSeconds,
+    stale: classification.kind === "stale",
+  };
+}
+
+function holderHint(holder) {
+  if (holder.corrupt)
+    return "the claim file does not parse — a human decides: `conveyor-skills checkout release --force`";
+  const pid = holder.pid ? ` pid ${holder.pid}` : "";
+  return `checkout held by card ${holder.card ?? "?"} on branch ${holder.branch ?? "(detached)"} (${holder.host}${pid}, heartbeat ${holder.ageSeconds}s ago) — do not touch the tree; run \`conveyor-skills checkout wait\``;
+}
+
+const HINTS = {
+  dirty:
+    "working tree is dirty and no live claim covers it — touch nothing; the user commits or stashes",
+  "branch-moved": "HEAD is not the claimed branch — do not commit or push; report it",
+  lost: "you no longer hold the checkout claim — stop and re-acquire before touching the tree",
+};
+
+const COMMANDS = ["acquire", "verify", "release", "status", "wait"];
+
+const EXIT_BY_STATE = {
+  held: EXIT.held,
+  lost: EXIT.held,
+  "branch-moved": EXIT.branchMoved,
+  dirty: EXIT.dirty,
+};
+
+/** Validate parsed options; returns an error message or null. */
+function usageProblem(command, opts) {
+  if (!COMMANDS.includes(command)) return `unknown checkout command '${command}'`;
+  if (["acquire", "verify"].includes(command) && !opts.card)
+    return `${command} needs --card <slug>`;
+  if (command === "release" && !opts.card && !opts.force)
+    return "release needs --card <slug> (or --force)";
+  return null;
+}
+
+function acquireOp({ ctx, claim, classification, stamp }) {
+  const { opts, repo, identity, hostname, claimPath } = ctx;
+  const decision = decideAcquire({ classification, claim, card: opts.card, dirty: repo.dirty });
+  if (!decision.write) return { state: decision.state };
+  const kept = classification.kind === "own" ? claim : null;
+  const record = {
+    schema: SCHEMA,
+    session: identity.session,
+    pid: identity.pid,
+    host: hostname,
+    card: opts.card,
+    branch: opts.branch ?? kept?.branch ?? repo.head,
+    acquiredAt: kept?.acquiredAt ?? stamp,
+    heartbeatAt: stamp,
+  };
+  writeClaim(claimPath, record);
+  return { state: decision.state, record };
+}
+
+function verifyOp({ ctx, claim, classification, stamp }) {
+  const { opts, repo, identity, claimPath } = ctx;
+  if (classification.kind !== "own") return { state: "lost" };
+  const expected = opts.branch ?? claim.branch;
+  if (expected && repo.head !== expected) return { state: "branch-moved", expected };
+  const record = { ...claim, pid: identity.pid ?? claim.pid, heartbeatAt: stamp };
+  writeClaim(claimPath, record);
+  return { state: "ok", record };
+}
+
+function releaseOp({ ctx, classification }) {
+  if (classification.kind === "none") return { state: "none" };
+  if (classification.kind !== "own" && !ctx.opts.force) return { state: "held" };
+  removeClaim(ctx.claimPath);
+  return { state: "released" };
+}
+
+const MUTATIONS = { acquire: acquireOp, verify: verifyOp, release: releaseOp };
+
+/** Run a mutating command inside the mutex: read, decide, write. */
+function mutate(ctx) {
+  // Test-only: widen the read→write window so the parallel-acquire test fails
+  // loudly if the mutex ever stops serializing callers.
+  const holdMs = Number(ctx.env.CONVEYOR_CHECKOUT_CLAIM_TEST_HOLD_MS) || 0;
+  return withMutex(ctx.repo.gitDir, () => {
+    const claim = readClaim(ctx.claimPath);
+    const classification = ctx.classify(claim);
+    if (holdMs > 0) sleepSync(holdMs);
+    const stamp = new Date(ctx.now()).toISOString();
+    const result = MUTATIONS[ctx.command]({ ctx, claim, classification, stamp });
+    return { ...result, claim, classification };
+  });
+}
+
+/** The JSON line and the stderr hint for a finished mutation. */
+function describeOutcome(base, outcome) {
+  const { state, claim, classification, record, expected } = outcome;
+  const payload = { ...base, state };
+  if (state === "took-over") payload.reason = classification.reason;
+  if (record) payload.claim = record;
+  if (expected) payload.expectedBranch = expected;
+  let hint = HINTS[state] ?? null;
+  if (["held", "lost"].includes(state) && claim !== null) {
+    payload.holder = describeHolder(claim, classification);
+    if (state === "held" || classification.kind === "corrupt") hint = holderHint(payload.holder);
+  }
+  if (state === "took-over")
+    hint = `took over a stale claim (${classification.reason}) from card ${claim.card ?? "?"}`;
+  return { payload, hint };
+}
+
+/** Parse argv into a command; throws on a usage error. */
+function parseCommand(argv, env) {
+  const opts = parseArgs(argv);
+  const ttlSeconds = positiveNumber(
+    opts.ttl ?? env.CONVEYOR_CHECKOUT_CLAIM_TTL_SECONDS ?? DEFAULT_TTL_SECONDS,
+    "ttl",
+  );
+  return { opts, command: opts._[0], ttlSeconds };
+}
+
+/** Everything a command needs to read and judge the claim. */
+function buildContext({ command, opts, ttlSeconds, env, repo, deps }) {
+  const now = deps.now ?? (() => Date.now());
+  const hostname = deps.hostname ?? osHostname();
+  const pidAlive = deps.pidAlive ?? defaultPidAlive;
+  const identity = resolveIdentity({ session: opts.session, card: opts.card, env });
+  const claimPath = join(repo.gitDir, CLAIM_FILE);
+  const classify = (claim) =>
+    classifyClaim(claim, { identity, now: now(), hostname, pidAlive, ttlSeconds });
+  const base = { command, head: repo.head, dirty: repo.dirty, file: claimPath };
+  return { command, opts, env, repo, identity, hostname, claimPath, classify, now, base };
+}
+
+async function runStatus({ ctx, emit }) {
+  const claim = readClaim(ctx.claimPath);
+  const classification = ctx.classify(claim);
+  await emit({
+    ...ctx.base,
+    state: classification.kind,
+    ...(classification.reason ? { reason: classification.reason } : {}),
+    claim: claim === null ? null : describeHolder(claim, classification),
+  });
+  return EXIT.ok;
+}
+
+async function runMutation({ ctx, emit, hint, fail }) {
+  const outcome = mutate(ctx);
+  if (outcome.busy) {
+    const message = `could not take ${MUTEX_DIR} within ${MUTEX_RETRY_MS}ms — another session is mid-claim; retry`;
+    return fail(message, ctx.base);
+  }
+  const { payload, hint: message } = describeOutcome(ctx.base, outcome.value);
+  if (message) hint(message);
+  await emit(payload);
+  return EXIT_BY_STATE[payload.state] ?? EXIT.ok;
+}
+
+/**
+ * Run one checkout command. Resolves to the exit code; writes exactly one JSON
+ * line to `deps.stdout` and waits for it to flush.
+ */
+export async function runCheckoutCli(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  let command = argv.find((a) => !a.startsWith("-")) ?? null;
+  const emit = (payload) =>
+    new Promise((resolve) => {
+      stdout.write(`${JSON.stringify(payload)}\n`, () => resolve());
+    });
+  const hint = (msg) => stderr.write(`conveyor-skills checkout: ${msg}\n`);
+  const fail = async (message, extra = {}) => {
+    hint(message);
+    await emit({ command, ...extra, state: "error", error: message });
+    return EXIT.error;
+  };
+
+  let parsed;
+  try {
+    parsed = parseCommand(argv, env);
+  } catch (err) {
+    return fail(err.message);
+  }
+  if (parsed.opts.help || !parsed.command) {
+    stderr.write(USAGE);
+    await emit({ command, state: "usage" });
+    return parsed.opts.help ? EXIT.ok : EXIT.error;
+  }
+  command = parsed.command;
+  const problem = usageProblem(command, parsed.opts);
+  if (problem) return fail(problem);
+
+  const repo = readRepo(deps.cwd ?? process.cwd(), env);
+  if (!repo) return fail("not inside a git repository");
+  const ctx = buildContext({ ...parsed, env, repo, deps });
+  const io = { ctx, emit, hint, fail };
+  if (command === "status") return runStatus(io);
+  if (command === "wait") return runWait(io);
+  return runMutation(io);
+}
+
+/** Sleep up to `ms`, returning early when `signal.wake()` is called. */
+function interruptibleSleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.wake = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+  });
+}
+
+const WAIT_VERDICTS = { none: "free", stale: "stale", own: "own" };
+
+async function runWait({ ctx, emit, hint, fail }) {
+  const { opts, base, claimPath, classify } = ctx;
+  let timeoutSeconds;
+  let intervalSeconds;
+  try {
+    timeoutSeconds = positiveNumber(opts.timeout ?? DEFAULT_WAIT_TIMEOUT_SECONDS, "timeout");
+    intervalSeconds = positiveNumber(opts.interval ?? DEFAULT_WAIT_INTERVAL_SECONDS, "interval");
+  } catch (err) {
+    return fail(err.message, base);
+  }
+
+  const signal = { interrupted: false, wake: () => {} };
+  const onSignal = () => {
+    signal.interrupted = true;
+    signal.wake();
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let announced = false;
+
+  try {
+    for (;;) {
+      const claim = readClaim(claimPath);
+      const classification = classify(claim);
+      const verdict = WAIT_VERDICTS[classification.kind];
+      if (verdict) {
+        const holder =
+          claim && claim !== CORRUPT ? { holder: describeHolder(claim, classification) } : {};
+        await emit({ ...base, state: verdict, ...holder });
+        return EXIT.ok;
+      }
+      if (!announced) {
+        hint(`waiting — ${holderHint(describeHolder(claim, classification))}`);
+        announced = true;
+      }
+      if (signal.interrupted || Date.now() >= deadline) {
+        await emit({ ...base, state: signal.interrupted ? "interrupted" : "timeout" });
+        return EXIT.ok;
+      }
+      await interruptibleSleep(
+        Math.min(intervalSeconds * 1000, Math.max(0, deadline - Date.now())),
+        signal,
+      );
+    }
+  } finally {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  }
+}

package/bin/cli.mjs

@@ -7,6 +7,9 @@
 // Usage:
 //   conveyor-skills link      (default) create/refresh links, prune stale ones
 //   conveyor-skills link --check   verify links; exit 1 if missing/stale
+//   conveyor-skills checkout <acquire|verify|release|status|wait> ...
+//                             take turns on a shared local checkout
+//                             (see bin/checkout-claim.mjs)
 //
 // Only links owned by this package (target path contains conveyor-skills/skills/)
 // are ever replaced or pruned. Real directories and foreign symlinks are left
@@ -68,10 +71,17 @@ function ownedBy(linkPath) {
 }
 
 const args = process.argv.slice(2);
+
+if (args[0] === "checkout") {
+  const { runCheckoutCli } = await import("./checkout-claim.mjs");
+  // runCheckoutCli resolves only after its JSON line has flushed.
+  process.exit(await runCheckoutCli(args.slice(1)));
+}
+
 const checkOnly = args.includes("--check");
 const command = args.find((a) => !a.startsWith("-")) ?? "link";
 if (command !== "link")
-  fail(`unknown command '${command}' — only 'link' (with optional --check) exists`);
+  fail(`unknown command '${command}' — expected 'link' (with optional --check) or 'checkout'`);
 
 // This package's own skills/ dir, resolved through any install symlink (bun
 // may install the package as a symlink into its store).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Shared Claude Code skills for Conveyor consumer repos, linked into .claude/skills via the conveyor-skills CLI",
   "keywords": [
     "claude",
@@ -20,5 +20,9 @@
   "type": "module",
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "node --test __tests__/checkout-claim.test.mjs",
+    "test:unit": "node --test __tests__/checkout-claim.test.mjs"
   }
 }

package/skills/conveyor-build/SKILL.md

@@ -102,6 +102,12 @@ task binding and no user account.
   stack) is the entire value of local execution, and worktrees have none of it.
   A dirty `git status` before any branch switch is a hard stop: report and let
   the user commit or stash. Do not solve it with a second checkout.
+- **Take turns on the checkout.** Another local session can share this
+  checkout, and a clean tree does not prove it is idle. Hold the checkout
+  claim from before the card claim until the finish line, and never switch
+  branches while another session holds it — the protocol, commands, and what
+  each result means are in
+  [references/checkout-claim.md](references/checkout-claim.md). A pod skips it.
 - The dev database and dev-server ports are shared with the user's own
   sessions. No destructive experiments, never reset the dev DB, and reuse a
   running dev stack rather than fighting over ports.
@@ -149,10 +155,13 @@ say why.
 
 ## Claim
 
-Re-confirm the card is still claimable, then `mcp__conveyor__update_task` →
+Re-confirm the card is still claimable. **Locally**, take the checkout claim
+first (`checkout acquire --card <slug>`,
+[references/checkout-claim.md](references/checkout-claim.md)); `held` means
+flag and wait, not claim. Then `mcp__conveyor__update_task` →
 `status: "InProgress"`, then `mcp__conveyor__post_to_chat` with a claim marker
 naming where you are running. Status changed under you → someone else took it;
-stop.
+release the checkout claim and stop.
 
 **A pack parent is claimed differently** — see the pack path. The parent stays
 parked and the chat marker IS the claim.
@@ -285,7 +294,10 @@ Refresh against the card's base first, then gate, then open — in that order, s
 nothing invalidates the verification you just did:
 
 1. `git fetch origin <base> && git merge origin/<base> --no-edit`
-2. One verification pass, scoped to the diff.
+2. One verification pass, scoped to the diff. **Locally**, run
+   `checkout verify --card <slug>` before the pass, each commit and push, and
+   the PR call; anything but `ok` means stop (see
+   [references/checkout-claim.md](references/checkout-claim.md)).
 3. `mcp__conveyor__create_pull_request`, naming the base branch **explicitly**.
    **The two surfaces spell these differently and unknown keys are silently
    dropped, not rejected** — locally it is `head:` / `base:`; in a pod it is
@@ -298,6 +310,8 @@ nothing invalidates the verification you just did:
    should look at, and anything you did NOT do.
 
 Then confirm CI actually started (read-only `gh pr checks`). Do not wait on it.
+**Locally**, that is the finish line for the checkout too:
+`checkout release --card <slug>`.
 
 **Do not re-merge the base and do not re-run a gate that already passed.** If
 the base moved while the gates ran, open the PR anyway — CI validates against
@@ -332,8 +346,9 @@ After two genuinely different failed approaches, or on a decision only the user
 can make: post the reason AND the specific question to chat, set the card back
 to `"Open"`, restore the tree (locally, `git checkout dev` — leaving a shared
 checkout parked on an abandoned feature branch is how the next session starts
-from the wrong base), and stop. A vague "this is hard" is not a handoff; the
-question is what makes it one.
+from the wrong base), release the checkout claim locally
+(`checkout release --card <slug>`), and stop. A vague "this is hard" is not a
+handoff; the question is what makes it one.
 
 **A thin plan is a different case, and it does not stop a pack.** A card whose
 plan fails the context-free-reader bar: post what is missing to its chat and

package/skills/conveyor-build/references/checkout-claim.md

@@ -0,0 +1,98 @@
+# Checkout claim — local sessions take turns on one checkout
+
+The protocol behind every "hold the checkout claim" line in
+[conveyor-build](../SKILL.md), its [task path](task-path.md) and
+[pack path](pack-path.md), [conveyor-local-loop](../../conveyor-local-loop/SKILL.md),
+and local fixes in [conveyor-review](../../conveyor-review/SKILL.md).
+
+**Why.** The card claim (`InProgress` plus a chat marker) stops two sessions
+working ONE card. It does nothing about two sessions working two cards in ONE
+checkout. A clean tree passes the "dirty `git status` → stop" rule even while
+another session is mid-task, so `git checkout -B <branch>` succeeds and switches
+the branch underneath it. The checkout claim closes that gap: one session holds
+the working tree at a time, and every other session waits.
+
+**Scope: local only.** A pod has its own checkout and never runs this. Skip
+every checkout-claim step when you are in a pod.
+
+## How to call it
+
+The helper is the `checkout` subcommand of the `conveyor-skills` bin. Pick the
+form once per session:
+
+```bash
+[ -x node_modules/.bin/conveyor-skills ] && echo local || echo npx
+```
+
+- `local` → `node_modules/.bin/conveyor-skills checkout <command> …`
+- `npx` → `npx -y -p @rallycry/conveyor-skills@latest conveyor-skills checkout <command> …`
+- The local bin answers `unknown command 'checkout'` (an older branch or an old
+  install) → use the `npx` form.
+
+Write the chosen form out literally in every call. Never store it in a shell
+variable and run `$VAR checkout …`: zsh does not word-split it.
+
+`--card` is the card you are working. Inside a pack it is ALWAYS the pack
+parent's slug, for the whole run. Identity comes from `CONVEYOR_SESSION_ID`, then
+`CLAUDE_CODE_SESSION_ID`. A runtime that sets neither passes a stable
+`--session <id>` on every call; without it the identity falls back to
+`card:<slug>`, which still works but frees a dead holder only after the TTL.
+
+The claim is one file, `<git dir>/conveyor-checkout-claim.json`. It is never
+committed and never shows in `git status`. Each command prints ONE line of
+JSON on stdout (`{"command","state","head","dirty",…}`) and a hint on stderr.
+
+## When
+
+| Moment | Command |
+| --- | --- |
+| Before the first git write or card status write (before the claiming `update_task`) | `acquire --card <slug>` |
+| After every branch create or switch | `acquire --card <slug> --branch <branch>` |
+| Before each gate, commit, push, and `create_pull_request`; at the start of every wake while you hold the claim | `verify --card <slug>` (also refreshes the heartbeat) |
+| Finish line reached (PR open, CI started), parked, blocked, or the card claim lost — after restoring the tree | `release --card <slug>` |
+
+## What each result means
+
+| Command | State (exit) | Do this |
+| --- | --- | --- |
+| `acquire` | `acquired`, `refreshed` (0) | Carry on. |
+| `acquire` | `took-over` (0) | The previous holder was dead or stale. If `dirty` is true, the tree holds that claim's unfinished work for THIS card: audit it before you continue. |
+| `acquire` | `held` (3) | Another session holds the checkout. Touch nothing — no checkout, no status write, no commit. Flag it (below), then wait. |
+| `acquire` | `dirty` (5) | The tree is dirty and no live claim covers it. Hard stop: report it. The user commits or stashes, never you. |
+| `verify` | `ok` (0) | Carry on. |
+| `verify` | `branch-moved` (4) | HEAD is not the claimed branch — someone switched it, or your own checkout failed and left you on the previous branch. Do not commit or push. Report it and stop. |
+| `verify` | `lost` (3) | You no longer hold the claim. Stop touching the tree and `acquire` again, then follow that result. |
+| `release` | `released`, `none` (0) | Done. |
+| `release` | `held` (3) | The claim is not yours. Leave it. |
+| any | `error` (1) | Usage error or not a git repo. Read the stderr line. |
+
+**Flag, then wait.** On `held`, tell the user which card, branch and host hold
+the checkout (the `holder` field has all three). A standalone build also posts
+one line to its card's chat, for example
+`[build] waiting — checkout held by <card> on <branch>`. Then wait:
+
+```bash
+node_modules/.bin/conveyor-skills checkout wait --timeout 1740   # or the npx form
+```
+
+In Claude Code, launch it with Bash `run_in_background: true` and end the
+turn. Its completion notification is the wake. In Codex, hold the command
+session open until it returns. The result is advisory, like `conveyor-wait`:
+`free`, `stale`, or `own` → run `acquire` again; `timeout` → arm ONE new wait.
+Never arm a second wait while one is running.
+
+## Rules that go with the claim
+
+- **Stage by path, never `git add -A`.** In a shared checkout an untracked file
+  can belong to another session.
+- **No claim, dirty tree → refuse.** `acquire` enforces the old "dirty tree is
+  a hard stop" rule deterministically. It also covers ad-hoc sessions that
+  never take a claim.
+- **A stale claim is taken over only on a clean tree, or when it names the
+  same card.** A holder is stale when its pid is dead on this host, when the
+  same pid now runs a different session (a `/clear`), or when its heartbeat is
+  older than the TTL (7200s; `CONVEYOR_CHECKOUT_CLAIM_TTL_SECONDS` or `--ttl`
+  overrides it).
+- **Human override.** `checkout status` shows the holder and never changes
+  anything. `checkout release --force` drops someone else's claim, or a claim
+  file that does not parse. Run it only when the user tells you to.

package/skills/conveyor-build/references/pack-path.md

@@ -24,6 +24,13 @@ alternative is where pack incidents come from.
    IMMEDIATELY record it: `mcp__conveyor__update_task` with
    `githubBranch: <branch>`.
 
+   **Locally, take the checkout claim before any of this** —
+   `checkout acquire --card <parent-slug>` before you cut or check out the
+   pack branch, then `acquire --card <parent-slug> --branch <pack>` once you
+   are on it ([checkout-claim.md](checkout-claim.md)). The pack holds the
+   claim for the WHOLE run: `--card` stays the parent's slug through every
+   child, and `--branch` follows each child-branch and pack-branch switch.
+
    That write is load-bearing, not bookkeeping. Identification mints a
    competing `conveyor/*` branch name onto any branchless card it processes,
    and every pack-child merge handler keys on the card's recorded branch
@@ -121,6 +128,10 @@ state and is a no-op. This is NOT the "insurance wakeup" the pod prompt
 forbids: that rule is about a background job's own completion notification,
 which does fire. Nothing at all notifies a pack between children, so the
 heartbeat is the only guaranteed wake a Claude pack has. Do not delete it.
+Locally, every wake — heartbeat or not — starts with
+`checkout verify --card <parent-slug>` before it touches the tree, and a
+result other than `ok` stops the pack (see
+[checkout-claim.md](checkout-claim.md)).
 
 **Codex CLI.** There is no `ScheduleWakeup` and no `/loop`. The thread goal
 created per the SKILL.md *Goal and finish line* section is the continuation:
@@ -153,7 +164,10 @@ parent chat, skip that child, and take the next ready one.
 Then follow [task-path.md](task-path.md), with one substitution: the child
 branches from the **pack branch**, not `dev`, and its PR's base is the pack
 branch. Name that base explicitly — the default is `dev`, and the two surfaces
-spell the argument differently (`base:` locally, `baseBranch:` in a pod).
+spell the argument differently (`base:` locally, `baseBranch:` in a pod). The
+pack already holds the checkout claim, so the task path's claim steps become
+`acquire --card <parent-slug> --branch <child-branch>` after you cut the child
+branch, and there is no release at the child's finish line.
 
 > **Environment — a pod has no child branches and no child PRs.** Everything
 > above describes the LOCAL model, where each child gets its own branch and its
@@ -261,7 +275,8 @@ leave the branch pushed, and stop.
    `base:` `dev`. The parent moves to ReviewPR. Post the pack summary: what
    shipped per child, how it was verified, what reviewers should look at.
 4. Confirm CI started. **Never approve or merge this PR** — it is the one that
-   gets independent review.
+   gets independent review. Locally, release the checkout:
+   `checkout release --card <parent-slug>`.
 
 ## Parked protocol
 
@@ -269,4 +284,6 @@ After two genuinely different failed approaches on a child, or a decision only
 the user can make: post the reason and the specific question to the child AND
 parent chats, set the child back to `Open`, restore the tree, and take the next
 child whose dependency chain does not run through the parked one. Everything
-remaining blocked → report and stop; the user's reply is the un-park signal.
+remaining blocked → restore the tree, release the checkout claim locally
+(`checkout release --card <parent-slug>`), report, and stop; the user's reply
+is the un-park signal, and the resumed run acquires again.

package/skills/conveyor-build/references/task-path.md

@@ -13,11 +13,14 @@ Re-confirm via `mcp__conveyor__get_task` that the card is still claimable —
 `Open` (or whatever status the user explicitly overrode), no assignee you do
 not expect, no active session. Then:
 
-1. `mcp__conveyor__update_task` → `status: "InProgress"`
-2. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
+1. **Locally only:** `checkout acquire --card <slug>` — the checkout claim from
+   [checkout-claim.md](checkout-claim.md). `held` → touch nothing, flag it, and
+   wait; `dirty` → hard stop. A pod skips this step.
+2. `mcp__conveyor__update_task` → `status: "InProgress"`
+3. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
 
 If the status changed under you between the read and the write, someone else
-took it. Stop rather than compete.
+took it. Release the checkout claim and stop rather than compete.
 
 ## 2. Branch from the card's base — never blindly `dev`
 
@@ -29,6 +32,10 @@ git fetch origin <base>
 git checkout -B <feat|fix|chore>/<slug> origin/<base>
 ```
 
+Locally, record the branch on the checkout claim straight after the checkout:
+`checkout acquire --card <slug> --branch <feat|fix|chore>/<slug>`. Do the
+same after any later branch switch.
+
 Two cases that are not a fresh branch:
 
 - **The card already has a `githubBranch` with commits on origin.** Resume THAT
@@ -39,7 +46,8 @@ Two cases that are not a fresh branch:
   absent even though the branch exists on the remote. Fetch it explicitly
   (`git fetch origin <branch>`) rather than concluding the branch is missing —
   and note that a failed `checkout` leaves you on your PREVIOUS branch, where a
-  follow-up `git push` will push the wrong thing.
+  follow-up `git push` will push the wrong thing. Locally, `checkout verify`
+  reports exactly that as `branch-moved`.
 
 Reinstall dependencies if the lockfile changed.
 
@@ -62,6 +70,8 @@ Chat at milestones, not per step.
 These are identical to the SKILL.md sections of the same names. In particular:
 sync the base BEFORE the verification pass, pass `base:` explicitly to
 `mcp__conveyor__create_pull_request`, and confirm CI started without waiting on
-it.
+it. Locally, `checkout verify --card <slug>` before the gate, each commit and
+push, and the PR call.
 
 Finish line: the card in ReviewPR with CI started. You do not merge it.
+Locally, `checkout release --card <slug>` once CI has started.

package/skills/conveyor-local-loop/SKILL.md

@@ -47,12 +47,27 @@ adds only selection, claiming, cadence, and local-machine hygiene.
   Clean tree before any branch switch is still a hard rule: dirty
   `git status` at iteration start → touch nothing, report, and idle — the
   resolution is the user committing or stashing, not a second checkout.
+- **Hold the checkout claim while you use the tree.** WIP = 1 is per loop,
+  not per checkout: two loops, or a loop plus an interactive session, can
+  share this checkout, and a clean tree does not prove it is idle. Every tier
+  that touches git takes the claim first and gives it back at the finish line —
+  protocol in [conveyor-build's checkout-claim reference](../conveyor-build/references/checkout-claim.md).
 - **Push early.** There is no pod WIP-autosync locally; committed-and-pushed is
   the only durable state. Push the branch (`-u origin`) as soon as it exists.
 
 ## Iteration order
 
-Each invocation does the FIRST of these that produces work, then paces:
+Each invocation does the FIRST of these that produces work, then paces.
+
+**Checkout first.** Start every iteration with `checkout status`. `live` or
+`corrupt` means another session holds this checkout: skip Recover, Babysit
+fixes, and Claim (all three touch the tree), arm ONE background
+`checkout wait` (see *Waking on board events*), and pace. Otherwise, each tier
+below runs `checkout acquire --card <slug>` for its card before its first git
+command or status write; `held` → stop that tier and arm the wait. The chat
+marker names only the host, so a second loop on this host also matches
+"my" marker in Recover — the checkout claim is what keeps it off a card another
+live loop is still working.
 
 1. **Recover** — a card with my `[local-loop] claimed` chat marker still
    InProgress without a PR? Resume it. The branch may already exist locally or
@@ -89,13 +104,14 @@ Each invocation does the FIRST of these that produces work, then paces:
    Skip `followParentStatus` mirror children. A blocker counts as met only
    when merged-or-beyond (ReviewDev/ReviewLive/Complete) or Cancelled — a
    blocker sitting in ReviewPR is NOT met until its PR merges.
-2. Claim: re-confirm via `get_task` it is still Open, then
-   `mcp__conveyor__update_task` → `status: "InProgress"`, then
+2. Claim: re-confirm via `get_task` it is still Open, take the checkout claim
+   (`checkout acquire --card <slug>`; `held` → do not claim, arm the wait),
+   then `mcp__conveyor__update_task` → `status: "InProgress"`, then
    `mcp__conveyor__post_to_chat`: `[local-loop] claimed — working locally on
    <hostname>`. Claiming a PACK is different — never set the parent
    InProgress: leave it Open and post the pack claim marker instead (see Pack
-   mode). Status changed under you → someone else took it; next
-   candidate.
+   mode). Status changed under you → someone else took it; release the
+   checkout claim and take the next candidate.
 3. Plan missing or failing the context-free-reader bar → don't wing it: post
    what's missing to chat, leave the card Open, skip it.
 
@@ -115,15 +131,18 @@ This section adds only what the LOOP changes:
   re-check the parent's status; if it went InProgress or ReviewPR, post
   `[local-loop] parked: pack coordinator active — yielding`, leave the branch
   pushed, and let the coordinator take over.
-- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`) and end
-  the iteration — the Babysit tier owns it from there. This is the loop's one
-  real departure from a standalone build, which stays with its PR.
+- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`),
+  `checkout release --card <slug>`, and end the iteration — the Babysit tier
+  owns it from there. This is the loop's one real departure from a standalone
+  build, which stays with its PR. A Babysit fix re-acquires with that card and
+  releases again once the fix is pushed. A pack child's PR is the exception:
+  the pack keeps the claim until its finale PR opens.
 
 **Parked protocol** — after 2 genuinely different failed approaches, or on a
 decision only the user can make: post `[local-loop] parked: <reason + the
 specific question>`, set status back to `"Open"`, restore the tree
-(`git checkout dev`), move on. The user's next chat reply is the un-park
-signal.
+(`git checkout dev`), `checkout release --card <slug>`, move on. The user's
+next chat reply is the un-park signal.
 
 ## Pack mode
 
@@ -136,9 +155,9 @@ dev→pack sync after every merge, cross-reference, then the finale parent PR
 into dev. That reference is the source of truth for the procedure; this section
 only defines how it embeds in the loop:
 
-- The pack occupies the loop's single WIP slot from claim until the finale PR
-  opens. Do not interleave unrelated cards mid-pack — that thrashes branch
-  state.
+- The pack occupies the loop's single WIP slot — and holds the checkout
+  claim under the parent's slug — from claim until the finale PR opens. Do not
+  interleave unrelated cards mid-pack — that thrashes branch state.
 - Claim marker goes to the PARENT chat: `[local-loop] claimed — driving this
   pack locally on <hostname>, pack branch <branch>`. The parent's status
   stays Open (parked); the marker is the claim.
@@ -208,9 +227,12 @@ On wake, run a normal iteration and re-enumerate with
 `mcp__conveyor__list_tasks`. By then the card may be claimed, cancelled, or
 blocked by a dependency — never claim straight from the wait payload.
 
-**Never arm a second wait.** On a wake where a wait process is still in flight
-and the queue is still empty, re-arm the fallback `ScheduleWakeup` and end the
-turn.
+**Never arm a second wait.** At most ONE background wait of either kind —
+`conveyor-wait` or `checkout wait` — runs at a time. On a wake where a wait
+process is still in flight and nothing else changed, re-arm the fallback
+`ScheduleWakeup` and end the turn. When the checkout is held, the
+`checkout wait` is the one to arm: the board wait cannot tell you when the
+checkout frees up.
 
 ## Pacing (dynamic /loop only)
 
@@ -219,7 +241,7 @@ Under `/loop` with no interval, end EVERY iteration with exactly one
 
 | State | Delay | Reason should say |
 |-------|-------|-------------------|
-| A background gate/agent/conveyor-wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
+| A background gate/agent/conveyor-wait/checkout wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
 | ANY actionable work exists: claimable cards or packs, a pack child to implement/merge, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
 | Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty; conveyor-wait armed, so this is only the fallback |
 | Loop-fatal: MCP dead after 2 tries, dirty tree, broken repo | notify the user (PushNotification if available), then 1800s — or `stop: true` if continuing is unsafe | what is wrong |
@@ -249,7 +271,8 @@ depth each iteration so the user can offload manually.
 - Not a pod: no sandbox, no WIP snapshots, and the dev DB + dev-server ports
   are shared with the user's interactive sessions — no destructive
   experiments, never reset the dev DB, reuse a running dev stack rather than
-  fighting over ports.
+  fighting over ports. The git checkout is shared the same way, which is why
+  the loop takes turns on it through the checkout claim.
 - Not a parallel executor: one card (or one pack) at a time is the point (the
   full machine per gate). Backlogged? That is what claudespaces — or the
   offload valve — are for.

package/skills/conveyor-release-review/SKILL.md

@@ -25,10 +25,11 @@ most two packs.
 **Finish line:** the report — verdict on its first line — posted to the
 conversation, and to the release card's chat when a release card exists.
 
-**A turn may end only when:** (a) the finish line is true, or (b) an
-`AskUserQuestion` is pending because the release scope is genuinely ambiguous.
-Anything else — a ledger with blank rows, findings listed but not filed, packs
-created with no report — is a stalled run, not a paused one.
+**A turn may end only when:** (a) the finish line is true, (b) an
+`AskUserQuestion` is pending because the release scope is genuinely ambiguous,
+or (c) agents you launched are still running; their completion notices resume
+the run. Anything else — a ledger with blank rows, findings listed but not
+filed, packs created with no report — is a stalled run, not a paused one.
 
 **Runtime:** *Codex CLI* — before step 0, create a thread goal with your goal
 tool: "Post a release verdict for <release> with every change evaluated and
@@ -63,6 +64,9 @@ the finish line above is the loop.
   access and any release checklist live in the host repo's CLAUDE.md. A wrapper
   skill may add dimensions (see the end of this file); it cannot lower the
   evidence bar.
+- **The fan-out rules are not project policy.** They follow from how the
+  harness behaves and from account limits, so no project can relax them. A
+  wrapper may LOWER the concurrency cap; it may never raise it or lift a rule.
 
 ## 0 — Discover the project
 
@@ -131,9 +135,21 @@ Anchor to a concrete diff before reading any code.
 5. **Build the coverage ledger** — one row per PR or card, one row per
    dimension in step 2. Every row ends `clean`, `finding`, or
    `not reviewable (why)`. "Evaluate everything" means the ledger has no blank
-   rows when you finish. On a large release, fan subagents out per area and
-   give each the ground rules and the evidence bar verbatim; the ledger is
-   still the completeness check, and it stays with you.
+   rows when you finish.
+
+**Fanning out.** On a large release, split the ledger across subagents per
+area. Give each the ground rules and the evidence bar verbatim. Three rules
+hold, and the mechanics are in [references/fan-out.md](references/fan-out.md):
+
+1. **The hand-back is the only report channel.** The harness refuses report
+   files written by subagents. Each agent's final message is its report, and
+   you save each one to the run directory the moment it arrives.
+2. **Only you spawn agents.** Every agent prompt forbids the Agent, Task and
+   Workflow tools. Nested agents share your session limit.
+3. **At most four agents in flight**, the adversarial agent included. Launch
+   the next slice when one hands back, never in fixed waves.
+
+The ledger is still the completeness check, and it stays with you.
 
 ## 2 — Review every dimension
 
@@ -206,9 +222,12 @@ in it that mattered.
 ## 5 — The adversarial pass
 
 Every candidate that reached step 4, **together with the fix you would
-propose**, now faces a reviewer whose only job is to strike it. Use a fresh
-subagent given the finding, its evidence and the tests below, told to argue
-for striking. Where subagents are unavailable, switch stance explicitly and
+propose**, now faces a reviewer whose only job is to strike it. Use one fresh
+subagent for all candidates, under the fan-out rules. Write the candidates,
+with their evidence, priority and proposed fix, to `candidates.md` in the run
+directory; with no fan-out, put them in the prompt instead. The agent argues
+for striking each against the tests below and hands back one verdict per
+candidate. Where subagents are unavailable, switch stance explicitly and
 write the case against each finding before deciding.
 
 Strike when:
@@ -344,6 +363,10 @@ moves.
   already happened.
 - Diagnosing an incident here. An incident the release implicates is
   evidence; its root cause belongs to `/conveyor-triage`.
+- Telling subagents to write findings files. The harness refuses them. The
+  hand-back is the report, and saving it is your job.
+- Letting a reviewer fan out. Its agents share your session limit, and a limit
+  hit kills every agent in flight with its unsaved work.
 
 ## Wrapping this skill for one project
 
@@ -364,6 +387,10 @@ evidence bar and adversarial pass.
   re-check before concluding.
 - The log tools appear only for a project with the matching integration. If
   they are absent, the project has none; say so instead of hunting.
+- `You've hit your session limit · resets <time>` (HTTP 429) is the account's
+  five-hour usage window, shared by every agent and by you. Nothing runs until
+  the reset, so do not retry. Resume per
+  [references/fan-out.md](references/fan-out.md).
 
 ## Improve This Skill
 

package/skills/conveyor-release-review/references/dimensions.md

@@ -287,3 +287,9 @@ Evidence tools:
 
 A wrapper may add dimensions and name tools. It may not lower the evidence
 bar, skip the adversarial pass, or change what the priority levels mean.
+
+A wrapper also may not relax the fan-out rules in
+[fan-out.md](fan-out.md): subagents hand back text and write no report files,
+only the orchestrator spawns agents, and at most four run at once. These
+follow from how the harness behaves and from account limits, not from project
+policy. A wrapper may LOWER the cap; it may never raise it or lift a rule.

package/skills/conveyor-release-review/references/fan-out.md

@@ -0,0 +1,130 @@
+# Fanning out — the mechanics
+
+How the orchestrator of a [release review](../SKILL.md) splits the ledger
+across subagents without losing their work. SKILL.md states the three rules;
+this file is how to follow them.
+
+## Why
+
+Two limits broke earlier runs. Neither is project policy. Both come from how
+the harness and the account behave, so a wrapper skill may lower the cap
+below but never raise it or lift a rule.
+
+1. **The harness refuses report files from subagents.** Claude Code's Write
+   tool refuses a subagent `.md` whose name starts with REPORT, SUMMARY,
+   FINDINGS or ANALYSIS:
+
+   ```
+   Subagents should return findings as text, not write report files.
+   ```
+
+   This guard is deliberate. Do not route around it with another file name or
+   a Bash heredoc. The subagent's final message is the report.
+
+2. **Every agent draws on one account session limit.** The limit is a single
+   five-hour usage window. Every subagent and the orchestrator share it. When
+   it runs out, every call fails at once:
+
+   ```
+   You've hit your session limit · resets 9:20pm
+   ```
+
+   (HTTP 429, `rateLimitType: "five_hour"`). Every agent in flight dies, and
+   its unsaved work dies with it. The orchestrator is down too, until the
+   reset. A run with 13 agents in flight lost 10; a run with about 10 in flight
+   (one reviewer spawned 3 of its own) lost 5. Runs at 7 and at 4 lost none.
+
+No cap makes a run safe, because the limit is account-wide. The cap bounds
+what one hit destroys. The no-nesting rule and the tool-call budget cut what a
+run spends.
+
+## The run directory
+
+`/tmp/conveyor-release-review/<label-slug>/`, where `<label-slug>` is the
+release label in kebab case (`release-2026-09-30`, `pre-release-2026-09-30`).
+Create it before the first launch. It holds:
+
+- `brief.md` — the shared part of every agent prompt: the brief block below,
+  the ground rules and the evidence bar, verbatim.
+- `ledger.md` — the coverage ledger. Its first line names the run directory,
+  so a resumed or compacted session finds it again.
+- `<slice>.md` — one file per agent, holding that agent's hand-back.
+
+**On each completion notice, in this order:**
+
+1. Write the hand-back verbatim to `<slice>.md`. Do this before you read it
+   closely, and before anything else can fail.
+2. Mark the ledger rows the hand-back covers.
+3. Launch the next slice, if one is waiting.
+
+The saved files are the durable record. They survive compaction and a resume,
+and the adversarial agent reads findings from them by path.
+
+## The brief block
+
+Paste this verbatim into every agent prompt, area and adversarial alike:
+
+```markdown
+1. Your final message is your report. Do not write report, summary or
+   findings files, and do not route a refused write through Bash or another
+   file name. The orchestrator saves your final message.
+2. Do not spawn agents or run workflows (no Agent, Task or Workflow tool).
+   The orchestrator owns all fan-out.
+3. Budget: about 150 tool calls. At the budget, stop and return what you
+   have, listing what you did not reach as "not reviewed".
+4. Already settled, do not re-derive: <list, or "nothing yet">.
+```
+
+Then give the hand-back format:
+
+- **Coverage** — one row per PR or card: `clean`, `finding`, or
+  `not reviewable (why)`.
+- **Findings** — each with its priority, the PR that introduced it, the
+  evidence grade, the exact command and its result, the smallest fix, and the
+  strongest case for striking it.
+- **Unverified** — each with the query that would settle it.
+- **Struck** — each with its reason.
+- **Deploy-checklist items.**
+
+## Scheduling
+
+- **At most 4 agents in flight**, the adversarial agent included.
+- **Launch as slots free up**, not in fixed waves. When one agent hands back
+  and its file is saved, launch the next slice.
+- **One adversarial agent.** Launch it only after every area file exists and
+  you have finished steps 3 and 4. First write `candidates.md`: every
+  candidate that reached step 4, with its evidence, its priority and the fix
+  you would propose. The area files hold raw hand-backs, so they miss your own
+  candidates, your grading and your fixes. The agent reads `candidates.md`,
+  opens the area files only for detail, argues for striking each candidate,
+  and hands back one verdict per candidate. Save its hand-back to
+  `adversarial.md`.
+- While agents run, end the turn. Their completion notices resume the run.
+
+## When an agent dies
+
+**A session limit** (`session limit · resets <time>`):
+
+1. You are down too. Nothing runs until the reset, and an immediate retry
+   fails. Do not retry.
+2. After the reset, reread the run directory and the ledger.
+3. Relaunch only the slices with no `<slice>.md`. Narrow each one if you can,
+   and give each an already-settled list built from the saved files.
+4. Never relaunch above the cap that hit the limit. If 4 in flight hit it,
+   relaunch at 3 or fewer.
+
+**Any other error** (overloaded, or a rate limit with no reset time):
+
+1. Wait a minute or two, then relaunch that one slice once.
+2. If it fails again, review the slice yourself, or mark its ledger rows
+   `not reviewable (agent failed twice: <error>)`.
+
+**Always:**
+
+- Never relaunch a slice whose file exists.
+- Never relaunch a whole wave.
+
+## If you were spawned as a subagent yourself
+
+You are not the orchestrator. Do not fan out. Work the ledger yourself, and
+return your report as your final message.

package/skills/conveyor-review/SKILL.md

@@ -110,6 +110,12 @@ You have write access. Use it in proportion:
 
 - **Small and unambiguous** → fix it, commit, push, then re-review your own
   change as part of the diff. After pushing, wait for CI before approving.
+  **Locally**, a fix checks out the PR branch in a checkout other sessions may
+  share. Run `checkout acquire --card <slug>` before the checkout (`held` →
+  flag the fix instead of making it), `checkout acquire --card <slug> --branch
+  <pr-branch>` after it, and `checkout release --card <slug>` once the fix is
+  pushed and the tree is restored — protocol in
+  [conveyor-build's checkout-claim reference](../conveyor-build/references/checkout-claim.md).
 - **Larger, or a judgment call the author should make** → flag it in the
   verdict with the file, the line, what is wrong, and a suggested direction.
 

package/skills/conveyor-workflows/SKILL.md

@@ -215,6 +215,13 @@ sync-spawned duplicate.
   origin <branch>` and `git merge-base --is-ancestor` before rebuilding
   anything locally — platform autosync may have already pushed for you, and a
   dirty tree may belong to a concurrent session.
+- **Local sessions take turns on one checkout.** `conveyor-build`,
+  `conveyor-local-loop` and local `conveyor-review` fixes hold a checkout
+  claim, so a second session waits instead of switching branches underneath
+  the first. `conveyor-skills checkout status` shows who holds it (card,
+  branch, host, heartbeat age). `conveyor-skills checkout release --force` is
+  the human override for a wedged claim — an agent runs it only when the user
+  says so. Protocol: `conveyor-build/references/checkout-claim.md`.
 
 ## Improve This Skill