agentbox-app 0.1.6

package/main/config.mjs

@@ -0,0 +1,345 @@
+// the app's config: one JSON file, all paths explicit, no discovery magic.
+//
+// The store's modules used to be another system's, loaded out of a private repo
+// by absolute path, and this file was where that coupling was declared. They are
+// Agentbox's own now (main/store/*), so the only outside thing left here is the
+// claude binary.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { resolveClaudeBin, candidatePaths } from './claude-bin.mjs';
+import { resolveCodexBin } from './codex-bin.mjs';
+import { Name } from '../shared/product-name.mjs';
+import { readPlans, slotsForPlans } from './claude-plan.mjs';
+import { machineSlots } from './machine.mjs';
+import { effectiveProfiles } from './account-discovery.mjs';
+import { runningAsAFreshUser } from '../shared/fresh-user-home.mjs';
+import { runningAsADemo } from '../shared/demo-world.mjs';
+
+const CONFIG_NAME = 'zero.config.json';
+
+/**
+ * HOW MANY SESSIONS ONE ACCOUNT RUNS WHEN NOBODY HAS SAID ANYTHING AT ALL.
+ *
+ * Exported because two places need the same number and a second copy of it is a
+ * number that drifts: `DEFAULTS` below, and `Supervisor#_slotsPerAccount`, which
+ * reaches for it as CODEX's cap when the number on the config is one a CLAUDE
+ * plan lowered. A Claude plan's rate limit says nothing about an OpenAI
+ * subscription, and there is no plan tier for Codex anywhere to read, so the
+ * honest answer for Codex is the one every engine gets when nobody has said --
+ * this, rather than a Codex-shaped number nobody measured.
+ */
+export const DEFAULT_SESSIONS_AT_ONCE = 3;
+
+const DEFAULTS = {
+  // Where the inbox's own files live. WHICH FOLDER THIS SHOULD BE ON A
+  // STRANGER'S MAC IS NOT DECIDED HERE: it is the open question on.
+  //
+  // IT IS THE APP'S OWN NAME SINCE 2026-09-22, where it used to be an older
+  // product's. A real store is always named in the config, so this default is
+  // only ever the answer for an install carrying none, and renaming it moved
+  // no files: the folder it used to point at is untouched and still on disk.
+  storeRoot: path.join(os.homedir(), Name),
+  // ONE ACCOUNT FOLDER PER INSTALL, AND NOBODY ELSE'S.
+  //
+  // This was a literal id for most of the app's life, which meant every copy
+  // ever downloaded filed its work under a folder named after the machine the
+  // app was written on. `null` is the honest default: `loadConfig` mints a
+  // fresh one on first run and writes it into the config, so an id exists from
+  // then on and is this install's own. An id already in the config always wins,
+  // so nothing that is already running moves.
+  accountId: null,
+  // The brain. Sessions run headless on the founder's subscription. Left unset
+  // on purpose: where Claude Code lives depends on how it was installed, so the
+  // answer is searched for at load (main/claude-bin.mjs) rather than assumed.
+  // Setting it here in zero.config.json still wins over the search.
+  claudeBin: null,
+  // How many sessions run at once. The queue absorbs the rest; when the plan
+  // window caps out, a longer queue is the visible, benign failure mode.
+  //
+  // THIS IS THE NUMBER FOR A MAX SUBSCRIPTION, which is the only kind this was
+  // ever chosen on. When nobody has set one, loadConfig below reads the plan
+  // Claude Code is signed in on and lowers this for a smaller one.
+  maxConcurrentSessions: DEFAULT_SESSIONS_AT_ONCE,
+  // What spawned sessions are allowed to do. Left unset on purpose, because the
+  // right default now depends on whether a store MCP server is present: see
+  // Supervisor#sessionArgsFor. Setting it here still wins over that, which is
+  // how letting workers build stays the founder's explicit opt-in.
+  sessionArgs: null,
+  // An OPTIONAL stdio MCP server giving spawned workers tools to read and write
+  // the store. Agentbox ships none, so this is null and a worker runs with no store
+  // tools at all. Point it at an executable to give workers their hands back.
+  storeMcpCommand: null,
+  // Products where agent-filed TASK items spawn without waiting for the
+  // founder's approval (questions and reviews still hold for them). Empty by
+  // default: autonomy here is granted per product, deliberately, in the
+  // config file, the same way sessionArgs is.
+  autonomousProducts: [],
+  // PERSONAL PROJECTS AND THE DRIVE WERE BOTH DECLARED HERE AND BOTH ARE GONE
+  // (w-d19d6d387c, 2026-09-22). A personal project ran its sessions on the
+  // founder's message and nothing else, with no brief and no store; the drive
+  // asked "what next?" by itself on a project that had gone quiet. Hers, on
+  // the same day: "I would get rid of 'personal' as well. I think there is no
+  // case where we should ever have that", and "we should get rid of the code
+  // that self-drives the product entirely. That should never have existed
+  // anyway, especially because we're open sourcing it soon."
+  //
+  // A config still carrying `personalProducts` or `driveEnabled` is not an
+  // error; nothing reads either key now.
+  // Products the app drives: slugs under the account root. Empty means all
+  // non-archived products found on disk.
+  products: [],
+  // WHETHER THE SECOND ENGINE MAY BE CHOSEN AT ALL, AND FROM WHEN. Null, so it
+  // may not, and that is the whole of the default: every row runs Claude Code,
+  // including one she marked `engine: "codex"` in August, exactly as it did
+  // before this key existed. There is no Settings row and no picker. This is a
+  // line somebody writes in zero.config.json on purpose, which is the point of
+  // it -- it is the config half of the capability gate in shared/engines.mjs,
+  // and `main/supervisor.mjs#_engineFor` is the one place that reads it and
+  // hands the gate's token over.
+  //
+  // IT IS THE MOMENT SHE OPENED IT AND NOT A `true`. The reasoning is in
+  // shared/engines.mjs, beside the function that parses this key, and is not
+  // repeated here; in one sentence, `engine` survived the 2026-08-27 removal on
+  // the work-item contract, so her ledger may still carry rows marked `codex`
+  // from 08-25 to 08-27, and a boolean would put every one of them onto a
+  // second engine the instant it was written, with no picker, no byline naming
+  // the engine and no warning. A moment means "Codex may be chosen from now on"
+  // instead.
+  //
+  // Written as an ISO date or date-time: "2026-09-04", or
+  // "2026-09-04T09:30:00Z". Anything else -- true, "yes", "1", or a shape
+  // `Date.parse` would merely guess at -- is read as off.
+  engineChoice: null,
+};
+
+/**
+ * `home` is the machine's home folder and exists so a test can be run against
+ *  a laid-out one rather than against whoever is logged in. Nothing in the app
+ *  passes it. */
+export function loadConfig(appDir, { home = os.homedir() } = {}) {
+  const file = path.join(appDir, CONFIG_NAME);
+  let overrides = {};
+  // WHETHER THIS MAC HAS EVER RUN AGENTBOX BEFORE. There is exactly one honest
+  // marker of that and this is it: no config file at all. A file that exists
+  // but happens not to mention a setting is somebody who has been here for
+  // weeks, and treating them as new is how a default silently changes under
+  // an install that was working.
+  //
+  // NOTHING DECIDES A DEFAULT ON THIS ANY MORE. It used to pick the
+  // `outsideAgents` default, and that split was the bug: the same machine got
+  // two different answers about the same setting depending on whether a file
+  // happened to exist. There is one default now, in main/settings.mjs. This
+  // stays as a plain fact about the machine, read by nobody today, because the
+  // next thing that wants it will want it honest.
+  let fresh = false;
+  try {
+    overrides = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') fresh = true;
+    else console.warn(`zero: could not read ${file}: ${err.message}`);
+  }
+  const config = { ...DEFAULTS, ...overrides, freshInstall: fresh };
+  // An older alias for `storeRoot` was read here until 2026-09-22. A config
+  // still carrying only the old key falls through to the default now, which is
+  // why the key was renamed in zero.config.json in the same step and not after
+  // it: the two are one move, and doing them apart points the app at an empty
+  // folder.
+  // The account id, minted once per install. Written back immediately, because
+  // a generated id that is not saved is a different id next launch and the
+  // store would move out from under everything.
+  if (typeof config.accountId !== 'string' || !config.accountId) {
+    config.accountId = crypto.randomUUID();
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, `${JSON.stringify({ ...overrides, accountId: config.accountId }, null, 2)}\n`);
+    } catch (err) {
+      console.warn(`zero: could not write the new account id to ${file}: ${err.message}`);
+    }
+  }
+  config.accountRoot = path.join(config.storeRoot, 'accounts', config.accountId);
+  // Where Claude Code is on THIS machine. Her setting wins; otherwise we look
+  // (main/claude-bin.mjs). What she SET is kept separately from what we FOUND,
+  // because `claudeBin` ends up filled in either way, and a later search that
+  // reads its own last answer back as a setting would never search again.
+  //
+  // When nothing is found at all, `claudeBin` falls back to the installer's
+  // path, so anything that tries to spawn it fails the way it always did, with
+  // a real path in the message, rather than on a null. `claudeFound` is the
+  // honest answer to whether it is there, and it is carried here so no screen
+  // has to re-derive it.
+  config.claudeBinConfigured = typeof overrides.claudeBin === 'string' && overrides.claudeBin
+    ? overrides.claudeBin
+    : null;
+  const claude = resolveClaudeBin(config.claudeBinConfigured);
+  config.claudeBin = claude.path ?? candidatePaths()[0];
+  config.claudeFound = claude.found;
+  config.claudeCertain = claude.certain !== false;
+  config.claudeFrom = claude.from;
+  // AND WHERE CODEX IS, THROUGH THE SAME DOOR AND FOR A SHARPER REASON.
+  //
+  // `codexBin` used to arrive on `config` by the unknown-key spread above: this
+  // file keeps whatever is in `zero.config.json` so a setting nobody has taught
+  // the app about survives a round trip, which is right for a setting and wrong
+  // for A PATH THAT GETS SPAWNED. `this.config.codexBin` reaches `spawn` in the
+  // supervisor raw, the file is gitignored and sits in the app directory, and
+  // every worker on this machine has a broad Bash allow. So the one path in the
+  // second engine that becomes a process was the one with no finder, no
+  // existence check and no `configured` split -- while `claudeBin`, three lines
+  // up, has had all three since it was written. main/codex-bin.mjs is that
+  // finder; until now nothing imported it.
+  //
+  // THE ONE ASYMMETRY IS DELIBERATE. Claude Code is required, so a miss falls
+  // back to the installer's path and anything spawning it fails with a real
+  // path in the message. Codex is OPTIONAL, so a miss is null: null is exactly
+  // what `engineFor` and `_capacityFor` read as "this Mac cannot run the second
+  // engine", and inventing a path there would advertise an engine that is not
+  // installed and turn every Codex row into an ENOENT.
+  config.codexBinConfigured = typeof overrides.codexBin === 'string' && overrides.codexBin
+    ? overrides.codexBin
+    : null;
+  const codex = resolveCodexBin(config.codexBinConfigured);
+  config.codexBin = codex.found ? codex.path : null;
+  config.codexFound = codex.found;
+  config.codexCertain = codex.certain !== false;
+  config.codexFrom = codex.from;
+  // HOW MANY AGENTS AT ONCE, WHEN NOBODY HAS SAID, IS THE PLAN AND THE MACHINE
+  // TOGETHER. Somebody on a smaller plan gets several sessions started for them,
+  // they all spend the same allowance, and what they see is agents that are slow
+  // and rows that fail. The founder's own bullet off a tester's onboarding was
+  // "not on max plan?". So a plan that is not Max answers 1 and that stands
+  // whatever the hardware is.
+  //
+  // HER OWN NUMBER ALWAYS WINS, including when it is the same as the default:
+  // this only fills in a number nobody set. And a Mac whose plan cannot be read
+  // keeps whatever the hardware suggests, so this can make an install smaller
+  // but never breaks one. `planSlotsFrom` is the account it came from, or null,
+  // so the Agents page can say why the number is what it is instead of leaving
+  // somebody to wonder why theirs says one.
+  // AND WHAT THIS MAC SUGGESTS IS WHAT THE PLAN FALLS BACK TO. The arithmetic
+  // and the measurement behind it are in main/machine.mjs; the short version is
+  // one agent per 4 GB of memory, which is the founder's own two anchors.
+  //
+  // THE MACHINE IS THE FALLBACK RATHER THAN A SECOND CAP, and the difference is
+  // the whole reason this reads the way it does. `slotsForPlans` answers 1 for a
+  // small subscription and its fallback for everything else, so handing it the
+  // machine number composes the two correctly in one expression: a Pro plan gets
+  // one at a time whatever the hardware, and everybody else gets what the
+  // hardware suggests. Taking `Math.min` of a flat 3 and the machine instead,
+  // which is what shipped first, held every Mac at 3 or below and so could never
+  // do the thing she asked for, which is scale up: "For 24 GB, have it scale
+  // accordingly."
+  //
+  // IT IS NOT A CAP. Nothing downstream clamps to this; the stepper and the
+  // writer both use the control's own range, the same on every machine. A number
+  // already in zero.config.json is untouched, for the same reason the plan cap
+  // leaves it alone.
+  config.machineSlots = machineSlots().slots;
+  if (typeof overrides.maxConcurrentSessions !== 'number') {
+    const plans = readPlans(effectiveProfiles(config.authProfiles, { home }), { home });
+    const slots = slotsForPlans(plans, config.machineSlots);
+    config.maxConcurrentSessions = slots;
+    config.planSlotsFrom = slots === config.machineSlots
+      ? null
+      : (plans.find((p) => p.known && !p.max)?.label ?? null);
+  } else {
+    config.planSlotsFrom = null;
+  }
+  // WHOSE MACHINE THIS IS, carried so nothing downstream has to ask the OS a
+  // second time and so a test can lay out a home of its own. The accounts the
+  // fleet runs on are read from it (main/account-discovery.mjs).
+  config.home = home;
+  // Where the file is, so anything that edits a setting can write it back
+  // without being handed appDir a second time.
+  config.appDir = appDir;
+  return config;
+}
+
+export function configFile(appDir) {
+  return path.join(appDir, CONFIG_NAME);
+}
+
+/**
+ * WHICH FOLDER `zero.config.json` IS READ FROM, and the whole of it is one
+ * rule: A COPY PRETENDING TO BE SOMEBODY ELSE MAY NOT READ THE CHECKOUT'S
+ * CONFIG.
+ *
+ * Running from source the config is the checkout's, which is what every session
+ * and every test already assumes. Packaged it cannot be, because the bundle is
+ * signed and a write into it breaks the signature notarisation just bought, so
+ * it is the user data folder.
+ *
+ * THE THIRD CASE IS THE ONE THAT WAS MISSING, AND IT IS WHAT SHE SAW. She
+ * pressed the ⌘K new user row on 2026-09-27 and the second window opened on HER
+ * INBOX, the personal rows among them, with no first run in front of it. A
+ * throwaway home moves the user data folder and it does NOT move the checkout,
+ * so on a source-run app the copy that was meant to be a stranger read
+ * `<checkout>/zero.config.json` and took her store root, her account id, her
+ * PostHog key and her session arguments off it. `shared/fresh-user-home.mjs`
+ * strips those names out of the child's ENVIRONMENT, which was the other half
+ * of the same leak; this is the half a file on disk causes, and no environment
+ * variable can fix it.
+ *
+ * The demo copy goes the same way, for the same reason rather than a second
+ * one: it seeds its own small store into the throwaway home and was then
+ * pointed straight past it at hers.
+ *
+ * Both marks are read off the environment the copy was launched with, so this
+ * answers correctly inside the child while staying a plain function a test can
+ * call with no Electron and no launch.
+ */
+export function configDir({ appDir, userData, packaged = false, env = process.env } = {}) {
+  if (packaged) return userData;
+  return runningAsAFreshUser(env) || runningAsADemo(env) ? userData : appDir;
+}
+
+// Change settings from the app, on the founder's own file.
+//
+// Two halves, and both are required. The FILE is rewritten so the choice
+// survives a restart, merging into whatever is on disk right now rather than
+// into what this process read at boot: several sessions edit this repo, and a
+// whole-object overwrite from stale memory is how an unrelated key silently
+// reverts. The LIVE object is then mutated in place, because every consumer
+// (the supervisor's tick, spawnPlan's grants, the digest) reads
+// `config.*` per call, so a setting she changes takes effect on the next tick
+// rather than at the next restart. A running app that ignores its own settings
+// screen until relaunch is the same failure as a fix that is not running.
+//
+// Written through a rename, like the standing instructions: a half-written
+// config is a fleet that boots with no grants at all.
+export function saveConfig(config, patch) {
+  const appDir = config.appDir;
+  if (!appDir) throw new Error('config has no appDir; cannot save');
+  const file = configFile(appDir);
+  let onDisk = {};
+  try {
+    onDisk = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const next = { ...onDisk };
+  // NOTHING IS PINNED HERE ANY MORE, and the deletion is the point. This used
+  // to write `outsideAgents` into a new install's first save, because the
+  // default flipped from "only the ones asking" to "every session" the moment a
+  // config file existed, and a stranger who had never opened the setting would
+  // have been flipped by it. There is one default now for every install, `off`
+  // in main/settings.mjs, so there is no flip left to guard against and no
+  // setting to write on somebody's behalf.
+  for (const [key, value] of Object.entries(patch)) {
+    // An explicit undefined REMOVES the key, which is how a per-project
+    // override goes back to meaning "same as the workspace" rather than
+    // hardening into an empty list that means something else entirely.
+    if (value === undefined) delete next[key];
+    else next[key] = value;
+  }
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, file);
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) delete config[key];
+    else config[key] = value;
+  }
+  return next;
+}

package/main/copy-selection.mjs

@@ -0,0 +1,55 @@
+// "COPY" IN THE RIGHT-CLICK MENU ALWAYS PUTS SOMETHING ON THE CLIPBOARD.
+//
+// The founder, w-f7d2841075 (2026-09-26): right-click a link, press Copy, paste,
+// and what comes out is whatever was on the clipboard before. Third report of
+// the same thing (w-71f790a6eb, w-b108b1d596), and each earlier fix was
+// measured on a bare test page where the copy did land.
+//
+// MEASURED this time on the real app: a seeded message, a real right-click on a
+// link (on a Mac that selects the link's words, so "Copy" is the top item), and
+// the real native menu item pressed through the accessibility API. The click
+// handler ran, `contents.copy()` was called, and the clipboard still held the
+// sentinel written before the click. "Copy Link Address", which writes the
+// clipboard directly from here, landed every time.
+//
+// `contents.copy()` asks the page to run its own copy command, and whether that
+// lands depends on focus and selection state inside the page at the moment the
+// menu closes, which this process cannot see. The words she right-clicked on
+// are already in hand: Chromium hands them over as `params.selectionText` at the
+// moment of the click. So the page still gets the first go, because its copy
+// carries the rich version (pictures inlined, our file links unwrapped, see
+// renderer/src/copy-out.ts), and if nothing has landed shortly after, the words
+// are written directly. Either way the old clipboard is gone.
+
+/**
+ * Copy what a context menu was raised on.
+ *
+ * @param {{ copy: () => void }} contents the web contents the menu was raised on
+ * @param {string} selectionText `params.selectionText` from the context-menu event
+ * @param {{ clear: () => void, availableFormats: () => string[], writeText: (t: string) => void }} clipboard
+ * @param {{ waitMs?: number, stepMs?: number, sleep?: (ms: number) => Promise<void> }} [opts]
+ * @returns {Promise<'page' | 'direct'>} which of the two put it there
+ */
+export async function copySelection(contents, selectionText, clipboard, opts = {}) {
+  const waitMs = opts.waitMs ?? 600;
+  const stepMs = opts.stepMs ?? 25;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  // Nothing selected (a Copy in an empty text box) has no words to fall back
+  // on, and clearing would throw away her clipboard for nothing.
+  if (!selectionText) {
+    try { contents.copy(); } catch { /* nothing to copy anyway */ }
+    return 'page';
+  }
+  // Cleared first, so "something is on the clipboard" can only mean this copy
+  // put it there. The words are written below if the page does not, so a
+  // cleared clipboard never outlives this function.
+  clipboard.clear();
+  try { contents.copy(); } catch { /* a destroyed contents; the words still go */ }
+  for (let waited = 0; waited < waitMs; waited += stepMs) {
+    if (clipboard.availableFormats().length) return 'page';
+    await sleep(stepMs);
+  }
+  if (clipboard.availableFormats().length) return 'page';
+  clipboard.writeText(selectionText);
+  return 'direct';
+}

package/main/crash-report.mjs

@@ -0,0 +1,158 @@
+// When Agentbox breaks on a stranger's Mac, somebody has to find out. Today
+// nothing catches anything: the window closes, they stop opening it, and the
+// only trace is one more download. Her yes, 2026-08-19.
+//
+// What this file is: the four ways the app can die, one scrubbed report each,
+// and a queue on disk. What it is NOT, deliberately: a network client. Where
+// reports go is her open pick on (PostHog from the main process, or Aptabase),
+// and picking it here would be an agent choosing the third party that receives
+// a stranger's crashes. So `setTransport` is the seam and until something is
+// passed to it, a report is written to disk and nothing leaves the machine.
+// That is also the honest default for a build we have not shipped yet.
+//
+// Every payload is built by `shared/crash-scrub.mjs`'s allowlist and then
+// checked again by `findPrivate` before it is written. A report that fails the
+// check is not sent minus the bad field; the whole report is dropped and a
+// counter is written instead, because a scrub that quietly half-works is how a
+// promise on the page turns into a lie.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findPrivate, scrubError, scrubText } from '../shared/crash-scrub.mjs';
+import { readInstallId } from '../shared/install-id.mjs';
+import { NAME, nameSlug } from '../shared/product-name.mjs';
+
+const MAX_KEPT = 50;
+
+let ctx = null;          // { home, username, appDir, dir, version, startedAt }
+let transport = null;    // set once she picks where reports go
+let installId = null;
+let fired = false;       // one hard crash is one report, never a loop
+
+// The same random per-install id the approved counts use, and it now lives in
+// ONE file (`shared/install-id.mjs`) because two copies of "it is not a
+// fingerprint" is one copy too many. No account, no email, no machine id.
+
+export function report(kind, err, extra = {}) {
+  if (!ctx) return null;
+  const payload = {
+    v: 1,
+    kind,                                   // where it died, not what was on screen
+    ts: new Date().toISOString(),
+    installId,
+    app: { name: NAME, version: ctx.version },
+    os: { platform: process.platform, release: os.release(), arch: process.arch },
+    // How long it had been open. Useful (a crash at 3 seconds is a boot bug and
+    // a crash at 3 hours is a leak) and carries nothing about anyone.
+    upMs: Date.now() - ctx.startedAt,
+    error: scrubError(err, ctx),
+  };
+  // Extras are scrubbed exactly like the error, and only strings and numbers
+  // survive at all, so no future caller can widen this by passing an object.
+  for (const [k, v] of Object.entries(extra)) {
+    if (typeof v === 'number') payload[k] = v;
+    else if (typeof v === 'string') payload[k] = scrubText(v, ctx);
+  }
+
+  const leaks = findPrivate(payload, ctx);
+  if (leaks.length) {
+    // The scrub failed. Say that we crashed and say nothing else.
+    return write({ v: 1, kind: 'redacted', ts: payload.ts, installId, app: payload.app, os: payload.os, reason: 'scrub check failed', fields: leaks.length });
+  }
+  return write(payload);
+}
+
+function write(payload) {
+  try {
+    fs.mkdirSync(ctx.dir, { recursive: true });
+    const file = path.join(ctx.dir, `crash-${payload.ts.replace(/[:.]/g, '-')}-${Math.floor(Math.random() * 1e6)}.json`);
+    fs.writeFileSync(file, JSON.stringify(payload, null, 2));
+    prune();
+    // No await, no retry, no queue drain here: this runs while the process is
+    // dying. Delivery is the transport's problem, on the next boot if it has to be.
+    if (transport) { try { transport(payload); } catch {} }
+    return file;
+  } catch { return null; }
+}
+
+function prune() {
+  try {
+    const files = fs.readdirSync(ctx.dir).filter((f) => f.startsWith('crash-')).sort();
+    for (const f of files.slice(0, Math.max(0, files.length - MAX_KEPT))) {
+      fs.unlinkSync(path.join(ctx.dir, f));
+    }
+  } catch {}
+}
+
+// Her pick on lands here and nowhere else.
+export function setTransport(fn) { transport = typeof fn === 'function' ? fn : null; }
+
+export function pending() {
+  try {
+    return fs.readdirSync(ctx.dir).filter((f) => f.startsWith('crash-')).map((f) => path.join(ctx.dir, f));
+  } catch { return []; }
+}
+
+export function installCrashReports({ app, appDir, dir, version, crashReporter } = {}) {
+  ctx = {
+    home: os.homedir(),
+    username: (() => { try { return os.userInfo().username; } catch { return null; } })(),
+    // realpath, because macOS hands `/tmp` back as `/private/tmp` and a stack
+    // frame written the other way then reads as somebody else's code and gets
+    // dropped. The frames inside our bundle are the entire point of the report.
+    appDir: (() => { const d = appDir || process.cwd(); try { return fs.realpathSync(d); } catch { return d; } })(),
+    dir: dir || path.join(os.tmpdir(), `${nameSlug}-crash-reports`),
+    version: version || '0.0.0',
+    startedAt: Date.now(),
+  };
+  installId = readInstallId(ctx.dir);
+
+  // Native crashes (the renderer's own process dying, a GPU fault) leave a
+  // minidump rather than a JS stack. `uploadToServer: false` is not a setting
+  // that could be flipped by accident: with no destination decided there is no
+  // submit URL to flip it to, so the dumps sit in the app's own folder.
+  if (crashReporter) {
+    try { crashReporter.start({ uploadToServer: false, compress: true, ignoreSystemCrashHandler: false }); } catch {}
+  }
+
+  const onUncaught = (err) => {
+    if (fired) return;
+    fired = true;
+    report('main-uncaught', err);
+    // Put the default back rather than living on in a state Electron never
+    // designed for. A reporter that silently swallows a fatal error turns "it
+    // crashed" into "it froze", which is worse for the person holding the Mac.
+    process.removeListener('uncaughtException', onUncaught);
+    throw err;
+  };
+  process.on('uncaughtException', onUncaught);
+
+  const onRejection = (reason) => {
+    report('main-rejection', reason instanceof Error ? reason : new Error(String(reason)));
+  };
+  process.on('unhandledRejection', onRejection);
+
+  if (app?.on) {
+    // The window's process died. `details.reason` is Electron's own vocabulary
+    // (`crashed`, `oom`, `killed`) and carries nothing of theirs.
+    app.on('render-process-gone', (_e, _wc, details = {}) => {
+      report('renderer-gone', new Error('render process gone'), { reason: String(details.reason || 'unknown'), exitCode: Number(details.exitCode ?? -1) });
+    });
+    app.on('child-process-gone', (_e, details = {}) => {
+      report('child-gone', new Error('child process gone'), { reason: String(details.reason || 'unknown'), processType: String(details.type || 'unknown'), exitCode: Number(details.exitCode ?? -1) });
+    });
+  }
+  return { report, pending, dir: ctx.dir };
+}
+
+// The renderer's uncaught errors arrive here over IPC. They are the ones most
+// likely to carry a task title inside the message, which is why they go through
+// exactly the same scrub as everything else and get no shortcut of their own.
+export function reportFromRenderer(payload = {}) {
+  return report('renderer-error', {
+    name: typeof payload.name === 'string' ? payload.name : 'Error',
+    message: typeof payload.message === 'string' ? payload.message : 'renderer error',
+    stack: typeof payload.stack === 'string' ? payload.stack : '',
+  });
+}