gcf-harness-aif-ext 0.28.0 → 0.30.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
@@ -176,7 +176,8 @@ Removal does not touch `.claude/settings.json`: delete the entries whose command
176
176
 
177
177
  - `gcf-harness hold <id>` holds an item: its session hands over at its next call, its work waits `ready`, and your Run goes on from the plan. `hold --project` holds the queue and the autopilot (your own Run still goes); `hold --release [<id>]` lets go.
178
178
  - Automation (`--wait-limit`, the autopilot's card sessions) keeps `quota_reserve_pct` of each usage window (`~/.gcf/settings.json`, 10): it waits for the 5-hour reset, and stops at the week's.
179
- - Planning and implementation are two sessions: `GCF_RUN_PHASE` comes from `gcf plan check`; `aif-implement` goes only on a converged plan. `gcf-harness plan-review <id>` is an outside reviewer's read-only pass (Codex CLI, `plan_review:`).
179
+ - `gcf-harness wake <id>` (or `--thread <t>`, or `--all`): the usage limit was reset early, so a live limit or reserve wait goes on now; it marks only a wait that lives. A fresh `/usage` reading under the limit wakes a wait too (automation reads it every 5 minutes; your own Run and a chat thread ask it themselves). A wake before the reset spends no try; the operator's wake lets the reserve go till that reset. The wait's chat says `limit {until, reserve?, pct?}` and, at its end, `limit_end {by}`. `gcf-harness chat say --json` prints `{id}` of the line it wrote.
180
+ - Planning and implementation are two sessions: `GCF_RUN_PHASE` comes from `gcf plan check`; `aif-implement` goes only on a converged plan. `gcf-harness codex-review <id> --kind plan|code --pass <k> --json` is a review pass by the Codex CLI, read-only, when row k of `review.plan|code` is Codex's: a family (`sol`, `astra`) is the newest listed slug of `codex debug models` (kept 6 h in `.gcf-session/codex-models.json`, `--bundled` when the live read fails); Claude rows are the session's subagents with the row's model and effort. A code review's rows over with a blocking finding: the code is committed and the card blocks (`stall.code`); under `--worktree` the trailer comes off first, so nothing merges until the human answers. Each session gets `GCF_RUN_BASE`, the commit its card's work started from.
180
181
 
181
182
  ## Docs
182
183
 
@@ -0,0 +1,125 @@
1
+ // `gcf-harness codex-review <id> --kind plan|code --pass <k>` (Operator-Tasks-Plan t2 d2): a review
2
+ // pass by the Codex CLI, read-only, when row k of `review.plan|code` is Codex's. Codex runs in its
3
+ // read-only sandbox: the audit holds by the sandbox, not by trust. The row's model is a family
4
+ // (`sol`), made the newest listed slug of the catalog, or a full slug as it is. Its answer is
5
+ // findings as JSON; with no Codex, or when it fails, the session's own subagent makes the pass
6
+ // (SKILL.md, steps 8-11 and 14-16).
7
+ import { spawnSync } from 'node:child_process';
8
+ import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
9
+ import os from 'node:os';
10
+ import path from 'node:path';
11
+ import { fileURLToPath } from 'node:url';
12
+ import { codexInstalled, codexModels, slugOf } from 'gcf-session';
13
+
14
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
15
+ export const FINDINGS_SCHEMA = path.join(HERE, 'codex-review.schema.json');
16
+ export const REVIEW_TIMEOUT_MS = 25 * 60_000;
17
+
18
+ const ANSWER = [
19
+ 'A finding is blocking when the work, as it stands, would be wrong, miss what the item asks,',
20
+ 'break what the code already does or a pillar; polish when it only reads better.',
21
+ 'Answer with the findings only, as the schema says.',
22
+ ];
23
+
24
+ /**
25
+ * The review's prompt: what to read and how to answer; the reviewer reads the files itself. The
26
+ * plan's carries aif-improve's criteria and the pillars' invariants; the code's the diff file and
27
+ * the pillars' review questions (SKILL.md steps 9, 15).
28
+ * @param {{id: string, kind: string, plan: string, diff?: string | null}} o
29
+ */
30
+ export function reviewPrompt({ id, kind, plan, diff }) {
31
+ if (kind === 'code')
32
+ return [
33
+ `Review the code change of work item ${id} before its commit. The diff is in ${diff};`,
34
+ `read it, the item gcf/work/${id}.md, its plan ${plan} and the code around the change.`,
35
+ 'Change nothing. Check that the change does what the item and the plan ask, breaks nothing,',
36
+ 'and is tested. Answer the review_question of each pillar in gcf/PILLARS.md over the diff:',
37
+ 'an answer that breaks a pillar is a blocking finding.',
38
+ ...ANSWER,
39
+ ].join('\n');
40
+
41
+ return [
42
+ `Audit the implementation plan of work item ${id}: ${plan}.`,
43
+ `Read the item gcf/work/${id}.md, the plan, and the code the plan names. Change nothing.`,
44
+ 'Apply the criteria of an improve pass: every task provable by a check, nothing the item asks',
45
+ 'missing, no wrong behavior, no conflict with a project rule. Check every task against the',
46
+ 'invariant of each pillar in gcf/PILLARS.md, and against the graveyard_hits lines of',
47
+ `\`ai-factory gcf context ${id} --json\`. Check each claim of the plan against the code.`,
48
+ ...ANSWER,
49
+ ].join('\n');
50
+ }
51
+
52
+ /**
53
+ * Run the pass: `{findings, by}`, `{skipped: why}` (the row is not Codex's, no Codex) or
54
+ * `{failed: why}`. `row` is `gcf review row`'s answer; `codex` the command (a test's fake).
55
+ * @param {string} projectDir
56
+ * @param {{row: any, codex?: string[], timeoutMs?: number}} o
57
+ */
58
+ export function codexReview(projectDir, o) {
59
+ const { row } = o;
60
+ if (row.row?.agent !== 'codex')
61
+ return { skipped: `pass ${row.pass} is ${row.by ?? 'no row'}'s: a subagent makes it` };
62
+ const cmd = o.codex
63
+ ? { exe: o.codex[0], pre: o.codex.slice(1), shell: false }
64
+ : { exe: 'codex', pre: [], shell: process.platform === 'win32' };
65
+ if (!codexInstalled(cmd)) return { skipped: 'no codex in PATH' };
66
+ // The catalog is read once a while for the project's runs (t2 d4).
67
+ const cache = path.join(projectDir, '.gcf-session', 'codex-models.json');
68
+ const slug = slugOf(codexModels({ cache, cmd }), row.row.model);
69
+ if (!slug) return { failed: `Codex lists no model of ${row.row.model}` };
70
+ const { effort } = row.row;
71
+
72
+ return { ...run(projectDir, cmd, { ...o, slug, effort }), by: `codex:${slug}:${effort}` };
73
+ }
74
+
75
+ /**
76
+ * `codex exec` in its read-only sandbox, the findings to a file.
77
+ * @param {string} projectDir
78
+ * @param {any} cmd
79
+ * @param {any} o
80
+ */
81
+ function run(projectDir, cmd, { row, slug, effort, timeoutMs }) {
82
+ const dir = mkdtempSync(path.join(os.tmpdir(), 'gcf-review-'));
83
+ const out = path.join(dir, 'findings.json');
84
+ try {
85
+ const args = [
86
+ ...['exec', '-', '-s', 'read-only', '-m', slug],
87
+ ...['-c', `model_reasoning_effort=${effort}`, '--ephemeral'],
88
+ ...['--output-schema', FINDINGS_SCHEMA, '-o', out],
89
+ ];
90
+ const res = spawnSync(cmd.exe, [...cmd.pre, ...args], {
91
+ windowsHide: true,
92
+ cwd: projectDir,
93
+ input: reviewPrompt({ ...row, diff: row.diff?.file ?? null }),
94
+ encoding: 'utf8',
95
+ timeout: timeoutMs ?? REVIEW_TIMEOUT_MS,
96
+ shell: cmd.shell,
97
+ });
98
+ if (/** @type {NodeJS.ErrnoException | undefined} */ (res.error)?.code === 'ETIMEDOUT')
99
+ return { failed: 'the review timed out' };
100
+ // A flag or a model the CLI does not take is named as it said it (Hold-Plan risk 11).
101
+ if (res.status !== 0)
102
+ return { failed: `codex exit ${res.status}: ${firstLine(res.stderr || res.stdout)}` };
103
+
104
+ return findingsOf(out);
105
+ } finally {
106
+ rmSync(dir, { recursive: true, force: true });
107
+ }
108
+ }
109
+
110
+ const firstLine = (text) =>
111
+ String(text ?? '')
112
+ .trim()
113
+ .split(/\r?\n/)[0] || 'no output';
114
+
115
+ /** The findings the reviewer wrote, or why they cannot be read. */
116
+ function findingsOf(file) {
117
+ try {
118
+ const x = JSON.parse(readFileSync(file, 'utf8'));
119
+ if (!Array.isArray(x?.findings)) return { failed: 'the answer has no findings list' };
120
+
121
+ return { findings: x.findings };
122
+ } catch (e) {
123
+ return { failed: `the answer is not JSON: ${e.message}` };
124
+ }
125
+ }
@@ -17,7 +17,7 @@ import { spawnSync } from 'node:child_process';
17
17
  import path from 'node:path';
18
18
  import { fileURLToPath } from 'node:url';
19
19
  import { metricsCommand, runsCommand } from './metrics.js';
20
- import { planReview } from './plan-review.js';
20
+ import { codexReview } from './codex-review.js';
21
21
  import {
22
22
  run,
23
23
  card,
@@ -32,6 +32,7 @@ import {
32
32
  loosePaths,
33
33
  queueOf,
34
34
  stopOf,
35
+ wakeOf,
35
36
  } from './run.js';
36
37
  import {
37
38
  CHAT_TIMEOUT_MIN,
@@ -41,6 +42,9 @@ import {
41
42
  chatOut,
42
43
  killTree,
43
44
  readText,
45
+ THREAD_ID,
46
+ threadWaits,
47
+ wakeThread,
44
48
  } from 'gcf-session';
45
49
 
46
50
  const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -197,22 +201,7 @@ function milestoneStop(report) {
197
201
  export function nextPlan(report, count, skip = []) {
198
202
  const stop = milestoneStop(report);
199
203
  if (stop) return { ids: [], mode: null, units: [], stop };
200
- const scope = inScope(report);
201
- const batch = [];
202
- const ready = (report.items ?? [])
203
- .filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
204
- .filter((i) => i.type !== 'release' && (!scope || scope.has(i.id)) && !skip.includes(i.id))
205
- .sort((a, b) => rank(a) - rank(b));
206
- // One run mode a batch: an autopilot starts it as one run, a main one in the checkout.
207
- let mode = null;
208
- for (const i of ready) {
209
- if (batch.length >= count) break;
210
- if (mode && (i.run_mode ?? mode) !== mode) continue;
211
- if (gate(report, [...batch, i.id]).pass) {
212
- batch.push(i.id);
213
- mode ??= i.run_mode ?? null;
214
- }
215
- }
204
+ const { batch, mode } = takeBatch(report, readyOf(report, inScope(report), skip), count);
216
205
 
217
206
  const building = (report.milestones ?? []).find((m) => m.name === report.build_milestone);
218
207
  const units = (building?.units ?? [])
@@ -232,6 +221,30 @@ export function nextPlan(report, count, skip = []) {
232
221
  return { ids: batch, mode, units, stop: empty };
233
222
  }
234
223
 
224
+ /** The ready items an autopilot may take, in scope and not skipped, by priority. */
225
+ const readyOf = (report, scope, skip) =>
226
+ (report.items ?? [])
227
+ .filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
228
+ .filter((i) => i.type !== 'release' && (!scope || scope.has(i.id)) && !skip.includes(i.id))
229
+ .sort((a, b) => rank(a) - rank(b));
230
+
231
+ /** Up to `count` of `ready`, each while the batch with it still passes the gate. */
232
+ function takeBatch(report, ready, count) {
233
+ const batch = [];
234
+ // One run mode a batch: an autopilot starts it as one run, a main one in the checkout.
235
+ let mode = null;
236
+ for (const i of ready) {
237
+ if (batch.length >= count) break;
238
+ if (mode && (i.run_mode ?? mode) !== mode) continue;
239
+ if (gate(report, [...batch, i.id]).pass) {
240
+ batch.push(i.id);
241
+ mode ??= i.run_mode ?? null;
242
+ }
243
+ }
244
+
245
+ return { batch, mode };
246
+ }
247
+
235
248
  /** The ids of `nextPlan`: what a board's Run offers. */
236
249
  export const nextBatch = (report, count) => nextPlan(report, count).ids;
237
250
 
@@ -295,7 +308,7 @@ export function withMainQueue(report, runs) {
295
308
  function auditReport() {
296
309
  // Re-enter the same ai-factory CLI that is running this command: no PATH or .cmd lookup.
297
310
  const args = [process.argv[1], 'gcf', 'audit', '--json'];
298
- const res = spawnSync(process.execPath, args, { encoding: 'utf8' });
311
+ const res = spawnSync(process.execPath, args, { windowsHide: true, encoding: 'utf8' });
299
312
  try {
300
313
  return withMainQueue(JSON.parse(res.stdout), path.join(process.cwd(), '.gcf-session', 'runs'));
301
314
  } catch (err) {
@@ -557,7 +570,48 @@ export function register(program) {
557
570
  .action(runGate);
558
571
 
559
572
  registerRun(harness);
573
+ registerNext(harness);
574
+ registerCard(harness);
575
+ harness
576
+ .command('metrics')
577
+ .description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
578
+ .option('--since <date>', 'only lines at or after this ISO date or time')
579
+ .option('--json', 'machine output')
580
+ .action(metricsCommand);
581
+ harness
582
+ .command('runs')
583
+ .description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
584
+ .option('--item <id>', 'only the runs that hold this item')
585
+ .option('--limit <n>', 'at most this many runs', '50')
586
+ .option('--json', 'machine output: {runs: [...]}')
587
+ .action(runsCommand);
588
+ harness
589
+ .command('stop <id>')
590
+ .description('Stop the session that works an item; the run goes on, the item stays ready')
591
+ .action((id) => console.log(stopRun(process.cwd(), id)));
592
+ harness
593
+ .command('wake [id]')
594
+ .description(
595
+ "The usage limit was reset early: an item's limit wait goes on now (--thread: a chat " +
596
+ "thread's; --all: every wait of the project)",
597
+ )
598
+ .option('--thread <t>', "a project chat thread's wait")
599
+ .option('--all', 'every live wait of the project: the limit is one for the account')
600
+ .action((id, o) => {
601
+ try {
602
+ console.log(wakeCommand(process.cwd(), id, o));
603
+ } catch (e) {
604
+ console.error(`gcf-harness wake: ${e.message}`);
605
+ process.exitCode = 1;
606
+ }
607
+ });
608
+ registerHold(harness);
609
+ registerCodexReview(harness);
610
+ registerChat(harness);
611
+ }
560
612
 
613
+ /** `gcf-harness next`: what can run together now, or an autopilot's plan. */
614
+ function registerNext(harness) {
561
615
  harness
562
616
  .command('next [count]')
563
617
  .description('The ready items that can run together now, by priority (the gate decides)')
@@ -588,6 +642,10 @@ export function register(program) {
588
642
  o.json ? JSON.stringify(ids) : ids.join('\n') || plan.stop?.text || 'nothing can run now',
589
643
  );
590
644
  });
645
+ }
646
+
647
+ /** `gcf-harness card`: design units into work, one agent session on main. */
648
+ function registerCard(harness) {
591
649
  harness
592
650
  .command('card <units...>')
593
651
  .description(
@@ -615,39 +673,21 @@ export function register(program) {
615
673
  process.exitCode = 1;
616
674
  }
617
675
  });
618
- harness
619
- .command('metrics')
620
- .description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
621
- .option('--since <date>', 'only lines at or after this ISO date or time')
622
- .option('--json', 'machine output')
623
- .action(metricsCommand);
624
- harness
625
- .command('runs')
626
- .description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
627
- .option('--item <id>', 'only the runs that hold this item')
628
- .option('--limit <n>', 'at most this many runs', '50')
629
- .option('--json', 'machine output: {runs: [...]}')
630
- .action(runsCommand);
631
- harness
632
- .command('stop <id>')
633
- .description('Stop the session that works an item; the run goes on, the item stays ready')
634
- .action((id) => console.log(stopRun(process.cwd(), id)));
635
- registerHold(harness);
636
- registerPlanReview(harness);
637
- registerChat(harness);
638
676
  }
639
677
 
640
- /** `gcf-harness plan-review`: the outside reviewer's pass of a plan (Hold-Plan d17). */
641
- function registerPlanReview(harness) {
678
+ /** `gcf-harness codex-review`: a review pass by the Codex CLI (Operator-Tasks-Plan t2 d2). */
679
+ function registerCodexReview(harness) {
642
680
  harness
643
- .command('plan-review <id>')
681
+ .command('codex-review <id>')
644
682
  .description(
645
- "An improve pass of the item's plan by an outside reviewer, read-only (plan_review: of " +
646
- 'gcf/config.yml; Codex CLI): its findings, or skipped or failed with why',
683
+ "Pass k of the item's plan or code review by the Codex CLI, read-only, when row k of " +
684
+ 'review.plan|code is Codex: its findings, or skipped or failed with why',
647
685
  )
648
- .option('--json', 'machine output: {findings} | {skipped} | {failed}')
686
+ .requiredOption('--kind <kind>', 'plan or code')
687
+ .requiredOption('--pass <k>', 'the pass number, 1 or more')
688
+ .option('--json', 'machine output: {findings, by} | {skipped} | {failed, by?}')
649
689
  .action((id, o) => {
650
- const r = reviewOf(process.cwd(), id);
690
+ const r = /** @type {any} */ (codexReviewOf(process.cwd(), id, o));
651
691
  if (o.json) return console.log(JSON.stringify(r));
652
692
  if (r.findings)
653
693
  for (const f of r.findings) console.log(`${f.severity}: ${f.where}: ${f.text}`);
@@ -731,6 +771,7 @@ function registerChat(harness) {
731
771
  .option('--text-file <path>', 'say: the message from a file, - for stdin')
732
772
  .option('--image <path>', 'say: a picture with it (png, jpg, gif, webp; repeat)', collect, [])
733
773
  .option('--answers-file <path>', 'answer: {"<question>": "<answer>"} from a file, - for stdin')
774
+ .option('--json', 'machine output: {id} of the line written (a message is known by it)')
734
775
  .action(chatAction);
735
776
  }
736
777
 
@@ -742,7 +783,7 @@ function collect(v, list) {
742
783
  function chatAction(id, action, words, opts) {
743
784
  try {
744
785
  const runs = path.join(process.cwd(), '.gcf-session', 'runs');
745
- chatInput(
786
+ const line = chatInput(
746
787
  process.cwd(),
747
788
  id,
748
789
  { action, words, ...opts },
@@ -751,7 +792,9 @@ function chatAction(id, action, words, opts) {
751
792
  read: readText,
752
793
  },
753
794
  );
754
- console.log('sent');
795
+ // A message's line has its id (AD-35); an answer or an interrupt has none.
796
+ const sent = line && 'id' in line ? line.id : null;
797
+ console.log(opts.json ? JSON.stringify({ id: sent }) : 'sent');
755
798
  } catch (e) {
756
799
  console.error(`gcf-harness chat: ${e.message}`);
757
800
  // 4: the input was good, writing it failed (a disk, a permission): the board answers 500.
@@ -811,17 +854,27 @@ export function itemLock(runs, id) {
811
854
  }
812
855
 
813
856
  /**
814
- * The review of item `id`'s plan with the project's `plan_review:`; GCF_CODEX (a JSON list: the
815
- * command and its first arguments) names another Codex, a test's fake.
857
+ * Pass k of item `id`'s review of `kind` by Codex: the row from the core (`gcf review row`, the
858
+ * code's diff written with it), then the pass. GCF_CODEX (a JSON list: the command and its first
859
+ * arguments) names another Codex, a test's fake.
816
860
  */
817
- function reviewOf(projectDir, id) {
818
- const board = json(cliCore(projectDir)(['board', '--json']), 'board');
819
- const item = board.items?.find((i) => i.id === id);
820
- if (!item) return { failed: `${id} is not a work item of the board` };
861
+ function codexReviewOf(projectDir, id, { kind, pass }) {
862
+ const diff = kind === 'code' ? ['--diff'] : [];
863
+ const r = cliCore(projectDir)([
864
+ 'review',
865
+ 'row',
866
+ id,
867
+ '--kind',
868
+ kind,
869
+ '--pass',
870
+ pass,
871
+ ...diff,
872
+ '--json',
873
+ ]);
874
+ if (!r.ok) return { failed: (r.err || r.out).trim() };
821
875
  const codex = process.env.GCF_CODEX ? JSON.parse(process.env.GCF_CODEX) : undefined;
822
- const plan = item.plan_file ?? `.ai-factory/plans/${id}.md`;
823
876
 
824
- return planReview(projectDir, { id, plan, config: board.plan_review ?? {}, codex });
877
+ return codexReview(projectDir, { row: json(r, 'review row'), codex });
825
878
  }
826
879
 
827
880
  /** The autopilot's stop while the project is held (Hold-Plan d9). */
@@ -872,6 +925,62 @@ export function holdCommand(projectDir, id, { project = false, release = false }
872
925
  : 'held the project: its sessions hand over, nothing queued or autopiloted starts';
873
926
  }
874
927
 
928
+ /**
929
+ * Whether item `id`'s run waits for the limit's reset now (t1 d1): its record names a reset and
930
+ * a live run holds its lock. A stopped or killed wait keeps its reset: the record alone is not.
931
+ */
932
+ function itemWaits(runs, id) {
933
+ try {
934
+ const rec = JSON.parse(readFileSync(path.join(runs, `${id}.agent.json`), 'utf8'));
935
+
936
+ return Boolean(rec.resets) && Boolean(itemLock(runs, id));
937
+ } catch {
938
+ return false;
939
+ }
940
+ }
941
+
942
+ /**
943
+ * `gcf-harness wake`: the mark that ends a limit wait early (Operator-Tasks-Plan t1 d4), only
944
+ * while one lives: an item's, a thread's (`thread`), or every one of the project (`all`).
945
+ * @param {string} projectDir
946
+ * @param {string | undefined} id
947
+ * @param {{thread?: string, all?: boolean}} [o]
948
+ */
949
+ export function wakeCommand(projectDir, id, { thread, all = false } = {}) {
950
+ if ([id, thread, all || undefined].filter(Boolean).length !== 1)
951
+ throw new Error('name one item, --thread <t> or --all');
952
+ const dir = path.resolve(projectDir);
953
+ if (thread) return wakeThread(dir, thread);
954
+ const runs = runsDir(dir);
955
+ if (id) {
956
+ if (!itemWaits(runs, id)) return `nothing waits for ${id}`;
957
+ writeFileSync(wakeOf(runs, id), `${new Date().toISOString()}\n`);
958
+
959
+ return `woke ${id}: its session goes on now`;
960
+ }
961
+
962
+ const items = safeList(runs)
963
+ .filter((n) => n.endsWith('.agent.json'))
964
+ .map((n) => n.slice(0, -'.agent.json'.length))
965
+ .filter((x) => itemWaits(runs, x));
966
+ for (const x of items) writeFileSync(wakeOf(runs, x), `${new Date().toISOString()}\n`);
967
+ const threads = safeList(path.join(dir, '.gcf-session', 'chats')).filter(
968
+ (t) => THREAD_ID.test(t) && threadWaits(dir, t),
969
+ );
970
+ for (const t of threads) wakeThread(dir, t);
971
+ const woke = [...items, ...threads.map((t) => `thread ${t}`)];
972
+
973
+ return woke.length ? `woke ${woke.join(', ')}` : 'nothing waits';
974
+ }
975
+
976
+ const safeList = (d) => {
977
+ try {
978
+ return readdirSync(d);
979
+ } catch {
980
+ return [];
981
+ }
982
+ };
983
+
875
984
  export function stopRun(projectDir, id, core = cliCore(projectDir)) {
876
985
  const runs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
877
986
  const lockFor = () => itemLock(runs, id);
@@ -899,14 +1008,22 @@ export const itemLine = (i) =>
899
1008
  i.process,
900
1009
  i.shelved && `${i.shelved.id}'s work went to ${i.shelved.branch}`,
901
1010
  i.returned && `its work came back with ${i.conflicts?.length ?? 0} conflict(s)`,
902
- i.build &&
903
- !i.build.ok &&
904
- !i.build.moved_on &&
905
- `no build to play: ${i.build.problem.split('\n')[0]}`,
906
- i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
1011
+ ...buildNotes(i),
907
1012
  ]
908
1013
  .filter(Boolean)
909
- .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
1014
+ .join(' — ') + lessonsNote(i);
1015
+
1016
+ /** What an item's line says of its build: none to play, or the files it changed. */
1017
+ const buildNotes = (i) => [
1018
+ i.build &&
1019
+ !i.build.ok &&
1020
+ !i.build.moved_on &&
1021
+ `no build to play: ${i.build.problem.split('\n')[0]}`,
1022
+ i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
1023
+ ];
1024
+
1025
+ /** The lessons an item's sessions left, at its line's end; empty without any. */
1026
+ const lessonsNote = (i) => (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
910
1027
 
911
1028
  /**
912
1029
  * The deny rule the last refusal in an item's run chat named (`kind: pattern`), or null: the
@@ -964,16 +1081,23 @@ const failed = (r) =>
964
1081
  r.items.some((i) => ['conflict', 'error'].includes(i.result)) ||
965
1082
  r.orphans.some((o) => o.conflict || o.error);
966
1083
 
1084
+ /** The minutes of `--timeout` and `--chat-timeout`; a bad option, `--mode` too, throws. */
1085
+ function runMinutes(opts) {
1086
+ const minutes = opts.timeout === undefined ? undefined : Number(opts.timeout);
1087
+ if (minutes !== undefined && !(minutes > 0))
1088
+ throw new Error('--timeout is a number of minutes above 0');
1089
+ if (opts.mode && !['worktree', 'main'].includes(opts.mode))
1090
+ throw new Error('--mode is worktree or main');
1091
+ const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
1092
+ if (answer !== null && !(answer >= 0))
1093
+ throw new Error('--chat-timeout is a number of minutes, 0 or more');
1094
+
1095
+ return { minutes, answer };
1096
+ }
1097
+
967
1098
  async function runItems(ids, opts) {
968
1099
  try {
969
- const minutes = opts.timeout === undefined ? undefined : Number(opts.timeout);
970
- if (minutes !== undefined && !(minutes > 0))
971
- throw new Error('--timeout is a number of minutes above 0');
972
- if (opts.mode && !['worktree', 'main'].includes(opts.mode))
973
- throw new Error('--mode is worktree or main');
974
- const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
975
- if (answer !== null && !(answer >= 0))
976
- throw new Error('--chat-timeout is a number of minutes, 0 or more');
1100
+ const { minutes, answer } = runMinutes(opts);
977
1101
  // The true-case path: Claude Code trusts a folder by its exact path, and a shell or a board
978
1102
  // may hand over c: for C:, which turns off every allow rule of the project.
979
1103
  const r = await run(realpathSync.native(process.cwd()), [...new Set(ids)], {
@@ -13,6 +13,8 @@ export const REVIEW = 'gcf review';
13
13
  /** @type {[RegExp, string][]} */
14
14
  const BASH = [
15
15
  [/\bai-factory\s+gcf\s+plan\s+check\b/, 'plan-check'],
16
+ // The code's review by Codex (Operator-Tasks-Plan t2 d2); the plan's is no step of the chat.
17
+ [/\bai-factory\s+gcf-harness\s+codex-review\b[^|&;]*--kind[\s=]+code\b/, 'review'],
16
18
  [/\bai-factory\s+gcf\s+verify\b/, 'dod'],
17
19
  [/\bgit\s+commit\b/, 'commit'],
18
20
  [/\bai-factory\s+gcf\s+(submit|close|block|decide)\b/, 'move'],
@@ -96,7 +98,13 @@ export function milestones({ verifyLog, item, head = () => null, worktree = fals
96
98
  const step = stepOf(e);
97
99
  if (step?.step === 'move' && worktree) return [];
98
100
  if (step && step.step !== 'plan')
99
- calls.set(e.id, { ...step, at: Date.now(), head: step.step === 'commit' ? head() : null });
101
+ calls.set(e.id, {
102
+ ...step,
103
+ at: Date.now(),
104
+ head: step.step === 'commit' ? head() : null,
105
+ // A shell in the background answers at once: its step ends with its task (t2 d2).
106
+ background: e.kind === 'shell' && e.input?.run_in_background === true,
107
+ });
100
108
 
101
109
  return [];
102
110
  };
@@ -114,6 +122,7 @@ export function milestones({ verifyLog, item, head = () => null, worktree = fals
114
122
 
115
123
  const ended = (e) => {
116
124
  const call = calls.get(e.id);
125
+ if (call?.background) return [];
117
126
  calls.delete(e.id);
118
127
  if (!call || call.step === 'plan-check') {
119
128
  if (call) w.checks++;
@@ -121,12 +130,23 @@ export function milestones({ verifyLog, item, head = () => null, worktree = fals
121
130
  return [];
122
131
  }
123
132
 
124
- const { at: _, head: __, ...step } = call;
133
+ const { at: _, head: __, background: ___, ...step } = call;
125
134
  const ok = okOf(call, e);
126
135
 
127
136
  return [{ type: 'step', ...step, ok, ...(ok === false ? { text: firstLine(e.text) } : {}) }];
128
137
  };
129
138
 
139
+ /** A background shell's step at its task's end: `completed` is ok, else its summary says why. */
140
+ const backgroundEnded = (e) => {
141
+ const call = e.call ? calls.get(e.call) : null;
142
+ if (!call?.background) return [];
143
+ calls.delete(/** @type {string} */ (e.call));
144
+ const { at: _, head: __, background: ___, ...step } = call;
145
+ const ok = e.status === 'completed';
146
+
147
+ return [{ type: 'step', ...step, ok, ...(ok ? {} : { text: firstLine(e.summary ?? '') }) }];
148
+ };
149
+
130
150
  return {
131
151
  // Kept for its callers: the plan's step comes from the phase's end now, not from a call.
132
152
  skipPlan: () => {},
@@ -144,6 +164,7 @@ export function milestones({ verifyLog, item, head = () => null, worktree = fals
144
164
  // A subagent's calls (a reviewer running the tests) are its own, not the item's steps.
145
165
  if (!e || e.sub) return [];
146
166
  if (e.type === 'tool_call') return called(e);
167
+ if (e.type === 'task' && e.phase === 'end') return backgroundEnded(e);
147
168
 
148
169
  return e.type === 'tool_result' ? ended(e) : [];
149
170
  },