agentbox-app 0.1.6

package/shared/rank.mjs

@@ -0,0 +1,146 @@
+// The founder's running order over her companies, and the one scoring rule
+// derived from it.
+//
+// This file exists because the rule was written twice: once in the supervisor
+// (which decides what to spawn) and once in the renderer (which decides what
+// the inbox shows first). Two copies of "what matters most" is two answers to
+// the same question, and the day they disagree is the day the top of the inbox
+// stops being what the agents are actually working on. There is one copy now,
+// imported by both.
+//
+// The model is an ORDER, not a set of buckets (founder's call, 2026-08-06).
+// Buckets leave every tie inside a bucket unanswered, and "which of these two
+// comes first" is the question the fleet needs settled.
+
+// A place in the order is worth this much, so it dominates any item's own
+// priority (which runs 0..9). A project one step higher in the order beats
+// anything filed under a project one step lower, whatever its tag says.
+export const RANK_STEP = 100;
+
+/** Clean a proposed order: strings only, no blanks, no duplicates. */
+export function normalizeOrder(slugs) {
+  if (!Array.isArray(slugs)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const slug of slugs) {
+    if (typeof slug !== 'string' || !slug || seen.has(slug)) continue;
+    seen.add(slug);
+    out.push(slug);
+  }
+  return out;
+}
+
+/**
+ * The score contributed by a product's place in the order. Higher is sooner.
+ *
+ * An UNRANKED product scores zero, which puts it below every ranked one and
+ * ties it with the other unranked. That is deliberate: a product the founder
+ * has never placed must not silently outrank one she has, and an empty order
+ * has to behave exactly like the flat inbox that existed before ranking did.
+ */
+export function productRankScore(order, slug) {
+  const idx = order.indexOf(slug);
+  if (idx === -1) return 0;
+  return (order.length - idx) * RANK_STEP;
+}
+
+/**
+ * The number an item carries into that score.
+ *
+ * An AGENT'S tag counts for nothing. Agents used to set this themselves, on a
+ * rule in the worker brief that told them 7 meant blocking; of the 442 items
+ * agents filed, 127 came in at 7 or higher, which is not an order, it is
+ * noise. She asked for the ordering to be the app's job, the rule is out of
+ * the brief, and this is the half that also covers the items already sitting
+ * in the store carrying an agent's 8.
+ *
+ * Everything else counts, and the test for "hers" is deliberately wide: her
+ * compose box writes the number as 'system' rather than 'founder' (the split
+ * in store.composeItem is words-versus-lifecycle, not authority), and a repeat
+ * rule's number arrives the same way. Reading only 'founder' here would have
+ * thrown away the Urgent tag on the very row she complained about
+ * (tests/urgent-does-not-wait-behind-medium.test.mjs).
+ *
+ * Nought means untagged, not bottom. It is the seed the fold starts an item
+ * at and the default her compose sends when she picks no number, and her own
+ * scale starts at Low, which is 2. An untagged row therefore sits in the
+ * middle with everything else and her order over the products, then age,
+ * decides it.
+ */
+export const DEFAULT_PRIORITY = 5;
+
+export function itemPriority(item) {
+  if (!item) return DEFAULT_PRIORITY;
+  if (item.wrote?.priority?.source === 'agent') return DEFAULT_PRIORITY;
+  const n = item.priority;
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_PRIORITY;
+}
+
+/**
+ * The top of her own scale, and the only level that INTERRUPTS.
+ *
+ * The number is the renderer's (renderer/src/priority.ts: Urgent is 9), and it
+ * is named here because the supervisor needs the same answer and importing a
+ * .ts module into the main process is not available to it. Same reason the
+ * whole file exists: the day the two copies disagree is the day Urgent stops
+ * meaning urgent in one half of the app.
+ */
+export const URGENT_PRIORITY = 9;
+
+/**
+ * Is this HER urgent row?
+ *
+ * itemPriority already throws away an agent's number, so this cannot be
+ * reached by a worker tagging its own proposal a nine. That matters more here
+ * than anywhere else in this file: everything downstream of this predicate
+ * takes a running session away from something else.
+ */
+export function isUrgent(item) {
+  return itemPriority(item) >= URGENT_PRIORITY;
+}
+
+/**
+ * Migration from the three-bucket model. Only ever runs against state written
+ * before the order existed, and preserves the founder's intent: everything she
+ * called high comes first, then untagged, then everything she called low.
+ */
+export function orderFromTiers(tiers) {
+  if (!tiers || typeof tiers !== 'object') return [];
+  const slugs = Object.keys(tiers);
+  const rank = (s) => (tiers[s] > 0 ? 0 : tiers[s] < 0 ? 2 : 1);
+  return normalizeOrder(slugs.filter((s) => tiers[s] !== 0).sort((a, b) => rank(a) - rank(b)));
+}
+
+/**
+ * Where a dragged chip would land, in READING ORDER, given the chips' boxes and
+ * the pointer. Returns an index to insert BEFORE; the length means "at the end".
+ *
+ * This is pure geometry and lives here rather than in the component because it
+ * is the half of ranking that was wrong. The first version compared the pointer
+ * against chip centres on the X axis alone, which is right for one row and
+ * useless for four: with twenty two projects the chips WRAP, every row spans
+ * the same X range, and dragging up or down moved nothing at all (founder,
+ * 2026-08-06). Row first, then position within the row.
+ */
+export function landingIndex(rects, x, y) {
+  if (!Array.isArray(rects)) return 0;
+  for (let i = 0; i < rects.length; i += 1) {
+    const r = rects[i];
+    if (!r) continue;
+    if (y < r.top) return i;                                 // above this row entirely
+    if (y <= r.bottom && x < r.left + r.width / 2) return i;  // this row, left of centre
+  }
+  return rects.length;
+}
+
+/**
+ * Move one product to a new index, returning a fresh order. Products that were
+ * never in the order join it on their first move, so dragging an unranked chip
+ * is how it gets ranked at all.
+ */
+export function moveProduct(order, slug, toIndex) {
+  const base = normalizeOrder(order).filter((s) => s !== slug);
+  const at = Math.max(0, Math.min(base.length, Math.trunc(toIndex)));
+  base.splice(at, 0, slug);
+  return base;
+}

package/shared/recovery.mjs

@@ -0,0 +1,26 @@
+// What the app says after it has swept up a night's stranded work.
+//
+// The two numbers mean different things and must never blur:
+//   resumed — sessions handed back their own context. Nothing for her to do.
+//   waiting — rows whose session is gone. Her rule was that these wait for her
+//             rather than being restarted, so the line has to say where they
+//             are, which is the palette command that already exists.
+//
+// Slots are not mentioned. A row that only ran out of capacity resumes itself
+// on the next tick, and a toast that lasts 2.5 seconds has no room for a
+// number that will be wrong before she has finished reading it.
+
+export function recoveryToast(r) {
+  if (!r) return null;
+  const resumed = Number(r.resumed) || 0;
+  const waiting = Number(r.waiting) || 0;
+  if (!resumed && !waiting) return null;
+  const agents = (n) => (n === 1 ? '1 agent' : `${n} agents`);
+  if (!waiting) {
+    return `${agents(resumed)} picked up where ${resumed === 1 ? 'it' : 'they'} left off`;
+  }
+  if (!resumed) {
+    return `${agents(waiting)} could not be resumed · waiting for you in ⌘K`;
+  }
+  return `${agents(resumed)} resumed · ${waiting} waiting for you in ⌘K`;
+}

package/shared/referenced-files.d.mts

@@ -0,0 +1,11 @@
+// Types for shared/referenced-files.mjs, which is plain ESM so that main (the
+// spawn path's brief) and the renderer (her attachment row) share one copy of
+// the rule about what counts as a file a message refers to.
+
+// The last argument may be `{ dir }`, the product's own folder, which is what
+// lets a path written out in full from the root be read as one of ours.
+export function referencedFiles(
+  ...texts: Array<string | null | undefined | { dir?: string | null }>
+): string[];
+export function fileLabel(path: string): { name: string; where: string };
+export function isImagePath(path: string | null | undefined): boolean;

package/shared/referenced-files.mjs

@@ -0,0 +1,122 @@
+// PURE. Every file a message refers to, in the order it refers to them.
+//
+// The last clause is the design. Nothing here asks a worker to remember to
+// attach anything: the message text IS the manifest, so a path a worker merely
+// mentioned in passing lands at the foot of the message like any other
+// attachment. Three ways a worker names a file, all of them already in use:
+//
+//   [the report](reports/week-32.md)   a markdown link or image
+//   `designs/round-3.html`             a path in a code span
+//   designs/round-3.html               a bare path in prose
+//
+// Absolute paths, urls and anchors are not files of this product's, so they are
+// left alone. The extension list is what decides: a bare word with a dot in it
+// is not a reference, and guessing wider would put "e.g" and "v1.2" in her
+// attachment row.
+//
+// IT LIVES IN shared/ BECAUSE THE BRIEF NEEDS IT TOO. This was the renderer's
+// own module, which meant the only reader of a message's manifest was the
+// screen. The spawn path had none, so a task carrying her screenshot was handed
+// to a worker as a relative link with nothing anywhere telling it to open one:
+// 155 of the 320 sessions on Agentbox that were handed one never did. Same rule,
+// one copy, both processes; renderer/src/referenced-files.ts re-exports it.
+// `change` is the newest one and it is the whole answer to David's call.A run
+// that touched the repository writes what it changed as a file, the file lands
+// in the row at the foot of the card like every drawing already does, and
+// clicking it opens the change in the pane.
+const EXT = 'png|jpe?g|gif|webp|svg|html?|pdf|md|markdown|csv|txt|json|ya?ml|sql|sh|css|jsx?|tsx?|mjs|cjs|py|rb|go|rs|toml|change';
+
+// A path, as it appears in prose or inside a link's parentheses. Deliberately
+// no leading slash and no scheme: this is a path relative to the product, which
+// is the only thing the app can resolve and open.
+// The lookbehind is what keeps a url or an absolute path from being read as a
+// relative one: without it "https://example.com/a.png" contributes
+// "example.com/a.png" and "/etc/hosts.md" contributes "etc/hosts.md", and both
+// would sit in her attachment row pointing at nothing.
+const PATH = new RegExp(String.raw`(?<![\w./:@-])(?:\.\/)?[\w-][\w./-]*\.(?:${EXT})\b`, 'gi');
+const LINK = new RegExp(String.raw`!?\[[^\]\n]*\]\(\s*([^)\s]+?)\s*(?:\s+"[^"]*")?\)`, 'g');
+
+// THE WHOLE PATH, from the root, as a worker that pasted one writes it. Kept
+// separate from PATH above because it is read by a different rule: a relative
+// path is a reference on sight, an absolute one only when `dir` says it lands
+// inside this product's own folder (see `take`).
+//
+// She was reading a card whose one document was written out in full,
+// /Users/…/astral/designs//the-first-row.html. Everything the pane can do with
+// a document hangs off this function: the chips at the foot of the message, the
+// page drawn in a frame under it, the document it opens on its own, and the
+// brief a worker is spawned with. All four were silent, because the path never
+// got past the leading slash. Counted over her Agentbox store the same day: 14 of
+// the 224 cards carrying any text name a file in full like this, and 8 of those
+// mentions point at a file in her own project folder that she should have been
+// able to open and could not.
+//
+// The other 10 are /tmp scratch and the app's own source, which is why the
+// leading slash is not simply allowed. Inside her folder it is the document she
+// was told to look at. Outside it, it is our machinery and stays plain text.
+const ABS_PATH = new RegExp(String.raw`(?<![\w.:@/-])/[\w-][\w./-]*\.(?:${EXT})\b`, 'gi');
+
+const ABSOLUTE = /^([a-z]+:|\/|#)/i;
+
+const IMAGE = /\.(png|jpe?g|gif|webp)$/i;
+
+/**
+ * Every file referenced across some pieces of a message, deduped, in order.
+ *
+ * Pass `{ dir }` last, the product's own folder, and a path written out in full
+ * from the root that lands inside it is read as the relative path it is. Every
+ * caller downstream keeps receiving relative paths and nothing else changes.
+ * Leave it out and only relative paths count, which is what this did before.
+ */
+export function referencedFiles(...texts) {
+  const last = texts[texts.length - 1];
+  const opts = last && typeof last === 'object' ? texts.pop() : null;
+  const dir = String(opts?.dir ?? '').replace(/\/+$/, '');
+
+  const found = [];
+  const seen = new Set();
+
+  const take = (raw) => {
+    if (!raw) return;
+    let path = raw.replace(/^\.\//, '').trim();
+    // Written out in full. It is one of ours only when it sits inside this
+    // product's folder, and then it is kept as the short path everything
+    // downstream already understands.
+    if (dir && path.startsWith(dir + '/')) path = path.slice(dir.length + 1);
+    if (!path || ABSOLUTE.test(path)) return;
+    // a link target that is not a file of ours (an id, a query) is not an
+    // attachment; the extension is what makes it one
+    if (!new RegExp(String.raw`\.(?:${EXT})$`, 'i').test(path)) return;
+    const key = path.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push(path);
+  };
+
+  for (const text of texts) {
+    if (!text) continue;
+    // links first, so a target that also matches the bare-path scan is recorded
+    // once, in the order a reader meets it
+    const source = String(text);
+    const hits = [];
+    for (const m of source.matchAll(LINK)) hits.push({ at: m.index ?? 0, path: m[1] });
+    for (const m of source.matchAll(PATH)) hits.push({ at: m.index ?? 0, path: m[0] });
+    if (dir) for (const m of source.matchAll(ABS_PATH)) hits.push({ at: m.index ?? 0, path: m[0] });
+    hits.sort((a, b) => a.at - b.at);
+    for (const hit of hits) take(hit.path);
+  }
+
+  return found;
+}
+
+/** What a chip says: the file's own name, with its folder as the quiet part. */
+export function fileLabel(path) {
+  const parts = path.split('/');
+  const name = parts.pop() ?? path;
+  return { name, where: parts.join('/') };
+}
+
+/** Whether a referenced path is a picture, which is what a worker must OPEN. */
+export function isImagePath(path) {
+  return IMAGE.test(String(path ?? ''));
+}

package/shared/repeats.d.mts

@@ -0,0 +1,45 @@
+// Types for shared/repeats.mjs, which is plain ESM so that main (Node) and the
+// renderer (Vite) can share one copy of the scheduling rule.
+
+// The SCHEDULE, apart from the rule that carries it: the composer and the reply
+// box hand this around before any rule exists.
+export interface RepeatShape {
+  every: 'day' | 'weekday' | 'week';
+  on?: number;              // 0..6 when every is 'week'
+  at: string;               // 24h local, "09:00"
+}
+
+export interface RepeatRule extends RepeatShape {
+  id: string;
+  title: string;
+  body?: string;
+  priority?: number;
+  createdAt: number;
+  updatedAt?: number;
+  endedAt?: number;
+  served: string;
+  misses: number;
+  alerted: number;
+  lastOccurrence?: string;
+}
+
+export const CLEAN_LABEL: string;
+export const REPEAT_LABEL_PREFIX: string;
+export function repeatLabel(ruleId: string): string;
+export function ruleIdOf(item: { labels?: string[] } | null | undefined): string | null;
+export function isCleanRun(item: { labels?: string[] } | null | undefined): boolean;
+export const DAY_NAMES: string[];
+export function isRepeatRule(rule: unknown): boolean;
+export function ruleLabel(rule: unknown): string;
+export function clockLabel(at: string): string;
+export function dateKey(now?: number): string;
+export function periodKey(rule: Partial<RepeatRule>, now?: number): string | null;
+export function nextRunAt(rule: Partial<RepeatRule>, now?: number): number | null;
+export function sameRule(a: unknown, b: unknown): boolean;
+export function servedOf(rule: Partial<RepeatRule>): string;
+export function isOwed(rule: Partial<RepeatRule>, now?: number): boolean;
+export function occurrenceId(ruleId: string, key: string): string;
+export function foldRepeats(
+  lines: Array<{ id: string; ts: number; patch: Record<string, unknown> } | null>,
+  now?: number,
+): Map<string, RepeatRule>;

package/shared/repeats.mjs

@@ -0,0 +1,193 @@
+// Repeating tasks: the pure rules, shared by the main process and the renderer
+// the way shared/rank.mjs is, so the tick and the list cannot come to disagree
+// about when something is due.
+//
+// A repeating task is a RULE, not a work item. The spec
+// (docs/superpowers/specs/2026-08-12-repeating-tasks-design.md) carries the six
+// reasons; the short one is that a work-item ledger is read from a bounded
+// trailing window and a template has to outlive that.
+
+// A period is a local CALENDAR date, never `now - 86_400_000`, which is wrong by
+// an hour twice a year. One date is one period, which is what makes DST, travel
+// and clock correction boring here instead of a source of double runs.
+const KEY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export const CLEAN_LABEL = 'clean';
+export const REPEAT_LABEL_PREFIX = 'repeat:';
+
+export function repeatLabel(ruleId) {
+  return `${REPEAT_LABEL_PREFIX}${ruleId}`;
+}
+
+export function ruleIdOf(item) {
+  const found = (item?.labels ?? []).find((l) => typeof l === 'string' && l.startsWith(REPEAT_LABEL_PREFIX));
+  return found ? found.slice(REPEAT_LABEL_PREFIX.length) : null;
+}
+
+// A clean run is one the worker EXPLICITLY marked clean. Everything else is news
+// and reaches her, including a run that died without saying anything: this
+// predicate exists to hide, never to show, so it fails open by construction.
+export function isCleanRun(item) {
+  return !!ruleIdOf(item) && (item?.labels ?? []).includes(CLEAN_LABEL);
+}
+
+export const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+// Three shapes, because they are the three a founder actually asks for:
+//   { every: 'day',     at }        every morning
+//   { every: 'weekday', at }        Monday to Friday, which is most work
+//   { every: 'week', on: 0..6, at } Thursdays
+// The `every` field was an object from the start so these would be additions
+// rather than a migration, and this is that.
+export function isRepeatRule(rule) {
+  if (!rule) return false;
+  if (typeof rule.at !== 'string' || !/^([01]\d|2[0-3]):[0-5]\d$/.test(rule.at)) return false;
+  if (rule.every === 'day' || rule.every === 'weekday') return true;
+  if (rule.every === 'week') return Number.isInteger(rule.on) && rule.on >= 0 && rule.on <= 6;
+  return false;
+}
+
+// the tag, the row and the picker's preview all print this, so they cannot
+// drift.
+export function ruleLabel(rule) {
+  if (!isRepeatRule(rule)) return 'Once';
+  const time = clockLabel(rule.at);
+  if (rule.every === 'day') return `daily at ${time}`;
+  if (rule.every === 'weekday') return `weekdays at ${time}`;
+  return `${DAY_NAMES[rule.on]}s at ${time}`;
+}
+
+export function clockLabel(at) {
+  const [h, m] = at.split(':').map(Number);
+  const d = new Date();
+  d.setHours(h, m, 0, 0);
+  return d.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })
+    .toLowerCase().replace(/\s/g, '');
+}
+
+// Does this calendar date belong to the rule at all? A weekday rule skips the
+// weekend and a weekly rule wants one day, which is the only thing that changes
+// about the period: it is still a date, still one per rule, still never
+// arithmetic.
+function servesDay(rule, d) {
+  if (rule.every === 'day') return true;
+  if (rule.every === 'weekday') return d.getDay() >= 1 && d.getDay() <= 5;
+  return d.getDay() === rule.on;
+}
+
+export function dateKey(now = Date.now()) {
+  const d = new Date(now);
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${m}-${day}`;
+}
+
+// The period `now` falls in: today's date once the hour has passed, yesterday's
+// before it. Built with calendar operations so a clock change cannot shift it. A
+// time that does not exist on a spring-forward date (02:30) normalizes to the
+// first minute that does, which is exactly when that period should be served.
+export function periodKey(rule, now = Date.now()) {
+  if (!isRepeatRule(rule)) return null;
+  const [h, m] = rule.at.split(':').map(Number);
+  const d = new Date(now);
+  const boundary = new Date(d.getFullYear(), d.getMonth(), d.getDate(), h, m, 0, 0);
+  if (boundary.getTime() > now) boundary.setDate(boundary.getDate() - 1);
+  // Walk back to the most recent day this rule actually serves. A week is the
+  // furthest that can ever be, so the loop is bounded and a rule whose day has
+  // not come round yet correctly reports the LAST one it served.
+  for (let back = 0; back < 8; back++) {
+    if (servesDay(rule, boundary)) return dateKey(boundary.getTime());
+    boundary.setDate(boundary.getDate() - 1);
+  }
+  return null;
+}
+
+// The moment this rule next runs, for the Scheduled row.
+export function nextRunAt(rule, now = Date.now()) {
+  if (!isRepeatRule(rule) || rule.endedAt) return null;
+  const [h, m] = rule.at.split(':').map(Number);
+  const d = new Date(now);
+  const next = new Date(d.getFullYear(), d.getMonth(), d.getDate(), h, m, 0, 0);
+  if (next.getTime() <= now) next.setDate(next.getDate() + 1);
+  for (let ahead = 0; ahead < 8; ahead++) {
+    if (servesDay(rule, next)) return next.getTime();
+    next.setDate(next.getDate() + 1);
+  }
+  return null;
+}
+
+// Two rules, same schedule? Used where typing drives the control: adopting a
+// rule the words already say would otherwise fight her own pick every keystroke.
+export function sameRule(a, b) {
+  if (!a || !b) return a === b;
+  return a.every === b.every && a.at === b.at && (a.on ?? null) === (b.on ?? null);
+}
+
+export function servedOf(rule) {
+  return KEY_RE.test(rule?.served ?? '') ? rule.served : '';
+}
+
+export function isOwed(rule, now = Date.now()) {
+  if (rule?.endedAt) return false;
+  const key = periodKey(rule, now);
+  return !!key && key > servedOf(rule);
+}
+
+// Deterministic, so two writers racing describe the SAME item rather than two
+// rows nothing can merge. Create-if-absent under the lock is what makes serving
+// idempotent; this is what makes that check possible at all.
+export function occurrenceId(ruleId, key) {
+  return `${ruleId}-${key.replace(/-/g, '')}`;
+}
+
+// `engine` and `model` are the LAST two and they are the reason this list is
+// worth reading twice: a field written by `setRule` and missing from here is
+// folded away, so it reads correctly once and is gone at the next app start.
+// That is exactly how `on` disappeared off every weekly rule.
+const FIELDS = [
+  'title', 'body', 'priority', 'every', 'at', 'on', 'engine', 'model',
+  'createdAt', 'endedAt', 'served', 'misses', 'alerted', 'lastOccurrence',
+];
+
+// Newest-wins per field, EXCEPT served, which folds by maximum period and
+// refuses a date later than today. Same append-only shape as dashboard.jsonl,
+// and the same reason: several writers, no read-modify-write, nothing lost.
+//
+// The two exceptions are one guard each against a watermark that lies. A
+// delayed or clock-skewed writer landing an older date last would re-run a
+// period already served, so the maximum wins rather than the latest line. And a
+// date in the FUTURE cannot be legitimate (a period key is never later than
+// today), so it is rejected outright: accepted, it would silence the task until
+// the real calendar caught up, which could be years, and no later correct write
+// could undo it because the maximum would keep it forever.
+export function foldRepeats(lines, now = Date.now()) {
+  const today = dateKey(now);
+  const rules = new Map();
+  for (const line of lines) {
+    if (!line || typeof line !== 'object') continue;
+    const { id, ts, patch } = line;
+    if (typeof id !== 'string' || !id || !patch || typeof patch !== 'object') continue;
+    if (!Number.isFinite(ts)) continue;
+    let rule = rules.get(id);
+    if (!rule) {
+      rule = { id, createdAt: ts, updatedAt: ts, served: '', misses: 0, alerted: 0, _ts: {} };
+      rules.set(id, rule);
+    }
+    for (const field of FIELDS) {
+      if (!(field in patch)) continue;
+      const value = patch[field];
+      if (field === 'served') {
+        if (KEY_RE.test(value ?? '') && value <= today && value > rule.served) rule.served = value;
+        continue;
+      }
+      const held = rule._ts[field];
+      if (held !== undefined && ts < held) continue;
+      rule[field] = value;
+      rule._ts[field] = ts;
+    }
+    rule.createdAt = Math.min(rule.createdAt, ts);
+    rule.updatedAt = Math.max(rule.updatedAt, ts);
+  }
+  for (const rule of rules.values()) delete rule._ts;
+  return rules;
+}

package/shared/schemes.mjs

@@ -0,0 +1,33 @@
+// THE APP'S TWO PRIVATE URL SCHEMES, NAMED FROM THE ONE PLACE THE APP IS NAMED.
+//
+// These were typed out as `astral-doc` and `astral-img`, two renames after the
+// app stopped being called that, in main, in the renderer and in the tests. An
+// agent reading any of them learns the wrong name for the app it is working
+// inside, which is the fault the founder opened the row about, and the next
+// rename would have had to find them all by hand.
+//
+// EVERY OLD SPELLING IS STILL SERVED, AND THAT IS NOT POLITENESS. A url on one
+// of these schemes is STORED: a product's logo is kept in the store as
+// `<scheme>://file/…` and a message she has already been sent holds picture
+// urls in its body. Dropping the old scheme would not degrade those, it would
+// break them, and the symptom is a broken image in a row she wrote months ago.
+// So the current name is what new urls are built with, and every name this app
+// has had is still registered and still answered.
+
+import { WAS, nameSlug } from './product-name.mjs';
+
+const under = (was) => was.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+/** What a url built today is on. */
+export const DOC_SCHEME = `${nameSlug}-doc`;
+export const IMG_SCHEME = `${nameSlug}-img`;
+
+/** Every spelling that must still resolve, current name first. */
+export const DOC_SCHEMES = Object.freeze([DOC_SCHEME, ...WAS.map((was) => `${under(was)}-doc`)]);
+export const IMG_SCHEMES = Object.freeze([IMG_SCHEME, ...WAS.map((was) => `${under(was)}-img`)]);
+
+/** Both, for the one place that registers all of them at once. */
+export const ALL_SCHEMES = Object.freeze([...DOC_SCHEMES, ...IMG_SCHEMES]);
+
+/** True when `protocol` (as `URL` gives it, with its colon) is one of them. */
+export const isScheme = (schemes, protocol) => schemes.some((s) => `${s}:` === protocol);

package/shared/settings-terminal.d.mts

@@ -0,0 +1 @@
+export declare const SETTINGS_TERMINAL: { product: string; id: string };

package/shared/settings-terminal.mjs

@@ -0,0 +1,14 @@
+// THE ONE TERMINAL THAT BELONGS TO NO TASK.
+//
+// Every other shell in this app is opened against a work item, and
+// `terminalFolder` refuses a key whose item does not exist. Signing a second
+// Codex account in needs a shell and has no item, so it gets this one reserved
+// key, and main resolves it to the folder main itself just made rather than to
+// anything the window asked for.
+//
+// THE PRODUCT WORD CARRIES A COLON ON PURPOSE. A key is `{product, id}`, and a
+// product here is a slug taken from a folder name; a colon never survives that,
+// so no project anybody creates can collide with this and be handed a shell
+// pointed somewhere else. Both sides import this rather than spelling it,
+// because the whole value of a reserved key is that there is one of it.
+export const SETTINGS_TERMINAL = { product: 'zero:settings', id: 'codex-login' };

package/shared/side-build.mjs

@@ -0,0 +1,57 @@
+// A SIDE BUILD IS A SECOND BUNDLE AND IT IS NOT A SECOND AGENTBOX.
+//
+// 2026-08-27.
+//
+// The bundle is separate. The DATA FOLDER MUST NOT BE, and this file is the one
+// place that says so, because two files saying it is how one of them goes
+// quietly wrong.
+//
+// Why it matters, in main.mjs's own words at the single-instance lock: "Two
+// instances mean two supervisors, and two supervisors spawn twin workers for
+// every answered item (observed 2026-08-04: nine items double-spawned one
+// second apart, four agents told the founder the same thing)." That lock lives
+// INSIDE the data folder — measured on this Mac 2026-08-27, the running Agentbox
+// holds SingletonLock in ~/Library/Application Support/Astral — so two folders
+// would be two locks and the protection would simply not be there.
+//
+// Sharing the folder also means the side build is not a stranger's copy: her
+// store, her settings, her theme, her place in everything, plus the branch.
+
+import { NAME } from '../shared/product-name.mjs';
+
+/**
+ * THE BUNDLE NAME, not a sentence, so it is the plain spelling however the
+ *  name is capitalised. Everything here compares against what macOS calls the
+ *  bundle, which is `productName` in package.json, which is this. */
+export const REAL_NAME = NAME;
+
+/**
+ * The app's own name and a word after it, yes. The bare name itself, no, that
+ *  is the real one. A bare word, or the name run into a word with no space, no:
+ *  a name that does not read as the app plus a word is a name
+ *  nobody will recognise in the Dock, and pack-side refuses it rather than
+ *  quietly building a second supervisor. */
+export function isSideBuild(name) {
+  const word = REAL_NAME.replace(/[.*+?^${}()|[\]\\]/g, (c) => `\\${c}`);
+  return new RegExp(`^${word} .+`).test(name ?? '');
+}
+
+// THE ONE SIDE BUILD THAT MUST NOT SHARE HER FOLDER.
+//
+// That folder has to be its OWN, or the hand-over would take the real
+// Agentbox's single-instance lock and bring her inbox to the front instead of
+// opening a stranger's.
+export const NEW_USER_NAME = `${REAL_NAME} new user`;
+
+export function isNewUserBuild(name) {
+  return name === NEW_USER_NAME;
+}
+
+/**
+ * The folder Chromium should name after this app, whatever the bundle is
+ * called. Everything downstream keys off app.getName, so a side build sets
+ * its name back to this before anything reads a path. */
+export function dataFolderName(name) {
+  if (isNewUserBuild(name)) return name;
+  return isSideBuild(name) ? REAL_NAME : name;
+}

package/shared/spawn-trouble.d.mts

@@ -0,0 +1,8 @@
+// Types for shared/spawn-trouble.mjs, which is plain ESM so that the
+// supervisor (Node) and the renderer (Vite) share one copy of every sentence
+// this app is allowed to say about a task that could not run.
+//
+// Only what the renderer imports is declared. The rest of the module is read by
+// main and by the tests, which are both plain JS and need nothing here.
+
+export function strandedTitle(count: number): string;