[lavaman131]

When a machine's Planner backend keeps failing to start, the document now says why. Until now Chat said Planner: starting on studio… for as long as the connector's restart loop went on, and the reason (for example unsafe-checkout: …) was only in the connector's log on that machine, which the document's members, often not the machine's owner, cannot read.

What people see

From the second failed launch in a row, the line under the composer changes. It is still the starting state (data-planner-state="starting", still a polite status), because the machine keeps trying:

• Planner: can’t start on studio, in the danger colour, with a red dot
• why, in the ordinary secondary ink (wraps; the dot stays with the first line)
• Tried 3 times in a row, last at 06:29 PM. Still trying., in the quietest ink

The machine's owner sees its name; a teammate in the same document sees @mona’s machine, as the starting line does today. One failed launch is treated as transient and changes nothing. An @chopin message sent meanwhile is refused with the reason instead of "try again in a moment". Once the Planner attaches, or a launch stays up, it all goes.

Screenshots from the end-to-end run (CHOPIN_SHOTS):

The machine's owner, desktop

A teammate with the document open, desktop

Under the composer on a phone

How it works

Three commits, one per layer.

1. Connector (apps/connector). It counts launches in a row that exited before staying up and posts after each to POST /api/connector/planner/failure: the document (by id, which the Planner credential names), the count, how the backend ended and why. The reason is the last stderr line that says why: not blank, and not a line that only announces the exit (Exiting with code 1; …, Shutting down, …), with terminal colors and a leading timestamp removed. It is masked with the connector's existing redacted (the Planner credential, GitHub tokens, --env values, token-shaped strings), the home directory shown as ~, and cut to 300 characters. When a launch stays up for the healthy interval it posts that nothing is failing. Reporting never waits on the restart loop and gives up after ten seconds.
2. Protocol and server (packages/protocol, apps/server). The server accepts the report only for a document it asked that machine to run, keeps the latest per document and machine in memory (like the rest of the Planner's attachment state) and forgets it when the Planner attaches, when the connector says a launch stayed up, when the machine is no longer asked for the document, and on restart. Session.PlannerAttachment's starting gains an optional failure: { attempts, reason, at }, sent to the room from the second launch on. The reason is sanitised again server-side (colors and control characters out, one line, 300 characters) and at is the server's own clock.
3. Web and e2e (apps/web, e2e). The line described above.

Compatibility

• No connector protocol bump. The server refuses a connector whose protocol is newer than its own, so a bump would have broken new connectors on older servers. The report is a new route instead.
• Older server, newer connector: the route answers 404; the connector takes it to mean the server never will and stops asking for that document (covered by a test that fails with that flag disabled).
• Newer server, older connector: it never calls the route, so nothing changes.
• Older web, newer server: failure is optional on starting; an older client ignores it.

Things to know

• The failure is shown to everyone in the room, read-only viewers included, like the login already is. The reason is the backend's own stderr line, so it can name things on the machine (paths under the home directory are shortened to ~, tokens masked). If that is too much for read-only viewers, it is one condition in plannerStatus in main.ts.
• chopin status is unchanged: it still shows the first stderr line. The line sent to Chopin is the last one that says why, because the first is often a banner.
• The @chopin refusal is covered end to end, and that waits the server's 30-second start window, so the new e2e test takes about 36 s.

Verification

• bun test in apps/connector (271 pass, 14 skip, 0 fail) and apps/server (3966 pass, 6 skip, 0 fail); apps/web/src/chat 227 pass.
• New tests: connector (reason picked and masked, home directory shortened, cleared once up, 404 asks once), server (second failure shown, first not, only for a machine asked, cleared on attach / on up / on choosing elsewhere, sanitised, malformed refused, @chopin message), web (the three lines, still starting, reason escaped, teammate's wording) and two e2e tests against a real remote-Planner server (desktop with a teammate, and phone).
• bun run e2e e2e/planner-picker.e2e.ts: all 8 pass, the 6 existing ones included.
• bun run ci (including the design contract and the impeccable check, no new findings) and bun run types pass.
• Red before green: the new server tests failed on the unchanged server and caught a crash on a report with no reason; the connector's 404 test fails with its guard disabled.

Not covered

No real connector was run against a real backend that refuses its checkout; the connector side is tested with a script that prints the same shape of stderr (reason, then an exit notice).