@oscaner-skills/cdd-engine 3.0.1 → 4.0.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.
@@ -15,12 +15,12 @@
15
15
  // bare functions.
16
16
  import process from "node:process";
17
17
  import { printParseErrorCode } from "jsonc-parser";
18
- import { ConfigLoader } from "../infra/config.js";
19
18
  import { TemplateAssembler } from "../render/templates.js";
20
19
  import { HandoffSchema } from "../session/handoff-schema.js";
21
20
  import { RoundNaming } from "../session/round-naming.js";
22
21
  import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
23
22
  import { TerminationPolicy, Terminator, } from "./termination.js";
23
+ import { Words } from "./words.js";
24
24
  /** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
25
25
  * non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
26
26
  * channel; the child's Return is prose, never the round's content). */
@@ -39,11 +39,14 @@ const STDOUT_TAIL_MAX = 40;
39
39
  export class CliLifecycle {
40
40
  #env;
41
41
  #sync;
42
- #config;
43
42
  #template;
44
43
  #io;
45
44
  #scene;
46
45
  #reviews;
46
+ /** The single word table (the promotion WARN wording + its station) — one instance,
47
+ * injected at the composition root, so the lifecycle never re-types a user-facing
48
+ * line. */
49
+ #words;
47
50
  /** The round-naming single source (P11 T4) — every prescribed artifact name of a
48
51
  * frame derives here (the report/evidence/brief names + the family op), so the
49
52
  * lifecycle and the dry-run preview name the same artifacts by one rule. */
@@ -60,8 +63,8 @@ export class CliLifecycle {
60
63
  this.#scene = opts.scene;
61
64
  this.#naming = new RoundNaming(opts.scene.workspace);
62
65
  this.#sync = opts.sync ?? new Terminator();
63
- this.#config = opts.config ?? new ConfigLoader();
64
66
  this.#template = opts.template ?? new TemplateAssembler();
67
+ this.#words = opts.words ?? new Words();
65
68
  this.#io = opts.io ?? {
66
69
  stdout: (t) => process.stdout.write(t),
67
70
  stderr: (t) => process.stderr.write(t),
@@ -120,7 +123,17 @@ export class CliLifecycle {
120
123
  // cause. `termination !== null` → the round concludes TIMEOUT (the words table's
121
124
  // status is already there), the reason rides the CDD_BLOCKED channel, and the
122
125
  // failure face (no `next:` line) follows from the status alone.
126
+ //
127
+ // The ONE promotion exception (D53 Q12's deliberate narrowing): a terminated
128
+ // REVIEW round whose draft already sits on disk — valid against the findings
129
+ // schema and carrying at least one finding — has done its work; its conclusion is
130
+ // derived from the handoff, never from the termination word (termination ⊥
131
+ // conclusion). Every other terminated round keeps the TIMEOUT failure face.
123
132
  if (result.termination !== null) {
133
+ const draft = this.#probeDraft(frame);
134
+ if (draft !== null) {
135
+ return this.#promote(frame, draft, result.termination, result);
136
+ }
124
137
  return this.#reject(frame, this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params), `child ${cliName} was terminated: ${result.termination.cause}`,
125
138
  // the terminated round's OWN death facts — the termination rides whole
126
139
  // (cause + last sample), the signalled child's code is null verbatim
@@ -235,6 +248,13 @@ export class CliLifecycle {
235
248
  : frame.type === "plan" || frame.type === "branch"
236
249
  ? this.#rel(scene.specLink ?? "")
237
250
  : "",
251
+ // The parent charter of the spec the face reads (INPUT_OVERALL) — the same
252
+ // value condition as INPUT_SPEC, one face (spec = its own `program:`; plan/
253
+ // branch = the same-slug identity doc's `program:`); empty off those faces and
254
+ // when the spec names no program (the assembler drops the empty slot).
255
+ INPUT_OVERALL: frame.type === "spec" || frame.type === "plan" || frame.type === "branch"
256
+ ? this.#rel(scene.overallLink ?? "")
257
+ : "",
238
258
  // The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
239
259
  // from the base artifact at dispatch; empty off those faces (spec/plan reviews
240
260
  // carry none, and the empty slot is dropped by the assembler).
@@ -291,6 +311,57 @@ export class CliLifecycle {
291
311
  // -------------------------------------------------------------------------
292
312
  // the read-back reconstruct (§3.6) — the draft is the round's content
293
313
  // -------------------------------------------------------------------------
314
+ /** The ONE draft-read point — the frame's handoff draft read with the lenient
315
+ * child-authored dialect (D39). The reconstruct reports its tri-state outcome;
316
+ * the terminated-round probe only asks "is there a promotable draft?". */
317
+ #readDraft(frame) {
318
+ const op = this.#opOf(frame);
319
+ return this.#scene.workspace.readJsonLenient(this.#scene.ledger.handoffName(op, frame.type, frame.params));
320
+ }
321
+ /** The non-rejecting draft probe of the termination branch — a terminated REVIEW
322
+ * round's draft is promotable iff it exists, parses, passes the judge plane's schema,
323
+ * and carries at least one finding. Returns the validated draft (the promotion
324
+ * then rides the reconstruct's existing validation/persistence/conclusion path) or
325
+ * null (the round keeps the TIMEOUT failure face). It calls no `#reject` and
326
+ * produces no outcome — a probe is a question, never a verdict. Implement/fix
327
+ * rounds are outside the promotion domain (their `op` is not the review family). */
328
+ #probeDraft(frame) {
329
+ const op = this.#opOf(frame);
330
+ if (op !== "review")
331
+ return null;
332
+ const plane = HandoffSchema.planeOf(op);
333
+ const read = this.#readDraft(frame);
334
+ if (read.kind !== "ok")
335
+ return null;
336
+ const draft = read.value;
337
+ if (this.#handoffSchema.violations(plane, draft).length > 0)
338
+ return null;
339
+ const findings = Array.isArray(draft.findings) ? draft.findings : [];
340
+ return findings.length >= 1 ? draft : null;
341
+ }
342
+ /** Promote a terminated review round whose draft is valid and carries findings —
343
+ * the terminal ⊥ conclusion exception (D53 Q12): the conclusion derives from the
344
+ * handoff, never from the termination word. The crash record still lands
345
+ * (`promoted: true`, carrying the termination's `idleMs`/last sample), and the
346
+ * lifecycle emits the ONE `CDD_WARN` line — the CLI layer emits none. The outcome
347
+ * is the ordinary read-back outcome (carrier + findings + derived status) plus the
348
+ * termination fact, so the bookkeep records the round and the route derives
349
+ * normally. */
350
+ #promote(frame, draft, termination, dead) {
351
+ const op = this.#opOf(frame);
352
+ const path = this.#scene.ledger.handoffPath(op, frame.type, frame.params);
353
+ const outcome = this.#reconstruct(frame, draft);
354
+ this.#writeCrash(frame, path, `child was terminated: ${termination.cause}`, { exitCode: dead.code, cause: termination.cause, termination }, true);
355
+ const findings = outcome.findings ?? [];
356
+ const text = this.#words.promotionWarning({
357
+ cause: termination.cause,
358
+ idleMs: termination.idleMs,
359
+ verdict: termination.lastSample?.verdict ?? "none",
360
+ count: findings.length,
361
+ });
362
+ this.#io.stderr(`${this.#words.station("warn")} ${text}\n`);
363
+ return { ...outcome, termination };
364
+ }
294
365
  /** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
295
366
  * content source of truth: read it, validate it against the mode's writable
296
367
  * subset (projection ② of session/handoff-schema.ts — the SAME declared objects
@@ -299,62 +370,77 @@ export class CliLifecycle {
299
370
  * remains the carrier's single author). A missing or schema-violating draft →
300
371
  * BLOCK over the CDD_BLOCKED channel + a crash record + the draft untouched
301
372
  * (on failure, no overwrite — the child's work is never clobbered; resume re-runs the same
302
- * command, which re-offers the round). The test-evidence file (task-family work
303
- * rounds only) is read back with the same stakes: a missing/violating file
373
+ * command, which re-offers the round). The test-evidence file (work-plane wave /
374
+ * branch rounds only) is read back with the same stakes: a missing/violating file
304
375
  * rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
305
- * bad), the second fix for a prose-only claim. */
306
- #reconstruct(frame) {
376
+ * bad), the second fix for a prose-only claim.
377
+ *
378
+ * `prefetched` is the terminated-review promotion's already-probed draft — the ONE
379
+ * draft parse stays single-sourced (`#readDraft`), and the promotion rides this
380
+ * same validation/persistence/conclusion path rather than a second implementation. */
381
+ #reconstruct(frame, prefetched) {
307
382
  const scene = this.#scene;
308
383
  const op = this.#opOf(frame);
309
- const face = this.#familyOf(op, frame.type).schema ?? "work";
384
+ const plane = HandoffSchema.planeOf(op);
310
385
  const schema = this.#handoffSchema;
311
386
  const path = scene.ledger.handoffPath(op, frame.type, frame.params);
312
- // The tri-state draft read — a MISSING draft ("never written") and a MALFORMED one
313
- // (present but unparseable JSON) are different facts: the rejection reports each
314
- // truly, so a corrupt draft is never misreported as "not written" (D27). The read
315
- // is LENIENT (D39): the draft is a child-LLM-authored carrier, and a trailing comma
316
- // (a routine model slip) must not void the whole round — jsonc-parser tolerates the
317
- // lenient dialect while a real break (a missing brace, …) still reports malformed.
318
- const draftRead = scene.workspace.readJsonLenient(scene.ledger.handoffName(op, frame.type, frame.params));
319
- if (draftRead.kind === "missing") {
320
- return this.#reject(frame, path, `the handoff draft was not written at ${path}`);
387
+ let draft;
388
+ if (prefetched !== undefined) {
389
+ draft = prefetched;
321
390
  }
322
- if (draftRead.kind === "malformed") {
323
- // The lenient face carries the parser's precise error codes (D39) — surface
324
- // them in the rejection so a genuinely corrupt draft is diagnosable, not just
325
- // "malformed".
326
- const codes = (draftRead.errors ?? [])
327
- .map((error) => printParseErrorCode(error.error))
328
- .join(", ");
329
- const detail = codes === "" ? "" : ` (${codes})`;
330
- return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
391
+ else {
392
+ // The tri-state draft read — a MISSING draft ("never written") and a MALFORMED
393
+ // one (present but unparseable JSON) are different facts: the rejection reports
394
+ // each truly, so a corrupt draft is never misreported as "not written" (D27).
395
+ // The read is LENIENT (D39): the draft is a child-LLM-authored carrier, and a
396
+ // trailing comma (a routine model slip) must not void the whole round —
397
+ // jsonc-parser tolerates the lenient dialect while a real break (a missing
398
+ // brace, …) still reports malformed.
399
+ const draftRead = this.#readDraft(frame);
400
+ if (draftRead.kind === "missing") {
401
+ return this.#reject(frame, path, `the handoff draft was not written at ${path}`, {
402
+ exitCode: 0,
403
+ cause: "handoff-absent",
404
+ termination: null,
405
+ });
406
+ }
407
+ if (draftRead.kind === "malformed") {
408
+ // The lenient face carries the parser's precise error codes (D39) — surface
409
+ // them in the rejection so a genuinely corrupt draft is diagnosable, not just
410
+ // "malformed".
411
+ const codes = (draftRead.errors ?? [])
412
+ .map((error) => printParseErrorCode(error.error))
413
+ .join(", ");
414
+ const detail = codes === "" ? "" : ` (${codes})`;
415
+ return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
416
+ }
417
+ draft = draftRead.value;
331
418
  }
332
- const draft = draftRead.value;
333
- const problems = schema.violations(face, draft);
419
+ const problems = schema.violations(plane, draft);
334
420
  if (problems.length > 0) {
335
- return this.#reject(frame, path, `the handoff draft at ${path} violates the ${face} schema: ${problems.join("; ")}`);
421
+ return this.#reject(frame, path, `the handoff draft at ${path} violates the ${plane} schema: ${problems.join("; ")}`);
336
422
  }
337
- // T2 — the face-aware read: the findings face ALONE reads `draft.findings` (its
338
- // own declared required field — rolled up to the conclusion); the work face
339
- // derives its status from the draft's declared status, never the findings plane
423
+ // T2 — the plane-aware read: the judge plane ALONE reads `draft.findings` (its
424
+ // own declared required field — rolled up to the conclusion); the work plane
425
+ // derives its status from the draft's declared status, never the findings slot
340
426
  // (the work writable subset declares no findings field — zero findings read).
341
427
  // The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
342
428
  // legs read too — the reconstruct never rules a work status by a second path.
343
- const findings = face === "findings" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
344
- // A validated draft's conclusion is total: the findings face rolls up its own
345
- // required findings, and the work face's `status` passed the `required` gate above
429
+ const findings = plane === "judge" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
430
+ // A validated draft's conclusion is total: the judge plane rolls up its own
431
+ // required findings, and the work plane's `status` passed the `required` gate above
346
432
  // — so the `?? "BLOCKED"` never fires here (a work draft without a status never
347
433
  // reaches this line; the absent→undefined case exists only for on-disk legacy
348
434
  // carriers the ledger reads back, never a schema-validated draft).
349
- let status = schema.conclusionOf(face, draft) ?? "BLOCKED";
435
+ let status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
350
436
  let reason = null;
351
- // The evidence gate (v1.9) — the work faces (implement/fix task+branch) write
352
- // the canonical `{family-prefix}-{key}-test-evidence.json` under the workspace
353
- // (§3.7 naming: tasks- for the task families, branch- for the branch fix); the
354
- // docs faces (review/docs-fix) carry no evidence file. The read-back is REAL — a
355
- // missing/malformed/schema-violating file rewrites the draft to BLOCKED (each
356
- // cause reported truly — the tri-state read, D27).
357
- if (face === "work") {
437
+ // The evidence gate (v1.9) — the work plane's wave / branch rounds (implement/fix
438
+ // task+branch) write the canonical `{family-prefix}-{key}-test-evidence.json` under
439
+ // the workspace (§3.7 naming: tasks- for the task families, branch- for the branch
440
+ // fix); the doc rounds (review/docs-fix) carry no evidence file. The read-back is
441
+ // REAL — a missing/malformed/schema-violating file rewrites the draft to BLOCKED
442
+ // (each cause reported truly — the tri-state read, D27).
443
+ if (plane === "work" && (frame.type === "wave" || frame.type === "branch")) {
358
444
  const evidenceName = this.#naming.evidenceName(frame);
359
445
  const evidencePath = scene.workspace.resolve(evidenceName);
360
446
  const evidenceRead = scene.workspace.readJson(evidenceName);
@@ -377,17 +463,18 @@ export class CliLifecycle {
377
463
  }
378
464
  return {
379
465
  status,
380
- findings: face === "findings" ? schema.findingsOf(findings) : undefined,
381
- carrier: this.#materialize(frame, face, draft, status, reason),
466
+ findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
467
+ carrier: this.#materialize(frame, plane, draft, status, reason),
382
468
  };
383
469
  }
384
470
  /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
385
471
  * same-command resume's decision source: the attempted handoff + the resume
386
472
  * command) + NO carrier (the bookkeep leaves the draft untouched). The crash
387
- * record carries the caller's REAL death facts: an absent draft/schema violation
388
- * is the read-back face (exit 0 · `contract-violation` — the defaults), a dead
473
+ * record carries the caller's REAL death facts: an absent draft is the
474
+ * `handoff-absent` read-back face (exit 0), a present-but-unqualified draft
475
+ * (malformed JSON / schema) is `contract-violation` (the default), a dead
389
476
  * child passes its own exit code + `child-exit`, and a terminated round passes
390
- * its whole `termination` fact (cause + last sample) — one record shape, three
477
+ * its whole `termination` fact (cause + last sample) — one record shape, four
391
478
  * truthful callers (the record is the postmortem artifact; a misreported death
392
479
  * sends a maintainer hunting the wrong fault).
393
480
  *
@@ -400,8 +487,29 @@ export class CliLifecycle {
400
487
  cause: "contract-violation",
401
488
  termination: null,
402
489
  }) {
403
- this.#io.stderr(`CDD_BLOCKED: ${reason}\n`);
490
+ this.#writeCrash(frame, path, reason, death, false);
491
+ // A terminated round extends its ONE CDD_BLOCKED line with the idle time and the
492
+ // last sample's verdict (the crash record carries the full sample).
493
+ const detail = death.termination === null
494
+ ? ""
495
+ : this.#words.terminationDetail({
496
+ idleMs: death.termination.idleMs,
497
+ verdict: death.termination.lastSample?.verdict ?? "none",
498
+ });
499
+ this.#io.stderr(`CDD_BLOCKED: ${reason}${detail}\n`);
500
+ if (death.termination === null)
501
+ return { status: "BLOCKED" };
502
+ return { status: "TIMEOUT", termination: death.termination };
503
+ }
504
+ /** Write the lane's crash record — the postmortem artifact and same-command
505
+ * resume's decision source. One writer serves both the rejection face
506
+ * (`promoted: false`) and the termination branch's promotion (`promoted: true`):
507
+ * the record shape is identical, only the promotion fact differs. */
508
+ #writeCrash(frame, path, reason, death, promoted) {
404
509
  const op = this.#opOf(frame);
510
+ // The cause rides the termination fact when one is present (one of the three
511
+ // causes or the `unknown` fallback); without it, the caller's own cause.
512
+ const cause = death.termination?.cause ?? death.cause;
405
513
  this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
406
514
  exitCode: death.exitCode,
407
515
  stderrTail: [reason],
@@ -410,22 +518,26 @@ export class CliLifecycle {
410
518
  // shape (never the absolute `handoffPath` syscall form — §2.7).
411
519
  attemptedHandoff: this.#rel(path),
412
520
  next: this.#resumeOf(frame),
413
- // The cause rides the termination fact when one is present (one of the three
414
- // causes or the `unknown` fallback); without it, the caller's own cause.
415
- cause: death.termination?.cause ?? death.cause,
521
+ cause,
416
522
  // The last sample rides WITH the termination (in memory, zero re-read of the
417
523
  // heartbeat file) — null on every non-terminated face.
418
524
  lastSample: death.termination?.lastSample ?? null,
525
+ promoted,
526
+ idleMs: death.termination?.idleMs ?? null,
419
527
  });
420
- return { status: death.termination === null ? "BLOCKED" : "TIMEOUT" };
528
+ // P14 — the sole contractViolationCount write seam: observe the FINAL crash
529
+ // cause (termination override wins). Never keyed off status === "BLOCKED".
530
+ if (cause === "handoff-absent" || cause === "contract-violation") {
531
+ this.#scene.ledger.incrementContractViolationCount();
532
+ }
421
533
  }
422
534
  /** Build the final carrier — the validated writable fields from the draft (the
423
535
  * engine-seated identity rides the canonical file name, never inline: phase/tasks
424
536
  * are not declared and never written — v1.30), persisted by the bookkeep
425
537
  * full-replace at the SAME path (agent draft → finalized). The evidence override
426
- * rewrites the status to BLOCKED + a failure_category + the reason note (the
427
- * child's work preserved, marked bad). */
428
- #materialize(frame, face, draft, status, reason) {
538
+ * rewrites the status to BLOCKED + the reason note (the child's work preserved,
539
+ * marked bad). */
540
+ #materialize(frame, plane, draft, status, reason) {
429
541
  const ledger = this.#scene.ledger;
430
542
  const notes = [];
431
543
  // The §8.7 classification ruling — the SAME judgment the read-back validator makes
@@ -433,42 +545,40 @@ export class CliLifecycle {
433
545
  // AT MOST ONE WARN on the carrier's notes (auditable, non-interrupting — replacing
434
546
  // the retired "BLOCK + crash-resume + reopen" chain). The engine stays the carrier's
435
547
  // single author; a child's stray key is surfaced, not obeyed.
436
- const dropped = this.#handoffSchema.droppedKeys(face, draft);
548
+ const dropped = this.#handoffSchema.droppedKeys(plane, draft);
437
549
  if (dropped.length > 0) {
438
550
  notes.push(`dropped non-declared draft field(s): ${dropped.join(", ")} — engine-reserved, never written`);
439
551
  }
440
- // The per-face carrier — buildHandoff's typed overloads: the findings face REQUIRES
552
+ // The per-plane carrier — buildHandoff's typed overloads: the judge plane REQUIRES
441
553
  // its findings payload (the schema-required field — cli.test pins the review
442
- // carrier's findings + status), the work face builds a findings-FREE typed carrier
443
- // (the work writable subset declares no findings field — the materialized work
444
- // carrier carries zero findings keys). `Record<string, unknown>` local: the round
445
- // conclusion (status — a RoundStatus, wider than the carrier's declared union) and
446
- // the engine's extended fields ride the caller's set below.
447
- const carrier = face === "findings"
448
- ? ledger.buildHandoff("findings", {
554
+ // carrier's findings + status), the work plane builds a findings-FREE typed carrier
555
+ // (the work writable subset declares no findings field — a docs-fix draft's residual
556
+ // findings are dropped, never materialized). `Record<string, unknown>` local: the
557
+ // round conclusion (status — a RoundStatus, wider than the carrier's declared union)
558
+ // and the engine's extended fields ride the caller's set below.
559
+ const carrier = plane === "judge"
560
+ ? ledger.buildHandoff("judge", {
449
561
  artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
450
562
  findings: this.#findingsList(draft.findings),
451
563
  })
452
564
  : ledger.buildHandoff("work", {
453
565
  artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
454
566
  });
455
- // The work face ALONE persists the round conclusion — it is the child's own
456
- // declared status (the schema enum pinned it to APPROVED | BLOCKED). The findings
457
- // face holds NO status field: its conclusion is DERIVED at judgment time
458
- // (`HandoffSchema.conclusionOf("findings", carrier)` → rollup(findings)), so the
459
- // persisted findings carrier stays the pure declaration plane
567
+ // The work plane ALONE persists the round conclusion — it is the child's own
568
+ // declared status (the schema enum pinned it to APPROVED | BLOCKED). The judge
569
+ // plane holds NO status field: its conclusion is DERIVED at judgment time
570
+ // (`HandoffSchema.conclusionOf("judge", carrier)` → rollup(findings)), so the
571
+ // persisted judge carrier stays the pure declaration plane
460
572
  // (findings/artifacts/notes) and a fix child's INPUT_REVIEWS carrier is
461
- // status-free (the judgment face is perpendicular to the input face · D27).
573
+ // status-free (the judgment plane is perpendicular to the input plane · D27).
462
574
  const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
463
- if (face === "work") {
575
+ if (plane === "work") {
464
576
  carrier.status = status;
465
- if (typeof draft.failure_category === "string")
466
- carrier.failure_category = draft.failure_category;
467
- // The evidence-contract override (work faces only — the evidence gate reads a
468
- // work round's evidence file) rewrites the persisted conclusion to BLOCKED.
577
+ // The evidence-contract override (work-plane wave / branch rounds only — the
578
+ // evidence gate reads that round's evidence file) rewrites the persisted
579
+ // conclusion to BLOCKED.
469
580
  if (reason !== null) {
470
581
  carrier.status = "BLOCKED";
471
- carrier.failure_category = "evidence-contract";
472
582
  draftNotes.push(reason);
473
583
  }
474
584
  }
@@ -526,23 +636,13 @@ export class CliLifecycle {
526
636
  }
527
637
  /** The `## Handoff schema` section value — the mode's writable-subset fence
528
638
  * (projection ①; byte-fixed per mode so the prompt's fixed prefix stays
529
- * cache-friendly). The family's `schema` field selects the face (§3.6: work →
530
- * carrier + evidence fence for the implement/fix modes; findings → the review /
531
- * docs-fix fence only). */
639
+ * cache-friendly). The op-derived plane selects the subset: work → carrier +
640
+ * evidence fence on the wave / branch rounds; judge → the review fence only. */
532
641
  #schemaText(frame) {
533
- const op = this.#opOf(frame);
534
- const face = this.#familyOf(op, frame.type).schema ?? "work";
535
- const evidence = face === "work";
642
+ const plane = HandoffSchema.planeOf(this.#opOf(frame));
643
+ const evidence = plane === "work" && (frame.type === "wave" || frame.type === "branch");
536
644
  const prefix = evidence ? this.#naming.prefix(frame) : "tasks";
537
- return this.#handoffSchema.schemaText(face, evidence, prefix);
538
- }
539
- /** The op.type family record — the engine-config handoff namespace single truth
540
- * (loud on an unknown family: never a second naming table). */
541
- #familyOf(op, type) {
542
- const family = this.#config.engineConfig().handoffNamespace.families[`${op}.${type}`];
543
- if (family === undefined)
544
- throw new Error(`unknown handoff family: ${op}.${type}`);
545
- return family;
645
+ return this.#handoffSchema.schemaText(plane, evidence, prefix);
546
646
  }
547
647
  /** The artifacts field as a string-map (only string values land — non-string rows
548
648
  * are dropped, never coerced). */
@@ -84,7 +84,7 @@ export class Preview {
84
84
  return this.#rel(this.#scene.planPath ?? "");
85
85
  }
86
86
  /** The artifacts the round would write — the frame's prescribed output set (the
87
- * handoff carrier, the round report and the work faces' test evidence), named by
87
+ * handoff carrier, the round report and the evidence rounds' test evidence), named by
88
88
  * the ONE naming source. A slot the frame's family does not consume (a review
89
89
  * round prescribes no evidence file) is dropped, never rendered blank. */
90
90
  #writesOf(frame) {
@@ -37,6 +37,12 @@ export class TerminationPolicy {
37
37
  fix: 3 * 60 * 60 * 1000,
38
38
  "branch-review": 3 * 60 * 60 * 1000,
39
39
  };
40
+ /** The child's per-command Bash ceiling (ms) — a DISCIPLINE constant, never a
41
+ * phase budget: the child prompt tells the child to put a `timeout` on every
42
+ * Bash invocation, no longer than this. It is deliberately not a `RoundPhase`
43
+ * key (no dispatch phase maps to it) and not an engine-side kill: the engine
44
+ * cannot see commands inside the child. */
45
+ static CHILD_BASH_TIMEOUT_MS = 15 * 60 * 1000;
40
46
  /** The stall window (ms) — how long a round may make no progress before the
41
47
  * judge rules it stalled (not per phase: "no progress" means the same thing on
42
48
  * every phase). */
@@ -95,6 +101,11 @@ export class StallJudge {
95
101
  this.#idleWindowMs = idleWindowMs;
96
102
  this.#idleSince = spawnedAt;
97
103
  }
104
+ /** The idle time (ms) at `now` — how long since the last progress (the spawn instant
105
+ * until the first one). */
106
+ idleMs(now) {
107
+ return Math.max(0, now - this.#idleSince);
108
+ }
98
109
  /** Judge one tick: feed the tick's sample and the instant it was taken. */
99
110
  observe(sample, now) {
100
111
  const cpuMs = sample.groupCpuMs;
@@ -297,6 +308,10 @@ class SamplingLoop {
297
308
  lastSample() {
298
309
  return this.#last;
299
310
  }
311
+ /** The judge's idle reading (ms) at this instant — the termination fact's idle time. */
312
+ idleMs() {
313
+ return this.#judge.idleMs(Date.now());
314
+ }
300
315
  /** End the loop at the dispatch's terminal state: the cadence stops, and the
301
316
  * heartbeat is removed iff the round ended by itself — a terminated round's file
302
317
  * stays for a human's postmortem. */
@@ -377,10 +392,22 @@ export class Terminator {
377
392
  cwd: run.cwd,
378
393
  reject: false,
379
394
  stripFinalNewline: false,
395
+ // fd 0 on /dev/null: a child that reads stdin sees EOF at once, never a pipe nobody closes.
396
+ stdin: "ignore",
380
397
  killDescendants: true,
381
398
  forceKillAfterDelay: Terminator.FORCE_KILL_AFTER_DELAY_MS,
382
399
  timeout: run.policy.budgetMs,
383
400
  });
401
+ // Reclaim the group the instant the direct child exits: a grandchild holding the stdout
402
+ // / stderr pipes would otherwise keep the `await` open. No execa option does this (its
403
+ // group kill is on-demand only), so execa's own group-aware `kill()` is called once, at
404
+ // the `exit` event, and only on the group the engine created (`killDescendants`). With
405
+ // live members the pgid is still reserved; with none (no grandchild) the kill is a no-op
406
+ // unless the pgid was reused inside a vanishingly small window. Every ordinary child exit in
407
+ // termination.test.ts (no grandchild) passes through this kill.
408
+ subprocess.nodeChildProcess.once("exit", () => {
409
+ subprocess.kill();
410
+ });
384
411
  const sampling = this.#startSampling(run, subprocess.pid, spawnedAt, () => {
385
412
  // The engine's own group kill — execa kills the process group and escalates
386
413
  // SIGTERM → SIGKILL after the grace. No signal logic of the engine's own.
@@ -400,6 +427,7 @@ export class Terminator {
400
427
  killedByStall,
401
428
  signal: result.signal,
402
429
  isTerminated: result.isTerminated,
430
+ idleMs: sampling?.idleMs() ?? 0,
403
431
  lastSample: sampling?.lastSample() ?? null,
404
432
  });
405
433
  endedByItself = termination === null;
@@ -468,15 +496,15 @@ export class Terminator {
468
496
  * signalled and read `stalled` — the idle verdict, not the kill landing, is the
469
497
  * criterion. */
470
498
  static terminationOf(facts) {
471
- const { timedOut, killedByStall, signal, isTerminated, lastSample } = facts;
499
+ const { timedOut, killedByStall, signal, isTerminated, idleMs, lastSample } = facts;
472
500
  if (timedOut)
473
- return { cause: "over-budget", lastSample };
501
+ return { cause: "over-budget", idleMs, lastSample };
474
502
  if (killedByStall)
475
- return { cause: "stalled", lastSample };
503
+ return { cause: "stalled", idleMs, lastSample };
476
504
  if (signal !== undefined)
477
- return { cause: "signal", lastSample };
505
+ return { cause: "signal", idleMs, lastSample };
478
506
  if (isTerminated)
479
- return { cause: "unknown", lastSample };
507
+ return { cause: "unknown", idleMs, lastSample };
480
508
  return null;
481
509
  }
482
510
  }