@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
@@ -37,11 +37,13 @@ exports.posixOnly = posixOnly;
37
37
  exports.posixOnlyNonRoot = posixOnlyNonRoot;
38
38
  exports.foldsCase = foldsCase;
39
39
  exports.posixOnlyWithCommand = posixOnlyWithCommand;
40
+ exports.bashWord = bashWord;
41
+ exports.removeWhenReleased = removeWhenReleased;
40
42
  exports.win32Only = win32Only;
41
43
  const fs = __importStar(require("node:fs"));
42
44
  const path = __importStar(require("node:path"));
43
45
  const node_crypto_1 = require("node:crypto");
44
- // @implements A-SPEC-220.3
46
+ // @implements A-SPEC-220.3, A-SPEC-220.4
45
47
  // @implements A-SPEC-597
46
48
  /**
47
49
  * A test that cannot run here says so, instead of returning early and being counted as a pass.
@@ -145,6 +147,34 @@ function posixOnlyWithCommand(reason, command, platform = process.platform, uid
145
147
  const base = posixOnlyNonRoot(reason, platform, uid); // reason is validated here, before anything else
146
148
  return lookup(command) ? base : it.skip;
147
149
  }
150
+ /**
151
+ * @implements A-SPEC-220.4
152
+ * A path as ONE Bash word. A Windows temp path holds backslashes (Bash escapes) and may hold a space (a word break), so
153
+ * a fixture that interpolates it unquoted is read, correctly, as other words; single quotes keep the native spelling.
154
+ */
155
+ function bashWord(p) {
156
+ return `'${p.replace(/'/g, `'\\''`)}'`;
157
+ }
158
+ /**
159
+ * @implements A-SPEC-220.4
160
+ * Remove a directory a child process ran in. Windows holds such a directory for a moment after the process has gone;
161
+ * `fs.rmSync`'s own `maxRetries` did not cover it and a retry of the whole call did (A-SPEC-698, measured 2026-09-20).
162
+ * Bounded: past `ms` the last error is thrown, so a genuine failure is not swallowed.
163
+ */
164
+ async function removeWhenReleased(dir, ms = 10000, remove = fs.rmSync) {
165
+ const t0 = Date.now();
166
+ for (;;) {
167
+ try {
168
+ remove(dir, { recursive: true, force: true });
169
+ return;
170
+ }
171
+ catch (e) {
172
+ if (Date.now() - t0 > ms)
173
+ throw e;
174
+ await new Promise((res) => setTimeout(res, 100));
175
+ }
176
+ }
177
+ }
148
178
  /**
149
179
  * @implements A-SPEC-255
150
180
  * The mirror of `posixOnly`: a test whose SUBJECT only exists on Windows.
@@ -36,6 +36,55 @@ export interface AxConfig {
36
36
  */
37
37
  cycleIgnore: string[];
38
38
  };
39
+ /**
40
+ * @implements A-SPEC-775.1
41
+ * `strict` is the owner's opt-in to the run-mode classification outside a run (the supervisor's
42
+ * `strict_classification`): nested test folders narrow and unclassified writes off the safe list are code.
43
+ * `testDirs` are folders the owner declares as test folders, in every mode.
44
+ */
45
+ classification: {
46
+ strict: boolean;
47
+ testDirs: string[];
48
+ };
49
+ /**
50
+ * @implements A-SPEC-532.6
51
+ * The owner's ceiling on automatic approval (autonomous and delegated seals). It only narrows the grader; `default`
52
+ * when absent, `off` when malformed — a ceiling must never fail toward wider.
53
+ */
54
+ autonomy: {
55
+ ceiling: AutonomyCeiling;
56
+ };
57
+ /**
58
+ * @implements A-SPEC-778
59
+ * In a run, a refusal code repeated this many times stops the run. An integer from 1 to 1000; anything else is 5.
60
+ */
61
+ run: {
62
+ refusalRepeatLimit: number;
63
+ approvalWaitMinutes: number;
64
+ };
65
+ /** @implements A-SPEC-781 — a run's stage machine: the stages, the allowed edges, and the stages that need review. */
66
+ stages: StageMachine;
67
+ }
68
+ /** @implements A-SPEC-781 */
69
+ /** @implements A-SPEC-781.1 — `deny`: per stage, the classifier actions the gate refuses in a run at that stage. */
70
+ /**
71
+ * @implements A-SPEC-781.2 — `conditions`: per edge `from->to`, the checks a transition must pass; `notes`: how the
72
+ * declaration was read (a fallback, a filled-in deny), for the run log and doctor.
73
+ */
74
+ export interface StageMachine {
75
+ order: string[];
76
+ transitions: Record<string, string[]>;
77
+ reviewed: string[];
78
+ deny: Record<string, string[]>;
79
+ conditions: Record<string, string[]>;
80
+ notes: string[];
39
81
  }
82
+ export declare const DEFAULT_STAGES: StageMachine;
83
+ /** @implements A-SPEC-778 */
84
+ export declare const RUN_REFUSAL_LIMIT_DEFAULT = 5;
85
+ /** @implements A-SPEC-779 — how long a run may wait for an operator's decision before it stops. */
86
+ export declare const RUN_APPROVAL_WAIT_DEFAULT = 60;
87
+ /** @implements A-SPEC-532.6 — narrowest first. */
88
+ export type AutonomyCeiling = 'off' | 'tests' | 'no-gate' | 'default';
40
89
  export declare const DEFAULT_CONFIG: AxConfig;
41
90
  export declare function loadConfig(root: string): AxConfig;
@@ -33,13 +33,117 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.DEFAULT_CONFIG = void 0;
36
+ exports.DEFAULT_CONFIG = exports.RUN_APPROVAL_WAIT_DEFAULT = exports.RUN_REFUSAL_LIMIT_DEFAULT = exports.DEFAULT_STAGES = void 0;
37
37
  exports.loadConfig = loadConfig;
38
- // @implements A-SPEC-278
38
+ // @implements A-SPEC-278, A-SPEC-781.2, A-SPEC-476.3
39
39
  // @implements A-SPEC-125.5
40
40
  // src/holmes/config/config.ts
41
41
  const fs = __importStar(require("node:fs"));
42
42
  const path = __importStar(require("node:path"));
43
+ exports.DEFAULT_STAGES = {
44
+ order: ['analysis', 'design', 'implement', 'review', 'test', 'done'],
45
+ transitions: { analysis: ['design'], design: ['implement'], implement: ['review'], review: ['test', 'implement'], test: ['done', 'implement'], done: [] },
46
+ reviewed: ['test', 'done'],
47
+ deny: {
48
+ analysis: ['WRITE_CODE', 'WRITE_TEST'], design: ['WRITE_CODE', 'WRITE_TEST'], implement: [],
49
+ review: ['WRITE_CODE', 'WRITE_TEST'], test: ['WRITE_CODE'], done: ['WRITE_CODE', 'WRITE_TEST'],
50
+ },
51
+ // @implements A-SPEC-781.2 — the G5.7 slot: design → implement needs a design section (checked when G5.7 lands).
52
+ conditions: { 'design->implement': ['design-section'] },
53
+ notes: [],
54
+ };
55
+ /** @implements A-SPEC-781.2 — what a new-named stage without a deny entry refuses. */
56
+ const NEW_STAGE_DENY = ['WRITE_CODE', 'WRITE_TEST'];
57
+ /**
58
+ * @implements A-SPEC-781 — a declaration is taken whole or not at all: any flaw means the default machine.
59
+ * @implements A-SPEC-781.2 — never silently: the fallback, and every deny filled in for a stage, is a note.
60
+ */
61
+ function stageMachineOf(raw) {
62
+ if (raw === undefined)
63
+ return structuredClone(exports.DEFAULT_STAGES);
64
+ const fallback = (what) => ({ ...structuredClone(exports.DEFAULT_STAGES), notes: [`the stages declaration is ignored (${what}): the default machine is used`] });
65
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
66
+ return fallback('it is not an object');
67
+ const r = raw;
68
+ if (!Array.isArray(r.order) || r.order.length === 0 || !r.order.every((s) => typeof s === 'string' && s !== '')) {
69
+ return fallback('order is not a non-empty list of stage names');
70
+ }
71
+ const order = r.order;
72
+ if (new Set(order).size !== order.length)
73
+ return fallback('order names a stage twice');
74
+ const known = new Set(order);
75
+ const transitions = {};
76
+ if (r.transitions !== undefined) {
77
+ if (r.transitions === null || typeof r.transitions !== 'object' || Array.isArray(r.transitions))
78
+ return fallback('transitions is not an object');
79
+ for (const [from, tos] of Object.entries(r.transitions)) {
80
+ if (!known.has(from) || !Array.isArray(tos) || !tos.every((t) => typeof t === 'string' && known.has(t))) {
81
+ return fallback(`transitions.${from} names a stage the order does not have`);
82
+ }
83
+ transitions[from] = tos;
84
+ }
85
+ }
86
+ else {
87
+ order.forEach((s, i) => { transitions[s] = i + 1 < order.length ? [order[i + 1]] : []; });
88
+ }
89
+ let reviewed = [];
90
+ if (r.reviewed !== undefined) {
91
+ if (!Array.isArray(r.reviewed) || !r.reviewed.every((s) => typeof s === 'string' && known.has(s)))
92
+ return fallback('reviewed names a stage the order does not have');
93
+ reviewed = r.reviewed;
94
+ }
95
+ // @implements A-SPEC-781.1 — a stage's deny as declared; A-SPEC-781.2 fills in the stages it leaves out.
96
+ const deny = {};
97
+ if (r.deny !== undefined) {
98
+ if (r.deny === null || typeof r.deny !== 'object' || Array.isArray(r.deny))
99
+ return fallback('deny is not an object');
100
+ for (const [stage, actions] of Object.entries(r.deny)) {
101
+ if (!known.has(stage) || !Array.isArray(actions) || !actions.every((a) => typeof a === 'string'))
102
+ return fallback(`deny.${stage} is not a list for a known stage`);
103
+ deny[stage] = actions;
104
+ }
105
+ }
106
+ // @implements A-SPEC-781.2 — a stage the declaration leaves without deny denies by default, and says so.
107
+ const notes = [];
108
+ for (const stage of order) {
109
+ if (deny[stage] !== undefined)
110
+ continue;
111
+ const dflt = exports.DEFAULT_STAGES.deny[stage];
112
+ if (dflt !== undefined) {
113
+ deny[stage] = [...dflt];
114
+ notes.push(`stage ${stage} has no deny entry: the default (${dflt.join(', ') || 'nothing denied'}) applies`);
115
+ }
116
+ else {
117
+ deny[stage] = [...NEW_STAGE_DENY];
118
+ notes.push(`stage ${stage} has no deny entry: ${NEW_STAGE_DENY.join(', ')} are denied (declare deny.${stage}: [] to allow them)`);
119
+ }
120
+ }
121
+ const conditions = {};
122
+ const isEdge = (edge) => {
123
+ const [from, to, ...rest] = edge.split('->');
124
+ return rest.length === 0 && (transitions[from] ?? []).includes(to);
125
+ };
126
+ if (r.conditions !== undefined) {
127
+ if (r.conditions === null || typeof r.conditions !== 'object' || Array.isArray(r.conditions))
128
+ return fallback('conditions is not an object');
129
+ for (const [edge, names] of Object.entries(r.conditions)) {
130
+ if (!isEdge(edge) || !Array.isArray(names) || !names.every((n) => typeof n === 'string'))
131
+ return fallback(`conditions.${edge} is not a list for an edge of the machine`);
132
+ conditions[edge] = names;
133
+ }
134
+ }
135
+ else {
136
+ for (const [edge, names] of Object.entries(exports.DEFAULT_STAGES.conditions))
137
+ if (isEdge(edge))
138
+ conditions[edge] = [...names];
139
+ }
140
+ return { order, transitions, reviewed, deny, conditions, notes };
141
+ }
142
+ /** @implements A-SPEC-778 */
143
+ exports.RUN_REFUSAL_LIMIT_DEFAULT = 5;
144
+ /** @implements A-SPEC-779 — how long a run may wait for an operator's decision before it stops. */
145
+ exports.RUN_APPROVAL_WAIT_DEFAULT = 60;
146
+ const CEILINGS = ['off', 'tests', 'no-gate', 'default'];
43
147
  exports.DEFAULT_CONFIG = {
44
148
  // @implements A-SPEC-332
45
149
  // `warn`, not `off` and not `block`. Off left Phase 2 present in code and absent in behaviour;
@@ -51,6 +155,10 @@ exports.DEFAULT_CONFIG = {
51
155
  highRiskDomains: ['@auth', '@payment'],
52
156
  storage: { specStore: 'local-markdown' },
53
157
  architecture: { cycleIgnore: [] },
158
+ classification: { strict: false, testDirs: [] },
159
+ autonomy: { ceiling: 'default' },
160
+ run: { refusalRepeatLimit: exports.RUN_REFUSAL_LIMIT_DEFAULT, approvalWaitMinutes: exports.RUN_APPROVAL_WAIT_DEFAULT },
161
+ stages: structuredClone(exports.DEFAULT_STAGES),
54
162
  };
55
163
  function deepMerge(base, ov) {
56
164
  if (ov == null || typeof ov !== 'object')
@@ -79,9 +187,44 @@ function loadConfig(root) {
79
187
  merged.architecture = {
80
188
  cycleIgnore: Array.isArray(declared) ? declared.filter((x) => typeof x === 'string') : [],
81
189
  };
190
+ // @implements A-SPEC-775.1 — the same rule for the classification keys: strict only when literally
191
+ // true, and a declaration that is not an array of strings declares nothing.
192
+ const cls = merged.classification;
193
+ const dirs = cls && typeof cls === 'object' ? cls.testDirs : undefined;
194
+ merged.classification = {
195
+ strict: cls !== null && typeof cls === 'object' && cls.strict === true,
196
+ testDirs: Array.isArray(dirs) ? dirs.filter((x) => typeof x === 'string') : [],
197
+ };
198
+ // @implements A-SPEC-532.6 — absent is `default` (deepMerge carried the default object in); anything present that is
199
+ // not a known value, including a non-object `autonomy`, is `off`.
200
+ const auto = merged.autonomy;
201
+ const declaredCeiling = auto !== null && typeof auto === 'object' ? auto.ceiling : undefined;
202
+ merged.autonomy = {
203
+ ceiling: CEILINGS.includes(declaredCeiling) ? declaredCeiling : 'off',
204
+ };
205
+ // @implements A-SPEC-778 — only an integer from 1 to 1000 is a limit.
206
+ const runCfg = merged.run;
207
+ const limit = runCfg !== null && typeof runCfg === 'object' ? runCfg.refusalRepeatLimit : undefined;
208
+ // @implements A-SPEC-779 — and only an integer from 1 to 10080 (a week) is a wait limit.
209
+ const wait = runCfg !== null && typeof runCfg === 'object' ? runCfg.approvalWaitMinutes : undefined;
210
+ merged.run = {
211
+ refusalRepeatLimit: typeof limit === 'number' && Number.isInteger(limit) && limit >= 1 && limit <= 1000 ? limit : exports.RUN_REFUSAL_LIMIT_DEFAULT,
212
+ approvalWaitMinutes: typeof wait === 'number' && Number.isInteger(wait) && wait >= 1 && wait <= 10080 ? wait : exports.RUN_APPROVAL_WAIT_DEFAULT,
213
+ };
214
+ // @implements A-SPEC-781 — read from the file as written, not from the deep merge with the default machine.
215
+ let declaredStages;
216
+ try {
217
+ declaredStages = JSON.parse(fs.readFileSync(f, 'utf8')).stages;
218
+ }
219
+ catch {
220
+ declaredStages = undefined;
221
+ }
222
+ merged.stages = stageMachineOf(declaredStages);
82
223
  return merged;
83
224
  }
84
225
  catch {
85
- return structuredClone(exports.DEFAULT_CONFIG);
226
+ // @implements A-SPEC-476.3 — the defaults carry the widest ceiling, so a broken file raised it; it reads `off`, as a
227
+ // malformed ceiling already does (A-SPEC-532.6: a ceiling never fails toward wider).
228
+ return { ...structuredClone(exports.DEFAULT_CONFIG), autonomy: { ceiling: 'off' } };
86
229
  }
87
230
  }
@@ -0,0 +1,21 @@
1
+ import type { AutonomyCeiling } from './config';
2
+ /**
3
+ * The two owner caps ax.config.json carries, read from a text the way their readers read the file: `semantic.maxTier`
4
+ * as `readSemanticCap` (A-SPEC-476.1) and `autonomy.ceiling` as `loadConfig` (A-SPEC-532.6). `null` is "no file".
5
+ * A test holds both equal to the readers, so the gate judges the value the runtime will use.
6
+ */
7
+ export type SemanticCapValue = 'cloud' | 'local' | 'none';
8
+ export interface ProjectCaps {
9
+ semantic: SemanticCapValue;
10
+ ceiling: AutonomyCeiling;
11
+ }
12
+ export declare const NARROWEST_CAPS: ProjectCaps;
13
+ export declare function projectCapsOfText(text: string | null): ProjectCaps;
14
+ /** The caps `after` sets wider than `before` (an absent cap is its widest value, so removing a set cap is a raise). */
15
+ export declare function raisedCaps(before: ProjectCaps, after: ProjectCaps): string[];
16
+ export declare function capsAtWidest(c: ProjectCaps): boolean;
17
+ export declare function sameCaps(a: ProjectCaps, b: ProjectCaps): boolean;
18
+ /** The disk text of `<root>/ax.config.json`: `null` when absent, `undefined` when it cannot be read. */
19
+ export declare function projectConfigText(root: string): string | null | undefined;
20
+ /** The caps on disk; a file that cannot be read is the narrowest caps (nothing about it may be widened unseen). */
21
+ export declare function readProjectCaps(root: string): ProjectCaps;
@@ -0,0 +1,114 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.NARROWEST_CAPS = void 0;
37
+ exports.projectCapsOfText = projectCapsOfText;
38
+ exports.raisedCaps = raisedCaps;
39
+ exports.capsAtWidest = capsAtWidest;
40
+ exports.sameCaps = sameCaps;
41
+ exports.projectConfigText = projectConfigText;
42
+ exports.readProjectCaps = readProjectCaps;
43
+ // @implements A-SPEC-476.3
44
+ const fs = __importStar(require("node:fs"));
45
+ const path = __importStar(require("node:path"));
46
+ const SEMANTIC_ORDER = ['none', 'local', 'cloud'];
47
+ const CEILING_ORDER = ['off', 'tests', 'no-gate', 'default'];
48
+ exports.NARROWEST_CAPS = { semantic: 'none', ceiling: 'off' };
49
+ function projectCapsOfText(text) {
50
+ if (text === null)
51
+ return { semantic: 'cloud', ceiling: 'default' };
52
+ let parsed;
53
+ try {
54
+ parsed = JSON.parse(text);
55
+ }
56
+ catch {
57
+ return { ...exports.NARROWEST_CAPS };
58
+ }
59
+ const obj = parsed !== null && typeof parsed === 'object' ? parsed : null;
60
+ return { semantic: semanticOf(obj), ceiling: ceilingOf(obj) };
61
+ }
62
+ function semanticOf(obj) {
63
+ if (obj === null || !('semantic' in obj))
64
+ return 'cloud';
65
+ const s = obj.semantic;
66
+ if (s === null || typeof s !== 'object' || Array.isArray(s))
67
+ return 'none';
68
+ if (!('maxTier' in s))
69
+ return 'cloud';
70
+ const v = s.maxTier;
71
+ return SEMANTIC_ORDER.includes(v) ? v : 'none';
72
+ }
73
+ // loadConfig deep-merges over the defaults: a root that is not an object, or no `autonomy`, keeps `default`; an
74
+ // `autonomy` object without `ceiling` keeps the default object's `default`; anything else not a known value is `off`.
75
+ function ceilingOf(obj) {
76
+ if (obj === null || Array.isArray(obj) || !('autonomy' in obj))
77
+ return 'default';
78
+ const a = obj.autonomy;
79
+ if (a === null || typeof a !== 'object')
80
+ return 'off';
81
+ if (!('ceiling' in a))
82
+ return 'default';
83
+ const v = a.ceiling;
84
+ return CEILING_ORDER.includes(v) ? v : 'off';
85
+ }
86
+ /** The caps `after` sets wider than `before` (an absent cap is its widest value, so removing a set cap is a raise). */
87
+ function raisedCaps(before, after) {
88
+ const out = [];
89
+ if (SEMANTIC_ORDER.indexOf(after.semantic) > SEMANTIC_ORDER.indexOf(before.semantic))
90
+ out.push(`semantic.maxTier ${before.semantic} → ${after.semantic}`);
91
+ if (CEILING_ORDER.indexOf(after.ceiling) > CEILING_ORDER.indexOf(before.ceiling))
92
+ out.push(`autonomy.ceiling ${before.ceiling} → ${after.ceiling}`);
93
+ return out;
94
+ }
95
+ function capsAtWidest(c) {
96
+ return c.semantic === 'cloud' && c.ceiling === 'default';
97
+ }
98
+ function sameCaps(a, b) {
99
+ return a.semantic === b.semantic && a.ceiling === b.ceiling;
100
+ }
101
+ /** The disk text of `<root>/ax.config.json`: `null` when absent, `undefined` when it cannot be read. */
102
+ function projectConfigText(root) {
103
+ try {
104
+ return fs.readFileSync(path.join(root, 'ax.config.json'), 'utf8');
105
+ }
106
+ catch (e) {
107
+ return e.code === 'ENOENT' ? null : undefined;
108
+ }
109
+ }
110
+ /** The caps on disk; a file that cannot be read is the narrowest caps (nothing about it may be widened unseen). */
111
+ function readProjectCaps(root) {
112
+ const t = projectConfigText(root);
113
+ return t === undefined ? { ...exports.NARROWEST_CAPS } : projectCapsOfText(t);
114
+ }
@@ -24,7 +24,12 @@ export declare const DECISION_KINDS: ReadonlySet<string>;
24
24
  * The line a refusal ends with to name its pending request and the operator command.
25
25
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
26
26
  */
27
- export declare function pendingRequestLine(id: string, kind?: string, root?: string): string;
27
+ /**
28
+ * @implements A-SPEC-770.12 — what a request is, for a person reading its refusal: ` · <kind> <target> 「<title>」`, or ''
29
+ * without a title (A-SPEC-770.1's bytes). Every field is flattened and bounded and loses `]`, so the bracket closes once.
30
+ */
31
+ export declare function requestLabel(kind: string | undefined, target: string | undefined, title: string | undefined): string;
32
+ export declare function pendingRequestLine(id: string, kind?: string, root?: string, title?: string, target?: string): string;
28
33
  export interface RefusalRecord {
29
34
  event: 'requested';
30
35
  id: string;
@@ -36,6 +41,8 @@ export interface RefusalRecord {
36
41
  /** @implements A-SPEC-564.2 — the byte size of the deny feedback this refusal put back into the
37
42
  * conversation (base reason + queue hint). Observation only; absent on legacy records. */
38
43
  reasonBytes?: number;
44
+ /** @implements A-SPEC-779.2 — the run that filed it; absent outside a run. */
45
+ requester_run?: string;
39
46
  }
40
47
  export declare function refusalsFilename(replica: string): string;
41
48
  /** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
@@ -70,6 +77,10 @@ export interface PendingRequest {
70
77
  execution?: ExecutionContext;
71
78
  subject?: string;
72
79
  risk?: string;
80
+ /** @implements A-SPEC-770.12 — the spec's title as the first filing named it; display only. */
81
+ title?: string;
82
+ /** @implements A-SPEC-779.2 — the run that filed it, the only one that may withdraw it; absent outside a run. */
83
+ requesterRun?: string;
73
84
  }
74
85
  export interface QueueState {
75
86
  pending: PendingRequest[];
@@ -91,8 +102,9 @@ export interface QueueState {
91
102
  * retries of one blocked action, because the agent had no way to see that a human had said no.
92
103
  * An invisible decision cannot stop a retry loop.
93
104
  */
105
+ /** @implements A-SPEC-779.2 — `withdrawn`: the filing run closed its own request; no operator decided it. */
94
106
  decisions: Record<string, {
95
- event: 'granted' | 'denied' | 'revoked';
107
+ event: 'granted' | 'denied' | 'revoked' | 'withdrawn';
96
108
  reason?: string;
97
109
  ts: string;
98
110
  covered?: number;
@@ -100,6 +112,7 @@ export interface QueueState {
100
112
  consumedTs?: string;
101
113
  expires?: string;
102
114
  actor?: string;
115
+ run?: string;
103
116
  }>;
104
117
  /**
105
118
  * @implements A-SPEC-650
@@ -156,7 +169,8 @@ export declare function foldQueue(lines: string[], opts?: {
156
169
  /** @implements A-SPEC-649 — what a request may say about its subject and risk, beyond kind/target/why. */
157
170
  export interface RequestDetails {
158
171
  subject?: string;
159
- risk?: string;
172
+ risk?: string; /** @implements A-SPEC-770.12 */
173
+ title?: string;
160
174
  }
161
175
  export declare function enqueueApprovalRequest(root: string, req: {
162
176
  kind: string;
@@ -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
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,14 +99,26 @@ 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) {
101
- const command = `${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
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
114
+ // @implements A-SPEC-770.3 — the version that issued the hint, past any older copy the bare npx command resolves first.
115
+ const command = `${(0, npx_bin_1.holmesKitCommand)(root)} approve`; // A-SPEC-770.6 — the root the request is stored in
102
116
  // @implements A-SPEC-770.2 — the request lives in the refusal log / queue of the workspace whose hook refused, not in
103
117
  // the shell's cwd (measured 2026-10-12: a command run under a worktree filed its request in the development root;
104
118
  // 2026-10-13, Codex X1: the hint carried no `--target` at all). With a root, every command names it; a root with
105
119
  // white space is double-quoted once; a root is never folded or relativised. Without a root the A-SPEC-770.1 lines
106
120
  // are produced byte for byte.
107
- const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
121
+ const targetFlag = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
108
122
  // @implements A-SPEC-770 — a request outside the decision inbox (A-SPEC-563.1 routes gate refusals to the local
109
123
  // refusal log) names the id-bearing command, because the bare command opens a screen that by design does not list
110
124
  // it. Field report (jarvis, 2026-10-11): the operator ran the bare command, saw six old inbox requests, and the
@@ -112,9 +126,9 @@ function pendingRequestLine(id, kind, root) {
112
126
  // @implements A-SPEC-770.1 — the id rides the `--grant` flag: the CLI refuses a positional id (`unexpected
113
127
  // argument: req-…`, measured by the operator on 0.35.17 with the command this line used to name).
114
128
  if (kind !== undefined && !exports.DECISION_KINDS.has(kind)) {
115
- return `\n[승인 대기 ${id}] 운영자: ${command} --grant ${id}${target} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals${target} 로 조회)`;
129
+ return `\n[승인 대기 ${id}${label}] 운영자: ${command} --grant ${id}${targetFlag} — 인박스 화면에는 뜨지 않는 거부입니다(${command} --refusals${targetFlag} 로 조회)`;
116
130
  }
117
- 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}`;
118
132
  }
119
133
  const REFUSALS_FILE_RE = /^refusals\.([^.]+)\.jsonl$/;
120
134
  function refusalsFilename(replica) {
@@ -255,6 +269,8 @@ function foldQueue(lines, opts) {
255
269
  ...(execution ? { execution } : {}),
256
270
  ...(typeof e.subject === 'string' && e.subject !== '' ? { subject: e.subject } : {}),
257
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
258
274
  });
259
275
  }
260
276
  break;
@@ -291,6 +307,22 @@ function foldQueue(lines, opts) {
291
307
  decisions[id] = { event: 'revoked', ...(typeof e.reason === 'string' ? { reason: e.reason } : {}), ts: typeof e.ts === 'string' ? e.ts : '', ...(execution ? { execution } : {}) };
292
308
  }
293
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;
294
326
  case 'held': {
295
327
  const entry = id ? pending.get(id) : undefined;
296
328
  if (entry) {
@@ -376,6 +408,14 @@ function enqueueApprovalRequestDetailed(root, req) {
376
408
  catch {
377
409
  execution = undefined;
378
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
+ }
379
419
  const event = {
380
420
  event: 'requested',
381
421
  id: approvalRequestId(req.kind, req.target),
@@ -387,6 +427,8 @@ function enqueueApprovalRequestDetailed(root, req) {
387
427
  ...(execution ? { execution } : {}),
388
428
  ...(typeof req.subject === 'string' && req.subject !== '' ? { subject: req.subject } : {}),
389
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 } : {}),
390
432
  // @implements A-SPEC-564.2 — only the refusal log carries the feedback cost; inbox kinds have
391
433
  // no deny text to measure.
392
434
  ...(!exports.DECISION_KINDS.has(req.kind) && typeof req.reasonBytes === 'number' && Number.isFinite(req.reasonBytes)
@@ -527,7 +569,7 @@ function queueHint(root, req, opts) {
527
569
  + `\n운영자 검토: ${opts.reviewCommand}`;
528
570
  }
529
571
  return (0, screen_safe_1.wrapColumns)(question
530
- + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 내립니다.`, 76, ' \u2502 ');
572
+ + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.holmesKitCommand)(root)} approve 에서 내립니다.`, 76, ' \u2502 ');
531
573
  }
532
574
  const decided = state.decisions[id];
533
575
  const denialLine = decided?.event === 'denied'
@@ -536,7 +578,7 @@ function queueHint(root, req, opts) {
536
578
  // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
537
579
  // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
538
580
  // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
539
- 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
540
582
  return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
541
583
  ? hint
542
584
  : denialLine;
@@ -635,5 +677,6 @@ function asPendingRequest(id, occurrences) {
635
677
  firstTs: occurrences[0].ts,
636
678
  lastTs: latest.ts,
637
679
  ...(latest.replica ? { replica: latest.replica } : {}),
680
+ ...(latest.requester_run ? { requesterRun: latest.requester_run } : {}), // @implements A-SPEC-779.2
638
681
  };
639
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