ai-engineering-loop 1.1.0 → 1.2.1

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 (39) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +5 -5
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
  5. package/README.md +20 -3
  6. package/README.npm.md +9 -1
  7. package/SECURITY.md +8 -2
  8. package/agents/judge.md +5 -5
  9. package/agents/maker.md +6 -6
  10. package/bin/ai-engineering-loop.js +223 -13
  11. package/core/configuration-precedence.md +4 -4
  12. package/core/context-impact-assessment.md +1 -1
  13. package/core/definition-of-done.md +3 -3
  14. package/core/escalation-policy.md +2 -2
  15. package/core/goal-contract.md +2 -2
  16. package/core/iteration-policy.md +4 -4
  17. package/core/project-initialization.md +2 -2
  18. package/core/runtime-safety.md +75 -0
  19. package/core/verification-loop.md +1 -1
  20. package/lib/budget.js +220 -0
  21. package/lib/doctor.js +14 -1
  22. package/lib/gates.js +55 -1
  23. package/lib/package-audit.js +78 -0
  24. package/lib/run-state.js +47 -8
  25. package/lib/runtime-files.js +53 -0
  26. package/lib/runtime-policy.js +118 -0
  27. package/lib/safe-context.js +3 -0
  28. package/lib/sandbox.js +305 -0
  29. package/package.json +6 -3
  30. package/policies/finding-policy.md +2 -2
  31. package/policies/no-progress-policy.md +2 -2
  32. package/profiles/README.md +5 -5
  33. package/profiles/backend-api.md +1 -1
  34. package/profiles/library.md +1 -1
  35. package/profiles/mobile-app.md +1 -1
  36. package/profiles/monorepo.md +1 -1
  37. package/profiles/web-app.md +1 -1
  38. package/schemas/delivery.schema.json +2 -1
  39. package/schemas/report.schema.json +17 -0
package/lib/budget.js ADDED
@@ -0,0 +1,220 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { assertRunId, getCurrentRun, loadRun } = require('./run-state.js');
6
+ const { loadPolicy, updatePolicy } = require('./runtime-policy.js');
7
+ const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
8
+
9
+ function usageDir(rootDir) {
10
+ return path.join(rootDir, '.ai-engineering-loop', 'usage');
11
+ }
12
+
13
+ function utcDay(now = new Date()) {
14
+ if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
15
+ const err = new Error('Usage timestamp must be a valid Date');
16
+ err.code = 'INVALID_USAGE';
17
+ throw err;
18
+ }
19
+ return now.toISOString().slice(0, 10);
20
+ }
21
+
22
+ function usagePath(rootDir, now = new Date()) {
23
+ return path.join(usageDir(rootDir), `${utcDay(now)}.jsonl`);
24
+ }
25
+
26
+ function usageError(message, code = 'INVALID_USAGE') {
27
+ const err = new Error(message);
28
+ err.code = code;
29
+ return err;
30
+ }
31
+
32
+ function validateTokenCount(name, value) {
33
+ if (!Number.isSafeInteger(value) || value < 0) {
34
+ throw usageError(`${name} must be a non-negative integer`);
35
+ }
36
+ }
37
+
38
+ function validateModel(model) {
39
+ if (!/^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/.test(String(model || ''))) {
40
+ throw usageError('model must be a provider model identifier, not free-form text');
41
+ }
42
+ return String(model);
43
+ }
44
+
45
+ function readUsageFile(filePath) {
46
+ let stat;
47
+ try {
48
+ stat = fs.lstatSync(filePath);
49
+ } catch (cause) {
50
+ if (cause.code === 'ENOENT') return [];
51
+ throw usageError(`Unable to inspect usage ledger: ${cause.message}`, 'INVALID_USAGE_LEDGER');
52
+ }
53
+ if (stat.isSymbolicLink()) {
54
+ throw usageError('Usage ledger must not be a symbolic link', 'INVALID_USAGE_LEDGER');
55
+ }
56
+ let lines;
57
+ try {
58
+ lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
59
+ } catch (cause) {
60
+ throw usageError(`Unable to read usage ledger: ${cause.message}`, 'INVALID_USAGE_LEDGER');
61
+ }
62
+ return lines.map((line, index) => {
63
+ try {
64
+ const entry = JSON.parse(line);
65
+ assertRunId(entry.runId);
66
+ validateTokenCount('inputTokens', entry.inputTokens);
67
+ validateTokenCount('outputTokens', entry.outputTokens);
68
+ if (entry.totalTokens !== entry.inputTokens + entry.outputTokens) {
69
+ throw new Error('totalTokens does not equal inputTokens + outputTokens');
70
+ }
71
+ validateModel(entry.model);
72
+ if (typeof entry.recordedAt !== 'string' || Number.isNaN(Date.parse(entry.recordedAt))) {
73
+ throw new Error('recordedAt is invalid');
74
+ }
75
+ return entry;
76
+ } catch (cause) {
77
+ throw usageError(
78
+ `Usage ledger line ${index + 1} is invalid: ${cause.message}`,
79
+ 'INVALID_USAGE_LEDGER'
80
+ );
81
+ }
82
+ });
83
+ }
84
+
85
+ function readUsage(rootDir, now = new Date()) {
86
+ return readUsageFile(usagePath(rootDir, now));
87
+ }
88
+
89
+ function readAllUsage(rootDir) {
90
+ const directory = usageDir(rootDir);
91
+ if (!fs.existsSync(directory)) return [];
92
+ let names;
93
+ try {
94
+ names = fs.readdirSync(directory)
95
+ .filter((name) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(name))
96
+ .sort();
97
+ } catch (cause) {
98
+ throw usageError(`Unable to enumerate usage ledgers: ${cause.message}`, 'INVALID_USAGE_LEDGER');
99
+ }
100
+ return names.flatMap((name) => readUsageFile(path.join(directory, name)));
101
+ }
102
+
103
+ function resolveRun(rootDir, runId) {
104
+ if (runId) return loadRun(rootDir, assertRunId(runId));
105
+ const current = getCurrentRun(rootDir);
106
+ if (!current) throw usageError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
107
+ return current;
108
+ }
109
+
110
+ function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() } = {}) {
111
+ validateTokenCount('estimatedTokens', estimatedTokens);
112
+ const run = resolveRun(rootDir, runId);
113
+ const policy = loadPolicy(rootDir);
114
+ const todayEntries = readUsage(rootDir, now);
115
+ const allEntries = readAllUsage(rootDir);
116
+ const spentToday = todayEntries.reduce((sum, entry) => sum + entry.totalTokens, 0);
117
+ const spentThisRun = allEntries
118
+ .filter((entry) => entry.runId === run.runId)
119
+ .reduce((sum, entry) => sum + entry.totalTokens, 0);
120
+ const projectedToday = spentToday + estimatedTokens;
121
+ const projectedThisRun = spentThisRun + estimatedTokens;
122
+ const reasons = [];
123
+ if (policy.killSwitch) reasons.push('kill switch is active');
124
+ if (projectedThisRun > policy.perRunTokenLimit) reasons.push('per-run token limit would be exceeded');
125
+ if (projectedToday > policy.dailyTokenLimit) reasons.push('daily token limit would be exceeded');
126
+ if (estimatedTokens === 0 && spentThisRun >= policy.perRunTokenLimit) {
127
+ reasons.push('per-run token limit is exhausted');
128
+ }
129
+ if (estimatedTokens === 0 && spentToday >= policy.dailyTokenLimit) {
130
+ reasons.push('daily token limit is exhausted');
131
+ }
132
+
133
+ return {
134
+ schemaVersion: 1,
135
+ runId: run.runId,
136
+ day: utcDay(now),
137
+ allowed: reasons.length === 0,
138
+ reasons: [...new Set(reasons)],
139
+ killSwitch: policy.killSwitch,
140
+ spentThisRun,
141
+ perRunTokenLimit: policy.perRunTokenLimit,
142
+ remainingThisRun: Math.max(0, policy.perRunTokenLimit - spentThisRun),
143
+ spentToday,
144
+ dailyTokenLimit: policy.dailyTokenLimit,
145
+ remainingToday: Math.max(0, policy.dailyTokenLimit - spentToday),
146
+ estimatedTokens
147
+ };
148
+ }
149
+
150
+ function assertBudgetAvailable(rootDir, options = {}) {
151
+ const status = budgetStatus(rootDir, options);
152
+ if (!status.allowed) {
153
+ const err = new Error(`Token budget blocked: ${status.reasons.join('; ')}`);
154
+ err.code = 'BUDGET_BLOCKED';
155
+ err.details = status.reasons;
156
+ err.status = status;
157
+ throw err;
158
+ }
159
+ return status;
160
+ }
161
+
162
+ function appendPrivateLine(rootDir, filePath, line) {
163
+ ensurePrivateRuntimeIgnores(rootDir);
164
+ fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
165
+ const noFollow = fs.constants.O_NOFOLLOW || 0;
166
+ let descriptor;
167
+ try {
168
+ descriptor = fs.openSync(
169
+ filePath,
170
+ fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY | noFollow,
171
+ 0o600
172
+ );
173
+ if (!fs.fstatSync(descriptor).isFile()) throw new Error('usage ledger is not a regular file');
174
+ fs.writeSync(descriptor, line);
175
+ fs.fchmodSync(descriptor, 0o600);
176
+ } catch (cause) {
177
+ throw usageError(`Unable to append usage ledger: ${cause.message}`, 'USAGE_WRITE_FAILED');
178
+ } finally {
179
+ if (descriptor != null) fs.closeSync(descriptor);
180
+ }
181
+ }
182
+
183
+ function recordTokenUsage(
184
+ rootDir,
185
+ { runId, inputTokens, outputTokens, model, now = new Date() } = {}
186
+ ) {
187
+ const run = resolveRun(rootDir, runId);
188
+ validateTokenCount('inputTokens', inputTokens);
189
+ validateTokenCount('outputTokens', outputTokens);
190
+ const normalizedModel = validateModel(model);
191
+ const totalTokens = inputTokens + outputTokens;
192
+ if (totalTokens === 0) throw usageError('A usage record must contain at least one token');
193
+ const entry = {
194
+ schemaVersion: 1,
195
+ runId: run.runId,
196
+ inputTokens,
197
+ outputTokens,
198
+ totalTokens,
199
+ model: normalizedModel,
200
+ recordedAt: now.toISOString()
201
+ };
202
+ appendPrivateLine(rootDir, usagePath(rootDir, now), `${JSON.stringify(entry)}\n`);
203
+ return { entry, status: budgetStatus(rootDir, { runId: run.runId, now }) };
204
+ }
205
+
206
+ function setKillSwitch(rootDir, active) {
207
+ return updatePolicy(rootDir, { killSwitch: Boolean(active) });
208
+ }
209
+
210
+ module.exports = {
211
+ usageDir,
212
+ utcDay,
213
+ usagePath,
214
+ readUsage,
215
+ readAllUsage,
216
+ budgetStatus,
217
+ assertBudgetAvailable,
218
+ recordTokenUsage,
219
+ setKillSwitch
220
+ };
package/lib/doctor.js CHANGED
@@ -3,6 +3,7 @@
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
5
  const { loadEvaluationCases } = require('./evaluation.js');
6
+ const { auditPackage } = require('./package-audit.js');
6
7
 
7
8
  const REQUIRED_HOST_ASSETS = [
8
9
  '.claude/skills/ai-engineering-loop/SKILL.md',
@@ -22,7 +23,8 @@ const REQUIRED_SCHEMAS = [
22
23
  'verification.schema.json',
23
24
  'finding-ledger.schema.json',
24
25
  'verdict.schema.json',
25
- 'delivery.schema.json'
26
+ 'delivery.schema.json',
27
+ 'report.schema.json'
26
28
  ];
27
29
 
28
30
  function check(id, passed, detail) {
@@ -80,6 +82,17 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
80
82
  missingPackageEntries.length ? `not packed: ${missingPackageEntries.join(', ')}` : 'runtime assets are allowlisted'
81
83
  ));
82
84
 
85
+ try {
86
+ const audit = auditPackage(rootDir);
87
+ checks.push(check(
88
+ 'package-privacy',
89
+ audit.ok,
90
+ audit.ok ? `${audit.filesScanned} packaged files scanned` : audit.findings.map((item) => `${item.file}: ${item.reason}`).join('; ')
91
+ ));
92
+ } catch (cause) {
93
+ checks.push(check('package-privacy', false, cause.message));
94
+ }
95
+
83
96
  const binPath = path.join(rootDir, 'bin', 'ai-engineering-loop.js');
84
97
  const executable = fs.existsSync(binPath) &&
85
98
  (process.platform === 'win32' || (fs.statSync(binPath).mode & 0o111) !== 0);
package/lib/gates.js CHANGED
@@ -10,18 +10,23 @@ const {
10
10
  } = require('./orchestration.js');
11
11
  const {
12
12
  RUN_STATES,
13
+ RUN_MODES,
13
14
  getCurrentRun,
14
15
  getGitRevision,
15
16
  loadRun,
16
17
  runsDir,
17
18
  transitionRun
18
19
  } = require('./run-state.js');
20
+ const {
21
+ assertModeAllowed
22
+ } = require('./runtime-policy.js');
19
23
  const {
20
24
  enforceVerdictTier
21
25
  } = require('./escalation.js');
22
26
 
23
27
  const GATE_FILES = Object.freeze({
24
28
  goal: 'goal-contract.json',
29
+ report: 'report.json',
25
30
  maker: 'diff.patch',
26
31
  verification: 'verification.json',
27
32
  review: 'findings.json',
@@ -181,6 +186,8 @@ function applyGate(rootDir, gate, { runId } = {}) {
181
186
  throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
182
187
  }
183
188
  const run = resolveRun(rootDir, runId);
189
+ const mode = run.mode || RUN_MODES.ASSISTED;
190
+ const policy = assertModeAllowed(rootDir, mode);
184
191
 
185
192
  if (gate === 'goal') {
186
193
  const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal);
@@ -193,7 +200,29 @@ function applyGate(rootDir, gate, { runId } = {}) {
193
200
  });
194
201
  }
195
202
 
203
+ if (gate === 'report') {
204
+ if (mode !== RUN_MODES.REPORT_ONLY) {
205
+ throw gateError('Report gate is only available in REPORT_ONLY mode');
206
+ }
207
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.report);
208
+ requireRunMetadata(value, run, 'report');
209
+ const reportErrors = [];
210
+ if (!String(value.summary || '').trim()) reportErrors.push('summary is required');
211
+ if (!Array.isArray(value.recommendations)) reportErrors.push('recommendations must be an array');
212
+ else if (value.recommendations.some((item) => !String(item || '').trim())) {
213
+ reportErrors.push('recommendations must contain non-empty strings');
214
+ }
215
+ if (reportErrors.length) throw gateError('Report gate failed', reportErrors);
216
+ return transitionRun(rootDir, run.runId, RUN_STATES.REPORTED, {
217
+ gate,
218
+ artifacts: { report: descriptor(rootDir, filePath) }
219
+ });
220
+ }
221
+
196
222
  if (gate === 'maker') {
223
+ if (mode === RUN_MODES.REPORT_ONLY) {
224
+ throw gateError('REPORT_ONLY mode cannot enter the Maker stage; finish with the report gate');
225
+ }
197
226
  const filePath = artifactPath(rootDir, run.runId, GATE_FILES.maker);
198
227
  let diff;
199
228
  try {
@@ -202,9 +231,31 @@ function applyGate(rootDir, gate, { runId } = {}) {
202
231
  throw gateError(`Missing ${GATE_FILES.maker}: ${cause.message}`);
203
232
  }
204
233
  if (!diff.trim()) throw gateError('Maker gate failed: diff.patch is empty');
234
+ const artifacts = { diff: descriptor(rootDir, filePath) };
235
+ if (mode === RUN_MODES.UNATTENDED && policy.requireSandboxForUnattended) {
236
+ const { filePath: sandboxFile, value: evidence } = readJsonArtifact(
237
+ rootDir,
238
+ run.runId,
239
+ 'sandbox-evidence.json'
240
+ );
241
+ const sandboxErrors = [];
242
+ requireRunMetadata(evidence, run, 'sandbox evidence');
243
+ if (evidence.sandboxed !== true) sandboxErrors.push('sandboxed must be true');
244
+ if (!/^[a-f0-9]{40,64}$/.test(String(evidence.baseRevision || ''))) {
245
+ sandboxErrors.push('baseRevision must be a Git revision');
246
+ }
247
+ if (evidence.baseRevision !== run.startedRevision) {
248
+ sandboxErrors.push('baseRevision does not match the run starting revision');
249
+ }
250
+ if (evidence.diffSha256 !== hashFile(filePath)) {
251
+ sandboxErrors.push('diffSha256 does not match the captured Maker diff');
252
+ }
253
+ if (sandboxErrors.length) throw gateError('Unattended Maker sandbox evidence failed', sandboxErrors);
254
+ artifacts.sandboxEvidence = descriptor(rootDir, sandboxFile);
255
+ }
205
256
  return transitionRun(rootDir, run.runId, RUN_STATES.MAKER_COMPLETE, {
206
257
  gate,
207
- artifacts: { diff: descriptor(rootDir, filePath) }
258
+ artifacts
208
259
  });
209
260
  }
210
261
 
@@ -295,6 +346,9 @@ function applyGate(rootDir, gate, { runId } = {}) {
295
346
  const deliveryErrors = [];
296
347
  if (!String(value.destination || '').trim()) deliveryErrors.push('destination is required');
297
348
  if (!String(value.summary || '').trim()) deliveryErrors.push('summary is required');
349
+ if (mode === RUN_MODES.ASSISTED && value.humanApproved !== true) {
350
+ deliveryErrors.push('humanApproved must be true for ASSISTED delivery');
351
+ }
298
352
  if (deliveryErrors.length) throw gateError('Delivery gate failed', deliveryErrors);
299
353
  return transitionRun(rootDir, run.runId, RUN_STATES.DELIVERED, {
300
354
  gate,
@@ -0,0 +1,78 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const TEXT_EXTENSIONS = new Set(['.js', '.json', '.md', '.yml', '.yaml', '.txt']);
7
+ const LOCAL_FILE_URL = new RegExp(`file:${'/'.repeat(3)}`, 'i');
8
+ const MAC_HOME = /\/Users\/(?!\.\.\.\/|<[^>]+>\/)[a-z0-9._-]+\//i;
9
+ const LINUX_HOME = /\/home\/(?!\.\.\.\/|<[^>]+>\/)[a-z0-9._-]+\//i;
10
+ const WINDOWS_HOME = /[a-z]:\\Users\\(?!\.\.\.\\|<[^>]+>\\)[^\\\r\n]+\\/i;
11
+ const PRIVATE_KEY = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/;
12
+
13
+ const PRIVACY_PATTERNS = Object.freeze([
14
+ { label: 'local file URL', pattern: LOCAL_FILE_URL },
15
+ { label: 'macOS user home', pattern: MAC_HOME },
16
+ { label: 'Linux user home', pattern: LINUX_HOME },
17
+ { label: 'Windows user home', pattern: WINDOWS_HOME },
18
+ { label: 'private key material', pattern: PRIVATE_KEY }
19
+ ]);
20
+
21
+ function walkFiles(rootDir, relativePath, files) {
22
+ const absolute = path.join(rootDir, relativePath);
23
+ if (!fs.existsSync(absolute)) return;
24
+ const stat = fs.lstatSync(absolute);
25
+ if (stat.isSymbolicLink()) return;
26
+ if (stat.isFile()) {
27
+ files.add(relativePath.split(path.sep).join('/'));
28
+ return;
29
+ }
30
+ if (!stat.isDirectory()) return;
31
+ for (const entry of fs.readdirSync(absolute)) {
32
+ walkFiles(rootDir, path.join(relativePath, entry), files);
33
+ }
34
+ }
35
+
36
+ function listPackageFiles(rootDir) {
37
+ const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
38
+ const files = new Set(['package.json']);
39
+ for (const entry of pkg.files || []) {
40
+ walkFiles(rootDir, entry.replace(/\/$/, ''), files);
41
+ }
42
+ for (const entry of fs.readdirSync(rootDir)) {
43
+ if (/^(?:readme|license|licence|security|support)(?:\.|$)/i.test(entry)) {
44
+ walkFiles(rootDir, entry, files);
45
+ }
46
+ }
47
+ return [...files].sort();
48
+ }
49
+
50
+ function auditText(content, relativePath) {
51
+ const findings = [];
52
+ for (const { label, pattern } of PRIVACY_PATTERNS) {
53
+ if (pattern.test(content)) findings.push({ file: relativePath, reason: label });
54
+ }
55
+ return findings;
56
+ }
57
+
58
+ function auditPackage(rootDir) {
59
+ const files = listPackageFiles(rootDir);
60
+ const findings = [];
61
+ for (const relativePath of files) {
62
+ if (!TEXT_EXTENSIONS.has(path.extname(relativePath).toLowerCase())) continue;
63
+ const content = fs.readFileSync(path.join(rootDir, relativePath), 'utf8');
64
+ findings.push(...auditText(content, relativePath));
65
+ }
66
+ return {
67
+ ok: findings.length === 0,
68
+ filesScanned: files.length,
69
+ findings
70
+ };
71
+ }
72
+
73
+ module.exports = {
74
+ PRIVACY_PATTERNS,
75
+ listPackageFiles,
76
+ auditText,
77
+ auditPackage
78
+ };
package/lib/run-state.js CHANGED
@@ -8,6 +8,7 @@ const { execFileSync } = require('child_process');
8
8
  const RUN_STATES = Object.freeze({
9
9
  STARTED: 'STARTED',
10
10
  GOAL_FROZEN: 'GOAL_FROZEN',
11
+ REPORTED: 'REPORTED',
11
12
  MAKER_COMPLETE: 'MAKER_COMPLETE',
12
13
  VERIFIED: 'VERIFIED',
13
14
  REVIEWED: 'REVIEWED',
@@ -16,9 +17,16 @@ const RUN_STATES = Object.freeze({
16
17
  ESCALATED: 'ESCALATED'
17
18
  });
18
19
 
20
+ const RUN_MODES = Object.freeze({
21
+ REPORT_ONLY: 'REPORT_ONLY',
22
+ ASSISTED: 'ASSISTED',
23
+ UNATTENDED: 'UNATTENDED'
24
+ });
25
+
19
26
  const ALLOWED_TRANSITIONS = Object.freeze({
20
27
  STARTED: ['GOAL_FROZEN'],
21
- GOAL_FROZEN: ['MAKER_COMPLETE'],
28
+ GOAL_FROZEN: ['REPORTED', 'MAKER_COMPLETE'],
29
+ REPORTED: [],
22
30
  MAKER_COMPLETE: ['VERIFIED'],
23
31
  VERIFIED: ['REVIEWED'],
24
32
  REVIEWED: ['GOAL_FROZEN', 'JUDGED_PASS', 'ESCALATED'],
@@ -27,7 +35,7 @@ const ALLOWED_TRANSITIONS = Object.freeze({
27
35
  ESCALATED: []
28
36
  });
29
37
 
30
- const TERMINAL_STATES = new Set([RUN_STATES.DELIVERED, RUN_STATES.ESCALATED]);
38
+ const TERMINAL_STATES = new Set([RUN_STATES.REPORTED, RUN_STATES.DELIVERED, RUN_STATES.ESCALATED]);
31
39
 
32
40
  function runsDir(rootDir) {
33
41
  return path.join(rootDir, '.ai-engineering-loop', 'runs');
@@ -42,11 +50,11 @@ function assertRunId(runId) {
42
50
  return runId;
43
51
  }
44
52
 
45
- function atomicWriteJson(filePath, value) {
53
+ function atomicWritePrivateFile(filePath, content) {
46
54
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
47
55
  const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
48
56
  try {
49
- fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
57
+ fs.writeFileSync(temporary, content, { mode: 0o600 });
50
58
  fs.renameSync(temporary, filePath);
51
59
  fs.chmodSync(filePath, 0o600);
52
60
  } finally {
@@ -58,6 +66,10 @@ function atomicWriteJson(filePath, value) {
58
66
  }
59
67
  }
60
68
 
69
+ function atomicWriteJson(filePath, value) {
70
+ atomicWritePrivateFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
71
+ }
72
+
61
73
  function readJson(filePath, label) {
62
74
  try {
63
75
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -96,7 +108,11 @@ function currentRunPath(rootDir) {
96
108
 
97
109
  function loadRun(rootDir, runId) {
98
110
  const state = readJson(runStatePath(rootDir, runId), `run ${runId}`);
99
- if (state.runId !== runId || !RUN_STATES[state.state]) {
111
+ if (
112
+ state.runId !== runId ||
113
+ !RUN_STATES[state.state] ||
114
+ (state.mode != null && !Object.values(RUN_MODES).includes(state.mode))
115
+ ) {
100
116
  const err = new Error(`Run ${runId} has an invalid state document`);
101
117
  err.code = 'INVALID_RUN_STATE';
102
118
  throw err;
@@ -111,7 +127,17 @@ function getCurrentRun(rootDir) {
111
127
  return loadRun(rootDir, assertRunId(runId));
112
128
  }
113
129
 
114
- function createRun(rootDir, { task = '', runId = newRunId(), now = new Date() } = {}) {
130
+ function normalizeRunMode(mode) {
131
+ const normalized = String(mode || RUN_MODES.ASSISTED).trim().replace(/-/g, '_').toUpperCase();
132
+ if (!Object.hasOwn(RUN_MODES, normalized)) {
133
+ const err = new Error(`Invalid run mode: ${mode}`);
134
+ err.code = 'INVALID_RUN_MODE';
135
+ throw err;
136
+ }
137
+ return RUN_MODES[normalized];
138
+ }
139
+
140
+ function createRun(rootDir, { task = '', runId = newRunId(), mode = RUN_MODES.ASSISTED, now = new Date() } = {}) {
115
141
  assertRunId(runId);
116
142
  const statePath = runStatePath(rootDir, runId);
117
143
  if (fs.existsSync(statePath)) {
@@ -125,6 +151,7 @@ function createRun(rootDir, { task = '', runId = newRunId(), now = new Date() }
125
151
  schemaVersion: 1,
126
152
  runId,
127
153
  state: RUN_STATES.STARTED,
154
+ mode: normalizeRunMode(mode),
128
155
  iteration: 1,
129
156
  task: String(task || '').trim(),
130
157
  startedRevision: getGitRevision(rootDir),
@@ -146,7 +173,7 @@ function createRun(rootDir, { task = '', runId = newRunId(), now = new Date() }
146
173
  return state;
147
174
  }
148
175
 
149
- function createOrResumeRun(rootDir, { task = '', forceNew = false, now = new Date() } = {}) {
176
+ function createOrResumeRun(rootDir, { task = '', mode = null, forceNew = false, now = new Date() } = {}) {
150
177
  const current = getCurrentRun(rootDir);
151
178
  const requestedTask = String(task || '').trim();
152
179
  if (current && !TERMINAL_STATES.has(current.state) && !forceNew) {
@@ -157,9 +184,17 @@ function createOrResumeRun(rootDir, { task = '', forceNew = false, now = new Dat
157
184
  err.code = 'ACTIVE_RUN';
158
185
  throw err;
159
186
  }
187
+ if (mode && normalizeRunMode(mode) !== (current.mode || RUN_MODES.ASSISTED)) {
188
+ const err = new Error(`Run ${current.runId} is already ${(current.mode || RUN_MODES.ASSISTED)}; mode cannot change during a run.`);
189
+ err.code = 'RUN_MODE_MISMATCH';
190
+ throw err;
191
+ }
160
192
  return { run: current, resumed: true };
161
193
  }
162
- return { run: createRun(rootDir, { task: requestedTask, now }), resumed: false };
194
+ return {
195
+ run: createRun(rootDir, { task: requestedTask, mode: mode || RUN_MODES.ASSISTED, now }),
196
+ resumed: false
197
+ };
163
198
  }
164
199
 
165
200
  function transitionRun(
@@ -205,14 +240,18 @@ function transitionRun(
205
240
 
206
241
  module.exports = {
207
242
  RUN_STATES,
243
+ RUN_MODES,
208
244
  ALLOWED_TRANSITIONS,
209
245
  TERMINAL_STATES,
210
246
  runsDir,
247
+ assertRunId,
211
248
  runStatePath,
212
249
  currentRunPath,
250
+ atomicWritePrivateFile,
213
251
  atomicWriteJson,
214
252
  getGitRevision,
215
253
  newRunId,
254
+ normalizeRunMode,
216
255
  loadRun,
217
256
  getCurrentRun,
218
257
  createRun,
@@ -0,0 +1,53 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const PRIVATE_RUNTIME_PATTERNS = Object.freeze([
7
+ 'runs/',
8
+ 'usage/',
9
+ 'worktrees/',
10
+ 'locks/',
11
+ 'tasks/current.diff',
12
+ 'tasks/*.log'
13
+ ]);
14
+
15
+ const PRIVATE_RUNTIME_GITIGNORE =
16
+ `# Runtime artifacts may contain source excerpts and verification logs.\n${PRIVATE_RUNTIME_PATTERNS.join('\n')}\n`;
17
+
18
+ function assertNotSymlink(filePath, label) {
19
+ let stat;
20
+ try {
21
+ stat = fs.lstatSync(filePath);
22
+ } catch (cause) {
23
+ if (cause.code !== 'ENOENT') throw cause;
24
+ }
25
+ if (stat?.isSymbolicLink()) {
26
+ const err = new Error(`${label} must not be a symbolic link`);
27
+ err.code = 'UNSAFE_RUNTIME_PATH';
28
+ throw err;
29
+ }
30
+ }
31
+
32
+ function ensurePrivateRuntimeIgnores(rootDir) {
33
+ const contextDir = path.join(rootDir, '.ai-engineering-loop');
34
+ assertNotSymlink(contextDir, '.ai-engineering-loop');
35
+ fs.mkdirSync(contextDir, { recursive: true });
36
+ const filePath = path.join(contextDir, '.gitignore');
37
+ assertNotSymlink(filePath, '.ai-engineering-loop/.gitignore');
38
+ const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
39
+ const missing = PRIVATE_RUNTIME_PATTERNS.filter((pattern) => (
40
+ !existing.split(/\r?\n/).includes(pattern)
41
+ ));
42
+ if (missing.length === 0) return false;
43
+ const separator = existing && !existing.endsWith('\n') ? '\n' : '';
44
+ const header = existing ? '' : '# Runtime artifacts may contain source excerpts and verification logs.\n';
45
+ fs.writeFileSync(filePath, `${existing}${separator}${header}${missing.join('\n')}\n`);
46
+ return true;
47
+ }
48
+
49
+ module.exports = {
50
+ PRIVATE_RUNTIME_PATTERNS,
51
+ PRIVATE_RUNTIME_GITIGNORE,
52
+ ensurePrivateRuntimeIgnores
53
+ };