gcf-harness-aif-ext 0.7.0 → 0.8.1

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.6.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
+- [`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
 
@@ -33,7 +33,7 @@ This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-h
 ai-factory gcf-harness init    # per project: .claude/settings.json + .gitignore
 ```
 
-It is **per project**, not global — run it again in every game repository: it adds the readset-guard `PreToolUse` entry to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
+It is **per project**, not global — run it again in every game repository: it adds the readset-guard `PreToolUse` entry to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)` — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
 
 ## Upgrade
 
@@ -47,6 +47,14 @@ 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.

package/commands/harness.js

@@ -1,13 +1,14 @@
 // `ai-factory gcf-harness init` — registers the readset-guard PreToolUse hook in the
 // project's .claude/settings.json (the AIF manifest cannot install Claude Code hooks —
-// same decision as gcf hooks-install for git hooks). Idempotent by marker comment.
+// same decision as gcf hooks-install for git hooks). Idempotent by marker comment. It also
+// allows what a headless agent run needs (AGENT_ALLOW).
 // `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, DEFAULT_TIMEOUT_MIN } 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 +28,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;
@@ -85,6 +88,26 @@ function batchProblem(items, wip, elsewhere = []) {
 
 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.
@@ -188,6 +211,20 @@ function registerGuard(settings, command) {
   return stale.length ? 'repointed' : null;
 }
 
+// What a headless `claude -p` run needs at least: it cannot ask, so anything not allowed is
+// denied. The engine's own tools (an editor's MCP server) are the project's to add.
+const AGENT_ALLOW = ['Edit', 'Write', 'Bash(git *)', 'Bash(ai-factory *)'];
+
+/** Adds the rules the settings do not hold yet; returns the ones added. */
+function allowAgent(settings) {
+  settings.permissions ??= {};
+  settings.permissions.allow ??= [];
+  const added = AGENT_ALLOW.filter((r) => !settings.permissions.allow.includes(r));
+  settings.permissions.allow.push(...added);
+
+  return added;
+}
+
 /**
  * Only an active rule ignoring the root .gcf-session/ counts — not a comment or a pattern
  * for some other directory that happens to contain the name.
@@ -213,14 +250,17 @@ async function init(program) {
   const guard = path.join(EXT_ROOT, 'hooks', 'readset-guard.js').replaceAll('\\', '/');
   const settings = await readSettings(settingsFile);
   const change = registerGuard(settings, `node "${guard}" # ${MARKER}`);
-  if (change) {
+  const allowed = allowAgent(settings);
+  if (change || allowed.length) {
     await mkdir(path.dirname(settingsFile), { recursive: true });
     await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
-    console.log(`readset-guard ${change} → ${settingsFile}`);
-  } else {
-    console.log('readset-guard already registered');
   }
 
+  console.log(
+    change ? `readset-guard ${change} → ${settingsFile}` : 'readset-guard already registered',
+  );
+  if (allowed.length) console.log(`agent runs may now: ${allowed.join(', ')}`);
+
   await ignoreSession(projectDir);
 }
 
@@ -239,7 +279,9 @@ export function register(program) {
 
   harness
     .command('init')
-    .description('Initialize the harness in this project: readset-guard hook (idempotent)')
+    .description(
+      'Initialize the harness in this project: readset-guard hook, agent permissions (idempotent)',
+    )
     .action(() => init(program));
 
   harness
@@ -261,8 +303,78 @@ export function register(program) {
       '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. */
@@ -287,10 +399,13 @@ 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';
 
@@ -69,25 +69,49 @@ function killTree(child) {
   }
 }
 
+// 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 in the item's worktree; 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.
+ * 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, id, dir, { fd, timeoutMs }) {
+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],
     });
+    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);
     };
@@ -217,22 +241,44 @@ async function prepare(ids, core, logs, agentOf) {
   return { ready, failed };
 }
 
-/** One session per item, its output in `.gcf-session/runs/<id>.log`. */
+/**
+ * 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(r.agent, r.id, r.dir, { fd: log.fd, timeoutMs }) };
+    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.
@@ -272,10 +318,95 @@ 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';
+
+/**
+ * `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 every item in its worktree at once, record each block
- * on main, integrate the verified branches. `gate(ids)` answers `{pass, reason}`; a session
- * past `timeoutMs` is stopped with all it started, and its item stays ready.
+ * 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,
@@ -285,30 +416,33 @@ export async function run(
     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 onBoard = json(await core(['board', '--json']), 'board').items ?? [];
+  const board = json(await core(['board', '--json']), 'board');
+  const runMode = mode ?? board.run_mode ?? 'worktree';
   const agentOf = (id) =>
     agentFor(
       agent,
-      onBoard.find((i) => i.id === id),
+      (board.items ?? []).find((i) => i.id === id),
     );
-  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));
+  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.7.0",
+  "version": "0.8.1",
   "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.7.0",
+  "version": "0.8.1",
   "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.6.0"
+    "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