feat: support allowlisted Pi models and primary effort routing

README.details.md

@@ -279,7 +279,10 @@ this version's format. The minimal weekly configuration is
 whole days and a real `YYYY-MM-DD` calendar date. Optional `skills.allowlist` is an
 array of `{ "name": "…", "source": "…" }` identities with nonempty strings;
 `execution.allowUnsandboxed` is a boolean. Optional top-level `models` supports
-only `luna`, `terra` and `sol`, each a `provider/modelId` string as described below.
+`luna`, `terra` and `sol` as `provider/modelId` strings, plus a nonempty unique
+`allowlist` of exact IDs and `implementPrimaryEffort` of `medium` or `high`.
+Optional top-level `efforts` maps `scout`, `implement`, or `review` to `medium`,
+`high`, or `xhigh`.
 Do not remove a valid `models` mapping. Other fields, including nested extras,
 are rejected; review and manually correct misplaced/unsupported fields rather
 than blindly deleting them or replacing the entire file with the minimal example.
@@ -306,22 +309,33 @@ Use the same OS account for onboarding and the daemon.
 
 Optional `models.luna`, `models.terra` and `models.sol` map Scout, Implement and
 Review profiles to exact Pi `provider/modelId` values. Omitted profiles use the
-Pi default. Configured models must exist in the catalog and support `high`.
-New Scout and Review attempts use `high`; Implement uses `medium` across risk
-levels and retries. High-risk tasks retain the Sol profile; unsupported efforts
-become `needs_replan`.
+Pi default. `models.allowlist` restricts all effective mappings and newly started
+or unfinished recovered attempts to exact IDs. Luna must support `high`, Terra
+must support `implementPrimaryEffort` (default `medium`), and Sol must support
+both `medium` and `high`. New Scout and Review attempts use `high`; primary
+Implement and a retained Terra retry use the configured primary effort;
+high-risk and escalated Implement use Sol at `medium`. Unsupported or denied
+effective mappings fail Pi backend startup before task admission. After startup,
+an advisor with no compatible route or a dispatch or unfinished-recovery policy
+denial stops before a prompt and becomes `needs_replan`.
 Each role gets at most three attempts. A first retry normally keeps its profile;
 model unavailability or the final retry can advance the profile. Existing
 attempts keep their recorded model and effort on restart.
 
-For GPT-6 Astra across all roles, merge this field into existing Roc settings.
-The role routing applies `high` to Scout/Review and `medium` to Implement:
+For a Kimi primary implementer with Codex Scout and independent Review, merge
+this field into existing Roc settings. Pi must already be configured for the
+providers under the daemon account:
 
 ```json
 "models": {
   "luna": "openai-codex/gpt-6-astra",
-  "terra": "openai-codex/gpt-6-astra",
-  "sol": "openai-codex/gpt-6-astra"
+  "terra": "kimi-coding/k3",
+  "sol": "openai-codex/gpt-6-astra",
+  "allowlist": [
+    "openai-codex/gpt-6-astra",
+    "kimi-coding/k3"
+  ],
+  "implementPrimaryEffort": "high"
 }
 ```
 
@@ -344,6 +358,19 @@ normal profile chain (for example Implement moves from Terra to Sol for
 `xhigh`). Raise effort for hard implementation work and lower it for cheap
 scouting when your provider and workload justify it.
 
+When `models.implementPrimaryEffort` is set, it is more specific than
+`efforts.implement`: it applies only to primary Terra Implement work and a
+retained Terra retry. High-risk or escalated Sol Implement uses an explicit
+`efforts.implement` value when present, otherwise `medium`. With an allowlist
+or primary policy, an unavailable Terra primary becomes `needs_replan` rather
+than silently selecting Sol.
+
+Use catalog IDs exactly as Pi reports them. If startup rejects a mapping or
+primary-model effort, correct that profile or effort to a catalog-supported value
+and restart; do not remove the allowlist to force a fallback. If recovery is
+denied after a policy change, inspect the retained descriptor and worktree, then
+create or approve a replan instead of rewriting its historical model or cursor.
+
 For advanced Claude or GLM setup, configure the bundled Pi CLI under the daemon
 account with `bun x --no-install pi`. Use its `/login` and `/model` commands where
 supported and save the default. Provider keys must be in the daemon environment.

docs/architecture.md

@@ -339,22 +339,35 @@ internal module paths when upgrading Pi.
 **Model attribution.** A short-lived probe process answers
 `get_available_models` and `get_state`; the probe's effective default model
 fills profiles omitted from the user's optional `models.luna`, `models.terra`,
-and `models.sol` settings. Explicit mappings must exist in the catalog and
-support `high`, or startup fails with `PI_MODEL_MAPPING_INVALID`. Onboarding
-preserves these mappings. Catalog ids are `provider/modelId` pairs, and each
-attempt re-asserts its routed pair with
+and `models.sol` settings. `models.allowlist` is an optional nonempty exact-ID
+admission list, and `models.implementPrimaryEffort` is `medium` or `high`
+(default `medium`). The backend snapshots both at scheduler startup. Luna must
+support high, Terra the selected primary effort, and Sol medium plus high;
+effective defaults are checked only for profiles they fill. Onboarding preserves
+the complete `models` object. The optional top-level `efforts` snapshot applies
+`medium`, `high`, or `xhigh` per role; its Implement value applies to Sol when
+high-risk or escalated, while `models.implementPrimaryEffort` overrides it only
+for primary Terra and a retained Terra retry. Catalog ids are `provider/modelId`
+pairs, and each attempt re-asserts its routed pair with
 `set_model` plus `set_thinking_level` (Roc efforts map one-to-one onto Pi
 thinking levels). A probe with no resolvable default model fails startup
 with `PI_MODEL_UNRESOLVED` instead of running an unobservable default. The
-resolved default must advertise `high` reasoning; otherwise startup fails with
-`PI_MODEL_UNSUPPORTED` rather than selecting a different model or provider.
+resolved default must satisfy the role requirements for every profile it fills;
+otherwise startup fails rather than selecting a different model or provider.
 
 By default, low- and medium-risk tasks start Scout on Luna, Implement on Terra, and Review
 on Sol. High-risk roles use only Sol. New Scout and Review attempts use `high`,
-while Implement uses `medium` across risk levels and retries. Unsupported
-effort routes the task to `needs_replan`. The operator chooses which actual
-model each profile represents. Existing attempt descriptors remain authoritative
-during recovery; new attempts use the mappings loaded at scheduler startup.
+while primary Implement uses the selected Terra effort and a retained Terra
+retry keeps it. High-risk and escalated Implement use Sol at `medium`.
+An invalid effective mapping, catalog lookup, allowlist, or primary-model effort
+requirement fails backend startup before task admission. An unsupported general
+role effort retains its existing diagnostic and default-effort fallback. After
+startup, an advisor with no compatible route or an allowlist-denied dispatch
+becomes `needs_replan` before a prompt, rather than falling through to Sol. The
+operator chooses which actual model each profile represents. Existing attempt
+descriptors remain authoritative during recovery; an unfinished descriptor denied
+by the run snapshot becomes `needs_replan` without substitution, while
+result-only reconciliation and cleanup remain possible.
 
 Pi Scout capsules use the existing structured output schema without a separate
 byte limit or truncation. Usage delivery and historical role-input recovery

docs/design/pi-multi-model-architecture.json

@@ -0,0 +1,144 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Roc model routing \u00b7 M1 design",
+    "locale": "en",
+    "quality_profile": "showcase",
+    "viewBox": [1290, 680]
+  },
+  "components": [
+    {
+      "id": "operator-settings",
+      "type": "security",
+      "label": "Model settings",
+      "sublabel": "Exact allowlist + effort",
+      "pos": [37.5, 80],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "pi-catalog",
+      "type": "database",
+      "label": "Pi model catalog",
+      "sublabel": "Available IDs + capabilities",
+      "pos": [37.5, 360],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "route-policy",
+      "type": "backend",
+      "label": "Model selector",
+      "sublabel": "Role, risk, retry rules",
+      "pos": [300.0, 220],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "task-scheduler",
+      "type": "backend",
+      "label": "Roc scheduler",
+      "sublabel": "One recorded role attempt",
+      "pos": [562.5, 220],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "attempt-record",
+      "type": "database",
+      "label": "Attempt record",
+      "sublabel": "Model, effort, cursor, result",
+      "pos": [562.5, 470],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "pi-execution",
+      "type": "backend",
+      "label": "Pi role process",
+      "sublabel": "Agent loop + tools",
+      "pos": [825.0, 220],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "codex-model",
+      "type": "external",
+      "label": "Codex model",
+      "sublabel": "Scout, Review, escalation",
+      "pos": [1087.5, 50],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "kimi-model",
+      "type": "external",
+      "label": "Kimi model",
+      "sublabel": "Selected implementer",
+      "pos": [1087.5, 220],
+      "size": [165.0, 80]
+    },
+    {
+      "id": "glm-model",
+      "type": "external",
+      "label": "GLM model",
+      "sublabel": "Selected implementer",
+      "pos": [1087.5, 390],
+      "size": [165.0, 80]
+    }
+  ],
+  "connections": [
+    {
+      "from": "operator-settings",
+      "to": "route-policy",
+      "label": "policy"
+    },
+    {
+      "from": "pi-catalog",
+      "to": "route-policy",
+      "label": "eligibility"
+    },
+    {
+      "from": "route-policy",
+      "to": "task-scheduler",
+      "label": "route",
+      "variant": "emphasis"
+    },
+    {
+      "from": "task-scheduler",
+      "to": "pi-execution",
+      "label": "RPC",
+      "variant": "emphasis"
+    },
+    {
+      "from": "task-scheduler",
+      "to": "attempt-record",
+      "label": "checkpoint",
+      "labelDy": 24
+    },
+    {
+      "from": "pi-execution",
+      "to": "codex-model"
+    },
+    {
+      "from": "pi-execution",
+      "to": "kimi-model"
+    },
+    {
+      "from": "pi-execution",
+      "to": "glm-model"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "One runtime, separate agents",
+      "items": [
+        "Each role uses its own Pi process and session.",
+        "Kimi or GLM is selected for primary implementation."
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Advice and selection have different jobs",
+      "items": [
+        "Model selection uses deterministic rules.",
+        "Architectural advice is not an extra paid routing call."
+      ]
+    }
+  ]
+}