@magnusekdahl/parallix 1.3.4 → 1.5.126

package/README.md

@@ -1,45 +1,52 @@
 # Parallix
 
-**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.**
+**Parallix is an agent-agnostic, local-first workflow that puts a trust ladder around AI coding work: separate review that prefers a different agent family when one is available, repository-owned verification where you configure a gate, Linux Bubblewrap confinement when available (falling back to an agent's native sandbox, or blocking until explicit consent when neither exists), and a human-owned squash merge.**
 
-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.
+Coding agents become much more useful when you can run several pieces of work at once. But simply starting more agents quickly creates a new bottleneck: they compete for the same working tree, lose context across long runs, hit provider limits, and produce more changes than one engineer can safely supervise and integrate.
 
-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.
+Parallix is the delivery layer around those agents. It gives every piece of work an isolated mission, lets multiple missions progress concurrently, preserves execution across sessions, separates implementation from review, runs repository-owned verification, and leaves the final integration decision with the human operator. Parallel Git isolation is how that trust ladder can operate across concurrent missions instead of one shared checkout.
 
-**The first concrete thing you can do** is install the CLI and run one complete mission:
+Parallix is deliberately not tied to one agent vendor or model family. The same mission workflow can use different agent families for drafting, implementation, and review, including commercially hosted agents, locally hosted AI, and custom runtimes.
+
+## Install
+
+For Bash, install Parallix and load its bundled worktree-switching integration
+in one step:
 
 ```sh
-npm install -g @magnusekdahl/parallix
-px draft "create a hello world program"
-px active
-px integrate
+npm install -g @magnusekdahl/parallix && eval "$(px shell-init bash)"
 ```
 
-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.
+**The first concrete thing you can do** is run one complete mission:
+
+[![Terminal demonstration showing a new directory, mission drafting, mission inspection, autonomous review, diff inspection, and operator integration](https://raw.githubusercontent.com/oxtan-maker/parallix/main/docs/assets/first-value-demo.gif)](https://raw.githubusercontent.com/oxtan-maker/parallix/main/docs/assets/first-value-demo.gif)
+
+The operator inspects the drafted mission before execution, then inspects the reviewed diff and decides whether to run `px integrate`. Parallix does not merge autonomously.
+
 
 ## Why Parallix?
 
-Running AI coding agents one session at a time hits a ceiling fast:
+The main reason to use coding agents is leverage: while one agent is working, another can be working on something else. The useful ceiling is therefore not how fast one agent can type code, but **how much trustworthy work one engineer can keep moving in parallel**, and running one session at a time leaves most of that unused. Simply starting several agents, however, creates a new set of coordination problems:
 
-- **One working tree, many agents.** Point two agents at the same checkout and they fight over the index, the branch, and uncommitted files. You either serialize them — one idle while the other runs — or hand-manage `git worktree` and branch names yourself.
+- **One working tree, many agents.** Point two agents at the same checkout and they fight over the index, the branch, and uncommitted files. You either serialize them — throwing away the parallelism — or hand-manage `git worktree` and branch names yourself.
 - **Runs die on usage caps.** An agent prints "usage limit reached", the run stops, and you babysit it: restart later or hand-switch to a different model.
 - **Long tasks lose their place.** A crashed or context-exhausted agent leaves you reconstructing what was already done by re-reading diffs.
 - **The author grades its own homework.** The agent that wrote the change also declares it done. Nobody independent looks before it lands.
 
-Parallix is a mission-based development workflow that addresses each of these directly, with the mechanics living in tested code rather than in prompts. It is not another agent or model — it is the operator-owned layer around the agents you already use.
+Parallix is a mission-based development workflow that addresses each of these directly so parallel agents can translate into actual delivery throughput. The mechanics live in tested code rather than in prompts. It is not another agent or model — it is the operator-owned layer around the agents you already use.
 
 ## What it does
 
-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**. 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**. 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**. 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 different agent families — including local AI — in the same workflow**. Parallix owns the mission lifecycle rather than one vendor's agent framework. Drafting, implementation, and review can use different eligible families, and custom/local runtimes participate in the same branch, checkpoint, review, and integration model.
+- **Fail over automatically when an agent hits its usage limit**. 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**. The execution agent records completed checkpoints with evidence and a concrete next action, and commits them locally, so a later session or a different agent can resume from the recorded progress.
+- **Force a second, preferentially-different coding agent review before merge**. 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 only guarantees a different reviewer when one is available.
+- **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 running locally and opens or updates the PR there; if Forgejo is disabled, the branch/worktree flow still runs without it.
 - **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.
+- **Confine supported agent processes with Bubblewrap on Linux**. When Bubblewrap is available, Parallix mounts the host filesystem read-only and selectively grants write access required by the current mission. Implementation gets its mission worktree and required Git state writable; review keeps the worktree read-only. If Bubblewrap is unavailable, Parallix falls back to the agent's own native sandbox where the family exposes one (e.g. Codex `--sandbox`, Qwen `-s`), otherwise it blocks the mutating launch until the operator explicitly consents to run unsandboxed — no silent fallback.
+- **Evaluate which agent family actually pays off across every repo one runtime drives**. A single operator-owned measurement database (`<PARALLIX_HOME>/parallix.db`) accumulates per-agent usage telemetry across repositories.
 
 ## The core workflow
 
@@ -53,76 +60,23 @@ backlog → draft → active → review → approved → done
                   checkpoints  gates   cleanup
 ```
 
-In practice: a human drafts a mission, Parallix creates the branch and worktree, an agent runs and writes checkpoints, a verification gate runs, a second (preferentially different) agent reviews the diff, and only then is the work integrated back to your primary branch by squash-merge. Blocking review findings loop back to `active` on the same branch and PR.
-
-## Quick start
-
-Install from the public npm registry and run a complete mission:
-
-```sh
-npm install -g @magnusekdahl/parallix
-px draft "hello world"
-px active
-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` 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:
-
-```sh
-# Draft from the current repository directory name
-px draft .
-
-# Draft from an existing structured task file
-px draft task-001
-```
-
-Optional but useful: run `px setup` if you want help creating `workflow.config.json`, appending workflow entries to `.gitignore`, or bootstrapping Forgejo review wiring.
-
-Optional but useful: add `px shell-init` to your shell rc so mission transitions can `cd` your terminal into the next worktree:
-
-```sh
-echo 'eval "$(px shell-init bash)"' >> ~/.bashrc
-```
-
-Alternatively, install from a local tarball (useful for development or when offline):
-
-```sh
-npm pack
-npm install -g ./magnus-parallix-*.tgz
-```
-
-Parallix runs on built-in defaults without setup. `px setup` becomes useful when you want to configure your verification command, customize the mission layout, or bootstrap the Forgejo review surface (repo, token files, and `review` remote). Forgejo is the PR viewer and publication surface here, not the authority for local branch ancestry or integration.
-
-`px draft` now works without a pre-existing task file. If the input is free text or a directory path, Parallix creates a synthetic markdown task with classification `unknown` so the later phases, stats, and preflight checks still have a consistent record to work from.
-
-If you already use Backlog.md-style task files, that still works. `px draft task-001` remains valid, and Parallix will use the existing task metadata and classification when it is present.
-
-## Optional task files
+In practice: a human drafts a mission, Parallix creates the branch and worktree, an agent runs and writes checkpoints, a configured verification gate runs, a second agent reviews the diff, and only then is the work integrated back to your primary branch by squash-merge. Review uses a different agent family when one is available; when none is runnable, it falls back to the same family as a second review attempt. Blocking review findings loop back to `active` on the same branch and PR.
 
-Structured markdown task files are now optional. They are still useful when you want stable IDs, explicit labels, or an external task-management flow.
+## Defence in depth
 
-```md
-backlog/tasks/task-001 - my-first-task.md
----
-id: TASK-001
-title: my first task
-status: backlog
-assignee: []
-labels: ["user_value"]
-dependencies: []
----
-```
+Running several agents in parallel is only worth doing if you can trust what comes back. Parallix combines isolation, mission-specific checks, separate review, and automatic repair so confidence comes from checked results throughout delivery.
 
-Then run the mission by slug:
+1. **Isolation.** Every mission gets its own branch and sibling worktree, so parallel agents do not compete over the same working tree, index, or branch.
+2. **Confinement.** On Linux with Bubblewrap enabled, supported agent processes see a read-only host filesystem, with write access limited to the mission worktree and the Git, temporary, and agent-state paths needed for the current step. During review, the mission worktree is read-only too.
+3. **Your existing checks at lifecycle transitions.** Connect your test pyramid by assigning existing test commands to the stages where you want them to run. For example, run fast unit tests and static analysis before a mission moves from `active` to `review`, and reserve expensive integration and end-to-end suites for the final merge. Parallix runs the selected commands and blocks progress when they fail. The [lifecycle check configuration](docs/config.md#lifecycle-gates) shows how to connect those commands to each stage.
+4. **Defences tailored to the mission.** Parallix instructs the drafting agent to investigate the codebase and mission, define concrete success criteria, and select suitable verification commands. For bug fixes, it calls for a failing reproduction test before implementation. The mission's declared checks run before it moves from `active` to `review`, turning the plan into checks on the delivery.
+5. **Evidence for review.** Before a mission moves from `active` to `review`, Parallix checks that the final checkpoint connects success criteria to concrete references, such as tests or runnable repository commands. Missing mission or checkpoint documents block that transition. Reviewers get a stated goal and supporting evidence to examine; generic claims such as “verified” are insufficient.
+6. **Separate review.** A second agent reviews the delivery, using a different agent family when one is available. The pull request author cannot formally approve their own work.
+7. **Automatic, focused repair.** When checks detect a repairable delivery failure, Parallix sends the agent back with a tight prompt containing the specific failure, captured output, and the repair required. It reruns the failing check to confirm the fix. Retries are bounded, and unresolved failures are surfaced to the operator.
+8. **Validate the final tree before merge.** When you choose to integrate an approved mission, Parallix runs the checks you assigned to integration against the exact tree about to land. This is where the broader tests from your pyramid check that the change works with the rest of the system. A failing check stops the merge.
+9. **Operator decision.** Nothing merges itself. A human reads the diff and decides whether to integrate at all.
 
-```sh
-px draft task-001
-px active task-001
-```
-
-Optional but useful: install the Graphify skill once per supported agent family if you want graph-backed codebase navigation in long missions and reviews. This is not a hard requirement like having a task file for `px draft`; when Graphify is not installed, Parallix skips graph updates and continues the workflow. The operator setup is documented separately because it is a workstation capability, not a minimum install step.
+Repository checks and mission-specific defences complement separate review: passing a command or finding an evidence reference does not prove the change meets its goal. Parallix runs the checks your repository and mission declare; the operator retains the final judgement. See [use cases](docs/use-cases.md) for supported capabilities.
 
 ## Example
 
@@ -151,22 +105,37 @@ px active task-042
 px integrate task-042
 ```
 
-The verification gate that runs at each phase is whatever you declare in `workflow.config.json`. In this repo that dispatcher is `./scripts/verify-local.sh {{area}}`: earlier phases use the fast general suite, while `px integrate` calls `verify-local.sh integrate`, which resolves repo-side integration gates from `config/integration-pipelines.json` and runs the stricter pre-merge checks there.
+Parallix runs on built-in defaults with no config file; `px setup` writes one when you want to declare your own verification gate or mission layout. See the [configuration reference](docs/config.md) for the supported overrides and their defaults. The verification gate that runs at each phase is whatever you declare in `workflow.config.json`. In this repo that dispatcher is `./scripts/verify-local.sh {{area}}`: earlier phases use the fast general suite, while `px integrate` calls `verify-local.sh integrate`, which resolves repo-side integration gates from `config/integration-pipelines.json` and runs the stricter pre-merge checks there.
+
+When a mission goes wrong and you want to start it over, `px cancel <slug> --yes`
+retires it: it deletes that one mission's lifecycle rows from the operator
+database, archives its Backlog task file so the card leaves the board, keeps its
+recorded usage and cost, and prints the
+`git worktree remove ... && git branch -D ...` cleanup for you to run yourself.
+The same action sits behind a confirmation on the TUI board (`Shift+X`) and on
+the web board (the `cancel ✕` button). See the [board guide](docs/tui-board.md)
+for the details.
+
+## Optional integrations
+
+Both are optional integrations, and each one is wired independently of the other.
+
+**Backlog.md.** Point `px draft` at a task key and Parallix adopts the existing record instead of creating one: it reads the ID, title, labels, and classification from `backlog/tasks/<slug> - <title>.md` and carries them through the mission. As the mission moves, Parallix writes the task's `status` frontmatter and, on completion, moves the file into `backlog/completed/`, so the board reflects mission state without a second bookkeeping step. Drafting from free text instead produces an equivalent synthetic record, so nothing downstream depends on you keeping task files.
+
+**Forgejo.** Review publication is off until you opt in. If you want its reviewer surface, `px setup` can bootstrap the review repository, agent tokens, and the `review` git remote; otherwise the branch/worktree workflow runs without Forgejo. Forgejo user accounts must already exist before that optional setup; see [`docs/forgejo-setup.md`](docs/forgejo-setup.md) for account creation, token layout, and running a local instance.
 
 ## Use cases
 
-The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md). The README focuses on the three claims that are best supported by the current code and retrospective data:
+The durable capability guide and confidence boundaries are in [`docs/use-cases.md`](docs/use-cases.md).
 
-1. **Parallel multi-agent execution (UC-1).** The isolated worktree-per-mission model is the *specific* mechanic an internal retrospective measured as the only configuration to beat a human baseline. Depending on whether you frame output as direct user-value missions or total completed missions in an already-productized setup, the observed gain ranges from roughly **+57%** to about **+1,280%**.
-2. **Usage-limit auto-failover (UC-2).** Family-specific limit detection → timed blocklist → retry-next-eligible is a tested control loop, not a retry button.
-3. **Second review gate (UC-4, Partial).** A self-approval is code-blocked and reviewer selection excludes the implementer family — forcing a second review *attempt* by a preferentially different agent, with an honest same-family fallback.
+An **internal retrospective, not external evidence,** measured the isolated worktree-per-mission model as the only configuration to beat a human baseline. Depending on whether you frame output as direct user-value missions or total completed missions in an already-productized setup, the observed gain ranges from roughly **+57%** to about **an order of magnitude**.
 
 ## 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/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 model and not an AI coding agent.** It does not generate code itself. It is agent-agnostic infrastructure around the agents and models you already use, including hosted and local AI.
+- **Not an IDE or an editor plugin.** It is a CLI workflow harness around Git and your existing toolchain. It has a terminal mission board, but no code editor, autocomplete, or 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.
+- **Not a guaranteed throughput multiplier.** The observed gain varies with context.
 
 ## Current status
 
@@ -174,35 +143,39 @@ 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-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.
 
 ## Documentation
 
-- [`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/use-cases.md`](docs/use-cases.md) — durable capability identities, confidence levels, and positioning boundaries.
 - [`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 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).
+- `docs/adr/` — architecture decision records, including ADR 0044 (distribution model) and ADR 0048 (the fail-closed harness defence inventory cited above).
 
 ## Development
 
 ```sh
-npm test     # FORCE_COLOR=0 node --test test/*.test.js
+npm test
+npm run test:integration  # real process, Git/worktree, package, and local-network boundary coverage
+npm run test:codeql       # CodeQL SAST scan (javascript-typescript security/code-scanning), run manually; not part of local integration
 ```
 
-The test suite is the verification gate this repo declares in `workflow.config.json`. Run it before integrating any change. Contributions follow the same mission lifecycle the tool itself runs: branch, worktree, checkpoints, a second review, and a passing gate before integration.
+The test suite is the verification gate this repo declares in `workflow.config.json`. Run it before integrating any change. Contributions follow the same mission lifecycle the tool itself runs: branch, worktree, checkpoints, a second review, and a passing gate before integration. To exercise the packaged artifact the way a user receives it: `npm pack && npm install -g ./magnusekdahl-parallix-*.tgz`.
 
-If you are developing Parallix itself from a checkout, the repo-root dispatcher is:
+If you are developing Parallix itself from a checkout, use the built runtime
+after `npm run build`, or run the TypeScript entry directly with the development
+script:
 
 ```sh
-node index.js <command>
+npm run build
+node build/px.mjs <command>
+
+# Direct-source development path
+npm run dev -- <command>
 ```
 
 ## License

package/build/asset-manifest.json

@@ -0,0 +1,129 @@
+{
+  "version": 1,
+  "assets": [
+    {
+      "key": "config/agents.json",
+      "sha256": "c380d909ddf757f9bbe5136d79652a19396ae69068d144e2b6031ed4b7fb4b78"
+    },
+    {
+      "key": "config/state-map.json",
+      "sha256": "6a4ec47387d1240e32967dc8e4ce54a15d69df2676b7a96ff72baafe996fef7d"
+    },
+    {
+      "key": "prompts/act-on-review-core.md",
+      "sha256": "c7931a2b30343eb509e6d06c8c71d6f0591fbe9bca9029ae8f88781858c8e26c"
+    },
+    {
+      "key": "prompts/act-on-review.md",
+      "sha256": "8f06b68b92c8cfc6f3ee0ff7a1e258258c1a1c2220bdfe5b1a3d5fbaab6befeb"
+    },
+    {
+      "key": "prompts/draft-core.md",
+      "sha256": "f5565ff259a2c830e8853573f7a774fb2ce21e1631d457a025d63ebcf9f4ea6a"
+    },
+    {
+      "key": "prompts/draft.md",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "key": "prompts/execute-core.md",
+      "sha256": "51b16691ee421a55c5a2da30e62fb8e41c910a5e1e3a16ea45ed6f67aa5e031f"
+    },
+    {
+      "key": "prompts/execute.md",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "key": "prompts/review-core.md",
+      "sha256": "7be9123246e77e669d0bbd7c1f6c6f436f58af0c216cb4ee43fd82824b344bbf"
+    },
+    {
+      "key": "prompts/review.md",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "key": "templates/mission-scaffold.md",
+      "sha256": "ce7f4aa6eb9e684434f243a64018d4dfa9962348bfdb5d59881783326cc0ec90"
+    },
+    {
+      "key": "migrations/0001-initial-schema.sql",
+      "sha256": "30a76fa3839753ddbfe312428dd1b7285ac1b8d0bd678fc79c79018ec6154f69"
+    },
+    {
+      "key": "migrations/0002-import-history.sql",
+      "sha256": "a8a0febfb4e448a11a5a16b2227d5cc1959bf4594aadd6fd65ea764283020edd"
+    },
+    {
+      "key": "migrations/0003-board-lane-events.sql",
+      "sha256": "d4080e33cb1a77e504188dbdafa0765ddf3391d99e1d81a76ab3a5ce3b9b40f2"
+    },
+    {
+      "key": "migrations/0004-mission-aggregate.sql",
+      "sha256": "27a88fa469f0197b9c54a0c1878c3fa3339061c15eb1b1b1928b72249ac7c67d"
+    },
+    {
+      "key": "migrations/0005-mission-external-task-ref.sql",
+      "sha256": "c92e3addb896b7f93221e70bf69c7eed70e94832921ef0177e28abf283639458"
+    },
+    {
+      "key": "migrations/0005-repository-scoped-session-markers.sql",
+      "sha256": "2c6318e475a40ecac6489bbd6b4bafc3fb5af80cfc8760dbff88b073fd694673"
+    },
+    {
+      "key": "migrations/0006-session-markers.sql",
+      "sha256": "f06bf2ae50ba8e1ed51b1cb643b5f6dc739f107bb8b7cabc7d511b5f42087433"
+    },
+    {
+      "key": "migrations/0007-usage-statistics-identity.sql",
+      "sha256": "0bba52d7101501a2a2bc95d20abed97f52bae10670bdf15e55c5d09c391315b3"
+    },
+    {
+      "key": "migrations/0008-review-workflow-state.sql",
+      "sha256": "02d772850468eb5b064080ca1fcb35100cfaf21cbeed4fe6a877278ab3b87148"
+    },
+    {
+      "key": "migrations/0009-review-gate-retries.sql",
+      "sha256": "905cbf1fdfbd357cc705ceb4762170ad6d649424bfc977dd4b241a31fa9e642d"
+    },
+    {
+      "key": "migrations/0010-review-events-and-implementer-response.sql",
+      "sha256": "c8f9327fe161bfdea6a7e56ad3fab2c1bc97a30989da3cb1236c35d9d672d07a"
+    },
+    {
+      "key": "migrations/0011-board-lane-events-repository-id.sql",
+      "sha256": "cee3b1df36dfa117ae8ef56f0cca813b81808ca62b65a6c6eb1f41fc0ad98d05"
+    },
+    {
+      "key": "migrations/0012-review-hook-retries.sql",
+      "sha256": "3511bf668060e7a70237176c80a8145ce521d41ff2965351e02e059ecd1992eb"
+    },
+    {
+      "key": "migrations/0013-usage-statistics-thoughts-tokens.sql",
+      "sha256": "b3b9c80e6372eeb3b2bf3b12813dc6fbc4c5d20f601a5abbb6ac0a7605467eb7"
+    },
+    {
+      "key": "migrations/0014-remove-usage-closed.sql",
+      "sha256": "4a14bf444be8cbb1d1ef67e0526fb3b31609e04877e0eec32e0b3e0094fa1757"
+    },
+    {
+      "key": "migrations/0015-current-work-latest-per-mission.sql",
+      "sha256": "a08063b188a91e901d462f73f4f154c98d85068324cef45eb144250e5000051a"
+    },
+    {
+      "key": "migrations/0016-review-drop-retry-counters.sql",
+      "sha256": "0acd31e661e720b563b92b3f75f99218dd99011b787ee8aad76b9a3bc1e363c4"
+    },
+    {
+      "key": "migrations/0017-retire-mission-import-provenance.sql",
+      "sha256": "f46823014782c22a9e40b486958770d2b5f7e7180fc9fe6be961a791cca97b50"
+    },
+    {
+      "key": "migrations/0018-adhoc-mission-counter.sql",
+      "sha256": "3560376d8e31e0b8fc527509211378a839ba24ef5e5e5fac9ee6dadc06c172c2"
+    },
+    {
+      "key": "migrations/0019-custom-agent-leases.sql",
+      "sha256": "07559cd5363f01a309d028673e6dcb9e222a848fae79c57d2fee9001589da19d"
+    }
+  ]
+}

package/{config → build/config}/agents.json

@@ -1,21 +1,17 @@
 {
-  "_comment": "Per-step agent eligibility policy. Modify to change which agents are eligible for each workflow step.",
+  "_comment": "Per-step agent eligibility policy. Modify to change which agents are eligible for each workflow step. In an installed/published build, drop a copy at <working-tree>/config/agents.json to override the bundled file without a rebuild; the working-tree copy is authoritative for steps.*.eligible. The bundled copy under the package root is the fallback when no working-tree copy exists.",
   "_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", "custom", "mistral"],
+      "eligible": ["codex", "custom", "qwen", "vibe"],
       "selection": "random"
     },
     "active": {
-      "eligible": ["codex", "claude",  "custom", "mistral"],
-      "selection": "random"
-    },
-    "conflict-resolution": {
-      "eligible": ["claude", "codex", "mistral"],
+      "eligible": ["codex", "claude", "custom", "qwen", "vibe"],
       "selection": "random"
     },
     "review": {
-      "eligible": ["codex", "claude", "custom", "mistral"],
+      "eligible": ["codex", "claude", "custom", "qwen", "vibe"],
       "selection": "random"
     }
   },

package/build/manifest.sha256

@@ -0,0 +1,40 @@
+2e6369b99697e6aaebc09838469bc8a4e546739bc39b05df7818a593a1ff320c  asset-manifest.json
+c380d909ddf757f9bbe5136d79652a19396ae69068d144e2b6031ed4b7fb4b78  config/agents.json
+6a4ec47387d1240e32967dc8e4ce54a15d69df2676b7a96ff72baafe996fef7d  config/state-map.json
+30a76fa3839753ddbfe312428dd1b7285ac1b8d0bd678fc79c79018ec6154f69  migrations/0001-initial-schema.sql
+a8a0febfb4e448a11a5a16b2227d5cc1959bf4594aadd6fd65ea764283020edd  migrations/0002-import-history.sql
+d4080e33cb1a77e504188dbdafa0765ddf3391d99e1d81a76ab3a5ce3b9b40f2  migrations/0003-board-lane-events.sql
+27a88fa469f0197b9c54a0c1878c3fa3339061c15eb1b1b1928b72249ac7c67d  migrations/0004-mission-aggregate.sql
+c92e3addb896b7f93221e70bf69c7eed70e94832921ef0177e28abf283639458  migrations/0005-mission-external-task-ref.sql
+2c6318e475a40ecac6489bbd6b4bafc3fb5af80cfc8760dbff88b073fd694673  migrations/0005-repository-scoped-session-markers.sql
+f06bf2ae50ba8e1ed51b1cb643b5f6dc739f107bb8b7cabc7d511b5f42087433  migrations/0006-session-markers.sql
+0bba52d7101501a2a2bc95d20abed97f52bae10670bdf15e55c5d09c391315b3  migrations/0007-usage-statistics-identity.sql
+02d772850468eb5b064080ca1fcb35100cfaf21cbeed4fe6a877278ab3b87148  migrations/0008-review-workflow-state.sql
+905cbf1fdfbd357cc705ceb4762170ad6d649424bfc977dd4b241a31fa9e642d  migrations/0009-review-gate-retries.sql
+c8f9327fe161bfdea6a7e56ad3fab2c1bc97a30989da3cb1236c35d9d672d07a  migrations/0010-review-events-and-implementer-response.sql
+cee3b1df36dfa117ae8ef56f0cca813b81808ca62b65a6c6eb1f41fc0ad98d05  migrations/0011-board-lane-events-repository-id.sql
+3511bf668060e7a70237176c80a8145ce521d41ff2965351e02e059ecd1992eb  migrations/0012-review-hook-retries.sql
+b3b9c80e6372eeb3b2bf3b12813dc6fbc4c5d20f601a5abbb6ac0a7605467eb7  migrations/0013-usage-statistics-thoughts-tokens.sql
+4a14bf444be8cbb1d1ef67e0526fb3b31609e04877e0eec32e0b3e0094fa1757  migrations/0014-remove-usage-closed.sql
+a08063b188a91e901d462f73f4f154c98d85068324cef45eb144250e5000051a  migrations/0015-current-work-latest-per-mission.sql
+0acd31e661e720b563b92b3f75f99218dd99011b787ee8aad76b9a3bc1e363c4  migrations/0016-review-drop-retry-counters.sql
+f46823014782c22a9e40b486958770d2b5f7e7180fc9fe6be961a791cca97b50  migrations/0017-retire-mission-import-provenance.sql
+3560376d8e31e0b8fc527509211378a839ba24ef5e5e5fac9ee6dadc06c172c2  migrations/0018-adhoc-mission-counter.sql
+07559cd5363f01a309d028673e6dcb9e222a848fae79c57d2fee9001589da19d  migrations/0019-custom-agent-leases.sql
+0b5d1cd2c31f63f18d543abd23de8efae08ed0692bd1335c9664329e73743d56  package.json
+c7931a2b30343eb509e6d06c8c71d6f0591fbe9bca9029ae8f88781858c8e26c  prompts/act-on-review-core.md
+8f06b68b92c8cfc6f3ee0ff7a1e258258c1a1c2220bdfe5b1a3d5fbaab6befeb  prompts/act-on-review.md
+f5565ff259a2c830e8853573f7a774fb2ce21e1631d457a025d63ebcf9f4ea6a  prompts/draft-core.md
+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  prompts/draft.md
+51b16691ee421a55c5a2da30e62fb8e41c910a5e1e3a16ea45ed6f67aa5e031f  prompts/execute-core.md
+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  prompts/execute.md
+7be9123246e77e669d0bbd7c1f6c6f436f58af0c216cb4ee43fd82824b344bbf  prompts/review-core.md
+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  prompts/review.md
+73d251f710121157b0e0cdabe1919551359f3b3658d8bf59ba6111e9272dfb7d  px.mjs
+f3f642e1a3ac8c624ca8894e9eac29a1eed18073a91b1cd871615263dc364631  px.mjs.map
+fbf9b7bd1d7cf095d0533f064b6aa0bac6b1606268765915a61ae3a7c918089e  sbom.json
+ce7f4aa6eb9e684434f243a64018d4dfa9962348bfdb5d59881783326cc0ec90  templates/mission-scaffold.md
+99784eaf9444cd3b2531bc71976751ffe78f8305f6affe78b8a258e4c9509dd2  web/assets/index-B8Hv3ORh.js
+807f92b40d54c1112d284e7c491702aa90e25edfc32ff5af9f4889beec5583a8  web/assets/index-DYY4ROtr.css
+9464b53a502745042971e980f4b89d1e37300d4eca96e8ab6e0591fb561c5562  web/index.html
+3f454a7af0f992df9a8da22f5a75768d4a4c4fca91d8bc5c5e8a5617882fa7bf  web/manifest.json

package/build/migrations/0001-initial-schema.sql

@@ -0,0 +1,91 @@
+-- Migration: 0001-initial-schema
+-- Description: Create initial operator-local state tables for all six domains
+-- Authority: operator-local only (agent-blocklist, usage-statistics, known-repositories,
+--   ui-preferences, operational-history, migration-ledger)
+-- No repository artifacts are stored in this schema.
+
+-- Agent blocklist: operator-local agent blocking rules
+CREATE TABLE IF NOT EXISTS agent_blocklist (
+  agent TEXT PRIMARY KEY NOT NULL,
+  blocked INTEGER NOT NULL DEFAULT 0,
+  until TEXT,
+  reason TEXT,
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+-- Usage statistics: agent work measurements and completed-mission projections.
+-- Types conform to the TASK-2294 domain model (src/domain/usage.ts): token,
+-- tool-call and round counts are INTEGER; durations, costs and provider-usage
+-- percentages are REAL. NULL means "unavailable" (an unmeasured value), which
+-- maps to the domain's `Measurement<'unavailable'>` kind — distinct from a
+-- measured 0. Free-text and ISO-8601 timestamp columns remain TEXT (SQLite has
+-- no native date type; ISO-8601 text is sortable and idiomatic).
+CREATE TABLE IF NOT EXISTS usage_statistics (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  date TEXT,
+  repo TEXT NOT NULL DEFAULT '',
+  mission TEXT NOT NULL DEFAULT '',
+  classification TEXT,
+  implementer TEXT,
+  pr_fix_rounds INTEGER,
+  provider TEXT,
+  model TEXT,
+  implementer_agent TEXT,
+  reviewer_agent TEXT,
+  stage TEXT DEFAULT 'default',
+  input_tokens INTEGER,
+  output_tokens INTEGER,
+  cached_tokens INTEGER,
+  context_tokens INTEGER,
+  tool_calls INTEGER,
+  openai_usage_before REAL,
+  openai_usage_after REAL,
+  openai_usage_delta REAL,
+  duration_minutes REAL,
+  cost_usd REAL,
+  closed TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_usage_statistics_mission
+  ON usage_statistics(repo, mission, stage);
+
+CREATE INDEX IF NOT EXISTS idx_usage_statistics_date
+  ON usage_statistics(date);
+
+-- Known repositories: operator-local cache of repository identity
+CREATE TABLE IF NOT EXISTS known_repositories (
+  id TEXT PRIMARY KEY NOT NULL,
+  path TEXT NOT NULL,
+  last_accessed TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_known_repositories_path
+  ON known_repositories(path);
+
+-- UI preferences: key-value store for operator-local UI settings
+CREATE TABLE IF NOT EXISTS ui_preferences (
+  key TEXT PRIMARY KEY NOT NULL,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+-- Operational history: local operational event log
+CREATE TABLE IF NOT EXISTS operational_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type TEXT NOT NULL,
+  event_data TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_operational_history_type
+  ON operational_history(event_type);
+
+CREATE INDEX IF NOT EXISTS idx_operational_history_created
+  ON operational_history(created_at);
+
+-- Migration ledger: records applied migrations with checksums
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  id TEXT PRIMARY KEY,
+  checksum TEXT NOT NULL,
+  applied_at TEXT NOT NULL
+);

package/build/migrations/0002-import-history.sql

@@ -0,0 +1,16 @@
+-- Migration: 0002-import-history
+-- Description: Add import history ledger for source path, digest, and idempotency tracking
+-- Authority: operator-local only
+
+CREATE TABLE IF NOT EXISTS import_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_path TEXT NOT NULL,
+  digest TEXT NOT NULL,
+  imported_count INTEGER NOT NULL DEFAULT 0,
+  skipped_count INTEGER NOT NULL DEFAULT 0,
+  imported_at TEXT NOT NULL,
+  backup_path TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_import_history_source
+  ON import_history(source_path);