@holmes-lab/holmes-kit 0.35.25 → 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 (125) hide show
  1. package/CHANGELOG.md +298 -0
  2. package/README.md +3 -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 +31 -1
  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 +25 -1
  13. package/dist/holmes/cli/doctor.js +153 -7
  14. package/dist/holmes/cli/index.js +99 -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.d.ts +30 -0
  27. package/dist/holmes/cli/runtime-binding.js +96 -7
  28. package/dist/holmes/cli/test-platform.d.ts +16 -0
  29. package/dist/holmes/cli/test-platform.js +31 -1
  30. package/dist/holmes/config/config.d.ts +49 -0
  31. package/dist/holmes/config/config.js +146 -3
  32. package/dist/holmes/config/project-caps.d.ts +21 -0
  33. package/dist/holmes/config/project-caps.js +114 -0
  34. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  35. package/dist/holmes/governance/approval-queue.js +48 -6
  36. package/dist/holmes/governance/autonomy.d.ts +6 -0
  37. package/dist/holmes/governance/autonomy.js +21 -0
  38. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  39. package/dist/holmes/governance/push-gate-runner.js +49 -1
  40. package/dist/holmes/governance/replica-id.d.ts +9 -0
  41. package/dist/holmes/governance/replica-id.js +44 -7
  42. package/dist/holmes/governance/role-policy.d.ts +41 -1
  43. package/dist/holmes/governance/role-policy.js +137 -20
  44. package/dist/holmes/governance/run-mode.d.ts +14 -0
  45. package/dist/holmes/governance/run-mode.js +120 -0
  46. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  47. package/dist/holmes/governance/tool-actions.js +121 -0
  48. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  49. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  50. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  51. package/dist/holmes/guardrail/classification-mode.js +135 -0
  52. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  53. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  54. package/dist/holmes/guardrail/phase.d.ts +2 -1
  55. package/dist/holmes/guardrail/phase.js +22 -8
  56. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  57. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  58. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  59. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  60. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  61. package/dist/holmes/guardrail/risk-classifier.js +242 -26
  62. package/dist/holmes/guardrail/risk-types.d.ts +15 -0
  63. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  64. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  65. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  66. package/dist/holmes/guardrail/run-refusals.js +348 -0
  67. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  68. package/dist/holmes/guardrail/run-stages.js +188 -0
  69. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  70. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  71. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  72. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  73. package/dist/holmes/guardrail/shell-words.js +7 -7
  74. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  75. package/dist/holmes/guardrail/write-target.js +118 -16
  76. package/dist/holmes/hooks/pre-tool-use.d.ts +35 -1
  77. package/dist/holmes/hooks/pre-tool-use.js +702 -81
  78. package/dist/holmes/hooks/session-start.js +5 -3
  79. package/dist/holmes/hooks/stop.d.ts +32 -0
  80. package/dist/holmes/hooks/stop.js +129 -4
  81. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  82. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  83. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  84. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  85. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  86. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  87. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  88. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  89. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  90. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  91. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  92. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  93. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  94. package/dist/holmes/mcp/handlers.d.ts +2 -3
  95. package/dist/holmes/mcp/handlers.js +22 -2
  96. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  97. package/dist/holmes/mcp/harness-attestation.js +3 -1
  98. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  99. package/dist/holmes/mcp/operator-recovery.js +4 -3
  100. package/dist/holmes/mcp/server.js +9 -0
  101. package/dist/holmes/mcp/tool-schemas.js +6 -3
  102. package/dist/holmes/project/root.js +6 -1
  103. package/dist/holmes/project/run-records.d.ts +17 -0
  104. package/dist/holmes/project/run-records.js +126 -0
  105. package/dist/holmes/review/mrp.d.ts +35 -0
  106. package/dist/holmes/review/mrp.js +119 -0
  107. package/dist/holmes/review/verdicts.d.ts +117 -0
  108. package/dist/holmes/review/verdicts.js +345 -0
  109. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  110. package/dist/holmes/semantic/cloud-usage.js +106 -0
  111. package/dist/holmes/semantic/embedder.d.ts +15 -6
  112. package/dist/holmes/semantic/embedder.js +84 -3
  113. package/dist/holmes/semantic/local-model.d.ts +21 -2
  114. package/dist/holmes/semantic/local-model.js +14 -3
  115. package/dist/holmes/semantic/tier.d.ts +25 -0
  116. package/dist/holmes/semantic/tier.js +86 -1
  117. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  118. package/dist/holmes/semantic/vector-cache.js +4 -1
  119. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  120. package/dist/holmes/spec/approval-blockers.js +70 -2
  121. package/dist/holmes/spec/renumber.d.ts +1 -1
  122. package/dist/holmes/spec/renumber.js +5 -2
  123. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  124. package/dist/holmes/spec/transition-policy.js +17 -2
  125. package/package.json +1 -1
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.DECISION_KINDS = exports.QUEUE_RELPATH = void 0;
37
+ exports.requestLabel = requestLabel;
37
38
  exports.pendingRequestLine = pendingRequestLine;
38
39
  exports.refusalsFilename = refusalsFilename;
39
40
  exports.isRefusalsFilename = isRefusalsFilename;
@@ -49,8 +50,9 @@ exports.refusalsOutsideInbox = refusalsOutsideInbox;
49
50
  exports.grantableRequests = grantableRequests;
50
51
  exports.openOccurrences = openOccurrences;
51
52
  exports.asPendingRequest = asPendingRequest;
52
- // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754, A-SPEC-770.3, A-SPEC-770.6
53
+ // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.12, A-SPEC-779.2
53
54
  const execution_context_1 = require("../project/execution-context");
55
+ const run_mode_1 = require("./run-mode");
54
56
  const root_1 = require("../project/root");
55
57
  const node_crypto_1 = require("node:crypto");
56
58
  const npx_bin_1 = require("../project/npx-bin");
@@ -97,7 +99,18 @@ exports.DECISION_KINDS = new Set([
97
99
  * The line a refusal ends with to name its pending request and the operator command.
98
100
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
99
101
  */
100
- function pendingRequestLine(id, kind, root) {
102
+ /**
103
+ * @implements A-SPEC-770.12 — what a request is, for a person reading its refusal: ` · <kind> <target> 「<title>」`, or ''
104
+ * without a title (A-SPEC-770.1's bytes). Every field is flattened and bounded and loses `]`, so the bracket closes once.
105
+ */
106
+ function requestLabel(kind, target, title) {
107
+ if (typeof title !== 'string' || title.trim() === '')
108
+ return '';
109
+ const f = (s, max) => (0, screen_safe_1.flattenField)(s, max).replace(/[\]「」]/g, ' ').trim();
110
+ return ` · ${f(kind ?? '', 40)} ${f(target ?? '', 60)} 「${f(title, 80)}」`;
111
+ }
112
+ function pendingRequestLine(id, kind, root, title, target) {
113
+ const label = requestLabel(kind, target, title); // @implements A-SPEC-770.12
101
114
  // @implements A-SPEC-770.3 — the version that issued the hint, past any older copy the bare npx command resolves first.
102
115
  const command = `${(0, npx_bin_1.holmesKitCommand)(root)} approve`; // A-SPEC-770.6 — the root the request is stored in
103
116
  // @implements A-SPEC-770.2 — the request lives in the refusal log / queue of the workspace whose hook refused, not in
@@ -105,7 +118,7 @@ function pendingRequestLine(id, kind, root) {
105
118
  // 2026-10-13, Codex X1: the hint carried no `--target` at all). With a root, every command names it; a root with
106
119
  // white space is double-quoted once; a root is never folded or relativised. Without a root the A-SPEC-770.1 lines
107
120
  // are produced byte for byte.
108
- const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
121
+ const targetFlag = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
109
122
  // @implements A-SPEC-770 — a request outside the decision inbox (A-SPEC-563.1 routes gate refusals to the local
110
123
  // refusal log) names the id-bearing command, because the bare command opens a screen that by design does not list
111
124
  // it. Field report (jarvis, 2026-10-11): the operator ran the bare command, saw six old inbox requests, and the
@@ -113,9 +126,9 @@ function pendingRequestLine(id, kind, root) {
113
126
  // @implements A-SPEC-770.1 — the id rides the `--grant` flag: the CLI refuses a positional id (`unexpected
114
127
  // argument: req-…`, measured by the operator on 0.35.17 with the command this line used to name).
115
128
  if (kind !== undefined && !exports.DECISION_KINDS.has(kind)) {
116
- return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id}${target} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals${target} 로 조회)`;
129
+ return `\n[승인 대기 ${id}${label}] 운영자: ${command} --grant ${id}${targetFlag} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals${targetFlag} 로 조회)`;
117
130
  }
118
- return root === undefined ? `\n[승인 대기 ${id}] 운영자: ${command}` : `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id}${target}`;
131
+ return root === undefined ? `\n[승인 대기 ${id}${label}] 운영자: ${command}` : `\n[승인 대기 ${id}${label}] 운영자: ${command} --grant ${id}${targetFlag}`;
119
132
  }
120
133
  const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
121
134
  function refusalsFilename(replica) {
@@ -256,6 +269,8 @@ function foldQueue(lines, opts) {
256
269
  ...(execution ? { execution } : {}),
257
270
  ...(typeof e.subject === 'string' && e.subject !== '' ? { subject: e.subject } : {}),
258
271
  ...(typeof e.risk === 'string' && e.risk !== '' ? { risk: e.risk } : {}),
272
+ ...(typeof e.title === 'string' && e.title !== '' ? { title: e.title } : {}), // @implements A-SPEC-770.12
273
+ ...(typeof e.requester_run === 'string' && e.requester_run !== '' ? { requesterRun: e.requester_run } : {}), // @implements A-SPEC-779.2
259
274
  });
260
275
  }
261
276
  break;
@@ -292,6 +307,22 @@ function foldQueue(lines, opts) {
292
307
  decisions[id] = { event: 'revoked', ...(typeof e.reason === 'string' ? { reason: e.reason } : {}), ts: typeof e.ts === 'string' ? e.ts : '', ...(execution ? { execution } : {}) };
293
308
  }
294
309
  break;
310
+ // @implements A-SPEC-779.2 — the filing run closed its request: it leaves pending like a denial, but no operator
311
+ // decided it, and `covered` reopens it on a later refusal as a decision does.
312
+ case 'withdrawn':
313
+ if (id) {
314
+ pending.delete(id);
315
+ delete holds[id];
316
+ decisions[id] = {
317
+ event: 'withdrawn',
318
+ ...(typeof e.reason === 'string' ? { reason: e.reason } : {}),
319
+ ts: typeof e.ts === 'string' ? e.ts : '',
320
+ ...(typeof e.covered === 'number' ? { covered: e.covered } : {}),
321
+ ...(typeof e.run === 'string' ? { run: e.run } : {}),
322
+ ...(execution ? { execution } : {}),
323
+ };
324
+ }
325
+ break;
295
326
  case 'held': {
296
327
  const entry = id ? pending.get(id) : undefined;
297
328
  if (entry) {
@@ -377,6 +408,14 @@ function enqueueApprovalRequestDetailed(root, req) {
377
408
  catch {
378
409
  execution = undefined;
379
410
  }
411
+ // @implements A-SPEC-779.2 — the run that files it, so only that run may withdraw it. Best-effort: omitted on failure.
412
+ let requesterRun;
413
+ try {
414
+ requesterRun = (0, run_mode_1.runMode)(process.env, root, process.cwd()).id;
415
+ }
416
+ catch {
417
+ requesterRun = undefined;
418
+ }
380
419
  const event = {
381
420
  event: 'requested',
382
421
  id: approvalRequestId(req.kind, req.target),
@@ -388,6 +427,8 @@ function enqueueApprovalRequestDetailed(root, req) {
388
427
  ...(execution ? { execution } : {}),
389
428
  ...(typeof req.subject === 'string' && req.subject !== '' ? { subject: req.subject } : {}),
390
429
  ...(typeof req.risk === 'string' && req.risk !== '' ? { risk: req.risk } : {}),
430
+ ...(typeof req.title === 'string' && req.title.trim() !== '' ? { title: (0, screen_safe_1.flattenField)(req.title, 200) } : {}), // @implements A-SPEC-770.12
431
+ ...(requesterRun ? { requester_run: requesterRun } : {}),
391
432
  // @implements A-SPEC-564.2 — only the refusal log carries the feedback cost; inbox kinds have
392
433
  // no deny text to measure.
393
434
  ...(!exports.DECISION_KINDS.has(req.kind) && typeof req.reasonBytes === 'number' && Number.isFinite(req.reasonBytes)
@@ -537,7 +578,7 @@ function queueHint(root, req, opts) {
537
578
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
538
579
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
539
580
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
540
- const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id, req.kind, root)); // @implements A-SPEC-770, A-SPEC-770.2
581
+ const hint = denialLine + (opts?.pendingHint ? opts.pendingHint(id) : pendingRequestLine(id, req.kind, root, req.title, req.target)); // @implements A-SPEC-770, A-SPEC-770.2, A-SPEC-770.12
541
582
  return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
542
583
  ? hint
543
584
  : denialLine;
@@ -636,5 +677,6 @@ function asPendingRequest(id, occurrences) {
636
677
  firstTs: occurrences[0].ts,
637
678
  lastTs: latest.ts,
638
679
  ...(latest.replica ? { replica: latest.replica } : {}),
680
+ ...(latest.requester_run ? { requesterRun: latest.requester_run } : {}), // @implements A-SPEC-779.2
639
681
  };
640
682
  }
@@ -33,6 +33,12 @@ export declare function autonomyRuleMeaning(rule: string): string;
33
33
  * could tell which rule had fired.
34
34
  */
35
35
  export declare function specApprovalAutonomyReason(spec: Spec, resolveParent: (id: string) => Spec | null, descendants?: Spec[]): string | null;
36
+ /**
37
+ * @implements A-SPEC-532.6 — the owner's ceiling (ax.config.json `autonomy.ceiling`) over every automatic seal, autonomous
38
+ * or delegated. It only narrows: `default` refuses nothing, and a spec it lets through still faces the grader. The
39
+ * returned text is why the seal stays with the operator, or null.
40
+ */
41
+ export declare function ceilingRefusal(ceiling: 'off' | 'tests' | 'no-gate' | 'default', spec: Spec, descendants?: Spec[]): string | null;
36
42
  /**
37
43
  * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
38
44
  * presented in-session while autonomous mode is enabled. This is intentionally narrower than
@@ -40,6 +40,7 @@ exports.specApprovalAutonomy = specApprovalAutonomy;
40
40
  exports.declaredGateDirection = declaredGateDirection;
41
41
  exports.autonomyRuleMeaning = autonomyRuleMeaning;
42
42
  exports.specApprovalAutonomyReason = specApprovalAutonomyReason;
43
+ exports.ceilingRefusal = ceilingRefusal;
43
44
  exports.requiresAutonomousApprovalPrompt = requiresAutonomousApprovalPrompt;
44
45
  exports.sessionAutonomyActive = sessionAutonomyActive;
45
46
  exports.projectDefaultAutonomy = projectDefaultAutonomy;
@@ -256,6 +257,26 @@ function specApprovalAutonomyReason(spec, resolveParent, descendants) {
256
257
  return 'unknown-kind'; // unknown kind: fail-safe to human
257
258
  }
258
259
  }
260
+ /**
261
+ * @implements A-SPEC-532.6 — the owner's ceiling (ax.config.json `autonomy.ceiling`) over every automatic seal, autonomous
262
+ * or delegated. It only narrows: `default` refuses nothing, and a spec it lets through still faces the grader. The
263
+ * returned text is why the seal stays with the operator, or null.
264
+ */
265
+ function ceilingRefusal(ceiling, spec, descendants) {
266
+ if (ceiling === 'default')
267
+ return null;
268
+ if (ceiling === 'off')
269
+ return 'no seal is automatic here';
270
+ if (spec.type === 'T-SPEC')
271
+ return null;
272
+ if (ceiling === 'tests')
273
+ return 'only T-SPECs seal automatically here';
274
+ // no-gate: a gate-behavior A-SPEC, or a REQ/H-SPEC above one, is the operator's whatever direction it declares.
275
+ const gate = (s) => s.type === 'A-SPEC' && breakingGrade(s) === 'gate-behavior';
276
+ if (gate(spec) || (descendants ?? []).some(gate))
277
+ return 'a gate-behavior change is never automatic here';
278
+ return null;
279
+ }
259
280
  /**
260
281
  * Whether an otherwise HITL-classed approval is one of the exceptional cases that must still be
261
282
  * presented in-session while autonomous mode is enabled. This is intentionally narrower than
@@ -10,6 +10,14 @@ export interface PrePushIo {
10
10
  stdinText: string;
11
11
  /** Refusals and notices land here (stderr in the shipped hook). */
12
12
  write: (s: string) => void;
13
+ /** @implements A-SPEC-102.4 — the environment run mode is read from; `process.env` when absent. */
14
+ env?: NodeJS.ProcessEnv;
13
15
  }
16
+ /**
17
+ * @implements A-SPEC-102.4 — in a run whose record carries `base`, a push of `sha` needs an independent passing review
18
+ * of base..sha. Null outside a run, without a base, for the base itself, on a passing gate, or on any error (the push
19
+ * gate stays fail-open on collection errors, H-SPEC-509).
20
+ */
21
+ export declare function runPushReviewRefusal(cwd: string, env: NodeJS.ProcessEnv, sha: string): string | null;
14
22
  /** Exit code of the hook: 0 = push proceeds, 1 = refused. */
15
23
  export declare function runPrePush(io: PrePushIo): 0 | 1;
@@ -34,8 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.effectiveHooksDir = effectiveHooksDir;
37
+ exports.runPushReviewRefusal = runPushReviewRefusal;
37
38
  exports.runPrePush = runPrePush;
38
- // @implements A-SPEC-509.1, A-SPEC-734
39
+ // @implements A-SPEC-509.1, A-SPEC-734, A-SPEC-102.4, A-SPEC-774.21
39
40
  /**
40
41
  * The push gate's IMPURE half: collect (stdin lines, git facts, the evidence ledger) and hand
41
42
  * everything to the pure judgePush. Any collection failure ALLOWS — this gate safens the default
@@ -62,6 +63,47 @@ function effectiveHooksDir(repoRoot) {
62
63
  catch { /* unset config exits 1 — the default location applies */ }
63
64
  return path.join(repoRoot, '.git', 'hooks');
64
65
  }
66
+ /**
67
+ * @implements A-SPEC-102.4 — in a run whose record carries `base`, a push of `sha` needs an independent passing review
68
+ * of base..sha. Null outside a run, without a base, for the base itself, on a passing gate, or on any error (the push
69
+ * gate stays fail-open on collection errors, H-SPEC-509).
70
+ */
71
+ function runPushReviewRefusal(cwd, env, sha) {
72
+ let mode;
73
+ try {
74
+ const { runMode } = require('./run-mode');
75
+ mode = runMode(env, cwd, cwd);
76
+ }
77
+ catch {
78
+ return null;
79
+ } // whether this is a run cannot be read: as an interactive push
80
+ if (!mode.run)
81
+ return null;
82
+ // @implements A-SPEC-774.21 — in a run, a push gate that cannot judge refuses, naming what it could not read.
83
+ const cannot = (what) => `[Holmes-Kit push gate] the run's review gate could not judge this push: ${what} — `
84
+ + 'repair the run record or end the run with holmes-kit run stop';
85
+ try {
86
+ if (!mode.id)
87
+ return cannot('the run has no id');
88
+ const { listRuns, mainCheckoutOf } = require('../project/run-records');
89
+ const rec = listRuns(mainCheckoutOf(cwd)).find((r) => r.run_id === mode.id);
90
+ if (!rec)
91
+ return cannot(`no run record for ${mode.id}`);
92
+ if (typeof rec.base !== 'string' || rec.base === '')
93
+ return cannot('run record carries no base');
94
+ if (rec.base === sha)
95
+ return null;
96
+ const { gateRange } = require('../review/verdicts');
97
+ const g = gateRange(rec.worktree, rec.base, sha, {});
98
+ if (g.ok)
99
+ return null;
100
+ return `[Holmes-Kit push gate] the run's commits ${rec.base}..${sha} are not reviewed (${g.reasons.join('; ')}) — an independent reviewer records a verdict with `
101
+ + `holmes-kit review record --base ${rec.base} --head ${sha} --verdict pass`;
102
+ }
103
+ catch (e) {
104
+ return cannot(e instanceof Error ? e.message : String(e));
105
+ }
106
+ }
65
107
  /** Exit code of the hook: 0 = push proceeds, 1 = refused. */
66
108
  function runPrePush(io) {
67
109
  try {
@@ -93,6 +135,12 @@ function runPrePush(io) {
93
135
  io.write((v.reason ?? '[Holmes-Kit push 게이트] 거부') + '\n');
94
136
  refused = true;
95
137
  }
138
+ // @implements A-SPEC-102.4 — a run's push also needs its range reviewed.
139
+ const review = runPushReviewRefusal(io.cwd, io.env ?? process.env, line.localSha);
140
+ if (review) {
141
+ io.write(review + '\n');
142
+ refused = true;
143
+ }
96
144
  }
97
145
  return refused ? 1 : 0;
98
146
  }
@@ -8,8 +8,16 @@
8
8
  * file is worse than either rule being wrong.
9
9
  */
10
10
  export declare function sanitizeReplicaId(raw: string): string;
11
+ /**
12
+ * @implements A-SPEC-643.1 — `<host>-<tag>-<value>` while it fits the 32-character limit. When it does not (a macOS
13
+ * host is often 25 characters already), the host is shortened and the value becomes an 8-hex digest of itself, so two
14
+ * worktrees or two runs never collapse into one id by truncation.
15
+ */
16
+ export declare function composeReplicaId(host: string, tag: 'wt' | 'run', value: string): string;
11
17
  /**
12
18
  * Resolve this machine's replica id: explicit env, then the stored value, then the hostname.
19
+ * @implements A-SPEC-643.1 — between the env override and the stored value, a run id gives `<host>-run-<id>`
20
+ * (never persisted: a run ends); between the stored value and the host, a linked worktree gives `<host>-wt-<name>`.
13
21
  *
14
22
  * The env override exists for CI and for tests, where the hostname is neither stable nor meaningful.
15
23
  * Writing the generated value down is what makes the identity stable — an id derived fresh each run
@@ -17,4 +25,5 @@ export declare function sanitizeReplicaId(raw: string): string;
17
25
  */
18
26
  export declare function resolveReplicaId(root: string, env?: NodeJS.ProcessEnv, opts?: {
19
27
  persist?: boolean;
28
+ host?: string;
20
29
  }): string;
@@ -34,8 +34,10 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.sanitizeReplicaId = sanitizeReplicaId;
37
+ exports.composeReplicaId = composeReplicaId;
37
38
  exports.resolveReplicaId = resolveReplicaId;
38
- // @implements A-SPEC-148
39
+ // @implements A-SPEC-148, A-SPEC-643.1
40
+ const node_crypto_1 = require("node:crypto");
39
41
  const fs = __importStar(require("node:fs"));
40
42
  const os = __importStar(require("node:os"));
41
43
  const path = __importStar(require("node:path"));
@@ -63,8 +65,39 @@ function sanitizeReplicaId(raw) {
63
65
  // Everything stripped (an all-punctuation name, or an empty one) still needs a usable filename.
64
66
  return cleaned === '' ? 'local' : cleaned;
65
67
  }
68
+ /**
69
+ * @implements A-SPEC-643.1 — `<host>-<tag>-<value>` while it fits the 32-character limit. When it does not (a macOS
70
+ * host is often 25 characters already), the host is shortened and the value becomes an 8-hex digest of itself, so two
71
+ * worktrees or two runs never collapse into one id by truncation.
72
+ */
73
+ function composeReplicaId(host, tag, value) {
74
+ const h = sanitizeReplicaId(host);
75
+ const v = (value || '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'x';
76
+ const plain = `${h}-${tag}-${v}`;
77
+ if (plain.length <= MAX)
78
+ return plain;
79
+ const digest = (0, node_crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, 8);
80
+ const room = MAX - tag.length - digest.length - 2;
81
+ return `${h.slice(0, room).replace(/-+$/, '') || 'h'}-${tag}-${digest}`;
82
+ }
83
+ /** @implements A-SPEC-643.1 — a linked worktree's name: its `.git` is a file with `gitdir:`. */
84
+ function linkedWorktreeName(root) {
85
+ try {
86
+ const pointer = path.join(root, '.git');
87
+ if (!fs.lstatSync(pointer).isFile())
88
+ return null;
89
+ if (!/^gitdir:\s*\S/m.test(fs.readFileSync(pointer, 'utf8')))
90
+ return null;
91
+ return path.basename(path.resolve(root));
92
+ }
93
+ catch {
94
+ return null;
95
+ }
96
+ }
66
97
  /**
67
98
  * Resolve this machine's replica id: explicit env, then the stored value, then the hostname.
99
+ * @implements A-SPEC-643.1 — between the env override and the stored value, a run id gives `<host>-run-<id>`
100
+ * (never persisted: a run ends); between the stored value and the host, a linked worktree gives `<host>-wt-<name>`.
68
101
  *
69
102
  * The env override exists for CI and for tests, where the hostname is neither stable nor meaningful.
70
103
  * Writing the generated value down is what makes the identity stable — an id derived fresh each run
@@ -75,6 +108,14 @@ function resolveReplicaId(root, env = process.env, opts = {}) {
75
108
  const fromEnv = env.HOLMES_REPLICA_ID;
76
109
  if (typeof fromEnv === 'string' && fromEnv.trim() !== '')
77
110
  return sanitizeReplicaId(fromEnv);
111
+ let host = 'local';
112
+ try {
113
+ host = opts.host ?? os.hostname();
114
+ }
115
+ catch { /* keep the fallback */ }
116
+ const run = env.HOLMES_RUN_ID;
117
+ if (typeof run === 'string' && run.trim() !== '')
118
+ return composeReplicaId(host, 'run', run.trim());
78
119
  const file = path.join(root, STORE);
79
120
  try {
80
121
  const stored = fs.readFileSync(file, 'utf8').trim();
@@ -82,12 +123,8 @@ function resolveReplicaId(root, env = process.env, opts = {}) {
82
123
  return sanitizeReplicaId(stored);
83
124
  }
84
125
  catch { /* not yet written */ }
85
- let host = 'local';
86
- try {
87
- host = os.hostname();
88
- }
89
- catch { /* keep the fallback */ }
90
- const id = sanitizeReplicaId(host);
126
+ const worktree = linkedWorktreeName(root);
127
+ const id = worktree !== null ? composeReplicaId(host, 'wt', worktree) : sanitizeReplicaId(host);
91
128
  // Best-effort persistence: failing to record the id must not stop the caller from writing to the
92
129
  // ledger, it only means the next run re-derives the same value from the same hostname.
93
130
  // @implements A-SPEC-150
@@ -15,8 +15,12 @@ import { Identity } from './identity';
15
15
  * would simply change what that role is allowed to do.
16
16
  */
17
17
  export interface RolePolicy {
18
+ /** @implements A-SPEC-774.19 — `stages`: the run stages the role may act in; absent means every stage. */
19
+ /** @implements A-SPEC-774.22 — `stagesMalformed`: a `stages` key that is not a list of strings (refused in a run). */
18
20
  roles: Record<string, {
19
21
  allow: string[];
22
+ stages?: string[];
23
+ stagesMalformed?: true;
20
24
  }>;
21
25
  /**
22
26
  * Which role an UNSPECIFIED agent is treated as. Declared by the project, never assumed by code.
@@ -29,14 +33,41 @@ export interface RolePolicy {
29
33
  * Omitting it keeps the fail-closed behaviour: unspecified is refused.
30
34
  */
31
35
  default?: string;
36
+ /** @implements A-SPEC-774.10 — 2 when the policy is written in the REQ-774 vocabulary and read strictly. */
37
+ vocabulary?: number;
38
+ /** @implements A-SPEC-774.15 — the roles directory exists but cannot be listed: the policy grants nothing. */
39
+ loadIssue?: string;
40
+ /** @implements A-SPEC-774.15 — role names declared in more than one file (the later still loads; a run refuses them). */
41
+ duplicates?: string[];
32
42
  }
33
43
  /** `null` when the project has not opted in. A PRESENT-but-broken policy is never null — see below. */
34
44
  export declare function loadRolePolicy(root: string): RolePolicy | null;
45
+ /** A policy from one document's text, as the loader would read it. */
46
+ export declare function parseRolePolicyText(text: string): RolePolicy;
47
+ /**
48
+ * @implements A-SPEC-774.10 — the actions REQ-774 added that 0.35.25 never role-checked. A policy written for
49
+ * 0.35.25 names none of them; outside a run it keeps allowing them, so no person has to migrate by hand. `AUTHOR_*`,
50
+ * `WRITE_CODE` and `WRITE_TEST` are not here: they kept their meaning, and their checks are the Fixed set (C1, C2).
51
+ */
52
+ export declare const LEGACY_UNCHECKED: ReadonlySet<string>;
53
+ /**
54
+ * @implements A-SPEC-774.10 §4 — the same policy written in the new vocabulary: `vocabulary: 2`, and every role
55
+ * granted the actions the legacy reading allowed implicitly, so verdicts outside a run are unchanged.
56
+ */
57
+ export declare function migrateRolePolicyText(text: string): string;
35
58
  /** What `doctor` reports. Three states, because "no policy" and "guidance present but off" differ. */
36
59
  export interface RolePolicyStatus {
37
60
  state: 'absent' | 'inactive' | 'active';
38
61
  roles: string[];
62
+ /** @implements A-SPEC-774.22 — roles whose `stages` cannot be read. */
63
+ malformedStages?: string[];
39
64
  default?: string;
65
+ /** @implements A-SPEC-774.8 — a default broader than every role: refused in a run, a doctor warning interactively. */
66
+ defaultIssue?: string;
67
+ /** @implements A-SPEC-774.15 — the roles directory could not be read; every action is refused. */
68
+ loadIssue?: string;
69
+ /** @implements A-SPEC-774.15 — roles declared in more than one file. */
70
+ duplicates?: string[];
40
71
  }
41
72
  /**
42
73
  * Describes the project's role configuration WITHOUT judging it. Not having roles on is not a
@@ -49,4 +80,13 @@ export declare function rolePolicyStatus(root: string): RolePolicyStatus;
49
80
  * Fail-closed once a policy exists: an absent role, an unregistered role, and a role without the
50
81
  * action are all refusals. Before a policy exists there is no opinion at all.
51
82
  */
52
- export declare function roleCheck(action: string, identity: Identity, policy: RolePolicy | null): string | null;
83
+ /**
84
+ * @implements A-SPEC-774.8 — a session reaches the default by LOSING its role (unset, or a harness that does not pass it
85
+ * to the MCP server). A default broader than what every role allows turns that loss into an escalation. Null when the
86
+ * default is a subset of the intersection of every role's allow list (an empty intersection makes `allow: []` valid).
87
+ */
88
+ export declare function defaultBreadthIssue(policy: RolePolicy): string | null;
89
+ export declare function roleCheck(action: string, identity: Identity, policy: RolePolicy | null, opts?: {
90
+ run?: boolean;
91
+ stage?: string;
92
+ }): string | null;