gcf-harness-aif-ext 0.8.9 → 0.9.1

package/README.md

@@ -47,6 +47,19 @@ 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.9.1 is a fix release:
+- A stopped session reads as `no result (stopped)`, and its kept record as `ended: stopped`: before, the kill's exit code (`agent exit 1` on Windows).
+- `gcf-harness stop <id>` never kills the run: a stop before the item's session starts (or between two sessions of a handoff) leaves `.gcf-session/runs/<id>.stop`, and that session is stopped as it starts. Before, a stop then killed the whole run with the other items of its batch. A run hung before its first session (in its worktree setup) is not stopped. On main, a stop marks the item too once the run has reached it. Known limit: a stop in the moment between a worktree run's claim of the item and its clearing of an old mark is lost.
+- A stop that comes while the session starts no longer misses it.
+
+0.9.0, to update together with core 0.7.6:
+- The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
+- A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.
+- Context handoff: past `context_handoff_pct` (60 by default) of the window, or at a compaction, the run flags the session; the handoff guard then denies every call of the main agent but the plan's read and edit with the instruction to write `## Handoff` into the plan and end. The run starts a fresh session with `/gcf-run <id> --handoff`, which goes on from the plan: the ticked tasks stay done. A session that works on past its flag is stopped; after 3 handoffs in a row the item is blocked with `context handoff limit`. The window is `context_window`, else the one a result of the same model reported (`.gcf-session/runs/windows.json`); with neither, the first session of a model runs without a handoff and says so. The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
+- `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
+- The readset-guard reads the manifest of the directory the session started in (`CLAUDE_PROJECT_DIR`): an agent's `cd` no longer lifts the readset.
+- `/gcf-run` writes a plan task's code through aif-implement, so the plan ticks show the item's progress, and answers aif-implement's questions itself: no commit, stash or merge.
+
 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.

package/commands/activity.js

@@ -38,7 +38,8 @@ 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}`);
+export 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`. */
@@ -106,7 +107,12 @@ function limitIn(text, whole = true) {
  * 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}}}
+ * The main agent's turns also carry `context`, the tokens its window holds (a subagent's turns,
+ * `parent_tool_use_id` set, fill a window of their own); the init names the `model`, the result
+ * the `windows` of its models, and a compaction says `compacted`.
+ * @returns {{lines: string[], cost?: Cost, session_id?: string, limit?: {resets: string | null},
+ *   context?: number, turn?: string, model?: string, windows?: Record<string, number>,
+ *   compacted?: boolean}}
  */
 export function activity(line, now = new Date()) {
   let e;
@@ -120,8 +126,8 @@ export function activity(line, now = new Date()) {
 
   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 === 'system') return system(e, at);
+  if (e.type === 'assistant') return { ...said(content, at), ...contextOf(e) };
   if (e.type === 'user')
     return {
       lines: content
@@ -133,11 +139,33 @@ export function activity(line, now = new Date()) {
   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: [] };
+/**
+ * A system event: the init names the session and its model; a compaction is a line, the
+ * agent's context summarized; the rest (hooks, thinking) give nothing.
+ */
+function system(e, at) {
+  if (e.subtype === 'compact_boundary')
+    return { lines: [`${at} compacted: the agent's context was summarized`], compacted: true };
+  if (e.subtype !== 'init' || typeof e.session_id !== 'string') return { lines: [] };
+
+  return {
+    lines: [],
+    session_id: e.session_id,
+    ...(typeof e.model === 'string' ? { model: e.model } : {}),
+  };
+}
+
+/** The tokens a main-agent turn holds in its window: its input, read from cache or written. */
+function contextOf(e) {
+  const u = e.message?.usage;
+  if (e.parent_tool_use_id != null || !u) return {};
+  const tokens =
+    Number(u.input_tokens ?? 0) +
+    Number(u.cache_read_input_tokens ?? 0) +
+    Number(u.cache_creation_input_tokens ?? 0);
+
+  return { context: tokens, ...(e.message.id ? { turn: String(e.message.id) } : {}) };
+}
 
 /** An assistant turn: its tool calls and its text, which may be the usage-limit message. */
 function said(content, at) {
@@ -162,9 +190,15 @@ function ended(e, at) {
   // An error result counts the message anywhere in it; any other only as the whole text.
   const limit = limitIn(e.result, !e.is_error);
 
+  // The window of each model the session used: its subagents may run on another.
+  const windows = Object.entries(e.modelUsage ?? {})
+    .map(([m, u]) => /** @type {[string, number]} */ ([m, Number(u?.contextWindow)]))
+    .filter(([, n]) => n > 0);
+
   return {
     lines: [...text, `${at} ${summary(e, cost, Boolean(limit.limit))}`],
     cost,
     ...limit,
+    ...(windows.length ? { windows: Object.fromEntries(windows) } : {}),
   };
 }

package/commands/harness.js

@@ -4,11 +4,11 @@
 // 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, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, writeFileSync } 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, MAIN_RUN } from './run.js';
+import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN, stopOf } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MARKER = 'gcf-readset-guard';
@@ -214,6 +214,9 @@ 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. On Windows
 // the agent runs commands through its PowerShell tool, which Bash rules do not cover.
+// The harness's own agent runs with bypassPermissions and the project's deny rules (run.js
+// runFlags), where allow rules do nothing: these serve an agent named with `--agent` and a
+// manual session. shortcut: the list stays this short; grow the deny groups, not this.
 const AGENT_ALLOW = [
   'Edit',
   'Write',
@@ -326,7 +329,7 @@ export function register(program) {
     });
   harness
     .command('stop <id>')
-    .description('Stop the run that drives an item, with every session it started; it stays ready')
+    .description('Stop the session that works an item; the run goes on, the item stays ready')
     .action((id) => console.log(stopRun(process.cwd(), id)));
 }
 
@@ -357,12 +360,12 @@ function lockOf(file) {
   }
 }
 
-/** Kill a process and everything under it: a tree on Windows, its own group elsewhere. */
-function killTree(pid, group) {
+/** Kill a session and everything under it: a tree on Windows, its own group elsewhere. */
+function killTree(pid) {
   if (WIN) spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
   else {
     try {
-      process.kill(group ? -pid : pid, group ? 'SIGKILL' : 'SIGTERM');
+      process.kill(-pid, 'SIGKILL');
     } catch {
       // Gone already.
     }
@@ -372,15 +375,24 @@ function killTree(pid, group) {
 /**
  * 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.
+ * run records it as stopped and goes on with the rest. 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);
+  const lockFor = () => {
+    const main = lockOf(path.join(runs, `${MAIN_RUN}.lock`));
+
+    return lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
+  };
+
+  // The mark says the session ended by a stop, and stops the next one as it starts: the lock
+  // names none before the item's first session, or between two of a handoff. Read again after
+  // the mark: a session that started meanwhile did not see it.
+  const lock = lockFor();
+  if (lock) writeFileSync(stopOf(runs, id), `${Date.now()}\n`);
+  const session = lock && lockFor()?.session;
+  if (session && alive(session)) killTree(session);
   core(['release', id]);
 
   return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;

package/commands/run.js

@@ -3,14 +3,97 @@
 // 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, writeSync } from 'node:fs';
+import { existsSync, mkdirSync, 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';
+import { fileURLToPath } from 'node:url';
+import { activity, clock, count } from './activity.js';
 
 // 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';
 
+const HOOKS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
+
+/**
+ * What the harness's own agent runs with (Harness-PRD §7): everything allowed but the project's
+ * deny rules, which hold in every mode; the project's settings and MCP servers only, so the
+ * operator's plugins, hooks and connectors stay out of the run; and `settingsFile`, the deny
+ * rules and the handoff guard. An agent the operator names (`--agent`) gets none of it.
+ */
+export function runFlags(dir, settingsFile) {
+  const mcp = existsSync(path.join(dir, '.mcp.json')) ? ' --mcp-config .mcp.json' : '';
+
+  return (
+    '--permission-mode bypassPermissions --setting-sources project,local ' +
+    `--strict-mcp-config${mcp} --settings "${settingsFile}"`
+  );
+}
+
+/** `.gcf-session/runs/agent-settings.json`: the deny rules of `gcf board`, the handoff guard. */
+export async function writeAgentSettings(logs, agent) {
+  const file = path.join(logs, 'agent-settings.json');
+  const guard = path.join(HOOKS, 'handoff-guard.js').replaceAll('\\', '/');
+  const settings = {
+    permissions: { deny: agent?.deny ?? [], allow: agent?.allow ?? [] },
+    hooks: {
+      PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: `node "${guard}"` }] }],
+    },
+  };
+  await writeFile(file, `${JSON.stringify(settings, null, 2)}\n`);
+
+  return file;
+}
+
+// The window of a model a run met before: `<model>: tokens`, from the result of its sessions.
+const windowsOf = (logs) => path.join(logs, 'windows.json');
+
+/**
+ * The context window a session's share is taken of: the project's `context_window`, the one a
+ * result of the same model reported, then a `[1m]` model; null when none says it.
+ */
+export function windowFor(model, configured, learned) {
+  if (configured > 0) return configured;
+  if (model && learned?.[model] > 0) return learned[model];
+
+  return /\[1m\]$/i.test(model ?? '') ? 1_000_000 : null;
+}
+
+/** Keep the window a session's result reported for its model. */
+async function learnWindow(logs, learned, ran) {
+  if (!ran.model || !(ran.window > 0) || learned[ran.model] === ran.window) return;
+  learned[ran.model] = ran.window;
+  await writeFile(windowsOf(logs), `${JSON.stringify(learned, null, 2)}\n`).catch(() => {});
+}
+
+// The flag the handoff guard reads, in the session's own checkout.
+const HANDOFF_FLAG = path.join('.gcf-session', 'handoff.json');
+// Fresh sessions one item may take in a row; the next handoff blocks it.
+export const MAX_HANDOFFS = 3;
+const HANDOFF_LIMIT =
+  `context handoff limit: ${MAX_HANDOFFS} fresh sessions did not finish the item - ` +
+  'split it, or raise context_handoff_pct';
+// A session that keeps on working past its flag: main-agent turns, or points over the share.
+const HARD_TURNS = 8;
+const HARD_OVER = 15;
+
+/** Two costs as one: what an item's sessions spent together. */
+function addCost(a, b) {
+  if (!a || !b) return a ?? b;
+  const t = (k) => a.tokens[k] + b.tokens[k];
+
+  return {
+    cost_usd: a.cost_usd + b.cost_usd,
+    tokens: {
+      input: t('input'),
+      output: t('output'),
+      cache_read: t('cache_read'),
+      cache_creation: t('cache_creation'),
+    },
+    turns: a.turns + b.turns,
+    duration_ms: a.duration_ms + b.duration_ms,
+  };
+}
+
 /** The core CLI: the same ai-factory that runs this command, in the project. */
 export function cliCore(projectDir) {
   return (args) => {
@@ -73,12 +156,12 @@ function killTree(child) {
   }
 }
 
-// The sessions this run has going: a stop (`gcf-harness stop`) takes them down with the run.
+// The sessions this run has going: a run that is killed (SIGTERM) takes them down with it.
 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.
+ * A run that gets SIGTERM (`gcf-harness stop <id>` stops one session, never the run): its
+ * sessions lead their own process groups, so the run takes each down before it exits.
  * Returns the unhook.
  */
 function stopWithSessions() {
@@ -104,9 +187,11 @@ function byLine(stream, take) {
     rest = lines.pop() ?? '';
     for (const l of lines) take(l);
   });
+  // Cleared before the take: a take that ends the session flushes again, and must find nothing.
   const flush = () => {
-    if (rest) take(rest);
+    const last = rest;
     rest = '';
+    if (last) take(last);
   };
 
   stream.on('end', flush);
@@ -117,35 +202,117 @@ function byLine(stream, take) {
 // What `claude --resume` prints on stderr for a session it does not have.
 const NO_SESSION = /No conversation found with session ID/;
 
+/** Keep what a session's activity told: the last of each, the model's window from the result. */
+function absorb(seen, a) {
+  seen.cost = a.cost ?? seen.cost;
+  seen.session_id = a.session_id ?? seen.session_id;
+  seen.limit = a.limit ?? seen.limit;
+  seen.model = a.model ?? seen.model;
+  // The init model's window; the largest when the result does not name that model.
+  if (a.windows) seen.window = a.windows[seen.model] ?? Math.max(...Object.values(a.windows));
+}
+
+/** Write the flag the handoff guard reads into the session's checkout. */
+function writeFlag(dir, flag) {
+  try {
+    mkdirSync(path.join(dir, '.gcf-session'), { recursive: true });
+    writeFileSync(path.join(dir, HANDOFF_FLAG), `${JSON.stringify(flag)}\n`);
+  } catch {
+    // No flag: the turns past it stop the session all the same.
+  }
+}
+
+/**
+ * An agent session's shell: its own process group off Windows, so a stop takes all it started.
+ * The guards read the session's own checkout, not one an outer Claude session named.
+ */
+function spawnAgent(command, dir, env) {
+  return spawn(command, {
+    cwd: dir,
+    shell: true,
+    // GCF_RUN_ITEM: the session's own gate must not refuse the item this run marked as running.
+    env: { ...process.env, ...env, CLAUDE_PROJECT_DIR: dir },
+    detached: !WIN,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * The handoff watch of one session (see `startAgent`): `see(a, model)` takes each activity, flags
+ * the session past its share or at a compaction, and calls `stop` once it works on past more.
+ */
+function handoffWatch(handoff, dir, write, stop) {
+  const w = { flagged: false, after: 0, context: 0, turn: undefined, unknown: false };
+  const unknownOnce = (model) => {
+    if (w.unknown) return;
+    w.unknown = true;
+    write([`[${clock()}] handoff: off, the window of ${model ?? 'the model'} is unknown`]);
+  };
+
+  const flag = (win, pct, compacted) => {
+    w.flagged = true;
+    writeFlag(dir, { pct, tokens: w.context, window: win, plan: handoff.plan ?? null });
+    const why = compacted
+      ? 'a compaction'
+      : `context ${pct}% (${count(w.context)} of ${count(win)})`;
+    write([`[${clock()}] handoff: ${why}, the session hands over`]);
+  };
+
+  const check = (model, compacted) => {
+    const win = handoff.windowOf(model);
+    const pct = win ? Math.round((100 * w.context) / win) : null;
+    // No share is under every threshold: a session of an unknown window hands over at a compaction.
+    const share = pct ?? 0;
+    if (pct === null && !compacted) unknownOnce(model);
+    if (!w.flagged && (compacted || share >= handoff.pct)) flag(win, pct, compacted);
+    if (w.flagged && (w.after > HARD_TURNS || share >= handoff.pct + HARD_OVER)) {
+      write([`[${clock()}] handoff: the session went on past its flag, stopped`]);
+      stop();
+    }
+  };
+
+  return {
+    state: w,
+    see(a, model) {
+      if (a.context !== undefined) {
+        w.context = a.context;
+        if (w.flagged && a.turn !== w.turn) w.after++;
+        w.turn = a.turn;
+      }
+
+      if (handoff?.pct && (a.context !== undefined || a.compacted))
+        check(model, Boolean(a.compacted));
+    },
+  };
+}
+
 /**
  * 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. 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.
+ *
+ * `handoff` ({pct, windowOf(model), plan}) watches the main agent's context: past `pct` of the
+ * window, or at a compaction, the session gets `.gcf-session/handoff.json`, and the handoff
+ * guard turns its tool calls into the instruction to hand over; one that keeps on working is
+ * stopped. `handoff: true` says the session was told to hand over, `handedOver` that it did.
  * @returns {Promise<{code: number | string, cost?: import('./activity.js').Cost,
- *   session_id?: string, limit?: {resets: string | null}, gone: boolean}>}
+ *   session_id?: string, limit?: {resets: string | null}, gone: boolean, handoff: boolean,
+ *   handedOver: boolean, model?: string, window?: number}>}
  */
-function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
+function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {}, handoff }) {
   return new Promise((resolve) => {
     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', 'pipe', 'pipe'],
-    });
+    const child = spawnAgent(command, dir, { ...env, GCF_RUN_ITEM: id });
     sessions.add(child);
     if (child.pid) onSpawn?.(child.pid);
     let open = true;
-    let cost;
-    let sessionId;
-    let limit;
+    /** @type {Record<string, any>} */
+    const seen = {};
     let gone = false;
     const write = (lines) => {
       try {
@@ -155,12 +322,15 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
       }
     };
 
+    const watch = handoffWatch(handoff, dir, write, () => {
+      killTree(child);
+      end('handoff');
+    });
     const flushOut = byLine(child.stdout, (line) => {
       const a = activity(line);
-      cost = a.cost ?? cost;
-      sessionId = a.session_id ?? sessionId;
-      limit = a.limit ?? limit;
+      absorb(seen, a);
       write(a.lines);
+      if (open) watch.see(a, seen.model);
     });
     const flushErr = byLine(child.stderr, (line) => {
       gone ||= NO_SESSION.test(line);
@@ -177,7 +347,11 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
       open = false;
       sessions.delete(child);
       clearTimeout(timer);
-      resolve({ code, cost, session_id: sessionId, limit, gone });
+      const { flagged, after } = watch.state;
+      // Told to hand over, and it went on past the flag: it read the guard's instruction, or the
+      // run stopped it. A flag on its last turn found a session already done.
+      const handedOver = flagged && (after > 0 || code === 'handoff');
+      resolve({ ...seen, code, gone, handoff: flagged, handedOver });
     }
 
     child.on('error', () => end(-1));
@@ -341,8 +515,14 @@ async function claimAll(ids, logs) {
   const failed = [];
   for (const id of ids) {
     const release = await claim(logs, id);
-    if (release) claimed.push({ id, release });
-    else failed.push({ id, result: 'error', error: `${id} is already running in another run` });
+    if (!release) {
+      failed.push({ id, result: 'error', error: `${id} is already running in another run` });
+      continue;
+    }
+
+    // A dead run's stop mark goes; one from now on stops the item's session as it starts.
+    await rm(stopOf(logs, id), { force: true });
+    claimed.push({ id, release });
   }
 
   return { claimed, failed };
@@ -369,6 +549,12 @@ async function prepare({ claimed, failed }, core, agentOf) {
   return { ready, failed };
 }
 
+/**
+ * `<id>.stop`: `gcf-harness stop` while the item has no session, before its first or between two
+ * of a handoff: the next one is stopped as it starts.
+ */
+export const stopOf = (logs, id) => path.join(logs, `${id}.stop`);
+
 /** `<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`);
 
@@ -380,12 +566,28 @@ 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;
+    if (SESSION_ID.test(String(rec?.session_id))) return rec;
+
+    // A handoff needs no session: the rerun starts fresh. An id that is not one is dropped.
+    return rec?.ended === 'handoff' ? { ...rec, session_id: undefined } : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * Why a kept session ended. A session that handed over is not resumed: the rerun starts fresh
+ * from the plan. So does one after a handoff that reported no id: the full session before it is
+ * never resumed.
+ */
+function endedOf(r) {
+  if (r.handoffPending || !r.session_id) return 'handoff';
+  if (r.limit) return 'limit';
+  if (r.stopped) return 'stopped';
+
+  return r.code === 'timeout' ? 'timeout' : `exit ${r.code}`;
+}
+
 /**
  * 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.
@@ -393,15 +595,23 @@ async function kept(logs, id) {
 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,
+  if (!r.session_id && !r.handoffPending && !r.handoffs) return;
+  await writeFile(recordOf(logs, r.id), `${JSON.stringify(recordFor(r), null, 2)}\n`);
+}
+
+/** The `<id>.agent.json` of a session that ended with its item still ready. */
+function recordFor(r) {
+  return {
+    ...(r.session_id ? { session_id: r.session_id } : {}),
+    ended: endedOf(r),
     ...(r.limit?.resets ? { resets: r.limit.resets } : {}),
+    // The handoffs so far: the cap holds across runs.
+    ...(r.handoffs ? { handoffs: r.handoffs } : {}),
+    // The fresh session a counted handoff started ended with no id: the next one is no new
+    // handoff, only the same fresh start again.
+    ...(!r.handoffPending && !r.session_id ? { counted: true } : {}),
     at: new Date().toISOString(),
   };
-  await writeFile(recordOf(logs, r.id), `${JSON.stringify(rec, null, 2)}\n`);
 }
 
 /**
@@ -416,6 +626,19 @@ function noResult(r, rerun) {
         `no result (its session could not be resumed, agent exit ${r.code}): ` +
         `${r.id} stays ready, a rerun starts fresh`,
     };
+  if (r.handoffPending) {
+    const limit = r.limit
+      ? `usage limit${r.limit.resets ? `, resets ${r.limit.resets}` : ''}; `
+      : '';
+
+    return {
+      id: r.id,
+      result:
+        `paused (${limit}context handoff): ${r.id} stays ready, ` + 'a rerun goes on from the plan',
+      ...(r.limit ? { limit_resets: r.limit.resets } : {}),
+    };
+  }
+
   const again = r.session_id ? 'a rerun resumes its session' : rerun;
   if (r.limit) {
     const resets = r.limit.resets ? `, resets ${r.limit.resets}` : '';
@@ -427,23 +650,31 @@ function noResult(r, rerun) {
     };
   }
 
-  const why = r.code === 'timeout' ? 'the session timed out' : `agent exit ${r.code}`;
+  const why = r.stopped
+    ? 'stopped'
+    : 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 /;
 
+const taskOf = (r) => (r.main ? `/gcf-run ${r.id}` : `/gcf-run ${r.id} --worktree`);
+
 /**
  * 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`;
+  const task = taskOf(r);
   if (fresh) await rm(recordOf(logs, r.id), { force: true });
+  const rec = fresh ? null : await kept(logs, r.id);
+  // A session that handed over goes on in a fresh one, whatever the agent.
+  if (rec?.ended === 'handoff') return { agent: r.agent, prompt: `${task} --handoff`, rec };
   // `--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 };
+  if (!rec || !/^claude(\s|$)/.test(r.agent)) return { agent: r.agent, prompt: task, rec: null };
   // One plain line: the prompt goes into the shell command in double quotes.
   const ended = String(rec.ended).replace(/[^\w -]/g, '');
 
@@ -454,40 +685,143 @@ async function commandOf(r, logs, fresh) {
   };
 }
 
+/**
+ * One agent session of the item `s.r`, its handoff flag cleared around it. `stopped` says a
+ * `gcf-harness stop` ended it.
+ */
+async function agentSession(s, agent, prompt) {
+  const { r, fd, deadline, launch } = s;
+  const flag = path.join(r.dir, HANDOFF_FLAG);
+  await rm(flag, { force: true });
+  const flags = launch?.flags(r.dir);
+  const handoff = launch?.handoff && { ...launch.handoff, plan: launch.planOf?.(r.id) };
+  const left = Math.max(deadline - Date.now(), 1000);
+  const opts = { fd, timeoutMs: left, id: r.id, onSpawn: s.onSpawn, env: launch?.env, handoff };
+  const ran = await startAgent(flags ? `${agent} ${flags}` : agent, prompt, r.dir, opts);
+  await rm(flag, { force: true });
+  // Between two sessions the lock names none: a stop then marks the item, not the run.
+  writeFileSync(s.lock, `${process.pid}\n${r.id}\n`);
+  if (launch?.learned) await learnWindow(s.logs, launch.learned, ran);
+
+  return { ...ran, stopped: existsSync(stopOf(s.logs, r.id)) };
+}
+
+/**
+ * Count the item's next handoff, or say the cap is reached: the item is then blocked. The cap
+ * counts each handoff once, the one a kept record still owes a session included.
+ */
+async function capped(count, r) {
+  if (count.handoffs < MAX_HANDOFFS) {
+    count.handoffs++;
+
+    return false;
+  }
+
+  count.limit = true;
+  // A worktree records no move: the main checkout reads the block from its outcome.
+  if (!r.main) {
+    await mkdir(path.join(r.dir, '.gcf-session'), { recursive: true });
+    const outcome = `${JSON.stringify({ block: HANDOFF_LIMIT })}\n`;
+    await writeFile(path.join(r.dir, '.gcf-session', 'outcome.json'), outcome);
+  }
+
+  return true;
+}
+
+/**
+ * Only a session that handed over as told goes on: one that saw its flag and ended its reply,
+ * or that the run stopped past it. A stop, a limit or the deadline leaves the handoff to the
+ * next run.
+ */
+async function goesOn(s, ran) {
+  const over = ran.handedOver && (ran.code === 0 || ran.code === 'handoff') && !ran.limit;
+
+  return over && Date.now() < s.deadline && !ran.stopped && !(await s.r.done?.());
+}
+
+/**
+ * Whether the session `rec` kept is gone: a resume that claude answered with `No conversation
+ * found`, so 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, and the resumed session's id stands in for one
+ * its own run did not report. A fresh session after a handoff has none to borrow: the full one is
+ * never resumed.
+ */
+function resumeLost(rec, ran) {
+  if (!rec || rec.ended === 'handoff') return false;
+  if (ran.gone) return true;
+  ran.session_id ??= rec.session_id;
+
+  return false;
+}
+
+/**
+ * The sessions of one item: the first runs its command; while one hands over as told, a fresh
+ * one goes on from the plan, up to MAX_HANDOFFS.
+ */
+async function handOver(s, { agent, prompt, rec }) {
+  const { r } = s;
+  const count = { handoffs: Number(rec?.handoffs) || 0, limit: false };
+  const fromHandoff = rec?.ended === 'handoff';
+  // A record whose handoff its own run already counted (`counted`) owes none.
+  if (fromHandoff && !rec.counted && (await capped(count, r)))
+    return { code: 0, handoffs: count.handoffs, handoffLimit: true, handoffPending: false };
+  let ran = await agentSession(s, agent, prompt);
+  let cost = ran.cost;
+  const lost = resumeLost(rec, ran);
+  while ((await goesOn(s, ran)) && !(await capped(count, r))) {
+    writeSync(
+      s.fd,
+      `[${clock()}] handoff ${count.handoffs}: a fresh session goes on from the plan\n`,
+    );
+    ran = await agentSession(s, r.agent, `${taskOf(r)} --handoff`);
+    cost = addCost(cost, ran.cost);
+  }
+
+  return {
+    ...ran,
+    cost,
+    handoffs: count.handoffs,
+    handoffLimit: count.limit,
+    // The session was told to hand over and no fresh one took it: the next run does.
+    // A limit there too: the rerun after the reset starts fresh, it does not resume the full one.
+    handoffPending: ran.handoff && !count.limit,
+    lost,
+  };
+}
+
 /**
  * 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, fresh) {
+async function session(r, { logs, timeoutMs, fresh, launch }) {
   /** @type {import('node:fs/promises').FileHandle | null} */
   let log = null;
   // 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`);
+  const onSpawn = (pid) => {
+    writeFileSync(lock, `${process.pid}\n${r.id}\n${pid}\n`);
+    // A stop that came while the lock named no session left only its mark: it ends this one.
+    if (existsSync(stopOf(logs, r.id))) killTree({ pid });
+  };
+
   // 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 {
-    const { agent, prompt, rec } = await commandOf(r, logs, fresh);
+    const cmd = 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;
+    // One deadline for the item, however many sessions it takes.
+    const deadline = Date.now() + timeoutMs;
 
     return {
       ...r,
-      ...ran,
-      session_id: ran.session_id ?? (lost ? undefined : rec?.session_id),
-      lost,
+      ...(await handOver({ r, logs, lock, fd: log.fd, deadline, launch, onSpawn }, cmd)),
     };
   } catch (e) {
     return { ...r, code: null, error: e.message };
   } finally {
     if (keep) clearInterval(keep);
+    await rm(stopOf(logs, r.id), { force: true });
     await log?.close();
     await r.release();
   }
@@ -569,6 +903,34 @@ function resultOf(run, integrated) {
 
 export const DEFAULT_TIMEOUT_MIN = 120;
 
+/**
+ * How the run starts its sessions (Harness-PRD §7): a `managed` agent, the harness's own, gets
+ * the run flags, the settings file and the handoff watch, which needs the guard those settings
+ * bring; every agent gets the compaction share. A core that reports no deny rules is refused:
+ * bypass with none would allow everything.
+ */
+async function launchOf(logs, managed, board) {
+  if (managed && !Array.isArray(board.agent?.deny))
+    throw new Error('gcf board reports no agent deny rules: update gcf-aif-ext to 0.7.6 or later');
+  const settings = managed ? await writeAgentSettings(logs, board.agent) : null;
+  const ctx = board.context ?? {};
+  const learned = await readFile(windowsOf(logs), 'utf8')
+    .then((t) => JSON.parse(t) ?? {})
+    .catch(() => ({}));
+
+  return {
+    flags: (dir) => (settings ? runFlags(dir, settings) : ''),
+    env: ctx.compact_pct > 0 ? { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: String(ctx.compact_pct) } : {},
+    handoff: managed &&
+      ctx.handoff_pct > 0 && {
+        pct: ctx.handoff_pct,
+        windowOf: (model) => windowFor(model, ctx.window, learned),
+      },
+    learned,
+    planOf: (id) => board.items?.find((i) => i.id === id)?.plan_file ?? null,
+  };
+}
+
 // The move an item's status shows after a run on main: the agent recorded it itself.
 const MOVE_OF = {
   'awaiting-verdict': 'submit',
@@ -619,30 +981,51 @@ async function runMain(projectDir, ids, ctx) {
 }
 
 /** One item of a main run: marked, its session, its mark cleared, its result read. */
-async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs, fresh }) {
+async function mainItem(projectDir, id, ctx) {
+  const { core, logs, agentOf } = ctx;
   let r;
+  await rm(stopOf(logs, id), { force: true });
+  // The checkout's lock names the item from now on: a stop before its session marks it.
+  writeFileSync(path.join(logs, `${MAIN_RUN}.lock`), `${process.pid}\n${id}\n`);
   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, fresh);
+    // The agent recorded the item's move: no fresh session takes it over.
+    // A board that cannot be read is no move: the run goes on, and the result read says why.
+    const done = async () => {
+      try {
+        const items = json(await core(['board', '--json']), 'board').items;
+
+        return items?.find((i) => i.id === id)?.status !== 'ready';
+      } catch {
+        return false;
+      }
+    };
+
+    const s = { id, dir: projectDir, agent: agentOf(id), release: none, main: true, done };
+    r = await session(s, ctx);
   } catch (e) {
     r = { id, error: e.message };
   }
 
   await core(['release', id]);
+  if (r.handoffLimit) await core(['block', id, '--reason', HANDOFF_LIMIT]);
   const item = await mainResult(core, r);
   await remember(logs, r, item);
 
-  return { ...item, ...r.cost };
+  return { ...item, ...r.cost, ...(r.handoffs ? { handoffs: r.handoffs } : {}) };
 }
 
 /** Every claimed item in its worktree at once; blocks recorded on main, verified ones merged. */
-async function runWorktrees(claims, { core, logs, agentOf, timeoutMs, fresh }) {
+async function runWorktrees(claims, ctx) {
+  const { core, logs, agentOf } = ctx;
   const { ready, failed } = await prepare(claims, core, agentOf);
-  const runs = await Promise.all(ready.map((r) => session(r, logs, timeoutMs, fresh)));
+  // A session that verified its branch, or left an outcome, is done: no fresh one follows.
+  const done = (r) => () =>
+    verified(r.dir, r.id) || existsSync(path.join(r.dir, '.gcf-session', 'outcome.json'));
+  const runs = await Promise.all(ready.map((r) => session({ ...r, done: done(r) }, ctx)));
   const items = [...failed];
   for (const r of runs) {
     const outcome = await outcomeOf(r.dir);
@@ -665,7 +1048,11 @@ async function runWorktrees(claims, { core, logs, agentOf, timeoutMs, fresh }) {
     );
 
   // 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 }));
+  return items.map((i) => {
+    const r = runs.find((x) => x.id === i.id);
+
+    return { ...i, ...r?.cost, ...(r?.handoffs ? { handoffs: r.handoffs } : {}) };
+  });
 }
 
 /**
@@ -683,6 +1070,8 @@ export async function run(
     timeoutMs = DEFAULT_TIMEOUT_MIN * 60_000,
     mode = undefined,
     fresh = false,
+    // The harness's flags, settings and handoff watch: its own agent's by default.
+    managed = agent === DEFAULT_AGENT,
   },
 ) {
   // An id names a lock file and goes into the agent's shell command: a slug, nothing else.
@@ -693,6 +1082,8 @@ export async function run(
   await mkdir(logs, { recursive: true });
   const board = json(await core(['board', '--json']), 'board');
   const runMode = mode ?? board.run_mode ?? 'worktree';
+  // Before any item is claimed: a refusal here leaves no lock behind.
+  const launch = await launchOf(logs, managed, board);
   // 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
@@ -705,12 +1096,9 @@ export async function run(
   });
   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, fresh };
+  const itemOf = (id) => (board.items ?? []).find((i) => i.id === id);
+  const agentOf = (id) => agentFor(agent, itemOf(id));
+  const ctx = { core, logs, agentOf, timeoutMs, fresh, launch };
   const unhook = stopWithSessions();
   try {
     const items =

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

package/hooks/handoff-guard.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Handoff guard (Harness-PRD §7): a PreToolUse hook the harness hands its agent runs through
+// `--settings`. When the run sees the session's context pass its handoff share it writes
+// .gcf-session/handoff.json; from then on every tool call of the main agent but the plan's
+// read and edit is denied with the handoff instruction, which the agent reads as the reason.
+// The session writes its `## Handoff` into the plan and ends; the harness starts a fresh one.
+// No flag → silent allow. A subagent's call passes: the reviewer it runs ends cleanly first.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const FLAG = path.join('.gcf-session', 'handoff.json');
+
+const PLAN_TOOLS = ['Read', 'Edit', 'Write', 'MultiEdit'];
+
+/** Whether a path is the item's plan (`flag.plan`) or a plan under `.ai-factory/plans/`. */
+function isPlan(file, projectDir, flag) {
+  if (typeof file !== 'string' || !file) return false;
+  const abs = path.resolve(projectDir, file);
+  if (typeof flag.plan === 'string' && abs === path.resolve(projectDir, flag.plan)) return true;
+  const rel = path.relative(path.join(projectDir, '.ai-factory', 'plans'), abs);
+
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/** The instruction the denied call carries to the agent. */
+export function handoffReason(flag) {
+  const at = flag?.pct ? `${flag.pct}%` : 'its limit';
+
+  return (
+    `context at ${at} of the window: hand over now. Start no new task. Write a "## Handoff" ` +
+    "section at the end of the item's plan: the tasks done, the one in progress and where it " +
+    'stands, the next step, the open review findings and the DoD diagnosis. Put no "- [ ]" ' +
+    'line in it. Leave the task in progress unticked. Then end your reply: a fresh session ' +
+    'goes on from the plan.'
+  );
+}
+
+/**
+ * The verdict on one tool call: `{allow}` or `{allow: false, reason}`. `flag` is the parsed
+ * handoff.json, or null.
+ */
+export function decide(input, projectDir, flag) {
+  if (!flag) return { allow: true };
+  if (input?.agent_id) return { allow: true };
+  const file = input?.tool_input?.file_path;
+  if (PLAN_TOOLS.includes(input?.tool_name) && isPlan(file, projectDir, flag))
+    return { allow: true };
+
+  return { allow: false, reason: handoffReason(flag) };
+}
+
+/** The flag of the session's checkout, or null; an unreadable one still hands over. */
+export function readFlag(projectDir) {
+  let text;
+  try {
+    text = readFileSync(path.join(projectDir, FLAG), 'utf8');
+  } catch {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+// 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('handoff-guard.js')) {
+  /** @type {Record<string, any> | null} */
+  let input = null;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    // No input: nothing to judge.
+  }
+
+  // The directory the session started in: `cwd` follows a `cd` of the agent.
+  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
+  const verdict = decide(input, projectDir, readFlag(projectDir));
+  if (!verdict.allow) {
+    console.error(`gcf handoff-guard: ${verdict.reason}`);
+    process.exit(2);
+  }
+
+  process.exit(0);
+}

package/hooks/readset-guard.js

@@ -141,7 +141,9 @@ export function keepSessionsAlive(projectDir, now = Date.now()) {
 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();
+  // The directory the session started in: `cwd` follows a `cd` of the agent, and a manifest
+  // not found there would allow every read.
+  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
   keepSessionsAlive(projectDir);
   const verdict = decide(input, projectDir, readManifest(projectDir));
   if (!verdict.allow) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.8.9",
+  "version": "0.9.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.7.0"
+    "gcf-aif-ext": "^0.7.6"
   },
   "files": [
     "extension.json",

package/skills/gcf-run/SKILL.md

@@ -14,6 +14,7 @@ purpose:
 inputs:
 - 1 or more work item or design unit ids; a batch shares one build and one playtest list
 - `--worktree` when `ai-factory gcf-harness run` started this session inside the item's worktree
+- `--handoff` when the harness started this session after the last one filled its context: the plan's `## Handoff` says where it stopped
 
 preconditions:
 - `gcf/` exists and `ai-factory gcf audit` runs (the gcf-aif-ext extension provides it)
@@ -37,6 +38,9 @@ forbidden_behaviors:
 - do not write a refused command into a DoD command or a config that `ai-factory gcf` runs
 - a dedicated tool doing the same job (Read, Grep, Glob, Edit) is no wrapper, nor is a refused pipe or `;` chain split into single allowed commands
 - a refusal none of those replaces is a stop: run `ai-factory gcf block <id> --reason "needs permission: <command>"` and stop the item; under `--worktree` step 22 records it instead
+- a call the handoff guard denies with "context at" is no refusal: block nothing, write the `## Handoff` it asks for and end the reply
+- a read the readset guard denies is no refusal either: drop that read, and widen the readset only through the item's `system:` or `depends:`
+- delete one file with `rm -f <file>` or `Remove-Item -Force <file>`, never with `-r`: the deny rules refuse a recursive delete
 
 workflow:
 1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf integrate` to merge the verified branches a dead run left; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line
@@ -63,6 +67,8 @@ workflow:
 22. with `--worktree`, every stop - a failed gate, an over budget readset, a failed plan check, a refused command, steps 11, 12, 14, 18 - writes `{"block": "<reason>"}` to `.gcf-session/outcome.json` and ends the session
 23. with `--worktree`, run no `ai-factory gcf block`, `submit` or `close`: the core refuses them on a `work/` branch, and the harness records the move on main
 24. with `--worktree`, step 17 is: commit everything but `gcf/.metrics`, then run `ai-factory gcf verify <id> --mark`; the harness merges the branch
+25. with `--handoff`: run steps 1, 5 and 6, read the plan's `## Handoff`, skip steps 7-11 unless it says the plan passes were not done, then go on at step 13; a plan with no `## Handoff` goes on at step 13 from its ticks
+26. with `--handoff`, take the review findings and the DoD diagnosis of `## Handoff` into steps 13-15, and delete the section before the commit of step 16
 
 invocation:
 - run when the user names a work item or a unit to drive; batches share steps 1 and 19