@holmes-lab/holmes-kit 0.37.2 → 0.39.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 (59) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +17 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +2 -1
  5. package/dist/holmes/cli/approve.d.ts +1 -0
  6. package/dist/holmes/cli/approve.js +36 -4
  7. package/dist/holmes/cli/autonomy.d.ts +28 -0
  8. package/dist/holmes/cli/autonomy.js +62 -8
  9. package/dist/holmes/cli/doctor.js +12 -1
  10. package/dist/holmes/cli/index.js +64 -5
  11. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  12. package/dist/holmes/cli/mcp-processes.js +132 -0
  13. package/dist/holmes/cli/run-provision.d.ts +6 -0
  14. package/dist/holmes/cli/run-provision.js +114 -0
  15. package/dist/holmes/cli/run.d.ts +5 -0
  16. package/dist/holmes/cli/run.js +38 -6
  17. package/dist/holmes/cli/runtime-binding-approval.js +2 -3
  18. package/dist/holmes/governance/approval-queue.d.ts +12 -1
  19. package/dist/holmes/governance/approval-queue.js +23 -28
  20. package/dist/holmes/governance/autonomy.d.ts +3 -1
  21. package/dist/holmes/governance/autonomy.js +28 -2
  22. package/dist/holmes/governance/full-autonomy.d.ts +72 -0
  23. package/dist/holmes/governance/full-autonomy.js +308 -0
  24. package/dist/holmes/governance/tool-actions.js +2 -0
  25. package/dist/holmes/guardrail/operator-person.js +3 -2
  26. package/dist/holmes/guardrail/refusal-codes.js +19 -4
  27. package/dist/holmes/guardrail/risk-classifier.js +21 -3
  28. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  29. package/dist/holmes/guardrail/run-refusals.js +19 -12
  30. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  31. package/dist/holmes/guardrail/run-stages.js +23 -3
  32. package/dist/holmes/guardrail/write-target.js +4 -1
  33. package/dist/holmes/hooks/pre-tool-use.d.ts +2 -0
  34. package/dist/holmes/hooks/pre-tool-use.js +88 -11
  35. package/dist/holmes/hooks/session-start.d.ts +5 -0
  36. package/dist/holmes/hooks/session-start.js +29 -1
  37. package/dist/holmes/hooks/stop.js +6 -4
  38. package/dist/holmes/mcp/elicit-approval.js +5 -6
  39. package/dist/holmes/mcp/handlers/approval-ask.d.ts +11 -0
  40. package/dist/holmes/mcp/handlers/approval-ask.js +18 -3
  41. package/dist/holmes/mcp/handlers/review-verdict.js +3 -2
  42. package/dist/holmes/mcp/handlers/spec-approval.d.ts +2 -0
  43. package/dist/holmes/mcp/handlers/spec-approval.js +23 -5
  44. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  45. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  46. package/dist/holmes/mcp/handlers.d.ts +12 -0
  47. package/dist/holmes/mcp/handlers.js +25 -3
  48. package/dist/holmes/mcp/operator-recovery.d.ts +7 -2
  49. package/dist/holmes/mcp/operator-recovery.js +15 -58
  50. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  51. package/dist/holmes/mcp/server-staleness.js +158 -0
  52. package/dist/holmes/mcp/server.js +26 -2
  53. package/dist/holmes/mcp/tool-schemas.js +14 -1
  54. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  55. package/dist/holmes/project/workspace-preflight.js +24 -1
  56. package/dist/holmes/review/verdicts.d.ts +5 -0
  57. package/dist/holmes/review/verdicts.js +16 -1
  58. package/package.json +1 -1
  59. package/playbooks/promote-slice/PLAYBOOK.md +2 -1
@@ -0,0 +1,72 @@
1
+ export declare const FULL_PROFILE_FILE: readonly [".holmes", "full-autonomy.json"];
2
+ export declare const FULL_PROFILE_SCHEMA = "full-autonomy/1";
3
+ export interface FullProfileFlags {
4
+ push: boolean;
5
+ publish: boolean;
6
+ architecture: boolean;
7
+ }
8
+ export interface FullProfileEntry {
9
+ scope: string;
10
+ flags: FullProfileFlags;
11
+ issuedAt: string;
12
+ issuedBy: string;
13
+ }
14
+ export type FullProfileState = {
15
+ active: true;
16
+ entry: FullProfileEntry;
17
+ } | {
18
+ active: false;
19
+ why: 'none' | 'unreadable' | 'invalid' | 'outside';
20
+ };
21
+ /** The entry covering `workspace` by real path; the longest scope wins. Fail-closed on every malformed shape. */
22
+ export declare function readFullProfile(home: string, workspace: string): FullProfileState;
23
+ export type FullSealVerdict = {
24
+ outcome: 'seal';
25
+ mark: string;
26
+ } | {
27
+ outcome: 'refuse';
28
+ route: string;
29
+ };
30
+ /**
31
+ * @implements A-SPEC-792.4 — what a full scope does with a seal the grader hands to a person: seal it, or refuse it at
32
+ * once with the step that needs no person. Three rules are refused because sealing them would seal something nobody
33
+ * declared (an un-admitted requirement, an undeclared or unknown grade); an architecture document follows its flag.
34
+ */
35
+ export declare function fullSealVerdict(rule: string, flags: FullProfileFlags): FullSealVerdict;
36
+ export type FullShellVerdict = {
37
+ outcome: 'approve';
38
+ recovery: boolean;
39
+ } | {
40
+ outcome: 'refuse';
41
+ route: string;
42
+ };
43
+ /**
44
+ * @implements A-SPEC-792.5 — what a full scope does with a hard-HITL shell verdict. Every reason must be approvable:
45
+ * a workspace-local destructive git act, an rm whose every target sits strictly inside the scope or the scratch root,
46
+ * or a force push the profile allows. Anything else — and anything whose landing place cannot be proven — is refused
47
+ * with a route. The classifier's verdict is never changed; only what happens to it.
48
+ */
49
+ export declare function fullModeShellVerdict(input: {
50
+ command: string;
51
+ reasons: readonly string[];
52
+ cwd: string;
53
+ workspace: string;
54
+ scratchRoot: string | null;
55
+ entry: FullProfileEntry;
56
+ }): FullShellVerdict;
57
+ /** The tail a full-scope refusal carries instead of a queued request (config, secrets, approvals, code under debt). */
58
+ export declare function fullModeRefusalTail(kind: 'shell' | 'config-write' | 'code-write', route?: string): string;
59
+ /**
60
+ * @implements A-SPEC-792.5 — the recovery point a full-scope destructive act needs first: the whole work tree (tracked
61
+ * and untracked, not ignored) committed through a temporary index and kept under `refs/holmes/full/`. Bounded git calls;
62
+ * any failure is returned so the act is refused.
63
+ */
64
+ export declare function writeRecoveryRef(workspace: string, now: string): {
65
+ ref: string;
66
+ } | {
67
+ error: string;
68
+ };
69
+ /** Add or replace the entry for `entry.scope` (the caller holds the operator proof). */
70
+ export declare function addFullProfileEntry(home: string, entry: FullProfileEntry): void;
71
+ /** Remove the entry for `scope`, or every entry; returns how many went. Revoking needs no proof. */
72
+ export declare function removeFullProfileEntry(home: string, scope?: string): number;
@@ -0,0 +1,308 @@
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.FULL_PROFILE_SCHEMA = exports.FULL_PROFILE_FILE = void 0;
37
+ exports.readFullProfile = readFullProfile;
38
+ exports.fullSealVerdict = fullSealVerdict;
39
+ exports.fullModeShellVerdict = fullModeShellVerdict;
40
+ exports.fullModeRefusalTail = fullModeRefusalTail;
41
+ exports.writeRecoveryRef = writeRecoveryRef;
42
+ exports.addFullProfileEntry = addFullProfileEntry;
43
+ exports.removeFullProfileEntry = removeFullProfileEntry;
44
+ // @implements A-SPEC-792.3, A-SPEC-792.4, A-SPEC-792.5
45
+ // The full autonomy profile (REQ-792) — the fifth envelope. The owner names, once, the scopes (a workspace or a root of
46
+ // workspaces) where no judgment may wait for a person. It lives at user level because a benchmark copies its arm for
47
+ // every run and a workspace-bound document (the run delegation, A-SPEC-771) does not follow the copy. The CLI writes it
48
+ // under operator proof; the gate protects it as user config (A-SPEC-728); anything malformed covers nothing.
49
+ const fs = __importStar(require("node:fs"));
50
+ const path = __importStar(require("node:path"));
51
+ exports.FULL_PROFILE_FILE = ['.holmes', 'full-autonomy.json'];
52
+ exports.FULL_PROFILE_SCHEMA = 'full-autonomy/1';
53
+ const ENTRY_KEYS = new Set(['scope', 'flags', 'issuedAt', 'issuedBy']);
54
+ const FLAG_KEYS = ['push', 'publish', 'architecture'];
55
+ const MAX_BYTES = 64 * 1024;
56
+ function realOrNull(p) {
57
+ try {
58
+ return fs.realpathSync.native(p);
59
+ }
60
+ catch {
61
+ return null;
62
+ }
63
+ }
64
+ const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
65
+ /** `scope` covers `target` (both real paths) at a path-segment boundary. */
66
+ function covers(scope, target) {
67
+ const s = fold(scope);
68
+ const t = fold(target);
69
+ return t === s || t.startsWith(s.endsWith(path.sep) ? s : s + path.sep);
70
+ }
71
+ /** One entry, or null when it is not exactly what the CLI writes: closed keys, an absolute real scope, boolean flags. */
72
+ function entryOf(raw) {
73
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw))
74
+ return null;
75
+ const e = raw;
76
+ if (Object.keys(e).some((k) => !ENTRY_KEYS.has(k)))
77
+ return null;
78
+ if (typeof e.scope !== 'string' || !path.isAbsolute(e.scope))
79
+ return null;
80
+ // A scope that is not its own real path (relative pieces, a link) could be re-pointed after issue: it covers nothing.
81
+ if (realOrNull(e.scope) !== e.scope)
82
+ return null;
83
+ const f = e.flags;
84
+ if (!f || typeof f !== 'object' || Object.keys(f).some((k) => !FLAG_KEYS.includes(k)))
85
+ return null;
86
+ if (FLAG_KEYS.some((k) => typeof f[k] !== 'boolean'))
87
+ return null;
88
+ if (typeof e.issuedAt !== 'string' || typeof e.issuedBy !== 'string')
89
+ return null;
90
+ return { scope: e.scope, flags: { push: f.push, publish: f.publish, architecture: f.architecture }, issuedAt: e.issuedAt, issuedBy: e.issuedBy };
91
+ }
92
+ function readEntries(home) {
93
+ const file = path.join(home, ...exports.FULL_PROFILE_FILE);
94
+ let raw;
95
+ try {
96
+ const st = fs.lstatSync(file);
97
+ if (!st.isFile() || st.size > MAX_BYTES)
98
+ return { why: 'invalid' };
99
+ raw = fs.readFileSync(file, 'utf8');
100
+ }
101
+ catch (e) {
102
+ return e.code === 'ENOENT' ? { why: 'none' } : { why: 'unreadable' };
103
+ }
104
+ let doc;
105
+ try {
106
+ doc = JSON.parse(raw);
107
+ }
108
+ catch {
109
+ return { why: 'unreadable' };
110
+ }
111
+ const d = doc;
112
+ if (!d || typeof d !== 'object' || d.schema !== exports.FULL_PROFILE_SCHEMA || !Array.isArray(d.entries))
113
+ return { why: 'invalid' };
114
+ const entries = d.entries.map(entryOf);
115
+ // One forged entry voids the file: the CLI never writes one, so its presence says the file was edited by hand.
116
+ if (entries.some((e) => e === null))
117
+ return { why: 'invalid' };
118
+ return { entries: entries };
119
+ }
120
+ /** The entry covering `workspace` by real path; the longest scope wins. Fail-closed on every malformed shape. */
121
+ function readFullProfile(home, workspace) {
122
+ const r = readEntries(home);
123
+ if ('why' in r)
124
+ return { active: false, why: r.why };
125
+ const target = realOrNull(workspace);
126
+ if (target === null)
127
+ return { active: false, why: 'outside' };
128
+ const hit = r.entries.filter((e) => covers(e.scope, target)).sort((a, b) => b.scope.length - a.scope.length)[0];
129
+ return hit ? { active: true, entry: hit } : { active: false, why: r.entries.length === 0 ? 'none' : 'outside' };
130
+ }
131
+ function writeEntries(home, entries) {
132
+ const file = path.join(home, ...exports.FULL_PROFILE_FILE);
133
+ fs.mkdirSync(path.dirname(file), { recursive: true });
134
+ const tmp = `${file}.${process.pid}.tmp`;
135
+ fs.writeFileSync(tmp, JSON.stringify({ schema: exports.FULL_PROFILE_SCHEMA, entries }, null, 2) + '\n', { mode: 0o600 });
136
+ fs.renameSync(tmp, file);
137
+ }
138
+ /** The bare grader rule an upstream reason resolves to (`upstream-has-human-aspec: <id> — <child>` → the child's). */
139
+ function bareRule(rule) {
140
+ const upstream = /^upstream-has-human-aspec: \S+ — (.+)$/.exec(rule);
141
+ return (upstream ? upstream[1] : rule).split(':')[0].trim();
142
+ }
143
+ /**
144
+ * @implements A-SPEC-792.4 — what a full scope does with a seal the grader hands to a person: seal it, or refuse it at
145
+ * once with the step that needs no person. Three rules are refused because sealing them would seal something nobody
146
+ * declared (an un-admitted requirement, an undeclared or unknown grade); an architecture document follows its flag.
147
+ */
148
+ function fullSealVerdict(rule, flags) {
149
+ switch (bareRule(rule)) {
150
+ case 'requirement-without-intake':
151
+ return { outcome: 'refuse', route: 'run requirement_triage({ persist: true }) on the requirement\'s prompt and record its triage_evidence on the REQ, then seal again' };
152
+ case 'breaking-change-undeclared':
153
+ return { outcome: 'refuse', route: 'declare breaking_change with one of the grader\'s grades, then seal again' };
154
+ case 'unknown-kind':
155
+ return { outcome: 'refuse', route: 'the spec kind is not one the grader knows — use REQ, H-SPEC, A-SPEC, C-SPEC, T-SPEC or ADR' };
156
+ case 'architecture-document':
157
+ return flags.architecture
158
+ ? { outcome: 'seal', mark: ' [architecture document sealed under full autonomy]' }
159
+ : { outcome: 'refuse', route: 'this full profile keeps architecture documents with the owner (issued with --no-architecture)' };
160
+ default:
161
+ return { outcome: 'seal', mark: '' };
162
+ }
163
+ }
164
+ /** Reasons a full scope may approve, by the classifier's own words (risk-classifier.ts), with whether a ref is needed. */
165
+ const WORKSPACE_GIT_ACTS = [/^git reset --hard\b/, /^git clean -f\b/, /^git restore\/checkout \./, /^git branch -D\b/];
166
+ const RM_ACTS = [/^recursive rm of a catastrophic/, /^rm -rf of an unverified target/];
167
+ /** A command that may land somewhere other than the workspace it is judged in. */
168
+ const ELSEWHERE = /(?:^|[\s;&|(`])(?:cd|pushd|chdir)(?:\s|$)|\bgit\s+(?:-C\b|--git-dir\b|--work-tree\b)/;
169
+ /** Text whose targets are only known when the shell runs it. */
170
+ const UNPROVABLE = /[$`*?[\]{}~]|\\/;
171
+ /** Tokens of every `rm` segment, flags dropped; null when a segment cannot be read as plain words. */
172
+ function rmTargetsOf(command) {
173
+ const out = [];
174
+ for (const seg of command.split(/&&|\|\||[;|\n]/)) {
175
+ const words = seg.trim().split(/\s+/).filter(Boolean);
176
+ if (words[0] !== 'rm')
177
+ continue;
178
+ let options = true;
179
+ for (const w of words.slice(1)) {
180
+ if (options && w === '--') {
181
+ options = false;
182
+ continue;
183
+ }
184
+ if (options && w.startsWith('-'))
185
+ continue;
186
+ const t = w.replace(/^(["'])(.*)\1$/, '$2');
187
+ if (UNPROVABLE.test(t) || /["']/.test(t))
188
+ return null;
189
+ out.push(t);
190
+ }
191
+ }
192
+ return out;
193
+ }
194
+ /** The entry's real location: the parent resolved, the last name not followed (rm removes a link, not its target). */
195
+ function entryReal(cwd, target) {
196
+ const abs = path.resolve(cwd, target);
197
+ const parent = realOrNull(path.dirname(abs));
198
+ return parent === null ? null : path.join(parent, path.basename(abs));
199
+ }
200
+ /**
201
+ * @implements A-SPEC-792.5 — what a full scope does with a hard-HITL shell verdict. Every reason must be approvable:
202
+ * a workspace-local destructive git act, an rm whose every target sits strictly inside the scope or the scratch root,
203
+ * or a force push the profile allows. Anything else — and anything whose landing place cannot be proven — is refused
204
+ * with a route. The classifier's verdict is never changed; only what happens to it.
205
+ */
206
+ function fullModeShellVerdict(input) {
207
+ const { command, reasons, entry } = input;
208
+ if (ELSEWHERE.test(command)) {
209
+ return { outcome: 'refuse', route: 'the command changes directory or names another work tree, so where it lands cannot be proven — run the act from the workspace without cd, pushd or git -C' };
210
+ }
211
+ let recovery = false;
212
+ for (const reason of reasons) {
213
+ if (/^git push --force/.test(reason)) {
214
+ if (!entry.flags.push)
215
+ return { outcome: 'refuse', route: 'this full profile keeps force pushes with the owner (issued without --allow-push)' };
216
+ continue;
217
+ }
218
+ if (WORKSPACE_GIT_ACTS.some((re) => re.test(reason))) {
219
+ recovery = true;
220
+ continue;
221
+ }
222
+ if (RM_ACTS.some((re) => re.test(reason))) {
223
+ const targets = rmTargetsOf(command);
224
+ if (targets === null || targets.length === 0)
225
+ return { outcome: 'refuse', route: 'an rm whose targets are only known when the shell runs it (globs, variables, quotes) cannot be proven inside the scope — name each target literally' };
226
+ const workspace = realOrNull(input.workspace) ?? input.workspace;
227
+ for (const t of targets) {
228
+ const real = entryReal(input.cwd, t);
229
+ if (real === null)
230
+ return { outcome: 'refuse', route: `cannot resolve ${t} — name a target whose parent directory exists` };
231
+ const inScratch = input.scratchRoot !== null && covers(input.scratchRoot, real) && fold(real) !== fold(input.scratchRoot);
232
+ const inScope = covers(entry.scope, real) && fold(real) !== fold(entry.scope) && !covers(real, workspace);
233
+ if (!inScratch && !inScope)
234
+ return { outcome: 'refuse', route: `${t} resolves outside the full scope (${entry.scope}) and the scratch root — full autonomy removes only what lies inside them` };
235
+ if (!inScratch && covers(workspace, real))
236
+ recovery = true;
237
+ }
238
+ continue;
239
+ }
240
+ return { outcome: 'refuse', route: `full autonomy approves only workspace-local destructive git acts and scoped rm; this act (${reason.split(' — ')[0]}) is refused` };
241
+ }
242
+ return { outcome: 'approve', recovery };
243
+ }
244
+ /** The tail a full-scope refusal carries instead of a queued request (config, secrets, approvals, code under debt). */
245
+ function fullModeRefusalTail(kind, route) {
246
+ const why = route ?? (kind === 'code-write'
247
+ ? 'resolve the constitution debt this refusal names'
248
+ : 'this act widens the agent\'s own authority (configuration, secrets or approvals) and is refused without asking');
249
+ return ` — full autonomy: ${why}; no approval request was filed`;
250
+ }
251
+ /**
252
+ * @implements A-SPEC-792.5 — the recovery point a full-scope destructive act needs first: the whole work tree (tracked
253
+ * and untracked, not ignored) committed through a temporary index and kept under `refs/holmes/full/`. Bounded git calls;
254
+ * any failure is returned so the act is refused.
255
+ */
256
+ function writeRecoveryRef(workspace, now) {
257
+ const { execFileSync } = require('node:child_process');
258
+ const os = require('node:os');
259
+ const run = (args, env) => execFileSync('git', args, {
260
+ cwd: workspace, encoding: 'utf8', timeout: 20_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
261
+ env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: '0' },
262
+ }).trim();
263
+ let step = 'git rev-parse HEAD';
264
+ const index = path.join(os.tmpdir(), `holmes-full-${process.pid}-${Date.now()}.index`);
265
+ try {
266
+ const head = run(['rev-parse', '--verify', 'HEAD']);
267
+ step = 'git add -A (temporary index)';
268
+ run(['add', '-A'], { GIT_INDEX_FILE: index });
269
+ step = 'git write-tree';
270
+ const tree = run(['write-tree'], { GIT_INDEX_FILE: index });
271
+ step = 'git commit-tree';
272
+ const commit = run(['commit-tree', tree, '-p', head, '-m', `holmes full-autonomy recovery point ${now}`], { GIT_AUTHOR_NAME: 'holmes-kit', GIT_AUTHOR_EMAIL: 'holmes-kit@localhost', GIT_COMMITTER_NAME: 'holmes-kit', GIT_COMMITTER_EMAIL: 'holmes-kit@localhost' });
273
+ step = 'git update-ref';
274
+ const ref = `refs/holmes/full/${now.replace(/[^0-9TZ]/g, '')}-${commit.slice(0, 8)}`;
275
+ run(['update-ref', ref, commit]);
276
+ return { ref };
277
+ }
278
+ catch (e) {
279
+ return { error: `the recovery point could not be written (${step}: ${String(e.message ?? e).split('\n')[0].slice(0, 160)})` };
280
+ }
281
+ finally {
282
+ fs.rmSync(index, { force: true });
283
+ }
284
+ }
285
+ /** Add or replace the entry for `entry.scope` (the caller holds the operator proof). */
286
+ function addFullProfileEntry(home, entry) {
287
+ const r = readEntries(home);
288
+ const kept = 'entries' in r ? r.entries.filter((e) => fold(e.scope) !== fold(entry.scope)) : [];
289
+ writeEntries(home, [...kept, entry]);
290
+ }
291
+ /** Remove the entry for `scope`, or every entry; returns how many went. Revoking needs no proof. */
292
+ function removeFullProfileEntry(home, scope) {
293
+ const r = readEntries(home);
294
+ if (!('entries' in r)) {
295
+ // An unreadable or forged file is removed whole when everything is revoked; a single-scope revoke leaves it.
296
+ if (scope === undefined && r.why !== 'none') {
297
+ fs.rmSync(path.join(home, ...exports.FULL_PROFILE_FILE), { force: true });
298
+ return 1;
299
+ }
300
+ return 0;
301
+ }
302
+ const want = scope === undefined ? null : fold(realOrNull(scope) ?? scope);
303
+ const kept = want === null ? [] : r.entries.filter((e) => fold(e.scope) !== want);
304
+ const removed = r.entries.length - kept.length;
305
+ if (removed > 0)
306
+ writeEntries(home, kept);
307
+ return removed;
308
+ }
@@ -42,6 +42,8 @@ exports.TOOL_ACTIONS = {
42
42
  approval_status: NONE, rtm_dashboard: NONE,
43
43
  // @implements A-SPEC-718.4 — the person decides in the form; the agent only asks, so no role act is the agent's.
44
44
  approval_ask: NONE,
45
+ // @implements A-SPEC-774 — approval_withdraw (A-SPEC-779.7) withdraws the server's own request and decides nothing.
46
+ approval_withdraw: NONE,
45
47
  // @implements A-SPEC-102.9 — it writes a review verdict, the act a role policy names RECORD_REVIEW.
46
48
  review_verdict: always('RECORD_REVIEW'),
47
49
  // approval_commit changes only the server's in-memory continuation; the act it completes is spec_approve's
@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.agentProcessReason = agentProcessReason;
4
4
  exports.setOperatorProbeForTests = setOperatorProbeForTests;
5
5
  exports.operatorActGuard = operatorActGuard;
6
- // @implements A-SPEC-779.4, A-SPEC-779.6
6
+ // @implements A-SPEC-779.4, A-SPEC-779.6, A-SPEC-792.1
7
7
  /**
8
8
  * Who may grant. The refusal text prints the very command that approves it, so a model following that text from its
9
9
  * own shell approved itself (measured on 0.36.1). A granting act here refuses a process that an agent harness started:
@@ -38,6 +38,7 @@ function operatorActGuard(act) {
38
38
  const remedy = why.startsWith(UNREADABLE)
39
39
  ? 'The operator decides in the session\'s approval dialog (approval_ask) — this process\'s parents could not be read, '
40
40
  + 'so it cannot be told apart from an agent\'s.'
41
- : 'The operator decides in the session\'s approval dialog, or from their own terminal.';
41
+ // @implements A-SPEC-792.1 — the dialog only; a typed command is not offered.
42
+ : 'The operator decides in the session\'s approval dialog (approval_ask).';
42
43
  return `${act} is the operator's — this process runs under an agent harness (${why}). ${remedy}`;
43
44
  }
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
- // @implements A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4
2
+ // @implements A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8, A-SPEC-792.9
3
3
  /**
4
4
  * @implements A-SPEC-777 — a refusal's kind, readable by a program. An orchestrator retries a `retryable` refusal,
5
5
  * pauses for a person on `needs_hitl`, and changes its plan on `permanent`. The prose stays for people; the line
@@ -17,7 +17,8 @@ exports.REFUSAL_CODES = [
17
17
  {
18
18
  // @implements A-SPEC-779 — a run waiting for the operator's decision: retry after it, never around it.
19
19
  code: 'run.awaiting-approval', class: 'retryable',
20
- remediation: ['wait: the operator decides the request in a terminal', 'retry after the decision; do not work around it'],
20
+ // @implements A-SPEC-792.1 — the session form, never a typed command.
21
+ remediation: ['wait: the person decides the request in the interactive session\'s approval form', 'retry after the decision; do not work around it'],
21
22
  test: /this run is awaiting approval/i,
22
23
  },
23
24
  {
@@ -26,6 +27,13 @@ exports.REFUSAL_CODES = [
26
27
  remediation: ['stop working in this run', 'the operator ends it with holmes-kit run stop and starts a new run'],
27
28
  test: /this run stopped|this run is now stopped|this run stalled|was not decided within|the Holmes install changed since run start/i, // A-SPEC-778.1/778.2: stalled
28
29
  },
30
+ {
31
+ // @implements A-SPEC-792.8 — under a full profile nothing was filed and no person decides; ahead of every row that
32
+ // would send an orchestrator to approval_ask or to the operator.
33
+ code: 'full-autonomy.refused', class: 'permanent',
34
+ remediation: ['no person decides this: full autonomy refused it without filing a request — do not call approval_ask', 'follow the route the refusal names, or change the plan'],
35
+ test: /full autonomy: [^\n]*no approval request was filed/i,
36
+ },
29
37
  {
30
38
  code: 'gate.unjudgeable', class: 'retryable',
31
39
  remediation: ['split the command or edit into smaller parts', 'retry; if it repeats, ask the operator'],
@@ -56,7 +64,7 @@ exports.REFUSAL_CODES = [
56
64
  {
57
65
  // @implements A-SPEC-779.1 — a grant refused because it is not the operator's, or a run may await it.
58
66
  code: 'grant.operator-only', class: 'needs_hitl',
59
- remediation: ['the operator grants the request from their own terminal'],
67
+ remediation: ['call approval_ask with the request id — the person decides in the session approval form'],
60
68
  // @implements A-SPEC-779.4 — and a granting act from a process an agent harness started.
61
69
  test: /a grant is the operator's|is awaited by run|cannot tell whether a run awaits|runs under an agent harness/i,
62
70
  },
@@ -69,7 +77,8 @@ exports.REFUSAL_CODES = [
69
77
  {
70
78
  code: 'approval.required', class: 'needs_hitl',
71
79
  // @implements A-SPEC-718.5 — the in-session route first; the terminal command is the operator's alternative.
72
- remediation: ['call approval_ask with the request id — the person decides in the session form', 'or the operator runs the approve command the refusal names'],
80
+ // A-SPEC-792.1 — the session form is the one route; no command to run is offered.
81
+ remediation: ['call approval_ask with the request id — the person decides in the session form', 'after the decision, retry the refused act once'],
73
82
  // @implements A-SPEC-476.4 — and raising an owner cap, or a shell write over one (A-SPEC-476.3).
74
83
  test: /hard-hitl|Integrity\]|Governance Path Destruction|requires operator|raises or removes a project cap|sets a project cap/i,
75
84
  },
@@ -109,6 +118,12 @@ exports.REFUSAL_CODES = [
109
118
  remediation: ['write a patch that applies to the file as it stands, with at least one + or - line', 'or use the Edit tool'],
110
119
  test: /the patch (?:does not apply|to\b)|patch tool or a patch marker/i,
111
120
  },
121
+ {
122
+ // @implements A-SPEC-792.9 — a spec write whose result the store cannot parse.
123
+ code: 'spec.unreadable', class: 'permanent',
124
+ remediation: ['fix the frontmatter in the same write: a value holding \' or : goes in double quotes, or in a >- block', 'or scaffold the spec again with spec_create'],
125
+ test: /unreadable to the spec store|the write would leave/i,
126
+ },
112
127
  {
113
128
  code: 'shell.code-write', class: 'permanent',
114
129
  remediation: ['write project code through the Edit or Write tool, not the shell'],
@@ -47,7 +47,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
47
47
  exports.classifySecret = classifySecret;
48
48
  exports.classifyBlastRadius = classifyBlastRadius;
49
49
  exports.assessRisk = assessRisk;
50
- // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4
50
+ // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4, A-SPEC-773.5
51
51
  const fs = __importStar(require("node:fs"));
52
52
  const path = __importStar(require("node:path"));
53
53
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -1800,10 +1800,28 @@ function classifyReversibility(action) {
1800
1800
  const raw = action.command ?? '';
1801
1801
  const joined = raw === '' ? raw : (0, write_target_2.joinShellText)(raw);
1802
1802
  if (joined === raw)
1803
- return classifyReversibilityAsWritten(action);
1803
+ return withAxCwdNote(classifyReversibilityAsWritten(action), action);
1804
1804
  const a = classifyReversibilityAsWritten(action);
1805
1805
  const b = classifyReversibilityAsWritten({ ...action, command: joined });
1806
- return (0, risk_types_1.maxLevel)(a.level, b.level) === a.level ? a : b;
1806
+ return withAxCwdNote((0, risk_types_1.maxLevel)(a.level, b.level) === a.level ? a : b, action);
1807
+ }
1808
+ /**
1809
+ * @implements A-SPEC-773.5 — G0 round 5: an agent left in .ax/specs by one `cd … && find` had six later commands refused
1810
+ * over .ax (pytest included) with no cause named. The verdict is unchanged; the first .ax reason names the working
1811
+ * directory and the one command that leaves it. Containment is by path, so `.axolotl` is not inside.
1812
+ */
1813
+ function withAxCwdNote(verdict, action) {
1814
+ if (verdict.level !== 'hard-hitl' || !action.cwd || !action.projectRoot)
1815
+ return verdict;
1816
+ const rel = path.relative(path.join(action.projectRoot, '.ax'), action.cwd);
1817
+ if (rel.startsWith('..') || path.isAbsolute(rel))
1818
+ return verdict;
1819
+ const i = verdict.reasons.findIndex((r) => /protected \.ax governance path/.test(r));
1820
+ if (i < 0)
1821
+ return verdict;
1822
+ const where = path.relative(action.projectRoot, action.cwd);
1823
+ const note = `; this shell's working directory (${where}) is inside .ax, so every command run there is judged over .ax: run \`cd ${action.projectRoot}\` on its own first, then the command`;
1824
+ return { ...verdict, reasons: verdict.reasons.map((r, j) => (j === i ? r + note : r)) };
1807
1825
  }
1808
1826
  function classifyReversibilityAsWritten(action) {
1809
1827
  const axis = 'reversibility';
@@ -4,7 +4,11 @@ type Install = {
4
4
  };
5
5
  export interface RunRefusalEvent {
6
6
  ts: string;
7
- event: 'refusal' | 'awaiting_approval' | 'approval_resolved' | 'approval_expired' | 'install_changed' | 'stage' | 'versions_accepted' | 'stages_interpreted' | 'stop_blocked' | 'stalled';
7
+ event: 'refusal' | 'awaiting_approval' | 'approval_resolved' | 'approval_expired' | 'install_changed' | 'stage' | 'versions_accepted' | 'stages_interpreted' | 'stop_blocked' | 'stalled' | 'review_unresolved';
8
+ /** @implements A-SPEC-102.10 — on `review_unresolved`: the cap, the range, and the last failing round's findings. */
9
+ cap?: number;
10
+ range?: string;
11
+ findings?: string[];
8
12
  /** @implements A-SPEC-778.1 — the constitution articles a blocked Stop named. */
9
13
  articles?: string[];
10
14
  /** @implements A-SPEC-778.1 — on `stalled`: how many Stops in a row were blocked. */
@@ -44,6 +48,7 @@ type Stop = {
44
48
  current: Install;
45
49
  };
46
50
  articles?: string[];
51
+ findings?: string[];
47
52
  };
48
53
  /** The first code refused `limit` times or more, with its count, the expired approval wait, or an install change; else null. */
49
54
  export declare function stoppedBy(events: readonly RunRefusalEvent[], limit: number): Stop | null;
@@ -45,7 +45,7 @@ exports.applyRunRefusalStop = applyRunRefusalStop;
45
45
  exports.recordRunStopBlock = recordRunStopBlock;
46
46
  exports.runState = runState;
47
47
  exports.grantGuard = grantGuard;
48
- // @implements A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781, A-SPEC-780.1, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-770.12, A-SPEC-778.1, A-SPEC-779.2
48
+ // @implements A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781, A-SPEC-780.1, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-770.12, A-SPEC-778.1, A-SPEC-779.2, A-SPEC-792.1, A-SPEC-102.10
49
49
  /**
50
50
  * @implements A-SPEC-778 — a refusal loop in a run ends in a stop the orchestrator can read, not in a used-up budget.
51
51
  * Every PreToolUse refusal of a run is appended to `<main>/.ax/state/run-refusals/<run>.jsonl` (a protected path the
@@ -112,6 +112,10 @@ function stoppedBy(events, limit) {
112
112
  const stalled = events.find((e) => e.event === 'stalled');
113
113
  if (stalled)
114
114
  return { code: 'run.stalled', count: stalled.count ?? 0, articles: stalled.articles ?? [] };
115
+ // @implements A-SPEC-102.10 — review rounds reached the run's cap with findings unresolved: the run stops for good.
116
+ const unresolved = events.find((e) => e.event === 'review_unresolved');
117
+ if (unresolved)
118
+ return { code: 'review.unresolved', count: unresolved.count ?? 0, findings: unresolved.findings ?? [] };
115
119
  const expired = events.find((e) => e.event === 'approval_expired');
116
120
  if (expired)
117
121
  return { code: 'approval.expired', count: 1, expired: expired.request ?? '' };
@@ -189,12 +193,14 @@ function appendRunEvent(main, runId, ev) {
189
193
  const stallLine = (count, articles) => `[Holmes-Kit] this run stalled: its Stop was blocked ${count} times in a row (${articles.join(', ') || 'no article named'}) — the turn ends blocked; ${END}`;
190
194
  const stopReason = (stop, limit, waitMinutes) => stop.code === 'run.stalled'
191
195
  ? stallLine(stop.count, stop.articles ?? [])
192
- : stop.install !== undefined
193
- ? `[Holmes-Kit] this run stopped: the Holmes install changed since run start (pinned ${stop.install.pinned.version ?? '?'} build ${stop.install.pinned.build ?? '?'}, `
194
- + `now ${stop.install.current.version ?? 'unreadable'} build ${stop.install.current.build ?? 'unreadable'}) — one build governs a run; ${END}`
195
- : stop.expired !== undefined
196
- ? `[Holmes-Kit] this run stopped: approval ${stop.expired} was not decided within ${waitMinutes} minutes — ${END}`
197
- : `[Holmes-Kit] this run stopped: refusal ${stop.code} repeated ${stop.count} times (limit ${limit}) — ${END}`;
196
+ : stop.code === 'review.unresolved'
197
+ ? `[Holmes-Kit] this run stopped: review.unresolved — ${stop.count} failing independent review round(s) reached the run's cap; unresolved: ${(stop.findings ?? []).slice(0, 3).join(' | ') || 'none named'} — ${END}`
198
+ : stop.install !== undefined
199
+ ? `[Holmes-Kit] this run stopped: the Holmes install changed since run start (pinned ${stop.install.pinned.version ?? '?'} build ${stop.install.pinned.build ?? '?'}, `
200
+ + `now ${stop.install.current.version ?? 'unreadable'} build ${stop.install.current.build ?? 'unreadable'}) — one build governs a run; ${END}`
201
+ : stop.expired !== undefined
202
+ ? `[Holmes-Kit] this run stopped: approval ${stop.expired} was not decided within ${waitMinutes} minutes — ${END}`
203
+ : `[Holmes-Kit] this run stopped: refusal ${stop.code} repeated ${stop.count} times (limit ${limit}) — ${END}`;
198
204
  /** The decision recorded for `request` at or after `since`, read from the queue it was filed in; null when undecided. */
199
205
  function decisionAfter(queueRoot, request, since) {
200
206
  try {
@@ -247,7 +253,8 @@ function applyRunRefusalStop(out, ctx) {
247
253
  return {
248
254
  permissionDecision: 'deny',
249
255
  permissionDecisionReason: `[Holmes-Kit] this run is awaiting approval ${wait.request} (${wait.code ?? 'approval'}) since ${wait.ts} — `
250
- + `the operator decides it in a terminal: holmes-kit approve --grant ${wait.request} --target ${queueRoot}; `
256
+ // @implements A-SPEC-792.1 — the interactive session's form (A-SPEC-779.5), never a command to type.
257
+ + `the person decides it in the interactive session's approval form (approval_ask with id "${wait.request}", workspace ${queueRoot}); `
251
258
  + `until then every tool call of this run is refused (the wait stops the run after ${cfg.approvalWaitMinutes} minutes)`,
252
259
  };
253
260
  }
@@ -262,7 +269,7 @@ function applyRunRefusalStop(out, ctx) {
262
269
  const request = REQUEST_RE.exec(reason)?.[1];
263
270
  if (request && rc.class === 'needs_hitl'
264
271
  && append(file, { ts: now.toISOString(), event: 'awaiting_approval', request, code: rc.code, queue_root: ctx.projectRoot })) {
265
- next += `\n[Holmes-Kit] this run now awaits approval ${request}: until the operator decides it in a terminal, every tool call of this run is refused`;
272
+ next += `\n[Holmes-Kit] this run now awaits approval ${request}: until the person decides it in the interactive session's approval form, every tool call of this run is refused`;
266
273
  }
267
274
  const count = events.filter((e) => e.event === 'refusal' && e.code === rc.code).length + 1;
268
275
  if (count >= limit)
@@ -321,13 +328,13 @@ function runState(main, runId, opts) {
321
328
  function grantGuard(root, id, opts) {
322
329
  const marker = opts.env.HOLMES_RUN_ID;
323
330
  if (typeof marker === 'string' && marker.trim() !== '') {
324
- return 'a grant is the operator\'s, from their own terminal — not from inside a run (HOLMES_RUN_ID is set in this process)';
331
+ return 'a grant is the operator\'s, in an interactive session\'s approval form — not from inside a run (HOLMES_RUN_ID is set in this process)';
325
332
  }
326
333
  if (opts.interactive)
327
334
  return null;
328
335
  const dir = (0, exports.runRefusalsDir)((0, run_records_1.mainCheckoutOf)(root));
329
336
  // @implements A-SPEC-779.1 — a log that cannot be read cannot say no run awaits the request: refuse, naming it.
330
- const unknown = (what) => `cannot tell whether a run awaits ${id}: the run logs cannot be read (${what}) — the operator grants it from a terminal`;
337
+ const unknown = (what) => `cannot tell whether a run awaits ${id}: the run logs cannot be read (${what}) — the person decides it in an interactive session's approval form`;
331
338
  let names;
332
339
  try {
333
340
  names = fs.readdirSync(dir).filter((n) => n.endsWith('.jsonl'));
@@ -341,7 +348,7 @@ function grantGuard(root, id, opts) {
341
348
  return unknown(path.join(dir, n));
342
349
  const wait = openWait(events);
343
350
  if (wait && wait.request === id) {
344
- return `${id} is awaited by run ${n.slice(0, -'.jsonl'.length)}; the operator grants it in a terminal (this CLI is not attached to one)`;
351
+ return `${id} is awaited by run ${n.slice(0, -'.jsonl'.length)}; the person decides it in an interactive session's approval form (this CLI is not attached to a terminal)`;
345
352
  }
346
353
  }
347
354
  return null;
@@ -28,6 +28,11 @@ export declare function applyRoleStage(out: Decision, ctx: {
28
28
  toolInput: Record<string, unknown>;
29
29
  }): Decision;
30
30
  export declare function currentStage(main: string, runId: string, machine: StageMachine): string;
31
+ /** @implements A-SPEC-102.10 — the review policy recorded at run start; anything unreadable is no policy. */
32
+ export declare function reviewPolicyOf(rec: unknown): {
33
+ rounds?: number;
34
+ strict: boolean;
35
+ };
31
36
  export declare function transitionRun(main: string, runId: string, to: string, opts: {
32
37
  key: string;
33
38
  why?: string;