agentbox-app 0.1.7 → 0.1.12

package/main/frame-scrollbars.mjs

@@ -0,0 +1,90 @@
+// A PAGE IN THE PANE KEEPS ITS SCROLLBAR OUT OF SIGHT UNTIL YOU SCROLL.
+//
+// The app's own scrollbars are invisible at rest (styles.css, "SCROLLBARS ARE
+// NOT FURNITURE"), but a page drawn in the document pane is its own document
+// and that stylesheet stops at the frame. With a mouse plugged in, macOS draws
+// classic scrollbars, and a page that does not declare itself dark gets the
+// light ones: a white track the full height of the pane with a grey thumb in
+// it. That was the report, with a screenshot, on 2026-10-05.
+//
+// THE FILE IS STILL SERVED EXACTLY AS IT WAS WRITTEN (doc-scheme.mjs). What is
+// added here is the app's own chrome, from outside, once the page's document
+// exists: one adopted stylesheet that touches nothing but scrollbars, inside a
+// cascade layer so a page that styled its own scrollbars keeps them, and two
+// passive listeners that only ever swap that sheet. Nothing a page does is
+// changed or stopped, and no key or gesture of hers is listened to.
+//
+// A frame whose sandbox has no allow-scripts cannot be handed this (measured:
+// "Script not run"). The one such frame is the small preview under a message,
+// and that one is told not to scroll at all (ArtifactThumbnail.tsx).
+import { DOC_SCHEMES, isScheme } from '../shared/schemes.mjs';
+
+const RULES = (thumb) => `@layer agentbox-scrollbars {
+  ::-webkit-scrollbar { width: 10px; height: 10px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-corner { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: ${thumb}; border-radius: 10px; border: 3px solid transparent; background-clip: content-box; }
+  ::-webkit-scrollbar-thumb:hover { background: rgba(150, 150, 150, 0.7); background-clip: content-box; }
+}`;
+
+/** No track and no thumb: what a page looks like while nobody is scrolling it. */
+export const AT_REST = RULES('transparent');
+/** A thin soft thumb that reads on a dark page and a light one alike. */
+export const SHOWN = RULES('rgba(140, 140, 140, 0.45)');
+
+/** Is this a page of ours or a file, rather than a running app or the web. */
+export function wantsQuietScrollbars(url) {
+  let parsed;
+  try { parsed = new URL(String(url ?? '')); } catch { return false; }
+  return parsed.protocol === 'file:' || isScheme(DOC_SCHEMES, parsed.protocol);
+}
+
+/**
+ * Runs INSIDE the page, so it is written to be serialised: everything it uses
+ * comes in through its arguments. Shown while the page or anything in it
+ * scrolls and for a moment after, and while the pointer is at the right edge
+ * where the thumb would be grabbed.
+ */
+export function quietScrollbars(page, atRest, shown) {
+  const doc = page.document;
+  if (doc.adoptedStyleSheets.some((s) => s.agentboxScrollbars)) return;
+  const sheet = new page.CSSStyleSheet();
+  sheet.agentboxScrollbars = true;
+  sheet.replaceSync(atRest);
+  doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, sheet];
+  let showing = false;
+  let atEdge = false;
+  let timer = null;
+  const show = () => { if (!showing) { sheet.replaceSync(shown); showing = true; } };
+  const hideSoon = () => {
+    page.clearTimeout(timer);
+    timer = page.setTimeout(() => { timer = null; if (!atEdge) { sheet.replaceSync(atRest); showing = false; } }, 900);
+  };
+  page.addEventListener('scroll', () => { show(); if (!atEdge) hideSoon(); }, { capture: true, passive: true });
+  page.addEventListener('mousemove', (e) => {
+    const edge = e.clientX >= doc.documentElement.clientWidth - 14;
+    if (edge === atEdge) return;
+    atEdge = edge;
+    if (edge) { page.clearTimeout(timer); timer = null; show(); } else hideSoon();
+  }, { passive: true });
+  page.addEventListener('mouseout', (e) => {
+    if (e.relatedTarget || !atEdge) return;
+    atEdge = false;
+    hideSoon();
+  }, { passive: true });
+}
+
+const SCRIPT = `(${quietScrollbars.toString()})(window, ${JSON.stringify(AT_REST)}, ${JSON.stringify(SHOWN)})`;
+
+function quiet(frame) {
+  if (!frame || !wantsQuietScrollbars(frame.url)) return;
+  frame.executeJavaScript(SCRIPT).catch(() => { /* a sandbox without scripts, or the frame went away */ });
+}
+
+/** Every page frame in this window gets the quiet scrollbar as its document is ready. */
+export function quietTheFramesScrollbars(contents) {
+  contents.on('frame-created', (_event, { frame }) => {
+    if (!frame || frame === contents.mainFrame) return;
+    frame.on('dom-ready', () => quiet(frame));
+  });
+}

package/main/fresh-user.mjs

@@ -57,6 +57,9 @@ export function relaunchCommand({ execPath = process.execPath, argv = process.ar
  *  It cannot break inbox zero: the walk shows only its own three examples. */
 export function openFreshUser({
   withAgents = true,
+  // False is a new user with no Claude Code or Codex of hers, who signs in
+  // for itself: the way to see the walk's plan question (w-9f6975906c).
+  withTools = true,
   execPath = process.execPath,
   argv = process.argv,
   packaged = true,
@@ -65,7 +68,7 @@ export function openFreshUser({
 } = {}) {
   let prepared;
   try {
-    prepared = prepareHome(makeHome(now), { withAgents });
+    prepared = prepareHome(makeHome(now), { withAgents: withTools && withAgents, withTools });
   } catch (err) {
     return { ok: false, error: `Could not make a throwaway home under ${HOMES}: ${err?.message ?? err}` };
   }
@@ -80,7 +83,7 @@ export function openFreshUser({
     child = spawnFn(bin, args, {
       detached: true,
       stdio: 'ignore',
-      env: freshEnv(prepared.home),
+      env: freshEnv(prepared.home, process.env, { ownSignIns: !withTools }),
     });
     child.unref?.();
   } catch (err) {
@@ -91,9 +94,9 @@ export function openFreshUser({
   // be missing without looking broken, and a test that quietly cannot run an
   // agent is a test that lies. They are said rather than assumed.
   const notes = [];
-  if (!prepared.claudeBin) notes.push('Claude Code is not at ~/.local/bin/claude, so agents will not run in it.');
+  if (withTools && !prepared.claudeBin) notes.push('Claude Code is not at ~/.local/bin/claude, so agents will not run in it.');
   if (!prepared.keychain) notes.push('There is no ~/Library/Keychains here, so Claude Code will say it is not logged in.');
-  if (withAgents && !prepared.agents) notes.push('There is no ~/.claude on this Mac, so it will have no agents to offer.');
+  if (withAgents && !prepared.agents) notes.push('There is no ~/.claude on this computer, so it will have no agents to offer.');
 
   return { ok: true, home: prepared.home, agents: prepared.agents, notes, pid: child?.pid ?? null };
 }

package/main/git-change-offthread.mjs

@@ -0,0 +1,70 @@
+// THE CHECKOUT IS PHOTOGRAPHED OFF THE THREAD THAT DRAWS HER WINDOW.
+//
+// Measured 2026-10-01 on a test copy: one snapshot of the app took 2.56 seconds
+// while an agent was starting, against a few milliseconds either side. The
+// spawn ran `snapshotRepo` inline, which is four git commands and a read of
+// every untracked file, and on a busy Mac each git command costs half a second.
+// That is the "long delay" after pressing Send. The same shape as
+// main/task-folders-offthread.mjs: main/git-change.mjs stays synchronous and
+// runs whole inside a worker thread, and if the thread cannot start the job
+// runs here, the old way.
+import { Worker } from 'node:worker_threads';
+import * as change from './git-change.mjs';
+
+const JOBS = new Set(['snapshotRepo']);
+
+let worker = null;
+let broken = false;
+let seq = 0;
+const waiting = new Map();
+
+function runHere({ name, args, resolve, reject }) {
+  try { resolve(change[name](...args)); } catch (error) { reject(error); }
+}
+
+function giveUp() {
+  broken = true;
+  worker = null;
+  const left = [...waiting.values()];
+  waiting.clear();
+  for (const job of left) runHere(job);
+}
+
+function thread() {
+  if (worker || broken) return worker;
+  try {
+    worker = new Worker(new URL('./git-change-thread.mjs', import.meta.url));
+  } catch (error) {
+    console.warn('zero: the checkout will be read on the main thread:', error.message);
+    broken = true;
+    return null;
+  }
+  worker.on('message', ({ id, ok, value, error }) => {
+    const job = waiting.get(id);
+    if (!job) return;
+    waiting.delete(id);
+    if (!waiting.size) worker?.unref();
+    if (ok) job.resolve(value); else job.reject(new Error(error));
+  });
+  worker.on('error', (error) => {
+    console.warn('zero: the checkout thread failed:', error.message);
+    giveUp();
+  });
+  worker.on('exit', () => { if (worker) giveUp(); });
+  worker.unref();
+  return worker;
+}
+
+/** Run one of git-change.mjs's exports without blocking this thread. */
+export function gitJob(name, ...args) {
+  if (!JOBS.has(name)) return Promise.reject(new Error(`not a git job: ${name}`));
+  return new Promise((resolve, reject) => {
+    const job = { name, args, resolve, reject };
+    const w = thread();
+    if (!w) { runHere(job); return; }
+    const id = ++seq;
+    waiting.set(id, job);
+    w.ref();
+    w.postMessage({ id, name, args });
+  });
+}

package/main/git-change-thread.mjs

@@ -0,0 +1,11 @@
+// THE OTHER END OF main/git-change-offthread.mjs. One job at a time, in order.
+import { parentPort } from 'node:worker_threads';
+import * as change from './git-change.mjs';
+
+parentPort.on('message', ({ id, name, args }) => {
+  try {
+    parentPort.postMessage({ id, ok: true, value: change[name](...args) });
+  } catch (error) {
+    parentPort.postMessage({ id, ok: false, error: String(error?.message ?? error) });
+  }
+});

package/main/git-change.mjs

@@ -5,7 +5,7 @@
 // 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.
+// from the conversation has nothing in it. That is what a tester 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
@@ -42,7 +42,10 @@ const MAX_ROWS_PER_FILE = 20_000;
 const NOT_CODE = /(^|\/)(node_modules|\.git)\//;
 
 function git(cwd, args, { maxBuffer = 64 * 1024 * 1024 } = {}) {
-  return execFileSync('git', ['--no-pager', ...args], {
+  // A user's `diff.mnemonicPrefix` rewrites a/ and b/ into c/ i/ o/ w/.
+  // The reader below only knows one prefix. Turn the setting off for this
+  // process so a checkout reads the same on every machine.
+  return execFileSync('git', ['--no-pager', '-c', 'diff.mnemonicPrefix=false', ...args], {
     cwd,
     encoding: 'utf8',
     maxBuffer,
@@ -189,7 +192,10 @@ export function filesFromPatch(patch) {
   const nameOn = (line, side) => {
     const name = line.slice(4).trim();
     if (name === '/dev/null') return null;
-    return name.replace(side === 'old' ? /^a\// : /^b\//, '');
+    // a/ and b/ are the ordinary prefixes. c/ i/ o/ w/ are mnemonicPrefix,
+    // and 1/ 2/ are `git diff --no-index` under that same setting. One
+    // prefix comes off; a file that is itself named `b/foo` stays `b/foo`.
+    return name.replace(/^[abiowc12]\//, '');
   };
   for (const line of String(patch ?? '').split('\n')) {
     if (line.startsWith('diff --git ')) { closeHunk(); file = null; oldName = null; continue; }

package/main/img-scheme.mjs

@@ -36,7 +36,9 @@
 //      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 fs from 'node:fs';
 import path from 'node:path';
+import { Readable } from 'node:stream';
 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
@@ -51,6 +53,12 @@ export const IMG_HOST = 'file';
 
 const PICTURES = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.bmp', '.ico']);
 
+// AND A SOUND OR A FILM, SINCE 2026-09-29, so a voice sample or a render a
+// worker names plays in the message (ArtifactMedia in Focus.tsx) instead of
+// sitting there as a grey path. Same two rules, same roots: this only widens
+// what counts as something to look at, to include something to listen to.
+const MEDIA = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.mp4', '.mov', '.m4v', '.webm']);
+
 /** 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;
@@ -82,9 +90,70 @@ function inside(dir, file) {
   return f === d || f.startsWith(d + path.sep);
 }
 
+const MEDIA_TYPES = {
+  '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.aac': 'audio/aac', '.ogg': 'audio/ogg',
+  '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.m4v': 'video/mp4', '.webm': 'video/webm',
+};
+
+/** The content type of a sound or a film, or null when `file` is neither. */
+export function mediaType(file) {
+  return MEDIA_TYPES[path.extname(String(file ?? '')).toLowerCase()] ?? null;
+}
+
+// A PLAYER ASKS FOR A SOUND IN PIECES, AND net.fetch IGNORES THE ASK.
+// Measured in a hidden Electron window on 2026-09-29 against one of her voice
+// samples, served on this scheme through net.fetch: it loaded and reported its
+// 39.36 seconds, and could not be moved. `seekable` was [0, 0] and a jump to
+// the middle stayed at 0, with or without the Range header passed through,
+// because a file:// fetch answers every range with the whole file and a 200.
+// So a sound or a film is answered here, in the byte range the player asked
+// for, with a 206.
+/**
+ * The bytes a Range header asks for, as { start, end } inclusive, or null for
+ * the whole file, or false when the range cannot be served. Only one range.
+ */
+export function byteRange(header, size) {
+  if (!header) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim());
+  if (!m || (m[1] === '' && m[2] === '')) return null;
+  let start;
+  let end;
+  if (m[1] === '') {
+    // The last N bytes.
+    start = Math.max(0, size - Number(m[2]));
+    end = size - 1;
+  } else {
+    start = Number(m[1]);
+    end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+  }
+  if (start >= size || start > end) return false;
+  return { start, end };
+}
+
+/**
+ * A sound or a film off disk, answered in the range the player asked for.
+ * The caller has already decided the file may be served (`servable`).
+ */
+export async function mediaResponse(file, rangeHeader) {
+  const { size } = await fs.promises.stat(file);
+  const range = byteRange(rangeHeader, size);
+  const headers = new Headers({ 'content-type': mediaType(file) ?? 'application/octet-stream', 'accept-ranges': 'bytes' });
+  if (range === false) {
+    headers.set('content-range', `bytes */${size}`);
+    return new Response(null, { status: 416, headers });
+  }
+  if (size === 0) return new Response(null, { status: 200, headers });
+  const { start, end } = range ?? { start: 0, end: size - 1 };
+  headers.set('content-length', String(end - start + 1));
+  if (range) headers.set('content-range', `bytes ${start}-${end}/${size}`);
+  const body = Readable.toWeb(fs.createReadStream(file, { start, end }));
+  return new Response(body, { status: range ? 206 : 200, headers });
+}
+
 /** 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;
+  const ext = path.extname(file).toLowerCase();
+  if (!PICTURES.has(ext) && !MEDIA.has(ext)) return false;
   return (roots ?? []).some((root) => inside(root, file));
 }

package/main/instruction-settings.mjs

@@ -1,17 +1,9 @@
 // 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.
+// General and writing instructions are one user document (w-fb0fe5e85a).
+// The old message id remains available for callers from an older renderer;
+// once migrated, it reads, saves and restores the general instructions.
 import fs from 'node:fs';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
@@ -19,56 +11,67 @@ import {fileURLToPath} from 'node:url';
 // 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`).
+// ADHD MODE IS A FOURTH FILE, NOT A PARAGRAPH INSIDE THE THIRD (w-5737fe67cf).
+// Its text is appended to the instructions while the mode is on and removed when
+// it is off. Kept in its own file so edits to it never mix with the user's own
+// rules, and survive while the mode is off. Whether it is on lives in the
+// 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 UNIFIED = '.unified-agent-instructions';
+export function agentInstructionsUnified(appDir) {
+ return fs.existsSync(path.join(appDir,'briefs',UNIFIED));
+}
+function sectionFor(appDir,id) {
+ fileFor(id);
+ return id==='messages' && agentInstructionsUnified(appDir) ? 'rules' : id;
+}
 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];
 }
+// WHAT THE BOX OPENS ON when the user has written nothing. The message rules
+// box starts empty like the general one (w-3ec9f07978): the app's own message
+// rules are not the user's to edit, because the inbox reads every message by
+// them, so they ride on every run from the checkout and never sit in the box.
+const boxDefault=(id)=>(id==='rules'||id==='messages') ? '' : defaults[id];
 export function readInstruction(appDir,id,shippedDir=appDir) {
+ id=sectionFor(appDir,id);
  const file=fileFor(id);
- const defaultText=id==='rules' ? '' : defaults[id];
+ const defaultText=boxDefault(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).
+ * (w-94b3af4e70).
  *
- * 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.'"
+ * Why the page needs this at all: a user can edit the agent instructions, lose
+ * something that mattered, and want an earlier version back.
  *
- * 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
+ * Until this, the only thing the page could hand back was our shipped text, so
+ * recovering meant throwing away everything the user had written to get the
+ * default. 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
+ * the user 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.
+ * failing to write what the user 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);
+ id=sectionFor(appDir,id);
  const dir=historyDir(appDir,id);
  let names;
  try {names=fs.readdirSync(dir);} catch(e) {if(e.code!=='ENOENT') throw e; return [];}
@@ -79,18 +82,18 @@ export function listVersions(appDir,id) {
  }).filter(Boolean).sort((a,b)=>b.ts-a.ts);
 }
 export function readVersion(appDir,id,ts) {
- fileFor(id);
+ id=sectionFor(appDir,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()) {
+function keepVersion(appDir,id,now=Date.now(),always=false) {
  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;
+  if(!always&&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;
@@ -102,6 +105,7 @@ function keepVersion(appDir,id,now=Date.now()) {
  } catch(e) {console.warn(`${nameSlug}: could not keep a restore point for ${id}: ${e.message}`);}
 }
 export function writeInstruction(appDir,id,text,now=Date.now()) {
+ id=sectionFor(appDir,id);
  const file=fileFor(id);
  if(typeof text!=='string') throw new Error('Instructions must be text');
  keepVersion(appDir,id,now);
@@ -123,21 +127,20 @@ export function readSystemTemplate(appDir,dataDir=appDir) {
 }
 
 /**
- * HER OWN WRITING, CARRIED OUT OF THE CHECKOUT ONCE (w-3dc46f3a67, 2026-09-21).
+ * THE USER'S OWN WRITING, CARRIED OUT OF THE CHECKOUT ONCE (w-3dc46f3a67).
  *
  * 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`.
+ * in. So the user's rules were being kept in the one folder every worker is
+ * allowed to `git checkout`, and agents had been committing to them.
  *
- * WHAT MOVES IS ONLY WHAT SHE WROTE, and the test for that is the shipped
+ * WHAT MOVES IS ONLY WHAT THE USER 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, and copying it into the user's folder would freeze it there: the next
+ * release's worker brief would never reach them, because the "edit" would
+ * shadow it forever. So a file is carried across only when it differs from the
+ * default, which is typically 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
@@ -151,6 +154,7 @@ export function carryHerBriefsAcross(fromDir,toDir) {
  if(!fromDir||!toDir||path.resolve(fromDir)===path.resolve(toDir)) return carried;
  for(const [id,file] of Object.entries(files)) {
   try {
+   if(id==='messages' && agentInstructionsUnified(toDir)) continue;
    const target=path.join(toDir,'briefs',file);
    if(fs.existsSync(target)) continue;
    let text;
@@ -165,41 +169,111 @@ export function carryHerBriefsAcross(fromDir,toDir) {
 }
 
 /**
- * THE TWO OLD MESSAGE FILES, JOINED INTO ONE, ONCE (w-3dc46f3a67, 2026-09-22).
+ * THE TWO OLD MESSAGE FILES, JOINED INTO ONE, ONCE (w-3dc46f3a67).
  *
- * `writing-rules.md` said how an agent writes to her during a task and
+ * `writing-rules.md` said how an agent writes to the user 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.
+ * WHAT IT DOES WITH THE HALF THE USER NEVER WROTE. The writing rules ship
+ * empty, so anything in that file is the user's. The finishing rules ship with
+ * 5,794 characters of text, so most people have never touched them. When the
+ * user has the one and not the other, the joined document takes the shipped
+ * finishing text as its second half rather than leaving it out: the user's 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.
+ * AND WHEN THE USER WROTE NEITHER, IT WRITES NOTHING AT ALL. That is the fresh
+ * install, and leaving them with no file of their own is what keeps a later
+ * release's default reaching them. Same rule as `carryHerBriefsAcross` above:
+ * never freeze our own text into the user's folder.
+ *
+ * IT READS ONLY THE USER'S FOLDER, AND ADDS NOTHING OF OURS (w-3ec9f07978).
+ * It used to fall back to the checkout's copies and to put the shipped ending
+ * under whatever it found. In this repository `writing-rules.md` ships 16,000
+ * characters long, so every fresh copy run from source joined our two files
+ * and saved them as the user's, and the box showed nothing but our machinery.
+ * The shipped ending rides on every run anyway now (`messageRules` in the
+ * supervisor), so there is nothing of ours left to carry.
  *
  * Never throws, never overwrites. Returns what it joined, or null.
  */
 export function joinMessageRules(shippedDir,toDir) {
  try {
+  if(agentInstructionsUnified(toDir)) return null;
   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());
+  const read=(name)=>{try {return fs.readFileSync(path.join(toDir,'briefs',name),'utf8');} catch {return null;}};
+  const [writing,finishing]=WAS_MESSAGES.map((name)=>(read(name) ?? '').trim());
   if(!writing && !finishing) return null;
-  const ending=finishing || defaults.messages.trim();
-  const joined=[writing,ending].filter(Boolean).join('\n\n');
+  const joined=[writing,finishing].filter(Boolean).join('\n\n');
   writeInstruction(toDir,'messages',`${joined}\n`);
-  return {writing:writing.length,ending:ending.length,total:joined.length+1};
+  return {writing:writing.length,ending:finishing.length,total:joined.length+1};
  } catch(e) {
   console.warn(`${nameSlug}: could not join the message rules: ${e.message}`);
   return null;
  }
 }
+
+/**
+ * A MESSAGE BOX THAT HOLDS ONLY OUR TEXT IS NOT THE USER'S, ONCE (w-3ec9f07978).
+ *
+ * The old join above wrote the checkout's writing rules and ending rules into
+ * the user's folder as if they had typed them, so their box opened on 21,743
+ * characters of the app's own rules. A file whose text is EXACTLY one of the
+ * things we ship, alone or joined the way the old join joined them, is set
+ * aside: kept as a restore point and removed, so the box opens empty and our
+ * rules reach the run from the checkout as they should.
+ *
+ * Exact only. One line of the user's own makes the whole file theirs, and
+ * nothing here tries to cut it apart. Never throws. Returns whether it acted.
+ */
+export function setAsideShippedMessageRules(shippedDir,toDir) {
+ try {
+  if(agentInstructionsUnified(toDir)) return false;
+  const target=path.join(toDir,'briefs',files.messages);
+  if(path.resolve(shippedDir)===path.resolve(toDir)||!fs.existsSync(target)) return false;
+  const read=(name)=>{try {return fs.readFileSync(path.join(shippedDir,'briefs',name),'utf8').trim();} catch {return '';}};
+  const writing=read(WAS_MESSAGES[0]);
+  const endings=[...new Set([read(files.messages),defaults.messages.trim()])].filter(Boolean);
+  const ours=new Set([...endings,...endings.map((e)=>[writing,e].filter(Boolean).join('\n\n'))]);
+  const text=fs.readFileSync(target,'utf8').trim();
+  if(!text||!ours.has(text)) return false;
+  keepVersion(toDir,'messages',Date.now(),true);
+  fs.rmSync(target,{force:true});
+  return true;
+ } catch(e) {
+  console.warn(`${nameSlug}: could not set aside the shipped message rules: ${e.message}`);
+  return false;
+ }
+}
+
+// Runs after the older migrations, before the supervisor or editors read.
+// Original message files and their histories remain on disk for recovery.
+// The completion marker prevents later boots reimporting them after an edit
+// or an intentional empty save. A failed save leaves both originals active.
+export function unifyAgentInstructions(shippedDir,toDir) {
+ try {
+  if(path.resolve(shippedDir)===path.resolve(toDir)||agentInstructionsUnified(toDir)) return null;
+  const general=readInstruction(toDir,'rules').text;
+  const writing=readInstruction(toDir,'messages').text;
+  if(writing.trim()) {
+   // If the combined save succeeded but completion was interrupted, the exact
+   // old text is already at the end. Retrying must not append it again.
+   const combined=general.endsWith(writing) ? general : general ? `${general}\n\n${writing}` : writing;
+   keepVersion(toDir,'rules',Date.now(),true);
+   keepVersion(toDir,'messages',Date.now(),true);
+   if(combined!==general) writeInstruction(toDir,'rules',combined);
+  }
+  const marker=path.join(toDir,'briefs',UNIFIED);
+  fs.mkdirSync(path.dirname(marker),{recursive:true});
+  const temporary=`${marker}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary,'1\n','utf8');
+  fs.renameSync(temporary,marker);
+  return {general:general.length,writing:writing.length};
+ } catch(e) {
+  console.warn(`${nameSlug}: could not combine the agent instructions: ${e.message}`);
+  return null;
+ }
+}