sumo-agents 0.0.0-stage → 0.3.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 (66) hide show
  1. package/AGENTS.md +38 -0
  2. package/LICENSE +21 -0
  3. package/README.md +111 -2
  4. package/bin/sumo.mjs +33 -0
  5. package/guides/delegation.md +33 -0
  6. package/guides/feature.md +14 -0
  7. package/guides/fix.md +14 -0
  8. package/guides/memory.md +23 -0
  9. package/guides/projects.md +27 -0
  10. package/guides/review.md +16 -0
  11. package/guides/workflows.md +26 -0
  12. package/logo.txt +19 -0
  13. package/package.json +42 -4
  14. package/prompts/agent.md +7 -0
  15. package/prompts/dream.md +13 -0
  16. package/prompts/scribe.md +21 -0
  17. package/spinner.txt +90 -0
  18. package/src/advisor.mjs +59 -0
  19. package/src/apply.mjs +368 -0
  20. package/src/auth.mjs +80 -0
  21. package/src/card.mjs +72 -0
  22. package/src/catalog.mjs +167 -0
  23. package/src/chat.mjs +1162 -0
  24. package/src/cli.mjs +815 -0
  25. package/src/cost.mjs +128 -0
  26. package/src/db.mjs +384 -0
  27. package/src/dream.mjs +97 -0
  28. package/src/editor.mjs +198 -0
  29. package/src/export.mjs +132 -0
  30. package/src/guard.mjs +121 -0
  31. package/src/guides.mjs +86 -0
  32. package/src/herdr.mjs +117 -0
  33. package/src/hooks.mjs +270 -0
  34. package/src/images.mjs +89 -0
  35. package/src/jobs.mjs +1184 -0
  36. package/src/jobtools.mjs +82 -0
  37. package/src/local-server.mjs +169 -0
  38. package/src/lock.mjs +45 -0
  39. package/src/loop.mjs +838 -0
  40. package/src/mcp.mjs +604 -0
  41. package/src/memory.mjs +400 -0
  42. package/src/model.mjs +270 -0
  43. package/src/page.html +304 -0
  44. package/src/page.mjs +135 -0
  45. package/src/paths.mjs +33 -0
  46. package/src/prime.mjs +177 -0
  47. package/src/projects.mjs +232 -0
  48. package/src/recall.mjs +45 -0
  49. package/src/redact.mjs +173 -0
  50. package/src/render.mjs +45 -0
  51. package/src/route.mjs +287 -0
  52. package/src/sandbox.mjs +173 -0
  53. package/src/scan.mjs +204 -0
  54. package/src/scribe.mjs +349 -0
  55. package/src/sessions.mjs +371 -0
  56. package/src/setup.mjs +528 -0
  57. package/src/sqlite.mjs +66 -0
  58. package/src/text.mjs +97 -0
  59. package/src/tools.mjs +987 -0
  60. package/src/transcript.mjs +106 -0
  61. package/src/tty.mjs +529 -0
  62. package/src/ui.mjs +1363 -0
  63. package/src/verify.mjs +369 -0
  64. package/src/web.mjs +49 -0
  65. package/src/workflows.mjs +270 -0
  66. package/src/worktree.mjs +128 -0
package/src/jobs.mjs ADDED
@@ -0,0 +1,1184 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { createHash } from 'node:crypto';
3
+ import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
4
+ import { join } from 'node:path';
5
+ import { applyOps } from './apply.mjs';
6
+ import { card } from './card.mjs';
7
+ import { usableModels } from './catalog.mjs';
8
+ import { getMeta, setMeta, tx } from './db.mjs';
9
+ import { autoGuides, guideBody, matchGuide, WORKER_GUIDES } from './guides.mjs';
10
+ import { heldBy } from './lock.mjs';
11
+ import { UsageError } from './memory.mjs';
12
+ import { callModel, failure, logRun } from './model.mjs';
13
+ import { paths } from './paths.mjs';
14
+ import { preferences } from './prime.mjs';
15
+ import { getProject, isScratch } from './projects.mjs';
16
+ import { chooseRoute, RETRY_IMPORTANT_THRESHOLD, statsLines } from './route.mjs';
17
+ import { verifyCommands } from './scan.mjs';
18
+ import { runScribe } from './scribe.mjs';
19
+ import { addCheckpoint, pendingTurns } from './sessions.mjs';
20
+ import { CONFIG_DEFAULTS } from './setup.mjs';
21
+ import { clip, estimateTokens, head, STOPWORDS } from './text.mjs';
22
+ import { changesSince, diffStat, hasCommit, snapshot, stillThere, takeBaseline, verdictLines, verify, writeChanges } from './verify.mjs';
23
+ import { bringBack, dropTree, makeTree, treeDiff } from './worktree.mjs';
24
+
25
+ const AGENTS = ['scout', 'worker', 'reviewer'];
26
+ /** Work with a written way of doing it: guides/<name>.md, carried into the brief on request. */
27
+ const GUIDES = ['fix', 'feature', 'review'];
28
+ const BRIEF_CARD_BUDGET = 400;
29
+ /** The user's own rules — global preferences and decisions — ride with every brief, the way the memory block opens every chat. */
30
+ const BRIEF_RULES_BUDGET = 400;
31
+ /** Where the project stands as a job begins — branch, what is uncommitted, the top level, the toolchain — heading included. */
32
+ const BRIEF_SITUATION_BUDGET = 150;
33
+ const MAX_LEARNED = 5;
34
+
35
+ export function parseJobId(raw) {
36
+ const match = /^j?(\d+)$/.exec(String(raw ?? '').trim());
37
+ if (!match) throw new UsageError(`"${raw}" is not a job id — ids look like j17`);
38
+ return Number(match[1]);
39
+ }
40
+
41
+ export function getJob(db, id) {
42
+ const job = db.prepare('SELECT * FROM jobs WHERE id = ?').get(id);
43
+ if (!job) throw new UsageError(`no job j${id}`);
44
+ return job;
45
+ }
46
+
47
+ const dirOf = (id) => join(paths().jobs, String(id));
48
+ const fileOf = (id, name) => join(dirOf(id), name);
49
+ const readOr = (file) => {
50
+ try {
51
+ return readFileSync(file, 'utf8');
52
+ } catch {
53
+ return '';
54
+ }
55
+ };
56
+
57
+ /** The lock a job's run holds while it runs (src/loop.mjs): it names the process. */
58
+ export const runLockFile = (id) => fileOf(id, 'run.lock');
59
+ /** Whether a job is being run right now: its run lock held by a live process. One a stop left open — budget, time, Esc — is not. */
60
+ const atWork = (id) => heldBy(runLockFile(id)) !== null;
61
+ /** How long a worker made and not yet run still counts as at work: the time between `sumo job new` and its run. */
62
+ const FRESH_MS = 10 * 60_000;
63
+ /** The open workers in a project, but one, the newest first. */
64
+ const openWorkers = (db, slug, id) => db.prepare(`SELECT * FROM jobs WHERE project = ? AND agent = 'worker' AND status IN ('running', 'needs_input') AND id <> ? ORDER BY id DESC`).all(slug, id);
65
+ /** A meta key taken off, so what it marked can happen again. */
66
+ const unmark = (db, key) => db.prepare('DELETE FROM meta WHERE key = ?').run(key);
67
+ function setStatus(db, id, status, now) {
68
+ db.prepare('UPDATE jobs SET status = ?, updated_at = ? WHERE id = ?').run(status, now, id);
69
+ }
70
+
71
+ /**
72
+ * A change of state that holds only while the job is still open. A note or a question is written to disk between the
73
+ * check and the change: a job abandoned or closed meanwhile stays as it was left, never reopened by a status read earlier.
74
+ */
75
+ function setOpenStatus(db, id, status, now) {
76
+ db.prepare(`UPDATE jobs SET status = COALESCE(?, status), updated_at = ? WHERE id = ? AND status IN ('running', 'needs_input')`).run(status, now, id);
77
+ }
78
+
79
+ function requireOpen(job, verb) {
80
+ if (job.status !== 'running' && job.status !== 'needs_input') throw new UsageError(`j${job.id} is ${job.status} — it cannot be ${verb}`);
81
+ }
82
+
83
+ const ROLE = {
84
+ worker: 'You are a worker: you build, fix and change things in the project below.',
85
+ scout:
86
+ 'You are a scout: you investigate the project below and report what you found. You have no edit tools and none can be granted — ' +
87
+ 'that is by design, so do not look for one. If something should change, say exactly what and in which file.',
88
+ reviewer:
89
+ 'You are a reviewer: you judge a change somebody else made in the project below. You did not write it and you owe it nothing. ' +
90
+ 'You have no edit tools and none can be granted — that is by design. If something should change, say exactly what and in which file.',
91
+ };
92
+
93
+ const LEARNED = `## Learned usually "none". Only a trap that cost you time and would cost the next person time —
94
+ a required env var, a misleading error, a command that silently does the wrong thing.
95
+ What you found out belongs in Summary, not here.`;
96
+
97
+ /** What each kind of sub-agent sends back. The headings are read by code and by the main agent, so they are fixed. */
98
+ const REPORT = {
99
+ scout: ` ## Summary
100
+ ## Files changed one line each: <path> — <what changed>
101
+ ## Check the command you ran and what it printed; or why there is none
102
+ ${LEARNED}`,
103
+ worker: ` ## Summary
104
+ ## Files changed one line each: <path> — <what changed>
105
+ ## Check the command you ran and what it printed; or why there is none
106
+ ## Concerns "none", or what you finished but are not sure of. Never hand over doubt silently.
107
+ ## Decisions "none", or each call you made for the user: what — why — what it costs if wrong
108
+ ${LEARNED}`,
109
+ reviewer: ` ## Summary one line: does it do what was asked, and can it be trusted as it stands
110
+ ## Asked vs built missing · extra · misunderstood — or "matches"
111
+ ## Findings numbered, worst first: \`1. <file:line> — how it fails, concretely — the smallest fix or test\`. No praise, no rewrites.
112
+ ## Minor listed, never a reason to reopen the work
113
+ ## Could not verify what the change alone cannot show — it lives in code that did not change
114
+ ${LEARNED}`,
115
+ };
116
+
117
+ /** How a worker's result gets judged. Said up front, because a rule met only at the end reads as a trap. */
118
+ function workerRules(job, { testsMayChange }) {
119
+ return `- Before you edit anything: \`baseline\` (allow it ten minutes). It runs the project's checks and records what already fails, so none of that is blamed on you — and nothing you break can hide behind it.
120
+ - Tests that are already here judge your change; they are not part of it. ${
121
+ testsMayChange
122
+ ? 'This task may change them — say in the report which, and why.'
123
+ : `Do not edit, skip or delete one. A test that is genuinely wrong, or that contradicts the task: stop and say why with \`ask\`.`
124
+ } Never loosen a lint or type setting, add an ignore, or special-case a test's input to get green.
125
+ - A question you can settle yourself: decide, carry on, and list it under Decisions. Stop and ask only for something destructive or irreversible, security-sensitive, outside this project, or a task so unclear that every path is a guess.
126
+ - You do not start other jobs. Review comes after you, from someone who did not write the code.
127
+ - At each major milestone (a phase of the task done) \`note\` one line — \`<what now works>; next: <step>\`. Nothing else in between.
128
+ - A task of several steps: \`note\` the plan first, as a checklist — one \`- [ ] <step>\` a line — and at each milestone note the list again, whole, with what is done ticked \`- [x]\`; the latest list is put back in front of you as you work.
129
+ `;
130
+ }
131
+
132
+ /** The toolchains a project's own files call for, and the command that says each one's version. */
133
+ const TOOLCHAINS = [
134
+ { name: 'node', files: ['package.json'], command: 'node', args: ['-v'] },
135
+ { name: 'go', files: ['go.mod'], command: 'go', args: ['version'] },
136
+ { name: 'python', files: ['pyproject.toml', 'requirements.txt'], command: 'python3', args: ['--version'] },
137
+ { name: 'cargo', files: ['Cargo.toml'], command: 'cargo', args: ['--version'] },
138
+ ];
139
+ const LOOK_TIMEOUT_MS = 3000;
140
+ const STATUS_LINES = 15;
141
+ const TOP_LEVEL_NAMES = 30;
142
+
143
+ /** As many of `items` as fit in `room` tokens, `max` at most, as `say(shown, left)` puts them: whole items are left out to fit, and counted. */
144
+ function fitted(items, max, room, say) {
145
+ let shown = items.slice(0, max);
146
+ while (shown.length > 0 && estimateTokens(say(shown, items.length - shown.length)) > room) shown = shown.slice(0, -1);
147
+ return say(shown, items.length - shown.length);
148
+ }
149
+
150
+ /**
151
+ * Where the project stands as a job begins — its branch, what is uncommitted, what is at its top level, the toolchain
152
+ * its files call for — so the job's first turns are not spent finding out. Each command is given three seconds and
153
+ * left out if it fails; outside git there are no git lines. What is uncommitted matters most, so the top level takes
154
+ * at most half the room. Empty when there is nothing to say.
155
+ */
156
+ function whereThingsStand(root) {
157
+ const run = (command, args) => {
158
+ try {
159
+ return execFileSync(command, args, { cwd: root, encoding: 'utf8', timeout: LOOK_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'] });
160
+ } catch {
161
+ return null;
162
+ }
163
+ };
164
+ const git = (...args) => run('git', ['--no-optional-locks', '-c', 'core.quotePath=false', ...args]);
165
+ const repo = git('rev-parse', '--is-inside-work-tree')?.trim() === 'true';
166
+ const heading = '## Where things stand as this job begins — no need to look it up again';
167
+ const lines = [];
168
+ if (repo) {
169
+ const branch = git('branch', '--show-current')?.trim();
170
+ const head = branch ? null : git('rev-parse', '--short', 'HEAD')?.trim();
171
+ if (branch || head) lines.push(`Branch: ${branch || `none — detached at ${head}`}`);
172
+ }
173
+ const versions = TOOLCHAINS.filter((t) => t.files.some((f) => existsSync(join(root, f)))).flatMap((t) => {
174
+ const version = /\d+(?:\.\d+)+/.exec(run(t.command, t.args) ?? '')?.[0];
175
+ return version ? [`${t.name} ${version}`] : [];
176
+ });
177
+ if (versions.length > 0) lines.push(`Toolchain: ${versions.join(' · ')}`);
178
+
179
+ const cost = (text) => estimateTokens(text) + 1;
180
+ let room = BRIEF_SITUATION_BUDGET - cost(heading) - lines.reduce((sum, line) => sum + cost(line), 0);
181
+ const status = repo ? git('status', '--short', '--', '.') : null;
182
+ let names = null;
183
+ try {
184
+ names = readdirSync(root).filter((name) => !name.startsWith('.')).sort((a, b) => a.localeCompare(b));
185
+ } catch {
186
+ // A folder that cannot be read has no top level to show.
187
+ }
188
+ if (names) {
189
+ const isDir = (name) => {
190
+ try {
191
+ return statSync(join(root, name)).isDirectory();
192
+ } catch {
193
+ return false;
194
+ }
195
+ };
196
+ const marked = names.map((name, i) => (i < TOP_LEVEL_NAMES && isDir(name) ? `${name}/` : name));
197
+ const line = fitted(marked, TOP_LEVEL_NAMES, (status === null ? room : room / 2) - 1, (shown, left) => `Top level: ${[...shown, ...(left > 0 ? [`… ${left} more`] : [])].join(' ') || 'nothing'}`);
198
+ lines.push(line);
199
+ room -= cost(line);
200
+ }
201
+ if (status !== null) {
202
+ const changed = status.split('\n').filter((l) => l.trim());
203
+ lines.push(changed.length === 0 ? 'git status --short: clean' : fitted(changed, STATUS_LINES, room - 1, (shown, left) => ['git status --short:', ...shown, ...(left > 0 ? [`… ${left} more`] : [])].join('\n')));
204
+ }
205
+ return lines.length > 0 ? [heading, ...lines].join('\n') : '';
206
+ }
207
+
208
+ function renderBrief({ job, project, known, rules, situation, task, guide, change, options = {} }) {
209
+ const closing =
210
+ job.agent === 'worker'
211
+ ? `\`finish\` with DONE (or FAILED). DONE is not taken on your word: the first is answered with the task beside your change, to look over once more; the next has the project's checks run and compared with the baseline, and is refused while something new fails. See the verdict first with \`verify\` (allow it ten minutes). The report:`
212
+ : `\`finish\` with DONE (or FAILED), and this report:`;
213
+ return `# Job j${job.id} — ${job.title}
214
+
215
+ ${ROLE[job.agent]}
216
+ Work only inside: ${project.path} (bash starts there; give files by absolute path)
217
+
218
+ ## What is already known about this project
219
+ ${known}
220
+ ${rules ? `\n## The user's standing rules — they hold here too\n${rules}\n` : ''}${situation ? `\n${situation}\n` : ''}
221
+ ## The task
222
+ ${task.trim()}
223
+ ${change ? `\n## The change to judge\n${change}\n` : ''}${guide ? `\n## How this kind of work is done here\n${guide}\n` : ''}
224
+ ## How to work
225
+ ${job.agent === 'worker' ? workerRules(job, options) : ''}- Worth keeping if you are interrupted — what you found, what you tried, what is left: \`note\`.
226
+ - When finished you must close the job, or nobody knows it ended: ${closing}
227
+ ${REPORT[job.agent]}
228
+ `;
229
+ }
230
+
231
+ const digest = (text) => createHash('sha256').update(text).digest('hex');
232
+ const stateKey = (id) => `job.${id}.verify`;
233
+
234
+ /**
235
+ * What code has recorded about a job's work: where it began, what already failed, and the last verdict.
236
+ * The job's shell can reach its folder, so the file is checked against the digest sumo kept when it wrote it:
237
+ * a record changed since — a baseline made to fail, a verdict made to pass — reads as none.
238
+ */
239
+ export const readState = (db, id) => {
240
+ try {
241
+ const text = readFileSync(fileOf(id, 'verify.json'), 'utf8');
242
+ const kept = getMeta(db, stateKey(id));
243
+ if (kept !== null && kept !== digest(text)) return null;
244
+ return JSON.parse(text);
245
+ } catch {
246
+ return null;
247
+ }
248
+ };
249
+ /** Written whole and then put in place: a run that dies half-way must not leave a record that reads as none. */
250
+ const writeState = (db, id, state) => {
251
+ const text = `${JSON.stringify(state, null, 2)}\n`;
252
+ const whole = fileOf(id, 'verify.json.part');
253
+ writeFileSync(whole, text, { mode: 0o600 });
254
+ setMeta(db, stateKey(id), digest(text));
255
+ renameSync(whole, fileOf(id, 'verify.json'));
256
+ };
257
+
258
+ /** The written way of doing one kind of work, without its title — the brief has its own heading for it. */
259
+ export function guideFor(name) {
260
+ if (!GUIDES.includes(name)) throw new UsageError(`--guide is one of: ${[...GUIDES, 'none'].join(', ')}`);
261
+ const text = guideBody(name);
262
+ if (!text) throw new UsageError(`guides/${name}.md is missing or empty`);
263
+ return text;
264
+ }
265
+
266
+ /**
267
+ * The guide a job carries when none is named: a reviewer always review; a worker the one its title and goal ask
268
+ * for, the way the chat is handed one by the user's words — unless the switch is off. A scout changes nothing.
269
+ */
270
+ function defaultGuide(db, { agent, title, task }) {
271
+ if (agent === 'reviewer') return 'review';
272
+ if (agent !== 'worker' || !autoGuides(db)) return null;
273
+ return matchGuide(`${title}\n${task.split(/\n(?=## )/)[0]}`, WORKER_GUIDES);
274
+ }
275
+
276
+ /**
277
+ * The change a reviewer is pointed at: another job's work, or whatever is
278
+ * uncommitted right now. Settled before the job exists, so a review of nothing
279
+ * is refused instead of created.
280
+ */
281
+ function changeToJudge(db, { project, reviews }) {
282
+ const lines = [];
283
+ let snap;
284
+ let root = project.path;
285
+ let kept = null;
286
+ if (reviews !== undefined) {
287
+ const target = getJob(db, reviews);
288
+ if (target.project !== project.slug) throw new UsageError(`j${target.id} belongs to ${target.project}, not ${project.slug}`);
289
+ const state = readState(db, target.id);
290
+ snap = state?.snap;
291
+ // A change still in the worktree it was made in is judged there.
292
+ if (state?.tree && existsSync(state.tree.path)) root = state.tree.path;
293
+ if (!snap) throw new UsageError(`j${target.id} recorded no starting point (not a worker job, or not a git repository) — there is no change to hand over`);
294
+ // One whose worktree is gone is judged by what it kept as it went (`changes`), not by the project against the tree's start:
295
+ // the project holds that change and more — what git ignores, what was never added — none of it the job's.
296
+ if (state.tree && !existsSync(state.tree.path)) kept = changes(db, target.id);
297
+ lines.push(`What was asked: ${fileOf(target.id, 'brief.md')} (read "## The task")`);
298
+ if (existsSync(fileOf(target.id, 'report.md'))) {
299
+ lines.push(`What its author says they did: ${fileOf(target.id, 'report.md')} — claims, not facts. A stated reason never makes a finding smaller.`);
300
+ }
301
+ } else {
302
+ if (!hasCommit(project.path)) throw new UsageError(`${project.path} is not a git repository with a commit — there is no change to hand over`);
303
+ snap = { base: 'HEAD', mixed: false, untracked: [] };
304
+ }
305
+ if (kept) {
306
+ if (kept.files === 0) throw new UsageError('nothing has changed — there is nothing to review');
307
+ return { snap, lines, root, kept };
308
+ }
309
+ const { tracked, created } = changesSince(root, snap);
310
+ if (tracked.length + created.length === 0) throw new UsageError('nothing has changed — there is nothing to review');
311
+ return { snap, lines, root };
312
+ }
313
+
314
+ const reviewsFile = (id) => fileOf(id, 'reviews.json');
315
+ /** The job a reviewer job was created to judge — set once, at creation, from `--reviews`. */
316
+ function recordReviewTarget(id, targetId) {
317
+ writeFileSync(reviewsFile(id), `${JSON.stringify({ reviews: targetId })}\n`, { mode: 0o600 });
318
+ }
319
+ function reviewTargetOf(id) {
320
+ try {
321
+ return JSON.parse(readFileSync(reviewsFile(id), 'utf8')).reviews;
322
+ } catch {
323
+ return null;
324
+ }
325
+ }
326
+
327
+ /** How lately a scout's answer still counts for the next scout, how much of its title the new one must share, and how many are offered. */
328
+ const ASKED_DAYS = 14;
329
+ const ASKED_ALIKE = 0.6;
330
+ const ASKED_SHOWN = 2;
331
+
332
+ /** The words of a title that say what it is about: lowercased, without stop words or words under three letters. */
333
+ const titleWords = (title) => new Set((title.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? []).filter((w) => w.length >= 3 && !STOPWORDS.has(w)));
334
+
335
+ /**
336
+ * Earlier scouts on the project, closed DONE in the last two weeks with a report, whose title has most of its words in
337
+ * this one's: a line for each of the two closest — the newer first of two as close — saying where to read the answer.
338
+ */
339
+ function askedBefore(db, slug, title, now) {
340
+ const mine = titleWords(title);
341
+ const since = new Date(Date.parse(now) - ASKED_DAYS * 86_400_000).toISOString();
342
+ const rows = db.prepare(`SELECT id, title, updated_at FROM jobs WHERE project = ? AND agent = 'scout' AND status = 'done' AND updated_at >= ?`).all(slug, since);
343
+ return rows
344
+ .filter((row) => existsSync(fileOf(row.id, 'report.md')))
345
+ .map((row) => {
346
+ const theirs = titleWords(row.title);
347
+ return { row, share: theirs.size === 0 ? 0 : [...theirs].filter((w) => mine.has(w)).length / theirs.size };
348
+ })
349
+ .filter(({ share }) => share >= ASKED_ALIKE)
350
+ .sort((a, b) => b.share - a.share || b.row.updated_at.localeCompare(a.row.updated_at))
351
+ .slice(0, ASKED_SHOWN)
352
+ .map(({ row }) => `A scout answered a similar question on ${row.updated_at.slice(0, 10)} — j${row.id} "${row.title}": read it with \`sumo job show ${row.id}\` and reuse what still holds.`);
353
+ }
354
+
355
+ /**
356
+ * Creates a job and its brief. The brief carries what memory knows about the
357
+ * project, so the sub-agent starts with its context instead of spending turns
358
+ * finding it — and the main agent's conversation never has to hold it. Its
359
+ * model and effort are the local router's answer under the route policy
360
+ * (`chooseRoute`, src/route.mjs), asked before the row is written: no answer, no job.
361
+ * A worker that finds another one open in its git project is given a worktree of its
362
+ * own (src/worktree.mjs), as is each of several `attempts` (`ownTree`, the route they
363
+ * share given once). A scout is pointed at what earlier scouts answered to much the
364
+ * same question (`askedBefore`).
365
+ */
366
+ export async function newJob(db, { project: nameOrAlias, title, agent = 'worker', task, guide: guideName, reviews, testsMayChange = false, retryOf, start, attempts = 1, ownTree = false, route: routed, now = new Date().toISOString() }) {
367
+ if (attempts !== 1) return newAttempts(db, { project: nameOrAlias, title, agent, task, guide: guideName, testsMayChange, attempts, now });
368
+ if (!AGENTS.includes(agent)) throw new UsageError(`--agent is one of: ${AGENTS.join(', ')}`);
369
+ if (!title?.trim()) throw new UsageError('a job needs a --title');
370
+ if (!task?.trim()) throw new UsageError('describe the task on stdin — see guides/delegation.md for the five headings');
371
+ if (reviews !== undefined && agent !== 'reviewer') throw new UsageError('--reviews goes with --agent reviewer');
372
+ const project = getProject(db, nameOrAlias);
373
+ // Everything that can refuse the job is settled before the job exists.
374
+ const chosen = guideName === 'none' ? null : (guideName ?? defaultGuide(db, { agent, title, task }));
375
+ const guide = chosen ? guideFor(chosen) : null;
376
+ const judged = agent === 'reviewer' ? changeToJudge(db, { project, reviews }) : null;
377
+
378
+ // A rule the user stated a minute ago may not be filed yet, and the brief is built from memory.
379
+ if (pendingTurns(db, 1).length > 0) await runScribe(db, { now });
380
+
381
+ const route = routed ?? (await chooseRoute(db, { agent, project, task, title: title.trim(), retryOf, reviews }));
382
+
383
+ // A job's own stand-in session (`job:j3`, see loop.mjs) is no one's conversation: it is never the session a new job belongs to.
384
+ const session = db.prepare(`SELECT id FROM sessions WHERE id NOT LIKE 'job:%' ORDER BY COALESCE(last_turn_at, started_at) DESC LIMIT 1`).get();
385
+ const { job, other } = tx(db, () => {
386
+ // A database put back from a backup has an older counter than the job folders on disk: the next id must not be one
387
+ // whose folder is still there, or the new job reads another job's notes and report as its own.
388
+ const onDisk = existsSync(paths().jobs) ? Math.max(0, ...readdirSync(paths().jobs).filter((name) => /^\d+$/.test(name)).map(Number)) : 0;
389
+ const counter = db.prepare(`SELECT seq FROM sqlite_sequence WHERE name = 'jobs'`).get()?.seq ?? 0;
390
+ if (onDisk > counter) {
391
+ if (db.prepare(`UPDATE sqlite_sequence SET seq = ? WHERE name = 'jobs'`).run(onDisk).changes === 0) {
392
+ db.prepare(`INSERT INTO sqlite_sequence (name, seq) VALUES ('jobs', ?)`).run(onDisk);
393
+ }
394
+ }
395
+ const { lastInsertRowid } = db
396
+ .prepare(
397
+ `INSERT INTO jobs (project, title, agent, status, session_id, created_at, updated_at, model, effort, route_reason, retry_of, risky)
398
+ VALUES (?, ?, ?, 'running', ?, ?, ?, ?, ?, ?, ?, ?)`,
399
+ )
400
+ .run(project.slug, title.trim(), agent, session?.id ?? null, now, now, route.model, route.effort, route.reason, retryOf ?? null, route.risky ? 1 : 0);
401
+ const id = Number(lastInsertRowid);
402
+ // Asked where the job is written: of two workers made at once, the second always sees the first. Only a worker at work counts —
403
+ // its run lock held — or one made in the last ten minutes, maybe not run yet: a job a stop left open is worked by nobody.
404
+ const since = new Date(Date.parse(now) - FRESH_MS).toISOString();
405
+ return { job: getJob(db, id), other: agent === 'worker' ? openWorkers(db, project.slug, id).find((o) => o.created_at >= since || atWork(o.id)) : undefined };
406
+ });
407
+ // Two workers in one working tree overwrite each other: in a git project the second is given a worktree of its own.
408
+ const own = agent === 'worker' && (ownTree || other !== undefined) && hasCommit(project.path);
409
+ let tree = null;
410
+
411
+ // The job's files. If any of them cannot be written the job is taken back: an open job with no brief is worse than no job.
412
+ try {
413
+ const known = card(db, project.slug, { budget: BRIEF_CARD_BUDGET, now }).split('\n').slice(1, -1).join('\n') || 'Nothing yet.';
414
+ const rules = preferences(db, BRIEF_RULES_BUDGET).slice(1).join('\n');
415
+ mkdirSync(dirOf(job.id), { recursive: true, mode: 0o700 });
416
+ if (agent === 'reviewer' && reviews !== undefined) recordReviewTarget(job.id, reviews);
417
+ if (own) tree = makeTree(project.path, join(dirOf(job.id), 'tree'));
418
+ const where = tree?.path ?? project.path;
419
+
420
+ let change = null;
421
+ if (judged) {
422
+ const own = fileOf(job.id, 'changes.diff');
423
+ if (judged.kept) copyFileSync(judged.kept.file, own);
424
+ const { file, files } = judged.kept ? { file: own, files: judged.kept.files } : writeChanges(judged.root, judged.snap, own);
425
+ change = [...judged.lines, `The whole change, ${files} file${files === 1 ? '' : 's'}: ${file} — read it once; do not re-derive it with git.`].join('\n');
426
+ }
427
+ // Where a worker starts from, and the checks that judge it there, so what it changed — and only that — can be told apart later.
428
+ // A retry is handed the first attempt's start instead — one in the project, never in a worktree made just now.
429
+ const begin = start && !tree ? start : { snap: snapshot(where), declared: verifyCommands(where), baseline: null };
430
+ if (agent === 'worker') writeState(db, job.id, { ...begin, testsMayChange, verdict: null, ...(tree ? { tree } : {}) });
431
+ writeFileSync(fileOf(job.id, 'brief.md'), renderBrief({ job, project: { ...project, path: where }, known, rules, situation: whereThingsStand(where), task, guide, change, options: { testsMayChange } }), { mode: 0o600 });
432
+ if (tree) {
433
+ const why = ownTree
434
+ ? 'Several attempts are made at this task, each in a git worktree of its own; the one to keep is picked once all have closed.'
435
+ : `j${other.id} "${other.title}" is another worker open in ${project.path}, so this job has a git worktree of its own; when it is done, its change is brought back to the project.`;
436
+ // The project's installed dependencies are linked in (makeTree): outside the job's roots, the sandbox lets it read them, never change them.
437
+ const deps =
438
+ tree.linked?.length > 0
439
+ ? ` The project's installed dependencies — ${tree.linked.join(', ')} — are its own, linked in: the checks run with them, and they are read-only here; if one must be added or changed, say so in the report. A workspace package or an editable install reached through them is the project's copy, not this tree's: a check that loads one tests the project's code, not your change to it.`
440
+ : ' If the checks need installed dependencies, install them there.';
441
+ appendFileSync(fileOf(job.id, 'brief.md'), `\n## Where you work\n${why} Files git ignores — build output and the like — were not copied into it.${deps}\n`, { mode: 0o600 });
442
+ }
443
+ // A question a scout answered lately is not asked from nothing again: the brief points at those answers, and the job goes ahead.
444
+ const asked = agent === 'scout' ? askedBefore(db, project.slug, title.trim(), now) : [];
445
+ if (asked.length > 0) appendFileSync(fileOf(job.id, 'brief.md'), `\n## Asked before\n${asked.join('\n')}\n`, { mode: 0o600 });
446
+ } catch (cause) {
447
+ db.prepare('DELETE FROM jobs WHERE id = ?').run(job.id);
448
+ try {
449
+ if (own) dropTree(project.path, join(dirOf(job.id), 'tree'));
450
+ rmSync(dirOf(job.id), { recursive: true, force: true });
451
+ } catch {
452
+ // Nothing was written there.
453
+ }
454
+ throw cause;
455
+ }
456
+
457
+ const warnings = [];
458
+ if (agent !== 'reviewer' && !/^#{1,3}\s*(the\s+)?check\b|^check\s*:/im.test(task)) {
459
+ warnings.push('note: the task names no check that proves the work — add a "## Check" with a command, or say why there is none');
460
+ }
461
+ if (other && tree) warnings.push(`note: j${other.id} "${other.title}" is already a worker in ${project.slug} — this one works in a worktree of its own, ${tree.top}, and its change is brought back when it is done`);
462
+ else if (other) warnings.push(`note: j${other.id} "${other.title}" is already a running worker in ${project.slug} — two workers in one working tree overwrite each other. Let it finish, or: sumo job abandon ${other.id}`);
463
+ return { job, warnings };
464
+ }
465
+
466
+ /**
467
+ * Several attempts at one hard task, when asked for: the same brief made into sibling worker jobs, routed once, each in a
468
+ * worktree of its own. Each is run and verified like any job; once all have closed, one verified attempt is brought back
469
+ * (`settle`). It costs as many runs as there are attempts, so it is never the default.
470
+ */
471
+ async function newAttempts(db, { attempts, title, ...options }) {
472
+ if (![2, 3].includes(attempts)) throw new UsageError('--attempts is 2 or 3');
473
+ if (options.agent !== 'worker') throw new UsageError('--attempts goes with a worker');
474
+ if (!title?.trim()) throw new UsageError('a job needs a --title');
475
+ const project = getProject(db, options.project);
476
+ if (!hasCommit(project.path)) throw new UsageError(`${project.path} is not a git repository with a commit — each attempt needs a worktree of its own`);
477
+ const made = [];
478
+ try {
479
+ for (let n = 1; n <= attempts; n++) {
480
+ const first = made[0]?.job;
481
+ const route = first && { model: first.model, effort: first.effort, reason: first.route_reason, risky: first.risky === 1 };
482
+ made.push(await newJob(db, { ...options, title: `${title.trim()} (attempt ${n} of ${attempts})`, ownTree: true, route }));
483
+ }
484
+ } catch (cause) {
485
+ // All of them, or none.
486
+ for (const { job } of made) {
487
+ abandon(db, job.id);
488
+ await settle(db, job.id);
489
+ }
490
+ throw cause;
491
+ }
492
+ const ids = made.map(({ job }) => job.id);
493
+ for (const id of ids) setMeta(db, attemptsKey(id), JSON.stringify(ids));
494
+ return { job: made[0].job, jobs: made.map(({ job }) => job), warnings: made[0].warnings };
495
+ }
496
+
497
+ /**
498
+ * Retries a job: same project, same title (marked as a retry), same task, with
499
+ * what the previous attempt found carried into the new brief — and, when a review
500
+ * judged it, that review's findings as the reviewer wrote them. The router is
501
+ * asked again for its route, like any new job, and the route goes at least one
502
+ * step above the attempt being retried. Only a failed job, or a done
503
+ * one a review found enough wrong with, is eligible. A done one that worked in a worktree of its own had its change
504
+ * brought back when it closed: its retry starts from the project as it is now, with that change already in it.
505
+ */
506
+ export async function retry(db, id, { now = new Date().toISOString() } = {}) {
507
+ const old = getJob(db, id);
508
+ const eligible = old.status === 'failed' || (old.status === 'done' && (old.important ?? 0) >= RETRY_IMPORTANT_THRESHOLD);
509
+ if (!eligible) {
510
+ throw new UsageError(
511
+ `j${id} is ${old.status}${old.status === 'done' ? ` (important: ${old.important ?? 0})` : ''} — only a failed job, or a done one reviewed with important >= ${RETRY_IMPORTANT_THRESHOLD}, can be retried`,
512
+ );
513
+ }
514
+ const task = taskFromBrief(readOr(fileOf(id, 'brief.md')));
515
+ if (!task) throw new UsageError(`j${id}'s brief has no "## The task" section to retry from`);
516
+
517
+ // What the original was allowed and pointed at travels with the task: a retry of a review judges the same job,
518
+ // and a retry of a worker keeps the permission the first attempt was given.
519
+ const reviews = reviewTargetOf(id) ?? undefined;
520
+ const state = readState(db, id);
521
+ const testsMayChange = Boolean(state?.testsMayChange);
522
+ // A worker's retry is judged from where the first attempt began, so what that attempt left in the tree is still answered for.
523
+ // Its baseline comes too: taken again now, it would call the first attempt's breakage "already there".
524
+ // A first attempt made in a worktree of its own left nothing in the project to answer for.
525
+ const start = !state?.tree && state?.snap && stillThere(getProject(db, old.project).path, state.snap) ? { snap: state.snap, declared: state.declared, baseline: state.baseline } : undefined;
526
+ const { job, warnings } = await newJob(db, { project: old.project, title: `${old.title} (retry of j${id})`, agent: old.agent, task, reviews, testsMayChange, retryOf: id, start, now });
527
+
528
+ const oldNotes = readOr(fileOf(id, 'notes.md')).trim();
529
+ const oldReport = readOr(fileOf(id, 'report.md')).trim();
530
+ // What a reviewer found is what the retry is for: given in the reviewer's own words, the head of it when it is long.
531
+ const review = reviewOf(db, old);
532
+ const findings = review === null ? '' : findingsSection(reportOf(review)).trim();
533
+ const judged = findings && `### What its review, j${review}, found\n${findings.length > REVIEW_FINDINGS_CHARS ? `${head(findings, REVIEW_FINDINGS_CHARS)}\n[… the rest of the review: sumo job show ${review}]` : findings}`;
534
+ const found = [oldNotes && `### Notes\n${oldNotes}`, oldReport && `### Report\n${oldReport}`, judged].filter(Boolean).join('\n\n');
535
+ if (found) appendFileSync(fileOf(job.id, 'brief.md'), `\n## What the previous attempt found\n${found}\n`, { mode: 0o600 });
536
+
537
+ return { job, warnings };
538
+ }
539
+
540
+ /** How much of a review's findings a retry's brief carries: enough for every finding of a usual review, not a flood. */
541
+ const REVIEW_FINDINGS_CHARS = 1500;
542
+
543
+ /** The newest reviewer job that judged this one with `--reviews` and closed DONE: its id, or null when none did. */
544
+ function reviewOf(db, job) {
545
+ const reviewers = db.prepare(`SELECT id FROM jobs WHERE agent = 'reviewer' AND status = 'done' AND project = ? AND id > ? ORDER BY id DESC`).all(job.project, job.id);
546
+ return reviewers.find((r) => reviewTargetOf(r.id) === job.id)?.id ?? null;
547
+ }
548
+
549
+ /** The task text a brief was built from — everything between "## The task" and the next section renderBrief adds. */
550
+ function taskFromBrief(brief) {
551
+ const marker = '## The task\n';
552
+ const start = brief.indexOf(marker);
553
+ if (start === -1) return null;
554
+ const from = start + marker.length;
555
+ const stops = ['\n## The change to judge\n', '\n## How this kind of work is done here\n', '\n## How to work\n']
556
+ .map((section) => brief.indexOf(section, from))
557
+ .filter((i) => i !== -1);
558
+ return brief.slice(from, stops.length > 0 ? Math.min(...stops) : brief.length).trim();
559
+ }
560
+
561
+ const setting = (db, key) => getMeta(db, `config.${key}`) ?? CONFIG_DEFAULTS[key];
562
+ const routeOf = (job) => `${job.model}/${job.effort}`;
563
+
564
+ const closingKey = (id) => `job.${id}.told-to-close`;
565
+ /** The limits sumo itself tells a run to close near (src/loop.mjs), as a report names them. */
566
+ const CLOSED_NEAR = { budget: 'budget', time: 'time limit', turns: 'turn limit' };
567
+ /** What sumo told a job's last run to close near — `budget`, `time` or `turns` — kept for what follows it; null when it told it nothing. */
568
+ export function toldToClose(db, id, near) {
569
+ if (near) setMeta(db, closingKey(id), near);
570
+ else unmark(db, closingKey(id));
571
+ }
572
+
573
+ /** The brief of a review nobody asked for: the change to judge comes with it, as with any `--reviews`. */
574
+ const reviewTask = (job, risky) => `## Goal
575
+ Judge the change j${job.id} made for "${job.title}" against what it was asked: does it do all of it, correctly, and can it be trusted as it stands? ${
576
+ risky ? 'The router called this work risky — it touches security, credentials, money, migrations or concurrency.' : 'Every worker that finishes is reviewed here (jobs.review is all).'
577
+ } It passed the project's checks; this review is for what the checks cannot see.
578
+ ## Non-goals
579
+ Rewriting the change, or judging code it did not touch.
580
+ ## Check
581
+ none: a review changes nothing — read the change, what was asked, and the code around it.
582
+ `;
583
+
584
+ /**
585
+ * What follows a worker's run without being asked, once the worker has closed. A first attempt that FAILED is retried
586
+ * once, on a route one step up (`retry`; `jobs.escalate`) — a retry is never retried again this way, nor one sumo told to
587
+ * close near its budget, time or turns, and one of several `attempts` is settled with its siblings instead. One that closed
588
+ * DONE, verified by the checks — in git, so there is a change to hand over — is reviewed when the
589
+ * router called its work risky, or always (`jobs.review`), by a reviewer at least as strong as it (`--reviews`). The job
590
+ * made, with a line that says why and on what route; only the line when it could not be made; null when nothing follows.
591
+ */
592
+ async function followUp(db, id, { now = new Date().toISOString() } = {}) {
593
+ const job = getJob(db, id);
594
+ if (job.agent !== 'worker' || attemptsOf(db, id) !== null) return null;
595
+ if (job.status === 'failed') {
596
+ if (job.retry_of !== null || setting(db, 'jobs.escalate') !== 'on') return null;
597
+ // Told by sumo to close near one of its limits, it closed where it stood: a run one step up with that limit fresh would only buy
598
+ // the limit off at a dearer price, and that is the user's call.
599
+ const near = CLOSED_NEAR[getMeta(db, closingKey(id))];
600
+ if (near) {
601
+ const why = `j${id} failed on ${routeOf(job)} after it was told to close near its ${near}: it is not retried one step up, which would start again on a dearer route with a fresh ${near}. To retry it anyway: sumo job retry ${id}`;
602
+ return { line: said(id, 'Not retried', [why])[0] };
603
+ }
604
+ try {
605
+ const made = await retry(db, id, { now });
606
+ return { ...made, kind: 'retry', line: `j${id} failed on ${routeOf(job)} and was retried on ${routeOf(made.job)}, as j${made.job.id} — j${id}'s own report: sumo job show ${id}` };
607
+ } catch (cause) {
608
+ return { line: `j${id} failed on ${routeOf(job)}; a retry one step up could not be made: ${cause.message}` };
609
+ }
610
+ }
611
+ const review = setting(db, 'jobs.review');
612
+ const risky = job.risky === 1;
613
+ if (job.status !== 'done' || !(review === 'all' || (review === 'risky' && risky))) return null;
614
+ // Work taken with --accept was never verified: a review is added to the checks, it does not stand in for them.
615
+ const state = readState(db, id);
616
+ if (state?.verdict?.ok !== true || /^## Accepted without verification$/m.test(reportOf(id))) return null;
617
+ // Outside git nothing recorded where the work began, so there is no change to hand a reviewer: none is asked for.
618
+ if (!state.snap) return null;
619
+ const why = risky ? `The router called j${id}'s work risky` : 'jobs.review is all';
620
+ try {
621
+ const made = await newJob(db, { project: job.project, title: `${job.title} (review of j${id})`, agent: 'reviewer', task: reviewTask(job, risky), reviews: id, now });
622
+ return { ...made, kind: 'review', line: `${why}, so j${made.job.id} reviewed j${id} on ${routeOf(made.job)}:` };
623
+ } catch (cause) {
624
+ return { line: `${why}, but a review could not be made: ${cause.message}` };
625
+ }
626
+ }
627
+
628
+ /**
629
+ * Runs a job with `run`, then what follows it unasked (`followUp`), each with `run` too, until nothing does — at most a
630
+ * retry of a first attempt that failed, and a review of the work once it is done. The chat and `sumo job run` both come
631
+ * through here, each with its own way of running one job: `run(id)` for the first, `run(id, warnings)` for each made
632
+ * here. `onFollow` hears each job made, before it runs; nothing more is made once `signal` is aborted. Each step comes
633
+ * back in order as `{ id, kind, line, result }` — `error` in place of `result` when a follow-up's run threw, and only a
634
+ * `line` when one could not be made. A throw from the first run is the caller's.
635
+ */
636
+ export async function runFollowed(db, id, run, { signal = null, onFollow = null, now = () => new Date().toISOString() } = {}) {
637
+ const ran = [{ id, kind: null, line: null, result: await run(id) }];
638
+ for (let at = id; !signal?.aborted; ) {
639
+ const next = await followUp(db, at, { now: now() });
640
+ if (!next) break;
641
+ if (!next.job) {
642
+ ran.push({ id: null, kind: null, line: next.line, result: null });
643
+ break;
644
+ }
645
+ onFollow?.(next.job.id);
646
+ const step = { id: next.job.id, kind: next.kind, line: next.line, result: null };
647
+ ran.push(step);
648
+ try {
649
+ step.result = await run(next.job.id, next.warnings);
650
+ } catch (cause) {
651
+ step.error = cause.message;
652
+ break;
653
+ }
654
+ at = next.job.id;
655
+ }
656
+ return ran;
657
+ }
658
+
659
+ /** `jobs, done, failed, reviewed, avg important` — one line per model/effort this project has finished. */
660
+ export function stats(db, { project } = {}) {
661
+ return statsLines(db, { project: project === undefined ? undefined : getProject(db, project).slug });
662
+ }
663
+
664
+ /** Everything a sub-agent needs to start — or to start again cold, in another session, after being interrupted. */
665
+ export function brief(db, id) {
666
+ const job = getJob(db, id);
667
+ const parts = [readOr(fileOf(id, 'brief.md')).trimEnd()];
668
+ const qa = readOr(fileOf(id, 'qa.md')).trim();
669
+ const notes = readOr(fileOf(id, 'notes.md')).trim();
670
+ const red = (readState(db, id)?.baseline ?? []).filter((c) => !c.ok);
671
+ if (red.length > 0) {
672
+ parts.push(`## Already failing before this job began — not yours to fix, and not to be made worse\n${red.map((c) => `- \`${c.command}\` — ${c.flaky ? 'flaky: run twice, it did not fail the same way — ' : ''}${c.file}`).join('\n')}`);
673
+ }
674
+ if (qa) parts.push(`## Questions and answers so far\n${qa}`);
675
+ if (notes) parts.push(`## Progress so far (from an earlier run of this job — continue from here, do not start over)\n${notes}`);
676
+ if (job.status === 'done' || job.status === 'failed') parts.push(`## This job is already ${job.status}. Do nothing.`);
677
+ return parts.join('\n\n');
678
+ }
679
+
680
+ /** Where a worker job works: the worktree it was given, or the project itself. */
681
+ const workdir = (state, project) => state?.tree?.path ?? project.path;
682
+ /** The worktree a worker job was given — `{ top, path, prefix, base }` — or null when it works in the project. */
683
+ export const treeOf = (db, id) => readState(db, id)?.tree ?? null;
684
+
685
+ /** A worker job's recorded state and where it works — or a plain reason why there is nothing to check. */
686
+ function checkable(db, id, verb) {
687
+ const job = getJob(db, id);
688
+ requireOpen(job, verb);
689
+ const state = readState(db, id);
690
+ if (job.agent !== 'worker' || !state) throw new UsageError(`j${id} is not a worker job with a recorded start — there is nothing to ${verb === 'verified' ? 'verify' : 'take a baseline of'}`);
691
+ const root = workdir(state, getProject(db, job.project));
692
+ if (!existsSync(root)) throw new UsageError(`${root} no longer exists`);
693
+ return { job, state, root };
694
+ }
695
+
696
+ /** The project's checks as they stand before the work. Taken once; a second call reports what the first found. */
697
+ export function baseline(db, id) {
698
+ const { state, root } = checkable(db, id, 'given a baseline');
699
+ if (!state.baseline) {
700
+ const taken = takeBaseline(root, state.snap, dirOf(id));
701
+ if (taken.refused) return [`no baseline taken: ${taken.refused}.`, 'Every check that fails at the end will count as this job\'s.'];
702
+ // A verdict given before there was a baseline judged against none: it no longer says what DONE would.
703
+ writeState(db, id, { ...state, baseline: taken.checks, verdict: null });
704
+ state.baseline = taken.checks;
705
+ }
706
+ if (state.baseline.length === 0) return ['this project declares no check, test, lint or typecheck command — there is nothing to take a baseline of'];
707
+ const failing = (c) =>
708
+ c.flaky
709
+ ? `is FLAKY — it failed, and run again it did not fail the same way; recorded so a failure of it is not blamed on you (${c.file}, ${c.again})`
710
+ : `ALREADY FAILS — not yours to fix, and recorded so it is not blamed on you (${c.file})`;
711
+ return state.baseline.map((c) => `\`${c.command}\` ${c.ok ? 'passes' : failing(c)}`);
712
+ }
713
+
714
+ /** Runs the checks now and records the verdict against the exact tree it judged. */
715
+ export function verifyJob(db, id, now = new Date().toISOString()) {
716
+ const { state, root } = checkable(db, id, 'verified');
717
+ const verdict = verify(root, state, dirOf(id), now);
718
+ writeState(db, id, { ...state, verdict });
719
+ return verdict;
720
+ }
721
+
722
+ /** Everything a job changed, as one file a reviewer can read. */
723
+ export function changes(db, id) {
724
+ const job = getJob(db, id);
725
+ const state = readState(db, id);
726
+ if (!state?.snap) throw new UsageError(`j${id} recorded no starting point (not a worker job, or not a git repository)`);
727
+ const root = workdir(state, getProject(db, job.project));
728
+ // A worktree that is gone wrote down its change as it went: that is kept, not overwritten from a project that has moved on.
729
+ if (state.tree && !existsSync(root) && existsSync(fileOf(id, 'changes.diff'))) {
730
+ return { file: fileOf(id, 'changes.diff'), files: (readOr(fileOf(id, 'changes.diff')).match(/^diff --git /gm) ?? []).length };
731
+ }
732
+ return writeChanges(root, state.snap, fileOf(id, 'changes.diff'));
733
+ }
734
+
735
+ /**
736
+ * The verdict a DONE rests on: the recorded one when the tree has not moved
737
+ * since it was given, otherwise a fresh one. Outside git there is no telling
738
+ * whether the tree moved, so it is always run again.
739
+ */
740
+ function verdictForDone(db, id, state, now) {
741
+ const root = workdir(state, getProject(db, getJob(db, id).project));
742
+ if (!existsSync(root)) return null;
743
+ const last = state.verdict;
744
+ if (last?.fingerprint && state.snap && unmoved(root, state.snap, last.fingerprint)) return last;
745
+ return verifyJob(db, id, now);
746
+ }
747
+
748
+ /** Whether the tree is exactly the one a verdict judged; a tree that cannot be compared has moved, as far as anyone can tell. */
749
+ function unmoved(root, snap, fingerprint) {
750
+ try {
751
+ return changesSince(root, snap).fingerprint === fingerprint;
752
+ } catch {
753
+ return false;
754
+ }
755
+ }
756
+
757
+ function append(id, name, heading, text, now) {
758
+ appendFileSync(fileOf(id, name), `### ${heading} — ${now.slice(0, 16).replace('T', ' ')}\n${text.trim()}\n\n`, { mode: 0o600 });
759
+ }
760
+
761
+ /** A line of a checklist, ticked or not: `- [ ] a step`, `- [x] a step`. */
762
+ const STEP = /^\s*[-*]\s+\[[ xX]\]\s+\S/;
763
+ /** The most of a plan put back in front of a job: it is a reminder, not the notes again. */
764
+ const PLAN_STEPS = 20;
765
+
766
+ /**
767
+ * A job's plan: the checklist in the latest of its notes that holds one. A worker notes its steps as `- [ ] …` and notes the
768
+ * list again, ticked `- [x] …`, as it goes, so the last list is where it stands. Null while no note holds one.
769
+ */
770
+ export function planOf(id) {
771
+ for (const entry of readOr(fileOf(id, 'notes.md')).split(/^### /m).reverse()) {
772
+ const steps = entry.split('\n').filter((l) => STEP.test(l)).map((l) => l.trim());
773
+ if (steps.length > 0) return [...steps.slice(0, PLAN_STEPS), ...(steps.length > PLAN_STEPS ? [`… ${steps.length - PLAN_STEPS} more steps`] : [])].join('\n');
774
+ }
775
+ return null;
776
+ }
777
+
778
+ export function note(db, id, text, now = new Date().toISOString()) {
779
+ const job = getJob(db, id);
780
+ requireOpen(job, 'noted on');
781
+ if (!text.trim()) throw new UsageError('the note is empty — put it on stdin');
782
+ append(id, 'notes.md', 'note', text, now);
783
+ setOpenStatus(db, id, null, now);
784
+ }
785
+
786
+ export function ask(db, id, question, now = new Date().toISOString()) {
787
+ requireOpen(getJob(db, id), 'asked about');
788
+ if (!question.trim()) throw new UsageError('the question is empty — put it on stdin');
789
+ append(id, 'qa.md', 'Question', question, now);
790
+ setOpenStatus(db, id, 'needs_input', now);
791
+ }
792
+
793
+ const inboxOf = (id) => fileOf(id, 'inbox');
794
+ let told = 0;
795
+
796
+ /**
797
+ * Something the user says to a running job from outside its process — the chat's `@j31 …` for a job it is
798
+ * not running, or `sumo job tell` from any shell. One file each, written whole and then given its name, and
799
+ * named so they sort in the order they were said: the job taking its inbox never reads half a message, and
800
+ * one that arrives while it is taking the others is simply there the next time.
801
+ */
802
+ export function tell(db, id, text, now = new Date().toISOString()) {
803
+ requireOpen(getJob(db, id), 'told anything');
804
+ if (!text.trim()) throw new UsageError('the message is empty — put it on stdin');
805
+ mkdirSync(inboxOf(id), { recursive: true, mode: 0o700 });
806
+ const name = `${String(Date.now()).padStart(15, '0')}-${String(told++).padStart(6, '0')}-${process.pid}`;
807
+ const unnamed = join(inboxOf(id), `.${name}`);
808
+ writeFileSync(unnamed, JSON.stringify({ text: text.trim(), at: now }), { mode: 0o600 });
809
+ renameSync(unnamed, join(inboxOf(id), `${name}.json`));
810
+ }
811
+
812
+ /** What a job run in the chat is doing, line by line, for whoever watches it; and how the run ended, once it has. */
813
+ export const liveFile = (id) => fileOf(id, 'live.log');
814
+ export const endFile = (id) => fileOf(id, 'live.end');
815
+ /** A run begins with an empty record: a watcher never mistakes how an earlier run ended for this one's end. */
816
+ export function startLive(id) {
817
+ rmSync(endFile(id), { force: true });
818
+ writeFileSync(liveFile(id), '', { mode: 0o600 });
819
+ }
820
+ export const appendLive = (id, text) => appendFileSync(liveFile(id), text, { mode: 0o600 });
821
+ export const endLive = (id, lines) => writeFileSync(endFile(id), `${lines.join('\n')}\n`, { mode: 0o600 });
822
+
823
+ /** What was told to the job since it last looked, taken off the disk so it is read once. A file that is not a message is passed over. */
824
+ export function takeInbox(id) {
825
+ let names;
826
+ try {
827
+ names = readdirSync(inboxOf(id)).filter((name) => name.endsWith('.json')).sort();
828
+ } catch {
829
+ return [];
830
+ }
831
+ return names.flatMap((name) => {
832
+ const file = join(inboxOf(id), name);
833
+ const raw = readOr(file);
834
+ rmSync(file, { force: true });
835
+ try {
836
+ const { text } = JSON.parse(raw);
837
+ return typeof text === 'string' ? [text] : [];
838
+ } catch {
839
+ return [];
840
+ }
841
+ });
842
+ }
843
+
844
+ export function answer(db, id, text, now = new Date().toISOString()) {
845
+ const job = getJob(db, id);
846
+ if (job.status !== 'needs_input') throw new UsageError(`j${id} is ${job.status} — it is not waiting for an answer`);
847
+ if (!text.trim()) throw new UsageError('the answer is empty — put it on stdin');
848
+ append(id, 'qa.md', 'Answer', text, now);
849
+ setOpenStatus(db, id, 'running', now);
850
+ }
851
+
852
+ /**
853
+ * The traps under "## Learned" in a report, minus the ways of saying "nothing". A trap is a bullet with the lines it wraps
854
+ * onto, or — where nothing is listed — the first paragraph; what stands after them is the report going on, not a trap.
855
+ */
856
+ function learnedLines(report) {
857
+ const section = /^##\s*Learned\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/im.exec(report)?.[1] ?? '';
858
+ const BULLET = /^\s*(?:[-*]|\d+[.)])\s+/;
859
+ const listed = section.split('\n').some((l) => BULLET.test(l));
860
+ const traps = [];
861
+ let open = false;
862
+ for (const raw of section.split('\n')) {
863
+ const text = raw.replace(BULLET, '').trim();
864
+ if (!text) {
865
+ // A blank line ends a trap; with nothing listed, it ends the one paragraph there is.
866
+ if (!listed && traps.length > 0) break;
867
+ open = false;
868
+ } else if (BULLET.test(raw) || (!listed && !open)) {
869
+ traps.push(text);
870
+ open = true;
871
+ } else if (open) traps[traps.length - 1] += ` ${text}`;
872
+ }
873
+ return traps.filter((l) => l.length > 12 && !/^(none|nothing|n\/a)\b/i.test(l)).slice(0, MAX_LEARNED);
874
+ }
875
+
876
+ /**
877
+ * The findings under "## Findings" in a review — the count that becomes the
878
+ * reviewed job's `important`. One per line that opens the way the template
879
+ * asks (`1. `) or the way reviewers here also write them (`<file:line> — `);
880
+ * a wrapped line is indented, so it is never counted twice.
881
+ */
882
+ function findingsCount(report) {
883
+ return (findingsSection(report).match(/^(?:\d+\.\s|\S+\.\w+:\d+)/gm) ?? []).length;
884
+ }
885
+
886
+ /** What a review lists under "## Findings", as it was written; empty when it has no such section. */
887
+ function findingsSection(report) {
888
+ return /^##\s*Findings\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/im.exec(report)?.[1] ?? '';
889
+ }
890
+
891
+ const checkedFile = (id) => fileOf(id, 'checked');
892
+ /** How many changed files, and how many new ones, the check names before it counts the rest. */
893
+ const CHECK_LISTED = 30;
894
+
895
+ /**
896
+ * What a worker's first DONE is answered with instead of being taken: the task as it was given, what has changed since
897
+ * the job began, and what to look for — the first thing a reviewer does, done by the author while it can still fix
898
+ * what it finds. Nothing is run here; the checks come with the next DONE.
899
+ */
900
+ function checkAgainstTask(db, job, state) {
901
+ // Where the job works: its worktree when it was given one, the project otherwise.
902
+ const root = workdir(state, getProject(db, job.project));
903
+ let change = ['not a git repository — what changed cannot be shown; look over it yourself'];
904
+ if (state.snap) {
905
+ try {
906
+ const { created } = changesSince(root, state.snap);
907
+ change = [
908
+ diffStat(root, state.snap, CHECK_LISTED) || '(no tracked file changed)',
909
+ ...created.slice(0, CHECK_LISTED).map((f) => ` new file: ${f}`),
910
+ ...(created.length > CHECK_LISTED ? [` … ${created.length - CHECK_LISTED} more new files`] : []),
911
+ ];
912
+ } catch {
913
+ change = ['what changed could not be read from git — look over it yourself'];
914
+ }
915
+ }
916
+ return [
917
+ `j${job.id} is not closed yet — before DONE counts, check the work against the task. Nothing was run.`,
918
+ '',
919
+ '## The task',
920
+ taskFromBrief(readOr(fileOf(job.id, 'brief.md'))) || '(the brief has no "## The task" section)',
921
+ '',
922
+ '## What changed since the job began',
923
+ ...change,
924
+ '',
925
+ '## Check each, and fix what is not so',
926
+ '- Every requirement in the task is met.',
927
+ '- Debug output and scratch files are removed.',
928
+ '- Tests were changed only if the task allows it.',
929
+ '- Every claim in the report is backed by a tool result from this run.',
930
+ '',
931
+ 'Then call `finish` again with the same report, or a corrected one, to go on to verification. This is asked once.',
932
+ ].join('\n');
933
+ }
934
+
935
+ /**
936
+ * Closes a job. What the sub-agent learned is filed by code, not by trust: only
937
+ * as gotchas, only in this project, marked as observed, through the same
938
+ * validator as every other model-written memory.
939
+ */
940
+ export function finish(db, id, { status, report, accept }, now = new Date().toISOString()) {
941
+ const job = getJob(db, id);
942
+ requireOpen(job, 'finished');
943
+ if (status !== 'DONE' && status !== 'FAILED') throw new UsageError('--status is DONE or FAILED (blocked on the user? use: sumo job ask)');
944
+ if (!report.trim()) throw new UsageError('the report is empty — put it on stdin');
945
+ if (accept !== undefined && !accept.trim()) throw new UsageError('--accept needs the reason the work is being taken without verification');
946
+
947
+ // The author of the work does not grade it. A worker's DONE rests on what the checks said, not on what the report says.
948
+ // A DONE that cannot be checked is refused, not waved through; --accept is the way to take it anyway, and it is written down.
949
+ const graded = job.agent === 'worker' && status === 'DONE';
950
+ const state = graded ? readState(db, id) : null;
951
+ const unchecked = (why) => new UsageError(`j${id} cannot be verified — ${why}. To take the work as it stands: sumo job finish ${id} --status DONE --accept "<why>"`);
952
+ if (graded && accept === undefined && !state) throw unchecked(`the record of where it began (${fileOf(id, 'verify.json')}) cannot be read, or was changed since sumo wrote it`);
953
+ // Before the checks are run, the author looks once at the task beside its change: the first DONE is answered with that, not taken.
954
+ // Kept in the job's folder, so a run started again goes on to the checks instead of being asked again.
955
+ if (graded && accept === undefined && !existsSync(checkedFile(id))) {
956
+ const asked = checkAgainstTask(db, job, state);
957
+ writeFileSync(checkedFile(id), `${now}\n`, { mode: 0o600 });
958
+ throw new UsageError(asked);
959
+ }
960
+ const verdict = state && accept === undefined ? verdictForDone(db, id, state, now) : null;
961
+ // The checks can take minutes: report a job closed in the meantime before interpreting their verdict.
962
+ requireOpen(getJob(db, id), 'finished');
963
+ if (graded && accept === undefined && !verdict) throw unchecked(`${getProject(db, job.project).path} no longer exists, so its checks cannot be run`);
964
+ if (verdict && !verdict.ok) {
965
+ throw new UsageError(
966
+ [
967
+ `j${id} is not done — the project's checks were run, and:`,
968
+ ...verdictLines(verdict).map((l) => ` ${l}`),
969
+ `Fix it and finish again. If it cannot be fixed: sumo job finish ${id} --status FAILED, or ask: sumo job ask ${id}`,
970
+ ].join('\n'),
971
+ );
972
+ }
973
+ const observed = verdict
974
+ ? `\n## Verified by code — not by the author of this report\n${verdictLines(verdict).map((l) => `- ${l}`).join('\n')}\n`
975
+ : graded && accept !== undefined
976
+ ? `\n## Accepted without verification\n${accept.trim()}\n`
977
+ : '';
978
+
979
+ // The checks can take minutes: a job abandoned or closed while they ran is left as it now is.
980
+ // Closed before the report is written, so one closed elsewhere meanwhile keeps the report it had; a report that cannot be written undoes the close.
981
+ tx(db, () => {
982
+ const closed = db.prepare(`UPDATE jobs SET status = ?, updated_at = ? WHERE id = ? AND status IN ('running', 'needs_input')`).run(status === 'DONE' ? 'done' : 'failed', now, id);
983
+ if (closed.changes === 0) requireOpen(getJob(db, id), 'finished');
984
+ writeFileSync(fileOf(id, 'report.md'), `${report.trim()}\n${observed}`, { mode: 0o600 });
985
+ });
986
+
987
+ // A reviewer job created with --reviews <id> grades that job: the count of numbered Findings becomes its "important".
988
+ if (job.agent === 'reviewer' && status === 'DONE') {
989
+ const targetId = reviewTargetOf(id);
990
+ if (targetId !== null) db.prepare('UPDATE jobs SET important = ? WHERE id = ?').run(findingsCount(report), targetId);
991
+ }
992
+
993
+ // Scratch keeps no memory: what a chore there taught is in its report, and where it stopped is nowhere to come back to.
994
+ const kept = !isScratch(getProject(db, job.project));
995
+ const ops = kept ? learnedLines(report).map((body) => ({ op: 'gotcha', scope: `project:${job.project}`, body: clip(body, 300) })) : [];
996
+ const learned = applyOps(db, ops, { source: 'worker', turns: new Map(), now });
997
+
998
+ const summary = /^##\s*Summary\s*\n+([^\n]+)/im.exec(report)?.[1]?.trim();
999
+ if (kept) {
1000
+ addCheckpoint(db, {
1001
+ sessionId: job.session_id,
1002
+ project: job.project,
1003
+ done: clip(`${status === 'DONE' ? 'finished' : 'FAILED'} job j${id} "${job.title}"${summary ? `: ${summary}` : ''}`, 300),
1004
+ next: status === 'FAILED' ? `read the report: sumo job show ${id}` : null,
1005
+ now,
1006
+ });
1007
+ }
1008
+ return { job: getJob(db, id), learned, verdict, unverified: graded && accept !== undefined };
1009
+ }
1010
+
1011
+ export function abandon(db, id, now = new Date().toISOString()) {
1012
+ requireOpen(getJob(db, id), 'abandoned');
1013
+ setStatus(db, id, 'abandoned', now);
1014
+ }
1015
+
1016
+ const LISTED = 30;
1017
+
1018
+ /** The newest jobs, open ones only unless `all`; `more` is how many older ones the list leaves out. */
1019
+ export function listJobs(db, { all = false } = {}) {
1020
+ const where = all ? '' : `WHERE status IN ('running', 'needs_input')`;
1021
+ const rows = db.prepare(`SELECT * FROM jobs ${where} ORDER BY id DESC LIMIT ${LISTED}`).all();
1022
+ const total = db.prepare(`SELECT COUNT(*) AS n FROM jobs ${where}`).get().n;
1023
+ return Object.assign(rows, { more: total - rows.length });
1024
+ }
1025
+
1026
+ export function jobLine(job) {
1027
+ return `j${job.id} [${job.agent}·${job.project}·${job.status}] ${job.title}`;
1028
+ }
1029
+
1030
+ /** The report a job closed with, as its sub-agent wrote it; empty while it has none. */
1031
+ export const reportOf = (id) => readOr(fileOf(id, 'report.md')).trim();
1032
+
1033
+ /** What the main agent needs to decide its next move — not the whole report. */
1034
+ export function show(db, id) {
1035
+ const job = getJob(db, id);
1036
+ const out = [jobLine(job), `files: ${dirOf(id)}`];
1037
+ if (job.model && job.effort) out.push(`route: ${job.model}/${job.effort} — ${job.route_reason}`);
1038
+ if (job.important !== null && job.important !== undefined) out.push(`important: ${job.important}`);
1039
+ const qa = readOr(fileOf(id, 'qa.md')).trim();
1040
+ if (job.status === 'needs_input' && qa) out.push('', 'waiting on this question:', qa.split(/^### /m).filter(Boolean).at(-1).replace(/^[^\n]*\n/, '').trim());
1041
+ const notes = readOr(fileOf(id, 'notes.md')).trim();
1042
+ if (notes) out.push('', 'latest note:', notes.split(/^### /m).filter(Boolean).at(-1).replace(/^[^\n]*\n/, '').trim());
1043
+ const report = readOr(fileOf(id, 'report.md')).trim();
1044
+ if (report) out.push('', report);
1045
+ return out.join('\n');
1046
+ }
1047
+
1048
+ const settledKey = (id) => `job.${id}.settled`;
1049
+ const attemptsKey = (id) => `job.${id}.attempts`;
1050
+ const pickedKey = (first) => `job.${first}.picked`;
1051
+ /** True for the one caller that gets there first, whoever else tries at the same moment. */
1052
+ const firstTo = (db, key, now) => tx(db, () => getMeta(db, key) === null && (setMeta(db, key, now), true));
1053
+
1054
+ /** The jobs one `--attempts` made, in order; null for a job that is not one of them. */
1055
+ export function attemptsOf(db, id) {
1056
+ const ids = getMeta(db, attemptsKey(id));
1057
+ return ids === null ? null : JSON.parse(ids);
1058
+ }
1059
+
1060
+ /** What the last of a set of attempts to close settled for them all, in lines; null until then. */
1061
+ export function attemptsSettled(db, first) {
1062
+ try {
1063
+ return JSON.parse(getMeta(db, pickedKey(first))).lines ?? null;
1064
+ } catch {
1065
+ return null;
1066
+ }
1067
+ }
1068
+
1069
+ /** Added to a job's report under a heading of its own, and handed back to be said. */
1070
+ function said(id, heading, lines) {
1071
+ appendFileSync(fileOf(id, 'report.md'), `\n## ${heading}\n${lines.join('\n')}\n`, { mode: 0o600 });
1072
+ return lines;
1073
+ }
1074
+
1075
+ /** The tree goes; what it changed stays beside the job as changes.diff, for a retry, a review or a person. */
1076
+ function release(id, project, state) {
1077
+ const kept = fileOf(id, 'changes.diff');
1078
+ try {
1079
+ writeChanges(state.tree.path, state.snap, kept);
1080
+ } catch {
1081
+ // A tree too broken to diff has nothing to keep.
1082
+ }
1083
+ dropTree(project.path, state.tree.top);
1084
+ return kept;
1085
+ }
1086
+
1087
+ /** The newest other worker at work in the project itself — not in a worktree of its own — right now, or undefined. */
1088
+ const inPlace = (db, project, id) => openWorkers(db, project.slug, id).find((o) => !readState(db, o.id)?.tree && atWork(o.id));
1089
+
1090
+ /**
1091
+ * The tree's change, brought back to the project: the tree goes once it is there, and stays, said, where it would not go.
1092
+ * Never under a worker at work in the project: its start, its baseline and its review would all count the change as its
1093
+ * own. Then the tree goes, and the change is kept whole as a patch, with the command that applies it once that one is done.
1094
+ */
1095
+ function applyTree(db, id, project, state) {
1096
+ const busy = inPlace(db, project, id);
1097
+ if (busy) {
1098
+ const patch = treeDiff(state.tree, { binary: true });
1099
+ if (patch.length > 0) writeFileSync(fileOf(id, 'change.patch'), patch, { mode: 0o600 });
1100
+ const kept = release(id, project, state);
1101
+ if (patch.length === 0) return 'It changed nothing; its worktree is removed.';
1102
+ return `The change was NOT applied: j${busy.id} "${busy.title}" is still working in ${project.path}, and the change would land under it — its start, its checks and its review would count it as its own. Its worktree is removed; what it changed is kept in ${kept}, and whole as a patch: once j${busy.id} is done, git -C ${project.path} apply ${fileOf(id, 'change.patch')}`;
1103
+ }
1104
+ const back = bringBack(project.path, state.tree, dirOf(id));
1105
+ if (!back.applied && !back.empty) {
1106
+ return `The change was NOT applied: it does not apply to ${project.path} as that stands now. It is kept in ${state.tree.top} — bring it over by hand, then: git -C ${project.path} worktree remove --force ${state.tree.top}${back.why ? ` (git said: ${back.why})` : ''}`;
1107
+ }
1108
+ release(id, project, state);
1109
+ return back.empty ? 'It changed nothing; its worktree is removed.' : `The change was applied to ${project.path}${back.merged ? ' by a three-way merge, and staged' : ''}; its worktree is removed.`;
1110
+ }
1111
+
1112
+ /** Done, judged by the checks, and its tree still the one they judged: an attempt worth keeping. */
1113
+ function verifiedDone(db, id, state) {
1114
+ const tree = state?.tree?.path;
1115
+ return getJob(db, id).status === 'done' && state.verdict?.ok === true && existsSync(tree ?? '') && unmoved(tree, state.snap, state.verdict.fingerprint);
1116
+ }
1117
+
1118
+ /**
1119
+ * What becomes of a closed worker's own worktree. Done, its change is brought back to the project and the tree removed —
1120
+ * or, where it does not apply, kept and said; failed or abandoned, the tree goes and what it changed stays as changes.diff.
1121
+ * One of several attempts keeps its tree only when verified done, and the last of them to close settles them all. Once per
1122
+ * job, by whoever gets there first; what happened is added to the report and handed back. Never throws: the job is closed either
1123
+ * way. One that fails part-way is not marked settled, so it can be tried again; where the tree is, and that its change was not
1124
+ * brought back, is said.
1125
+ */
1126
+ export async function settle(db, id, now = new Date().toISOString()) {
1127
+ const job = getJob(db, id);
1128
+ const state = readState(db, id);
1129
+ if (!state?.tree || job.status === 'running' || job.status === 'needs_input' || !firstTo(db, settledKey(id), now)) return [];
1130
+ const project = getProject(db, job.project);
1131
+ const group = attemptsOf(db, id);
1132
+ let picking = false;
1133
+ try {
1134
+ if (!group) return said(id, 'Worktree', [job.status === 'done' ? applyTree(db, id, project, state) : `Its worktree is removed; what it changed is kept in ${release(id, project, state)}.`]);
1135
+ // Settled already, by another attempt that closed at the same moment.
1136
+ if (getMeta(db, pickedKey(group[0])) !== null) return [];
1137
+ const own = verifiedDone(db, id, state) ? [] : said(id, 'Worktree', [`Not verified done, so not a candidate: its worktree is removed; what it changed is kept in ${release(id, project, state)}.`]);
1138
+ const open = group.some((m) => ['running', 'needs_input'].includes(getJob(db, m).status));
1139
+ if (open || !firstTo(db, pickedKey(group[0]), now)) return own;
1140
+ picking = true;
1141
+ const lines = await settleAttempts(db, group, project, now);
1142
+ setMeta(db, pickedKey(group[0]), JSON.stringify({ lines }));
1143
+ return [...own, ...said(group[0], 'Attempts', lines)];
1144
+ } catch (cause) {
1145
+ unmark(db, settledKey(id));
1146
+ if (picking) unmark(db, pickedKey(group[0]));
1147
+ const where = existsSync(state.tree.top)
1148
+ ? `the tree is still at ${state.tree.top} — bring it over by hand, then: git -C ${project.path} worktree remove --force ${state.tree.top}`
1149
+ : `what it changed is kept in ${fileOf(id, 'changes.diff')}`;
1150
+ return said(id, 'Worktree', [`Its worktree could not be settled: ${cause.message.trim()}. Its change was NOT brought back; ${where}`]);
1151
+ }
1152
+ }
1153
+
1154
+ /** A set of attempts, all closed: of the verified ones, one is picked and brought back, and every other tree goes. */
1155
+ async function settleAttempts(db, group, project, now) {
1156
+ const states = new Map(group.map((m) => [m, readState(db, m)]));
1157
+ const candidates = group.filter((m) => states.get(m)?.tree && verifiedDone(db, m, states.get(m)));
1158
+ const pick = candidates.length === 0 ? null : candidates.length === 1 ? { id: candidates[0], reason: 'the only one verified done' } : await pickAttempt(db, group[0], candidates.map((m) => ({ id: m, tree: states.get(m).tree })), now);
1159
+ for (const m of group) if (m !== pick?.id && existsSync(states.get(m)?.tree?.top ?? '')) release(m, project, states.get(m));
1160
+ const lines = [`${group.map((m) => `j${m} ${getJob(db, m).status}`).join(', ')}; verified done: ${candidates.map((m) => `j${m}`).join(', ') || 'none'}.`];
1161
+ if (!pick) return [...lines, 'None was verified done, so nothing was brought back.'];
1162
+ return [...lines, `Picked j${pick.id}: ${pick.reason}`, applyTree(db, pick.id, project, states.get(pick.id))];
1163
+ }
1164
+
1165
+ const PICK_DIFF_CHARS = 20_000;
1166
+ const PICK_SCHEMA = { type: 'object', properties: { pick: { type: 'integer' }, reason: { type: 'string' } }, required: ['pick', 'reason'], additionalProperties: false };
1167
+ const PICK_SYSTEM =
1168
+ "Several attempts were made at one coding task, and each passed the project's checks. Pick the one to keep: the one that does all the task asks, " +
1169
+ 'correctly, with the least that was not asked for. Answer with its number and one sentence saying why.';
1170
+
1171
+ /** Which of several verified attempts to keep: one structured answer from sonnet, given the task and each change; the smallest change when none comes. */
1172
+ async function pickAttempt(db, first, candidates, now) {
1173
+ const diffs = candidates.map(({ tree }) => treeDiff(tree));
1174
+ const shown = (d) => (d.length > PICK_DIFF_CHARS ? `${head(d, PICK_DIFF_CHARS)}\n[… ${d.length - PICK_DIFF_CHARS} more characters not shown]` : d);
1175
+ const prompt = [`## The task\n${taskFromBrief(readOr(fileOf(first, 'brief.md'))) ?? ''}`, ...diffs.map((d, i) => `## Attempt ${i + 1}\n${shown(d)}`)].join('\n\n');
1176
+ const result = usableModels(db).includes('sonnet') ? await callModel(db, { system: PICK_SYSTEM, prompt, schema: PICK_SCHEMA, model: 'sonnet', kind: 'pick' }) : failure('sonnet is switched off');
1177
+ const n = result.data?.pick;
1178
+ const ok = result.ok && Number.isInteger(n) && n >= 1 && n <= candidates.length;
1179
+ const why = ok ? `picked attempt ${n}` : (result.error ?? `there is no attempt ${n}`);
1180
+ logRun(db, { kind: 'pick', model: 'sonnet', result: { ...result, ok }, note: why, now, jobId: first });
1181
+ if (ok) return { id: candidates[n - 1].id, reason: String(result.data.reason ?? '').trim() || 'no reason was given' };
1182
+ const smallest = diffs.reduce((at, d, i) => (d.length < diffs[at].length ? i : at), 0);
1183
+ return { id: candidates[smallest].id, reason: `the smallest change — no pick came back (${why})` };
1184
+ }