agentbox-app 0.1.11 → 0.1.13

package/main/harnesses/instructions-file.mjs

@@ -0,0 +1,116 @@
+/**
+ * THE PERSON'S STANDING INSTRUCTIONS, FOR AN ENGINE WITH NO SYSTEM PROMPT.
+ *
+ * Claude Code takes them on `--append-system-prompt` and Codex takes them as a
+ * thread's `developerInstructions`. Every other engine we have looked at takes
+ * neither: ACP has no system prompt in the protocol, and OpenCode's server
+ * takes none. So the instructions are the one thing that would arrive nowhere
+ * while everything else about a run looked perfect, and a worker that never
+ * read them is worse than one that failed to start, because it works and
+ * answers against rules it was never given.
+ *
+ * Decided on w-380b06bf53: they go into the file the tool itself reads, and
+ * which file that is lives in the definition as data — AGENTS.md for most of
+ * them, GEMINI.md for Gemini CLI. Same shape as every other name in there.
+ *
+ * TWO RULES THIS FILE IS BUILT AROUND, both of them other people's property.
+ *
+ * NEVER A TRACKED FILE. A task folder is a worktree of somebody's own
+ * repository, and AGENTS.md is frequently committed in one. This codebase has
+ * already paid for writing a tracked file once: every folder that had run the
+ * app reported itself dirty, `releaseTaskFolder` would not reclaim a folder,
+ * and change cards carried files nobody had touched (CLAUDE.md, 2026-10-07).
+ * So the preferred home is the tool's own config directory, which is per-task
+ * and ours; and if a definition does ask for the working folder, a path the
+ * repository tracks is refused rather than written.
+ *
+ * NEVER SOMEBODY ELSE'S WORDS. If the file is already there, what is in it
+ * stays. Only the block between our two markers is rewritten, so resuming a
+ * thread fifty times leaves one block and their own text untouched.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const INSTRUCTIONS_BEGIN = '<!-- agentbox:instructions -->';
+export const INSTRUCTIONS_END = '<!-- /agentbox:instructions -->';
+
+/**
+ * HOW THIS ENGINE CARRIES INSTRUCTIONS: 'flag', 'file', or null for neither.
+ *
+ * Null is the answer that matters. It is not a default to be filled in later;
+ * it is an engine that cannot be offered, because the person's rules would not
+ * reach it and nothing on screen would say so.
+ */
+export function carriesInstructions(definition) {
+  if (definition?.run?.system) return 'flag';
+  if (definition?.instructions?.file) return 'file';
+  return null;
+}
+
+/** The absolute path this engine's instructions belong at, or null. */
+export function instructionsTarget(definition, { cwd, home } = {}) {
+  const spec = definition?.instructions;
+  if (!spec?.file) return null;
+  const root = spec.in === 'cwd' ? cwd : home;
+  return root ? path.join(root, spec.file) : null;
+}
+
+/** Whether this repository has the file under version control. */
+export function fileIsTracked(file, cwd) {
+  const where = cwd ?? path.dirname(file);
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', file], { cwd: where, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;   // not tracked, or not a repository at all
+  }
+}
+
+/**
+ * Put the instructions in the file, and nothing else in it out.
+ *
+ * Idempotent on purpose: a thread resumes many times and each run writes the
+ * block again, so the test that matters is that there is exactly one of them
+ * afterwards. Returns the path written.
+ */
+export function writeInstructions({ file, text, cwd = null, tracked = null }) {
+  if (!file) throw Error('There is nowhere to write these instructions');
+  const isTracked = tracked ?? fileIsTracked(file, cwd);
+  if (isTracked) {
+    // Their file, under their version control. Writing it would dirty the
+    // worktree and could ride into the change this task is for.
+    throw Error(`${file} is tracked by this repository, so the instructions cannot be written there`);
+  }
+  const block = `${INSTRUCTIONS_BEGIN}\n${text}\n${INSTRUCTIONS_END}`;
+  let before = '';
+  try { before = fs.readFileSync(file, 'utf8'); } catch {}
+  let next;
+  const begins = before.indexOf(INSTRUCTIONS_BEGIN);
+  const ends = before.indexOf(INSTRUCTIONS_END);
+  if (begins >= 0 && ends > begins) {
+    next = before.slice(0, begins) + block + before.slice(ends + INSTRUCTIONS_END.length);
+  } else {
+    next = before ? `${before.replace(/\s*$/, '')}\n\n${block}\n` : `${block}\n`;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  return file;
+}
+
+/**
+ * The `instructions` operation every harness answers.
+ *
+ * `{ by: 'flag' }` for an engine whose command line carries them, so nothing
+ * is written and the existing path is untouched. `{ by: 'file', file }` once
+ * they are on disk. An engine that carries them neither way has no business
+ * being offered, so this throws rather than returning a shrug.
+ */
+export function instructionsFor(definition, { cwd, home, text } = {}) {
+  const how = carriesInstructions(definition);
+  if (how === 'flag') return { by: 'flag' };
+  if (how !== 'file') throw Error(`${definition?.label ?? 'This engine'} has nowhere to put standing instructions`);
+  const file = instructionsTarget(definition, { cwd, home });
+  if (!text) return { by: 'file', file, written: false };
+  return { by: 'file', file: writeInstructions({ file, text, cwd }), written: true };
+}

package/main/harnesses/opencode.mjs

@@ -0,0 +1,234 @@
+// THE OPENCODE ADAPTER, AND IT IS THE POINT OF THE ENGINE ROW.
+//
+// The engine proposal (w-380b06bf53) counted 96 `=== 'codex'` or
+// `=== 'claude'` branch points across 12 files and claimed one interface would
+// turn the next harness into one new module. This is the test of that claim,
+// and the answer is nearly yes: OpenCode is this file, main/opencode.mjs,
+// main/opencode-server.mjs, one entry of data in shared/harness-definitions,
+// one line registering it in main/harnesses.mjs -- and one filter in
+// shared/engines.mjs, which was NOT free and is written up there. No existing
+// file grew an engine branch.
+//
+// WHAT IS DECLARED MISSING RATHER THAN FAKED. `usage` is absent, so the
+// registry answers `{ supported: false }` for it: OpenCode bills through
+// whichever provider the user connected and has no endpoint that reports a
+// plan limit. Per-run tokens and cost do arrive and are read
+// (main/opencode.mjs), but "what is left" is a question nothing can answer, and
+// docs/harnesses.md says never to mark missing usage as zero. `attachInput` is
+// absent too: there is a `/tui/append-prompt` endpoint but it drives the
+// terminal UI, not a headless run, so remoteControl is false.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { harnessDefinition } from '../../shared/harness-definitions.mjs';
+import { openCodeClient, createOpenCodeWorker, splitModel } from '../opencode-server.mjs';
+import {
+  captureOpenCodeEvent, openCodeStreamingText, summarizeOpenCodeEvent,
+  traceOpenCodeEvent, openCodeActivity, rememberOpenCodeProsePart,
+  openCodePermissionConfig,
+} from '../opencode.mjs';
+import { definitionMethods, commonUpdatePlan } from './common.mjs';
+
+const definition = harnessDefinition('opencode');
+
+/**
+ * WHERE THIS WORKER'S PERMISSION POLICY LIVES ON DISK.
+ *
+ * One file per task folder, inside the folder, so two workers cannot read each
+ * other's policy and nothing is written into the user's own OpenCode config.
+ * `OPENCODE_CONFIG` points at it. It is rewritten on every start rather than
+ * reused, because a stale one is how a run silently stops asking.
+ */
+export function writePermissionConfig(cwd) {
+  const file = path.join(cwd, '.agentbox-opencode.json');
+  fs.writeFileSync(file, `${JSON.stringify(openCodePermissionConfig(), null, 2)}\n`, 'utf8');
+  return file;
+}
+
+/** The models OpenCode itself says are available, as `provider/model` rows. */
+export function openCodeModelRows(providers) {
+  const list = Array.isArray(providers?.providers) ? providers.providers : [];
+  const rows = [];
+  for (const provider of list) {
+    for (const [id, model] of Object.entries(provider?.models ?? {})) {
+      rows.push({ id: `${provider.id}/${id}`, label: `${provider.name ?? provider.id} · ${model?.name ?? id}` });
+    }
+  }
+  return rows;
+}
+
+export const openCodeHarness = {
+  ...definitionMethods(definition),
+
+  // BINARY DISCOVERY. No bespoke resolver: the binary is whatever the config
+  // names, the same question `common.mjs` answers for the other two.
+  discover: (config = {}) => config?.[definition.binKey] ?? null,
+
+  // SIGN-IN. `opencode auth login` writes to OpenCode's own store and
+  // `opencode auth list` reports it. Agentbox launches those two and reads
+  // neither file, which is the whole of its involvement with credentials.
+  //
+  // AND SIGNED IN IS NOT REQUIRED. The other two harnesses cannot run without
+  // a login; OpenCode can, on the Zen free tier (measured: zero credentials,
+  // ten models, a finished run at cost 0). So this answers true rather than
+  // gating the run, and a provider that does need a key fails loudly at
+  // `session.error` with its own words, which the readers surface.
+  signedIn: () => true,
+  profiles: () => ['default'],
+  profileHome: () => null,
+
+  // THE WORKER'S ENVIRONMENT. `profileEnv` points OPENCODE_CONFIG at the
+  // policy file written for this folder; `workerEnv` (from the definition)
+  // strips every provider key first, so nothing we hold can reach it.
+  profileEnv: (env, profile) => (profile && profile !== 'default' ? { ...env, [definition.homeEnv]: profile } : env),
+  accountKey: () => `${definition.accountPrefix}default`,
+  signInFiles: ({ folder, home }) => (folder
+    ? definition.credentialFiles.map(file => path.join(folder, file))
+    : [path.join(home, '.local/share/opencode/auth.json')]),
+
+  // MODELS. Asked of the running server rather than kept in a list here, for
+  // the reason Conductor's own docs give for doing the same: the set depends
+  // entirely on what the user connected, and we do not know it.
+  async models({ client } = {}) {
+    if (!client) return { supported: false, engine: definition.id, capability: 'models' };
+    try { return openCodeModelRows(await client.providers()); }
+    catch { return { supported: false, engine: definition.id, capability: 'models' }; }
+  },
+  defaultModel: () => null,
+  workspaceModel: () => null,
+  effortLevels: () => ({ supported: false, engine: definition.id, capability: 'effortLevels' }),
+
+  tooling: () => null,
+
+  /**
+   * ONE RUN. A server for this folder, then a worker on a session in it.
+   *
+   * The server is started per folder and killed with the worker. `--port 0`
+   * is not used: OpenCode picks a random port when none is given and prints
+   * the address it chose, which is what `openCodeServerAddress` waits for.
+   */
+  spawn(sup, plan, { cwd, item, profile = 'default', env }) {
+    const configFile = writePermissionConfig(cwd);
+    const password = sup._openCodePassword?.() ?? null;
+    const server = spawn(sup.config[definition.binKey], ['serve', '--hostname', '127.0.0.1', '--port', '0'], {
+      cwd,
+      env: {
+        ...env,
+        [definition.homeEnv]: configFile,
+        ...(password ? { OPENCODE_SERVER_PASSWORD: password } : {}),
+        ZERO_PRODUCT: item.product, ZERO_ITEM: item.id,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const worker = createOpenCodeWorker({
+      client: openCodeServerClient(server, password),
+      plan,
+      cwd,
+      resumeSessionId: plan.resumeId ?? null,
+      title: item.id,
+      onApproval: sup._openCodeApprovals?.(item) ?? null,
+    });
+    worker.once('exit', () => { try { server.kill(); } catch { /* already gone */ } });
+    worker.server = server;
+    return worker;
+  },
+
+  readers: () => ({
+    capture: captureOpenCodeEvent,
+    stream: openCodeStreamingText,
+    summarize: summarizeOpenCodeEvent,
+    trace: traceOpenCodeEvent,
+    activity: openCodeActivity,
+  }),
+
+  // Native names through, untranslated, as the Codex adapter does. The prose
+  // part is remembered first so a reasoning delta is never streamed as prose.
+  subscribe(child, session, absorb) {
+    child.on('event', (type, properties) => {
+      rememberOpenCodeProsePart(session, type, properties);
+      absorb(type, properties);
+    });
+  },
+
+  transcript: () => null,
+  change: session => (session?.opencodeChange?.length ? { files: [...session.opencodeChange] } : null),
+  release: () => {},
+
+  // COMPACTION. `POST /session/:id/summarize` -- measured, returns true.
+  compact: (sup, rec) => (rec?.sessionId && rec.client
+    ? rec.client.summarize(rec.sessionId, rec.model ?? null)
+    : Promise.resolve(false)),
+
+  // SLASH COMMANDS. `GET /command` lists them and
+  // `POST /session/:id/command` runs one, both first-party.
+  runCommand: (sup, { client, sessionId, name, args = '' } = {}) => (client && sessionId
+    ? client.runCommand(sessionId, { command: name, arguments: args })
+    : Promise.resolve(null)),
+
+  // VERSION UPDATES. `opencode upgrade` is its own updater and knows how it
+  // was installed; brew and npm installs are still caught by the common plan
+  // first so the user's package manager stays in charge where it is the owner.
+  updatePlan: options => commonUpdatePlan(definition, options, ({ bin, real, name }) => (
+    path.isAbsolute(bin) && real
+      ? { name, file: bin, args: ['upgrade'], feed: 'https://api.github.com/repos/sst/opencode/releases/latest', format: 'text' }
+      : null)),
+  updateSettings: () => ({}),
+
+  smallModelArgs: (prompt, model) => ['run', '--format', 'json', ...(model ? ['--model', model] : []), prompt],
+  memoryGate: () => ({}),
+};
+
+/** A client bound to a server whose port is only known once it says so. */
+export function openCodeServerClient(server, password = null) {
+  const address = openCodeServerAddress(server, { password });
+  const bind = method => async (...args) => {
+    const client = await address;
+    return client[method](...args);
+  };
+  const client = {};
+  for (const method of ['createSession', 'prompt', 'abort', 'replyPermission', 'summarize', 'runCommand', 'providers', 'commands', 'config', 'health']) {
+    client[method] = bind(method);
+  }
+  client.events = ({ signal } = {}) => ({
+    close: () => {},
+    async *[Symbol.asyncIterator]() {
+      const real = await address;
+      const stream = real.events({ signal });
+      client.events.close = () => stream.close();
+      yield* stream;
+    },
+  });
+  return client;
+}
+
+/**
+ * THE ADDRESS THE SERVER CHOSE, READ OFF ITS OWN FIRST LINE.
+ *
+ * `opencode serve` prints "opencode server listening on http://127.0.0.1:PORT"
+ * and nothing else before it is ready -- measured. Asking for port 0 and
+ * reading the answer is how two workers on one Mac never collide, which
+ * guessing a port does not survive.
+ */
+export function openCodeServerAddress(server, { password = null, timeoutMs = 30_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let text = '';
+    const timer = setTimeout(() => reject(Error('OpenCode did not say which port it was listening on')), timeoutMs);
+    const done = outcome => {
+      clearTimeout(timer);
+      server.stdout?.off?.('data', look);
+      server.stderr?.off?.('data', look);
+      outcome();
+    };
+    const look = data => {
+      text += data.toString();
+      const found = text.match(/https?:\/\/[0-9.]+:\d+/);
+      if (found) done(() => resolve(openCodeClient({ baseUrl: found[0], password })));
+    };
+    server.stdout?.on?.('data', look);
+    server.stderr?.on?.('data', look);
+    server.once('exit', code => done(() => reject(Error(`OpenCode's server stopped before it was ready (${code})`))));
+  });
+}
+
+export { splitModel };

package/main/harnesses.mjs

@@ -0,0 +1,65 @@
+// One registry, no user-installed plugin execution or automatic enrollment.
+// Optional reads report absence; unsupported actions fail before side effects.
+import { claudeHarness } from './harnesses/claude.mjs';
+import { codexHarness } from './harnesses/codex.mjs';
+import { openCodeHarness } from './harnesses/opencode.mjs';
+
+export const HARNESS_OPERATIONS = Object.freeze([
+  'discover', 'binary', 'workerArgs', 'install', 'signIn', 'signInStatus', 'signInFiles',
+  'workerEnv', 'launchEnv', 'profileEnv', 'profiles', 'signedIn', 'accountKey',
+  'models', 'defaultModel', 'workspaceModel', 'profileHome', 'effortLevels', 'usage', 'spawn', 'readers',
+  'subscribe', 'attachInput', 'tooling', 'transcript', 'change', 'release',
+  'compact', 'settleApproval', 'approvalChanged', 'memoryGate', 'updatePlan',
+  'smallModelArgs', 'updateSettings', 'runCommand', 'instructions',
+]);
+const OPTIONAL_READS = new Set(['usage', 'models', 'effortLevels']);
+export function createHarnessRegistry(adapters) {
+  const entries = new Map();
+  for (const adapter of adapters) {
+    if (!adapter || typeof adapter.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(adapter.id) || !adapter.label) throw Error('A harness needs an id and label.');
+    if (entries.has(adapter.id)) throw Error(`Duplicate harness: ${adapter.id}`);
+    for (const [name, value] of Object.entries(adapter.capabilities ?? {})) {
+      if (typeof value !== 'boolean') throw Error(`${adapter.id}.${name} must be a boolean.`);
+    }
+    if (adapter.capabilities?.remoteControl && typeof adapter.attachInput !== 'function') throw Error(`${adapter.id}.remoteControl requires attachInput.`);
+    if (adapter.available != null && typeof adapter.available !== 'function') throw Error(`${adapter.id}.available must be a function or absent.`);
+    // WHAT IT CAN DO IS WHAT IT SAYS, NOT WHAT IT HAS A METHOD FOR. Having the
+    // method was the whole truth while every adapter was written by hand for
+    // one tool. One adapter serving several tools over a shared protocol
+    // breaks it: it implements every operation for all of them, and what THIS
+    // tool can do is what it negotiated when the session opened. So an adapter
+    // may declare an operation unavailable, and a declined one is refused
+    // exactly as a missing one is — before it does anything.
+    const declines = name => adapter.available ? adapter.available(name) !== true : false;
+    const complete = { ...adapter };
+    for (const name of HARNESS_OPERATIONS) {
+      if (adapter[name] != null && typeof adapter[name] !== 'function') throw Error(`${adapter.id}.${name} must be a function or absent.`);
+      const absent = (..._args) => {
+        if (OPTIONAL_READS.has(name)) return { supported: false, engine: adapter.id, capability: name };
+        throw Error(`${adapter.label} does not support ${name}.`);
+      };
+      const own = complete[name];
+      complete[name] = own ? ((...args) => declines(name) ? absent(...args) : own(...args)) : absent;
+    }
+    entries.set(adapter.id, { adapter, complete: Object.freeze(complete) });
+  }
+  return Object.freeze({
+    get(id = 'claude') {
+      const entry = entries.get(id);
+      if (!entry) throw Error(`Unknown coding agent: ${String(id)}`);
+      return entry.complete;
+    },
+    supports(id, capability) {
+      const adapter = entries.get(id)?.adapter;
+      if (typeof adapter?.[capability] !== 'function') return false;
+      return adapter.available ? adapter.available(capability) === true : true;
+    },
+  });
+}
+// REGISTERED IS NOT OFFERED. OpenCode is here so anything that asks for it by
+// name gets the real adapter, and it is deliberately absent from `ENGINES`
+// (shared/engines.mjs) so no row can choose it and no picker draws it until
+// that is turned on deliberately. The two decisions are separate on purpose.
+const registry = createHarnessRegistry([claudeHarness, codexHarness, openCodeHarness]);
+export const harnessFor = id => registry.get(id);
+export const supportsHarnessOperation = (id, name) => registry.supports(id, name);

package/main/importable-threads.mjs

@@ -0,0 +1,38 @@
+// WHAT THE IMPORT CARD IS HANDED, in one function, so the read setup's last
+// card depends on can be tested whole rather than through a copy of it
+// (w-e46f2e9cea, 2026-10-11: "confirm this works during onboarding, that's the
+// critical location"). `zero:agent-threads` in main/ipc.mjs is this and the
+// `imported` marks; the walk's finish card and the ⌘K card both read it.
+//
+// Every folder either tool keeps sessions in (main/agent-homes.mjs), both
+// readers, newest first. A reader that throws costs its own half, never the
+// other one.
+//
+// AND WHEN THE LAST TEN DAYS HOLD NOTHING, THE NEWEST OLDER ONES. Setup skips
+// its last card when it has nothing to offer, so somebody whose newest session
+// was eleven days old was never told importing exists. The ten days stay the
+// list whenever they hold anything; only an empty one reaches back, ninety days
+// at most and the twenty newest, and the card says so (`listLine` in
+// renderer/src/agent-import-card.ts).
+
+import os from 'node:os';
+import { appSessionFolders } from './agent-homes.mjs';
+import { RECENT_DAYS, readSessionThreads } from './agent-sessions.mjs';
+import { readCodexThreads } from './codex-threads.mjs';
+
+export const OLDER_DAYS = 90;
+export const OLDER_MOST = 20;
+
+export function readImportableThreads({ config = null, supervisor = null, env = process.env, shellEnv, home = os.homedir(), now = Date.now() } = {}) {
+  const { dirs, codexDirs } = appSessionFolders({ config, supervisor, env, home, ...(shellEnv ? { shellEnv } : {}) });
+  const read = (days, max) => {
+    let claude = [];
+    let codex = [];
+    try { ({ threads: claude } = readSessionThreads({ home, dirs, now, days, ...(max ? { max } : {}) })); } catch { claude = []; }
+    try { ({ threads: codex } = readCodexThreads({ home, codexDirs, now, days })); } catch { codex = []; }
+    return [...claude, ...codex].sort((a, b) => (b.when ?? 0) - (a.when ?? 0));
+  };
+  const recent = read(RECENT_DAYS);
+  if (recent.length) return recent;
+  return read(OLDER_DAYS, OLDER_MOST).slice(0, OLDER_MOST);
+}

package/main/instruction-settings.mjs

@@ -1,15 +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). Five editable layers of
-// prompts was too many for a person to manage, so some were merged.
-//
-// 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". In
-// practice a rules file is mostly about how agents write to the person rather
-// than what they do, which is why the two were one thing all along.
-// `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';
@@ -25,6 +19,14 @@ import {nameSlug} from '../shared/product-name.mjs';
 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');
@@ -36,6 +38,7 @@ function fileFor(id) {
 // 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=boxDefault(id);
  let text=defaultText;
@@ -68,7 +71,7 @@ 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,7 +82,7 @@ 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')};
@@ -102,6 +105,7 @@ function keepVersion(appDir,id,now=Date.now(),always=false) {
  } 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);
@@ -150,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;
@@ -196,6 +201,7 @@ export function carryHerBriefsAcross(fromDir,toDir) {
  */
 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=(name)=>{try {return fs.readFileSync(path.join(toDir,'briefs',name),'utf8');} catch {return null;}};
@@ -225,6 +231,7 @@ export function joinMessageRules(shippedDir,toDir) {
  */
 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 '';}};
@@ -241,3 +248,32 @@ export function setAsideShippedMessageRules(shippedDir,toDir) {
   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;
+ }
+}