docs: mosaic on PATH can be the pinned copy wrapper (row 70, #1564)

Sage's row 70 round 2 candidate (agents/sage/work/queue-70/r2, manifest
098b9aef...604e), approved by Filbert in comment 28602. Landing gate on
4a34fb0d6 with rows 133 and 70 applied: all 24 suites passed, 0 failed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/TOOLS.md

@@ -171,10 +171,17 @@ leaves one registration record at `<dataRoot>/seats/<layout>/<seat>/registration
 that the control board reads: seat, project, task, workspace, tmux session,
 harness, start time, pid. Rewritten on every launch. `seat task` changes the
 task field only. The four repository seats (`agents/*/launch.sh`) register
-themselves through this path unless called with `--check`. Not the
-npm-global `mosaic` CLI; run by path. Exit codes: the launch script's own
-once it runs; before that 1 could not start, 2 invalid config or seat, 4
-usage. Details and the record's fields: `packages/seat/README.md`.
+themselves through this path unless called with `--check`. Run it by
+path from the checkout. On a pinned host, `mosaic` on PATH is a wrapper
+around a pinned copy's `scripts/mosaic`
+([Stack copies](#stack-copies-scriptsstack-copysh)) and carries the human
+commands; on Jason's host the estate CLI it replaced is `mosaic-old`.
+Queue commands stay on `scripts/mosaic queue` in the canonical checkout,
+because a copy refuses them ([One pinned
+copy](../packages/cli/README.md#one-pinned-copy-row-85-1579)). Exit
+codes: the launch script's own once it runs; before that 1 could not
+start, 2 invalid config or seat, 4 usage. Details and the record's
+fields: `packages/seat/README.md`.
 
 ## Work queue (`scripts/mosaic queue`)
 

packages/queue/tests/dispatch.test.mjs

@@ -102,10 +102,13 @@ test("`queue` reaches the queue CLI with the rest of the arguments", (t) => {
 test("the pre-A2 fixture is the script A2 changed", () => {
   const fixture = readFileSync(join(HERE, "fixtures", "mosaic-pre-a2.sh"), "utf8");
   const now = readFileSync(join(SCRIPTS, "mosaic"), "utf8");
-  // A2 adds lines and removes none.
-  const lines = now.split("\n");
+  // A2 adds lines and removes none. Lines that start with "# " are left out:
+  // later rows rewrite the header (row 70), and the pin is on what the script
+  // runs. The shebang and any other line stay in.
+  const code = (s) => s.split("\n").filter((l) => !l.startsWith("# "));
+  const lines = code(now);
   let i = 0;
-  for (const l of fixture.split("\n")) {
+  for (const l of code(fixture)) {
     while (i < lines.length && lines[i] !== l) i++;
     assert.ok(i < lines.length, `pre-A2 line missing: ${l}`);
     i++;

packages/seat/README.md

@@ -10,9 +10,15 @@ Issue #1504. Plain ESM, no dependencies, Node 24 or newer.
 
 ## Commands
 
-The repository wrapper is `scripts/mosaic`. It is not on PATH and is not
-the npm-global `mosaic` CLI from the estate tooling, which has no `launch`
-or `seat` command; run it by path.
+The repository wrapper is `scripts/mosaic`; run it by path from the
+checkout. A host may also put `mosaic` on PATH as a wrapper around a
+pinned copy's `scripts/mosaic` (`scripts/stack-copy.sh wrapper`, see
+[docs/TOOLS.md, Stack copies](../../docs/TOOLS.md#stack-copies-scriptsstack-copysh)). On
+Jason's host the estate CLI it replaced is `mosaic-old`, which has no
+`launch` or `seat` command. On a pinned host the human commands go
+through `mosaic` on PATH, and queue commands stay on `scripts/mosaic
+queue` in the canonical checkout, because a copy refuses them. Details:
+[packages/cli/README.md, One pinned copy](../cli/README.md#one-pinned-copy-row-85-1579).
 
 ```
 scripts/mosaic launch <seat|seat-dir> [--task TEXT] [--project NAME] [--workspace PATH]

scripts/mosaic

@@ -7,8 +7,14 @@
 # `mosaic inbox|decide|tasks|agents|trail|talk|stop|launches` and
 # `mosaic bus start|stop|status`: the human commands, managed sessions and
 # the bus host. See packages/cli/README.md.
-# Not the npm-global `mosaic` CLI from the estate tooling; this one is
-# repository-local and only reachable as scripts/mosaic.
+# This is the repository wrapper; run it by path from the checkout. A host
+# may also put `mosaic` on PATH as a wrapper that runs a pinned copy's
+# scripts/mosaic (scripts/stack-copy.sh wrapper, docs/TOOLS.md "Stack
+# copies"). On Jason's host the estate CLI it replaced is `mosaic-old`.
+# On a pinned host the human commands and --tester go through
+# that `mosaic`, and from a checkout they exit 3. Queue commands stay on
+# scripts/mosaic queue in the canonical checkout, because a copy refuses
+# them. See packages/cli/README.md "One pinned copy".
 set -euo pipefail
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # No argument: the full-screen app on a terminal (packages/cli/README.md).