@holmes-lab/holmes-kit 0.35.18 → 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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,45 @@ 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
+
8
47
  ## [0.35.18] - 2026-10-12
9
48
 
10
49
  ### 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
- **439/441** source files (99.5%) trace to an approved spec · **769/832** approved A-SPECs (92.4%) are anchored from code.
13
- Measured at `32936217f72e` (specs `sha256:889a6e38d4b1`) — 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,7 @@ Measured at `32936217f72e` (specs `sha256:889a6e38d4b1`) — 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.
26
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.
27
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.
28
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.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 313705f8-mv4rnlmn
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('');
@@ -206,7 +206,7 @@ async function runWatch(root, io, actor, opts = {}) {
206
206
  io.print(exports.WATCH_IDLE);
207
207
  idleAnnounced = true;
208
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));
209
+ const footer = (0, approve_1.outsideInboxFooter)((0, approval_queue_1.refusalsOutsideInbox)(root), root); // @implements A-SPEC-770.2
210
210
  if (footer !== null)
211
211
  io.print(footer);
212
212
  }
@@ -63,11 +63,11 @@ export declare function staleView(flags: Record<string, unknown>): {
63
63
  * `approve --grant <id>` reach them). A count and two commands — never a target. `null` when there is nothing to say.
64
64
  * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
65
65
  */
66
- export declare function outsideInboxFooter(outside: number | undefined): string | null;
66
+ export declare function outsideInboxFooter(outside: number | undefined, root?: string): string | null;
67
67
  export declare function renderPending(state: QueueState, view?: {
68
68
  staleHours: number;
69
69
  showAll: boolean;
70
- }, outside?: number): string;
70
+ }, outside?: number, root?: string): string;
71
71
  /**
72
72
  * @implements A-SPEC-262.1
73
73
  * What a decision line must say. Round-1: `✓ approved — valid until <expires>` named NOTHING, so an index
@@ -130,7 +130,7 @@ export declare function renderRefusals(refusals: Array<{
130
130
  target: string;
131
131
  why: string;
132
132
  ts: string;
133
- }>, limit?: number): string;
133
+ }>, limit?: number, root?: string): string;
134
134
  export declare function renderNonTtyHint(state: QueueState): string;
135
135
  export interface ApproveIO {
136
136
  print: (s: string) => void;
@@ -352,16 +352,19 @@ function staleView(flags) {
352
352
  * `approve --grant <id>` reach them). A count and two commands — never a target. `null` when there is nothing to say.
353
353
  * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
354
354
  */
355
- function outsideInboxFooter(outside) {
355
+ function outsideInboxFooter(outside, root) {
356
356
  if (!outside || outside <= 0)
357
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}`;
358
361
  // `◆` rather than the `◇` the spec sketched: §13 (approve-corpus) admits only the template's own glyphs on a decision
359
362
  // row, and U+25C7 is of ambiguous width while U+25C6 is already furniture of this screen.
360
- 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 · grant one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>`;
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}`;
361
364
  }
362
- function renderPending(state, view, outside) {
365
+ function renderPending(state, view, outside, root) {
363
366
  const withFooter = (lines) => {
364
- const footer = outsideInboxFooter(outside);
367
+ const footer = outsideInboxFooter(outside, root);
365
368
  return (footer === null ? lines : [...lines, footer]).join('\n');
366
369
  };
367
370
  if (state.pending.length === 0) {
@@ -485,7 +488,7 @@ function decisionDetail(p, tail = '') {
485
488
  * and this renderer is the reason an operator can find the id the deny message named. Row width
486
489
  * follows the decision list's screen-safe discipline.
487
490
  */
488
- function renderRefusals(refusals, limit = 20) {
491
+ function renderRefusals(refusals, limit = 20, root) {
489
492
  if (refusals.length === 0)
490
493
  return '◆ no refusals recorded on this machine';
491
494
  const recent = refusals.slice(-Math.max(1, limit));
@@ -495,7 +498,9 @@ function renderRefusals(refusals, limit = 20) {
495
498
  lines.push(` \u2502 ${(0, screen_safe_1.rowField)(r.why, 66)} ${(0, screen_safe_1.rowField)(r.ts, 24)}`);
496
499
  }
497
500
  // @implements A-SPEC-770.1 — `--grant <id>`: the positional form this line named since 2026-09-06 is refused.
498
- lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>`);
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}`);
499
504
  return lines.join('\n');
500
505
  }
501
506
  function renderNonTtyHint(state) {
@@ -549,7 +554,7 @@ function renderNonTtyHint(state) {
549
554
  */
550
555
  async function runInteractive(root, io, actor) {
551
556
  const state = (0, approval_queue_1.readQueue)(root);
552
- io.print(renderPending(state, undefined, (0, approval_queue_1.refusalsOutsideInbox)(root))); // @implements A-SPEC-770
557
+ io.print(renderPending(state, undefined, (0, approval_queue_1.refusalsOutsideInbox)(root), root)); // @implements A-SPEC-770, A-SPEC-770.2
553
558
  if (state.pending.length === 0)
554
559
  return;
555
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,7 +710,8 @@ 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
716
  // @implements A-SPEC-769.6 — the identity is the ROUTER's: conferred when the receipt rows under the registry
716
717
  // directory are intact, whatever a settings or workspace wiring row says (those are reported on their own rows
@@ -751,6 +752,11 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
751
752
  + (report.conflicts.length ? `; ${report.conflicts.join('; ')}` : '')
752
753
  + (changedSinceInstall.length ? `; changed since installation (operator-owned, still routed): ${changedSinceInstall.join(', ')}` : '')
753
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
+ }
754
760
  // @implements A-SPEC-751.4 — a source checkout whose sessions are routed to another package: say whether the
755
761
  // hooks it builds are the hooks those sessions run. A consumer project holds no package source and gets no row.
756
762
  const checkoutRoot = [target ?? process.cwd(), packageRoot].find((candidate) => {
@@ -81,7 +81,7 @@ const KNOWN_FLAGS = {
81
81
  'runtime-binding': ['help', 'workspace', 'package', 'release-package', 'registry', 'dry-run', 'activate-hooks'],
82
82
  guidance: ['help', 'target', 'dry-run'],
83
83
  init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent', 'mcp-launcher', 'autonomy', 'no-autonomy'],
84
- autonomy: ['help', 'target', 'for'],
84
+ autonomy: ['help', 'target', 'for', 'run', 'allow', 'limit', 'rationale'], // @implements A-SPEC-771.1 — the run delegation's flags
85
85
  doctor: ['help', 'target', 'json', 'agent', 'registry'],
86
86
  // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
87
87
  attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
@@ -129,6 +129,8 @@ class UnknownFlagError extends Error {
129
129
  // A-SPEC-251.1 (round 26): `yes` — `upgrade --yes` was refused as "--yes requires a value", so the non-interactive
130
130
  // upgrade its own guidance names could not run (measured).
131
131
  const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy', 'yes']); // A-SPEC-650: --status
132
+ /** @implements A-SPEC-771.1 — value flags that may be given more than once. */
133
+ const REPEATABLE_FLAGS = new Set(['limit']);
132
134
  function parseFlags(argv, known) {
133
135
  const flags = {};
134
136
  const positionals = [];
@@ -164,6 +166,15 @@ function parseFlags(argv, known) {
164
166
  // `--target A --target B` acted on B while the operator was looking at A. 'Cannot decide is not
165
167
  // permission' applies to the operator's own contradiction too.
166
168
  if (Object.prototype.hasOwnProperty.call(flags, key)) {
169
+ // @implements A-SPEC-771.1 — `--limit k=v` is the one flag that repeats by design (one limit per flag); the
170
+ // values are joined with a newline, which no argv value carries, and split again by the autonomy command.
171
+ if (REPEATABLE_FLAGS.has(key) && typeof flags[key] === 'string') {
172
+ const more = inline !== undefined ? inline : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : undefined);
173
+ if (more === undefined)
174
+ throw new UnknownFlagError(`--${key} requires a value`);
175
+ flags[key] = `${flags[key]}\n${more}`;
176
+ continue;
177
+ }
167
178
  throw new UnknownFlagError(`--${key} was given more than once — say it once, or the run acts on a directory you did not read`);
168
179
  }
169
180
  if (inline !== undefined) {
@@ -239,7 +250,12 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
239
250
  <ref> list index (1,2,…), full id, or a unique id prefix
240
251
  --target <dir> project root (default: cwd)
241
252
 
242
- holmes-kit autonomy status|on|off grant/end per-session autonomous spec approval
253
+ holmes-kit autonomy status|on|off|delegate|revoke-delegation grant/end autonomous spec approval
254
+ delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]
255
+ run delegation for THIS workspace: hitl specs whose only reason is a
256
+ listed grader rule seal on their own (never architecture-document,
257
+ requirement-without-intake); same human proof as 'on'
258
+ revoke-delegation end the run delegation now (always free; 'off' ends it too)
243
259
  on [--for 2h] self-drive low-risk specs this session (governance-critical still
244
260
  ask you); at a TTY it just asks, non-interactive needs HOLMES_APPROVAL
245
261
  off end it now (always free)
@@ -315,7 +331,7 @@ async function main(argv) {
315
331
  // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
316
332
  const expected = cmd === 'runtime-binding' ? ['setup', 'status', 'remove'] : cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
317
333
  : cmd === 'semantic-key' ? ['set', 'unset', 'status']
318
- : cmd === 'autonomy' ? ['status', 'on', 'off'] : [];
334
+ : cmd === 'autonomy' ? ['status', 'on', 'off', 'delegate', 'revoke-delegation'] : []; // @implements A-SPEC-771.1
319
335
  const unexpected = positionals.filter((p) => !expected.includes(p));
320
336
  if (unexpected.length > 0) {
321
337
  const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
@@ -407,12 +423,15 @@ async function main(argv) {
407
423
  const { runAutonomy } = await Promise.resolve().then(() => __importStar(require('./autonomy')));
408
424
  const root = path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd());
409
425
  const forStr = typeof flags.for === 'string' ? flags.for : undefined;
426
+ // @implements A-SPEC-771.1 — the delegation's own inputs ride through to the core; `--limit` may repeat.
427
+ const str = (k) => (typeof flags[k] === 'string' ? flags[k] : undefined);
428
+ const extra = { run: str('run'), allow: str('allow'), limits: str('limit')?.split('\n'), rationale: str('rationale') };
410
429
  return (0, cli_execution_1.runOperatorExecution)(root, () => {
411
430
  const r = runAutonomy(root, positionals[0], forStr, {
412
431
  now: new Date().toISOString(),
413
432
  isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY,
414
433
  approval: readApproval(),
415
- });
434
+ }, extra);
416
435
  process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
417
436
  return r.exitCode;
418
437
  });
@@ -1004,7 +1023,7 @@ async function main(argv) {
1004
1023
  if (flags.list) {
1005
1024
  // @implements A-SPEC-770 — the list ends with the count of refusals outside it.
1006
1025
  const { refusalsOutsideInbox } = require('../governance/approval-queue');
1007
- process.stdout.write(renderPending(readQueue(root, queueOpts), listView, refusalsOutsideInbox(root)) + '\n');
1026
+ process.stdout.write(renderPending(readQueue(root, queueOpts), listView, refusalsOutsideInbox(root), root) + '\n'); // @implements A-SPEC-770.2
1008
1027
  return 0;
1009
1028
  }
1010
1029
  // @implements A-SPEC-650 — the whole picture, read-only; the list above stays script-clean.
@@ -1022,7 +1041,7 @@ async function main(argv) {
1022
1041
  process.stderr.write(`✗ --refusals expects a positive integer count — received: ${flags.refusals}\n`);
1023
1042
  return 1;
1024
1043
  }
1025
- process.stdout.write(renderRefusals(readRefusals(root), limit) + '\n');
1044
+ process.stdout.write(renderRefusals(readRefusals(root), limit, root) + '\n'); // @implements A-SPEC-770.2
1026
1045
  return 0;
1027
1046
  }
1028
1047
  // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
@@ -33,13 +33,30 @@ export declare function registryWiringOwnership(file: string, registryPath?: str
33
33
  matches: boolean;
34
34
  };
35
35
  export declare function registryOwnedWiring(file: string, registryPath?: string): boolean;
36
- export declare function runtimeBindingStatus(registryPath: string, workspace: string): {
36
+ /**
37
+ * @implements A-SPEC-769.8 — a Codex lifecycle routed to Holmes from BOTH the user-level `hooks.json` and the
38
+ * workspace's `.codex/hooks.json`, while the user-level entry is not switched off in `config.toml` `[hooks.state]`
39
+ * (a missing table or a missing `enabled` key counts as on). Measured 2026-10-12/13: the X1 fixtures' Stop hook wrote
40
+ * two identical cycle rows 1 ms apart because `~/.codex/hooks.json:stop:0:0` carried no `enabled = false` while
41
+ * `pre_tool_use` did. Reads files only; unreadable or absent files contribute nothing (a diagnostic fails open).
42
+ */
43
+ export interface DuplicateRoute {
44
+ harness: 'codex';
45
+ event: 'pre_tool_use' | 'stop' | 'session_start';
46
+ files: string[];
47
+ fix: string;
48
+ }
49
+ export declare function codexDuplicateRoutes(codexHome: string, workspace: string): DuplicateRoute[];
50
+ export declare function runtimeBindingStatus(registryPath: string, workspace: string, opts?: {
51
+ codexHome?: string;
52
+ }): {
37
53
  selection: import("../runtime/binding").RuntimeSelection;
38
54
  conflicts: string[];
39
55
  drift: {
40
56
  path: string;
41
57
  kind: "operator-config" | "stale-workspace";
42
58
  }[];
59
+ duplicateRoutes: DuplicateRoute[];
43
60
  router: "changed" | "intact";
44
61
  activation: "unverified";
45
62
  };