agentbox-app 0.1.11 → 0.1.13

package/shared/instruction-defaults.json

@@ -1,5 +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\nA PICTURE YOU SHOW IS SAVED IN THE PRODUCT'S DOCS FOLDER, the one your brief\nnames, in designs/ under this task's id, and named in the message by its full\npath, one per line. The app draws it where you name it. Not in your code\ncheckout, which is deleted once the work ships, and never in /tmp, which the\napp will not draw at all.\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\nOffer one to four options; two or three is usual, and one is fine. Mark exactly\none recommended. 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\nNEVER OFFER WHAT YOUR RUN ALREADY DID. Shipped, merged or sent: line one says\nso, and no option offers it again. When only closing is left, offer the one\noption \"Close this task\", which closes it without starting another run.\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",
+  "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\nA PICTURE YOU SHOW IS SAVED IN THE PRODUCT'S DOCS FOLDER, the one your brief\nnames, in designs/ under this task's id, and named by its full path. Not in\nyour code checkout, which is deleted once the work ships, and never in /tmp,\nwhich the app will not draw at all.\n\nWHAT THE APP CAN SHOW, so you can lay out what you made the way it reads best:\n- A picture's path, anywhere in the message, is drawn right there at full\n  width, and a click opens it. It is drawn as a block, so inside a sentence or\n  a bullet it splits the line.\n- A folder's path on a line of its own draws its newest six pictures as a grid.\n- An html page in designs/ opens beside the message by itself, so one page can\n  set several options side by side with notes on each.\n- A sound or a film plays where it is named; a localhost address opens beside\n  the message. Headings, lists, tables and bold all draw.\nThe arrangement is yours. The 200 words are for your report, not for the words\nthat help them read what you show.\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\nOffer one to four options; two or three is usual, and one is fine. Mark exactly\none recommended. 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\nNEVER OFFER WHAT YOUR RUN ALREADY DID. Shipped, merged or sent: line one says\nso, and no option offers it again. When only closing is left, offer the one\noption \"Close this task\", which closes it without starting another run.\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 their inbox for them to read and reply to. So your last\nmessage is not a sign-off. It is the whole of what they get, 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\nThe person you work for may be anyone on a team. Call them \"you\", their\nname or \"they\", never \"she\", \"he\" or \"the founder\".\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\nKeep the thread's summary current. Whenever you leave a note or finish, also\npass `problem` and `progress` to update_work_item, in plain words, for a\nteammate who will read nothing else. `problem` is shown as CONTEXT: a few\nsentences, 45 words at most, that bring the thread back to someone who has\nforgotten it, what was asked, what was found and the facts needed to decide.\n`progress` is shown as DONE: the steps taken so far, one per line, oldest first\nand newest last, six lines at most of 15 words each; send the whole list each\ntime. A longer one is refused. Leave `solution` out; it is no longer shown. If\nit waits on another thread, pass that thread's id in `blockedBy`. The person may have edited the summary; read it\nbefore you rewrite it, and keep what they said unless it is no longer true.\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 them 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 their products, and their 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 their inbox app)\n  and blocks you until they answer, 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 they deny\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 them 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 their 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 THEY 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 they\n  actually read about your run: the app shows the newest while you work and keeps\n  the rest as the record, everything you typed folded behind them. A session that\n  narrates nothing leaves a thread saying it did nothing.\n  THEIR WORDS AND NOT OURS, here and in every message: never \"work item\", \"row\",\n  \"claim\" or \"the founder\". Say this task, this thread, picked it up, you.\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 THEM IS NOT CLOSING THEIR ROW. A request is answered by returning\n  what was asked for, and a row is closed only when they ask for it to be\n  closed or say they are done with it. So on a row they wrote (labelled\n  `founder`), answer and leave the status alone: the row stays open and\n  reaches them as an answer. Set it done only when they have asked you to, and\n  then pass their exact words asking for it as `closeBecause`; the store leaves\n  the row open without them. Rows an agent filed are still yours to close,\n  except that a thread they are talking on is theirs to end: if their reply was\n  a request for information, or the work it points at is still ahead of you,\n  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 their\n  row can take them 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 their inbox app)\n  and blocks you until they answer, 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 they deny\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 they\n  can say yes to. Their 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 THEY 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 they\n  actually read about your run, and the only progress they see before you finish,\n  so say one before every real step.\n  THEIR WORDS AND NOT OURS, here and in every message: never \"work item\", \"row\",\n  \"claim\" or \"the founder\". Say this task, this thread, picked it up, you.\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 their 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 them either way, so a\n  blocker they can act on is worth more than a partial job dressed up as a\n  finished one. Their 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 they need 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 they can leave one running.\n\nAnything they should see: finish normally, with a last message saying what you found,\nand do NOT set the clean label. It reaches their 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 them every morning\nwhatever it says. On a run with nothing in it, say that in one line and stop.\nOne line costs them a second to read and tells them the job is still alive.\n<!-- no-store-tools:end -->\n<!-- repeat-rules:end -->\n"
 }

package/shared/notify-rules.d.mts

@@ -0,0 +1,25 @@
+// Types for shared/notify-rules.mjs, which is plain ESM so that main (Node)
+// and the screen (Vite) can share one copy of the rule about when Agentbox is
+// allowed to interrupt you. The screen asks only `isNew`, which is the
+// question before "are you away"; the rest is main's.
+
+export const AWAY_AFTER_MS: number;
+
+export function atTheApp(state?: { focused?: boolean; idleMs?: number }): boolean;
+
+// `known` is the ids on the snapshot before this one, and null means there has
+// not been one. Empty and never-looked are different facts, and the module
+// says what reading one as the other cost.
+export function isNew(known: ReadonlySet<string> | null | undefined, id: string): boolean;
+
+export function clip(text: unknown, max?: number): string;
+
+export function shouldSpeak(state?: {
+  spoke?: boolean;
+  spokeAsk?: boolean;
+  waiting?: ReadonlyArray<{ kind?: string } | null | undefined>;
+}): boolean;
+
+export function banner(
+  waiting: ReadonlyArray<{ id?: string; title?: unknown; kind?: string } | null | undefined> | null | undefined,
+): { title: string; body: string; open: string | null } | null;

package/shared/notify-rules.mjs

@@ -31,6 +31,25 @@ export function atTheApp({ focused = false, idleMs = 0 } = {}) {
   return !!focused && idleMs < AWAY_AFTER_MS;
 }
 
+// WHAT COUNTS AS NEWS, which is the question before "is she away".
+//
+// renderer/src/App.tsx owns the definition of the inbox and asks this of every
+// row in it, against the ids it remembered from the snapshot before. `known` is
+// those ids, and `null` means there has not been a snapshot yet: on the app's
+// first look, everything waiting has been waiting, so none of it is a banner.
+//
+// EMPTY AND NEVER-LOOKED ARE DIFFERENT FACTS, and reading one as the other is
+// what sent this feature's best moment into the bin. App.tsx used to decide it
+// had never looked by asking whether the ids it remembered were empty, which is
+// also true of inbox zero — the state the whole product aims at. So the
+// arrival that most deserved to reach her, the first one after she got clear,
+// was the one the app silently dropped before any rule here could see it.
+// tests/the-first-arrival-after-inbox-zero-still-speaks.test.mjs.
+export function isNew(known, id) {
+  if (!known) return false;
+  return !known.has(id);
+}
+
 // A title long enough to be a paragraph is normal here; hers run past a
 // hundred characters. macOS will hard-truncate mid-word, so cut on a space and
 // say that it was cut.

package/shared/project-folder-check.mjs

@@ -78,7 +78,7 @@ export function checkProjectFolder(folder, { home = '' } = {}) {
     return {
       ok: false,
       reason: 'home',
-      say: 'That is your whole home folder. Agents would work across everything on this Mac, and macOS will ask you about Downloads, Music and every app you have. Pick the folder your project’s code is in.',
+      say: 'That is your whole home folder. Agents would work across everything on this computer, and the system will ask you about Downloads, Music and every app you have. Pick the folder your project’s code is in.',
     };
   }
 
@@ -86,7 +86,7 @@ export function checkProjectFolder(folder, { home = '' } = {}) {
     return {
       ok: false,
       reason: 'guarded',
-      say: `${rel} holds a lot more than one project, and macOS guards it, so choosing it means a run of permission panels. Pick the folder inside it that your project’s code is in.`,
+      say: `${rel} holds a lot more than one project, and the system guards it, so choosing it means a run of permission panels. Pick the folder inside it that your project’s code is in.`,
     };
   }
 
@@ -94,7 +94,7 @@ export function checkProjectFolder(folder, { home = '' } = {}) {
     return {
       ok: false,
       reason: 'system',
-      say: `${p} is part of macOS rather than one of your projects. Pick the folder your project’s code is in.`,
+      say: `${p} is part of the system rather than one of your projects. Pick the folder your project’s code is in.`,
     };
   }
 

package/shared/provider-commands.mjs

@@ -1,5 +1,6 @@
 // A command is an operation, never prose asking a model to imitate a CLI.
 import { CLAUDE_COMMANDS, commandWords } from './claude-commands.mjs';
+import { harnessDefinition } from './harness-definitions.mjs';
 const command = (name, description, argumentHint = null, aliases = []) => ({ name, description, menuDescription: null, whole: true, argumentHint, aliases });
 export const CODEX_COMMANDS = [
  command('model','Show models or change this task’s model','[model]'),
@@ -23,12 +24,18 @@ export const LOCAL_COMMANDS = CODEX_COMMANDS.filter(c=>['model','effort','diff',
 // is refused on Codex for now, in a sentence that says why, because that call
 // has never been made against a real server here.
 const FORK = command('fork','Start a new task from this conversation','<what to try instead>');
+const COMMAND_MENUS = {
+ codex: CODEX_COMMANDS,
+ claude: [command('remote-control','Continue this conversation in Claude on another device',null,['rc']),FORK,...CLAUDE_COMMANDS.map(c=>LOCAL_COMMANDS.find(l=>l.name===c.name)??c),...LOCAL_COMMANDS.filter(l=>!CLAUDE_COMMANDS.some(c=>c.name===l.name))],
+ local: LOCAL_COMMANDS,
+};
 export function providerCommands(engine) {
  // NOT ON THE CODEX MENU, because this menu's rule is that it offers nothing
  // that engine cannot run, and Codex forking is not connected yet. Typed there
  // it gets the ordinary unavailable refusal, which points at the native Codex
  // client, where `codex fork` genuinely works.
- return engine==='codex' ? CODEX_COMMANDS : [command('remote-control','Continue this conversation in Claude on another device',null,['rc']),FORK,...CLAUDE_COMMANDS.map(c=>LOCAL_COMMANDS.find(l=>l.name===c.name)??c),...LOCAL_COMMANDS.filter(l=>!CLAUDE_COMMANDS.some(c=>c.name===l.name))];
+ const definition = harnessDefinition(engine) ?? harnessDefinition();
+ return COMMAND_MENUS[definition.commandMenu] ?? [];
 }
 export function providerCommand(text, engine) {
  if(typeof text!=='string')return null;
@@ -38,7 +45,8 @@ export function providerCommand(text, engine) {
  const cmd=providerCommands(engine).find(c=>commandWords(c).includes(word));
  if(!cmd) return {name:word,args,route:'unavailable'};
  if(cmd.name==='fork')return {name:'fork',args,route:'fork'};
- return {name:cmd.name,args,route:cmd.name==='remote-control'?'remote':engine==='codex'?'codex':LOCAL_COMMANDS.some(c=>c.name===cmd.name)?'local':'claude'};
+ const route = (harnessDefinition(engine) ?? harnessDefinition()).commandRoute;
+ return {name:cmd.name,args,route:cmd.name==='remote-control'?'remote':route==='codex'?'codex':LOCAL_COMMANDS.some(c=>c.name===cmd.name)?'local':route};
 }
 export function reviewTarget(args='') {
  args=args.trim();

package/shared/rank.d.mts

@@ -18,3 +18,5 @@ export function landingIndex(
   x: number, y: number,
 ): number;
 export function moveProduct(order: string[], slug: string, toIndex: number): string[];
+export function placedScore(place: number | null | undefined, natural: number): number;
+export function dropPlaces(rows: Array<{ id: string; score: number }>, from: number, to: number): Record<string, number> | null;

package/shared/rank.mjs

@@ -155,6 +155,56 @@ export function landingIndex(rects, x, y) {
   return rects.length;
 }
 
+/**
+ * A THREAD'S OWN PLACE, SET BY DRAGGING IT IN THE LIST (w-6e5b532a95,
+ * 2026-10-07). Her words: "sometimes there are tasks that are higher priority
+ * than other projects and it's hard to articulate. I'd rather be able to drag
+ * things around here ... and have that priority remembered and that's how the
+ * app processes it." A project's place and a thread's level could never say
+ * that one Low thread matters more today than a whole project above it.
+ *
+ * So a dragged thread carries a PLACE: a number on the same scale as the score
+ * it would otherwise have, which replaces that score outright. It is a number
+ * and not a list of ids so that everything it was not dragged past keeps
+ * sorting the way it always did: a new Urgent thread still lands by its level,
+ * next to the placed ones rather than under all of them.
+ */
+export function placedScore(place, natural) {
+  return Number.isFinite(place) ? place : natural;
+}
+
+/**
+ * The places a drop writes. `rows` is the list as drawn, top first, each with
+ * the score it sorts by (its place, or its project and level); `from` is the
+ * dragged row and `to` the row it was let go in front of, or the length for
+ * the end, both counted in `rows`. Null when it lands where it was.
+ *
+ * The dragged row goes between its new neighbours. When those two TIE (two
+ * Medium threads in one project, whose order is only which changed last) no
+ * number fits between them, so the tied rows above the drop are given places
+ * of their own first, spread in the order they were drawn. The rows below are
+ * never written.
+ */
+export function dropPlaces(rows, from, to) {
+  if (!Array.isArray(rows) || from < 0 || from >= rows.length) return null;
+  const rest = rows.filter((_, i) => i !== from);
+  const at = Math.max(0, Math.min(rest.length, to > from ? to - 1 : to));
+  if (at === from || !rest.length) return null;
+  const close = (a, b) => Math.abs(a - b) < 1e-6;
+  const below = rest[at]?.score;
+  const floor = below ?? rest[at - 1].score - 2;
+  // The run of rows just above the drop that tie with the floor.
+  let top = at;
+  while (top > 0 && close(rest[top - 1].score, floor)) top -= 1;
+  const ceiling = top > 0 ? rest[top - 1].score : floor + 2;
+  const run = rest.slice(top, at);
+  const step = (ceiling - floor) / (run.length + 2);
+  const out = {};
+  run.forEach((r, j) => { out[r.id] = floor + (run.length + 1 - j) * step; });
+  out[rows[from].id] = floor + step;
+  return out;
+}
+
 /**
  * Move one product to a new index, returning a fresh order. Products that were
  * never in the order join it on their first move, so dragging an unranked chip

package/shared/relay-address.mjs

@@ -0,0 +1,6 @@
+// THE RELAY EVERY COPY OF THE APP USES (relay/worker.mjs), deployed to the
+// founder's Cloudflare account on 2026-10-12. With an address here every
+// computer offers "Anywhere" in Settings, then Phone, and starts new people on
+// it; AGENTBOX_RELAY_URL or relay/relay.local.json still take precedence
+// (main/relay-address.mjs). Redeploy with `cd relay && npx wrangler deploy`.
+export const RELAY_URL = 'https://agentbox-relay.agentbox-app.workers.dev';

package/shared/relay-crypto.mjs

@@ -0,0 +1,165 @@
+// THE RELAY'S LOCKS (relay/worker.mjs, main/relay-client.mjs, relay/phone/).
+//
+// A phone away from home reaches the Mac through a relay we run. Everything
+// that crosses it is sealed on one end and opened on the other with keys made
+// from the phone's key, which is in the QR code and nowhere else: it never
+// leaves the Mac except into the code, and the phone keeps it in the address's
+// fragment, which a browser never sends. So the relay can pass messages and
+// cannot read, alter or forge one.
+//
+// What the relay does see: a room name, and the Mac's proof that it may hold
+// that room. The room is a hash of the proof, so the relay can check a Mac
+// against it, and neither one tells it the key.
+//
+// Plain WebCrypto, so this one file runs on the Mac (Node), on Cloudflare, and
+// in the phone's service worker.
+
+const enc = new TextEncoder();
+const subtle = () => globalThis.crypto.subtle;
+const SALT = enc.encode('agentbox-relay-v1');
+
+export function b64u(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+async function bits(key, info, length = 256) {
+  const ikm = await subtle().importKey('raw', enc.encode(String(key)), 'HKDF', false, ['deriveBits']);
+  return new Uint8Array(await subtle().deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: SALT, info: enc.encode(info) }, ikm, length));
+}
+
+async function roomOf(proof) {
+  return b64u(new Uint8Array(await subtle().digest('SHA-256', enc.encode(`agentbox-room:${proof}`))));
+}
+
+/** The room the relay knows this pair by, and the Mac's proof that it is the Mac's. */
+export async function relayIds(key) {
+  const proof = b64u(await bits(key, 'mac-proof'));
+  return { room: await roomOf(proof), proof };
+}
+
+/** Is `proof` the proof for `room`? The relay asks this of every Mac. */
+export async function macMayJoin(room, proof) {
+  if (typeof room !== 'string' || typeof proof !== 'string' || !proof) return false;
+  const want = await roomOf(proof);
+  if (want.length !== room.length) return false;
+  let diff = 0;
+  for (let i = 0; i < want.length; i += 1) diff |= want.charCodeAt(i) ^ room.charCodeAt(i);
+  return diff === 0;
+}
+
+const aes = async (raw) => subtle().importKey('raw', raw, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+
+/** One key for each direction, so nothing sealed one way opens the other. */
+export async function relayKeys(key) {
+  return { up: await aes(await bits(key, 'phone-to-mac')), down: await aes(await bits(key, 'mac-to-phone')) };
+}
+
+/**
+ * Seal `bytes` for the other end. `aad` names what it is (a request, or the
+ * n-th frame of the answer to one request), so a frame cannot be passed off
+ * as another. Out: 12 bytes of nonce, then the sealed bytes.
+ */
+export async function seal(key, bytes, aad) {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await subtle().encrypt({ name: 'AES-GCM', iv, additionalData: enc.encode(aad) }, key, bytes));
+  const out = new Uint8Array(12 + ct.length);
+  out.set(iv, 0);
+  out.set(ct, 12);
+  return out;
+}
+
+/** Open what `seal` made, or throw if a single bit of it was changed. */
+export async function open(key, sealed, aad) {
+  if (!(sealed instanceof Uint8Array) || sealed.length < 28) throw new Error('Too short to be sealed.');
+  const pt = await subtle().decrypt({ name: 'AES-GCM', iv: sealed.subarray(0, 12), additionalData: enc.encode(aad) }, key, sealed.subarray(12));
+  return new Uint8Array(pt);
+}
+
+/* ------------------------------------------------------------- the wire */
+
+// A request, phone to Mac, before it is sealed: four bytes giving the length of
+// a json head, the head, then the body. The head carries a time and a random
+// nonce, so the Mac can turn away one it has already answered.
+export function packRequest(head, body = new Uint8Array(0)) {
+  const h = enc.encode(JSON.stringify(head));
+  const out = new Uint8Array(4 + h.length + body.length);
+  new DataView(out.buffer).setUint32(0, h.length);
+  out.set(h, 4);
+  out.set(body, 4 + h.length);
+  return out;
+}
+
+export function unpackRequest(bytes) {
+  const n = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0);
+  const head = JSON.parse(new TextDecoder().decode(bytes.subarray(4, 4 + n)));
+  return { head, body: bytes.subarray(4 + n) };
+}
+
+// An answer, Mac to phone, is a run of frames, each sealed on its own: a head
+// (status and headers), the body in pieces, and an end. The end is sealed too,
+// so an answer cut short by anyone in between is seen to be cut short.
+//
+// WAIT comes before the head and says only "still working". A reply to an
+// agent mid-step is answered when the agent takes it, which can be minutes,
+// and the room gives a Mac 30 seconds to start answering. A phone that asks
+// for these (`wait` in its request's head) skips them; one that does not
+// never gets one.
+export const FRAME = Object.freeze({ HEAD: 0, DATA: 1, END: 2, WAIT: 3 });
+
+export const frameAad = (nonce, seq) => `res:${nonce}:${seq}`;
+
+// ON THE MAC'S SOCKET TO THE RELAY one byte says what a message is, then eight
+// bytes of request number, then whatever it carries:
+//   to the Mac     0x01 a request (the sealed bytes)   0x02 the phone gave up
+//                  0x03 a piece of a request too big for one message; the
+//                       0x01 that follows carries the last piece
+//   from the Mac   0x10 one sealed frame of the answer  0x11 done
+//                  0x12 refused: it would not open, or it was a replay
+export const TO_MAC = Object.freeze({ REQUEST: 0x01, CANCEL: 0x02, PART: 0x03 });
+/** The most the relay puts in one socket message to the Mac. Cloudflare's limit is 1 MB. */
+export const PART_BYTES = 512 * 1024;
+export const FROM_MAC = Object.freeze({ FRAME: 0x10, DONE: 0x11, REFUSED: 0x12 });
+export const ID_BYTES = 8;
+
+export function tag(type, id, rest = new Uint8Array(0)) {
+  const out = new Uint8Array(1 + ID_BYTES + rest.length);
+  out[0] = type;
+  out.set(id, 1);
+  out.set(rest, 1 + ID_BYTES);
+  return out;
+}
+
+// Between the relay and either end each sealed piece goes with its length in
+// front, so one stream of bytes can carry many.
+export function lengthPrefixed(bytes) {
+  const out = new Uint8Array(4 + bytes.length);
+  new DataView(out.buffer).setUint32(0, bytes.length);
+  out.set(bytes, 4);
+  return out;
+}
+
+/** Split a stream (or a reader of one) of length-prefixed pieces back into the pieces. */
+export async function* pieces(source) {
+  const reader = typeof source.getReader === 'function' ? source.getReader() : source;
+  let buf = new Uint8Array(0);
+  try {
+    for (;;) {
+      while (buf.length >= 4) {
+        const n = new DataView(buf.buffer, buf.byteOffset, buf.byteLength).getUint32(0);
+        if (buf.length < 4 + n) break;
+        yield buf.slice(4, 4 + n);
+        buf = buf.subarray(4 + n);
+      }
+      const { value, done } = await reader.read();
+      if (done) return;
+      const next = new Uint8Array(buf.length + value.length);
+      next.set(buf, 0);
+      next.set(value, buf.length);
+      buf = next;
+    }
+  } finally {
+    try { reader.releaseLock(); } catch { /* cancelled under us */ }
+  }
+}

package/shared/runs-on.d.mts

@@ -0,0 +1,10 @@
+export interface RunsOn {
+  /** 'claude' or 'codex', or null on a Mac where nothing is signed in. */
+  engine?: string | null;
+}
+
+/** The word for the plan behind an engine, or null for one we cannot name. */
+export declare function runsOnName(engine?: string | null): string | null;
+
+/** The one line the walk says on a Mac that was already set up. Null for null. */
+export declare function foundOnThisMac(facts?: RunsOn): string | null;

package/shared/runs-on.mjs

@@ -0,0 +1,55 @@
+// THE ONE LINE SAYING IT FOUND AN ACCOUNT ALREADY ON THIS MAC.
+//
+// From a session with a new user, 2026-10-07, in her words: a new user came in,
+// started running an agent, and was "like, 'Oh my God, where are the tokens
+// coming from? I didn't even connect my account.'"
+//
+// He was right that nothing said. The app finds whichever coding agent is
+// already signed in on the Mac and runs every worker on that subscription
+// (main/claude-plan.mjs, main/codex-account.mjs), and the walk is SILENT about
+// it by design: `needsPlan` in renderer/src/plan-setup.ts skips the plan
+// question entirely when one tool is found and signed in, which is the right
+// call and leaves nobody told.
+//
+// IT IS A ONE-TIME SURPRISE, SO IT GETS A ONE-TIME ANSWER. A row saying this
+// permanently, in the sidebar's foot, is what this file held first; it shipped
+// on 2026-10-07 and came out the same day. Her words: "we have to get rid of
+// this. It should never say that on the sidebar." Somebody asks where the
+// tokens are coming from ONCE, on their first day, so the place for the answer
+// is the walk they are standing in.
+//
+// AND IT NAMES NO PLAN. The row said "Claude · Max 20x" and that was the half
+// she wanted gone most: "very critically, I want to get rid of that Claude Max
+// 20x plan." The question being answered is "did it connect to something of
+// mine", not "what am I paying for", and the second one is already answered
+// properly on each agent's own page in Settings, where somebody goes when they
+// want it.
+//
+// THE PLAN'S VOCABULARY, NOT THE TOOL'S. "Claude" and "ChatGPT" here, never
+// "Claude Code" and "Codex", which is the rule the walk already follows
+// (renderer/src/plan-setup.ts: words people know, "never the names of the tools
+// underneath"). The tool names stay where they belong: on a byline about which
+// agent is working a row (`engineWordFor`, renderer/src/byline.ts).
+//
+// NOTHING IS SAID UNTIL SOMETHING IS KNOWN. Both functions answer null on an
+// engine they cannot name, and the walk draws nothing at all for null rather
+// than "checking…" or a dash.
+
+/** The word for the plan behind an engine. Null for an engine we cannot name. */
+export function runsOnName(engine) {
+  if (engine === 'claude') return 'Claude';
+  if (engine === 'codex') return 'ChatGPT';
+  return null;
+}
+
+/**
+ * THE ONE LINE DURING THE WALK, on the Mac where there was nothing to ask.
+ *
+ *  It replaces silence, not a question: somebody with no coding agent set up
+ *  still gets the plan question and the setup card, and never sees this.
+ */
+export function foundOnThisMac({ engine = null } = {}) {
+  const name = runsOnName(engine);
+  if (!name) return null;
+  return `Your agents will run on the ${name} account already signed in on this Mac.`;
+}

package/shared/shortcuts.mjs

@@ -166,8 +166,8 @@ export const SHORTCUTS = [
     ],
   },
   {
-    // The one group that cannot be named by WHERE she is, because all four of
-    // its keys work both in the list and inside an open task. So it is named by
+    // The one group that cannot be named by WHERE she is, because all of its
+    // keys work both in the list and inside an open task. So it is named by
     // what the keys do, literally and in the order they are drawn.
     label: 'Closing, scheduling and undoing',
     keys: [
@@ -179,10 +179,16 @@ export const SHORTCUTS = [
       // the summary inside a thread and still meant the schedule picker in the
       // list, so this page taught one letter for two different things and an
       // office manager testing the app met both inside a minute. One meaning
-      // per letter: S is the summary, L is later.
-      { keys: ['L'], what: 'Put the task off until a time you pick.' },
+      // per letter: S is the summary, L is later. And the page says the word
+      // the key stands for, because that word is the action's name now
+      // (w-66e3ece93d): the ⌘K row, the picker and the toast all say Later.
+      { keys: ['L'], what: 'Later: put the task off until a time you pick.' },
       // focused branch and list switch: 'z' → undo
       { keys: ['Z'], what: 'Undo the last thing you did.' },
+      // opensTheToast(e.key, toast) above the focused branch → openToastRow.
+      // Z's other half: Z takes back what the toast announced, O goes into it.
+      // Only while a toast with somewhere to go is up (w-f0bfe32859).
+      { keys: ['O'], what: 'Open the task you just sent or answered, while its note is on screen.' },
       // (meta||ctrl) && 'a' && !inInput && !modal → tick the whole list
       { keys: ['⌘A'], what: 'Tick every task in the list. Press it again to untick.' },
     ],
@@ -192,7 +198,7 @@ export const SHORTCUTS = [
     keys: [
       // (meta||ctrl) && 'k' → the palette, above every other branch, and
       // forwarded from inside an open file by main.mjs as well.
-      { keys: ['⌘K'], what: `The command bar: everything ${NAME} can do, by name.` },
+      { keys: ['⌘K', 'Ctrl+K'], join: 'or', what: `The command bar: everything ${NAME} can do, by name.` },
       // 'n' in both branches → setModal('compose'). C does the same and is
       // left off: N is the default (w-fb9051e597).
       // "Threads", not tasks, since w-ec62ab6b38.