sumo-agents 0.4.0 → 0.5.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 (52) hide show
  1. package/AGENTS.md +8 -6
  2. package/CHANGELOG.md +155 -0
  3. package/README.md +76 -18
  4. package/bin/sumo.mjs +13 -2
  5. package/guides/feature.md +2 -1
  6. package/guides/memory.md +6 -4
  7. package/guides/projects.md +1 -1
  8. package/guides/review.md +1 -1
  9. package/package.json +5 -4
  10. package/prompts/dream.md +6 -0
  11. package/spinner.txt +25 -1
  12. package/src/apply.mjs +146 -18
  13. package/src/auth.mjs +32 -5
  14. package/src/card.mjs +39 -2
  15. package/src/catalog.mjs +6 -3
  16. package/src/chat.mjs +197 -86
  17. package/src/cli.mjs +359 -135
  18. package/src/cost.mjs +67 -8
  19. package/src/db.mjs +106 -3
  20. package/src/dream.mjs +445 -19
  21. package/src/editor.mjs +3 -2
  22. package/src/export.mjs +105 -7
  23. package/src/guard.mjs +57 -11
  24. package/src/guides.mjs +5 -4
  25. package/src/herdr.mjs +4 -2
  26. package/src/hooks.mjs +31 -18
  27. package/src/jobs.mjs +118 -39
  28. package/src/jobtools.mjs +6 -4
  29. package/src/keeper.mjs +77 -0
  30. package/src/local-server.mjs +9 -16
  31. package/src/lock.mjs +2 -1
  32. package/src/logs.mjs +165 -0
  33. package/src/loop.mjs +121 -44
  34. package/src/mcp.mjs +72 -16
  35. package/src/memory.mjs +142 -15
  36. package/src/model.mjs +41 -21
  37. package/src/paths.mjs +38 -0
  38. package/src/prime.mjs +19 -31
  39. package/src/projects.mjs +76 -12
  40. package/src/redact.mjs +10 -0
  41. package/src/render.mjs +2 -1
  42. package/src/route.mjs +16 -22
  43. package/src/sandbox.mjs +82 -3
  44. package/src/scan.mjs +35 -1
  45. package/src/scribe.mjs +10 -22
  46. package/src/sessions.mjs +46 -11
  47. package/src/setup.mjs +423 -78
  48. package/src/text.mjs +100 -1
  49. package/src/tools.mjs +258 -21
  50. package/src/tty.mjs +205 -78
  51. package/src/ui.mjs +869 -293
  52. package/src/verify.mjs +17 -1
package/src/guard.mjs CHANGED
@@ -14,10 +14,11 @@ import { homedir } from 'node:os';
14
14
 
15
15
  /**
16
16
  * A file whose contents are a secret: reading it is refused, and a change that adds one is never DONE. A glob (`.env*`) names them too.
17
- * Any case: the disk a Mac ships with reads `.ENV` as `.env`. A redirect (`<.env`) is a reading too.
17
+ * Any case: the disk a Mac ships with reads `.ENV` as `.env`. A redirect (`<.env`) is a reading too, and so is a file at a
18
+ * revision (`HEAD:.env`).
18
19
  */
19
20
  const SECRET_FILE =
20
- /(^|[\s/'"=<])(\.env[*?]*(\.(?!example\b|sample\b|template\b)[\w*?-]+)?|\.netrc|\.git-credentials|\.aws\/credentials|\.ssh\/(?!known_hosts\b|config\b|authorized_keys\b)[\w.-]+(?<!\.pub)|id_(rsa|dsa|ecdsa|ed25519)(?!\.pub)|[\w.-]+\.(pem|key|p12|pfx))(?=$|[\s'"|;&)])/i;
21
+ /(^|[\s/'"=<:])(\.env[*?]*(\.(?!example\b|sample\b|template\b)[\w*?-]+)?|\.netrc|\.git-credentials|\.aws\/credentials|\.ssh\/(?!known_hosts\b|config\b|authorized_keys\b)[\w.-]+(?<!\.pub)|id_(rsa|dsa|ecdsa|ed25519)(?!\.pub)|[\w.-]+\.(pem|key|p12|pfx))(?=$|[\s'"|;&)])/i;
21
22
 
22
23
  /** Anything that would put a file's contents in front of the model, `$(< file)` among them. `source .env` is not on it: that sets variables without showing them. */
23
24
  const PRINTS = /(^|[\s;&|($`])(cat|head|tail|less|more|bat|grep|rg|egrep|fgrep|sed|awk|cut|strings|xxd|hexdump|od|base64|nl|tac|view|vim?|nano|code|open|pbcopy|jq|yq)\s|\$\(\s*</;
@@ -25,22 +26,67 @@ const PRINTS = /(^|[\s;&|($`])(cat|head|tail|less|more|bat|grep|rg|egrep|fgrep|s
25
26
  /** Where one simple command ends and the next begins: a separator, a pipe, a new line, a subshell or a substitution. */
26
27
  const SEPARATORS = /[;&|\n()`]|\$\(/;
27
28
 
28
- /** A secret file bound to a name instead of read: `f=.env`, `for f in .env .env.local`. What later prints `$f` is a reading of it. */
29
- const BINDS = /(^|[\s;&|(`])(?:\w+=|for\s+\w+\s+in\s)/;
29
+ /**
30
+ * Commands that name a secret file without putting what is in it in front of the model: loading it (`source`, `.`),
31
+ * listing, testing, touching or removing it, changing its mode, and `echo`/`printf`, which print the name.
32
+ */
33
+ const NAMES_ONLY = new Set(['source', '.', 'ls', 'test', '[', '[[', 'touch', 'chmod', 'chown', 'rm', 'stat', 'file', 'echo', 'printf', 'mkdir']);
34
+ /** Of git's commands, those that name a file without printing it. `git diff` and `git show` print it. */
35
+ const GIT_NAMES_ONLY = new Set(['add', 'rm', 'mv', 'status', 'check-ignore', 'ls-files', 'update-index', 'restore']);
36
+ /** Commands that copy a file: harmless only when the secret is where it goes, never where it comes from. */
37
+ const COPIES = new Set(['cp', 'mv', 'install', 'ln']);
38
+ /** Words in front of a command that leave it the same command. */
39
+ const PREFIXES = new Set(['sudo', 'command', 'builtin', 'nohup', 'time', 'exec', 'env']);
40
+ /** A here-document whose delimiter is quoted: its body is text, nothing in it runs or expands. */
41
+ const QUOTED_HEREDOC = /<<-?\s*(['"])(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2[ \t]*(?=\n|$)/g;
42
+ /** A shell started on a command string: what matters is the command inside the quotes. */
43
+ const SHELL_C = /\b(?:ba|z)?sh\s+-l?c\s+/g;
44
+ const isSecret = (word) => SECRET_FILE.test(` ${word} `);
45
+
46
+ /**
47
+ * Whether one simple command reads a secret file it names. Read narrowly the other way round from a list of printing
48
+ * commands, which a reader nobody listed (`sort`, `diff`, a one-line script) walks past: it reads it unless what it does
49
+ * with it is one of the few things that never show what is in it — loading, listing, writing into it, copying onto it,
50
+ * git's bookkeeping, or handing it to a container as its environment.
51
+ */
52
+ function readsSecret(part) {
53
+ // Written into, not read: a redirect's target is not an argument.
54
+ const rest = part.replace(/\d*>>?\s*\S+/g, ' ');
55
+ if (!SECRET_FILE.test(rest)) return false;
56
+ // `$(< .env)` was split at its `$(`: what is left starts with the redirect.
57
+ if (/^\s*</.test(rest)) return true;
58
+ const words = rest.trim().replace(/^["']+/, '').split(/\s+/).filter(Boolean);
59
+ let i = 0;
60
+ while (i < words.length && (PREFIXES.has(words[i]) || /^\w+=/.test(words[i]))) i++;
61
+ const [command, sub] = [words[i], words[i + 1]];
62
+ if (NAMES_ONLY.has(command)) return false;
63
+ if (command === 'git' && GIT_NAMES_ONLY.has(sub)) return false;
64
+ if (COPIES.has(command)) return !isSecret(words.at(-1));
65
+ if (command === 'docker' || command === 'podman') return SECRET_FILE.test(rest.replace(/--env-file[=\s]+\S+/g, ' '));
66
+ return true;
67
+ }
30
68
 
31
69
  /**
32
- * Whether a command puts a secret file's contents in front of the model: a printing command with the file among its
33
- * words — in the same simple command, not merely somewhere in the same line, so `source .env && npm test | tail` is
34
- * what it looks like — or a printing command given a variable the file was bound to earlier in the line.
70
+ * Whether a command puts a secret file's contents in front of the model: one of its simple commands reads the file —
71
+ * judged command by command, not across the line, so `source .env && npm test | tail` is what it looks like — or a
72
+ * printing command is given a variable the file was bound to earlier in the line.
35
73
  */
36
74
  function printsSecret(command) {
37
- const parts = command.replace(/\\\n/g, ' ').split(SEPARATORS);
75
+ const parts = command.replace(/\\\n/g, ' ').replace(QUOTED_HEREDOC, '<<heredoc').replace(SHELL_C, ' ').split(SEPARATORS);
38
76
  let bound = false;
39
77
  for (const part of parts) {
40
78
  if (!SECRET_FILE.test(part)) continue;
41
- // `$(< .env)` was split at its `$(`: what is left starts with the redirect.
42
- if (PRINTS.test(part) || /^\s*</.test(part)) return true;
43
- if (BINDS.test(part)) bound = true;
79
+ // Bound to a name, not read: `f=.env`, `export ENV_FILE=.env`, `for f in .env …`. What later prints `$f` is a reading.
80
+ const first = part.trim().split(/\s+/)[0];
81
+ if (/^\w+=/.test(first) && part.trim().split(/\s+/).every((w) => /^\w+=/.test(w))) {
82
+ bound = true;
83
+ continue;
84
+ }
85
+ if (first === 'export' || first === 'for') {
86
+ bound = true;
87
+ continue;
88
+ }
89
+ if (readsSecret(part)) return true;
44
90
  }
45
91
  return bound && parts.some((part) => PRINTS.test(part) && part.includes('$'));
46
92
  }
package/src/guides.mjs CHANGED
@@ -1,8 +1,6 @@
1
1
  import { readdirSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import { getMeta } from './db.mjs';
4
3
  import { REPO_ROOT } from './paths.mjs';
5
- import { CONFIG_DEFAULTS } from './setup.mjs';
6
4
  import { stem, words } from './text.mjs';
7
5
 
8
6
  /**
@@ -82,5 +80,8 @@ export function renderGuide(name) {
82
80
  return `<guide ${name}>\nThe user is asking for ${asking}. This is how that is done here — follow it in order:\n${body}\n</guide>`;
83
81
  }
84
82
 
85
- /** `guides.auto`: whether guides ride in unasked and the end of a turn is held for an unchecked edit. */
86
- export const autoGuides = (db) => (getMeta(db, 'config.guides.auto') ?? CONFIG_DEFAULTS['guides.auto']) !== 'off';
83
+ /**
84
+ * Whether guides ride in unasked and the end of a turn is held for an unchecked edit: always, for the user. The coding
85
+ * eval's `--no-guides` switches them off for its own run (SUMO_AGENTS_GUIDES=off), to measure what a guide is worth.
86
+ */
87
+ export const autoGuides = () => process.env.SUMO_AGENTS_GUIDES !== 'off';
package/src/herdr.mjs CHANGED
@@ -12,7 +12,7 @@ import { paths, SELF } from './paths.mjs';
12
12
  export const runHerdr = (args) => spawnSync('herdr', args, { encoding: 'utf8', timeout: 10_000 });
13
13
 
14
14
  /** The name a job goes by in Herdr's lists: `j33 scout`. */
15
- export const agentLabel = (job) => `j${job.id} ${job.agent}`;
15
+ const agentLabel = (job) => `j${job.id} ${job.agent}`;
16
16
 
17
17
  /**
18
18
  * What the job's own process tells Herdr about itself, when it runs in a pane: working while it works, blocked
@@ -78,7 +78,9 @@ const screen = (herdr, pane) => {
78
78
  */
79
79
  export async function startWatcher(herdr, { pane, job, command, sleep = pause, tries = TRIES }) {
80
80
  const watching = new RegExp(`job watch ${job}(?!\\d)`);
81
- const started = (info) => info.foreground_processes?.some((p) => watching.test(String(p.cmdline))) || screen(herdr, pane)?.includes(`⏺ j${job} `);
81
+ // The record's first line: the job named in the ledger's gutter, then who works on it.
82
+ const shown = new RegExp(`(?:^|\\n) *j${job} {2,}\\S`);
83
+ const started = (info) => info.foreground_processes?.some((p) => watching.test(String(p.cmdline))) || shown.test(screen(herdr, pane) ?? '');
82
84
  for (let attempt = 0; attempt < tries; attempt++) {
83
85
  let last = null;
84
86
  for (let waited = 0; waited < READY_MS; waited += POLL_MS) {
package/src/hooks.mjs CHANGED
@@ -1,17 +1,17 @@
1
- import { appendFileSync, mkdirSync } from 'node:fs';
2
- import { join } from 'node:path';
3
1
  import { card } from './card.mjs';
4
2
  import { getMeta, openDb, setMeta } from './db.mjs';
5
3
  import { backup } from './export.mjs';
6
4
  import { guardCommand, guardPath } from './guard.mjs';
7
5
  import { autoGuides, firingGuides, matchGuide, renderGuide } from './guides.mjs';
8
- import { paths } from './paths.mjs';
6
+ import { appendLog } from './logs.mjs';
7
+ import { expireUnusedGotchas, GOTCHA_UNUSED_DAYS } from './memory.mjs';
9
8
  import { prime } from './prime.mjs';
10
- import { detect, keepScratch, projectAt, touch } from './projects.mjs';
9
+ import { detect, freshen, keepScratch, projectAt, touch } from './projects.mjs';
11
10
  import { closingQuestions, recallBeforeAsking } from './recall.mjs';
12
11
  import { line } from './render.mjs';
13
12
  import { shouldRun, spawnDetached } from './scribe.mjs';
14
- import { clearInjections, contextBand, contextNudge, contextUse, currentProject, endSession, ensureSession, injectedSlugs, markInjected, pruneStates, recordTurn, sessionsAwaitingDream } from './sessions.mjs';
13
+ import { tidyDue } from './dream.mjs';
14
+ import { clearInjections, contextBand, contextNudge, contextUse, currentProject, endSession, ensureSession, injectedSlugs, markInjected, pruneStates, recordTurn } from './sessions.mjs';
15
15
  import { claim, renderWorkflow, withoutSumoCalls } from './workflows.mjs';
16
16
 
17
17
  /**
@@ -23,10 +23,9 @@ import { claim, renderWorkflow, withoutSumoCalls } from './workflows.mjs';
23
23
  */
24
24
 
25
25
  const BACKUP_EVERY_MS = 7 * 24 * 3_600_000;
26
- const SESSIONS_TO_DREAM = 3;
27
26
 
28
27
  /** The one event shape. Field names are what the payload carries; a missing one is simply absent. */
29
- export function fieldsOf(p) {
28
+ function fieldsOf(p) {
30
29
  return {
31
30
  sessionId: p.session_id,
32
31
  cwd: p.cwd ?? null,
@@ -53,7 +52,7 @@ const deny = (reason) => JSON.stringify({ deny: reason });
53
52
  const isRead = (tool) => tool === 'read' || tool === 'view';
54
53
 
55
54
  /** The guard, first and without memory: a destructive command or a secret file is refused on sight. */
56
- export function earlyRefusal(e) {
55
+ function earlyRefusal(e) {
57
56
  if (e.toolName === 'bash' && e.command) return guardCommand(e.command, { cwd: e.cwd }) ?? '';
58
57
  if (isRead(e.toolName) && e.path) return guardPath(e.path) ?? '';
59
58
  return '';
@@ -91,7 +90,7 @@ function sizeNudge(db, e, now) {
91
90
  * was shown before, and whatever the switch says: the user asked for it.
92
91
  */
93
92
  function guideDue(db, e, now, taught) {
94
- const name = e.guide ?? (!taught && autoGuides(db) ? matchGuide(e.prompt) : null);
93
+ const name = e.guide ?? (!taught && autoGuides() ? matchGuide(e.prompt) : null);
95
94
  if (!name || !firingGuides().some((g) => g.name === name)) return '';
96
95
  const slug = `guide:${name}`;
97
96
  if (!e.guide && db.prepare('SELECT 1 FROM session_injections WHERE session_id = ? AND slug = ?').get(e.sessionId, slug)) return '';
@@ -106,7 +105,7 @@ function guideDue(db, e, now, taught) {
106
105
  * left alone.
107
106
  */
108
107
  function unchecked(db, e) {
109
- if (e.edited.length === 0 || !autoGuides(db)) return '';
108
+ if (e.edited.length === 0 || !autoGuides()) return '';
110
109
  const first = e.edited.slice(0, 3);
111
110
  const rest = e.edited.length > 3 ? `${e.edited.length - 3} more` : first.length > 1 ? first.pop() : null;
112
111
  const shown = rest ? `${first.join(', ')} and ${rest}` : first[0];
@@ -125,8 +124,8 @@ const HANDLERS = {
125
124
  // A fresh start wipes the cards from context; forgetting they were shown lets them come back.
126
125
  if (e.source === 'compact' || e.source === 'new') clearInjections(db, e.sessionId);
127
126
 
128
- if (shouldRun(db, { event: 'session-start', now })) spawnDetached(['scribe', 'run']);
129
- if (sessionsAwaitingDream(db, now, SESSIONS_TO_DREAM).length >= SESSIONS_TO_DREAM) spawnDetached(['dream', 'run']);
127
+ // One memory pass: it files what waits, and tidies too when conversations have finished or a week has gone by.
128
+ if (shouldRun(db, { event: 'session-start', now }) || tidyDue(db, now)) spawnDetached(['memory', 'run']);
130
129
 
131
130
  const last = getMeta(db, 'last_backup');
132
131
  if (!last || Date.parse(now) - Date.parse(last) > BACKUP_EVERY_MS) {
@@ -149,8 +148,16 @@ const HANDLERS = {
149
148
  // And this: scratch that cannot be made or tidied is said in the hook log; the session still gets its memory.
150
149
  logFailure('session-start scratch', cause);
151
150
  }
151
+ try {
152
+ // A trap nobody was ever shown, filed by an agent and never confirmed, lets go after a while; history keeps it.
153
+ const expired = expireUnusedGotchas(db, now);
154
+ if (expired > 0) appendLog('hook.log', `${now} session-start: ${expired} gotcha${expired === 1 ? '' : 's'} never shown in ${GOTCHA_UNUSED_DAYS} days let go (sumo history shows them)\n`);
155
+ } catch (cause) {
156
+ logFailure('session-start expire', cause);
157
+ }
152
158
 
153
- return prime(db, { now });
159
+ // The questions put to the user are this session's: about everything, or the project it was started in.
160
+ return prime(db, { now, project: currentProject(db, e.sessionId) ?? (e.cwd ? projectAt(db, e.cwd) : null) });
154
161
  },
155
162
 
156
163
  prompt(db, e, now) {
@@ -167,7 +174,14 @@ const HANDLERS = {
167
174
  // Every mention is stamped, not only the first: the project named last is the one the session is about, also when its card was shown before.
168
175
  markInjected(db, e.sessionId, slug, now);
169
176
  if (shown.has(slug)) continue;
170
- cards.push(card(db, slug, { now }));
177
+ // The card is built from the repository as it is now: a scan a week old, or older than a file it reads, is redone.
178
+ try {
179
+ freshen(db, slug, now);
180
+ } catch (cause) {
181
+ logFailure('prompt rescan', cause);
182
+ }
183
+ // Its questions come with it, unless the block this session started with asked them: a session started inside the project.
184
+ cards.push(card(db, slug, { now, asks: slug !== (e.cwd ? projectAt(db, e.cwd) : null) }));
171
185
  }
172
186
 
173
187
  const asked = claim(db, { sessionId: e.sessionId, text: e.prompt, scopes: scopesOf(db, e.sessionId), now });
@@ -210,7 +224,7 @@ const HANDLERS = {
210
224
 
211
225
  stop(db, e, now) {
212
226
  ensureSession(db, { id: e.sessionId, cwd: e.cwd, transcriptPath: e.transcriptPath, now });
213
- if (shouldRun(db, { event: 'stop', now })) spawnDetached(['scribe', 'run']);
227
+ if (shouldRun(db, { event: 'stop', now })) spawnDetached(['memory', 'run']);
214
228
 
215
229
  // The other gates: a turn that ends on an edit nothing checked, or by asking the user something memory may
216
230
  // already hold. Already continuing because of one → whatever the turn ends on now goes to the user.
@@ -223,7 +237,7 @@ const HANDLERS = {
223
237
  'session-end'(db, e, now) {
224
238
  ensureSession(db, { id: e.sessionId, cwd: e.cwd, transcriptPath: e.transcriptPath, now });
225
239
  endSession(db, e.sessionId, now);
226
- if (shouldRun(db, { event: 'session-end', now })) spawnDetached(['scribe', 'run']);
240
+ if (shouldRun(db, { event: 'session-end', now })) spawnDetached(['memory', 'run']);
227
241
  return '';
228
242
  },
229
243
  };
@@ -242,8 +256,7 @@ export function handleEvent(db, event, payload, now = new Date().toISOString())
242
256
  /** What went wrong, in logs/hook.log. If even the log cannot be written there is nothing left to do but stay out of the way. */
243
257
  function logFailure(what, cause) {
244
258
  try {
245
- mkdirSync(paths().logs, { recursive: true, mode: 0o700 });
246
- appendFileSync(join(paths().logs, 'hook.log'), `${new Date().toISOString()} ${what}: ${cause.stack ?? cause}\n`);
259
+ appendLog('hook.log', `${new Date().toISOString()} ${what}: ${cause.stack ?? cause}\n`);
247
260
  } catch {
248
261
  // Said above.
249
262
  }
package/src/jobs.mjs CHANGED
@@ -8,7 +8,7 @@ import { usableModels } from './catalog.mjs';
8
8
  import { getMeta, setMeta, tx } from './db.mjs';
9
9
  import { autoGuides, guideBody, matchGuide, WORKER_GUIDES } from './guides.mjs';
10
10
  import { heldBy } from './lock.mjs';
11
- import { UsageError } from './memory.mjs';
11
+ import { Refusal, UsageError } from './memory.mjs';
12
12
  import { callModel, failure, logRun } from './model.mjs';
13
13
  import { paths } from './paths.mjs';
14
14
  import { preferences } from './prime.mjs';
@@ -40,7 +40,7 @@ export function parseJobId(raw) {
40
40
 
41
41
  export function getJob(db, id) {
42
42
  const job = db.prepare('SELECT * FROM jobs WHERE id = ?').get(id);
43
- if (!job) throw new UsageError(`no job j${id}`);
43
+ if (!job) throw new Refusal(`no job j${id}`);
44
44
  return job;
45
45
  }
46
46
 
@@ -77,7 +77,7 @@ function setOpenStatus(db, id, status, now) {
77
77
  }
78
78
 
79
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}`);
80
+ if (job.status !== 'running' && job.status !== 'needs_input') throw new Refusal(`j${job.id} is ${job.status} — it cannot be ${verb}`);
81
81
  }
82
82
 
83
83
  const ROLE = {
@@ -208,7 +208,7 @@ function whereThingsStand(root) {
208
208
  function renderBrief({ job, project, known, rules, situation, task, guide, change, options = {} }) {
209
209
  const closing =
210
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:`
211
+ ? `\`finish\` with DONE (or FAILED). DONE is not taken on your word: the first is answered with the task as a numbered list beside your change, each number to answer once; 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
212
  : `\`finish\` with DONE (or FAILED), and this report:`;
213
213
  return `# Job j${job.id} — ${job.title}
214
214
 
@@ -256,7 +256,7 @@ const writeState = (db, id, state) => {
256
256
  };
257
257
 
258
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) {
259
+ function guideFor(name) {
260
260
  if (!GUIDES.includes(name)) throw new UsageError(`--guide is one of: ${[...GUIDES, 'none'].join(', ')}`);
261
261
  const text = guideBody(name);
262
262
  if (!text) throw new UsageError(`guides/${name}.md is missing or empty`);
@@ -265,11 +265,11 @@ export function guideFor(name) {
265
265
 
266
266
  /**
267
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.
268
+ * for, the way the chat is handed one by the user's words — unless the coding eval switched guides off. A scout changes nothing.
269
269
  */
270
- function defaultGuide(db, { agent, title, task }) {
270
+ function defaultGuide({ agent, title, task }) {
271
271
  if (agent === 'reviewer') return 'review';
272
- if (agent !== 'worker' || !autoGuides(db)) return null;
272
+ if (agent !== 'worker' || !autoGuides()) return null;
273
273
  return matchGuide(`${title}\n${task.split(/\n(?=## )/)[0]}`, WORKER_GUIDES);
274
274
  }
275
275
 
@@ -285,29 +285,31 @@ function changeToJudge(db, { project, reviews }) {
285
285
  let kept = null;
286
286
  if (reviews !== undefined) {
287
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}`);
288
+ if (target.project !== project.slug) throw new Refusal(`j${target.id} belongs to ${target.project}, not ${project.slug}`);
289
289
  const state = readState(db, target.id);
290
290
  snap = state?.snap;
291
291
  // A change still in the worktree it was made in is judged there.
292
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`);
293
+ if (!snap) throw new Refusal(`j${target.id} recorded no starting point (not a worker job, or not a git repository) — there is no change to hand over`);
294
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
295
  // the project holds that change and more — what git ignores, what was never added — none of it the job's.
296
296
  if (state.tree && !existsSync(state.tree.path)) kept = changes(db, target.id);
297
297
  lines.push(`What was asked: ${fileOf(target.id, 'brief.md')} (read "## The task")`);
298
+ // The task as the author was asked to answer it: the reviewer gives a verdict on each number under "Asked vs built".
299
+ lines.push('Asked, by number — a verdict on each under "Asked vs built", with what in the change shows it:', ...checklistOf(taskFromBrief(readOr(fileOf(target.id, 'brief.md')))).map((item, i) => ` ${i + 1}. ${item}`));
298
300
  if (existsSync(fileOf(target.id, 'report.md'))) {
299
301
  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
302
  }
301
303
  } 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`);
304
+ if (!hasCommit(project.path)) throw new Refusal(`${project.path} is not a git repository with a commit — there is no change to hand over`);
303
305
  snap = { base: 'HEAD', mixed: false, untracked: [] };
304
306
  }
305
307
  if (kept) {
306
- if (kept.files === 0) throw new UsageError('nothing has changed — there is nothing to review');
308
+ if (kept.files === 0) throw new Refusal('nothing has changed — there is nothing to review');
307
309
  return { snap, lines, root, kept };
308
310
  }
309
311
  const { tracked, created } = changesSince(root, snap);
310
- if (tracked.length + created.length === 0) throw new UsageError('nothing has changed — there is nothing to review');
312
+ if (tracked.length + created.length === 0) throw new Refusal('nothing has changed — there is nothing to review');
311
313
  return { snap, lines, root };
312
314
  }
313
315
 
@@ -371,7 +373,7 @@ export async function newJob(db, { project: nameOrAlias, title, agent = 'worker'
371
373
  if (reviews !== undefined && agent !== 'reviewer') throw new UsageError('--reviews goes with --agent reviewer');
372
374
  const project = getProject(db, nameOrAlias);
373
375
  // Everything that can refuse the job is settled before the job exists.
374
- const chosen = guideName === 'none' ? null : (guideName ?? defaultGuide(db, { agent, title, task }));
376
+ const chosen = guideName === 'none' ? null : (guideName ?? defaultGuide({ agent, title, task }));
375
377
  const guide = chosen ? guideFor(chosen) : null;
376
378
  const judged = agent === 'reviewer' ? changeToJudge(db, { project, reviews }) : null;
377
379
 
@@ -473,7 +475,7 @@ async function newAttempts(db, { attempts, title, ...options }) {
473
475
  if (options.agent !== 'worker') throw new UsageError('--attempts goes with a worker');
474
476
  if (!title?.trim()) throw new UsageError('a job needs a --title');
475
477
  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`);
478
+ if (!hasCommit(project.path)) throw new Refusal(`${project.path} is not a git repository with a commit — each attempt needs a worktree of its own`);
477
479
  const made = [];
478
480
  try {
479
481
  for (let n = 1; n <= attempts; n++) {
@@ -507,12 +509,12 @@ export async function retry(db, id, { now = new Date().toISOString() } = {}) {
507
509
  const old = getJob(db, id);
508
510
  const eligible = old.status === 'failed' || (old.status === 'done' && (old.important ?? 0) >= RETRY_IMPORTANT_THRESHOLD);
509
511
  if (!eligible) {
510
- throw new UsageError(
512
+ throw new Refusal(
511
513
  `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
514
  );
513
515
  }
514
516
  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`);
517
+ if (!task) throw new Refusal(`j${id}'s brief has no "## The task" section to retry from`);
516
518
 
517
519
  // What the original was allowed and pointed at travels with the task: a retry of a review judges the same job,
518
520
  // and a retry of a worker keeps the permission the first attempt was given.
@@ -583,7 +585,7 @@ none: a review changes nothing — read the change, what was asked, and the code
583
585
 
584
586
  /**
585
587
  * 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
588
+ * once, on a route one step up (`retry`) — a retry is never retried again this way, nor one sumo told to
587
589
  * close near its budget, time or turns, and one of several `attempts` is settled with its siblings instead. One that closed
588
590
  * DONE, verified by the checks — in git, so there is a change to hand over — is reviewed when the
589
591
  * router called its work risky, or always (`jobs.review`), by a reviewer at least as strong as it (`--reviews`). The job
@@ -593,7 +595,7 @@ async function followUp(db, id, { now = new Date().toISOString() } = {}) {
593
595
  const job = getJob(db, id);
594
596
  if (job.agent !== 'worker' || attemptsOf(db, id) !== null) return null;
595
597
  if (job.status === 'failed') {
596
- if (job.retry_of !== null || setting(db, 'jobs.escalate') !== 'on') return null;
598
+ if (job.retry_of !== null) return null;
597
599
  // 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
600
  // the limit off at a dearer price, and that is the user's call.
599
601
  const near = CLOSED_NEAR[getMeta(db, closingKey(id))];
@@ -687,9 +689,9 @@ function checkable(db, id, verb) {
687
689
  const job = getJob(db, id);
688
690
  requireOpen(job, verb);
689
691
  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'}`);
692
+ if (job.agent !== 'worker' || !state) throw new Refusal(`j${id} is not a worker job with a recorded start — there is nothing to ${verb === 'verified' ? 'verify' : 'take a baseline of'}`);
691
693
  const root = workdir(state, getProject(db, job.project));
692
- if (!existsSync(root)) throw new UsageError(`${root} no longer exists`);
694
+ if (!existsSync(root)) throw new Refusal(`${root} no longer exists`);
693
695
  return { job, state, root };
694
696
  }
695
697
 
@@ -723,7 +725,7 @@ export function verifyJob(db, id, now = new Date().toISOString()) {
723
725
  export function changes(db, id) {
724
726
  const job = getJob(db, id);
725
727
  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)`);
728
+ if (!state?.snap) throw new Refusal(`j${id} recorded no starting point (not a worker job, or not a git repository)`);
727
729
  const root = workdir(state, getProject(db, job.project));
728
730
  // 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
731
  if (state.tree && !existsSync(root) && existsSync(fileOf(id, 'changes.diff'))) {
@@ -820,6 +822,24 @@ export function startLive(id) {
820
822
  export const appendLive = (id, text) => appendFileSync(liveFile(id), text, { mode: 0o600 });
821
823
  export const endLive = (id, lines) => writeFileSync(endFile(id), `${lines.join('\n')}\n`, { mode: 0o600 });
822
824
 
825
+ /**
826
+ * The tools a job used that read the world outside the machine — a web search, a fetch, an MCP server — one name a
827
+ * line, each once. What such a run says it learned may be what a page told it, so it is not filed as a fact (see finish).
828
+ */
829
+ const outsideFile = (id) => fileOf(id, 'outside');
830
+ export function noteOutsideRead(id, tool) {
831
+ const name = String(tool).replace(/\s+/g, ' ');
832
+ if (outsideReads(id).includes(name)) return;
833
+ appendFileSync(outsideFile(id), `${name}\n`, { mode: 0o600 });
834
+ }
835
+ export function outsideReads(id) {
836
+ try {
837
+ return readFileSync(outsideFile(id), 'utf8').split('\n').filter(Boolean);
838
+ } catch {
839
+ return [];
840
+ }
841
+ }
842
+
823
843
  /** 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
844
  export function takeInbox(id) {
825
845
  let names;
@@ -843,7 +863,7 @@ export function takeInbox(id) {
843
863
 
844
864
  export function answer(db, id, text, now = new Date().toISOString()) {
845
865
  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`);
866
+ if (job.status !== 'needs_input') throw new Refusal(`j${id} is ${job.status} — it is not waiting for an answer`);
847
867
  if (!text.trim()) throw new UsageError('the answer is empty — put it on stdin');
848
868
  append(id, 'qa.md', 'Answer', text, now);
849
869
  setOpenStatus(db, id, 'running', now);
@@ -892,10 +912,48 @@ const checkedFile = (id) => fileOf(id, 'checked');
892
912
  /** How many changed files, and how many new ones, the check names before it counts the rest. */
893
913
  const CHECK_LISTED = 30;
894
914
 
915
+ /** The most lines of one section of the task that become items of their own; past it, the rest is one item. */
916
+ const ITEMS_PER_SECTION = 12;
917
+
918
+ /** The lines under one `## heading` of a task, bullets and numbers stripped, until the next heading. */
919
+ function sectionLines(task, heading) {
920
+ const lines = String(task ?? '').split('\n');
921
+ const at = lines.findIndex((l) => l.trim().toLowerCase() === `## ${heading}`.toLowerCase());
922
+ if (at === -1) return [];
923
+ const body = [];
924
+ for (const line of lines.slice(at + 1)) {
925
+ if (/^##\s/.test(line)) break;
926
+ const said = line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, '').trim();
927
+ if (said && !/^none\.?$/i.test(said)) body.push(said);
928
+ }
929
+ return body;
930
+ }
931
+
932
+ /**
933
+ * The task as a numbered list, one line each — what was asked, what must not change, what must not be attempted, and the
934
+ * check that proves it — for an author or a reviewer to answer by number. A checklist drawn from the task is answered;
935
+ * "check your work" is not: measured on long tasks, an itemized list caught what a general self-check let through. A task
936
+ * without those headings is one item: the whole of it.
937
+ */
938
+ export function checklistOf(task) {
939
+ const items = [];
940
+ const take = (heading, say) => {
941
+ const lines = sectionLines(task, heading);
942
+ for (const line of lines.slice(0, ITEMS_PER_SECTION)) items.push(say(line));
943
+ if (lines.length > ITEMS_PER_SECTION) items.push(`and the ${lines.length - ITEMS_PER_SECTION} more lines under ${heading}`);
944
+ };
945
+ take('Goal', (l) => `Done: ${l}`);
946
+ take('Must not change', (l) => `Unchanged: ${l}`);
947
+ take('Non-goals', (l) => `Not attempted: ${l}`);
948
+ take('Check', (l) => `Ran, and it passed: ${l}`);
949
+ if (items.length === 0) items.push('Done: everything the task asks, as it asks it.');
950
+ return items;
951
+ }
952
+
895
953
  /**
896
954
  * 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.
955
+ * the job began, and the task as a list to answer by number — the first thing a reviewer does, done by the author while
956
+ * it can still fix what it finds. Nothing is run here; the checks come with the next DONE.
899
957
  */
900
958
  function checkAgainstTask(db, job, state) {
901
959
  // Where the job works: its worktree when it was given one, the project otherwise.
@@ -913,20 +971,21 @@ function checkAgainstTask(db, job, state) {
913
971
  change = ['what changed could not be read from git — look over it yourself'];
914
972
  }
915
973
  }
974
+ const task = taskFromBrief(readOr(fileOf(job.id, 'brief.md')));
975
+ // Asked to hunt for the bug, an author judges its own work closest (arXiv 2602.06948: told to find what breaks it,
976
+ // not whether it works); and nothing that was in the tree before the job is the job's to undo.
977
+ const items = [...checklistOf(task), 'Debug output and scratch files are removed.', 'Tests were changed only if the task allows it.', 'Every claim in the report is backed by a tool result from this run.', 'The input most likely to break this change is named, and was run.', 'No change you did not make was reverted or overwritten.'];
916
978
  return [
917
979
  `j${job.id} is not closed yet — before DONE counts, check the work against the task. Nothing was run.`,
918
980
  '',
919
981
  '## The task',
920
- taskFromBrief(readOr(fileOf(job.id, 'brief.md'))) || '(the brief has no "## The task" section)',
982
+ task || '(the brief has no "## The task" section)',
921
983
  '',
922
984
  '## What changed since the job began',
923
985
  ...change,
924
986
  '',
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.',
987
+ '## Answer each by number — what in the change or a tool result shows it — and fix what is not so',
988
+ ...items.map((item, i) => `${i + 1}. ${item}`),
930
989
  '',
931
990
  'Then call `finish` again with the same report, or a corrected one, to go on to verification. This is asked once.',
932
991
  ].join('\n');
@@ -948,21 +1007,21 @@ export function finish(db, id, { status, report, accept }, now = new Date().toIS
948
1007
  // 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
1008
  const graded = job.agent === 'worker' && status === 'DONE';
950
1009
  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>"`);
1010
+ const unchecked = (why) => new Refusal(`j${id} cannot be verified — ${why}. To take the work as it stands: sumo job finish ${id} --status DONE --accept "<why>"`);
952
1011
  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
1012
  // 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
1013
  // Kept in the job's folder, so a run started again goes on to the checks instead of being asked again.
955
1014
  if (graded && accept === undefined && !existsSync(checkedFile(id))) {
956
1015
  const asked = checkAgainstTask(db, job, state);
957
1016
  writeFileSync(checkedFile(id), `${now}\n`, { mode: 0o600 });
958
- throw new UsageError(asked);
1017
+ throw new Refusal(asked);
959
1018
  }
960
1019
  const verdict = state && accept === undefined ? verdictForDone(db, id, state, now) : null;
961
1020
  // The checks can take minutes: report a job closed in the meantime before interpreting their verdict.
962
1021
  requireOpen(getJob(db, id), 'finished');
963
1022
  if (graded && accept === undefined && !verdict) throw unchecked(`${getProject(db, job.project).path} no longer exists, so its checks cannot be run`);
964
1023
  if (verdict && !verdict.ok) {
965
- throw new UsageError(
1024
+ throw new Refusal(
966
1025
  [
967
1026
  `j${id} is not done — the project's checks were run, and:`,
968
1027
  ...verdictLines(verdict).map((l) => ` ${l}`),
@@ -994,6 +1053,16 @@ export function finish(db, id, { status, report, accept }, now = new Date().toIS
994
1053
  const kept = !isScratch(getProject(db, job.project));
995
1054
  const ops = kept ? learnedLines(report).map((body) => ({ op: 'gotcha', scope: `project:${job.project}`, body: clip(body, 300) })) : [];
996
1055
  const learned = applyOps(db, ops, { source: 'worker', turns: new Map(), now });
1056
+ // A run that read a page or an MCP server may be passing on what it was told: what it learned waits for the user to
1057
+ // confirm (arXiv 2503.03704 — memory written from injected content is read later as trusted). Exactly what this
1058
+ // finish wrote is held: another job finishing in the same project at the same moment keeps its own.
1059
+ const outside = outsideReads(id);
1060
+ if (outside.length > 0 && learned.written.length > 0) {
1061
+ const held = db
1062
+ .prepare(`UPDATE memories SET state = 'unconfirmed', provenance = 'inferred', held_for = 'outside' WHERE id IN (${learned.written.map(() => '?').join(', ')}) AND type = 'gotcha' AND state = 'active' RETURNING id`)
1063
+ .all(...learned.written);
1064
+ if (held.length > 0) learned.applied = learned.applied.map((said) => `${said} — held for the user to confirm: this run read ${outside.join(', ')}`);
1065
+ }
997
1066
 
998
1067
  const summary = /^##\s*Summary\s*\n+([^\n]+)/im.exec(report)?.[1]?.trim();
999
1068
  if (kept) {
@@ -1020,11 +1089,21 @@ export function listJobs(db, { all = false } = {}) {
1020
1089
  const where = all ? '' : `WHERE status IN ('running', 'needs_input')`;
1021
1090
  const rows = db.prepare(`SELECT * FROM jobs ${where} ORDER BY id DESC LIMIT ${LISTED}`).all();
1022
1091
  const total = db.prepare(`SELECT COUNT(*) AS n FROM jobs ${where}`).get().n;
1023
- return Object.assign(rows, { more: total - rows.length });
1092
+ return Object.assign(rows.map((row) => ({ ...row, shown: shownStatus(db, row) })), { more: total - rows.length });
1093
+ }
1094
+
1095
+ /**
1096
+ * A job's state as a person reads it; the stored status is unchanged. Open, it is running only while a run holds it,
1097
+ * not started if no run ever sent a request for it, and stopped if a stop — budget, time, Esc — left it open.
1098
+ */
1099
+ function shownStatus(db, job) {
1100
+ if (job.status !== 'running') return job.status;
1101
+ if (atWork(job.id)) return 'running';
1102
+ return db.prepare('SELECT 1 FROM model_runs WHERE job_id = ? LIMIT 1').get(job.id) ? 'stopped' : 'not started';
1024
1103
  }
1025
1104
 
1026
- export function jobLine(job) {
1027
- return `j${job.id} [${job.agent}·${job.project}·${job.status}] ${job.title}`;
1105
+ export function jobLine(job, status = job.status) {
1106
+ return `j${job.id} [${job.agent}·${job.project}·${status}] ${job.title}`;
1028
1107
  }
1029
1108
 
1030
1109
  /** The report a job closed with, as its sub-agent wrote it; empty while it has none. */
@@ -1033,7 +1112,7 @@ export const reportOf = (id) => readOr(fileOf(id, 'report.md')).trim();
1033
1112
  /** What the main agent needs to decide its next move — not the whole report. */
1034
1113
  export function show(db, id) {
1035
1114
  const job = getJob(db, id);
1036
- const out = [jobLine(job), `files: ${dirOf(id)}`];
1115
+ const out = [jobLine(job, shownStatus(db, job)), `files: ${dirOf(id)}`];
1037
1116
  if (job.model && job.effort) out.push(`route: ${job.model}/${job.effort} — ${job.route_reason}`);
1038
1117
  if (job.important !== null && job.important !== undefined) out.push(`important: ${job.important}`);
1039
1118
  const qa = readOr(fileOf(id, 'qa.md')).trim();
@@ -1052,7 +1131,7 @@ const pickedKey = (first) => `job.${first}.picked`;
1052
1131
  const firstTo = (db, key, now) => tx(db, () => getMeta(db, key) === null && (setMeta(db, key, now), true));
1053
1132
 
1054
1133
  /** The jobs one `--attempts` made, in order; null for a job that is not one of them. */
1055
- export function attemptsOf(db, id) {
1134
+ function attemptsOf(db, id) {
1056
1135
  const ids = getMeta(db, attemptsKey(id));
1057
1136
  return ids === null ? null : JSON.parse(ids);
1058
1137
  }