stack/agents/darkwing/work/queue-a2/build.md

# Queue A2 (#1508), candidate for review

Darkwing, 2026-09-27. A2 is migration, render and dispatch (lead decision
20), plus every item Sage carried forward from A1's review (decision 26:
N5, N8, N10, N11, N12, P1, P2, P3). Base is HEAD c9539baa; A1 is 34a72af9.
Filbert reviews. Sage commits, then installs the hook and runs genesis.
Nothing is committed, staged or pushed.

## Files

`build.patch` (sha256 `dc0be7ce74aaaaaf43deebe68af439d1b2b80c77aad6538420e929de35e2f21f`) changes 13 files and adds 8.
`build-manifest.sha256` (sha256 `782bcb62e555659333a35888d418d986da63bdf522f38cafa447db7ddd0074b7`) pins all 21 after the patch.
In a fresh clone at c9539baa the patch applies and the result matches
the manifest 21/21, file modes included. `git apply` warns about one
blank line at the end of `fixtures/genesis-render.md`. It belongs there:
the render ends with one, and the golden has to match byte for byte.

- `packages/queue/src/`: `queue.mjs` (N8, N10, N11, P2), `store.mjs` (N12,
  N11's shared check, P1's helper, P3's caller), `lock.mjs` (P1, P3),
  `io.mjs` (N5), `cli.mjs` (usage comment).
- `scripts/mosaic`: `queue` execs `packages/queue/src/cli.mjs` with the
  remaining arguments. Every other call reaches the seat CLI as before.
- `scripts/test-queue.sh`: syntax checks for `scripts/mosaic` and the new
  fixture; `scripts/mosaic queue help` always; after genesis, `verify` and
  `render --check` on the live queue through `scripts/mosaic queue`.
- `packages/queue/README.md`: the dispatch, N5, N7, N8, N10, N12, P2, the
  map and `map-check.mjs`, two new test files.
- Tests: 107 in A1, 122 now. New: `dispatch.test.mjs` (3),
  `migration.test.mjs` (3), and 9 more in data, lock, store and write.
  Fixtures: `mosaic-pre-a2.sh` (the script before A2), `queue-marked.md`
  (QUEUE.md with the markers), `genesis-render.md` (the golden render).
- `agents/darkwing/work/queue-migration-map.md`: the genesis input.
- `agents/darkwing/work/queue-a2/map-check.mjs`: the drift check.
- `agents/darkwing/work/queue-a2/carry-forward.md`: the item list Sage
  confirmed (773dbd75), with the r1 section added after it.

Outside the patch, for Sage to apply (condition 2 keeps them out of A2):

- `queue-md.patch` (sha256 `2ca8f689e1dcda5bb30e9af4c3f867242d5239d72e13001369c7b7aca7956402`): the two markers, a header that points
  seats at `scripts/mosaic queue next`, and a line freezing the old log of
  table changes. It applies to HEAD.
- `tools-md.patch` (sha256 `c53aea1f6e871e17d04335ef60250adcdbe64f6466d9ff641042c00094d1c3a8`): a "Work queue" section in
  `docs/TOOLS.md`. It applies to HEAD. Optional; the README already has
  the detail.

## The five conditions

1. **Nothing ran against the canonical `.git`.** Tests use scratch
   repositories under the temp directory. The dry run below used
   `/tmp/qa2-dry`. Checked after all runs: no `mosaic-queue*` file in
   `.git/`, `.git/hooks/pre-commit` absent, `core.hooksPath` unset in every
   scope, nothing staged.
2. **No QUEUE.md, AGENTS.md or TOOLS.md edits.** The two proposals are
   patch files. `git status` shows none of the three modified.
3. **`scripts/test-queue.sh` is green at a HEAD with no `queue.json`:**
   24/24, the live checks skipped. After the dry-run genesis it ran 26/26, with `verify` and
   `render --check` on the live queue.
4. **H is recorded before the canary.** `queue-commit.sh` is unchanged
   from A1, and its test "F1: H is recorded before the canary, so HEAD
   moving during the canary makes update-ref fail" passes.
5. **The fault layer is reachable only from tests.** N5 narrows this
   further: tmpfs was the one fault-free path open to the CLI, and now
   only a layer with `allowTmpfs: true` gets it. The test asserts
   `realIo` has no such key and that `"yes"` doesn't count.

## Carried-forward items

| Item | Change | Test |
|---|---|---|
| N8 | `piece`, `gate`, `note`, move `reason`, brief anchor and `blockedReason` refuse `\` and `<`, at the CLI and in replay | "text the table shows refuses \ and <, everywhere it enters"; "every accepted text renders to nine cells on every row" (GFM's cell rule, no `marked` import) |
| N11 | Replay holds every log entry, round op and claim op to `CALLER_OP_RE` and refuses `.outcome`, genesis and `accept-history` included. `LOG_OP_RE` stays for Piece D's derived ids; no verb derives one yet | "replay holds every op id to the caller's rule" |
| N10 | `set issues` moves `closes` only if it equalled the old issues; a narrowed `closes` keeps its intersection, and the receipt says `(kept narrowed)` | "set issues keeps a logged narrowing of closes" |
| P2 | Each round records `issue`; `review` is `{rounds}` only. A later round keeps the last round's issue | "the row schema refuses a round with a null issue, and the A1 review shape", and A1's R2 tests updated |
| P1 | Both gate paths in `acquire` release through `releaseOrWarn`; a failed release is a message naming the lock, not a stack trace | "a release that fails on a gate path is reported, never a stack trace" |
| P3 | `lock.unlock` returns `{result, warning}`; nothing splits on newlines | "unlock keeps a multi-line lock record on stdout" |
| N5 | tmpfs left `FS_TYPES`; only `allowTmpfs === true` admits it | "tmpfs passes only a test layer that allows it" |
| N12 | `--by` still wins; a different non-empty `MOSAIC_AGENT_NAME` adds a stderr warning on success and on refusal. Nothing is logged | "--by that differs from MOSAIC_AGENT_NAME warns on stderr and logs nothing more" |

The rest, as `carry-forward.md` records and decision 26 confirmed: N7 is a
README line (the leftover `.git/mosaic-queue.lock.<pid>.<hex>.tmp` is
removed by hand). N15, N16, N13-a and ext2/ext3 are won't-do.

## Migration

The map (`queue-migration-map.md`) is built from QUEUE.md blob c8e3d34e,
which HEAD has. `node agents/darkwing/work/queue-a2/map-check.mjs` prints
`ok: QUEUE.md matches the map (blob c8e3d34e)`. Run it again just before
genesis. It exits 1 and lists the rows if QUEUE.md moved.

map-check did its job once already. HEAD moved from 8dba3ff7 to c9539baa
while I worked, and it reported row 5 (the CHAT-03 brief pinned, lead
decision 33). I rebuilt row 5's note, `queue-md.patch`, the marked fixture
and the golden render against the new blob. No other row changed.

The map's "Choices Sage should check" has eight items. None blocks review.
The ones that change what genesis writes: row 7 stays a live row (decision
27), row 10's owner stays `coordinator` with `queue assign 10 sage`
recommended as the first op, rows 12 and 13 have Sage as gate owner, row 16
stays `waiting-on-jason` unless #1510 is closed, and rows 9 to 12 close
nothing so row 13 closes #1508. Rows 9 to 13 have no `after`: decision 29
took the wait on row 6 off them, and `after: 9 done` on row 10 would wait
on a gate that needs row 10.

Dry run in a shared clone (`/tmp/qa2-dry`), the candidate plus
`queue-md.patch` and `tools-md.patch` committed on top of c9539baa. I
reran it from scratch after the rebase:

0. `map-check.mjs`: `ok: QUEUE.md matches the map (blob c8e3d34e)`.
1. `scripts/test-queue.sh`: 24/24, live checks skipped.
2. `scripts/queue-commit.sh --install-hook --by sage`: installed; canary
   passed.
3. `scripts/mosaic queue genesis --root /tmp/qa2-dry --branch a2-dry --map
   … --op genesis-2026-09-27 --by sage`: `ok genesis-2026-09-27 rev 0
   genesis 30 rows`.
4. `scripts/queue-commit.sh --genesis`: committed.
5. `verify --current`: briefs match HEAD. `render --check`: current.
   `legacyView` equals the marked body byte for byte, and `mapBlob` is the
   map's blob.
6. `next`: darkwing resumes 9, sage resumes 7, dewey resumes 5, filbert
   and rocko have nothing.
7. `scripts/test-queue.sh`: 26/26 with the live checks.
8. `queue assign 10 sage --op assign-10-dry --by sage`: `ok … rev 1 row 10 owner:
   coordinator→sage`.

The dry clone's hook is `.git/hooks/pre-commit`, mode 0755, blob
abdf14e7. `core.hooksPath` is unset there too.

## Choices I made

- **N8 refuses instead of escaping.** An escape has to be right for every
  Markdown renderer that reads QUEUE.md; a refusal doesn't. No line in
  today's table has either character.
- **P2 drops `review.issue`.** The last round's issue is the kept one, so
  a second copy could only disagree. Piece D reads `rounds[].issue`.
- **N10's edge.** A `closes` narrowed to nothing stays empty whatever the
  new issues are. `set closes` with a reason is the way to widen it again.
- **N12 warns on a refusal too,** so a seat that mistyped `--by` sees it on
  the error it was reading anyway.
- **`scripts/mosaic queue` uses `exec`,** so exit codes and signals are the
  queue CLI's own. Any first argument other than exactly `queue` goes to
  the seat CLI, as before; the dispatch test compares argv, cwd,
  environment and stdin against the pre-A2 script.

## Mutations

Each mutation ran alone in a shared clone of the candidate, with
`node --test packages/queue/tests/`. A killed mutation fails at least one
test.

46 mutations. Each one below failed at least one test; the number is
how many.

| Item | Mutations |
|---|---|
| N8 | backslash 2, lt 2, noteVerb 1, rowNote 2, anchor 1, reason 1 |
| N11 | entryShape 1, outcome 2, genesisOnly 1, roundOp 1, claimOp 1 |
| N10 | always 2, noIntersect 1, receipt 1 |
| P2 | keptFirst 1, noCheck 1, reviewIssue 10 |
| P1 | gateErr 1, gatePresent 1, gatePresentMsg 1, withLock 1 |
| P3 | joined 2, storeSplit 1 |
| N5 | inTypes 1, truthy 1, anyType 1 |
| N12 | noWarnOk 1, noWarnErr 1, envWins 1, emptyEnv 1 |
| Dispatch | noShift 1, unsetArg 1, prefix 1, noExec 1 |
| Golden render | mapGate 1, mapState 1 |
| map-check | fixed26 1, owner 1, issues 1, lineDiff 1, parkedPiece 1 |

Five of them survived the first pass. Each now has a test that kills it:

- N11 roundOp and claimOp (replay stops checking a review round's op or a
  claim's op). The N11 test now builds a claimed row and a reviewed row and
  refuses an op of 73 characters and one ending `.outcome` in each.
- P1 withLock (the post-op release goes back to the throwing `release`).
  New write test: the lock's unlink fails with EACCES after the op, and the
  receipt and a refusal both carry "cannot release the queue lock (EACCES)".
- N12 emptyEnv (an empty `MOSAIC_AGENT_NAME` warns). The N12 test now runs
  with it empty and expects no stderr.
- Dispatch noExec (`node` without `exec`, so a successful queue call falls
  through to the seat CLI). The dispatch test now runs a queue call that
  exits 0 and checks that only the queue CLI ran.

The map and golden-render mutations ran again after the rebase and were
still killed.

## Suites

All nine green at the final candidate: config 24, task 90, foundation
44, conductor 17, release 14, auth 15, discord 64, extension-package 18,
queue 24 (no `queue.json` at HEAD). `node --test packages/queue/tests/`:
122/122.

## After approval (Sage)

1. Check the canonical tree against `build-manifest.sha256`, then commit
   the 21 files by path.
2. Apply `queue-md.patch` (and `tools-md.patch` if wanted) and commit.
3. `node agents/darkwing/work/queue-a2/map-check.mjs` must print `ok`.
4. `scripts/queue-commit.sh --install-hook --by sage`.
5. `scripts/mosaic queue genesis --root /mnt/storage/src/mosaic-stack
   --branch refactor --map agents/darkwing/work/queue-migration-map.md
   --op <id> --by sage`.
6. `scripts/queue-commit.sh --genesis -m MSG`.
7. `scripts/test-queue.sh` runs the live checks from here on.