gcf-harness-aif-ext 0.9.0 → 0.9.1

package/README.md

@@ -47,6 +47,11 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
 
+0.9.1 is a fix release:
+- A stopped session reads as `no result (stopped)`, and its kept record as `ended: stopped`: before, the kill's exit code (`agent exit 1` on Windows).
+- `gcf-harness stop <id>` never kills the run: a stop before the item's session starts (or between two sessions of a handoff) leaves `.gcf-session/runs/<id>.stop`, and that session is stopped as it starts. Before, a stop then killed the whole run with the other items of its batch. A run hung before its first session (in its worktree setup) is not stopped. On main, a stop marks the item too once the run has reached it. Known limit: a stop in the moment between a worktree run's claim of the item and its clearing of an old mark is lost.
+- A stop that comes while the session starts no longer misses it.
+
 0.9.0, to update together with core 0.7.6:
 - The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
 - A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.

package/commands/activity.js

@@ -192,7 +192,7 @@ function ended(e, at) {
 
   // The window of each model the session used: its subagents may run on another.
   const windows = Object.entries(e.modelUsage ?? {})
-    .map(([m, u]) => [m, Number(u?.contextWindow)])
+    .map(([m, u]) => /** @type {[string, number]} */ ([m, Number(u?.contextWindow)]))
     .filter(([, n]) => n > 0);
 
   return {

package/commands/harness.js

@@ -329,7 +329,7 @@ export function register(program) {
     });
   harness
     .command('stop <id>')
-    .description('Stop the run that drives an item, with every session it started; it stays ready')
+    .description('Stop the session that works an item; the run goes on, the item stays ready')
     .action((id) => console.log(stopRun(process.cwd(), id)));
 }
 
@@ -360,12 +360,12 @@ function lockOf(file) {
   }
 }
 
-/** Kill a process and everything under it: a tree on Windows, its own group elsewhere. */
-function killTree(pid, group) {
+/** Kill a session and everything under it: a tree on Windows, its own group elsewhere. */
+function killTree(pid) {
   if (WIN) spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
   else {
     try {
-      process.kill(group ? -pid : pid, group ? 'SIGKILL' : 'SIGTERM');
+      process.kill(-pid, 'SIGKILL');
     } catch {
       // Gone already.
     }
@@ -375,23 +375,24 @@ function killTree(pid, group) {
 /**
  * Stop the session that works `id`: the one its own lock names (worktree mode), or the main
  * checkout's run when that run works this very item (main mode). Only that session goes: the
- * run records it as no result and goes on with the rest. A run that has not started a session
- * yet goes down whole. The item stays ready and its work in progress is kept.
+ * run records it as stopped and goes on with the rest. The item stays ready and its work in
+ * progress is kept.
  */
 export function stopRun(projectDir, id, core = cliCore(projectDir)) {
   const runs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
-  const main = lockOf(path.join(runs, `${MAIN_RUN}.lock`));
-  const lock = lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
-  // Between two sessions of the item (a context handoff) the lock names none: the mark keeps
-  // the run from starting the next one.
-  if (lock?.item === id)
-    writeFileSync(
-      stopOf(runs, id),
-      `${Date.now()}
-`,
-    );
-  if (lock && lock.session && alive(lock.session)) killTree(lock.session, true);
-  else if (lock && lock.item !== id) killTree(lock.run, false);
+  const lockFor = () => {
+    const main = lockOf(path.join(runs, `${MAIN_RUN}.lock`));
+
+    return lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
+  };
+
+  // The mark says the session ended by a stop, and stops the next one as it starts: the lock
+  // names none before the item's first session, or between two of a handoff. Read again after
+  // the mark: a session that started meanwhile did not see it.
+  const lock = lockFor();
+  if (lock) writeFileSync(stopOf(runs, id), `${Date.now()}\n`);
+  const session = lock && lockFor()?.session;
+  if (session && alive(session)) killTree(session);
   core(['release', id]);
 
   return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;

package/commands/run.js

@@ -156,12 +156,12 @@ function killTree(child) {
   }
 }
 
-// The sessions this run has going: a stop (`gcf-harness stop`) takes them down with the run.
+// The sessions this run has going: a run that is killed (SIGTERM) takes them down with it.
 const sessions = new Set();
 
 /**
- * `gcf-harness stop` signals the run (SIGTERM); its sessions lead their own process groups, so
- * the run takes each down before it exits. On Windows the stop kills the whole tree itself.
+ * A run that gets SIGTERM (`gcf-harness stop <id>` stops one session, never the run): its
+ * sessions lead their own process groups, so the run takes each down before it exits.
  * Returns the unhook.
  */
 function stopWithSessions() {
@@ -202,6 +202,91 @@ function byLine(stream, take) {
 // What `claude --resume` prints on stderr for a session it does not have.
 const NO_SESSION = /No conversation found with session ID/;
 
+/** Keep what a session's activity told: the last of each, the model's window from the result. */
+function absorb(seen, a) {
+  seen.cost = a.cost ?? seen.cost;
+  seen.session_id = a.session_id ?? seen.session_id;
+  seen.limit = a.limit ?? seen.limit;
+  seen.model = a.model ?? seen.model;
+  // The init model's window; the largest when the result does not name that model.
+  if (a.windows) seen.window = a.windows[seen.model] ?? Math.max(...Object.values(a.windows));
+}
+
+/** Write the flag the handoff guard reads into the session's checkout. */
+function writeFlag(dir, flag) {
+  try {
+    mkdirSync(path.join(dir, '.gcf-session'), { recursive: true });
+    writeFileSync(path.join(dir, HANDOFF_FLAG), `${JSON.stringify(flag)}\n`);
+  } catch {
+    // No flag: the turns past it stop the session all the same.
+  }
+}
+
+/**
+ * An agent session's shell: its own process group off Windows, so a stop takes all it started.
+ * The guards read the session's own checkout, not one an outer Claude session named.
+ */
+function spawnAgent(command, dir, env) {
+  return spawn(command, {
+    cwd: dir,
+    shell: true,
+    // GCF_RUN_ITEM: the session's own gate must not refuse the item this run marked as running.
+    env: { ...process.env, ...env, CLAUDE_PROJECT_DIR: dir },
+    detached: !WIN,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * The handoff watch of one session (see `startAgent`): `see(a, model)` takes each activity, flags
+ * the session past its share or at a compaction, and calls `stop` once it works on past more.
+ */
+function handoffWatch(handoff, dir, write, stop) {
+  const w = { flagged: false, after: 0, context: 0, turn: undefined, unknown: false };
+  const unknownOnce = (model) => {
+    if (w.unknown) return;
+    w.unknown = true;
+    write([`[${clock()}] handoff: off, the window of ${model ?? 'the model'} is unknown`]);
+  };
+
+  const flag = (win, pct, compacted) => {
+    w.flagged = true;
+    writeFlag(dir, { pct, tokens: w.context, window: win, plan: handoff.plan ?? null });
+    const why = compacted
+      ? 'a compaction'
+      : `context ${pct}% (${count(w.context)} of ${count(win)})`;
+    write([`[${clock()}] handoff: ${why}, the session hands over`]);
+  };
+
+  const check = (model, compacted) => {
+    const win = handoff.windowOf(model);
+    const pct = win ? Math.round((100 * w.context) / win) : null;
+    // No share is under every threshold: a session of an unknown window hands over at a compaction.
+    const share = pct ?? 0;
+    if (pct === null && !compacted) unknownOnce(model);
+    if (!w.flagged && (compacted || share >= handoff.pct)) flag(win, pct, compacted);
+    if (w.flagged && (w.after > HARD_TURNS || share >= handoff.pct + HARD_OVER)) {
+      write([`[${clock()}] handoff: the session went on past its flag, stopped`]);
+      stop();
+    }
+  };
+
+  return {
+    state: w,
+    see(a, model) {
+      if (a.context !== undefined) {
+        w.context = a.context;
+        if (w.flagged && a.turn !== w.turn) w.after++;
+        w.turn = a.turn;
+      }
+
+      if (handoff?.pct && (a.context !== undefined || a.compacted))
+        check(model, Boolean(a.compacted));
+    },
+  };
+}
+
 /**
  * One agent session on `prompt` in `dir`; resolves with its exit code, or `timeout` when it ran
  * past `timeoutMs`: a hung session would hold the item's run lock, and every move on it, for
@@ -212,40 +297,23 @@ const NO_SESSION = /No conversation found with session ID/;
  * `handoff` ({pct, windowOf(model), plan}) watches the main agent's context: past `pct` of the
  * window, or at a compaction, the session gets `.gcf-session/handoff.json`, and the handoff
  * guard turns its tool calls into the instruction to hand over; one that keeps on working is
- * stopped. `handoff: true` says the session was told to hand over.
+ * stopped. `handoff: true` says the session was told to hand over, `handedOver` that it did.
  * @returns {Promise<{code: number | string, cost?: import('./activity.js').Cost,
  *   session_id?: string, limit?: {resets: string | null}, gone: boolean, handoff: boolean,
- *   model?: string, window?: number}>}
+ *   handedOver: boolean, model?: string, window?: number}>}
  */
 function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {}, handoff }) {
   return new Promise((resolve) => {
     const command = `${agent} "${prompt}"`;
     // A line before the agent's first: the log's time says the session is alive from its start.
     writeSync(fd, `[${clock()}] start: ${command}\n`);
-    const child = spawn(command, {
-      cwd: dir,
-      shell: true,
-      // The session's own gate must not refuse the item this run marked as running.
-      // The guards read the session's own checkout, not one an outer Claude session named.
-      env: { ...process.env, ...env, GCF_RUN_ITEM: id, CLAUDE_PROJECT_DIR: dir },
-      detached: !WIN,
-      windowsHide: true,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    const child = spawnAgent(command, dir, { ...env, GCF_RUN_ITEM: id });
     sessions.add(child);
     if (child.pid) onSpawn?.(child.pid);
     let open = true;
-    let cost;
-    let sessionId;
-    let limit;
+    /** @type {Record<string, any>} */
+    const seen = {};
     let gone = false;
-    let model;
-    let window;
-    let context = 0;
-    let flagged = false;
-    let unknown = false;
-    let turn;
-    let after = 0;
     const write = (lines) => {
       try {
         if (open && lines.length) writeSync(fd, lines.map((l) => `${l}\n`).join(''));
@@ -254,50 +322,15 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {},
       }
     };
 
-    /** The handoff watch of one event: flag the session past its share, stop it past more. */
-    const watch = (compacted) => {
-      if (!handoff?.pct || !open) return;
-      const win = handoff.windowOf(model);
-      const pct = win ? Math.round((100 * context) / win) : null;
-      if (pct === null && !compacted && !unknown) {
-        unknown = true;
-        write([`[${clock()}] handoff: off, the window of ${model ?? 'the model'} is unknown`]);
-      }
-      if (!flagged && (compacted || (pct !== null && pct >= handoff.pct))) {
-        flagged = true;
-        const flag = { pct, tokens: context, window: win, plan: handoff.plan ?? null };
-        try {
-          mkdirSync(path.join(dir, '.gcf-session'), { recursive: true });
-          writeFileSync(path.join(dir, HANDOFF_FLAG), `${JSON.stringify(flag)}\n`);
-        } catch {
-          // No flag: the turns past it stop the session all the same.
-        }
-        const at = compacted ? 'a compaction' : `context ${pct}%`;
-        const of = win && !compacted ? ` (${count(context)} of ${count(win)})` : '';
-        write([`[${clock()}] handoff: ${at}${of}, the session hands over`]);
-      }
-      if (flagged && (after > HARD_TURNS || (pct !== null && pct >= handoff.pct + HARD_OVER))) {
-        write([`[${clock()}] handoff: the session went on past its flag, stopped`]);
-        killTree(child);
-        end('handoff');
-      }
-    };
-
+    const watch = handoffWatch(handoff, dir, write, () => {
+      killTree(child);
+      end('handoff');
+    });
     const flushOut = byLine(child.stdout, (line) => {
       const a = activity(line);
-      cost = a.cost ?? cost;
-      sessionId = a.session_id ?? sessionId;
-      limit = a.limit ?? limit;
-      model = a.model ?? model;
-      // The init model's window; the largest when the result does not name that model.
-      if (a.windows) window = a.windows[model] ?? Math.max(...Object.values(a.windows));
+      absorb(seen, a);
       write(a.lines);
-      if (a.context !== undefined) {
-        context = a.context;
-        if (flagged && a.turn !== turn) after++;
-        turn = a.turn;
-      }
-      if (a.context !== undefined || a.compacted) watch(Boolean(a.compacted));
+      if (open) watch.see(a, seen.model);
     });
     const flushErr = byLine(child.stderr, (line) => {
       gone ||= NO_SESSION.test(line);
@@ -314,20 +347,11 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {},
       open = false;
       sessions.delete(child);
       clearTimeout(timer);
+      const { flagged, after } = watch.state;
       // Told to hand over, and it went on past the flag: it read the guard's instruction, or the
       // run stopped it. A flag on its last turn found a session already done.
       const handedOver = flagged && (after > 0 || code === 'handoff');
-      resolve({
-        code,
-        cost,
-        session_id: sessionId,
-        limit,
-        gone,
-        handoff: flagged,
-        handedOver,
-        model,
-        window,
-      });
+      resolve({ ...seen, code, gone, handoff: flagged, handedOver });
     }
 
     child.on('error', () => end(-1));
@@ -491,8 +515,14 @@ async function claimAll(ids, logs) {
   const failed = [];
   for (const id of ids) {
     const release = await claim(logs, id);
-    if (release) claimed.push({ id, release });
-    else failed.push({ id, result: 'error', error: `${id} is already running in another run` });
+    if (!release) {
+      failed.push({ id, result: 'error', error: `${id} is already running in another run` });
+      continue;
+    }
+
+    // A dead run's stop mark goes; one from now on stops the item's session as it starts.
+    await rm(stopOf(logs, id), { force: true });
+    claimed.push({ id, release });
   }
 
   return { claimed, failed };
@@ -519,7 +549,10 @@ async function prepare({ claimed, failed }, core, agentOf) {
   return { ready, failed };
 }
 
-/** `<id>.stop`: `gcf-harness stop` between two sessions of the item: no fresh one starts. */
+/**
+ * `<id>.stop`: `gcf-harness stop` while the item has no session, before its first or between two
+ * of a handoff: the next one is stopped as it starts.
+ */
 export const stopOf = (logs, id) => path.join(logs, `${id}.stop`);
 
 /** `<id>.agent.json`: the agent session an item's last run left unfinished, for a rerun. */
@@ -542,6 +575,19 @@ async function kept(logs, id) {
   }
 }
 
+/**
+ * Why a kept session ended. A session that handed over is not resumed: the rerun starts fresh
+ * from the plan. So does one after a handoff that reported no id: the full session before it is
+ * never resumed.
+ */
+function endedOf(r) {
+  if (r.handoffPending || !r.session_id) return 'handoff';
+  if (r.limit) return 'limit';
+  if (r.stopped) return 'stopped';
+
+  return r.code === 'timeout' ? 'timeout' : `exit ${r.code}`;
+}
+
 /**
  * The record of a session that ended with its item still ready: a rerun resumes it with all the
  * agent read and decided. The item's move ends the session for good; an error leaves it as is.
@@ -550,19 +596,14 @@ async function remember(logs, r, item) {
   if (item.result === 'error') return;
   if (!STAYED.test(item.result) || r.lost) return rm(recordOf(logs, r.id), { force: true });
   if (!r.session_id && !r.handoffPending && !r.handoffs) return;
-  // A session that handed over is not resumed: the rerun starts fresh from the plan. So does
-  // one after a handoff that reported no id: the full session before it is never resumed.
-  const ended =
-    r.handoffPending || !r.session_id
-      ? 'handoff'
-      : r.limit
-        ? 'limit'
-        : r.code === 'timeout'
-          ? 'timeout'
-          : `exit ${r.code}`;
-  const rec = {
+  await writeFile(recordOf(logs, r.id), `${JSON.stringify(recordFor(r), null, 2)}\n`);
+}
+
+/** The `<id>.agent.json` of a session that ended with its item still ready. */
+function recordFor(r) {
+  return {
     ...(r.session_id ? { session_id: r.session_id } : {}),
-    ended,
+    ended: endedOf(r),
     ...(r.limit?.resets ? { resets: r.limit.resets } : {}),
     // The handoffs so far: the cap holds across runs.
     ...(r.handoffs ? { handoffs: r.handoffs } : {}),
@@ -571,7 +612,6 @@ async function remember(logs, r, item) {
     ...(!r.handoffPending && !r.session_id ? { counted: true } : {}),
     at: new Date().toISOString(),
   };
-  await writeFile(recordOf(logs, r.id), `${JSON.stringify(rec, null, 2)}\n`);
 }
 
 /**
@@ -593,10 +633,12 @@ function noResult(r, rerun) {
 
     return {
       id: r.id,
-      result: `paused (${limit}context handoff): ${r.id} stays ready, a rerun goes on from the plan`,
+      result:
+        `paused (${limit}context handoff): ${r.id} stays ready, ` + 'a rerun goes on from the plan',
       ...(r.limit ? { limit_resets: r.limit.resets } : {}),
     };
   }
+
   const again = r.session_id ? 'a rerun resumes its session' : rerun;
   if (r.limit) {
     const resets = r.limit.resets ? `, resets ${r.limit.resets}` : '';
@@ -608,7 +650,11 @@ function noResult(r, rerun) {
     };
   }
 
-  const why = r.code === 'timeout' ? 'the session timed out' : `agent exit ${r.code}`;
+  const why = r.stopped
+    ? 'stopped'
+    : r.code === 'timeout'
+      ? 'the session timed out'
+      : `agent exit ${r.code}`;
 
   return { id: r.id, result: `no result (${why}): ${r.id} stays ready, ${again}` };
 }
@@ -639,6 +685,110 @@ async function commandOf(r, logs, fresh) {
   };
 }
 
+/**
+ * One agent session of the item `s.r`, its handoff flag cleared around it. `stopped` says a
+ * `gcf-harness stop` ended it.
+ */
+async function agentSession(s, agent, prompt) {
+  const { r, fd, deadline, launch } = s;
+  const flag = path.join(r.dir, HANDOFF_FLAG);
+  await rm(flag, { force: true });
+  const flags = launch?.flags(r.dir);
+  const handoff = launch?.handoff && { ...launch.handoff, plan: launch.planOf?.(r.id) };
+  const left = Math.max(deadline - Date.now(), 1000);
+  const opts = { fd, timeoutMs: left, id: r.id, onSpawn: s.onSpawn, env: launch?.env, handoff };
+  const ran = await startAgent(flags ? `${agent} ${flags}` : agent, prompt, r.dir, opts);
+  await rm(flag, { force: true });
+  // Between two sessions the lock names none: a stop then marks the item, not the run.
+  writeFileSync(s.lock, `${process.pid}\n${r.id}\n`);
+  if (launch?.learned) await learnWindow(s.logs, launch.learned, ran);
+
+  return { ...ran, stopped: existsSync(stopOf(s.logs, r.id)) };
+}
+
+/**
+ * Count the item's next handoff, or say the cap is reached: the item is then blocked. The cap
+ * counts each handoff once, the one a kept record still owes a session included.
+ */
+async function capped(count, r) {
+  if (count.handoffs < MAX_HANDOFFS) {
+    count.handoffs++;
+
+    return false;
+  }
+
+  count.limit = true;
+  // A worktree records no move: the main checkout reads the block from its outcome.
+  if (!r.main) {
+    await mkdir(path.join(r.dir, '.gcf-session'), { recursive: true });
+    const outcome = `${JSON.stringify({ block: HANDOFF_LIMIT })}\n`;
+    await writeFile(path.join(r.dir, '.gcf-session', 'outcome.json'), outcome);
+  }
+
+  return true;
+}
+
+/**
+ * Only a session that handed over as told goes on: one that saw its flag and ended its reply,
+ * or that the run stopped past it. A stop, a limit or the deadline leaves the handoff to the
+ * next run.
+ */
+async function goesOn(s, ran) {
+  const over = ran.handedOver && (ran.code === 0 || ran.code === 'handoff') && !ran.limit;
+
+  return over && Date.now() < s.deadline && !ran.stopped && !(await s.r.done?.());
+}
+
+/**
+ * Whether the session `rec` kept is gone: a resume that claude answered with `No conversation
+ * found`, so the next run starts fresh rather than fail on it again. Any other early end (a stop,
+ * a crash, no network) keeps it for the next try, and the resumed session's id stands in for one
+ * its own run did not report. A fresh session after a handoff has none to borrow: the full one is
+ * never resumed.
+ */
+function resumeLost(rec, ran) {
+  if (!rec || rec.ended === 'handoff') return false;
+  if (ran.gone) return true;
+  ran.session_id ??= rec.session_id;
+
+  return false;
+}
+
+/**
+ * The sessions of one item: the first runs its command; while one hands over as told, a fresh
+ * one goes on from the plan, up to MAX_HANDOFFS.
+ */
+async function handOver(s, { agent, prompt, rec }) {
+  const { r } = s;
+  const count = { handoffs: Number(rec?.handoffs) || 0, limit: false };
+  const fromHandoff = rec?.ended === 'handoff';
+  // A record whose handoff its own run already counted (`counted`) owes none.
+  if (fromHandoff && !rec.counted && (await capped(count, r)))
+    return { code: 0, handoffs: count.handoffs, handoffLimit: true, handoffPending: false };
+  let ran = await agentSession(s, agent, prompt);
+  let cost = ran.cost;
+  const lost = resumeLost(rec, ran);
+  while ((await goesOn(s, ran)) && !(await capped(count, r))) {
+    writeSync(
+      s.fd,
+      `[${clock()}] handoff ${count.handoffs}: a fresh session goes on from the plan\n`,
+    );
+    ran = await agentSession(s, r.agent, `${taskOf(r)} --handoff`);
+    cost = addCost(cost, ran.cost);
+  }
+
+  return {
+    ...ran,
+    cost,
+    handoffs: count.handoffs,
+    handoffLimit: count.limit,
+    // The session was told to hand over and no fresh one took it: the next run does.
+    // A limit there too: the rerun after the reset starts fresh, it does not resume the full one.
+    handoffPending: ran.handoff && !count.limit,
+    lost,
+  };
+}
+
 /**
  * One session per item, its output in `.gcf-session/runs/<id>.log`. In a worktree the skill runs
  * its worktree mode; on main it records the item's move itself.
@@ -653,97 +803,19 @@ async function session(r, { logs, timeoutMs, fresh, launch }) {
     // A stop that came while the lock named no session left only its mark: it ends this one.
     if (existsSync(stopOf(logs, r.id))) killTree({ pid });
   };
+
   // On main the item carries a session mark; a stage with no gcf command must not expire it.
   const mark = path.join(logs, `${r.id}.session`);
   const keep = r.main ? setInterval(() => touch(mark), 5 * 60_000) : null;
-  const flag = path.join(r.dir, HANDOFF_FLAG);
-  await rm(stopOf(logs, r.id), { force: true });
   try {
-    let { agent, prompt, rec } = await commandOf(r, logs, fresh);
+    const cmd = await commandOf(r, logs, fresh);
     log = await open(path.join(logs, `${r.id}.log`), 'a');
-    const fd = log.fd;
-    const flags = launch?.flags(r.dir);
-    const handoff = launch?.handoff && { ...launch.handoff, plan: launch.planOf?.(r.id) };
     // One deadline for the item, however many sessions it takes.
     const deadline = Date.now() + timeoutMs;
-    let handoffs = Number(rec?.handoffs) || 0;
-    let cost;
-    let ran = null;
-    let lost = false;
-    let handoffLimit = false;
-    const stopped = () => existsSync(stopOf(logs, r.id));
-    // The cap counts each handoff once, the one a kept record still owes a session included.
-    const capped = async () => {
-      if (handoffs < MAX_HANDOFFS) {
-        handoffs++;
-
-        return false;
-      }
-      handoffLimit = true;
-      // A worktree records no move: the main checkout reads the block from its outcome.
-      if (!r.main) {
-        await mkdir(path.join(r.dir, '.gcf-session'), { recursive: true });
-        await writeFile(
-          path.join(r.dir, '.gcf-session', 'outcome.json'),
-          `${JSON.stringify({ block: HANDOFF_LIMIT })}
-`,
-        );
-      }
-
-      return true;
-    };
-    // A record whose handoff its own run already counted (`counted`) owes none.
-    const fromHandoff = rec?.ended === 'handoff';
-    const owed = fromHandoff && !rec.counted;
-    for (let first = true; !(first && owed && (await capped())); first = false) {
-      await rm(flag, { force: true });
-      const command = flags ? `${agent} ${flags}` : agent;
-      const left = Math.max(deadline - Date.now(), 1000);
-      const opts = { fd, timeoutMs: left, id: r.id, onSpawn, env: launch?.env, handoff };
-      ran = await startAgent(command, prompt, r.dir, opts);
-      await rm(flag, { force: true });
-      // Between two sessions the lock names none: a stop then marks the item, not the run.
-      writeFileSync(
-        lock,
-        `${process.pid}
-${r.id}
-`,
-      );
-      cost = addCost(cost, ran.cost);
-      if (launch?.learned) await learnWindow(logs, launch.learned, ran);
-      // A resume that claude answered with `No conversation found`: the session is gone, and
-      // the next run starts fresh rather than fail on it again. Any other early end (a stop, a
-      // crash, no network) keeps it for the next try.
-      if (first) lost = Boolean(rec) && !fromHandoff && ran.gone;
-      // The resumed session's id stands in for one its own run did not report; a fresh session
-      // after a handoff has none to borrow: the full one is never resumed.
-      if (first && !fromHandoff && !lost) ran.session_id ??= rec?.session_id;
-
-      // Only a session that handed over as told goes on: one that saw its flag and ended its
-      // reply, or that the run stopped past it. A stop, a limit or the deadline leaves the
-      // handoff to the next run.
-      const over = ran.handedOver && (ran.code === 0 || ran.code === 'handoff') && !ran.limit;
-      if (!over || Date.now() >= deadline || stopped() || (await r.done?.())) break;
-      if (await capped()) break;
-      writeSync(
-        fd,
-        `[${clock()}] handoff ${handoffs}: a fresh session goes on from the plan
-`,
-      );
-      agent = r.agent;
-      prompt = `${taskOf(r)} --handoff`;
-    }
 
     return {
       ...r,
-      ...(ran ?? { code: 0 }),
-      cost,
-      handoffs,
-      handoffLimit,
-      // The session was told to hand over and no fresh one took it: the next run does.
-      // A limit there too: the rerun after the reset starts fresh, it does not resume the full one.
-      handoffPending: Boolean(ran?.handoff) && !handoffLimit,
-      lost,
+      ...(await handOver({ r, logs, lock, fd: log.fd, deadline, launch, onSpawn }, cmd)),
     };
   } catch (e) {
     return { ...r, code: null, error: e.message };
@@ -855,7 +927,7 @@ async function launchOf(logs, managed, board) {
         windowOf: (model) => windowFor(model, ctx.window, learned),
       },
     learned,
-    planOf: () => null,
+    planOf: (id) => board.items?.find((i) => i.id === id)?.plan_file ?? null,
   };
 }
 
@@ -912,10 +984,14 @@ async function runMain(projectDir, ids, ctx) {
 async function mainItem(projectDir, id, ctx) {
   const { core, logs, agentOf } = ctx;
   let r;
+  await rm(stopOf(logs, id), { force: true });
+  // The checkout's lock names the item from now on: a stop before its session marks it.
+  writeFileSync(path.join(logs, `${MAIN_RUN}.lock`), `${process.pid}\n${id}\n`);
   try {
     const claimed = await core(['claim', id]);
     if (!claimed.ok) throw new Error((claimed.err || claimed.out).trim());
     const none = async () => {};
+
     // The agent recorded the item's move: no fresh session takes it over.
     // A board that cannot be read is no move: the run goes on, and the result read says why.
     const done = async () => {
@@ -1023,7 +1099,6 @@ export async function run(
   const itemOf = (id) => (board.items ?? []).find((i) => i.id === id);
   const agentOf = (id) => agentFor(agent, itemOf(id));
   const ctx = { core, logs, agentOf, timeoutMs, fresh, launch };
-  launch.planOf = (id) => itemOf(id)?.plan_file ?? null;
   const unhook = stopWithSessions();
   try {
     const items =

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-harness-aif-ext",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/handoff-guard.js

@@ -57,6 +57,7 @@ export function readFlag(projectDir) {
   } catch {
     return null;
   }
+
   try {
     return JSON.parse(text) ?? {};
   } catch {
@@ -67,12 +68,14 @@ export function readFlag(projectDir) {
 // Hook entry: only runs when executed directly, so tests can import decide().
 const entry = process.argv[1]?.replaceAll('\\', '/');
 if (import.meta.url === `file://${entry}` || entry?.endsWith('handoff-guard.js')) {
+  /** @type {Record<string, any> | null} */
   let input = null;
   try {
     input = JSON.parse(readFileSync(0, 'utf8'));
   } catch {
     // No input: nothing to judge.
   }
+
   // The directory the session started in: `cwd` follows a `cd` of the agent.
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
   const verdict = decide(input, projectDir, readFlag(projectDir));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "type": "module",
   "license": "MIT",