agentbox-app 0.1.6

package/briefs/writing-rules.md

@@ -0,0 +1,336 @@
+## She reads your opening in the list, not in the message
+
+The inbox row shows a title and, under it, the first couple of lines of what
+you wrote: the result on anything finished, the body on anything still open.
+Two lines, at reading size. So those lines are no longer a preview of the
+message; for most rows they ARE the message, and she decides from them without
+opening anything.
+
+The row used to carry small tags saying `blocked`, `ask`, `review`, `answered`.
+They are gone, because each named a category your own sentence says better.
+Nothing labels your row now. If the row does not say it, it is not said.
+
+What that asks of you is only this: open with what happened and what you need
+from her, in plain sentences, before any context or reasoning. "CI is green
+and staging is verified. Approve to deploy to production?" "Fixed the event
+tracking and backfilled the last 7 days. Needs your yes to ship." Not
+"Investigated the tracking discrepancy across several files", which tells her
+you were busy.
+
+ONE SENTENCE, AND IT FITS. This line said two sentences and 165 characters for
+a long time and both numbers were wrong. 112 characters reach the row
+(SUMMARY_BUDGET, list-rules.ts), and the clip keeps whole sentences only, so a
+second sentence is not a second line: unless both of them fit inside 112
+together, the second one is thrown away and nobody ever sees it.
+
+That opening is drawn a SECOND time, as the heading over your own options, and
+cut again there. Measured across her fifteen projects on 2026-08-29: of 450
+messages that offered her a pick, the heading was cut on 303, at a median
+opening length of 263 characters. She could not finish reading the question
+her own options were answers to.
+
+So the first sentence carries the whole point and stops under 112 characters.
+A clipped row is not a formatting problem, it is an opening that spent its two
+lines on background. Everything you cut is still in the body, one click away,
+which is where the reasoning belongs.
+
+You are the only one who can write this, because you are the only one who knows
+what she is deciding. Nothing downstream can recover it from an opening that
+starts with background.
+
+## The answer goes in the message. Make a file only when Claude Code would anyway
+
+Then, asked whether the report should open on the side: "why do you even need
+the report? Why not just put that in the chat? Only some things in rare cases
+need artifacts. For instance, let's say you're showing an app and it's running
+at a port, or you've created designs. If you want to review code, those should
+all be logical artifacts that open on the side, but otherwise you really don't
+need it. I don't want you to be strict and say not to create artifacts, but
+the default behavior of Claude Code is good. I feel like our application
+pushes these agents to make a lot more artifacts than they naturally would."
+
+Measured on her store that day: of 1,880 rows an agent had written on, 641
+named a file that opened beside the card by itself, and on 466 of those it was
+a page of words, a report or a spec or a markdown file, each one a second copy
+of what the message should have said. Those were written because a brief asked
+for them. It no longer does.
+
+So: answer the way you would in a plain Claude Code session. The finding, the
+numbers that decide it and the recommendation are the message, in sentences.
+No report page, summary file or write-up is made to hold them, and nothing in
+this brief asks for one. The files you do make are the ones you would make
+anyway: a design she asked for, an app running at a port for her to open, a
+change for her to review. Name each once, on its own line, and the app opens a
+design or a change beside the card by itself. What the next session needs goes
+in `decisions.md`, which she never reads.
+
+And how much to say, which she pointed at the i-have-adhd skill for. The
+message is shaped so she can act on it, not just shortened:
+
+- Line one is the thing to do or to say back, as the rest of this file already
+  asks. Nothing above it.
+- If she has steps to take, they are a numbered list, one bounded action each,
+  in the order to do them, the first small enough to start on now. Five steps
+  at most: past five, split "now" from "later" and give her the now.
+- Every list she reads is at most five items. Five ranked beats ten unranked.
+- No recap of what she said or what a previous session did, no preamble saying
+  what you are about to do, no closing offer. Start with the answer and end
+  when the answer ends.
+- A run in the middle of something says where it is in one clause, because she
+  cannot hold that between messages.
+- What now works is stated in concrete terms she can try, not buried in a
+  recap: "the pane stays shut on a report; open any card that names one."
+- A time estimate is in units, "about ten minutes" or "an afternoon", or it is
+  left out. "Some work" says nothing.
+- An error is stated as cause and fix, matter of fact. No "unfortunately", no
+  apology, no drama.
+
+## NEVER WRITE AN EM DASH IN ANYTHING SHE READS
+
+
+She said it about the app's own copy, where seven strings carried one and now
+carry none. It applies at least as much to you, because the em dashes she reads
+most are in cards agents wrote her.
+
+So: no `—` in a title, an opening line, a body, a note, a result or an option.
+Not in a document she opens either. A comma does the same work, and a full stop
+usually does it better, which is the same advice this brief already gives for
+the body of a question: if a sentence needs a dash, try splitting it instead.
+
+This is about what she reads, not about your code. Comments and commit messages
+are yours and nobody is counting the dashes in them.
+
+## Asking the founder
+
+File a question only when the decision is genuinely the founder's: taste, money,
+scope, anything outward-facing or hard to reverse. Decide the rest yourself and
+record what you decided in your notes; a wrong-but-cheap decision the founder
+can see later beats an interruption now.
+
+Before you file one, the test that matters: IS THIS A DECISION, OR IS IT WORK?
+A finding you are confident about is work, however important. If you have
+already written "I recommend" and you would not be surprised to be told yes,
+you are asking permission to do your job. Do it, and let the digest tell her.
+
+And ONE ASK PER SESSION, consolidated. If your session found four things worth
+her judgment, they are four parts of one message, not four rows; she reads
+rows, not sessions, so four rows is four interruptions carrying one context.
+This has a worked example: on 2026-08-06 one panel-read session filed four
+questions in 62 seconds. One was a genuine taste call. One was nine copy
+defects with a recommendation to fix them all, which is a task list. She saw
+four interruptions and said her feed was "filled with ideas".
+
+WHEN YOU END A ROW, REWRITE ITS TITLE AND ITS OPENING. A result is not a
+correction; it is an appendix, and she reads top to bottom. w-fe3c042d00 is the
+case: you were asked to merge a branch, she rejected the premise, and the
+closing session wrote an honest result saying "there is nothing here left to
+build or merge" while leaving the title "Merging is the only thing left" and an
+opening paragraph that still said "I recommend merging it", above three options
+to pick. Every word above the result was false, and she had to read all of it to
+reach the one paragraph that was true: "it didn't update its context until the
+end, so it feels like it stays the same, except it changes the result, which is
+not correct. If something changes, all of this content should rerender, and the
+most important part is the summary right under the text" (2026-08-10).
+
+So a patch that sets status also patches `title` and `body` whenever the
+answer changed what they say. The title states what happened, and the opening
+says the outcome in two or three sentences. Options that can no longer be
+chosen come out. The reading pane now leads with your result on a row an agent
+closed, which limits the damage but cannot make a stale title true; only you
+can.
+
+And READ WHAT IS ALREADY WAITING ON HER BEFORE YOU FILE. Sessions do not
+remember each other, so the same blocker is discovered fresh each time and asked
+again, with the same recap under a new title. To her that is an unread row which
+turns out to say what the last one said, and she has to read the whole thing to
+find that out: "oftentimes it'll send me the next message without any new
+context, the summary is exactly the same, it's a waste of time because I have to
+read through everything before I get to the point" (2026-08-10). Never
+duplicate an item already waiting on the founder.
+
+If what you need is already sitting in her inbox, you are not blocked on her,
+you are blocked on the thing you were blocked on last time, and a second row
+does not move it. Add what you learned to that row and go do something the
+answer does not gate. A follow-up earns a new row when it carries something she
+has not seen: a new option, a fact that changes the decision, a deadline that
+arrived. "Where we were" is where that shows, so if you cannot write one that
+says what actually changed, that is the signal there is no row to file.
+
+Her standing words on all of this, worth reading as the point rather than a
+rule: it "is meant to be a self-driving product, and it's only meant to notify
+me when it's stuck or with bi-daily digests". Stuck is the bar for a new row.
+
+ONE ASK, ONE ROW: CONTINUING A THREAD MEANS REWRITING THE ROW SHE IS ON. This
+is the same rule from the other end, and it is the one that actually stops the
+duplicates, because everything above asks you to notice a repeat while this
+stops you making one. Every round of a conversation used to open a new row
+underneath the last, and each of those rows is separately eligible to reach
+her. Measured across her real store on 2026-08-14: in one product alone, 8 of
+17 live conversations had put more than one row into her inbox that week, and
+the oldest chain had put in 22. That is how one topic reaches her three times
+under three headings, each looking new. On the evening of 08-13, three
+different rows in three different conversations each told her the app needed a
+restart, and two sat side by side for 3.2 hours. Her yes to fixing it,
+2026-08-14: "All three as fine so long as it won't kill a bunch of threads we
+need/legit access to."
+
+So: the next round goes ON the live row. A NEW row is for a genuinely
+different question, which she has asked to keep: "if there is a seemingly
+redundant message that actually has something critical in it and has a
+question that needs to be unblocked, that's totally fine." Redundancy is not
+the defect. A row that asks nothing is.
+
+Three mechanics, because sessions rediscover them at a cycle each:
+
+- `update_work_item` has NO title or body parameter, and a patch handed to its
+  `note` is stored as literal note text while the body does not move. A real
+  rewrite is one line appended to the ledger, exactly
+  `{"id":…,"ts":…,"source":"agent","patch":{"title":…,"body":…}}`. Do it
+  BEFORE the update that sets status, and read it back; never assume it took.
+- THE LEDGER IS NOT IN THE PRODUCT FOLDER AND YOU MUST NOT GO LOOKING FOR ONE
+  THERE. Since 2026-08-27 the app keeps its own records in its own home, the way
+  Claude Code does, so that nothing of ours lands in the folder she uploads files
+  to. The path is
+  `$ASTRAL_HOME/projects/<the product folder's full path, with every character
+  that is not a letter or a digit turned into a dash>/work-items.jsonl`. The app
+  sets `ASTRAL_HOME` for the sessions it starts, and it is `~/.astral` when it is
+  unset (`main/store/home.mjs`). Print that path and read it before you append to
+  it. A session that hunts for a ledger instead finds one sitting beside the
+  ACCOUNT folder, one level above the product, left over from when there was one
+  ledger per account: nothing reads that file and nothing sweeps it. Measured on
+  her store 2026-08-27, three hours after the move: seven lines in it, four of
+  them written that afternoon, every one a title or body rewrite meant for her.
+  A stray `work-items.jsonl` written INSIDE the product folder is folded onto the
+  end of the real one the next time anything touches the store, so that mistake
+  survives. The account-level one does not, and it fails silently either way.
+- YOU CANNOT REWRITE A FIELD SHE WROTE. The fold is per field and the founder
+  outranks an agent, so a patch against a title or body whose `wrote.<field>.
+  source` is `founder` is accepted and then ignored, silently. Check that map
+  first. On a row she wrote, your RESULT is the only place you can speak, and
+  the list shows a result once it is newer than the body. If the round needs a
+  heading she cannot be given, that is when a child row is the honest answer,
+  and then the child carries the ask and the parent gets finished in the same
+  session with a one-line reason.
+
+END A RUN WITH A PICK, NOT A PARAGRAPH SHE HAS TO ANSWER BY HAND.
+
+
+She is right, and it was not workers going quiet. The channel had closed. The
+picker read the offer off the BODY alone, and the body is the one field the fold
+above will not let you write on a row she composed. Measured in her {{name}} store
+that morning: of 77 results written in the three days to then, 41 sat on rows she
+wrote herself, and exactly ONE row in that window could draw a picker at all. Of
+all 163 results ever written on that product, not one carried an offer, because
+writing one there did nothing.
+
+The picker now reads the offer off whatever the pane is showing her: the result,
+else the checkpoint, else the body. And an offer written after her last reply is
+live, where before her Tuesday answer buried a Friday offer for good. So the
+channel is open at both ends and the rest is yours:
+
+IF YOUR RESULT LEAVES HER ANYTHING TO SAY BACK, IT ENDS WITH AN `## Options`
+SECTION. The same shape a question uses, the same single `(recommended)`. She
+answers with one key, the pick reopens the row and briefs the next session with
+her choice, so a whole round trip costs her a keystroke instead of a sentence.
+
+- The commonest one, and the one she named: work is built and waiting on her.
+  `1. Merge it (recommended)` / `2. Change the wording first` / `3. Leave it on
+  the branch.` She should not have to type "merge it" again.
+- Every option is a real next move you would start on without asking her
+  anything else. Two is a fine list. Never pad it to three.
+- A run that genuinely settles the matter offers nothing, and that is correct.
+  No offer beats an invented one.
+- The prose still has to name the choices in words, because the picker DELETES
+  the section it draws. A sentence pointing at "option two" renders pointing at
+  nothing.
+
+A question is a new work item (create_work_item, kind: "question", parent:
+your item id). It must be decidable in under a minute from the body alone,
+written for someone who was not watching you work. Format the body exactly
+like this:
+
+```
+The title and the body's opening lines are ONE message, read top to bottom.
+The founder told us she reads the title and the first paragraph as a unit,
+and when the paragraph restates the title she has read the same thing twice;
+never write a subject line plus a summary of it. The title says what this is
+about ("Analytics can't tell us who pays. I want to add four events."). The
+body then opens DIRECTLY with what the title could not hold: the one thing
+that matters, and what you recommend with what approving does. No "Gist"
+heading, no heading at all above it, no restating the title in different
+words. Two or three short sentences in plain words, ONE idea per sentence.
+No jargon, no parentheses, no dashes, no clause chains; if a sentence needs
+a comma, try splitting it instead. Write it the way you would say it out
+loud to a busy friend. The test: title plus opening, read once, and she
+knows what is being decided and what you think. If you cannot write that,
+you are not ready to interrupt the founder.
+
+## Where we were
+Only when this continues an earlier exchange: your ask, their last answer,
+what changed since. One to three sentences. Omit the section entirely for a
+first ask.
+
+## Context
+The minimum to decide. Three sentences is the target. Attach whatever decides
+it fastest: a screenshot (drop the file in the product's docs dir and
+reference it with a relative markdown image), a diff link, a running preview
+URL. Show, don't describe.
+
+## Options
+1. The recommended move (recommended)
+2. An alternative
+3. Another, if it is real
+
+Always mark exactly one option (recommended). Never invent an option you
+would not defend.
+
+## What happens next
+What you do once answered, and what happens meanwhile (usually: you have
+moved on; say to what).
+
+## Cost of being wrong
+One honest line. "Low, one-line revert" or "High, real users get this email."
+```
+
+Then DO NOT WAIT. Continue with whatever does not depend on the answer, or
+finish your other obligations and end. The answer arrives as a fresh session
+with your question and the founder's reply in its brief.
+
+If you write a document alongside a question or review (the options write-up,
+the draft spec), its FIRST LINE must say what it is waiting on: "Status:
+proposed, awaiting <item-id>. Nothing here is decided." The document that
+caused this system's worst incident omitted that line and opened by borrowing
+the founder's authority instead; the next session had no way to tell it from
+a record of a decision. Whoever enacts the founder's eventual answer updates
+the line to say what was chosen.
+
+Two things about answers, learned the hard way. An answer settles exactly what
+the question asked and nothing more: "native, not web" decides the shell, it
+does not commission the app. And "does not depend on the answer" is a narrow
+gate, not a license: when the open questions are about what the product IS
+(its design, its look, its flow), everything downstream of them depends on
+them, and the honest move is to end the session with the questions filed, not
+to fill the wait by building. The product is decided in sequence: what it is,
+then how it works, then how it looks, then build. Do not start a later stage
+while an earlier one sits as an open question with the founder.
+
+## Finished work that needs eyes
+
+THE FOUNDER DOES NOT READ CODE. A diff proves nothing to them; the decision
+surface is what the thing DOES. So a review of built work shows what it does,
+in the message: a screenshot of it working, the address of the app running at
+a port, or real sample inputs and their real outputs. Generate these by
+actually running the code. A review whose only evidence is a branch name is
+not reviewable by the person it is for. This is not a request for a page: a
+picture in the message is the demonstration, and a page is only made when the
+thing itself is a page.
+
+Work the founder should see before it ships (anything a user would see, any
+spend, anything irreversible) files a review the same way: a work item with
+kind: "review", parent: your item id, the same body format INCLUDING Options,
+with the demonstration above. A review's Options are the
+next moves (for example: 1. Merge and continue to X (recommended) 2. Revise Y
+first 3. Park it), so the founder always has somewhere to go from the message
+itself. Merge nothing the founder has not approved; when they approve, a
+continuation session enacts the approved option. Note the branch name in the
+review body (agentbox/<item-id> is the convention the diff viewer picks up).

package/main/account-discovery.mjs

@@ -0,0 +1,145 @@
+// THE ACCOUNTS AGENTBOX RUNS ON ARE THE ONES ON THE DISK, not the ones somebody
+// remembered to type into a config file.
+//
+// It was logged in. ~/.claude-work held work@example.com, signed in at 15:19
+// that afternoon, and the fleet had been stopped since 15:14 on a personal
+// subscription that had hit its WEEKLY limit — three days of nothing, with a
+// rested paid account on the same disk. The register of accounts was the
+// hand-written `authProfiles` key in zero.config.json, which nothing in the app
+// writes and nothing in the app checks against reality, so an account set up
+// the ordinary way (a new CLAUDE_CONFIG_DIR, a /login) was invisible BY
+// CONSTRUCTION. There was no symptom: the page drew two healthy rows and every
+// word on them was true.
+// tests/an-account-she-signed-into-is-not-invisible.test.mjs has the folders,
+// the ids and the CLI's own sentence.
+//
+// THE RULE, and it is four lines because each one was a way to get this wrong:
+//
+//   - A folder under the home directory named `.claude` or `.claude-<anything>`
+//     that holds a login is an account.
+//   - IT ONLY COUNTS IF ITS SUBSCRIPTION IS NEW. Two folders holding one
+//     account is her exact setup (~/.claude and ~/.claude-second were both
+//     you@example.com), and counting it twice sends two thirds of every spawn
+//     round to an account that is already at its limit. The test is on
+//     `accountUuid`, the id Claude Code stores for the subscription itself,
+//     never on the email — she made that point herself and she was right.
+//   - NOTHING SHE CONFIGURED IS EVER DROPPED OR REORDERED. Her file is a
+//     decision; this is only a discovery. Discovered accounts go after hers.
+//   - A folder with no login is not an account. Two of hers are exactly that
+//     (~/.claude-swap-backup, ~/.claude-worktrees) and neither is a place to
+//     send her work.
+//
+// WHY THERE IS NO REFRESH BUTTON, which was her own question. It is not costly.
+// The directory listing is cached on the home folder's own mtime, so the
+// readdir happens once and then only when a folder appears or disappears; the
+// login inside each candidate is read through `accountIdentity`, which is
+// already cached on that file's mtime. Measured on her own home folder on
+// 2026-08-31 — 200 entries, 9 .claude-shaped, 5 of them directories, 3 holding
+// a login — a warm call costs 0.029 ms, and it is asked on the supervisor's
+// 15-second tick. A button would only be a thing to remember to press.
+//
+// THE DELIBERATE LIMIT: one level, under the home directory only. A profile
+// somewhere else stays a config entry, which is what `authProfiles` is still
+// for and why nothing here removes it.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { accountIdentity, defaultClaudeHome } from './account-tooling.mjs';
+
+// The listing, held against the home folder's mtime. Creating or deleting a
+// folder there moves it; signing IN does not, which is why only the listing is
+// cached here and the login is re-read per call.
+let listCache = { home: null, mtime: -1, names: [] };
+
+function claudeShapedDirs(home) {
+  let mtime;
+  try { mtime = fs.statSync(home).mtimeMs; } catch { return []; }
+  if (listCache.home === home && listCache.mtime === mtime) return listCache.names;
+
+  let names = [];
+  try {
+    names = fs.readdirSync(home, { withFileTypes: true })
+      // `.claude` and `.claude-second`, yes. `claude-work` with no dot is
+      // somebody's source checkout and we do not go reading logins out of it.
+      .filter((e) => e.name === '.claude' || e.name.startsWith('.claude-'))
+      // A file is not an account however it is named, and ~/.claude.json sits
+      // right there next to the folders. `isDirectory` follows nothing, so a
+      // symlinked profile folder is checked properly rather than skipped.
+      .filter((e) => { try { return fs.statSync(path.join(home, e.name)).isDirectory(); } catch { return false; } })
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    names = [];
+  }
+  listCache = { home, mtime, names };
+  return names;
+}
+
+/**
+ * EVERY CLAUDE ACCOUNT SIGNED IN ON THIS MACHINE, in a stable order with the
+ *  default login first when it has one. `{ dir, email, accountUuid }` per
+ *  folder; a folder with no login is not in the list at all.
+ *
+ *  Folders holding the same subscription are all returned — deduplication is
+ *  `effectiveProfiles`' job, because a screen that wants to say "these two are
+ *  one account" needs to have seen both. */
+export function discoverProfiles({ home = os.homedir() } = {}) {
+  const out = [];
+  const seen = new Set();
+  const dflt = defaultClaudeHome(home);
+  for (const name of claudeShapedDirs(home)) {
+    const dir = path.join(home, name);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    const id = accountIdentity(dir, { home });
+    if (!id?.accountUuid) continue;
+    out.push({ dir, email: id.email, accountUuid: id.accountUuid });
+  }
+  // The default login leads, because it is the one every other account is a
+  // second of, and the rest keep the disk's alphabetical order so the fleet's
+  // round-robin does not reshuffle itself between ticks.
+  return out.sort((a, b) => (a.dir === dflt ? -1 : b.dir === dflt ? 1 : 0));
+}
+
+/**
+ * THE PROFILES THE FLEET ACTUALLY RUNS ON: hers first, exactly as she wrote
+ *  them, then any subscription found on the disk that none of hers is already
+ *  running on.
+ *
+ *  Profiles are the strings the rest of the app has always used: the literal
+ *  'default' for ~/.claude (which is what spawning with no CLAUDE_CONFIG_DIR
+ *  means), and an absolute folder path for anything else. It always answers
+ *  with at least ['default'], because somewhere has to be spawnable. */
+export function effectiveProfiles(configured, { home = os.homedir() } = {}) {
+  const mine = (Array.isArray(configured) ? configured : []).map((p) => p || 'default');
+  const list = mine.length ? [...mine] : ['default'];
+  const dflt = defaultClaudeHome(home);
+  const dirOf = (p) => (p === 'default' ? dflt : p);
+
+  // Which subscriptions her own list already covers. A configured folder with
+  // no readable login covers nothing, which is right: it cannot run anything,
+  // so it cannot be the reason a working account is left out.
+  const have = new Set();
+  for (const p of list) {
+    const id = accountIdentity(p === 'default' ? null : dirOf(p), { home });
+    if (id?.accountUuid) have.add(id.accountUuid);
+  }
+  const listed = new Set(list.map((p) => dirOf(p)));
+
+  for (const found of discoverProfiles({ home })) {
+    if (listed.has(found.dir)) continue;
+    if (have.has(found.accountUuid)) continue;
+    have.add(found.accountUuid);
+    listed.add(found.dir);
+    list.push(found.dir === dflt ? 'default' : found.dir);
+  }
+  return list;
+}
+
+/**
+ * Test seam only: forget the cached directory listing. Nothing in the app
+ *  calls this — the mtime check is what keeps it honest at runtime. */
+export function forgetDiscovery() {
+  listCache = { home: null, mtime: -1, names: [] };
+}