agent-bios 0.3.0 → 0.4.0

package/DEPENDENCIES.md

@@ -12,6 +12,7 @@ Korean: [`ko/DEPENDENCIES.md`](ko/DEPENDENCIES.md). Dates = verification time; u
 | `bash` | `scripts/*.sh` | POSIX + arrays; runs on macOS system bash | 3.2.57 · 2026-07 |
 | `python3` | `scripts/session-cost.py`, `scripts/agent-launch.py` | stdlib for every direct / non-TTY / numbered path; Python 3.11+ (`tomllib`). The interactive preflight additionally needs `textual` (next row) | 3.14.5 · 2026-07-13 |
 | `textual` (managed venv) | `scripts/agent-launch.py` interactive preflight; provisioned by `scripts/provision-venv.sh` | Textual TUI framework in `~/.local/share/agent-launch/venv` (override `AGENT_LAUNCH_VENV`); the launcher re-execs into it on the interactive TTY path only. Absent/broken venv, non-TTY, or `TERM` `dumb`/unset falls back to numbered prompts and never blocks | 8.2.8 · py 3.14.5 · 2026-07-13 |
+| `jsonschema` (system python) | `scripts/check-learning.py` (learning record gate; chained from `scripts/check-parity.sh`) | JSON Schema Draft 2020-12 validator executing `config/learning.schema.json` as the SSOT | 4.26.0 · 2026-07-20 |
 | `zsh` | `shell/agent-launch.zsh` | functions, TTY tests, argument-preserving dispatch | 5.9 · 2026-07-13 |
 | `git` | scripts, workflow (`origin/<base>..HEAD`, worktrees) | modern git; worktree support | 2.50.1 · 2026-07 |
 | coreutils (`mktemp`, `cp`) | `codex-run.sh` hermetic home; `codex-helm.sh` managed home | BSD or GNU | 2026-07 |

package/README.md

@@ -59,6 +59,7 @@ The `agent-bios` CLI deploys this SSOT into your environment by copy — idempot
 ```bash
 npm install -g agent-bios
 agent-bios install     # deploy, back up replaced files, then verify
+agent-bios onboard     # pick domain packages, packaged install, activation canary
 agent-bios verify      # re-check the deployed state matches the source
 agent-bios status      # show what is installed and where
 agent-bios update      # git pull + reinstall (clone), or print the npm update line
@@ -67,7 +68,7 @@ agent-bios uninstall   # remove deployed files and the zsh hook
 
 From a git clone, run `./scripts/install.sh install` directly (the same CLI). `install` respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `AGENT_LAUNCH_VENV`, and `ZDOTDIR`; `--dry-run` prints actions without changing anything. Deploy to **every active environment in one sitting** — a partial deploy leaves a shared global pointing at a guide some environment lacks; globals are English only. Replaced files are backed up under `~/.local/share/agent-bios/backups/<timestamp>/`, and the installed set is recorded in a manifest that `uninstall` consumes. The published npm package ships only the deploy set (never `settings.json`, `config.toml`, `ko/`, or `benchmarks/`).
 
-In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the preset root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. Choose a preset or select **Custom** to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`scripts/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native, onto, and ultracode — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode via `claude --effort ultracode -p` — Claude Code's headless `/workflows` ultracode mode, verified accepted on claude 2.1.210). The concrete reviewer command, resolved absolute path, `llmOverride`, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
+In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **General user** (Vanilla: the bare CLI with no launch contract, no tier bindings, standard permissions; domain presets arrive with the non-technical rollout), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off), **Session distill** — then a preset within it. In Builder, select **Custom** to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`scripts/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native, onto, and ultracode — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, onto via an `llmOverride` to the configured openai seat, ultracode via the `$ultracode-for-codex` Codex skill); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, onto via an `llmOverride` to the anthropic seat, ultracode via `claude --effort ultracode -p` — Claude Code's headless `/workflows` ultracode mode, verified accepted on claude 2.1.210). The concrete reviewer command, resolved absolute path, `llmOverride`, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
 
 At the shell-wrapper boundary, every argument-bearing command (`codex exec ...`, `claude -p ...`) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, `--dangerously-skip-permissions`. `codex --no-tui ...` / `claude --no-tui ...` explicitly take that direct path, and `AGENT_LAUNCH_TUI=0` disables zero-argument TUI interception for a process tree.
 

package/claude/CLAUDE.md

@@ -110,7 +110,8 @@
 - Ambient state — the active shell, cloud CLI project/context, command-name resolution, 'latest'-style pointers, version-bearing paths — drifts silently; where an outcome depends on it, pin it explicitly (a pinned interpreter, --project/--context flags, exact handles, resolved paths) instead of trusting the environment.
 - Before relying on any model id, tool flag, API capability, dependency version, or runtime constraint, confirm it empirically against the live or installed artifact (a minimal probe, the binary's registered options, the installed package version) rather than docs, memory, or a version string.
 - Scope destructive actions (kill, rm, force-push, reset --hard) to targets you own, identified by PID, path, or ancestry — never a broad command-line substring or blanket match — and diagnose the actual state before any irreversible git, remote, or process operation; snapshot the last good state before any in-place resume or overwrite of a completed run, and gate irreversible identity-tied actions (revoke, delete, grant, consent) on a live identity check — never auto-open a browser for a non-default identity (hand the operator the URL).
-- Never accept secrets through transcript- or history-logged channels; provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
+- Never accept secrets through transcript- or history-logged channels.
+- When a secret must be supplied, provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
 - Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
@@ -121,6 +122,7 @@
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
 - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/gpt-prompting.md` for gpt-family targets and `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
+- When the user asks for design AND two or more providers are reachable at frontier tier, run dual-provider frontier design drafts: two independent drafts from the same blind packet, one per provider, compared and synthesized into the working draft. The consent gate is about metered spend, not the fan-out: a provider reached via an OAuth session (subscription-covered, no marginal cost) proceeds WITHOUT asking — if a non-main-context OAuth frontier provider exists, just run the dual-provider design; do not ask. Explicit per-request approval (never standing) is required ONLY before dispatching to a provider reachable solely via a metered API key, and it approves that spend. If withholding un-approved API spend leaves fewer than two providers, run single-provider rather than blocking the design on approval. Inject the corpus design principles (concept economy, LLM/capability boundary, staged workflow) into every dispatched design packet — an external model does not load this corpus.
 - Never retry-storm a live rate limit: give unattended batches you author a code-level circuit breaker with per-item completion tracking (thresholds, backoff, and dead-letter rules in the guide); for third-party dispatchers, confirm equivalent protection exists or attend the run.
 - On any resumed, cleared, or relocated session, re-verify where you are (pwd; in a repo, branch and HEAD) before acting on prior-session assumptions — against the pinned handoff state when one exists.
 

package/claude/guides/cli-multi-model-workflow.md

@@ -108,6 +108,12 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
 - Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED.
 
+## Dual-Provider Design Drafts
+
+- Trigger: the task is design (the staged-workflow guide's design stages) AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
+- Mechanics: compose ONE blind packet (evidence, constraints, rubric, neutral alternatives — the escalation-gate packet shape) and dispatch it unchanged to one frontier-tier model per provider; drafts stay independent — neither sees the other's output. Then adjudicate: compare the two dual-provider frontier design drafts against the rubric, take the winner as the skeleton, graft the loser's superior parts, and record what differed and why the synthesis chose as it did (FRONTIER disposition line).
+- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged-workflow design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
+
 ## Unattended Batch Safety
 
 - The parent owns per-item completion and a **code-level circuit breaker**. For dispatchers you do not control, verify equivalent protection or attend the run.

package/claude/guides/{session-learning-workflow.md → session-distill-workflow.md}

@@ -1,12 +1,12 @@
 ---
-guide_id: session-learning-workflow
+guide_id: session-distill-workflow
 language: en
 status: active
 use_when:
-  - a session was launched with the Session learning preset (mission-injected)
+  - a session was launched with the Session distill preset (mission-injected)
   - the launcher nudge says enough sessions accumulated for a mining window
   - mining local Claude/Codex sessions for learnings absent from the corpus
-  - promoting, incubating, or retiring items in the session-learning ledger
+  - promoting, incubating, or retiring items in the session-distill ledger
 core_rules:
   - the ledger and HANDOFF are the SSOT; read them before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
@@ -15,21 +15,21 @@ core_rules:
   - close the window by updating mirrors, parity, deployment, and the nudge baseline
 ---
 
-# Session-Learning Workflow
+# Session-Distill Workflow
 
-Runbook for a learning-refinement session: mine recent main-context sessions,
+Runbook for a session-distill run: mine recent main-context sessions,
 verify candidates, place them through the framework, and apply with the user.
 Everything durable lives in the agent-bios repo.
 
 ## Read first (SSOT)
 
-1. `design/session-learning/HANDOFF.md` — initiative state, prior decisions,
-   open threads. 2. `design/session-learning/PLACEMENT-FRAMEWORK.md` — the
+1. `design/session-distill/HANDOFF.md` — initiative state, prior decisions,
+   open threads. 2. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the
    placement authority (typology A–G, layers, admission bars, lifecycle).
-3. `design/session-learning/ledger.json` — cumulative item states
+3. `design/session-distill/ledger.json` — cumulative item states
    (placed / incubating / absorbed / retired) with provenance.
 
-## Stage 1 — Mine (pipeline in `scripts/session-learning/`)
+## Stage 1 — Mine (pipeline in `scripts/session-distill/`)
 
 Run in order; each stage reads the previous stage's `out/`:
 
@@ -92,9 +92,9 @@ Run in order; each stage reads the previous stage's `out/`:
 1. Ledger: statuses to placed (with implementation paths) / incubating;
    dated corrections for anything refuted.
 2. HANDOFF: completion record, incidental finds as next-window candidates.
-3. Register the learning version: append {version = window end, commit = the
-   corpus-close commit} to `design/session-learning/versions.json` — this is
+3. Register the corpus version: append {version = window end, commit = the
+   corpus-close commit} to `design/session-distill/versions.json` — this is
    what the launcher's Versions & rollback screen offers — then run
-   `python3 scripts/session-learning/update-state.py --window-end <date>`
-   (nudge baseline) and `learning-state.py project` (launcher status panel).
+   `python3 scripts/session-distill/update-state.py --window-end <date>`
+   (nudge baseline) and `corpus-state.py project` (launcher status panel).
 4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).

package/claude/hooks/tooling-gotchas-hook.py

@@ -2,7 +2,7 @@
 """PreToolUse(Bash) hook: inject tooling-gotchas reminders on matching commands.
 
 Read-only context injection only — never blocks, rewrites, or judges (hook
-charter, design/session-learning/PLACEMENT-FRAMEWORK.md). Message text derives
+charter, design/session-distill/PLACEMENT-FRAMEWORK.md). Message text derives
 from claude/guides/tooling-gotchas.md; edit the guide first, then sync here.
 The verification suite greps each message's anchor phrase against the guide.
 """

package/codex/AGENTS.md

@@ -110,7 +110,8 @@
 - Ambient state — the active shell, cloud CLI project/context, command-name resolution, 'latest'-style pointers, version-bearing paths — drifts silently; where an outcome depends on it, pin it explicitly (a pinned interpreter, --project/--context flags, exact handles, resolved paths) instead of trusting the environment.
 - Before relying on any model id, tool flag, API capability, dependency version, or runtime constraint, confirm it empirically against the live or installed artifact (a minimal probe, the binary's registered options, the installed package version) rather than docs, memory, or a version string.
 - Scope destructive actions (kill, rm, force-push, reset --hard) to targets you own, identified by PID, path, or ancestry — never a broad command-line substring or blanket match — and diagnose the actual state before any irreversible git, remote, or process operation; snapshot the last good state before any in-place resume or overwrite of a completed run, and gate irreversible identity-tied actions (revoke, delete, grant, consent) on a live identity check — never auto-open a browser for a non-default identity (hand the operator the URL).
-- Never accept secrets through transcript- or history-logged channels; provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
+- Never accept secrets through transcript- or history-logged channels.
+- When a secret must be supplied, provide a gitignored env slot, read the value only from the environment, verify its presence and format without echoing it, and advise rotating anything already pasted; assume a resource-creating call may echo the secret back in its success output — suppress or discard the response body, and treat an echoed secret as pasted (rotate).
 - Treat a coarse runtime signal — a failure label, a `ps`/process-inspection result, idle CPU with no output — as a hypothesis, and confirm the cause against the authoritative low-level evidence the mechanism emits before attributing blame or intervening: read the raw provider/skill log payload (e.g. `input_tokens:0` proves a pre-dispatch rejection that exonerates your content and your change), and confirm a config/env toggle reached a subprocess via a cheap artifact the gated branch emits rather than an unreliable `ps` env read. A multi-minute LLM or subprocess call at ~0% CPU with an output gap is the normal signature of I/O wait, not a hang — check process state and the call trace's in-flight duration before acting, so you do not abort healthy long-running work.
 - Before reasoning about what a branch contains or opening a PR, run `git fetch` and compute the range as `origin/<base>..HEAD`, never `<base>..HEAD` against the local tracking ref — on a shared repo the local base drifts behind the remote until you pull, silently inflating the diff with already-merged work; if the range is surprisingly large, suspect a stale base before suspecting the branch. Platform "mergeable" flags are computed against the base only — sibling PRs can each look clean yet conflict; before picking a merge order, diff their changed-file sets and simulate the sequence.
 
@@ -122,6 +123,7 @@
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CODEX_HOME:-$HOME/.codex}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
 - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CODEX_HOME:-$HOME/.codex}/guides/gpt-prompting.md` for gpt-family targets and `${CODEX_HOME:-$HOME/.codex}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
+- When the user asks for design AND two or more providers are reachable at frontier tier, run dual-provider frontier design drafts: two independent drafts from the same blind packet, one per provider, compared and synthesized into the working draft. The consent gate is about metered spend, not the fan-out: a provider reached via an OAuth session (subscription-covered, no marginal cost) proceeds WITHOUT asking — if a non-main-context OAuth frontier provider exists, just run the dual-provider design; do not ask. Explicit per-request approval (never standing) is required ONLY before dispatching to a provider reachable solely via a metered API key, and it approves that spend. If withholding un-approved API spend leaves fewer than two providers, run single-provider rather than blocking the design on approval. Inject the corpus design principles (concept economy, LLM/capability boundary, staged workflow) into every dispatched design packet — an external model does not load this corpus.
 - Never retry-storm a live rate limit: give unattended batches you author a code-level circuit breaker with per-item completion tracking (thresholds, backoff, and dead-letter rules in the guide); for third-party dispatchers, confirm equivalent protection exists or attend the run.
 - On any resumed, cleared, or relocated session, re-verify where you are (pwd; in a repo, branch and HEAD) before acting on prior-session assumptions — against the pinned handoff state when one exists.
 

package/codex/guides/cli-multi-model-workflow.md

@@ -108,6 +108,12 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - A silent/dead lens is incomplete, never clean. Confirm liveness from usage/error/report evidence; rerun, swap provider, or report PROPOSED.
 - Kind labels do not guarantee distinct backends: wrappers and rate-limit fallbacks can silently route two "different-kind" verifiers to the same model/provider. Before trusting diversity on a high-stakes verdict, confirm each verifier's actual backing model from live process or usage evidence; on collapse, treat the pair as one kind and label PROPOSED.
 
+## Dual-Provider Design Drafts
+
+- Trigger: the task is design (the staged-workflow guide's design stages) AND two or more providers are reachable at frontier tier. Reachability via an OAuth session is subscription-covered — no marginal spend, so no approval and no question: if a non-main-context OAuth frontier provider exists, proceed with the dual-provider design directly. The consent gate applies ONLY to a provider reachable solely via a metered API key: dispatching to it needs the user's explicit per-request approval of that spend (per-request, not standing — an old approval does not carry to the next design). If the only way to reach a second provider is un-approved metered API spend, stay single-provider rather than blocking the design.
+- Mechanics: compose ONE blind packet (evidence, constraints, rubric, neutral alternatives — the escalation-gate packet shape) and dispatch it unchanged to one frontier-tier model per provider; drafts stay independent — neither sees the other's output. Then adjudicate: compare the two dual-provider frontier design drafts against the rubric, take the winner as the skeleton, graft the loser's superior parts, and record what differed and why the synthesis chose as it did (FRONTIER disposition line).
+- Packet injection: a dispatched designer is hermetic — it reads only its packet and never loads this corpus. Inject the design principles the corpus would have supplied: concept economy (reuse/extend/rename/split, compact concept graph), the LLM/tools-code capability boundary, the staged-workflow design rules (smallest viable path, falsifiable done-when), and any domain-specific principles the design touches. A draft produced without the principles is not comparable to one produced with them.
+
 ## Unattended Batch Safety
 
 - The parent owns per-item completion and a **code-level circuit breaker**. For dispatchers you do not control, verify equivalent protection or attend the run.

package/codex/guides/{session-learning-workflow.md → session-distill-workflow.md}

@@ -1,12 +1,12 @@
 ---
-guide_id: session-learning-workflow
+guide_id: session-distill-workflow
 language: en
 status: active
 use_when:
-  - a session was launched with the Session learning preset (mission-injected)
+  - a session was launched with the Session distill preset (mission-injected)
   - the launcher nudge says enough sessions accumulated for a mining window
   - mining local Claude/Codex sessions for learnings absent from the corpus
-  - promoting, incubating, or retiring items in the session-learning ledger
+  - promoting, incubating, or retiring items in the session-distill ledger
 core_rules:
   - the ledger and HANDOFF are the SSOT; read them before touching the pipeline
   - placement follows PLACEMENT-FRAMEWORK.md, never ad-hoc judgment
@@ -15,21 +15,21 @@ core_rules:
   - close the window by updating mirrors, parity, deployment, and the nudge baseline
 ---
 
-# Session-Learning Workflow
+# Session-Distill Workflow
 
-Runbook for a learning-refinement session: mine recent main-context sessions,
+Runbook for a session-distill run: mine recent main-context sessions,
 verify candidates, place them through the framework, and apply with the user.
 Everything durable lives in the agent-bios repo.
 
 ## Read first (SSOT)
 
-1. `design/session-learning/HANDOFF.md` — initiative state, prior decisions,
-   open threads. 2. `design/session-learning/PLACEMENT-FRAMEWORK.md` — the
+1. `design/session-distill/HANDOFF.md` — initiative state, prior decisions,
+   open threads. 2. `design/session-distill/PLACEMENT-FRAMEWORK.md` — the
    placement authority (typology A–G, layers, admission bars, lifecycle).
-3. `design/session-learning/ledger.json` — cumulative item states
+3. `design/session-distill/ledger.json` — cumulative item states
    (placed / incubating / absorbed / retired) with provenance.
 
-## Stage 1 — Mine (pipeline in `scripts/session-learning/`)
+## Stage 1 — Mine (pipeline in `scripts/session-distill/`)
 
 Run in order; each stage reads the previous stage's `out/`:
 
@@ -92,9 +92,9 @@ Run in order; each stage reads the previous stage's `out/`:
 1. Ledger: statuses to placed (with implementation paths) / incubating;
    dated corrections for anything refuted.
 2. HANDOFF: completion record, incidental finds as next-window candidates.
-3. Register the learning version: append {version = window end, commit = the
-   corpus-close commit} to `design/session-learning/versions.json` — this is
+3. Register the corpus version: append {version = window end, commit = the
+   corpus-close commit} to `design/session-distill/versions.json` — this is
    what the launcher's Versions & rollback screen offers — then run
-   `python3 scripts/session-learning/update-state.py --window-end <date>`
-   (nudge baseline) and `learning-state.py project` (launcher status panel).
+   `python3 scripts/session-distill/update-state.py --window-end <date>`
+   (nudge baseline) and `corpus-state.py project` (launcher status panel).
 4. Merge the branch, push, and confirm deployed state (`agent-bios verify`).

package/config/agent-launch.toml

@@ -72,6 +72,7 @@ effort = "low"
 [presets.balanced]
 label = "Balanced"
 description = "HELM default for everyday work with native multi-perspective review."
+mode = "builder"
 main_tier = "helm"
 frontier_effort = "max"
 review_setup = "native-panel"
@@ -82,6 +83,7 @@ claude_permission_mode = "bypassPermissions"
 [presets.deep-review]
 label = "Deep review"
 description = "HELM with hybrid onto, native, and Ultracode review at deep FRONTIER effort."
+mode = "builder"
 main_tier = "helm"
 frontier_effort = { codex = "ultra", claude = "max" }
 review_setup = "hybrid"
@@ -92,6 +94,7 @@ claude_permission_mode = "bypassPermissions"
 [presets.fast-batch]
 label = "Fast batch"
 description = "WORKHORSE default for high-volume, cost-conscious execution."
+mode = "builder"
 main_tier = "workhorse"
 frontier_effort = "max"
 review_setup = "native-panel"
@@ -99,19 +102,42 @@ delegation = true
 codex_execution_policy = "bypass"
 claude_permission_mode = "bypassPermissions"
 
-[presets.session-learning]
-label = "Session learning"
-description = "Dedicated learning-refinement session: mine recent sessions, verify, place, and apply per the session-learning workflow."
+[presets.solo]
+label = "Solo"
+description = "Single-model session: delegation off (no tier fan-out; the standing spawn policy is lifted), review via the host's own command only."
+mode = "builder"
+main_tier = "helm"
+frontier_effort = "max"
+review_setup = "none"
+delegation = false
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.vanilla]
+label = "Vanilla"
+description = "Plain CLI session: no launch contract, no tier bindings, standard permissions — exactly what the bare backend gives you."
+mode = "general"
+main_tier = "helm"
+frontier_effort = "max"
+review_setup = "none"
+delegation = false
+codex_execution_policy = "standard"
+claude_permission_mode = "standard"
+
+[presets.session-distill]
+label = "Session distill"
+description = "Dedicated session-distill run: mine recent sessions, verify, place, and apply per the session-distill workflow."
+mode = "distill"
 main_tier = "helm"
 frontier_effort = "max"
 review_setup = "hybrid"
 delegation = true
 codex_execution_policy = "bypass"
 claude_permission_mode = "bypassPermissions"
-mission = "This is a session-learning initiative session, gated on a trigger. When the user enters the trigger command '{trigger}': read the session-learning-workflow guide in your installed guides directory, then the initiative SSOT design/session-learning/HANDOFF.md in the agent-bios repo, and run the next mining window per that guide. Until the trigger arrives, respond normally and do not start the workflow. Every promotion passes through explicit user approval; nothing is applied to the corpus without it."
-trigger = "learn!"
+mission = "This is a session-distill initiative session, gated on a trigger. When the user enters the trigger command '{trigger}': read the session-distill-workflow guide in your installed guides directory, then the initiative SSOT design/session-distill/HANDOFF.md in the agent-bios repo, and run the next mining window per that guide. Until the trigger arrives, respond normally and do not start the workflow. Every promotion passes through explicit user approval; nothing is applied to the corpus without it."
+trigger = "distill!"
 
-# Nudge baseline lives in ~/.local/share/agent-bios/session-learning-state.json,
-# written by scripts/session-learning/update-state.py at window close.
-[session_learning]
+# Nudge baseline lives in ~/.local/share/agent-bios/session-distill-state.json,
+# written by scripts/session-distill/update-state.py at window close.
+[session_distill]
 nudge_after = 250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bios",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
     "agent-bios": "scripts/install.sh"