diff --git a/.changeset/mcp-waits-for-busy-board.md b/.changeset/mcp-waits-for-busy-board.md
new file mode 100644
index 00000000..50134488
--- /dev/null
+++ b/.changeset/mcp-waits-for-busy-board.md
@@ -0,0 +1,7 @@
+---
+"@shivaedev/work-board": patch
+---
+
+### Fixed
+
+- `work-board mcp` waits 30 seconds for a busy board instead of 10, so a Fleet view that takes most of its 25-second budget no longer reads as a stopped board. A board that does not answer in time is reported as busy, and an unreachable board as not reachable with the command that starts it.
diff --git a/packages/work-board/README.md b/packages/work-board/README.md
index 9b3527af..544023ca 100644
--- a/packages/work-board/README.md
+++ b/packages/work-board/README.md
@@ -567,7 +567,9 @@ claude mcp add --transport stdio work-board -- work-board mcp /absolute/path/to/
codex mcp add work-board -- work-board mcp /absolute/path/to/notes
```
-Both commands require `work-board` on the client's PATH. `work-board mcp
` reads the running board through `/board.sock`; it uses the same computed queries as the browser. If no board answers, every tool returns one error naming the directory and the `work-board ` command to start it.
+Both commands require `work-board` on the client's PATH. Without a global install, register `pnpm dlx @shivaedev/work-board mcp /absolute/path/to/notes`. Avoid `npx -y @shivaedev/work-board`: npm keeps its first install of the package, refuses to update that copy once a release pins another Effect version, and the server exits before the client connects.
+
+`work-board mcp ` reads the running board through `/board.sock`; it uses the same computed queries as the browser. The server starts and lists its tools whether or not a board runs, and each tool call reads the board when it runs, so a board that starts later answers the next call. A call waits for a busy board while its Fleet view finishes. If no board answers, the tool returns one error naming the directory and the `work-board ` command to start it.
| Tool | Returns |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
diff --git a/packages/work-board/src/server/diagnostics/daemon.ts b/packages/work-board/src/server/diagnostics/daemon.ts
index 76eae6cf..4ccb74cc 100644
--- a/packages/work-board/src/server/diagnostics/daemon.ts
+++ b/packages/work-board/src/server/diagnostics/daemon.ts
@@ -10,8 +10,10 @@ function makeDaemonClient() {
type DaemonClient = Effect.Success>;
const FLEET_STOPPED = "Fleet isn't running, so agent work and its health are unknown.";
-// A busy Fleet took up to 15 seconds for one read in measurement.
+// A busy Fleet took up to 15 seconds for one read in measurement. Both reads of the Fleet view share one budget,
+// so the Board answers inside the 30 seconds Claude Code's plugin fetch waits.
const FLEET_WAIT_SECONDS = 20;
+export const FLEET_VIEW_MS = 25_000;
// npx runs the project's own @shivaedev/work-fleet, because the bare work-fleet command is rarely on PATH.
export function daemonUnavailable(error: unknown, port: number, folder: string): { readonly reason: string; readonly startCommand?: string } {
diff --git a/packages/work-board/src/server/mcp.slow.spec.ts b/packages/work-board/src/server/mcp.slow.spec.ts
new file mode 100644
index 00000000..b900f979
--- /dev/null
+++ b/packages/work-board/src/server/mcp.slow.spec.ts
@@ -0,0 +1,18 @@
+import { expect, vi } from "vitest";
+import { boardStory, projectFiles } from "#test/boardStory.ts";
+import { slowFleetDaemon } from "#test/workspaceBoardTraits.ts";
+
+vi.setConfig({ testTimeout: 60_000 });
+
+const project = projectFiles({ "one.md": "---\nid: one\nkind: task\nstatus: draft\n---\n# First task" });
+const reported = { completed: [], items: [{ stage: "queued" as const, stageEnteredAt: 100, updatedAt: 200, workId: "one" }] };
+
+boardStory.it(
+ "an agent's board_overview waits for a busy Fleet that answers after 15 seconds",
+ [project, slowFleetDaemon(reported, 15)],
+ function* ({ agentReads }) {
+ expect(yield* agentReads("board_overview")).toMatchObject({
+ fleet: { items: [expect.objectContaining({ stage: "queued", workId: "one" })], state: "ready" },
+ });
+ },
+);
diff --git a/packages/work-board/src/server/mcp.spec.ts b/packages/work-board/src/server/mcp.spec.ts
index 2b9ecdc8..fe252166 100644
--- a/packages/work-board/src/server/mcp.spec.ts
+++ b/packages/work-board/src/server/mcp.spec.ts
@@ -22,7 +22,7 @@ const withFleet = [
})),
];
const unavailable = { reason: "Fleet isn't set up for this Board.", state: "unavailable" };
-const NO_BOARD = "error: No board answers in the project folder. Start one with: work-board 'the project folder'";
+const NO_BOARD = "error: The Work Board in the project folder is not reachable. Start it with: work-board 'the project folder'";
boardStory.it("an agent connecting over MCP stdio finds three read-only tools", withFleet, function* ({ agentTools }) {
expect(yield* agentTools()).toEqual([
@@ -32,6 +32,18 @@ boardStory.it("an agent connecting over MCP stdio finds three read-only tools",
]);
});
+boardStory.it(
+ "with no board running, an agent connecting over MCP stdio still finds the three tools",
+ [project, deferredServing],
+ function* ({ agentTools }) {
+ expect(yield* agentTools()).toEqual([
+ { name: "board_overview", readOnly: true },
+ { name: "item", readOnly: true },
+ { name: "needs_you", readOnly: true },
+ ]);
+ },
+);
+
boardStory.it(
"board_overview reports the Fleet items, the goal counts and the Needs-you list the browser computes",
withFleet,
@@ -86,7 +98,7 @@ for (const [tool, args] of [
["item", { id: "task.first" }],
] as const) {
boardStory.it(
- `with no board running, ${tool} answers one error that says how to start the board`,
+ `with no board running, ${tool} answers that the board is not reachable and how to start it`,
[project, deferredServing],
function* ({ agentReads }) {
expect(yield* agentReads(tool, args)).toBe(NO_BOARD);
@@ -94,6 +106,18 @@ for (const [tool, args] of [
);
}
+boardStory.it(
+ "an agent that connected before the board started reads the board once it starts",
+ [project, deferredServing],
+ function* ({ agentReads, boardStarts }) {
+ expect(yield* agentReads("board_overview")).toBe(NO_BOARD);
+
+ yield* boardStarts();
+
+ expect(yield* agentReads("board_overview")).toEqual(expect.objectContaining({ fleet: expect.objectContaining(unavailable) }));
+ },
+);
+
boardStory.it(
"without Fleet, board_overview and item say Fleet isn't set up instead of failing",
[project, boardWithoutFleet],
@@ -147,7 +171,7 @@ boardStory.it("item answers an error that names a missing item", [project, board
});
boardStory.it(
- "after the board stops, an agent's next read says no board answers",
+ "after the board stops, an agent's next read says the board is not reachable",
[project, boardWithoutFleet],
function* ({ agentReads, boardStops }) {
expect(yield* agentReads("board_overview")).toEqual(expect.objectContaining({ fleet: expect.objectContaining(unavailable) }));
diff --git a/packages/work-board/src/server/mcp/client.ts b/packages/work-board/src/server/mcp/client.ts
index 99b2ee23..f32d5dd9 100644
--- a/packages/work-board/src/server/mcp/client.ts
+++ b/packages/work-board/src/server/mcp/client.ts
@@ -1,12 +1,13 @@
import { connect } from "node:net";
import { join } from "node:path";
import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
-import { Effect, Layer, Schema } from "effect";
+import { Cause, Effect, Layer, Schema } from "effect";
import { HttpClient, HttpClientRequest } from "effect/http";
import { RpcClient, RpcSerialization } from "effect/rpc";
import { RpcClientError } from "effect/rpc/RpcClientError";
import { errorMessage } from "#errorMessage.ts";
import { workContract } from "#rpc/contract.ts";
+import { FLEET_VIEW_MS } from "#server/diagnostics/daemon.ts";
import { RPC_PATH } from "#server/http/rpcPolicy.ts";
export class BoardToolError extends Schema.TaggedError()("BoardToolError", { message: Schema.String }) {}
@@ -16,9 +17,19 @@ function makeClient() {
}
export type BoardClient = Effect.Success>;
+// The Board's Fleet view alone may take its whole budget, and the Board's own index and document reads come on top.
+const BOARD_WAIT_SECONDS = FLEET_VIEW_MS / 1000 + 5;
+
function toolError(directory: string, error: unknown) {
- if (error instanceof RpcClientError || (error instanceof Error && "_tag" in error && error._tag === "TimeoutError")) {
- return new BoardToolError({ message: `No board answers in ${directory}. Start one with: work-board '${directory.replaceAll("'", "'\\''")}'` });
+ if (Cause.isTimeoutError(error)) {
+ return new BoardToolError({
+ message: `The Work Board in ${directory} did not answer within ${BOARD_WAIT_SECONDS} seconds. It may be busy; try again.`,
+ });
+ }
+ if (error instanceof RpcClientError) {
+ return new BoardToolError({
+ message: `The Work Board in ${directory} is not reachable. Start it with: work-board '${directory.replaceAll("'", "'\\''")}'`,
+ });
}
return new BoardToolError({ message: errorMessage(error) });
}
@@ -38,7 +49,7 @@ export function readBoard(directory: string, read: (client: BoardClient) =
}).pipe(Layer.provide([http, RpcSerialization.layerNdjson]));
return Effect.scoped(Effect.flatMap(makeClient(), read)).pipe(
Effect.provide(protocol),
- Effect.timeout("10 seconds"),
+ Effect.timeout(`${BOARD_WAIT_SECONDS} seconds`),
Effect.mapError((error) => toolError(directory, error)),
);
}
diff --git a/packages/work-board/src/server/views/fleetItems.ts b/packages/work-board/src/server/views/fleetItems.ts
index aa431707..574d5467 100644
--- a/packages/work-board/src/server/views/fleetItems.ts
+++ b/packages/work-board/src/server/views/fleetItems.ts
@@ -6,7 +6,7 @@ import { laneOf } from "#browser/views/now.ts";
import { DAEMON_PORT } from "#diagnostics/daemonContract.ts";
import { inboxItems } from "#server/attention/inbox.ts";
import { requestInbox } from "#server/attention/requestInbox.ts";
-import { daemonUnavailable, readDaemon } from "#server/diagnostics/daemon.ts";
+import { daemonUnavailable, FLEET_VIEW_MS, readDaemon } from "#server/diagnostics/daemon.ts";
import { fleetChecksBrief } from "#server/document/briefDiagnostic.ts";
import { itemRequests } from "#server/document/requests.ts";
import type { Snapshot } from "#server/search/snapshot.ts";
@@ -39,9 +39,6 @@ const fleetItemsUnavailable = Effect.fn("WorkBoard.fleetItemsUnavailable")(funct
return projection;
});
-// Both Fleet reads share one budget, so the Board answers inside the 30 seconds Claude Code's plugin fetch waits.
-const FLEET_VIEW_MS = 25_000;
-
export function fleetItems(folder: string, fleetPort: number | null = DAEMON_PORT): Effect.Effect {
if (fleetPort === null) {
return fleetItemsUnavailable({ reason: "Fleet isn't set up for this Board." });
diff --git a/packages/work-board/src/test-support/mcpClient.ts b/packages/work-board/src/test-support/mcpClient.ts
index 9416f003..d7d18f81 100644
--- a/packages/work-board/src/test-support/mcpClient.ts
+++ b/packages/work-board/src/test-support/mcpClient.ts
@@ -76,7 +76,7 @@ export const mcpClient = Effect.fn("Test.mcpClient")(function* (directory: strin
pending.set(id, { reject, resolve });
child.stdin.write(`${JSON.stringify({ id, jsonrpc: "2.0", method, params })}\n`);
}),
- ).pipe(Effect.timeout("15 seconds"));
+ ).pipe(Effect.timeout("45 seconds"));
}
yield* send("initialize", { capabilities: {}, clientInfo: { name: "board-test", version: "1" }, protocolVersion: "2025-11-25" });
child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);