Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .changeset/busy-areas-patient-fleet.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
"@shivaedev/work-board": minor
"@shivaedev/work-fleet": patch
---

### Changed

- `@shivaedev/work-fleet`: `daemon.fleetItems` lists only the areas that Fleet work holds, queues or reserves. It no longer lists every repository folder as an idle area.

### Fixed

- `@shivaedev/work-board`: Board waits up to 20 seconds for each Fleet read, up from 5, so a busy Fleet no longer shows as unavailable. Its Fleet view, items and brief checks together, stays within 25 seconds, inside the 30 seconds Claude Code waits for a plugin's request. A Fleet that has not answered by then is reported as not answering in time.

### Breaking

- `@shivaedev/work-board`: The `board` integration object no longer exports `areaFolders` or `repositoryRoot`. Fleet stopped using them. A consumer that needs area folders reads the repository directly.
4 changes: 2 additions & 2 deletions packages/work-board-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ 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. 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. 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).

### The pane

The pane folds goals with status `done` under an “Achieved (N)” row, closed by default. Click it to show those goals. Open goals stay visible, including goals whose tasks are all done. In flight and goal running counts use the same Board overview snapshot. If Fleet cannot be reached, In flight shows why it is unavailable.

Areas appear as wrapping chips. Green means no holder and no approved task queued; amber marks a held area or a queue of fewer than five tasks; red marks five or more queued tasks. Each chip names its state and queue count. Open a chip to read its holders, stages and PR links, followed by the approved queue in Fleet's order. Package folders and the Board's other repository areas stay visible even when idle. A Fleet daemon that does not supply availability is shown as unknown.
Areas lists only the areas Fleet holds or queues work for, as wrapping chips with held areas first; free areas are left out, and with none busy the section says no area is held or queued. Amber marks a held area or a queue of fewer than five tasks; red marks five or more queued tasks. Each chip names its state and queue count. Open a chip to read its holders, stages and PR links, followed by the approved queue in Fleet's order. A Fleet daemon that does not supply availability is shown as unknown.

### Install

Expand Down
4 changes: 2 additions & 2 deletions packages/work-board-plugin/src/adapters/hostBoard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import type { EngineInterface, HttpResponse } from "claude-code";
import { platformClient } from "#adapters/platformClient.ts";
import type { Board } from "#boardTools.ts";
import { findBoard } from "#findBoard.ts";
import { refusedLine, waitingLine } from "#lines.ts";
import { refusedLine, unansweredLine, waitingLine } from "#lines.ts";
import { RPC_URL, rpcPost } from "#rpc.ts";

type Client = ReturnType<typeof platformClient>;
Expand All @@ -12,7 +12,7 @@ async function post($: EngineInterface, directory: string, body: string): Promis
try {
response = await $.http.fetch(RPC_URL, rpcPost(directory, body));
} catch (cause) {
throw new Error(waitingLine({ directory, kind: "down" }), { cause });
throw new Error(unansweredLine(directory, cause), { cause });
}
if (!response.ok) {
throw new Error(refusedLine(response, directory));
Expand Down
4 changes: 2 additions & 2 deletions packages/work-board-plugin/src/areaAvailability.dom.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@ const files = Object.fromEntries(
);

pluginFleet.it(
"the plugin's area chips read live Fleet ownership and queues through Board HTTP",
"the plugin's area chips read live Fleet ownership and queues through Board HTTP and leave idle folders out",
[boardWork(files)],
function* ({ approve, admit, openPane }) {
yield* approve("holder");
yield* admit();
const pane = yield* openPane();
yield* outcomes([
["Chips", () => pane.areaChips(), ["work-fleet", "work-board"]],
["Held area", () => pane.areaState("work-fleet"), { color: "#d74253", state: "held · 5 queued" }],
["Short queue", () => pane.areaState("work-board"), { color: "#ad7400", state: "unheld · 1 queued" }],
["Idle area", () => pane.areaState("free"), { color: "#16853f", state: "free" }],
]);
},
);
23 changes: 13 additions & 10 deletions packages/work-board-plugin/src/areaView.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,6 @@ import type { WorkboardArea, WorkboardAreaTask, WorkboardBlock } from "#types/in

function stateOf(area: WorkboardArea) {
const count = area.queue.length;
if (area.holders.length === 0 && count === 0) {
return { color: "#16853f", label: "free" };
}
return { color: count >= 5 ? "#d74253" : "#ad7400", label: `${area.holders.length > 0 ? "held" : "unheld"} · ${count} queued` };
}

Expand All @@ -16,13 +13,7 @@ export function areaView(t: Table, areas: WorkboardBlock<WorkboardArea>, view: P
return (
<Box flexDirection="column" gap={1}>
<Text weight="semibold">Areas</Text>
{areas.problem === null ? (
<Box columnGap={2} flexDirection="row" flexWrap="wrap" gap={1}>
{areas.items.map((area) => areaChip(t, area, view.onToggleArea))}
</Box>
) : (
<Text dimColor>{areas.problem}</Text>
)}
{areas.problem === null ? areaChips(t, areas.items, view.onToggleArea) : <Text dimColor>{areas.problem}</Text>}
{areas.problem === null && selected !== undefined ? (
<Box flexDirection="column">
<Text weight="semibold">{selected.area}</Text>
Expand All @@ -38,6 +29,18 @@ export function areaView(t: Table, areas: WorkboardBlock<WorkboardArea>, view: P
);
}

function areaChips(t: Table, areas: WorkboardArea[], onToggle: (area: string) => void) {
const { Box, Text } = t;
if (areas.length === 0) {
return <Text dimColor>No area is held or queued.</Text>;
}
return (
<Box columnGap={2} flexDirection="row" flexWrap="wrap" gap={1}>
{areas.map((area) => areaChip(t, area, onToggle))}
</Box>
);
}

function areaChip(t: Table, area: WorkboardArea, onToggle: (area: string) => void) {
const { Box, Text, Button } = t;
const state = stateOf(area);
Expand Down
25 changes: 18 additions & 7 deletions packages/work-board-plugin/src/areas.dom.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,21 @@ import { areasAnswered, paneColumns, pluginPane } from "#test/pluginPane.ts";
const holder = { prUrl: "https://github.com/example/project/pull/42", stage: "reviewing", workId: "Build Fleet" };
const queue = ["First", "Second", "Third", "Fourth", "Fifth"].map((workId) => ({ prUrl: null, stage: "queued", workId }));
const availability = areasAnswered([
{ area: "work-fleet", holders: [holder], queue },
{ area: ".pnpm-store", holders: [], queue: [] },
{ area: "work-board", holders: [], queue: queue.slice(0, 1) },
{ area: "work-fleet", holders: [holder], queue },
{ area: "work-github", holders: [holder], queue: [] },
{ area: "free", holders: [], queue: [] },
]);

pluginPane.it(
"area chips distinguish a held long queue, a short queue and idle work",
"area chips show only held and queued areas, held areas first, and tell a long queue from a short one",
[availability, paneColumns(32)],
function* ({ areaState, click, areaDetails }) {
function* ({ areaChips, areaState, click, areaDetails }) {
yield* outcomes([
["Chips", () => areaChips(), ["work-fleet", "work-github", "work-board"]],
["Held area", () => areaState("work-fleet"), { color: "#d74253", state: "held · 5 queued" }],
["Short queue", () => areaState("work-board"), { color: "#ad7400", state: "unheld · 1 queued" }],
["Idle area", () => areaState("free"), { color: "#16853f", state: "free" }],
]);
yield* click("work-fleet");
expect(yield* areaDetails()).toEqual([
Expand All @@ -31,13 +33,22 @@ pluginPane.it(
]);
yield* click("work-board");
expect(yield* areaDetails()).toEqual(["work-board", "No holder", "1. First · queued"]);
yield* click("free");
expect(yield* areaDetails()).toEqual(["free", "No holder", "No approved tasks queued"]);
yield* click("free");
yield* click("work-board");
expect(yield* areaDetails()).toEqual([]);
},
);

pluginPane.it(
"a Fleet whose areas are all free shows that no area is held or queued",
[areasAnswered([{ area: "free", holders: [], queue: [] }])],
function* ({ areaChips, lookOf }) {
yield* outcomes([
["Chips", () => areaChips(), []],
["Notice", () => lookOf("No area is held or queued."), "dimmed"],
]);
},
);

pluginPane.it("an older Fleet reply leaves area availability unknown", [], function* ({ lookOf }) {
expect(yield* lookOf("This Fleet has not supplied area availability.")).toBe("dimmed");
});
8 changes: 4 additions & 4 deletions packages/work-board-plugin/src/areasOf.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ export function areasOf(value: unknown): WorkboardBlock<WorkboardArea> {
return { prUrl: text(entry.prUrl) ?? null, stage: text(entry.stage) ?? "unknown", title: titles.get(workId) ?? workId, workId };
});
}
return {
items: records(value.areas).map((entry) => ({ area: text(entry.area) ?? "unknown", holders: tasks(entry.holders), queue: tasks(entry.queue) })),
problem: null,
};
const busy = records(value.areas)
.map((entry) => ({ area: text(entry.area) ?? "unknown", holders: tasks(entry.holders), queue: tasks(entry.queue) }))
.filter((area) => area.holders.length > 0 || area.queue.length > 0);
return { items: [...busy.filter((area) => area.holders.length > 0), ...busy.filter((area) => area.holders.length === 0)], problem: null };
}
9 changes: 9 additions & 0 deletions packages/work-board-plugin/src/lines.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,15 @@ export function waitingLine(state: Exclude<WorkboardBoard, { kind: "ready" }>):
return "Loading the Work Board…";
}

// The host aborts $.http.fetch after a fixed wait and says so in its error; any other failure means nothing answered on the socket.
export function unansweredLine(directory: string, cause: unknown): string {
const message = cause instanceof Error ? cause.message : String(cause);
const waited = /no complete answer within (?<ms>\d+)ms/u.exec(message)?.groups?.ms;
return waited === undefined
? waitingLine({ directory, kind: "down" })
: `The Work Board for ${directory} is busy: it took longer than ${Math.round(Number(waited) / 1000)} seconds to answer. The pane asks again on its next refresh.`;
}

export function refusedLine(response: RpcReply, directory: string): string {
return `The Work Board for ${directory} refused the request (${response.status}): ${response.text.trim()}`;
}
Expand Down
20 changes: 20 additions & 0 deletions packages/work-board-plugin/src/lines.unit.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import { describe, expect, it } from "vitest";
import { unansweredLine } from "#lines.ts";

describe("a Board request that got no answer", () => {
it("calls a Board busy when the host gave up waiting for its answer", () => {
const cause = new Error(
"workboard: $.http.fetch(http://localhost/_board/rpc) over /work/.work/board.sock aborted: no complete answer within 30000ms",
);
expect(unansweredLine("/work", cause)).toBe(
"The Work Board for /work is busy: it took longer than 30 seconds to answer. The pane asks again on its next refresh.",
);
});

it("calls a Board not running when nothing answered on its socket", () => {
const cause = new Error(
"workboard: $.http.fetch(http://localhost/_board/rpc) over /work/.work/board.sock failed: ECONNREFUSED: connect ECONNREFUSED",
);
expect(unansweredLine("/work", cause)).toBe("The Work Board for /work isn't running. Start it there: npx @shivaedev/work-board .work");
});
});
6 changes: 6 additions & 0 deletions packages/work-board-plugin/src/test-support/areaReadouts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@ import { Effect } from "effect";

export function areaReadouts(container: Element, tell: (text: string) => void) {
return {
areaChips: () =>
Effect.sync(() => {
tell("read the area chips in the order the pane shows them");
const heading = [...container.querySelectorAll("span")].find((span) => span.textContent === "Areas");
return [...(heading?.parentElement?.children[1]?.querySelectorAll("button") ?? [])].map((button) => button.textContent);
}),
areaDetails: () =>
Effect.sync(() => {
tell("read the open area's holder and ordered queue");
Expand Down
2 changes: 1 addition & 1 deletion packages/work-board/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ An open page updates in place as files change, and **Pause updates** holds what

The view refreshes through `client.api.diagnostics.query()` every 15 seconds while visible. Pause updates holds the displayed state; resume and returning to a visible tab refresh it. The shared `DiagnosticsContract` and `DiagnosticsSnapshot` schemas live in `@shivaedev/work-board/diagnostics/daemonContract.ts`; the version 2 `FleetHealth` schema lives in `@shivaedev/work-board/diagnostics/health.ts`. The Fleet lane lists every running or waiting item from `client.api.fleetItems.query()` by source title, stage and recorded PR, with explicit loading, unavailable and empty states. Items without readable source retain their work ID; missing PRs remain explicit. The page also shows the publisher's observation time, freshness, running and queued counts, the **Needs you** count Today and the sidebar show, Fleet's counts of work waiting on the orchestrator and on Fleet agents, concurrency cap, last scheduler pass and last observed provider capacity rejection. Fleet's waiting counts never mark the Fleet card as needing attention, so the Board's count stays the only needs-you number on System. Stale snapshots show a Stale badge. Reset times show relative time and the browser’s local clock; System requires JavaScript. Communication failures and API-key accounts explain why their data is unavailable. A publisher clock ahead of Board is disclosed; absent scheduler/rejection observations remain unknown or unobserved.

`client.api.fleetItems.run(undefined)` reads per-item execution through the same daemon client. A `ready` result has `items` for every stage except `done` and `released`, and `completed` for current records completed within the last seven days, including the boundary. Each item carries `workId`, `stage`, a waiting `attentionOwner` when present, `prUrl` when known, and millisecond `stageEnteredAt` and `updatedAt`; completions also carry `completedAt`. Board joins each unique matching ID to `document: { file, title, metadata }`; missing or duplicate IDs keep the Fleet item with `document: null`. For legacy records, stage entry and completion times remain unknown until an observed stage transition; `updatedAt` becomes known on the next write. A stopped daemon returns `{ state: "unavailable", reason, startCommand }`; a communication failure or Board index failure returns `{ state: "unavailable", reason }`. When Board can read every source, an unavailable result also carries `authored`: tasks whose authored status is `ready`, each with `file`, `status`, `title` and `workId`. Set `BoardOptions.fleetPort: null` to disable the item integration.
`client.api.fleetItems.run(undefined)` reads per-item execution through the same daemon client. A `ready` result has `items` for every stage except `done` and `released`, and `completed` for current records completed within the last seven days, including the boundary. Each item carries `workId`, `stage`, a waiting `attentionOwner` when present, `prUrl` when known, and millisecond `stageEnteredAt` and `updatedAt`; completions also carry `completedAt`. Board joins each unique matching ID to `document: { file, title, metadata }`; missing or duplicate IDs keep the Fleet item with `document: null`. For legacy records, stage entry and completion times remain unknown until an observed stage transition; `updatedAt` becomes known on the next write. A stopped daemon returns `{ state: "unavailable", reason, startCommand }`; a communication failure or Board index failure returns `{ state: "unavailable", reason }`. Board waits up to 20 seconds for each daemon read, so a busy Fleet still answers, and keeps the whole Fleet view, items and brief checks together, within 25 seconds; a daemon that has not answered by then is reported as not answering in time. When Board can read every source, an unavailable result also carries `authored`: tasks whose authored status is `ready`, each with `file`, `status`, `title` and `workId`. Set `BoardOptions.fleetPort: null` to disable the item integration.

#### Find what waits on you

Expand Down
16 changes: 10 additions & 6 deletions packages/work-board/src/server/diagnostics/daemon.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { Clock, Effect, Layer, Predicate, Schema } from "effect";
import { Cause, Clock, Duration, Effect, Layer, Predicate, Schema } from "effect";
import { FetchHttpClient } from "effect/http";
import { RpcClient, RpcSerialization } from "effect/rpc";
import { RpcClientError } from "effect/rpc/RpcClientError";
Expand All @@ -10,20 +10,24 @@ function makeDaemonClient() {
type DaemonClient = Effect.Success<ReturnType<typeof makeDaemonClient>>;

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.
const FLEET_WAIT_SECONDS = 20;

// 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 } {
const stopped = error instanceof RpcClientError && error.reason._tag === "HttpError" && error.reason.kind === "TransportError";
return stopped
? { reason: FLEET_STOPPED, startCommand: `npx @shivaedev/work-fleet serve ${shellWord(folder)} --port ${port}` }
if (error instanceof RpcClientError && error.reason._tag === "HttpError" && error.reason.kind === "TransportError") {
return { reason: FLEET_STOPPED, startCommand: `npx @shivaedev/work-fleet serve ${shellWord(folder)} --port ${port}` };
}
return Cause.isTimeoutError(error)
? { reason: `Fleet on port ${port} didn't answer within ${FLEET_WAIT_SECONDS} seconds, so agent work and its health are unknown.` }
: { reason: `Fleet on port ${port} didn't answer as expected, so agent work and its health are unknown.` };
}

function shellWord(value: string) {
return /^[\w./@%+=:,-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
}

export function readDaemon<A, E>(port: number, read: (client: DaemonClient) => Effect.Effect<A, E>) {
export function readDaemon<A, E>(port: number, read: (client: DaemonClient) => Effect.Effect<A, E>, wait = Duration.seconds(FLEET_WAIT_SECONDS)) {
return Effect.scoped(
Effect.gen(function* () {
const client = yield* makeDaemonClient();
Expand All @@ -34,7 +38,7 @@ export function readDaemon<A, E>(port: number, read: (client: DaemonClient) => E
Layer.provide([FetchHttpClient.layer, RpcSerialization.layerNdjson]),
),
),
Effect.timeout("5 seconds"),
Effect.timeout(wait),
),
);
}
Expand Down
3 changes: 0 additions & 3 deletions packages/work-board/src/server/integration/board.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ import { type Changes, watchChanges } from "#server/files/changes.ts";
import { listMarkdown } from "#server/files/list.ts";
import { markdownPath } from "#server/files/markdownPath.ts";
import { areaDiagnostics } from "#server/metadata/areaDiagnostics.ts";
import { areaFolders, repositoryRoot } from "#server/metadata/areaFolders.ts";
import { metadataModel } from "#server/metadata/model.ts";
import { type Snapshot, searchSnapshot } from "#server/search/snapshot.ts";
import { watchIndex } from "#server/search/watchIndex.ts";
Expand All @@ -18,13 +17,11 @@ const snapshot: (
export const board = {
archiveSettled,
areaDiagnostics,
areaFolders,
listMarkdown,
loadSettled,
markdownPath,
metadataModel,
metadataParse,
repositoryRoot,
searchSnapshot: snapshot,
watchChanges,
watchIndex,
Expand Down
Loading
Loading