@holmes-lab/holmes-kit 0.35.17 → 0.35.19

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.
Files changed (35) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.d.ts +4 -1
  5. package/dist/holmes/cli/approve-status.js +10 -0
  6. package/dist/holmes/cli/approve-watch.js +4 -0
  7. package/dist/holmes/cli/approve.d.ts +9 -2
  8. package/dist/holmes/cli/approve.js +33 -9
  9. package/dist/holmes/cli/autonomy.d.ts +13 -6
  10. package/dist/holmes/cli/autonomy.js +105 -16
  11. package/dist/holmes/cli/doctor.js +21 -3
  12. package/dist/holmes/cli/index.js +33 -9
  13. package/dist/holmes/cli/init.js +3 -1
  14. package/dist/holmes/cli/interactive-prompt.d.ts +5 -0
  15. package/dist/holmes/cli/interactive-prompt.js +12 -4
  16. package/dist/holmes/cli/runtime-binding.d.ts +23 -1
  17. package/dist/holmes/cli/runtime-binding.js +117 -5
  18. package/dist/holmes/governance/approval-queue.d.ts +7 -1
  19. package/dist/holmes/governance/approval-queue.js +34 -3
  20. package/dist/holmes/governance/autonomy.d.ts +0 -2
  21. package/dist/holmes/governance/autonomy.js +27 -5
  22. package/dist/holmes/governance/delegation.d.ts +40 -0
  23. package/dist/holmes/governance/delegation.js +151 -0
  24. package/dist/holmes/guardrail/write-target.d.ts +10 -0
  25. package/dist/holmes/guardrail/write-target.js +82 -0
  26. package/dist/holmes/hooks/pre-tool-use.d.ts +3 -1
  27. package/dist/holmes/hooks/pre-tool-use.js +22 -4
  28. package/dist/holmes/hooks/stop-timing.d.ts +12 -0
  29. package/dist/holmes/hooks/stop-timing.js +22 -0
  30. package/dist/holmes/hooks/stop.js +28 -0
  31. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  32. package/dist/holmes/mcp/handlers/spec-approval.js +21 -2
  33. package/dist/holmes/mcp/handlers.d.ts +5 -5
  34. package/dist/holmes/runtime/dispatch.js +28 -3
  35. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,79 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.19] - 2026-10-13
9
+
10
+ ### Added
11
+
12
+ - **Run delegation — a third autonomy envelope for benchmark runs** (REQ-771, A-SPEC-771, A-SPEC-771.1). Measured
13
+ 2026-10-12 (X1): a fixture the operator had approved as a whole still stopped a REQ and an H-SPEC on
14
+ `upstream-has-human-aspec: … — files-to-touch-root-only`, because neither the project default (A-SPEC-552.1) nor the
15
+ session marker (A-SPEC-553.1) can name a run, a workspace or a grader rule. `holmes-kit autonomy delegate --run <id>
16
+ --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]` (same human proof as `autonomy on`) writes
17
+ `.ax/state/delegation.json` with the resolved workspace realpath, the covered rules (a closed set: root-only or
18
+ gate-file Files to Touch, an undirected gate-behavior grade, an upstream without A-SPEC — never architecture
19
+ documents, un-admitted requirements, undeclared or unknown grades), an expiry and declared limits. `spec_approve`
20
+ then seals a hitl verdict whose rule the delegation covers with `source: 'delegated'`, actor `delegated:<client>`
21
+ and the ledger rationale `delegated grant (run <id>, rule <rule>)`; an uncovered case refuses with
22
+ `[delegation: run … does not cover …]`, `[delegation: expired …]`, `[delegation: for <workspace>, not this root]` or
23
+ `[delegation: invalid document …]`. `autonomy status`, `approve --status` and the session-start banner show it;
24
+ `revoke-delegation` (or `off`) ends it. The grader's verdicts are unchanged; the host's own approval layer is named
25
+ as not covered.
26
+
27
+ ### Fixed
28
+
29
+ - **Every operator hint names the workspace the request lives in** (A-SPEC-770.2). Measured 2026-10-13 in the Codex X1
30
+ native run: the refusal hint read `approve --grant req-38dd3372238c` with no `--target`, while a request is stored in
31
+ the refusal log of the workspace whose hook refused — not the shell's cwd (2026-10-12: a worktree command's request
32
+ lived in the development root and `--target <worktree>` answered "no pending request matches"). The hook's deny text,
33
+ the inbox footer and the `--refusals` closing line now end their commands with `--target <absolute root>` (quoted once
34
+ when it contains white space, never folded); without a root the 0.35.18 text is produced byte for byte.
35
+ - **A context-only Codex patch is refused by its own name** (A-SPEC-769.7). Measured 2026-10-13 (X1 HB negative
36
+ control): an `apply_patch` whose update block had only context lines was refused as `file_path missing or not a
37
+ string` although its header named the file. `canonicalPatchReason` tells a no-op update from a grammar fault, and the
38
+ hook says `the patch to <path> adds or removes no line (a context-only update is a no-op), so there is nothing to
39
+ judge — include at least one + or - line`. The deny stays a deny; malformed, path-missing and non-application keep
40
+ their own sentences.
41
+ - **`runtime-binding status` and `doctor` report a Codex lifecycle routed to Holmes twice** (A-SPEC-769.8). Measured
42
+ 2026-10-12 in both X1 fixtures: the Stop hook wrote two identical cycle rows 1 ms apart because `~/.codex/hooks.json`
43
+ and the workspace `.codex/hooks.json` both route `codex-stop.js` and `[hooks.state]` switches off only the user-level
44
+ `pre_tool_use`. The status carries `duplicateRoutes [{ harness, event, files, fix }]` and doctor prints one
45
+ `WARN codex duplicate route` line per lifecycle with the `enabled = false` fix; nothing is written or switched.
46
+
47
+ ## [0.35.18] - 2026-10-12
48
+
49
+ ### Fixed
50
+
51
+ - **An autonomy refusal names the child rule that forces the human decision** (A-SPEC-769). Measured 2026-10-12 in
52
+ the Codex X1 runtime session: `spec_approve` on a parent spec answered "autonomy hitl" with no reason an operator
53
+ could act on. `specApprovalAutonomyReason` now returns `upstream-has-human-aspec: <child id> — <child rule>` (the
54
+ `files-to-touch-root-only` policy of A-SPEC-654 was the rule in the measured case; the policy itself is unchanged).
55
+ - **The `--autonomy` usage entry, the `init` refusal line and the interactive prompt say the same thing** (A-SPEC-769.1).
56
+ The three texts had drifted apart; each now names the grade, what it decides alone, and what still asks a person.
57
+ - **A runtime deadline refusal says which phase spent the budget** (A-SPEC-769.2). `Selected hook runtime deadline
58
+ exceeded` now ends with `; phases (ms of <budget>): input <n|->, selection <n|->, hook child <n|->`, and the Stop hook
59
+ prints `[Holmes-Kit] Stop hook used <total> ms of its 18000 ms hook budget — …` with the per-stage clock
60
+ (`src/holmes/hooks/stop-timing.ts`) once a run passes half the budget. Measured: the `scan` stage alone is ≈7 s on
61
+ this workspace; the figure is now visible, not reduced — see Known issues.
62
+ - **`runtime-binding status` separates drift from conflict** (A-SPEC-769.3, A-SPEC-769.5, A-SPEC-769.6). The status carries
63
+ `drift [{ path, kind: 'operator-config' | 'stale-workspace' }]` beside `conflicts`, `router: 'intact' | 'changed'`
64
+ and `activation`; `doctor` reads the harness identity from the router rows. A receipt that differs only because
65
+ the operator edited `~/.claude/settings.json` stays a conflict as A-SPEC-752.5/752.6 pin it (owner decision pending).
66
+ - **A refusal written to the refusal log is answerable from its own hint** (A-SPEC-770, 770.1). Field report
67
+ 2026-10-12 (jarvis): "approval impossible" — the design was intact (REQ-563/690: a refusal outside the inbox is
68
+ granted with `approve --grant <id>`), but the hint carried no id and the inbox never said such requests existed.
69
+ Every refusal line now ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the
70
+ inbox (`--list`, `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line
71
+ spells the same command. The first repair had written the positional form `approve <id>`, which the CLI refuses
72
+ with `unexpected argument` — measured once on the released CLI before the hint was rewritten (A-SPEC-770.1).
73
+
74
+ ### Known issues
75
+
76
+ - The Stop hook `scan` stage still takes ≈7 s on a 440-file workspace; under a parallel full-suite load (≥ 9) the
77
+ 18 s hook budget is exceeded and the refusal is now explained but still a refusal. Reduction is a separate slice.
78
+ - The inbox footer glyph is `◆` (the file's bullet, pinned by A-SPEC-770.1); A-SPEC-770's text says `◇`. The spec
79
+ text is the stale side; it is amended with the next unseal of REQ-770, not by a code change.
80
+
8
81
  ## [0.35.17] - 2026-10-11
9
82
 
10
83
  ### Fixed
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **438/440** source files (99.5%) trace to an approved spec · **761/824** approved A-SPECs (92.3%) are anchored from code.
13
- Measured at `70dcb37ccf6b` (specs `sha256:675042379d48`) — reproduce with `holmes-kit attest`.
12
+ **440/442** source files (99.5%) trace to an approved spec · **774/837** approved A-SPECs (92.4%) are anchored from code.
13
+ Measured at `11a1b841c813` (specs `sha256:2e7481e061f1`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,8 @@ Measured at `70dcb37ccf6b` (specs `sha256:675042379d48`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **A benchmark run the operator pre-approved finishes with zero human waits — the run delegation** *(new in 0.35.19)*: `holmes-kit autonomy delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]` (same human proof as `autonomy on`) writes a run-scoped, workspace-bound (realpath), expiring delegation that covers a closed set of autonomy-grader rules — root-only or gate-file Files to Touch, an undirected gate-behavior grade, an upstream without A-SPEC; never architecture documents, un-admitted requirements, undeclared or unknown grades. A hitl spec whose only reason is a covered rule seals on its own with `source: 'delegated'` and a ledger row naming the run and the rule; an uncovered case refuses with the named limit (`does not cover`, `expired`, `for <workspace>, not this root`, `invalid document`). `autonomy status`, `approve --status` and the session-start banner show it; `revoke-delegation` or `off` ends it. The host's own approval layer is named as not covered. Measured need: X1 (2026-10-12) stopped a pre-approved fixture on `files-to-touch-root-only`. Every operator hint now also names the workspace (`--target <root>`), a context-only Codex patch is refused as a no-op by name, and `runtime-binding status`/`doctor` report a Codex lifecycle routed to Holmes from both the user-level and the workspace hooks file.
27
+ - **A refusal you cannot see in the inbox is still answerable from its own hint** *(new in 0.35.18)*: six repairs measured in a Codex X1 runtime session and a field report. Every refusal line written to the refusal log ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the inbox (`approve --list` / `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line spells the same command (the positional `approve <id>` the first repair wrote is refused by the CLI, so it was measured and rewritten). An autonomy refusal on a parent spec names the child rule that forces the human decision (`upstream-has-human-aspec: <id> — <rule>`). A runtime deadline refusal ends with the per-phase millisecond split, and the Stop hook prints how much of its 18 s budget it used once it passes half. `runtime-binding status` separates `drift` (operator-config / stale-workspace) from `conflicts` and reports whether the router is intact. The `--autonomy` usage, the `init` refusal and the interactive prompt now say the same thing.
26
28
  - **An agent is told what to do after an approval, and a patch is judged the way the tool applies it** *(new in 0.35.17)*: five repairs measured on a Codex worker in a SWE-bench comparison. `approval_status` now carries `request { id, state, question?, reason?, ts? }` (pending / held / granted / consumed / denied / revoked, read from the approval queue, with the operator's LATEST hold question) and one `nextAction` sentence — a sealed spec says "stop polling", a held request relays the question; the pending-approval hint ends with an `Agent:` line beside the unchanged operator lines. `test_run` reports `anchorDiagnostics` for an `@implements` list joined by `;`, `|`, `&`, `/` or `and` (the comma grammar does not read them; attribution is unchanged, the omission is named). A Codex `apply_patch` update is applied chunk by chunk from the previous chunk's position, as the tool does, so a context line that recurs earlier in the file no longer makes it "unreadable", and a patch that does not apply is refused by a sentence naming the file and the chunk. A quoted or escaped glob (`rg ".*"`) is no longer read as a spelling of the `.ax` store (an unquoted `.*` still is). The background refresh child records `failure { stage, reason }` on its freshness receipt instead of failing silently.
27
29
  - **The analysis names the unchanged files a change has broken** *(new in 0.35.16)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.removedNameUsers` every unchanged file that imports a changed file and still uses a top-level name that file no longer defines (removed or renamed), and the files still importing a deleted TypeScript/JavaScript file. Deterministic and read-only; TypeScript/JavaScript and Python. Measured on public repositories: every file named was one the commit did change (22 of 22, 21 of 21). It fires rarely — 2–7% of the files an incomplete change set was missing. Member names and changed signatures are not read.
28
30
  - **The analysis names the file a change still has to create** *(new in 0.35.15)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.missingNewFiles` every relative import a changed TypeScript/JavaScript file newly introduces that resolves to nothing — the importing file, the specifier and the candidate paths. Deterministic and read-only. On two unseen windows of a public TypeScript monorepo every naming was a file the change did create (precision 1.000), covering 78–86% of the not-yet-existing files an incomplete change set was missing. Only uncommitted changes in a git repository; other languages, bare package names and path aliases are not read.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- e14712a6-mv3zqox3
1
+ fdff132e-mv6ac9v3
@@ -6,9 +6,12 @@ export interface StatusContext {
6
6
  workspaceId?: string;
7
7
  replicaId?: string;
8
8
  };
9
+ /** @implements A-SPEC-771 — `run`: an operator-issued run delegation (A-SPEC-771) is on for this workspace. */
9
10
  delegation: {
10
- mode: 'project-default' | 'session' | 'off';
11
+ mode: 'project-default' | 'session' | 'run' | 'off';
11
12
  until?: string;
13
+ run?: string;
14
+ covers?: string[];
12
15
  };
13
16
  /** Nonces that still have a grant file — a granted decision is LIVE only while its file exists. */
14
17
  liveGrants: ReadonlySet<string>;
@@ -75,6 +75,13 @@ function statusContext(root, now = new Date().toISOString()) {
75
75
  }
76
76
  delegation = { mode: 'session', ...(until ? { until } : {}) };
77
77
  }
78
+ else {
79
+ // @implements A-SPEC-771 — the run delegation is the third envelope, read the same way the server reads it.
80
+ const { readDelegation } = require('../governance/delegation');
81
+ const s = readDelegation(root, now);
82
+ if (s.active)
83
+ delegation = { mode: 'run', run: s.delegation.run, until: s.delegation.expires, covers: s.delegation.allow };
84
+ }
78
85
  }
79
86
  catch {
80
87
  delegation = { mode: 'off' };
@@ -124,6 +131,9 @@ function renderStatus(state, ctx, opts) {
124
131
  lines.push('\u25c6 delegation: autonomous spec approval ON (project default, .mcp.json) \u2014 governance-critical, high-risk and irreversible still ask you');
125
132
  else if (ctx.delegation.mode === 'session')
126
133
  lines.push(`\u25c6 delegation: autonomous spec approval ON (this session, until ${(0, screen_safe_1.rowField)(ctx.delegation.until ?? '?', 28)}) \u2014 end early: holmes-kit autonomy off`);
134
+ // @implements A-SPEC-771 \u2014 the run delegation names its run, expiry and covered rules; end early with revoke-delegation.
135
+ else if (ctx.delegation.mode === 'run')
136
+ lines.push(`\u25c6 delegation: run ${(0, screen_safe_1.rowField)(ctx.delegation.run ?? '?', 24)} until ${(0, screen_safe_1.rowField)(ctx.delegation.until ?? '?', 28)} \u2014 covers ${(ctx.delegation.covers ?? []).join(', ')} \u2014 end early: holmes-kit autonomy revoke-delegation`);
127
137
  else
128
138
  lines.push('\u25c6 delegation: autonomous spec approval OFF \u2014 every spec approval is human');
129
139
  lines.push('');
@@ -205,6 +205,10 @@ async function runWatch(root, io, actor, opts = {}) {
205
205
  if (!idleAnnounced) {
206
206
  io.print(exports.WATCH_IDLE);
207
207
  idleAnnounced = true;
208
+ // @implements A-SPEC-770 — once per idle announcement: the refusals this surface does not list, by count.
209
+ const footer = (0, approve_1.outsideInboxFooter)((0, approval_queue_1.refusalsOutsideInbox)(root), root); // @implements A-SPEC-770.2
210
+ if (footer !== null)
211
+ io.print(footer);
208
212
  }
209
213
  // No reset of `lastPresented` here (round-3): the top-of-pass prune above already intersects
210
214
  // it with the current pending set every pass, so on an empty queue it becomes empty before it
@@ -57,10 +57,17 @@ export declare function staleView(flags: Record<string, unknown>): {
57
57
  ttlMs: number;
58
58
  showAll: boolean;
59
59
  } | null;
60
+ /**
61
+ * @implements A-SPEC-770 — the one line an inbox screen ends with when this machine's refusal log holds open requests
62
+ * the screen does not list (A-SPEC-563.1 keeps gate refusals out of the inbox; A-SPEC-563.2 / A-SPEC-690 let
63
+ * `approve --grant <id>` reach them). A count and two commands — never a target. `null` when there is nothing to say.
64
+ * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
65
+ */
66
+ export declare function outsideInboxFooter(outside: number | undefined, root?: string): string | null;
60
67
  export declare function renderPending(state: QueueState, view?: {
61
68
  staleHours: number;
62
69
  showAll: boolean;
63
- }): string;
70
+ }, outside?: number, root?: string): string;
64
71
  /**
65
72
  * @implements A-SPEC-262.1
66
73
  * What a decision line must say. Round-1: `✓ approved — valid until <expires>` named NOTHING, so an index
@@ -123,7 +130,7 @@ export declare function renderRefusals(refusals: Array<{
123
130
  target: string;
124
131
  why: string;
125
132
  ts: string;
126
- }>, limit?: number): string;
133
+ }>, limit?: number, root?: string): string;
127
134
  export declare function renderNonTtyHint(state: QueueState): string;
128
135
  export interface ApproveIO {
129
136
  print: (s: string) => void;
@@ -39,6 +39,7 @@ exports.revokeGrant = revokeGrant;
39
39
  exports.denyRequest = denyRequest;
40
40
  exports.holdRequest = holdRequest;
41
41
  exports.staleView = staleView;
42
+ exports.outsideInboxFooter = outsideInboxFooter;
42
43
  exports.renderPending = renderPending;
43
44
  exports.subjectCells = subjectCells;
44
45
  exports.subjectRoom = subjectRoom;
@@ -86,7 +87,7 @@ const MAX_TTL_MINUTES = 7 * 24 * 60;
86
87
  const DEFAULT_RATIONALE = 'approved via holmes-kit approve';
87
88
  const findPending = (root, id) => {
88
89
  // @implements A-SPEC-576.1 — RESOLUTION reads everything; the human's LIST reads decisions only.
89
- // The inbox filter hides gate refusals from the screen, but `approve <id>` must still find one:
90
+ // The inbox filter hides gate refusals from the screen, but `approve --grant <id>` must still find one:
90
91
  // the fallback below only holds entries written after the REQ-563 split, so anything refused
91
92
  // before it lives in the queue alone. Filtering here would cut the out-of-band approval path the
92
93
  // deny message itself promises.
@@ -345,17 +346,37 @@ function staleView(flags) {
345
346
  return null;
346
347
  return { ttlMs: hours * 3_600_000, showAll: flags.all === true };
347
348
  }
348
- function renderPending(state, view) {
349
+ /**
350
+ * @implements A-SPEC-770 — the one line an inbox screen ends with when this machine's refusal log holds open requests
351
+ * the screen does not list (A-SPEC-563.1 keeps gate refusals out of the inbox; A-SPEC-563.2 / A-SPEC-690 let
352
+ * `approve --grant <id>` reach them). A count and two commands — never a target. `null` when there is nothing to say.
353
+ * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
354
+ */
355
+ function outsideInboxFooter(outside, root) {
356
+ if (!outside || outside <= 0)
357
+ return null;
358
+ // @implements A-SPEC-770.2 — the commands name the workspace this screen read, so a line pasted elsewhere resolves
359
+ // the id against the right store (measured 2026-10-13: the hint reached the operator without any `--target`).
360
+ const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
361
+ // `◆` rather than the `◇` the spec sketched: §13 (approve-corpus) admits only the template's own glyphs on a decision
362
+ // row, and U+25C7 is of ambiguous width while U+25C6 is already furniture of this screen.
363
+ return `◆ ${outside} refusal(s) on this machine are outside this inbox (shell/gate refusals) — list them: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --refusals${target} · grant one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>${target}`;
364
+ }
365
+ function renderPending(state, view, outside, root) {
366
+ const withFooter = (lines) => {
367
+ const footer = outsideInboxFooter(outside, root);
368
+ return (footer === null ? lines : [...lines, footer]).join('\n');
369
+ };
349
370
  if (state.pending.length === 0) {
350
371
  // Round-7: this early return made the malformed-line row below UNREACHABLE in exactly the case
351
372
  // it exists for — a wholly corrupted queue printed "no requests waiting" and exited 0, which is
352
373
  // what an agent would see after destroying it. approval-queue.ts promises the opposite:
353
374
  // "an empty-looking queue must be distinguishable from a corrupted one".
354
375
  if (state.malformedLines > 0) {
355
- return ['No requests awaiting approval.',
356
- `(${state.malformedLines} unreadable line(s) in the queue — check for corruption)`].join('\n');
376
+ return withFooter(['No requests awaiting approval.',
377
+ `(${state.malformedLines} unreadable line(s) in the queue — check for corruption)`]);
357
378
  }
358
- return 'No requests awaiting approval.';
379
+ return withFooter(['No requests awaiting approval.']);
359
380
  }
360
381
  const lines = [`◆ ${state.pending.length} request(s) awaiting approval`, ''];
361
382
  // @implements A-SPEC-507.1 — the LIST VIEW sorts newest-activity-first and folds stale entries
@@ -396,7 +417,7 @@ function renderPending(state, view) {
396
417
  }
397
418
  if (state.malformedLines > 0)
398
419
  lines.push(`(${state.malformedLines} unreadable line(s) in the queue — check for corruption)`);
399
- return lines.join('\n');
420
+ return withFooter(lines);
400
421
  }
401
422
  /**
402
423
  * @implements A-SPEC-262.1
@@ -467,7 +488,7 @@ function decisionDetail(p, tail = '') {
467
488
  * and this renderer is the reason an operator can find the id the deny message named. Row width
468
489
  * follows the decision list's screen-safe discipline.
469
490
  */
470
- function renderRefusals(refusals, limit = 20) {
491
+ function renderRefusals(refusals, limit = 20, root) {
471
492
  if (refusals.length === 0)
472
493
  return '◆ no refusals recorded on this machine';
473
494
  const recent = refusals.slice(-Math.max(1, limit));
@@ -476,7 +497,10 @@ function renderRefusals(refusals, limit = 20) {
476
497
  lines.push(`${(0, screen_safe_1.rowField)(r.id, 20)} ${(0, screen_safe_1.rowField)(r.kind, screen_safe_1.KIND_COLS)} ${(0, screen_safe_1.rowField)(r.target, 40)}`);
477
498
  lines.push(` \u2502 ${(0, screen_safe_1.rowField)(r.why, 66)} ${(0, screen_safe_1.rowField)(r.ts, 24)}`);
478
499
  }
479
- lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve <id>`);
500
+ // @implements A-SPEC-770.1 — `--grant <id>`: the positional form this line named since 2026-09-06 is refused.
501
+ // @implements A-SPEC-770.2 — and the workspace whose log this screen read, when the caller knows it.
502
+ const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
503
+ lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>${target}`);
480
504
  return lines.join('\n');
481
505
  }
482
506
  function renderNonTtyHint(state) {
@@ -530,7 +554,7 @@ function renderNonTtyHint(state) {
530
554
  */
531
555
  async function runInteractive(root, io, actor) {
532
556
  const state = (0, approval_queue_1.readQueue)(root);
533
- io.print(renderPending(state));
557
+ io.print(renderPending(state, undefined, (0, approval_queue_1.refusalsOutsideInbox)(root), root)); // @implements A-SPEC-770, A-SPEC-770.2
534
558
  if (state.pending.length === 0)
535
559
  return;
536
560
  const grantDefault = (p) => {
@@ -1,5 +1,5 @@
1
1
  import { Approval } from '../guardrail/risk-gate';
2
- /** `--for` accepts `2h` / `90m` / a bare number of hours. Minutes, capped at 7 days (like grants);
2
+ /** `--for` accepts `2h` / `90m` / `7d` / a bare number of hours. Minutes, capped at 7 days (like grants);
3
3
  * null on a malformed value; default 2h when omitted. */
4
4
  export declare function parseForMinutes(s: string | undefined): number | null;
5
5
  export interface AutonomyIO {
@@ -8,15 +8,22 @@ export interface AutonomyIO {
8
8
  approval?: Approval;
9
9
  env?: NodeJS.ProcessEnv;
10
10
  }
11
+ /** @implements A-SPEC-771 — the delegation subcommand's own inputs, parsed by the CLI entry and passed through. */
12
+ export interface AutonomyExtra {
13
+ run?: string;
14
+ allow?: string;
15
+ limits?: string[];
16
+ rationale?: string;
17
+ }
11
18
  export interface AutonomyResult {
12
19
  ok: boolean;
13
20
  exitCode: 0 | 1 | 2;
14
21
  message: string;
15
22
  }
16
23
  /**
17
- * The `holmes-kit autonomy status|on|off` core. Pure over injected io (clock/TTY/approval/env) so
18
- * every branch is testable. Enabling (`on`) is protected exactly like `init --autonomy`: the raw-TTY
19
- * terminal is the human-presence proof, and a non-TTY caller (an agent's Bash) must carry an
20
- * out-of-band HOLMES_APPROVAL covering kind `autonomy-grant`. Disabling is always free.
24
+ * The `holmes-kit autonomy status|on|off|delegate|revoke-delegation` core. Pure over injected io (clock/TTY/approval/
25
+ * env) so every branch is testable. Enabling (`on`) and delegating are protected exactly like `init --autonomy`: the
26
+ * raw-TTY terminal is the human-presence proof, and a non-TTY caller (an agent's Bash) must carry an out-of-band
27
+ * HOLMES_APPROVAL covering kind `autonomy-grant`. Disabling and revoking are always free.
21
28
  */
22
- export declare function runAutonomy(root: string, sub: string | undefined, forStr: string | undefined, io: AutonomyIO): AutonomyResult;
29
+ export declare function runAutonomy(root: string, sub: string | undefined, forStr: string | undefined, io: AutonomyIO, extra?: AutonomyExtra): AutonomyResult;
@@ -35,61 +35,96 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.parseForMinutes = parseForMinutes;
37
37
  exports.runAutonomy = runAutonomy;
38
- // @implements A-SPEC-553.1, A-SPEC-553.2
38
+ // @implements A-SPEC-553.1, A-SPEC-553.2, A-SPEC-771
39
39
  const fs = __importStar(require("node:fs"));
40
40
  const path = __importStar(require("node:path"));
41
41
  const risk_gate_1 = require("../guardrail/risk-gate");
42
42
  const autonomy_1 = require("../governance/autonomy");
43
+ const delegation_1 = require("../governance/delegation");
43
44
  const PROJECT_DEFAULT_ON = 'autonomous spec approval: ON (project default, .mcp.json) — governance-critical still ask you. '
44
45
  + 'Turn it off by removing HOLMES_AUTONOMOUS_APPROVAL from .mcp.json (or holmes-kit init --no-autonomy).';
45
46
  const ledger_store_1 = require("../governance/ledger-store");
46
47
  const provenance_chain_1 = require("../governance/provenance-chain");
47
- /** `--for` accepts `2h` / `90m` / a bare number of hours. Minutes, capped at 7 days (like grants);
48
+ /** `--for` accepts `2h` / `90m` / `7d` / a bare number of hours. Minutes, capped at 7 days (like grants);
48
49
  * null on a malformed value; default 2h when omitted. */
49
50
  function parseForMinutes(s) {
50
51
  if (s === undefined)
51
52
  return 120;
52
- const m = /^\s*(\d+)\s*(h|m)?\s*$/.exec(s);
53
+ // @implements A-SPEC-771 — `d` joins `h` and `m` (a run window is days-long); a compound like `7d1m` stays malformed.
54
+ const m = /^\s*(\d+)\s*(h|m|d)?\s*$/.exec(s);
53
55
  if (!m)
54
56
  return null;
55
57
  const n = parseInt(m[1], 10);
56
58
  if (!Number.isFinite(n) || n <= 0)
57
59
  return null;
58
- const mins = m[2] === 'm' ? n : n * 60;
60
+ const mins = m[2] === 'm' ? n : m[2] === 'd' ? n * 24 * 60 : n * 60;
59
61
  return mins <= 7 * 24 * 60 ? mins : null;
60
62
  }
63
+ const DELEGATION_HOST_NOTE = 'host approval layer: not covered (a harness\'s own tool-confirmation stays the host\'s)';
64
+ function delegationStatusLine(root, now) {
65
+ const s = (0, delegation_1.readDelegation)(root, now);
66
+ if (!s.active)
67
+ return null;
68
+ const d = s.delegation;
69
+ const limits = d.limits && Object.keys(d.limits).length ? `; limits ${Object.entries(d.limits).map(([k, v]) => `${k}=${v}`).join(', ')}` : '';
70
+ return `delegation: run ${d.run} until ${d.expires} — covers ${d.allow.join(', ')}${limits}; ${DELEGATION_HOST_NOTE}`;
71
+ }
72
+ function revokeDelegationQuietly(root, io, rationale) {
73
+ let run = '';
74
+ try {
75
+ const s = (0, delegation_1.readDelegation)(root, io.now);
76
+ run = s.active ? s.delegation.run : (s.run ?? '');
77
+ }
78
+ catch { /* best effort */ }
79
+ if (!(0, delegation_1.removeDelegation)(root))
80
+ return;
81
+ try {
82
+ new ledger_store_1.FileLedgerStore(path.join(root, '.ax', 'ledger')).append({
83
+ ts: io.now, actor: io.approval?.actor ?? 'operator', kind: 'autonomy-delegation-revoked',
84
+ summary: `run delegation revoked${run ? ` (run ${run})` : ''}`, rationale,
85
+ });
86
+ }
87
+ catch { /* the document is gone either way */ }
88
+ }
61
89
  /**
62
- * The `holmes-kit autonomy status|on|off` core. Pure over injected io (clock/TTY/approval/env) so
63
- * every branch is testable. Enabling (`on`) is protected exactly like `init --autonomy`: the raw-TTY
64
- * terminal is the human-presence proof, and a non-TTY caller (an agent's Bash) must carry an
65
- * out-of-band HOLMES_APPROVAL covering kind `autonomy-grant`. Disabling is always free.
90
+ * The `holmes-kit autonomy status|on|off|delegate|revoke-delegation` core. Pure over injected io (clock/TTY/approval/
91
+ * env) so every branch is testable. Enabling (`on`) and delegating are protected exactly like `init --autonomy`: the
92
+ * raw-TTY terminal is the human-presence proof, and a non-TTY caller (an agent's Bash) must carry an out-of-band
93
+ * HOLMES_APPROVAL covering kind `autonomy-grant`. Disabling and revoking are always free.
66
94
  */
67
- function runAutonomy(root, sub, forStr, io) {
95
+ function runAutonomy(root, sub, forStr, io, extra = {}) {
68
96
  const env = io.env ?? process.env;
69
97
  const markerPath = path.join(root, ...autonomy_1.SESSION_AUTONOMY_MARKER);
70
98
  if (sub === undefined || sub === 'status') {
99
+ // @implements A-SPEC-771 — an active run delegation is reported beside whichever posture is on.
100
+ const delegationLine = delegationStatusLine(root, io.now);
101
+ const withDelegation = (message) => delegationLine === null ? message : `${message}\n${delegationLine}`;
71
102
  const envOn = typeof env[autonomy_1.AUTONOMY_ENV] === 'string' && env[autonomy_1.AUTONOMY_ENV] !== '';
72
103
  if (envOn)
73
- return { ok: true, exitCode: 0, message: 'autonomous spec approval: ON (project default, .mcp.json) — governance-critical still ask you' };
104
+ return { ok: true, exitCode: 0, message: withDelegation('autonomous spec approval: ON (project default, .mcp.json) — governance-critical still ask you') };
74
105
  // @implements A-SPEC-553.2 — the same project default the server and the session banner read
75
106
  // (A-SPEC-560.2). The CLI read only the shell environment, which never carries .mcp.json's env, and
76
107
  // answered OFF while the server sealed specs autonomously.
77
108
  if ((0, autonomy_1.projectDefaultAutonomy)(root))
78
- return { ok: true, exitCode: 0, message: PROJECT_DEFAULT_ON };
109
+ return { ok: true, exitCode: 0, message: withDelegation(PROJECT_DEFAULT_ON) };
79
110
  if ((0, autonomy_1.sessionAutonomyActive)(root, io.now)) {
80
111
  let expires = '';
81
112
  try {
82
113
  expires = String(JSON.parse(fs.readFileSync(markerPath, 'utf8')).expires);
83
114
  }
84
115
  catch { /* best effort */ }
85
- return { ok: true, exitCode: 0, message: `autonomous spec approval: ON (this session, until ${expires}) — governance-critical still ask you` };
116
+ return { ok: true, exitCode: 0, message: withDelegation(`autonomous spec approval: ON (this session, until ${expires}) — governance-critical still ask you`) };
86
117
  }
118
+ if (delegationLine !== null)
119
+ return { ok: true, exitCode: 0, message: `autonomous spec approval: ON (run delegation) — ${delegationLine}` };
87
120
  return { ok: true, exitCode: 0, message: 'autonomous spec approval: OFF — every spec approval is human (holmes-kit autonomy on to self-drive this session)' };
88
121
  }
89
122
  if (sub === 'off') {
90
123
  // @implements A-SPEC-558.1 — `off` is the emergency de-escalation control; it must fail CLOSED.
91
124
  // If the marker cannot be removed it is still ON, so never report OFF: re-check after rmSync and
92
125
  // report failure honestly if it survives.
126
+ // @implements A-SPEC-771 — the run delegation goes with it: `off` ends every envelope this CLI issued.
127
+ revokeDelegationQuietly(root, io, 'holmes-kit autonomy off');
93
128
  let existed = false;
94
129
  let removeError;
95
130
  try {
@@ -128,16 +163,70 @@ function runAutonomy(root, sub, forStr, io) {
128
163
  }
129
164
  return { ok: true, exitCode: 0, message: 'autonomous spec approval: OFF — every spec approval is human again' };
130
165
  }
131
- if (sub === 'on') {
166
+ // @implements A-SPEC-771 — revoking needs no proof (de-escalation is always free), like `off`.
167
+ if (sub === 'revoke-delegation') {
168
+ const s = (0, delegation_1.readDelegation)(root, io.now);
169
+ const had = s.active || (s.why !== 'none');
170
+ revokeDelegationQuietly(root, io, 'holmes-kit autonomy revoke-delegation');
171
+ return { ok: true, exitCode: 0, message: had ? 'run delegation revoked — hitl specs ask a person again' : 'no run delegation on file' };
172
+ }
173
+ if (sub === 'on' || sub === 'delegate') {
132
174
  if (!io.isTTY && !(0, risk_gate_1.approvalCovers)(io.approval, { kind: 'autonomy-grant', target: root }, io.now)) {
133
- return { ok: false, exitCode: 2, message: 'Enabling session autonomy needs a human: run it at a terminal, or supply an out-of-band approval.\n'
175
+ return { ok: false, exitCode: 2, message: `${sub === 'on' ? 'Enabling session autonomy' : 'Issuing a run delegation'} needs a human: run it at a terminal, or supply an out-of-band approval.\n`
134
176
  + `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "autonomy-grant") and re-run.` };
135
177
  }
136
178
  const mins = parseForMinutes(forStr);
137
179
  if (mins === null)
138
- return { ok: false, exitCode: 2, message: '--for must look like 2h or 90m (1 minute .. 7 days)' };
180
+ return { ok: false, exitCode: 2, message: '--for must look like 2h, 90m or 7d (1 minute .. 7 days)' };
139
181
  const expires = new Date(Date.parse(io.now) + mins * 60_000).toISOString();
140
182
  const grantedBy = io.approval?.actor ?? 'operator(tty)';
183
+ if (sub === 'delegate') {
184
+ // @implements A-SPEC-771 — the document names the run, the resolved workspace, the covered grader rules, the
185
+ // expiry and the declared limits; a NEVER or unknown rule is refused before anything is written.
186
+ const run = extra.run?.trim() ?? '';
187
+ if (!delegation_1.RUN_ID_RE.test(run))
188
+ return { ok: false, exitCode: 2, message: '--run <id> is required: 1..64 characters of letters, digits, dot, underscore or dash' };
189
+ const allow = (extra.allow ?? '').split(',').map((a) => a.trim()).filter((a) => a !== '');
190
+ if (allow.length === 0)
191
+ return { ok: false, exitCode: 2, message: `--allow <rule[,rule]> is required; delegable rules: ${delegation_1.DELEGABLE_RULES.join(', ')}` };
192
+ for (const a of allow) {
193
+ if (delegation_1.NEVER_DELEGABLE.includes(a))
194
+ return { ok: false, exitCode: 1, message: `rule ${a} is never delegable (${delegation_1.NEVER_DELEGABLE.join(', ')} stay the operator's)` };
195
+ if (!delegation_1.DELEGABLE_RULES.includes(a))
196
+ return { ok: false, exitCode: 1, message: `rule ${a} is not a delegable grader rule; delegable: ${delegation_1.DELEGABLE_RULES.join(', ')}` };
197
+ }
198
+ const limits = {};
199
+ for (const kv of extra.limits ?? []) {
200
+ const eq = kv.indexOf('=');
201
+ if (eq <= 0)
202
+ return { ok: false, exitCode: 2, message: `--limit expects key=value, received: ${kv}` };
203
+ limits[kv.slice(0, eq).trim()] = kv.slice(eq + 1).trim();
204
+ }
205
+ let workspace;
206
+ try {
207
+ workspace = fs.realpathSync.native(root);
208
+ }
209
+ catch (e) {
210
+ return { ok: false, exitCode: 1, message: `the workspace root cannot be resolved: ${e instanceof Error ? e.message : String(e)}` };
211
+ }
212
+ try {
213
+ (0, delegation_1.writeDelegation)(root, { schema: delegation_1.DELEGATION_SCHEMA, run, workspace, allow, issuedAt: io.now, expires, issuedBy: grantedBy,
214
+ ...(Object.keys(limits).length ? { limits } : {}), ...(extra.rationale ? { rationale: extra.rationale } : {}) });
215
+ }
216
+ catch (e) {
217
+ return { ok: false, exitCode: 1, message: `could not write the run delegation: ${e instanceof Error ? e.message : String(e)}` };
218
+ }
219
+ try {
220
+ new ledger_store_1.FileLedgerStore(path.join(root, '.ax', 'ledger')).append({
221
+ ts: io.now, actor: grantedBy, kind: 'autonomy-delegated', summary: `run delegation ${run} until ${expires}`,
222
+ rationale: `covers ${allow.join(', ')}${Object.keys(limits).length ? `; limits ${Object.entries(limits).map(([k, v]) => `${k}=${v}`).join(', ')}` : ''}${extra.rationale ? ` — ${extra.rationale}` : ''}`,
223
+ ...(io.approval ? { authorization: (0, provenance_chain_1.authorizationRef)(io.approval.actor, io.approval.token) } : {}),
224
+ });
225
+ }
226
+ catch { /* the document IS the record; the ledger entry is additive */ }
227
+ return { ok: true, exitCode: 0, message: `run delegation: run ${run} until ${expires} — covers ${allow.join(', ')} in ${workspace}.\n`
228
+ + `Hitl specs whose only reason is a covered rule seal on their own and the ledger names the run and the rule; ${DELEGATION_HOST_NOTE}. End early: holmes-kit autonomy revoke-delegation.` };
229
+ }
141
230
  try {
142
231
  fs.mkdirSync(path.dirname(markerPath), { recursive: true });
143
232
  fs.writeFileSync(markerPath, JSON.stringify({ enabled: true, expires, grantedBy, rationale: `session autonomy for ${mins}m` }, null, 2) + '\n');
@@ -155,5 +244,5 @@ function runAutonomy(root, sub, forStr, io) {
155
244
  return { ok: true, exitCode: 0, message: `autonomous spec approval: ON for this session, until ${expires}.\n`
156
245
  + 'Low-risk specs self-approve; governance-critical, high-risk and irreversible still ask you. End early: holmes-kit autonomy off.' };
157
246
  }
158
- return { ok: false, exitCode: 2, message: 'usage: holmes-kit autonomy [status|on [--for 2h]|off]' };
247
+ return { ok: false, exitCode: 2, message: 'usage: holmes-kit autonomy [status|on [--for 2h]|off|delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]|revoke-delegation]' };
159
248
  }
@@ -710,9 +710,14 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
710
710
  let routed;
711
711
  if (fs.existsSync(runtimeRegistry)) {
712
712
  try {
713
- const report = (0, runtime_binding_1.runtimeBindingStatus)(runtimeRegistry, target ?? process.cwd());
713
+ // @implements A-SPEC-769.8 — the Codex home the duplicate-route check reads is the one doctor was pointed at.
714
+ const report = (0, runtime_binding_1.runtimeBindingStatus)(runtimeRegistry, target ?? process.cwd(), { codexHome: opts?.codexConfigPath ? path.dirname(opts.codexConfigPath) : undefined });
714
715
  const s = report.selection;
715
- if (report.conflicts.length === 0) {
716
+ // @implements A-SPEC-769.6 — the identity is the ROUTER's: conferred when the receipt rows under the registry
717
+ // directory are intact, whatever a settings or workspace wiring row says (those are reported on their own rows
718
+ // and on the `runtime binding` line). Before: any receipt conflict withheld it, and an edited user settings file
719
+ // made doctor call the intact router "not this install's server" (measured 2026-10-12).
720
+ if (report.router === 'intact') {
716
721
  const script = (h, e) => path.join(path.dirname(runtimeRegistry), `${h}-${e}.js`);
717
722
  routed = { script, command: (h, e) => (0, runtime_binding_1.runtimeHookCommand)(runtimeRegistry, h, e),
718
723
  mcp: (h, e) => ['claude', 'codex', 'antigravity'].includes(h) && e?.command === process.execPath
@@ -737,8 +742,21 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
737
742
  catch { /* no build id */ }
738
743
  own = `; doctor runs from ${packageRoot} (build ${ownBuild}); sessions routed by this registry load the package named first`;
739
744
  }
745
+ // @implements A-SPEC-769.3 — drift outside the registry directory is named, not counted as a conflict: the routed
746
+ // identity above is conferred on an intact router, and the line says which operator-owned files changed and which
747
+ // receipt rows belong to a workspace that no longer exists.
748
+ const drift = report.drift ?? [];
749
+ const changedSinceInstall = drift.filter((d) => d.kind === 'operator-config').map((d) => d.path);
750
+ const staleRows = drift.filter((d) => d.kind === 'stale-workspace').map((d) => d.path);
740
751
  add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN', `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}${own}; specs=${s.specsRoot}; live activation unverified`
741
- + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
752
+ + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : '')
753
+ + (changedSinceInstall.length ? `; changed since installation (operator-owned, still routed): ${changedSinceInstall.join(', ')}` : '')
754
+ + (staleRows.length ? `; stale receipt rows (workspace gone): ${staleRows.join(', ')}` : ''), 'Use runtime-binding status and setup --dry-run to inspect routed wiring. Native hook trust and enable state remain operator-controlled.');
755
+ // @implements A-SPEC-769.8 — one WARN per Codex lifecycle routed to Holmes from both the user-level and the
756
+ // workspace hooks file (measured 2026-10-12: the Stop hook ran twice per session end in both X1 fixtures).
757
+ for (const d of report.duplicateRoutes ?? []) {
758
+ add('codex duplicate route', 'WARN', `${d.event} is routed to Holmes from ${d.files[0]} and ${d.files[1]}; Codex runs both, so the ${d.event} hook runs twice per lifecycle (for stop: the Stop scan twice per session end)`, d.fix);
759
+ }
742
760
  // @implements A-SPEC-751.4 — a source checkout whose sessions are routed to another package: say whether the
743
761
  // hooks it builds are the hooks those sessions run. A consumer project holds no package source and gets no row.
744
762
  const checkoutRoot = [target ?? process.cwd(), packageRoot].find((candidate) => {