From bd9431198c794c7a20b09ea625fc7891bd0225cf Mon Sep 17 00:00:00 2001 From: Marvin Bitterlich <644950+marvin-bitterlich@users.noreply.github.com> Date: Sat, 7 Nov 2026 00:33:53 +0000 Subject: [PATCH] The Claude Code pane reads a Board with much finished work again The Board's overview answer had grown past the 4 MiB Claude Code reads of a plugin's fetch. The host cut the decompressed answer there, the cut dropped the line's end, and the pane's ndjson reader found no Exit, so the pane said the Board sent no answer. The overview now leaves out every item's record and Fleet's completed work, which no overview reader showed. The plugin names an answer that breaks off mid-message instead of reporting no answer. --- .changeset/slim-board-overview.md | 11 +++++ packages/work-board-plugin/README.md | 2 +- .../src/adapters/hostProtocol.ts | 5 ++ packages/work-board/README.md | 2 +- .../src/browser/views/OverviewProjection.ts | 10 +++- .../src/server/document/deliveredId.spec.ts | 20 +++++--- .../src/server/rpc/pluginReadLimit.spec.ts | 48 +++++++++++++++++++ .../src/test-support/socketVerbs.ts | 43 ++++++++++++----- .../src/test-support/workspaceBoardVerbs.ts | 10 ---- 9 files changed, 119 insertions(+), 32 deletions(-) create mode 100644 .changeset/slim-board-overview.md create mode 100644 packages/work-board/src/server/rpc/pluginReadLimit.spec.ts diff --git a/.changeset/slim-board-overview.md b/.changeset/slim-board-overview.md new file mode 100644 index 00000000..d6122d7e --- /dev/null +++ b/.changeset/slim-board-overview.md @@ -0,0 +1,11 @@ +--- +"@shivaedev/work-board": minor +--- + +### Fixed + +- `@shivaedev/work-board`: The Claude Code pane and its overview tool read the Board again on a board with much finished work. The overview answer had grown past the 4 MiB Claude Code reads of a plugin's answer, so the pane showed "The Work Board sent no answer to work-board.overview." It now carries only what the pane and the overview tools show, which keeps it small however much finished work the board keeps. + +### Breaking + +- `@shivaedev/work-board`: `work-board.overview` no longer returns `goals.items` or the ready Fleet's `completed` list. Read `work-board.goals` for the items and `work-board.fleetItems` for completed Fleet work. diff --git a/packages/work-board-plugin/README.md b/packages/work-board-plugin/README.md index e7f7e8fd..4ddfb602 100644 --- a/packages/work-board-plugin/README.md +++ b/packages/work-board-plugin/README.md @@ -20,7 +20,7 @@ The plugin needs a running Work Board. It finds one by walking up from the sessi npx @shivaedev/work-board .work ``` -Without a `.work` folder, the pane and every tool say the session's folder has no Work Board and how to start one; with a Board that is not running, they say so and name the start command. Claude Code waits 30 seconds for each Board answer; a Board still working after that is reported as busy, not stopped, and the next refresh asks again. The band stays hidden until the Board answers. Pressing a Needs you item opens it with `open -g` at the URL the Board says it is served on, so opening items works on macOS. +Without a `.work` folder, the pane and every tool say the session's folder has no Work Board and how to start one; with a Board that is not running, they say so and name the start command. Claude Code waits 30 seconds for each Board answer; a Board still working after that is reported as busy, not stopped, and the next refresh asks again. Claude Code also reads at most 4 MiB of each answer; an answer cut off there is reported as broken off at that limit, not as no answer. The band stays hidden until the Board answers. Pressing a Needs you item opens it with `open -g` at the URL the Board says it is served on, so opening items works on macOS. The plugin only reads the Board. Answer decisions in the Board itself or through [`@shivaedev/work-board`](../work-board/README.md). diff --git a/packages/work-board-plugin/src/adapters/hostProtocol.ts b/packages/work-board-plugin/src/adapters/hostProtocol.ts index e04e92e3..f6fd59ce 100644 --- a/packages/work-board-plugin/src/adapters/hostProtocol.ts +++ b/packages/work-board-plugin/src/adapters/hostProtocol.ts @@ -26,6 +26,11 @@ const exchange = Effect.fn("WorkboardPlugin.exchange")(function* ( catch: (cause) => defect(cause instanceof Error ? cause.message : String(cause), cause), try: () => post(body), }); + if (text !== "" && !text.endsWith("\n")) { + return yield* defect( + `The Work Board's answer to ${request.tag} breaks off mid-message after ${text.length} characters. Claude Code reads at most 4 MiB of an answer.`, + ); + } const responses = yield* Effect.try({ catch: (cause) => defect("The Work Board answered with an unreadable RPC stream.", cause), try: () => parser.decode(text).filter(isServerMessage), diff --git a/packages/work-board/README.md b/packages/work-board/README.md index 9b3527af..613ae09b 100644 --- a/packages/work-board/README.md +++ b/packages/work-board/README.md @@ -432,7 +432,7 @@ Call this function with a revision whose source/context you have reviewed and a `client.api.goals.query()` returns `{ closedGoals, deferredGoals, goals, items }`. Goals are uniquely identified goal documents grouped by authored status, with standing homes kept active. `items` holds identified implementing documents with source metadata and open-ask context; answer records are excluded. Each goal has authored fields, `criteria`, `asks`, `openAsks`, task `counts`, `linked` and `unlinked`, plus `lanes` containing each implementing goal and its own task counts. Counts use `done`, `running`, `blocked`, `scheduled` and `parked`, count each task once through child goals, and exclude dropped tasks. Each criterion includes its task counts and the number of recorded evidence claims targeting it. Started Fleet work stays running until done or released, including turns waiting for an answer, CI or merge; work blocked before it starts counts as blocked. Fleet replies without execution details use their working or reviewing stage. Approved work that has not started counts as scheduled; draft, deferred, held and manual work stays parked. Mounted queries refresh when indexed source changes. [Read a goal](docs/reading.md#read-a-goal) describes the goal page that renders this query. -`client.api.overview.query()` returns `{ fleet, goals }` from one Board index and one Fleet read. The pane and overview tools use this snapshot so In flight and goal running counts agree. An unreachable Fleet returns an explicit unavailable state. +`client.api.overview.query()` returns `{ fleet, goals }` from one Board index and one Fleet read. The pane and overview tools use this snapshot so In flight and goal running counts agree. `goals` holds the three goal lists without `items`, and a ready `fleet` holds `items` and `areas` without `completed`, so the answer stays within the 4 MiB Claude Code reads of a plugin's answer however much finished work the board keeps; `goals` and `fleetItems` return those. An unreachable Fleet returns an explicit unavailable state. For a handoff, first read the preview with `client.run(client.handoffs.handoffSource.run({ item: "work.search" }))` and inspect its `context`. This complete program takes that reviewed path and revision as inputs: diff --git a/packages/work-board/src/browser/views/OverviewProjection.ts b/packages/work-board/src/browser/views/OverviewProjection.ts index 9cf34471..dd7cb745 100644 --- a/packages/work-board/src/browser/views/OverviewProjection.ts +++ b/packages/work-board/src/browser/views/OverviewProjection.ts @@ -1,5 +1,11 @@ -import { Schema } from "effect"; +import { Schema, Struct } from "effect"; import { FleetItemsProjection } from "./FleetItemsProjection.ts"; import { GoalsProjection } from "./GoalsProjection.ts"; -export const OverviewProjection = Schema.Struct({ fleet: FleetItemsProjection, goals: GoalsProjection }); +// Claude Code reads at most 4 MiB of a plugin's answer, so the overview leaves out the finished history that grows +// with the board: every item's record and Fleet's completed work. +const [ReadyFleet, UnavailableFleet] = FleetItemsProjection.members; +export const OverviewProjection = Schema.Struct({ + fleet: Schema.Union([ReadyFleet.mapFields(Struct.omit(["completed"])), UnavailableFleet]), + goals: GoalsProjection.mapFields(Struct.omit(["items"])), +}); diff --git a/packages/work-board/src/server/document/deliveredId.spec.ts b/packages/work-board/src/server/document/deliveredId.spec.ts index 884b0560..e6c677b8 100644 --- a/packages/work-board/src/server/document/deliveredId.spec.ts +++ b/packages/work-board/src/server/document/deliveredId.spec.ts @@ -40,7 +40,7 @@ const SHOWN = Array.from({ length: 30 }, (_, index) => `fleet.shown-${index}`); const fleetItem = { attentionOwner: "automation" as const, stage: "working" as const, stageEnteredAt: 100, updatedAt: 200 }; boardStory.it( - "the overview checks all thirty shown briefs with Fleet in one request and hides the one Fleet refuses", + "the Fleet work view checks all thirty shown briefs with Fleet in one request and hides the one Fleet refuses", [ projectFiles({ ...Object.fromEntries(SHOWN.map((id, index) => [`tasks/${index}.md`, `---\nid: ${id}\nkind: task\nstatus: ready\n---\n# Shown ${index}\n`])), @@ -54,10 +54,18 @@ boardStory.it( }, ), ], - function* ({ fleetBriefRequests, overviewFleet }) { - const overview = yield* overviewFleet(); - - expect(overview).toEqual({ completed: ["fleet.delivered"], shown: SHOWN.slice(1) }); - expect(yield* fleetBriefRequests()).toEqual([SHOWN.map((id, index) => `${id} at tasks/${index}.md`)]); + function* ({ fleetBriefRequests, fleetWork }) { + yield* outcomes([ + [ + "Fleet work", + () => fleetWork(), + expect.objectContaining({ + completed: [expect.objectContaining({ workId: "fleet.delivered" })], + items: SHOWN.slice(1).map((workId) => expect.objectContaining({ workId })), + state: "ready", + }), + ], + ["briefs asked about", () => fleetBriefRequests(), [SHOWN.map((id, index) => `${id} at tasks/${index}.md`)]], + ]); }, ); diff --git a/packages/work-board/src/server/rpc/pluginReadLimit.spec.ts b/packages/work-board/src/server/rpc/pluginReadLimit.spec.ts new file mode 100644 index 00000000..f8d62201 --- /dev/null +++ b/packages/work-board/src/server/rpc/pluginReadLimit.spec.ts @@ -0,0 +1,48 @@ +import { expect } from "vitest"; +import { boardStory, projectFiles } from "#test/boardStory.ts"; + +const NOTE = "n".repeat(512 * 1024); +const FINISHED = Array.from({ length: 9 }, (_, index) => index); + +boardStory.it( + "the plugin reads goal progress from a board whose finished tasks hold more than Claude Code reads of one answer", + [ + projectFiles({ + "goal.md": "---\nid: goal.ship\nkind: goal\nstatus: ready\n---\n# Ship the Board", + ...Object.fromEntries( + FINISHED.map((index) => [ + `done/${index}.md`, + `---\nid: task.done-${index}\nkind: task\nstatus: done\nnext_action: ${NOTE}\nrelationships:\n - kind: implements\n target: goal.ship\n---\n# Finished ${index}\n`, + ]), + ), + }), + ], + function* ({ openPlugin, pluginProgress }) { + yield* openPlugin(); + + expect(yield* pluginProgress()).toBe("9 of 9 done"); + }, +); + +const CRITERION = "c".repeat(1536 * 1024); + +boardStory.it( + "the plugin says the Board's answer broke off at Claude Code's read limit instead of saying it sent none", + [ + projectFiles( + Object.fromEntries( + [1, 2, 3].map((index) => [ + `goal-${index}.md`, + `---\nid: goal.wide-${index}\nkind: goal\nstatus: ready\ncriteria:\n - id: wide\n text: ${CRITERION}\n---\n# Wide goal ${index}\n`, + ]), + ), + ), + ], + function* ({ openPlugin, pluginProblem }) { + yield* openPlugin(); + + expect(yield* pluginProblem()).toBe( + "The Work Board's answer to work-board.overview breaks off mid-message after 4194304 characters. Claude Code reads at most 4 MiB of an answer.", + ); + }, +); diff --git a/packages/work-board/src/test-support/socketVerbs.ts b/packages/work-board/src/test-support/socketVerbs.ts index 1dca2aa3..0a404eb6 100644 --- a/packages/work-board/src/test-support/socketVerbs.ts +++ b/packages/work-board/src/test-support/socketVerbs.ts @@ -8,6 +8,8 @@ import { type BoardEngine, connected, served } from "#test/storyEngine.ts"; type WorkboardBoard = ReturnType; +const HOST_READ_BYTES = 4 * 1024 * 1024; + export interface SocketObservations { readonly connections: string[]; } @@ -33,9 +35,17 @@ export function socketVerbs(engine: BoardEngine, tell: (line: string) => void) { } function boardSocket(body: string) { return socketExchange(join(engine.notes.root, "board.sock"), rpcPost(engine.notes.root, body)).then((reply) => - reply.ok ? reply.text : Promise.reject(new Error(`The board refused the plugin's request (${reply.status})`)), + reply.ok + ? new TextDecoder().decode(new TextEncoder().encode(reply.text).subarray(0, HOST_READ_BYTES)) + : Promise.reject(new Error(`The board refused the plugin's request (${reply.status})`)), ); } + function opened() { + if (plugin === undefined) { + throw new Error("The plugin is not open; call openPlugin first"); + } + return plugin; + } return { followDocument: (url: string) => Effect.gen(function* () { @@ -53,24 +63,33 @@ export function socketVerbs(engine: BoardEngine, tell: (line: string) => void) { Effect.gen(function* () { const clock = yield* Clock.Clock; const { platformClient } = yield* bundledClient(); - tell("the Claude plugin opens its shipped client, which posts each request over board.sock as the host's fetch does"); + tell( + "the Claude plugin opens its shipped client, which posts each request over board.sock and reads at most 4 MiB of each answer, as the host's fetch does", + ); const client = platformClient(engine.notes.root, boardSocket, () => Promise.resolve(clock.currentTimeMillisUnsafe())); plugin = client; return client; }), (client) => Effect.sync(client.close), ), - pluginProgress: () => { - tell("the plugin reads the board, as its Refresh button and timer do, and shows its goal progress"); - const client = plugin; - if (client === undefined) { - return Effect.die(new Error("The plugin is not open; call openPlugin first")); - } - return Effect.map( - Effect.promise(() => client.board()), + pluginProblem: () => + Effect.promise(() => { + tell("the plugin reads the board, as its Refresh button and timer do, and shows why it could not"); + return opened() + .board() + .then( + () => "the board answered", + (error: unknown) => (error instanceof Error ? error.message : String(error)), + ); + }), + pluginProgress: () => + Effect.map( + Effect.promise(() => { + tell("the plugin reads the board, as its Refresh button and timer do, and shows its goal progress"); + return opened().board(); + }), progressOf, - ); - }, + ), socketsOpened: () => Effect.sync(() => { tell("the reader lists the sockets the page and the node clients opened"); diff --git a/packages/work-board/src/test-support/workspaceBoardVerbs.ts b/packages/work-board/src/test-support/workspaceBoardVerbs.ts index 1b0211e5..c3a16592 100644 --- a/packages/work-board/src/test-support/workspaceBoardVerbs.ts +++ b/packages/work-board/src/test-support/workspaceBoardVerbs.ts @@ -227,15 +227,5 @@ export function workspaceBoardVerbs(engine: BoardEngine, tell: (line: string) => return { goals: navigation.counts.goals, inbox: navigation.inboxCount ?? "unknown" }; }, ), - overviewFleet: () => - Effect.map( - rpc((client) => client("work-board.overview", undefined)), - ({ fleet }) => { - tell("the reader checks the Fleet work the overview shows"); - return fleet.state === "ready" - ? { completed: fleet.completed.map((item) => item.workId), shown: fleet.items.map((item) => item.workId) } - : fleet.state; - }, - ), }; }