sumo-agents 0.4.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/AGENTS.md +8 -6
  2. package/CHANGELOG.md +187 -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 +186 -75
  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 +1 -1
  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 +210 -44
  51. package/src/ui.mjs +816 -226
  52. package/src/verify.mjs +17 -1
package/src/projects.mjs CHANGED
@@ -3,10 +3,11 @@ import { homedir } from 'node:os';
3
3
  import { basename, join, resolve } from 'node:path';
4
4
  import { getMeta, setMeta, tx } from './db.mjs';
5
5
  import * as memory from './memory.mjs';
6
- import { UsageError } from './memory.mjs';
6
+ import { Refusal, UsageError } from './memory.mjs';
7
7
  import { paths } from './paths.mjs';
8
- import { gitRemote, scan } from './scan.mjs';
9
- import { CONFIG_DEFAULTS } from './setup.mjs';
8
+ import { changedSince, gitRemote, presentOf, scan } from './scan.mjs';
9
+
10
+ import { STOPWORDS } from './text.mjs';
10
11
 
11
12
  /**
12
13
  * Names too ordinary to mean "this project" when they turn up in a sentence.
@@ -22,7 +23,7 @@ const slugify = (name) => name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').repl
22
23
 
23
24
  function expand(path) {
24
25
  const full = resolve(path.replace(/^~(?=$|\/)/, homedir()));
25
- if (!existsSync(full) || !statSync(full).isDirectory()) throw new UsageError(`${full} is not a directory`);
26
+ if (!existsSync(full) || !statSync(full).isDirectory()) throw new Refusal(`${full} is not a directory`);
26
27
  return realpathSync(full);
27
28
  }
28
29
 
@@ -35,13 +36,47 @@ export function aliasesOf(db, slug) {
35
36
  return db.prepare('SELECT alias FROM project_aliases WHERE slug = ? ORDER BY alias').all(slug).map((r) => r.alias);
36
37
  }
37
38
 
39
+ /**
40
+ * A name too short or too common to stand for a project: every sentence holding it would name the project, and its
41
+ * card — and its folder as the chat's place to work — would come with it.
42
+ */
43
+ const tooCommon = (name) => name.length < 3 || STOPWORDS.has(name);
44
+
45
+ /**
46
+ * Folders that are never a project: the disk's top, your home and anything above it, and sumo's own home. Made the
47
+ * chat's project, one would be the shell's place to write — all of it.
48
+ */
49
+ function refuseTooWide(path) {
50
+ const real = (p) => {
51
+ try {
52
+ return realpathSync(p);
53
+ } catch {
54
+ return p;
55
+ }
56
+ };
57
+ const holds = (outer, inner) => outer === '/' || outer === inner || `${inner}/`.startsWith(`${outer}/`);
58
+ const home = real(homedir());
59
+ const sumo = real(paths().home);
60
+ const refuse = (what) => {
61
+ throw new Refusal(`${path} cannot be a project: it holds ${what} — a project is one folder of work`);
62
+ };
63
+ if (path === '/') refuse('the whole disk');
64
+ if (holds(path, home)) refuse('your home');
65
+ if (holds(path, sumo)) refuse("sumo's own home");
66
+ // A system folder on the PATH (/opt/homebrew/bin, /usr/local/bin): made the shell's place to write, a program put there
67
+ // would run whenever its name is typed. One in the home is the user's own, and judged as the home is.
68
+ const onPath = String(process.env.PATH ?? '').split(':').filter((d) => d.startsWith('/')).map(real).find((d) => !holds(home, d) && holds(path, d));
69
+ if (onPath) refuse(`${onPath}, a folder on your PATH`);
70
+ }
71
+
38
72
  export function addAlias(db, slug, rawAlias) {
39
73
  const alias = slugify(rawAlias);
40
74
  if (!alias) throw new UsageError(`"${rawAlias}" is not a usable alias`);
75
+ if (tooCommon(alias)) throw new UsageError(`"${alias}" is too short or too common a word to name a project: every sentence with it would mean the project`);
41
76
  const takenBySlug = db.prepare('SELECT slug FROM projects WHERE slug = ?').get(alias);
42
77
  const takenByAlias = db.prepare('SELECT slug FROM project_aliases WHERE alias = ?').get(alias);
43
78
  const owner = takenBySlug?.slug ?? takenByAlias?.slug;
44
- if (owner && owner !== slug) throw new UsageError(`"${alias}" already means the project ${owner}`);
79
+ if (owner && owner !== slug) throw new Refusal(`"${alias}" already means the project ${owner}`);
45
80
  if (!owner) db.prepare('INSERT INTO project_aliases (alias, slug) VALUES (?, ?)').run(alias, slug);
46
81
  return alias;
47
82
  }
@@ -52,6 +87,7 @@ export function addAlias(db, slug, rawAlias) {
52
87
  */
53
88
  export function addProject(db, rawPath, { slug: wantedSlug, aliases = [], now = new Date().toISOString() } = {}) {
54
89
  const path = expand(rawPath);
90
+ refuseTooWide(path);
55
91
  // Read off disk before the write lock is taken, as rescan does.
56
92
  const read = { scanned: scan(path), remote: gitRemote(path) };
57
93
  return tx(db, () => {
@@ -60,8 +96,9 @@ export function addProject(db, rawPath, { slug: wantedSlug, aliases = [], now =
60
96
  if (created) {
61
97
  const slug = slugify(wantedSlug ?? basename(path));
62
98
  if (!slug) throw new UsageError('could not derive a name from that path — pass --slug');
99
+ if (wantedSlug !== undefined && tooCommon(slug)) throw new UsageError(`"${slug}" is too short or too common a word to name a project: every sentence with it would mean the project`);
63
100
  if (db.prepare('SELECT 1 FROM projects WHERE slug = ?').get(slug) || db.prepare('SELECT 1 FROM project_aliases WHERE alias = ?').get(slug)) {
64
- throw new UsageError(`the name "${slug}" is taken by another project — pass --slug <name>`);
101
+ throw new Refusal(`the name "${slug}" is taken by another project — pass --slug <name>`);
65
102
  }
66
103
  db.prepare('INSERT INTO projects (slug, name, path, remote, created_at, last_touched_at) VALUES (?, ?, ?, ?, ?, ?)').run(
67
104
  slug,
@@ -89,10 +126,11 @@ export function addProject(db, rawPath, { slug: wantedSlug, aliases = [], now =
89
126
  */
90
127
  export function rescan(db, nameOrAlias, now = new Date().toISOString(), read = null) {
91
128
  const project = getProject(db, nameOrAlias);
92
- if (!existsSync(project.path)) throw new UsageError(`${project.path} no longer exists — archive the project or re-add it at its new path`);
129
+ if (!existsSync(project.path)) throw new Refusal(`${project.path} no longer exists — archive the project or re-add it at its new path`);
93
130
  const scope = `project:${project.slug}`;
94
131
  // Read off disk before the write lock is taken: a slow disk or a strange file must not hold every other writer.
95
132
  const { scanned, remote } = read ?? { scanned: scan(project.path), remote: gitRemote(project.path) };
133
+ const present = presentOf(project.path);
96
134
 
97
135
  return tx(db, () => {
98
136
  const current = new Map(
@@ -127,10 +165,36 @@ export function rescan(db, nameOrAlias, now = new Date().toISOString(), read = n
127
165
  }
128
166
 
129
167
  db.prepare('UPDATE projects SET scanned_at = ?, remote = ? WHERE slug = ?').run(now, remote, project.slug);
168
+ // Which of the files it reads were there: one made or deleted since is a change no file's time can show.
169
+ setMeta(db, presentKey(project.slug), present);
130
170
  return changes;
131
171
  });
132
172
  }
133
173
 
174
+ /** Where a project's last scan keeps which of the files it reads were there. */
175
+ const presentKey = (slug) => `scan.present.${slug}`;
176
+
177
+ /** How old a scan may get before a card is built from a new one, whatever the disk says. */
178
+ const SCAN_FRESH_MS = 7 * 24 * 3_600_000;
179
+
180
+ /**
181
+ * A project's scanned facts made current before its card is shown: rescanned when the scan is a week old or anything it
182
+ * reads changed since — a stat of each file decides, so a card shown often costs nothing. True when it rescanned. A
183
+ * project whose folder is gone is left as it is: the card says where it was, and `project rescan` says what to do.
184
+ */
185
+ export function freshen(db, slug, now = new Date().toISOString()) {
186
+ const project = db.prepare('SELECT * FROM projects WHERE slug = ?').get(slug);
187
+ if (!project || !existsSync(project.path)) return false;
188
+ const stale =
189
+ !project.scanned_at ||
190
+ Date.parse(now) - Date.parse(project.scanned_at) > SCAN_FRESH_MS ||
191
+ changedSince(project.path, project.scanned_at) ||
192
+ getMeta(db, presentKey(slug)) !== presentOf(project.path);
193
+ if (!stale) return false;
194
+ rescan(db, slug, now);
195
+ return true;
196
+ }
197
+
134
198
  export function listProjects(db, { includeArchived = false } = {}) {
135
199
  return db
136
200
  .prepare(`SELECT * FROM projects ${includeArchived ? '' : `WHERE status = 'active'`} ORDER BY COALESCE(last_touched_at, created_at) DESC`)
@@ -186,7 +250,7 @@ export function projectAt(db, dir) {
186
250
  }
187
251
 
188
252
  /** The project for work that belongs to none. It lives in Sumo's own home, and a chore in it is kept only while it is worked on. */
189
- export const SCRATCH = 'scratch';
253
+ const SCRATCH = 'scratch';
190
254
  const DAY_MS = 24 * 3_600_000;
191
255
 
192
256
  /** Scratch's directory, made if it is not there: tools start in it, so it has to be. */
@@ -199,12 +263,12 @@ export function scratchDir() {
199
263
  export const isScratch = (project) => project.path === scratchDir();
200
264
 
201
265
  /** How many days a chore nothing is written in is kept. */
202
- export const scratchDays = (db) => Number(getMeta(db, 'config.scratch.days') ?? CONFIG_DEFAULTS['scratch.days']);
266
+ export const SCRATCH_DAYS = 14;
203
267
 
204
268
  /** How scratch is used, as its card and a job's brief say it. */
205
- export const scratchRules = (db) => [
269
+ export const scratchRules = () => [
206
270
  'for work that belongs to no project: one folder per chore, named <date>-<what it is>',
207
- `a folder nothing is written in for ${scratchDays(db)} days is deleted — to keep one, move it out of here, then: sumo project add <path>`,
271
+ `a folder nothing is written in for ${SCRATCH_DAYS} days is deleted — to keep one, move it out of here, then: sumo project add <path>`,
208
272
  'nothing here is checked or remembered: say in the report what you ran to prove the work',
209
273
  ];
210
274
 
@@ -245,6 +309,6 @@ export function keepScratch(db, now) {
245
309
  ensureScratch(db, now);
246
310
  const last = getMeta(db, 'scratch.pruned');
247
311
  if (last && Date.parse(now) - Date.parse(last) < DAY_MS) return;
248
- pruneScratch(now, scratchDays(db));
312
+ pruneScratch(now, SCRATCH_DAYS);
249
313
  setMeta(db, 'scratch.pruned', now);
250
314
  }
package/src/redact.mjs CHANGED
@@ -17,6 +17,12 @@ const PATTERNS = [
17
17
  /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
18
18
  ];
19
19
 
20
+ /**
21
+ * A credential sent the HTTP way — `Authorization: Bearer <token>`, `Basic <base64>` — whatever its vendor: the scheme is
22
+ * kept, the credential goes. A token has a digit in it; a long plain word after "basic" in prose is left alone.
23
+ */
24
+ const AUTH_SCHEME = /\b(Bearer|Basic)\s+(?=[A-Za-z0-9._~+/=-]*\d)[A-Za-z0-9._~+/=-]{16,}/gi;
25
+
20
26
  // The name may be the tail of a longer one (DB_PASSWORD, GITHUB_TOKEN) and may be quoted, as a JSON key is; what follows it must be the assignment itself.
21
27
  const ASSIGNMENT = /(password|passwd|secret|token|api[_-]?key|access[_-]?key)(["']?\s*[:=]\s*)(["']?)([^\s"']{6,})\3/gi;
22
28
 
@@ -149,6 +155,10 @@ function redactReadable(text) {
149
155
  return `${head}${MARK}@`;
150
156
  });
151
157
  for (const pattern of PATTERNS) out = out.replace(pattern, hit);
158
+ out = out.replace(AUTH_SCHEME, (_m, scheme) => {
159
+ count++;
160
+ return `${scheme} ${MARK}`;
161
+ });
152
162
  out = keyFragments(out, hit);
153
163
  out = out.replace(ENV_KEY_QUOTED, (m, name, sep, _quote, value) => {
154
164
  if (value.startsWith('${')) return m;
package/src/render.mjs CHANGED
@@ -14,7 +14,8 @@ export function scopeLabel(scope) {
14
14
 
15
15
  function tags(m) {
16
16
  const parts = [TYPE_TAG[m.type], scopeLabel(m.scope), m.provenance];
17
- if (m.state !== 'active') parts.push(m.state);
17
+ // Stored as invalid; said as what the user did to it.
18
+ if (m.state !== 'active') parts.push(m.state === 'invalid' ? 'forgotten' : m.state);
18
19
  if (m.pinned) parts.push('pinned');
19
20
  return `[${parts.join('·')}]`;
20
21
  }
package/src/route.mjs CHANGED
@@ -16,8 +16,8 @@ const ROUTER_SYSTEM =
16
16
  'You assign a coding job to a model and an effort level. Answer with JSON only. First classify the job, then choose. kind: mechanical (typos, ' +
17
17
  'renames, comments, constants, tests for a pure function), routine (an ordinary feature or fix with a clear spec), hard (design, a bug whose ' +
18
18
  'cause is unknown, or reviewing risky code), novel (new algorithms, subtle concurrency, deep security review). surface: how much code the job ' +
19
- 'touches. risky: true when it touches security, credentials, money, migrations or concurrency. Model follows kind: haiku for mechanical (it ' +
20
- 'takes no effort setting), sonnet for routine, opus for hard, fable for novel. Effort follows surface: low for one spot, medium for a few ' +
19
+ 'touches. risky: true when it touches security, credentials, money, migrations or concurrency. Model follows kind: haiku for mechanical, ' +
20
+ 'sonnet for routine, opus for hard, fable for novel. Effort follows surface: low for one spot, medium for a few ' +
21
21
  'files, high for many interacting parts. risky raises the effort one step (low, medium, high, xhigh, max) and makes a routine job hard. ' +
22
22
  'History lists only the routes that failed or drew Important review findings on this project: for work like that, go above them.';
23
23
 
@@ -33,15 +33,15 @@ const SCOUT_ROUTER_SYSTEM =
33
33
  'exist, which dependencies are behind — however large or unfamiliar the project), hard (it must judge: an audit of security or ' +
34
34
  'correctness, a review, a hunt for the cause of a bug), novel (almost never: only reasoning nobody has written down, such as proving a ' +
35
35
  'concurrent algorithm correct). surface: how much code must be read. risky: true when what is judged is security, credentials, money, ' +
36
- 'migrations or concurrency. Model follows kind: haiku for mechanical (it takes no effort setting), sonnet for routine, opus for hard, ' +
36
+ 'migrations or concurrency. Model follows kind: haiku for mechanical, sonnet for routine, opus for hard, ' +
37
37
  'fable for novel. Effort follows surface: low for one spot, medium for a few files or a whole project read for a summary, high when ' +
38
38
  'many interacting parts must be judged together. risky raises the effort one step (low, medium, high, xhigh, max). ' +
39
39
  'History lists only the routes that failed or drew Important review findings on this project: for work like that, go above them.';
40
40
 
41
41
  /**
42
- * One answer shape per pairing, so the grammar itself cannot give haiku an effort or another model none.
43
- * The classification comes first: a small model that names the route first just repeats a route it was
44
- * shown, and one that has described the job first chooses from the description.
42
+ * The answer shape: the models that are on and the efforts every one of them takes. The classification comes
43
+ * first: a small model that names the route first just repeats a route it was shown, and one that has described
44
+ * the job first chooses from the description.
45
45
  */
46
46
  const answerShape = (models, efforts) => ({
47
47
  type: 'object',
@@ -56,13 +56,8 @@ const answerShape = (models, efforts) => ({
56
56
  required: ['kind', 'surface', 'risky', 'model', 'effort', 'reason'],
57
57
  additionalProperties: false,
58
58
  });
59
- /** The grammar over the models that are on: the haiku branch while haiku is, the effort branch over the others. */
60
- const routerSchema = (usable) => ({
61
- anyOf: [
62
- ...(usable.includes('haiku') ? [answerShape(['haiku'], ['none'])] : []),
63
- ...(usable.some((m) => m !== 'haiku') ? [answerShape(usable.filter((m) => m !== 'haiku'), EFFORTS)] : []),
64
- ],
65
- });
59
+ /** The grammar over the models that are on. */
60
+ const routerSchema = (usable) => answerShape(usable, EFFORTS);
66
61
 
67
62
  const TASK_CUT = 3500;
68
63
 
@@ -170,7 +165,7 @@ const CHAT_ROUTER_SYSTEM =
170
165
  'rename, running a command and reporting), routine (an ordinary feature or fix with a clear ask, a summary, an explanation), hard (design, ' +
171
166
  'a bug whose cause is unknown, a review of risky code, planning across a codebase), novel (new algorithms, subtle concurrency, deep security ' +
172
167
  'review). surface: how much code the turn touches. risky: true when it touches security, credentials, money, migrations or concurrency. ' +
173
- 'Model follows kind: haiku for mechanical (it takes no effort setting), sonnet for routine, opus for hard, fable for novel. Effort follows ' +
168
+ 'Model follows kind: haiku for mechanical, sonnet for routine, opus for hard, fable for novel. Effort follows ' +
174
169
  'surface: low for one spot, medium for a few files, high for many interacting parts. risky raises the effort one step (low, medium, high, ' +
175
170
  'xhigh, max) and makes a routine turn hard.';
176
171
 
@@ -180,7 +175,7 @@ function chatRouterPrompt(db, { project, text }) {
180
175
  }
181
176
 
182
177
  /** The smallest model a job may run on (`jobs.floor`); haiku, the cheapest, holds nothing back. */
183
- export const jobFloor = (db) => getMeta(db, 'config.jobs.floor') ?? CONFIG_DEFAULTS['jobs.floor'];
178
+ const jobFloor = (db) => getMeta(db, 'config.jobs.floor') ?? CONFIG_DEFAULTS['jobs.floor'];
184
179
 
185
180
  /** The models a job may be routed to: the ones that are on, from the floor up — or all of them, when none at or above it is on. */
186
181
  export function jobModels(db) {
@@ -198,24 +193,23 @@ async function askFor(db, system, prompt, models = usableModels(db)) {
198
193
  if (!result.ok) return { ok: false, error: result.error };
199
194
  const { model, effort, reason, risky } = result.data ?? {};
200
195
  // The same pairing the schema enforces, checked again: a backend without grammar support can still answer anything.
201
- const fits = usable.includes(model) && (model === 'haiku' ? effort === 'none' : EFFORTS.includes(effort));
196
+ const fits = usable.includes(model) && EFFORTS.includes(effort);
202
197
  if (!fits || typeof reason !== 'string' || !reason.trim()) return { ok: false, error: `the router answered outside its schema: ${JSON.stringify(result.data)}` };
203
198
  // Whether the work touches security, credentials, money, migrations or concurrency: kept, so such work is reviewed. Only a plain yes is one.
204
199
  return { ok: true, model, effort, reason: reason.replace(/\s+/g, ' ').trim(), risky: risky === true };
205
200
  }
206
201
 
207
202
  // Routes compared on one scale: by model first, cheapest to dearest as the catalog lists them, then by effort.
208
- // Haiku's 'none' sits below every effort.
203
+ // The 'none' an old job ran at, from when haiku took no effort, sits below every effort.
209
204
  const modelRank = (model) => MODELS.indexOf(model);
210
205
  const effortRank = (effort) => EFFORTS.indexOf(effort);
211
206
  const compareRoutes = (a, b) => modelRank(a.model) - modelRank(b.model) || effortRank(a.effort) - effortRank(b.effort);
212
207
 
213
- /** One step above a route: the next model up that is on, keeping the effort (medium, off haiku); on the top one, one effort up, max at most. */
208
+ /** One step above a route: the next model up that is on, keeping the effort (medium, off an old 'none'); on the top one, one effort up, max at most. */
214
209
  function stepAbove({ model, effort }, usable) {
215
210
  const next = usable.find((m) => modelRank(m) > modelRank(model));
216
211
  if (next) return { model: next, effort: EFFORTS.includes(effort) ? effort : 'medium' };
217
212
  const top = usable.at(-1);
218
- if (top === 'haiku') return { model: top, effort: 'none' };
219
213
  return { model: top, effort: EFFORTS[Math.min(effortRank(effort) + 1, EFFORTS.length - 1)] };
220
214
  }
221
215
 
@@ -225,7 +219,7 @@ function stepAbove({ model, effort }, usable) {
225
219
  * 2 of 5 at more than twice the price of opus, which finished 5 of 6. So these hold whatever it answers:
226
220
  * - A first attempt starts lower: a worker's never runs on fable while opus is on, and no first attempt runs above high effort.
227
221
  * - A scout's first attempt does not run on haiku while sonnet is on: on the ledger, haiku scouts left 3 of 11 unfinished,
228
- * sonnet and opus ones none of 9 — and haiku caches nothing below 4,096 tokens. It runs on sonnet at low effort instead.
222
+ * sonnet and opus ones none of 9 (measured on Haiku 4.5; not yet on 5.5). It runs on sonnet at low effort instead.
229
223
  * - A retry of a job that failed, or that drew RETRY_IMPORTANT_THRESHOLD Important findings, runs at least one step above it.
230
224
  * - A reviewer pointed at a job runs on at least that job's model, at medium effort or more.
231
225
  * Pure: `retryOf` and `reviews` are the rows (id, model, effort, status, important) of the job retried and the job judged,
@@ -239,7 +233,7 @@ export function routePolicy({ agent, routed, retryOf: prev, reviews: target, usa
239
233
  if (floor && modelRank(route.model) < modelRank(floor)) {
240
234
  const up = usable.find((m) => modelRank(m) >= modelRank(floor));
241
235
  if (up) {
242
- route = { model: up, effort: up === 'haiku' ? 'none' : EFFORTS.includes(route.effort) ? route.effort : 'medium' };
236
+ route = { model: up, effort: EFFORTS.includes(route.effort) ? route.effort : 'medium' };
243
237
  why.push(`jobs.floor is ${floor}`);
244
238
  }
245
239
  }
@@ -270,7 +264,7 @@ export function routePolicy({ agent, routed, retryOf: prev, reviews: target, usa
270
264
  route.model = usable.find((m) => modelRank(m) >= modelRank(target.model)) ?? usable.at(-1);
271
265
  why.push(`a reviewer is at least as strong as j${target.id}'s ${target.model}`);
272
266
  }
273
- if (route.model !== 'haiku' && effortRank(route.effort) < effortRank('medium')) {
267
+ if (effortRank(route.effort) < effortRank('medium')) {
274
268
  route.effort = 'medium';
275
269
  why.push('a reviewer runs at medium effort at least');
276
270
  }
package/src/sandbox.mjs CHANGED
@@ -21,7 +21,7 @@ const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
21
21
  const TOOL_CACHES = ['.npm', 'Library/Caches', '.cache', 'go/pkg', '.cargo/registry', '.cargo/git', 'Library/pnpm', '.bun/install/cache', '.gradle/caches', '.m2/repository'];
22
22
 
23
23
  /** What is printed for a write the sandbox refused — Codex looks for the same two — in any case: Node says `EPERM: operation not permitted`. */
24
- const BLOCKED = /operation not permitted|read-only file system/i;
24
+ const BLOCKED = /operation not permitted|read-only file system|unable to open database file|readonly database/i;
25
25
 
26
26
  /** Why the model's shell cannot be sandboxed here, or null when it can. */
27
27
  export function unsandboxable({ platform = process.platform, exec = SANDBOX_EXEC } = {}) {
@@ -32,7 +32,7 @@ export function unsandboxable({ platform = process.platform, exec = SANDBOX_EXEC
32
32
 
33
33
  const real = (path) => {
34
34
  try {
35
- return realpathSync(path);
35
+ return realpathSync.native(path);
36
36
  } catch {
37
37
  return null;
38
38
  }
@@ -100,10 +100,89 @@ function darwinUserCache() {
100
100
  * `sumo job finish`, which write there), the per-user cache macOS gives compilers, and the tool caches that exist. A
101
101
  * place that does not exist is left out.
102
102
  */
103
- export function writablePlaces(roots, { home = homedir(), tmp = tmpdir(), sumo = paths().home, userCache = darwinUserCache() } = {}) {
103
+ export function writablePlaces(roots, { home = homedir(), tmp = tmpdir(), sumo = paths().home, userCache = darwinUserCache(), opened = [] } = {}) {
104
104
  const places = [];
105
105
  for (const root of roots.map(real).filter(Boolean)) places.push(root, gitCommonDir(root));
106
106
  places.push(real(tmp), real('/private/tmp'), real(sumo), userCache && real(userCache), ...TOOL_CACHES.map((cache) => real(join(home, cache))));
107
+ // What the user opened for the session at the editor's question — a file, or a directory with everything under it — the shell may write too.
108
+ places.push(...[...opened].map(real));
109
+ return [...new Set(places.filter(Boolean))];
110
+ }
111
+
112
+ /**
113
+ * Files that something else reads later, outside the sandbox — the shell at its next start, a tool before it runs, an
114
+ * editor, a commit hook — by name: changed only when the user says so, in the project or anywhere else, and never
115
+ * opened for the session. Claude Code and Codex keep the same names. `sumo`'s own MCP file holds what may run unasked.
116
+ */
117
+ const GUARDED = {
118
+ 'your shell reads it when it starts': ['.zshrc', '.zshenv', '.zprofile', '.zlogin', '.bashrc', '.bash_profile', '.bash_login', '.profile', '.envrc'],
119
+ // Husky's hooks are the directory git's config names (`.husky/_`), kept with git's own; the rest of `.husky` is the project's.
120
+ 'a tool reads it before it runs': ['.npmrc', '.yarnrc', '.yarnrc.yml', 'bunfig.toml', '.pre-commit-config.yaml', 'lefthook.yml', '.mcp.json', '.claude', '.codex', '.agents'],
121
+ 'your editor reads it': ['.vscode', '.idea', '.devcontainer'],
122
+ // Keys and logins other programs trust: a line added to authorized_keys or a profile in .aws outlives every session.
123
+ 'it holds credentials other programs trust': ['.ssh', '.aws', '.gnupg', '.kube', '.docker', '.netrc', '.git-credentials', '.pgpass'],
124
+ };
125
+ /**
126
+ * Names that matter only in the home: a program's own setup, which runs or is read whenever that program starts. In a
127
+ * project a `bin` folder or a `.gitconfig` is the project's own.
128
+ */
129
+ const HOME_GUARDED = {
130
+ 'git reads it, and runs what it names': ['.gitconfig', '.config/git'],
131
+ 'macOS runs it when you log in': ['Library/LaunchAgents'],
132
+ 'a program there runs as a command': ['.local/bin', 'bin'],
133
+ 'a program you use reads it when it starts': ['.config/fish', '.vimrc', '.config/nvim', '.tmux.conf'],
134
+ };
135
+ const whyOf = (lists) => [...Object.entries(lists)].flatMap(([why, names]) => names.map((name) => [name.toLowerCase(), why]));
136
+ const GUARDED_WHY = whyOf(GUARDED);
137
+ const HOME_WHY = [...GUARDED_WHY, ...whyOf(HOME_GUARDED)];
138
+
139
+ /** What sumo keeps for itself, which only sumo writes: its memory and settings, its MCP servers, its own program and model. */
140
+ const SUMO_PRIVATE = ['memory.db', 'memory.db-wal', 'memory.db-shm', 'mcp.json', 'bin', 'models', 'eval.env'];
141
+
142
+ /** The directories on the PATH, absolute: a program put in one runs whenever its name is typed. */
143
+ const pathDirs = (env = process.env) => [...new Set(String(env.PATH ?? '').split(':').filter((d) => d.startsWith('/')).map((d) => resolve(d)))];
144
+
145
+ /**
146
+ * Why a path is changed only when the user says so, or null: it is, or is in, one of the guarded names directly under
147
+ * the project or the home — whichever holds it most closely, so a project kept inside `~/.claude` is its own. A
148
+ * `.vscode` deep in a package is the package's. Any repository's git directory, any folder on the PATH and sumo's own
149
+ * files are guarded wherever they are.
150
+ */
151
+ export function guardedWhy(path, { roots = [], home = homedir(), sumo = paths().home, env = process.env } = {}) {
152
+ // By name in any case: on macOS's disk `.ENVRC` is `.envrc` to whatever opens it.
153
+ const lower = path.toLowerCase();
154
+ for (const place of [sumo, real(sumo)].filter(Boolean)) {
155
+ const name = SUMO_PRIVATE.find((n) => lower === join(place, n).toLowerCase() || lower.startsWith(`${join(place, n).toLowerCase()}/`));
156
+ if (name) return name === 'mcp.json' ? 'it is the MCP allow list, which says what may run unasked' : 'it is sumo\'s own: its memory, settings or program';
157
+ }
158
+ const homes = new Set([home, real(home)].filter(Boolean));
159
+ const bases = [...new Set([...roots, home].flatMap((base) => [base, real(base)]).filter(Boolean))].sort((a, b) => b.length - a.length);
160
+ const base = bases.find((b) => path.startsWith(`${b}/`));
161
+ if (base) {
162
+ const rel = path.slice(base.length + 1).toLowerCase();
163
+ const named = (homes.has(base) ? HOME_WHY : GUARDED_WHY).find(([name]) => rel === name || rel.startsWith(`${name}/`));
164
+ if (named) return named[1];
165
+ }
166
+ // Any repository's git directory, not only the project's: its hooks run outside the sandbox on the next commit there.
167
+ if (lower.split('/').includes('.git')) return 'git runs what is in it, outside the sandbox';
168
+ const dirs = pathDirs(env);
169
+ return dirs.includes(dirname(path)) || dirs.some((d) => real(d) === dirname(path)) ? 'it is on your PATH: a program there runs as a command' : null;
170
+ }
171
+
172
+ /**
173
+ * What the shell may not write inside the places it may: the guarded files that are there, in each root and the home;
174
+ * sumo's own files by name, there or not (`mcp.json` made by the shell would be read as servers allowed to run); and
175
+ * the PATH's folders outside the project. Kept read-only as git's hooks are.
176
+ */
177
+ export function guardedPlaces(roots, { home = homedir(), sumo = paths().home, env = process.env } = {}) {
178
+ const places = [];
179
+ for (const dir of roots) places.push(...Object.values(GUARDED).flat().map((name) => real(join(dir, name))));
180
+ places.push(...[...Object.values(GUARDED), ...Object.values(HOME_GUARDED)].flat().map((name) => real(join(home, name))));
181
+ const own = real(sumo) ?? sumo;
182
+ places.push(...SUMO_PRIVATE.map((name) => join(own, name)));
183
+ // A PATH folder in a project is the project's; one above a project would make all of it read-only.
184
+ const inRoot = (d) => roots.map(real).filter(Boolean).some((r) => d === r || d.startsWith(`${r}/`) || r.startsWith(`${d}/`));
185
+ places.push(...pathDirs(env).map(real).filter((d) => d && !inRoot(d)));
107
186
  return [...new Set(places.filter(Boolean))];
108
187
  }
109
188
 
package/src/scan.mjs CHANGED
@@ -99,7 +99,7 @@ function recipe(makefile, target) {
99
99
  * project itself says what a command runs — a script, a recipe — that is its
100
100
  * `definition`, so a job that rewrites it can be told apart from one that does not.
101
101
  */
102
- export function projectCommands(root, pkg = readJson(root, 'package.json')) {
102
+ function projectCommands(root, pkg = readJson(root, 'package.json')) {
103
103
  const found = [];
104
104
  if (pkg?.scripts) {
105
105
  const pm = nodePackageManager(root);
@@ -188,6 +188,40 @@ function ci(root) {
188
188
  }
189
189
  }
190
190
 
191
+ /**
192
+ * Everything a scan reads, by its place in the repository: a file here changed, appeared or went away, and a fact may
193
+ * have too. The directories are in it for what is made or deleted in them — a README added, a CLAUDE.md removed.
194
+ */
195
+ /**
196
+ * The files and folders a scan reads. Not the project folder itself: its time moves with every swap file, .DS_Store and
197
+ * save-by-rename. A scanned file made or deleted is told by `presentOf` instead.
198
+ */
199
+ const READS = [
200
+ '.claude', join('.github', 'workflows'),
201
+ 'package.json', 'tsconfig.json', 'bun.lock', 'bun.lockb', 'pnpm-lock.yaml', 'yarn.lock', 'pnpm-workspace.yaml',
202
+ 'pyproject.toml', 'requirements.txt', 'uv.lock', 'poetry.lock', 'go.mod', 'Cargo.toml', 'Gemfile', 'pom.xml',
203
+ 'build.gradle', 'build.gradle.kts', 'Package.swift', 'Makefile', 'README.md', 'readme.md', 'README', 'README.rst',
204
+ 'AGENTS.md', 'CLAUDE.md', join('.claude', 'CLAUDE.md'),
205
+ ];
206
+
207
+ /** Which of the files and folders a scan reads are there, as one string to keep beside the scan and compare with later. */
208
+ export function presentOf(root) {
209
+ return READS.filter((name) => existsSync(join(root, name))).join('\n');
210
+ }
211
+
212
+ /** Whether anything a scan reads changed after `since` (an ISO time): a stat of each, never a read. */
213
+ export function changedSince(root, since) {
214
+ const at = Date.parse(since);
215
+ if (!Number.isFinite(at)) return true;
216
+ return READS.some((name) => {
217
+ try {
218
+ return statSync(join(root, name)).mtimeMs > at;
219
+ } catch {
220
+ return false;
221
+ }
222
+ });
223
+ }
224
+
191
225
  /** Facts in the order the project card should show them. A key with nothing to say is simply absent. */
192
226
  export function scan(root) {
193
227
  const pkg = readJson(root, 'package.json');
package/src/scribe.mjs CHANGED
@@ -3,11 +3,10 @@ import { appendFileSync, closeSync, openSync, readFileSync, rmSync, statSync, wr
3
3
  import { join } from 'node:path';
4
4
  import { applyOps } from './apply.mjs';
5
5
  import { resolveAnthropicCredential } from './auth.mjs';
6
- import { ago } from './card.mjs';
7
6
  import { MODELS, offLine, usableModels } from './catalog.mjs';
8
7
  import { getMeta, openDb, setMeta, tx } from './db.mjs';
9
- import { localServerStatus } from './local-server.mjs';
10
8
  import { callModel, failure, logRun } from './model.mjs';
9
+ import { appendLog } from './logs.mjs';
11
10
  import { paths, REPO_ROOT, SELF } from './paths.mjs';
12
11
  import { aliasesOf, listProjects } from './projects.mjs';
13
12
  import { line } from './render.mjs';
@@ -135,7 +134,7 @@ export async function withLock(name, fn) {
135
134
  }
136
135
  }
137
136
 
138
- export function projectEnum(db) {
137
+ function projectEnum(db) {
139
138
  return listProjects(db, { includeArchived: true }).map((p) => p.slug);
140
139
  }
141
140
 
@@ -173,6 +172,7 @@ export function opsSchema(db, ops) {
173
172
  ? branch('checkpoint', { project: { type: 'string', enum: slugs }, done: { type: 'string' }, next: { type: ['string', 'null'] } })
174
173
  : null,
175
174
  contradiction: branch('contradiction', { ids: { type: 'array', items: { type: 'integer' } }, note: { type: 'string' } }),
175
+ same: branch('same', { ids: { type: 'array', items: { type: 'integer' } }, note: { type: 'string' } }),
176
176
  procedure: branch('procedure', { scope: field.scope, title: { type: 'string' }, cue: { type: 'string' }, body: field.body }),
177
177
  };
178
178
  return {
@@ -243,11 +243,12 @@ const fallbackModel = (db) => usableModels(db)[0] ?? null;
243
243
 
244
244
  /** Shared by the writer and the consolidation pass: ask, validate, record what it cost. */
245
245
  export async function askAndApply(db, { kind, promptFile, bundle, ops, sessionId, now }) {
246
- let model = getMeta(db, `config.${kind}.model`) ?? CONFIG_DEFAULTS[`${kind}.model`];
246
+ // One setting for the whole memory pass, filing and tidying alike.
247
+ let model = getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model'];
247
248
  const system = readFileSync(join(REPO_ROOT, 'prompts', promptFile), 'utf8').trim();
248
249
  const schema = opsSchema(db, ops);
249
250
  // A writer set to a model the user has since turned off is not called: the refusal is the pass's failure, in the ledger like any other.
250
- const off = MODELS.includes(model) ? offLine(db, model, `sumo config ${kind}.model local`) : null;
251
+ const off = MODELS.includes(model) ? offLine(db, model, 'sumo config memory.model local') : null;
251
252
  let result = off ? failure(off) : await callModel(db, { system, prompt: bundle.prompt, schema, model, kind });
252
253
  // A local answer that failed (server down, bundle past its context, answer cut off) is one failed row, then one more try —
253
254
  // when a credential is there to pay for it and a model is on to take it.
@@ -268,21 +269,21 @@ export async function askAndApply(db, { kind, promptFile, bundle, ops, sessionId
268
269
  logRun(db, { kind, model, result: { ...result, ok: false }, note: error, now });
269
270
  return { ok: false, error, applied: [], dropped: [], usage: result.usage };
270
271
  }
271
- const outcome = applyOps(db, result.data.ops, { source: kind, turns: bundle.turns, sessionId, now });
272
+ const outcome = applyOps(db, result.data.ops, { source: kind, turns: bundle.turns, shown: bundle.shown, sessionId, now });
272
273
  logRun(db, { kind, model, result, note: `applied=${outcome.applied.length} dropped=${outcome.dropped.length}`, now });
273
- for (const reason of outcome.dropped) appendFileSync(join(paths().logs, 'scribe.log'), `${now} dropped — ${reason}\n`);
274
+ for (const reason of outcome.dropped) appendLog('scribe.log', `${now} dropped — ${reason}\n`);
274
275
  return { ok: true, error: null, ...outcome, usage: result.usage };
275
276
  }
276
277
 
277
278
  /** Whether the user turned the writer off: nothing gets filed, so nothing should wait for it to be. */
278
- export const writerOff = (db) => (getMeta(db, 'config.scribe.model') ?? CONFIG_DEFAULTS['scribe.model']) === 'off';
279
+ export const writerOff = (db) => (getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model']) === 'off';
279
280
 
280
281
  /**
281
282
  * Files what was said since the last run. Turns are marked done only after the
282
283
  * answer was applied, so a failed call costs nothing but a retry.
283
284
  */
284
285
  export async function runScribe(db, { now = new Date().toISOString() } = {}) {
285
- if (writerOff(db)) return { skipped: 'scribe.model is off' };
286
+ if (writerOff(db)) return { skipped: 'memory.model is off' };
286
287
 
287
288
  return withLock('scribe', async () => {
288
289
  const bundle = buildBundle(db);
@@ -306,19 +307,6 @@ export async function runScribe(db, { now = new Date().toISOString() } = {}) {
306
307
  });
307
308
  }
308
309
 
309
- export async function scribeStatus(db) {
310
- const failures = Number(getMeta(db, 'scribe.failures') ?? 0);
311
- const last = getMeta(db, 'scribe.last_run');
312
- const model = getMeta(db, 'config.scribe.model') ?? CONFIG_DEFAULTS['scribe.model'];
313
- return [
314
- `model: ${model}`,
315
- ...(model === 'local' ? [await localServerStatus(db, { file: getMeta(db, 'config.model.file') ?? CONFIG_DEFAULTS['model.file'] })] : []),
316
- `turns waiting: ${pendingTurns(db, 1000).length}`,
317
- `last run: ${last ? `${last} (${ago(last, new Date().toISOString())})` : 'never'}`,
318
- failures > 0 ? `failing: ${failures} in a row — ${getMeta(db, 'scribe.last_error')}` : 'healthy',
319
- ];
320
- }
321
-
322
310
  export function modelStats(db) {
323
311
  const rows = db
324
312
  .prepare(