@holmes-lab/holmes-kit 0.35.24 → 0.36.0

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 (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +34 -4
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
@@ -40,6 +40,7 @@ exports.readCodexConfigBytes = readCodexConfigBytes;
40
40
  exports.codexConfigLoadProblem = codexConfigLoadProblem;
41
41
  exports.codexConfigWriteProblem = codexConfigWriteProblem;
42
42
  exports.defaultCodexConfigPath = defaultCodexConfigPath;
43
+ exports.tomlStr = tomlStr;
43
44
  exports.codexMcpBlock = codexMcpBlock;
44
45
  exports.mergeCodexToml = mergeCodexToml;
45
46
  exports.removeCodexToml = removeCodexToml;
@@ -49,7 +50,7 @@ exports.mentionsHolmes = mentionsHolmes;
49
50
  exports.unownedHolmesShape = unownedHolmesShape;
50
51
  exports.readCodexFixedSpecs = readCodexFixedSpecs;
51
52
  exports.invalidTomlEscape = invalidTomlEscape;
52
- // @implements A-SPEC-733, A-SPEC-731, A-SPEC-721
53
+ // @implements A-SPEC-733, A-SPEC-731, A-SPEC-721, A-SPEC-769.22
53
54
  // @implements A-SPEC-266
54
55
  // Codex reads default MCP servers from `$CODEX_HOME/config.toml` (normally
55
56
  // `~/.codex/config.toml`), not from a repository-local `.codex/config.toml`. This module owns only
@@ -210,6 +210,17 @@ export declare function wiringSpawnCheck(command: string, args: string[], timeou
210
210
  * over as it was, the server's supervisor (`HOLMES_MCP_AUTORELOAD=1`) started the `node` the workspace had put on PATH.
211
211
  */
212
212
  export declare function mcpProbeEnv(env: NodeJS.ProcessEnv, target: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
213
+ /**
214
+ * @implements A-SPEC-182.3 — approved specs whose ancestor chain (direct parents included) holds a spec that is not
215
+ * approved: a WARN with the count and the ancestors that hold most of them, or null on a clean store. Measured here on
216
+ * 2026-10-18: 28 (REQ-102 13, REQ-125 11, H-SPEC-100 4).
217
+ */
218
+ export declare function sealedUnderUnsealedAncestorCheck(target: string): Check | null;
219
+ /**
220
+ * @implements A-SPEC-781.2 — how the run stage machine in `ax.config.json` was read: a WARN naming the fallback or the
221
+ * deny entries filled in, or null when it was read as written (no line, so a clean project's doctor is unchanged).
222
+ */
223
+ export declare function stageMachineCheck(target: string): Check | null;
213
224
  /**
214
225
  * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
215
226
  * AND has git. Absence or a hook without our signature is a WARN carrying the install command —
@@ -255,6 +266,12 @@ export type CodexGateReading = {
255
266
  * beside a Codex-only report read as Codex's activation.
256
267
  */
257
268
  export declare function activationText(observed: string[], agent?: string): string;
269
+ /**
270
+ * @implements A-SPEC-770.3 — the nearest ancestor node_modules copy of holmes-kit, which the bare npx command run from the
271
+ * target (or below) resolves before any global install. Field incident 2026-10-17: ~/node_modules held 0.19.3 and a
272
+ * 0.35.23 refusal's own grant hint answered "no pending request matches". No copy: no row.
273
+ */
274
+ export declare function npxResolutionCheck(target: string, runningVersion: string): Check | null;
258
275
  export declare function hookObservationChecks(targetIn: string, now?: number, agent?: Agent): Check[];
259
276
  /**
260
277
  * Codex runs the Holmes PreToolUse gate here but no Holmes Stop gate: Codex sessions end without the constitution
@@ -300,6 +317,15 @@ export declare function formatChecks(checks: Check[]): string;
300
317
  * target is told that the shared file lacks a Holmes entry.
301
318
  */
302
319
  export declare function codexWiredTarget(target: string): boolean;
320
+ /** The Holmes wirings of the three harnesses, read the way the handshake reads them (nothing is started). */
321
+ export declare function holmesWirings(target: string, codexConfigPath: string): Array<{
322
+ label: string;
323
+ file: string;
324
+ entry: {
325
+ command: string;
326
+ args: string[];
327
+ } | null;
328
+ }>;
303
329
  /**
304
330
  * @implements A-SPEC-251.2 (0.31.0) — each harness whose Holmes wiring runs npx gets a WARN: npx runs npm in every
305
331
  * session workspace, and that workspace's .npmrc (node-options, registry) and node_modules replaced the server
@@ -367,8 +393,12 @@ export declare function wiringHandshakeChecks(target: string, codexConfigPath?:
367
393
  * user decides the trade with numbers rather than adjectives.
368
394
  */
369
395
  export declare function semanticCoverageCheck(root: string, tier: SemanticTier): Check | null;
396
+ /**
397
+ * @implements A-SPEC-476.1 — the tier row names the project's cap: a key it withheld (by source, never the value) and the
398
+ * cap that applied; a cap that could not be read is FAIL, because the tier is none until it is fixed.
399
+ */
370
400
  export declare function semanticTierVerdict(t: SemanticTier): {
371
- level: 'PASS' | 'WARN';
401
+ level: 'PASS' | 'WARN' | 'FAIL';
372
402
  detail: string;
373
403
  fix?: string;
374
404
  };
@@ -51,15 +51,19 @@ exports.resetWiringSpawns = resetWiringSpawns;
51
51
  exports.wiringSpawnShared = wiringSpawnShared;
52
52
  exports.wiringSpawnCheck = wiringSpawnCheck;
53
53
  exports.mcpProbeEnv = mcpProbeEnv;
54
+ exports.sealedUnderUnsealedAncestorCheck = sealedUnderUnsealedAncestorCheck;
55
+ exports.stageMachineCheck = stageMachineCheck;
54
56
  exports.pushGateCheck = pushGateCheck;
55
57
  exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
56
58
  exports.activationText = activationText;
59
+ exports.npxResolutionCheck = npxResolutionCheck;
57
60
  exports.hookObservationChecks = hookObservationChecks;
58
61
  exports.codexStopGateCheck = codexStopGateCheck;
59
62
  exports.ciMatrixCheck = ciMatrixCheck;
60
63
  exports.checksJson = checksJson;
61
64
  exports.formatChecks = formatChecks;
62
65
  exports.codexWiredTarget = codexWiredTarget;
66
+ exports.holmesWirings = holmesWirings;
63
67
  exports.wiringLauncherChecks = wiringLauncherChecks;
64
68
  exports.wiringVersionChecks = wiringVersionChecks;
65
69
  exports.harnessClause = harnessClause;
@@ -71,7 +75,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
71
75
  exports.semanticCoverageCheck = semanticCoverageCheck;
72
76
  exports.semanticTierVerdict = semanticTierVerdict;
73
77
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
74
- // @implements A-SPEC-751.4, A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
78
+ // @implements A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
75
79
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
76
80
  const doctor_guidance_1 = require("./doctor-guidance");
77
81
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -87,11 +91,13 @@ const npx_bin_1 = require("../project/npx-bin");
87
91
  const install_scripts_policy_1 = require("../project/install-scripts-policy");
88
92
  const native_deps_1 = require("./native-deps");
89
93
  const tier_1 = require("../semantic/tier");
94
+ const cloud_usage_1 = require("../semantic/cloud-usage");
90
95
  const probe_process_1 = require("./probe-process");
91
96
  const npx_cache_check_1 = require("./npx-cache-check");
92
97
  const ci_runs_1 = require("../project/ci-runs");
93
98
  const vector_coverage_1 = require("../semantic/vector-coverage");
94
99
  const path = __importStar(require("node:path"));
100
+ const config_1 = require("../config/config");
95
101
  const role_policy_1 = require("../governance/role-policy");
96
102
  const blind_spots_1 = require("../guardrail/blind-spots");
97
103
  const node_child_process_1 = require("node:child_process");
@@ -908,6 +914,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
908
914
  checks.push(...wiringVersionChecks(target, opts?.codexConfigPath, cli));
909
915
  }
910
916
  }
917
+ // @implements A-SPEC-770.3 — the copy the bare npx command would run from the target, when it is not this install.
918
+ {
919
+ const cli = (0, mcp_launcher_1.readPackageVersion)(packageRoot);
920
+ const row = cli ? npxResolutionCheck(target ?? process.cwd(), cli) : null;
921
+ if (row)
922
+ checks.push(row);
923
+ }
911
924
  // 7. Target wiring — do the configured commands point at THIS installed package and exist?
912
925
  if (target) {
913
926
  // @implements A-SPEC-190 §13 (round 11) — `init --settings project` wires `.claude/settings.json`,
@@ -1169,9 +1182,40 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1169
1182
  // operators that doctor's failures are noise, which costs more than this check is worth.
1170
1183
  if (target) {
1171
1184
  const rs = (0, role_policy_1.rolePolicyStatus)(target);
1172
- add('role policy', 'PASS', rs.state === 'absent' ? 'not configured (optional)'
1173
- : rs.state === 'inactive' ? 'guidance present, no policy — roles are off (see .ax/roles/README.md)'
1174
- : `active — ${rs.roles.length} role(s): ${rs.roles.join(', ')}; default=${rs.default ?? '(none — unspecified is refused)'}`);
1185
+ // @implements A-SPEC-774.8 — a broad default is refused in a run; interactively it is a warning with the migration.
1186
+ // @implements A-SPEC-774.15 — an unreadable policy refuses every action; a role defined twice is refused in a run.
1187
+ if (rs.loadIssue)
1188
+ add('role policy', 'WARN', `${rs.loadIssue}. Every role-checked action is refused until it can be read.`);
1189
+ else if (rs.duplicates?.length)
1190
+ add('role policy', 'WARN', `role(s) defined in more than one file under .ax/roles: ${rs.duplicates.join(', ')}. The later definition holds interactively; an orchestrated run refuses them. Define each role once.`);
1191
+ else if (rs.defaultIssue)
1192
+ add('role policy', 'WARN', `${rs.defaultIssue}. In an orchestrated run this policy is refused; interactive sessions are unaffected.`);
1193
+ // @implements A-SPEC-774.22 — a stages declaration that cannot be read: ignored interactively, refused in a run.
1194
+ else if (rs.malformedStages?.length)
1195
+ add('role policy', 'WARN', `role(s) whose stages cannot be read: ${rs.malformedStages.join(', ')} — interactive sessions ignore them; an orchestrated run refuses them in every stage. Write stages as a list of stage names.`);
1196
+ else
1197
+ add('role policy', 'PASS', rs.state === 'absent' ? 'not configured (optional)'
1198
+ : rs.state === 'inactive' ? 'guidance present, no policy — roles are off (see .ax/roles/README.md)'
1199
+ : `active — ${rs.roles.length} role(s): ${rs.roles.join(', ')}; default=${rs.default ?? '(none — unspecified is refused)'}`);
1200
+ // @implements A-SPEC-781.2 — a stage machine not read as written is named, never replaced silently.
1201
+ const sm = stageMachineCheck(target);
1202
+ if (sm)
1203
+ checks.push(sm);
1204
+ }
1205
+ // @implements A-SPEC-532.6 — the owner's ceiling on automatic approval; a value the loader could not read is `off`.
1206
+ if (target) {
1207
+ let raw;
1208
+ try {
1209
+ raw = JSON.parse(fs.readFileSync(path.join(target, 'ax.config.json'), 'utf8')).autonomy?.ceiling;
1210
+ }
1211
+ catch {
1212
+ raw = undefined;
1213
+ }
1214
+ const ceiling = (0, config_1.loadConfig)(target).autonomy.ceiling;
1215
+ if (raw !== undefined && raw !== ceiling)
1216
+ add('autonomy ceiling', 'WARN', `ax.config.json autonomy.ceiling ${JSON.stringify(raw)} is not one of off, tests, no-gate, default — read as "off": no seal is automatic until it is corrected`);
1217
+ else
1218
+ add('autonomy ceiling', 'PASS', ceiling === 'default' ? 'default — the grader decides which seals are automatic' : `"${ceiling}" — automatic seals above it are the operator's`);
1175
1219
  }
1176
1220
  // @implements A-SPEC-165
1177
1221
  // The boundary, told to the user rather than left in a document nobody opens. PASS, not FAIL: a
@@ -1206,6 +1250,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1206
1250
  : `${orphaned.length} approved spec(s) with a non-approved parent: ${orphaned.map((s) => s.id).slice(0, 5).join(', ')}`);
1207
1251
  }
1208
1252
  catch { /* an unreadable corpus is doctor's other checks' business, not this one's */ }
1253
+ // @implements A-SPEC-182.3 — the whole chain, not only the direct parents: named, never silent.
1254
+ try {
1255
+ const anc = sealedUnderUnsealedAncestorCheck(target);
1256
+ if (anc)
1257
+ checks.push(anc);
1258
+ }
1259
+ catch { /* as above */ }
1209
1260
  // @implements A-SPEC-254.1
1210
1261
  // Distributed id preemption (the 2026-08-23 REQ-220 incident): two offline workspaces issue the
1211
1262
  // same number, silent at create and at push. Judgment lives in the ONE pure detector; identity is
@@ -1701,13 +1752,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1701
1752
  issues.push(`${file}: hooks are disabled`);
1702
1753
  for (const g of ours.PreToolUse ?? [])
1703
1754
  for (const hook of g.hooks ?? []) {
1704
- if (hook.command === routed.command('antigravity', 'pre-tool-use')) {
1755
+ if ((0, runtime_binding_1.sameAgyCommand)(hook.command, routed.command('antigravity', 'pre-tool-use'))) { // A-SPEC-751.9
1705
1756
  pres++;
1706
1757
  if (g.matcher !== '*')
1707
1758
  issues.push(`${file}: PreToolUse matcher must be *`);
1708
1759
  }
1709
1760
  }
1710
- stops += (ours.Stop ?? []).filter((h2) => h2.command === routed.command('antigravity', 'stop')).length;
1761
+ stops += (ours.Stop ?? []).filter((h2) => (0, runtime_binding_1.sameAgyCommand)(h2.command, routed.command('antigravity', 'stop'))).length; // A-SPEC-751.9
1711
1762
  }
1712
1763
  if (pres !== 1 || (stops !== 1 && !(emptyStop && stops === 0)))
1713
1764
  issues.push('expected exactly one registered PreToolUse and Stop across Antigravity sources');
@@ -2335,9 +2386,11 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
2335
2386
  add('global prefix', verdict.level, verdict.detail, verdict.fix);
2336
2387
  }
2337
2388
  {
2338
- const t = (0, tier_1.resolveSemanticTier)();
2389
+ const t = (0, tier_1.resolveProjectSemanticTier)(target ?? process.cwd()); // @implements A-SPEC-476.1
2339
2390
  const v = semanticTierVerdict(t);
2340
2391
  add('semantic tier', v.level, v.detail, v.fix);
2392
+ // @implements A-SPEC-476.5 — what this project actually sent to the cloud embedder, by day (every tier, so a cap shows 0).
2393
+ add('cloud embedding usage', 'PASS', (0, cloud_usage_1.cloudUsageLine)((0, cloud_usage_1.cloudUsageSummary)(target ?? process.cwd())));
2341
2394
  // @implements A-SPEC-682 — the tier line says what is CONFIGURED. Measured 2026-09-19 on this
2342
2395
  // repository, the configured tier was cloud while 0 of 602 scanned files had a cached document
2343
2396
  // vector under it, so every lookup returned nothing and both semantic surfaces were inert —
@@ -2683,6 +2736,85 @@ function mcpHandshakeCheck(packageRoot, target, timeoutMs = 15000) {
2683
2736
  send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } });
2684
2737
  });
2685
2738
  }
2739
+ /**
2740
+ * @implements A-SPEC-182.3 — approved specs whose ancestor chain (direct parents included) holds a spec that is not
2741
+ * approved: a WARN with the count and the ancestors that hold most of them, or null on a clean store. Measured here on
2742
+ * 2026-10-18: 28 (REQ-102 13, REQ-125 11, H-SPEC-100 4).
2743
+ */
2744
+ function sealedUnderUnsealedAncestorCheck(target) {
2745
+ const { parseSpec } = require('../spec/spec-parser');
2746
+ const byId = new Map();
2747
+ const walk = (dir, depth) => {
2748
+ if (depth > 6)
2749
+ return;
2750
+ let entries;
2751
+ try {
2752
+ entries = fs.readdirSync(dir, { withFileTypes: true });
2753
+ }
2754
+ catch {
2755
+ return;
2756
+ }
2757
+ for (const e of entries) {
2758
+ const p = path.join(dir, e.name);
2759
+ if (e.isDirectory())
2760
+ walk(p, depth + 1);
2761
+ else if (e.isFile() && e.name.endsWith('.md')) {
2762
+ try {
2763
+ const s = parseSpec(fs.readFileSync(p, 'utf8'));
2764
+ if (s.id)
2765
+ byId.set(s.id, s);
2766
+ }
2767
+ catch { /* unreadable: other checks */ }
2768
+ }
2769
+ }
2770
+ };
2771
+ walk(path.join(target, '.ax', 'specs'), 0);
2772
+ const holders = new Map();
2773
+ let count = 0;
2774
+ for (const s of byId.values()) {
2775
+ if (s.status !== 'approved')
2776
+ continue;
2777
+ const bad = new Set();
2778
+ const seen = new Set([s.id]);
2779
+ const up = (id, depth) => {
2780
+ if (depth > 16 || seen.has(id))
2781
+ return;
2782
+ seen.add(id);
2783
+ const a = byId.get(id);
2784
+ // @implements A-SPEC-182.4 — an ancestor no spec carries holds the chain up as an unapproved one does.
2785
+ if (!a) {
2786
+ bad.add(`${id} (missing)`);
2787
+ return;
2788
+ }
2789
+ if (a.status !== 'approved')
2790
+ bad.add(`${a.id} (${a.status})`);
2791
+ for (const d of a.dependsOn ?? [])
2792
+ up(d, depth + 1);
2793
+ };
2794
+ for (const d of s.dependsOn ?? [])
2795
+ up(d, 1);
2796
+ if (bad.size > 0) {
2797
+ count++;
2798
+ for (const b of bad)
2799
+ holders.set(b, (holders.get(b) ?? 0) + 1);
2800
+ }
2801
+ }
2802
+ if (count === 0)
2803
+ return null;
2804
+ const top = [...holders.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([k, v]) => `${k}: ${v}`).join(', ');
2805
+ return { name: 'sealed under unsealed ancestor', level: 'WARN',
2806
+ detail: `${count} approved spec(s) sit under an ancestor that is not approved — ${top}. A run or classification.strict refuses such a seal; seal the ancestor to restore the chain.` };
2807
+ }
2808
+ /**
2809
+ * @implements A-SPEC-781.2 — how the run stage machine in `ax.config.json` was read: a WARN naming the fallback or the
2810
+ * deny entries filled in, or null when it was read as written (no line, so a clean project's doctor is unchanged).
2811
+ */
2812
+ function stageMachineCheck(target) {
2813
+ const notes = (0, config_1.loadConfig)(target).stages.notes;
2814
+ if (notes.length === 0)
2815
+ return null;
2816
+ return { name: 'stage machine', level: 'WARN', detail: `${notes.join('; ')}. Orchestrated runs use the machine as read; interactive sessions are unaffected.` };
2817
+ }
2686
2818
  // @implements A-SPEC-509.1
2687
2819
  /**
2688
2820
  * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
@@ -2984,6 +3116,49 @@ function activationText(observed, agent) {
2984
3116
  return `live activation observed (${agent})`;
2985
3117
  return `live activation unverified for ${agent}${observed.length ? ` (observed: ${observed.join(', ')})` : ''}`;
2986
3118
  }
3119
+ /**
3120
+ * @implements A-SPEC-770.3 — the nearest ancestor node_modules copy of holmes-kit, which the bare npx command run from the
3121
+ * target (or below) resolves before any global install. Field incident 2026-10-17: ~/node_modules held 0.19.3 and a
3122
+ * 0.35.23 refusal's own grant hint answered "no pending request matches". No copy: no row.
3123
+ */
3124
+ function npxResolutionCheck(target, runningVersion) {
3125
+ // @implements A-SPEC-770.6 — what npx resolves: the first node_modules/.bin/holmes-kit link from the target up (round
3126
+ // 1: a pnpm link and an unscoped package were run by npx and missed here). The command is spelled via npxBin().
3127
+ const { shadowCopy, runningCli, powershellLiteral, posixLiteral, binEntryNames } = require('../project/npx-bin');
3128
+ const shadowed = `${(0, npx_bin_1.npxBin)()} holmes-kit`;
3129
+ const shadow = shadowCopy(target);
3130
+ if (shadow === null) {
3131
+ // @implements A-SPEC-770.7 — PASS only when npx would take a file entry here and it is this install; a dangling link
3132
+ // or a directory is skipped by npx, so it gives no row (round 2: a dangling link read as PASS).
3133
+ for (let dir = path.resolve(target);; dir = path.dirname(dir)) {
3134
+ // @implements A-SPEC-770.9 — the platform's entry names, as shadowCopy reads them (round 4: .cmd PASS on POSIX).
3135
+ if (binEntryNames().some((n) => { try {
3136
+ return fs.statSync(path.join(dir, 'node_modules', '.bin', n)).isFile();
3137
+ }
3138
+ catch {
3139
+ return false;
3140
+ } })) {
3141
+ return { name: 'npx resolution', level: 'PASS', detail: `${shadowed} from ${target} runs this install (${runningCli()})` };
3142
+ }
3143
+ if (path.dirname(dir) === dir)
3144
+ return null;
3145
+ }
3146
+ }
3147
+ // @implements A-SPEC-770.7 — the fix names the package directory itself, quoted for this platform, and never a
3148
+ // node_modules directory (round 2: a shim made it `rm -r <project>/node_modules`).
3149
+ const q = process.platform === 'win32' ? powershellLiteral : posixLiteral;
3150
+ const removable = shadow.packageDir !== null && path.basename(shadow.packageDir) !== 'node_modules';
3151
+ // @implements A-SPEC-770.10 — npx runs the project's OWN bin here (a holmes-kit checkout or fork): nothing to remove.
3152
+ if (path.basename(shadow.link) === 'package.json' && shadow.packageDir === null) {
3153
+ return { name: 'npx resolution', level: 'WARN',
3154
+ detail: `npx run here starts this project's own bin.holmes-kit (${shadow.version || 'unknown version'}), not this install (${runningVersion}) — expected in a holmes-kit checkout; approval hints name this install's own path` };
3155
+ }
3156
+ return { name: 'npx resolution', level: 'WARN',
3157
+ detail: `${shadowed} from ${target} or below runs ${shadow.link}${shadow.packageDir ? ` (${shadow.packageDir})` : ''} ${shadow.version || '(unknown version)'}, not this install (${runningVersion}); approval hints there name this install's own path so they reach it`,
3158
+ fix: removable
3159
+ ? `Remove that copy (rm -r ${q(shadow.packageDir)} and the link ${q(shadow.link)}) or update it to ${runningVersion}.`
3160
+ : `Update or remove the holmes-kit install that provides ${q(shadow.link)}.` };
3161
+ }
2987
3162
  /** @implements A-SPEC-772.11 — the workspace a target belongs to (a subdirectory reads its project's records). */
2988
3163
  function governedRootOf(target) {
2989
3164
  try {
@@ -3145,6 +3320,7 @@ function codexWiredTarget(target) {
3145
3320
  || fs.existsSync(path.join(target, '.codex', 'mcp_config.json'));
3146
3321
  }
3147
3322
  /** The Holmes wirings of the three harnesses, read the way the handshake reads them (nothing is started). */
3323
+ // @implements A-SPEC-774.18 — exported: run start reads the same wirings to pin the MCP version of a run.
3148
3324
  function holmesWirings(target, codexConfigPath) {
3149
3325
  const wirings = [
3150
3326
  {
@@ -3782,7 +3958,28 @@ function semanticCoverageCheck(root, tier) {
3782
3958
  return unjudgeable();
3783
3959
  }
3784
3960
  }
3961
+ /**
3962
+ * @implements A-SPEC-476.1 — the tier row names the project's cap: a key it withheld (by source, never the value) and the
3963
+ * cap that applied; a cap that could not be read is FAIL, because the tier is none until it is fixed.
3964
+ */
3785
3965
  function semanticTierVerdict(t) {
3966
+ if (t.cap?.problem) {
3967
+ return {
3968
+ level: 'FAIL',
3969
+ detail: `semantic.maxTier in ax.config.json could not be read (${t.cap.problem}) — the semantic tier is none until it is fixed.`,
3970
+ fix: 'Set semantic.maxTier to "cloud", "local" or "none" in ax.config.json, or remove the key for no cap.',
3971
+ };
3972
+ }
3973
+ const v = uncappedTierVerdict(t);
3974
+ if (!t.cap)
3975
+ return v;
3976
+ const key = t.cap.keyWithheld === undefined ? 'no key' : `key present (${KEY_SOURCE_LABEL[t.cap.keyWithheld]})`;
3977
+ return { ...v, detail: `${v.detail} [${key}, project cap ${t.cap.maxTier} (ax.config.json semantic.maxTier)]` };
3978
+ }
3979
+ const KEY_SOURCE_LABEL = {
3980
+ 'env': 'HOLMES_SEMANTIC_API_KEY', 'env-compat': 'GEMINI_API_KEY', 'keychain': 'macOS keychain', 'file': '~/.holmes/credentials.json',
3981
+ };
3982
+ function uncappedTierVerdict(t) {
3786
3983
  if (t.tier === 'cloud') {
3787
3984
  // @implements A-SPEC-477 — the SOURCE of the consent is shown (env/keychain/file); the value
3788
3985
  // never is. Consent must be able to see what it consented to, and where it lives.
@@ -37,7 +37,7 @@ exports.isBrokenPipe = void 0;
37
37
  exports.packageRoot = packageRoot;
38
38
  exports.main = main;
39
39
  exports.installPipeGuard = installPipeGuard;
40
- // @implements A-SPEC-704, A-SPEC-709, A-SPEC-734, A-SPEC-751, A-SPEC-752, A-SPEC-772.4
40
+ // @implements A-SPEC-704, A-SPEC-773, A-SPEC-770.11,A-SPEC-709, A-SPEC-734,A-SPEC-751, A-SPEC-752, A-SPEC-772.4, A-SPEC-779, A-SPEC-102.2, A-SPEC-774.20, A-SPEC-102.7, A-SPEC-779.2
41
41
  // @implements A-SPEC-549.2
42
42
  // @implements A-SPEC-591, A-SPEC-626
43
43
  const cli_execution_1 = require("./cli-execution");
@@ -85,10 +85,16 @@ const KNOWN_FLAGS = {
85
85
  doctor: ['help', 'target', 'json', 'agent', 'registry'],
86
86
  // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
87
87
  attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
88
+ // @implements A-SPEC-773 — the Holmes scratch root an agent may clean up on its own.
89
+ scratch: ['help', 'new'],
90
+ // @implements A-SPEC-774.10 — the role policy rewritten into the new vocabulary with equal verdicts.
91
+ roles: ['help', 'target', 'dry-run'],
92
+ run: ['help', 'target', 'worktree', 'engine', 'engine-arg', 'id', 'key', 'scope', 'to', 'why', 'accept-unknown-versions'], // @implements A-SPEC-774.17, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20
93
+ review: ['help', 'target', 'base', 'head', 'verdict', 'finding', 'engine', 'model', 'session', 'strict', 'solid'], // @implements A-SPEC-102.2, A-SPEC-102.7
88
94
  skills: ['help', 'target'],
89
95
  ci: ['help', 'target', 'specs-dir', 'json'],
90
96
  serve: ['help', 'target', 'port'],
91
- approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'], // A-SPEC-649: --revoke · A-SPEC-650: --status
97
+ approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'withdraw', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'], // A-SPEC-649: --revoke · A-SPEC-650: --status · A-SPEC-779.2: --withdraw
92
98
  ledger: ['help', 'target', 'ref', 'dry-run'],
93
99
  // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
94
100
  'semantic-key': ['help'],
@@ -116,6 +122,7 @@ const APPROVE_USAGE = `holmes-kit approve — decide pending approval requests (
116
122
  --deny <id> --reason <text> deny — the reason rides the agent's next refusal
117
123
  --ask <id> --question <text> leave a question and hold — the agent relays it to the user
118
124
  --revoke <id> --reason <text> withdraw a live grant — the request must be decided again
125
+ --withdraw <ref> --reason <text> the run that filed a request closes it (recorded as withdrawn, not denied)
119
126
  --target <dir> project root (default: current directory)
120
127
  `;
121
128
  class UnknownFlagError extends Error {
@@ -128,9 +135,12 @@ class UnknownFlagError extends Error {
128
135
  */
129
136
  // A-SPEC-251.1 (round 26): `yes` — `upgrade --yes` was refused as "--yes requires a value", so the non-interactive
130
137
  // upgrade its own guidance names could not run (measured).
138
+ // A-SPEC-774.24: --accept-unknown-versions names its fields, so it is a value flag, not one of these.
131
139
  const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy', 'yes']); // A-SPEC-650: --status
140
+ /** @implements A-SPEC-770.11 — value flags whose value may be omitted; the handler supplies the default. */
141
+ const OPTIONAL_VALUE_FLAGS = new Set(['refusals']);
132
142
  /** @implements A-SPEC-771.1 — value flags that may be given more than once. */
133
- const REPEATABLE_FLAGS = new Set(['limit']);
143
+ const REPEATABLE_FLAGS = new Set(['limit', 'engine-arg', 'finding', 'scope']); // @implements A-SPEC-774.17 — one engine argument per flag; A-SPEC-102.2 — one finding id per flag
134
144
  function parseFlags(argv, known) {
135
145
  const flags = {};
136
146
  const positionals = [];
@@ -247,9 +257,32 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
247
257
  --deny <ref> --reason <text> record a denial the agent will see
248
258
  --ask <ref> --question <text> hold with a question the agent relays
249
259
  --revoke <id> --reason <text> withdraw a live grant (full id or unique prefix)
260
+ --withdraw <ref> --reason <text> the filing run closes its own request (recorded withdrawn)
250
261
  <ref> list index (1,2,…), full id, or a unique id prefix
251
262
  --target <dir> project root (default: cwd)
252
263
 
264
+ holmes-kit run start|status|stop open, list and end an orchestrated run (JSON on stdout)
265
+ start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]… [--scope <A-SPEC-id>]…
266
+ [--accept-unknown-versions <field,...>]
267
+ checks the worktree would be governed (specs, MCP, gate hook, no
268
+ gate-off argument, every version and build readable), writes the run
269
+ record, prints the headless command, HOLMES_RUN_ID and a one-time stop
270
+ key; exit 3 if refused. --accept-unknown-versions hook,mcp starts
271
+ despite those unreadable fields only, and records them; fields a
272
+ harness cannot read by design (agy: hook, hook_build) are exempt
273
+ stop --id <run_id> --key <stop_key> end the run (only the holder of the key can)
274
+ transition --id <run_id> --to <stage> --key <stop_key> [--why <text>]
275
+ move the run along its stage machine (ax.config.json stages);
276
+ test and done need an independent passing review; exit 3 if refused
277
+
278
+ holmes-kit review record|status|gate review verdicts bound to a base and head (JSON on stdout)
279
+ record --base <rev> --head <rev> --verdict pass|fail [--finding <id>]… [--engine e] [--model m]
280
+ refuses a self-review (the run that wrote the head) and a role
281
+ without RECORD_REVIEW; the ledger lives in the main checkout
282
+ gate --base <rev> --head <rev> [--strict] exit 1 unless an independent pass covers the range
283
+ and no open critical (with --strict, important) finding remains
284
+ mrp --base <rev> --head <rev> the merge-ready package: spec chain, test evidence, verdict, missing
285
+
253
286
  holmes-kit autonomy status|on|off|delegate|revoke-delegation grant/end autonomous spec approval
254
287
  delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]
255
288
  run delegation for THIS workspace: hitl specs whose only reason is a
@@ -273,6 +306,9 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
273
306
  --target <dir> also verify that target's wiring points at this install
274
307
  --json machine-readable output
275
308
 
309
+ holmes-kit scratch [--new <label>]
310
+ print the Holmes scratch root, or make a fresh directory under it; the gate lets
311
+ an agent rm -rf such a directory by its absolute path in every harness
276
312
  holmes-kit attest [flags] say how many source files trace to an APPROVED spec (a statement, not a gate)
277
313
  --target <dir> the project to measure (default: current directory)
278
314
  --exclude <a,b> path prefixes that are not this project's source (vendored trees); echoed in the output
@@ -322,6 +358,10 @@ async function main(argv) {
322
358
  for (const [key, v] of Object.entries(flags)) {
323
359
  // `--target` (true) AND `--target=` ('') both point at nothing — an empty inline value
324
360
  // resolved to CWD and wired it silently (round-5 HIGH).
361
+ // @implements A-SPEC-770.11 — an optional-value flag defaults where it is read (`--refusals` → 20 rows): the
362
+ // `approve --refusals --target <root>` every refusal prints exited 2 here (measured 2026-10-17).
363
+ if (OPTIONAL_VALUE_FLAGS.has(key) && v === true)
364
+ continue;
325
365
  if (!BOOLEAN_FLAGS.has(key) && (v === true || (typeof v === 'string' && v.trim() === ''))) {
326
366
  process.stderr.write(`--${key} requires a value\n\n${USAGE}`);
327
367
  return 2;
@@ -331,7 +371,10 @@ async function main(argv) {
331
371
  // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
332
372
  const expected = cmd === 'runtime-binding' ? ['setup', 'status', 'remove'] : cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
333
373
  : cmd === 'semantic-key' ? ['set', 'unset', 'status']
334
- : cmd === 'autonomy' ? ['status', 'on', 'off', 'delegate', 'revoke-delegation'] : []; // @implements A-SPEC-771.1
374
+ : cmd === 'autonomy' ? ['status', 'on', 'off', 'delegate', 'revoke-delegation'] // @implements A-SPEC-771.1
375
+ : cmd === 'roles' ? ['migrate'] // @implements A-SPEC-774.10
376
+ : cmd === 'run' ? ['start', 'status', 'stop', 'transition'] // @implements A-SPEC-774.17, A-SPEC-781
377
+ : cmd === 'review' ? ['record', 'status', 'gate', 'mrp'] : []; // @implements A-SPEC-102.2, A-SPEC-102.6
335
378
  const unexpected = positionals.filter((p) => !expected.includes(p));
336
379
  if (unexpected.length > 0) {
337
380
  const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
@@ -466,6 +509,48 @@ async function main(argv) {
466
509
  }
467
510
  // @implements A-SPEC-702 — reads one scan and the spec store; writes only the badge and the README's
468
511
  // marker region, and only when asked. The numbers never change the exit code.
512
+ // @implements A-SPEC-773
513
+ // @implements A-SPEC-774.10
514
+ // @implements A-SPEC-774.17 — open, list and end an orchestrated run (the record A-SPEC-774.9's run mode reads).
515
+ if (cmd === 'run') {
516
+ const { runRun, parseAcceptedVersions } = require('./run');
517
+ const str = (k) => (typeof flags[k] === 'string' ? flags[k] : undefined);
518
+ // @implements A-SPEC-774.24 — the accepted unreadable fields, by name; an empty or unknown name is refused.
519
+ const acceptText = str('accept-unknown-versions');
520
+ const acceptParsed = acceptText === undefined ? null : parseAcceptedVersions(acceptText);
521
+ if (acceptParsed !== null && 'refusal' in acceptParsed) {
522
+ process.stderr.write(`✗ ${acceptParsed.refusal}\n`);
523
+ return 2;
524
+ }
525
+ return runRun(positionals[0], {
526
+ target: str('target') ? path.resolve(str('target')) : undefined, worktree: str('worktree'), engine: str('engine'),
527
+ engineArgs: str('engine-arg')?.split('\n'), id: str('id'), key: str('key'), scope: str('scope')?.split('\n'), to: str('to'), why: str('why'),
528
+ // @implements A-SPEC-774.20 — start despite unreadable versions; run start records which.
529
+ ...(acceptParsed !== null ? { acceptUnknownVersions: acceptParsed.fields } : {}),
530
+ }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
531
+ }
532
+ // @implements A-SPEC-102.2 — review verdicts for callers that are not MCP clients.
533
+ if (cmd === 'review') {
534
+ const { runReview, REVIEW_USAGE } = require('./review');
535
+ if (flags.help) {
536
+ process.stdout.write(REVIEW_USAGE);
537
+ return 0;
538
+ }
539
+ const str = (k) => (typeof flags[k] === 'string' ? flags[k] : undefined);
540
+ return runReview(positionals[0], {
541
+ target: str('target'), base: str('base'), head: str('head'), verdict: str('verdict'), findings: str('finding')?.split('\n'),
542
+ solid: str('solid')?.split('\n'), // @implements A-SPEC-102.7
543
+ engine: str('engine'), model: str('model'), session: str('session'), strict: flags.strict === true,
544
+ }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
545
+ }
546
+ if (cmd === 'roles') {
547
+ const { runRoles } = require('./roles');
548
+ return runRoles(positionals[0], { target: typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd(), dryRun: flags['dry-run'] === true }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
549
+ }
550
+ if (cmd === 'scratch') {
551
+ const { runScratch } = require('./scratch');
552
+ return runScratch({ label: typeof flags.new === 'string' ? flags.new : undefined }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
553
+ }
469
554
  if (cmd === 'attest') {
470
555
  const { runAttest } = require('./attest');
471
556
  const target = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
@@ -961,6 +1046,15 @@ async function main(argv) {
961
1046
  process.stdout.write(`\u2717 ${ref.refusal}\n`);
962
1047
  return 1;
963
1048
  }
1049
+ // @implements A-SPEC-779 \u2014 never from inside a run; a run's awaited request only from a terminal.
1050
+ const { grantGuard } = require('../guardrail/run-refusals');
1051
+ const guarded = grantGuard(root, ref.id, { env: process.env, interactive: process.stdin.isTTY === true && process.stdout.isTTY === true });
1052
+ if (guarded !== null) {
1053
+ // @implements A-SPEC-779.1 \u2014 the refusal carries its envelope, so an orchestrator reads its class.
1054
+ const { withRefusalLine } = require('../guardrail/refusal-codes');
1055
+ process.stdout.write(`${withRefusalLine(`\u2717 ${guarded}`)}\n`);
1056
+ return 1;
1057
+ }
964
1058
  const r = grantRequest(root, ref.id, opts);
965
1059
  process.stdout.write(r.ok ? `✓ approved — ${ref.subject('✓ approved — ')}\n${ref.detail(`valid until ${r.expires}`)}\n` : `✗ ${r.reason}\n`);
966
1060
  return r.ok ? 0 : 1;
@@ -980,6 +1074,23 @@ async function main(argv) {
980
1074
  process.stdout.write(r.ok ? `✓ denied — ${ref.subject('✓ denied — ')}\n${ref.detail('the denial was recorded')}\n` : `✗ ${r.reason}\n`);
981
1075
  return r.ok ? 0 : 1;
982
1076
  }
1077
+ // @implements A-SPEC-779.2 — the requester's own close: only the run that filed it, recorded as `withdrawn`.
1078
+ if (typeof flags.withdraw === 'string') {
1079
+ const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
1080
+ if (reason === '') {
1081
+ process.stderr.write('✗ --withdraw requires --reason — it is what the operator reads in place of a decision\n');
1082
+ return 1;
1083
+ }
1084
+ const { withdrawRequest } = require('./approve');
1085
+ const ref = resolveRef(flags.withdraw);
1086
+ if ('refusal' in ref) {
1087
+ process.stdout.write(`✗ ${ref.refusal}\n`);
1088
+ return 1;
1089
+ }
1090
+ const r = withdrawRequest(root, ref.id, reason, { env: process.env, cwd: process.cwd() });
1091
+ process.stdout.write(r.ok ? `↩ withdrawn — ${ref.subject('↩ withdrawn — ')}\n${ref.detail('withdrawn by its run')}\n` : `✗ ${r.reason}\n`);
1092
+ return r.ok ? 0 : 1;
1093
+ }
983
1094
  // @implements A-SPEC-649 — the operator withdraws a live grant. A granted id is no longer
984
1095
  // pending, so it resolves against the DECIDED ids (full id or a unique prefix), never a list index.
985
1096
  if (typeof flags.revoke === '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, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6
39
+ // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-476.1
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-769.11
42
42
  // @implements A-SPEC-340
@@ -1356,9 +1356,10 @@ function runInitUnguarded(opts) {
1356
1356
  // runs doctor never met it. One-time by the nature of the act, so no marker is needed here.
1357
1357
  // Fail-open: an invitation is not worth failing a wiring over.
1358
1358
  try {
1359
- const { resolveSemanticTier } = require('../semantic/tier');
1359
+ const { resolveProjectSemanticTier } = require('../semantic/tier');
1360
1360
  const { tierAdviceLines } = require('../semantic/tier-advice');
1361
- for (const line of tierAdviceLines(resolveSemanticTier()))
1361
+ // @implements A-SPEC-476.1 — the target project's capped tier.
1362
+ for (const line of tierAdviceLines(resolveProjectSemanticTier(opts.target)))
1362
1363
  messages.push(line);
1363
1364
  }
1364
1365
  catch { /* the wiring is the point; the invitation is not */
@@ -16,4 +16,6 @@ export interface NotifyDeps {
16
16
  detached?: boolean;
17
17
  }) => Pick<ChildProcess, 'unref' | 'on'>;
18
18
  }
19
- export declare function notifyQueueArrival(item: Pick<PendingRequest, 'kind' | 'target'>, deps?: NotifyDeps): void;
19
+ /** @implements A-SPEC-770.12 — the notification text: kind, target and, when the request carries one, its title. */
20
+ export declare function notificationBody(item: Pick<PendingRequest, 'kind' | 'target' | 'title'>): string;
21
+ export declare function notifyQueueArrival(item: Pick<PendingRequest, 'kind' | 'target' | 'title'>, deps?: NotifyDeps): void;