[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_228":-5,"_231":232,"_233":234},"routes/shell",{"_40":41,"_227":-5,"_228":-5,"_229":230},"routes/repo",{"_33":-7,"_34":35,"_36":37,"_38":39,"_40":41,"_42":31,"_43":31,"_44":31,"_45":31,"_46":31,"_47":31,"_48":49,"_50":49,"_51":31,"_52":-7,"_53":-7,"_54":55,"_56":57,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":14,"_22":23,"_24":-5,"_25":26,"_27":28,"_28":29,"_30":31,"_32":14},"ref","05135decc3df8cbf0165be75c20d35d8a7c0de87","path","agents.md","oid","7009de01631a59485ca3bc73a81bb23b4924d07f","size",33826,"commit","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Working on chopin\n\nNotes for whoever changes this next, human or otherwise. The readme is for\npeople running it; this is for people editing it.\n\n## Before pushing\n\nRun the complete repository checks:\n\n```bash\nbun run ci\nbun run types\nbun test\nbun run e2e\n```\n\nA non-zero result is blocking, even when the failing file predates the current\nwork. Fix it or ask before pushing. Scoped checks are useful while iterating,\nbut never replace these full commands.\n\n## Commands\n\n```bash\nbun run dev # supervisor: Vite + server on one origin, Ctrl-C stops both\nbun test # 525 tests, no browser, no agent spawned\nbun run e2e # 49 tests, Chromium, builds the client first\nbun run types # every package, and e2e\nbun run ci # dprint check && oxlint\nbun run build # production client\nbun run start # serve the built client\n```\n\n`.github/workflows/ci.yml` runs all four checks on every push and pull request,\nin two jobs: `bun run ci`, `bun run types` and `bun test` together, and the\nbrowser suite on its own because it has to build the client first and should\nnot make a formatting mistake wait behind Vite. A failed browser run uploads\nits report and traces.\n\n`bun run dev` needs `GITHUB_TOKEN`. `AGENT=off` runs everything except the\nagent, which is what both suites use.\n\n`bun run e2e` needs a browser once: `bun run e2e:browsers`. It builds the\nclient, then starts two servers of its own — 8788, and 8789 with the injection\nflags on — so having `bun run dev` open at the same time costs nothing.\n\nTo iterate against a server you are already running, skipping the build and the\nsupervision, give it the three things the suite assumes and name it:\n\n```bash\nPORT=8790 AGENT=off DATA_DIR=\"$PWD/e2e/.scratch/8790\" \\\n DEV_QUESTIONS=1 DEV_COMMENTS=1 bun apps/server/src/main.ts\nE2E_BASE_URL=http://127.0.0.1:8790 bun node_modules/@playwright/test/cli.js \\\n test --config e2e/playwright.config.ts\n```\n\nThe `DATA_DIR` is not decoration: tests that need prose before anybody opens\nthe room write it themselves, and they derive where from the port in the base\nURL. Point it elsewhere and they seed a directory the server never reads.\n\n## Shape\n\n```\npackages/dialect 4.6k the MDX dialect and its Lexical schema\npackages/editor 10.5k the browser editor, cursors, the sidecar, agent marks\npackages/question 1.8k questionnaires: definition, shared answer, derivation\npackages/protocol 0.9k the wire, as types, plus the addressing rule\napps/server 11.4k rooms, documents, questions, comments, the agent\napps/web 1.5k the three panes\ne2e 1.3k the browser suite, and the servers it runs against\nscripts/dev.ts the development supervisor\n```\n\nDependencies point one way: `apps` depend on `packages`, `packages` depend on\n`protocol`, and nothing depends on an app. `protocol` is types plus one runtime\nmodule — the rule for whether a message addresses the agent, which both ends\nneed and must not disagree about.\n\n## How a room works\n\nEach room holds a Yjs document with a **headless Lexical editor bound to it**.\nThat mirror is the reason the server can validate an edit rather than relay\nbytes it cannot read: it turns opaque CRDT updates into a tree that can be\nprojected back to canonical MDX with nobody connected.\n\nClient updates are grouped for 5ms, applied together, and only then\nacknowledged. Yjs cannot undo a transaction, so a batch that leaves the\ndocument invalid is not rolled back — the document is rebuilt from its last\nknown-good state under a fresh epoch and everyone re-opens.\n\nAgent edits take a different path. They are staged on the parsed document,\nserialised, re-parsed, validated, and only then _reconciled_ into the live\ntree, so blocks the agent did not touch keep their Lexical identity and nobody\nloses a cursor to somebody else's edit.\n\nCanonical MDX goes to `data//plan.mdx` on a debounce, with questionnaire\nrecords, comment threads, anchors and the transcript beside it. Yjs history is\ndeliberately not persisted: it would buy undo across a restart at the price of\na binary checkpoint that could disagree with the source.\n\n## Decisions, and why\n\n**The dialect is an allowlist.** Anything not described in\n`packages/dialect/src/dialect.ts` is rejected before it reaches a renderer.\nPlan content is parsed and rendered, never evaluated.\n\n**The permission gate is the only boundary.** There is no sandbox — this runs\nas you, on your filesystem. So `apps/server/src/agent/permissions.ts` is an\nallowlist: writes refused outright rather than confined, reads limited to\n`WORKING_DIR` with credential patterns excluded, shell limited to commands the\nruntime classifies read-only, unrecognised kinds denied. Read it before\npointing the agent at anything you care about.\n\n**Ids are minted wherever a component is created**, client or server. A ULID\nhas enough entropy that two editors cannot collide, so buying uniqueness with a\nround trip would only make a block appear later than the keystroke that asked\nfor it. The agent's ids are minted server-side in `plan/edit.ts` because a\nmodel that copies a block it read copies the id with it.\n\n**The record owns an answer; the plan shows it.** A questionnaire's answer\nlives in `data//state.json`, and what appears in the MDX is a projection\nkept so the source reads correctly alone. An agent rewriting the prose around a\ndecision cannot change the decision.\n\n**Resolution is two-phase.** Answering has to reach both the record and the\ndocument, and until both have happened nobody may be told it is final. A failed\ndocument write rolls the claim back and the questionnaire stays open.\n\n**The agent acts only when addressed** with `@ai`. Everything else is\nconversation, carried into its next turn as context. Without this, two people\nplanning together cannot talk — \"should we ask about auth first?\" would start a\nturn. Not `@plan`: it is the most common noun in the product.\n\n**Accepting a comment is an address.** The `@ai` rule separates conversation\nfrom instruction, and a button press is already the latter — so accept starts a\nturn, through the same queue a message does. It writes a system line into the\ntranscript, because an agent that begins editing for no visible reason is worse\nthan a noisy log. Accepting also freezes the thread: it is what the room\nsettled, so `edit_plan` cannot author or remove the `` it projects.\n\n**Anchors are a relative position plus a digest**, and the two do different\njobs. The position survives edits around a block; the digest recovers it when\nthe position cannot resolve — a move rebuilds a block's collaborative identity,\nand an epoch rotation discards the history the position was expressed in. A\ndigest matching two blocks recovers neither.\n\n**A passage is the same idea one level finer.** A comment marks a phrase, not a\nblock, so it carries the block anchors plus a pair of relative positions into\nthe text and the quoted words. The positions make the highlight stretch as\nsomebody types inside the phrase; the quote finds it again when they cannot\nresolve. Two occurrences equally near the recorded offset recover neither.\n\n**A client sends what it read, not where it thinks that is.** `comment:start`\ncarries block indices and the selected text; the server finds the quote and\nmints every Yjs position itself. Finding it is the concurrency check, and a\nbetter one than a digest — it tests whether the sentence is still there, which\nis what matters, and a browser cannot compute a canonical block digest without\nre-serialising the document. The two ends must agree on which blocks the source\naddresses; they need not agree on the offset, so a divergence surfaces as a\nrefusal rather than a comment landing on the wrong sentence.\n\n**A decision has one place in the plan, not two.** A question used to carry\nwhat it was about and what its answer produced as separate anchor sets, on the\ntheory that they move independently. Asked to tell them apart, the agent\nanchored the first block of the result and called it the subject — in every\nrecord it ever wrote — so a resolved card offered two adjacent, identically\nlabelled buttons that led to the same block. The subject was also never derived\nwhen a question was asked and never invalidated when the plan moved, so it sat\npermanently unreviewed: an inert link, and an entry in `anchors_pending` that no\namount of anchoring could clear. A comment thread still keeps two, because there\nthe halves have different authors and different shapes and neither can stand for\nthe other.\n\n**The quote is the way back, not the card.** A sidecar card holds a reply box,\nan Accept and a Dismiss, so making the whole of it a link would mean deciding on\nevery click whether the reader meant the link or the control they actually hit.\nThe quotation becomes a button when the thread has somewhere to send one and\nstays a blockquote when it does not, which is the rule a question's answer\nalready followed. It matters most for an accepted comment: a `` draws\nnothing in the prose, so the pane is the whole of where the decision can be seen\nand the quote is the only route to what it produced.\n\n**A table's header row is furniture, not a row.** GFM has exactly one header\nand it is always the first, so nothing in the document marks it as one — being\nfirst is the whole of what makes it the header, and the column alignment hangs\noff its cells. A drag that moved it would therefore not reorder the table so\nmuch as change what it claims: two rows would swap meaning at the next save and\nthe alignment would follow whichever stopped being the header. So the header\ncannot be dragged, cannot be dropped onto, cannot be removed, and nothing can\nbe inserted above it. Its bar is still drawn, because a rail with a gap where\na row plainly is reads as a bug. The last _body_ row can go, though —\n`| a |\\n| - |\\n` is well formed and round-trips, and refusing it would mean the\nonly way to empty a table is to delete it.\n\n**The rails are measured, because a `` cannot contain a `

`.** Every\nother widget in the editor puts its chrome in a `data-plan-chrome` slot the\nnode reserves and Lexical is told to leave alone. A table has nowhere to put\none: the browser hoists a stray div straight back out. So the choice was\nbetween subclassing `TableNode` and measuring cell rectangles, and measuring is\nwhat the selection bubble already does. The grips are one lane and the buttons\nanother, with nothing overlapping — a cross in the middle of a grip is exactly\nwhere a drag is most naturally begun, and it swallowed the gesture it was drawn\nbeside. Intermittently, too, since whether it had become live yet depended on a\nre-render landing between the pointer arriving and the button going down.\n\n**A limit is enforced where the button is, not where the document is.** A table\npast `MAX_TABLE_ROWS` or `MAX_TABLE_COLUMNS` applies locally, syncs cleanly and\nis then refused by the server — which cannot undo a Yjs transaction, so it\nrebuilds the room under a fresh epoch and everyone in it loses their undo and\ntheir cursors. `table/shape.ts` is asked before anything is created, so the\ncost of reaching a hundred rows is a grey button rather than everybody's\nsession. The same argument as `toolbar/url.ts`, one order of magnitude worse.\n\n**A rendered fence is a second reading, never the document.** `@pierre/diffs`\ncolours code and draws patches, and it is asked for nothing else: it has an\nedit mode, and turning it on would put a character model of its own beside the\none the room is collaborating in, so that two people typing would each be\ncorrecting a copy. The source stays where it was, as Lexical text children\nunder Yjs, directly editable underneath what was drawn from it. It arrives on\ndemand, because Shiki's grammars outweigh everything else the editor loads and\na plan with no code in it should pay none of that.\n\n**A fence with no language draws nothing**, and that is the whole of what makes\nthe control worth having. Uncoloured text above the same uncoloured text is two\nof the same thing with a caret in only one of them; naming the language is what\nturns the upper one into something the lower one is not. So `/code` opens a\nfence with a selector and no preview, and choosing from it is an edit to the\nfence like any other — it syncs, it saves, and everybody else's copy is\ncoloured too.\n\n**A patch is repaired on the way to the renderer, and nowhere else.** Nobody\nwrites a hunk header correctly, least of all a model quoting a change it is\nproposing, and the counts in one are how a parser knows where the hunk ends —\nso a count that is too low truncates the change silently, which is the one\noutcome worth any amount of trouble to avoid. `widgets/code.ts` recounts them\nfrom the lines that are actually there, reads a stripped blank line as the\nunchanged line it was, and takes off the `a/` and `b/` that the renderer only\nremoves for git's own form. What comes out is handed over and thrown away; the\nfence keeps every byte the author wrote. Anything still malformed is refused by\nthe parser and drawn as coloured text, which is the honest rendering of a\nfragment that was never a patch.\n\n**Enter is a newline in a fence, and twice over is the way out.** Lexical asks\na block to make its own successor and a code block returns null, which is why\nEnter inside one did nothing whatsoever — no newline, and no way past a fence\nsitting at the end of a plan. `widgets/enter.tsx` answers\n`INSERT_PARAGRAPH_COMMAND` rather than the keystroke, because that is what rich\ntext turns an unshifted Enter into and what everything else meaning \"start a\nnew block\" dispatches. The blank line that asked to leave goes with the\nrequest, or every fence anybody escaped would keep a trailing empty line\nnobody typed.\n\n**A hover asks; a click sends.** Both leave the same wash, because they are the\nsame fact — this is the prose that card refers to — and the difference is how\nlong it is owed. A hover is over when the pointer moves; a click has put the\nreader somewhere they were not looking, so the mark is pinned for five seconds\nafter the pointer has gone, or they arrive at a block with nothing to say which\none it was. Pointing at another card in the meantime borrows the wash and gives\nit back, which is what makes a detour a detour.\n\n**There is one pin, in `marks.ts`, not one per store.** A reader has one\npointer, so going to a comment has to put out the question they went to before\nit — the same argument that already put the registry there. Whether a walk\nthrough several places continues is asked of the pin rather than announced by\nit: nothing needs redrawing when it lapses, since the lapse redraws itself, and\na callback fired on the way to replacing a pin would reach a store in the middle\nof walking and wipe the step it had just taken.\n\n**Hard-fail at boot.** A missing token, an unusable CLI or a `WORKING_DIR` that\nis not there are all detectable in seconds by trying, and discovering them when\nsomebody types their first message is worse. `AGENT=off` is the deliberate way\nto run without one.\n\n**A mark for an agent edit waits to be seen.** The agent writes wherever it\nlikes, including several screens away from whoever is reading, so a mark that\nspent its few seconds off screen would have told nobody anything. Nothing\nstarts counting down until it has been in the viewport, which makes it an\nunread marker rather than a flash — and unread markers do not expire on a\nclock, so an unseen one waits indefinitely and the set is bounded by a cap\ninstead. Once seen the clock runs whether or not the mark is still in view: two\nstates and one timer, so nothing can go dark and light up again on a later\nscroll, which would read as a second edit that never happened.\n\n**Those marks take no space and add no element.** An agent editing below the\nfold must not shift the sentence somebody is in the middle of typing, and a\nmark expiring a few seconds later must not shift it back. What the agent removed\nhas no element at all, which is why a hole is drawn in `box-shadow` on the edge\nof the block still beside it and why the side is part of its address — and why\nwhat was removed can only be read in the list behind the chips.\n\n**The agent's cursor and the agent's marks disagree about time, on purpose.**\nThe cursor is presence: it says the agent is working _here, now_, so it is\nbroadcast the moment an edit lands, it is not held back for anyone, and it goes\nshortly after the turn ends. A mark is a record: it waits until it has been\nread and may sit unseen indefinitely. So somebody who comes back after a long\nturn sees marks and no cursor, and somebody watching sees both — which looks\nlike an inconsistency until you notice they answer different questions. The\ncursor cannot replace the marks, because a cursor off screen is simply not\nthere, and that is the case the marks exist for.\n\n**It sits at the end of what the agent wrote, and says its name for longer.**\nAn anchor names a block from its start, which is the stable end of one; a\ncursor is where an edit _finished_, so `room.endOf` is its own function rather\nthan a flag on `anchorAt`. A caret at the top of a new block points at the\nfirst thing the reader already knows and looks like something about to be\ntyped. The label keeps the same distinction: a person's caret is one of several\nand its owner is watching it, so a second names them and that is enough, while\nthe agent's turns up unannounced in a document somebody else is reading and the\nnaming is the entire point of drawing it.\n\n**The agent rides in the presence mirror's own local slot.** Everything else\nin `plan/presence.ts` is a reflection of some socket, which is what lets a\ndisconnect clear it; the agent has no socket, so it goes where nothing can\nattribute it to one. That slot is also in the join snapshot, so somebody\narriving mid-turn sees where the agent is.\n\n## Things that fail silently\n\nEvery bug found in this project so far was invisible. These are the mechanisms.\n\n**An unhandled node type kills collaboration.** MDXEditor re-serialises the\ndocument on every update, and a type its serialiser cannot write throws inside\nthe first update listener — which stops every listener after it, including the\none that syncs. The editor keeps accepting edits and none of them leave the\nbrowser. `registry.test.ts` asserts every dialect node is writable; keep it\npassing when you touch the dialect.\n\n**Lexical swallows errors thrown inside `editor.update()`**, routing them to the\neditor's `onError`. A seeding failure looked like an empty document until\n`plan/room.ts` started carrying the error out by hand.\n\n**Everything in an SDK event lives under `event.data`**, and several fields have\nnear-homonyms on the envelope. `event.id` is the event's; `event.data.messageId`\nis the message's. Reading the wrong one produced a duplicated reply and a\nstreaming caret that never stopped. Nothing throws.\n\n**`session.send()` resolves when the message is accepted, not when the turn\nends.** Waiting on it alone tears the handler down before the agent has said\nanything. Turns end on `session.idle`.\n\n**A custom agent's `tools` list cannot admit MCP tools.** Not by wildcard, not\nby exact name, not with the server declared on the agent. The entry matches\nnothing and is dropped without a word, and the agent then explains its way\naround the absence. The session's `availableTools` is the filter that\nunderstands `builtin:`, `mcp:` and `custom:` prefixes — the allowlist lives\nthere, and the agent declares none of its own.\n\n**Permission is decided before execution**, so a refused tool produces no start\nand no completion. `chat/service.ts` renders `permission.completed` denials as\nfailed tool chips; without that a boundary the agent keeps hitting is invisible.\n\n**Tailwind v4 translate utilities emit the `translate` property**, not\n`transform`. They compose rather than override, so an element positioned by\nscript must not also carry them.\n\n**A grammar the highlighter does not have rejects a promise nobody is\nwatching.** `@pierre/diffs` starts its first highlight from a render and never\nattaches a handler to it, so a fence saying `foobar` — or `pseudocode`, which a\nmodel will write — resolves nothing, renders nothing, and leaves a block that\nis simply blank. `code-view.tsx` asks `resolveLanguage` first and falls back to\nplain text, which is also why the answer is cached: the question is asked again\non every keystroke in the block.\n\n**One preview slot, two writers, and the loser is whoever committed first.**\nThe rendered output used to be assigned as `innerHTML` and the code renderer is\nReact, so a fence that changed language from `mermaid` had to clear the slot on\nthe way out — and a passive effect's cleanup runs _after_ React has already\ninserted the next renderer's nodes into it. Everything in `data-plan-preview`\nis React's now, including the markup KaTeX and Mermaid produce as strings.\n\n**A `