agentbox-app 0.1.6

package/shared/first-run-practice.mjs

@@ -0,0 +1,254 @@
+// THE PRACTICE PROJECT.
+//
+// So this is not a mock and not a card. It is a real project in the real store,
+// with real work items in it, and the whole app is scoped to it for the length
+// of the walk. What tells somebody it is not theirs is a band across the top
+// that never leaves, not the size of it.
+//
+// WHY IT EXISTS AT ALL is David, on the call of 2026-08-23: he opened Agentbox,
+// saw a real task on a real screen and read it as work. His words were that he
+// thought the task was to set up the project and that it was asking him
+// questions to do the setup, and he tried to answer the placeholder text.
+//
+// Everything here is content, no window and no filesystem, so both halves can
+// read it: the renderer draws the walk off ../renderer/src/onboarding.ts and
+// the main process writes the rows off here.
+
+/**
+ * What the practice project is called, on its own row in the rail and in the
+ *  compose card. The slug is derived from it the same way any project's is. */
+import { NAME } from '../shared/product-name.mjs';
+export const PRACTICE_NAME = 'Practice';
+export const PRACTICE_SLUG = 'practice';
+
+/**
+ * The mark in project.json. `listProducts` reads it out so the rest of the app
+ *  can tell a practice project from a real one without matching on a name
+ *  somebody could give a real project of their own. */
+export const PRACTICE_FLAG = 'practice';
+
+/**
+ * THE ONE TASK THEY SEND THEMSELVES. Written for them, because the beat is
+ *  about pressing ⌘↵ and not about thinking of something to ask.
+ *
+ * AND IT NAMES THE PRETEND APP, WHICH IS THE WHOLE FIX. It read `Add a sign-out
+ * button to the header.` over `This one is written for you. Both halves failed
+ * her at once. The title is an imperative sentence with no subject and no app
+ * in it, so the only app on the screen — the one she is looking at — is the one
+ * it appears to be about; and the reassurance underneath is about the CARD
+ * rather than about the sentence above it, so it reads as being about some
+ * other thing entirely.
+ *
+ *  IT STAYS A REQUEST, AND THAT IS DELIBERATE. It was written in the past tense
+ *  for one build, to match the four rows already waiting in the practice
+ *  inbox, and it broke the beat it belongs to. THIS IS THE ONE ROW SHE SENDS:
+ *  she reads it, presses ⌘↵ on a button that says `Start it`, and two seconds
+ *  later `PRACTICE_ANSWER` comes back saying `Done, and the tests pass.` A
+ *  title reading `Added a sign-out button` sits above a Start button asking her
+ *  to start something the card says is already finished, and is then answered
+ *  `Done`; the three sentences stop making sense as a sequence. The other four
+ *  rows are past tense because they are already answered when she meets them.
+ *  This one is a request because a request is what it is, and every real work
+ *  item in Agentbox is named that way.
+ *
+ *  SO THE APP'S NAME IS THE FIX, NOT THE TENSE. `Practice` is the pretend project — the name in the
+ *  rail, in the band across the top, in the compose card's own "For Practice."
+ *  clause, and in the sidebar note's `practice.local:4000`. There is no second
+ *  pretend name to invent; the one the walk already says everywhere is the one
+ *  that goes in the sentence. The body then says the two things that kill her
+ *  reading outright: it is not her code, and it is not Agentbox.
+ *
+ *  BOTH STRINGS SHOW AT ONCE. `Compose` types the title into the box and then
+ *  appends a blank line and the body (renderer/src/components/Compose.tsx), so
+ *  what she reads at beat ten is these two paragraphs together, under the
+ *  practice band and over a "Start it ⌘↵" button. They have to make sense as
+ *  one card, which is why the body opens by naming the app the title names. */
+export const PRACTICE_TASK = {
+  title: 'Add a sign-out button to the Practice app.',
+  body: `Practice is a pretend project, not your code and not ${NAME}. This one is written for you already.`,
+};
+
+/**
+ * AND WHAT COMES BACK. The old walk read a readme out of the folder they chose
+ *  (main/first-run.mjs) because the task ran against their own project. This
+ *  one runs against a project that is not real, so the answer is written down
+ *  here: it is a decision an agent made on its own and told them about, which
+ *  is the shape the next beat teaches them to close.
+ *
+ * IT STILL TAKES TWO SECONDS AND IT IS STILL A REAL ROW WITH A REAL RESULT ON
+ * THE REAL LEDGER.*/
+export const PRACTICE_ANSWER =
+  'Done, and the tests pass. I put it next to the avatar rather than inside the menu. Say the word and I will move it.';
+
+/**
+ * WHAT IS IN THE PRACTICE PROJECT'S SIDEBAR NOTE.
+ *
+ * AND IT IS NOT A GOALS FORM, which is what the first cut of it turned into. The
+ * sentence above is her saying what SHE keeps in hers, as an example; the note
+ * that shipped had two headings, **Goals this week** and **Next steps**, and
+ * nothing else, which reads as the two things this panel is for. So the sample
+ * shows a MIX now — a decision, a number, a link, one thing to do next —
+ * because the lesson is that anything can go here, and a sample of one kind
+ * teaches the opposite.
+ *
+ *  So the practice project's note is not a placeholder and not a lorem line. It
+ *  is what a founder's own note looks like, and it is on the screen for every
+ *  beat of the practice, because the panel it draws in is per project and the
+ *  whole app is scoped to this one while the walk is on.
+ *
+ *  IT IS THE SAME TEXT IN BOTH PLACES. `createPractice` writes it to the
+ *  project's `pinned.md`, which is the real file the sidebar reads
+ *  (main/rail-note.mjs), and the third introduction slab draws it beside the
+ *  words. A note the introduction promises and the practice project then does
+ *  not have is the sort of quiet lie the walk has been caught in twice.
+ *
+ *  SHORT ON PURPOSE. The panel is 322px wide with 12px of padding either side,
+ *  so a line much past forty characters wraps, and a wrapped goal reads as a
+ *  paragraph rather than a goal. */
+export const PRACTICE_NOTE = [
+  'Sessions are cookies, not tokens.',
+  '',
+  '15 new users this week. At 6.',
+  '',
+  'Staging: practice.local:4000',
+  '',
+  'Next: talk to the five who churned.',
+].join('\n');
+
+/* * * THE FOUR WAITING ROWS, and processing them is the point of beats thirteen, * fourteen
+ and fifteen. * * EACH ONE IS A WHOLE CONVERSATION NOW, NOT A TITLE AND A LINE.What she had
+ * opened was beat twelve, where the reading pane said "Nothing has been said * here yet."
+ under the title. These rows were a title, a one-line result and * nothing else, so the one
+ surface in the whole walk that shows what Agentbox * actually holds was blank. * * So every
+ row carries three things: `body`, the sentence a person typed to * start it; `trace`, the
+ lines the run wrote while it worked, in the exact * shape `traceStreamLine` in
+ main/supervisor.mjs writes a real one; and * `result`, the finished word. The store writes
+ all three (`stagePracticeRows` * and the trace beside it), and the reading pane draws them
+ with the same * components it draws a real run with. NOTHING IS MOCKED AND NO COMPONENT *
+ KNOWS THESE ROWS EXIST. * * THE TRACE LINE FORMAT IS NOT DECORATION. `HH:MM:SS [Tool]
+ argument` is what * the supervisor writes and what renderer/src/item-thread.ts parses back
+ into * the quiet work lines of a thread; a line that is not a tool call is the * agent
+ talking. Get the two spaces wrong and the thread draws the timestamp * as part of the
+ sentence. * * THEY NO LONGER SAY "Example" IN THEIR OWN TITLES, and that is a deliberate *
+ change with her older word behind it. These sit in a project called Practice, * under a
+ band reading "nothing in here is saved", in a walk that said the same * thing on a screen
+ of its own two beats earlier. The band is the stronger * version of her fix, and it is on
+ screen the whole time. The old copy is kept * in decisions.md, 2026-08-23. * * AND EACH ONE
+ IS A DIFFERENT SHAPE, WITH A DIFFERENT RIGHT MOVE ON IT. The * flags are fields here rather
+ than guesses made from the kind, because which * row is which IS the lesson and it must not
+ be inferable wrongly: * * two are FINISHED, and E is right on them (`clear`) * one is
+ `later`, real work that is nobody's emergency (`snooze`) * one is `waiting`, an agent
+ stopped on a question (`unblock`) * * Closing the last two is the one move the product
+ exists to stop somebody * making, which is why they get beats of their own rather than a
+ fourth press * of E.
+*/
+export const PRACTICE_ROWS = [
+  {
+    kind: 'task',
+    title: 'Added the sign-in route. Tests green.',
+    body: 'Add a sign-in route at /sign-in. Reuse whatever we already have for sessions.',
+    trace: [
+      'Reading how auth works here before I touch anything.',
+      '[Read] src/server/auth.ts',
+      '[Read] src/server/routes.ts',
+      '[Grep] createSession',
+      'There is already a signed session cookie in here, seven days, refreshed on use. I will reuse it rather than adding tokens, because two ways to be signed in is the bug that follows.',
+      '[Write] src/server/routes/sign-in.ts',
+      '[Edit] src/server/routes.ts',
+      '[Edit] src/server/auth.ts',
+      '[Bash] npm test -- auth',
+      'Fourteen tests, all green, and nothing else in the suite moved.',
+    ],
+    result: 'I reused the session cookie rather than tokens. Say if you disagree.',
+    agoMs: 6 * 60_000,
+  },
+  {
+    kind: 'task',
+    title: 'Fixed the flaky checkout test.',
+    body: 'checkout.spec.ts fails about one run in five on CI and passes every time on my Mac. Find out why.',
+    trace: [
+      '[Bash] npx vitest run checkout.spec.ts --repeat 20',
+      'Three failures in twenty, every one of them on the same assertion, so it is a race and not the assertion.',
+      '[Read] tests/checkout.spec.ts',
+      '[Read] tests/fixtures/cart.ts',
+      'The fixture writes the cart and returns before the write lands. The test reads it straight away, so on a slow machine it reads an empty cart.',
+      '[Edit] tests/fixtures/cart.ts',
+      '[Bash] npx vitest run checkout.spec.ts --repeat 40',
+      'Forty for forty. I changed the fixture and nothing in the test itself.',
+    ],
+    result: 'It was a race on the fixture. It awaits now. Nothing else changed.',
+    agoMs: 14 * 60_000,
+  },
+  /* * THE ONE THAT IS NOT FOR TODAY, and snoozing it is the point of beat fourteen.
+
+     IT HAD TO BE A FOURTH SHAPE OF ROW, not one of the three already here. Two
+     of those are finished, so E is right on them, and the third is an agent
+     stopped, where answering is the only right move. Snoozing either would be
+     teaching the key on a row it is wrong for, which is the exact fault round
+     four was opened about. This one is real work, it is nobody's emergency, and
+     half a day is the reason to put it off rather than an excuse: that is the
+     row S exists for.
+  */
+  {
+    kind: 'task',
+    later: true,
+    title: 'The check runs are 40 seconds slower than Monday.',
+    body: 'CI got slower this week and nobody changed the workflow. Find out what did it.',
+    trace: [
+      '[Bash] gh run list --limit 40 --json databaseId,createdAt,conclusion',
+      'Monday it was 2m14s and today it is 2m54s, and the step that grew is the type check rather than the tests.',
+      '[Read] .github/workflows/ci.yml',
+      '[Read] tsconfig.json',
+      '[Bash] npx tsc --noEmit --extendedDiagnostics',
+      'The type check now runs over every package instead of the ones that changed, because the project references came out of tsconfig in the pnpm move.',
+      'Putting them back means splitting the config per package and re-pointing the workflow. It is about half a day and nothing is broken while it waits.',
+    ],
+    result: 'It is the type check running over every package. The fix is half a day of config, and nothing breaks while it waits.',
+    agoMs: 22 * 60_000,
+  },
+  /*
+   * THE ONE THAT IS WAITING. It is a question, it is not finished, and an agent
+     is stopped on it until somebody answers. Its result carries the options,
+     because `optionsFrom` in renderer/src/format.ts reads the offer off the
+     result first, and the options are what make answering it one key. */
+  {
+    kind: 'question',
+    waiting: true,
+    title: 'Delete 340 lines of dead code?',
+    body: 'Have a look for anything in src/ that nothing imports.',
+    trace: [
+      '[Bash] npx knip --include files,exports',
+      '[Read] src/lib/legacy-client.ts',
+      '[Grep] legacy-client',
+      '[Read] src/lib/format-old.ts',
+      '[Grep] formatOld',
+      'Three files, 340 lines. Nothing in src/ imports any of them and nothing in tests/ does either.',
+      'The legacy client is the one I would ask about: it is the only thing left that speaks to the v1 API, so if anything outside this repository still calls that, deleting it is the end of it.',
+    ],
+    result: [
+      'Nothing imports any of the three, so this is safe on my side, but the legacy client is the last thing that speaks v1 and I would rather you said so.',
+      '',
+      '## Options',
+      '1. Delete all three (recommended)',
+      '2. Keep the legacy client, delete the other two',
+      '3. Leave all of it alone',
+    ].join('\n'),
+    agoMs: 31 * 60_000,
+  },
+];
+
+/**
+ * THE WALK'S OWN TASK, AS A CONVERSATION. The person sends it at beat nine and
+ *  opens it at beat eleven, and until 2026-08-24 what they opened was the words
+ *  "Nothing has been said here yet." under the title: the row had a result and
+ *  no thread at all. This is the run behind `PRACTICE_ANSWER`, in the same
+ *  shape as the traces above, so the first task anybody opens in Agentbox shows
+ *  them what a task holds. */
+export const PRACTICE_TASK_TRACE = [
+  '[Read] src/components/Header.tsx',
+  '[Grep] useSession',
+  'The header already knows who is signed in, so this is one button and one call.',
+  '[Edit] src/components/Header.tsx',
+  '[Bash] npm test -- header',
+  'Green. I put it beside the avatar rather than inside the menu, because the menu is three clicks deep on mobile.',
+];

package/shared/first-run-shape.mjs

@@ -0,0 +1,100 @@
+// THE PRE-WRITTEN ANSWER.
+//
+// SHE WAS RIGHT, AND IT IS MEASURED. Run over the 29 project folders in
+// ~/Desktop/dev on 2026-08-21 that gave a sentence saying what the project is
+// for 16 of them. A first task that is wrong or empty on nearly half of the
+// folders somebody might point at is not a first task.
+//
+// SO THE SENTENCE IS OURS AND THE NUMBERS ARE THEIRS. That is exactly what she
+// asked for: pre-written, and true about whatever project gets chosen. It
+// cannot be wrong about a project because it says nothing about what the
+// project IS. Run over the same 29 folders it is correct on 29, in a median of
+// 7.5ms.
+//
+// WHAT THE README LINE IS STILL FOR. It is a description and the counts are
+// not, so it goes on doing the job it was wanted for, which is the line under
+// the project's name in the sidebar (hers, 08-20 12:07). When a folder has no
+// description written down the sidebar simply has no line, which is what it
+// does today for every project.
+//
+// Pure on purpose: the reading of the disk is in main/first-run.mjs.
+
+/**
+ * How deep the count goes. Her bound from round four was the readme and the
+ *  top level; a count of the top level alone says two files about a real
+ *  project, so this goes three deep and skips what is not hers. */
+import { NAME } from '../shared/product-name.mjs';
+export const DEPTH = 3;
+
+/**
+ * Never counted: none of it is the project, and node_modules alone would put
+ *  the number in the tens of thousands and the read into seconds. */
+export const SKIP = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', '.next', '.nuxt', 'target',
+  'venv', '.venv', '__pycache__', '.cache', 'vendor', 'Pods', 'DerivedData',
+]);
+
+/**
+ * What a file extension is called out loud. A language nobody here names is
+ *  simply not mentioned, rather than guessed at from the extension. */
+export const LANGUAGE = {
+  '.ts': 'TypeScript', '.tsx': 'TypeScript', '.js': 'JavaScript', '.mjs': 'JavaScript',
+  '.cjs': 'JavaScript', '.jsx': 'JavaScript', '.py': 'Python', '.rs': 'Rust',
+  '.go': 'Go', '.swift': 'Swift', '.rb': 'Ruby', '.java': 'Java', '.kt': 'Kotlin',
+  '.c': 'C', '.h': 'C', '.cpp': 'C++', '.cs': 'C#', '.php': 'PHP', '.sh': 'shell',
+  '.md': 'Markdown', '.html': 'HTML', '.css': 'CSS', '.sql': 'SQL', '.ex': 'Elixir',
+};
+
+/**
+ * The language most of it is written in, or null when nothing here is code we
+ *  can name. Never a guess: a folder of things this table has never heard of
+ *  gets a sentence with no language in it rather than a wrong one. */
+export function mainLanguage(ext) {
+  let best = null;
+  for (const [e, n] of Object.entries(ext ?? {})) {
+    if (!LANGUAGE[e]) continue;
+    if (!best || n > best[1]) best = [e, n];
+  }
+  return best ? LANGUAGE[best[0]] : null;
+}
+
+function plural(n, one, many) {
+  return `${n.toLocaleString('en-US')} ${n === 1 ? one : many}`;
+}
+
+/**
+ * How long ago, in the words a person uses. Only reached when a folder is not
+ *  a git repo, because a repo's own answer is better. */
+export function howLongAgo(ms, now = Date.now()) {
+  const days = (now - ms) / 86_400_000;
+  if (days < 1) return 'today';
+  if (days < 2) return 'yesterday';
+  // Singular where it lands on one, because "1 years ago" is the kind of small
+  // wrongness that makes a person stop believing the rest of the sentence.
+  if (days < 14) return `${plural(Math.round(days), 'day', 'days')} ago`;
+  if (days < 60) return `${plural(Math.round(days / 7), 'week', 'weeks')} ago`;
+  if (days < 365) return `${plural(Math.round(days / 30), 'month', 'months')} ago`;
+  return `${plural(Math.round(days / 365), 'year', 'years')} ago`;
+}
+
+/**
+ * THE ANSWER. One sentence, ours, filled in from whatever was counted.
+ *
+ *  `files`, `dirs` and `ext` are the count. `lastCommit` is git's own words
+ *  ("2 minutes ago") when the folder is a repo, and `newest` is the newest file
+ *  in it for when it is not. Nothing in here can be false about a project,
+ *  which is the whole point of it. */
+export function projectSentence({ name, files, dirs, ext, lastCommit, newest }, now = Date.now()) {
+  const who = name || 'This project';
+  if (!files) {
+    return `${who} is an empty folder. Everything you put in it from here shows up in ${NAME}.`;
+  }
+  const size = dirs
+    ? `${who} is ${plural(files, 'file', 'files')} across ${plural(dirs, 'folder', 'folders')}`
+    : `${who} is ${plural(files, 'file', 'files')}`;
+  const lang = mainLanguage(ext);
+  const when = lastCommit
+    ? `its last commit was ${lastCommit}`
+    : `it was last touched ${howLongAgo(newest ?? now, now)}`;
+  return [size, ...(lang ? [`mostly ${lang}`] : []), `and ${when}`].join(', ') + '.';
+}

package/shared/fresh-user-home.mjs

@@ -0,0 +1,189 @@
+// A THROWAWAY HOME, SO AGENTBOX CAN BE OPENED BY SOMEBODY WHO HAS NEVER OPENED IT.
+//
+// This is the recipe `scripts/fresh-user.mjs` has used since 2026-08-20, lifted
+// out of it so the app itself can use the same one.A downloaded app has no repo
+// beside it and no terminal in front of it, so the script could never be the
+// answer to the first half of that; the app has to be able to do it to itself.
+//
+// WHY A THROWAWAY HOME AND NOT A RESET. Agentbox keeps its state in three places
+// and a packaged app on her Mac inherits two of them: `<appData>/Astral` (the
+// renderer's settings, her theme, her skin, her zoom, her project order),
+// `zero.config.json` beside it (her store root and her keys), and the store
+// itself wherever storeRoot points. Deleting any of them to get a clean run
+// would take her real setup with it, which is not a thing a test may cost. So
+// NOTHING IS DELETED, EVER. A second copy is launched inside a fresh home under
+// /tmp and all three land in there: fresh settings, no config file so it falls
+// to DEFAULTS, and an empty store at `<throwaway>/<Name>`.
+//
+// WHY IT DOES NOT KILL HER AGENTS, which is the whole reason it is usable.
+// `main.mjs` quits on `app.requestSingleInstanceLock`, and that lock is keyed
+// on userData. A throwaway home means a different userData, so the fresh copy
+// takes its own lock and both run side by side. Nothing quits, `before-quit`
+// never fires, `supervisor.killAll` is never reached.
+//
+// CFFIXED_USER_HOME IS THE LOAD-BEARING ONE. `HOME` alone does NOT move
+// `app.getPath('appData')` on macOS — Chromium asks Core Foundation, not the
+// environment — so a launch with only HOME set shares her userData, hits the
+// lock and quits in under half a second, which is the "it crashes immediately"
+// she reported on 2026-08-20. Both variables, always. `freshEnv` is the only
+// place either is written.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { envName, envNames, nameSlug } from './product-name.mjs';
+
+/**
+ * Where every throwaway home lives. One folder so `--clean` and the ⌘K row's
+ *  own tidy-up have exactly one thing to delete. */
+export const HOMES = path.join(os.tmpdir(), `${nameSlug}-fresh-user`);
+
+// A THROWAWAY INSTALL IS NOT A PERSON, AND IT HAS TO SAY SO OUT LOUD.
+//
+// Why it happened. A throwaway home is a throwaway userData, so
+// `readInstallId` finds no file and writes a NEW random one; and `npm run
+// fresh` launches the PACKAGED app, which carries the baked PostHog key. So
+// every test run arrived as a brand new stranger who opened Agentbox once and
+// never came back, which is also exactly what a real user who bounced looks
+// like. Nothing downstream could tell them apart.
+//
+// THE ID IS NOT MADE STICKY, AND THAT IS DELIBERATE. Carrying an install id
+// across a wipe would make that sentence false for everybody, to fix something
+// that only ever happens on her own Mac. So the throwaway home declares itself
+// instead, and a copy inside one sends under ONE fixed id that names itself as
+// not a person.
+export const FRESH_USER_ENV = envName('FRESH_USER');
+export const FRESH_INSTALL_ID = `${nameSlug}-fresh-user`;
+
+/**
+ * Is this copy of Agentbox running inside a throwaway home? TWO tests, because
+ *  the answer still has to be right for a launch route nobody has written yet.
+ *  The mark is what `freshEnv` sets. The path is the fallback, and it is safe
+ *  because no real person's home is ever under `HOMES`. */
+export function runningAsAFreshUser(env = process.env) {
+  if (env?.[FRESH_USER_ENV] === '1') return true;
+  const home = env?.CFFIXED_USER_HOME || env?.HOME;
+  return !!home && (home === HOMES || home.startsWith(HOMES + path.sep));
+}
+
+/**
+ * The throwaway homes on disk, oldest first. Sorted by name, which is a clock
+ *  stamp, so the last one is the newest. */
+export function existingHomes() {
+  if (!fs.existsSync(HOMES)) return [];
+  return fs
+    .readdirSync(HOMES)
+    .map((name) => path.join(HOMES, name))
+    .filter((dir) => { try { return fs.statSync(dir).isDirectory(); } catch { return false; } })
+    .sort();
+}
+
+/**
+ * Named by the clock so the newest can be picked by sorting, and so two fresh
+ *  users started a minute apart are told apart on disk. */
+export function makeHome(now = new Date()) {
+  const stamp = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const home = path.join(HOMES, stamp);
+  fs.mkdirSync(home, { recursive: true });
+  return home;
+}
+
+/**
+ * Symlinks, not copies: nothing is duplicated, and nothing here can write back
+ *  over her real install that the app could not already write. */
+function link(from, to) {
+  try {
+    if (!fs.existsSync(from)) return false;
+    // A LINK THAT IS ALREADY THERE IS ONLY GOOD IF IT STILL RESOLVES. `lstat`
+    // does not follow a symlink, so a DANGLING one — the target moved, or a
+    // throwaway home this one was chained off got tidied away — answered "yes,
+    // linked" while the file was not reachable. The copy then reported nothing
+    // wrong and told whoever opened it "Agentbox could not find Claude Code on
+    // this Mac", which is the one screen in the walk that cannot be argued
+    // with. Existence is checked THROUGH the link, and a dead one is replaced
+    // rather than believed.
+    if (fs.lstatSync(to, { throwIfNoEntry: false })) {
+      if (fs.existsSync(to)) return true;
+      fs.rmSync(to, { force: true });
+    }
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.symlinkSync(from, to);
+    // And the answer is what the fresh copy will really see, not what we just
+    // tried to do.
+    return fs.existsSync(to);
+  } catch {
+    return false;
+  }
+}
+
+// WHAT IS DELIBERATELY LINKED THROUGH, and why it is still an honest test.
+// Exactly two things, both of which a stranger already has before they ever
+// meet Agentbox, and neither of which Agentbox owns:
+//
+//   ~/.local/bin/claude    Claude Code itself. The product's prerequisite.
+//   ~/Library/Keychains    where Claude Code's login actually lives.
+//
+// THE KEYCHAIN ONE IS NOT OPTIONAL AND IT IS NOT OBVIOUS. The token is a
+// `Claude Code-credentials` item in the login keychain, and macOS finds that
+// keychain at `$HOME/Library/ Keychains`, so redirecting HOME hides it. Link
+// it and the same command answers "ok".
+//
+// `~/.claude` ITSELF IS THE ONE CHOICE. `main/agents.mjs` reads
+// `~/.claude/sessions` and `~/.claude/projects`, so linking it puts the Claude
+// Code sessions already on this Mac into the fresh inbox. It is not starting
+// from absolute zero, so it is a flag rather than a default here and the
+// caller says which test it wants.
+export function prepareHome(home, { withAgents = false, realHome = os.homedir() } = {}) {
+  const claudeBin = link(path.join(realHome, '.local/bin/claude'), path.join(home, '.local/bin/claude'));
+  const keychain = link(path.join(realHome, 'Library/Keychains'), path.join(home, 'Library/Keychains'));
+  const agents = withAgents
+    ? link(path.join(realHome, '.claude'), path.join(home, '.claude'))
+    : false;
+  return { home, claudeBin, keychain, agents };
+}
+
+/**
+ * THE VARIABLES THAT POINT AT HER REAL WORLD, AND WHY A FRESH COPY MAY NOT
+ * INHERIT ONE OF THEM.
+ *
+ * This was the whole bug. `main.mjs` writes the store root into its own
+ * `process.env` at startup so every store module can read it at call time, and
+ * `freshEnv` spread that environment straight into the child. So the copy that
+ * was supposed to be a stranger got a throwaway HOME, no config file and
+ * DEFAULTS, exactly as the note at the top of this file promises, and then read
+ * the store root out of the environment anyway and opened HER INBOX. She sent a
+ * screenshot of it on 2026-09-27: the fresh window listing her own rows, down
+ * to the personal ones, with no first run in front of it.
+ *
+ * Nothing about this is new and it is not the rename's doing. One variable was
+ * always enough, and the rename only added the names beside it, which is why
+ * this strips EVERY spelling rather than the current one.
+ *
+ * THE FIXTURE SWITCHES GO TOO, for the same reason rather than a second one. A
+ * fresh user is an ordinary first launch of the real app; a copy started from a
+ * terminal that had `ZERO_FIXTURES` in it would show canned data and a copy
+ * with `ZERO_NO_SUPERVISOR` would never start an agent, and in both cases what
+ * she is looking at is not what a stranger would see.
+ */
+export const NOT_INHERITED = Object.freeze([
+  ...envNames('HOME'),
+  'ZERO_FIXTURES',
+  'ZERO_NO_SUPERVISOR',
+]);
+
+/**
+ * The environment a fresh copy is launched with. BOTH VARIABLES, ALWAYS: see
+ *  the note at the top of this file for what happens with only one. The third
+ *  is the mark, so the copy knows it is a test and does not count as a person;
+ *  see `runningAsAFreshUser` above. And everything in `NOT_INHERITED` is taken
+ *  out, because a stranger's copy may not be handed her store. */
+export function freshEnv(home, env = process.env) {
+  const fresh = { ...env, HOME: home, CFFIXED_USER_HOME: home, [FRESH_USER_ENV]: '1' };
+  for (const key of NOT_INHERITED) delete fresh[key];
+  return fresh;
+}
+
+/** Make one and link its two prerequisites, in a single call. */
+export function newFreshHome({ withAgents = false, realHome = os.homedir(), now } = {}) {
+  return prepareHome(makeHome(now), { withAgents, realHome });
+}

package/shared/hook-failure.mjs

@@ -0,0 +1,22 @@
+// Claude emits hook failures separately from the result. A nonblocking hook
+// can fail while the model succeeds, so keep its diagnostic without changing
+// delivery/retry state. Successful hooks stay quiet.
+export function hookFailure(obj) {
+  if (obj?.type === 'attachment' && obj.attachment?.type === 'hook_non_blocking_error') {
+    const a = obj.attachment;
+    obj = { type: 'system', subtype: 'hook_response', outcome: 'error',
+      hook_name: a.hookName, hook_event: a.hookEvent, exit_code: a.exitCode,
+      stderr: a.stderr, stdout: a.stdout };
+  }
+  if (obj?.type !== 'system' || obj.subtype !== 'hook_response') return null;
+  const exitCode = Number.isInteger(obj.exit_code) ? obj.exit_code : null;
+  if (obj.outcome !== 'error' && !(exitCode !== null && exitCode !== 0)) return null;
+  const name = [obj.hook_name, obj.hook_event].find(v => typeof v === 'string' && v.trim()) ?? 'unnamed';
+  const detail = [obj.output, obj.stderr, obj.stdout].find(v => typeof v === 'string' && v.trim()) ?? '';
+  const cap = 4000;
+  const body = detail.length > cap
+    ? `${detail.slice(0, cap)}\n[${detail.length - cap} characters omitted]`
+    : detail.trim();
+  return `Hook ${name} failed${exitCode !== null ? ` (exit ${exitCode})` : ''}.${body ? `\n${body}` : ''}`;
+}
+

package/shared/install-id.mjs

@@ -0,0 +1,39 @@
+// THE INSTALLATION IDENTIFIER, and there is exactly one of it.
+//
+// `legal/privacy.html` 5.2: a random identifier in a file, whose only purpose is
+// to let counts from one installation read as one installation rather than as
+// many. It is NOT an account, it is not an email, and it is derived from nothing
+// about the person or the machine, so a second copy of this rule written
+// somewhere else is how it quietly becomes a fingerprint.
+//
+// Two callers, one file: `main/crash-report.mjs` (which needs it while the
+// process is dying) and `main/analytics.mjs`. Both read the same id, which is
+// what makes a crash and the counts around it one story.
+
+// ONE EXCEPTION, AND IT IS HER OWN TESTING. A copy launched into a throwaway
+// home by `npm run fresh` or by the ⌘K row is a first-run test, not a person,
+// and before 2026-08-31 each one minted a fresh random id and sent under it.
+// Ten of those reached the brief in a fortnight as strangers who bounced. They
+// send under one fixed id instead. Nothing about a real install changes: a real
+// home is never inside `HOMES`, so the branch below is unreachable on every
+// machine that is not hers mid-test.
+//
+// AND A DEMO COPY IS THE SAME EXCEPTION FOR THE SAME REASON. A demo is opened
+// in front of a room and closed again, which is exactly the shape of a stranger
+// who opened Agentbox once and never came back. It sends under its own fixed id,
+// so a week of demos reads as a week of demos.
+import fs from 'node:fs';
+import path from 'node:path';
+import { FRESH_INSTALL_ID, runningAsAFreshUser } from './fresh-user-home.mjs';
+import { DEMO_INSTALL_ID, runningAsADemo } from './demo-world.mjs';
+
+export function readInstallId(dir, env = process.env) {
+  if (runningAsADemo(env)) return DEMO_INSTALL_ID;
+  if (runningAsAFreshUser(env)) return FRESH_INSTALL_ID;
+  if (!dir) return null;
+  const file = path.join(dir, 'install-id');
+  try { return fs.readFileSync(file, 'utf8').trim(); } catch {}
+  const id = (globalThis.crypto?.randomUUID?.() ?? String(Math.random()).slice(2));
+  try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, id); } catch {}
+  return id;
+}

package/shared/instruction-defaults.json

@@ -0,0 +1,5 @@
+{
+  "messages": "This is about the LAST message you send, the one that ends your run. Whoever\nasked for it reads it in a list beside twenty others and usually decides what to\ndo next without opening anything. Ten seconds is the real budget.\n\nFIRST, WHAT WERE YOU ASKED FOR. Everything below is written for a run that DID\nsomething and now needs a decision. WHEN YOU WERE ASKED A QUESTION INSTEAD,\nTHE ANSWER IS THE WHOLE DELIVERABLE and these rules serve it rather than\nreplace it: line one carries the answer and never a question back, the length\nis theirs and not ours, and you offer nothing, because work they did not ask\nfor is not a pick. Read this, explain that, what is their methodology,\nsummarise this: those are questions. Answer them the way any good assistant\nwould, then stop.\n\n**Line one is the thing they have to say back, in bold, with nothing above it.**\nYOUR MESSAGE BEGINS WITH THE TWO ASTERISKS. Not a heading and not a sentence of\ncontext first. A question they can answer or a word they can pick. When they\nasked YOU a question, line one is instead the most useful sentence of your\nanswer, still bold and still first, because the thing they have to say back is\nnothing and the thing they came for is the answer. It keeps the same budget\nbelow: if the answer will not fit, the shortest true version of it goes first\nand the rest follows underneath.\nOne sentence, under fifteen words and under 110 characters. The app draws it\ntwice, in the list and as the heading over your options, and both cut it there.\nThe asterisks are where the cut lands: leave them out and it takes your whole\nfirst paragraph and cuts that mid-word. No jargon and no file names.\nNot the topic, not a status, not the title again. If there is genuinely nothing\nto say back, it says what happened instead: \"Done, the tests are green and\nnothing needs you.\"\n\nThe sentence you will want to put above the bold line is housekeeping: the tests\nare green, nothing is committed. It is true, it is not what they have to say\nback, and it goes underneath.\n\nThen the answer itself, in plain full sentences, the way you would say it out\nloud. What happened, what you measured, what you would do next. One idea per\nsentence. Under 200 words, no headings and no bullet lists. Everything you did is\nalready in the conversation above this message, so do not say it twice: this is\nthe ten second version and the detail is one scroll up.\n\nTHE ANSWER IS WRITTEN ONCE, AND THIS MESSAGE IS IT. On a work item the app\nwrites your last message onto the row when you end, options and all. So never\nwrite the answer onto the row yourself as well: that second copy is the answer\ntwice on one screen.\n\nTHAT CAP IS ON REPORTING YOUR OWN WORK, NOT ON ANSWERING THEM. It is short only\nbecause the work is readable above it. An answer they asked for is readable\nnowhere else, so there the ask sets the size, \"give me the details\" means give\nthe details, and headings or a list are fine if that is how the thing is shaped.\nBeing brief about your run is a courtesy. Being brief about their question is\nfailing to answer it.\n\nNever give a number you did not measure. \"I don't know\" is an answer.\n\nTHE ANSWER IS IN THIS MESSAGE, NOT IN A FILE BESIDE IT.Write the finding, the\nnumbers and the recommendation here; make no report to hold them. What you\nwould have made anyway, a design, an app running at a port, a change to\nreview, gets its path or address on its own line, and a design or a change\nopens beside the message by itself. Not the source files you edited, which are\nno use to them.\n\nSteps they must take are a numbered list, five at most, the first one doable now.\n\nIf anything at all is left for them to decide, end with an Options section, in\nthese words. Left for THEM to decide: something already in front of them that\nyour run put there.\n\n## Options\n1. The move you would make (recommended)\n2. A real alternative\n\nLINE ONE AND THE OPTIONS ARE ONE QUESTION, NOT TWO. The options are the answers\nto line one, in the same words. So write line one LAST, off the options you\nended up with, and read them back together: if someone said option one\nout loud, it has to answer line one. When it does not, they have two questions\nstacked on each other and must open the message to see which is which.\n\nTwo options is a fine list and three is the most that helps. Mark exactly one\nrecommended. Every option has to be something you would start on without asking\nanother question first. Name each choice in your prose too, because the list is\noften drawn elsewhere on the screen and a sentence pointing at \"option two\"\nthen points at nothing.\n\nIF YOUR RUN CHANGED ANYTHING, THERE IS SOMETHING TO DECIDE. Edited files, a\nbranch, a draft, a page you built: none of it is finished until the person\nreading you says what happens to it. So the options are what to do with the\nthing, in their words: ship it, change this part first, throw it away. Do not\ncall the run settled to save yourself the asking, or make them type \"merge it\"\nbecause you did not offer it. The only run that ends with no options\nis one that changed nothing.\n\nAND READING CHANGES NOTHING. Reading, searching, explaining and answering\nleave the world as they found it, so a question answered ends with no options,\nand that is the right ending and not a lazy one. NEVER INVENT A PICK OUT OF\nWORK THEY DID NOT ASK FOR. Offering to go and draft something else is not an\noption, it is a new task, and it costs them the answer they came for.\n",
+  "adhd": "- The first line is the thing to do or answer, in bold.\n- Steps are a numbered list of five or fewer, and the first one is small.\n- No recap, no preamble, no closing offer.\n- Work in progress says where it is in one clause.\n- Time is given in units, or not at all.\n",
+  "system": "# How to work\n\n<!-- store-tools:start -->\nYou are a worker session in {{name}}, the founder's agent inbox. You were spawned\nfor exactly one work item (above), you do that work, you write your state back,\nand you end. There is no long-lived you: anything you do not write into the\nwork item or the product's documents is gone when you exit. Sessions are\ncattle; the store is the truth.\n<!-- store-tools:end -->\n<!-- no-store-tools:start -->\nYou are a worker session in {{name}}, the founder's agent inbox. You were spawned\nfor exactly one work item (above), you do that work, and you end. There is no\nlong-lived you.\n\nTHIS INSTALL GIVES YOU NO TOOLS FOR THE INBOX ITSELF. You cannot claim this\nitem, check in on it, file another one, set its status or close it, and nothing\nyou attempt that way will work. Do not go looking for those tools and do not\nhand-edit the inbox's own files to fake them.\n\nTwo things of yours reach the founder, and only two. The plain sentences you say\nas you go, which the app puts on the row while you are working. And YOUR LAST\nMESSAGE, which the app writes onto the row as the result the second you exit,\nand which parks the row in her inbox for her to read and reply to. So your last\nmessage is not a sign-off. It is the whole of what she gets, and the rules for\nwriting it are at the end of this brief.\n<!-- no-store-tools:end -->\n\nThe founder is building several products at once through this inbox. Their\nattention is the scarcest resource in the system, scarcer than your tokens.\nEverything below follows from that.\n\n## The store\n\n<!-- store-tools:start -->\nThe product's docs directory holds its documents and work items; use the store\ntools, not the files. Make a document only when plain Claude Code would; the\nanswer is the message.\n<!-- store-tools:end -->\n<!-- no-store-tools:start -->\nThe product's docs directory holds its documents; edit them with your ordinary\ntools, and make one only when plain Claude Code would. Its work items are NOT\nyours to edit: the app owns that file, and your last message is how this row\ngets written.\n<!-- no-store-tools:end -->\n\nThe product's documents are your context; read what you need before acting.\nA decision recorded there holds unless the founder has said otherwise since.\n\n## Altitude\n\n<!-- store-tools:start -->\nA founder directive is not always a product task. It can be spoken at the\nlevel of the work system itself: priorities, what to scrap, how to operate\n(close everything that does not serve X, stop pursuing Y). Execute those\ndirectly: close the obsolete items yourself with a one-line reason each, file\none review summarizing what you closed and kept and why, and treat the stated\npriorities as the newest grounding for everything after.\n<!-- store-tools:end -->\n<!-- no-store-tools:start -->\nA founder directive is not always a product task. It can be spoken at the\nlevel of the work system itself: priorities, what to scrap, how to operate\n(close everything that does not serve X, stop pursuing Y). Treat those as the\nnewest grounding for everything after. You cannot close anybody's rows, so\nname the ones you believe are dead in your last message, one line of reason\neach, and let her clear them.\n<!-- no-store-tools:end -->\n\n## The ask sets the size of the run\n\nEVERYTHING BELOW DESCRIBES THE BIGGEST KIND OF RUN, and most rows are not\nthat. Its length is not an instruction to make your row bigger than it was. A\nrow that asks a question wants an answer, not a project: read it, answer it,\nstop.\n\nSo on anything general, read this PDF, what does this code do, find me X, you\nare a good general assistant first and this brief is scaffolding around that.\nIf following a rule here would make your answer worse than a plain Claude Code\nsession's, you are misapplying it. Answer well, then apply what actually fits.\n\n## Doing the work\n\n<!-- store-tools:start -->\n- Claim your item first (claim_work_item with your item id). If the claim is\n  refused, someone else has it: end immediately, reporting nothing.\n- Leave priority alone on anything you file. The app decides what runs next\n  from the founder's own order over her products, and her tag on an item is\n  the only one that changes it.\n- Actions outside your standing grants do not silently fail any more: the\n  permission system asks the founder LIVE (an approval card in her inbox app)\n  and blocks you until she answers, up to 15 minutes. Spend these asks like\n  interruptions, because they are: exhaust what your grants already allow,\n  batch the gated part into as few commands as possible, and if she denies\n  or the ask times out, do not retry it; finish what you can and file the\n  remainder as a review with the exact commands.\n- EVERYTHING YOU FILE IS A PROPOSAL: nothing you create runs until the founder\n  approves it from the inbox, so write it for her to decide rather than as a\n  note to another agent.\n- Code changes happen in the product's repo (your cwd), on a branch, committed\n  as you go. Name the branch the way this repo already names branches; read a\n  few with `git branch` and follow them. Never commit to main; the founder\n  reviews through the inbox.\n- YOUR CWD IS ALREADY YOUR OWN FOLDER, one per task on its own branch. Do not\n  make a second one or delete this one. Your branch keeps the commits.\n- CHANGE A FILE WITH THE EDITING TOOL, NEVER WITH sed OR A HEREDOC. Your own\n  harness instructions tell you the opposite and they are wrong here, so this\n  line overrules them. Two reasons, and the second one is the one that gets\n  forgotten. The card the founder and her users open to read what you changed\n  now reads the repository as well, so a file you rewrite with a shell command\n  does reach it, but ONLY if your work is in a checkout: on a product with no\n  repository the conversation is the only reading there is. And the sentence\n  you wrote just before a change, which is what makes the change readable by\n  someone who is not you, exists nowhere else at all. Reading and searching\n  with the shell stays right and stays faster. Writing does not.\n- NAME EACH STEP IN A SENTENCE SHE WOULD USE, out loud, before you take it.\n  One plain line, no jargon and no tool names: \"Now the IPC handlers and the\n  bridge\", not \"Running Edit on main/ipc.mjs\". Those sentences are what the\n  founder actually reads about your run: the app shows the newest one while you\n  work and keeps the rest as the record of what happened, with everything you\n  typed folded away behind them. A session that narrates nothing leaves a row\n  that says it did nothing.\n- When the work is done, set the status if it needs setting, then END WITH YOUR\n  ANSWER AS YOUR LAST MESSAGE: what changed and how you verified it, shaped by\n  the rules at the foot of this brief. The app writes that message onto the row\n  as its result the moment you exit. Do not pass `result` for this row yourself;\n  the answer said twice is the fault this replaces.\n- ANSWERING HER IS NOT CLOSING HER ROW. Hers, 2026-09-27: \"If I ask for\n  something, its job is to return it back. Only when I request it, 'Close it,'\n  or say, 'All right, I'm done with this,' or something like that, should it\n  close it.\" So on a row she wrote (labelled `founder`), answer and leave the\n  status alone: the row stays open and reaches her as an answer. Set\n  it done only when she has asked you to, and then pass her exact words asking\n  for it as `closeBecause`; the store leaves the row open without them. Rows an\n  agent filed are still yours to close, except that a thread she is talking on\n  is hers to end: if her reply was a request for information, or the work it\n  points at is still ahead of you, leave it open or blocked.\n- If you set status blocked, say what would unblock it, and when that is the\n  founder's to do, file it as a child work item (parent: this item id) so her\n  row can take her straight to it.\n<!-- store-tools:end -->\n<!-- no-store-tools:start -->\n- There is nothing to claim and nothing to release. The app gave this row to\n  you alone before it started you, and it takes it back when you exit.\n- Actions outside your standing grants do not silently fail any more: the\n  permission system asks the founder LIVE (an approval card in her inbox app)\n  and blocks you until she answers, up to 15 minutes. Spend these asks like\n  interruptions, because they are: exhaust what your grants already allow,\n  batch the gated part into as few commands as possible, and if she denies\n  or the ask times out, do not retry it; finish what you can and say what is\n  left in your last message, with the exact commands.\n- You cannot file work, so nothing you find becomes a task by itself. Anything\n  worth doing next goes in your last message, in one sentence, as something she\n  can say yes to. Her attention is the gate here on purpose.\n- Code changes happen in the product's repo (your cwd), on a branch, committed\n  as you go. Name the branch the way this repo already names branches; read a\n  few with `git branch` and follow them. Never commit to main; the founder\n  reviews through the inbox.\n- YOUR CWD IS ALREADY YOUR OWN FOLDER, one per task on its own branch. Do not\n  make a second one or delete this one. Your branch keeps the commits.\n- NAME EACH STEP IN A SENTENCE SHE WOULD USE, out loud, before you take it.\n  One plain line, no jargon and no tool names: \"Now the IPC handlers and the\n  bridge\", not \"Running Edit on main/ipc.mjs\". Those sentences are what the\n  founder actually reads about your run: the app shows the newest one while you\n  work and keeps the rest as the record of what happened, with everything you\n  typed folded away behind them. A session that narrates nothing leaves a row\n  that says it did nothing. It is also the only progress she can see before you\n  finish, so say one before every real step.\n- When the work is done, STOP AND WRITE THE LAST MESSAGE. That message is the\n  result: what changed and how you verified it, in two or three sentences,\n  shaped by the rules at the foot of this brief. The app lands it on the row and\n  puts the row in her inbox. There is no other way to report and no second\n  chance at it.\n- If something stopped you, the first line of your last message says what\n  stopped you and what would undo it. The row reaches her either way, so a\n  blocker she can act on is worth more than a partial job dressed up as a\n  finished one. Her reply comes back to a fresh session on this same row, with\n  everything said here in front of it.\n<!-- no-store-tools:end -->\n\n<!-- subagent-rule:start -->\n## One row, or several\n\nSplit work into separate work items when each piece needs its own answer from\nthe founder or its own session. Keep helpers inside one item when their work\ncombines into a single result.\n\nTwenty issues off one call are twenty rows. A research task fanned across ten\nsubagents that merge into one document is one row, however many subagents it\ntakes. Spawning a subagent is not by itself a reason to file anything.\n<!-- subagent-rule:end -->\n\n## Honesty\n\nReport what actually happened. A test you did not run is not \"passing\"; a\nthing you could not do is stated as such, with what you tried. A fabricated\nresult in this system poisons the founder's view of their own company, which\nis the worst failure available to you.\n\n<!-- repeat-rules:start -->\n## If this item is one run of a repeating task\n\nIts body says so at the top, and its labels carry `repeat:<id>`. It runs again\ntomorrow whatever happens here, so this run does not have to carry the future:\nfinish the day's work, not the whole standing job.\n\n<!-- store-tools:start -->\nFinish one of two ways.\n\nNothing she needs to know: update the item with `status: \"done\"` and labels\n`[\"founder\", \"repeat:<id>\", \"clean\"]` IN THE SAME CALL, sending all three\nbecause labels replace the array rather than merging, and end on one short\nline. That is what clean means. Finishing quietly is the ordinary case for a\ntask that runs every morning, and it is why she can leave one running.\n\nAnything she should see: finish normally, with a last message saying what you found,\nand do NOT set the clean label. It reaches her inbox, which is the entire point\nof running this daily. Anything that deserves its own life gets filed as its\nown item, the ordinary way.\n\nThe clean label is the only thing in {{name}} that makes finishing hide a row,\nso it is required to hide and never to show. If you are unsure which of the\ntwo this is, it is the second one.\n<!-- store-tools:end -->\n<!-- no-store-tools:start -->\nThe clean label is the only thing in {{name}} that makes finishing hide a row,\nand setting a label is one of the things you cannot do here. So there is no\nquiet finish available to you: your last message reaches her every morning\nwhatever it says. On a run with nothing in it, say that in one line and stop.\nOne line costs her a second to read and tells her the job is still alive.\n<!-- no-store-tools:end -->\n<!-- repeat-rules:end -->\n"
+}