gcf-harness-aif-ext 0.6.1 → 0.8.0

package/README.md

@@ -11,7 +11,7 @@ The harness turns policy-as-text into an executable pipeline. It has **no memory
 
 ## Requirements
 
-- [`gcf-aif-ext`](../gcf-aif-ext) `^0.5.3` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
+- [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.0` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
 - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
 - AI Factory 2.x, Node.js ≥ 22.14
 
@@ -47,6 +47,16 @@ 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.8.0, to update together with core 0.7.0:
+- `run_mode: main` in `gcf/config.yml` (or `run --mode main`): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
+- `gcf-harness next [N] --json`: the ready items that can run together now, by priority; each is taken while the batch with it passes the gate.
+- `gcf-harness stop <id>`: stops the session that works the item (its run lock names it); the run records no result for it and goes on with the rest. The item stays ready and its work is kept. Known limit: the session is killed at once, so a `gcf` move it was in the middle of may leave `.gcf-session/main.lock` behind (taken over once its pid is gone).
+- A run on main refreshes its item's mark every 5 minutes, and the readset-guard hook refreshes live marks on each read: a long build without a gcf command does not expire it.
+- `run` refuses an id that is not a slug before it names a lock file or builds the agent's command line.
+- The gate lets a session through for the item its own run marked (`GCF_RUN_ITEM`); `/gcf-run` outside a worktree claims each item after its gate and releases one it leaves without a move.
+
+0.7.0, to update together with core 0.6.0: an item's `model:` and `effort:` (`gcf item new --model <m> --effort <e>`) go to its agent as `--model <m> --effort <e>`, read from `gcf board --json`; a value that is not one plain word fails that item and starts no session. `--timeout <minutes>` (120 by default) stops a session that runs longer, with every process it started; its item stays ready, and its run lock is freed. The gate counts the items other runs drive now: their places under the WIP limit, and their systems — a board starts one run per click. Requires `gcf-aif-ext` 0.6.
+
 0.6.1 is a fix release, to update together with core 0.5.3. The run lock `.gcf-session/runs/<id>.lock` is created exclusively, and a lock left by a dead run is taken over; while it is live, the gate refuses the item to another run and the core refuses any move on it, `/gcf-run` on main included. A session whose log cannot open ends as an error and releases its claim.
 
 0.6.0 adds `ai-factory gcf-harness run` (a batch at once, a worktree and an agent session per item, then the integrator) and the `--worktree` mode of `/gcf-run`, whose session ritual now integrates the verified branches a dead run left. It requires `gcf-aif-ext` 0.5.0 (`gcf worktree`, `gcf integrate`, `gcf verify`) — update both together and run `ai-factory gcf init`. The DoD of `/gcf-run` is `ai-factory gcf verify <id>`, and the item's `live:` delta is written before it.

package/commands/harness.js

@@ -3,11 +3,11 @@
 // same decision as gcf hooks-install for git hooks). Idempotent by marker comment.
 // `ai-factory gcf-harness gate <ids…>` — the /gcf-run gate as code (Harness-PRD §4.3).
 import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { run, cliCore, DEFAULT_AGENT } from './run.js';
+import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MARKER = 'gcf-readset-guard';
@@ -27,7 +27,9 @@ function itemProblem(id, item, report) {
     return `${id} is ${item.status} — only ready items are driven`;
   }
 
-  if (item.running) return `${id} is driven by another harness run — wait until it ends`;
+  // The session a run started for this very item gates it too: its own run is not "another".
+  if (item.running && process.env.GCF_RUN_ITEM !== id)
+    return `${id} is driven by another harness run — wait until it ends`;
 
   // A child of a feature paused after a death does not start: the decision may kill it.
   const parent = item.parent ? report.items.find((p) => p.id === item.parent) : null;
@@ -49,20 +51,26 @@ function itemProblem(id, item, report) {
   return null;
 }
 
-/** Why the batch as a whole may not go, or null. */
-function batchProblem(items, wip) {
+/**
+ * Why the batch as a whole may not go, or null. `elsewhere` are the items other runs drive now:
+ * a board starts one run per click, so each run sees the others only through their locks.
+ */
+function batchProblem(items, wip, elsewhere = []) {
   // Only an item that ends waiting for a verdict takes a WIP place; `wip.over` is false at
-  // count === limit, and this run adds every such item of the batch.
+  // count === limit, and this run adds every such item of the batch — and of the other runs.
   const waiting = items.filter((i) => i.gate === 'verdict').length;
-  if (waiting && wip.count + waiting > wip.limit) {
+  const coming = elsewhere.filter((i) => i.gate === 'verdict').length;
+  if (waiting && wip.count + coming + waiting > wip.limit) {
+    const others = coming ? ` + ${coming} in other runs` : '';
+
     return (
-      `WIP: ${wip.count} awaiting a verdict + ${waiting} in this run exceeds the limit of ` +
-      `${wip.limit} — playtest first`
+      `WIP: ${wip.count} awaiting a verdict${others} + ${waiting} in this run exceeds the ` +
+      `limit of ${wip.limit} — playtest first`
     );
   }
 
   for (let i = 0; i < items.length; i++) {
-    for (const other of items.slice(i + 1)) {
+    for (const other of [...items.slice(i + 1), ...elsewhere]) {
       const shared = items[i].system.filter((s) => other.system.includes(s));
       // `parallel: ok` on both is the operator's explicit permission (Methodology §7).
       const allowed = items[i].parallel === 'ok' && other.parallel === 'ok';
@@ -79,6 +87,26 @@ function batchProblem(items, wip) {
 
 const verdict = (reason) => ({ pass: !reason, reason: reason ?? '' });
 
+const rank = (i) => i.priority ?? Number.MAX_SAFE_INTEGER;
+
+/**
+ * The ready items that can run together now, up to `count`, by priority: each is taken while
+ * the batch with it still passes the gate — a dependency not played, a shared subsystem, a full
+ * WIP leave it out. The gate decides; a board only shows and runs the answer.
+ */
+export function nextBatch(report, count) {
+  const batch = [];
+  const ready = (report.items ?? [])
+    .filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
+    .sort((a, b) => rank(a) - rank(b));
+  for (const i of ready) {
+    if (batch.length >= count) break;
+    if (gate(report, [...batch, i.id]).pass) batch.push(i.id);
+  }
+
+  return batch;
+}
+
 /**
  * Decides whether the work items may enter the paid stages, from one `gcf audit --json` report.
  * Pure: the report is the whole input, so every rule has a test and no model compares numbers.
@@ -104,6 +132,7 @@ export function gate(report, ids) {
     batchProblem(
       ids.map((id) => byId.get(id)),
       report.wip,
+      report.items.filter((c) => c.running && !ids.includes(c.id)),
     ),
   );
 }
@@ -249,8 +278,83 @@ export function register(program) {
       'the agent command; it gets "/gcf-run <id> --worktree"',
       process.env.GCF_RUN_AGENT ?? DEFAULT_AGENT,
     )
+    .option(
+      '--timeout <minutes>',
+      'stop a session that runs longer; its item stays ready',
+      String(DEFAULT_TIMEOUT_MIN),
+    )
+    .option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
     .option('--json', 'machine output')
     .action(runItems);
+
+  harness
+    .command('next [count]')
+    .description('The ready items that can run together now, by priority (the gate decides)')
+    .option('--json', 'machine output: a list of ids')
+    .action((count, o) => {
+      const ids = nextBatch(auditReport(), Math.max(1, Number(count ?? 1) || 1));
+      console.log(o.json ? JSON.stringify(ids) : ids.join('\n') || 'nothing can run now');
+    });
+  harness
+    .command('stop <id>')
+    .description('Stop the run that drives an item, with every session it started; it stays ready')
+    .action((id) => console.log(stopRun(process.cwd(), id)));
+}
+
+const WIN = process.platform === 'win32';
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A run lock: `<run pid>\n<item>\n<session pid>\n` once the session started, the run pid alone
+ * before. Null when its run is gone.
+ */
+function lockOf(file) {
+  try {
+    const [run, item, session] = readFileSync(file, 'utf8').split('\n');
+    if (!alive(Number(run))) return null;
+
+    return { run: Number(run), item: item || null, session: Number(session) || null };
+  } catch {
+    return null;
+  }
+}
+
+/** Kill a process and everything under it: a tree on Windows, its own group elsewhere. */
+function killTree(pid, group) {
+  if (WIN) spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+  else {
+    try {
+      process.kill(group ? -pid : pid, group ? 'SIGKILL' : 'SIGTERM');
+    } catch {
+      // Gone already.
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+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);
+  if (lock && lock.session && alive(lock.session)) killTree(lock.session, true);
+  else if (lock) killTree(lock.run, false);
+  core(['release', id]);
+
+  return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;
 }
 
 /** The run report a human reads, then the playtest sheet of what now waits for play. */
@@ -273,9 +377,15 @@ const failed = (r) =>
 
 async function runItems(ids, opts) {
   try {
+    const minutes = Number(opts.timeout);
+    if (!(minutes > 0)) throw new Error('--timeout is a number of minutes above 0');
+    if (opts.mode && !['worktree', 'main'].includes(opts.mode))
+      throw new Error('--mode is worktree or main');
     const r = await run(process.cwd(), [...new Set(ids)], {
       agent: opts.agent,
       gate: (batch) => gate(auditReport(), batch),
+      timeoutMs: minutes * 60_000,
+      mode: opts.mode,
     });
     if (opts.json) console.log(JSON.stringify(r, null, 2));
     else printRun(r);

package/commands/run.js

@@ -3,7 +3,7 @@
 // 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 } from 'node:fs';
+import { existsSync, utimesSync, writeFileSync } from 'node:fs';
 import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
@@ -31,16 +31,93 @@ function json(res, what) {
   }
 }
 
-/** One agent session in the item's worktree; resolves with its exit code. */
-function startAgent(agent, id, dir, fd) {
+// The core's rule for `item new`: a leading hyphen would read as a flag.
+const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
+
+/**
+ * The agent command of one item: its `model:` and `effort:` become `--model` and `--effort`,
+ * the flags of `claude`. The command goes through a shell, and an item file can be edited by
+ * hand: a value that is not one plain word is refused.
+ */
+export function agentFor(agent, item) {
+  const flags = [];
+  for (const k of ['model', 'effort']) {
+    const v = item?.[k];
+    if (v === null || v === undefined) continue;
+    if (!RUN_WORD.test(String(v))) throw new Error(`${k}: ${v} is not one plain word`);
+    flags.push(`--${k} ${v}`);
+  }
+
+  return [agent, ...flags].join(' ');
+}
+
+const WIN = process.platform === 'win32';
+
+/**
+ * Stop a session and everything it started: the shell, the agent, its tools. Windows has no
+ * process groups to signal, `taskkill /T` walks the tree; elsewhere the session leads its own
+ * group (`detached`), and the group gets the signal.
+ */
+function killTree(child) {
+  if (WIN) spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+  else {
+    try {
+      process.kill(-child.pid, 'SIGKILL');
+    } catch {
+      // Gone already.
+    }
+  }
+}
+
+// The sessions this run has going: a stop (`gcf-harness stop`) takes them down with the run.
+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.
+ * Returns the unhook.
+ */
+function stopWithSessions() {
+  const stop = () => {
+    for (const c of sessions) killTree(c);
+    process.exit(143);
+  };
+
+  process.once('SIGTERM', stop);
+
+  return () => process.removeListener('SIGTERM', stop);
+}
+
+/**
+ * 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.
+ */
+function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
   return new Promise((resolve) => {
-    const child = spawn(`${agent} "/gcf-run ${id} --worktree"`, {
+    const child = spawn(`${agent} "${prompt}"`, {
       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],
     });
-    child.on('error', () => resolve(-1));
-    child.on('exit', (code) => resolve(code ?? -1));
+    sessions.add(child);
+    if (child.pid) onSpawn?.(child.pid);
+    const timer = setTimeout(() => {
+      killTree(child);
+      resolve('timeout');
+    }, timeoutMs);
+    const end = (code) => {
+      sessions.delete(child);
+      clearTimeout(timer);
+      resolve(code);
+    };
+
+    child.on('error', () => end(-1));
+    child.on('exit', (code) => end(code ?? -1));
   });
 }
 
@@ -136,8 +213,11 @@ function verified(dir, id) {
   return (res.stdout ?? '').split('\n').some((v) => v.trim() === id);
 }
 
-/** The worktree of each item, claimed for this run; an item that cannot start is an error. */
-async function prepare(ids, core, logs) {
+/**
+ * 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.
+ */
+async function prepare(ids, core, logs, agentOf) {
   const ready = [];
   const failed = [];
   for (const id of ids) {
@@ -148,9 +228,10 @@ async function prepare(ids, core, logs) {
     }
 
     try {
+      const agent = agentOf(id);
       const wt = json(await core(['worktree', id, '--json']), `worktree ${id}`);
       if (wt.sync) throw new Error(wt.sync);
-      ready.push({ id, dir: wt.path, release });
+      ready.push({ id, dir: wt.path, agent, release });
     } catch (e) {
       await release();
       failed.push({ id, result: 'error', error: e.message });
@@ -160,21 +241,44 @@ async function prepare(ids, core, logs) {
   return { ready, failed };
 }
 
-/** One session per item, its output in `.gcf-session/runs/<id>.log`. */
-async function session(r, agent, logs) {
+/**
+ * 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) {
+  /** @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`);
+  // 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;
   try {
     log = await open(path.join(logs, `${r.id}.log`), 'a');
+    const opts = { fd: log.fd, timeoutMs, id: r.id, onSpawn };
 
-    return { ...r, code: await startAgent(agent, r.id, r.dir, log.fd) };
+    return { ...r, code: await startAgent(r.agent, prompt, r.dir, opts) };
   } catch (e) {
     return { ...r, code: null, error: e.message };
   } finally {
+    if (keep) clearInterval(keep);
     await log?.close();
     await r.release();
   }
 }
 
+/** Refresh a file's time, when it is still there. */
+function touch(file) {
+  try {
+    const now = new Date();
+    utimesSync(file, now, now);
+  } catch {
+    // Released meanwhile.
+  }
+}
+
 /**
  * A run that asked to block is recorded on main. Asked after its branch was verified, the
  * block wins: an empty commit takes the trailer off the tip, so no integrate merges it.
@@ -197,13 +301,14 @@ async function recordBlock(r, outcome, core) {
 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)
+  if (!done) {
+    const why = run.code === 'timeout' ? 'the session timed out' : `agent exit ${run.code}`;
+
     return {
       id: run.id,
-      result:
-        `no result (agent exit ${run.code}): ${run.id} stays ready, a rerun resumes its ` +
-        'worktree',
+      result: `no result (${why}): ${run.id} stays ready, a rerun resumes its worktree`,
     };
+  }
 
   return {
     ...done,
@@ -211,31 +316,133 @@ function resultOf(run, integrated) {
   };
 }
 
+export const DEFAULT_TIMEOUT_MIN = 120;
+
+// The move an item's status shows after a run on main: the agent recorded it itself.
+const MOVE_OF = {
+  'awaiting-verdict': 'submit',
+  'awaiting-decision': 'submit',
+  unplayed: 'close',
+  blocked: 'block',
+};
+
+/** What a run on main left: the item's move read from its status, or why there is none. */
+async function mainResult(core, r) {
+  const after = json(await core(['board', '--json']), 'board').items?.find((i) => i.id === r.id);
+  if (r.error) return { id: r.id, result: 'error', error: r.error };
+  // An item that ended left the board: its run closed it.
+  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` };
+}
+
+// The lock of the main checkout itself: one run works there at a time. Not a slug, so no item.
+export const MAIN_RUN = '.main-run';
+
 /**
- * Pick up orphans, gate the batch, run every item in its worktree at once, record each block
- * on main, integrate the verified branches. `gate(ids)` answers `{pass, reason}`.
+ * `run_mode: main` (Methodology §7): one item after another in the main checkout, where the
+ * editor the agent works through lives. The agent records each item's move itself, so the item
+ * 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 }) {
+  const releaseMain = await claim(logs, MAIN_RUN);
+  if (!releaseMain)
+    return ids.map((id) => ({
+      id,
+      result: 'error',
+      error: 'another run works in the main checkout: wait for it, or stop it',
+    }));
+
+  const items = [];
+  try {
+    for (const id of ids)
+      items.push(await mainItem(projectDir, id, { core, logs, agentOf, timeoutMs }));
+  } finally {
+    await releaseMain();
+  }
+
+  return items;
+}
+
+/** One item of a main run: marked, its session, its mark cleared, its result read. */
+async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs }) {
+  let r;
+  try {
+    const claimed = await core(['claim', id]);
+    if (!claimed.ok) throw new Error((claimed.err || claimed.out).trim());
+    const none = async () => {};
+
+    const s = { id, dir: projectDir, agent: agentOf(id), release: none, main: true };
+    r = await session(s, logs, timeoutMs);
+  } catch (e) {
+    r = { id, error: e.message };
+  }
+
+  await core(['release', id]);
+
+  return mainResult(core, r);
+}
+
+/** 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)));
+  const items = [...failed];
+  for (const r of runs) {
+    const outcome = await outcomeOf(r.dir);
+    if (outcome?.block) items.push(await recordBlock(r, outcome, core));
+  }
+
+  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));
+
+  return items;
+}
+
+/**
+ * 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.
  */
 export async function run(
   projectDir,
   ids,
-  { core = cliCore(projectDir), agent = DEFAULT_AGENT, gate },
+  {
+    core = cliCore(projectDir),
+    agent = DEFAULT_AGENT,
+    gate,
+    timeoutMs = DEFAULT_TIMEOUT_MIN * 60_000,
+    mode = undefined,
+  },
 ) {
+  // 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 { ready, failed } = await prepare(ids, core, logs);
-  const runs = await Promise.all(ready.map((r) => session(r, agent, logs)));
-  const items = [...failed];
-  for (const r of runs) {
-    const outcome = await outcomeOf(r.dir);
-    if (outcome?.block) items.push(await recordBlock(r, outcome, core));
-  }
-
-  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));
+  const board = json(await core(['board', '--json']), 'board');
+  const runMode = mode ?? board.run_mode ?? 'worktree';
+  const agentOf = (id) =>
+    agentFor(
+      agent,
+      (board.items ?? []).find((i) => i.id === id),
+    );
+  const ctx = { core, logs, agentOf, timeoutMs };
+  const unhook = stopWithSessions();
+  try {
+    const items =
+      runMode === 'main' ? await runMain(projectDir, ids, ctx) : await runWorktrees(ids, ctx);
 
-  return { orphans, items };
+    return { orphans, mode: runMode, items };
+  } finally {
+    unhook();
+  }
 }

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

package/hooks/readset-guard.js

@@ -6,7 +6,7 @@
 // are never touched, and neither is a search that cannot reach gcf/ — the project's own
 // code stays freely greppable. Honest limit: Bash `cat` bypasses this; it is a discipline
 // tool for a solo developer, not a security perimeter.
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, utimesSync } from 'node:fs';
 import path from 'node:path';
 
 function readStdin() {
@@ -115,11 +115,34 @@ function readManifest(projectDir) {
   }
 }
 
+// The core's SESSION_TTL_MS (gcf-aif-ext lib/session-mark.js): a mark older than this is dead.
+const SESSION_TTL_MS = 120 * 60_000;
+
+/**
+ * Keep the running marks of this checkout fresh (`gcf claim`): an agent reading files is a
+ * session at work, even through a long stage with no gcf command. A mark already expired stays
+ * expired: a session that stopped is not revived. Best effort, never in the way of the read.
+ * shortcut: it refreshes every live mark of the checkout, not only this session's; one agent
+ * works a main checkout at a time, so that is the same mark — key marks by session when two do.
+ */
+export function keepSessionsAlive(projectDir, now = Date.now()) {
+  const runs = path.join(projectDir, '.gcf-session', 'runs');
+  try {
+    for (const name of readdirSync(runs).filter((n) => n.endsWith('.session'))) {
+      const file = path.join(runs, name);
+      if (now - statSync(file).mtimeMs < SESSION_TTL_MS) utimesSync(file, now / 1000, now / 1000);
+    }
+  } catch {
+    // No runs directory, or a mark released meanwhile.
+  }
+}
+
 // 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('readset-guard.js')) {
   const input = readStdin();
   const projectDir = input?.cwd ?? process.cwd();
+  keepSessionsAlive(projectDir);
   const verdict = decide(input, projectDir, readManifest(projectDir));
   if (!verdict.allow) {
     console.error(`gcf readset-guard: ${verdict.reason}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version)\""
   },
   "peerDependencies": {
-    "gcf-aif-ext": "^0.5.3"
+    "gcf-aif-ext": "^0.7.0"
   },
   "files": [
     "extension.json",

package/skills/gcf-run/SKILL.md

@@ -8,6 +8,8 @@ mode: pipeline
 purpose:
 - drive a work item through gate, readset, plan, implement and its DoD with the stop rules checked before each paid stage
 - end every item in a state the core records: `submit` (waits for the human), `close` (gate auto, done) or `block` (needs the human)
+- outside `--worktree`, mark each item running after its gate passes: `ai-factory gcf claim <id>`; a move clears the mark, and an item left without one gets `ai-factory gcf release <id>`
+- a claimed item takes only its session's moves: run `submit`, `close` and `block` on it with `--claimed`
 
 inputs:
 - 1 or more work item or design unit ids; a batch shares one build and one playtest list