agentbox-app 0.1.6

package/main/git-change.mjs

@@ -0,0 +1,323 @@
+// WHAT ACTUALLY MOVED ON THE DISK, READ OUT OF THE REPOSITORY.
+//
+// THE HOLE. main/code-change.mjs builds a run's change out of the agent's own
+// conversation, which only carries the before and after when the agent used
+// the Edit or Write tool. Measured on this Mac 2026-08-24: of 105 runs that
+// changed a file over two days, 4 would have shown the whole change. The other
+// 101 rewrote their files with sed, a heredoc or a script, and a card drawn
+// from the conversation has nothing in it. That is what David was clicking.
+//
+// SO THE CARD STOPS ASKING HOW THE AGENT TYPED. A run's checkout is
+// photographed when the session spawns and read again when it exits, and the
+// difference between the two is the change. It catches every route in, because
+// it never asks which one was taken.
+//
+// WHY THE CONVERSATION IS STILL READ AND NOT REPLACED. Three reasons, all
+// real: a product with no repository (most of her twenty-eight) has nothing
+// here to read; the product's own docs folder is not a checkout and that is
+// where the reports and drawings a run makes for her live; and the agent's
+// sentence beside a hunk only exists in the conversation. So git fills the
+// code and the transcript fills the words, and where git has a file the
+// transcript also has, git wins: it is the disk.
+//
+// WHAT IT STILL CANNOT DO, said plainly because the next session will wonder.
+// In a checkout two agents share, a file the other one wrote inside this run's
+// window is inside this run's window, and no reading of the disk can tell them
+// apart. Most workers get their own worktree, where this does not arise.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Bigger than this is not a file anybody reads a diff of. */
+const BIG_FILE = 512 * 1024;
+
+/** How much already-changed work we copy at spawn before giving up on it. */
+const COPY_BUDGET = 16 * 1024 * 1024;
+
+/** Rows one file may contribute before the rest is left out and said so. */
+const MAX_ROWS_PER_FILE = 20_000;
+
+/** The store's own bookkeeping, which git would not offer anyway. */
+const NOT_CODE = /(^|\/)(node_modules|\.git)\//;
+
+function git(cwd, args, { maxBuffer = 64 * 1024 * 1024 } = {}) {
+  return execFileSync('git', ['--no-pager', ...args], {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+function tryGit(cwd, args, opts) {
+  try { return git(cwd, args, opts); } catch { return null; }
+}
+
+/** Split a -z list, dropping the empty tail. */
+function zList(out) {
+  return String(out ?? '').split('\0').filter(Boolean);
+}
+
+/** Text we would draw. A NUL in the first block means a picture or a binary. */
+function readTextFile(file) {
+  let stat;
+  try { stat = fs.statSync(file); } catch { return null; }
+  if (!stat.isFile() || stat.size > BIG_FILE) return null;
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  if (text.includes('\0')) return null;
+  return text;
+}
+
+/**
+ * The checkout as it stands, kept so the same checkout can be read again when
+ * the run ends.
+ *
+ * Cheap on purpose, because it runs on the spawn path of every worker: two
+ * git commands that list names, and a copy of only those files that were
+ * already changed before the run started. In a worker's own fresh worktree
+ * that last set is empty. Measured on her main checkout, which is the worst
+ * case she has: 199 untracked files, 4 already changed, 0.02s.
+ *
+ * Returns null when the directory is not a repository at all, which is the
+ * ordinary case for a product with no code, and the caller carries on with
+ * the conversation alone.
+ */
+export function snapshotRepo(cwd) {
+  if (!cwd) return null;
+  const root = tryGit(cwd, ['rev-parse', '--show-toplevel'])?.trim();
+  if (!root) return null;
+  const head = tryGit(root, ['rev-parse', 'HEAD'])?.trim() || null;
+
+  // Everything that was ALREADY different from HEAD when we arrived, plus
+  // everything untracked. Their contents are the only thing we have to keep,
+  // because for every other file the start state is the commit.
+  const dirty = head ? zList(tryGit(root, ['diff', '--name-only', '-z', 'HEAD'])) : [];
+  const others = zList(tryGit(root, ['ls-files', '-z', '--others', '--exclude-standard']));
+
+  const before = new Map();
+  let kept = 0;
+  for (const rel of new Set([...dirty, ...others])) {
+    if (NOT_CODE.test(rel)) continue;
+    const text = readTextFile(path.join(root, rel));
+    // A file that is missing, binary or huge is remembered as unreadable
+    // rather than as empty: calling it empty would draw the whole of it green
+    // at the end as if this run had written it.
+    if (text === null) { before.set(rel, null); continue; }
+    if (kept + text.length > COPY_BUDGET) { before.set(rel, null); continue; }
+    kept += text.length;
+    before.set(rel, text);
+  }
+  return { root, head, before, at: Date.now() };
+}
+
+/**
+ * WHERE A HUNK STARTS IN EACH FILE, off its `@@` header —.
+ *
+ * Measured while looking into that: the pane had no line numbers at all, and
+ * the reason is that this parser matched `@@` only to know a hunk had started
+ * and threw the header away, numbers included. They were always right there.
+ *
+ * `@@ -12,7 +14,9 @@ some context` means the old file's run starts at line 12
+ * and the new file's at 14. The counts after the commas are how many lines each
+ * run covers and are not needed: walking the body gives the same answer and
+ * cannot disagree with the rows actually drawn.
+ */
+function hunkStarts(header) {
+  const m = /^@@+ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(String(header ?? ''));
+  return m ? { old: Number(m[1]), now: Number(m[2]) } : null;
+}
+
+/**
+ * One line of a change, the shape renderer/src/code-artifact.ts draws, and the
+ * line number each one had in each file.
+ *
+ * `nums` runs parallel to `rows`, one `[old, now]` per row, with null on the
+ * side a row does not exist in: a removed line has no number in the new file
+ * and an added one has none in the old. It is a SECOND array rather than a
+ * third slot on the row because `Row` is `['=' | '+' | '-', string]` in six
+ * other files and their tests, and widening it to carry a number that only
+ * git can supply would touch every one of them to no purpose.
+ *
+ * With no header there are no numbers, and that is left honest rather than
+ * guessed: `nums` comes back null and the pane draws the gutter empty.
+ */
+function rowsFromPatchBody(body, starts) {
+  const rows = [];
+  const nums = starts ? [] : null;
+  let old = starts?.old ?? 0;
+  let now = starts?.now ?? 0;
+  for (const line of body) {
+    const mark = line[0];
+    if (mark === '\\') continue; // ""
+    if (mark === '+') { rows.push(['+', line.slice(1)]); nums?.push([null, now++]); }
+    else if (mark === '-') { rows.push(['-', line.slice(1)]); nums?.push([old++, null]); }
+    else if (mark === ' ') { rows.push(['=', line.slice(1)]); nums?.push([old++, now++]); }
+  }
+  return { rows, nums };
+}
+
+/**
+ * A unified diff as files and hunks.
+ *
+ * Git's own diff rather than our line matcher, because a whole file read off
+ * the disk is thousands of lines and the matcher in code-change.mjs gives up
+ * over four million cells, which a 3,000 line file crosses on its own. Git
+ * also brings the three lines of context that make a save able to find its
+ * place again (renderer/src/code-edit.ts).
+ */
+export function filesFromPatch(patch) {
+  const out = new Map();
+  let file = null;
+  let oldName = null;
+  let hunk = null;
+  // The `@@` line for the hunk being collected, kept until its body is closed.
+  let starts = null;
+  const closeHunk = () => {
+    if (!file || !hunk) return;
+    const { rows, nums } = rowsFromPatchBody(hunk, starts);
+    hunk = null;
+    starts = null;
+    const plus = rows.filter((r) => r[0] === '+').length;
+    const minus = rows.filter((r) => r[0] === '-').length;
+    if (!plus && !minus) return;
+    file.hunks.push(nums ? { rows, nums, plus, minus } : { rows, plus, minus });
+    file.plus += plus;
+    file.minus += minus;
+  };
+  const nameOn = (line, side) => {
+    const name = line.slice(4).trim();
+    if (name === '/dev/null') return null;
+    return name.replace(side === 'old' ? /^a\// : /^b\//, '');
+  };
+  for (const line of String(patch ?? '').split('\n')) {
+    if (line.startsWith('diff --git ')) { closeHunk(); file = null; oldName = null; continue; }
+    if (line.startsWith('--- ')) { closeHunk(); oldName = nameOn(line, 'old'); file = null; continue; }
+    if (line.startsWith('+++ ')) {
+      // A delete has no new name, so it is filed under the old one. A rename
+      // is filed under the new one, which is where it now is on the disk.
+      const rel = nameOn(line, 'new') ?? oldName;
+      file = null;
+      if (rel && !NOT_CODE.test(rel)) {
+        file = out.get(rel) ?? { path: rel, hunks: [], plus: 0, minus: 0 };
+        out.set(rel, file);
+      }
+      continue;
+    }
+    if (line.startsWith('@@')) { closeHunk(); hunk = file ? [] : null; starts = file ? hunkStarts(line) : null; continue; }
+    if (hunk) hunk.push(line);
+  }
+  closeHunk();
+  // A file git listed but whose whole diff was binary says nothing here.
+  return [...out.values()].filter((f) => f.hunks.length);
+}
+
+/** A file that was not there before: every line of it, green. */
+function wholeFileRows(text) {
+  const parts = String(text).split('\n');
+  if (parts.length > 1 && parts[parts.length - 1] === '') parts.pop();
+  return parts.map((l) => ['+', l]);
+}
+
+/** Two texts, diffed by git without either of them being in a repository. */
+function patchBetweenTexts(before, after) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'zero-diff-'));
+  try {
+    const a = path.join(dir, 'before');
+    const b = path.join(dir, 'after');
+    fs.writeFileSync(a, before);
+    fs.writeFileSync(b, after);
+    // --no-index exits 1 when the files differ, which is the whole point, so
+    // the non-zero exit is the success case and is read off the error.
+    try {
+      return git(dir, ['diff', '--no-color', '--no-ext-diff', '--no-index', '-U3', '--', a, b]);
+    } catch (e) {
+      return String(e?.stdout ?? '');
+    }
+  } finally {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+/**
+ * What this run changed in this checkout, read off the disk.
+ *
+ * Three sources, because a checkout has three kinds of file in it and the
+ * start state of each is somewhere different:
+ *
+ * - Tracked and untouched at spawn: the commit we were on is the before, so
+ *   one `git diff` against it says everything, committed work included.
+ * - Already changed at spawn: the copy we kept is the before, because the
+ *   commit would credit this run with somebody else's unfinished work.
+ * - Written by this run and never tracked: there is no before, so the file is
+ *   every line green.
+ */
+export function changeFromRepo(snapshot) {
+  if (!snapshot?.root) return { files: [], plus: 0, minus: 0, root: snapshot?.root ?? null };
+  const { root, head, before } = snapshot;
+  const files = new Map();
+  const add = (file) => {
+    if (!file.hunks.length) return;
+    if (file.hunks.length && file.plus + file.minus > MAX_ROWS_PER_FILE) {
+      // Kept honest rather than kept whole: a generated file can be tens of
+      // thousands of lines and nobody reads past the first screen anyway.
+      let rows = 0;
+      const keep = [];
+      for (const h of file.hunks) {
+        if (rows >= MAX_ROWS_PER_FILE) break;
+        keep.push(h);
+        rows += h.rows.length;
+      }
+      file.leftOut = file.hunks.length - keep.length;
+      file.hunks = keep;
+    }
+    files.set(file.path, file);
+  };
+
+  // 1. Everything tracked, against the commit the run started on. The files
+  //    we kept a copy of are cut out here and done properly below.
+  if (head) {
+    const excludes = [...before.keys()].map((rel) => `:(exclude,literal)${rel}`);
+    const patch = tryGit(root, [
+      'diff', '--no-color', '--no-ext-diff', '-U3', '-M', head, '--', '.', ...excludes,
+    ]);
+    for (const file of filesFromPatch(patch ?? '')) add(file);
+  }
+
+  // 2. The files that were already changed when we arrived.
+  for (const [rel, kept] of before) {
+    if (kept === null) continue; // unreadable at spawn; we cannot honestly diff it
+    const now = readTextFile(path.join(root, rel));
+    const after = now === null ? '' : now;
+    if (after === kept) continue;
+    for (const file of filesFromPatch(patchBetweenTexts(kept, after))) {
+      add({ ...file, path: rel });
+    }
+  }
+
+  // 3. Files this run made that git has never tracked.
+  for (const rel of zList(tryGit(root, ['ls-files', '-z', '--others', '--exclude-standard']))) {
+    if (before.has(rel) || files.has(rel) || NOT_CODE.test(rel)) continue;
+    const text = readTextFile(path.join(root, rel));
+    if (text === null || !text.length) continue;
+    const rows = wholeFileRows(text);
+    // A FILE NOBODY HAS SEEN BEFORE NUMBERS ITSELF. Every row is an addition
+    // and the file starts at line 1, so there is nothing to parse and no reason
+    // to leave this the one place in the pane with an empty gutter.
+    const nums = rows.map((_, i) => [null, i + 1]);
+    add({ path: rel, hunks: [{ rows, nums, plus: rows.length, minus: 0 }], plus: rows.length, minus: 0 });
+  }
+
+  const out = [...files.values()];
+  return {
+    files: out,
+    plus: out.reduce((n, f) => n + f.plus, 0),
+    minus: out.reduce((n, f) => n + f.minus, 0),
+    root,
+    // When the photograph was taken, which is the run's own start and the only
+    // honest answer to "how long did this take" for a run whose conversation
+    // carried no edits at all.
+    at: snapshot.at,
+  };
+}

package/main/img-scheme.mjs

@@ -0,0 +1,90 @@
+// THE ORIGIN A PICTURE IN THE APP'S OWN WINDOW IS LOADED FROM.
+//
+// WHY, MEASURED RATHER THAN GUESSED. A pasted screenshot goes to disk the
+// moment it is pasted, so the thumbnail beside the reply box stopped carrying
+// bytes and started carrying a path, drawn as `<img
+// src="file:///…/.staging/…png">`. Her Agentbox runs from the dev server —
+// `ZERO_DEV_URL=http://localhost:5199` on the process that was up when this was
+// written — and an http page may not touch file://. The same probe, same
+// picture, same window settings, two origins:
+//
+//   page at file:///…            naturalWidth 788
+//   page at http://127.0.0.1/…   naturalWidth 0
+//     console: "Not allowed to load local resource: file:///…"
+//
+// So every pasted thumbnail is a broken image in a dev-served window, and so is
+// every screenshot a worker put in a message, because `ArtifactImg` in
+// `Focus.tsx` builds file:// urls too. A packaged app is loaded with loadFile
+// and does not hit it, which is why it survived so long: the app she uses all
+// day is the one build that cannot draw its own pictures.
+//
+// THE FIX IS AN ORIGIN, NOT A FLAG. Turning webSecurity off would fix it and
+// would also let any page in this window read the disk, which is not a trade
+// worth making for a thumbnail. Instead the renderer asks for pictures on a
+// scheme of the app's own, registered standard and secure, and this decides
+// what may come back. Same shape as main/doc-scheme.mjs, and deliberately NOT
+// the same scheme: that one serves whole documents an agent wrote, under grants
+// the pane opens one at a time, and this one serves her pictures wherever they
+// sit. Two answers to two different questions.
+//
+// WHAT MAY BE SERVED, and it is two rules that both have to pass:
+//
+//   1. It is a picture. An extension off the list below, nothing else. A url is
+//      the only thing between a page and the disk, so a scheme that can hand
+//      out any file is a scheme that can hand out `zero.config.json`.
+//   2. It is inside a root the app owns: the account root (which holds every
+//      product's docs, its attachments, its designs and the `.staging` folder a
+//      paste lands in) or a product's own code repo, which is where a worker
+//      writes `shots/…` and then names it on a card.
+import path from 'node:path';
+import { IMG_SCHEME, IMG_SCHEMES, isScheme } from '../shared/schemes.mjs';
+
+// The name is read rather than typed, and every spelling this app has used is
+// still answered: a product's logo is kept in the store as a url on this
+// scheme. shared/schemes.mjs carries that argument in full.
+export { IMG_SCHEME, IMG_SCHEMES };
+
+// One host, so every picture in the window shares one origin. Same reason
+// doc-scheme keeps one: a page and the picture beside it must never look
+// cross-origin to each other.
+export const IMG_HOST = 'file';
+
+const PICTURES = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.bmp', '.ico']);
+
+/** The url the renderer draws, for a picture already resolved on disk. */
+export function imgUrl(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) return null;
+  // Segment by segment: encodeURIComponent would eat the separators, and
+  // encodeURI would leave '#' and '?' in a filename to be read as url syntax.
+  const parts = file.split('/').filter(Boolean).map(encodeURIComponent);
+  return `${IMG_SCHEME}://${IMG_HOST}/${parts.join('/')}`;
+}
+
+/** The file a request under this scheme is asking for, or null if it is not one. */
+export function imgPath(url) {
+  let parsed;
+  try { parsed = new URL(String(url)); } catch { return null; }
+  if (!isScheme(IMG_SCHEMES, parsed.protocol)) return null;
+  let file;
+  try { file = decodeURIComponent(parsed.pathname); } catch { return null; }
+  if (!file.startsWith('/')) return null;
+  // A climb written into the url is normalised away here rather than trusted to
+  // the root check below.
+  const normal = path.normalize(file);
+  return path.isAbsolute(normal) ? normal : null;
+}
+
+/** Is `file` inside `dir`, without /a/bc counting as inside /a/b. */
+function inside(dir, file) {
+  if (!dir || !file) return false;
+  const d = path.resolve(dir);
+  const f = path.resolve(file);
+  return f === d || f.startsWith(d + path.sep);
+}
+
+/** Is this a picture the window is allowed to draw? Pure, so it is testable. */
+export function servable(file, roots) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) return false;
+  if (!PICTURES.has(path.extname(file).toLowerCase())) return false;
+  return (roots ?? []).some((root) => inside(root, file));
+}

package/main/instruction-settings.mjs

@@ -0,0 +1,205 @@
+// A fixed allowlist exposes the instruction files, never arbitrary paths.
+// Defaults are shipped separately so an edited live file can always be reset.
+//
+// THERE ARE THREE OF THEM NOW, NOT FOUR (w-3dc46f3a67, 2026-09-22). Hers, on
+// being shown the five prompts a person could edit: "Those five layers of
+// prompts that the user can adjust might be overkill. Maybe we decide not to
+// expose some of them, or maybe we would best aggregate others."
+//
+// A person opening that page is answering two questions, what should agents do
+// and how should they talk to me, so the writing rules and the finishing rules
+// became ONE document: `message-rules.md`, "How agents write to you". The
+// evidence they were one thing all along is her own rules file, where three of
+// four paragraphs are about how agents write to her rather than what they do.
+// `joinMessageRules` below carries the two old files into the new one.
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+// Every line this file prints is prefixed with the app's own name, read from the
+// one place that holds it. Typing it here is what left three dead names in the
+// code through two renames (tests/the-app-is-named-in-one-place).
+import {nameSlug} from '../shared/product-name.mjs';
+// ADHD MODE IS A FOURTH FILE, NOT A PARAGRAPH INSIDE THE THIRD (w-5737fe67cf,
+// 2026-09-25). Hers: "it should really just append that text to your content if
+// you have ADHD mode on, and then remove it when you turn it off... Maybe it
+// opens a new section with additional instructions that get applied." Kept in
+// its own file so her edits to it never mix with her own rules, and survive
+// while the mode is off. Whether it is on lives in her config (`adhdMode`).
+const files = {rules:'founder.md',messages:'message-rules.md',adhd:'adhd-mode.md',system:'worker.md'};
+// The two names the joined document replaced, read only by the migration.
+const WAS_MESSAGES = ['writing-rules.md','finishing.md'];
+const defaults = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../shared/instruction-defaults.json',import.meta.url)),'utf8'));
+function fileFor(id) {
+ if (!Object.hasOwn(files,id)) throw new Error('Unknown instruction section');
+ return files[id];
+}
+export function readInstruction(appDir,id,shippedDir=appDir) {
+ const file=fileFor(id);
+ const defaultText=id==='rules' ? '' : defaults[id];
+ let text=defaultText;
+ try {text=fs.readFileSync(path.join(appDir,'briefs',file),'utf8');} catch(e) {if(e.code!=='ENOENT') throw e; if(id==='system') text=readSystemTemplate(shippedDir,appDir);}
+ return {text,defaultText};
+}
+/**
+ * RESTORE POINTS, BECAUSE A SAVE USED TO BE THE END OF THE OLD TEXT
+ * (w-94b3af4e70, 2026-09-28).
+ *
+ * Hers, on why the page needs this at all: "a user might change the agent
+ * instructions and lose some critical information to the point where maybe the
+ * app doesn't work the way they want it or they think, 'It worked better
+ * before. I want to restore it.'"
+ *
+ * Until this, the only thing the page could hand back was our shipped text, and
+ * on her Mac that means deleting about 21,000 characters of her own writing to
+ * recover 5,654 of ours. The box saves 400ms after a keystroke, straight over
+ * the file, so a paragraph deleted at noon was gone at noon.
+ *
+ * WHAT COUNTS AS A VERSION: the text that was in the file before a save, kept
+ * under the time that text was itself saved, so the list reads as the versions
+ * she wrote rather than as a log of keystrokes. A burst of typing is one
+ * version and not two hundred, because text that has been sitting untouched for
+ * less than QUIET_MS is still being written and is not a place to come back to.
+ *
+ * It never throws into a save. Losing a restore point is a small thing and
+ * failing to write what she just typed is not.
+ */
+const HISTORY='instruction-history';
+const KEEP=20;
+const QUIET_MS=10*60*1000;
+function historyDir(appDir,id) {return path.join(appDir,HISTORY,id);}
+export function listVersions(appDir,id) {
+ fileFor(id);
+ const dir=historyDir(appDir,id);
+ let names;
+ try {names=fs.readdirSync(dir);} catch(e) {if(e.code!=='ENOENT') throw e; return [];}
+ return names.filter(n=>n.endsWith('.md')).map(n=>{
+  const ts=Number(n.slice(0,-3));
+  if(!Number.isFinite(ts)) return null;
+  try {return {ts,chars:fs.readFileSync(path.join(dir,n),'utf8').length};} catch {return null;}
+ }).filter(Boolean).sort((a,b)=>b.ts-a.ts);
+}
+export function readVersion(appDir,id,ts) {
+ fileFor(id);
+ const at=Number(ts);
+ if(!Number.isFinite(at)) throw new Error('Unknown version');
+ return {text:fs.readFileSync(path.join(historyDir(appDir,id),`${at}.md`),'utf8')};
+}
+function keepVersion(appDir,id,now=Date.now()) {
+ try {
+  const live=path.join(appDir,'briefs',fileFor(id));
+  let stat,text;
+  try {stat=fs.statSync(live); text=fs.readFileSync(live,'utf8');}
+  catch(e) {if(e.code!=='ENOENT') throw e; return;}
+  if(now-stat.mtimeMs<QUIET_MS) return;
+  const ts=Math.floor(stat.mtimeMs);
+  const have=listVersions(appDir,id);
+  if(have.some(v=>v.ts===ts)) return;
+  if(have.length && readVersion(appDir,id,have[0].ts).text===text) return;
+  const dir=historyDir(appDir,id);
+  fs.mkdirSync(dir,{recursive:true});
+  fs.writeFileSync(path.join(dir,`${ts}.md`),text,'utf8');
+  for(const old of [{ts},...have].sort((a,b)=>b.ts-a.ts).slice(KEEP)) fs.rmSync(path.join(dir,`${old.ts}.md`),{force:true});
+ } catch(e) {console.warn(`${nameSlug}: could not keep a restore point for ${id}: ${e.message}`);}
+}
+export function writeInstruction(appDir,id,text,now=Date.now()) {
+ const file=fileFor(id);
+ if(typeof text!=='string') throw new Error('Instructions must be text');
+ keepVersion(appDir,id,now);
+ const target=path.join(appDir,'briefs',file);
+ fs.mkdirSync(path.dirname(target),{recursive:true});
+ const temporary=`${target}.tmp-${process.pid}`;
+ fs.writeFileSync(temporary,text,'utf8');
+ fs.renameSync(temporary,target);
+ return {ok:true};
+}
+
+// Installed bundles are read-only. User templates shadow the shipped brief.
+export function readSystemTemplate(appDir,dataDir=appDir) {
+ for(const root of new Set([dataDir,appDir])) {
+  try {return fs.readFileSync(path.join(root,'briefs','worker.md'),'utf8');}
+  catch(e) {if(e.code!=='ENOENT') throw e;}
+ }
+ return defaults.system;
+}
+
+/**
+ * HER OWN WRITING, CARRIED OUT OF THE CHECKOUT ONCE (w-3dc46f3a67, 2026-09-21).
+ *
+ * Until this ran, the four boxes in Settings read and wrote `dataDir/briefs`,
+ * and running from source `dataDir` is the git checkout the whole fleet works
+ * in. Measured on her repo that day: briefs/founder.md had four commits, all of
+ * them an agent's, and the working copy matched the newest exactly. Her rules
+ * were being kept in the one folder every worker is allowed to `git checkout`.
+ *
+ * WHAT MOVES IS ONLY WHAT SHE WROTE, and the test for that is the shipped
+ * default. A file whose text IS the default is our file sitting where we put
+ * it, and copying it into her folder would freeze it there: the next release's
+ * worker brief would never reach her, because her "edit" would shadow it
+ * forever. So a file is carried across only when it differs from the default,
+ * which on her Mac is founder.md and writing-rules.md and neither of the two we
+ * ship. Those two are the same pair package.json keeps out of the download.
+ *
+ * It is a COPY, not a move, and it never overwrites. The checkout keeps its
+ * copy so that merging this cannot lose a word, and a second run finds the
+ * target already there and does nothing. Never throws: a migration that cannot
+ * run must not stop the app from starting.
+ *
+ * Returns the ids it carried, so a caller can say what really happened.
+ */
+export function carryHerBriefsAcross(fromDir,toDir) {
+ const carried=[];
+ if(!fromDir||!toDir||path.resolve(fromDir)===path.resolve(toDir)) return carried;
+ for(const [id,file] of Object.entries(files)) {
+  try {
+   const target=path.join(toDir,'briefs',file);
+   if(fs.existsSync(target)) continue;
+   let text;
+   try {text=fs.readFileSync(path.join(fromDir,'briefs',file),'utf8');}
+   catch(e) {if(e.code!=='ENOENT') console.warn(`${nameSlug}: could not read ${file}: ${e.message}`); continue;}
+   if(text===(id==='rules' ? '' : defaults[id])) continue;
+   writeInstruction(toDir,id,text);
+   carried.push(id);
+  } catch(e) {console.warn(`${nameSlug}: could not carry ${file} into the data folder: ${e.message}`);}
+ }
+ return carried;
+}
+
+/**
+ * THE TWO OLD MESSAGE FILES, JOINED INTO ONE, ONCE (w-3dc46f3a67, 2026-09-22).
+ *
+ * `writing-rules.md` said how an agent writes to her during a task and
+ * `finishing.md` said how it writes the last message. They are one box now, so
+ * they have to become one document, and this is where that happens: on the
+ * first boot after the change, before anything reads the new name.
+ *
+ * WHAT IT DOES WITH THE HALF SHE NEVER WROTE. The writing rules ship empty, so
+ * anything in that file is hers. The finishing rules ship with 5,794 characters
+ * of text, so most people have never touched them. When she has the one and not
+ * the other, the joined document takes the shipped finishing text as its second
+ * half rather than leaving it out: her copy shadows the default from here on,
+ * and dropping it would quietly stop every task ending the way it does today.
+ *
+ * AND WHEN SHE WROTE NEITHER, IT WRITES NOTHING AT ALL. That is the fresh
+ * install, and leaving her with no file of her own is what keeps a later
+ * release's default reaching her. Same rule as `carryHerBriefsAcross` above:
+ * never freeze our own text into her folder.
+ *
+ * Never throws, never overwrites. Returns what it joined, or null.
+ */
+export function joinMessageRules(shippedDir,toDir) {
+ try {
+  const target=path.join(toDir,'briefs',files.messages);
+  if(fs.existsSync(target)) return null;
+  const read=(dir,name)=>{try {return fs.readFileSync(path.join(dir,'briefs',name),'utf8');} catch {return null;}};
+  const either=(name)=>read(toDir,name) ?? read(shippedDir,name);
+  const [writing,finishing]=WAS_MESSAGES.map((name)=>(either(name) ?? '').trim());
+  if(!writing && !finishing) return null;
+  const ending=finishing || defaults.messages.trim();
+  const joined=[writing,ending].filter(Boolean).join('\n\n');
+  writeInstruction(toDir,'messages',`${joined}\n`);
+  return {writing:writing.length,ending:ending.length,total:joined.length+1};
+ } catch(e) {
+  console.warn(`${nameSlug}: could not join the message rules: ${e.message}`);
+  return null;
+ }
+}