gcf-harness-aif-ext 0.27.0 → 0.28.1

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
@@ -189,22 +197,7 @@ function milestoneStop(report) {
189
197
  export function nextPlan(report, count, skip = []) {
190
198
  const stop = milestoneStop(report);
191
199
  if (stop) return { ids: [], mode: null, units: [], stop };
192
- const scope = inScope(report);
193
- const batch = [];
194
- const ready = (report.items ?? [])
195
- .filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
196
- .filter((i) => i.type !== 'release' && (!scope || scope.has(i.id)) && !skip.includes(i.id))
197
- .sort((a, b) => rank(a) - rank(b));
198
- // One run mode a batch: an autopilot starts it as one run, a main one in the checkout.
199
- let mode = null;
200
- for (const i of ready) {
201
- if (batch.length >= count) break;
202
- if (mode && (i.run_mode ?? mode) !== mode) continue;
203
- if (gate(report, [...batch, i.id]).pass) {
204
- batch.push(i.id);
205
- mode ??= i.run_mode ?? null;
206
- }
207
- }
200
+ const { batch, mode } = takeBatch(report, readyOf(report, inScope(report), skip), count);
208
201
 
209
202
  const building = (report.milestones ?? []).find((m) => m.name === report.build_milestone);
210
203
  const units = (building?.units ?? [])
@@ -224,6 +217,30 @@ export function nextPlan(report, count, skip = []) {
224
217
  return { ids: batch, mode, units, stop: empty };
225
218
  }
226
219
 
220
+ /** The ready items an autopilot may take, in scope and not skipped, by priority. */
221
+ const readyOf = (report, scope, skip) =>
222
+ (report.items ?? [])
223
+ .filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
224
+ .filter((i) => i.type !== 'release' && (!scope || scope.has(i.id)) && !skip.includes(i.id))
225
+ .sort((a, b) => rank(a) - rank(b));
226
+
227
+ /** Up to `count` of `ready`, each while the batch with it still passes the gate. */
228
+ function takeBatch(report, ready, count) {
229
+ const batch = [];
230
+ // One run mode a batch: an autopilot starts it as one run, a main one in the checkout.
231
+ let mode = null;
232
+ for (const i of ready) {
233
+ if (batch.length >= count) break;
234
+ if (mode && (i.run_mode ?? mode) !== mode) continue;
235
+ if (gate(report, [...batch, i.id]).pass) {
236
+ batch.push(i.id);
237
+ mode ??= i.run_mode ?? null;
238
+ }
239
+ }
240
+
241
+ return { batch, mode };
242
+ }
243
+
227
244
  /** The ids of `nextPlan`: what a board's Run offers. */
228
245
  export const nextBatch = (report, count) => nextPlan(report, count).ids;
229
246
 
@@ -287,7 +304,7 @@ export function withMainQueue(report, runs) {
287
304
  function auditReport() {
288
305
  // Re-enter the same ai-factory CLI that is running this command: no PATH or .cmd lookup.
289
306
  const args = [process.argv[1], 'gcf', 'audit', '--json'];
290
- const res = spawnSync(process.execPath, args, { encoding: 'utf8' });
307
+ const res = spawnSync(process.execPath, args, { windowsHide: true, encoding: 'utf8' });
291
308
  try {
292
309
  return withMainQueue(JSON.parse(res.stdout), path.join(process.cwd(), '.gcf-session', 'runs'));
293
310
  } catch (err) {
@@ -549,7 +566,32 @@ export function register(program) {
549
566
  .action(runGate);
550
567
 
551
568
  registerRun(harness);
569
+ registerNext(harness);
570
+ registerCard(harness);
571
+ harness
572
+ .command('metrics')
573
+ .description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
574
+ .option('--since <date>', 'only lines at or after this ISO date or time')
575
+ .option('--json', 'machine output')
576
+ .action(metricsCommand);
577
+ harness
578
+ .command('runs')
579
+ .description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
580
+ .option('--item <id>', 'only the runs that hold this item')
581
+ .option('--limit <n>', 'at most this many runs', '50')
582
+ .option('--json', 'machine output: {runs: [...]}')
583
+ .action(runsCommand);
584
+ harness
585
+ .command('stop <id>')
586
+ .description('Stop the session that works an item; the run goes on, the item stays ready')
587
+ .action((id) => console.log(stopRun(process.cwd(), id)));
588
+ registerHold(harness);
589
+ registerPlanReview(harness);
590
+ registerChat(harness);
591
+ }
552
592
 
593
+ /** `gcf-harness next`: what can run together now, or an autopilot's plan. */
594
+ function registerNext(harness) {
553
595
  harness
554
596
  .command('next [count]')
555
597
  .description('The ready items that can run together now, by priority (the gate decides)')
@@ -580,6 +622,10 @@ export function register(program) {
580
622
  o.json ? JSON.stringify(ids) : ids.join('\n') || plan.stop?.text || 'nothing can run now',
581
623
  );
582
624
  });
625
+ }
626
+
627
+ /** `gcf-harness card`: design units into work, one agent session on main. */
628
+ function registerCard(harness) {
583
629
  harness
584
630
  .command('card <units...>')
585
631
  .description(
@@ -607,26 +653,6 @@ export function register(program) {
607
653
  process.exitCode = 1;
608
654
  }
609
655
  });
610
- harness
611
- .command('metrics')
612
- .description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
613
- .option('--since <date>', 'only lines at or after this ISO date or time')
614
- .option('--json', 'machine output')
615
- .action(metricsCommand);
616
- harness
617
- .command('runs')
618
- .description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
619
- .option('--item <id>', 'only the runs that hold this item')
620
- .option('--limit <n>', 'at most this many runs', '50')
621
- .option('--json', 'machine output: {runs: [...]}')
622
- .action(runsCommand);
623
- harness
624
- .command('stop <id>')
625
- .description('Stop the session that works an item; the run goes on, the item stays ready')
626
- .action((id) => console.log(stopRun(process.cwd(), id)));
627
- registerHold(harness);
628
- registerPlanReview(harness);
629
- registerChat(harness);
630
656
  }
631
657
 
632
658
  /** `gcf-harness plan-review`: the outside reviewer's pass of a plan (Hold-Plan d17). */
@@ -684,6 +710,13 @@ function registerRun(harness) {
684
710
  )
685
711
  .option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
686
712
  .option('--fresh', 'start new agent sessions: an interrupted one is not resumed')
713
+ .option(
714
+ '--allow <rule>',
715
+ 'go without this deny rule in force for this run only, as a refusal names it ' +
716
+ '(`edit: .claude/**`); repeat for more',
717
+ (v, all) => [...all, v],
718
+ [],
719
+ )
687
720
  .option(
688
721
  '--wait-limit',
689
722
  'a queued start: each session first waits while the usage limit is known to reset ahead',
@@ -884,21 +917,68 @@ export const itemLine = (i) =>
884
917
  i.process,
885
918
  i.shelved && `${i.shelved.id}'s work went to ${i.shelved.branch}`,
886
919
  i.returned && `its work came back with ${i.conflicts?.length ?? 0} conflict(s)`,
887
- i.build &&
888
- !i.build.ok &&
889
- !i.build.moved_on &&
890
- `no build to play: ${i.build.problem.split('\n')[0]}`,
891
- i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
920
+ ...buildNotes(i),
892
921
  ]
893
922
  .filter(Boolean)
894
- .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
923
+ .join(' — ') + lessonsNote(i);
924
+
925
+ /** What an item's line says of its build: none to play, or the files it changed. */
926
+ const buildNotes = (i) => [
927
+ i.build &&
928
+ !i.build.ok &&
929
+ !i.build.moved_on &&
930
+ `no build to play: ${i.build.problem.split('\n')[0]}`,
931
+ i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
932
+ ];
933
+
934
+ /** The lessons an item's sessions left, at its line's end; empty without any. */
935
+ const lessonsNote = (i) => (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
936
+
937
+ /**
938
+ * The deny rule the last refusal in an item's run chat named (`kind: pattern`), or null: the
939
+ * one `--allow` takes (docs/Permission-Stop-Plan.md, d5).
940
+ */
941
+ export function deniedRuleOf(projectDir, id) {
942
+ const file = chatOut(path.join(projectDir, '.gcf-session', 'runs'), id);
943
+ const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
944
+ const events = text.split('\n').flatMap((l) => {
945
+ try {
946
+ return l ? [JSON.parse(l)] : [];
947
+ } catch {
948
+ return [];
949
+ }
950
+ });
951
+ // The last session's last rule refusal, as the board's deniedRuleOf: none from an older
952
+ // session, none when two rules held (it names none), none of a group no run goes without.
953
+ const start = events.findLastIndex((e) => e.type === 'session' && e.kind === 'start');
954
+ const last = events
955
+ .slice(Math.max(0, start))
956
+ .findLast((e) => e.type === 'denied' && e.by === 'rule');
957
+ if (!last?.rule || NEVER_ALLOWED.includes(last.group)) return null;
958
+
959
+ return last.rule;
960
+ }
961
+
962
+ // The groups whose rules no run goes without: history, the operator's moves, the play build.
963
+ const NEVER_ALLOWED = ['git-history', 'git-destroy', 'human-moves', 'run-play'];
964
+
965
+ /** How to rerun an item a refused call blocked, without that rule, or null. */
966
+ export function rerunHint(projectDir, i) {
967
+ const rule = /^needs permission/.test(i.reason ?? '') ? deniedRuleOf(projectDir, i.id) : null;
968
+
969
+ return rule
970
+ ? ` rerun without it: ai-factory gcf unblock ${i.id}, then ` +
971
+ `ai-factory gcf-harness run ${i.id} --allow "${rule}"`
972
+ : null;
973
+ }
895
974
 
896
975
  /** The run report a human reads, then the playtest sheet of what now waits for play. */
897
976
  function printRun(r) {
898
977
  for (const o of r.orphans)
899
978
  console.log(`orphan ${o.id}: ${o.move ?? o.conflict ?? o.error ?? o.skipped}`);
900
979
  if (r.gate) console.error(`gcf gate: ${r.gate}`);
901
- for (const i of r.items) console.log(itemLine(i));
980
+ for (const i of r.items)
981
+ console.log([itemLine(i), rerunHint(process.cwd(), i)].filter(Boolean).join('\n'));
902
982
  for (const f of r.features ?? [])
903
983
  console.log(`feature ${f.id}: ${f.result}${f.error ? ` — ${f.error}` : ''}`);
904
984
 
@@ -910,16 +990,23 @@ const failed = (r) =>
910
990
  r.items.some((i) => ['conflict', 'error'].includes(i.result)) ||
911
991
  r.orphans.some((o) => o.conflict || o.error);
912
992
 
993
+ /** The minutes of `--timeout` and `--chat-timeout`; a bad option, `--mode` too, throws. */
994
+ function runMinutes(opts) {
995
+ const minutes = opts.timeout === undefined ? undefined : Number(opts.timeout);
996
+ if (minutes !== undefined && !(minutes > 0))
997
+ throw new Error('--timeout is a number of minutes above 0');
998
+ if (opts.mode && !['worktree', 'main'].includes(opts.mode))
999
+ throw new Error('--mode is worktree or main');
1000
+ const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
1001
+ if (answer !== null && !(answer >= 0))
1002
+ throw new Error('--chat-timeout is a number of minutes, 0 or more');
1003
+
1004
+ return { minutes, answer };
1005
+ }
1006
+
913
1007
  async function runItems(ids, opts) {
914
1008
  try {
915
- const minutes = opts.timeout === undefined ? undefined : Number(opts.timeout);
916
- if (minutes !== undefined && !(minutes > 0))
917
- throw new Error('--timeout is a number of minutes above 0');
918
- if (opts.mode && !['worktree', 'main'].includes(opts.mode))
919
- throw new Error('--mode is worktree or main');
920
- const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
921
- if (answer !== null && !(answer >= 0))
922
- throw new Error('--chat-timeout is a number of minutes, 0 or more');
1009
+ const { minutes, answer } = runMinutes(opts);
923
1010
  // The true-case path: Claude Code trusts a folder by its exact path, and a shell or a board
924
1011
  // may hand over c: for C:, which turns off every allow rule of the project.
925
1012
  const r = await run(realpathSync.native(process.cwd()), [...new Set(ids)], {
@@ -928,6 +1015,7 @@ async function runItems(ids, opts) {
928
1015
  timeoutMs: minutes === undefined ? undefined : minutes * 60_000,
929
1016
  mode: opts.mode,
930
1017
  fresh: Boolean(opts.fresh),
1018
+ allow: opts.allow,
931
1019
  waitLimit: Boolean(opts.waitLimit),
932
1020
  chat: opts.chat ? { answerMin: answer } : null,
933
1021
  model: opts.model,
@@ -45,13 +45,15 @@ export function planReview(projectDir, o) {
45
45
  ...['--output-schema', FINDINGS_SCHEMA, '-o', out],
46
46
  ];
47
47
  const res = spawnSync(exe, [...pre, ...args], {
48
+ windowsHide: true,
48
49
  cwd: projectDir,
49
50
  input: reviewPrompt(o.id, o.plan),
50
51
  encoding: 'utf8',
51
52
  timeout: o.timeoutMs ?? REVIEW_TIMEOUT_MS,
52
53
  shell,
53
54
  });
54
- if (res.error?.code === 'ETIMEDOUT') return { failed: 'the review timed out' };
55
+ if (/** @type {NodeJS.ErrnoException | undefined} */ (res.error)?.code === 'ETIMEDOUT')
56
+ return { failed: 'the review timed out' };
55
57
  // A flag the CLI no longer takes is named as it said it (Hold-Plan risk 11).
56
58
  if (res.status !== 0)
57
59
  return { failed: `codex exit ${res.status}: ${firstLine(res.stderr || res.stdout)}` };
@@ -66,7 +68,11 @@ export function planReview(projectDir, o) {
66
68
  function reviewerMissing(cfg, exe, pre, shell) {
67
69
  if (cfg.agent === 'none') return 'plan_review.agent is none';
68
70
  if (cfg.agent !== 'codex') return `no reviewer named ${cfg.agent}: only codex runs`;
69
- const version = spawnSync(exe, [...pre, '--version'], { encoding: 'utf8', shell });
71
+ const version = spawnSync(exe, [...pre, '--version'], {
72
+ windowsHide: true,
73
+ encoding: 'utf8',
74
+ shell,
75
+ });
70
76
 
71
77
  return version.error || version.status !== 0 ? 'no codex in PATH' : null;
72
78
  }