agentbox-app 0.1.7 → 0.1.12

package/main/ipc.mjs

@@ -1,5 +1,6 @@
 import { openSourceFile } from './open-source-file.mjs';
 import {submitReply} from './live-replies.mjs';
+import { createEngineSetup } from './engine-setup.mjs';
 // IPC: a thin, typed-by-convention surface. The renderer asks; the main
 // process derives from files and answers. Pushes go one way: "state changed,
 // refetch." No state is cached on either side of the bridge.
@@ -21,14 +22,19 @@ import {submitReply} from './live-replies.mjs';
 import {terminalSenderAllowed} from './terminal-access.mjs';
 import {TaskTerminals,terminalPlace} from './task-terminals.mjs';
 import {SETTINGS_TERMINAL} from '../shared/settings-terminal.mjs';
+import {AgentUpdates,installedAgent} from './agent-updates.mjs';
+import {refreshAgentModels} from './refresh-agent-models.mjs';
 import {readInstruction,writeInstruction,listVersions,readVersion} from './instruction-settings.mjs';
 import path from 'node:path';
 import os from 'node:os';
 import fsWatch from 'node:fs';
 import { listFolders } from './folders.mjs';
+import { feedbackUrl, sendFeedback } from './feedback.mjs';
+import { feedbackPayload } from '../shared/feedback.mjs';
 import * as approvals from './approvals.mjs';
 import { restartNeeded } from './staleness.mjs';
 import { artifactRoots, resolveArtifact } from './artifact-path.mjs';
+import { folderPictures } from './folder-pictures.mjs';
 import { docUrl } from './doc-scheme.mjs';
 import { readDoc, writeDoc } from './doc-file.mjs';
 import { readChange } from './code-change.mjs';
@@ -43,6 +49,7 @@ import * as agents from './agents.mjs';
 import { findAgentFolders, readAgentFiles, readFolderAgents } from './agent-files.mjs';
 import { readSessionThreads } from './agent-sessions.mjs';
 import { readCodexThreads } from './codex-threads.mjs';
+import { markImported } from '../shared/agent-import.mjs';
 import { codexIdOf, importChoice, isCodexImportRow, isNotImportedRow } from '../shared/codex-import.mjs';
 import { checkProjectFolder } from '../shared/project-folder-check.mjs';
 import { openFreshUser } from './fresh-user.mjs';
@@ -52,6 +59,7 @@ import { agentKey } from '../shared/agents.mjs';
 import { machineryPath } from './store/home.mjs';
 import { EVENT_NAMES } from '../shared/analytics-events.mjs';
 import { Name } from '../shared/product-name.mjs';
+import { handedOnByReply } from '../shared/team-rules.mjs';
 
 // WHAT A WORKER IS TOLD WHEN HER DECISION COULD NOT BE RECORDED.
 const SPOOL_REFUSED = `${Name} could not record the founder's decision, so nothing was allowed. Finish what your grants cover and file the rest as a review.`;
@@ -85,7 +93,7 @@ const NO_UPDATER = {
   install: () => false,
 };
 
-export function registerIpc({ store, supervisor, config, window, analytics = NO_ANALYTICS, docGrants = null, updater = NO_UPDATER, host }) {
+export function registerIpc({ store, supervisor, config, window, analytics = NO_ANALYTICS, docGrants = null, updater = NO_UPDATER, host, team = null }) {
   // The three Electron things, or a plain Node stand-in for them. There is no
   // default: a caller that forgets says so here rather than throwing eighty
   // lines further down on `ipcMain.handle` of undefined.
@@ -123,7 +131,7 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   // Allow/Deny Pending Approval in the Agents menu. All three go through here
   // so all three tell the renderer what was just decided: without that, the
   // card only ever "disappeared" on the next store push and nothing on screen
-  // acknowledged the press (the founder, 2026-08-06). The card's exit is drawn
+  // acknowledged the press. The card's exit is drawn
   // from this.
   //
   // THE MENU WAS NOT ONE OF THE THREE UNTIL NOW, AND THIS PARAGRAPH SAID IT
@@ -196,12 +204,19 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   // and attaches the properties itself. This is the reason there is no
   // analytics SDK in the renderer at all (a test fails the build if one
   // appears): a browser SDK autocaptures the text of what was clicked, and in
-  // Agentbox that text is task titles.
-  ipcMain.handle('zero:track', (_e, { name } = {}) => {
+  // Agentbox that text is task titles. A NUMBER MAY RIDE WITH THE NAME, and only
+  // a number (2026-10-06): which setup step was reached.
+  ipcMain.handle('zero:track', (_e, { name, count } = {}) => {
     if (!EVENT_NAMES.includes(name)) return false;
-    return analytics.track(name);
+    return analytics.track(name, Number.isFinite(count) ? { count } : undefined);
   });
 
+  // WHETHER A COUNT CAME FROM SETUP'S PRACTICE PROJECT, read off the project's
+  // own flag rather than its name, so the walkthrough and real use part.
+  const isPractice = (slug) => {
+    try { return store.listProducts().some((p) => p.slug === slug && p.practice === true); } catch { return false; }
+  };
+
   ipcMain.handle('zero:approve', (_e, { id, allow, note }) => {
     return { ok: answerApproval(id, allow, note) };
   });
@@ -304,17 +319,32 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     const agent=id.startsWith('agent:')?liveAgents().find(a=>'agent:'+a.pid===id && (a.product??'')===product):null;
     return terminalPlace({store,supervisor,product,id,agent});
   }});
+  const agentUpdates=new AgentUpdates({
+    installation:async engine=>{if(engine==='claude')recheckClaude(config);else recheckCodex(config);return installedAgent(engine,config);},
+    refresh:async engine=>{if(engine==='claude')recheckClaude(config);else recheckCodex(config);await refreshAgentModels(engine,config,supervisor._codexHome());if(engine==='codex')for(const profile of supervisor._codexProfiles())supervisor._releaseIdleCodex(profile);},
+  });
+  ipcMain.handle('zero:agent-update',async(event,{engine,action}={})=>{
+    if(event.senderFrame?.parent||(event.sender&&event.sender!==window.webContents))throw Error('Updates are only available in the main app window.');
+    if(!['claude','codex'].includes(engine))throw Error('Unknown agent.');
+    if(action==='check')return agentUpdates.check(engine);
+    if(action==='recheck')return agentUpdates.check(engine,true);
+    if(action==='start')return agentUpdates.start(engine);
+    if(action==='status')return agentUpdates.status(engine);
+    if(action==='refresh'){await refreshAgentModels(engine,config,supervisor._codexHome());return true;}
+    throw Error('Unknown update action.');
+  });
   let terminalQuitPending=false,terminalQuitReady=false;
   app.on('before-quit',event=>{
-    if(terminalQuitReady||(!terminalQuitPending&&!terminals.sessions.size))return;
+    if(terminalQuitReady||(!terminalQuitPending&&!terminals.sessions.size&&!agentUpdates.terminals.sessions.size))return;
     event.preventDefault();
-    if(!terminalQuitPending){terminalQuitPending=true;void terminals.shutdown().finally(()=>{terminalQuitReady=true;app.quit();});}
+    if(!terminalQuitPending){terminalQuitPending=true;void Promise.all([terminals.shutdown(),agentUpdates.shutdown()]).finally(()=>{terminalQuitReady=true;app.quit();});}
   });
   ipcMain.handle('zero:terminal',(_event,payload={})=>{
     if(_event.senderFrame?.parent || (_event.sender && _event.sender!==window.webContents)) throw Error('Terminal is only available in the main app window.');
     const {product,id,action,data,cols,rows,offset}=payload;
     if(typeof product!=='string'||typeof id!=='string'||!id||id.length>300)throw Error('Invalid task.');
     const key=JSON.stringify({product,id});
+    if(product==='@agent-update')return agentUpdates.terminal(id,payload);
     switch(action){
       case 'open':return terminals.open(key);
       case 'read':return terminals.read(key,offset);
@@ -325,6 +355,11 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     }
   });
 
+  // The Done and All tabs' next page of finished threads the snapshot's 8 MB
+  // read left out, asked for as she scrolls to their foot (main/store.mjs).
+  ipcMain.handle('zero:older-items', (_e, { offset = 0, limit = 50 } = {}) =>
+    store.listOlderItems({ offset: Number(offset) || 0, limit: Math.min(Number(limit) || 50, 200) }));
+
   ipcMain.handle('zero:snapshot', () => {
     const now = Date.now();
     const items = store.listItems(now);
@@ -345,6 +380,10 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     return {
       products: store.listProducts(),
       items,
+      // THE TEAM: who is signed in, their team and its people, and the
+      // title-free activity of their private work. Null on a build with no
+      // team cloud, which is the single-person app.
+      team: team ? team.state() : null,
       agents: liveAgents(),
       approvals: approvals.listPending(config.storeRoot),
       supervisor: running,
@@ -361,6 +400,17 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
       // coding agent this is one entry and an empty map, and nothing anywhere
       // draws anything new.
       engines,
+      // WHICH SUBSCRIPTION ALL OF THIS IS RUNNING ON (w-e217e577e5, 2026-10-07).
+      // A new user watched agents work and could not tell what was powering
+      // them, because the app finds whichever sign-in is already on the Mac and
+      // spends it in silence.
+      //
+      // It rides the snapshot rather than the settings model because the SIDEBAR
+      // reads it, which is on screen the whole time, and the settings model is
+      // only fetched while that screen is open. It costs no file read per tick:
+      // `main/runs-on.mjs` caches on the login files' own modification times, so
+      // this re-parses only after a sign-in or a profile refetch.
+      runsOn: supervisor.runsOnAccount(engines.workspace),
       // Whether this process is still the app on disk. It rides the snapshot
       // rather than boot-info because the staleness DEVELOPS while the app
       // runs: the case that cost her three times was a process left up for days
@@ -414,23 +464,22 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     };
   });
 
-  // HER WORDS, INTO A LIVE AGENT OF HERS. The only thing in the app that writes
+  // THE USER'S WORDS, INTO ONE OF THEIR LIVE AGENTS. The only thing in the app that writes
   // anywhere outside its own store, and it writes into a socket rather than to
   // disk. The reader refuses a send to an agent frozen on a permission box, and
   // reports back whether the agent actually moved rather than assuming it did.
   ipcMain.handle('zero:agent-reply', async (_e, { pid, text }) => {
     try {
       const out = await agents.reply(Number(pid), text);
-      // AND THE ROW REMEMBERS THAT SHE SPOKE. Only on a delivered message: a
+      // AND THE ROW REMEMBERS THAT THE USER SPOKE. Only on a delivered message: a
       // mark written for a send that failed would move the row into In progress
       // over words that never arrived, which is the failure this codebase cares
-      // about most.It does now, until the session stops. AND WHAT SHE TYPED,
-      // not only that she typed. Claude Code marks a message arriving over its
-      // socket as machine chatter (`isMeta`), so the transcript reader drops it
-      // and her own sentence never reached the card: she sent session-67 two
-      // messages on 2026-08-17 and the row went on saying only what she had
-      // started it with four days before. This is the only process that knows
-      // she said it, so this is where it is written.
+      // about most. It does now, until the session stops. AND WHAT THE USER
+      // TYPED, not only that they typed. Claude Code marks a message arriving over
+      // its socket as machine chatter (`isMeta`), so the transcript reader drops
+      // it and the user's own sentence never reached the card: the row went on
+      // saying only what the session was started with days before. This is the
+      // only process that knows the user said it, so this is where it is written.
       if (out?.ok && out.key) agentSchedule.replied(out.key, out.at ?? Date.now(), Date.now(), String(text ?? ''));
       push();
       return out;
@@ -491,8 +540,17 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   ipcMain.handle('zero:compact', (_e, { product, id }) => supervisor.compactItem(product, id));
   ipcMain.handle('zero:compaction-status', (_e, { product, id }) => supervisor.compactionStatus(product, id));
 
-  ipcMain.handle('zero:answer', async (_e, { product, id, answer, status, priority, permissionMode, model, effort }) => {
+  // Send now: cut the running agent's current step so her waiting message is
+  // answered at once (supervisor.sendNow).
+  ipcMain.handle('zero:send-now', (_e, { product, id }) => supervisor.sendNow(product, id));
+
+  ipcMain.handle('zero:answer', async (_e, { product, id, answer, status, priority, permissionMode, model, effort, now, inReplyTo }) => {
     if (isAgentRow(id)) return { ok: false };
+    // A REPLY IN A THREAD (w-920461cbe6) only means something in a conversation
+    // between people, which is the only place a thread is drawn and the only
+    // record the mark crosses to a teammate in (shared/team-rules.mjs). Anywhere
+    // else it is dropped and the words go in as an ordinary reply.
+    const thread = typeof inReplyTo === 'string' && inReplyTo && productOf(product)?.team?.direct ? inReplyTo : undefined;
     // A CODEX CONVERSATION'S YES OR NO NEVER REACHES A WORKER. The row asking
     // whether to import one is answered by the app itself: yes makes it a row
     // she can read, no parks it in Closed under Not imported, and Import on a
@@ -524,11 +582,15 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     // handing them over in one call and writing the model afterwards would be a
     // race the run usually wins, so she would pick a model and watch the old one
     // take the task. `answerItem` writes both, and it writes the model first.
-    const out = await submitReply(supervisor,{product,id,answer,status,permissionMode},()=>store.answerItem(product, id, { answer, status, priority, permissionMode, model, effort }));
-    // THAT she replied and THAT something finished. Never a word of either:
+    const out = await submitReply(supervisor,{product,id,answer,status,permissionMode,now:!!now},()=>store.answerItem(product, id, { answer, status, priority, permissionMode, model, effort, inReplyTo: thread }));
+    // A REPLY ON A ROW A TEAMMATE GAVE YOU HANDS IT BACK TO THEM, so the
+    // conversation moves to their inbox instead of sitting in both
+    // (shared/team-rules.mjs handedOnByReply). Archiving hands nothing on.
+    if (team && status !== 'done' && typeof answer === 'string' && answer.trim()) handOnByReply(product, id);
+    // THAT the user replied and THAT something finished. Never a word of either:
     // in Agentbox the answer IS the prompt (privacy page, section 4).
-    if (typeof answer === 'string' && answer.trim()) analytics.track('reply_sent');
-    if (status === 'done') analytics.track('task_finished');
+    if (typeof answer === 'string' && answer.trim()) analytics.track('reply_sent', { practice: isPractice(product) });
+    if (status === 'done') analytics.track('task_finished', { practice: isPractice(product) });
     // HER REPLY IS THE OTHER HALF OF THE SAME WAIT, and it is the one she pays
     // on every round trip rather than once: measured 2026-08-24, median 9.1
     // seconds between pressing the key and the continuation being spawned.
@@ -555,13 +617,141 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     return supervisor.status();
   });
 
-  ipcMain.handle('zero:compose', (_e, { product, title, body, kind, priority, runAt, labels, engine, model, effort }) => {
+  // WHO IS SIGNED IN, and the project a row is in, for the team's rules.
+  const teamMe = () => team?.state()?.me?.id ?? null;
+  const productOf = (slug) => store.listProducts().find((p) => p.slug === slug) ?? null;
+
+  function handOnByReply(product, id) {
+    try {
+      const row = store.readItem(product, id);
+      const next = row && handedOnByReply(row, productOf(product), teamMe());
+      if (next) store.teamPatch(product, id, { assignee: next });
+    } catch (err) {
+      console.warn(`team: could not hand ${id} on: ${err.message}`);
+    }
+  }
+
+  // FEEDBACK, from the card the sidebar's Feedback row opens (w-1b574413db).
+  // main/feedback.mjs decides where it goes and whether it may; the version
+  // and the macOS release ride along so a report can be matched to a build.
+  ipcMain.handle('zero:send-feedback', async (_e, { text, files } = {}) => sendFeedback({
+    url: feedbackUrl(config),
+    payload: feedbackPayload({ text, files, app: { version: app.getVersion(), os: `${process.platform} ${os.release()}` } }),
+  }));
+
+  // THE TEAM'S DOORS. Each answers { ok, team } or { ok: false, error } with
+  // the error in words, so the window can say what went wrong where it
+  // happened instead of a row silently not appearing.
+  const teamCall = (fn) => async (_e, arg) => {
+    if (!team) return { ok: false, error: 'This build has no team cloud set up.' };
+    try {
+      await fn(arg ?? {});
+      push();
+      return { ok: true, team: team.state() };
+    } catch (err) {
+      return { ok: false, error: String(err?.message ?? err), team: team.state() };
+    }
+  };
+  // Signing in finishes in the browser, so the app comes back to the front
+  // when it lands rather than leaving the person to find it.
+  ipcMain.handle('zero:team-sign-in', teamCall(async () => {
+    await team.signIn();
+    try { if (window?.isMinimized?.()) window.restore(); window?.show?.(); app?.focus?.({ steal: true }); } catch { /* no window to raise */ }
+  }));
+  ipcMain.handle('zero:team-sign-in-cancel', teamCall(() => team.cancelSignIn()));
+  ipcMain.handle('zero:team-sign-in-reopen', teamCall(() => team.reopenSignIn()));
+  ipcMain.handle('zero:team-sign-out', teamCall(() => team.signOut()));
+  ipcMain.handle('zero:team-sign-in-email', teamCall(({ email, password }) => team.signInWithEmail(email, password)));
+  // Its own door, because it has one more thing to say: whether the account
+  // waits on the link in its confirmation email.
+  ipcMain.handle('zero:team-sign-up', async (_e, { email, password, name } = {}) => {
+    if (!team) return { ok: false, error: 'This build has no team cloud set up.' };
+    try {
+      const out = await team.signUp(email, password, name);
+      push();
+      return { ok: true, team: team.state(), confirm: !!out?.confirm };
+    } catch (err) {
+      return { ok: false, error: String(err?.message ?? err), team: team.state() };
+    }
+  });
+  ipcMain.handle('zero:team-create', teamCall(({ name }) => team.createTeam(name)));
+  // An invite answered yes. Nothing else joins a team.
+  ipcMain.handle('zero:team-accept-invite', teamCall(({ teamId }) => team.acceptInvite(teamId)));
+  ipcMain.handle('zero:team-invite', teamCall(({ email }) => team.invite(email)));
+  ipcMain.handle('zero:team-rename', teamCall(({ name }) => team.renameTeam(name)));
+  ipcMain.handle('zero:team-remove-member', teamCall(({ personId }) => team.removeMember(personId)));
+  ipcMain.handle('zero:team-leave', teamCall(() => team.leaveTeam()));
+  ipcMain.handle('zero:team-cancel-invite', teamCall(({ email }) => team.cancelInvite(email)));
+  // A line you write about yourself, so a day in meetings is not read off
+  // the Team page as idleness.
+  ipcMain.handle('zero:team-status', teamCall(({ text, hold, until }) => team.setStatus({ text, hold, until })));
+  ipcMain.handle('zero:team-share', teamCall(({ product, visibility, people }) => team.share(product, { visibility, people })));
+  ipcMain.handle('zero:team-sync', teamCall(() => team.syncNow()));
+  // A MESSAGE TO A PERSON (approved 2026-10-01: people get messages, never
+  // tasks). main/team/index.mjs keeps it between the two of them.
+  ipcMain.handle('zero:team-message', teamCall(({ to, body, priority }) => team.message(to, body, priority)));
+  // AN EDIT TO A THREAD, MADE IN PLACE from its summary: the summary's lines,
+  // who sees it, its priority and what it is linked to. Works with or without a
+  // team, since every thread has a summary.
+  ipcMain.handle('zero:thread-edit', (_e, { product, id, patch }) => {
+    try {
+      store.threadEdit(product, id, patch);
+      push();
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: String(err?.message ?? err) };
+    }
+  });
+  // A TASK A TEAMMATE GAVE YOU, ROUTED WITH ONE KEY. To an agent: it runs on
+  // your Mac (you become its runner). Keep it: it stays yours and the routing
+  // choices go away. Hand it back: it returns to whoever gave it to you.
+  ipcMain.handle('zero:team-route', teamCall(({ product, id, route }) => {
+    const me = teamMe();
+    if (!me) throw new Error('sign in first');
+    const row = store.readItem(product, id);
+    if (!row) throw new Error('that task is gone');
+    if (row.assignee !== me) throw new Error('this task is not yours to route');
+    if (route === 'agent') store.teamPatch(product, id, { assignee: 'agent', runner: me });
+    else if (route === 'me') store.teamPatch(product, id, { assignee: me });
+    else if (route === 'back') {
+      const to = (row.people ?? []).find((p) => p !== me) || row.createdBy;
+      if (!to || to === me) throw new Error('there is nobody to hand it back to');
+      store.teamPatch(product, id, { assignee: to });
+    } else throw new Error(`unknown route ${route}`);
+    supervisor.wake();
+  }));
+
+  // PUT A REACTION ON ONE MESSAGE, OR TAKE YOURS BACK (w-560647d4db). Only in a
+  // conversation between people, because a chip is only ever drawn in one: the
+  // sync carries a reaction across in a message record and nowhere else
+  // (shared/team-rules.mjs), so one written anywhere else would sit on this Mac
+  // alone and look to its author like it had reached somebody.
+  ipcMain.handle('zero:team-react', teamCall(async ({ product, id, on, emoji, off }) => {
+    const me = teamMe();
+    if (!me) throw new Error('sign in first');
+    const row = store.readItem(product, id);
+    if (!row) throw new Error('that conversation is gone');
+    const here = store.listProducts().find((p) => p.slug === product);
+    if (!here?.team?.direct) throw new Error('reactions are for a conversation with a teammate');
+    store.react(product, id, { on, emoji, off });
+    await team.syncNow();
+  }));
+
+  ipcMain.handle('zero:compose', (_e, { product, title, body, kind, priority, runAt, start, labels, engine, model, effort, assignee, due, visibility, visibleTo }) => {
     const out = store.composeItem(product, {
       // HOW HARD IT THINKS rides through unjudged: the store keeps any word
       // shaped like a level, and the spawn is the gate that knows each
       // engine's real list (`Supervisor#spawnPlan` for Claude Code,
       // `codexEffortRefusal` for Codex).
-      title, body, kind, priority, runAt, labels, effort,
+      title, body, kind, priority, runAt, start, labels, effort,
+      // WHO DOES IT, when it is a person (the team version): the teammate it
+      // goes to and the day it is due, and the two of you as the conversation,
+      // so a reply can hand it back. An agent's row carries none of these.
+      assignee, due, visibility,
+      // AND WHO MAY SEE IT, when she chose people rather than the team
+      // (w-41ff964775). The store keeps the list only beside 'people'.
+      visibleTo,
+      people: assignee && teamMe() ? [teamMe(), assignee] : undefined,
       // WHICH CODING AGENT SHE CHOSE, AND ONLY IF SHE COULD HAVE. `engineOffered`
       // is the supervisor's own test and the door makes no judgement of its own:
       // it answers null on any Mac where the picker is not drawn, so a renderer
@@ -576,12 +766,17 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
       // fields cannot be corrected separately.
       model: supervisor.modelOffered(engine, model),
     });
+    // A real thread ends the walk's hold on agents (`Supervisor#sentByThem`).
+    supervisor.sentByThem(labels);
+    // THAT a task was written, and whether in practice. Never its words.
+    analytics.track('task_written', { practice: isPractice(product) });
     // AND LOOK AT IT NOW. Composing used to write the line and stop, so the
     // task sat in the store until the next fifteen second tick: measured
     // 2026-08-24, median 7.0 seconds and up to 15.0 before the spawn was even
     // attempted. A row scheduled for later is not woken for, because it is not
     // due; the timer is what serves those.
-    if (!runAt || runAt <= Date.now()) supervisor.wake();
+    // Nothing to wake for a thread added to Later: it starts when she says.
+    if (start !== 'later' && (!runAt || runAt <= Date.now())) supervisor.wake();
     return out;
   });
 
@@ -591,8 +786,8 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   // The whole of the work is reading the readme in the folder chosen two
   // screens earlier, so this returns in milliseconds. The two second pause
   // before it is called is in the renderer, where the row is being watched.
-  ipcMain.handle('zero:first-run-answer', (_e, { product, id }) => {
-    return store.finishFirstRunTask(product, id);
+  ipcMain.handle('zero:first-run-answer', (_e, { product, id, round = 0 }) => {
+    return store.finishFirstRunTask(product, id, round);
   });
 
   // THE PRACTICE PROJECT.Made when the hand-off screen is pressed, filled with
@@ -606,7 +801,12 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     // somebody mid-walk. They land in an empty practice inbox and the beat that
     // clears them is skipped, exactly as beat thirteen already behaves.
     try { rows = store.stagePracticeRows(made.slug); } catch { rows = { ids: [] }; }
-    return { ...made, examples: rows.ids };
+    // AND THE REST OF THE PRACTICE TEAM'S WORK, so the tour and the board have
+    // something in every column (w-58c8f466e7). Its own try: a store that will
+    // not take these still leaves the walk its four rows.
+    let backdrop = { ids: [] };
+    try { backdrop = store.stagePracticeBackdrop(made.slug); } catch { backdrop = { ids: [] }; }
+    return { ...made, examples: rows.ids, backdrop: backdrop.ids };
   });
 
   // AND TAKING IT BACK OFF THE SCREEN. `sweepPractice` rather than the one
@@ -640,6 +840,7 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   ipcMain.handle('zero:open-fresh-user', (_e, payload) => {
     return openFreshUser({
       withAgents: payload?.withAgents !== false,
+      withTools: payload?.withTools !== false,
       packaged: app.isPackaged,
     });
   });
@@ -661,6 +862,14 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     return store.scheduleItem(product, id, runAt);
   });
 
+  // Snooze changes when a person sees the thread, never what an agent does.
+  ipcMain.handle('zero:snooze', (_e, { product, id, snoozedUntil }) => {
+    if (isAgentRow(id)) return { ok: false };
+    const item = store.snoozeItem(product, id, snoozedUntil);
+    push();
+    return item;
+  });
+
   // said about an agent instead of about a task. The row it moves stands for
   // somebody's terminal, so this writes to no ledger, sends no message and
   // stops no process: it records the moment her inbox should raise the agent
@@ -869,10 +1078,10 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   // feel instant. The card read them a moment before pressing, so the last read
   // is the right answer and it is ours rather than the renderer's.
   let lastThreads = [];
-  // HER CODEX CONVERSATIONS ARE ON THE SAME CARD. They carry `source:
+  // THE USER'S CODEX CONVERSATIONS ARE ON THE SAME CARD. They carry `source:
   // 'codex'`, land under the project whose folder they ran in exactly as the
-  // Claude Code ones do, and the ones she said not now to are here too, which
-  // is the way back she asked for.
+  // Claude Code ones do, and the ones the user said not now to are here too, so
+  // there is a way back to them.
   const readAllThreads = () => {
     let claude = [];
     let codex = [];
@@ -883,7 +1092,11 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   ipcMain.handle('zero:agent-threads', () => {
     const threads = readAllThreads();
     lastThreads = threads;
-    return { threads };
+    // Each one already in the inbox says so, and the card leaves it out
+    // (w-db6f5e331e). The walk's folder suggestions still read all of them.
+    let items = [];
+    try { items = store.listItems(); } catch { items = []; }
+    return { threads: markImported(threads, items) };
   });
 
   // So this is `zero:import-agents` with the agent taken out of it. No ticks are
@@ -924,7 +1137,7 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
   // `projectAgents` and stopped. Three occurrences of that key in the whole
   // shipped app, all of them this file and settings.mjs, and none in the
   // renderer: the list was read back only so the card could remember its own
-  // ticks the next time somebody walked the setup. Measured on the build David
+  // ticks the next time somebody walked the setup. Measured on the build a tester
   // used, the store was byte for byte identical before and after pressing it.
   //
   // The names are still saved, because the card still opens on what was taken
@@ -976,6 +1189,12 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     return store.answerItem(product, id, { status: 'blocked' });
   });
 
+  // Run now, from the three-dot menu on a waiting task (supervisor.runNow).
+  ipcMain.handle('zero:run-now', (_e, { product, id }) => {
+    if (isAgentRow(id)) return { ok: false, reason: 'missing' };
+    return supervisor.runNow(product, id);
+  });
+
   // Send a stopped/blocked item back to the queue; the fresh worker's brief
   // carries whatever the founder wrote on the item meanwhile.
   ipcMain.handle('zero:reopen', (_e, { product, id }) => {
@@ -1096,6 +1315,45 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     }
   });
 
+  // SETTING UP THEIR PLAN FOR THEM (w-9f6975906c). The walk asks which plan
+  // they pay for and this installs the tool and starts its own sign-in. The
+  // finder is the recheck, so what gets installed lands on the config and the
+  // rest of the app runs on it without a restart.
+  const engineSetup = createEngineSetup({
+    find: (engine) => {
+      if (engine === 'claude') { const s = recheckClaude(config); return { found: s.claudeFound, path: s.claudeBin }; }
+      const s = recheckCodex(config);
+      return { found: s.found, path: s.bin };
+    },
+    // WHICH ONE IS SIGNED IN, kept on the config for the run that reads it
+    // (`Supervisor#_enginesFound`) and never saved: it changes outside the app.
+    onSignIn: (engine, signedIn) => {
+      config[`${engine}SignedIn`] = signedIn;
+    },
+  });
+  // ASKED ONCE AT LAUNCH, and only on a Mac with both, which is the only Mac
+  // where the answer moves a task (w-d5d632e503): a tester who pays for
+  // ChatGPT had the Claude app's copy of Claude Code, never signed in, so
+  // every task went to Claude Code and Codex was never offered.
+  if (config.claudeFound && config.codexBin) {
+    void engineSetup.signedInNow('claude', config.claudeBin);
+    void engineSetup.signedInNow('codex', config.codexBin);
+  }
+  // A sign-in left waiting on the browser is not left running after the app.
+  app.on('will-quit', () => { engineSetup.cancel('claude'); engineSetup.cancel('codex'); });
+  ipcMain.handle('zero:engine-setup', async (_e, { action, engine } = {}) => {
+    if (engine !== 'claude' && engine !== 'codex') return { ok: false, error: 'Unknown coding agent.' };
+    try {
+      if (action === 'ready') return { ok: true, ...(await engineSetup.readiness(engine)) };
+      if (action === 'start') return { ok: true, ...engineSetup.start(engine) };
+      if (action === 'again') return { ok: true, ...engineSetup.signInAgain(engine) };
+      if (action === 'cancel') return { ok: true, ...engineSetup.cancel(engine) };
+      return { ok: true, ...engineSetup.status(engine) };
+    } catch (err) {
+      return { ok: false, error: String(err.message) };
+    }
+  });
+
   /* * ADD A CODEX ACCOUNT: make the folder, register the login, hand back the one line the
      terminal has to run.
   */
@@ -1166,7 +1424,7 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
       const dir = productDirOf(product);
       if (!dir) return { ok: false, error: 'That project could not be found.' };
       const saved = setProjectName(dir, name);
-      // PUSH, because the name is on far more than the screen she typed it on:
+      // PUSH, because the name is on far more than the screen it was typed on:
       // the rail, every row's byline, the composer's picker and ⌘K all print it,
       // and a rename that only redrew Settings would leave the rest of the app
       // calling it the old thing until something else happened to refresh.
@@ -1177,6 +1435,32 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     }
   });
 
+  // ARCHIVE A PROJECT, OR BRING ONE BACK (main/store.mjs setProductArchived).
+  // Its files stay on disk; it leaves every list the app draws. Pushed for the
+  // same reason a rename is: the rail, the inbox and the picker all list it.
+  ipcMain.handle('zero:project-archive', (_e, { product, archived } = {}) => {
+    try {
+      store.setProductArchived(product, archived === true);
+      push();
+      return { ok: true, ...readSettings({ config, supervisor, store }) };
+    } catch (err) {
+      return { ok: false, error: String(err.message) };
+    }
+  });
+
+  // WHO SEES A PROJECT'S THREADS (main/store.mjs setProductSeenBy,
+  // w-b989839656). Pushed, because the inbox's locks and the New thread
+  // card's starting chip both read it off the snapshot's projects.
+  ipcMain.handle('zero:project-seen-by', (_e, { product, who, people } = {}) => {
+    try {
+      store.setProductSeenBy(product, { who, people });
+      push();
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: String(err.message) };
+    }
+  });
+
   // Opens the picker AND does the copy, in one round trip. Two handlers would
   // mean the renderer briefly holds a path into her Downloads folder and hands
   // it back to be trusted; this way the only path that crosses the bridge is one
@@ -1248,10 +1532,10 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     for (const file of files ?? []) {
       const safe = String(file.name ?? 'file').replace(/[^\w.-]+/g, '-').slice(0, 80);
       // A RANDOM SUFFIX, THE SAME ONE THE STAGING PATH ALREADY USES. The name
-      // was the millisecond plus her filename, so two files saved in the same
+      // was the millisecond plus the filename, so two files saved in the same
       // millisecond with the same name overwrote each other and the message
-      // ended up with two links to one picture. She sends screenshots in pairs,
-      // which is exactly the shape that collides. It has never been observed
+      // ended up with two links to one picture. Screenshots are often sent in
+      // pairs, which is exactly the shape that collides. It has never been observed
       // happening; it is one line to make impossible.
       const rel = `attachments/${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}-${safe}`;
       const abs = path.join(dir, rel);
@@ -1265,13 +1549,12 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
 
   // A PASTED SCREENSHOT GOES TO DISK THE MOMENT IT IS PASTED.
   //
-  // She was right and the constraint was ours. Pasted bytes used to ride in the
-  // draft as base64, and a draft lives in localStorage, whose quota MEASURED on
-  // this machine is 5,241,856 characters for the WHOLE app. Seven of the
-  // ninety-one screenshots she has actually pasted are over that; the largest
-  // is 6.08 MB.
+  // The constraint was ours. Pasted bytes used to ride in the draft as base64,
+  // and a draft lives in localStorage, whose quota MEASURED on this machine is
+  // 5,241,856 characters for the WHOLE app. Ordinary full-screen screenshots
+  // are regularly over that; 6 MB is not unusual.
   //
-  // Raising the number cannot reach her bar: even the whole quota is under 4 MB
+  // Raising the number cannot reach that bar: even the whole quota is under 4 MB
   // of image, and Claude's own limit is 10 MB base64 per image (about 7.5 MB of
   // file) at up to 8000x8000. localStorage is simply the wrong place for image
   // bytes. So they go here instead, and the draft keeps a path — which the draft
@@ -1408,6 +1691,16 @@ export function registerIpc({ store, supervisor, config, window, analytics = NO_
     return err ? { ok: false, error: err } : { ok: true, opened: found.path };
   });
 
+  // THE PICTURES IN A FOLDER A MESSAGE NAMES, so the folder line draws them
+  // (FolderPreview in Focus.tsx). Only pictures, only inside this product.
+  ipcMain.handle('zero:folder-pictures', (_e, { product, src } = {}) => folderPictures({
+    src,
+    product,
+    products: store.listProducts(),
+    accountRoot: config.accountRoot,
+    storeRoot: config.storeRoot,
+  }));
+
   // THE DOCUMENT PANE READS AND WRITES THE FILE ITSELF. A path goes through
   // the very same finder the links and the chips use, so the pane opens
   // exactly the file a click would have opened, and then main hands back the