stack/agents/dewey/work/queue-89/build.md

# Row 89 (#1583): PM task reads that fit a session, round 1

Owner: Dewey. Reviewer: Darkwing, then Sage's gate. Brief:
`docs/plans/2026-10-12_pm-task-flow.md`, section "PM task reads that fit a
session" (blob `e8a1150e`, commit `4d095b77`).

Base `a3f6e9e6` (queue rev 744). `build.patch` is
`git diff --cached --binary a3f6e9e6 --` the twelve paths in
`candidate-manifest.sha256`. Apply it with `git apply --index` to a detached
worktree of the base; the manifest then checks 12/12 OK. No commit from the
base to `refactor` HEAD `70b7b8d5` touches the twelve paths.

| File | What changed |
|---|---|
| `packages/bus/src/broker.mjs` | `tasks` takes optional arguments; `#tasks` filters and pages the short form |
| `packages/bus/tests/task-page.test.mjs` | new: six tests on a 500-task board |
| `packages/bus/README.md` | the `tasks` row and a paragraph on its arguments |
| `packages/harness/src/tools.mjs` | `list_tasks` arguments, `get_task`, the `done: false` default, `REPLY_CAP`, `replyText` |
| `packages/harness/src/mcp-server.mjs` | replies through `replyText` |
| `packages/harness/src/pi-extension.mjs` | replies through `replyText` |
| `packages/harness/src/bundle.mjs` | the built-in tools line names the harness's own tools |
| `packages/harness/tests/tools.test.mjs` | the schemas, the default, `replyText`'s boundary |
| `packages/harness/tests/mcp-server.test.mjs` | compact JSON, the default sent, the cap from the MCP server |
| `packages/harness/tests/pi-session.test.mjs` | compact JSON, the cap, `list_tasks` and `get_task` from a real pi session |
| `packages/harness/tests/bundle.test.mjs` | the tools line for each harness, and "none" |
| `packages/harness/README.md` | the tools line, compact replies, the cap, the two task tools, a limit |

## The threshold, and the cap

The bus unit runs `MOSAIC_CLAUDE_BIN=~/.local/bin/claude` (decision 91),
which is version 2.1.296 today. I found the threshold in that binary and then
confirmed it with a probe.

- **The binary.** The MCP tool's `maxResultSizeChars` is `1e5`. The function
  that picks the persist threshold takes the minimum of that and
  `pH=50000`. A GrowthBook flag, `tengu_velvet_ibis`, can override it per
  tool. `cachedGrowthBookFeatures` is `{}` in both Claude config files on
  this host, so no override applies. A result is saved to a file when the
  total `.length` of its text blocks is over the threshold. The same
  variable list holds `tjn=200000`, a budget per message across all tool
  results. `MAX_MCP_OUTPUT_TOKENS` (25000 tokens by default) comes later
  than 50000 characters for this kind of text.
- **The probe** (`probe/`). `probe-server.mjs` is a stdio MCP server whose
  one tool returns a text block of exactly `n` characters. A headless
  `claude -p` run of 2.1.296 (haiku, cost $0.0145) called it with 49990,
  50000 and 50010 (`probe/results.txt`):
  - 49990 and 50000 came back inline, at full length.
  - 50010 came back as "Error: result (50,010 characters across 1 line)
    exceeds maximum allowed tokens. Output has been saved to" a file under
    `~/.claude/projects/`, outside the workspace. That is the PM's fault.

So the threshold is "over 50000 characters", counted as JavaScript counts
(UTF-16 units). **`REPLY_CAP` is 40000**, 20% under it. `replyText`
measures with `.length` too, so a reply of astral characters is counted the
way the CLI counts it (the tools test has a surrogate-pair case at 40002).

Over the cap, the tool throws "reply too large: N characters, over the
40000-character cap. Narrow the query: a filter, a smaller limit, or
get_task for one task." Both servers report a throw as a tool error
(`isError` on MCP, a thrown error on pi). A reply is never cut short.
Replies are compact JSON in both servers; that is the cap's input.

### Sizes on the test board

500 tasks, titles about 55 characters, descriptions over 2000:

| Read | Compact | Indented |
|---|---|---|
| `list_tasks` default (open, 50) | 11,210 | 16,618 |
| `limit: 200` | 44,698, refused by the cap | 66,303 |
| no arguments, the whole board | 1,518,073 | |
| `get_task`, one full row | 3,028 (task 2; 3,055 at most, 365 for a tombstone) | |

The default page is about a quarter of the cap. `limit: 200` with these
titles is over it, so the session gets the cap error and narrows. That's
the cap doing its job, and the reason the default is 50.

## Decisions

1. **The no-argument read is unchanged.** `tasks` with `{}` returns
   `#taskRows` as before, so the Console and `mosaic tasks` read what they
   did. A test compares it with `taskView` for the pm, a human and a
   reader.
2. **The tool always filters.** `ARG_DEFAULTS = { list_tasks: { done: false } }`
   is merged in `callTool`, under the session's own arguments. A session
   can't reach the whole board through `list_tasks`, even with no
   arguments; `done: true` overrides the default.
3. **`task_ref` stands alone.** With any other argument it refuses
   `invalid-request`. A ref not on the board refuses `task-not-found`, a
   code the broker already has. The row is today's full row, tombstones
   included.
4. **Tombstones are left out of filtered reads.** A tombstone has no
   title or state to show, and isn't on the board. `get_task` still
   returns one by ref.
5. **Assignees are roles.** The short form lists the roles whose
   `roles[*].tracker.botId` is among the task's assignees, sorted. A
   person or another bot isn't a role and doesn't appear. A role whose
   `tracker` is null holds no task, so `assignee` for it matches nothing.
   An `assignee` that isn't a role of the business refuses (`toString`
   included; the check is `Object.hasOwn`).
6. **`changed_at` is the row's `at`**, the time the broker last recorded a
   change, as the Console's board shows it.
7. **Paging is in `task_ref` order as text**, the order `#taskRows`
   already gives (`ORDER BY task_ref`), and `after` compares with `>` on
   the same strings. `after` needn't be on the board or match the
   filters; the page starts past it. `total` counts every match, not the
   page. `next` is the last ref of the page, null when the page ends on
   the last match.
8. **The page sizes live in two files.** `TASK_PAGE` and `TASK_PAGE_MAX`
   are exported from `broker.mjs` and repeated in `tools.mjs`, so the
   session's tool server doesn't load the broker. A tools test holds the
   schema maximum equal to the broker's.
9. **The tools line is built in `prompt()`.** For pi it prints the role's
   tools as before; for Claude Code, `claudeBuiltins({ tools })`, the
   names the gate gives Claude Code. Its call site is unchanged. With no
   tools, it says "none" for both.

## Limits

- **The cap is per reply.** The CLI's 200000-character budget is per
  message: six or more replies near the cap in one turn could still be
  saved to a file. Five at the cap total exactly 200000, which isn't over.
- **A full row over 40000 characters can't be read** through `get_task`.
  The session gets the cap error. The test board's longest full row is
  3,055; I haven't measured the live board's.
- **The threshold belongs to 2.1.296.** `~/.local/bin/claude` updates
  itself, so a later version can move it. The harness README says so.
  The probe here rechecks a new version in one run.
- **`limit: 200` can exceed the cap** on a real board with long titles,
  as it does on the test board. The error tells the session to narrow.

## Gate (my run on the candidate)

Sequential, in a worktree of `a3f6e9e6` holding the candidate, `TMPDIR` in
my scratch, `test-task.sh` with `DOCKER_HOST=unix:///nonexistent`
(`gate.sh`, `gate-summary.txt`). The brief's four node suites, plus tasks
and control-board, then every `scripts/test-*.sh`.
2026-10-12T20:13:35Z to 20:18:12Z, all rc=0:

| Suite | Result |
|---|---|
| bus | 108 pass (the six in `task-page.test.mjs` among them) |
| harness | 65 pass |
| webui | 84 pass |
| cli | 115 pass |
| tasks | 74 pass |
| control-board | 124 pass |
| test-auth | 15 passed |
| test-conductor | 17 passed |
| test-config | 24 passed |
| test-discord | 66 passed |
| test-extension-package | 18 passed |
| test-foundation | 44 passed |
| test-queue | 27 passed |
| test-release | 14 passed |
| test-task | 26 passed; four Docker groups skip (adapter seam, workspace/capability, live task, live recall pair) |

After the mutants I added one assertion to `packages/harness/tests/tools.test.mjs`
(below), so the manifest's hash for that file is newer than this run. No other
suite loads that file. The harness suite on the final candidate, 20:43:56Z to
20:44:07Z: 65 pass, rc=0 (the last line of `gate-summary.txt`).

## Mutants

`mutants.py` swaps one exact string in a second worktree of the base that holds
the candidate. It runs the bus or harness node suite, restores the file and
reports killed or SURVIVED; an anchor matching anything but once is reported
and skipped (none was). 34 mutants, 34 killed in the end. The copy checked
12/12 against the manifest afterwards.

- **Run 1** (`mutants-run1.txt`, from 20:18:19Z). The first 16 were killed.
  The 17th, `after ignored`, makes `pages()` in `task-page.test.mjs` follow
  `next` forever. It hung until the harness's 900 s timeout, and the test
  child it left behind ran on until I stopped it by PID at 20:35Z. My
  harness's fault: it killed only the runner, not the runner's children.
  `mutants.py` now starts each run in its own process group, kills the group
  after 300 s, and reports a hang as a kill.
- **Run 2** (`mutants-run2.txt`, 20:35:08Z to 20:43:08Z), the 18 from
  `after ignored` on. 17 killed, `after ignored` among them as a hang. One
  survived: `cap counts bytes` (`Buffer.byteLength` for `.length`). The
  surrogate-pair case at 40002 units is over the cap either way, so it can't
  tell units from bytes. I added a case that fits by units and not by bytes:
  19999 emoji, 40000 units and 80002 bytes, fits.
- **Run 3** (`mutants-run3.txt`, 20:43:36Z to 20:43:47Z): `cap counts bytes`
  killed.

| Mutant | Site | What it undoes |
|---|---|---|
| no args filtered too | broker | the no-argument read returns the whole projection |
| tombstones kept | broker | filtered reads leave tombstones out |
| next on an exact last page | broker | `next` is null when the page ends on the last match |
| default limit ignored | broker | the page is 50 by default |
| limit max unchecked | broker | `limit` over 200 refuses |
| assignee by raw id | broker | assignees are role names |
| assignees keep persons | broker | a person's assignment shows as no role |
| task_ref with other args | broker | `task_ref` stands alone |
| missing task_ref is null | broker | a ref not on the board refuses `task-not-found` |
| done check dropped | broker | `done` must be a boolean |
| done filter dropped | broker | `done` filters |
| assignee any string | broker | `assignee` must be a role of the business |
| label check dropped | broker | `label` must be a positive integer |
| label filter dropped | broker | `label` filters |
| requirement pattern dropped | broker | `requirement` must match the id pattern |
| requirement filter dropped | broker | `requirement` filters |
| after ignored | broker | `after` starts the page (killed by hanging) |
| after inclusive | broker | the page starts past `after`, not at it |
| total counts the page | broker | `total` counts every match |
| description kept | broker | the short form has no description |
| tasks keys closed | broker | `tasks` takes its arguments at all |
| ARG_DEFAULTS removed | tools | `list_tasks` sends `done: false` |
| default overrides the caller | tools | the session's `done` wins over the default |
| cap at >= | tools | a reply of exactly 40000 fits |
| cap counts bytes | tools | the cap counts UTF-16 units, as the CLI does |
| indented JSON | tools | replies are compact |
| cap 50000 | tools | the cap is 40000 |
| mcp server uncapped | mcp-server | the MCP server applies the cap |
| pi uncapped | pi-extension | the pi extension applies the cap |
| tool limit max 500 | tools | the schema's `limit` maximum equals the broker's |
| get_task not required | tools | `get_task` requires `task_ref` |
| get_task without tracker | tools | `get_task` is for tracker holders only |
| bundle line pi names | bundle | Claude Code's line names its own tools |
| bundle none dropped | bundle | no tools says "none" |