gcf-harness-aif-ext 0.8.2 → 0.8.4

package/README.md

@@ -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 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.
+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 *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — 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
 

package/commands/harness.js

@@ -4,7 +4,7 @@
 // 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, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -212,8 +212,16 @@ function registerGuard(settings, command) {
 }
 
 // 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 *)'];
+// denied. The engine's own tools (an editor's MCP server) are the project's to add. On Windows
+// the agent runs commands through its PowerShell tool, which Bash rules do not cover.
+const AGENT_ALLOW = [
+  'Edit',
+  'Write',
+  'Bash(git *)',
+  'Bash(ai-factory *)',
+  'PowerShell(git *)',
+  'PowerShell(ai-factory *)',
+];
 
 /** Adds the rules the settings do not hold yet; returns the ones added. */
 function allowAgent(settings) {
@@ -401,7 +409,9 @@ async function runItems(ids, opts) {
     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)], {
+    // The true-case path: Claude Code trusts a folder by its exact path, and a shell or a board
+    // may hand over c: for C:, which turns off every allow rule of the project.
+    const r = await run(realpathSync.native(process.cwd()), [...new Set(ids)], {
       agent: opts.agent,
       gate: (batch) => gate(auditReport(), batch),
       timeoutMs: minutes * 60_000,

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, utimesSync, writeFileSync } from 'node:fs';
+import { existsSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
@@ -154,11 +154,18 @@ 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.
+  for (let attempt = 0; attempt < 3; 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());
+    // Released meanwhile: the next create may take it, and that try is not spent.
+    if (text === null) {
+      attempt--;
+      continue;
+    }
+
+    // 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 +204,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 {
@@ -215,20 +230,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}`);
@@ -287,8 +332,7 @@ 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 });
+  unverify(r);
   const b = await core(['block', r.id, '--reason', reason]);
 
   return {
@@ -299,6 +343,28 @@ async function recordBlock(r, outcome, core) {
   };
 }
 
+/**
+ * An empty commit takes the trailer off the branch tip: no integrate merges it. `--only` keeps
+ * what a killed agent staged out of it, and a killed git leaves an index.lock to clear first.
+ */
+function unverify(r) {
+  if (!verified(r.dir, r.id)) return null;
+  const args = ['commit', '-q', '--no-verify', '--allow-empty', '--only', '-m'];
+  const commit = () =>
+    spawnSync('git', [...args, `gcf(unverified): ${r.id}`], { cwd: r.dir, encoding: 'utf8' });
+  if (commit().status === 0) return null;
+  const gitDir = spawnSync('git', ['rev-parse', '--absolute-git-dir'], {
+    cwd: r.dir,
+    encoding: 'utf8',
+  }).stdout.trim();
+  if (gitDir) rmSync(path.join(gitDir, 'index.lock'), { force: true });
+  const again = commit();
+
+  // 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 again.status === 0 ? null : `could not take its trailer off: ${again.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);
@@ -389,14 +455,20 @@ async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs }) {
   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);
+/** Every claimed item in its worktree at once; blocks recorded on main, verified ones merged. */
+async function runWorktrees(claims, { core, logs, agentOf, timeoutMs }) {
+  const { ready, failed } = await prepare(claims, core, 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));
+    // 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');
@@ -425,13 +497,22 @@ export async function run(
   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,
@@ -441,7 +522,7 @@ export async function run(
   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.2",
+  "version": "0.8.4",
   "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.2",
+  "version": "0.8.4",
   "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 });
   }