@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
package/CHANGELOG.md CHANGED
@@ -5,8 +5,50 @@ 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.1] - 2026-10-04
9
+
10
+ ### Fixed
11
+
12
+ - **A patch tool no longer writes past the gate** (A-SPEC-163.1–163.6). Measured on codex-cli 0.160.0: `apply_patch`
13
+ created an unanchored code file in a governed project because the gate asked for a path field and a patch names
14
+ its targets only in the patch text. The gate now reads the patch and judges every target on the file it produces —
15
+ an update is applied to the file on disk, a move is a write of the result and a delete of the source. Only the
16
+ canonical patch form is judged; anything else (text around the envelope, an unknown `*** ` line, a path with
17
+ quotes or expansion characters, two targets on one file, a context line that differs from the file, an old text
18
+ found more than once) is refused as unreadable.
19
+ - **Constitution debt no longer blocks the fix that clears it** (A-SPEC-134.1). An open critical finding (ART-7)
20
+ recorded as debt refused every source edit, including the sealed fix for that finding, and the refusal filed no
21
+ request. Debt that is ART-7 alone no longer denies a code write; every other gate still applies and the Stop gate
22
+ still reports the finding. Debt from any other article is refused as before, and that refusal now files a
23
+ `code-write` request and prints its id and the operator command; a queue grant for that path lifts it.
24
+ - **A refused installer apply names the act** (A-SPEC-753.1/753.2). A `runtime-binding setup|remove` without
25
+ `--dry-run` was refused as "starts the Holmes MCP server". It is now refused as governance wiring, with the
26
+ command for the operator; the command no longer reaches the provenance ledger, and the installed bin and
27
+ `--name=value` spellings are classified like the documented form.
28
+ - **A reviewed wiring plan survives a model switch** (A-SPEC-752.5/752.6). The installation receipt recorded the
29
+ whole bytes of `~/.claude/settings.json`, so switching the model changed the plan digest with no wiring change.
30
+ The receipt now records the document without its `model` key; a change to any other key is still a conflict.
31
+
32
+ ### Changed
33
+
34
+ - **A shell command that carries a patch or names the patch tool is judged in one form only** (A-SPEC-163.4–163.6).
35
+ `apply_patch <<'EOF' … EOF` as the whole command is judged on its patch. Any other shell command whose text shows
36
+ `apply_patch`, `applypatch` or a patch envelope marker is refused, except one plain `grep`, `egrep`, `fgrep`, `rg`,
37
+ `cat`, `head`, `tail`, `wc` or `ls` with literal words (no pipe, redirect, substitution or long option). Searching
38
+ for the tool's name through a pipeline or `git grep` is refused; the harness's own search tools are unaffected.
39
+ A command that composes the tool's name at run time and takes its patch from a file is outside this rule.
40
+
8
41
  ## [0.35.0] - 2026-10-02
9
42
 
43
+ ### Added
44
+
45
+ - **Explicit development/consumer runtime binding** (A-SPEC-751/752). `runtime-binding setup|status|remove`
46
+ uses an operator-owned registry to select registered checkout builds independently of the release package.
47
+ Setup previews exact edits, requires plan-bound authority for changes, preserves unrelated wiring and native
48
+ trust, and supports explicit `--activate-hooks` selection. A fully validated zero-change retry needs no new
49
+ grant; changed build identities and legacy receipt migration still require reviewed installation changes.
50
+ `doctor --registry` diagnoses custom registries. Native activation remains distinct from configuration checks.
51
+
10
52
  ### Changed
11
53
 
12
54
  - **The pre-edit evidence gate follows new files and the RED commit** (A-SPEC-278.2/278.3). Persisted
@@ -20,6 +62,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
20
62
 
21
63
  ### Fixed
22
64
 
65
+ - **Routed hooks bound execution and owned-process cleanup** (A-SPEC-751.1). Input, selection and execution
66
+ share an 18-second budget, followed by at most 8 seconds of cleanup. POSIX process-group and Windows
67
+ task-tree cleanup preserve external termination and report uncertainty. Partial or invalid protocol output
68
+ is not forwarded as a decision. Refusals name diagnosis commands and approved repair/retry steps without
69
+ clearing governance debt. Persistent MCP sessions retain their separate lifetime.
70
+ - **Recovery arguments are distinguished from executed shell actions** (A-SPEC-753). Literal Codex prompt
71
+ text, recognized search-pattern arguments and the exact supported runtime-binding dry-run grammar no longer
72
+ look like protected writes or server launches. Substitutions, redirects, output paths and uncertain syntax
73
+ retain their checks. Non-preview installation still uses the official operator approval path.
74
+ - **Environment approval validates every nonce before consumption** (A-SPEC-477.1). An invalid or replayed
75
+ sibling cannot consume another otherwise usable grant before validation completes. This does not claim
76
+ transactional rollback after a later ledger append failure.
77
+ - **Routed MCP preserves its genuine native parent** (A-SPEC-754). The dedicated dispatcher loads the
78
+ validated package entry in the same process, retaining argv, package-local dependencies and the entry's
79
+ opt-in autoreload branch. Partial synchronous startup failures terminate nonzero. Unattested routes still
80
+ use the official operator queue: guidance names the running CLI, bound workspace and recorded request,
81
+ then identifies the original operation to retry. Held questions and denials remain visible; commands
82
+ are quoted as literal paths and are not broken by narrative wrapping. Native attestation and grant
83
+ validity checks are unchanged; configuration or subprocess tests alone do not prove live recovery.
23
84
  - **File redirects using `>&` or `>|` reach the protected-write classifier** (A-SPEC-728.1). Descriptor
24
85
  duplication and closure such as `2>&1`, `>&2`, and `>&-` keep their existing interpretation.
25
86
  - **The ART-4 static test counter reads literals, aliases, and suite skips correctly** (A-SPEC-750). A
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
+ - **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
+ - **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.
26
28
  - **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.
27
29
  - 📖 **Reading `.ax` from the shell is a read, and a docs fix does not re-run the whole release suite** *(new in 0.34.0)*: the gate splits shell commands at operators outside quotes and substitutions, judges every command substitution it would run, and knows literal `cd`, `pwd`, `sleep`, `seq`, `pgrep`, clock-reading `date`, `git -C` and `while`/`until` loops — so `grep "a\|b" .ax/…`, `f=$(find .ax/specs …)` or `until grep -q … .ax/…; do sleep 20; done` no longer file an approval request, while every write form is still refused (and `echo "$(sh -c …)"` now is). `sed -i` is judged by the files it edits, not by the words in its script. After a full release lane, `node scripts/verify-release.js --inherit-release-test-lane` lets a commit that changes only `README.md` or unshipped `docs/` files publish on the full lane's receipt by running just the docs tests; the publish check recomputes that diff with git. `requirement_triage` counts a lineage with sub-slices as approved, and an autoreload MCP launcher exits when its client goes away.
28
30
  - 🗜️ **Large answers are compressed, not cut, and new requirements are not blocked by a guess** *(new in 0.33.0)*: `spec_list`, `review_status` and `reverse_scan` answer by default with a compressed view — duplicates removed, digests dropped, what needs action first, anything left out counted with a note — and `detail: "full"` (or paging, or `spec_list({ ids })` for one spec) gives the complete answer. `requirement_triage` confirms a lineage only when both of its channels agree and the lineage mentions every code identifier the request names, so a requirement next to a finished one, or on an install without a semantic layer, can still be admitted. `maintenance_analyze` judges a Korean or Japanese request against unreadable files by its words and, on the cloud tier, by meaning; the pre-edit gate finds the analysis the session persisted; `spec_approve` names a spec's blockers instead of queueing an approval nobody could use; and `holmes-kit autonomy status`/`off` read the project default in `.mcp.json`, so `off` never claims OFF while autonomous approval is still on.
@@ -288,6 +290,9 @@ flowchart LR
288
290
  | `holmes-kit init --agent all` | Non-interactive instant setup for all supported agents |
289
291
  | `holmes-kit init --autonomy` | Opt the project into autonomous spec approval (low-risk only; governance-critical still HITL) |
290
292
  | `holmes-kit init --dry-run` | Preview files and configuration changes without writing |
293
+ | `holmes-kit runtime-binding setup --workspace <root> --package <built-package> --release-package <release-install> --dry-run` | Preview explicit development/release routing; omit `--dry-run` only after reviewing the plan and satisfying its approval request |
294
+ | `holmes-kit runtime-binding status --workspace <root>` | Inspect selected package, build, spec store and wiring conflicts; not proof of active hooks |
295
+ | `holmes-kit doctor --target <root> --registry <bindings.json>` | Diagnose the same operator registry used by custom routing installations |
291
296
  | `holmes-kit autonomy status` | Show the current autonomous-approval posture (project default + session envelope) |
292
297
  | `holmes-kit autonomy on --for 2h` | Self-drive low-risk specs for this session only (expiring; needs a TTY or `HOLMES_APPROVAL`) |
293
298
  | `holmes-kit autonomy off` | End session autonomy immediately; if the project default in `.mcp.json` still keeps autonomy on, it says so and exits 1 instead of claiming OFF |
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 7dd2aa11-muqzdhr1
1
+ 68b21a0e-mutvc7i3
@@ -949,7 +949,7 @@ const WORKER = [
949
949
  ' } else if (m.id === 2 || m.id === 3) {',
950
950
  // Round 10 (measured): a 25 MB hooks file's answer overflowed the parent's 64 MiB pipe buffer (ENOBUFS →
951
951
  // approximate). Only what the verdict reads travels: per entry cwd/errors/warnings, per hook four fields.
952
- " if (m.id === 3 && m.result && Array.isArray(m.result.data)) m.result = { data: m.result.data.map((e) => (e && typeof e === 'object') ? { cwd: e.cwd, errors: e.errors, warnings: e.warnings, hooks: Array.isArray(e.hooks) ? e.hooks.map((h) => (h && typeof h === 'object') ? { eventName: h.eventName, command: h.command, matcher: h.matcher, enabled: h.enabled } : h) : e.hooks } : e) };",
952
+ " if (m.id === 3 && m.result && Array.isArray(m.result.data)) m.result = { data: m.result.data.map((e) => (e && typeof e === 'object') ? { cwd: e.cwd, errors: e.errors, warnings: e.warnings, hooks: Array.isArray(e.hooks) ? e.hooks.map((h) => (h && typeof h === 'object') ? { key: h.key, eventName: h.eventName, command: h.command, matcher: h.matcher, enabled: h.enabled } : h) : e.hooks } : e) };",
953
953
  ' answers[m.id] = m;',
954
954
  ' if (answers[2] && answers[3]) { clearTimeout(timer); finish({ ok: true, config: answers[2], hooks: answers[3] }); }',
955
955
  ' }',
@@ -1226,6 +1226,40 @@ function verdictOf(config, hooks, home, input) {
1226
1226
  }
1227
1227
  const ownProblems = problems.filter(own);
1228
1228
  const otherProblems = problems.filter((m) => !own(m) && m !== otherConfigError && !(configError ?? '').includes(m));
1229
+ // The bytes stay unchanged for Codex's validation. Only the copied hook's identity moved:
1230
+ // consult Codex's effective state at its original key, never match by command (a project
1231
+ // hook can run the same command). This can preserve a disable, never enable a native refusal.
1232
+ const effective = config.result?.config?.hooks?.state;
1233
+ // Codex canonicalizes its home before forming source keys. An alias-only state key must
1234
+ // not suppress a genuinely enabled hook; resolving every spelling and accepting any disable
1235
+ // would hide duplicates. Resolve the directory, not a potentially symlinked hooks file.
1236
+ const originalHooks = (() => {
1237
+ if (!input.realHooksPath)
1238
+ return null;
1239
+ try {
1240
+ return path.join(fs.realpathSync.native(path.dirname(input.realHooksPath)), path.basename(input.realHooksPath));
1241
+ }
1242
+ catch {
1243
+ return null;
1244
+ }
1245
+ })();
1246
+ const enabledInOriginal = (h) => {
1247
+ if (h.enabled === false)
1248
+ return false;
1249
+ if (!originalHooks || typeof h.key !== 'string' || !isTableValue(effective))
1250
+ return true;
1251
+ for (const homePath of homes) {
1252
+ const prefix = path.join(homePath, 'hooks.json') + ':';
1253
+ if (!h.key.startsWith(prefix))
1254
+ continue;
1255
+ const suffix = h.key.slice(prefix.length);
1256
+ if (!/^[a-z_]+:\d+:\d+$/.test(suffix))
1257
+ return true;
1258
+ const state = effective[`${originalHooks}:${suffix}`];
1259
+ return !isTableValue(state) || state.enabled !== false;
1260
+ }
1261
+ return true;
1262
+ };
1229
1263
  return {
1230
1264
  available: true,
1231
1265
  configError: configError === null ? null : toUser(configError),
@@ -1236,7 +1270,7 @@ function verdictOf(config, hooks, home, input) {
1236
1270
  event: String(h.eventName ?? ''),
1237
1271
  ...(typeof h.command === 'string' ? { command: h.command } : {}),
1238
1272
  matcher: typeof h.matcher === 'string' ? h.matcher : null,
1239
- enabled: h.enabled !== false,
1273
+ enabled: enabledInOriginal(h),
1240
1274
  })),
1241
1275
  ...(otherProblems.length > 0 ? { otherHookProblems: otherProblems } : {}),
1242
1276
  ...(otherHolmesServers.length > 0 ? { otherHolmesServers } : {}),
@@ -21,7 +21,20 @@ export declare function resolvesToPackage(filePath: string, packageRoot: string)
21
21
  import type { Check, Level } from './doctor-check';
22
22
  export type { Check, Level } from './doctor-check';
23
23
  import type { Agent } from './agents';
24
+ import type { RuntimeHarness, RuntimeEntry } from '../runtime/binding';
25
+ interface RoutedDoctorContext {
26
+ mcp: (harness: string, entry: {
27
+ command?: unknown;
28
+ args?: unknown;
29
+ } | null | undefined) => boolean;
30
+ command: (harness: RuntimeHarness, entry: RuntimeEntry) => string;
31
+ script: (harness: RuntimeHarness, entry: RuntimeEntry) => string;
32
+ }
24
33
  export interface DoctorOptions {
34
+ /** Explicit operator registry for isolated installation diagnostics. */
35
+ runtimeRegistryPath?: string;
36
+ /** Isolated native Claude settings home for integration diagnostics. */
37
+ claudeHome?: string;
25
38
  run?: ProbeRunner;
26
39
  autoFix?: boolean;
27
40
  agent?: Agent;
@@ -293,7 +306,7 @@ export declare function probeContext(target: string): {
293
306
  ownInside: boolean;
294
307
  keep: (entry: string) => boolean;
295
308
  };
296
- export declare function wiringHandshakeChecks(target: string, codexConfigPath?: string, packageRoot?: string): Promise<Check[]>;
309
+ export declare function wiringHandshakeChecks(target: string, codexConfigPath?: string, packageRoot?: string, routed?: RoutedDoctorContext): Promise<Check[]>;
297
310
  /**
298
311
  * @implements A-SPEC-476
299
312
  * The semantic tier's doctor verdict, pure so the three states are unit-testable offline.