ai-engineering-loop 1.14.0 → 1.15.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 (92) hide show
  1. package/.agents/{workflows/ai-engineering-loop.md → skills/ai-engineering-loop/SKILL.md} +8 -6
  2. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  3. package/.claude/skills/ai-engineering-loop/SKILL.md +9 -10
  4. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  5. package/CHANGELOG.md +47 -0
  6. package/README.md +52 -6
  7. package/adapters/dot/README.md +1 -1
  8. package/bin/ai-engineering-loop.js +296 -11
  9. package/core/grill-policy.md +1 -1
  10. package/core/runtime-safety.md +2 -1
  11. package/lib/auto-update.js +3 -1
  12. package/lib/cli-args.js +11 -0
  13. package/lib/doctor.js +4 -15
  14. package/lib/host-skill-build.js +15 -15
  15. package/lib/hosts/agent-formats.js +135 -0
  16. package/lib/hosts/commands.js +126 -0
  17. package/lib/hosts/detect.js +56 -0
  18. package/lib/hosts/doctor.js +76 -0
  19. package/lib/hosts/redetect.js +60 -0
  20. package/lib/hosts/registry.js +271 -0
  21. package/lib/hosts/table.js +35 -0
  22. package/lib/run-abandon.js +116 -0
  23. package/lib/sync-hosts.js +155 -112
  24. package/package.json +2 -3
  25. package/.agents/devil-advocate.md +0 -79
  26. package/.agents/judge.md +0 -58
  27. package/.claude/commands/ai-engineering-loop.md +0 -11
  28. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -61
  29. package/.gemini/skills/animate/RECIPES.md +0 -324
  30. package/.gemini/skills/animate/SKILL.md +0 -207
  31. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  32. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  33. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  34. package/.gemini/skills/apple-design/SKILL.md +0 -290
  35. package/.gemini/skills/ask-sonner/API.md +0 -64
  36. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  37. package/.gemini/skills/backend-development/SKILL.md +0 -272
  38. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  39. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  40. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  41. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  42. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  43. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  44. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  45. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  46. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  47. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  48. package/.gemini/skills/prototype/PICKER.md +0 -197
  49. package/.gemini/skills/prototype/SKILL.md +0 -98
  50. package/.gemini/skills/review-animations/SKILL.md +0 -120
  51. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  52. package/.gemini/skills/write-swift/SKILL.md +0 -396
  53. package/.grok/commands/ai-engineering-loop.md +0 -11
  54. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -62
  55. package/.grok/skills/ai-engineering-loop/references/loop-commands.md +0 -20
  56. package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +0 -8
  57. package/.grok/skills/ai-engineering-loop/references/loop-goal.md +0 -10
  58. package/.grok/skills/ai-engineering-loop/references/loop-maker.md +0 -8
  59. package/.grok/skills/ai-engineering-loop/references/loop-review.md +0 -18
  60. package/.grok/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  61. package/.grok/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  62. package/.grok/skills/animate/RECIPES.md +0 -324
  63. package/.grok/skills/animate/SKILL.md +0 -207
  64. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  65. package/.grok/skills/animate-expo/SKILL.md +0 -263
  66. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  67. package/.grok/skills/apple-design/SKILL.md +0 -290
  68. package/.grok/skills/ask-sonner/API.md +0 -64
  69. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  70. package/.grok/skills/backend-development/SKILL.md +0 -272
  71. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  72. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  73. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  74. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  75. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  76. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  77. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  78. package/.grok/skills/improve-animations/SKILL.md +0 -109
  79. package/.grok/skills/mobile-native/SKILL.md +0 -311
  80. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  81. package/.grok/skills/prototype/PICKER.md +0 -197
  82. package/.grok/skills/prototype/SKILL.md +0 -98
  83. package/.grok/skills/review-animations/SKILL.md +0 -120
  84. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  85. package/.grok/skills/write-swift/SKILL.md +0 -396
  86. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-commands.md +0 -0
  87. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-deliver.md +0 -0
  88. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-goal.md +0 -0
  89. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-maker.md +0 -0
  90. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-review.md +0 -0
  91. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-risky.md +0 -0
  92. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-verify.md +0 -0
@@ -0,0 +1,271 @@
1
+ 'use strict';
2
+
3
+ // Host registry (#49). One data entry per AI coding agent: how to detect it,
4
+ // where its skills and reviewer subagents go, and which skill folders it scans.
5
+ // Code per host is only an agent formatter in agent-formats.js.
6
+ //
7
+ // - `detect.dirs`: config directories under $HOME (any present = detected).
8
+ // - `detect.bins`: executable names looked up on PATH with stat only; a binary
9
+ // is never executed.
10
+ // - `skills`: 'shared' = the host reads ~/.agents/skills (one copy for every
11
+ // such host), or { dir } for a host that needs its own copy.
12
+ // - `reads`: every user-level skill folder the host scans (official docs);
13
+ // used by `hosts doctor` and the one-copy-per-host test.
14
+ // - `agents`: reviewer subagent format and directory, or null when the host
15
+ // has no file-based custom subagents.
16
+ // - `docs` / `verified`: sources checked, and when.
17
+
18
+ const SHARED_SKILLS_DIR = '.agents/skills';
19
+
20
+ const HOSTS = Object.freeze([
21
+ {
22
+ id: 'claude',
23
+ name: 'Claude Code',
24
+ tier: 1,
25
+ detect: { dirs: ['.claude'], bins: ['claude'] },
26
+ skills: { dir: '.claude/skills' },
27
+ reads: ['.claude/skills'],
28
+ agents: { format: 'claude-md', dir: '.claude/agents' },
29
+ docs: ['https://code.claude.com/docs/en/skills', 'https://code.claude.com/docs/en/sub-agents'],
30
+ verified: '2026-10-11'
31
+ },
32
+ {
33
+ id: 'codex',
34
+ name: 'Codex CLI',
35
+ tier: 1,
36
+ detect: { dirs: ['.codex'], bins: ['codex'] },
37
+ skills: 'shared',
38
+ reads: ['.agents/skills'],
39
+ agents: { format: 'codex-toml', dir: '.codex/agents' },
40
+ docs: ['https://developers.openai.com/codex/skills', 'https://developers.openai.com/codex/subagents'],
41
+ verified: '2026-10-11'
42
+ },
43
+ {
44
+ id: 'gemini',
45
+ name: 'Gemini CLI',
46
+ tier: 1,
47
+ detect: { dirs: ['.gemini'], bins: ['gemini'] },
48
+ skills: 'shared',
49
+ reads: ['.gemini/skills', '.agents/skills'],
50
+ agents: { format: 'gemini-md', dir: '.gemini/agents' },
51
+ docs: ['https://geminicli.com/docs/cli/skills/', 'https://geminicli.com/docs/core/subagents/'],
52
+ verified: '2026-10-11'
53
+ },
54
+ {
55
+ id: 'antigravity',
56
+ name: 'Antigravity (IDE / 2.0)',
57
+ tier: 1,
58
+ detect: { dirs: ['.gemini/antigravity'], bins: ['antigravity'] },
59
+ skills: { dir: '.gemini/config/skills' },
60
+ reads: ['.gemini/config/skills'],
61
+ agents: { format: 'antigravity-md', dir: '.gemini/config/agents' },
62
+ docs: ['https://antigravity.google/docs/skills/', 'https://antigravity.google/docs/subagents/'],
63
+ verified: '2026-10-11'
64
+ },
65
+ {
66
+ id: 'antigravity-cli',
67
+ name: 'Antigravity CLI (agy)',
68
+ tier: 1,
69
+ detect: { dirs: ['.gemini/antigravity-cli'], bins: ['agy'] },
70
+ skills: { dir: '.gemini/antigravity-cli/skills' },
71
+ reads: ['.gemini/antigravity-cli/skills'],
72
+ agents: { format: 'antigravity-md', dir: '.gemini/config/agents' },
73
+ docs: ['https://antigravity.google/docs/cli/install/', 'https://antigravity.google/docs/cli/plugins/'],
74
+ verified: '2026-10-11'
75
+ },
76
+ {
77
+ id: 'grok',
78
+ name: 'Grok CLI',
79
+ tier: 1,
80
+ detect: { dirs: ['.grok'], bins: ['grok'] },
81
+ skills: 'shared',
82
+ reads: ['.grok/skills', '.claude/skills', '.agents/skills'],
83
+ agents: { format: 'grok-md', dir: '.grok/agents' },
84
+ docs: ['https://docs.x.ai/build/features/skills-plugins-marketplaces', 'https://docs.x.ai/build/features/subagents'],
85
+ verified: '2026-10-11'
86
+ },
87
+ {
88
+ id: 'cursor',
89
+ name: 'Cursor (editor + CLI)',
90
+ tier: 1,
91
+ // The CLI installs `agent` plus a legacy `cursor-agent` link; `agent` is too
92
+ // generic to count as evidence on its own.
93
+ detect: { dirs: ['.cursor'], bins: ['cursor-agent', 'cursor'] },
94
+ skills: 'shared',
95
+ reads: ['.cursor/skills', '.agents/skills', '.claude/skills', '.codex/skills'],
96
+ agents: { format: 'cursor-md', dir: '.cursor/agents' },
97
+ docs: ['https://cursor.com/docs/context/skills', 'https://cursor.com/docs/subagents', 'https://cursor.com/docs/cli/installation'],
98
+ verified: '2026-10-11'
99
+ },
100
+ {
101
+ id: 'copilot',
102
+ name: 'GitHub Copilot (CLI / VS Code)',
103
+ tier: 1,
104
+ detect: { dirs: ['.copilot'], bins: ['copilot'] },
105
+ skills: 'shared',
106
+ reads: ['.copilot/skills', '.agents/skills'],
107
+ agents: { format: 'copilot-agent-md', dir: '.copilot/agents' },
108
+ docs: ['https://docs.github.com/en/copilot/concepts/agents/about-agent-skills', 'https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli'],
109
+ verified: '2026-10-11'
110
+ },
111
+ // Phase 2 (#50): hosts that read the shared ~/.agents/skills folder.
112
+ {
113
+ id: 'opencode',
114
+ name: 'OpenCode',
115
+ tier: 2,
116
+ detect: { dirs: ['.config/opencode'], bins: ['opencode'] },
117
+ skills: 'shared',
118
+ reads: ['.config/opencode/skills', '.claude/skills', '.agents/skills'],
119
+ agents: { format: 'opencode-md', dir: '.config/opencode/agents' },
120
+ docs: ['https://opencode.ai/docs/skills/', 'https://opencode.ai/docs/agents/'],
121
+ verified: '2026-10-11'
122
+ },
123
+ {
124
+ id: 'windsurf',
125
+ name: 'Windsurf / Devin Desktop',
126
+ tier: 2,
127
+ // No CLI binary is documented; detect by config folder only.
128
+ detect: { dirs: ['.codeium/windsurf', '.config/devin'], bins: [] },
129
+ skills: 'shared',
130
+ reads: ['.codeium/windsurf/skills', '.config/devin/skills', '.agents/skills'],
131
+ agents: null,
132
+ docs: ['https://docs.devin.ai/desktop/cascade/skills'],
133
+ verified: '2026-10-11'
134
+ },
135
+ {
136
+ id: 'amp',
137
+ name: 'Amp',
138
+ tier: 2,
139
+ detect: { dirs: ['.config/amp'], bins: ['amp'] },
140
+ skills: 'shared',
141
+ reads: ['.config/agents/skills', '.agents/skills', '.config/amp/skills', '.claude/skills'],
142
+ // Custom subagents are TypeScript plugins (amp.createAgent), not files.
143
+ agents: null,
144
+ docs: ['https://ampcode.com/manual/agent-skills.md', 'https://ampcode.com/news/custom-agents'],
145
+ verified: '2026-10-11'
146
+ },
147
+ {
148
+ id: 'factory',
149
+ name: 'Factory Droid',
150
+ tier: 2,
151
+ detect: { dirs: ['.factory'], bins: ['droid'] },
152
+ skills: 'shared',
153
+ reads: ['.factory/skills', '.agents/skills'],
154
+ agents: { format: 'factory-md', dir: '.factory/droids' },
155
+ docs: ['https://docs.factory.ai/cli/configuration/skills', 'https://docs.factory.ai/harness/subagents'],
156
+ verified: '2026-10-11'
157
+ },
158
+ {
159
+ id: 'augment',
160
+ name: 'Augment (Auggie)',
161
+ tier: 2,
162
+ detect: { dirs: ['.augment'], bins: ['auggie'] },
163
+ skills: 'shared',
164
+ reads: ['.augment/skills', '.claude/skills', '.agents/skills'],
165
+ agents: { format: 'augment-md', dir: '.augment/agents' },
166
+ docs: ['https://docs.augmentcode.com/cli/skills', 'https://docs.augmentcode.com/cli/subagents'],
167
+ verified: '2026-10-11'
168
+ },
169
+ {
170
+ id: 'zed',
171
+ name: 'Zed',
172
+ tier: 2,
173
+ detect: { dirs: ['.config/zed', 'Library/Application Support/Zed'], bins: ['zed'] },
174
+ skills: 'shared',
175
+ reads: ['.agents/skills'],
176
+ agents: null,
177
+ docs: ['https://zed.dev/docs/ai/skills'],
178
+ verified: '2026-10-11'
179
+ },
180
+ {
181
+ id: 'goose',
182
+ name: 'Goose',
183
+ tier: 2,
184
+ detect: { dirs: ['.config/goose'], bins: ['goose'] },
185
+ skills: 'shared',
186
+ reads: ['.agents/skills', '.config/goose/skills', '.config/agents/skills', '.claude/skills'],
187
+ // Subrecipes, not file-based reviewer agents.
188
+ agents: null,
189
+ docs: ['https://goose-docs.ai/docs/guides/context-engineering/using-skills'],
190
+ verified: '2026-10-11'
191
+ },
192
+ // Phase 3 (#51): hosts verified to need their own skill folder (Cline, Kiro,
193
+ // Qwen), plus Roo and Junie, which the docs show also read ~/.agents/skills.
194
+ {
195
+ id: 'cline',
196
+ name: 'Cline',
197
+ tier: 3,
198
+ detect: { dirs: ['.cline'], bins: ['cline'] },
199
+ skills: { dir: '.cline/skills' },
200
+ reads: ['.cline/skills'],
201
+ // Subagents use built-in tools only; no documented reviewer agent file.
202
+ agents: null,
203
+ docs: ['https://docs.cline.bot/customization/skills', 'https://docs.cline.bot/features/subagents'],
204
+ verified: '2026-10-11'
205
+ },
206
+ {
207
+ id: 'roo',
208
+ name: 'Roo Code',
209
+ tier: 3,
210
+ detect: { dirs: ['.roo'], bins: [] },
211
+ skills: 'shared',
212
+ reads: ['.roo/skills', '.agents/skills'],
213
+ // Modes, not file-based subagents.
214
+ agents: null,
215
+ docs: ['https://docs.roocode.com/features/skills'],
216
+ verified: '2026-10-11'
217
+ },
218
+ {
219
+ id: 'kiro',
220
+ name: 'Kiro (IDE + CLI)',
221
+ tier: 3,
222
+ detect: { dirs: ['.kiro'], bins: ['kiro-cli', 'kiro'] },
223
+ skills: { dir: '.kiro/skills' },
224
+ reads: ['.kiro/skills'],
225
+ agents: { format: 'kiro-md', dir: '.kiro/agents' },
226
+ docs: ['https://kiro.dev/docs/skills/', 'https://kiro.dev/docs/cli/custom-agents/configuration-reference/'],
227
+ verified: '2026-10-11'
228
+ },
229
+ {
230
+ id: 'qwen',
231
+ name: 'Qwen Code',
232
+ tier: 3,
233
+ detect: { dirs: ['.qwen'], bins: ['qwen'] },
234
+ skills: { dir: '.qwen/skills' },
235
+ reads: ['.qwen/skills'],
236
+ agents: { format: 'qwen-md', dir: '.qwen/agents' },
237
+ // Pages: Features > Agent Skills, Features > Subagents (the page path
238
+ // contains a segment the package privacy audit treats as a home folder).
239
+ docs: ['https://qwenlm.github.io/qwen-code-docs/'],
240
+ verified: '2026-10-11'
241
+ },
242
+ {
243
+ id: 'junie',
244
+ name: 'JetBrains Junie',
245
+ tier: 3,
246
+ detect: { dirs: ['.junie'], bins: ['junie'] },
247
+ skills: 'shared',
248
+ reads: ['.junie/skills', '.agents/skills'],
249
+ agents: { format: 'junie-md', dir: '.junie/agents' },
250
+ docs: ['https://junie.jetbrains.com/docs/agent-skills.html', 'https://junie.jetbrains.com/docs/junie-cli-subagents.html'],
251
+ verified: '2026-10-11'
252
+ }
253
+ ]);
254
+
255
+ // Out of scope (no native SKILL.md support): Aider, Continue.
256
+ const OUT_OF_SCOPE = Object.freeze([
257
+ { id: 'aider', name: 'Aider', reason: 'no native skills; use --read or .aider.conf.yml' },
258
+ { id: 'continue', name: 'Continue', reason: 'no native skills; joined Cursor' }
259
+ ]);
260
+
261
+ const HOST_IDS = Object.freeze(HOSTS.map((host) => host.id));
262
+
263
+ function getHost(id) {
264
+ return HOSTS.find((host) => host.id === id) || null;
265
+ }
266
+
267
+ function usesSharedSkills(host) {
268
+ return host.skills === 'shared';
269
+ }
270
+
271
+ module.exports = { HOSTS, HOST_IDS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, getHost, usesSharedSkills };
@@ -0,0 +1,35 @@
1
+ 'use strict';
2
+
3
+ // README host table generated from the registry (#52); `npm test` fails on drift.
4
+
5
+ const { HOSTS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, usesSharedSkills } = require('./registry.js');
6
+
7
+ const START = '<!-- hosts-table:start (generated from lib/hosts/registry.js; run npm run build:hosts-table) -->';
8
+ const END = '<!-- hosts-table:end -->';
9
+
10
+ function renderHostTable() {
11
+ const rows = HOSTS.map((host) => {
12
+ const skills = usesSharedSkills(host) ? `\`~/${SHARED_SKILLS_DIR}\` (shared)` : `\`~/${host.skills.dir}\``;
13
+ const agents = host.agents ? `\`~/${host.agents.dir}\`` : 'none (in-session review)';
14
+ const detect = [...host.detect.dirs.map((d) => `\`~/${d}\``), ...(host.detect.bins || []).map((b) => `\`${b}\``)].join(', ');
15
+ return `| ${host.name} | \`${host.id}\` | ${skills} | ${agents} | ${detect} |`;
16
+ });
17
+ return [
18
+ START,
19
+ '| Host | id | Skill folder | Reviewer agents | Detected by |',
20
+ '|---|---|---|---|---|',
21
+ ...rows,
22
+ '',
23
+ `Not supported (no native skills): ${OUT_OF_SCOPE.map((h) => h.name).join(', ')}.`,
24
+ END
25
+ ].join('\n');
26
+ }
27
+
28
+ function replaceHostTable(text) {
29
+ const start = text.indexOf(START);
30
+ const end = text.indexOf(END);
31
+ if (start === -1 || end === -1 || end < start) throw new Error('README has no hosts-table markers');
32
+ return text.slice(0, start) + renderHostTable() + text.slice(end + END.length);
33
+ }
34
+
35
+ module.exports = { START, END, renderHostTable, replaceHostTable };
@@ -0,0 +1,116 @@
1
+ 'use strict';
2
+
3
+ // `run --abandon` (issue #46): close a run that will never finish so it stops
4
+ // holding `refresh --non-destructive` and `update auto` back. The run moves to
5
+ // CANCELLED with reason, actor, and time in its history ledger (workflow runs
6
+ // also get a RUN_CANCELLED event in events.jsonl). Run data is never deleted.
7
+ // The current.json pointer is released only when it pointed at that run.
8
+
9
+ const fs = require('fs');
10
+ const {
11
+ RUN_STATES,
12
+ TERMINAL_STATES,
13
+ assertRunId,
14
+ atomicWriteJson,
15
+ currentRunPath,
16
+ loadRun,
17
+ transitionRun
18
+ } = require('./run-state.js');
19
+ const { redactSecrets } = require('./safe-context.js');
20
+
21
+ const STALE_RUN_DAYS = 7;
22
+ const DAY_MS = 24 * 60 * 60 * 1000;
23
+
24
+ function abandonError(message, code, exitCode = 1) {
25
+ const err = new Error(message);
26
+ err.code = code;
27
+ err.exitCode = exitCode;
28
+ return err;
29
+ }
30
+
31
+ function currentPointerRunId(rootDir) {
32
+ try {
33
+ const { runId } = JSON.parse(fs.readFileSync(currentRunPath(rootDir), 'utf8'));
34
+ return assertRunId(runId);
35
+ } catch {
36
+ return null;
37
+ }
38
+ }
39
+
40
+ // { stale, idleDays } for an active run; terminal runs are never stale.
41
+ function staleRunInfo(run, { now = new Date(), days = STALE_RUN_DAYS } = {}) {
42
+ if (!run || TERMINAL_STATES.has(run.state)) return { stale: false, idleDays: 0 };
43
+ const last = Date.parse(run.updatedAt || run.createdAt);
44
+ if (!Number.isFinite(last)) return { stale: false, idleDays: 0 };
45
+ const idleDays = Math.floor((now.getTime() - last) / DAY_MS);
46
+ return { stale: idleDays >= days, idleDays };
47
+ }
48
+
49
+ function abandonCommand(runId) {
50
+ return `ai-engineering-loop run --abandon${runId ? ` --run ${runId}` : ''} --reason "<why>" --by <name>`;
51
+ }
52
+
53
+ // Validates everything before writing anything.
54
+ function planAbandon(rootDir, { runId = null, reason, by } = {}) {
55
+ const pointer = currentPointerRunId(rootDir);
56
+ const target = runId || pointer;
57
+ if (!target) {
58
+ throw abandonError('No current run to abandon. Pass --run <id> (see `ai-engineering-loop history`).', 'NO_ACTIVE_RUN', 2);
59
+ }
60
+ const run = loadRun(rootDir, assertRunId(target));
61
+ if (TERMINAL_STATES.has(run.state)) {
62
+ throw abandonError(`Run ${run.runId} is already finished (${run.state}); nothing to abandon.`, 'RUN_ALREADY_FINISHED', 2);
63
+ }
64
+ const actor = String(by || '').trim();
65
+ if (!/^[A-Za-z0-9@._-]{1,64}$/.test(actor)) {
66
+ throw abandonError('--by <name> is required (letters, digits, @._-; max 64).', 'INVALID_RUN_ACTOR');
67
+ }
68
+ const cleanReason = redactSecrets(String(reason || '').trim()).text;
69
+ if (!cleanReason || cleanReason.length > 500) {
70
+ throw abandonError('--reason "<text>" is required (1-500 characters).', 'INVALID_ABANDON_REASON');
71
+ }
72
+ return { run, pointer, actor, reason: cleanReason };
73
+ }
74
+
75
+ function abandonRun(rootDir, { runId = null, reason, by, now = new Date() } = {}) {
76
+ const plan = planAbandon(rootDir, { runId, reason, by });
77
+ const { run, pointer, actor } = plan;
78
+ const fromState = run.state;
79
+ let next;
80
+ if (run.workflow) {
81
+ next = require('./workflow-runtime.js').cancelWorkflowRun(rootDir, {
82
+ runId: run.runId,
83
+ actor,
84
+ reason: `Abandoned: ${plan.reason}`,
85
+ now
86
+ }).run;
87
+ } else {
88
+ next = transitionRun(rootDir, run.runId, RUN_STATES.CANCELLED, {
89
+ gate: 'run-abandoned',
90
+ reason: plan.reason,
91
+ historyMetadata: { actor, action: 'abandon' },
92
+ now
93
+ });
94
+ }
95
+ // transitionRun rewrote current.json to this run. Release it, or put back
96
+ // the pointer to the other run that was current before.
97
+ let released = false;
98
+ if (pointer && pointer !== run.runId) {
99
+ atomicWriteJson(currentRunPath(rootDir), { schemaVersion: 1, runId: pointer });
100
+ } else {
101
+ fs.rmSync(currentRunPath(rootDir), { force: true });
102
+ released = Boolean(pointer);
103
+ }
104
+ return {
105
+ runId: run.runId,
106
+ from: fromState,
107
+ state: next.state,
108
+ reason: plan.reason,
109
+ by: actor,
110
+ at: now.toISOString(),
111
+ released,
112
+ current: pointer && pointer !== run.runId ? pointer : null
113
+ };
114
+ }
115
+
116
+ module.exports = { STALE_RUN_DAYS, staleRunInfo, abandonCommand, planAbandon, abandonRun, currentPointerRunId };