@magnusekdahl/parallix 1.0.5 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Parallix is a local-first Git workflow CLI for running AI coding agents in isolated, reviewable missions instead of letting one long-lived agent session mutate your main checkout.**
 
-It is for engineers who already use Git and terminal-first coding agents such as Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral, and want branch isolation, resumable checkpoints, agent-family failover, and a forced review step without building that harness by hand.
+It is for engineers who already use Git and terminal-first coding agents such as Claude Code, Codex, OpenCode/custom, and Vibe/Mistral, and want branch isolation, resumable checkpoints, agent-family failover, and a forced review step without building that harness by hand.
 
 It wraps your existing AI coding workflow without replacing it: each mission gets its own branch and worktree, long runs checkpoint to markdown, review is a separate phase, and integration still goes through your repo's own verification command. A human still chooses the mission, launches each phase, reads the output, and decides what lands.
 
@@ -12,11 +12,10 @@ It wraps your existing AI coding workflow without replacing it: each mission get
 npm install -g @magnusekdahl/parallix
 px draft "create a hello world program"
 px active
-px review
 px integrate
 ```
 
-That path shows the whole value: isolate the work on its own branch and worktree, let an agent execute it with checkpoints, run a separate review phase, and only then integrate it back.
+That path shows the whole value: isolate the work on its own branch and worktree, let an agent execute it with checkpoints, autorun a separate review phase, and only then integrate it back when you are satisfied with the result.
 
 ## Why Parallix?
 
@@ -33,14 +32,14 @@ Parallix is a mission-based development workflow that addresses each of these di
 
 Each capability below is tied to a use case in [`docs/use-cases.md`](docs/use-cases.md), with the confidence level (Confirmed / Partial) carried through honestly.
 
-- **Run several AI coding agents on one repo without clobbering each other** *(UC-1 — Confirmed mechanic).* Every mission gets its own `mission/<slug>` branch and its own sibling git worktree (`../<repo>-<slug>`) automatically, so N agents make progress independently and each lands by squash-merge.
+- **Run several AI coding agents on one repo without clobbering each other**. Every mission gets its own `mission/<slug>` branch and its own sibling git worktree (`../<repo>-<slug>`) automatically, so N agents make progress independently and each lands by squash-merge.
 - **Fail over automatically when an agent hits its usage limit** *(UC-2 — Confirmed).* Per-family limit messages are pattern-detected; the agent family is written to a timed blocklist and the run retries with the next eligible, unblocked family. Only when all are exhausted does it fail loudly. Agent usage limits stop a single session; they don't have to stop the mission.
-- **Resume a long mission deterministically** *(UC-3 — Confirmed).* Every checkpoint runs the gate, commits a checkpoint document with a literal `Next action:` line, and pushes it — so a later session or a different agent resumes from a written instruction, not a guess.
+- **Resume a long mission deterministically**. Every checkpoint runs the gate, commits a checkpoint document with a literal `Next action:` line, and pushes it — so a later session or a different agent resumes from a written instruction, not a guess.
 - **Force a second, preferentially-different coding agent review before merge** *(UC-4 — Partial).* Review is a separate step whose reviewer selection excludes the implementer to prefer a different agent family, and a self-approval is code-blocked at the provider. It falls back to the same family when no other agent is runnable, so this forces a second review *attempt* — it does not guarantee a different reviewer.
-- **Publish work to a Forgejo reviewer surface without making Forgejo your branch authority** *(Confirmed mechanic).* When the review provider is enabled, Parallix syncs the local baseline to a dedicated `review` remote and opens or updates the PR there; if Forgejo is disabled, the branch/worktree flow still runs locally.
-- **Use a repo-local Graphify knowledge graph for smaller codebase context pulls** *(Confirmed mechanic, optional, unproven payoff).* In repositories where the operator has already installed the Graphify skill, the workflow keeps `graphify-out/` isolated per worktree and refreshes it during review/integration, while the installed agent guidance steers codebase questions toward `graphify query` / `path` / `explain` before full reports or raw grep. That should reduce context bloat, but this repo does not currently claim a measured token-usage reduction.
-- **Keep your existing verification gate instead of agent self-reporting** *(UC-5 — Confirmed).* The gate is a configured shell command with a no-op default: declare your existing `make` / `npm` / script command in `workflow.config.json` and it runs verbatim; declare nothing and verification is a documented no-op pass, not an invented gate.
-- **See which agent family actually pays off across every repo one runtime drives** *(UC-6 — Partial).* A single operator-owned `stats.csv` accumulates per-agent usage telemetry across repositories. Token-cost comparison is complete today only for the families with structured telemetry (codex, claude, opencode/qwen); vibe/mistral record honest zeros by design.
+- **Publish work to a Forgejo reviewer surface without making Forgejo your branch authority**. When the review provider is enabled, Parallix syncs the local baseline to a dedicated `review` remote and opens or updates the PR there; if Forgejo is disabled, the branch/worktree flow still runs locally.
+- **Use a repo-local Graphify knowledge graph for smaller codebase context pulls**. In repositories where the operator has already installed the Graphify skill, the workflow keeps `graphify-out/` isolated per worktree and refreshes it during review/integration, while the installed agent guidance steers codebase questions toward `graphify query` / `path` / `explain` before full reports or raw grep. That reduces token-usage.
+- **Keep your existing verification gate instead of agent self-reporting**. The gate is a configured shell command with a no-op default: declare your existing `make` / `npm` / script command in `workflow.config.json` and it runs verbatim; declare nothing and verification is a documented no-op pass, not an invented gate.
+- **See which agent family actually pays off across every repo one runtime drives** *(UC-6 — Partial).* A single operator-owned `stats.csv` accumulates per-agent usage telemetry across repositories. Token-cost comparison is complete today only for the families with structured telemetry (codex, claude, opencode/local AI/custom); vibe/mistral record honest zeros by design.
 
 ## The core workflow
 
@@ -62,14 +61,12 @@ Install from the public npm registry and run a complete mission:
 
 ```sh
 npm install -g @magnusekdahl/parallix
-px --version
 px draft "hello world"
 px active
-px review
 px integrate
 ```
 
-`px draft` creates the mission branch, sibling worktree, mission file, and task record. Then `cd` into the mission worktree and run `px active`, `px review`, and `px integrate` there with no slug; the CLI infers the mission from the current branch/worktree.
+`px draft` creates the mission branch, sibling worktree, mission file, and task record. Then `cd` into the mission worktree and run `px active` and `px integrate` there with no slug; the CLI infers the mission from the current branch/worktree.
 
 Other draft entry points are available when you need them:
 
@@ -145,7 +142,6 @@ px active task-042
 # A second, preferentially-different agent reviews <main>..HEAD.
 # If Forgejo review is enabled, the PR is published to the dedicated
 # review surface; a self-approval by the implementing agent is blocked.
-px review task-042
 
 # Land it: runs configured integration gates, squash-merges to
 # the primary branch, updates board state, removes the branch
@@ -165,7 +161,7 @@ The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md
 
 ## What Parallix is not
 
-- **Not a model and not an AI coding agent.** It does not generate code itself. It coordinates the agents and models you already use (Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral).
+- **Not a model and not an AI coding agent.** It does not generate code itself. It coordinates the agents and models you already use (Claude Code, Codex, OpenCode/custom, and Vibe/Mistral).
 - **Not an IDE or an editor plugin.** It is a CLI workflow harness around Git and your existing toolchain — there is no UI, no autocomplete, no inline suggestions.
 - **Not a magic autonomous engineer.** This is a human-in-the-loop workflow. Nothing merges itself, and the safe operating model is that a human decides what to queue, when to run `px active`, how to respond to review findings, and whether `px integrate` should happen at all.
 - **Not a guaranteed throughput multiplier.** The observed gain varies with context. In the data we have, it ranges from roughly **+57%** on strict user-value output to about **+1,280%** on total completed-mission throughput in a later productized setup. Those are both real observations, but they are different mission-output measures and should be labeled that way.
@@ -177,8 +173,8 @@ The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md
 - **Distribution:** Published to the public npm registry as `@magnusekdahl/parallix`. Local tarball install (`npm pack`) is also supported. No Homebrew, no Docker image, no standalone binary, and no CI/release automation today.
 - **Review surface:** Forgejo is supported as the hosted PR viewer/publication surface, but the workflow remains local-first and can run without Forgejo when that provider is disabled.
 - **Versioning:** `CHANGELOG.md` is the versioning authority; PATCH bumps are the release discipline.
-- **Telemetry:** structured token/usage telemetry exists for the codex and claude families; the local-Qwen and mistral paths record honest zeros by design rather than fabricated numbers.
-- **Graphify:** the knowledge-graph path is supported for codex, claude, and qwen/opencode after one-time operator setup. It is optional, not a workflow prerequisite. The credible claim today is better-scoped context retrieval, not a proven token-savings benchmark.
+- **Telemetry:** structured token/usage telemetry exists for the codex and claude families; the local-custom and mistral paths record honest zeros by design rather than fabricated numbers.
+- **Graphify:** the knowledge-graph path is supported for codex, claude, and custom/opencode after one-time operator setup. It is optional, not a workflow prerequisite. The credible claim today is better-scoped context retrieval, not a proven token-savings benchmark.
 - **Review coverage** is best-effort, not guaranteed — see UC-4's caveats in [`docs/use-cases.md`](docs/use-cases.md).
 
 This is a tool for a local-first developer workflow on one machine, driven by an operator who reads the caveats.
@@ -188,7 +184,7 @@ This is a tool for a local-first developer workflow on one machine, driven by an
 - [`docs/use-cases.md`](docs/use-cases.md) — evidence-backed use-case inventory with confidence levels and red-team analysis (primary source of truth for what Parallix actually does today).
 - [`docs/authority-reference.md`](docs/authority-reference.md) — the internal operator reference: workflow modes, the authority model, agent selection, the layered validation model, checkpoint model, state mapping, command aliases, stats, persistent operator data, and the full public-distribution story.
 - [`docs/forgejo-setup.md`](docs/forgejo-setup.md) — how the Forgejo review surface, tokens, and `review` remote are bootstrapped.
-- [`docs/operator-setup.md`](docs/operator-setup.md) — one-time Graphify skill installation for codex, claude, and qwen/opencode.
+- [`docs/operator-setup.md`](docs/operator-setup.md) — one-time Graphify skill installation for codex, claude, and custom/opencode.
 - [`docs/readme-rewrite-benchmark.md`](docs/readme-rewrite-benchmark.md) — how comparable developer-tool READMEs are structured, and the decisions behind this one.
 - [`AGENTS.md`](AGENTS.md) — hard rules, restricted actions, and verification entrypoints.
 - `docs/adr/` — architecture decision records, including ADR 0044 (distribution model).

package/config/agents.json

@@ -3,11 +3,11 @@
   "_weights_comment": "Weights are relative integers (not percentages). Agent is selected by weighted random draw from eligible-and-supported set. Omit weights to use equal probability.",
   "steps": {
     "draft": {
-      "eligible": ["codex", "qwen", "mistral"],
+      "eligible": ["codex", "custom", "mistral"],
       "selection": "random"
     },
     "active": {
-      "eligible": ["codex", "claude",  "qwen", "mistral"],
+      "eligible": ["codex", "claude",  "custom", "mistral"],
       "selection": "random"
     },
     "conflict-resolution": {
@@ -15,7 +15,7 @@
       "selection": "random"
     },
     "review": {
-      "eligible": ["codex", "claude", "qwen", "mistral"],
+      "eligible": ["codex", "claude", "custom", "mistral"],
       "selection": "random"
     }
   },

package/config/workflow.config.schema.json

@@ -87,7 +87,7 @@
           "properties": {
             "models": {
               "type": "object",
-              "description": "Optional per-agent-family LLM model override, keyed by agent family name (e.g. codex, claude, gemini, glm, mistral, qwen). Each value is the model identifier passed to that agent's CLI. A family that is not listed sends no model parameter, so the agent uses its own default. There is no 'default' key.",
+              "description": "Optional per-agent-family LLM model override, keyed by agent family name (e.g. codex, claude, gemini, glm, mistral, custom). Each value is the model identifier passed to that agent's CLI. A family that is not listed sends no model parameter, so the agent uses its own default. There is no 'default' key.",
               "additionalProperties": { "type": "string" }
             }
           }

package/docs/agents.md

@@ -7,13 +7,13 @@
 | codex   | `codex` |
 | claude  | `claude` |
 | mistral | `vibe` |
-| qwen    | `opencode` |
+| custom    | `opencode` |
 
 All four listed launchers are supported on this workstation. Step eligibility for all workflow steps (`draft`, `active`, `conflict-resolution`, `review`) is controlled by `parallix/config/agents.json`. If a launcher is missing from `PATH`, the harness fails loudly with the exact blocker before launching.
 
-## Tool Calling Workaround (qwen/opencode)
+## Tool Calling Workaround (custom/opencode)
 
-Opencode (qwen agent family) may encounter issues with concurrent tool calls or tool call timeouts during long-running workflow sessions. When working with opencode:
+Opencode (custom agent family) may encounter issues with concurrent tool calls or tool call timeouts during long-running workflow sessions. When working with opencode:
 
 - **Prefer sequential tool calls** over parallel calls for dependent operations — if tool B needs output from tool A, call them separately.
 - **Use `workdir` parameter instead of `cd` chains** — avoid `cd <dir> && command` patterns; always use `workdir` for directory changes.
@@ -27,7 +27,7 @@ Opencode (qwen agent family) may encounter issues with concurrent tool calls or
 | codex   | `codex exec --sandbox danger-full-access --cd <worktree> <prompt>` with a worktree-local `HOME` under `.workflow/codex-home`; resume uses `codex exec resume <session-id-or---last> <prompt>`; the launcher also seeds `.workflow/codex-home/.codex/config.toml` with the repo-standard trusted posture and copies `.codex/auth.json` so headless review commands can start and keep localhost Forgejo access |
 | claude  | `claude --dangerously-skip-permissions --output-format stream-json --verbose --include-partial-messages -p <prompt>` (cwd=worktree) — uses `--output-format stream-json --verbose --include-partial-messages` to stream real-time JSONL events (tool calls, assistant text chunks) to the operator's terminal via the spawn-tee mechanism. `--include-partial-messages` is required: without it, the assistant event contains the full response at once and no intermediate progress is emitted. Session-id extraction parses the `result` event from stream-json output, falling back to the `claude --resume <id>` regex on plain text. |
 | mistral | `vibe --prompt <prompt> --trust --output text` (cwd=worktree) — **Note: NOT resume-capable in current Vibe version**; session management uses internal state in `~/.vibe/logs/session/` but does not emit a parseable resume hint to stdout/stderr. |
-| qwen    | `opencode run --pure --dangerously-skip-permissions <prompt>` (cwd=worktree); resume uses `-s <session>` when a session id is known or `--continue` when only the family marker is known |
+| custom    | `opencode run --pure --dangerously-skip-permissions <prompt>` (cwd=worktree); resume uses `-s <session>` when a session id is known or `--continue` when only the family marker is known |
 
 ## Launch output watchdog
 
@@ -74,10 +74,10 @@ Eligibility is controlled by `parallix/config/agents.json`. The default config c
 ```json
 {
   "steps": {
-    "draft": { "eligible": ["codex", "qwen", "mistral"], "selection": "random" },
-    "active": { "eligible": ["codex", "claude", "qwen", "mistral"], "selection": "random" },
+    "draft": { "eligible": ["codex", "custom", "mistral"], "selection": "random" },
+    "active": { "eligible": ["codex", "claude", "custom", "mistral"], "selection": "random" },
     "conflict-resolution": { "eligible": ["claude", "codex", "mistral"], "selection": "random" },
-    "review": { "eligible": ["codex", "claude", "qwen", "mistral"], "selection": "random" }
+    "review": { "eligible": ["codex", "claude", "custom", "mistral"], "selection": "random" }
   }
 }
 ```
@@ -141,7 +141,7 @@ The workflow detects limit-hit messages in agent stdout/stderr and automatically
 
 ### Detection
 
-`parallix/lib/limit-hit.js` ships a regex catalog per agent family (`claude`, `codex`, `qwen`, `mistral`) covering the common shapes:
+`parallix/lib/limit-hit.js` ships a regex catalog per agent family (`claude`, `codex`, `custom`, `mistral`) covering the common shapes:
 - explicit phrases like `Claude usage limit reached`, `weekly limit`, `Quota exceeded`, `RESOURCE_EXHAUSTED`
 - HTTP signals (`429 Too Many Requests`, `rate_limit_exceeded`, `Retry-After: ...`)
 

package/docs/authority-reference.md

@@ -45,7 +45,7 @@ Mission flow: `backlog → draft → ready → active → review → approved
 
 ## 3. Agent Selection
 
-Four families: `codex`, `claude`, `mistral`, `qwen`. Step eligibility is in `config/agents.json`. Launchers are resolved from `PATH` by bare executable name.
+Four families: `codex`, `claude`, `mistral`, `custom`. Step eligibility is in `config/agents.json`. Launchers are resolved from `PATH` by bare executable name.
 
 `WORKFLOW_AGENT=<name>` overrides random selection only when that agent is eligible and unblocked. The effective blocklist is operator-owned at `<PARALLIX_HOME>/agents.local.json`; on first use parallix non-destructively migrates the legacy runtime-config, repo-root, and main-worktree files in that precedence order. Per-agent values: `true` (permanent block), `{ "until": "YYYY-MM-DD HH" }` (timed), `{ "blocked": false }` (unblock).
 
@@ -256,7 +256,7 @@ Behavior:
 Telemetry capture contract (task-1285):
 - Stage rows are keyed by `(mission, stage)`; `draft.js`, `active.js`, and the review loop each record their phase via `recordStageStats`/`recordActiveStats`/`recordReviewStats`.
 - Structured sources: Codex (`codex-telemetry.js`, rollout JSONL) and Claude (`claude-telemetry.js`, stdout SSE) populate real token/usage fields.
-- `opencode` (local Qwen) exposes no structured usage source, so `opencode-telemetry.js` records honest zeros with provider/model falling back to the agent family — never fabricated numbers.
+- `opencode` (local custom) exposes no structured usage source, so `opencode-telemetry.js` records honest zeros with provider/model falling back to the agent family — never fabricated numbers.
 - `vibe`/`mistral` telemetry is **blocked** in this environment; `mistral-telemetry.js` records honest zeros and the verification is tracked as follow-up task-1288.
 
 ---

package/docs/doc-standards.md

@@ -0,0 +1,89 @@
+# Documentation Standard
+
+Rules for writing and editing README.md and subdirectory READMEs in this repository. Derived from `docs/readme-rewrite-benchmark.md` (task-1336) and applied to the current product state.
+
+---
+
+## 1. Headline / Tagline
+
+- The first line after the H1 must be a **one-line capability statement** that tells a skeptical engineer what the tool does.
+- Zero internal jargon. Do not use terms like `authority stack`, `state-map`, `adapter internals`, `worktree pattern`, or any abstraction that only makes sense to someone who has read the code.
+- Name the audience or the execution context if it matters (e.g., "local-first", "CLI", "for Git operators").
+- **Bad:** "Parallix is an authority-driven mission orchestration engine."
+- **Good:** "Parallix is a local-first Git workflow CLI for running AI coding agents in isolated, reviewable missions."
+
+## 2. Opening Paragraph
+
+- After the headline, the first paragraph should be **problem-first or contrast-first**: name the pain or define against the adjacent category before describing the mechanism.
+- Keep it to 2-4 sentences. Do not lead with features, screenshots, or install commands.
+- If the tool has a potentially surprising default behavior, state it early (like Aider stating Git auto-commit behavior, like Cline stating the permission model).
+
+## 3. Quickstart Depth
+
+- Provide a **shallow path to value**: 2-3 commands to a first working result.
+- Do not bury the quickstart behind enterprise walkthroughs, multi-provider setups, or configuration steps.
+- The quickstart section must be visually separated (fenced code block) and immediately scannable.
+
+## 4. Caveats and Honesty
+
+- Caveats are **trust signals** when stated early and specifically. Alpha status, local-first constraints, limited telemetry, and best-effort guarantees belong in their own visible section ("Current status" or "Limitations").
+- Stating limitations upfront builds more credibility than hiding them in fine print.
+- Every quantitative claim must travel with its caveats and source references.
+
+## 5. Superlative Prohibition
+
+- No superlatives ("leading", "best", "fastest", "2x faster") without **adoption data or measured benchmarks** to back them.
+- If a claim cannot be falsified with a specific number and source, do not use it.
+- This is a hard rule for alpha-stage projects with limited measured data.
+
+## 6. "What It Is Not" Section
+
+- Every README must include a section titled **"What \<tool\> is not"** (or equivalent).
+- Pre-empt the top 3 objections a skeptical user would have (e.g., "not a model", "not an IDE", "not a magic autonomous engineer").
+- This section should appear after use cases and before current status.
+
+## 7. Structural Ordering
+
+The canonical order for this repository's README.md is:
+
+1. H1 title + one-line capability headline (bold)
+2. Audience + positioning paragraph
+3. **The first concrete thing you can do** (brief intro to quickstart)
+4. Quick start (fenced code block, 2-3 commands)
+5. Why \<tool\>? (problem-first)
+6. What it does (capabilities with evidence refs)
+7. The core workflow (diagram or description)
+8. Example (realistic human-in-the-loop pass)
+9. Use cases (summary with link to full inventory)
+10. What \<tool\> is not
+11. Current status (alpha caveats, distribution, review surface, versioning, telemetry)
+12. Documentation (links to supporting docs)
+13. Development (test command)
+14. License
+
+Subdirectory READMEs follow a simplified variant: H1 with capability statement, brief description, and relevant sections.
+
+## 8. Tone and Voice
+
+- **Plain, anti-hype, engineer-to-engineer.** Write like an engineer wrote it for engineers, not a marketing team.
+- Precise and sober. Casual is fine but do not drift into jokes or bluntness that undermines credibility with a skeptical engineering manager.
+- Use active voice. Prefer concrete verbs over abstract nouns.
+- When describing capabilities, tie them to evidence: use-case IDs, file paths, test names, or config references.
+
+## 9. Link Hygiene
+
+- All relative links in README.md must resolve to existing files.
+- Before editing any README, verify: `docs/use-cases.md`, `docs/authority-reference.md`, `docs/forgejo-setup.md`, `docs/operator-setup.md`, `docs/readme-rewrite-benchmark.md`, `AGENTS.md`, `CHANGELOG.md`, `LICENSE`, `docs/adr/`.
+- Broken links are defects, not acceptable trade-offs.
+
+## 10. Subdirectory READMEs
+
+- `lib/README.md`, `examples/README.md`, and any future subdirectory READMEs must begin with a one-line capability statement (no internal jargon).
+- Use consistent heading hierarchy: H1 for the directory name, H2 for sections, H3 for subsections.
+- Keep them concise — they are navigation aids, not deep documentation.
+
+---
+
+## Enforcement Hook
+
+These rules are enforced by the hook in `AGENTS.md` under the "Documentation" section. Agents editing any `.md` file in the repo root or `docs/` directory MUST consult this standard before committing changes.

package/docs/forgejo-setup.md

@@ -10,18 +10,42 @@ Standalone workflow installs need three review-surface pieces before `active`, `
 
 1. Export the workflow into the repo.
 2. If you need a local Forgejo instance, run `parallix/tools/setup-forgejo-docker.sh` and start it with Docker Compose.
-3. Run `px setup`.
-4. Choose whether to keep the standard Backlog.md-style layout:
+3. Create the Forgejo accounts the workflow will use (see [Create the agent accounts](#create-the-agent-accounts-fresh-instance)). On a fresh instance these do not exist yet, and `px setup` only mints *tokens* for accounts that already exist — it does not create the accounts themselves.
+4. Run `px setup`.
+5. Choose whether to keep the standard Backlog.md-style layout:
    - task storage in `backlog/`
    - missions in `missions/`
    - `mission/*` branches on `main`
    - worktrees in `../<repo>-<slug>`
    - verification via `npm test`
-5. If you keep Forgejo bootstrap enabled, enter the Forgejo password for the login that can create the review repo.
-6. Enter passwords for the agent users you want available on this machine, or leave them blank to skip token creation for that user.
+6. If you keep Forgejo bootstrap enabled, enter the Forgejo password for the login that can create the review repo.
+7. Enter passwords for the agent users you want available on this machine, or leave them blank to skip token creation for that user.
 
 `setup` writes `workflow.config.json`, writes token files into `.forgejo-local/tokens/`, grants the listed agent users write access to the configured review repo, creates or updates the git `review` remote, and runs `verify-env` so the install is validated before you start missions.
 
+## Create the agent accounts (fresh instance)
+
+`px setup` / `px setup-review` create **tokens** and grant repo access, but they do **not** create Forgejo user accounts — both the basic-auth token path and the owner-token bootstrap path call `POST /users/<user>/tokens` and `PUT /repos/<repo>/collaborators/<user>`, which require the account to already exist. On a fresh Forgejo you must create the accounts first, or token creation fails with HTTP 404 / 401 for users that don't exist.
+
+Create one account per identity the workflow uses:
+
+- the **owner** that holds the review repo (default `human`),
+- one account per agent family that runs `active`/`review` steps. The canonical list comes from `suggestedForgejoUsers()` — currently `codex`, `claude`, `custom`, `mistral`. (`custom` is the opencode-backed local-model family; it is a first-class identity just like the hosted agents.)
+
+For the bundled Docker instance, create them with the Forgejo admin CLI inside the container (replace `<container>` with your Forgejo container name, e.g. `workflow-forgejo`):
+
+```bash
+for u in human codex claude custom mistral; do
+  docker exec -u 1000 <container> forgejo admin user create \
+    --username "$u" --email "$u@localhost" \
+    --password "CHANGE-ME-$u" --must-change-password=false
+done
+```
+
+Then run `px setup` and enter each account's password so the token files are minted into `.forgejo-local/tokens/`.
+
+> **Adding or renaming an agent family later** (e.g. the `qwen` → `custom` rename): the new family name is a new Forgejo identity. Create its account with `forgejo admin user create`, grant it write on the review repo, then re-run `px setup-review` to mint its token. Without this, `integrate`/`review` fail with `no token file found for <family>` even though every other agent works.
+
 ## Notes
 
 - The configured review repo is created only if it does not already exist.

package/docs/migration/task-classification.md

@@ -15,7 +15,7 @@
 | `TASK-1275` | move | workflow/parallix subject from title and mission context |
 | `TASK-1277` | stay | model-capacity tuning note for GPT family selection; not the parallix workflow tool itself |
 | `TASK-1281` | move | workflow/parallix subject from title and mission context |
-| `TASK-1287` | stay | qwen-9B benchmark note; a model-evaluation task, not a parallix workflow change |
+| `TASK-1287` | stay | custom-9B benchmark note; a model-evaluation task, not a parallix workflow change |
 | `TASK-1288` | move | workflow/parallix subject from title and mission context |
 | `TASK-1290` | move | workflow/parallix subject from title and mission context |
 | `TASK-1294` | move | workflow/parallix subject from title and mission context |

package/docs/operator-setup.md

@@ -25,7 +25,7 @@ Run the installer once per agent family. It copies a platform-specific skill (an
 |--------|---------|-----------------|
 | claude | `graphify install --platform claude` | `~/.claude/skills/graphify/` + `CLAUDE.md` directive |
 | codex | `graphify install --platform codex` | `~/.agents/skills/graphify/` |
-| qwen/opencode | `graphify install --platform opencode` | `~/.config/opencode/skills/graphify/` |
+| custom/opencode | `graphify install --platform opencode` | `~/.config/opencode/skills/graphify/` |
 
 Each command produces a `SKILL.md` file in the target directory. After running all three, verify:
 

package/docs/readme-rewrite-benchmark.md

@@ -73,7 +73,7 @@ line-by-line transcription. The decisions column is the actionable output.
   caveats are light.
 - **Borrow:** Naming the audience inside the positioning ("for operators comfortable with
   Git and CLI"); stating provider-agnosticism (Parallix's multi-family support is a
-  genuine parallel — codex/claude/mistral/qwen).
+  genuine parallel — codex/claude/mistral/custom).
 - **Avoid:** The screenshot-first above-the-fold — Parallix's mission is explicitly *out
   of scope* for screenshots/demos (task-1336 Out of Scope), and a CLI workflow harness is
   better shown by a command-flow block than a TUI image. Lead with text and a fenced

package/docs/use-cases.md

@@ -24,7 +24,7 @@ Each use case carries the four required parts: **(P) persona/buyer**, **(B) befo
 
 ### UC-2 — Don't lose a run when one AI provider hits its usage cap
 
-- **(P)** Anyone driving agents on metered/rate-limited LLM subscriptions (Claude, Codex/GPT, Mistral, local Qwen).
+- **(P)** Anyone driving agents on metered/rate-limited LLM subscriptions (Claude, Codex/GPT, Mistral, local custom).
 - **(B)** *Before:* the agent prints "usage limit reached", the run dies, and you babysit it — manually restarting later or hand-switching to a different model. *After:* the limit message is pattern-detected, that agent family is written to a timed blocklist, and the run retries with the next eligible, unblocked family; only when all are exhausted does it fail loudly.
 - **(E)** Per-family limit regexes: `lib/agents/limit-hit.js:8-36`; selection honoring eligibility + blocklist + env override: `lib/agents/agents.js:382` (`selectAgent`), `:340-348` (`isAgentBlocked` for permanent/timed/`blocked:false`). Tested: `test/agents-limit-hit.test.js` — `startAgent persists a block via updateAgentBlock when limit-hit detector fires`, `startAgent throws when every eligible agent hits the limit`, `startAgent does not loop forever when WORKFLOW_AGENT is pinned and that agent hits limit`.
 - **(C)** **Confirmed** — detection, timed-block persistence, and next-agent retry are each covered by named passing tests.
@@ -55,7 +55,7 @@ Each use case carries the four required parts: **(P) persona/buyer**, **(B) befo
 - **(P)** Operator/buyer deciding which paid agent subscriptions to keep or cut.
 - **(B)** *Before:* no durable, cross-repo record of how each agent performs, so the keep/cut decision is a hunch. *After:* a single parallix-owned `stats.csv` accumulates per-agent telemetry (`classification, implementer, pr_fix_rounds`, plus an extended 21-column schema) across every repository one runtime drives, keyed so the same mission in different repos stays distinct.
 - **(E)** `lib/commands/stats.js:14` (legacy 5-col schema), `:21-30` (extended schema). Tested: `test/stats.test.js` — `upsertStatsRow writes the workflow stats schema and updates existing missions idempotently`, `task-1314: upsertStatsRow keys on (repo, mission, stage) so same mission in different repos stays distinct`. The kind of agent-comparison this enables is demonstrated in `../visualBoard/docs/missions/2026/task-1023/RETROSPECTIVE_P5.md:198-243` (per-family PRs, reviews/PR, durations).
-- **(C)** **Partial.** Schema and CSV upsert are tested, but the value is bounded: the richest per-agent comparison in the evidence came from Forgejo PR data, not `stats.csv`, and two of four families record honest zeros for token usage (`opencode`/local Qwen and `mistral`/vibe telemetry are zeroed by design, per `README.md:230-231` describing `opencode-telemetry.js`/`mistral-telemetry.js`). So cross-agent *cost/value* comparison is complete only for `codex` and `claude` today.
+- **(C)** **Partial.** Schema and CSV upsert are tested, but the value is bounded: the richest per-agent comparison in the evidence came from Forgejo PR data, not `stats.csv`, and two of four families record honest zeros for token usage (`opencode`/local custom and `mistral`/vibe telemetry are zeroed by design, per `README.md:230-231` describing `opencode-telemetry.js`/`mistral-telemetry.js`). So cross-agent *cost/value* comparison is complete only for `codex` and `claude` today.
 
 ---
 

package/examples/README.md

@@ -1,4 +1,4 @@
-# parallix examples
+# Parallix Examples
 
 These examples use the provisional `px` runner from inside a **caller-supplied**
 target repository. They contain no fixed workstation paths, no sibling worktree

package/index.js

@@ -223,6 +223,13 @@ ${fmt.bold('Core Commands:')}
   rebase [<slug>] [--push]          Rebase mission branch onto the primary integration branch (main) with auto-resolution of mission-specific conflicts.
   diff [<slug>]                Launch the primary local diff tool for branch-vs-main review.
   stats [<csv_file>|--csv-file <path>] [--today YYYY-MM-DD|--from YYYY-MM-DD --to YYYY-MM-DD] [--output <file>]  Print parallix weekly or range tables from <PARALLIX_HOME>/stats.csv; legacy retrospective CSVs remain supported.
+  config                Print the effective configuration (built-in defaults merged with workflow.config.json). Read-only.
+  aliases               Print the derived command-alias table (state-map virtual states → canonical commands).
+
+${fmt.bold('Utility Commands:')}
+  version, --version, -v  Print the package version, px path, package root, and Node version.
+  shell-init [bash|zsh]   Print the shell integration snippet that cds your terminal into the next mission worktree on transitions.
+  review-event <slug> --type <type> --actor <actor> --content <text> [--timestamp <stamp>] [--skip-git]  Append a review-thread event for a mission.
 
 ${fmt.bold('Notes:')}
   - <slug> is optional if it can be inferred from the current branch, directory name, or git worktree.

package/lib/agents/agents.js

@@ -5,7 +5,7 @@ const fmt = require('../core/fmt');
 const { startCodexDraftAgent, resolveCodexCommand } = require('./codex');
 const { startClaudeAgent, resolveClaudeCommand } = require('./claude');
 const { startMistralAgent, resolveMistralCommand } = require('./mistral');
-const { startOpencodeAgent, resolveOpencodeCommand } = require('./opencode');
+const { startOpencodeAgent, resolveOpencodeCommand, isSpuriousOpencodeExit } = require('./opencode');
 const { detectLimitHit, formatBlockUntil, DEFAULT_FALLBACK_HOURS } = require('./limit-hit');
 const sessions = require('../tools/sessions');
 const storage = require('../core/storage');
@@ -17,9 +17,9 @@ const { migrateAgentBlocklists } = require('../core/persistent-data-migration');
 // "codex resume <id>", "opencode -s ses_<id>",
 // "claude --resume <id>"). The resume flag is only used when the caller
 // passes slug+role+worktree and the session marker matches the chosen agent.
-// qwen (opencode) always uses --continue; claude uses --continue; codex uses
+// custom (opencode) always uses --continue; claude uses --continue; codex uses
 // `exec resume --last`.
-const RESUME_CAPABLE = new Set(['claude', 'codex', 'qwen']);
+const RESUME_CAPABLE = new Set(['claude', 'codex', 'custom']);
 
 const CONFIG_PATH = path.join(__dirname, '..', '..', 'config', 'agents.json');
 
@@ -30,21 +30,21 @@ const LAUNCHERS = {
   codex: startCodexDraftAgent,
   claude: startClaudeAgent,
   mistral: startMistralAgent,
-  qwen: startOpencodeAgent
+  custom: startOpencodeAgent
 };
 
 const RESOLVERS = {
   codex: resolveCodexCommand,
   claude: resolveClaudeCommand,
   mistral: resolveMistralCommand,
-  qwen: resolveOpencodeCommand
+  custom: resolveOpencodeCommand
 };
 
 const HEALTH_PROBE_ARGS = Object.freeze({
   codex: ['--help'],
   claude: ['--help'],
   mistral: ['--help'],
-  qwen: ['--help']
+  custom: ['--help']
 });
 const LAUNCHER_HEALTH_TIMEOUT_MS = 3000;
 const DEFAULT_NO_OUTPUT_INITIAL_DELAY_MS = 60_000;
@@ -800,9 +800,13 @@ async function startAgent(step, opts = {}) {
     // Only treat `status !== null && status !== 0` or `signal` (with no spawn
     // error) as a launch failure; `status: null` without signal is ambiguous
     // (spawn-tee close event can emit null code) and should not trigger a retry.
+    // Spurious opencode v2.0.0 JSON-mode exits (exit 1 after a valid
+    // "reason":"stop" completion) are excluded — the agent completed, the
+    // non-zero code is a post-run cleanup race.
     const launchFailed = result &&
       ((result.status !== null && result.status !== 0) || (result.signal && !result.error)) &&
-      !limitHit;
+      !limitHit &&
+      !isSpuriousOpencodeExit(result);
     if (launchFailed) {
       const exitInfo = result.signal
         ? `signal ${result.signal}`
@@ -820,10 +824,10 @@ async function startAgent(step, opts = {}) {
       });
       tried.add(chosen);
       launched.add(chosen);
-      // Block non-qwen agents on non-limit failures so selectAgent excludes them
+      // Block non-custom agents on non-limit failures so selectAgent excludes them
       // on the next retry iteration, and the review-loop fallback path can activate.
-      // qwen (opencode/local AI) is excluded — exit 1 is a temporary local error.
-      if (chosen !== 'qwen') {
+      // custom (opencode/local AI) is excluded — exit 1 is a temporary local error.
+      if (chosen !== 'custom') {
         const blockUntil = formatBlockUntil(new Date(Date.now() + DEFAULT_FALLBACK_HOURS * 60 * 60 * 1000));
         try {
           const blockResult = updateAgentBlockFn(chosen, blockUntil);

package/lib/agents/limit-hit.js

@@ -20,7 +20,7 @@ const PATTERN_SETS = Object.freeze({
     /resource_exhausted/i
   ],
 
-  qwen: [
+  custom: [
     /\b(?:rate|usage|quota)\s*limit\s*(?:reached|exceeded)\b/i,
     /\b429\b[^\n]*?\b(?:rate|quota|usage)\b/i,
     /\b429\b/i,

package/lib/agents/opencode-telemetry.js

@@ -4,20 +4,20 @@
  * Opencode Telemetry Parser
  *
  * Parses `opencode export` JSON output to extract real token-usage data for
- * Qwen sessions. The exported JSON may contain token usage in various shapes
+ * custom/opencode sessions. The exported JSON may contain token usage in various shapes
  * depending on the opencode version, so this parser is resilient to:
  *   - Missing token fields (substitutes 0)
  *   - Nested vs flat structures
  *   - Different field name conventions
  *
- * Provider and model fields are set to "opencode" and "qwen" respectively,
+ * Provider and model fields are set to "opencode" and "custom" respectively,
  * matching the convention used by other telemetry modules.
  *
  * See task-1285 for the full telemetry credibility design.
  */
 
 const PROVIDER = 'opencode';
-const MODEL = 'qwen';
+const MODEL = 'custom';
 
 /**
  * Safely extract a finite number from a value, defaulting to 0.
@@ -255,10 +255,18 @@ function countToolCalls(parsed) {
  * Returns null when the content yields no usable token signal (empty string,
  * non-JSON, or JSON without any token-usage fields).
  *
+ * When the JSON contains token data but no model field, falls back to
+ * `fallbackModel` — the model the launcher was configured with for this run
+ * (from workflow.config.json) — so telemetry records the actual model id
+ * instead of the generic family label.  When no model is configured, falls
+ * back to the generic family label `MODEL`.
+ *
  * @param {string} jsonString - Raw JSON string from `opencode export`
+ * @param {string=} [fallbackModel] - Configured model id for this run, used
+ *   when the export JSON omits the model field
  * @returns {object|null} Normalized telemetry object or null
  */
-function extractOpencodeTelemetryFromExport(jsonString) {
+function extractOpencodeTelemetryFromExport(jsonString, fallbackModel) {
   if (!jsonString || typeof jsonString !== 'string' || !jsonString.trim()) {
     return null;
   }
@@ -292,17 +300,17 @@ function extractOpencodeTelemetryFromExport(jsonString) {
     // total_tokens is set but individual fields are zero — treat total_tokens as the real signal
     // and derive input/output from it conservatively
     const totalTokens = num(tokenUsage.total_tokens);
-    return {
-      sessionId: extractSessionId(parsed),
-      provider: PROVIDER,
-      model: extractModelName(parsed) || MODEL,
-      inputTokens: 0,
-      outputTokens: 0,
-      cachedTokens: 0,
-      totalTokens,
-      toolCalls: countToolCalls(parsed),
-      usagePercent: null,
-    };
+      return {
+        sessionId: extractSessionId(parsed),
+        provider: PROVIDER,
+        model: extractModelName(parsed) || fallbackModel || MODEL,
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedTokens: 0,
+        totalTokens,
+        toolCalls: countToolCalls(parsed),
+        usagePercent: null,
+      };
   }
 
   const totalTokens = num(tokenUsage.total_tokens) || (inputTokens + outputTokens);
@@ -310,7 +318,7 @@ function extractOpencodeTelemetryFromExport(jsonString) {
   return {
     sessionId: extractSessionId(parsed),
     provider: PROVIDER,
-    model: extractModelName(parsed) || MODEL,
+    model: extractModelName(parsed) || fallbackModel || MODEL,
     inputTokens,
     outputTokens,
     cachedTokens,
@@ -342,10 +350,12 @@ function extractOpencodeTelemetry(result) {
  * Return the provider/model pair for opencode tasks.
  * Used as fallback when telemetry is null.
  *
+ * @param {string=} [defaultModel] - Optional configured model id; falls back
+ *   to the generic family label when absent.
  * @returns {{provider: string, model: string}}
  */
-function getOpencodeProviderModel() {
-  return { provider: PROVIDER, model: MODEL };
+function getOpencodeProviderModel(defaultModel) {
+  return { provider: PROVIDER, model: defaultModel || MODEL };
 }
 
 module.exports = {