@holmes-lab/holmes-kit 0.35.1 → 0.35.2

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,53 @@ 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.2] - 2026-10-05
9
+
10
+ ### Security
11
+
12
+ - **A protected store path is recognised wherever it is spelled** (A-SPEC-226.1, A-SPEC-226.2). Through 0.35.1 the
13
+ gate recognised a protected `.ax` store path in a shell command only after white space, a quote, `=`, `(` or `/`.
14
+ A path spelled directly after a shell expansion, a variable, or a letter the shell removes at run time was not seen
15
+ as protected, so a removal, move or overwrite of sealed specs, the ledger or the approval queue could pass without
16
+ a refusal. The spelling now counts wherever it appears in the command, and an output redirect to a computed target
17
+ is no longer treated as a read. Found by independent review; upgrade is recommended for every governed project.
18
+ Cost: a real directory whose name ends in `.ax` and holds a child named like the store's (`backup.ax/specs`) is
19
+ judged as the store; reads still pass. Known limit, unchanged: a path assembled so that the store spelling never
20
+ appears in the command text.
21
+
22
+ ### Fixed
23
+
24
+ - **`init` and `upgrade` leave wiring that the operator runtime registry owns** (A-SPEC-752.8). On a machine with a
25
+ runtime registry, `init --agent codex` (and so `upgrade`) rewrote the user-level Codex config and hooks files that a
26
+ reviewed `runtime-binding setup` plan had written, replacing the dispatcher wiring with direct entries. A wiring
27
+ file listed in the registry's installation receipt is now left byte for byte, `--force` included, and the report
28
+ says why. Not covered: a sibling file the receipt does not list is still created.
29
+ - **In-session approval works under the runtime dispatcher** (A-SPEC-751.3). The server decides whether a harness
30
+ launched it by walking up its parent processes; the registry's `<harness>-mcp.js` dispatcher was not a known
31
+ launcher, so on a registered machine the approval dialog never opened and every approval fell to an out-of-band
32
+ command. The receipted dispatcher is now recognised. Takes effect once the new build is bound and the session is
33
+ restarted; not yet observed live.
34
+ - **A marked shell refusal says what it is** (A-SPEC-163.7). A shell command refused for mentioning the patch tool was
35
+ told an edit's `file_path` was missing. It now gets its own reason naming the plain reads that pass.
36
+ - **`git check-ignore` over the store is a read** (A-SPEC-747.1). The rest of A-SPEC-747.1 (not counting a write verb
37
+ inside another word) was withdrawn after review showed it let real writes through; those read-only commands are
38
+ still refused.
39
+
40
+ ### Changed
41
+
42
+ - **Autonomous approval covers gate changes that only tighten or only reword** (A-SPEC-532.4). An A-SPEC that declares
43
+ `gate-behavior: tightens — …` or `gate-behavior: wording — …` is sealed without the operator even when it touches
44
+ gate files; any other gate change still asks. The seal event records the declared direction.
45
+ - **A seal handed to the operator names the rule** (A-SPEC-532.3). The refusal carries the grading rule that fired, and
46
+ the pending hint also offers the resident approval surface (`approve --watch`).
47
+ - **An approval bound to its content does not expire** (A-SPEC-532.5). A grant made for a request that carries a
48
+ content digest, without `--ttl`, has no time limit: it ends when used, revoked, or when the approved content
49
+ changes. Grants without a content digest keep the 30-minute default. Not yet changed: the in-session dialog's own
50
+ time limit, and the status view still shows such a grant with a far date.
51
+ - **`doctor` and `runtime-binding setup` say more** (A-SPEC-751.2, A-SPEC-752.7). `doctor` names its own package when
52
+ the registry routes sessions to a different one; the setup report lists changed files that git tracks and how to
53
+ keep them local.
54
+
8
55
  ## [0.35.1] - 2026-10-04
9
56
 
10
57
  ### Fixed
package/README.md CHANGED
@@ -23,6 +23,8 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **The protected store is recognised however a shell command spells it** *(new in 0.35.2 — security fix, upgrade recommended)*: through 0.35.1 a path into `.ax/specs`, `.ax/ledger`, `.ax/approvals` or `.ax/state` written directly after a shell expansion, a variable, or a character the shell removes at run time was not seen as protected, so a removal, move or overwrite of governance state could pass the gate. The store spelling now counts wherever it appears in a command, and an output redirect to a computed target is not a read. Reads still pass. A directory that merely ends in `.ax` and has a child named like the store's is judged as the store. Limit: a path assembled so the spelling never appears in the command text is outside this rule.
27
+ - **Approvals that fit how people work** *(new in 0.35.2)*: an approval for a request that carries the approved content's digest (a spec seal) no longer expires after 30 minutes — it stays valid until used, revoked, or the content changes (`--ttl` still bounds it; requests without a digest keep the default). With autonomous approval on, a gate change declared `gate-behavior: tightens — …` or `gate-behavior: wording — …` is sealed without the operator; any other gate change still asks, and a seal handed to the operator says which rule handed it over. On a machine with a runtime registry the in-session approval dialog is reachable again, and `init`/`upgrade` no longer replace wiring the registry owns. Not yet changed: the in-session dialog's own time limit.
26
28
  - **Separate development and consumer runtimes** *(new in 0.35.0)*: `runtime-binding setup` explicitly registers a checkout and its built package in an operator-owned registry. Normal Claude, Codex and Antigravity launches select that development package for the registered workspace; other workspaces select the configured release. Missing or conflicting bindings refuse with diagnosis instead of silently switching builds. Setup previews exact changes and requires authority for a changed installation; a validated unchanged plan needs no new grant. Normal migration preserves disabled hooks and native trust. `--activate-hooks` explicitly restores selected Holmes entries, while native trust and global disable switches still require native review. See [development runtime setup and recovery](docs/install-guide.md#development-and-consumer-runtime-binding) for the workflow and current approval limitation. Configuration readiness does not prove live three-harness enforcement.
27
29
  - **Bounded routed-hook recovery** *(new in 0.35.0)*: routed hooks share an 18-second input/selection/execution budget and allow up to 8 seconds for owned-process cleanup. Failure reports the selected runtime and diagnosis commands, retains unresolved findings, and directs an approved repair followed by retry of the original operation. Cleanup uncertainty is reported; persistent MCP sessions have no hook lifetime deadline. Literal recovery prompts and recognized installer previews are distinguished from actual shell writes without permitting command substitutions or protected output targets.
28
30
  - **Maintenance evidence survives the RED commit, and test evidence records what ran** *(new in 0.35.0)*: persisted `maintenance_analyze` evidence includes the request and explicit `changedFiles`, allowing the pre-edit advisory to cover named new files and analyses up to 20 ancestor commits back when every intervening change is covered. A passing `test_run` records the tree captured before execution, so edits made during a run remain unverified changes. The static test counter handles literals and same-file aliases, and recognizes suite skips only in code. The shared shell gate accepts read-only loops, prose literals, and commit messages mentioning `.ax`, and classifies file redirects using `>&` and `>|` as protected writes where applicable.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 68b21a0e-mutvc7i3
1
+ ccbc4eef-muu3n3bt
@@ -47,7 +47,7 @@ exports.decisionDetail = decisionDetail;
47
47
  exports.renderRefusals = renderRefusals;
48
48
  exports.renderNonTtyHint = renderNonTtyHint;
49
49
  exports.runInteractive = runInteractive;
50
- // @implements A-SPEC-246, A-SPEC-626
50
+ // @implements A-SPEC-246, A-SPEC-626, A-SPEC-532.5
51
51
  // @implements A-SPEC-549.4 — renderPending and renderNonTtyHint in this file are the English CLI
52
52
  // surface the Hangul-absence guard reads.
53
53
  const execution_context_1 = require("../project/execution-context");
@@ -175,6 +175,11 @@ function grantRequest(root, id, opts) {
175
175
  return { ok: false, reason: `TTL must be an integer number of minutes in 1..${MAX_TTL_MINUTES} — received: ${(0, screen_safe_1.rowField)(String(ttl), 40)}` };
176
176
  }
177
177
  const { entry } = findPending(root, id);
178
+ // @implements A-SPEC-532.5 — owner decision 2026-10-05: a grant bound to the content the operator read does not
179
+ // expire by time; it ends when it is used, revoked, or the content changes (the subject no longer matches). Measured
180
+ // 2026-10-04: five seal grants expired unused after 30 minutes. An explicit --ttl still bounds it; a request without
181
+ // a subject keeps the default, because there the clock is all that stands between the decision and a changed act.
182
+ const untilUsed = opts.ttlMinutes === undefined && typeof entry?.subject === 'string' && entry.subject !== '';
178
183
  if (!entry)
179
184
  return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.npxBin)()} holmes-kit approve --list` };
180
185
  if (!recordIsSelfConsistent(entry))
@@ -184,7 +189,7 @@ function grantRequest(root, id, opts) {
184
189
  // different id, so the lookup misses; the SAME id can only carry the same subject. An unexercised
185
190
  // second guard is not defence in depth, it is a line nobody can prove still works (round-3
186
191
  // mutation test: neutering it left the suite green).
187
- const expires = new Date(Date.now() + ttl * 60_000).toISOString();
192
+ const expires = untilUsed ? approval_grants_1.GRANT_NO_EXPIRY : new Date(Date.now() + ttl * 60_000).toISOString();
188
193
  // @implements A-SPEC-649 — the grant names WHERE it was minted and WHAT the operator read, so a
189
194
  // copy in another clone and a seal of changed content are refused by name (measured 2026-09-14:
190
195
  // both were accepted). A legacy workspace has no id to name; a request filed without a subject
@@ -213,6 +218,8 @@ function grantRequest(root, id, opts) {
213
218
  // "the grant is for what the human saw" (round-3) in the scope layer.
214
219
  scope: [{ kind: entry.kind, pattern: entry.target, exact: true }],
215
220
  expires,
221
+ // Stated, never implied by a missing field: a file that merely lacks an expiry is not a grant (isNarrow).
222
+ ...(untilUsed ? { lifetime: 'until-used' } : {}),
216
223
  nonce: id,
217
224
  };
218
225
  // @implements A-SPEC-262.1 — AUDIT AND AUTHORITY STAND OR FALL TOGETHER.
@@ -67,7 +67,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
67
67
  exports.semanticCoverageCheck = semanticCoverageCheck;
68
68
  exports.semanticTierVerdict = semanticTierVerdict;
69
69
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
70
- // @implements A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751
70
+ // @implements A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2
71
71
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712
72
72
  const doctor_guidance_1 = require("./doctor-guidance");
73
73
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -717,7 +717,26 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
717
717
  mcp: (h, e) => ['claude', 'codex', 'antigravity'].includes(h) && e?.command === process.execPath
718
718
  && Array.isArray(e.args) && e.args.length === 1 && e.args[0] === script(h, 'mcp') };
719
719
  }
720
- add('runtime binding', report.conflicts.length ? 'FAIL' : 'WARN', `${s.mode}: workspace=${s.workspaceRoot}; package=${s.packageRoot}; build=${s.buildId}; specs=${s.specsRoot}; live activation unverified`
720
+ // @implements A-SPEC-751.2 — the routed package and the package doctor checks can be two packages (measured: a
721
+ // local 0.35.1 install beside a registry routing to the global 0.34.0); the line says so when they are.
722
+ const real = (p) => { try {
723
+ return fs.realpathSync.native(p);
724
+ }
725
+ catch {
726
+ return null;
727
+ } };
728
+ const routedReal = real(s.packageRoot);
729
+ const ownReal = real(packageRoot);
730
+ let own = '';
731
+ if (routedReal === null || ownReal === null || routedReal !== ownReal) {
732
+ let ownBuild = 'unknown';
733
+ try {
734
+ ownBuild = fs.readFileSync(path.join(packageRoot, 'dist/.build-id'), 'utf8').trim() || 'unknown';
735
+ }
736
+ catch { /* no build id */ }
737
+ own = `; doctor runs from ${packageRoot} (build ${ownBuild}); sessions routed by this registry load the package named first`;
738
+ }
739
+ 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`
721
740
  + (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.');
722
741
  }
723
742
  catch (e) {
@@ -46,6 +46,8 @@ export interface InitOptions {
46
46
  }) => CodexVerdict;
47
47
  autonomy?: boolean;
48
48
  autonomyInteractive?: boolean;
49
+ /** @implements A-SPEC-752.8 — test override for the operator runtime registry whose receipt names owned wiring. */
50
+ runtimeRegistryPath?: string;
49
51
  }
50
52
  export interface FileChange {
51
53
  path: string;
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
37
37
  exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
- // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738
39
+ // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-340
42
42
  // @implements A-SPEC-100.2
@@ -61,6 +61,7 @@ const governed_precondition_1 = require("./governed-precondition");
61
61
  const risk_gate_1 = require("../guardrail/risk-gate");
62
62
  const bounded_io_1 = require("../project/bounded-io");
63
63
  const claude_switches_1 = require("./claude-switches");
64
+ const runtime_binding_1 = require("./runtime-binding");
64
65
  /**
65
66
  * `holmes-kit init` — wire holmes-kit into a TARGET project (the I/O half; all merge logic is pure
66
67
  * and lives in settings-merge.ts / gitignore-merge.ts).
@@ -1154,6 +1155,41 @@ function runInitUnguarded(opts) {
1154
1155
  if (guidance && !changes.some(c => c.path === guidanceFile)) {
1155
1156
  changes.push({ path: guidanceFile, before: guidance.before, after: guidance.after });
1156
1157
  }
1158
+ // @implements A-SPEC-752.8 — a wiring file the operator runtime registry's receipt lists is left byte for byte: its
1159
+ // content is a reviewed plan's, and init rewrote it thirteen seconds after a global install (measured 2026-10-04:
1160
+ // the user-level Codex files went back to direct release entries and every workspace's status reported a conflict).
1161
+ // `--force` does not override; a claim about a file that is not written is withdrawn, as for a failed write below.
1162
+ {
1163
+ const leftOwned = [];
1164
+ for (let i = changes.length - 1; i >= 0; i--) {
1165
+ const own = (0, runtime_binding_1.registryWiringOwnership)(changes[i].path, opts.runtimeRegistryPath);
1166
+ if (own.owned) {
1167
+ leftOwned.unshift({ path: changes[i].path, matches: own.matches });
1168
+ changes.splice(i, 1);
1169
+ }
1170
+ }
1171
+ for (let i = removals.length - 1; i >= 0; i--) {
1172
+ const own = (0, runtime_binding_1.registryWiringOwnership)(removals[i], opts.runtimeRegistryPath);
1173
+ if (own.owned) {
1174
+ leftOwned.unshift({ path: removals[i], matches: own.matches });
1175
+ removals.splice(i, 1);
1176
+ }
1177
+ }
1178
+ if (leftOwned.length > 0) {
1179
+ const names = leftOwned.map((l) => l.path);
1180
+ const codexLeft = names.some((p) => /[\\/]\.codex[\\/]/.test(p) || p === (opts.codexConfigPath ?? '') || p === (opts.codexHooksPath ?? ''));
1181
+ const claims = (m) => (names.some((p) => m.includes(p)) && /wired|active|repaired|written/.test(m))
1182
+ || (codexLeft && /pre-tool gate runs from the user-level Codex hooks file|codex: the gate is enforced \(hooks wired\)|codex: tools and instructions wired/.test(m));
1183
+ for (let i = messages.length - 1; i >= 0; i--)
1184
+ if (claims(messages[i]))
1185
+ messages.splice(i, 1);
1186
+ for (const l of leftOwned) {
1187
+ messages.push(l.matches
1188
+ ? `${l.path}: left as it is — owned by the operator runtime registry. Preview a change to it with: holmes-kit runtime-binding setup --dry-run`
1189
+ : `${l.path}: left as it is — owned by the operator runtime registry, but the registry's receipt and the file disagree. Inspect with: holmes-kit runtime-binding status, then preview with: holmes-kit runtime-binding setup --dry-run`);
1190
+ }
1191
+ }
1192
+ }
1157
1193
  // @implements A-SPEC-251.1 (round 27) — no write, removal or link goes through a link the repository carries out of the
1158
1194
  // target: a cloned repo's `.agents -> ../../.codex` made the default init merge Antigravity's hooks into
1159
1195
  // `~/.codex/hooks.json` and turn the Codex gate off everywhere (measured). A user's own (untracked) link is followed
@@ -21,9 +21,25 @@ export declare function runtimeHookCommand(registryPath: string, harness: Runtim
21
21
  * A list of keys to keep missed ones that switch Holmes off, so the view names what it drops (A-SPEC-752.6).
22
22
  */
23
23
  export declare function wiringViewOf(file: string, content: string): string;
24
+ /**
25
+ * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
26
+ * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
27
+ * nothing outside this module read the receipt. No registry, no receipt, or a receipt that cannot be read owns nothing.
28
+ */
29
+ export declare function registryWiringOwnership(file: string, registryPath?: string): {
30
+ owned: boolean;
31
+ matches: boolean;
32
+ };
33
+ export declare function registryOwnedWiring(file: string, registryPath?: string): boolean;
24
34
  export declare function runtimeBindingStatus(registryPath: string, workspace: string): {
25
35
  selection: import("../runtime/binding").RuntimeSelection;
26
36
  conflicts: string[];
27
37
  activation: "unverified";
28
38
  };
29
39
  export declare function runRuntimeBinding(opts: RuntimeBindingOptions): unknown;
40
+ /**
41
+ * @implements A-SPEC-752.7 — which of `files` lie inside `root` and are tracked by git, relative to `root` and sorted.
42
+ * Measured 2026-10-04: setup rewrote committed wiring files with machine paths and the release check was the first to
43
+ * say so. No work tree, no git, a timeout or a failure all read as "none": this report never fails for it.
44
+ */
45
+ export declare function trackedWorkspacePaths(root: string, files: readonly string[], env?: NodeJS.ProcessEnv): string[];
@@ -36,13 +36,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.defaultRuntimeRegistry = void 0;
37
37
  exports.runtimeHookCommand = runtimeHookCommand;
38
38
  exports.wiringViewOf = wiringViewOf;
39
+ exports.registryWiringOwnership = registryWiringOwnership;
40
+ exports.registryOwnedWiring = registryOwnedWiring;
39
41
  exports.runtimeBindingStatus = runtimeBindingStatus;
40
42
  exports.runRuntimeBinding = runRuntimeBinding;
41
- // @implements A-SPEC-751, A-SPEC-752
43
+ exports.trackedWorkspacePaths = trackedWorkspacePaths;
44
+ // @implements A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8
42
45
  const fs = __importStar(require("node:fs"));
43
46
  const os = __importStar(require("node:os"));
44
47
  const path = __importStar(require("node:path"));
45
48
  const node_crypto_1 = require("node:crypto");
49
+ const bounded_io_1 = require("../project/bounded-io");
46
50
  const smol_toml_1 = require("smol-toml");
47
51
  const binding_1 = require("../runtime/binding");
48
52
  const runtime_binding_approval_1 = require("./runtime-binding-approval");
@@ -125,6 +129,38 @@ function wiringViewOf(file, content) {
125
129
  const { model: _model, ...rest } = doc;
126
130
  return JSON.stringify(rest);
127
131
  }
132
+ /**
133
+ * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
134
+ * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
135
+ * nothing outside this module read the receipt. No registry, no receipt, or a receipt that cannot be read owns nothing.
136
+ */
137
+ function registryWiringOwnership(file, registryPath = (0, exports.defaultRuntimeRegistry)()) {
138
+ const none = { owned: false, matches: false };
139
+ try {
140
+ const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
141
+ if (manifest === null)
142
+ return none;
143
+ const rows = JSON.parse(manifest).files;
144
+ if (!Array.isArray(rows))
145
+ return none;
146
+ const wanted = canonicalFuture(file);
147
+ for (const row of rows) {
148
+ if (!object(row) || typeof row.path !== 'string' || typeof row.digest !== 'string')
149
+ return none;
150
+ if (row.path !== wanted && row.path !== file)
151
+ continue;
152
+ const current = readOptional(row.path);
153
+ return { owned: true, matches: current !== null && (digest(wiringViewOf(row.path, current)) === row.digest || digest(current) === row.digest) };
154
+ }
155
+ return none;
156
+ }
157
+ catch {
158
+ return none;
159
+ }
160
+ }
161
+ function registryOwnedWiring(file, registryPath) {
162
+ return registryWiringOwnership(file, registryPath).owned;
163
+ }
128
164
  function runtimeBindingStatus(registryPath, workspace) {
129
165
  const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(registryPath), { cwd: workspace });
130
166
  const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
@@ -566,5 +602,29 @@ function runRuntimeBinding(opts) {
566
602
  }
567
603
  });
568
604
  }
569
- return { dryRun: opts.dryRun, changes, conflicts, selection, planDigest, activation: 'unverified' };
605
+ // @implements A-SPEC-752.7 — outside the plan digest: what git tracks is not part of the reviewed wiring plan.
606
+ const trackedChanges = trackedWorkspacePaths(root, changes.map((c) => c.path));
607
+ return { dryRun: opts.dryRun, changes, conflicts, selection, planDigest, activation: 'unverified', trackedChanges,
608
+ ...(trackedChanges.length ? { trackedAdvice: `${trackedChanges.length} changed file(s) are tracked by git and now hold this machine's paths; do not commit them — keep them local with: git update-index --skip-worktree ${trackedChanges.join(' ')} (a release check otherwise sees a dirty tree)` } : {}) };
609
+ }
610
+ /**
611
+ * @implements A-SPEC-752.7 — which of `files` lie inside `root` and are tracked by git, relative to `root` and sorted.
612
+ * Measured 2026-10-04: setup rewrote committed wiring files with machine paths and the release check was the first to
613
+ * say so. No work tree, no git, a timeout or a failure all read as "none": this report never fails for it.
614
+ */
615
+ function trackedWorkspacePaths(root, files, env = process.env) {
616
+ const rel = files.filter((f) => (0, binding_1.inside)(root, f) && f !== root).map((f) => path.relative(root, f));
617
+ if (rel.length === 0)
618
+ return [];
619
+ try {
620
+ // The shared bounded child (A-SPEC-734): a timeout, a large buffer, and the blocked-root memory.
621
+ const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'ls-files', '-z', '--', ...rel], 'worktree', { env });
622
+ if (r.error || r.status !== 0 || typeof r.stdout !== 'string')
623
+ return [];
624
+ const wanted = new Set(rel.map((p) => p.split(path.sep).join('/')));
625
+ return r.stdout.split('\0').filter((p) => wanted.has(p)).sort();
626
+ }
627
+ catch {
628
+ return [];
629
+ }
570
630
  }
@@ -43,7 +43,14 @@ export type BoundGrant = Approval & {
43
43
  workspace?: string;
44
44
  subject?: string;
45
45
  requestedBy?: string;
46
+ lifetime?: 'until-used';
46
47
  };
48
+ /**
49
+ * @implements A-SPEC-532.5 — the `expires` a subject-bound grant carries: it keeps the field every grant must have
50
+ * (a grant is narrow: scope, expires, nonce) and the comparison every consumer already makes, while the grant's
51
+ * `lifetime: 'until-used'` says in words that no time limit was meant.
52
+ */
53
+ export declare const GRANT_NO_EXPIRY = "9999-12-31T23:59:59.999Z";
47
54
  export type BindingRefusal = 'foreign-workspace' | 'stale-subject';
48
55
  /** @implements A-SPEC-649 — the grants that WOULD cover this action but are refused by their binding, by name. */
49
56
  export declare function refusedGrantReasons(root: string, action: {
@@ -33,13 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.GRANTS_RELDIR = void 0;
36
+ exports.GRANT_NO_EXPIRY = exports.GRANTS_RELDIR = void 0;
37
37
  exports.readGrants = readGrants;
38
38
  exports.refusedGrantReasons = refusedGrantReasons;
39
39
  exports.pickCoveringGrant = pickCoveringGrant;
40
40
  exports.resolveApproval = resolveApproval;
41
41
  exports.consumeGrantFile = consumeGrantFile;
42
- // @implements A-SPEC-245
42
+ // @implements A-SPEC-245, A-SPEC-532.5
43
43
  const fs = __importStar(require("node:fs"));
44
44
  const path = __importStar(require("node:path"));
45
45
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -105,6 +105,12 @@ function readGrants(root) {
105
105
  }
106
106
  return { grants, ignored };
107
107
  }
108
+ /**
109
+ * @implements A-SPEC-532.5 — the `expires` a subject-bound grant carries: it keeps the field every grant must have
110
+ * (a grant is narrow: scope, expires, nonce) and the comparison every consumer already makes, while the grant's
111
+ * `lifetime: 'until-used'` says in words that no time limit was meant.
112
+ */
113
+ exports.GRANT_NO_EXPIRY = '9999-12-31T23:59:59.999Z';
108
114
  /** The current workspace id, or undefined for a legacy workspace / an unreadable identity. */
109
115
  function currentWorkspaceId(root) {
110
116
  try {
@@ -26,6 +26,15 @@ export declare function descendantAspecs(spec: Spec, all: Spec[]): Spec[];
26
26
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
27
27
  */
28
28
  export declare function specApprovalAutonomy(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): ApprovalAutonomy;
29
+ export declare function declaredGateDirection(spec: Spec): 'tightens' | 'wording' | null;
30
+ /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
31
+ export declare function autonomyRuleMeaning(rule: string): string;
32
+ /**
33
+ * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
34
+ * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
35
+ * could tell which rule had fired.
36
+ */
37
+ export declare function specApprovalAutonomyReason(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): string | null;
29
38
  /**
30
39
  * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
31
40
  * presented in-session while autonomous mode is enabled. This is intentionally narrower than
@@ -37,6 +37,9 @@ exports.SESSION_AUTONOMY_MARKER = exports.AUTONOMY_ENV = void 0;
37
37
  exports.isHighRiskPath = isHighRiskPath;
38
38
  exports.descendantAspecs = descendantAspecs;
39
39
  exports.specApprovalAutonomy = specApprovalAutonomy;
40
+ exports.declaredGateDirection = declaredGateDirection;
41
+ exports.autonomyRuleMeaning = autonomyRuleMeaning;
42
+ exports.specApprovalAutonomyReason = specApprovalAutonomyReason;
40
43
  exports.requiresAutonomousApprovalPrompt = requiresAutonomousApprovalPrompt;
41
44
  exports.sessionAutonomyActive = sessionAutonomyActive;
42
45
  exports.projectDefaultAutonomy = projectDefaultAutonomy;
@@ -45,7 +48,7 @@ exports.autonomyBanner = autonomyBanner;
45
48
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
46
49
  exports.versionBumpKind = versionBumpKind;
47
50
  exports.releaseAutonomy = releaseAutonomy;
48
- // @implements A-SPEC-532.1, A-SPEC-718
51
+ // @implements A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4
49
52
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
50
53
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
51
54
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -155,40 +158,89 @@ function descendantAspecs(spec, all) {
155
158
  * or no A-SPEC at all (unknown scope) → human. The two-argument call keeps the old answer.
156
159
  */
157
160
  function specApprovalAutonomy(spec, resolveParent, descendants) {
161
+ // @implements A-SPEC-532.3 — one walk: the verdict is "no rule fired", so it cannot disagree with the rule's name.
162
+ return specApprovalAutonomyReason(spec, resolveParent, descendants) === null ? 'auto' : 'hitl';
163
+ }
164
+ /**
165
+ * @implements A-SPEC-532.4 — the declared direction of a gate change: `gate-behavior: tightens — …` (nothing refused
166
+ * before passes after) or `gate-behavior: wording — …` (no input changes side). Owner decision 2026-10-05: these are
167
+ * sealed autonomously; any other gate change asks the owner. The word is the first of the reason, read
168
+ * case-sensitively, and must be followed by white space or a dash.
169
+ */
170
+ function gateDirection(spec) {
171
+ const raw = spec.frontmatter?.breaking_change;
172
+ if (typeof raw !== 'string')
173
+ return null;
174
+ const m = /^\s*gate-behavior\s*:\s*(tightens|wording)(?=[\s—–-])/.exec(raw);
175
+ return m ? m[1] : null;
176
+ }
177
+ function declaredGateDirection(spec) {
178
+ return spec.type === 'A-SPEC' ? gateDirection(spec) : null;
179
+ }
180
+ /** @implements A-SPEC-532.3 — one plain clause per rule name, for the refusal a person reads. */
181
+ function autonomyRuleMeaning(rule) {
182
+ if (rule.startsWith('files-to-touch-gate-file'))
183
+ return 'Files to Touch names a gate or governance file and the spec declares no tightening-only or wording-only gate change';
184
+ if (rule === 'breaking-change-gate-behavior')
185
+ return 'the gate change does not declare its direction as tightens or wording';
186
+ if (rule.startsWith('breaking-change-'))
187
+ return rule === 'breaking-change-undeclared' ? 'breaking_change is not declared' : 'the breaking_change grade is not one the grader knows';
188
+ switch (rule) {
189
+ case 'upstream-without-aspec': return 'no A-SPEC exists beneath it yet, so its scope is unknown';
190
+ case 'upstream-has-human-aspec': return 'an A-SPEC beneath it is the operator\'s to seal';
191
+ case 'architecture-document': return 'a C-SPEC or ADR is a decision';
192
+ case 'files-to-touch-empty': return 'Files to Touch names no path, so its scope is unbounded';
193
+ case 'files-to-touch-root-only': return 'Files to Touch names only root-level files';
194
+ case 'requirement-without-intake': return 'the requirement was never admitted through requirement_triage';
195
+ default: return 'the spec kind is not one the grader knows';
196
+ }
197
+ }
198
+ /**
199
+ * @implements A-SPEC-532.3 — the first rule that hands this seal to the owner, or null when none does. Measured
200
+ * 2026-10-04: two gate specs were refused with the generic out-of-band sentence and neither the session nor the owner
201
+ * could tell which rule had fired.
202
+ */
203
+ function specApprovalAutonomyReason(spec, resolveParent, descendants) {
158
204
  switch (spec.type) {
159
205
  case 'T-SPEC':
160
- return 'auto'; // tests are low risk
206
+ return null; // tests are low risk
161
207
  case 'REQ':
162
208
  case 'H-SPEC': {
163
209
  const below = (descendants ?? []).filter((s) => s.type === 'A-SPEC');
164
210
  if (below.length === 0)
165
- return 'hitl'; // unknown scope stays human
166
- return below.every((a) => specApprovalAutonomy(a, resolveParent) === 'auto') ? 'auto' : 'hitl';
211
+ return 'upstream-without-aspec'; // unknown scope stays human
212
+ return below.every((a) => specApprovalAutonomyReason(a, resolveParent) === null) ? null : 'upstream-has-human-aspec';
167
213
  }
168
214
  case 'C-SPEC':
169
215
  case 'ADR': // @implements A-SPEC-571.1 — a decision is the human's to seal
170
- return 'hitl'; // architecture / structural constraint — the owner's exception
216
+ return 'architecture-document'; // architecture / structural constraint — the owner's exception
171
217
  case 'A-SPEC': {
172
218
  const grade = breakingGrade(spec);
173
- if (grade === null || !AUTO_GRADES.has(grade))
174
- return 'hitl'; // undeclared or gate-behavior
219
+ if (grade === null)
220
+ return 'breaking-change-undeclared';
221
+ // @implements A-SPEC-532.4 — a gate change that declares tightening or wording passes the grade rule and the
222
+ // gate-file rule; an undirected one, and a gate file under any other grade, do not.
223
+ const directed = grade === 'gate-behavior' && gateDirection(spec) !== null;
224
+ if (!directed && !AUTO_GRADES.has(grade))
225
+ return `breaking-change-${grade}`; // gate-behavior, or unrecognised
175
226
  const paths = (0, scope_judgment_1.fttPathTokens)(spec.sections['Files to Touch'] ?? '');
176
227
  // @implements A-SPEC-556.1 — no path tokens (prose-only / empty FtT) is an UNCONSTRAINED scope:
177
228
  // the enforcer imposes nothing, so the spec can write ANYWHERE incl. the gate. Never self-approve.
178
229
  if (paths.length === 0)
179
- return 'hitl';
180
- if (paths.some(isHighRiskPath))
181
- return 'hitl'; // gate/governance/taint file
230
+ return 'files-to-touch-empty';
231
+ const gateFile = paths.find(isHighRiskPath);
232
+ if (gateFile !== undefined && !directed)
233
+ return `files-to-touch-gate-file: ${gateFile}`; // gate/governance/taint file
182
234
  // @implements A-SPEC-654 — a ROOT-level file is project-wide configuration (the test runner, the
183
235
  // manifest, the ignore policy): admitting it at the gate was the point of that slice, but grading
184
236
  // it auto would be a widening nobody asked for. A spec earns self-approval only when it also names
185
237
  // a directory-scoped surface — the same doubt `paths.length === 0` already encodes.
186
238
  if (!paths.some((p) => p.includes('/')))
187
- return 'hitl';
188
- return 'auto';
239
+ return 'files-to-touch-root-only';
240
+ return null;
189
241
  }
190
242
  default:
191
- return 'hitl'; // unknown kind: fail-safe to human
243
+ return 'unknown-kind'; // unknown kind: fail-safe to human
192
244
  }
193
245
  }
194
246
  /**
@@ -44,7 +44,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
44
44
  exports.classifySecret = classifySecret;
45
45
  exports.classifyBlastRadius = classifyBlastRadius;
46
46
  exports.assessRisk = assessRisk;
47
- // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747, A-SPEC-753
47
+ // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
50
50
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -391,6 +391,22 @@ const REMOVAL_VERB_RE = /\b(rm|rmdir|unlink|git\s+rm|git\s+mv|mv|cp)\b/i;
391
391
  // 240 000 of them). A later `>` inside an already-scanned token can only see a suffix of it.
392
392
  const CLOBBER_AX_RE = (0, linear_match_1.redirectTokenTester)(new RegExp(String.raw `\.ax/(${PROTECTED_AX_ALT})\b`, 'i'));
393
393
  const CMD_PROTECTED_AX_RE = new RegExp(String.raw `(^|[\s'"=(/])\.ax/(${PROTECTED_AX_ALT})(/|\b)`, 'i');
394
+ // No boundary after the child either: under a separator the text does not show, `mvq.ax/specsq/tmp/z` is `mv .ax/specs /tmp/z`.
395
+ const PROTECTED_AX_ANYWHERE_RE = new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})`, 'i');
396
+ /**
397
+ * @implements A-SPEC-226.1 — does the text name a protected .ax path. The pattern above asks for white space, a quote,
398
+ * `=`, `(` or `/` before `.ax/`, so a path glued to an expansion was not one: `rm${IFS}-rf${IFS}.ax/specs/…` and
399
+ * `rm$IFS-rf$IFS.ax/specs` were allowed while `rm -rf .ax/specs/…` was refused (shipped through 0.35.1; measured
400
+ * 2026-10-05). Only tightens: everything the old pattern matched still matches. One linear pattern test.
401
+ */
402
+ function namesProtectedAx(text) {
403
+ // @implements A-SPEC-226.2 — the spelling counts wherever it appears. A-SPEC-226.1 kept "a spelling that continues a
404
+ // longer file name" out, and its re-review (2026-10-05) passed removals through exactly that door: `rm -f $-.ax/specs/…`
405
+ // (dash), `rm -f $X:t.ax/specs/…` (zsh), `P=q.ax/specs; mv ${P#q} /tmp/gone`, `echo mvq.ax/specsq/tmp/z | tr q ' ' | sh`,
406
+ // `sed -n w.ax/ledger/p.jsonl /dev/null`. The text cannot tell a longer file name from a prefix the shell removes, so
407
+ // it no longer tries; 226.1's three rules are subsumed. Cost, stated: `backup.ax/specs` is judged as the store.
408
+ return CMD_PROTECTED_AX_RE.test(text) || PROTECTED_AX_ANYWHERE_RE.test(text);
409
+ }
394
410
  /**
395
411
  * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so
396
412
  * `./.ax//ledger/x` matches the same rules as `.ax/ledger/x` (adversarial probe: those forms slipped
@@ -641,6 +657,11 @@ function normalizeCommandPaths(cmd, followCd = true) {
641
657
  }
642
658
  // File-mutating shell verbs beyond redirect/removal: these WRITE a target path, so a protected path
643
659
  // as their argument is the same governance breach as `>` or `rm` (probe: tee/cp/install slipped).
660
+ // A-SPEC-747.1 rules 1–5 (count a verb only as a shell word) are NOT implemented: the independent review of the first
661
+ // build (2026-10-04) showed the exemption for a verb inside a longer file name passes real writes whenever the shell
662
+ // splits a word the text does not (`cp${IFS}a${IFS}.ax/specs/x.md`, a custom IFS, text re-parsed by `sh -c`). The
663
+ // `\b…\b` test stays; `docs/install-guide.md` beside an .ax path is still refused, on purpose, until a rule exists
664
+ // that the shell cannot split around.
644
665
  const WRITE_VERB_AX_RE = (0, linear_match_1.headThenTail)(/\b(?:tee|cp|install|dd|ln|mv|rsync)\b/i, SEG, new RegExp(String.raw `\.ax/(?:${PROTECTED_AX_ALT})\b`, 'i'));
645
666
  // An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
646
667
  // `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
@@ -671,6 +692,8 @@ const READ_ONLY_SHELL = new Set([
671
692
  const READ_ONLY_GIT = new Set([
672
693
  'show', 'log', 'status', 'diff', 'ls-tree', 'ls-files', 'blame', 'cat-file', 'rev-parse',
673
694
  'merge-base', 'describe',
695
+ // @implements A-SPEC-747.1 — `git check-ignore -v .ax/state/…` was refused (measured); it only reads.
696
+ 'check-ignore',
674
697
  ]);
675
698
  /** Is `t` a spelling of the long option `--<full>` that getopt_long accepts (an unambiguous prefix of `min`+ letters)? */
676
699
  function longOption(t, full, min) {
@@ -1419,6 +1442,8 @@ function awkIsRead(clause, args) {
1419
1442
  const FOR_HEAD_RE = /^for\s+[A-Za-z_][A-Za-z0-9_]*\s+in\b/;
1420
1443
  const SUBSTITUTION_RE = /\$\(|`|<\(|>\(/;
1421
1444
  const OUTPUT_REDIRECT_RE = />(?!\s*(?:\/dev\/null\b|&\d))/;
1445
+ /** An output redirect whose target word holds an expansion (`> ${P#q}`, `>> "$f"`, `` > `x` ``). Linear: one word after `>`. */
1446
+ const COMPUTED_REDIRECT_RE = />[>|&]?[ \t]*[^\s;|&<>$`]*[$`]/;
1422
1447
  function clausesAreReads(clauses, isRead) {
1423
1448
  let inLoop = false;
1424
1449
  for (const raw of clauses) {
@@ -1515,7 +1540,7 @@ function stripCommitMessages(cmd) {
1515
1540
  * @implements A-SPEC-226
1516
1541
  */
1517
1542
  function shellWritesProtectedAx(ncmd) {
1518
- if (!CMD_PROTECTED_AX_RE.test(ncmd))
1543
+ if (!namesProtectedAx(ncmd))
1519
1544
  return false;
1520
1545
  // @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
1521
1546
  // because it is a property of the TARGET rather than of the command shape.
@@ -1532,6 +1557,10 @@ function shellWritesProtectedAx(ncmd) {
1532
1557
  sawCd = true;
1533
1558
  else if (sawCd && OUTPUT_REDIRECT_RE.test(c))
1534
1559
  return false;
1560
+ // @implements A-SPEC-226.2 — an output redirect whose target is computed is not a read here: the re-review passed
1561
+ // `P=q.ax/ledger/p.jsonl; echo x > ${P#q}` (the protected spelling in the text, the write through an expansion).
1562
+ if (COMPUTED_REDIRECT_RE.test(c))
1563
+ return false;
1535
1564
  return clauseIsRead(c, isRead);
1536
1565
  });
1537
1566
  }
@@ -1594,7 +1623,7 @@ function classifyReversibilityAsWritten(action) {
1594
1623
  const ncmd = [...new Set([flat, asWritten, bySegment, ...outputTargets])].join('\n');
1595
1624
  // @implements A-SPEC-737 — one reason served all four channels, so an interpreter READ was refused as
1596
1625
  // a "removal command" and the author could not tell what to change. Each channel names itself.
1597
- const axChannel = REMOVAL_VERB_RE.test(ncmd) && CMD_PROTECTED_AX_RE.test(ncmd)
1626
+ const axChannel = REMOVAL_VERB_RE.test(ncmd) && namesProtectedAx(ncmd)
1598
1627
  ? 'removal, move or copy command targets a protected .ax governance path'
1599
1628
  : CLOBBER_AX_RE.test(ncmd) ? 'output redirection writes into a protected .ax governance path'
1600
1629
  : WRITE_VERB_AX_RE.test(ncmd) ? 'file-writing command (tee/cp/install/dd/ln/mv/rsync) targets a protected .ax governance path'
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Whether `text` names one of `verbs` as a shell word, rather than as letters inside another word.
3
+ *
4
+ * Measured 2026-10-04: `\bverb\b` matched `install` in `docs/install-guide.md` and `ln` in `grep -ln`, so read-only
5
+ * commands were refused as file writes. A verb occurrence still counts in every spelling a shell runs it under
6
+ * (`cp`, `/usr/bin/install`, `'cp'`, `cp.exe`, `--to-command=tee`, `rsync-ssl`); only two shapes do not:
7
+ * a. the word is a single-dash option cluster of letters and digits (`-ln`, `-rm1`);
8
+ * b. inside the word the verb is followed by `/`, or the word ends in a file extension other than `.exe`.
9
+ * Callers keep their own matching for what the verb targets — this answers only "is there such a verb at all", so a
10
+ * caller's verdict is removed only when the whole text holds no counting occurrence. One pass: a word's shape is read
11
+ * once however many occurrences it holds.
12
+ */
13
+ export declare function namesWriteVerb(text: string, verbs: RegExp): boolean;
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.namesWriteVerb = namesWriteVerb;
4
+ // @implements A-SPEC-747.1
5
+ /** A shell word ends at white space or at one of `;|&()<>`. */
6
+ function isBreak(code) {
7
+ return code === 32 || code === 9 || code === 10 || code === 13 || code === 11 || code === 12
8
+ || code === 59 || code === 124 || code === 38 || code === 40 || code === 41 || code === 60 || code === 62;
9
+ }
10
+ /**
11
+ * Whether `text` names one of `verbs` as a shell word, rather than as letters inside another word.
12
+ *
13
+ * Measured 2026-10-04: `\bverb\b` matched `install` in `docs/install-guide.md` and `ln` in `grep -ln`, so read-only
14
+ * commands were refused as file writes. A verb occurrence still counts in every spelling a shell runs it under
15
+ * (`cp`, `/usr/bin/install`, `'cp'`, `cp.exe`, `--to-command=tee`, `rsync-ssl`); only two shapes do not:
16
+ * a. the word is a single-dash option cluster of letters and digits (`-ln`, `-rm1`);
17
+ * b. inside the word the verb is followed by `/`, or the word ends in a file extension other than `.exe`.
18
+ * Callers keep their own matching for what the verb targets — this answers only "is there such a verb at all", so a
19
+ * caller's verdict is removed only when the whole text holds no counting occurrence. One pass: a word's shape is read
20
+ * once however many occurrences it holds.
21
+ */
22
+ function namesWriteVerb(text, verbs) {
23
+ const re = new RegExp(verbs.source, verbs.flags.includes('g') ? verbs.flags : `${verbs.flags}g`);
24
+ let wordStart = -1;
25
+ let wordEnd = -1;
26
+ let cluster = false;
27
+ let extension = false;
28
+ for (let m = re.exec(text); m !== null; m = re.exec(text)) {
29
+ if (m[0].length === 0) {
30
+ re.lastIndex++;
31
+ continue;
32
+ }
33
+ const at = m.index;
34
+ if (at < wordStart || at >= wordEnd) {
35
+ let s = at;
36
+ while (s > 0 && !isBreak(text.charCodeAt(s - 1)))
37
+ s--;
38
+ let e = at;
39
+ while (e < text.length && !isBreak(text.charCodeAt(e)))
40
+ e++;
41
+ wordStart = s;
42
+ wordEnd = e;
43
+ const raw = text.slice(s, e);
44
+ cluster = /^-[A-Za-z0-9]+$/.test(raw);
45
+ const ext = /\.([A-Za-z0-9]{1,8})$/.exec(raw.replace(/["'\\]/g, ''));
46
+ extension = ext !== null && ext[1].toLowerCase() !== 'exe';
47
+ }
48
+ if (cluster || extension)
49
+ continue;
50
+ if (text.charCodeAt(at + m[0].length) === 47)
51
+ continue; // the verb is a directory name inside a path
52
+ return true;
53
+ }
54
+ return false;
55
+ }
@@ -93,6 +93,8 @@ export interface HookInput {
93
93
  malformed?: boolean;
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
+ /** @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';
96
98
  }
97
99
  /**
98
100
  * @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
@@ -48,7 +48,7 @@ exports.gateErrorDecision = gateErrorDecision;
48
48
  exports.wiredSpecsDir = wiredSpecsDir;
49
49
  exports.evaluateHook = evaluateHook;
50
50
  exports.readSpecsSync = readSpecsSync;
51
- // @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753
51
+ // @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7
52
52
  const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
53
53
  // @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
54
54
  // evaluateHook in this file to prove it.
@@ -952,6 +952,9 @@ const PATCH_STRINGS_MAX = 256;
952
952
  /** A file an update hunk is applied to; a larger one is not judged by its result. */
953
953
  const PATCH_UPDATE_BYTES_MAX = 8 * 1024 * 1024;
954
954
  const PATCH_UNREADABLE_REASON = '[Holmes-Kit] cannot read the edit target path, so it cannot be judged (file_path missing or not a string)';
955
+ // @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).
956
+ 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 — '
957
+ + '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)';
955
958
  /**
956
959
  * @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
957
960
  * The installer refusal (A-SPEC-753.1) carries the raw command after ` Operator: ` for the operator to run; the ledger
@@ -1026,6 +1029,9 @@ function normalizeHookInput(raw) {
1026
1029
  // A patch that cannot be read one way (no target, an empty path, too many, an indented header) is unreadable.
1027
1030
  const toolName = (str(r.tool_name) ?? '').toLowerCase();
1028
1031
  let patchUnreadable = false;
1032
+ // @implements A-SPEC-163.7 — why: a shell command refused for a patch marker is told so (it has no file path to miss).
1033
+ let shellMarked = false;
1034
+ let otherUnreadable = false;
1029
1035
  if (!write_target_1.READ_ONLY_TOOLS.includes(toolName)) {
1030
1036
  const strings = [];
1031
1037
  const collect = (v, depth) => {
@@ -1033,8 +1039,10 @@ function normalizeHookInput(raw) {
1033
1039
  if (!v.includes('*** '))
1034
1040
  return;
1035
1041
  // @implements A-SPEC-163.3 (rule 6) — more than the gate reads is unreadable, never unread.
1036
- if (strings.length >= PATCH_STRINGS_MAX)
1042
+ if (strings.length >= PATCH_STRINGS_MAX) {
1037
1043
  patchUnreadable = true;
1044
+ otherUnreadable = true;
1045
+ }
1038
1046
  else
1039
1047
  strings.push(v);
1040
1048
  return;
@@ -1055,21 +1063,25 @@ function normalizeHookInput(raw) {
1055
1063
  const patches = strings.filter((text) => !(isShell && text === cmd) && (isPatchTool ? (0, write_target_1.hasPatchEnvelope)(text) : (0, write_target_1.isWholePatch)(text)));
1056
1064
  if (isShell && cmd !== undefined) {
1057
1065
  const shellPatch = shellPatchOf(cmd);
1058
- if (shellPatch === 'unreadable')
1066
+ if (shellPatch === 'unreadable') {
1059
1067
  patchUnreadable = true;
1068
+ shellMarked = true;
1069
+ }
1060
1070
  else if (shellPatch !== null)
1061
1071
  patches.push(shellPatch.text);
1062
1072
  }
1063
1073
  if (patches.length > 0) {
1064
1074
  const targets = patches.flatMap((text) => (0, write_target_1.patchTargetsOf)(text));
1065
- if (targets.length === 0 || targets.length > write_target_1.PATCH_TARGETS_MAX || patches.some((text) => !(0, write_target_1.canonicalPatch)(text)))
1075
+ if (targets.length === 0 || targets.length > write_target_1.PATCH_TARGETS_MAX || patches.some((text) => !(0, write_target_1.canonicalPatch)(text))) {
1066
1076
  patchUnreadable = true;
1077
+ otherUnreadable = true;
1078
+ }
1067
1079
  else
1068
1080
  out.patch_targets = targets;
1069
1081
  }
1070
1082
  }
1071
1083
  return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(malformed ? { malformed: true } : {}),
1072
- ...(patchUnreadable ? { patchUnreadable: true } : {}) };
1084
+ ...(patchUnreadable ? { patchUnreadable: true } : {}), ...(shellMarked && !otherUnreadable ? { patchUnreadableCause: 'shell-marker' } : {}) };
1073
1085
  }
1074
1086
  /**
1075
1087
  * Which way to fail when the gate itself throws.
@@ -1220,8 +1232,10 @@ function evaluateHook(input, specsDir, opts) {
1220
1232
  // disk); a move's source is judged as a delete; a relative target is `<base>/<path>` as written, not folded first;
1221
1233
  // a patch that cannot be read or applied is denied. When no target is denied, a payload with a path field or a
1222
1234
  // shell command is then judged as before.
1223
- if (input.patchUnreadable)
1224
- return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1235
+ if (input.patchUnreadable) {
1236
+ return { permissionDecision: 'deny', permissionDecisionReason: input.patchUnreadableCause === 'shell-marker'
1237
+ ? SHELL_MARKED_REASON : PATCH_UNREADABLE_REASON };
1238
+ }
1225
1239
  const patchTargets = input.tool_input.patch_targets;
1226
1240
  if (patchTargets !== undefined && !input.malformed) {
1227
1241
  const isShell = (input.tool_name ?? '').toLowerCase() === 'bash';
@@ -89,6 +89,10 @@ function createSpecApprovalHandlers(context) {
89
89
  // id helps no one — the standard refusal handles it).
90
90
  let elicitExpiredMs;
91
91
  let risk;
92
+ // @implements A-SPEC-532.3 — which grading rule handed this seal to the operator (said in the refusal).
93
+ let autonomyNote = '';
94
+ // @implements A-SPEC-532.4 — the declared direction of a gate change sealed without the owner (said in the ledger).
95
+ let sealedDirection = '';
92
96
  let subject;
93
97
  // @implements A-SPEC-732 (round 2) — the digest a person or the autonomy grade decided on; the
94
98
  // seal must be built from that same content.
@@ -179,9 +183,17 @@ function createSpecApprovalHandlers(context) {
179
183
  })();
180
184
  if (noIntake)
181
185
  risk = 'hitl';
186
+ if (autonomyOn && risk === 'hitl') {
187
+ const rule = noIntake ? 'requirement-without-intake' : (0, autonomy_1.specApprovalAutonomyReason)(target.spec, resolver([target.spec]), below);
188
+ if (rule !== null)
189
+ autonomyNote = `\n[autonomy: this seal is the operator's — ${rule} (${(0, autonomy_1.autonomyRuleMeaning)(rule)})]`;
190
+ }
182
191
  if (autonomyOn && risk === 'auto') {
183
192
  approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
184
193
  decidedSubject = targetSubject;
194
+ const direction = (0, autonomy_1.declaredGateDirection)(target.spec);
195
+ if (direction !== null)
196
+ sealedDirection = ` [gate change sealed without the owner — declared ${direction}]`;
185
197
  }
186
198
  else if (autonomyOn && !(0, autonomy_1.requiresAutonomousApprovalPrompt)(target.spec, below)) {
187
199
  // @implements A-SPEC-551.1 — autonomous mode does not turn an ordinary HITL request
@@ -244,7 +256,7 @@ function createSpecApprovalHandlers(context) {
244
256
  catch {
245
257
  refusedGrants = '';
246
258
  }
247
- return { ok: false, reason: (elicitExpiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(elicitExpiredMs) : '') + refusedGrants + (context.approvalRouteNote?.() ?? '')
259
+ return { ok: false, reason: (elicitExpiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(elicitExpiredMs) : '') + refusedGrants + (context.approvalRouteNote?.() ?? '') + autonomyNote
248
260
  + 'spec_approve requires an out-of-band HOLMES_APPROVAL that COVERS this act — a request-payload approval is not a channel, and an expired or elsewhere-scoped token does not open this door (scoped approvals need kind "spec-approve"). (fail-closed)'
249
261
  + context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인', ...(subject ? { subject } : {}), ...(risk ? { risk } : {}) }) };
250
262
  }
@@ -392,7 +404,7 @@ function createSpecApprovalHandlers(context) {
392
404
  ts: new Date().toISOString(),
393
405
  actor: approveResolved.approval.actor,
394
406
  kind: 'spec-approved',
395
- summary: `approved ${a.id} sealing ${digest}`,
407
+ summary: `approved ${a.id} sealing ${digest}${sealedDirection}`,
396
408
  inputs: [a.id, digest],
397
409
  rationale: approveResolved.approval.rationale,
398
410
  authorization: (0, provenance_chain_1.authorizationRef)(approveResolved.approval.actor, approveResolved.approval.token),
@@ -14,7 +14,16 @@ export interface HarnessAttestation {
14
14
  harness?: string;
15
15
  reason?: string;
16
16
  }
17
+ /**
18
+ * @implements A-SPEC-751.3 — is `script` one of the operator runtime registry's own MCP dispatcher files, unchanged
19
+ * since its installation receipt. Measured 2026-10-04: A-SPEC-751 starts the server through
20
+ * `node <registry dir>/<harness>-mcp.js`; the walk below read that as a plain node script and stopped, so in-session
21
+ * approval was switched off on every workspace of a registered machine. Any read or parse failure is "no".
22
+ * Limit, stated: the receipt and the file are writable by the operator's own account — this shows the launcher is the
23
+ * installed dispatcher, not that the account is uncompromised (the trust the image check already rests on).
24
+ */
25
+ export declare function dispatcherVerifier(registryPath: string): (script: string) => boolean;
17
26
  /** Walk up from `pid` (the server's parent) through launchers to a harness executable. */
18
- export declare function attestHarness(pid: number, lookup: ProcLookup, maxDepth?: number): HarnessAttestation;
27
+ export declare function attestHarness(pid: number, lookup: ProcLookup, maxDepth?: number, isDispatcher?: (script: string) => boolean): HarnessAttestation;
19
28
  /** The live process table: `ps` on POSIX, CIM through PowerShell on Windows. Null when unreadable. */
20
29
  export declare function systemProcLookup(platform?: NodeJS.Platform): ProcLookup;
@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.dispatcherVerifier = dispatcherVerifier;
36
37
  exports.attestHarness = attestHarness;
37
38
  exports.systemProcLookup = systemProcLookup;
38
- // @implements A-SPEC-732
39
+ // @implements A-SPEC-732, A-SPEC-751.3
39
40
  // In-session approval (a form, or the host-gated continuation) trusts the client that answers it. An
40
41
  // agent can start its own copy of this server, name itself `claude-code` and answer for a person
41
42
  // (measured, H7 round 1). So before offering either route, the server asks who launched it: the
@@ -50,6 +51,7 @@ exports.systemProcLookup = systemProcLookup;
50
51
  const fs = __importStar(require("node:fs"));
51
52
  const path = __importStar(require("node:path"));
52
53
  const node_child_process_1 = require("node:child_process");
54
+ const node_crypto_1 = require("node:crypto");
53
55
  const HARNESS_EXES = new Set(['claude', 'codex', 'agy', 'antigravity']);
54
56
  const imageName = (image) => path.win32.basename(path.posix.basename(image)).toLowerCase().replace(/\.exe$/, '');
55
57
  /** `agy` and `antigravity` name the same harness. */
@@ -101,8 +103,66 @@ function isLauncher(args) {
101
103
  }
102
104
  return false;
103
105
  }
106
+ const NODE_PROGRAM_OPTIONS = new Set(['-e', '-p', '-r', '--eval', '--print', '--require', '--import', '--loader', '--experimental-loader']);
107
+ /** Quote-aware words of a process's argument string (the first is the executable). */
108
+ function argWords(args) {
109
+ const out = [];
110
+ const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
111
+ for (let m = re.exec(args); m !== null; m = re.exec(args))
112
+ out.push(m[1] ?? m[2] ?? m[3]);
113
+ return out;
114
+ }
115
+ /**
116
+ * @implements A-SPEC-751.3 — the script a `node` process runs, or null when an option names a program or a preload
117
+ * (`-e`, `-r`, `--require`, `--import`, `--loader` …: such a process runs something other than its script).
118
+ * Options that take no program are stepped over; `--` ends options.
119
+ */
120
+ function nodeScriptOf(args) {
121
+ const words = argWords(args).slice(1);
122
+ for (let i = 0; i < words.length; i++) {
123
+ const w = words[i];
124
+ if (w === '--')
125
+ return words[i + 1] ?? null;
126
+ if (!w.startsWith('-'))
127
+ return w;
128
+ if (NODE_PROGRAM_OPTIONS.has(w.split('=')[0]) || !w.startsWith('--'))
129
+ return null;
130
+ }
131
+ return null;
132
+ }
133
+ /**
134
+ * @implements A-SPEC-751.3 — is `script` one of the operator runtime registry's own MCP dispatcher files, unchanged
135
+ * since its installation receipt. Measured 2026-10-04: A-SPEC-751 starts the server through
136
+ * `node <registry dir>/<harness>-mcp.js`; the walk below read that as a plain node script and stopped, so in-session
137
+ * approval was switched off on every workspace of a registered machine. Any read or parse failure is "no".
138
+ * Limit, stated: the receipt and the file are writable by the operator's own account — this shows the launcher is the
139
+ * installed dispatcher, not that the account is uncompromised (the trust the image check already rests on).
140
+ */
141
+ function dispatcherVerifier(registryPath) {
142
+ return (script) => {
143
+ try {
144
+ if (!path.isAbsolute(script))
145
+ return false;
146
+ const dir = fs.realpathSync.native(path.dirname(registryPath));
147
+ const real = fs.realpathSync.native(script);
148
+ if (path.dirname(real) !== dir || !/^(?:claude|codex|antigravity)-mcp\.js$/.test(path.basename(real)))
149
+ return false;
150
+ const st = fs.lstatSync(real);
151
+ if (!st.isFile() || st.size > 1024 * 1024)
152
+ return false;
153
+ const rows = JSON.parse(fs.readFileSync(path.join(dir, 'installation.json'), 'utf8')).files;
154
+ if (!Array.isArray(rows))
155
+ return false;
156
+ const digest = (0, node_crypto_1.createHash)('sha256').update(fs.readFileSync(real, 'utf8')).digest('hex');
157
+ return rows.some((r) => !!r && typeof r === 'object' && r.path === real && r.digest === digest);
158
+ }
159
+ catch {
160
+ return false;
161
+ }
162
+ };
163
+ }
104
164
  /** Walk up from `pid` (the server's parent) through launchers to a harness executable. */
105
- function attestHarness(pid, lookup, maxDepth = 8) {
165
+ function attestHarness(pid, lookup, maxDepth = 8, isDispatcher) {
106
166
  const chain = [];
107
167
  const seen = new Set();
108
168
  let cur = pid;
@@ -114,8 +174,15 @@ function attestHarness(pid, lookup, maxDepth = 8) {
114
174
  if (row === null)
115
175
  return { attested: false, chain, reason: 'the process table could not be read' };
116
176
  const harness = harnessOf(row.args, row.exe);
117
- const shown = harness ?? (exeName(row.args) || '?');
177
+ // @implements A-SPEC-751.3 — the receipted runtime dispatcher is a launcher; the chain records the hop as such.
178
+ const viaDispatcher = harness === null && isDispatcher !== undefined && ['node', 'nodejs'].includes(exeName(row.args))
179
+ && (() => { const script = nodeScriptOf(row.args); return script !== null && isDispatcher(script); })();
180
+ const shown = viaDispatcher ? 'dispatcher' : harness ?? (exeName(row.args) || '?');
118
181
  chain.push(shown);
182
+ if (viaDispatcher) {
183
+ cur = row.ppid;
184
+ continue;
185
+ }
119
186
  if (harness !== null) {
120
187
  if (typeof row.image !== 'string' || row.image === '') {
121
188
  return { attested: false, chain, reason: `the executable image of ${shown} could not be read` };
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.operatorRecovery = operatorRecovery;
37
- // @implements A-SPEC-754
37
+ // @implements A-SPEC-754, A-SPEC-532.3
38
38
  const path = __importStar(require("node:path"));
39
39
  const unsafeDisplay = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/;
40
40
  function literal(value, platform) {
@@ -56,7 +56,10 @@ function operatorRecovery(root, target, operation, options) {
56
56
  return '';
57
57
  if (!command)
58
58
  return `\n[승인 대기 ${id}] The request was recorded. Use the installed approval UI; a path exceeds the safe command display limit. No truncated command is provided.`;
59
+ // @implements A-SPEC-532.3 — the resident surface is offered beside the one-off command (owner, 2026-10-04:
60
+ // "why am I still pasting commands"): one key per arriving request.
59
61
  return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${literal(id, platform)}`
62
+ + `\nOr keep the approval surface open and decide each arriving request with one key: ${command} --watch`
60
63
  + `\nAfter official approval, retry ${operation ? display(operation) : 'the original MCP operation'} for target ${display(target)} in the same workspace. Do not retry until approval is available.`;
61
64
  },
62
65
  };
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734
4
+ // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3
5
5
  const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
6
6
  const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
7
7
  const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
@@ -49,12 +49,15 @@ const elicit = async (req) => {
49
49
  }
50
50
  };
51
51
  // @implements A-SPEC-732 (round 2) — who launched this server, asked once, on first need.
52
- const { attestHarness, systemProcLookup } = require('./harness-attestation');
52
+ const { attestHarness, systemProcLookup, dispatcherVerifier } = require('./harness-attestation');
53
+ // @implements A-SPEC-751.3 — the operator runtime registry's dispatcher is a launcher (it sits between the harness and
54
+ // this server on a registered machine); the path is the registry's fixed default, never taken from the request.
55
+ const runtimeRegistryPath = require('node:path').join(require('node:os').homedir(), '.holmes', 'runtime', 'bindings.json');
53
56
  let attested;
54
57
  const harnessAttestation = () => {
55
58
  if (attested === undefined) {
56
59
  try {
57
- attested = attestHarness(process.ppid, systemProcLookup());
60
+ attested = attestHarness(process.ppid, systemProcLookup(), 8, dispatcherVerifier(runtimeRegistryPath));
58
61
  }
59
62
  catch {
60
63
  attested = { attested: false, chain: [], reason: 'the process table could not be read' };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.35.1",
4
+ "version": "0.35.2",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",