@holmes-lab/holmes-kit 0.35.0 → 0.35.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +61 -0
  2. package/README.md +5 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/codex-oracle.js +36 -2
  5. package/dist/holmes/cli/doctor.d.ts +14 -1
  6. package/dist/holmes/cli/doctor.js +335 -71
  7. package/dist/holmes/cli/index.d.ts +1 -1
  8. package/dist/holmes/cli/index.js +38 -5
  9. package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
  10. package/dist/holmes/cli/runtime-binding-approval.js +102 -0
  11. package/dist/holmes/cli/runtime-binding.d.ts +29 -0
  12. package/dist/holmes/cli/runtime-binding.js +570 -0
  13. package/dist/holmes/governance/approval-queue.d.ts +2 -0
  14. package/dist/holmes/governance/approval-queue.js +11 -4
  15. package/dist/holmes/guardrail/risk-classifier.js +45 -24
  16. package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
  17. package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
  18. package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
  19. package/dist/holmes/guardrail/shell-syntax.js +489 -0
  20. package/dist/holmes/guardrail/shell-words.d.ts +2 -18
  21. package/dist/holmes/guardrail/shell-words.js +15 -441
  22. package/dist/holmes/guardrail/write-target.d.ts +54 -0
  23. package/dist/holmes/guardrail/write-target.js +327 -1
  24. package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
  25. package/dist/holmes/hooks/pre-tool-use.js +377 -66
  26. package/dist/holmes/mcp/handlers.d.ts +9 -1
  27. package/dist/holmes/mcp/handlers.js +6 -4
  28. package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
  29. package/dist/holmes/mcp/operator-recovery.js +63 -0
  30. package/dist/holmes/runtime/binding.d.ts +30 -0
  31. package/dist/holmes/runtime/binding.js +164 -0
  32. package/dist/holmes/runtime/dispatch.d.ts +9 -0
  33. package/dist/holmes/runtime/dispatch.js +169 -0
  34. package/dist/holmes/runtime/hook-process.d.ts +11 -0
  35. package/dist/holmes/runtime/hook-process.js +130 -0
  36. package/docs/install-guide.md +65 -0
  37. package/package.json +1 -1
@@ -39,6 +39,7 @@ exports.readApprovalFromEnv = readApprovalFromEnv;
39
39
  exports.sedInPlaceFiles = sedInPlaceFiles;
40
40
  exports.hookOutputFor = hookOutputFor;
41
41
  exports.dumpsEnvInCommandPosition = dumpsEnvInCommandPosition;
42
+ exports.ledgerSummaryOf = ledgerSummaryOf;
42
43
  exports.normalizeHookInput = normalizeHookInput;
43
44
  exports.preEditEvidenceGate = preEditEvidenceGate;
44
45
  exports.decideOnGateError = decideOnGateError;
@@ -47,7 +48,8 @@ exports.gateErrorDecision = gateErrorDecision;
47
48
  exports.wiredSpecsDir = wiredSpecsDir;
48
49
  exports.evaluateHook = evaluateHook;
49
50
  exports.readSpecsSync = readSpecsSync;
50
- // @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747
51
+ // @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753
52
+ const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
51
53
  // @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
52
54
  // evaluateHook in this file to prove it.
53
55
  // @implements A-SPEC-643
@@ -73,11 +75,13 @@ const forbidden_edges_1 = require("../cpg/forbidden-edges");
73
75
  const required_calls_1 = require("../cpg/required-calls");
74
76
  const language_parser_1 = require("../cpg/language-parser");
75
77
  const write_target_1 = require("../guardrail/write-target");
78
+ const shell_syntax_1 = require("../guardrail/shell-syntax");
76
79
  const anchors_1 = require("../guardrail/anchors");
77
80
  const governance_history_1 = require("../guardrail/governance-history");
78
81
  const rtm_check_1 = require("../rtm/rtm-check");
79
82
  const ledger_store_1 = require("../governance/ledger-store");
80
83
  const provenance_chain_1 = require("../governance/provenance-chain");
84
+ const ledger_lock_1 = require("../governance/ledger-lock");
81
85
  // @implements A-SPEC-574.3 — the caller owns the store and hands the chain the question.
82
86
  const ledger_store_2 = require("../governance/ledger-store");
83
87
  const risk_gate_1 = require("../guardrail/risk-gate");
@@ -514,6 +518,7 @@ function wrappedServerWord(normalized) {
514
518
  return false;
515
519
  }
516
520
  function startsHolmesServer(command) {
521
+ command = (0, shell_argument_roles_1.shellArgumentRoles)(command).serverText;
517
522
  if (SERVER_RUNNERS.some((t) => t.test(command)))
518
523
  return true;
519
524
  const normalized = normalizedCommand(command);
@@ -801,6 +806,161 @@ function incomingSetsApproved(ti) {
801
806
  const text = `${ti.content ?? ''}\n${ti.new_string ?? ''}\n${(ti.edits ?? []).map((e) => e.new_string ?? '').join('\n')}`;
802
807
  return (0, linear_match_1.setsApprovedStatus)(text); // A-SPEC-728 rule 38: the regex it replaces, in one pass
803
808
  }
809
+ /** @implements A-SPEC-163.2 — the shell form of a patch: the command names the tool as a word. No pattern to back-track on. */
810
+ const APPLY_PATCH_WORD = /(?:^|[^\w-])(?:apply_patch|applypatch)(?![\w-])/;
811
+ const isBlankChar = (c) => c === ' ' || c === '\t' || c === '\r' || c === '\n';
812
+ /**
813
+ * The patch a shell command applies: its text, `'unreadable'`, or null when the command runs no patch tool.
814
+ *
815
+ * @implements A-SPEC-163.4 (rule 3)
816
+ * A shell can rewrite what a patch tool receives — an unquoted heredoc expands its body, a `cd` or a second
817
+ * invocation moves the base, an argument or a file carries text this gate never sees. So one form is read: the whole
818
+ * command line is `apply_patch <<'D'`, the patch, `D`. When the command line runs the tool in any other way — or
819
+ * cannot be parsed into commands and names it — it is unreadable. A command that only mentions the name is not a patch.
820
+ * Walked by index and by line: no pattern over the whole command, nothing to back-track on.
821
+ */
822
+ function shellPatchOf(command) {
823
+ let i = 0;
824
+ while (i < command.length && isBlankChar(command.charAt(i)))
825
+ i++;
826
+ const word = ['apply_patch', 'applypatch'].find((w) => command.startsWith(w, i));
827
+ if (word !== undefined) {
828
+ let j = i + word.length;
829
+ const spaced = j;
830
+ while (j < command.length && (command.charAt(j) === ' ' || command.charAt(j) === '\t'))
831
+ j++;
832
+ const quote = command.charAt(j + 2);
833
+ if (j > spaced && command.startsWith('<<', j) && (quote === "'" || quote === '"')) {
834
+ const close = command.indexOf(quote, j + 3);
835
+ const delimiter = close === -1 ? '' : command.slice(j + 3, close);
836
+ // @implements A-SPEC-163.6 (rule 1) — a line feed directly after the quote: a carriage return there would be
837
+ // part of the delimiter for a shell, which then never finds the closing line this gate found.
838
+ const k = close + 1;
839
+ if (close !== -1 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(delimiter) && command.charAt(k) === '\n') {
840
+ const lines = command.slice(k + 1).split('\n');
841
+ // Exactly the delimiter: a shell does not end a heredoc on `EOF` followed by a carriage return or a space.
842
+ const end = lines.findIndex((line) => line === delimiter);
843
+ if (end !== -1 && lines.slice(end + 1).every((line) => line.trim() === ''))
844
+ return { text: lines.slice(0, end).join('\n') };
845
+ }
846
+ }
847
+ }
848
+ // @implements A-SPEC-163.5, A-SPEC-163.6 — not the one form. Which word a shell runs is not decidable from its text,
849
+ // and four review rounds showed that asking the parser is the deny-list again (a substitution skipped the word
850
+ // test, a heredoc body reshaped the words, the envelope was looked for only at line starts, a reader's option ran
851
+ // a program). So the TEXT is asked (163.6 rule 2): quotes and backslashes are how a shell lets a name be spelled
852
+ // apart; with them removed, a statically written name or envelope marker is a substring whatever the parse. A
853
+ // marked command line is unreadable unless it is one plain read (rule 3), a shape that cannot run anything.
854
+ //
855
+ // Fifth re-review (2026-10-04; measured natively the same day: codex-cli 0.160.0 puts `apply_patch` on the shell
856
+ // PATH): the exemption still trusted the parser (the operand of `<<<` was dropped, an attached `<(` was not a
857
+ // substitution), a backslash-newline split a marker, and ANSI-C quoting spelled one with no marker in the text.
858
+ // So the plain read is decided on the raw text too — only characters that cannot start an expansion, a redirect, a
859
+ // group or a second command — and a marker is also looked for in the words as the parser decodes them.
860
+ let parsed = null;
861
+ try {
862
+ parsed = (0, shell_syntax_1.shellWords)(command);
863
+ }
864
+ catch {
865
+ parsed = null;
866
+ }
867
+ const decodedMark = parsed === null
868
+ ? PATCH_DECODE_HINT.test(command)
869
+ : parsed.commands.some((c) => c.words.some((w) => patchMarked(w.text))) || parsed.subs.some((s) => patchMarked(s));
870
+ // Sixth re-review (2026-10-04): the parser decodes ANSI-C quoting only in top-level words — not in a substitution
871
+ // body, a here-string operand, or after a heredoc body has flipped its quote state. So the escapes are decoded in
872
+ // the TEXT, wherever they sit, whenever the command uses `$'`.
873
+ const ansiMark = command.includes("$'") && patchMarked(command.replace(PATCH_ANSI_ESCAPE, patchAnsiChar));
874
+ if (!patchMarked(command) && !decodedMark && !ansiMark)
875
+ return null;
876
+ if (!PATCH_PLAIN_READ.test(command))
877
+ return 'unreadable';
878
+ try {
879
+ if (parsed === null)
880
+ return 'unreadable';
881
+ if (parsed.overflow || parsed.subs.length > 0 || parsed.commands.length !== 1)
882
+ return 'unreadable';
883
+ const only = parsed.commands[0];
884
+ if (only.redirects.length > 0 || only.words.length === 0 || !only.words.every((w) => w.known && !w.glob))
885
+ return 'unreadable';
886
+ if (!PATCH_READERS.has(only.words[0].text))
887
+ return 'unreadable';
888
+ // An option word may not hold a marker, and no long option is a plain read: a long option can hand the next word
889
+ // to a program (`rg --pre <command>`), which the spec's own test point refuses.
890
+ if (only.words.slice(1).some((w) => w.text.startsWith('--') || (w.text.startsWith('-') && patchMarked(w.text))))
891
+ return 'unreadable';
892
+ return null;
893
+ }
894
+ catch {
895
+ return 'unreadable';
896
+ }
897
+ }
898
+ /** The tool's names and the envelope markers, lower case (A-SPEC-163.6 rule 2). */
899
+ const PATCH_MARKERS = ['apply_patch', 'applypatch', '*** begin patch', '*** add file:', '*** update file:', '*** delete file:', '*** move to:'];
900
+ /** Whether a text shows a marker once its quotes and backslashes are removed and its letters lowered. Substring tests only. */
901
+ function patchMarked(text) {
902
+ // A backslash before a line feed is a line continuation: the shell removes both, so both are removed here.
903
+ const plain = text.split('\\\n').join('').split('"').join('').split("'").join('').split('\\').join('').toLowerCase();
904
+ // `$'…'` and `$"…"` leave their `$` behind once the quotes are gone (`apply$'_patch'` reads `apply$_patch`), so the
905
+ // text is tested with the dollars removed as well.
906
+ const undollared = plain.split('$').join('');
907
+ return PATCH_MARKERS.some((marker) => plain.includes(marker) || undollared.includes(marker));
908
+ }
909
+ /**
910
+ * The whole text of a plain read: letters, digits, spaces, tabs, quotes and `_ . / - : = , + @ % * ?`. Nothing that
911
+ * starts an expansion, a redirect, a group, a comment, a home directory or a second command — and no line break.
912
+ * One character class under one anchored repeat: linear.
913
+ */
914
+ const PATCH_PLAIN_READ = /^[A-Za-z0-9 \t'"_.\/\-:=,+@%*?]*$/;
915
+ /** The numeric escapes of ANSI-C quoting: hex, octal and the two Unicode forms. Alternation of bounded repeats: linear. */
916
+ const PATCH_ANSI_ESCAPE = /\\(?:x\{([0-9A-Fa-f]{1,8})\}?|x([0-9A-Fa-f]{1,2})|([0-7]{1,3})|u([0-9A-Fa-f]{1,4})|U([0-9A-Fa-f]{1,8}))/g;
917
+ function patchAnsiChar(_match, braced, hex, octal, short, long) {
918
+ const code = braced !== undefined ? parseInt(braced, 16) : hex !== undefined ? parseInt(hex, 16)
919
+ : octal !== undefined ? parseInt(octal, 8) : parseInt(short ?? long ?? '0', 16);
920
+ try {
921
+ return String.fromCodePoint(code);
922
+ }
923
+ catch {
924
+ return '';
925
+ }
926
+ }
927
+ /** When the command line does not parse at all: ANSI-C quoting is the one static spelling that hides a marker from the text. */
928
+ const PATCH_DECODE_HINT = /\$'/;
929
+ /** First words of a command that only reads its operands (A-SPEC-163.6 rule 3). */
930
+ const PATCH_READERS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'cat', 'head', 'tail', 'wc', 'ls']);
931
+ /** One key per file: links resolved on the longest existing part, letter case folded (A-SPEC-163.4 rule 5). */
932
+ function patchFileKey(file) {
933
+ // The path is handed to the OS as written: folding `..` first would step back from a link's NAME, not from where
934
+ // the link leads. An existing file is its device and inode, so a link of either kind names the same key.
935
+ try {
936
+ const stat = fs.statSync(file);
937
+ return 'inode:' + stat.dev + ':' + stat.ino;
938
+ }
939
+ catch { /* not there yet: its real parent and its name */ }
940
+ const slash = file.lastIndexOf('/');
941
+ const parent = slash <= 0 ? '/' : file.slice(0, slash);
942
+ const name = file.slice(slash + 1);
943
+ let real = path.resolve(file);
944
+ try {
945
+ real = fs.realpathSync(parent) + '/' + name;
946
+ }
947
+ catch { /* the parent is not there either: the lexical path */ }
948
+ return 'path:' + real.normalize('NFC').toLowerCase();
949
+ }
950
+ /** Strings read from one payload; more than this is not a payload a tool sends. */
951
+ const PATCH_STRINGS_MAX = 256;
952
+ /** A file an update hunk is applied to; a larger one is not judged by its result. */
953
+ const PATCH_UPDATE_BYTES_MAX = 8 * 1024 * 1024;
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
+ /**
956
+ * @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
957
+ * The installer refusal (A-SPEC-753.1) carries the raw command after ` Operator: ` for the operator to run; the ledger
958
+ * is the one artefact meant to carry no raw command. The reason printed to the harness is unchanged.
959
+ */
960
+ function ledgerSummaryOf(reason) {
961
+ const at = reason.indexOf(' Operator: ');
962
+ return at === -1 ? reason : reason.slice(0, at);
963
+ }
804
964
  function normalizeHookInput(raw) {
805
965
  const str = (v) => (typeof v === 'string' ? v : undefined);
806
966
  if (!raw || typeof raw !== 'object')
@@ -858,7 +1018,58 @@ function normalizeHookInput(raw) {
858
1018
  }
859
1019
  const cwdRaw = str(r.cwd);
860
1020
  const cwd = cwdRaw === undefined ? undefined : (cwdRaw.trim() || undefined);
861
- return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(malformed ? { malformed: true } : {}) };
1021
+ // @implements A-SPEC-163.1, A-SPEC-163.2 — a patch names its targets only inside the patch text, under a key no
1022
+ // contract of ours pins. Measured 2026-10-04: Codex `apply_patch` wrote an unanchored code file past this gate.
1023
+ // 163.2 (rule 1): strings are taken at any nesting to depth 4. A patch tool: every string with an envelope line.
1024
+ // The shell tool: its command when it runs `apply_patch`, and any nested whole patch. Any other write tool: only a
1025
+ // whole patch — prose that quotes patch lines is not a write. A path field does not hide the patch beside it.
1026
+ // A patch that cannot be read one way (no target, an empty path, too many, an indented header) is unreadable.
1027
+ const toolName = (str(r.tool_name) ?? '').toLowerCase();
1028
+ let patchUnreadable = false;
1029
+ if (!write_target_1.READ_ONLY_TOOLS.includes(toolName)) {
1030
+ const strings = [];
1031
+ const collect = (v, depth) => {
1032
+ if (typeof v === 'string') {
1033
+ if (!v.includes('*** '))
1034
+ return;
1035
+ // @implements A-SPEC-163.3 (rule 6) — more than the gate reads is unreadable, never unread.
1036
+ if (strings.length >= PATCH_STRINGS_MAX)
1037
+ patchUnreadable = true;
1038
+ else
1039
+ strings.push(v);
1040
+ return;
1041
+ }
1042
+ if (patchUnreadable)
1043
+ return;
1044
+ if (depth >= 4 || !v || typeof v !== 'object')
1045
+ return;
1046
+ for (const item of Array.isArray(v) ? v : Object.values(v))
1047
+ collect(item, depth + 1);
1048
+ };
1049
+ collect(ti, 0);
1050
+ const isPatchTool = toolName.includes('patch');
1051
+ const isShell = toolName === 'bash';
1052
+ // @implements A-SPEC-163.4 — which strings are patches is 163.2's rule; whether one is JUDGED is one positive
1053
+ // grammar. The shell tool's command is a patch only as one quoted-heredoc `apply_patch` (rule 3); every string
1054
+ // read as a patch must be canonical (rules 1-2). Anything else is unreadable, not unread.
1055
+ const patches = strings.filter((text) => !(isShell && text === cmd) && (isPatchTool ? (0, write_target_1.hasPatchEnvelope)(text) : (0, write_target_1.isWholePatch)(text)));
1056
+ if (isShell && cmd !== undefined) {
1057
+ const shellPatch = shellPatchOf(cmd);
1058
+ if (shellPatch === 'unreadable')
1059
+ patchUnreadable = true;
1060
+ else if (shellPatch !== null)
1061
+ patches.push(shellPatch.text);
1062
+ }
1063
+ if (patches.length > 0) {
1064
+ 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)))
1066
+ patchUnreadable = true;
1067
+ else
1068
+ out.patch_targets = targets;
1069
+ }
1070
+ }
1071
+ return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(malformed ? { malformed: true } : {}),
1072
+ ...(patchUnreadable ? { patchUnreadable: true } : {}) };
862
1073
  }
863
1074
  /**
864
1075
  * Which way to fail when the gate itself throws.
@@ -1003,6 +1214,70 @@ function evaluateHook(input, specsDir, opts) {
1003
1214
  // @implements A-SPEC-728 (rule 40) — a spec edit's result is shared within this call only: a caller that hands the same
1004
1215
  // tool_input object back changed must not be judged on the earlier result.
1005
1216
  editedMemo = null;
1217
+ // @implements A-SPEC-163.1 — each file a patch names is judged by the same path as a `file_path` write of it;
1218
+ // the first denial is the decision. A relative target is where the tool would write it: from the payload cwd.
1219
+ // @implements A-SPEC-163.2 — an update or a move is judged on the file it produces (the hunk applied to the file on
1220
+ // disk); a move's source is judged as a delete; a relative target is `<base>/<path>` as written, not folded first;
1221
+ // a patch that cannot be read or applied is denied. When no target is denied, a payload with a path field or a
1222
+ // shell command is then judged as before.
1223
+ if (input.patchUnreadable)
1224
+ return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1225
+ const patchTargets = input.tool_input.patch_targets;
1226
+ if (patchTargets !== undefined && !input.malformed) {
1227
+ const isShell = (input.tool_name ?? '').toLowerCase() === 'bash';
1228
+ // A relative `workdir` is relative to the payload cwd, never to wherever this hook process happens to run.
1229
+ const outer = input.cwd ?? opts.projectRoot;
1230
+ const workdir = isShell ? input.tool_input.workdir : undefined;
1231
+ const base = workdir === undefined ? outer : (path.isAbsolute(workdir) ? workdir : outer.replace(/\/+$/, '') + '/' + workdir);
1232
+ const at = (p) => (path.isAbsolute(p) ? p : base.replace(/\/+$/, '') + '/' + p);
1233
+ const resultOf = (source, hunk) => {
1234
+ try {
1235
+ // @implements A-SPEC-163.3 (rule 7) — only a regular file is read: a FIFO or a device would hold the hook.
1236
+ const stat = fs.statSync(source);
1237
+ if (!stat.isFile() || stat.size > PATCH_UPDATE_BYTES_MAX)
1238
+ return null;
1239
+ return (0, write_target_1.applyPatchUpdate)(fs.readFileSync(source, 'utf8'), hunk);
1240
+ }
1241
+ catch {
1242
+ return null;
1243
+ }
1244
+ };
1245
+ // @implements A-SPEC-163.3 (rule 1), A-SPEC-163.4 (rule 5) — two targets on one file have no one result: the tool
1246
+ // applies them in sequence, the gate reads the disk once. One file is one key whatever link or letter case names it.
1247
+ // (What a shell could rewrite is settled before this point: only the one quoted-heredoc form reaches here.)
1248
+ const files = new Set();
1249
+ for (const t of patchTargets) {
1250
+ const file = patchFileKey(at(t.path));
1251
+ if (files.has(file))
1252
+ return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1253
+ files.add(file);
1254
+ }
1255
+ for (const t of patchTargets) {
1256
+ let content;
1257
+ if (t.kind === 'add')
1258
+ content = t.content;
1259
+ else if (t.kind === 'update' && t.movedTo === undefined) {
1260
+ const result = resultOf(at(t.path), t.hunk ?? '');
1261
+ if (result === null)
1262
+ return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1263
+ content = result;
1264
+ }
1265
+ else if (t.kind === 'move') {
1266
+ const result = t.from === undefined ? null : resultOf(at(t.from), t.hunk ?? '');
1267
+ if (result === null)
1268
+ return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1269
+ content = result;
1270
+ }
1271
+ // Judged as a patch tool's write whichever tool carried the patch, so the shell branch below is not re-entered.
1272
+ const verdict = evaluateHook({ tool_name: 'apply_patch', tool_input: { file_path: at(t.path), ...(content === undefined ? {} : { content }) },
1273
+ ...(input.cwd === undefined ? {} : { cwd: input.cwd }) }, specsDir, opts);
1274
+ if (verdict.permissionDecision === 'deny')
1275
+ return verdict;
1276
+ }
1277
+ const hasPathField = typeof input.tool_input.file_path === 'string' || typeof input.tool_input.notebook_path === 'string';
1278
+ if (!hasPathField && !isShell)
1279
+ return { permissionDecision: 'allow' };
1280
+ }
1006
1281
  // @implements A-SPEC-133 — resolved once so every gate in this call shares one timestamp.
1007
1282
  const nowTs = opts?.now ?? new Date().toISOString();
1008
1283
  // @implements A-SPEC-125.4
@@ -1060,13 +1335,16 @@ function evaluateHook(input, specsDir, opts) {
1060
1335
  // replayed token denies exactly as an absent one — one token stops being a master key.
1061
1336
  // @implements A-SPEC-728 — an operator who approved THIS exact hard-hitl command (e.g. a covered
1062
1337
  // `rm -rf /`) has already judged its deletions; the wiring-deletion rule below must not re-deny it.
1338
+ // @implements A-SPEC-477.1 — spend only after every shell check succeeds.
1339
+ const pendingApprovals = [];
1340
+ const legacySessionApproval = approval?.scope === undefined
1341
+ && (0, risk_gate_1.approvalCovers)(approval, { kind: 'config-write', target: command }, nowTs);
1063
1342
  let hardHitlCovered = false;
1064
1343
  if (assessment.level === 'hard-hitl') {
1065
1344
  // @implements A-SPEC-245 — env first, then the grant files. The grant's mandatory nonce rides
1066
1345
  // the SAME atomic ledger consumption below, so hard-hitl single-use needs no new machinery.
1067
1346
  const resolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'shell', target: command }, nowTs);
1068
1347
  const covers = resolved !== undefined;
1069
- const acting = resolved?.approval ?? approval;
1070
1348
  const deny = (why) => ({
1071
1349
  permissionDecision: 'deny',
1072
1350
  permissionDecisionReason: `[Holmes-Kit] hard-hitl risk: ${assessment.reasons.join('; ')} — ${why}`,
@@ -1081,60 +1359,12 @@ function evaluateHook(input, specsDir, opts) {
1081
1359
  return deny(base
1082
1360
  + (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'shell', target: command, why: assessment.reasons.join('; ') }, { baseReasonBytes: base.length }));
1083
1361
  }
1084
- // @implements A-SPEC-141
1085
- // Check and spend in ONE atomic operation. The previous shape asked `isNonceConsumed(...)`
1086
- // and only afterwards appended the consumption record, so two concurrent agents both saw
1087
- // "not consumed" and both proceeded — measured, the same single-use approval was honoured
1088
- // twice in 20 of 20 barrier-synchronized trials. That is a TOCTOU on the authorization gate,
1089
- // not a logging problem, so the fix belongs here rather than around the append.
1090
- // @implements A-SPEC-191 §15 (round 11) — NOT a refusal here, deliberately, and this is the
1091
- // reasoning: the MCP consumers refuse a nonce they cannot record in a bound project (§13b),
1092
- // and round-10 flagged the hook for lacking the same rule. But this consumer's anchor now
1093
- // walks UP (§14a), so a subdirectory resolves to the real project and the only case left is a
1094
- // directory with no project above it at all — a fresh project's first guarded command, where
1095
- // creating `.ax/ledger` is the wiring working, not a plant. Refusing there would deny the
1096
- // first legitimate use in every new project. The single-use guarantee still holds: the record
1097
- // lands in the resolved root, which is the same file every later call resolves to.
1098
- // @implements A-SPEC-643 — the writer's replica chain, resolved only on this path so ordinary hook
1099
- // calls leave no footprint; the spent check below still spans every chain in the directory.
1100
- const ledgerFile = (0, ledger_store_2.writerChainFile)(path.join(opts.projectRoot, '.ax', 'ledger'));
1101
- // @implements A-SPEC-642 — a covered command is still denied, and no nonce spent, while the
1102
- // merged ledger holds an unreconciled cross-replica double-spend; the reason names the exit.
1103
- {
1104
- const conflict = (0, ledger_store_2.ledgerConflictReason)(path.dirname(ledgerFile));
1105
- if (conflict)
1106
- return deny(conflict);
1107
- }
1108
- if ((0, provenance_chain_1.blankNonce)(acting?.nonce)) {
1109
- return deny('the approval declared single-use (nonce) but the value is empty — single-use cannot be enforced, so it is denied');
1110
- }
1111
- if (acting?.nonce) {
1112
- let won;
1113
- try {
1114
- won = (0, provenance_chain_1.consumeNonceExclusively)(acting.nonce, ledgerFile, {
1115
- ts: nowTs, actor: acting.actor, kind: 'nonce-consumed',
1116
- summary: `consumed single-use approval for: ${(0, provenance_chain_1.redactTarget)('command', command)}`.slice(0, 200),
1117
- inputs: [(0, provenance_chain_1.nonceFingerprint)(acting.nonce)], rationale: acting.rationale, authorization: (0, provenance_chain_1.authorizationRef)(acting.actor, acting.token),
1118
- }, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
1119
- }
1120
- catch (err) {
1121
- // FAIL CLOSED. A gate that cannot prove exclusivity must not grant — degrading to an
1122
- // allow here would restore exactly the race this exists to remove. The wording is
1123
- // deliberately DIFFERENT from the replay wording: an operator debugging a wedged agent
1124
- // needs to tell "someone already used this token" from "the ledger was busy".
1125
- return deny(`could not obtain exclusive ledger access to spend the single-use approval (${err instanceof Error ? err.message : String(err)})`);
1126
- }
1127
- if (!won)
1128
- return deny('single-use approval already consumed (replay)');
1129
- // The ledger consumption is the authority; removing the file is cleanup for the next reader.
1130
- if (resolved?.source === 'grant')
1131
- (0, approval_grants_1.consumeGrantFile)(opts.projectRoot, acting.nonce);
1132
- }
1362
+ pendingApprovals.push(resolved);
1133
1363
  }
1134
1364
  // Bash BYPASS gates (adversarial review: `cat > evil.ts` created ungoverned files, `echo x >
1135
1365
  // .claude/settings.json` forged hook config, and `echo $HOLMES_LEDGER_KEY` harvested the very
1136
1366
  // secrets the out-of-band channel depends on). All override-able by a valid approval.
1137
- if (!(0, risk_gate_1.isValidApproval)(approval)) {
1367
+ {
1138
1368
  // (a) Reading/dumping the out-of-band secrets: possession of the approval token or ledger key
1139
1369
  // lets the agent forge approvals / re-sign history. Best-effort (a determined exfil via an
1140
1370
  // interpreter remains — documented residual); raises the cost from one echo to a gated act.
@@ -1169,7 +1399,8 @@ function evaluateHook(input, specsDir, opts) {
1169
1399
  // Which of the two harms this is. Setting a role or a bypass is not reading a secret, it is
1170
1400
  // self-granting authority — reporting both as "reads the environment" sends an operator to
1171
1401
  // hunt a leak that never happened.
1172
- const GRANTS_SELF = new RegExp(String.raw `\b(?:HOLMES_(?:ROLE|GATE_BYPASS|AUTONOMOUS_APPROVAL)|HOLMES_SEMANTIC_API_KEY|GEMINI_API_KEY|GOOGLE_API_KEY)\b`).test(command);
1402
+ const GRANTS_SELF = /\bHOLMES_(?:ROLE|GATE_BYPASS|AUTONOMOUS_APPROVAL|SEMANTIC_API_KEY)\b/.test(command);
1403
+ const providerCredential = /\b(?:GEMINI_API_KEY|GOOGLE_API_KEY)\b/.test(command);
1173
1404
  const usesSecret =
1174
1405
  // @implements A-SPEC-477 — the credential file is the same secret at rest; reading,
1175
1406
  // copying or redirecting it is the harvest in file form. Path-usage only, so mentioning
@@ -1208,21 +1439,43 @@ function evaluateHook(input, specsDir, opts) {
1208
1439
  tailAfterFirst(command, /\n/, /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php|awk|gawk)\b/, /(?<![.\w])ENV\b/);
1209
1440
  // @implements A-SPEC-732 (round 2) — an agent starting its own copy of the MCP server can pose as a
1210
1441
  // harness and answer its own approval; no agent task needs that copy (doctor starts one internally).
1211
- if (startsHolmesServer(command)) {
1442
+ // @implements A-SPEC-753.1 — the documented installer without --dry-run starts no server: it changes which
1443
+ // build governs a workspace. Measured 2026-10-04, it was refused under the server-start wording below with
1444
+ // nothing for the operator to run. It stays refused; the reason names the act and carries the command. No
1445
+ // request id is printed: none exists until the operator runs the command, which files it.
1446
+ if (!legacySessionApproval && (0, shell_argument_roles_1.installerInvocationOf)(command) === 'apply') {
1212
1447
  return {
1213
1448
  permissionDecision: 'deny',
1214
- permissionDecisionReason: '[Holmes-Kit] the command starts the Holmes MCP server (or loads its handlers) itself — a copy the agent drives could answer its own approval (A-SPEC-732). The harness starts the server; use its tools. To run it by operator judgment, an approval that covers this command is required.',
1449
+ permissionDecisionReason: '[Holmes-Kit] runtime-binding setup/remove changes which Holmes build governs a workspace (governance wiring); the operator runs it, not the session. It prints the request id to approve; after the grant the operator runs the same command again. Use --dry-run to preview it here. Operator: ' + command,
1215
1450
  };
1216
1451
  }
1217
- if (dumpsEnv) {
1452
+ if (!legacySessionApproval && startsHolmesServer(command)) {
1218
1453
  return {
1219
1454
  permissionDecision: 'deny',
1220
- permissionDecisionReason: GRANTS_SELF
1221
- ? '[Holmes-Kit] the command sets or reads HOLMES_ROLE/HOLMES_GATE_BYPASS — a path by which a session grants itself authority.'
1222
- + ' Roles are set out-of-band by whoever launches the agent. To run it by operator judgment, an approval that includes config-write is required.'
1223
- : '[Holmes-Kit] command reads or dumps process environment (holds the out-of-band HOLMES_APPROVAL / HOLMES_LEDGER_KEY secrets) — requires out-of-band approval',
1455
+ permissionDecisionReason: '[Holmes-Kit] the command starts the Holmes MCP server (or loads its handlers) itself — a copy the agent drives could answer its own approval (A-SPEC-732). The harness starts the server; use its tools. To run it by operator judgment, an approval that covers this command is required.',
1224
1456
  };
1225
1457
  }
1458
+ if (dumpsEnv) {
1459
+ const reason = GRANTS_SELF
1460
+ ? '[Holmes-Kit] the command accesses Holmes authority or semantic-egress configuration — requires operator approval'
1461
+ : providerCredential
1462
+ ? '[Holmes-Kit] the command accesses a protected provider credential — requires operator approval'
1463
+ : '[Holmes-Kit] command reads or dumps process environment (holds out-of-band approval secrets) — requires operator approval';
1464
+ const resolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'config-write', target: command }, nowTs);
1465
+ if (!resolved) {
1466
+ let hint = (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'config-write', target: command, why: reason });
1467
+ // The queue deliberately suppresses duplicate writes, not the pending operator decision.
1468
+ const id = (0, approval_queue_1.approvalRequestId)('config-write', command);
1469
+ if (!hint && (0, approval_queue_1.readQueue)(opts.projectRoot).pending.some((request) => request.id === id)) {
1470
+ hint = ` — approval request ${id} is pending; retry after operator approval`;
1471
+ }
1472
+ return { permissionDecision: 'deny', permissionDecisionReason: reason
1473
+ + (hint || ' — could not persist the approval request; ask the operator to check the project approval queue storage') };
1474
+ }
1475
+ pendingApprovals.push(resolved);
1476
+ }
1477
+ }
1478
+ if (!legacySessionApproval) {
1226
1479
  // (b) Shell-writing hook/approval CONFIG (the F6a surface, previously Write/Edit-only).
1227
1480
  // @implements A-SPEC-191 §28 (round 13) — the rule matched only redirection and `tee`, and
1228
1481
  // `cp`, `mv`, `install`, `ln -f`, `dd of=`, `rsync` and `sed -i` write the same file just as
@@ -1415,8 +1668,7 @@ function evaluateHook(input, specsDir, opts) {
1415
1668
  const liftByConfigWrite = (why) => {
1416
1669
  const r = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'config-write', target: command }, nowTs);
1417
1670
  if (r !== undefined) {
1418
- if (r.source === 'grant' && r.approval.nonce)
1419
- (0, approval_grants_1.consumeGrantFile)(opts.projectRoot, r.approval.nonce);
1671
+ pendingApprovals.push(r);
1420
1672
  return null;
1421
1673
  }
1422
1674
  return { permissionDecision: 'deny', permissionDecisionReason: `[Holmes-Kit] ${why} — an out-of-band approval that includes config-write is required (A-SPEC-728)`
@@ -1593,6 +1845,52 @@ function evaluateHook(input, specsDir, opts) {
1593
1845
  }
1594
1846
  }
1595
1847
  }
1848
+ if (pendingApprovals.length > 0) {
1849
+ const deny = (why) => ({ permissionDecision: 'deny',
1850
+ permissionDecisionReason: `[Holmes-Kit] ${why}` });
1851
+ // @implements A-SPEC-477.1 — a later invalid approval must not spend an earlier valid one.
1852
+ // Validate the complete set, then check all replays and append under ONE existing ledger hold.
1853
+ // This coordinates validation; it does not promise rollback after an I/O failure during append.
1854
+ if (pendingApprovals.some(({ approval }) => (0, provenance_chain_1.blankNonce)(approval.nonce))) {
1855
+ return deny('the approval declared single-use (nonce) but the value is empty — single-use cannot be enforced, so it is denied');
1856
+ }
1857
+ const ledgerFile = (0, ledger_store_2.writerChainFile)(path.join(opts.projectRoot, '.ax', 'ledger'));
1858
+ const unique = new Map(pendingApprovals.filter(({ approval }) => !!approval.nonce)
1859
+ .map(({ approval }) => [approval.nonce, approval]));
1860
+ const check = () => {
1861
+ const conflict = (0, ledger_store_2.ledgerConflictReason)(path.dirname(ledgerFile));
1862
+ if (conflict)
1863
+ return conflict;
1864
+ const consumed = (0, ledger_store_2.nonceConsumedIn)(ledgerFile);
1865
+ if ([...unique.keys()].some(consumed))
1866
+ return 'single-use approval already consumed (replay)';
1867
+ return null;
1868
+ };
1869
+ try {
1870
+ const chain = new provenance_chain_1.ProvenanceChain(ledgerFile);
1871
+ const failure = unique.size === 0 ? check() : (0, ledger_lock_1.withLedgerLock)(ledgerFile, () => {
1872
+ const reason = check();
1873
+ if (reason)
1874
+ return reason;
1875
+ for (const [nonce, acting] of unique)
1876
+ chain.appendInsideLock({
1877
+ ts: nowTs, actor: acting.actor, kind: 'nonce-consumed',
1878
+ summary: `consumed single-use approval for: ${(0, provenance_chain_1.redactTarget)('command', command)}`.slice(0, 200),
1879
+ inputs: [(0, provenance_chain_1.nonceFingerprint)(nonce)], rationale: acting.rationale, authorization: (0, provenance_chain_1.authorizationRef)(acting.actor, acting.token),
1880
+ });
1881
+ return null;
1882
+ }, { onStaleBreak: chain.staleBreakRecorder() });
1883
+ if (failure)
1884
+ return deny(failure);
1885
+ }
1886
+ catch (err) {
1887
+ return deny(`could not obtain exclusive ledger access to spend the single-use approval (${err instanceof Error ? err.message : String(err)})`);
1888
+ }
1889
+ for (const { source, approval } of pendingApprovals) {
1890
+ if (source === 'grant' && approval.nonce)
1891
+ (0, approval_grants_1.consumeGrantFile)(opts.projectRoot, approval.nonce);
1892
+ }
1893
+ }
1596
1894
  // auto/notify/confirm, or hard-hitl with a valid approval: this slice blocks only
1597
1895
  // hard-hitl; confirm is advisory here.
1598
1896
  return { permissionDecision: 'allow' };
@@ -2254,12 +2552,25 @@ function evaluateHook(input, specsDir, opts) {
2254
2552
  // new CODE must not be layered on top of it. WRITE_TEST and spec authoring stay open — you must be
2255
2553
  // able to fix the tests/specs that clear the debt. A covering approval overrides; a clean Stop
2256
2554
  // clears the debt and code resumes.
2555
+ //
2556
+ // @implements A-SPEC-134.1 — measured 2026-10-04: an open critical (ART-7) became debt, its fix was sealed source
2557
+ // work, and this branch refused every edit that fixes it; the refusal filed no request, so neither the session nor
2558
+ // `holmes-kit approve` could act. (1) Debt that is ART-7 alone does not deny: a critical is cleared only by changing
2559
+ // source, and every other gate still judges the write. (2) Any other debt denies as before, and (3) that denial is
2560
+ // grantable — a queue grant for this exact path lifts THIS branch only (the seal, role, scope and evidence gates
2561
+ // keep `codeWriteCovered`, the environment approval); it is not consumed, so a fix of several edits is one operator
2562
+ // act per file. The refusal files the request and prints its id and the operator command.
2257
2563
  if (action === 'WRITE_CODE' && !codeWriteCovered) {
2258
2564
  const debt = (0, constitution_debt_1.readDebt)(projectRoot);
2259
- if (debt && debt.length > 0) {
2565
+ const cureOnly = !!debt && debt.length > 0 && debt.every((a) => a === 'ART-7');
2566
+ if (debt && debt.length > 0 && !cureOnly
2567
+ && (0, approval_grants_1.resolveApproval)(projectRoot, weApproval, { kind: 'code-write', target: relPath }, nowTs) === undefined) {
2568
+ const why = `code write under constitution debt (${debt.join(', ')})`;
2260
2569
  return {
2261
2570
  permissionDecision: 'deny',
2262
- permissionDecisionReason: `[Holmes-Kit] constitution-debt outstanding (${debt.join(', ')}) — resolve the constitution (a clean turn clears it) before writing new code, or supply a covering approval`,
2571
+ permissionDecisionReason: `[Holmes-Kit] constitution-debt outstanding (${debt.join(', ')}) — resolve the constitution (a clean turn clears it) before writing new code, or supply a covering approval`
2572
+ + ((0, approval_queue_1.queueHint)(projectRoot, { kind: 'code-write', target: relPath, why })
2573
+ || ' — could not persist the approval request; ask the operator to check the project approval queue storage'),
2263
2574
  };
2264
2575
  }
2265
2576
  }
@@ -2541,7 +2852,7 @@ if (require.main === module) {
2541
2852
  // trail was the one artefact guaranteed to accumulate the secrets the gate protects.
2542
2853
  // `summary` keeps the human-readable classification, which is the auditable part.
2543
2854
  summary: out.permissionDecision === 'deny'
2544
- ? (out.permissionDecisionReason ?? 'denied')
2855
+ ? ledgerSummaryOf(out.permissionDecisionReason ?? 'denied')
2545
2856
  : `approved action: ${input.tool_name} ${target}`.slice(0, 300),
2546
2857
  // @implements A-SPEC-133 — a master-key use becomes an audit line: the approval's
2547
2858
  // narrowing (or its absence) travels with the record (r7-191: promised, never shipped).
@@ -406,7 +406,15 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
406
406
  root: string;
407
407
  base?: string;
408
408
  head?: string;
409
- since?: string;
409
+ since
410
+ /**
411
+ * A root the caller named that this process cannot read is the CALLER'S mistake, not a fault.
412
+ * @implements A-SPEC-189 §10 (round 11)
413
+ */
414
+ ? /**
415
+ * A root the caller named that this process cannot read is the CALLER'S mistake, not a fault.
416
+ * @implements A-SPEC-189 §10 (round 11)
417
+ */: string;
410
418
  }) => Promise<{
411
419
  requirementSemanticWarm?: {
412
420
  tier: string;
@@ -38,7 +38,8 @@ exports.isHandlerRefusal = isHandlerRefusal;
38
38
  exports.unreadableAmong = unreadableAmong;
39
39
  exports.makeHandlers = makeHandlers;
40
40
  exports.collectDecisions = collectDecisions;
41
- // @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732
41
+ // @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754
42
+ const operator_recovery_1 = require("./operator-recovery");
42
43
  // @implements A-SPEC-643
43
44
  // @implements A-SPEC-642
44
45
  // @implements A-SPEC-642
@@ -213,7 +214,7 @@ function resolveHandlerApproval(rootArg, store, envApproval, action, now) {
213
214
  const r = (0, approval_grants_1.resolveApproval)(root, envApproval, action, now);
214
215
  return r ? { ...r, root } : undefined;
215
216
  }
216
- function refusalQueueHint(rootArg, store, req) {
217
+ function refusalQueueHint(rootArg, store, req, operation) {
217
218
  try {
218
219
  // The SpecStore interface carries no root; the file-backed store exposes one. A store without a
219
220
  // root files nothing — the queue lives on disk, and with no disk location there is nothing to do.
@@ -221,7 +222,8 @@ function refusalQueueHint(rootArg, store, req) {
221
222
  const base = rootArg !== undefined ? rootArg : (typeof storeRoot === 'string' ? storeRoot : undefined);
222
223
  if (base === undefined)
223
224
  return '';
224
- return (0, approval_queue_1.queueHint)(projectRootOf(base), req);
225
+ const root = projectRootOf(base);
226
+ return (0, approval_queue_1.queueHint)(root, req, (0, operator_recovery_1.operatorRecovery)(root, req.target, operation));
225
227
  }
226
228
  catch {
227
229
  return '';
@@ -873,7 +875,7 @@ function makeRawHandlers(store, opts) {
873
875
  prepareHostApproval,
874
876
  consumeHostApproval,
875
877
  resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
876
- refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
878
+ refusalQueueHint: (root, request) => refusalQueueHint(root, store, request, 'spec_approve'),
877
879
  foreignRootReason: (root) => foreignRootReason(store, root),
878
880
  });
879
881
  /**
@@ -0,0 +1,9 @@
1
+ /** Formatting only: the caller must return pending text only after a successful enqueue. */
2
+ export declare function operatorRecovery(root: string, target: string, operation?: string, options?: {
3
+ platform?: NodeJS.Platform;
4
+ executable?: string;
5
+ cli?: string;
6
+ }): {
7
+ reviewCommand: string;
8
+ pendingHint(id: string): string;
9
+ };