session-orchestrator 3.21.0 → 3.23.0

package/skills/session-start/phase-8-5-express-path.md

@@ -4,13 +4,57 @@
 
 After the user confirms the session type and scope via the Q&A above, evaluate whether the **Express Path** applies before handing off to session-plan. The express path collapses the full 5-wave plan into a single coordinator-direct phase for lightweight sessions.
 
-**Activation conditions (ALL three must be true):**
+**Do not evaluate these conditions by hand — run the CLI (#1119, #1146).**
+
+```bash
+node scripts/express-path.mjs \
+  --repo-root "$PWD" \
+  --session-type <housekeeping|feature|deep> \
+  --task-count <N> \
+  --parallel-agents <true|false>
+```
+
+stdout is one JSON line — `{"activated":<bool>,"reasons":[…]}`. The activation banner and every
+diagnostic go to stderr. Exit `0` means the evaluation COMPLETED, activation and refusal alike:
+branch on the `activated` field, never on the exit code. Exit `1` is an input error (a missing or
+invalid `--session-type` / `--task-count` / `--repo-root`), exit `2` an unreadable config file.
+`--parallel-agents` is optional and tri-state — omitting it asserts nothing and leaves the field
+out of the record, which is NOT the same claim as `false`.
+
+`--repo-root` is required and is never defaulted from `SO_PROJECT_DIR` (#941): an ambient
+destination once put a synthetic record into the operator's real fleet ledger.
+
+Until #1146 this block was a fenced `js` snippet with an `import` — prose no process runs. Measured
+at HEAD `01eb35d`: `rg -n "evaluateExpressPath" scripts hooks` returned the definition and nothing
+else, so the module had ZERO production callers. A hook cannot close that gap either — `sessionType`
+and `taskCount` exist only AFTER the Phase 8 Q&A, and no hook event fires there. The caller has to
+be something the coordinator RUNS at this point in the flow, which is what `scripts/express-path.mjs`
+is.
+
+`evaluateExpressPath` (behind the CLI) makes the decision AND records it as `orchestrator.express_path.evaluated`
+— on **every** evaluation, activation and refusal alike. That is the whole point: until #1119 the
+conditions below were prose only, `scripts/lib/config.mjs` discarded `express-path` **even when the
+block was present** (measured: 88 keys emitted, none of them this one), and the ledger held **0**
+express-path events across its entire history. Whether the path ever fired was unanswerable.
+Re-deriving the conditions in a coordinator turn re-opens exactly that hole; the conditions below
+are the specification the module implements, not a second implementation.
+
+`reasons` carries the blocking codes when `activated: false` and the satisfied ones when `true`.
+Nothing short-circuits, so a refusal names **every** blocker — a reader can see whether trimming
+the issue list alone would have helped. Unmeasured inputs are omitted from the payload, never
+written as `0`/`false`, and an unmeasured `sessionType`/`taskCount` fails CLOSED.
+
+**Activation conditions (the module's specification):**
 
 1. `express-path.enabled` is `true` in Session Config (default: `true` — opt-in by default, opt-out via `express-path.enabled: false`).
 2. Session type is `housekeeping` (the user confirmed `housekeeping` in Phase 8).
 3. Agreed issue scope is ≤ 3 issues AND no parallel agents are required (i.e., tasks are sequential, no wave decomposition needed).
 
-**Backward compat:** when `express-path.enabled: false`, this evaluation is skipped entirely and the normal 5-wave session-plan flow runs as before.
+> Condition 3 carries **two** clauses, so the module takes **four** inputs, not three. The
+> condition matrix below and `docs/session-config-reference.md` both list a `housekeeping` / 1–3 /
+> `enabled: true` row that still does NOT activate, because parallel agents are required.
+
+**Backward compat:** when `express-path.enabled: false`, the normal 5-wave session-plan flow runs as before. Note that the EVALUATION itself is not skipped — run the CLI regardless, and it returns `{"activated":false,"reasons":["disabled-by-config"]}` and records that refusal. An opt-out that leaves no record is indistinguishable in the ledger from an evaluation that never happened, which is the #1119 hole.
 
 **Historical context:** The 13 prior coordinator-direct sessions documented in `CLAUDE.md` (or `AGENTS.md` on Codex CLI; 2026-04 series — vault-mirror GH#31, phased-rollout #307, v3.2.0 release, etc.) were all running this pattern implicitly: no wave decomposition, coordinator executes tasks directly in sequence. This phase codifies what was already proven to work.
 
@@ -22,23 +66,42 @@ Emit the following banner immediately after the Phase 8 Q&A resolves:
 Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.
 ```
 
-Then **skip the handoff to session-plan entirely**. Instead, execute the agreed tasks directly as the coordinator:
-
-1. For each agreed task (in dependency order): execute as a direct coordinator action — read files, make changes, run quality checks inline.
-2. After all tasks complete, invoke `skills/session-end/SKILL.md` directly (bypass session-plan and wave-executor).
-3. Log the express-path activation in STATE.md `## Deviations` section: `Express path: N tasks executed coord-direct (express-path.enabled: true, session-type: housekeeping, scope: N issues)`.
+> **RESOLVED (#1146, operator decision) — session-plan RUNS, in shortened form.** Five documents
+> described the post-activation routing and two of them said session-plan was skipped entirely.
+> That reading cannot work: `commands/go.md` gates on a 1-wave Express Path plan, which under a
+> skipped session-plan would never have been produced — `/go` would look for a plan that does not
+> exist. The routing is now one sentence everywhere:
+>
+> **Phase 8.5 evaluates via `scripts/express-path.mjs`, prints the banner, then hands off NORMALLY
+> to Phase 9 → session-plan.** session-plan detects the banner and its
+> `## Express Path Short-Circuit (#214)` section emits a minimal 1-wave `coordinator-direct` plan
+> (0 agents dispatched, no role decomposition, no wave splitting). `/go` detects that plan per
+> `commands/go.md` § Express Path Detection and routes to coord-direct execution plus
+> session-end auto-invocation — never to wave-executor.
+>
+> What activation skips is the WAVE MACHINERY (subagent dispatch, role decomposition, inter-wave
+> checkpoints), not the planning handoff. The two sites that said otherwise —
+> this file and `skills/session-start/SKILL.md` — were corrected in the same pass;
+> `docs/session-config-reference.md`, `skills/session-plan/SKILL.md` and `commands/go.md`
+> already carried the surviving reading.
+
+Hand off to Phase 9 as usual. The coordinator then executes the 1-wave plan session-plan emits directly, without dispatching subagents:
+
+1. Proceed to Phase 9 (session-plan handoff) carrying the banner. session-plan short-circuits to the 1-wave `coordinator-direct` plan; `/go` detects it and does NOT invoke wave-executor.
+2. For each agreed task (in dependency order): execute as a direct coordinator action — read files, make changes, run quality checks inline. No subagents, no inter-wave checkpoints.
+3. Log the express-path activation in STATE.md `## Deviations` section: `Express path: N tasks executed coord-direct (express-path.enabled: true, session-type: housekeeping, scope: N issues)` — written BEFORE session-end is invoked. Then invoke `skills/session-end/SKILL.md` directly.
 4. After session-end completes successfully: verify STATE.md `status` is `completed` and `## Deviations` contains the express-path entry from step 3. If either is missing, warn the user with a one-line note and instructions to re-run `/close` manually. Then return the final session summary to the user.
 
 **Persistence contract:**
 
-The four steps above MUST all happen within a single coordinator turn. Specifically:
+Step 1 is the Phase 9 handoff and ends the session-start turn — the operator types `/go` next, exactly as on the normal path. Steps 2–4 then MUST all happen within a SINGLE coordinator turn, the one `/go` opens. Specifically:
 
-- Step 1 (execute tasks) happens first in the coordinator's main flow.
-- Step 2 (deviations log) is written BEFORE session-end is invoked. The coordinator calls `appendDeviation()` from `scripts/lib/state-md.mjs` to append the `Express path:` bullet to the `## Deviations` section while STATE.md is still `status: active`.
-- Step 3 (invoke session-end) flips `status` to `completed`, writes the metrics record to `.orchestrator/metrics/sessions.jsonl`, and runs the standard close flow. Session-end has no Express Path-specific logic — it treats this run identically to any other completed session.
+- Step 2 (execute tasks) happens first in that turn's main flow.
+- Step 3a (deviations log) is written BEFORE session-end is invoked. The coordinator calls `appendDeviation()` from `scripts/lib/state-md.mjs` to append the `Express path:` bullet to the `## Deviations` section while STATE.md is still `status: active`.
+- Step 3b (invoke session-end) flips `status` to `completed`, writes the metrics record to `.orchestrator/metrics/sessions.jsonl`, and runs the standard close flow. Session-end has no Express Path-specific logic — it treats this run identically to any other completed session.
 - Step 4 (verification) is the coordinator's final action before returning control. The verification check uses `parseStateMd()` from `scripts/lib/state-md.mjs` to read the file and check `frontmatter.status === 'completed'` and that the body contains the literal string `Express path:`.
 
-If `/go` is invoked but the session-plan emitted a 1-wave Express Path plan (per `skills/session-plan/SKILL.md` § "Express Path Short-Circuit"), the `/go` command MUST detect this and route to coord-direct execution + session-end auto-invocation, NOT to wave-executor. See `commands/go.md` for the detection branch.
+When `/go` is invoked and session-plan emitted a 1-wave Express Path plan (per `skills/session-plan/SKILL.md` § "Express Path Short-Circuit"), the `/go` command MUST detect this and route to coord-direct execution + session-end auto-invocation, NOT to wave-executor. See `commands/go.md` for the detection branch — that plan is the artifact `/go` keys on, which is why Phase 8.5 hands off to session-plan rather than skipping it.
 
 **When Express Path does NOT activate** (conditions not met):
 
@@ -56,6 +119,8 @@ Proceed normally to Phase 9 (session-plan handoff). The express-path evaluation
 
 ## See Also
 
+- `scripts/express-path.mjs` — the CLI this phase runs; `scripts/lib/express-path.mjs` holds the decision + its `orchestrator.express_path.evaluated` record
+- `skills/session-plan/SKILL.md` § "Express Path Short-Circuit (#214)" — the 1-wave plan Phase 9 emits when the banner is present
 - `commands/go.md` — Express Path detection and auto-invocation of session-end after coord-direct tasks
 - `skills/session-end/SKILL.md` — Phase 1 pre-check (Rule 2) blocks `/close` when STATE.md `status: completed`; auto-invocation from express-path bypasses this
 - `commands/close.md` — Rule 2 wording the user sees if express-path persistence breaks

package/skills/session-start/soul.md

@@ -64,6 +64,116 @@ The active level is `efficiency.output-level` in `~/.config/session-orchestrator
 - Shape: explain the WHY behind each recommendation, name the alternatives you rejected and why, spell out unfamiliar terms on first use.
 - Escalation: `expand <topic>` — see § Escalation above.
 
+### Register — how a sentence reads
+
+The budgets above set *how much* you say. This sets *how*. It binds at every
+level and is not itself a budget: applying it changes word order and word
+choice, not line count. It is the canonical statement for this repo — the
+other three souls (`plan`, `brainstorm`, `grill`) point here rather than
+copying it.
+
+**Write for someone who knows this project but has not seen what you just saw.**
+What he needs to decide stands in the text, not in the file it points at — in
+the AUQ payload and in every finding you post.
+
+This is not "explain it like he is five". The operator owns this repo. He is
+not missing knowledge, he is missing **observation** — he did not watch the
+command you just ran or read the file you just opened. A knowledge framing
+would be factually wrong and condescending at the same time. Write across, not
+down: same expertise as yours, minus your last ten minutes.
+
+#### Plain words, real things
+
+> **Say more simply what actually happens — and introduce nothing that does not exist.**
+>
+> **The test:** delete every noun the system does not contain. If the sentence
+> is still true and complete, it was no analogy. If it collapses, the analogy
+> was load-bearing — replace it with a description of what actually happens.
+
+Five worked cases, in rising difficulty:
+
+1. "Waiting means the other session finishes first." — **allowed.** Sessions
+   and waiting both exist; nothing foreign was introduced.
+2. "Think of the session as a level crossing." — **forbidden.** Delete "level
+   crossing" and nothing is left. Say what happens instead: one session holds
+   `.orchestrator/session.lock`, the other waits for it.
+3. "The token budget is used up." — **allowed.** `TOKEN_BUDGET_EXCEEDED` is a
+   real identifier and "budget" is the system's own word. Adding "…like a tank
+   of fuel" would be forbidden — the tank does not exist.
+4. "Think of the kill-switches as a fuse box." — **forbidden, and wrong on the
+   facts.** Fuses trip on overload; the kill-switches also test elapsed time and
+   confidence. The image sounds helpful and is not. A wrong picture costs more
+   than no picture, because the operator reasons from it.
+5. **Dead metaphors.** A proper name may itself be a metaphor —
+   `pre-bash-destructive-guard` is called a guard — and you use the name as
+   given. Reviving the image is the violation: "the guard will not let it
+   through" invites the operator to picture a guard and then reason from the
+   picture instead of from the hook. Name the identifier, then say what it
+   does: the hook denies the Bash call.
+
+#### Precedence over § "Never traded for brevity"
+
+There is a real collision above: "say it more simply" can water down a precise
+error message. Resolve it in three steps.
+
+1. **Simplifying removes words, never facts.** If a path, a number, an error
+   code, an identifier, or an instruction to act disappears, that is data loss,
+   not simplification — and § "Never traded for brevity" already forbids it.
+2. **When both will not fit in one sentence: precision in the sentence,
+   plainness in the one beside it.** The exact term is never replaced, only
+   accompanied. It is what the operator greps, quotes, and pastes into an issue.
+3. **The mechanical tie-breaker:** could the token you are about to cut ever
+   appear in a `grep`? Then it stays.
+
+Measured 2026-08-22 at `a4f93cf`: of 191 option descriptions in this repo, the
+20 that match the safety lexicon (`SAFETY_PATTERN` in
+`scripts/lib/auq/schema.mjs`) run 26–108 codepoints — all of them under both K6
+length thresholds (`descriptionCharsWarn` 120, `descriptionCharsFail` 150). The
+collision therefore does not occur today. This precedence rule is a precaution,
+not a repair.
+
+#### Worked example — an operator-visible message
+
+`formatBlockReason()` in `scripts/lib/issue-budget.mjs` is what the operator
+sees when the issue cap blocks a creation. Rendered with the collector-issue
+sink, before:
+
+```
+issue-budget: session cap reached — 12/12 issues already created.
+This request was NOT created. It is parked as overflow entry #3 in:
+  .orchestrator/runtime/issue-budget-overflow.jsonl
+session-end Phase 5 will fold all overflow entries into ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`. Nothing is lost.
+Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),
+and broken-window closure issues — those are never deferred.
+To raise the cap for this repo, edit `issue-budget.max-per-session` in the Session Config;
+`mode: warn` reports without blocking, `mode: off` disables the gate.
+```
+
+After:
+
+```
+Nothing is lost — the issue is parked, and nothing needs doing right now.
+issue-budget: session cap reached — 12/12 issues already created, so this one was NOT created.
+It is parked as overflow entry #3 in:
+  .orchestrator/runtime/issue-budget-overflow.jsonl
+session-end Phase 5 folds all overflow entries into ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`.
+Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),
+and broken-window closure issues — those are never deferred.
+To raise the cap for this repo, edit `issue-budget.max-per-session` in the Session Config; `mode: warn` reports without blocking, `mode: off` disables the gate.
+```
+
+Three changes, and only these three: the operator's own question — *must I do
+something?* — moved to line 1, carrying "Nothing is lost" up from line 4 where
+he used to reach it last; `will fold` became the active `folds`; and the first
+two lines merged on a causal `so`, which is why "This request" is now "this
+one" — the same subject, already named in the sentence.
+
+The whole word-level diff is four dropped tokens: `This`, `request`, `will`,
+`fold`. Not one of them is a path, a count, a label, a config key, or a mode
+value; every one of those survives character for character. Eight lines before,
+eight lines after — **this register is not a diet.** It is the same facts, in
+the order the reader needs them.
+
 ### Companion dials
 
 Same file, same lookup, same fallback-to-default rule:

package/skills/test-runner/SKILL.md

@@ -216,11 +216,11 @@ Group `medium` and `low` findings and present via a single `AskUserQuestion` cal
 AskUserQuestion({
   questions: [{
     question: `<N> medium/low findings to triage. How to handle?`,
-    header: "Test-runner triage",
+    header: "Triage",
     options: [
       {
         label: "Create all (Recommended)",
-        description: "File <N> new issues, all with label from:test-runner"
+        description: "Files <N> new issues at once, all with label from:test-runner — fastest, and you can still close any of them afterwards."
       },
       {
         label: "Review each",

package/skills/using-orchestrator/SKILL.md

@@ -67,7 +67,7 @@ When two or more candidates score ≥ 0.85 with delta < 0.15, call `AskUserQuest
 AskUserQuestion({
   questions: [{
     question: "Your message matches multiple workflows. Which one did you mean?",
-    header: "Skill Dispatch",
+    header: "Dispatch",
     multiSelect: false,
     options: [
       { label: "<top-skill display name> (Recommended)", description: "<one-line description of what it does>" },

package/skills/vault-sync/validator.mjs

@@ -92,6 +92,26 @@ const vaultNoteTypeSchema = z.enum([
   'board',
 ]);
 
+// VENDORED COPY. SSOT: projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts
+// (`vaultNoteStatusSchema`). This file is a standalone CLI with no exports, so the
+// values cannot be imported — they are hand-kept in sync, and that is the known cost.
+//
+// Measured 2026-08-23: FOUR hand-maintained copies of this enum exist —
+//   1. the SSOT above
+//   2. this file
+//   3. sven-infra `02-cron/vault-overview-sync.sh:216`
+//   4. `tests/lib/vault-mirror/render-sessions.test.mjs:490`, whose own comment names
+//      this file as its source and then transcribes it
+// Copy 4 is deliberately NOT widened: it asserts membership for a mapper that emits
+// only `verified`/`draft`, so adding values it cannot produce would weaken it.
+//
+// A drift test reading the SSOT directly was considered and REJECTED: the SSOT lives
+// in a sibling repo resolved host-locally, so such a test passes on this machine and
+// fails in CI, where projects-baseline is not checked out. The durable fix is
+// generation from the SSOT at build time, not a test that reads across a repo
+// boundary. Revisit trigger: a fifth copy, or the first CI-visible drift.
+//
+// Order below mirrors the SSOT exactly, so a diff of the two lists is readable.
 const vaultNoteStatusSchema = z.enum([
   'draft',
   'active',
@@ -100,6 +120,17 @@ const vaultNoteStatusSchema = z.enum([
   'production',
   'mvp',
   'idea',
+  // Added 2026-08-23 (baseline MR !27, merge 6f38aeb). sven renders these into
+  // `01-projects/*/_overview.md`; measured the same day, SIX of them already carried
+  // one of these values (4x dead, 1x paused, 1x maintenance). Falsified rather than
+  // assumed: removing the four again produced exactly 6 `status` errors, re-adding
+  // them produced 0. Without them the strict gate blocks every vault session-close.
+  // Slugs deliberately not listed here — the scanner treats them as private
+  // (`check-owner-leakage` CP6), and the count is the load-bearing part anyway.
+  'maintenance',
+  'planned',
+  'paused',
+  'dead',
 ]);
 
 const vaultFrontmatterSchema = z

package/skills/wave-executor/SKILL.md

@@ -44,7 +44,7 @@ Every harness creates friction. The goal is not minimum friction — it is usefu
 - Silent partial completion (STATUS line requirement forces explicit reporting)
 - Untracked carryover work (session-end plan verification catches unresolved tasks)
 
-The harness does not hope agents self-correct. It detects stagnation patterns — pagination-spiral, turn-key-repetition, error-echo — classifies them into the Error-Class Taxonomy defined in `circuit-breaker.md`, and re-scopes mechanically. Review logic lives in `wave-loop.md` § "Review Agent Outputs".
+The harness does not hope agents self-correct. It detects stagnation patterns — pagination-spiral, turn-key-repetition, error-echo (read by the coordinator during post-wave review), plus psa007-git-write and status-partial (detected live by the transcript tailer, recorded with `source: "tail"`) — classifies error-echo into the Error-Class Taxonomy defined in `circuit-breaker.md`, and re-scopes mechanically. Review logic lives in `wave-loop.md` § "Review Agent Outputs"; the tailer's start and its silence-is-not-success caveat live in the same file, step 2.0-bis.
 
 ## Platform Note
 
@@ -192,6 +192,8 @@ Read and follow `wave-loop.md` in this skill directory for the complete wave exe
 
 The coordinator (you) is responsible for updating per-task mission status in STATE.md as tasks progress through the wave. Use `setMissionStatus(stateContent, taskId, status)` from `scripts/lib/state-md.mjs` and write the result back to STATE.md immediately.
 
+**`taskId` grammar (enforced).** `setMissionStatus` refuses any `taskId` outside `[a-z][a-z0-9]*(?:-[a-z0-9]+)*-\d+` — lowercase segments joined by single hyphens, ending in a bare digit run. Accepted: `m-1`, `docs-2`, `w2-1`, `w2-a-10`. Refused (`refused: 'id-grammar'`): `w2-a10` (digits fused onto a letter segment), `w3-p2` (no trailing bare-digit segment), `W3-I1` (uppercase), `Docs_2` (underscore). A refused write returns `{ written: false, reason: 'id-grammar' }` from `setMissionStatusOnDisk` and logs a stderr WARN naming the rejected id — nothing is written to STATE.md on refusal, so mint ids matching this grammar from the start rather than relying on the refusal to catch a typo.
+
 **Per-task transition rules (coordinator fires these, NOT wave-loop.md):**
 
 | Transition | When to fire |
@@ -479,7 +481,7 @@ An opt-in bounded-concurrency cursor-based pull loop that replaces the default P
 
 ## Anti-Patterns
 
-- **NEVER** run `run_in_background: true` during waves — you lose coordination ability
+- **NEVER** count launch acks as completions — verify the started set against `agent-<id>.meta.json` sidecars and completions against task-notifications (`wave-loop.md § Started-Set Verification`). `run_in_background: true` is ALLOWED and RECOMMENDED for wave dispatch: measured 2026-08-22 (v2.1.239), under blocking dispatch the coordinator was 143 s incapable of acting between an agent's mid-run escalation and its own next turn — escalation latency equals the batch's remaining runtime. Background dispatch returns turns to the coordinator between agent completions; a running agent received a queued message mid-run and answered ~9 min before its final report.
 - **NEVER** skip inter-wave review — quality degrades exponentially
 - **NEVER** let agents commit independently — coordinator commits at session end
 - **NEVER** continue to next wave if previous wave has unresolved failures

package/skills/wave-executor/circuit-breaker.md

@@ -103,12 +103,14 @@ The function never throws — it always returns a result object. Treat `skipped:
      description: "...",
      prompt: "...",
      subagent_type: "general-purpose",
-     run_in_background: false,
+     run_in_background: true,
      isolation: "worktree"
    })
    ```
    When resolved isolation is `none`, omit the `isolation` parameter (agents run in the coordinator's working tree).
 
+   `isolation` and `run_in_background` are orthogonal: worktree isolation partitions the filesystem, backgrounding decides when the coordinator's turn returns. A backgrounded worktree agent still merges back on completion — but do NOT read the immediate launch ack as "the worktree merged". Wait for the agent's task-notification before step 4 below (`wave-loop.md § Started-Set Verification`).
+
 4. **Post-wave merge**: After wave completes, worktree changes are automatically available. If agents made changes in worktrees:
    - Review each agent's changes for conflicts using `git diff` between worktree branches
    - **Merge strategy**: Apply agent changes sequentially (by agent number). For each agent:
@@ -120,7 +122,11 @@ The function never throws — it always returns a result object. Treat `skipped:
 
 ## Stagnation Patterns
 
-> Detection rules for the coordinator to apply during post-wave review (step 2 of `wave-loop.md`). All three patterns are LLM heuristics, not executable code — the coordinator interprets them contextually based on agent output and tool-call history.
+> Detection rules applied at two different moments, by two different producers of the SAME `stagnation_detected` record (`wave-loop.md` § "Review Agent Outputs" carries the schema; `source` says which).
+>
+> - **Coordinator heuristics (3):** Pagination Spiral, Turn-Key Repetition, Error Echo. LLM heuristics, not executable code — the coordinator interprets them contextually from agent output and tool-call history during post-wave review (step 2 of `wave-loop.md`). Recorded with `source: "coordinator"`.
+> - **Tail-mechanical (2):** PSA-007 Git-Write and Status-Partial (§ 4 / § 5 below). Executable regexes run live by `scripts/lib/wave-transcript-tail.mjs` against the session's subagent transcripts — no model call, no judgement. Recorded with `source: "tail"`.
+> - **Error Echo is BOTH.** The coordinator's contextual reading of it is unchanged, and the tailer additionally matches its repeated-failure signature mechanically. One wave can therefore produce an error-echo record from either producer; the records are otherwise identical and are told apart only by `source`.
 
 ### 1. Pagination Spiral
 
@@ -153,19 +159,38 @@ Same error message returned 3 times, with the agent attempting the same fix (or
 - `command-blocked` — denial from `enforce-commands.sh` (blocked command list).
 - `other` — fallback when none of the above match.
 
-The `error_class` value is used by the stagnation event-write rule in `wave-loop.md` § "Review Agent Outputs".
+The `error_class` value is used by the stagnation event-write rule in `wave-loop.md` § "Review Agent Outputs". The taxonomy belongs to Error Echo **alone** — the four patterns below and above it omit the field entirely rather than falling back to `other`.
+
+### 4. PSA-007 Git-Write (source: tail)
+
+**Indicator:** a subagent's Bash call runs a git-write command — `git add`, `git commit`, `git stash`, `git push`, and equally `git mv` / `git rm` / `git reset` / `git checkout -- <file>`. `.claude/rules/parallel-sessions.md` § PSA-007 forbids all of them for dispatched agents: the git index and stash are shared resources of the working copy, not a per-agent workspace. Fleet evidence (2 repos, 2026-07, conf ≥ 0.9) records `index.lock` collisions and stash operations that silently discarded a sibling agent's work-in-progress.
+
+**Detected by:** the tailer, mechanically, on the FIRST occurrence — not by post-wave review, and not on a repetition threshold. Today the coordinator learns of a subagent git-write only when the agent volunteers it in its own report.
+
+**Action:** surface it in the wave progress update at once and inspect the shared index (`git status --porcelain`, `git stash list`) before the next dispatch. Do NOT re-dispatch into the same shared tree until the index state is understood — a stash the agent created is one the sibling cannot find. No `error_class`; `occurrences: 1` is the normal value.
+
+### 5. Status-Partial (source: tail)
+
+**Indicator:** the agent's own transcript contains `STATUS: partial` (or `STATUS: failed`) — a **self-reported** failure, not an inferred one, so there is nothing to interpret.
+
+**Detected by:** the tailer, mechanically. The value here is **durability, not earliness**: when maxTurns kills an agent after it wrote the line but before its final report reaches the coordinator, the finding is lost today. The `events.jsonl` record survives that kill.
+
+**Action:** treat exactly as the § Status Detection Protocol `partial` / `failed` branch above — carry forward the remaining work, or re-dispatch with narrower scope. A tail record is a **backstop for** the agent's report, never a replacement: when the report does arrive, the report wins and the tail record is corroboration (do not double-count one failure as two). No `error_class`; `occurrences: 1`.
 
 ### Decision Table
 
-| Pattern | Indicator | Action | Error Class |
-|---------|-----------|--------|-------------|
-| Pagination Spiral | 3+ Read/Grep on same file with only pagination args, no Edit between | STAGNANT — re-dispatch with line-range scope | N/A |
-| Turn-Key Repetition | 3 identical consecutive turn keys (pagination-stripped) | SPIRAL — revert, narrow, re-dispatch | N/A |
-| Error Echo | Same error 3x, same fix attempted | FAILED — escalate with error context | see taxonomy above |
+| Pattern | Indicator | Action | Error Class | Source |
+|---------|-----------|--------|-------------|--------|
+| Pagination Spiral | 3+ Read/Grep on same file with only pagination args, no Edit between | STAGNANT — re-dispatch with line-range scope | N/A | coordinator |
+| Turn-Key Repetition | 3 identical consecutive turn keys (pagination-stripped) | SPIRAL — revert, narrow, re-dispatch | N/A | coordinator |
+| Error Echo | Same error 3x, same fix attempted | FAILED — escalate with error context | see taxonomy above | coordinator **and** tail |
+| PSA-007 Git-Write | Subagent Bash runs `git add`/`commit`/`stash`/`push` (or `mv`/`rm`/`reset`/`checkout --`) | Surface immediately; inspect shared index before next dispatch | N/A | tail |
+| Status-Partial | Agent transcript carries `STATUS: partial` / `STATUS: failed` | Same as the Status Detection Protocol `partial`/`failed` branch; backstop for a lost report | N/A | tail |
 
 ### Detection Discipline
 
-- These checks run during step 2 of `wave-loop.md` ("Review Agent Outputs"), per agent, after the wave completes — not during the agent's execution.
+- The three **coordinator** checks run during step 2 of `wave-loop.md` ("Review Agent Outputs"), per agent, after the wave completes — not during the agent's execution. The two **tail** checks (§ 4 / § 5) run live and are the exception to that timing, which is exactly why they survive a maxTurns kill.
+- **Tail silence is not a clean wave.** Transcripts flush per turn, so an agent inside one long tool call is unobservable for that call's duration (`.claude/rules/loop-and-monitor.md` § LM-002). Absence of tail records never substitutes for the post-wave review.
 - Two different agents reading the same file is **not** a spiral. That is coordination across agents, not stagnation within an agent.
 - A legitimate sequential read of a large file (e.g., reading lines 1-200, then 200-400 to gather full context for an upcoming edit) is **not** a pagination spiral if the agent eventually edits the file. The pattern triggers only when paging continues without ever producing an edit.
 - These patterns are heuristics. When in doubt, prefer false negatives (let the agent finish) over false positives (kill productive work).