agentbox-app 0.1.13 → 0.1.16

package/shared/notify-rules.mjs

@@ -31,6 +31,15 @@ export function atTheApp({ focused = false, idleMs = 0 } = {}) {
   return !!focused && idleMs < AWAY_AFTER_MS;
 }
 
+// THE PHONE'S RULE IS WIDER: she is at the computer, in any app, so the phone
+// says nothing. Someone in a browser on the laptop is not at the app, and the
+// desktop banner above is how she hears; buzzing the phone in her bag as well
+// is the "tons and tons of notifications" she reported (2026-10-13). The
+// phone is for when she has left the machine, which only the idle clock knows.
+export function atTheComputer({ idleMs = 0 } = {}) {
+  return idleMs < AWAY_AFTER_MS;
+}
+
 // WHAT COUNTS AS NEWS, which is the question before "is she away".
 //
 // renderer/src/App.tsx owns the definition of the inbox and asks this of every
@@ -78,14 +87,15 @@ export function clip(text, max = 120) {
 // main/notify.mjs resets this the moment she has the window, so the next time
 // she walks away she can be told again.
 //
-// THE ONE EXCEPTION, and it is here because an approval card has a clock on it.
-// A finished agent waits as long as it takes. An approval is a worker frozen
-// mid-run with her as the only way through, and it is DENIED AUTOMATICALLY
-// after fifteen minutes (TIMEOUT_MS, main/approval-prompt-server.mjs). If the
-// first banner of the stretch was a finished agent, an approval landing twenty
-// minutes later would die unheard under a strict one-and-done rule. So an
-// approval gets to speak once more, and that is the cap: at most two in one
-// stretch away, never more.
+// THE ONE EXCEPTION, and it is here because an approval is the one thing in the
+// inbox that nothing else can move. A finished agent has said its piece and the
+// thread is readable without her. An approval is a worker frozen mid-run with
+// her as the only way through, and it waits exactly that long: no clock answers
+// it (main/codex-approvals.mjs). If the first banner of the stretch was a
+// finished agent, an approval landing twenty minutes later would die unheard
+// under a strict one-and-done rule, and the run would still be standing there
+// when she got back. So an approval gets to speak once more, and that is the
+// cap: at most two in one stretch away, never more.
 export function shouldSpeak({ spoke = false, spokeAsk = false, waiting = [] } = {}) {
   const items = (waiting ?? []).filter(Boolean);
   if (!items.length) return false;
@@ -137,3 +147,21 @@ export function banner(waiting) {
     open: lead.kind === 'approval' ? null : (lead.id ?? null),
   };
 }
+
+// THE PHONE'S ALERT IS HEADED BY THE THREAD (2026-10-13). On a phone the
+// banner is read in a stack of others, and she asked for the bold line to be
+// "the specific chat title so I know which thread we're talking about". iOS
+// wraps the body and gives the title a line of its own, so the macOS reason
+// above for keeping a name out of the title does not hold there. The sentence
+// moves under it. An approval names the thread that is asking (`thread`) and
+// what it wants to run; with no thread to name, it is the desktop's words.
+export function phoneBanner(waiting) {
+  const say = banner(waiting);
+  if (!say) return null;
+  const items = waiting.filter(Boolean);
+  const asks = items.filter((i) => i.kind === 'approval');
+  const lead = asks.length ? asks[0] : items[items.length - 1];
+  const name = clip(asks.length ? lead.thread : lead.title, 80);
+  if (!name) return say;
+  return { title: name, body: asks.length ? `Waiting on you: ${say.body}` : say.title, open: say.open };
+}

package/shared/phone-files.mjs

@@ -0,0 +1,28 @@
+// A FILE HER PHONE SENT WITH A REPLY OR A NEW THREAD: put in her storage, in
+// the folder of the computer the thread is on, named by what is in it
+// (renderer/src/phone-sends-files.ts), and linked in her words. The computer
+// (main/phone-inbox.mjs) and the cloud server (cloud/gateway/phone.mjs) each
+// put it in the project's attachments under the same name, made from what is
+// in it, so a turn the cloud ran and the row the computer keeps link one file.
+
+export const PHONE_FILE = /(!?)\[([^\]\n]*)\]\(phone-files\/([0-9a-f]{64}\.[a-z0-9]{1,8})\)/g;
+export const PHONE_FILES_MAX = 10;
+// The bucket's own bound on a file (20261017000000_phone_files.sql).
+export const PHONE_FILE_MAX_BYTES = 25 * 1024 * 1024;
+
+export function phoneFilesIn(text) {
+  return [...String(text ?? '').matchAll(PHONE_FILE)].map((m) => ({ link: m[0], picture: m[1] === '!', label: m[2], name: m[3] }));
+}
+
+/** The name it goes under, as main/save-attachments.mjs makes one safe. */
+export const phoneFileSafeName = (f) => String(String(f.label ?? '').trim() || f.name).replace(/[^\w.-]+/g, '-').slice(0, 80);
+
+/** Where it goes in the project's documents folder: the same file, the same place. */
+export const phoneAttachmentRel = (f) => `attachments/${String(f.name).slice(0, 16)}-${phoneFileSafeName(f)}`;
+
+/** Her words with each file linked where it was put. */
+export function linkPhoneFiles(text, found = phoneFilesIn(text)) {
+  let out = String(text ?? '');
+  for (const f of found) out = out.replace(f.link, () => `${f.picture ? '!' : ''}[${phoneFileSafeName(f)}](${phoneAttachmentRel(f)})`);
+  return out;
+}

package/shared/phone-settings.mjs

@@ -0,0 +1,118 @@
+// YOUR COMPUTER'S SETTINGS ON YOUR PHONE: the copy the Mac sends, and the
+// changes the phone may ask for. The Mac's own handlers (main/settings.mjs)
+// still decide every value. This keeps paths and instruction text out of the
+// cloud, and refuses any key the phone has no page for.
+import { CLAUDE_PERMISSION_MODES } from './work-items.mjs';
+import { CODEX_MODE_ORDER } from './codex-modes.mjs';
+import { AGENT_MODES } from './agents.mjs';
+
+export const SETTINGS_VERSION = 1;
+
+/** A login by the last part of its folder's name; the folder itself stays on the Mac. */
+export const accountIdOf = (profile) => (profile === 'default' ? 'default' : String(profile ?? '').split(/[\\/]/).filter(Boolean).pop() ?? '');
+
+const ACCOUNT_ID = /^[\w.-]{1,80}$/;
+const SLUG = /^[a-z0-9][\w-]{0,119}$/i;
+const bool = (v) => typeof v === 'boolean';
+const oneOf = (list) => (v) => list.includes(v);
+const count = (v) => Number.isInteger(v) && v >= 1 && v <= 64;
+const accountId = (v) => typeof v === 'string' && ACCOUNT_ID.test(v) && v !== '.' && v !== '..';
+
+const WORKSPACE = {
+  cornerTag: bool,
+  diagnostics: bool,
+  adhdMode: bool,
+  alphaRooms: bool,
+  alphaTeammates: bool,
+  agentsAuto: bool,
+  memoryGate: bool,
+  cleanupLeftovers: bool,
+  sessionsAtOnce: count,
+  memoryGateSlots: (v) => v === null || count(v),
+  agentsFeltSlow: oneOf(['more', 'reset']),
+  outsideAgents: oneOf(AGENT_MODES),
+  permission: oneOf(CLAUDE_PERMISSION_MODES),
+  codexMode: oneOf(CODEX_MODE_ORDER),
+  phoneProjects: (v) => !!v && bool(v.all) && Array.isArray(v.except) && v.except.length <= 500 && v.except.every((s) => typeof s === 'string' && SLUG.test(s)),
+  activeAccount: (v) => !!v && oneOf(['claude', 'codex'])(v.engine) && (v.account === null || accountId(v.account)),
+};
+const PROJECT = {
+  autonomous: bool,
+  permission: oneOf(['workspace', ...CLAUDE_PERMISSION_MODES]),
+  codexMode: oneOf(['workspace', ...CODEX_MODE_ORDER]),
+  account: (v) => v === 'any' || accountId(v),
+};
+
+/** Why the Mac should not carry out this change, or null. */
+export function checkSetting(p) {
+  if (!p || typeof p !== 'object') return 'not a setting';
+  const rules = p.scope === 'workspace' ? WORKSPACE : p.scope === 'project' ? PROJECT : null;
+  if (!rules || !Object.hasOwn(rules, p.key)) return 'not a setting your phone can change';
+  if (p.scope === 'project' && !(typeof p.product === 'string' && SLUG.test(p.product))) return 'that setting needs its project';
+  return rules[p.key](p.value) ? null : 'not a value that setting takes';
+}
+
+function profileFor(model, engine, id) {
+  if (id === null) return null;
+  const list = engine === 'codex' ? model?.workspace?.codex?.accounts : model?.workspace?.accounts;
+  const hit = (list ?? []).find((a) => accountIdOf(a.profile) === id);
+  if (!hit) throw new Error('that account is not on this computer');
+  return hit.profile;
+}
+
+/** The window's own handler for a checked change, and what to hand it. */
+export function settingRoute(p, model) {
+  if (p.scope === 'project') {
+    const value = p.key === 'account' && p.value !== 'any' ? profileFor(model, 'claude', p.value) : p.value;
+    return ['zero:settings-set-project', { product: p.product, key: p.key, value }];
+  }
+  const value = p.key === 'activeAccount' ? { engine: p.value.engine, profile: profileFor(model, p.value.engine, p.value.account) } : p.value;
+  return ['zero:settings-set-workspace', { key: p.key, value }];
+}
+
+/**
+ * What the phone's Settings pages draw, from the Mac's settings model. Null
+ * when the Mac could not read its own settings.
+ */
+export function phoneSettingsOf(model, { version }) {
+  if (!model?.ok || !model.workspace) return null;
+  const w = model.workspace;
+  const gate = w.memoryGate ?? {};
+  return {
+    v: SETTINGS_VERSION,
+    version: String(version ?? ''),
+    workspace: {
+      cornerTag: !!w.cornerTag,
+      diagnostics: !!w.diagnostics,
+      adhdMode: !!w.adhdMode,
+      alpha: { rooms: !!w.alpha?.rooms },
+      outsideAgents: w.outsideAgents,
+      permission: w.permission,
+      codexMode: w.codexMode ?? null,
+      engines: (w.engineChoices ?? []).map((e) => e.id),
+      claude: { found: !!w.claudeFound },
+      codex: { found: !!w.codex?.found },
+      agentsAuto: !!w.agentsAuto,
+      sessionsAtOnce: w.sessionsAtOnce,
+      agentsTotal: w.agentsTotal,
+      agentsAutoTotal: w.agentsAutoTotal,
+      agentsNudge: w.agentsNudge ?? 0,
+      slotsMax: w.slotsMax,
+      slotsSuggested: w.slotsSuggested,
+      running: w.running,
+      memoryGate: { on: !!gate.on, slots: gate.slots ?? null, slotsAuto: gate.slotsAuto ?? null, slotsMax: gate.slotsMax ?? null, now: gate.now ?? null },
+      leftovers: { on: !!w.leftovers?.on, now: w.leftovers?.now ?? null },
+      accounts: (w.accounts ?? []).map((a) => ({
+        id: accountIdOf(a.profile), email: a.email ?? null, chosen: !!a.chosen, state: a.state,
+        note: a.trouble?.note ?? null, plan: a.plan?.label ?? null, running: a.running ?? 0,
+      })),
+      codexAccounts: (w.codex?.accounts ?? []).map((a) => ({
+        id: accountIdOf(a.profile), email: a.email ?? null, name: a.name ?? null, plan: a.plan ?? null, signedIn: !!a.signedIn, chosen: !!a.chosen,
+      })),
+    },
+    projects: (model.projects ?? []).map((p) => ({
+      slug: p.slug, name: p.name, onPhone: !!p.onPhone, autonomous: !!p.autonomous,
+      permission: p.permission, codexMode: p.codexMode, account: p.account === 'any' ? 'any' : accountIdOf(p.account), running: p.running ?? 0,
+    })),
+  };
+}

package/shared/phone-snapshot.d.mts

@@ -0,0 +1,16 @@
+// Types for shared/phone-snapshot.mjs, for the phone with the computer closed.
+export const SNAPSHOT_LIMITS: { lines: number; textChars: number; items: number; bytes: number };
+export const PHONE_COMMANDS: string[];
+export function hideSecrets(text: string, opts?: { home?: string | null }): string;
+export function bytesOf(value: unknown): number;
+export function threadSnapshot(item: Record<string, unknown>, history?: unknown[], limits?: typeof SNAPSHOT_LIMITS, opts?: { home?: string | null }): { v: number; item: Record<string, unknown>; history: unknown[]; olderLines: number };
+export function threadsWorthCarrying<T>(items: T[], opts?: { now?: number }): T[];
+export function snapshotKey(snapshot: unknown): string;
+export function madeHere(commandId: string): string;
+export function phoneChoices(kind: string, p: Record<string, unknown> | null | undefined): Record<string, unknown>;
+export function phoneChoiceOf(saved: unknown, personId: string | null | undefined, every?: string[]): { all: boolean; except: string[] };
+export function phoneProjectsOf(saved: unknown, personId: string | null | undefined, every?: string[]): string[];
+export function withPhoneProject(saved: unknown, personId: string | null | undefined, slug: string, on: boolean, every?: string[]): { owner: string; all: boolean; except: string[] };
+export function withPhoneAll(saved: unknown, personId: string | null | undefined, on: boolean, every?: string[]): { owner: string; all: boolean; except: string[] };
+export function checkCommand(cmd: unknown, ctx: { projects: string[]; hasItem: (project: string, id: string) => boolean }): string | null;
+export function phoneEligible(products: { slug?: string }[]): string[];

package/shared/phone-snapshot.mjs

@@ -0,0 +1,348 @@
+// ONE THREAD, AS HER PHONE SEES IT WITH THE MAC SHUT (docs/cloud/PHONE-PLAN.md).
+//
+// Her Mac writes this for each thread of a project she put on her phone, and
+// the phone reads it. It is what the phone's own screens already draw: the row
+// as the Mac folded it (the phone never decides a thread's state from raw
+// lines; Codex's review of the plan, finding 5), and the thread's history as
+// the window reads it (store.readHistory), which the thread view turns into
+// the conversation. Long text is cut, and only the latest lines go. Browser-
+// safe: no node imports.
+
+import { checkSetting } from './phone-settings.mjs';
+
+// How much of one thread goes up. The latest of a thread is what she reads on
+// a phone; the whole of it stays on the Mac. `bytes` is measured in UTF-8, as
+// the database measures it (Codex's review of step 1, finding 9).
+export const SNAPSHOT_LIMITS = { lines: 400, textChars: 12_000, items: 300, bytes: 900_000 };
+
+// WHAT A COPY MAY CARRY, BY NAME (Codex's review of step 1, finding 2). A copy
+// is built out of these and nothing else, never by copying a row and deleting
+// the bad parts: a lease, an epoch, who may see a team thread, a field some
+// later version adds, none of it leaves unless it is named here.
+const ROW_FIELDS = [
+  'id', 'title', 'label', 'body', 'kind', 'labels', 'priority', 'parent', 'status',
+  'result', 'note', 'answer', 'runAt', 'snoozedUntil', 'answeredThrough',
+  'engine', 'model', 'start', 'due', 'problem', 'progress', 'solution',
+  'createdAt', 'updatedAt',
+];
+// The fields a line in a thread's history may carry in its patch: what the
+// thread view draws as the conversation and its state changes.
+const LINE_FIELDS = [
+  'title', 'label', 'body', 'kind', 'labels', 'priority', 'status', 'result',
+  'note', 'answer', 'runAt', 'snoozedUntil', 'start', 'due', 'problem',
+  'progress', 'solution', 'inReplyTo',
+];
+const SOURCES = new Set(['founder', 'agent', 'system']);
+
+// KEYS AND TOKENS IN WHAT AN AGENT OR SHE WROTE, hidden. A conversation can
+// quote one ("here is the key it used"), and a copy online is no place for it.
+const SECRETS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g,
+  /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}/g,
+  /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{40,}\b/g,
+  /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+  /\bxox[abposr]-[A-Za-z0-9-]{10,}/g,
+  /\bAIza[0-9A-Za-z_-]{35}\b/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  /\b(Bearer\s+)[A-Za-z0-9._~+/-]{20,}=*/gi,
+  /\b(Basic\s+)[A-Za-z0-9+/]{12,}=*/gi,
+];
+// A VALUE GIVEN A SECRET'S NAME, whatever it looks like (Codex's second and
+// third reviews): `AWS_SECRET_ACCESS_KEY=...`, `password: hunter22`,
+// `PASSWORD=12345678`, `password="correct horse battery staple"`. The name
+// stays, so the sentence still reads; a quoted value goes whole.
+const STRONG = '[A-Za-z0-9_.-]*(?:passw(?:or)?d|passphrase|secret|api[_-]?key|access[_-]?key|private[_-]?key|credentials?|authorization|(?:auth|access|refresh|session|bearer|id)[_-]?token)[A-Za-z0-9_.-]*';
+// "token" alone is a word people use ("token: unexpected identifier"), so it
+// counts only as an ENV_STYLE name, or before a long run that looks like a key.
+const WEAK = '(?:[A-Z0-9_]*TOKEN[A-Z0-9_]*|token)';
+// A quoted value goes whole, however long, escaped quotes and all; a bare one
+// is everything up to a space, brackets included (Codex's fourth review).
+const VALUE = '(?:"((?:[^"\\\\\\n]|\\\\.)*)"|\'((?:[^\'\\\\\\n]|\\\\.)*)\'|([^\\s"\',;]+))';
+const NAMED_STRONG = new RegExp(`\\b(${STRONG})(["']?\\s*[:=]\\s*)${VALUE}`, 'gi');
+const NAMED_WEAK = new RegExp(`\\b(${WEAK})(["']?\\s*[:=]\\s*)${VALUE}`, 'g');
+const hidden = (name, sep, dq, sq, bare) => `${name}${sep}${dq !== undefined ? '"[hidden]"' : sq !== undefined ? "'[hidden]'" : '[hidden]'}`;
+function hideNamed(text) {
+  let out = text.replace(NAMED_STRONG, (m, name, sep, dq, sq, bare) => (bare === '[hidden]' ? m : hidden(name, sep, dq, sq, bare)));
+  out = out.replace(NAMED_WEAK, (m, name, sep, dq, sq, bare) => {
+    const value = dq ?? sq ?? bare ?? '';
+    // MAX_TOKENS=128000 and TOKEN_LIMIT=8192 are settings: a bare number is
+    // never taken for a key under this weaker name.
+    const envStyle = name !== 'token' && name === name.toUpperCase() && !/^[0-9]+$/.test(value);
+    const keyLike = value.length >= 16 && /[0-9]/.test(value) && !/\s/.test(value);
+    return value !== '[hidden]' && (envStyle || keyLike) ? hidden(name, sep, dq, sq, bare) : m;
+  });
+  return out;
+}
+// AND A LONG RUN OF LETTERS AND DIGITS THAT LOOKS LIKE NOTHING BUT A KEY: 32 or
+// more, upper and lower case and digits all present. A commit id or a uuid is
+// one case of hex and is left alone.
+const KEYLIKE = /\b(?=[A-Za-z0-9_-]{32,}\b)(?=[A-Za-z0-9_-]*[a-z])(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[0-9])[A-Za-z0-9_-]{32,}\b/g;
+export function hideSecrets(text, { home = null } = {}) {
+  let out = String(text);
+  for (const re of SECRETS) out = out.replace(re, (m, bearer) => (typeof bearer === 'string' && /^(Bearer|Basic)/i.test(bearer) ? `${bearer}[hidden]` : '[hidden]'));
+  out = hideNamed(out);
+  out = out.replace(KEYLIKE, '[hidden]');
+  // Her home folder is ~ online, as it is in a crash report (shared/crash-scrub.mjs).
+  if (home && home.length > 1) out = out.split(home).join('~');
+  return out;
+}
+
+const clip = (s, n, ctx) => {
+  const t = hideSecrets(s, ctx);
+  return t.length > n ? `${t.slice(0, n)}…` : t;
+};
+// A value of a named field: text cut and cleaned, numbers as they are, short
+// lists of words, nothing nested.
+function plain(v, n, ctx) {
+  if (typeof v === 'string') return clip(v, n, ctx);
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  if (typeof v === 'boolean' || v === null) return v;
+  if (Array.isArray(v)) return v.filter((x) => typeof x === 'string').slice(0, 40).map((x) => clip(x, 200, ctx));
+  return undefined;
+}
+function pick(obj, fields, n, ctx) {
+  const out = {};
+  for (const f of fields) {
+    if (!obj || !(f in obj)) continue;
+    const v = plain(obj[f], n, ctx);
+    if (v !== undefined) out[f] = v;
+  }
+  return out;
+}
+
+export const bytesOf = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
+
+// `item` is the folded row; `history` is store.readHistory for it. `home` is
+// her home folder, written ~ in the copy.
+export function threadSnapshot(item, history = [], limits = SNAPSHOT_LIMITS, { home = null } = {}) {
+  const ctx = { home };
+  const row = pick(item, ROW_FIELDS, limits.textChars, ctx);
+  // Who wrote each field, which is how the screens tell her words from an
+  // agent's: the source and the moment, nothing else of it.
+  if (item?.wrote && typeof item.wrote === 'object') {
+    const wrote = {};
+    for (const f of ROW_FIELDS) {
+      const w = item.wrote[f];
+      if (w && SOURCES.has(w.source) && Number.isFinite(w.ts)) wrote[f] = { ts: w.ts, source: w.source };
+    }
+    row.wrote = wrote;
+  }
+  const lines = [];
+  for (const l of Array.isArray(history) ? history : []) {
+    if (!l || l.claim || l.release || l.heartbeat || !SOURCES.has(l.source) || !Number.isFinite(l.ts)) continue;
+    const patch = pick(l.patch, LINE_FIELDS, limits.textChars, ctx);
+    if (!Object.keys(patch).length) continue;
+    lines.push({ id: row.id, ts: l.ts, source: l.source, patch });
+  }
+  // Under the database's megabyte, with room: fewer lines until it fits, and
+  // then shorter text, so one long thread never stops the rest being sent.
+  for (let keep = limits.lines, chars = limits.textChars; ;) {
+    const kept = lines.slice(-keep);
+    const snap = {
+      v: 3,
+      item: chars === limits.textChars ? row : pick(row, ROW_FIELDS, chars, ctx),
+      history: chars === limits.textChars ? kept : kept.map((l) => ({ ...l, patch: pick(l.patch, LINE_FIELDS, chars, ctx) })),
+      olderLines: lines.length - kept.length,
+    };
+    if (row.wrote && snap.item !== row) snap.item.wrote = row.wrote;
+    if (bytesOf(snap) <= limits.bytes) return snap;
+    if (keep > 1) keep = Math.floor(keep / 2);
+    else if (chars > 200) chars = Math.floor(chars / 4);
+    else return { v: 3, item: { id: row.id, title: clip(row.title ?? '', 200, ctx), status: row.status, updatedAt: row.updatedAt }, history: [], olderLines: lines.length };
+  }
+}
+
+// WHICH PROJECTS ARE ON THE PHONE OF THE PERSON SIGNED IN.
+//
+// ALL OF THEM, UNLESS SHE SAYS OTHERWISE (2026-10-15: "95% of people just want
+// all of their projects connected ... I just turn them all on"). One switch
+// for the lot, on until she turns it off, and new projects go up with the
+// rest; keeping a project on this computer only is the exception, named
+// project by project (`except`).
+//
+// Her choice is kept with her id on it (`phoneProducts` in the config:
+// { owner, all, except }), so somebody else signing in on this computer starts
+// from the default rather than from her choices (Codex's review of step 1,
+// finding 1). A choice saved in the first shape, a list of the projects she
+// turned on ({ owner, slugs }), reads as all of them except the ones that list
+// left out, so the projects she had on stay on.
+// `every` is every project here, by slug.
+// The projects that can go to a phone at all: not the walk's practice project.
+export const phoneEligible = (products) => (Array.isArray(products) ? products : []).map((p) => p?.slug).filter((s) => typeof s === 'string' && s && s !== 'practice');
+export function phoneChoiceOf(saved, personId, every = []) {
+  const mine = personId && saved && typeof saved === 'object' && saved.owner === personId ? saved : null;
+  if (!mine) return { all: true, except: [] };
+  if (mine.all === undefined && Array.isArray(mine.slugs)) {
+    const on = new Set(mine.slugs);
+    return { all: true, except: every.filter((s) => !on.has(s)) };
+  }
+  return { all: mine.all !== false, except: Array.isArray(mine.except) ? mine.except.filter((s) => typeof s === 'string' && s) : [] };
+}
+export function phoneProjectsOf(saved, personId, every = []) {
+  if (!personId) return [];
+  const { all, except } = phoneChoiceOf(saved, personId, every);
+  if (!all) return [];
+  const kept = new Set(except);
+  return every.filter((s) => typeof s === 'string' && s && !kept.has(s));
+}
+// One project on or off the phone; the rest as they were.
+export function withPhoneProject(saved, personId, slug, on, every = []) {
+  if (!personId) throw new Error('sign in first');
+  const { all, except } = phoneChoiceOf(saved, personId, every);
+  const kept = new Set(except);
+  if (on) kept.delete(slug); else kept.add(slug);
+  return { owner: personId, all, except: [...kept] };
+}
+// The whole phone on or off; which projects stay local is remembered.
+export function withPhoneAll(saved, personId, on, every = []) {
+  if (!personId) throw new Error('sign in first');
+  const { except } = phoneChoiceOf(saved, personId, every);
+  return { owner: personId, all: !!on, except };
+}
+
+// A NEW THREAD STARTED ON THE PHONE has a row there before the Mac makes it,
+// under this id, and a reply to it before then is a reply to this id. The Mac
+// remembers which real row it became (main/phone-inbox.mjs) (Codex's review of
+// step 1, finding 8). Shaped like a row id, so every screen takes it.
+export const madeHere = (commandId) => `w-${String(commandId).replace(/[^0-9a-f]/gi, '').slice(0, 10).toLowerCase()}`;
+
+// The threads of a project worth carrying: everything not yet archived, and
+// what was finished in the last fortnight, newest first, at most `items`.
+export function threadsWorthCarrying(items, { now = Date.now(), limits = SNAPSHOT_LIMITS } = {}) {
+  const fortnight = 14 * 24 * 3600_000;
+  return (Array.isArray(items) ? items : [])
+    .filter((i) => i && !i.agent && (i.status !== 'done' || now - (i.updatedAt ?? 0) < fortnight))
+    .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+    .slice(0, limits.items);
+}
+
+// A cheap, stable fingerprint, so a thread that did not change is not sent.
+export function snapshotKey(snapshot) {
+  const text = JSON.stringify(snapshot);
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i += 1) { h ^= text.charCodeAt(i); h = Math.imul(h, 16777619); }
+  return `${text.length}:${(h >>> 0).toString(36)}`;
+}
+
+// WHAT HER PHONE MAY ASK HER MAC TO DO, and nothing else. A command that is not
+// one of these, or names a project she did not put on her phone, or a thread
+// that is not in it, is refused and says why.
+// A `setting` belongs to the computer, not a project (shared/phone-settings.mjs).
+export const PHONE_COMMANDS = ['reply', 'new', 'snooze', 'close', 'stop', 'run-now', 'send-now', 'reopen', 'schedule', 'approve', 'setting'];
+
+// A PERMISSION CARD AS HER PHONE DRAWS IT: what the agent asks to do, with the
+// secrets in it hidden as a thread's words are, and the fingerprint of the card
+// her Mac drew, which her answer must carry back.
+export function phoneApproval(request, card, ctx = {}) {
+  // Her Allow signs the whole request by its digest, so the phone may carry the
+  // digest only when it drew the request whole; a card that hid, clipped or
+  // dropped anything carries none and is answered on the computer. A home path
+  // written ~ is for her eyes, not a value hidden from what she signs.
+  let lossy = false;
+  const text = (s, n) => {
+    if (hideSecrets(s) !== s) lossy = true;
+    const t = hideSecrets(s, ctx);
+    if (t.length > n) { lossy = true; return `${t.slice(0, n)}…`; }
+    return t;
+  };
+  const clean = (v, depth = 0) => {
+    if (typeof v === 'string') return text(v, 4000);
+    if (typeof v === 'number' || typeof v === 'boolean' || v === null) return v;
+    if (depth > 3) { lossy = true; return undefined; }
+    if (Array.isArray(v)) { if (v.length > 40) lossy = true; return v.slice(0, 40).map((x) => clean(x, depth + 1)); }
+    if (v && typeof v === 'object') {
+      const entries = Object.entries(v);
+      if (entries.length > 40) lossy = true;
+      return Object.fromEntries(entries.slice(0, 40).map(([k, x]) => [k, clean(x, depth + 1)]));
+    }
+    return undefined;
+  };
+  const shown = { id: String(request.id), at: Number(request.at) || 0, tool: text(String(request.tool ?? 'unknown'), 200), input: clean(request.input ?? {}) };
+  return lossy ? { ...shown, card: null, answerOnComputer: true } : { ...shown, card };
+}
+
+// WHAT SHE PICKED WITH A REPLY OR A NEW THREAD, as the window's own handlers
+// take it (main/ipc.mjs zero:answer, zero:compose): only these fields, each
+// only in its right shape. Null on a reply clears a choice, as in the window.
+const WORD = /^[A-Za-z][\w.:-]{0,79}$/;
+const word = (v, n = 80) => typeof v === 'string' && v.length <= n && WORD.test(v);
+const orNull = (ok) => (v) => v === null || ok(v);
+const CHOICES = {
+  reply: {
+    permissionMode: orNull((v) => word(v, 40)), model: orNull(word), effort: orNull((v) => word(v, 20)),
+    priority: (v) => Number.isInteger(v) && v >= 0 && v <= 10, now: (v) => v === true, unschedule: (v) => v === true,
+  },
+  new: {
+    runAt: (v) => Number.isFinite(v) && v > 0, start: (v) => v === 'later' || v === 'now',
+    engine: (v) => word(v, 40), model: word, effort: (v) => word(v, 20), priority: (v) => Number.isInteger(v) && v >= 0 && v <= 10,
+    assignee: (v) => typeof v === 'string' && v.length >= 1 && v.length <= 80, due: (v) => typeof v === 'string' && v.length <= 40,
+    visibility: (v) => ['team', 'people', 'private'].includes(v),
+    visibleTo: (v) => Array.isArray(v) && v.length <= 50 && v.every((x) => typeof x === 'string' && x.length <= 80),
+  },
+};
+export function phoneChoices(kind, p) {
+  const out = {};
+  for (const [k, ok] of Object.entries(CHOICES[kind] ?? {})) if (p && k in p && p[k] !== undefined && ok(p[k])) out[k] = p[k];
+  return out;
+}
+export function checkCommand(cmd, { projects, hasItem }) {
+  if (!cmd || !PHONE_COMMANDS.includes(cmd.kind)) return 'not something the phone may do';
+  if (cmd.kind === 'setting') return cmd.project != null || cmd.item != null ? 'a setting names no project or thread' : checkSetting(cmd.payload);
+  if (!projects.includes(cmd.project)) return 'that project is not on your phone';
+  const p = cmd.payload || {};
+  if (cmd.kind === 'new') {
+    const title = typeof p.title === 'string' ? p.title.trim() : '';
+    const body = typeof p.body === 'string' ? p.body.trim() : '';
+    if (!title && !body) return 'a new thread needs some words';
+    return null;
+  }
+  if (!cmd.item || !hasItem(cmd.project, cmd.item)) return 'that thread is not on your phone';
+  if (cmd.kind === 'reply' && !(typeof p.text === 'string' && p.text.trim())) return 'an empty reply';
+  if (cmd.kind === 'snooze' && !(Number.isFinite(p.until) && p.until >= 0)) return 'a snooze needs a time';
+  if (cmd.kind === 'schedule' && !(Number.isFinite(p.runAt) && p.runAt >= 0)) return 'a schedule needs a time';
+  if (cmd.kind === 'approve' && !(typeof p.approval === 'string' && /^[\w-]{1,80}$/.test(p.approval) && typeof p.allow === 'boolean'
+    && typeof p.card === 'string' && /^[\w+/=-]{8,200}$/.test(p.card) && (p.note === undefined || (typeof p.note === 'string' && p.note.length <= 500)))) return 'an answer needs its card';
+  return null;
+}
+
+// A TURN THE CLOUD TOOK WITH THE COMPUTER SHUT, written into the thread's copy
+// by the cloud server (cloud/gateway/phone.mjs), as the computer would have
+// written it: her reply, the agent's answer and the row waiting on her
+// (main/store.mjs recordSessionResult). The computer's own copy replaces this
+// one once it is back and has brought the run home.
+export function withCloudTurn(snapshot, { reply, answer, repliedAt, answeredAt, status = 'blocked' }, limits = SNAPSHOT_LIMITS) {
+  if (!snapshot || typeof snapshot !== 'object' || !snapshot.item?.id) return null;
+  const ctx = { home: null };
+  const id = snapshot.item.id;
+  // No reply for a new thread's first turn: her ask is already its first line.
+  const replied = reply !== null && reply !== undefined;
+  const said = clip(String(reply ?? ''), limits.textChars, ctx);
+  const result = clip(String(answer ?? ''), limits.textChars, ctx);
+  const lines = [
+    ...(replied ? [{ id, ts: repliedAt, source: 'founder', patch: { answer: said, status: 'open' } }] : []),
+    { id, ts: answeredAt, source: 'agent', patch: { result } },
+    { id, ts: answeredAt, source: 'system', patch: { status } },
+  ];
+  const wrote = { ...(snapshot.item.wrote ?? {}), ...(replied ? { answer: { ts: repliedAt, source: 'founder' } } : {}), result: { ts: answeredAt, source: 'agent' }, status: { ts: answeredAt, source: 'system' } };
+  const item = { ...snapshot.item, ...(replied ? { answer: said } : {}), result, status, updatedAt: answeredAt, wrote };
+  let history = [...(Array.isArray(snapshot.history) ? snapshot.history : []), ...lines];
+  let older = Number(snapshot.olderLines) || 0;
+  while (history.length > limits.lines || (history.length > lines.length && bytesOf({ ...snapshot, item, history }) > limits.bytes)) {
+    history = history.slice(1);
+    older += 1;
+  }
+  return { ...snapshot, item, history, olderLines: older };
+}
+
+// THE PHONE'S COPY OF A THREAD THE CLOUD STARTED FROM THE PHONE, before its
+// computer has one: the row her ask made, being worked on.
+export function newThreadSnapshot({ itemId, title, body = '', at }, limits = SNAPSHOT_LIMITS) {
+  const words = { title: String(title ?? ''), ...(body ? { body: String(body) } : {}) };
+  const said = { ts: at, source: 'founder' };
+  return threadSnapshot(
+    { id: itemId, ...words, kind: 'directive', labels: ['founder'], priority: 0, status: 'claimed', createdAt: at, updatedAt: at, wrote: { title: said, ...(body ? { body: said } : {}) } },
+    [{ ts: at, source: 'founder', patch: { ...words, status: 'open' } }],
+    limits,
+  );
+}

package/shared/picture-formats.d.mts

@@ -0,0 +1 @@
+export declare function turnedName(name: string | null | undefined): string | null;

package/shared/picture-formats.mjs

@@ -0,0 +1,13 @@
+// PICTURES THE WINDOW CANNOT DRAW, and what each is turned into so it can.
+// Chromium decodes no TIFF and no HEIC, so one pasted or dropped into a reply
+// box is turned into a PNG or a JPEG as it comes in (main/stage-attachment.mjs).
+// Both sides read this: the window to know a dropped file is worth staging,
+// the main process to turn it.
+const TURNED = [[/\.tiff?$/i, '.png'], [/\.hei[cf]$/i, '.jpg']];
+
+/** The name the picture goes on under once turned, or null when it is not one of these. */
+export function turnedName(name) {
+  const s = String(name ?? '');
+  const hit = TURNED.find(([re]) => re.test(s));
+  return hit ? s.replace(/\.[^.]+$/, hit[1]) : null;
+}

package/shared/rank.d.mts

@@ -8,7 +8,8 @@ export function placeScore(order: string[], slug: string, direct?: ReadonlySet<s
 
 export const DEFAULT_PRIORITY: number;
 
-export function itemPriority(item: { priority?: number; wrote?: Record<string, { source?: string } | undefined> } | null | undefined): number;
+export function itemPriority(item: { priority?: number | null; wrote?: Record<string, { source?: string } | undefined> } | null | undefined): number;
+export function shownPriority(item: { priority?: number | null; wrote?: Record<string, { source?: string } | undefined> } | null | undefined, conversation?: boolean): number | null;
 export const URGENT_PRIORITY: number;
 export function isUrgent(item: { priority?: number; wrote?: Record<string, { source?: string } | undefined> } | null | undefined): boolean;