gcf-harness-aif-ext 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -123,7 +123,7 @@ Updating keeps the hook entry valid — it points into the extension's install d
123
123
  - A stop that comes while the session starts no longer misses it.
124
124
 
125
125
  0.9.0, to update together with core 0.7.6:
126
- - 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>`.
126
+ - 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>`. `gcf-harness run <id> --allow "<rule>"` reruns it with that one rule off for this run only (the rule as the refusal names it, `edit: .claude/**`; repeat for more): its sessions get a settings file of their own, removed at the end, and a run beside it keeps the rule. A rule not in force is refused. The run report of an item so blocked prints that rerun line.
127
127
  - 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.
128
128
  - 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. A fresh session already over the share at its first turn (claude's own prompt and the skills hold about 40k tokens) is not handed over by the share, for a fresh one would start there too: its log says `handoff: off, the session starts at N% of the window, over context_handoff_pct P`; a compaction still hands it over (0.21.0). The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
129
129
  - `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
@@ -33,7 +33,15 @@ import {
33
33
  queueOf,
34
34
  stopOf,
35
35
  } from './run.js';
36
- import { CHAT_TIMEOUT_MIN, ChatRefusal, alive, chatInput, killTree, readText } from 'gcf-session';
36
+ import {
37
+ CHAT_TIMEOUT_MIN,
38
+ ChatRefusal,
39
+ alive,
40
+ chatInput,
41
+ chatOut,
42
+ killTree,
43
+ readText,
44
+ } from 'gcf-session';
37
45
 
38
46
  const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
39
47
  const SCHEMA = 1; // the only gcf/config.yml schema this harness drives
@@ -684,6 +692,13 @@ function registerRun(harness) {
684
692
  )
685
693
  .option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
686
694
  .option('--fresh', 'start new agent sessions: an interrupted one is not resumed')
695
+ .option(
696
+ '--allow <rule>',
697
+ 'go without this deny rule in force for this run only, as a refusal names it ' +
698
+ '(`edit: .claude/**`); repeat for more',
699
+ (v, all) => [...all, v],
700
+ [],
701
+ )
687
702
  .option(
688
703
  '--wait-limit',
689
704
  'a queued start: each session first waits while the usage limit is known to reset ahead',
@@ -893,12 +908,51 @@ export const itemLine = (i) =>
893
908
  .filter(Boolean)
894
909
  .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
895
910
 
911
+ /**
912
+ * The deny rule the last refusal in an item's run chat named (`kind: pattern`), or null: the
913
+ * one `--allow` takes (docs/Permission-Stop-Plan.md, d5).
914
+ */
915
+ export function deniedRuleOf(projectDir, id) {
916
+ const file = chatOut(path.join(projectDir, '.gcf-session', 'runs'), id);
917
+ const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
918
+ const events = text.split('\n').flatMap((l) => {
919
+ try {
920
+ return l ? [JSON.parse(l)] : [];
921
+ } catch {
922
+ return [];
923
+ }
924
+ });
925
+ // The last session's last rule refusal, as the board's deniedRuleOf: none from an older
926
+ // session, none when two rules held (it names none), none of a group no run goes without.
927
+ const start = events.findLastIndex((e) => e.type === 'session' && e.kind === 'start');
928
+ const last = events
929
+ .slice(Math.max(0, start))
930
+ .findLast((e) => e.type === 'denied' && e.by === 'rule');
931
+ if (!last?.rule || NEVER_ALLOWED.includes(last.group)) return null;
932
+
933
+ return last.rule;
934
+ }
935
+
936
+ // The groups whose rules no run goes without: history, the operator's moves, the play build.
937
+ const NEVER_ALLOWED = ['git-history', 'git-destroy', 'human-moves', 'run-play'];
938
+
939
+ /** How to rerun an item a refused call blocked, without that rule, or null. */
940
+ export function rerunHint(projectDir, i) {
941
+ const rule = /^needs permission/.test(i.reason ?? '') ? deniedRuleOf(projectDir, i.id) : null;
942
+
943
+ return rule
944
+ ? ` rerun without it: ai-factory gcf unblock ${i.id}, then ` +
945
+ `ai-factory gcf-harness run ${i.id} --allow "${rule}"`
946
+ : null;
947
+ }
948
+
896
949
  /** The run report a human reads, then the playtest sheet of what now waits for play. */
897
950
  function printRun(r) {
898
951
  for (const o of r.orphans)
899
952
  console.log(`orphan ${o.id}: ${o.move ?? o.conflict ?? o.error ?? o.skipped}`);
900
953
  if (r.gate) console.error(`gcf gate: ${r.gate}`);
901
- for (const i of r.items) console.log(itemLine(i));
954
+ for (const i of r.items)
955
+ console.log([itemLine(i), rerunHint(process.cwd(), i)].filter(Boolean).join('\n'));
902
956
  for (const f of r.features ?? [])
903
957
  console.log(`feature ${f.id}: ${f.result}${f.error ? ` — ${f.error}` : ''}`);
904
958
 
@@ -928,6 +982,7 @@ async function runItems(ids, opts) {
928
982
  timeoutMs: minutes === undefined ? undefined : minutes * 60_000,
929
983
  mode: opts.mode,
930
984
  fresh: Boolean(opts.fresh),
985
+ allow: opts.allow,
931
986
  waitLimit: Boolean(opts.waitLimit),
932
987
  chat: opts.chat ? { answerMin: answer } : null,
933
988
  model: opts.model,
@@ -51,7 +51,8 @@ export function planReview(projectDir, o) {
51
51
  timeout: o.timeoutMs ?? REVIEW_TIMEOUT_MS,
52
52
  shell,
53
53
  });
54
- if (res.error?.code === 'ETIMEDOUT') return { failed: 'the review timed out' };
54
+ if (/** @type {NodeJS.ErrnoException | undefined} */ (res.error)?.code === 'ETIMEDOUT')
55
+ return { failed: 'the review timed out' };
55
56
  // A flag the CLI no longer takes is named as it said it (Hold-Plan risk 11).
56
57
  if (res.status !== 0)
57
58
  return { failed: `codex exit ${res.status}: ${firstLine(res.stderr || res.stdout)}` };
package/commands/run.js CHANGED
@@ -74,8 +74,8 @@ const HOOKS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'hoo
74
74
  * which the harness's own agent runs with (Harness-PRD §7, the adapter's trusted flags). An
75
75
  * agent the operator names (`--agent`) gets none of it.
76
76
  */
77
- export async function writeAgentSettings(logs, agent) {
78
- const file = path.join(logs, 'agent-settings.json');
77
+ export async function writeAgentSettings(logs, agent, name = 'agent-settings.json') {
78
+ const file = path.join(logs, name);
79
79
  const guard = path.join(HOOKS, 'handoff-guard.js').replaceAll('\\', '/');
80
80
  const settings = {
81
81
  // The neutral rules (AD-4) in claude's form: the adapter translates them.
@@ -988,7 +988,7 @@ function reserveWatch(s) {
988
988
  return {
989
989
  gate: async () => {
990
990
  const d = await read();
991
- if (!d || d.go) return null;
991
+ if (!d || 'go' in d) return null;
992
992
  writeSync(s.fd, `[${clock()}] reserve: the quota is at quota_reserve_pct ${pct}\n`);
993
993
 
994
994
  return d;
@@ -1171,12 +1171,12 @@ export const DEFAULT_TIMEOUT_MIN = 120;
1171
1171
  * bring; every agent gets the compaction share. A core that reports no deny rules is refused:
1172
1172
  * bypass with none would allow everything.
1173
1173
  */
1174
- async function launchOf(logs, managed, board, chat) {
1175
- if (managed && !Array.isArray(board.agent?.rules?.deny))
1174
+ async function launchOf(logs, managed, read, { chat, allow }) {
1175
+ if (managed && !Array.isArray(read.agent?.rules?.deny))
1176
1176
  throw new Error(
1177
1177
  'gcf board reports no neutral agent rules: update gcf-aif-ext to 0.12 or later',
1178
1178
  );
1179
- const settings = managed ? await writeAgentSettings(logs, board.agent) : null;
1179
+ const { board, settings } = await settingsOf(logs, managed, read, allow);
1180
1180
  const ctx = board.context ?? {};
1181
1181
  const learned = readWindows(logs);
1182
1182
 
@@ -1197,6 +1197,48 @@ async function launchOf(logs, managed, board, chat) {
1197
1197
  };
1198
1198
  }
1199
1199
 
1200
+ /**
1201
+ * The board the run's sessions go by, its `allow` rules taken out, and the settings file of a
1202
+ * managed agent: a run that goes without a rule writes its own, so a run beside it keeps it.
1203
+ */
1204
+ async function settingsOf(logs, managed, board, allow = []) {
1205
+ if (!allow.length)
1206
+ return { board, settings: managed ? await writeAgentSettings(logs, board.agent) : null };
1207
+ const less = withoutAllowed(board, allow);
1208
+ const name = allowedSettingsName();
1209
+
1210
+ return {
1211
+ board: less,
1212
+ settings: managed ? await writeAgentSettings(logs, less.agent, name) : null,
1213
+ };
1214
+ }
1215
+
1216
+ /** A card session's launch: no run chat, every deny rule in force. */
1217
+ const CARD_LAUNCH = { chat: null, allow: [] };
1218
+
1219
+ /** The settings file of a run that goes without some deny rules: this process's own. */
1220
+ export const allowedSettingsName = () => `agent-settings.${process.pid}.json`;
1221
+
1222
+ /** A deny rule as a refusal in the chat names it: `kind: pattern`, or the kind alone. */
1223
+ const ruleName = (r) => (r.pattern ? `${r.kind}: ${r.pattern}` : r.kind);
1224
+
1225
+ /**
1226
+ * The board with the deny rules `allow` names taken out (docs/Permission-Stop-Plan.md, d2): the
1227
+ * operator's decision for this one run. Each must be a rule in force, as a refusal named it.
1228
+ */
1229
+ export function withoutAllowed(board, allow) {
1230
+ const deny = board.agent.rules.deny;
1231
+ const missing = allow.find((a) => !deny.some((r) => ruleName(r) === a));
1232
+ if (missing)
1233
+ throw new Error(
1234
+ `--allow ${missing}: no such deny rule in force ` +
1235
+ '(gcf permissions lists them, as kind: pattern)',
1236
+ );
1237
+ const rules = { ...board.agent.rules, deny: deny.filter((r) => !allow.includes(ruleName(r))) };
1238
+
1239
+ return { ...board, agent: { ...board.agent, rules } };
1240
+ }
1241
+
1200
1242
  /**
1201
1243
  * A run's chat as the flag and `chat:` of gcf/config.yml set it (a core before 0.11 has none):
1202
1244
  * how long a question waits, and what the agent asks by a card; nobody to answer asks nothing.
@@ -1600,10 +1642,10 @@ async function yieldedRest(projectDir, ids, n, ctx) {
1600
1642
  }
1601
1643
 
1602
1644
  /**
1603
- * The first ticket that needs the checkout: a worktree build (`from`) needs only its turn, and the
1604
- * run does not wait for it.
1645
+ * The first ticket that needs the checkout: a worktree build (`from`), or one the core builds in
1646
+ * its build folder (`free`, a worktree project), needs only its turn; the run does not wait for it.
1605
1647
  */
1606
- const checkoutTicket = (logs) => buildTickets(logs).find((t) => !t.job?.from);
1648
+ const checkoutTicket = (logs) => buildTickets(logs).find((t) => !t.job?.from && !t.job?.free);
1607
1649
 
1608
1650
  /**
1609
1651
  * Wait while ticket `n` lives, read again each time (its waiter takes it after the CLI that wrote
@@ -1989,6 +2031,7 @@ function commandsOf(core, agent, board, override) {
1989
2031
  };
1990
2032
 
1991
2033
  const agentOf = async (id) => {
2034
+ /** @type {{items?: {id: string}[]} | null} */
1992
2035
  let now = null;
1993
2036
  try {
1994
2037
  now = json(await core(['board', '--json']), 'board');
@@ -2024,6 +2067,12 @@ export const run = async (projectDir, ids, opts) => {
2024
2067
  try {
2025
2068
  return await runBatch(projectDir, ids, opts);
2026
2069
  } finally {
2070
+ // Its own settings, with the rules it went without, end with it.
2071
+ if (opts.allow?.length) {
2072
+ const logs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
2073
+ await rm(path.join(logs, allowedSettingsName()), { force: true });
2074
+ }
2075
+
2027
2076
  if (was === undefined) delete process.env.GCF_MOVE_BY;
2028
2077
  else process.env.GCF_MOVE_BY = was;
2029
2078
  }
@@ -2094,6 +2143,10 @@ const DOD = (ok) => (ok === true ? 'green' : ok === false ? 'red' : 'unknown');
2094
2143
  * took, main's commit, the plan's tasks left unticked, the lessons it filed, a broken step, the
2095
2144
  * run's last DoD and review (from `launch.events`, its chat's events since the last run's end),
2096
2145
  * the work it left uncommitted in its worktree (`launch.worktree`).
2146
+ * @param {any} i
2147
+ * @param {string} projectDir
2148
+ * @param {{planOf?: (id: string) => string | null, events?: any[], worktree?: string | null}
2149
+ * | null} [launch]
2097
2150
  */
2098
2151
  export function runEndOf(i, projectDir, launch = null) {
2099
2152
  const result = String(i.result ?? 'merged');
@@ -2107,6 +2160,7 @@ export function runEndOf(i, projectDir, launch = null) {
2107
2160
  : (OUTCOME[word] ??
2108
2161
  (word === 'skipped' ? 'skipped' : word === 'merged' ? 'submitted' : 'no-result'));
2109
2162
  const plan = launch?.planOf?.(i.id) ?? null;
2163
+ /** @type {number | null} */
2110
2164
  let unticked = null;
2111
2165
  let handoff = false;
2112
2166
  try {
@@ -2176,6 +2230,7 @@ export function runEvents(file) {
2176
2230
  * Post an item's run end to its chat (Tails «Первым» 2), when the run has one: not for an item
2177
2231
  * that never started (another run's lock), whose chat is that run's. The plan is the board's now:
2178
2232
  * a first run made it.
2233
+ * @param {string | null} [worktree]
2179
2234
  */
2180
2235
  async function postEnd(ctx, item, worktree = null) {
2181
2236
  if (!ctx.launch?.chat || item.started === false) return;
@@ -2218,6 +2273,7 @@ export const CARD_RUN = 'card';
2218
2273
  * holds it), or `none`. The core's moves its agent makes are the run's.
2219
2274
  * @param {string} projectDir
2220
2275
  * @param {string[]} units
2276
+ * @param {Parameters<typeof cardUnits>[2]} [opts]
2221
2277
  */
2222
2278
  export const card = async (projectDir, units, opts = {}) => {
2223
2279
  const was = { by: process.env.GCF_MOVE_BY, owner: process.env.GCF_RUN_OWNER };
@@ -2226,15 +2282,21 @@ export const card = async (projectDir, units, opts = {}) => {
2226
2282
  try {
2227
2283
  return await cardUnits(projectDir, units, opts);
2228
2284
  } finally {
2229
- for (const [k, v] of [
2285
+ for (const [k, v] of /** @type {[string, string | undefined][]} */ ([
2230
2286
  ['GCF_MOVE_BY', was.by],
2231
2287
  ['GCF_RUN_OWNER', was.owner],
2232
- ])
2288
+ ]))
2233
2289
  if (v === undefined) delete process.env[k];
2234
2290
  else process.env[k] = v;
2235
2291
  }
2236
2292
  };
2237
2293
 
2294
+ /**
2295
+ * @param {string} projectDir
2296
+ * @param {string[]} units
2297
+ * @param {{core?: ReturnType<typeof cliCore>, agent?: string, timeoutMs?: number,
2298
+ * managed?: boolean, waitLimit?: boolean}} [opts]
2299
+ */
2238
2300
  async function cardUnits(
2239
2301
  projectDir,
2240
2302
  units,
@@ -2258,7 +2320,7 @@ async function cardUnits(
2258
2320
  let launch;
2259
2321
  let agentFirst;
2260
2322
  try {
2261
- launch = await launchOf(logs, managed ?? agent === DEFAULT_AGENT, board, null);
2323
+ launch = await launchOf(logs, managed ?? agent === DEFAULT_AGENT, board, CARD_LAUNCH);
2262
2324
  ({ agentFirst } = commandsOf(core, agent, board, {}));
2263
2325
  } catch (e) {
2264
2326
  // Its session never starts: the checkout goes back now, not at the process's end.
@@ -2326,8 +2388,8 @@ async function runBatch(
2326
2388
  agent = DEFAULT_AGENT,
2327
2389
  gate,
2328
2390
  // None: `session_timeout_min` of gcf/config.yml, else DEFAULT_TIMEOUT_MIN.
2329
- timeoutMs = undefined,
2330
- mode = undefined,
2391
+ timeoutMs = /** @type {number | undefined} */ (undefined),
2392
+ mode = /** @type {string | undefined} */ (undefined),
2331
2393
  fresh = false,
2332
2394
  // A queued start: each session first waits while the usage limit's reset is ahead (AD-19).
2333
2395
  waitLimit = false,
@@ -2340,6 +2402,8 @@ async function runBatch(
2340
2402
  // This run's model and effort over each item's own (`default` or none: the item's).
2341
2403
  model,
2342
2404
  effort,
2405
+ // Deny rules in force this run goes without (`kind: pattern`): the operator's, one run.
2406
+ allow = /** @type {string[]} */ ([]),
2343
2407
  // How to call the core as a process of its own: a build must be stoppable.
2344
2408
  coreCommand = [process.execPath, process.argv[1], 'gcf'],
2345
2409
  },
@@ -2370,7 +2434,7 @@ async function runBatch(
2370
2434
  ];
2371
2435
  timeoutMs ??= (board.session_timeout_min ?? DEFAULT_TIMEOUT_MIN) * 60_000;
2372
2436
  // Before any item is claimed: a refusal here leaves no lock behind.
2373
- const launch = await launchOf(logs, managed, board, chat);
2437
+ const launch = await launchOf(logs, managed, board, { chat, allow });
2374
2438
  // One gate over the whole batch, and this run's holds go in with it: the gate counts the items
2375
2439
  // other runs hold. A worktree part's locks; a main part's checkout with its queue, the items it
2376
2440
  // has yet to reach.
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-harness-aif-ext",
4
- "version": "0.26.0",
4
+ "version": "0.28.0",
5
5
  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
6
6
  "skills": [
7
7
  "skills/gcf-run",
@@ -121,6 +121,7 @@ export const decide = (input, projectDir, state, phase) =>
121
121
  * implementation session starts it only on a plan the check calls converged. `phase.now` is the
122
122
  * run's GCF_RUN_PHASE (none: as before, the operator's own terminal); `phase.converged()` reads
123
123
  * the plan check, null when it cannot.
124
+ * @param {{now?: string, converged?: () => boolean | null}} [phase]
124
125
  */
125
126
  function phaseRefusal({ now, converged } = {}) {
126
127
  if (now === 'plan')
@@ -100,6 +100,9 @@ function refusedBy(deny, call) {
100
100
  };
101
101
  }
102
102
 
103
+ /** A call's error text when a deny rule refused it: a path rule's, or a command rule's. */
104
+ const DENIED_TEXT = /denied by your permission settings|Permission to use .+ has been denied/;
105
+
103
106
  /** How long a question waits for the operator when neither the flag nor the config says. */
104
107
  export const CHAT_TIMEOUT_MIN = 15;
105
108
 
@@ -852,6 +855,9 @@ const SEEN = {
852
855
  // stays out of the chat. The session's rule that holds for it, and the rule's group, say what
853
856
  // refused it (refusedBy).
854
857
  refused: (c, e) => {
858
+ // One refusal comes as the system event and as its call's error text: it posts once.
859
+ if (c.refusedIds.has(e.id)) return;
860
+ c.refusedIds.add(e.id);
855
861
  const call = c.calls.get(e.id);
856
862
  const why = typeof call?.input?.description === 'string' ? call.input.description : '';
857
863
  post(c, {
@@ -873,6 +879,11 @@ const SEEN = {
873
879
  if (!e.sub && m) c.proposals.set(e.id, { move: m[1].replaceAll('_', '-'), fields: e.input });
874
880
  },
875
881
  tool_result: (c, e) => {
882
+ // A deny rule on a path refuses in the tool's own input check: claude sends no
883
+ // permission_denied then, only this error text (spike in docs/Session-Engine.md).
884
+ const call = c.calls.get(e.id);
885
+ if (e.error && call && DENIED_TEXT.test(e.text))
886
+ SEEN.refused(c, { type: 'refused', id: e.id, tool: call.tool, reason: e.text });
876
887
  c.calls.delete(e.id);
877
888
  const p = c.proposals.get(e.id);
878
889
  if (!p) return;
@@ -1029,6 +1040,7 @@ function chatState(opts) {
1029
1040
  ...{ sent: 0, read: 0, cards: new Map(), wait: null, defaulted: false, closed: false },
1030
1041
  ...{ stopped: false, stopWait: false, grace: null, idle: false, inTurn: true, tasks: [] },
1031
1042
  ...{ proposals: new Map(), calls: new Map(), heard: false, summary: null, wanted: null },
1043
+ refusedIds: new Set(),
1032
1044
  // When each task's last progress reached the chat; the last one it held back since.
1033
1045
  taskAt: new Map(),
1034
1046
  taskHeld: new Map(),
@@ -167,6 +167,7 @@ const fresh = (r, maxAgeMs, now) =>
167
167
  Boolean(r?.at) && now - Date.parse(r.at) < maxAgeMs && !r.failed;
168
168
 
169
169
  // One ask a process: a second caller waits for it (claim gives the lock to its own pid again).
170
+ /** @type {ReturnType<typeof askShared> | null} */
170
171
  let inFlight = null;
171
172
 
172
173
  /**
@@ -248,6 +249,11 @@ const scopedTo = (limit, model) => {
248
249
  );
249
250
  };
250
251
 
252
+ /**
253
+ * @typedef {{go: true} | {wait: true, until: Date, reserve: true}
254
+ * | {stop: true, why: string, reserve: {weekly?: boolean, until?: string | null}}} Reserve
255
+ */
256
+
251
257
  /**
252
258
  * The reserve's gate over a reading (`usage.json`): a failed ask is no reading, so it goes
253
259
  * (Hold-Plan d10), as does none.
@@ -255,6 +261,7 @@ const scopedTo = (limit, model) => {
255
261
  * @param {string | null | undefined} model
256
262
  * @param {number} pct
257
263
  * @param {number} [now]
264
+ * @returns {Reserve}
258
265
  */
259
266
  export const reserveOfReading = (reading, model, pct, now = Date.now()) =>
260
267
  reading && !reading.failed ? reserveOf(reading.limits, model, pct, now) : { go: true };
@@ -267,6 +274,7 @@ export const reserveOfReading = (reading, model, pct, now = Date.now()) =>
267
274
  * @param {string | null | undefined} model
268
275
  * @param {number} pct
269
276
  * @param {number} [now]
277
+ * @returns {Reserve}
270
278
  */
271
279
  export function reserveOf(limits, model, pct, now = Date.now()) {
272
280
  if (!limits?.length) return { go: true };
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-session",
3
- "version": "0.19.1",
3
+ "version": "0.19.2",
4
4
  "private": true,
5
5
  "description": "The session engine of GCF: one agent session and a run as a chain of them, the chat protocol, the provider adapters. Bundled by gcf-harness-aif-ext and gcf-board, never published.",
6
6
  "type": "module",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-harness-aif-ext",
3
- "version": "0.26.0",
3
+ "version": "0.28.0",
4
4
  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -28,7 +28,7 @@
28
28
  "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);require('node:fs').statSync('node_modules/gcf-session/lib/index.js')\""
29
29
  },
30
30
  "peerDependencies": {
31
- "gcf-aif-ext": ">=0.28.0 <0.29.0"
31
+ "gcf-aif-ext": ">=0.29.0 <0.30.0"
32
32
  },
33
33
  "dependencies": {
34
34
  "gcf-session": "file:../gcf-session"
@@ -82,6 +82,8 @@ forbidden_behaviors:
82
82
  - do not write a refused command into a DoD command or a config that `ai-factory gcf` runs
83
83
  - 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
84
84
  - 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
85
+ - the operator reruns a `needs permission` stop with that one rule off (the board's **Allow <rule> for one run**, or `gcf-harness run <id> --allow`)
86
+ - so name the refused call and what the tree already holds, and do not ask the operator to turn its group off
85
87
  - a call the handoff guard denies with "context at", "the operator holds this item" or "reserve" is no refusal: block nothing, write the `## Handoff` it asks for and end the reply
86
88
  - an aif-implement the implement guard denies for the planning phase or an unconverged plan is no refusal either: record the pass, if any, and end the reply; the harness starts the next session
87
89
  - a read the readset guard denies is no refusal either: drop that read; never add a `system:` or `depends:` only to read a file - when one of them is wrong in substance, fix it on main, and under `--worktree` stop with a block that names the fix