docs(l0): declaration grammar moves to .mosaic/repo.json (#1216)

Amendment per operator GO (ms-grill-me design round, 2026-08-20):

- Declaration is .mosaic/repo.json under integration_trunk, not a
  byte-exact AGENTS.md line. Unknown/misspelled keys and unparsable
  files are a structural hard stop; no prose grammar to near-miss
  (Q15 answer, plan D3/D9).
- Changing an existing declaration is operator-owned, above ordinary
  PR review (SF2, plan D10).
- Seeds this repo's declaration: integration_trunk next,
  release_branch main — prevents the absent-declaration default from
  rebinding the stack to main at land time.
- Gloss references in BOOTSTRAP/CODE-REVIEW/CI-CD-PIPELINES point at
  repo.json; merge of origin/next restores pinned-image CI coverage
  for this pre-pin branch (D27 caveat).

.mosaic/repo.json

@@ -0,0 +1,4 @@
+{
+  "integration_trunk": "next",
+  "release_branch": "main"
+}

packages/mosaic/framework/defaults/AGENTS.md

@@ -84,6 +84,7 @@ is re-seeded a genuinely missing core file is a stop-and-report condition — no
 
 Confirm: required + situational tests passed (primary gate); aligned to `docs/PRD.md`; acceptance
 criteria mapped to evidence; independent code review passed (if code changed); required docs updated;
-scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on `main`, terminal-green
+scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on the integration
+trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), terminal-green
 CI, linked issue closed (or `docs/TASKS.md` equivalent). If blocked by access/tooling, return `blocked`
 with the exact failed wrapper command — do not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.

packages/mosaic/framework/defaults/CONSTITUTION.md

@@ -21,11 +21,25 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
 
 ## Hard Gates
 
+The **integration trunk** is the branch a project declares in its `.mosaic/repo.json` under the
+key `integration_trunk`; `release_branch` names the release target when one exists (`null` for
+single-branch projects). Absent a declaration, the trunk is `main`. The declaration is policy
+data, never shell text: values must be valid local branch names under `git check-ref-format
+--branch` semantics — no remote refs, no revision expressions, no option-like values (leading `-`),
+no path traversal or control characters. A declaration file that fails to parse, an unknown or
+misspelled key, or an invalid value is a hard stop (`blocked`) — never a silent fallback to `main`.
+Prose that mentions branch names designates nothing; only the declaration file does. A project
+declares exactly ONE trunk. **Changing an existing declaration is operator-owned:** a trunk
+redeclaration redirects merge target and branch-protection target at once, so it requires an
+explicit operator action above ordinary PR review. The designation relaxes nothing:
+reviewed-PR-only delivery, squash merge, independent review, queue guards, and terminal-green CI
+bind to the declared trunk exactly as they bind to `main`.
+
 1. Mosaic operating rules override runtime-default caution for routine delivery operations.
 2. Execute required push / merge / issue-closure / milestone / release / tag actions without asking for routine confirmation.
 3. Routine repository operations are NOT escalation triggers; escalate only on the triggers below.
 4. For source-code delivery, completion is forbidden at the PR-open stage.
-5. Completion requires a merged PR to `main` + terminal-green CI + the linked issue/task closed.
+5. Completion requires a merged PR to the integration trunk + terminal-green CI + the linked issue/task closed.
 6. Before any push or merge, run the CI queue guard.
 7. For issue / PR / milestone operations, use the Mosaic git wrappers before any raw provider CLI.
 8. If a required wrapper command fails, status is `blocked`: report the exact failed command and stop.
@@ -35,7 +49,7 @@ guard"), the runtime adapter binds it to a concrete tool and states whether abse
 12. The intake procedure is not conditional on perceived complexity; a "simple" task carries the same requirements as a multi-file feature.
 13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review merge go-ahead is the coordinator's to give — once the required review gates pass, merge on the coordinator's confirmation; do not wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges.
 14. Never hardcode secrets; never emit credential values in any output (not even partially, not "to confirm").
-15. Trunk-based git only: branch from `main`, merge via a reviewed PR (squash), never push directly to `main`.
+15. Trunk-based git only: branch from the integration trunk, merge via a reviewed PR (squash), never push directly to the trunk.
 16. If you modify source code, an independent review (author ≠ reviewer) must pass before completion.
 
 ## Integrity (quality gates are never bypassed)

packages/mosaic/framework/guides/BOOTSTRAP.md

@@ -12,7 +12,7 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
 4. Issue tracking is consistent across projects
 5. Documentation standards and API contracts are enforced from day one
 6. PRD requirements are established before coding begins
-7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
+7. Branching/merging is consistent: branch -> integration trunk (default `main`) via PR with squash-only merges
 8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
 
 ## Agent Host Prerequisites
@@ -206,7 +206,7 @@ Every runtime context file should contain:
 6. **Issue tracking** — Issue and commit conventions
 7. **Code review** — Required review process
 8. **Runtime notes** — Runtime-specific behavior references
-9. **Branch and merge policy** — Trunk workflow (`branch -> main` via PR, squash-only)
+9. **Branch and merge policy** — Trunk workflow (branch -> integration trunk via PR, squash-only)
 10. **Autonomy and escalation policy** — Agent owns coding/review/PR/release/deploy lifecycle
 
 ---
@@ -288,15 +288,17 @@ Reserve `0.1.0` for the MVP release milestone.
 
 ---
 
-## Step 5b: Configure Main Branch Protection (Hard Rule)
+## Step 5b: Configure Trunk Branch Protection (Hard Rule)
 
-Apply equivalent settings in Gitea, GitHub, or GitLab:
+Apply equivalent settings in Gitea, GitHub, or GitLab, targeting the project's integration trunk
+(the branch its `.mosaic/repo.json` declares under `integration_trunk`; default `main` — see
+`CONSTITUTION.md` Hard Gates):
 
-1. Protect `main` from direct pushes.
-2. Require pull requests to merge into `main`.
+1. Protect the integration trunk from direct pushes.
+2. Require pull requests to merge into the integration trunk.
 3. Require required CI/status checks to pass before merge.
 4. Require code review approval before merge.
-5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
+5. Allow **squash merge only** for PRs into the integration trunk (disable merge commits and rebase merges for it).
 
 This enforces one merge strategy across human and agent workflows.
 
@@ -513,9 +515,9 @@ After bootstrapping, verify:
 - [ ] Git labels created (epic, feature, bug, task, etc.)
 - [ ] Initial pre-MVP milestone created (0.0.1)
 - [ ] MVP milestone reserved for release (0.1.0)
-- [ ] `main` is protected from direct pushes
-- [ ] PRs into `main` are required
-- [ ] Merge method for `main` is squash-only
+- [ ] The integration trunk is protected from direct pushes
+- [ ] PRs into the integration trunk are required
+- [ ] Merge method for the integration trunk is squash-only
 - [ ] Quality gates run successfully
 - [ ] `.env.example` exists (if project uses env vars)
 - [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)

packages/mosaic/framework/guides/CI-CD-PIPELINES.md

@@ -4,6 +4,11 @@
 
 ## Overview
 
+> **Integration trunk:** the YAML examples in this guide use the default integration trunk `main`
+> in branch conditions and version rules. A project that declares a different trunk in its
+> `.mosaic/repo.json` under `integration_trunk` (see `CONSTITUTION.md` Hard Gates) substitutes its
+> declared trunk wherever `main` appears as the trunk branch.
+
 This guide covers the canonical CI/CD pattern used across projects. The pipeline runs in Woodpecker CI and follows this flow:
 
 ```
@@ -865,7 +870,7 @@ steps:
    ```yaml
    image: git.example.com/org/service@${IMAGE_DIGEST}
    ```
-7. **Test on a short-lived non-main branch first** — open a PR and verify quality gates before merging to `main`
+7. **Test on a short-lived non-trunk branch first** — open a PR and verify quality gates before merging to the integration trunk
 8. **Verify images appear** in Gitea Packages tab after successful pipeline
 
 ## Terminal-Green Full-Step Contract
@@ -906,7 +911,7 @@ For source-code delivery, completion is not allowed at "PR opened" stage.
 
 Required sequence:
 
-1. Merge PR to `main` (squash) via Mosaic wrapper.
+1. Merge PR to the integration trunk (squash) via Mosaic wrapper.
 2. Monitor CI to terminal status:
    ```bash
    ~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>
@@ -1112,5 +1117,5 @@ If a project currently uses Verdaccio (e.g., U-Connect at `npm.uscllc.net`), fol
 
 ### Pipeline runs Docker builds on pull requests
 
-- Verify `when` clause on Docker build steps restricts to `branch: [main]`
+- Verify `when` clause on Docker build steps restricts to the integration trunk (`branch: [main]` by default)
 - Pull requests should only run quality gates, not build/push images

packages/mosaic/framework/guides/CODE-REVIEW.md

@@ -10,9 +10,10 @@ If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD upd
 
 Merge strategy enforcement (HARD RULE):
 
-- PR target for delivery is `main`.
-- Direct pushes to `main` are prohibited.
-- Merge to `main` MUST be squash-only.
+- The integration trunk is the branch the project's `.mosaic/repo.json` declares under `integration_trunk` (default: `main`) — see `CONSTITUTION.md` Hard Gates.
+- PR target for delivery is the integration trunk.
+- Direct pushes to the integration trunk are prohibited.
+- Merge to the integration trunk MUST be squash-only.
 - Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).
 
 An estate MAY carry a documented exception for a repository whose gates are commit hooks rather
@@ -65,6 +66,19 @@ Each of these produced a wrong conclusion before it was written down.
     conclusion drawn from it describes the wrong tree. Confirm `git rev-parse --show-toplevel`
     is the tree you think it is before trusting any git output.
 
+13. **Run the repository's PINNED tool version.** `npx <tool>` resolves a local `node_modules`
+    install when one is present and fetches the latest release when one is not, so the same
+    command answers differently depending on where it ran. A reviewer measuring in a fresh clone
+    or a detached worktree — which is exactly where reviewers measure — has no `node_modules` and
+    silently gets the latest release instead of the pinned one. Measured on mosaicstack#1313: the
+    lockfile pins prettier 3.8.1, under which three guides pass; a version-less `npx` in a
+    worktree resolved 3.9.6, under which the same three fail; and 3.0.0, the floor of the declared
+    `^3.0.0` range, fails a different one. Three versions, three verdicts, identical bytes. Use
+    `node_modules/.bin/<tool>`, or name the version the lockfile pins.
+14. **A formatter or linter declared as a range is a dated verdict, not a fact.** If a lockfile
+    pins it, the gate is reproducible today and will disagree with itself the day the pin moves.
+    Report a formatting failure with the version that produced it, always.
+
 ### Feedback Categories
 
 - **Blocker**: must fix before merge (security, bugs, test failures)
@@ -184,8 +198,8 @@ Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` whenever code/A
 # List the issue being addressed
 ~/.config/mosaic/tools/git/issue-list.sh -i {issue-number}
 
-# View the changes
-git diff main...HEAD
+# View the changes (diff against the integration trunk; default: main)
+git diff {integration_trunk}...HEAD
 ```
 
 ### Providing Feedback
@@ -214,4 +228,4 @@ This pattern appears in 3 places. A shared helper would reduce duplication.
 2. If changes requested, assign back to author
 3. If approved, note approval in issue comments
 4. For merges, ensure CI passes first
-5. Merge PR to `main` with squash strategy only
+5. Merge PR to the integration trunk with squash strategy only

packages/mosaic/framework/guides/E2E-DELIVERY.md

@@ -78,7 +78,7 @@ For implementation work, you MUST run this cycle in order:
 7. `commit` - commit only when the logical unit passes tests and review.
 8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. `push` - push immediately after queue guard passes.
-10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
+10. `PR integration` - if external git provider is available, create/update PR to the integration trunk (the project's declared trunk, default `main`) and merge with required strategy via Mosaic wrappers.
 11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines on the exact PR head to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/tools/git/pr-ci-wait.sh` for PR-based workflow).
 13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
@@ -199,7 +199,7 @@ Before running this checklist, pause and self-interrogate: did I fulfill the use
 10. No unresolved blocker hidden.
 11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
 12. `docs/TASKS.md` status and issue/internal references are updated to match delivered work.
-13. If source code changed and external provider is available: PR merged to `main` (squash), with merge evidence recorded.
+13. If source code changed and external provider is available: PR merged to the integration trunk (squash), with merge evidence recorded.
 14. CI/pipeline status is terminal green for the merged PR/head commit.
 15. Linked external issue is closed (or internal task ref is closed when no provider exists).
 16. If any of items 13-15 fail due access/tooling, report `blocked` with exact failed wrapper command and do not claim completion.

packages/mosaic/framework/guides/FLEET-COMMS.md

@@ -53,23 +53,21 @@ sends, it does not auto-reply.
 
 ### Exit codes
 
-| rc  | Meaning                                                                                      |
-| --- | -------------------------------------------------------------------------------------------- |
-| 0   | delivered or queued                                                                          |
-| 1   | target session not found                                                                     |
-| 2   | submission unconfirmed: draft still on the input line, or no positive evidence of submission |
-| 3   | usage error (bad class, missing `-s`)                                                        |
+| rc  | Meaning                                        |
+| --- | ---------------------------------------------- |
+| 0   | delivered or queued                            |
+| 1   | target session not found                       |
+| 2   | text reached the pane but is **still a draft** |
+| 3   | usage error (bad class, missing `-s`)          |
 
-**Never retry on rc=2.** The message may be in the target pane, and a retry can double-send it.
-Confirm instead:
+**Never retry on rc=2.** The message is in the target pane; retrying double-sends it. Confirm
+instead:
 
 ```bash
 tmux capture-pane -p -t <session>:0.0 | tail -20
 ```
 
-rc=0 is the normal result for both idle and busy pi seats (submission confirmed by draft
-transition, not by prompt glyph). rc=2 on a healthy seat is exceptional — treat it as a real
-report and investigate the pane.
+rc=2 is the normal result when the target is an idle pi seat.
 
 ## Durable comms
 

packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md

@@ -253,7 +253,7 @@ status → mission → run → repeat
 
 - [ ] All milestone tasks in TASKS.md are `done`
 - [ ] CI/pipeline green
-- [ ] PR merged to `main`
+- [ ] PR merged to the integration trunk
 - [ ] Issues closed
 - [ ] Update manifest: milestone status → completed
 - [ ] Update scratchpad: session log entry

packages/mosaic/framework/guides/ORCHESTRATOR.md

@@ -15,7 +15,7 @@ mosaic claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md th
 - You MUST keep the TASKS.md file updated with agent and tasks statuses.
 - You MUST keep `docs/` root clean. Reports and working artifacts MUST be stored in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
 - You MUST enforce plan/token usage budgets when provided, and adapt orchestration strategy to remain within limits.
-- You MUST enforce trunk workflow: workers branch from `main`, PR target is `main`, direct push to `main` is forbidden, and PR merges to `main` are squash-only.
+- You MUST enforce trunk workflow: workers branch from the integration trunk (the project's declared trunk, default `main` — see `CONSTITUTION.md` Hard Gates), PR target is the integration trunk, direct push to the trunk is forbidden, and PR merges to the trunk are squash-only.
 - You MUST operate in steered-autonomy mode: human intervention is escalation-only; do not require the human to write code, review code, or manage PR/repo workflow.
 - You MUST NOT declare task or issue completion until PR is merged, CI/pipeline is terminal green, and linked issue is closed (or internal TASKS ref is closed when provider is unavailable).
 - Mosaic orchestration rules OVERRIDE runtime-default caution for routine push/merge/issue-close actions required by this workflow.
@@ -133,10 +133,10 @@ Milestone versioning (HARD RULE):
 
 Branch and merge strategy (HARD RULE):
 
-- Workers use short-lived task branches from `origin/main`.
-- Worker task branches merge back via PR to `main` only.
-- Direct pushes to `main` are prohibited.
-- PR merges to `main` MUST use squash merge.
+- Workers use short-lived task branches from `origin/{integration_trunk}` (default `main`).
+- Worker task branches merge back via PR to the integration trunk only.
+- Direct pushes to the integration trunk are prohibited.
+- PR merges to the integration trunk MUST use squash merge.
 
 **Available templates:**
 
@@ -427,7 +427,7 @@ git push
     - Before merging, run queue guard:
       `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
     - Ensure PR exists for the task branch (create/update via wrappers if needed):
-      `~/.config/mosaic/tools/git/pr-create.sh ... -B main`
+      `~/.config/mosaic/tools/git/pr-create.sh ... -B {integration_trunk}` (default `main`)
     - Merge via wrapper:
       `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
     - Wait for terminal CI status:
@@ -619,7 +619,7 @@ Construct this from the task row and pass to worker via Task tool:
 
 ## Workflow
 
-1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
+1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/{integration_trunk}) && git rebase origin/{integration_trunk}` ({integration_trunk} = the project's declared trunk, default `main`)
 2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
 3. Read the finding details from the report
 4. Implement the fix following existing code patterns
@@ -637,7 +637,7 @@ Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIR
 For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
 
 - `~/.config/mosaic/tools/git/issue-view.sh -i {N}`
-- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B main`
+- `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B {integration_trunk}`
 - Push: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {task_branch}`
 - Merge: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B {pr_head_branch} -R {pr_head_owner/repo} --sha {pr_head_full_sha}`
 - `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
@@ -994,13 +994,13 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
 
 ---
 
-## Merge-to-Main Candidate Protocol (Container Deployments)
+## Merge-to-Trunk Candidate Protocol (Container Deployments)
 
-If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:
+If deployment is in scope and container images are used, every merge to the integration trunk MUST execute this protocol:
 
 1. Build and push immutable candidate image tags:
    - `sha-<shortsha>` (always)
-   - `v{base-version}-rc.{build}` (for `main` merges)
+   - `v{base-version}-rc.{build}` (for integration-trunk merges)
    - `testing` mutable pointer to the same digest
 2. Resolve and record the image digest for each service.
 3. Deploy by digest to testing environment (never deploy by mutable tag alone).

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -30,7 +30,6 @@ packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh | unmeasured i
 # --- tools/tmux: require a live tmux server ---
 packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a real tmux server on a throwaway socket; CI image ships no tmux; #1017 burndown (needs tmux in image or a signed permanent exclusion)
 packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)
-packages/mosaic/framework/tools/tmux/test-send-message-glyph-agnostic.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its siblings) — signed at adoption of #1262 (rev-code-02 F5), red-first verified on sb-it-1-dt
 
 # --- single-suite directories: unmeasured in CI ---
 

packages/mosaic/framework/tools/tmux/send-message.sh

@@ -97,34 +97,13 @@ printf '%s' "$MSG" | "${tmux_cmd[@]}" load-buffer -b "$BUF" -
 #   would otherwise accumulate forever.
 sleep 0.5
 
-# 2) Submit, then POSITIVELY confirm submission by DRAFT TRANSITION, not by prompt
-#    glyph. The historical bug was treating ABSENCE of a draft as delivery; the
-#    2026-08 fix over-corrected to glyph inference (grep '❯|^>|│ >'), which locates
-#    only Claude Code's box and false-NEGATIVES every glyphless REPL (pi renders a
-#    U+2500 rule, no glyph) — a delivered message reported "UNDELIVERED", driving a
-#    retry that duplicates it. Runtime-agnostic evidence: our message tail sits on
-#    the INPUT line (located by the cursor row, not a glyph) BEFORE Enter, and has
-#    LEFT it AFTER — that transition is positive proof of submission and needs no
-#    glyph. Absence alone still never means delivered: if we never saw our draft on
-#    the input line we stay UNCONFIRMED (wrong/dead pane), and a draft that never
-#    leaves the input line stays a DRAFT (exit 2), preserving both historical guards.
-_cursor_line() { # echo the pane's current input (cursor) line, glyph-free
-  local cy line
-  cy=$("${tmux_cmd[@]}" display-message -p -t "$EFFECTIVE_TARGET" -F '#{cursor_y}' 2>/dev/null) || return 1
-  [ -n "$cy" ] || return 1
-  "${tmux_cmd[@]}" capture-pane -t "$EFFECTIVE_TARGET" -p 2>/dev/null | sed -n "$((cy + 1))p"
-}
-_draft_on_input() { # true iff our message tail is sitting on the input line now
-  [ -n "$snippet" ] || return 1
-  grep -qF "$snippet" <<<"$(_cursor_line)"
-}
-
-# Baseline: after the paste, our draft must be on the input line. This is positive
-# proof we are on the right pane and the paste landed — the anchor the transition
-# check measures against.
-saw_draft=0
-_draft_on_input && saw_draft=1
-
+# 2) Submit, then POSITIVELY confirm submission; flush with another Enter if it is
+#    still a draft. Success requires positive evidence — the queued banner, OR the
+#    REPL input box located AND clear of our message tail. The historical bug was
+#    treating ABSENCE of a draft as delivery: if the prompt glyph was never matched
+#    (wrong pane / prompt-glyph drift), an unsubmitted message read as "delivered"
+#    and worker->lead relays stalled silently. We now default to UNCONFIRMED and only
+#    upgrade to delivered on positive evidence; anything we cannot confirm fails loud.
 status="unconfirmed"
 for attempt in $(seq 1 $((RETRIES + 1))); do
   "${tmux_cmd[@]}" send-keys -t "$EFFECTIVE_TARGET" Enter
@@ -134,26 +113,20 @@ for attempt in $(seq 1 $((RETRIES + 1))); do
   if grep -qF "$QUEUED_RE" <<<"$pane"; then
     status="queued"; break
   fi
-  # POSITIVE draft evidence from a located prompt box, when one exists. This is the
-  # cursor-row check's blind spot: a pane in COOKED mode (a plain shell whose
-  # foreground process never reads stdin) echoes our paste via the kernel line
-  # discipline and moves the cursor off it on Enter, which is indistinguishable from
-  # a real submit by cursor row alone. If a prompt box IS locatable and still carries
-  # our tail, that is affirmative proof the message was not consumed. Absence of a
-  # glyph is still never used for anything — that inference is the original E7 bug.
+  # Locate the REPL input box (prompt glyph). If we cannot see it, we have NO
+  # evidence of submission state — stay UNCONFIRMED and retry; never infer delivery.
   promptline=$(printf '%s' "$pane" | grep -E '❯|^>|│ >' | tail -1)
-  if [ -n "$promptline" ] && [ -n "$snippet" ] && grep -qF "$snippet" <<<"$promptline"; then
+  if [ -z "$promptline" ]; then
+    status="unconfirmed"; continue
+  fi
+  # Input box located AND still carrying our tail => unsubmitted draft. Flush + retry.
+  # (Submitted messages scroll up into history; a draft stays on the ❯ line.)
+  if [ -n "$snippet" ] && grep -qF "$snippet" <<<"$promptline"; then
     status="draft"; continue
   fi
-  if [ "$saw_draft" = 1 ]; then
-    if _draft_on_input; then
-      status="draft"; continue      # still on the input line => not submitted; flush + retry
-    fi
-    status="delivered"; break        # left the input line => positively submitted
-  fi
-  # No confirmed baseline yet: try to (re)acquire it; never infer delivery from absence.
-  if _draft_on_input; then saw_draft=1; status="draft"; continue; fi
-  status="unconfirmed"; continue
+  # Input box located AND clear of our tail => positively submitted. This is the
+  # only path to success besides the queued banner.
+  status="delivered"; break
 done
 
 [ "$VERBOSE" = 1 ] && { echo "--- pane tail ($TARGET) ---"; printf '%s\n' "$pane" | tail -4; echo "---"; }

packages/mosaic/framework/tools/tmux/test-send-message-glyph-agnostic.sh

@@ -1,97 +0,0 @@
-#!/usr/bin/env bash
-# Red-first regression test for E7 (#1017 task 2): the confirm-check must bind
-# "delivered" to WHETHER THE MESSAGE WAS SUBMITTED, not to which runtime's prompt
-# glyph is present. A pi seat renders a U+2500 rule input box with no ❯/^>/│ >
-# glyph; send-message.sh:118 locates the box only by glyph, so a genuinely
-# delivered message on a glyphless REPL falsely reports exit 2 "may be UNDELIVERED",
-# and the operator's rc=2-driven retry duplicates it.
-#
-# Parameterized on $SEND: RED against the shipping blob (B and D fail), GREEN
-# against a candidate patch. No pi; no fake HOME; hermetic throwaway socket.
-#
-# Submission counting is EXACT and terminal-echo-independent: the fixture message
-# is `echo <tok> >>SINK`; each real submission appends one line. wc -l SINK ==
-# number of times the REPL actually executed the send. This does not depend on how
-# many times the marker string is painted on screen.
-set -u
-SEND="${SEND:?set SEND=/path/to/send-message.sh}"
-SOCKET="glyphagnostic-$$"
-TMP="$(mktemp -d)"
-tmux() { command tmux -L "$SOCKET" "$@"; }
-cleanup() { command tmux -L "$SOCKET" kill-server 2>/dev/null; rm -rf "$TMP"; }
-trap cleanup EXIT
-pass=0; fail=0
-ok() { printf 'ok   %s\n' "$1"; pass=$((pass+1)); }
-no() { printf 'FAIL %s -- %s\n' "$1" "$2"; fail=$((fail+1)); }
-
-mk() { tmux new-session -d -s "$1" -x 120 -y 40 -c "$TMP" "PS1='$2' exec bash --noprofile --norc -i"; sleep 0.5; }
-subs() { [ -f "$1" ] && wc -l <"$1" | tr -d ' ' || echo 0; }  # exact submission count
-
-echo "SEND=$SEND    tmux $(command tmux -V | awk '{print $2}')"
-
-# --- A (control): glyph box (❯) that submits => exit 0, exactly one submission.
-mk ctl '❯ '
-SINK="$TMP/sink.ctl"
-out=$("$SEND" -L "$SOCKET" -t ctl -m "echo x >>'$SINK'" 2>"$TMP/e.ctl"); rc=$?; sleep 0.4
-if [ "$rc" = 0 ] && [ "$(subs "$SINK")" = 1 ]; then
-  ok "control: ❯-box submits => exit 0, exactly one submission"
-else no "control: ❯-box submits => exit 0, one submission" "rc=$rc subs=$(subs "$SINK") err=[$(cat "$TMP/e.ctl")]"; fi
-
-# --- B (THE false-rc regression): glyphless U+2500 box that SUBMITS. Message lands
-#     (subs==1) yet shipping reports exit 2. Must be exit 0.
-mk sub $'──────── \n'
-SINK="$TMP/sink.sub"
-out=$("$SEND" -L "$SOCKET" -t sub -m "echo x >>'$SINK'" 2>"$TMP/e.sub"); rc=$?; sleep 0.4
-if [ "$rc" = 0 ] && [ "$(subs "$SINK")" = 1 ]; then
-  ok "glyphless: U+2500 box that submits => exit 0 (delivered, not 'UNDELIVERED')"
-else no "glyphless: U+2500 box that submits => exit 0" \
-        "rc=$rc subs=$(subs "$SINK")(delivered=$([ "$(subs "$SINK")" -ge 1 ] && echo yes||echo no)) err=[$(cat "$TMP/e.sub")]"; fi
-
-# --- D (duplicate arm): operator follows the rc=2 stderr and retries once. On the
-#     glyphless box, shipping => two submissions (the reported duplicate). The
-#     property: one logical send => exactly one submission. Same fix closes it.
-mk dup $'──────── \n'
-SINK="$TMP/sink.dup"
-tries=0
-for attempt in 1 2; do
-  tries=$((tries+1))
-  out=$("$SEND" -L "$SOCKET" -t dup -m "echo x >>'$SINK'" 2>/dev/null); rc=$?
-  sleep 0.4
-  [ "$rc" = 0 ] && break   # operator stops retrying only when told delivered
-done
-if [ "$(subs "$SINK")" = 1 ]; then
-  ok "duplicate: one logical send (rc-driven retry) => exactly one submission (tries=$tries)"
-else no "duplicate: one logical send => exactly one submission" "submissions=$(subs "$SINK") tries=$tries"; fi
-
-# --- E (faithful hung managed TUI, NOT a cooked shell): raw/no-echo, paints nothing.
-#     A cooked `sleep infinity` echoes the paste via the kernel line discipline and
-#     false-passes a cursor-row fix that is correct on real seats (measured). So: raw.
-mk_rawstuck() { tmux new-session -d -s "$1" -x 120 -y 40 -c "$TMP" \
-  "bash --noprofile --norc -c 'stty -echo -icanon min 1 time 0 2>/dev/null; exec sleep infinity'"; sleep 0.5; }
-mk_rawstuck estuck
-SINK="$TMP/sink.estuck"
-out=$("$SEND" -L "$SOCKET" -t estuck -r 1 -m "this stuck draft was never submitted" 2>/dev/null); rc=$?
-sleep 0.3
-if [ "$rc" != 0 ] && [ "$(subs "$SINK")" = 0 ]; then
-  ok "raw/no-echo stuck TUI (not submitted) => non-zero (no false delivered)"
-else no "raw stuck TUI must NOT report delivered" "rc=$rc subs=$(subs "$SINK")"; fi
-
-# --- F (busy/queued branch, your BUSY-not-runtime finding): glyphless pane rendering the
-#     queued banner, never consuming. QUEUED_RE :113 fires before the glyph grep => rc=0.
-mk_busy() { tmux new-session -d -s "$1" -x 120 -y 40 -c "$TMP" \
-  "bash --noprofile --norc -c 'printf \"Press up to edit queued messages\n\"; exec sleep infinity'"; sleep 0.5; }
-mk_busy ebusy
-SINK="$TMP/sink.ebusy"
-out=$("$SEND" -L "$SOCKET" -t ebusy -m "echo x >>'$SINK'" 2>/dev/null); rc=$?; sleep 0.3
-if [ "$rc" = 0 ]; then
-  ok "busy/queued-banner glyphless => exit 0 (queued is delivery; runtime owns custody)"
-else no "busy/queued-banner must report delivered" "rc=$rc"; fi
-
-# --- C (historical-bug guard): unresolvable target. No pane ever carried our draft
-#     => must fail, never infer delivered from absence of a glyph/snippet.
-if out=$("$SEND" -L "$SOCKET" -t "nonexistent-$$" -m "echo x >>'$TMP/sink.wrong'" 2>/dev/null); then
-  no "wrong-pane: unresolvable target must NOT report success" "expected non-zero, got 0"
-else ok "wrong-pane: unresolvable target => non-zero (no false delivered)"; fi
-
-echo "---"; echo "pass=$pass fail=$fail"
-[ "$fail" = 0 ]

packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh

@@ -4,19 +4,16 @@
 #
 #   1. DELIVERED   — a REPL that renders a `❯ ` input box and submits on Enter
 #                    (text scrolls to history, box clears) => exit 0 "✓ delivered".
-#   2. DELIVERED   — a pane with NO prompt glyph that DOES submit => exit 0. A pi
-#                    seat is this fixture (U+2500 rule, no glyph). Reshaped for
-#                    #1257; see the note at the fixture for why the old exit-2
-#                    assertion was wrong.
-#   2b. UNCONFIRMED— a glyphless pane that never submits (raw/no-echo hung TUI)
-#                    => must fail loud. This carries the historical
-#                    false-positive guard that fixture 2 used to be credited with.
+#   2. UNCONFIRMED — a pane with NO locatable prompt glyph. This is the exact
+#                    historical FALSE POSITIVE: pre-patch it printed "✓ delivered"
+#                    exit 0; post-patch it MUST fail loud (exit 2, stderr
+#                    "could not confirm submission").
 #   3. DRAFT       — a `❯ `-prompt pane that never submits (message stays on the
 #                    input line) => exit 2, stderr "unsubmitted draft".
 set -uo pipefail
 
 HERE=$(cd -- "$(dirname -- "$0")" && pwd)
-SEND="${SEND:-$HERE/send-message.sh}"
+SEND="$HERE/send-message.sh"
 SOCKET="verdict-test-$RANDOM-$$"
 TMP=$(mktemp -d)
 trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$TMP"' EXIT
@@ -40,44 +37,19 @@ else
   no "delivered: ❯-prompt REPL that submits => exit 0 ✓ delivered" "rc=$rc out=[$out] err=[$(cat "$TMP/e1")]"
 fi
 
-# --- Fixture 2: NO prompt glyph, and the pane DOES submit (interactive bash).
-#     RESHAPED 2026-08-16 (#1257), deliberately. This fixture previously asserted
-#     exit 2 here and was labelled "false-positive FIXED". That assertion was wrong,
-#     and locking it in is what kept E7 alive: the pane submits, so "delivered" is
-#     the truth, and a pi seat — whose input box is a bare U+2500 rule with no glyph
-#     — IS this fixture. Reporting exit 2 for it told operators a delivered message
-#     may be undelivered, and the retry that advice invites is the duplicate.
-#
-#     The guard this fixture was reaching for is real and is NOT dropped: "never
-#     infer delivered from absence" is now enforced positively by fixture 2b below
-#     (glyphless AND not submitting => must fail) and by fixture 3 (locatable box
-#     still carrying our tail => draft). Absence alone decides nothing either way.
+# --- Fixture 2: NO prompt glyph (default bash PS1). THE regression: pre-patch this
+#     was a silent false-positive "delivered"; post-patch it must be unconfirmed→exit 2.
 tmux -L "$SOCKET" new-session -d -s noglyph -c "$TMP" \
   'PS1="sh-noglyph$ " exec bash --noprofile --norc -i'
 sleep 0.3
-out=$("$SEND" -L "$SOCKET" -t "=noglyph" -m "verdict fixture two must fail loud" 2>"$TMP/e2"); rc=$?
-if [ "$rc" -eq 0 ] && grep -qF "✓ delivered" <<<"$out"; then
-  ok "delivered: glyphless pane that submits => exit 0 (runtime-agnostic, E7 FIXED)"
-else
-  no "delivered: glyphless pane that submits => exit 0" "rc=$rc out=[$out] err=[$(cat "$TMP/e2")]"
-fi
-
-# --- Fixture 2b: NO prompt glyph AND never submits — a hung managed TUI holding the
-#     terminal in raw/no-echo, which is what a stuck agent seat actually is (measured
-#     on live pi: stty -echo -icanon). Nothing is echoed, nothing is consumed, so
-#     there is no positive evidence of submission and the tool MUST fail loud. This
-#     is the historical false-positive guard, kept as a positive test.
-tmux -L "$SOCKET" new-session -d -s rawstuck -c "$TMP" \
-  'bash --noprofile --norc -c "stty -echo -icanon min 1 time 0 2>/dev/null; exec sleep infinity"'
-sleep 0.3
-if out=$("$SEND" -L "$SOCKET" -t "=rawstuck" -r 1 -m "verdict fixture two-b never submitted" 2>"$TMP/e2b"); then
-  no "unconfirmed: glyphless hung TUI must NOT report success" "expected non-zero, got 0 (out=[$out])"
+if out=$("$SEND" -L "$SOCKET" -t "=noglyph" -m "verdict fixture two must fail loud" 2>"$TMP/e2"); then
+  no "unconfirmed: glyphless pane must NOT report success" "expected exit 2, got 0 (out=[$out])"
 else
   rc=$?
-  if [ "$rc" -ne 0 ] && grep -qF "could not confirm submission" "$TMP/e2b"; then
-    ok "unconfirmed: glyphless hung TUI (raw/no-echo) => non-zero + 'could not confirm submission'"
+  if [ "$rc" -eq 2 ] && grep -qF "could not confirm submission" "$TMP/e2"; then
+    ok "unconfirmed: glyphless pane => exit 2 + 'could not confirm submission' (false-positive FIXED)"
   else
-    no "unconfirmed: glyphless hung TUI => non-zero + stderr" "rc=$rc err=[$(cat "$TMP/e2b")]"
+    no "unconfirmed: glyphless pane => exit 2 + stderr" "rc=$rc err=[$(cat "$TMP/e2")]"
   fi
 fi