@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.
@@ -38,6 +38,7 @@ exports.runtimeHookCommand = runtimeHookCommand;
38
38
  exports.wiringViewOf = wiringViewOf;
39
39
  exports.registryWiringOwnership = registryWiringOwnership;
40
40
  exports.registryOwnedWiring = registryOwnedWiring;
41
+ exports.codexDuplicateRoutes = codexDuplicateRoutes;
41
42
  exports.runtimeBindingStatus = runtimeBindingStatus;
42
43
  exports.runRuntimeBinding = runRuntimeBinding;
43
44
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
@@ -161,7 +162,78 @@ function registryWiringOwnership(file, registryPath = (0, exports.defaultRuntime
161
162
  function registryOwnedWiring(file, registryPath) {
162
163
  return registryWiringOwnership(file, registryPath).owned;
163
164
  }
164
- function runtimeBindingStatus(registryPath, workspace) {
165
+ const CODEX_LIFECYCLES = [
166
+ ['PreToolUse', 'pre_tool_use', 'pre-tool-use'], ['Stop', 'stop', 'stop'], ['SessionStart', 'session_start', 'session-start'],
167
+ ];
168
+ /** For each lifecycle the file routes to a Holmes router: the `<group>:<hook>` index of that entry. */
169
+ function holmesRoutesIn(file) {
170
+ let doc;
171
+ try {
172
+ const raw = readOptional(file); // a strict decode may throw on bytes Codex itself refuses: nothing to report
173
+ if (raw === null)
174
+ return null;
175
+ doc = JSON.parse(raw);
176
+ }
177
+ catch {
178
+ return null;
179
+ }
180
+ const hooks = doc?.hooks;
181
+ if (!object(hooks))
182
+ return null;
183
+ const out = new Map();
184
+ for (const [jsonKey, stateKey, router] of CODEX_LIFECYCLES) {
185
+ const groups = hooks[jsonKey];
186
+ if (!Array.isArray(groups))
187
+ continue;
188
+ groups.forEach((group, g) => {
189
+ const entries = group?.hooks;
190
+ if (!Array.isArray(entries))
191
+ return;
192
+ entries.forEach((entry, h) => {
193
+ const command = entry?.command;
194
+ if (typeof command !== 'string' || out.has(stateKey))
195
+ return;
196
+ if (/holmes/i.test(command) && command.includes(`${router}.js`))
197
+ out.set(stateKey, `${g}:${h}`);
198
+ });
199
+ });
200
+ }
201
+ return out;
202
+ }
203
+ function codexDuplicateRoutes(codexHome, workspace) {
204
+ const userHooks = path.join(codexHome, 'hooks.json');
205
+ const wsHooks = path.join(workspace, '.codex', 'hooks.json');
206
+ const user = holmesRoutesIn(userHooks);
207
+ const ws = holmesRoutesIn(wsHooks);
208
+ if (user === null || ws === null)
209
+ return [];
210
+ const configPath = path.join(codexHome, 'config.toml');
211
+ let state = {};
212
+ try {
213
+ const rawConfig = readOptional(configPath);
214
+ if (rawConfig !== null) {
215
+ const parsed = (0, codex_toml_1.parseCodexConfig)(rawConfig);
216
+ const table = parsed.ok ? parsed.doc.hooks?.state : undefined;
217
+ if (object(table))
218
+ state = table;
219
+ }
220
+ }
221
+ catch { /* an unreadable config: every entry counts as on, which is what Codex does with a file it cannot load */ }
222
+ const out = [];
223
+ for (const [, stateKey] of CODEX_LIFECYCLES) {
224
+ const index = user.get(stateKey);
225
+ if (index === undefined || !ws.has(stateKey))
226
+ continue;
227
+ const key = `${userHooks}:${stateKey}:${index}`;
228
+ const entry = state[key];
229
+ if (object(entry) && entry.enabled === false)
230
+ continue;
231
+ out.push({ harness: 'codex', event: stateKey, files: [userHooks, wsHooks],
232
+ fix: `set enabled = false under [hooks.state."${key}"] in ${configPath} (or remove the ${stateKey} entry from one file) — Holmes runs once per lifecycle` });
233
+ }
234
+ return out;
235
+ }
236
+ function runtimeBindingStatus(registryPath, workspace, opts) {
165
237
  const registry = (0, binding_1.readRuntimeRegistry)(registryPath);
166
238
  const selection = (0, binding_1.selectRuntime)(registry, { cwd: workspace });
167
239
  const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
@@ -218,7 +290,9 @@ function runtimeBindingStatus(registryPath, workspace) {
218
290
  conflicts.push(`Wiring changed or incomplete: ${row.path}`);
219
291
  }
220
292
  }
221
- return { selection, conflicts, drift, router: routerChanged ? 'changed' : 'intact', activation: 'unverified' };
293
+ // @implements A-SPEC-769.8 — reported beside the receipt verdicts; it changes neither `conflicts` nor `router`.
294
+ const duplicateRoutes = codexDuplicateRoutes(opts?.codexHome ?? path.join(os.homedir(), '.codex'), workspace);
295
+ return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', activation: 'unverified' };
222
296
  }
223
297
  function runRuntimeBinding(opts) {
224
298
  if (opts.activateHooks !== undefined && (!Array.isArray(opts.activateHooks)
@@ -24,7 +24,7 @@ export declare const DECISION_KINDS: ReadonlySet<string>;
24
24
  * The line a refusal ends with to name its pending request and the operator command.
25
25
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
26
26
  */
27
- export declare function pendingRequestLine(id: string, kind?: string): string;
27
+ export declare function pendingRequestLine(id: string, kind?: string, root?: string): string;
28
28
  export interface RefusalRecord {
29
29
  event: 'requested';
30
30
  id: string;
@@ -97,8 +97,14 @@ exports.DECISION_KINDS = new Set([
97
97
  * The line a refusal ends with to name its pending request and the operator command.
98
98
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
99
99
  */
100
- function pendingRequestLine(id, kind) {
100
+ function pendingRequestLine(id, kind, root) {
101
101
  const command = `${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
102
+ // @implements A-SPEC-770.2 — the request lives in the refusal log / queue of the workspace whose hook refused, not in
103
+ // the shell's cwd (measured 2026-10-12: a command run under a worktree filed its request in the development root;
104
+ // 2026-10-13, Codex X1: the hint carried no `--target` at all). With a root, every command names it; a root with
105
+ // white space is double-quoted once; a root is never folded or relativised. Without a root the A-SPEC-770.1 lines
106
+ // are produced byte for byte.
107
+ const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
102
108
  // @implements A-SPEC-770 — a request outside the decision inbox (A-SPEC-563.1 routes gate refusals to the local
103
109
  // refusal log) names the id-bearing command, because the bare command opens a screen that by design does not list
104
110
  // it. Field report (jarvis, 2026-10-11): the operator ran the bare command, saw six old inbox requests, and the
@@ -106,9 +112,9 @@ function pendingRequestLine(id, kind) {
106
112
  // @implements A-SPEC-770.1 — the id rides the `--grant` flag: the CLI refuses a positional id (`unexpected
107
113
  // argument: req-…`, measured by the operator on 0.35.17 with the command this line used to name).
108
114
  if (kind !== undefined && !exports.DECISION_KINDS.has(kind)) {
109
- return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals 로 조회)`;
115
+ return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id}${target} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals${target} 로 조회)`;
110
116
  }
111
- return `\n[승인 대기 ${id}] 운영자: ${command}`;
117
+ return root === undefined ? `\n[승인 대기 ${id}] 운영자: ${command}` : `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id}${target}`;
112
118
  }
113
119
  const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
114
120
  function refusalsFilename(replica) {
@@ -530,7 +536,7 @@ function queueHint(root, req, opts) {
530
536
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
531
537
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
532
538
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
533
- const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id, req.kind)); // @implements A-SPEC-770
539
+ const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id, req.kind, root)); // @implements A-SPEC-770, A-SPEC-770.2
534
540
  return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
535
541
  ? hint
536
542
  : denialLine;
@@ -1,6 +1,4 @@
1
1
  import { Spec } from '../spec/spec-parser';
2
- /** The out-of-band switch. An agent cannot read or set it — the pre-tool-use gate blocks that
3
- * (A-SPEC-532.2), the same self-disarm protection HOLMES_APPROVAL and HOLMES_GATE_BYPASS have. */
4
2
  export declare const AUTONOMY_ENV = "HOLMES_AUTONOMOUS_APPROVAL";
5
3
  export type ApprovalAutonomy = 'auto' | 'hitl';
6
4
  export declare function isHighRiskPath(p: string): boolean;
@@ -64,6 +64,7 @@ const path = __importStar(require("node:path"));
64
64
  const scope_judgment_1 = require("../guardrail/scope-judgment");
65
65
  /** The out-of-band switch. An agent cannot read or set it — the pre-tool-use gate blocks that
66
66
  * (A-SPEC-532.2), the same self-disarm protection HOLMES_APPROVAL and HOLMES_GATE_BYPASS have. */
67
+ const delegation_1 = require("./delegation"); // @implements A-SPEC-771 — the run delegation, the third envelope
67
68
  exports.AUTONOMY_ENV = 'HOLMES_AUTONOMOUS_APPROVAL';
68
69
  /**
69
70
  * Path prefixes whose files govern the gate, the ledger, taint boundaries, or this session's own
@@ -330,16 +331,25 @@ function autonomousApprovalEnabled(env, root, now) {
330
331
  return true;
331
332
  if (root !== undefined && projectDefaultAutonomy(root))
332
333
  return true; // @implements A-SPEC-560.2
333
- return root !== undefined && now !== undefined && sessionAutonomyActive(root, now);
334
+ if (root !== undefined && now !== undefined && sessionAutonomyActive(root, now))
335
+ return true;
336
+ // @implements A-SPEC-771 — an active run delegation is the third envelope: ON for its workspace while it is valid.
337
+ return root !== undefined && now !== undefined && (0, delegation_1.readDelegation)(root, now).active;
334
338
  }
335
339
  // @implements A-SPEC-554.1 — the session-start REMINDER (the headless hook surfaces, it never decides).
336
340
  // Only ON postures get a line; OFF is silent (a permanent line is one nobody reads). Wired below.
337
341
  function autonomyBanner(env, root, now) {
338
342
  const v = env[exports.AUTONOMY_ENV];
343
+ // @implements A-SPEC-771 — one added line names an active run delegation, beside whichever posture line applies.
344
+ const delegation = (0, delegation_1.readDelegation)(root, now);
345
+ const runLine = delegation.active
346
+ ? `[Holmes-Kit] run delegation: ${delegation.delegation.run} until ${delegation.delegation.expires} — covers ${delegation.delegation.allow.join(', ')}`
347
+ : '';
348
+ const withRun = (line) => (runLine === '' ? line : line === '' ? runLine : `${line}\n${runLine}`);
339
349
  // @implements A-SPEC-560.2 — the project default is visible via env (server-side) OR .mcp.json
340
350
  // (hook-side); either way the banner names the same posture.
341
351
  if ((typeof v === 'string' && v !== '') || projectDefaultAutonomy(root)) {
342
- return '[Holmes-Kit] autonomous spec approval: ON (project default) — governance-critical, high-risk and irreversible specs still ask you.';
352
+ return withRun('[Holmes-Kit] autonomous spec approval: ON (project default) — governance-critical, high-risk and irreversible specs still ask you.');
343
353
  }
344
354
  if (sessionAutonomyActive(root, now)) {
345
355
  let expires = '';
@@ -347,9 +357,9 @@ function autonomyBanner(env, root, now) {
347
357
  expires = String(JSON.parse(fs.readFileSync(path.join(root, ...exports.SESSION_AUTONOMY_MARKER), 'utf8')).expires);
348
358
  }
349
359
  catch { /* the marker parsed inside sessionAutonomyActive; a stray read failure just omits the time */ }
350
- return `[Holmes-Kit] autonomous spec approval: ON (this session, until ${expires}) — governance-critical still ask you. End early: holmes-kit autonomy off.`;
360
+ return withRun(`[Holmes-Kit] autonomous spec approval: ON (this session, until ${expires}) — governance-critical still ask you. End early: holmes-kit autonomy off.`);
351
361
  }
352
- return '';
362
+ return withRun('');
353
363
  }
354
364
  // @implements A-SPEC-554.1 — true when a marker file exists but is NOT active (expired / disabled /
355
365
  // malformed): housekeeping the headless hook may do. A LIVE envelope is never prunable.
@@ -0,0 +1,40 @@
1
+ export declare const DELEGATION_MARKER: readonly [".ax", "state", "delegation.json"];
2
+ export declare const DELEGATION_SCHEMA = "run-delegation/1";
3
+ /** Grader rules an operator may delegate for a run (bare names; a suffixed rule is matched by its bare name). */
4
+ export declare const DELEGABLE_RULES: readonly string[];
5
+ /** Never delegable, whatever the document says: a decision, an un-admitted requirement, an undeclared or unknown grade. */
6
+ export declare const NEVER_DELEGABLE: readonly string[];
7
+ export interface RunDelegation {
8
+ schema: typeof DELEGATION_SCHEMA;
9
+ run: string;
10
+ workspace: string;
11
+ allow: string[];
12
+ issuedAt: string;
13
+ expires: string;
14
+ issuedBy: string;
15
+ limits?: Record<string, string>;
16
+ rationale?: string;
17
+ }
18
+ export type DelegationState = {
19
+ active: true;
20
+ delegation: RunDelegation;
21
+ } | {
22
+ active: false;
23
+ why: 'none' | 'expired' | 'workspace-mismatch' | 'unreadable' | 'invalid';
24
+ expires?: string;
25
+ workspace?: string;
26
+ run?: string;
27
+ };
28
+ export declare const RUN_ID_RE: RegExp;
29
+ /** The bare rule name a grader reason resolves to: the child rule of an upstream reason, with any `: <argument>` dropped. */
30
+ export declare function baseRule(rule: string): string;
31
+ /** Read the document for `root` as it stands at `now`. Fail-closed: anything unreadable or malformed grants nothing. */
32
+ export declare function readDelegation(root: string, now: string): DelegationState;
33
+ /** Whether an active delegation covers the grader reason `rule` (its bare name must be delegable and in `allow`). */
34
+ export declare function delegationCovers(d: RunDelegation, rule: string): boolean;
35
+ /** The one refusal line that names which limit of the delegation applied (empty when there is no document). */
36
+ export declare function delegationNote(state: DelegationState, rule: string): string;
37
+ /** Write the document for the CLI (operator proof is the caller's job). Returns the written document. */
38
+ export declare function writeDelegation(root: string, d: RunDelegation): void;
39
+ /** Remove the document; true when one was there. Never throws on absence. */
40
+ export declare function removeDelegation(root: string): boolean;
@@ -0,0 +1,151 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.RUN_ID_RE = exports.NEVER_DELEGABLE = exports.DELEGABLE_RULES = exports.DELEGATION_SCHEMA = exports.DELEGATION_MARKER = void 0;
37
+ exports.baseRule = baseRule;
38
+ exports.readDelegation = readDelegation;
39
+ exports.delegationCovers = delegationCovers;
40
+ exports.delegationNote = delegationNote;
41
+ exports.writeDelegation = writeDelegation;
42
+ exports.removeDelegation = removeDelegation;
43
+ // @implements A-SPEC-771
44
+ // The run delegation — the third autonomy envelope. Measured need (X1, 2026-10-12): a benchmark fixture the operator
45
+ // had approved as a whole still stopped on `upstream-has-human-aspec: … — files-to-touch-root-only`, because neither
46
+ // the project default (A-SPEC-552.1) nor the session marker (A-SPEC-553.1) can name a run, a workspace boundary or a
47
+ // grader rule. This document can. It is written only by the operator CLI under operator proof, lives under the
48
+ // protected state directory an agent cannot write, binds to the workspace by realpath, expires, and covers a CLOSED
49
+ // set of grader rules — never the NEVER set. The grader itself is untouched: this module only answers "does the
50
+ // operator's delegation cover the rule the grader named?".
51
+ const fs = __importStar(require("node:fs"));
52
+ const path = __importStar(require("node:path"));
53
+ exports.DELEGATION_MARKER = ['.ax', 'state', 'delegation.json'];
54
+ exports.DELEGATION_SCHEMA = 'run-delegation/1';
55
+ /** Grader rules an operator may delegate for a run (bare names; a suffixed rule is matched by its bare name). */
56
+ exports.DELEGABLE_RULES = [
57
+ 'files-to-touch-root-only', 'files-to-touch-gate-file', 'breaking-change-gate-behavior', 'upstream-without-aspec',
58
+ ];
59
+ /** Never delegable, whatever the document says: a decision, an un-admitted requirement, an undeclared or unknown grade. */
60
+ exports.NEVER_DELEGABLE = [
61
+ 'architecture-document', 'requirement-without-intake', 'breaking-change-undeclared', 'unknown-kind',
62
+ ];
63
+ exports.RUN_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
64
+ /** The bare rule name a grader reason resolves to: the child rule of an upstream reason, with any `: <argument>` dropped. */
65
+ function baseRule(rule) {
66
+ const upstream = /^upstream-has-human-aspec: \S+ — (.+)$/.exec(rule);
67
+ const inner = upstream ? upstream[1] : rule;
68
+ return inner.split(':')[0].trim();
69
+ }
70
+ function realpathOrNull(p) {
71
+ try {
72
+ return fs.realpathSync.native(p);
73
+ }
74
+ catch {
75
+ return null;
76
+ }
77
+ }
78
+ /** Read the document for `root` as it stands at `now`. Fail-closed: anything unreadable or malformed grants nothing. */
79
+ function readDelegation(root, now) {
80
+ const file = path.join(root, ...exports.DELEGATION_MARKER);
81
+ let raw;
82
+ try {
83
+ raw = fs.readFileSync(file, 'utf8');
84
+ }
85
+ catch (e) {
86
+ return e.code === 'ENOENT' ? { active: false, why: 'none' } : { active: false, why: 'unreadable' };
87
+ }
88
+ let doc;
89
+ try {
90
+ doc = JSON.parse(raw);
91
+ }
92
+ catch {
93
+ return { active: false, why: 'unreadable' };
94
+ }
95
+ if (!doc || typeof doc !== 'object')
96
+ return { active: false, why: 'invalid' };
97
+ const d = doc;
98
+ const str = (v) => typeof v === 'string' && v.trim() !== '';
99
+ if (d.schema !== exports.DELEGATION_SCHEMA || !str(d.run) || !exports.RUN_ID_RE.test(d.run) || !str(d.workspace) || !str(d.expires) || !str(d.issuedBy) || !Array.isArray(d.allow)) {
100
+ return { active: false, why: 'invalid' };
101
+ }
102
+ const allow = d.allow.filter((a) => typeof a === 'string');
103
+ if (allow.length !== d.allow.length || allow.length === 0)
104
+ return { active: false, why: 'invalid' };
105
+ // A NEVER rule anywhere in `allow` voids the document: the CLI never writes one, so its presence is a forgery or a
106
+ // hand edit, and a forged document must not cover even the rules it names correctly.
107
+ if (allow.some((a) => !exports.DELEGABLE_RULES.includes(a)))
108
+ return { active: false, why: 'invalid' };
109
+ const exp = Date.parse(d.expires);
110
+ const nowMs = Date.parse(now);
111
+ if (!Number.isFinite(exp) || !Number.isFinite(nowMs) || nowMs >= exp)
112
+ return { active: false, why: 'expired', expires: d.expires, run: d.run };
113
+ const here = realpathOrNull(root);
114
+ const there = realpathOrNull(d.workspace);
115
+ if (here === null || there === null || here !== there)
116
+ return { active: false, why: 'workspace-mismatch', workspace: d.workspace, run: d.run };
117
+ return { active: true, delegation: { schema: exports.DELEGATION_SCHEMA, run: d.run, workspace: d.workspace, allow, issuedAt: str(d.issuedAt) ? d.issuedAt : '', expires: d.expires, issuedBy: d.issuedBy,
118
+ ...(d.limits && typeof d.limits === 'object' ? { limits: d.limits } : {}), ...(str(d.rationale) ? { rationale: d.rationale } : {}) } };
119
+ }
120
+ /** Whether an active delegation covers the grader reason `rule` (its bare name must be delegable and in `allow`). */
121
+ function delegationCovers(d, rule) {
122
+ const bare = baseRule(rule);
123
+ if (exports.NEVER_DELEGABLE.includes(bare) || !exports.DELEGABLE_RULES.includes(bare))
124
+ return false;
125
+ return d.allow.includes(bare);
126
+ }
127
+ /** The one refusal line that names which limit of the delegation applied (empty when there is no document). */
128
+ function delegationNote(state, rule) {
129
+ if (state.active)
130
+ return delegationCovers(state.delegation, rule) ? '' : `\n[delegation: run ${state.delegation.run} does not cover ${rule}]`;
131
+ switch (state.why) {
132
+ case 'none': return '';
133
+ case 'expired': return `\n[delegation: expired ${state.expires ?? '?'}]`;
134
+ case 'workspace-mismatch': return `\n[delegation: for ${state.workspace ?? '?'}, not this root]`;
135
+ case 'unreadable': return '\n[delegation: unreadable document — covers nothing]';
136
+ case 'invalid': return '\n[delegation: invalid document (schema, run id, expiry or a rule outside the delegable set) — covers nothing]';
137
+ }
138
+ }
139
+ /** Write the document for the CLI (operator proof is the caller's job). Returns the written document. */
140
+ function writeDelegation(root, d) {
141
+ const file = path.join(root, ...exports.DELEGATION_MARKER);
142
+ fs.mkdirSync(path.dirname(file), { recursive: true });
143
+ fs.writeFileSync(file, JSON.stringify(d, null, 2) + '\n');
144
+ }
145
+ /** Remove the document; true when one was there. Never throws on absence. */
146
+ function removeDelegation(root) {
147
+ const file = path.join(root, ...exports.DELEGATION_MARKER);
148
+ const existed = fs.existsSync(file);
149
+ fs.rmSync(file, { force: true });
150
+ return existed;
151
+ }
@@ -94,6 +94,16 @@ export declare function patchAmbiguous(text: string): boolean;
94
94
  * pattern over the whole text, nothing to back-track on.
95
95
  */
96
96
  export declare function canonicalPatch(text: string): boolean;
97
+ /**
98
+ * @implements A-SPEC-769.7 — WHY a text is not canonical, for the refusal that names it. `null` when `canonicalPatch`
99
+ * is true; `'no-op'` when every grammar rule holds and the only fault is an update block with no `+`/`-` line (the
100
+ * X1 HB negative control, 2026-10-13: a context-only `apply_patch` was refused as "file_path missing" although its
101
+ * header named the file); `'grammar'` for every other shape. Invariant pinned by its test: `canonicalPatch(t) ===
102
+ * (canonicalPatchReason(t) === null)`. The walk is the same walk as `canonicalPatch`, with one difference: an update
103
+ * block that closes with zero content lines is counted instead of refused, and an add block that adds nothing stays a
104
+ * grammar fault (an add must add). This function changes no gate decision — only the reason text a caller prints.
105
+ */
106
+ export declare function canonicalPatchReason(text: string): null | 'no-op' | 'grammar';
97
107
  /** Every header is a target, in order; nothing is merged or dropped by path (A-SPEC-163.2 rule 2). */
98
108
  export declare function patchTargetsOf(text: string): PatchTarget[];
99
109
  /**
@@ -41,6 +41,7 @@ exports.hasPatchEnvelope = hasPatchEnvelope;
41
41
  exports.isWholePatch = isWholePatch;
42
42
  exports.patchAmbiguous = patchAmbiguous;
43
43
  exports.canonicalPatch = canonicalPatch;
44
+ exports.canonicalPatchReason = canonicalPatchReason;
44
45
  exports.patchTargetsOf = patchTargetsOf;
45
46
  exports.applyPatchUpdate = applyPatchUpdate;
46
47
  exports.applyPatchUpdateDetailed = applyPatchUpdateDetailed;
@@ -315,6 +316,87 @@ function canonicalPatch(text) {
315
316
  }
316
317
  return block !== null && closes();
317
318
  }
319
+ /**
320
+ * @implements A-SPEC-769.7 — WHY a text is not canonical, for the refusal that names it. `null` when `canonicalPatch`
321
+ * is true; `'no-op'` when every grammar rule holds and the only fault is an update block with no `+`/`-` line (the
322
+ * X1 HB negative control, 2026-10-13: a context-only `apply_patch` was refused as "file_path missing" although its
323
+ * header named the file); `'grammar'` for every other shape. Invariant pinned by its test: `canonicalPatch(t) ===
324
+ * (canonicalPatchReason(t) === null)`. The walk is the same walk as `canonicalPatch`, with one difference: an update
325
+ * block that closes with zero content lines is counted instead of refused, and an add block that adds nothing stays a
326
+ * grammar fault (an add must add). This function changes no gate decision — only the reason text a caller prints.
327
+ */
328
+ function canonicalPatchReason(text) {
329
+ const lines = text.split('\n').map(unCR);
330
+ let start = 0;
331
+ let end = lines.length;
332
+ while (start < end && lines[start].trim() === '')
333
+ start++;
334
+ while (end > start && lines[end - 1].trim() === '')
335
+ end--;
336
+ if (end - start < 3 || lines[start] !== PATCH_BEGIN || lines[end - 1] !== PATCH_END)
337
+ return 'grammar';
338
+ let block = null;
339
+ let content = 0;
340
+ let sinceHeader = 0;
341
+ let moved = false;
342
+ let emptyUpdates = 0;
343
+ const closes = () => {
344
+ if (block === 'update' && content === 0) {
345
+ emptyUpdates++;
346
+ return true;
347
+ }
348
+ return block === null || block === 'delete' || content > 0;
349
+ };
350
+ for (let i = start + 1; i < end - 1; i++) {
351
+ const line = lines[i];
352
+ if (PATCH_LINE_BREAK.test(line))
353
+ return 'grammar';
354
+ if (line === PATCH_BEGIN || line === PATCH_END)
355
+ return 'grammar';
356
+ if (line.startsWith('*** ')) {
357
+ if (line === PATCH_EOF) {
358
+ if (block !== 'update')
359
+ return 'grammar';
360
+ sinceHeader++;
361
+ continue;
362
+ }
363
+ if (line.startsWith(PATCH_MOVE)) {
364
+ if (block !== 'update' || sinceHeader !== 0 || moved || !canonicalPath(line.slice(PATCH_MOVE.length)))
365
+ return 'grammar';
366
+ moved = true;
367
+ sinceHeader++;
368
+ continue;
369
+ }
370
+ const header = PATCH_FILE_HEADERS.find(([prefix]) => line.startsWith(prefix));
371
+ if (header === undefined || !canonicalPath(line.slice(header[0].length)) || !closes())
372
+ return 'grammar';
373
+ block = header[1];
374
+ content = 0;
375
+ sinceHeader = 0;
376
+ moved = false;
377
+ continue;
378
+ }
379
+ if (block === 'add') {
380
+ if (!line.startsWith('+'))
381
+ return 'grammar';
382
+ content++;
383
+ continue;
384
+ }
385
+ if (block !== 'update')
386
+ return 'grammar';
387
+ sinceHeader++;
388
+ if (line === '@@' || line.startsWith('@@ '))
389
+ continue;
390
+ const head = line.charAt(0);
391
+ if (head === '+' || head === '-')
392
+ content++;
393
+ else if (head !== ' ')
394
+ return 'grammar';
395
+ }
396
+ if (block === null || !closes())
397
+ return 'grammar';
398
+ return emptyUpdates > 0 ? 'no-op' : null;
399
+ }
318
400
  /** Every header is a target, in order; nothing is merged or dropped by path (A-SPEC-163.2 rule 2). */
319
401
  function patchTargetsOf(text) {
320
402
  if (!text.includes('*** '))
@@ -94,7 +94,9 @@ export interface HookInput {
94
94
  /** @implements A-SPEC-163.2 — the payload carries a patch whose targets cannot be read one way; denied whichever tool sent it. */
95
95
  patchUnreadable?: boolean;
96
96
  /** @implements A-SPEC-163.7 — set only when the one cause is a marked shell command (A-SPEC-163.6 rule 3). */
97
- patchUnreadableCause?: 'shell-marker';
97
+ /** @implements A-SPEC-769.7 — `'no-op'`: the one cause is an update block with no `+`/`-` line; the paths are named. */
98
+ patchUnreadableCause?: 'shell-marker' | 'no-op';
99
+ patchNoopPaths?: string[];
98
100
  }
99
101
  /**
100
102
  * @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
@@ -955,6 +955,9 @@ const PATCH_UNREADABLE_REASON = '[Holmes-Kit] cannot read the edit target path,
955
955
  // @implements A-SPEC-768.2 — a patch the tool could not apply is told so, by file and chunk; measured 2026-10-11 (H0 arm)
956
956
  // the path-missing sentence above was returned for a readable file whose patch simply did not apply.
957
957
  const patchNotAppliedReason = (file, why) => `[Holmes-Kit] the patch does not apply to ${file} as it stands (${why}), so the result cannot be judged`;
958
+ // @implements A-SPEC-769.7 — a context-only update is refused by its own name (measured 2026-10-13, X1 HB control: the
959
+ // path-missing sentence was printed for a patch whose header named the file). The deny is unchanged; the reason is not.
960
+ const patchNoopReason = (files) => `[Holmes-Kit] the patch to ${files.join(', ')} adds or removes no line (a context-only update is a no-op), so there is nothing to judge — include at least one + or - line`;
958
961
  // @implements A-SPEC-163.7 — the refusal of A-SPEC-163.6 rule 3 in its own words (each refusal names its channel, A-SPEC-737).
959
962
  const SHELL_MARKED_REASON = '[Holmes-Kit] this shell command mentions the patch tool or a patch marker and is not one plain read, so it is not judged — '
960
963
  + 'search with the harness\'s own search tool, or run one plain grep, egrep, fgrep, rg, cat, head, tail, wc or ls with literal words (no pipe, redirect or substitution)';
@@ -1032,6 +1035,7 @@ function normalizeHookInput(raw) {
1032
1035
  // A patch that cannot be read one way (no target, an empty path, too many, an indented header) is unreadable.
1033
1036
  const toolName = (str(r.tool_name) ?? '').toLowerCase();
1034
1037
  let patchUnreadable = false;
1038
+ let noopPaths = null; // @implements A-SPEC-769.7
1035
1039
  // @implements A-SPEC-163.7 — why: a shell command refused for a patch marker is told so (it has no file path to miss).
1036
1040
  let shellMarked = false;
1037
1041
  let otherUnreadable = false;
@@ -1078,13 +1082,22 @@ function normalizeHookInput(raw) {
1078
1082
  if (targets.length === 0 || targets.length > write_target_1.PATCH_TARGETS_MAX || patches.some((text) => !(0, write_target_1.canonicalPatch)(text))) {
1079
1083
  patchUnreadable = true;
1080
1084
  otherUnreadable = true;
1085
+ // @implements A-SPEC-769.7 — when the targets are readable and the only fault is a context-only update block,
1086
+ // the refusal names that condition and those paths instead of a missing path.
1087
+ if (targets.length > 0 && targets.length <= write_target_1.PATCH_TARGETS_MAX) {
1088
+ const reasons = patches.map(write_target_1.canonicalPatchReason);
1089
+ if (reasons.every((why) => why === null || why === 'no-op') && reasons.includes('no-op')) {
1090
+ noopPaths = targets.filter((t) => t.kind === 'update' && !/^[+-]/m.test(t.hunk ?? '')).map((t) => t.path);
1091
+ }
1092
+ }
1081
1093
  }
1082
1094
  else
1083
1095
  out.patch_targets = targets;
1084
1096
  }
1085
1097
  }
1086
1098
  return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(malformed ? { malformed: true } : {}),
1087
- ...(patchUnreadable ? { patchUnreadable: true } : {}), ...(shellMarked && !otherUnreadable ? { patchUnreadableCause: 'shell-marker' } : {}) };
1099
+ ...(patchUnreadable ? { patchUnreadable: true } : {}), ...(shellMarked && !otherUnreadable ? { patchUnreadableCause: 'shell-marker' } : {}),
1100
+ ...(noopPaths !== null && !shellMarked ? { patchUnreadableCause: 'no-op', patchNoopPaths: noopPaths } : {}) };
1088
1101
  }
1089
1102
  /**
1090
1103
  * Which way to fail when the gate itself throws.
@@ -1236,8 +1249,11 @@ function evaluateHook(input, specsDir, opts) {
1236
1249
  // a patch that cannot be read or applied is denied. When no target is denied, a payload with a path field or a
1237
1250
  // shell command is then judged as before.
1238
1251
  if (input.patchUnreadable) {
1239
- return { permissionDecision: 'deny', permissionDecisionReason: input.patchUnreadableCause === 'shell-marker'
1240
- ? SHELL_MARKED_REASON : PATCH_UNREADABLE_REASON };
1252
+ const cause = input;
1253
+ // @implements A-SPEC-769.7 — four conditions, four sentences: shell marker, no-op update, and (below) the
1254
+ // path-missing sentence for a payload whose targets cannot be read; non-application has its own site.
1255
+ return { permissionDecision: 'deny', permissionDecisionReason: cause.patchUnreadableCause === 'shell-marker'
1256
+ ? SHELL_MARKED_REASON : cause.patchUnreadableCause === 'no-op' ? patchNoopReason(cause.patchNoopPaths ?? []) : PATCH_UNREADABLE_REASON };
1241
1257
  }
1242
1258
  const patchTargets = input.tool_input.patch_targets;
1243
1259
  if (patchTargets !== undefined && !input.malformed) {
@@ -2598,7 +2614,9 @@ function evaluateHook(input, specsDir, opts) {
2598
2614
  if (!hint) {
2599
2615
  const id = (0, approval_queue_1.approvalRequestId)('code-write', relPath);
2600
2616
  if ((0, approval_queue_1.readQueue)(projectRoot).pending.some((request) => request.id === id)) {
2601
- hint = (0, approval_queue_1.pendingRequestLine)(id);
2617
+ // @implements A-SPEC-770.2 — the already-pending line names the same kind and workspace the filing line
2618
+ // did, so the two refusals of one request read the same (gate-isolation pins their equality).
2619
+ hint = (0, approval_queue_1.pendingRequestLine)(id, 'code-write', projectRoot);
2602
2620
  }
2603
2621
  }
2604
2622
  return {
@@ -97,7 +97,7 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
97
97
  advisoryIds?: Partial<Record<string, string>> | undefined;
98
98
  killsAdvisory?: import("../../review/kills-check").KillsAdvisory | undefined;
99
99
  fttFulfilment?: import("../../rtm/ftt-fulfilment").FttFulfilment | undefined;
100
- impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
100
+ impactAdvisoryUnavailable?: "unreadable" | "empty" | undefined;
101
101
  impactGraph?: {
102
102
  status: "current" | "stale" | "unverified";
103
103
  sourceCommit: string | null;
@@ -46,6 +46,7 @@ const validator_1 = require("../../spec/validator");
46
46
  const elicit_approval_1 = require("../elicit-approval");
47
47
  const autonomy_1 = require("../../governance/autonomy");
48
48
  const write_target_1 = require("../../guardrail/write-target");
49
+ const delegation_1 = require("../../governance/delegation"); // @implements A-SPEC-771
49
50
  const approval_grants_1 = require("../../governance/approval-grants");
50
51
  const spec_digest_1 = require("../../spec/spec-digest");
51
52
  const version_conflict_1 = require("../../spec/version-conflict");
@@ -189,10 +190,28 @@ function createSpecApprovalHandlers(context) {
189
190
  risk = 'hitl';
190
191
  if (autonomyOn && risk === 'hitl') {
191
192
  const rule = noIntake ? 'requirement-without-intake' : (0, autonomy_1.specApprovalAutonomyReason)(target.spec, resolver([target.spec]), below);
192
- if (rule !== null)
193
+ if (rule !== null) {
193
194
  autonomyNote = `\n[autonomy: this seal is the operator's — ${rule} (${(0, autonomy_1.autonomyRuleMeaning)(rule)})]`;
195
+ // @implements A-SPEC-771 — the operator's run delegation may cover this very rule: then the seal proceeds
196
+ // as a DELEGATED grant (actor `delegated:<client>`, the run and the rule in the ledger) and no person is
197
+ // asked; otherwise the refusal names which limit of the delegation applied. The grader's verdict above
198
+ // is unchanged — only its consumer learned a third envelope (A-SPEC-552.1 project default, A-SPEC-553.1
199
+ // session marker, and this).
200
+ const delegation = autonomyRoot === undefined ? { active: false, why: 'none' } : (0, delegation_1.readDelegation)(autonomyRoot, new Date().toISOString());
201
+ if (delegation.active && (0, delegation_1.delegationCovers)(delegation.delegation, rule)) {
202
+ const base = autonomousApproval(below?.map((s) => s.id));
203
+ approveResolved = { approval: { ...base, actor: base.actor.replace(/^autonomous:/, 'delegated:'), rationale: `delegated grant (run ${delegation.delegation.run}, rule ${rule})` }, source: 'delegated' };
204
+ decidedSubject = targetSubject;
205
+ }
206
+ else {
207
+ autonomyNote += (0, delegation_1.delegationNote)(delegation, rule);
208
+ }
209
+ }
210
+ }
211
+ if (approveResolved !== undefined) {
212
+ // @implements A-SPEC-771 — delegated above: the existing seal path owns validation and audit from here.
194
213
  }
195
- if (autonomyOn && risk === 'auto') {
214
+ else if (autonomyOn && risk === 'auto') {
196
215
  approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
197
216
  decidedSubject = targetSubject;
198
217
  const direction = (0, autonomy_1.declaredGateDirection)(target.spec);