gcf-harness-aif-ext 0.8.3 → 0.8.7

package/README.md

@@ -77,7 +77,7 @@ Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry wh
 
 **`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code. It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
 
-**`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree. Logs: `.gcf-session/runs/<id>.log`. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`.
+**`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p --output-format stream-json --verbose "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree and the agent's own session (`--resume <session_id>`, kept in `.gcf-session/runs/<id>.agent.json`), in either run mode; `--fresh` starts a new session instead. A session cut off by Claude's usage limit reports `paused (usage limit, resets 3am (…))` and `limit_resets`. Logs: `.gcf-session/runs/<id>.log`, written as the session works: a `start:` line, then one stamped line per agent message, tool call (`tool: Edit <file>`, `tool: Bash <command>`) and failed tool result, and at the end the agent's final text and `done in 34m, 212 turns, $3.41 (…tokens)`; stderr goes in as it is, and a non-Claude `--agent` keeps its own lines. With `--json`, each item carries the session's `cost_usd`, `tokens`, `turns` and `duration_ms` when the agent reported them. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`.
 
 **`/gcf-run-ingest <gdd.md>`** — imports a design document as a fan-out workflow: parallel aspect extraction, provenance verified by code rather than by an agent (a quote either is a verbatim substring of its section or it is not), completeness lenses per candidate, and an interaction matrix computed from the candidates that write the same state.
 

package/commands/activity.js

@@ -0,0 +1,161 @@
+// The live log of an agent session: `claude -p --output-format stream-json` prints one JSON event
+// per line, and the run log gets one readable line per event worth seeing, so an operator can tell
+// a working session from a stuck one. A line that is not JSON is another agent's own output.
+
+/**
+ * @typedef {object} Cost What a session spent, from its `result` event.
+ * @property {number} cost_usd
+ * @property {{input: number, output: number, cache_read: number, cache_creation: number}} tokens
+ * @property {number} turns
+ * @property {number} duration_ms
+ */
+
+/** `12:03:10`, the local time of day. */
+export const clock = (now = new Date()) => now.toTimeString().slice(0, 8);
+
+const cut = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
+
+/** The first `n` non-empty lines of a text, trimmed, on one line. */
+const firstLines = (text, n) =>
+  String(text)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .slice(0, n)
+    .join(' ');
+
+// The input field that tells most about a tool call, in this order; with none, the name alone.
+const TELLING = ['file_path', 'command', 'pattern', 'url'];
+
+function toolLine(use) {
+  const key = TELLING.find((k) => typeof use.input?.[k] === 'string');
+
+  return key ? `tool: ${use.name} ${cut(firstLines(use.input[key], 1), 120)}` : `tool: ${use.name}`;
+}
+
+/** A tool result's text: a string, or a list of text blocks. */
+const resultText = (content) =>
+  Array.isArray(content) ? content.map((c) => c?.text ?? '').join('\n') : String(content ?? '');
+
+/** `1.2M`, `85k`, `950`: one decimal below ten of its unit. */
+const count = (n) => (n >= 1e6 ? scaled(n / 1e6, 'M') : n >= 1e3 ? scaled(n / 1e3, 'k') : `${n}`);
+const scaled = (v, unit) => `${v < 10 ? v.toFixed(1) : Math.round(v)}${unit}`;
+
+/** `8s`, `34m`, `1h 12m`. */
+function span(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.round(s / 60);
+
+  return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+
+/** @returns {Cost} */
+function costOf(e) {
+  const u = e.usage ?? {};
+
+  return {
+    cost_usd: Number(e.total_cost_usd ?? 0),
+    tokens: {
+      input: Number(u.input_tokens ?? 0),
+      output: Number(u.output_tokens ?? 0),
+      cache_read: Number(u.cache_read_input_tokens ?? 0),
+      cache_creation: Number(u.cache_creation_input_tokens ?? 0),
+    },
+    turns: Number(e.num_turns ?? 0),
+    duration_ms: Number(e.duration_ms ?? 0),
+  };
+}
+
+function summary(e, c) {
+  const end = e.is_error ? `ended (${e.subtype ?? 'error'})` : 'done';
+  const t = c.tokens;
+
+  return (
+    `${end} in ${span(c.duration_ms)}, ${c.turns} turns, $${c.cost_usd.toFixed(2)} ` +
+    `(in ${count(t.input)} / out ${count(t.output)} tokens, cache read ${count(t.cache_read)}, ` +
+    `cache write ${count(t.cache_creation)})`
+  );
+}
+
+/**
+ * Claude's usage-limit ending, `You've hit your session limit · resets 3am (Europe/Berlin)`:
+ * `{limit: {resets}}`, the time it names (null without one), or nothing for any other text. An
+ * error result is the session's end, so the message anywhere in it counts; an agent's text or a
+ * plain line counts only when it is that message whole: prose about some other limit is not.
+ * @returns {{limit?: {resets: string | null}}}
+ */
+function limitIn(text, whole = true) {
+  const s = String(text ?? '').trim();
+  const hit = whole ? /^You['’]ve hit your [^\n]*limit[^\n]*$/i : /hit your .*limit/i;
+  if (!hit.test(s)) return {};
+
+  return { limit: { resets: s.match(/resets (.+)$/im)?.[1].trim() || null } };
+}
+
+/**
+ * One stdout line of a session as log lines: an event worth seeing becomes one stamped line, the
+ * rest of the stream (hooks, init, thinking, rate limits) none; the `result` event gives the
+ * final text, a summary line and the cost. `session_id` comes with the init event, `limit` with
+ * the usage-limit message, in whatever form it arrives: the session can be resumed after either.
+ * @param {string} line
+ * @returns {{lines: string[], cost?: Cost, session_id?: string, limit?: {resets: string | null}}}
+ */
+export function activity(line, now = new Date()) {
+  let e;
+  try {
+    e = JSON.parse(line);
+  } catch {
+    return { lines: [line], ...limitIn(line) };
+  }
+
+  if (typeof e?.type !== 'string') return { lines: [line] };
+
+  const at = `[${clock(now)}]`;
+  const content = Array.isArray(e.message?.content) ? e.message.content : [];
+  if (e.type === 'system') return system(e);
+  if (e.type === 'assistant') return said(content, at);
+  if (e.type === 'user')
+    return {
+      lines: content
+        .filter((b) => b.type === 'tool_result' && b.is_error)
+        .map((b) => `${at} tool error: ${cut(firstLines(resultText(b.content), 1), 300)}`),
+    };
+  if (e.type === 'result') return ended(e, at);
+
+  return { lines: [] };
+}
+
+/** A system event: the init names the session; the rest (hooks, thinking) give nothing. */
+const system = (e) =>
+  e.subtype === 'init' && typeof e.session_id === 'string'
+    ? { lines: [], session_id: e.session_id }
+    : { lines: [] };
+
+/** An assistant turn: its tool calls and its text, which may be the usage-limit message. */
+function said(content, at) {
+  const texts = content.filter((b) => b.type === 'text').map((b) => b.text);
+
+  return {
+    ...(texts.map((t) => limitIn(t)).find((l) => l.limit) ?? {}),
+    lines: content.flatMap((b) => {
+      if (b.type === 'tool_use') return [`${at} ${toolLine(b)}`];
+      const text = b.type === 'text' ? cut(firstLines(b.text, 2), 300) : '';
+
+      return text ? [`${at} agent: ${text}`] : [];
+    }),
+  };
+}
+
+/** The `result` event: the final text, a summary line, the cost, and a limit that ended it. */
+function ended(e, at) {
+  const cost = costOf(e);
+  const text =
+    typeof e.result === 'string' && e.result.trim() ? [`${at} result:\n${e.result}`] : [];
+
+  return {
+    lines: [...text, `${at} ${summary(e, cost)}`],
+    cost,
+    ...(e.is_error ? limitIn(e.result, false) : {}),
+  };
+}

package/commands/harness.js

@@ -303,7 +303,7 @@ export function register(program) {
     .description('Run items at once, each in its worktree with its own agent, then integrate')
     .option(
       '--agent <command>',
-      'the agent command; it gets "/gcf-run <id> --worktree"',
+      'the agent command; it gets "/gcf-run <id> --worktree", or --resume <session> to go on',
       process.env.GCF_RUN_AGENT ?? DEFAULT_AGENT,
     )
     .option(
@@ -312,6 +312,7 @@ export function register(program) {
       String(DEFAULT_TIMEOUT_MIN),
     )
     .option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
+    .option('--fresh', 'start new agent sessions: an interrupted one is not resumed')
     .option('--json', 'machine output')
     .action(runItems);
 
@@ -416,6 +417,7 @@ async function runItems(ids, opts) {
       gate: (batch) => gate(auditReport(), batch),
       timeoutMs: minutes * 60_000,
       mode: opts.mode,
+      fresh: Boolean(opts.fresh),
     });
     if (opts.json) console.log(JSON.stringify(r, null, 2));
     else printRun(r);

package/commands/run.js

@@ -3,11 +3,13 @@
 // verified branches a dead run left; an agent that needs the human leaves `outcome.json` in its
 // worktree, and the block is recorded on main — a worktree never writes gcf/ status.
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, utimesSync, writeFileSync } from 'node:fs';
+import { existsSync, utimesSync, writeFileSync, writeSync } from 'node:fs';
 import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { activity, clock } from './activity.js';
 
-export const DEFAULT_AGENT = 'claude -p';
+// The event stream, not the final answer alone: the log shows the session at work as it goes.
+export const DEFAULT_AGENT = 'claude -p --output-format stream-json --verbose';
 
 /** The core CLI: the same ai-factory that runs this command, in the project. */
 export function cliCore(projectDir) {
@@ -90,36 +92,104 @@ function stopWithSessions() {
   return () => process.removeListener('SIGTERM', stop);
 }
 
+/**
+ * Hand a stream to `take` line by line. Returns the flush of a last line with no newline: a
+ * stream destroyed under a tool that holds it open never ends.
+ */
+function byLine(stream, take) {
+  let rest = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk) => {
+    const lines = (rest + chunk).split('\n');
+    rest = lines.pop() ?? '';
+    for (const l of lines) take(l);
+  });
+  const flush = () => {
+    if (rest) take(rest);
+    rest = '';
+  };
+
+  stream.on('end', flush);
+
+  return flush;
+}
+
+// What `claude --resume` prints on stderr for a session it does not have.
+const NO_SESSION = /No conversation found with session ID/;
+
 /**
  * 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
- * good.
+ * good. Its stdout reaches the log through `activity`, its stderr as it is; `cost` is what a
+ * Claude session reported at its end, `session_id` the id a rerun resumes it by, `limit` the
+ * usage limit that ended it, `gone` that the session it was to resume does not exist.
+ * @returns {Promise<{code: number | string, cost?: import('./activity.js').Cost,
+ *   session_id?: string, limit?: {resets: string | null}, gone: boolean}>}
  */
 function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
   return new Promise((resolve) => {
-    const child = spawn(`${agent} "${prompt}"`, {
+    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.
       env: { ...process.env, GCF_RUN_ITEM: id },
       detached: !WIN,
       windowsHide: true,
-      stdio: ['ignore', fd, fd],
+      stdio: ['ignore', 'pipe', 'pipe'],
     });
     sessions.add(child);
     if (child.pid) onSpawn?.(child.pid);
+    let open = true;
+    let cost;
+    let sessionId;
+    let limit;
+    let gone = false;
+    const write = (lines) => {
+      try {
+        if (open && lines.length) writeSync(fd, lines.map((l) => `${l}\n`).join(''));
+      } catch {
+        // A log that cannot be written loses its lines, not the run.
+      }
+    };
+
+    const flushOut = byLine(child.stdout, (line) => {
+      const a = activity(line);
+      cost = a.cost ?? cost;
+      sessionId = a.session_id ?? sessionId;
+      limit = a.limit ?? limit;
+      write(a.lines);
+    });
+    const flushErr = byLine(child.stderr, (line) => {
+      gone ||= NO_SESSION.test(line);
+      write([line]);
+    });
     const timer = setTimeout(() => {
       killTree(child);
-      resolve('timeout');
+      end('timeout');
     }, timeoutMs);
-    const end = (code) => {
+    function end(code) {
+      if (!open) return;
+      flushOut();
+      flushErr();
+      open = false;
       sessions.delete(child);
       clearTimeout(timer);
-      resolve(code);
-    };
+      resolve({ code, cost, session_id: sessionId, limit, gone });
+    }
 
     child.on('error', () => end(-1));
-    child.on('exit', (code) => end(code ?? -1));
+    // `close` waits for the agent's output as well: its last lines, the result, may come after
+    // its exit. A tool it left running may hold that output open: the session ends with it.
+    child.on('close', (code) => end(code ?? -1));
+    child.on('exit', () =>
+      setTimeout(() => {
+        child.stdout.destroy();
+        child.stderr.destroy();
+      }, 2000).unref(),
+    );
   });
 }
 
@@ -154,11 +224,24 @@ function alive(pid) {
  */
 async function claim(logs, id) {
   const file = path.join(logs, `${id}.lock`);
-  for (let attempt = 0; attempt < 2; attempt++) {
+  // Three tries: a breaker a dead run left, then the dead lock itself, is cleared on the way. A
+  // lock released between the create and the read spends no try, up to six rounds in all.
+  for (let attempt = 0, round = 0; attempt < 3 && round < 6; round++) {
     if (await create(file)) return () => rm(file, { force: true });
-    const text = await readFile(file, 'utf8').catch(() => null);
-    if (text === null) continue; // released meanwhile
-    const pid = Number(text.trim());
+    let text;
+    try {
+      text = await readFile(file, 'utf8');
+    } catch (e) {
+      // Released meanwhile: the next create may take it. A lock that cannot be read is busy.
+      if (e.code === 'ENOENT') continue;
+
+      return null;
+    }
+
+    attempt++;
+
+    // The run's pid is the first line; a started session adds the item and its own pid.
+    const pid = Number(text.split('\n')[0]);
     if (pid === process.pid) return () => rm(file, { force: true });
     if (!(await dead(file, pid))) return null;
     await clearDead(file, text);
@@ -197,7 +280,15 @@ async function dead(file, pid) {
  */
 async function clearDead(file, text) {
   const breaker = `${file}.break`;
-  if (!(await create(breaker))) return;
+  if (!(await create(breaker))) {
+    // A breaker is held for a read and a remove: one whose run is gone was left by a crash there.
+    const held = await readFile(breaker, 'utf8').catch(() => null);
+    if (held !== null && (await dead(breaker, Number(held.split('\n')[0]))))
+      await rm(breaker, { force: true });
+
+    return;
+  }
+
   try {
     if ((await readFile(file, 'utf8').catch(() => null)) === text) await rm(file, { force: true });
   } finally {
@@ -205,9 +296,14 @@ async function clearDead(file, text) {
   }
 }
 
-/** Whether the tip of the worktree's branch carries `GCF-Verified: <id>`. */
+// The item's branch, as the integrator reads it: not HEAD, which a session cut off mid-rebase
+// leaves detached.
+const branchRef = (id) => `refs/heads/work/${id}`;
+
+/** Whether the tip of the item's branch carries `GCF-Verified: <id>`. */
 function verified(dir, id) {
-  const res = spawnSync('git', ['log', '-1', '--format=%(trailers:key=GCF-Verified,valueonly)'], {
+  const format = '--format=%(trailers:key=GCF-Verified,valueonly)';
+  const res = spawnSync('git', ['log', '-1', format, branchRef(id)], {
     cwd: dir,
     encoding: 'utf8',
   });
@@ -215,20 +311,50 @@ function verified(dir, id) {
   return (res.stdout ?? '').split('\n').some((v) => v.trim() === id);
 }
 
+// Not a slug, so no item: the lock a run gates its batch and claims its items under.
+const ADMIT = '.admit';
+
 /**
- * The worktree and the agent command of each item, claimed for this run; an item that cannot
- * start is an error. `agentOf(id)` gives the command.
+ * `fn` under the admission lock: two runs started at once (two board clicks) would each pass a
+ * gate that sees no lock of the other yet, and run together what the gate keeps apart.
  */
-async function prepare(ids, core, logs, agentOf) {
-  const ready = [];
+async function admitted(logs, fn) {
+  const until = Date.now() + 60_000;
+  let release = await claim(logs, ADMIT);
+  while (!release) {
+    if (Date.now() > until)
+      throw new Error(`another run is starting (${ADMIT}.lock in ${logs}): retry when it ends`);
+    await new Promise((r) => setTimeout(r, 100));
+    release = await claim(logs, ADMIT);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}
+
+/** Every item claimed for this run, or an error when another run drives it. */
+async function claimAll(ids, logs) {
+  const claimed = [];
   const failed = [];
   for (const id of ids) {
     const release = await claim(logs, id);
-    if (!release) {
-      failed.push({ id, result: 'error', error: `${id} is already running in another run` });
-      continue;
-    }
+    if (release) claimed.push({ id, release });
+    else failed.push({ id, result: 'error', error: `${id} is already running in another run` });
+  }
 
+  return { claimed, failed };
+}
+
+/**
+ * The worktree and the agent command of each claimed item; an item that cannot start is an
+ * error. `agentOf(id)` gives the command.
+ */
+async function prepare({ claimed, failed }, core, agentOf) {
+  const ready = [];
+  for (const { id, release } of claimed) {
     try {
       const agent = agentOf(id);
       const wt = json(await core(['worktree', id, '--json']), `worktree ${id}`);
@@ -243,14 +369,98 @@ async function prepare(ids, core, logs, agentOf) {
   return { ready, failed };
 }
 
+/** `<id>.agent.json`: the agent session an item's last run left unfinished, for a rerun. */
+const recordOf = (logs, id) => path.join(logs, `${id}.agent.json`);
+
+// A session id goes into the agent's shell command: a UUID, nothing else.
+const SESSION_ID = /^[0-9a-f-]{36}$/i;
+
+/** The kept session of an item, or null: a file that is not a record is none. */
+async function kept(logs, id) {
+  try {
+    const rec = JSON.parse(await readFile(recordOf(logs, id), 'utf8'));
+
+    return SESSION_ID.test(String(rec?.session_id)) ? rec : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+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) return;
+  const ended = r.limit ? 'limit' : r.code === 'timeout' ? 'timeout' : `exit ${r.code}`;
+  const rec = {
+    session_id: r.session_id,
+    ended,
+    ...(r.limit?.resets ? { resets: r.limit.resets } : {}),
+    at: new Date().toISOString(),
+  };
+  await writeFile(recordOf(logs, r.id), `${JSON.stringify(rec, null, 2)}\n`);
+}
+
+/**
+ * The line of a session that ended with its item still ready: why, and what a rerun does. A
+ * usage limit pauses the item; `limit_resets` tells a board when it may go on.
+ */
+function noResult(r, rerun) {
+  if (r.lost)
+    return {
+      id: r.id,
+      result:
+        `no result (its session could not be resumed, agent exit ${r.code}): ` +
+        `${r.id} stays ready, a rerun starts fresh`,
+    };
+  const again = r.session_id ? 'a rerun resumes its session' : rerun;
+  if (r.limit) {
+    const resets = r.limit.resets ? `, resets ${r.limit.resets}` : '';
+
+    return {
+      id: r.id,
+      result: `paused (usage limit${resets}): ${r.id} stays ready, ${again}`,
+      limit_resets: r.limit.resets,
+    };
+  }
+
+  const why = r.code === 'timeout' ? 'the session timed out' : `agent exit ${r.code}`;
+
+  return { id: r.id, result: `no result (${why}): ${r.id} stays ready, ${again}` };
+}
+
+const STAYED = / stays ready, a rerun /;
+
+/**
+ * The agent command and prompt of an item's session: `/gcf-run`, or the resume of the session
+ * its last run kept (`--resume`, in the same directory, so the agent finds it) unless `fresh`.
+ */
+async function commandOf(r, logs, fresh) {
+  const task = r.main ? `/gcf-run ${r.id}` : `/gcf-run ${r.id} --worktree`;
+  if (fresh) await rm(recordOf(logs, r.id), { force: true });
+  // `--resume` is a flag of `claude`: another agent gets the task, and the record stays.
+  const rec = fresh || !/^claude(\s|$)/.test(r.agent) ? null : await kept(logs, r.id);
+  if (!rec) return { agent: r.agent, prompt: task, rec };
+  // One plain line: the prompt goes into the shell command in double quotes.
+  const ended = String(rec.ended).replace(/[^\w -]/g, '');
+
+  return {
+    agent: `${r.agent} --resume ${rec.session_id}`,
+    prompt: `Continue ${task}: the session was cut off (${ended}). Pick up where you stopped.`,
+    rec,
+  };
+}
+
 /**
  * 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.
  */
-async function session(r, logs, timeoutMs) {
+async function session(r, logs, timeoutMs, fresh) {
   /** @type {import('node:fs/promises').FileHandle | null} */
   let log = null;
-  const prompt = r.main ? `/gcf-run ${r.id}` : `/gcf-run ${r.id} --worktree`;
   // The lock names the item and its session: `stop <id>` ends that session alone, not the run.
   const lock = path.join(logs, `${r.main ? MAIN_RUN : r.id}.lock`);
   const onSpawn = (pid) => writeFileSync(lock, `${process.pid}\n${r.id}\n${pid}\n`);
@@ -258,10 +468,22 @@ async function session(r, logs, timeoutMs) {
   const mark = path.join(logs, `${r.id}.session`);
   const keep = r.main ? setInterval(() => touch(mark), 5 * 60_000) : null;
   try {
+    const { agent, prompt, rec } = await commandOf(r, logs, fresh);
     log = await open(path.join(logs, `${r.id}.log`), 'a');
     const opts = { fd: log.fd, timeoutMs, id: r.id, onSpawn };
+    const ran = await startAgent(agent, prompt, r.dir, opts);
+
+    // 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.
+    const lost = Boolean(rec) && ran.gone;
 
-    return { ...r, code: await startAgent(r.agent, prompt, r.dir, opts) };
+    return {
+      ...r,
+      ...ran,
+      session_id: ran.session_id ?? (lost ? undefined : rec?.session_id),
+      lost,
+    };
   } catch (e) {
     return { ...r, code: null, error: e.message };
   } finally {
@@ -287,8 +509,11 @@ function touch(file) {
  */
 async function recordBlock(r, outcome, core) {
   const reason = String(outcome.block);
-  if (verified(r.dir, r.id))
-    spawnSync('git', ['commit', '--allow-empty', '-m', `gcf(unverified): ${r.id}`], { cwd: r.dir });
+  // A block recorded over a trailer that stayed would see the branch merged after its unblock,
+  // without the answer: the operator gets the error instead.
+  const failed = unverify(r);
+  if (failed)
+    return { id: r.id, result: 'error', reason, error: `${failed}; the block is not recorded` };
   const b = await core(['block', r.id, '--reason', reason]);
 
   return {
@@ -299,18 +524,42 @@ async function recordBlock(r, outcome, core) {
   };
 }
 
+// The bookkeeping commit's author when the worktree has none: the trailer must come off anyway.
+const GCF_IDENT = {
+  GIT_AUTHOR_NAME: 'gcf',
+  GIT_AUTHOR_EMAIL: 'gcf@localhost',
+  GIT_COMMITTER_NAME: 'gcf',
+  GIT_COMMITTER_EMAIL: 'gcf@localhost',
+};
+
+/**
+ * An empty commit takes the trailer off the branch tip: no integrate merges it. Plumbing, not
+ * `git commit`: it never touches the index, so what a killed agent staged, its index.lock or a
+ * merge it left half done cannot stop it.
+ */
+function unverify(r) {
+  if (!verified(r.dir, r.id)) return null;
+  const git = (args, env = {}) =>
+    spawnSync('git', args, { cwd: r.dir, encoding: 'utf8', env: { ...process.env, ...env } });
+  const ref = branchRef(r.id);
+  const tip = git(['rev-parse', ref]).stdout.trim();
+  const tree = ['commit-tree', `${ref}^{tree}`, '-p', ref, '-m', `gcf(unverified): ${r.id}`];
+  let made = git(tree);
+  if (made.status !== 0) made = git(tree, GCF_IDENT);
+  const moved = made.status === 0 && git(['update-ref', ref, made.stdout.trim(), tip]);
+
+  // shortcut: the integrate after it still merges a branch whose trailer stayed; the report
+  // says so, upgrade to integrating only the named branches if it ever happens.
+  return moved && moved.status === 0
+    ? null
+    : `could not take its trailer off: ${(moved || made).stderr.trim()}`;
+}
+
 /** The result line of an item the integrator handled, or why it has none. */
 function resultOf(run, integrated) {
   const done = integrated.find((x) => x.id === run.id);
   if (!done && run.error) return { id: run.id, result: 'error', error: run.error };
-  if (!done) {
-    const why = run.code === 'timeout' ? 'the session timed out' : `agent exit ${run.code}`;
-
-    return {
-      id: run.id,
-      result: `no result (${why}): ${run.id} stays ready, a rerun resumes its worktree`,
-    };
-  }
+  if (!done) return noResult(run, 'a rerun resumes its worktree');
 
   return {
     ...done,
@@ -336,9 +585,8 @@ async function mainResult(core, r) {
   if (!after) return { id: r.id, result: 'close' };
   if (after.status !== 'ready')
     return { id: r.id, result: MOVE_OF[after.status] ?? after.status, reason: after.blocked };
-  const why = r.code === 'timeout' ? 'the session timed out' : `agent exit ${r.code}`;
 
-  return { id: r.id, result: `no result (${why}): ${r.id} stays ready, a rerun picks it up` };
+  return noResult(r, 'a rerun picks it up');
 }
 
 // The lock of the main checkout itself: one run works there at a time. Not a slug, so no item.
@@ -350,7 +598,8 @@ export const MAIN_RUN = '.main-run';
  * carries a session mark (`gcf claim`), not a run lock: a lock would refuse the agent's own
  * moves. A session that stopped without a move leaves no mark behind.
  */
-async function runMain(projectDir, ids, { core, logs, agentOf, timeoutMs }) {
+async function runMain(projectDir, ids, ctx) {
+  const { logs } = ctx;
   const releaseMain = await claim(logs, MAIN_RUN);
   if (!releaseMain)
     return ids.map((id) => ({
@@ -361,8 +610,7 @@ async function runMain(projectDir, ids, { core, logs, agentOf, timeoutMs }) {
 
   const items = [];
   try {
-    for (const id of ids)
-      items.push(await mainItem(projectDir, id, { core, logs, agentOf, timeoutMs }));
+    for (const id of ids) items.push(await mainItem(projectDir, id, ctx));
   } finally {
     await releaseMain();
   }
@@ -371,7 +619,7 @@ async function runMain(projectDir, ids, { core, logs, agentOf, timeoutMs }) {
 }
 
 /** One item of a main run: marked, its session, its mark cleared, its result read. */
-async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs }) {
+async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs, fresh }) {
   let r;
   try {
     const claimed = await core(['claim', id]);
@@ -379,36 +627,51 @@ async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs }) {
     const none = async () => {};
 
     const s = { id, dir: projectDir, agent: agentOf(id), release: none, main: true };
-    r = await session(s, logs, timeoutMs);
+    r = await session(s, logs, timeoutMs, fresh);
   } catch (e) {
     r = { id, error: e.message };
   }
 
   await core(['release', id]);
+  const item = await mainResult(core, r);
+  await remember(logs, r, item);
 
-  return mainResult(core, r);
+  return { ...item, ...r.cost };
 }
 
-/** Every item in its own worktree at once; blocks recorded on main, verified branches merged. */
-async function runWorktrees(ids, { core, logs, agentOf, timeoutMs }) {
-  const { ready, failed } = await prepare(ids, core, logs, agentOf);
-  const runs = await Promise.all(ready.map((r) => session(r, logs, timeoutMs)));
+/** Every claimed item in its worktree at once; blocks recorded on main, verified ones merged. */
+async function runWorktrees(claims, { core, logs, agentOf, timeoutMs, fresh }) {
+  const { ready, failed } = await prepare(claims, core, agentOf);
+  const runs = await Promise.all(ready.map((r) => session(r, logs, timeoutMs, fresh)));
   const items = [...failed];
   for (const r of runs) {
     const outcome = await outcomeOf(r.dir);
     if (outcome?.block) items.push(await recordBlock(r, outcome, core));
+    // A session cut short (timeout, `stop`, a crash) may have meant to block after its trailer:
+    // its item stays ready, and the rerun verifies its branch again.
+    else if (r.code !== 0) {
+      const failed = unverify(r);
+      if (failed) items.push({ id: r.id, result: 'error', error: failed });
+    }
   }
 
   const integrated = json(await core(['integrate', '--json']), 'integrate');
   for (const r of runs) if (!items.some((i) => i.id === r.id)) items.push(resultOf(r, integrated));
+  for (const r of runs)
+    await remember(
+      logs,
+      r,
+      items.find((i) => i.id === r.id),
+    );
 
-  return items;
+  // What each session spent rides on its item's line, when the agent reported it.
+  return items.map((i) => ({ ...i, ...runs.find((r) => r.id === i.id)?.cost }));
 }
 
 /**
  * Pick up orphans, gate the batch, run the items in the project's run mode (`mode` overrides
  * it). `gate(ids)` answers `{pass, reason}`; a session past `timeoutMs` is stopped with all it
- * started, and its item stays ready.
+ * started, and its item stays ready. `fresh` starts new sessions where kept ones would resume.
  */
 export async function run(
   projectDir,
@@ -419,29 +682,39 @@ export async function run(
     gate,
     timeoutMs = DEFAULT_TIMEOUT_MIN * 60_000,
     mode = undefined,
+    fresh = false,
   },
 ) {
   // An id names a lock file and goes into the agent's shell command: a slug, nothing else.
   const bad = ids.find((id) => !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(id));
   if (bad) throw new Error(`${bad} is not an item id (a lowercase hyphen slug)`);
   const orphans = json(await core(['integrate', '--json']), 'integrate');
-  const passed = gate(ids);
-  if (!passed.pass) return { orphans, gate: passed.reason, items: [] };
-
   const logs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
   await mkdir(logs, { recursive: true });
   const board = json(await core(['board', '--json']), 'board');
   const runMode = mode ?? board.run_mode ?? 'worktree';
+  // The gate counts the items other runs hold locks on, so this run's locks go in with its gate.
+  // shortcut: a main run marks each item only as its session starts, so the items it has yet
+  // to reach do not count for another run's gate; claim them all here if main and worktree
+  // runs come to share a project.
+  const { passed, claims } = await admitted(logs, async () => {
+    const verdict = gate(ids);
+    const go = verdict.pass && runMode !== 'main';
+
+    return { passed: verdict, claims: go ? await claimAll(ids, logs) : null };
+  });
+  if (!passed.pass) return { orphans, gate: passed.reason, items: [] };
+
   const agentOf = (id) =>
     agentFor(
       agent,
       (board.items ?? []).find((i) => i.id === id),
     );
-  const ctx = { core, logs, agentOf, timeoutMs };
+  const ctx = { core, logs, agentOf, timeoutMs, fresh };
   const unhook = stopWithSessions();
   try {
     const items =
-      runMode === 'main' ? await runMain(projectDir, ids, ctx) : await runWorktrees(ids, ctx);
+      runMode === 'main' ? await runMain(projectDir, ids, ctx) : await runWorktrees(claims, ctx);
 
     return { orphans, mode: runMode, items };
   } finally {

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.8.3",
+  "version": "0.8.7",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/package.json

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

package/workflows/ingest.js

@@ -224,8 +224,9 @@ function splitByProvenance({ aspect, units }, bodyOf) {
   const cited = [];
   const inferred = [];
   for (const u of units) {
-    const body = ws(bodyOf.get(u.anchor) ?? '');
-    if (u.quote && body.includes(ws(u.quote))) cited.push(u);
+    // A blank quote is in every body, even the empty one of an anchor the GDD does not have.
+    const quote = ws(u.quote ?? '');
+    if (quote && ws(bodyOf.get(u.anchor) ?? '').includes(quote)) cited.push(u);
     else inferred.push({ ...u, aspect });
   }