From 2d8e7b98b14df644463a3e6b132832e187855858 Mon Sep 17 00:00:00 2001 From: tdwd <111124579+tdwd@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:44:02 +0200 Subject: [PATCH] Record what is left of the connected-sessions work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The reasoning for three open items lived only in a conversation. Sessions can now read each other's work and have it reviewed by a spawned agent, both scoped to the project, and what remains is a set of decisions rather than a set of tasks. Connections were deferred rather than dropped, and the note says why: a connection gates the shared log and the analysis, so building it before the analysis existed would have stored a type nothing read. Now that both exist the question is answerable from use — whether project scope is actually too coarse — and the one case project scope cannot express is a connection across projects, which inverts what a connection is for. Live token counts need a parser rather than a field read, and are worth it only if a review runs long enough that a moving number says more than a spinner does. Pushing work to an existing session goes under "Not built yet" instead, since it is deliberately absent rather than pending. The case for it evaporated when the reviewer became a spawned agent: nothing has to be pushed into a session that is already there. --- docs/architecture.md | 10 +++++++++ docs/backlog.md | 53 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 75c80ca..f6510aa 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -669,3 +669,13 @@ already answer. - `--continue` for non-isolated sessions. See `agentArgsFor`: a shared project directory may have been last used by another tool, and resuming someone else's conversation silently is worse than starting fresh. +- **Pushing work to a session that already exists.** Deck writes to a pane only + for the keys a person types. Delivering to an agent instead would be small to + build — `Runner.Write` exists, the hooks report when a session is idle, and + the trick of sending the text and the newline as separate writes is already + in `live_claude_test.go` — but it works dependably only for the one agent + that reports turn boundaries, and it spends a property stated deliberately in + `README.md`. It is listed here because the case for it evaporated rather than + because it is hard: `analyse` spawns a **new** agent, so nothing has to be + pushed into an existing one. Revisit only if pulling proves insufficient in + practice. diff --git a/docs/backlog.md b/docs/backlog.md index f94033e..e576fab 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -4,7 +4,7 @@ Work that is decided but not done, and the reasoning behind each. Things deliberately *not* built are in `docs/architecture.md` under "Not built yet"; this file is only for work that should happen. -Last reviewed 2026-08-24. +Last reviewed 2026-08-28. ## ~~1. Exact status from Claude Code hooks~~ — done 2026-08-23 @@ -142,3 +142,54 @@ Lowest value of the set: the app is keyboard-first and nothing about it is currently awkward without a mouse. It lived under "Not built yet" until the deferral reason expired, and was listed in both places for a while — a deferred item and a planned one are different claims. + +## 10. Connections between sessions in a project + +Sessions on one project can already read each other's work (`work`) and have it +reviewed by a spawned agent (`analyse`). Both are scoped to the project, which +is the same scope `Siblings`, `notes` and `message` use. + +A **connection** would be a smaller grouping inside that: a set of sessions +that share context and can review each other, persisted as +`Connections []Connection` on `store.State` rather than as a field on +`Session`, so there is no two-way link to keep consistent. `Load` already +back-fills missing fields, so an older state file stays readable. + +It was deliberately deferred rather than built first. A connection gates two +things — the shared log and the analysis — and until the analysis existed a +`Connection` type would have been stored, rendered and read by nothing. Now +that both exist, the question is answerable from use rather than from +prediction: **is project scope actually too coarse?** With three or four +sessions on one repository it is not, and a grouping inside it would add a +concept without removing a problem. + +The case that project scope genuinely cannot express is a connection *across* +projects — an API changing in one repository while its consumer is updated in +another. `Siblings` excludes that by construction. If connections are built, +that is the motivating case, and it inverts the framing: a connection is not a +narrowing of the project, it is an escape from it. + +One question decides the shape and should be answered before any code: does a +connection **narrow the shared notes log**, or only gate the analysis? +Narrowing changes behaviour every sibling relies on today; gating is additive. + +## 11. Live token counts while a review runs + +The sidebar shows elapsed time while a spawned analysis is in flight and the +exact cost once it lands, because the figures arrive only in the final result +envelope. Showing them as they accumulate needs `--output-format stream-json` +with `--include-partial-messages`, which is a parser rather than a field read. + +Worth doing only if a review ever runs long enough that watching the number +move tells you something a spinner does not. The measured runs so far finish in +a few seconds. + +## 12. A public-repo notice a cloner will meet + +`CLAUDE.md` carries the rule that this repository is public, that it is written +for a stranger, and that fixtures count. It is deliberately not committed, so +that rule reaches nobody who clones. + +A short section in `docs/architecture.md` would put it where the next +contributor meets it. Left open because it is a decision about how much of the +working instructions belong in the published tree, not an oversight.