gcf-harness-aif-ext 0.6.0 → 0.7.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.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.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
 - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
 - AI Factory 2.x, Node.js ≥ 22.14
 
@@ -47,6 +47,10 @@ 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.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.
 
 0.4.1 is a patch release. `/gcf-run` now commits the implementation first, then flips the card to `built` in a second commit, with `built_at` set to the implementation commit's hash. Update the core to 0.3.1 together with the harness: without it, an audit run before a verdict makes the pre-commit gate refuse that verdict.

package/commands/harness.js

@@ -7,7 +7,7 @@ import { existsSync } 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 } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MARKER = 'gcf-readset-guard';
@@ -27,6 +27,8 @@ 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`;
+
   // 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;
   if (parent?.status === 'awaiting-decision') {
@@ -47,20 +49,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';
@@ -102,6 +110,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)),
     ),
   );
 }
@@ -247,6 +256,11 @@ 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('--json', 'machine output')
     .action(runItems);
 }
@@ -271,9 +285,12 @@ 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');
     const r = await run(process.cwd(), [...new Set(ids)], {
       agent: opts.agent,
       gate: (batch) => gate(auditReport(), batch),
+      timeoutMs: minutes * 60_000,
     });
     if (opts.json) console.log(JSON.stringify(r, null, 2));
     else printRun(r);

package/commands/run.js

@@ -4,7 +4,7 @@
 // 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 { mkdir, open, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 export const DEFAULT_AGENT = 'claude -p';
@@ -31,16 +31,69 @@ 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.
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+function startAgent(agent, id, dir, { fd, timeoutMs }) {
   return new Promise((resolve) => {
     const child = spawn(`${agent} "/gcf-run ${id} --worktree"`, {
       cwd: dir,
       shell: true,
+      detached: !WIN,
+      windowsHide: true,
       stdio: ['ignore', fd, fd],
     });
-    child.on('error', () => resolve(-1));
-    child.on('exit', (code) => resolve(code ?? -1));
+    const timer = setTimeout(() => {
+      killTree(child);
+      resolve('timeout');
+    }, timeoutMs);
+    const end = (code) => {
+      clearTimeout(timer);
+      resolve(code);
+    };
+
+    child.on('error', () => end(-1));
+    child.on('exit', (code) => end(code ?? -1));
   });
 }
 
@@ -57,23 +110,73 @@ async function outcomeOf(dir) {
   }
 }
 
+/** Whether a pid is a live process; EPERM is alive under another user. */
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
 /**
  * One harness run per item at a time: `.gcf-session/runs/<id>.lock` holds the pid of the run
- * that drives it. A lock whose process is gone is taken over. Returns the release, or null.
+ * that drives it, created exclusively. A lock whose process is gone is taken over; the core
+ * refuses moves on the item while the lock is live. Returns the release, or null.
  */
 async function claim(logs, id) {
   const file = path.join(logs, `${id}.lock`);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    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());
+    if (pid === process.pid) return () => rm(file, { force: true });
+    if (!(await dead(file, pid))) return null;
+    await clearDead(file, text);
+  }
+
+  return null;
+}
+
+/** Create the lock with this pid, or false when it exists. */
+async function create(file) {
   try {
-    const pid = Number((await readFile(file, 'utf8')).trim());
-    process.kill(pid, 0);
-    if (pid !== process.pid) return null;
-  } catch {
-    // no lock, or its process is gone
+    await writeFile(file, `${process.pid}\n`, { flag: 'wx' });
+
+    return true;
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+
+    return false;
   }
+}
 
-  await writeFile(file, `${process.pid}\n`);
+/** A lock whose pid is gone, or that never got one and is old: its creator died writing it. */
+async function dead(file, pid) {
+  if (Number.isInteger(pid) && pid > 0) return !alive(pid);
+  const age = await stat(file).then(
+    (s) => Date.now() - s.mtimeMs,
+    () => 0,
+  );
 
-  return () => rm(file, { force: true });
+  return age > 10000;
+}
+
+/**
+ * Remove a dead lock under `<lock>.break`, as the core's main lock does: two runs that judged
+ * the same lock dead cannot both remove it, so neither deletes the other's fresh lock.
+ */
+async function clearDead(file, text) {
+  const breaker = `${file}.break`;
+  if (!(await create(breaker))) return;
+  try {
+    if ((await readFile(file, 'utf8').catch(() => null)) === text) await rm(file, { force: true });
+  } finally {
+    await rm(breaker, { force: true });
+  }
 }
 
 /** Whether the tip of the worktree's branch carries `GCF-Verified: <id>`. */
@@ -86,8 +189,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) {
@@ -98,9 +204,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 });
@@ -111,12 +218,17 @@ async function prepare(ids, core, logs) {
 }
 
 /** One session per item, its output in `.gcf-session/runs/<id>.log`. */
-async function session(r, agent, logs) {
-  const log = await open(path.join(logs, `${r.id}.log`), 'a');
+async function session(r, logs, timeoutMs) {
+  /** @type {import('node:fs/promises').FileHandle | null} */
+  let log = null;
   try {
-    return { ...r, code: await startAgent(agent, r.id, r.dir, log.fd) };
+    log = await open(path.join(logs, `${r.id}.log`), 'a');
+
+    return { ...r, code: await startAgent(r.agent, r.id, r.dir, { fd: log.fd, timeoutMs }) };
+  } catch (e) {
+    return { ...r, code: null, error: e.message };
   } finally {
-    await log.close();
+    await log?.close();
     await r.release();
   }
 }
@@ -142,13 +254,15 @@ async function recordBlock(r, outcome, core) {
 /** 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)
+  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 (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,
@@ -156,14 +270,22 @@ function resultOf(run, integrated) {
   };
 }
 
+export const DEFAULT_TIMEOUT_MIN = 120;
+
 /**
  * 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}`.
+ * 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.
  */
 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,
+  },
 ) {
   const orphans = json(await core(['integrate', '--json']), 'integrate');
   const passed = gate(ids);
@@ -171,8 +293,14 @@ export async function run(
 
   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 onBoard = json(await core(['board', '--json']), 'board').items ?? [];
+  const agentOf = (id) =>
+    agentFor(
+      agent,
+      onBoard.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);

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.0",
+  "version": "0.7.0",
   "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.6.0",
+  "version": "0.7.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.0"
+    "gcf-aif-ext": "^0.6.0"
   },
   "files": [
     "extension.json",