fix(docs): resolve audit mismatches + writable mode resolves conflicts itself

Two changes, both on the existing v0.8.0 (no version bump — marketplace.json
just catches up to the other spots).

Docs (from the Fusion docs-vs-reality audit):
- marketplace.json: 0.7.2 -> 0.8.0 (the 5th version spot, previously missed).
- README/CLAUDE: drop the phantom `MMT_LIVE=1 npm test` live-test gate (no
  such gate exists in test/); state the suite is fully offline + live work is
  smoke-tested by hand. Fix the matching backends.mjs comment.
- PROBES.md: add SUPERSEDED annotations — winpty -> node-pty/ConPTY is the
  live agy fix; codex prompt is delivered on STDIN (`-`), not a positional
  arg; remove/annotate deleted bash-era refs (backends.sh/route.sh/run.sh/
  python/jq); correct the `--dangerously-bypass-approvals-and-sandbox`
  "not used" line (it IS used by --writable). Probe findings preserved.
- roster.json: _comment backends.sh -> src/lib/backends.mjs; codex _note now
  describes the stdin invocation + writable_extra.
- dir maps (README+CLAUDE): add src/lib/validate-config.mjs + docs/INTERFACES.md.
- docs/REASONING.md: "zero runtime deps" -> stdlib-only for the reasoning path
  (node-pty is lazy-loaded only by the agy lane).

Writable mode — orchestrator resolves conflicts (was: report + leave for user):
- workflows/team.mjs Integrate stage: on a merge conflict the integration
  agent (now opus, with Read/Edit/Write) RESOLVES it inside the dedicated
  integration worktree — reads both sides, edits to a correct combined result,
  removes all markers, completes the merge — so the user gets ONE finished,
  conflict-free `mmt/team-<slug>` branch. Only a genuinely-unreconcilable
  conflict is aborted + left as `unresolved` (worktree kept). Schema:
  `conflicts` -> `resolved` + `unresolved`. Safety rule intact: all merges/
  edits happen in INT_WORKTREE; the user's current branch is never touched.
- Docs (README/CLAUDE/commands/team.md) + tests updated to match.

99/99 offline tests green. Codex-verified: the conflict-resolution change
passed codex review (safety rule intact, safe resolution, bounded unresolved
escape hatch, correct cleanup); one [LOW] log-wording nit fixed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: WatchAndyTW

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "multi-model-team",
       "description": "Delegates token-heavy, self-contained tasks to local CLI backends chosen by task size and type, with credit-exhaustion fallback through the backend chain to native Claude and a glanceable statusline HUD. Routing and shipped backend behavior are configured in config/roster.json; adding a new backend kind requires invoker and health support in code. /team runs a decompose → dispatch → verify → fix → synthesize pipeline; an optional config-gated UserPromptSubmit hook can proactively nudge delegation.",
-      "version": "0.7.2",
+      "version": "0.8.0",
       "author": {
         "name": "WatchAndyTW",
         "email": "watchandytw@gmail.com"
@@ -29,5 +29,5 @@
       ]
     }
   ],
-  "version": "0.7.2"
+  "version": "0.8.0"
 }

CLAUDE.md

@@ -10,7 +10,8 @@ glanceable statusline HUD.
 else is Node stdlib. Cross-platform (Windows/Linux/macOS). `package.json` `"type":"module"`.
 
 **Status:** built, adversarially reviewed, and green. `npm test` passes **99/99** offline
-(plus live agy + codex smoke tests under `MMT_LIVE=1`). Two live backends: **agy** (Gemini)
+(no backend calls; live agy/codex behaviour is smoke-tested by hand, not via a `npm test` gate).
+Two live backends: **agy** (Gemini)
 and **codex** (OpenAI Codex CLI); opencode remains a config-only stub. codex also serves as the
 **`/team` verifier**. See `README.md` (user-facing), `PROBES.md` (grounded CLI findings), and
 `docs/PLAN.md` (original design plan).
@@ -108,6 +109,7 @@ src/lib/team-spec.mjs           /team cap-spec parser (replaces team_spec.py)
 src/lib/team-plan.mjs           plan.json → per-subtask files (replaces team_plan.py)
 src/lib/reason-spec.mjs         /reasoning panel-spec parser: expandPanel / parsePanel / splitPanel
 src/lib/gen-agents.mjs          regenerate agents/*.md from roster.json (replaces gen_agents.py)
+src/lib/validate-config.mjs     roster.json validator (unique route names, valid tiers/backends/agents)
 src/bin/route.mjs               task → decision JSON CLI (replaces route.sh)
 src/bin/run.mjs                 executor + fallback chain + HUD state (replaces run.sh)
 src/bin/team.mjs                scripted CLI-backend fan-out (replaces team.sh)
@@ -125,6 +127,7 @@ workflows/reasoning.mjs         Ultracode Fusion workflow: Panel → Judge → S
 test/*.test.mjs                 offline test suite (npm test — node --test)
 docs/PLAN.md                    original implementation plan (historical)
 docs/REASONING.md               design contract for the /reasoning Fusion pipeline
+docs/INTERFACES.md              module interface contract (binding signatures for the Node ESM port)
 ```
 
 ---
@@ -190,8 +193,10 @@ PR** (back-compat). *writable (`--writable`):* each subtask gets its **own git w
 HEAD; the agent makes **real changes** there (CLI **full-auto** via `run.mjs --cwd <wt> --writable`,
 selecting the backend's `writable_extra` instead of `extra`); then a deterministic **Setup → Integrate**
 pair of Bash sub-agents (the Workflow runtime has no fs/git) create the worktrees and **merge each into
-one integration branch `mmt/team-<slug>`** off HEAD — **conflicts reported, never auto-resolved**; the
-user's branch is untouched (no auto-merge) and **no `gh` PR** is created. Worktrees live under
+one integration branch `mmt/team-<slug>`** off HEAD — **the orchestrator resolves any merge conflicts
+itself and completes the merge**, so you get one finished, conflict-free branch (only a conflict it
+genuinely can't reconcile is left as `unresolved`); the user's branch is untouched (no auto-merge) and
+**no `gh` PR** is created. Worktrees live under
 `.mmt/worktrees/<slug>/` (gitignored). Enable per-invocation (`--writable` / Workflow `args.writable`)
 or via roster `team.mode:"writable"`. The full-auto sandbox is config-tunable: each backend's
 `writable_extra` in `roster.json` (codex `--dangerously-bypass-approvals-and-sandbox`; agy keeps its
@@ -349,11 +354,11 @@ fallback hop.
 
 ```bash
 npm test                         # offline: 99/99 routing + unit tests (no backend calls)
-MMT_LIVE=1 npm test              # + live agy + codex smoke tests (network required)
 ```
 
 Keep the suite green. Add cases for any routing or behavior change. Tests live in `test/*.test.mjs`
-and run with `node --test`.
+and run with `node --test`. The suite is fully offline — there is no `MMT_LIVE` live-test gate; verify
+agy/codex behaviour by hand against the installed CLIs.
 
 ---
 

PROBES.md

@@ -1,7 +1,16 @@
 # Grounded probe findings — agy v1.0.8 (Windows)
 
+> **Historical capture — read with the SUPERSEDED notes.** This file records the raw probe results
+> from the original **bash** implementation (2026-06-13/14): the actual CLI bytes, flags, the
+> `isatty` discovery, and the model list — all still factually true about the CLIs. But the *plugin's
+> implementation* has since moved to **Node ESM** with **node-pty/ConPTY** (not winpty) and a
+> **stdin-delivered** codex prompt. Where a section describes the old bash/winpty mechanism, a
+> **SUPERSEDED** note points to the live code (`src/lib/backends.mjs`); `backends.sh`, `route.sh`,
+> `run.sh`, and the python/jq tooling referenced below were all deleted in the rewrite. `CLAUDE.md`
+> is the current source of truth for the implementation.
+
 Captured 2026-06-13 against the real `agy` CLI. These resolve the plan's open probes
-P1/P2 and the non-obvious headless behavior. Source of truth for `backends.sh` / `clean()`.
+P1/P2 and the non-obvious headless behavior.
 
 ## Binary
 - Path: `C:\Users\WatchAndyTW\AppData\Local\agy\bin\agy.exe`
@@ -13,12 +22,21 @@ P1/P2 and the non-obvious headless behavior. Source of truth for `backends.sh` /
   Subcommands: `models`, `update`, `install`, `plugin`/`plugins`, `changelog`, `help`.
   **No `--output-format`** — text output only (matches plan).
 
-## THE KEY FINDING — agy needs a TTY (use winpty)
+## THE KEY FINDING — agy needs a TTY
 `agy` gates its output on `isatty(stdout)`. When invoked through a normal pipe
 (Claude Code Bash/PowerShell tool, hook runner, subagent shell) it **exits 0 and prints
-NOTHING**. It only produces output when attached to a real console.
+NOTHING**. It only produces output when attached to a real console. *(This finding is still true
+and is the whole reason the agy lane needs a pseudo-terminal.)*
+
+> **SUPERSEDED — the live fix is node-pty/ConPTY, not winpty.** The plugin now runs agy under a real
+> pseudo-terminal via **node-pty** (`backends.mjs runPty`): **ConPTY** on Windows, **forkpty** on
+> POSIX — so `isatty(stdout)` is true with **no visible console**, working from a fully headless
+> parent. winpty could NOT allocate a console with non-zero dims from a console-less parent (the
+> `winpty.cc:924` assertion below), so it was dropped from the agy path; `platform.ptyWrap` (winpty/
+> `script`) survives only as the **POSIX-without-node-pty** fallback. The winpty recipe below is the
+> historical bash approach, kept for the byte-level findings — not the current mechanism.
 
-Fix: wrap every invocation in **winpty** (`/usr/bin/winpty`, present on this msys/git-bash):
+Historical bash fix (superseded): wrap every invocation in **winpty** (`/usr/bin/winpty`):
 
 ```
 winpty -Xallow-non-tty -Xplain <agy.exe> --print "<prompt>" --model "<name>" \
@@ -39,8 +57,10 @@ With the recipe above, `agy -p "Say exactly: HELLO"`:
   appears AFTER output, does **not** change the exit code (still 0 on success).
 - **exit**: 0 on success.
 
-=> `clean()`: take stdout only, strip `\r`, trim trailing newline/whitespace.
-   Defensive: also drop any line matching winpty's `Assertion failed:.*winpty\.cc`.
+=> `clean()` (now `backends.mjs clean()`): take stdout only, strip `\r` + ANSI/CSI/OSC, trim trailing
+   whitespace. *(The winpty `Assertion failed:.*winpty\.cc` line filter still exists in `clean()` for
+   the POSIX winpty fallback, but is dead on the primary node-pty/ConPTY path — ConPTY emits no such
+   assertion.)*
 => HUD token totals are **char estimates** (no usage emitted) — label them `~`.
 
 ### `--model` argument format (RESOLVED)
@@ -65,11 +85,17 @@ Not yet hit a real limit. Shipping default `quota_patterns`; will harden on firs
 exhaustion. winpty's assertion line is NOT a quota pattern, so no false positive.
 
 ## Tooling on this machine (bash/msys)
-- `jq`: **missing** -> statusline parses state.json with pure bash/sed (no jq dep).
-- `python3`: 3.12.12 (stdlib `json`) -> used by `route.sh`/`run.sh` to parse `roster.json`.
-- `winpty`, `timeout`, `sed`, `grep`, `awk`, `perl`: present.
-- agy is **not** on bash PATH in this session (added after Claude Code started); scripts
-  resolve the binary themselves (env override -> `command -v` -> `$LOCALAPPDATA` path).
+> **SUPERSEDED.** This captured the *bash-era* tool deps. The plugin is now **Node ESM with one
+> native dep (`node-pty`)** — no `jq`, no `python3`, no `route.sh`/`run.sh`. `roster.json` is parsed
+> by `JSON.parse` (`src/lib/config.mjs`); the statusline parses `state.json` line-by-line in Node
+> (`statusline/statusline.mjs`); routing/execution are `src/bin/route.mjs` / `src/bin/run.mjs`.
+
+- `jq`: **missing** -> (bash era) statusline parsed state.json with pure bash/sed. *(Now: Node, no jq.)*
+- `python3`: 3.12.12 -> (bash era) `route.sh`/`run.sh` parsed `roster.json` with it. *(Now: `JSON.parse`; those scripts are deleted.)*
+- `winpty`, `timeout`, `sed`, `grep`, `awk`, `perl`: present. *(Now off the hot path — only the POSIX winpty/`script` fallback remains.)*
+- agy is **not** on bash PATH in this session (added after Claude Code started); the binary is
+  resolved by the plugin itself (env override -> PATH scan -> `$LOCALAPPDATA` path) — still true
+  (`platform.resolveBinary`).
 
 ---
 
@@ -81,10 +107,14 @@ section above; contrasts noted explicitly.
 ## Binary
 - Path: `~/AppData/Roaming/npm/codex` (on PATH; resolved via `command -v codex`).
 - Version: `codex --version` -> `codex-cli 0.139.0`. Not TTY-gated — runs fine headless.
-- Non-interactive entrypoint: **`codex exec [OPTIONS] [PROMPT]`** (alias `codex e`).
-  The prompt rides as the positional arg. If stdin is piped AND a prompt arg is given,
-  codex appends stdin as a `<stdin>` block — so invoke with stdin = `/dev/null` (or
-  the equivalent held-closed) to avoid spurious context injection.
+- Non-interactive entrypoint: **`codex exec [OPTIONS] [PROMPT]`** (alias `codex e`). codex also
+  reads the prompt from **stdin** via the `-` sentinel: `codex exec … -`.
+  > **SUPERSEDED — the live invoker delivers the prompt on STDIN, not as a positional arg.**
+  > `backends.mjs invokeCodex` builds `codex exec … -` and writes the prompt to stdin. This was a
+  > deliberate fix: on Windows codex is a `.cmd` shim spawned via `cmd.exe`, which **truncates a
+  > multi-line prompt at the first newline** (and expands `%VAR%`) when it rides as an argv element.
+  > stdin sidesteps both. The "prompt as positional arg + stdin=`/dev/null`" recipe below is the
+  > historical pre-fix approach.
 
 ## THE KEY DIFFERENCE vs agy — no winpty, no TTY gating
 
@@ -117,16 +147,21 @@ No `winpty`, no open-stdin FIFO, no output-scrubbing gymnastics required.
 | `-m <MODEL>` | Model selector (omitted → codex's own `config.toml` default). |
 | `--add-dir <DIR>` | Extra readable directory to expose. |
 
-`--dangerously-bypass-approvals-and-sandbox` exists but is NOT used — `read-only` is
-safer for relay use.
+`--dangerously-bypass-approvals-and-sandbox` is the read-only DEFAULT's opposite: it is **used** by
+the `/team --writable` lane (`roster.json` codex `writable_extra`) so codex can write files + run
+commands in its worktree (full-auto). The default `extra` keeps `-s read-only` for the safe text-relay
+path. *(Original note said this flag was "not used" — true in the read-only-only era, now stale.)*
 
 ## Health check
 
 `codex --version` (not `codex exec`) prints the version line to stdout, exit 0.
-Not TTY-gated. Suitable for a fast health gate in `backends.sh`.
+Not TTY-gated. Suitable for a fast health gate — now in `backends.mjs health()` (was `backends.sh`).
 
 ## Invocation recipe
 
+> **SUPERSEDED** — the live invoker is `backends.mjs invokeCodex` (prompt on stdin via `-`; writable
+> mode swaps the sandbox flags). Historical read-only recipe (positional prompt + `/dev/null`):
+
 ```bash
 codex exec \
   -s read-only \

README.md

@@ -90,11 +90,13 @@ work runs across parallel agents — never one inline session.
 - **writable (`--writable`):** each subtask gets its **own git worktree + branch** off your current
   `HEAD`; the assigned agent makes **real file changes** there (CLI backends run **full-auto** in the
   worktree). The orchestrator then **merges every subtask branch into one integration branch
-  `mmt/team-<slug>`** (off `HEAD`), **reports any merge conflicts** instead of guessing at them, and
-  leaves that branch for you. **Your current branch is never touched** (no auto-merge) and **no
-  GitHub PR is created** — you inspect / merge / open a PR for the integration branch yourself
-  (`git log mmt/team-<slug>`). Per-subtask worktrees live under `.mmt/worktrees/` (gitignored);
-  conflicted ones are kept so you can resolve them. The full-auto sandbox per backend is tunable via
+  `mmt/team-<slug>`** (off `HEAD`) and **resolves any merge conflicts itself** — reading both sides and
+  editing to a correct combined result, then completing the merge — so you get **one finished,
+  conflict-free branch**, not a pile of worktrees to reconcile. **Your current branch is never touched**
+  (no auto-merge onto it) and **no GitHub PR is created** — you merge / open a PR for the integration
+  branch when ready (`git log mmt/team-<slug>`). Only a conflict the orchestrator genuinely can't
+  reconcile is left for you (reported as `unresolved`, its worktree kept). Per-subtask worktrees live
+  under `.mmt/worktrees/` (gitignored). The full-auto sandbox per backend is tunable via
   `writable_extra` in `roster.json`. Enable per-invocation with `--writable`, or set
   `team.mode: "writable"` in the roster.
 
@@ -271,6 +273,7 @@ src/lib/team-spec.mjs        /team cap-spec parser
 src/lib/team-plan.mjs        plan.json → per-subtask files
 src/lib/reason-spec.mjs      /reasoning panel-spec parser
 src/lib/gen-agents.mjs       regenerate agents/*.md from the roster
+src/lib/validate-config.mjs  roster.json validator (route names, tiers, backends, agents)
 src/bin/route.mjs            task → decision JSON CLI
 src/bin/run.mjs              executor + fallback chain + HUD state (file relay transport: --call-file)
 src/bin/team.mjs             scripted CLI fan-out for /team
@@ -287,6 +290,7 @@ workflows/reasoning.mjs      Ultracode Fusion workflow: Panel → Judge → Synt
 test/*.test.mjs              offline test suite
 docs/PLAN.md                 original implementation plan (historical)
 docs/REASONING.md            design contract for the /reasoning Fusion pipeline
+docs/INTERFACES.md           module interface contract (Node ESM port signatures)
 ```
 
 ---
@@ -295,9 +299,11 @@ docs/REASONING.md            design contract for the /reasoning Fusion pipeline
 
 ```bash
 npm test                # offline: 99/99 routing + unit tests (no backend calls)
-MMT_LIVE=1 npm test     # also run live agy + codex smoke tests (network required)
 ```
 
+The suite is fully offline — no backend calls. Live agy/codex behaviour is verified by hand (run a
+real `node src/bin/run.mjs --call-file=…` against the installed CLIs), not by a `npm test` gate.
+
 > **Why Node ESM?** The original bash hooks forked ~6–7 processes per invocation under a 10 s msys
 > timeout and were intermittently killed ("hooks not triggering sometimes"). Each hook is now **one
 > fork-free Node process** — read payload, gate with real `JSON.parse`, route in-process, emit.

commands/team.md

@@ -63,9 +63,11 @@ otherwise **read-only mode** (the default).
 - **writable (`--writable`):** each subtask gets its **own git worktree + branch** off the current HEAD;
   the assigned agent (CLI **full-auto** via `run.mjs --cwd <worktree> --writable`, or a native solver
   writing in the worktree) makes **real file changes** there; then the orchestrator **merges every
-  subtask branch into one integration branch `mmt/team-<slug>`** off HEAD, **reports conflicts** (never
-  blind-resolves them), and leaves that branch for you. Your current branch is **untouched** (no
-  auto-merge), and **no GitHub PR is created** — you inspect/merge/PR the integration branch yourself.
+  subtask branch into one integration branch `mmt/team-<slug>`** off HEAD and **resolves any merge
+  conflicts itself** (reading both sides, editing to a correct combined result, completing the merge) —
+  so you get **one finished, conflict-free branch**, not a pile of worktrees. (Only a conflict it
+  genuinely can't reconcile is left `unresolved` for you.) Your current branch is **untouched** (no
+  auto-merge onto it), and **no GitHub PR is created** — you merge/PR the integration branch when ready.
 
 In the Ultracode path, pass `writable: true` in the Workflow args for writable mode (the workflow runs
 the Setup → Dispatch → Integrate stages). In the Task-agent path, follow the writable steps marked
@@ -265,9 +267,10 @@ override (`verifier`, `caps`, `verify`, `maxFixLoops`). With no `teamConfig`, th
 apply (all three backends eligible; codex verify). Read its returned `{ plan, mode, backends, caps,
 counts:{byBackend,…}, verifier, writable, results, final }` and present `final`, noting `counts.failed`
 if non-zero. **In writable mode** (`mode:"writable"`), also surface `writable.integration_branch` and
-`writable.integration` — tell the user the changes are on that branch (their current branch is
-untouched), list any `writable.integration.conflicts` that still need manual resolution, and how to
-inspect it (`git switch <integration_branch>` / `git log <integration_branch>`). (`args.task` is passed
+`writable.integration` — tell the user the changes are on that **finished, conflict-free** branch (their
+current branch is untouched), note any `writable.integration.resolved` conflicts the orchestrator
+reconciled (so they can review the resolution) and flag any `writable.integration.unresolved` ones that
+still need their hand, and how to inspect it (`git log <integration_branch>`). (`args.task` is passed
 as a JSON value, not shell — injection-safe.)
 
 A trivial single task needs no fan-out: one subtask reduces this to a plain verified dispatch.