nodmix 2026.5.25

package/docs/help/gpt55-codex-agentic-parity-maintainers.md

@@ -0,0 +1,196 @@
+---
+summary: "How to review the GPT-5.5 / Codex parity program as four merge units"
+title: "GPT-5.5 / Codex parity maintainer notes"
+read_when:
+  - Reviewing the GPT-5.5 / Codex parity PR series
+  - Maintaining the six-contract agentic architecture behind the parity program
+---
+
+This note explains how to review the GPT-5.5 / Codex parity program as four merge units without losing the original six-contract architecture.
+
+## Merge units
+
+### PR A: strict-agentic execution
+
+Owns:
+
+- `executionContract`
+- GPT-5-first same-turn follow-through
+- `update_plan` as non-terminal progress tracking
+- explicit blocked states instead of plan-only silent stops
+
+Does not own:
+
+- auth/runtime failure classification
+- permission truthfulness
+- replay/continuation redesign
+- parity benchmarking
+
+### PR B: runtime truthfulness
+
+Owns:
+
+- Codex OAuth scope correctness
+- typed provider/runtime failure classification
+- truthful `/elevated full` availability and blocked reasons
+
+Does not own:
+
+- tool schema normalization
+- replay/liveness state
+- benchmark gating
+
+### PR C: execution correctness
+
+Owns:
+
+- provider-owned OpenAI/Codex tool compatibility
+- parameter-free strict schema handling
+- replay-invalid surfacing
+- paused, blocked, and abandoned long-task state visibility
+
+Does not own:
+
+- self-elected continuation
+- generic Codex dialect behavior outside provider hooks
+- benchmark gating
+
+### PR D: parity harness
+
+Owns:
+
+- first-wave GPT-5.5 vs Opus 4.7 scenario pack
+- parity documentation
+- parity report and release-gate mechanics
+
+Does not own:
+
+- runtime behavior changes outside QA-lab
+- auth/proxy/DNS simulation inside the harness
+
+## Mapping back to the original six contracts
+
+| Original contract                        | Merge unit |
+| ---------------------------------------- | ---------- |
+| Provider transport/auth correctness      | PR B       |
+| Tool contract/schema compatibility       | PR C       |
+| Same-turn execution                      | PR A       |
+| Permission truthfulness                  | PR B       |
+| Replay/continuation/liveness correctness | PR C       |
+| Benchmark/release gate                   | PR D       |
+
+## Review order
+
+1. PR A
+2. PR B
+3. PR C
+4. PR D
+
+PR D is the proof layer. It should not be the reason runtime-correctness PRs are delayed.
+
+## What to look for
+
+### PR A
+
+- GPT-5 runs act or fail closed instead of stopping at commentary
+- `update_plan` no longer looks like progress by itself
+- behavior stays GPT-5-first and embedded-Pi scoped
+
+### PR B
+
+- auth/proxy/runtime failures stop collapsing into generic "model failed" handling
+- `/elevated full` is only described as available when it is actually available
+- blocked reasons are visible to both the model and the user-facing runtime
+
+### PR C
+
+- strict OpenAI/Codex tool registration behaves predictably
+- parameter-free tools do not fail strict schema checks
+- replay and compaction outcomes preserve truthful liveness state
+
+### PR D
+
+- the scenario pack is understandable and reproducible
+- the pack includes a mutating replay-safety lane, not only read-only flows
+- reports are readable by humans and automation
+- parity claims are evidence-backed, not anecdotal
+
+Expected artifacts from PR D:
+
+- `qa-suite-report.md` / `qa-suite-summary.json` for each model run
+- `qa-agentic-parity-report.md` with aggregate and scenario-level comparison
+- `qa-agentic-parity-summary.json` with a machine-readable verdict
+
+## Release gate
+
+Do not claim GPT-5.5 parity or superiority over Opus 4.7 until:
+
+- PR A, PR B, and PR C are merged
+- PR D runs the first-wave parity pack cleanly
+- runtime-truthfulness regression suites remain green
+- the parity report shows no fake-success cases and no regression in stop behavior
+
+```mermaid
+flowchart LR
+    A["PR A-C merged"] --> B["Run GPT-5.5 parity pack"]
+    A --> C["Run Opus 4.7 parity pack"]
+    B --> D["qa-suite-summary.json"]
+    C --> E["qa-suite-summary.json"]
+    D --> F["qa parity-report"]
+    E --> F
+    F --> G["Markdown report + JSON verdict"]
+    G --> H{"Pass?"}
+    H -- "yes" --> I["Parity claim allowed"]
+    H -- "no" --> J["Keep runtime fixes / review loop open"]
+```
+
+The parity harness is not the only evidence source. Keep this split explicit in review:
+
+- PR D owns the scenario-based GPT-5.5 vs Opus 4.7 comparison
+- PR B deterministic suites still own auth/proxy/DNS and full-access truthfulness evidence
+
+## Quick maintainer merge workflow
+
+Use this when you are ready to land a parity PR and want a repeatable, low-risk sequence.
+
+1. Confirm evidence bar is met before merge:
+   - reproducible symptom or failing test
+   - verified root cause in touched code
+   - fix in the implicated path
+   - regression test or explicit manual verification note
+2. Triage/label before merge:
+   - apply any `r:*` auto-close labels when the PR should not land
+   - keep merge candidates free of unresolved blocker threads
+3. Validate locally on the touched surface:
+   - `pnpm check:changed`
+   - `pnpm test:changed` when tests changed or bug-fix confidence depends on test coverage
+4. Land with the standard maintainer flow (`/landpr` process), then verify:
+   - linked issues auto-close behavior
+   - CI and post-merge status on `main`
+5. After landing, run duplicate search for related open PRs/issues and close only with a canonical reference.
+
+If any one of the evidence bar items is missing, request changes instead of merging.
+
+## Goal-to-evidence map
+
+| Completion gate item                     | Primary owner | Review artifact                                                     |
+| ---------------------------------------- | ------------- | ------------------------------------------------------------------- |
+| No plan-only stalls                      | PR A          | strict-agentic runtime tests and `approval-turn-tool-followthrough` |
+| No fake progress or fake tool completion | PR A + PR D   | parity fake-success count plus scenario-level report details        |
+| No false `/elevated full` guidance       | PR B          | deterministic runtime-truthfulness suites                           |
+| Replay/liveness failures remain explicit | PR C + PR D   | lifecycle/replay suites plus `compaction-retry-mutating-tool`       |
+| GPT-5.5 matches or beats Opus 4.7        | PR D          | `qa-agentic-parity-report.md` and `qa-agentic-parity-summary.json`  |
+
+## Reviewer shorthand: before vs after
+
+| User-visible problem before                                 | Review signal after                                                                     |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| GPT-5.5 stopped after planning                              | PR A shows act-or-block behavior instead of commentary-only completion                  |
+| Tool use felt brittle with strict OpenAI/Codex schemas      | PR C keeps tool registration and parameter-free invocation predictable                  |
+| `/elevated full` hints were sometimes misleading            | PR B ties guidance to actual runtime capability and blocked reasons                     |
+| Long tasks could disappear into replay/compaction ambiguity | PR C emits explicit paused, blocked, abandoned, and replay-invalid state                |
+| Parity claims were anecdotal                                | PR D produces a report plus JSON verdict with the same scenario coverage on both models |
+
+## Related
+
+- [GPT-5.5 / Codex agentic parity](/help/gpt55-codex-agentic-parity)

package/docs/help/gpt55-codex-agentic-parity.md

@@ -0,0 +1,230 @@
+---
+summary: "How Nodmix closes agentic execution gaps for GPT-5.5 and Codex-style models"
+title: "GPT-5.5 / Codex agentic parity"
+read_when:
+  - Debugging GPT-5.5 or Codex agent behavior
+  - Comparing Nodmix agentic behavior across frontier models
+  - Reviewing the strict-agentic, tool-schema, elevation, and replay fixes
+---
+
+Nodmix already worked well with tool-using frontier models, but GPT-5.5 and Codex-style models were still underperforming in a few practical ways:
+
+- they could stop after planning instead of doing the work
+- they could use strict OpenAI/Codex tool schemas incorrectly
+- they could ask for `/elevated full` even when full access was impossible
+- they could lose long-running task state during replay or compaction
+- parity claims against Claude Opus 4.7 were based on anecdotes instead of repeatable scenarios
+
+This parity program fixes those gaps in four reviewable slices.
+
+## What changed
+
+### PR A: strict-agentic execution
+
+This slice adds an opt-in `strict-agentic` execution contract for embedded Pi GPT-5 runs.
+
+When enabled, Nodmix stops accepting plan-only turns as "good enough" completion. If the model only says what it intends to do and does not actually use tools or make progress, Nodmix retries with an act-now steer and then fails closed with an explicit blocked state instead of silently ending the task.
+
+This improves the GPT-5.5 experience most on:
+
+- short "ok do it" follow-ups
+- code tasks where the first step is obvious
+- flows where `update_plan` should be progress tracking rather than filler text
+
+### PR B: runtime truthfulness
+
+This slice makes Nodmix tell the truth about two things:
+
+- why the provider/runtime call failed
+- whether `/elevated full` is actually available
+
+That means GPT-5.5 gets better runtime signals for missing scope, auth refresh failures, HTML 403 auth failures, proxy issues, DNS or timeout failures, and blocked full-access modes. The model is less likely to hallucinate the wrong remediation or keep asking for a permission mode the runtime cannot provide.
+
+### PR C: execution correctness
+
+This slice improves two kinds of correctness:
+
+- provider-owned OpenAI/Codex tool-schema compatibility
+- replay and long-task liveness surfacing
+
+The tool-compat work reduces schema friction for strict OpenAI/Codex tool registration, especially around parameter-free tools and strict object-root expectations. The replay/liveness work makes long-running tasks more observable, so paused, blocked, and abandoned states are visible instead of disappearing into generic failure text.
+
+### PR D: parity harness
+
+This slice adds the first-wave QA-lab parity pack so GPT-5.5 and Opus 4.7 can be exercised through the same scenarios and compared using shared evidence.
+
+The parity pack is the proof layer. It does not change runtime behavior by itself.
+
+After you have two `qa-suite-summary.json` artifacts, generate the release-gate comparison with:
+
+```bash
+pnpm nodmix qa parity-report \
+  --repo-root . \
+  --candidate-summary .artifacts/qa-e2e/openai-candidate/qa-suite-summary.json \
+  --baseline-summary .artifacts/qa-e2e/anthropic-baseline/qa-suite-summary.json \
+  --output-dir .artifacts/qa-e2e/parity
+```
+
+That command writes:
+
+- a human-readable Markdown report
+- a machine-readable JSON verdict
+- an explicit `pass` / `fail` gate result
+
+## Why this improves GPT-5.5 in practice
+
+Before this work, GPT-5.5 on Nodmix could feel less agentic than Opus in real coding sessions because the runtime tolerated behaviors that are especially harmful for GPT-5-style models:
+
+- commentary-only turns
+- schema friction around tools
+- vague permission feedback
+- silent replay or compaction breakage
+
+The goal is not to make GPT-5.5 imitate Opus. The goal is to give GPT-5.5 a runtime contract that rewards real progress, supplies cleaner tool and permission semantics, and turns failure modes into explicit machine- and human-readable states.
+
+That changes the user experience from:
+
+- "the model had a good plan but stopped"
+
+to:
+
+- "the model either acted, or Nodmix surfaced the exact reason it could not"
+
+## Before vs after for GPT-5.5 users
+
+| Before this program                                                                            | After PR A-D                                                                             |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| GPT-5.5 could stop after a reasonable plan without taking the next tool step                   | PR A turns "plan only" into "act now or surface a blocked state"                         |
+| Strict tool schemas could reject parameter-free or OpenAI/Codex-shaped tools in confusing ways | PR C makes provider-owned tool registration and invocation more predictable              |
+| `/elevated full` guidance could be vague or wrong in blocked runtimes                          | PR B gives GPT-5.5 and the user truthful runtime and permission hints                    |
+| Replay or compaction failures could feel like the task silently disappeared                    | PR C surfaces paused, blocked, abandoned, and replay-invalid outcomes explicitly         |
+| "GPT-5.5 feels worse than Opus" was mostly anecdotal                                           | PR D turns that into the same scenario pack, the same metrics, and a hard pass/fail gate |
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A["User request"] --> B["Embedded Pi runtime"]
+    B --> C["Strict-agentic execution contract"]
+    B --> D["Provider-owned tool compatibility"]
+    B --> E["Runtime truthfulness"]
+    B --> F["Replay and liveness state"]
+    C --> G["Tool call or explicit blocked state"]
+    D --> G
+    E --> G
+    F --> G
+    G --> H["QA-lab parity pack"]
+    H --> I["Scenario report and parity gate"]
+```
+
+## Release flow
+
+```mermaid
+flowchart LR
+    A["Merged runtime slices (PR A-C)"] --> B["Run GPT-5.5 parity pack"]
+    A --> C["Run Opus 4.7 parity pack"]
+    B --> D["qa-suite-summary.json"]
+    C --> E["qa-suite-summary.json"]
+    D --> F["nodmix qa parity-report"]
+    E --> F
+    F --> G["qa-agentic-parity-report.md"]
+    F --> H["qa-agentic-parity-summary.json"]
+    H --> I{"Gate pass?"}
+    I -- "yes" --> J["Evidence-backed parity claim"]
+    I -- "no" --> K["Keep runtime/review loop open"]
+```
+
+## Scenario pack
+
+The first-wave parity pack currently covers five scenarios:
+
+### `approval-turn-tool-followthrough`
+
+Checks that the model does not stop at "I'll do that" after a short approval. It should take the first concrete action in the same turn.
+
+### `model-switch-tool-continuity`
+
+Checks that tool-using work remains coherent across model/runtime switching boundaries instead of resetting into commentary or losing execution context.
+
+### `source-docs-discovery-report`
+
+Checks that the model can read source and docs, synthesize findings, and continue the task agentically rather than producing a thin summary and stopping early.
+
+### `image-understanding-attachment`
+
+Checks that mixed-mode tasks involving attachments remain actionable and do not collapse into vague narration.
+
+### `compaction-retry-mutating-tool`
+
+Checks that a task with a real mutating write keeps replay-unsafety explicit instead of quietly looking replay-safe if the run compacts, retries, or loses reply state under pressure.
+
+## Scenario matrix
+
+| Scenario                           | What it tests                           | Good GPT-5.5 behavior                                                          | Failure signal                                                                 |
+| ---------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `approval-turn-tool-followthrough` | Short approval turns after a plan       | Starts the first concrete tool action immediately instead of restating intent  | plan-only follow-up, no tool activity, or blocked turn without a real blocker  |
+| `model-switch-tool-continuity`     | Runtime/model switching under tool use  | Preserves task context and continues acting coherently                         | resets into commentary, loses tool context, or stops after switch              |
+| `source-docs-discovery-report`     | Source reading + synthesis + action     | Finds sources, uses tools, and produces a useful report without stalling       | thin summary, missing tool work, or incomplete-turn stop                       |
+| `image-understanding-attachment`   | Attachment-driven agentic work          | Interprets the attachment, connects it to tools, and continues the task        | vague narration, attachment ignored, or no concrete next action                |
+| `compaction-retry-mutating-tool`   | Mutating work under compaction pressure | Performs a real write and keeps replay-unsafety explicit after the side effect | mutating write happens but replay safety is implied, missing, or contradictory |
+
+## Release gate
+
+GPT-5.5 can only be considered at parity or better when the merged runtime passes the parity pack and the runtime-truthfulness regressions at the same time.
+
+Required outcomes:
+
+- no plan-only stall when the next tool action is clear
+- no fake completion without real execution
+- no incorrect `/elevated full` guidance
+- no silent replay or compaction abandonment
+- parity-pack metrics that are at least as strong as the agreed Opus 4.7 baseline
+
+For the first-wave harness, the gate compares:
+
+- completion rate
+- unintended-stop rate
+- valid-tool-call rate
+- fake-success count
+
+Parity evidence is intentionally split across two layers:
+
+- PR D proves same-scenario GPT-5.5 vs Opus 4.7 behavior with QA-lab
+- PR B deterministic suites prove auth, proxy, DNS, and `/elevated full` truthfulness outside the harness
+
+## Goal-to-evidence matrix
+
+| Completion gate item                                     | Owning PR   | Evidence source                                                    | Pass signal                                                                              |
+| -------------------------------------------------------- | ----------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| GPT-5.5 no longer stalls after planning                  | PR A        | `approval-turn-tool-followthrough` plus PR A runtime suites        | approval turns trigger real work or an explicit blocked state                            |
+| GPT-5.5 no longer fakes progress or fake tool completion | PR A + PR D | parity report scenario outcomes and fake-success count             | no suspicious pass results and no commentary-only completion                             |
+| GPT-5.5 no longer gives false `/elevated full` guidance  | PR B        | deterministic truthfulness suites                                  | blocked reasons and full-access hints stay runtime-accurate                              |
+| Replay/liveness failures stay explicit                   | PR C + PR D | PR C lifecycle/replay suites plus `compaction-retry-mutating-tool` | mutating work keeps replay-unsafety explicit instead of silently disappearing            |
+| GPT-5.5 matches or beats Opus 4.7 on the agreed metrics  | PR D        | `qa-agentic-parity-report.md` and `qa-agentic-parity-summary.json` | same scenario coverage and no regression on completion, stop behavior, or valid tool use |
+
+## How to read the parity verdict
+
+Use the verdict in `qa-agentic-parity-summary.json` as the final machine-readable decision for the first-wave parity pack.
+
+- `pass` means GPT-5.5 covered the same scenarios as Opus 4.7 and did not regress on the agreed aggregate metrics.
+- `fail` means at least one hard gate tripped: weaker completion, worse unintended stops, weaker valid tool use, any fake-success case, or mismatched scenario coverage.
+- "shared/base CI issue" is not itself a parity result. If CI noise outside PR D blocks a run, the verdict should wait for a clean merged-runtime execution instead of being inferred from branch-era logs.
+- Auth, proxy, DNS, and `/elevated full` truthfulness still come from PR B's deterministic suites, so the final release claim needs both: a passing PR D parity verdict and green PR B truthfulness coverage.
+
+## Who should enable `strict-agentic`
+
+Use `strict-agentic` when:
+
+- the agent is expected to act immediately when a next step is obvious
+- GPT-5.5 or Codex-family models are the primary runtime
+- you prefer explicit blocked states over "helpful" recap-only replies
+
+Keep the default contract when:
+
+- you want the existing looser behavior
+- you are not using GPT-5-family models
+- you are testing prompts rather than runtime enforcement
+
+## Related
+
+- [GPT-5.5 / Codex parity maintainer notes](/help/gpt55-codex-agentic-parity-maintainers)

package/docs/help/index.md

@@ -0,0 +1,39 @@
+---
+summary: "Help hub: common fixes, install sanity, and where to look when something breaks"
+read_when:
+  - You are new and want a "what do I click/run" guide
+  - Something broke and you want the fastest path to a fix
+title: "Help"
+---
+
+Quick "get unstuck" path for the most common problems:
+
+- [Troubleshooting](/help/troubleshooting) - symptom-first decision tree
+- [Debugging](/help/debugging) - watch mode, raw streams, dev profile
+- [Install sanity](/install/node#troubleshooting) - Node / npm / PATH checks
+- [Gateway troubleshooting](/gateway/troubleshooting) - gateway-specific issues
+- [Doctor](/gateway/doctor) - automated repair + diagnostic bundle
+
+## FAQ
+
+- [FAQ](/help/faq) - day-to-day concepts and operational questions
+- [First-run FAQ](/help/faq-first-run) - install, onboard, auth, subscriptions, early failures
+- [Models FAQ](/help/faq-models) - model selection, failover, auth profiles
+
+## Diagnostics
+
+- [Environment variables](/help/environment) - where Nodmix loads env vars and precedence
+- [Diagnostics flags](/diagnostics/flags) - runtime diagnostics and verbose modes
+- [Node + tsx crash](/debug/node-issue) - specific Node / tsx runtime crash scenarios
+
+## Testing
+
+- [Testing](/help/testing) - test suites and Docker runners
+- [Update and plugin tests](/help/testing-updates-plugins) - package update, migration, and plugin install validation
+- [Live tests](/help/testing-live) - network-touching provider and CLI smokes
+
+## Community and meta
+
+- [Nodmix lore](/start/lore) - the story
+- [Docs hubs](/start/hubs) - how this documentation is organized
+- [Docs directory](/start/docs-directory) - full file map

package/docs/help/scripts.md

@@ -0,0 +1,56 @@
+---
+summary: "Repository scripts: purpose, scope, and safety notes"
+read_when:
+  - Running scripts from the repo
+  - Adding or changing scripts under ./scripts
+title: "Scripts"
+---
+
+The `scripts/` directory contains helper scripts for local workflows and ops tasks.
+Use these when a task is clearly tied to a script; otherwise prefer the CLI.
+
+## Conventions
+
+- Scripts are **optional** unless referenced in docs or release checklists.
+- Prefer CLI surfaces when they exist (example: auth monitoring uses `nodmix models status --check`).
+- Assume scripts are host-specific; read them before running on a new machine.
+
+## Auth monitoring scripts
+
+Auth monitoring is covered in [Authentication](/gateway/authentication). The scripts under `scripts/` are optional extras for systemd/Termux phone workflows.
+
+## GitHub read helper
+
+Use `scripts/gh-read` when you want `gh` to use a GitHub App installation token for repo-scoped read calls while leaving normal `gh` on your personal login for write actions.
+
+Required env:
+
+- `NODMIX_GH_READ_APP_ID`
+- `NODMIX_GH_READ_PRIVATE_KEY_FILE`
+
+Optional env:
+
+- `NODMIX_GH_READ_INSTALLATION_ID` when you want to skip repo-based installation lookup
+- `NODMIX_GH_READ_PERMISSIONS` as a comma-separated override for the read permission subset to request
+
+Repo resolution order:
+
+- `gh ... -R owner/repo`
+- `GH_REPO`
+- `git remote origin`
+
+Examples:
+
+- `scripts/gh-read pr view 123`
+- `scripts/gh-read run list -R nodmix/nodmix`
+- `scripts/gh-read api repos/nodmix/nodmix/pulls/123`
+
+## When adding scripts
+
+- Keep scripts focused and documented.
+- Add a short entry in the relevant doc (or create one if missing).
+
+## Related
+
+- [Testing](/help/testing)
+- [Testing live](/help/testing-live)