fix(agents): enforce exact profile model identity (#3473)

Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Alassane
2026-09-15 18:11:43 -04:00
committed by GitHub
parent 4ef775afc9
commit 739eabc49a
141 changed files with 4136 additions and 2338 deletions
@@ -1,6 +1,6 @@
# ADR-2026-08-15: Let the Executor Own Model Selection
**Status:** accepted
**Status:** superseded by 2026-09-06-exact-profile-model-identity
**Date:** 2026-08-15
**Area:** backend, frontend, protocol, persistence
@@ -0,0 +1,44 @@
# ADR-2026-09-06-exact-profile-model-identity: Enforce Exact Profile Model Identity
**Status:** superseded by 2026-09-15-explicit-profile-model-strictness
**Date:** 2026-09-06
**Area:** backend, frontend, protocol, persistence, workflow
See [the per-profile opt-in amendment](2026-09-15-explicit-profile-model-strictness.md).
The original decision below is historical; its implicit default is superseded.
## Context
An executor catalog remains authoritative for whether a model can be selected,
but allowing its default after an exact profile's model is absent changes the
user's chosen runtime identity and cost policy before the first prompt.
## Decision
A profile with a non-empty model, `auto_fallback = false`, and no
`fallback_model` is exact. Its configured model must be advertised and applied
before inference. If that cannot be attested, the session fails before a
prompt, tool call, or agent output.
Kandev never sends `SetModel` for an unadvertised model. An advertised explicit
fallback is the only authorized alternate model when auto fallback is off.
`auto_fallback = true` explicitly authorizes continuation on the executor
default and keeps its durable warning behavior. This same decision applies on
initial launch, context reset, and fresh workspace rebind.
## Consequences
Exact profiles can fail when an executor, account, or pinned runtime does not
advertise their configured model. The failure records sanitized requested,
effective-when-known, and stable mismatch-reason evidence. Existing workflow
profile precedence and intentional same-session runtime overrides remain
unchanged.
## Alternatives Considered
1. Continue on the executor default for every catalog mismatch. Rejected
because it silently substitutes the chosen model identity.
2. Send an unadvertised model selection request. Rejected because the executor
catalog is still the availability authority.
3. Rewrite the saved profile from an executor observation. Rejected because a
transient executor/account state must not mutate the user's profile.
@@ -1,9 +1,12 @@
# ADR-2026-09-07: Resolve Only One Advertised Model Variation
**Status:** proposed
**Status:** superseded by 2026-09-15-explicit-profile-model-strictness
**Date:** 2026-09-07
**Area:** backend, frontend, protocol
**Amends:** `2026-08-15-executor-authoritative-model-selection`
The historical rejection below is superseded by the
[compatible-only variation rule](2026-09-15-explicit-profile-model-strictness.md).
Explicit strict profiles continue to reject inferred variations.
## Context
@@ -20,55 +23,25 @@ Variation text is provider-owned. Kandev cannot safely rank `270k`, `1m`,
`fast`, or future labels. Catalog order and the current-model marker do not
express user intent.
## Decision
## Rejection
Kandev recognizes a model variation only by a narrow bracketed ID shape. A bare
requested ID `x` matches an advertised ID `x[v]` when `v` is non-empty and
contains no bracket. Matching is exact and case-sensitive. Kandev treats `v` as
opaque text.
This proposal was not adopted. It would have inferred a bracketed advertised
model from a bare profile model and treated that inferred ID as an authorized
selection. That conflicts with the accepted exact-profile boundary: an
inferred ID is a different runtime identity from the configured model.
For profiles with `auto_fallback = false`, the executor-authoritative resolution
order is:
No variation-matching algorithm, inferred-selection outcome, warning reason,
or launch, reset, or workspace-rebind behavior was adopted from this proposal.
The accepted policy is recorded exclusively in
[Enforce Exact Profile Model Identity](2026-09-06-exact-profile-model-identity.md).
1. Exact requested model.
2. Advertised explicit fallback from the profile.
3. One distinct advertised variation of the requested bare model.
4. Provider current or default model, with no speculative model-selection call.
## Consequences of rejection
Kandev applies step 3 only when exactly one distinct candidate exists. Zero or
multiple candidates produce no inferred selection. An unadvertised explicit
fallback does not block step 3.
A requested ID that contains a bracket is an exact ID only. Kandev does not
infer another variation from it.
Profiles with `auto_fallback = true` retain the legacy path when the requested
model is absent. Kandev ignores the configured explicit fallback, does not
infer a variation, and continues with the provider current or default model.
Apply errors for an advertised model remain best-effort in that mode.
The lifecycle stores `unique_variation` as the decision outcome and
`unique_variation_applied` as the warning reason. The effective model contains
the advertised variation. The explicit fallback field keeps its existing
meaning and stays empty when Kandev infers a variation.
The saved profile model does not change. The rule runs for initial launch,
context reset, and workspace rebind. The executor catalog remains authoritative.
Any host-catalog result remains an advisory.
## Consequences
- A profile with `opus` follows `opus[1m]` when it is the only advertised
variation.
- A catalog with `opus[270k]` and `opus[1m, fast]` remains ambiguous and uses
the existing provider-default path.
- An explicit advertised fallback remains stronger than inference.
- Kandev never sends a model ID that the executor did not advertise.
- Users receive a durable warning because the effective model differs from the
saved request.
- Provider-specific ranking logic does not enter the lifecycle policy.
- Backend and frontend helpers need mirrored contract tests. The backend result
remains authoritative when their input catalogs differ.
- The historical `opus` to `opus[1m]` example does not authorize inference.
- Provider-specific variation labels and catalog order do not establish a
substitute model identity.
- Any future variation policy requires a new accepted decision that is
compatible with exact-profile identity.
## Alternatives Considered
@@ -0,0 +1,51 @@
# ADR-2026-09-15-explicit-profile-model-strictness: Make Exact Model Selection a Profile Opt-in
**Status:** accepted
**Date:** 2026-09-15
**Area:** backend, frontend, persistence, workflow
## Context
PR #3473 makes existing profiles strict when automatic fallback is false and
no explicit fallback is saved. These values previously permitted executor-default
continuation in catalog mismatch cases. Existing stored values do not prove
that a user selected strict behavior. Upgrading must not introduce that failure.
## Decision
Add a per-profile `require_exact_model` setting, default false for existing and
new profiles. Strictness takes priority over dormant fallback choices. Turning
it off restores those saved choices without rewriting them. Require a concrete
model when strictness is enabled. Do not add a global or workspace override.
Compatible profiles retain the pre-PR selection/error behavior, including the
single advertised variation rule. Strict profiles never infer variations and
fail before inference when the requested model cannot be advertised and applied.
Both paths retain executor authority, unchanged saved model IDs, and durable
fallback warnings. No policy sends an unadvertised model.
This decision supersedes
[implicit exact-profile identity](2026-09-06-exact-profile-model-identity.md).
It replaces the blanket variation rejection recorded in
[the variation decision](2026-09-07-unique-model-variation-resolution.md) with a
compatible-only rule. The implementation is tracked in the
[PR package](../plans/exact-profile-model-identity/plan.md).
## Consequences
Upgrades preserve working mismatch launches without enabling broader automatic
fallback. Profiles can enforce exactness independently across executors. The
additional field must traverse storage, APIs, profile copies, runtime resolution,
and all editors. Existing fallback values remain dormant while strictness is on.
Office post-start provider routing remains separately workspace-owned.
## Alternatives Considered
- Infer strictness from existing false/empty fields: changes existing launch
behavior and cannot distinguish an explicit decision from a default.
- Set automatic fallback true on every old profile: ignores explicit fallback
models and tolerates errors that previously stopped the launch.
- Replace current fields with an enum: adds migration scope and risks losing
existing fallback/error distinctions for this compatibility fix.
- Add global and profile settings: creates inheritance/precedence rules and
broad effects unrelated to an individual profile's identity policy.
@@ -0,0 +1,205 @@
---
created: 2026-09-14
status: implemented
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
system_design:
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
legacy_specs: []
---
# Implementation Plan: Exact Profile Model Identity as an Explicit Opt-in
## Overview
Revise PR #3473 so existing remote-executor launches keep their pre-PR model
fallback behavior. Add Require exact model as a per-profile opt-in, default off.
Implement storage/API/runtime policy first, then profile editors, then end-to-end
acceptance and public documentation. All new work orders are sequential.
This package was requested on 2026-09-15 and is implemented as a maintainer
fixup on the contributor branch. The plan, work orders, requirements, design,
tests, and public guidance are included with the implementation.
## Baseline and completed work
Implementation baseline: `561d2a8cf0d5c30224696304839a550952331ebe`.
Reviewed PR head: `561d2a8cf0d5c30224696304839a550952331ebe`.
The two intervening commits only retrigger CI; their tree diff is empty.
Compatibility oracle: pre-PR merge base
`ba960f973205854733e0dcd9afa355bdda3dddf6`.
The implementation was based on this contributor head and preserves the
completed transport and reuse fixes.
Task 01 records the completed strict-by-default implementation. Preserve its
transport staging, replacement catalog event handling, single validated reuse
lookup, and durable warnings. Its old inferred strict predicate is superseded
by the new explicit field. Existing green tests do not prove upgrade compatibility.
## Scope
### In scope
- False-by-default persisted `require_exact_model` through every profile path.
- Strict mode precedence over dormant fallback values; no destructive migration.
- Compatible launch/error behavior, including runtime-only unique variations.
- Shared launch/reset/rebind/recovery policy and explicit strict workflow reuse.
- Desktop/mobile profile editors, settings discovery, copy, and public guides.
- Actual store-upgrade-to-launch evidence and strict/non-strict regressions.
### Out of scope
Global/workspace/executor policy, runtime feature flags, provider authentication,
Office post-start routing changes, a live-session model lock, new provider APIs,
and unrelated PR cleanup. Do not recreate completed transport fixes.
## Technical approach
The [requirement](../../specs/agents/requirements/no-silent-model-fallback.md)
and [policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
own the behavior matrix, migration, precedence, and transport contracts.
[Recovery and UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
owns replacement-catalog handling, workflow eligibility, and profile surfaces.
The [ADR](../../decisions/2026-09-15-explicit-profile-model-strictness.md)
records why strictness is per profile and why old auto-fallback fields remain.
Extend the existing profile store and DTO contract, `StartModelPolicy`, profile
resolvers, executor/backend adapters, and profile snapshots. Gate strict checks
on the new field. Preserve legacy omissions on partial update. Compatible mode
must not be implemented by setting `AutoFallback=true`: that changes fallback
priority and error tolerance. Extend existing React shared fallback components.
No new state-management or provider abstraction is needed.
## ASCII UI preview
### UI-01: Desktop profile, expanded Fallback settings
Entry: Settings > Agents > profile. Default state; strictness is off.
```text
Start model [ saved model v ]
Fallback settings v Executor default allowed
+------------------------------------------------------------+
| Require exact model [ OFF ] |
| Stop before starting if the selected model cannot be used. |
| Fallback settings do not apply while this is on. |
+-----------------------------+------------------------------+
| Automatic fallback [ OFF ] | Explicit fallback [ OFF ] |
| Existing help and controls | Existing help and controls |
+-----------------------------+------------------------------+
[ Cancel ] [ Save ]
```
Strict on: summary becomes "Exact model required". Both fallback cards remain
visible and disabled, including their switches. Existing values remain saved.
Strict off restores their prior states. The fallback selector appears only when
its existing enable switch is on.
A strict+empty-model validation error appears beside the model field; Save
keeps the draft open. Collapsed state retains the summary and dirty indicator.
### UI-02: Phone profile, expanded Fallback settings
```text
< Agent profile
Start model
[ saved model v ]
Fallback settings v
Executor default allowed
+----------------------------------+
| Require exact model [ OFF ] |
| Stop before starting if the |
| selected model cannot be used. |
| Fallback settings do not apply |
| while this is on. |
+----------------------------------+
| Automatic fallback [ OFF ] |
| Visible helper text (i) |
+----------------------------------+
| Explicit fallback [ OFF ] |
| Visible helper text (i) |
+----------------------------------+
[ Cancel ] [ Save ]
```
The existing page/editor scrolls as one form. Help opens the shared inset
bottom drawer and returns focus on close. Switch rows and help targets have
at least 44px touch hit areas; desktop ordinary controls keep 28px sizing.
Strict-on, collapsed, and validation states have the same semantics on phone.
Long translations wrap without horizontal overflow or hiding Save.
Order, grouping, visible disabled values, and shared state are requirements;
ASCII spacing and the illustrative model names are not pixel specifications.
UI-01/UI-02 map to AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6 and .7.
## Tests
The following checks were run after implementation.
| Acceptance | Evidence |
| --- | --- |
| 001.1/.4/.5, 002.1 | Lifecycle policy table and focused lifecycle run passed. It covers strict/compatible selection, fallback precedence, apply errors, and unique variations. |
| 001.3/.6 | SQLite migration, round-trip, explicit clear, schema replay, controller validation, and generated discovery checks passed. Postgres evidence was not run because no isolated `KANDEV_TEST_POSTGRES_DSN` was available. |
| 001.1/.3/.8 | Lifecycle reset, rebind, replacement, and profile-resolution regressions passed in the focused run. |
| 001.8 | Replacement-client catalog, cancellation, and strict reset/rebind tests passed in the focused lifecycle run. |
| 001.9 | Focused orchestrator model/profile/reuse/drift tests passed, including strict unknown drift and the validated empty candidate path. |
| 001.2/.10 | Existing desktop/mobile mismatch E2E tests passed with explicit strict fixtures and persisted compatible warnings. |
| 001.6/.7 | Frontend normalization, settings, editor, dirty/reconciliation, and CLI tests passed; typecheck, i18n checks, and targeted lint passed. |
## E2E tests
Extend existing specs; do not replace strict fixtures with compatible fixtures
and lose strict coverage. Set `require_exact_model=true` in strict fixtures.
| File under apps/web/e2e/tests | Project | Acceptance and scenario |
| --- | --- | --- |
| `settings/no-silent-model-fallback.spec.ts` | chromium | 001.6/.7/.10: default off, enable/save/reload, disable restores dormant settings, strict validation keeps form open, desktop help and dimensions |
| `settings/mobile-no-silent-model-fallback.spec.ts` | mobile-chrome | 001.6/.7: same edit/save/reload flow, drawer dismiss then toggle/save, 44px hit targets, no overflow, long labels |
| `session/model-mismatch-warning.spec.ts` | chromium | 001.1/.2/.3/.4/.5: old-style profile omits field and starts on default with one reloaded warning; explicit strict profile fails before prompt; explicit fallback and auto=true remain distinct |
| `session/mobile-model-mismatch-warning.spec.ts` | mobile-chrome | 001.1/.2/.6: phone selection/launch reflects saved compatible/strict policy; warning survives reload |
Mock E2E proves the user flow. The store-to-transport regression proves actual
migration compatibility; the Kubernetes transport test proves replacement
catalog ownership. None substitutes for the others.
## Work orders
- [x] [Task 01: Historical strict identity implementation](task-01-enforce-launch-identity.md)
- [x] [Task 02: Persist and apply explicit strictness](task-02-explicit-profile-policy.md)
- [x] [Task 03: Expose profile controls on desktop and phone](task-03-profile-strictness-controls.md)
- [x] [Task 04: Prove user flows and update public guides](task-04-compatibility-acceptance.md)
## Verification results
Implementation checks passed on 2026-09-15 unless noted below:
- `python3 scripts/list-docs.py validate`: 269 decisions and 902 specifications.
- `python3 scripts/lint-spec-files.test.py`: 36 tests passed.
- `python3 scripts/lint-spec-files.py --all`: all specification files passed.
- `git diff --check`: passed.
- Backend focused lifecycle, settings, controller, handlers, executor, backendapp,
and orchestrator checks passed. A broader combined run reached unrelated
pre-existing orchestrator failures and an SSH close test timeout; the changed
focused tests passed.
- Frontend typecheck and 83 focused Vitest tests passed.
- Desktop settings E2E: 3 passed. Mobile settings E2E: 3 passed.
- Desktop session E2E: 2 passed. Mobile session E2E: 2 passed.
- Public docs validators and specification validators passed.
- `go run ./cmd/settings-catalog -check`, `pnpm run i18n:check`, and
`pnpm run i18n:ratchet` passed.
- Package-relative links and work-order REQ/AC references resolve.
- Catalog queries discover the amended specs and the new decision.
The Postgres migration check remains explicitly pending until an isolated test
DSN is available. The implementation does not change the Postgres migration
contract, but SQLite and all application projections are covered.
## Risks
- Missing a DTO/draft/copy path can silently clear or drop strictness.
- A bulk auto-fallback migration can change fallback priorities and tolerated errors.
- Treating a recovery timeout as transport success can hide a broken session.
- Old session snapshots omit the new field; they must not imply strictness.
- Restoring compatible variation selection must never affect strict mode or edit saved IDs.
- Existing custom TUI/dynamic profiles do not have an enforceable concrete ACP model.
- Supported Postgres migration evidence requires an isolated test database; a skipped test is not a pass.
@@ -0,0 +1,53 @@
---
id: "01-enforce-launch-identity"
title: "Enforce exact profile model identity before inference"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
acceptance_criteria:
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2
system_design:
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
---
# Task 01: Enforce Exact Profile Model Identity
## Historical scope
This work order is complete for the original PR implementation. The 2026-09-15
amendment in [Task 02](task-02-explicit-profile-policy.md) supersedes its implicit
strict predicate. Its transport, warning, and validated-reuse fixes remain.
The original scope below is historical, not the current compatibility contract.
## Change
Apply the shared start-model policy before the first inference on every
launch path: initial session start, context reset, and fresh ACP
workspace-rebind sessions. A concrete profile with a non-empty model,
`auto_fallback=false`, and no `fallback_model` must fail the launch before
a prompt or tool call when the executor does not advertise the configured
model; no speculative `SetModel` is sent for an unadvertised model.
Workflow step entry must also isolate stale runtime identity: a parked
session whose persisted provider model disagrees with the destination
profile's configured model policy is replaced with a fresh session before
any auto-start prompt runs. Explicit `fallback_model` and `auto_fallback`
profiles remain the only authorized deviation paths, each with one durable
warning.
## Verification
- `go test ./internal/agent/runtime/lifecycle` covers
`TestApplyStartModelPolicy` behavior for advertised, fallback, and
unauthorized substitution cases (`start_model.go`,
`start_model_executor_authority_test.go`).
- `go test ./internal/orchestrator` covers session isolation on workflow
entry (`event_handlers_workflow.go`,
`event_handlers_workflow_profile_session_policy_resolution_test.go`,
`event_handlers_workflow_profile_session_policy_test.go`).
- Turn/message attribution and pre-prompt warnings agree on the effective
model; failures never expose credentials or provider secrets.
@@ -0,0 +1,130 @@
---
id: "02-explicit-profile-policy"
title: "Persist and apply explicit profile strictness"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
acceptance_criteria:
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.8
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.9
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.1
system_design:
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
---
# Task 02: Persist and apply explicit profile strictness
## Summary
Deliver an independently testable backend/API policy from persisted profile to prompt.
## In scope
Deliver an independently testable backend/API policy from persisted profile to prompt.
Add the additive false-default migration and profile field across storage,
DTO/controller/handler mappings, discovery schema, copy/import paths, resolvers,
internal projections, and session snapshots. Keep omitted partial updates intact.
Validate strict+empty/dynamic/passthrough without invalidating legacy profiles.
Regenerate discovery snapshots with the existing generator.
Extend the shared policy with explicit strictness and restore compatible
selection/error behavior from the oracle. Update reset/rebind/replacement waits
and workflow drift eligibility. Preserve fresh-client-only evidence, cancellation,
validated reuse candidates, prompt ordering, and warning persistence.
Add a real legacy-store-to-agentctl/lifecycle launch regression. Exercise normal
launch and all replacement boundaries. Do not only test synthetic policy structs.
Parameterize the real store migration/round-trip evidence for SQLite and Postgres.
Add projection tests proving true and false reach the runtime and snapshot.
## Out of scope
Global policy, provider authentication, Office post-start routing redesign,
unrelated cleanup, and publication.
## Acceptance
- A migrated old profile launches through the real lifecycle/transport boundary
under the same missing-model conditions as before. Explicit strictness stops
that launch before its prompt. Saved fallback fields remain identical.
- The complete policy matrix, partial-update/copy paths, and generated contract
pass. Strictness survives every projection, including dynamic candidate resolution.
- Recovery and workflow tests preserve existing fixes while applying the new
flag, with deterministic delayed events, cancellation, and empty reuse lookup.
## Verification
Run from the repository root. Use TDD for changed logic; first record the
behavioral failure, then run the listed checks after implementation.
```bash
(cd apps/backend && go run ./cmd/settings-catalog)
(cd apps/backend && go test ./internal/agent/settings/... ./internal/agent/runtime/agentctl ./internal/agent/runtime/lifecycle ./internal/orchestrator/... ./internal/backendapp)
(cd apps/backend && go run ./cmd/settings-catalog -check)
: "${KANDEV_TEST_POSTGRES_DSN:?Set an isolated Postgres test DSN before this check}"
(cd apps/backend && go test -count=1 ./internal/agent/settings/store -run 'TestPostgres.*(RequireExactModel|Schema)')
git diff --check
```
## Files likely touched
- `apps/backend/internal/agent/settings/{models,dto,store,controller,handlers}/`
- `apps/backend/internal/agent/settings/store/sqlite_require_exact_model_test.go` (new)
- `apps/backend/internal/agent/runtime/lifecycle/{types,profile_resolver,manager_profile,start_model}.go`
- `apps/backend/internal/agent/runtime/lifecycle/{session,manager_interaction,manager_workspace_rebind,manager_kubernetes_refresh}.go`
- `apps/backend/internal/agent/runtime/lifecycle/profile_model_upgrade_test.go` (new)
- Existing lifecycle model, reset, rebind, and remote transport tests.
- `apps/backend/internal/orchestrator/event_handlers_workflow.go` and profile session policy tests.
- `apps/backend/internal/orchestrator/executor/{executor,executor_execute}.go` and tests.
- `apps/backend/internal/backendapp/adapters.go` and projection tests.
- `apps/web/lib/settings-discovery/{contract,profile-contract}.generated.json` (generator output).
## Dependencies
None; preserve Task 01 transport and candidate-lookup fixes.
## Risks
Do not convert old auto=false values into strict intent. Do not swallow
initialization/transport errors as missing catalogs. Postgres tests must actually
run with an isolated DSN. A stale cached profile must not lose true strictness.
## Parallelism
`sequential`
## Inputs
- [Requirements](../../specs/agents/requirements/no-silent-model-fallback.md)
- [Policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
- [Recovery/UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
- [Plan and regression matrix](plan.md)
- Scoped AGENTS.md, existing tests beside the affected code, and compatibility
behavior at `ba960f973205854733e0dcd9afa355bdda3dddf6`.
## Results
Implemented on 2026-09-15. The profile field now has an additive SQLite
migration, full DTO/controller/handler/store mappings, generated discovery
contracts, runtime lifecycle and workflow propagation, strict and compatible
selection behavior, and validation for unsupported profile kinds. Existing
fallback values remain dormant while strictness is enabled and survive an
explicit disable.
Focused settings, lifecycle, executor, backend adapter, and orchestrator tests
passed. The broader combined backend command reached unrelated pre-existing
orchestrator failures and an SSH close test timeout. The Postgres-specific
check was skipped because `KANDEV_TEST_POSTGRES_DSN` was not available.
@@ -0,0 +1,176 @@
---
id: "03-profile-strictness-controls"
title: "Expose strictness in both profile editors"
status: done
wave: 2
depends_on: ['02-explicit-profile-policy']
plan: "plan.md"
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
acceptance_criteria:
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.7
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10
system_design:
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
---
# Task 03: Expose strictness in both profile editors
## Summary
Expose the saved profile setting through both existing editor paths.
## In scope
Expose the saved profile setting through both existing editor paths.
Update normalized/HTTP types, serialization, draft state, dirty comparison,
reconciliation, settings store options, discovery inventory, and editor submit
payloads. Add the full-width strict row above the existing fallback cards.
Preserve dormant values, disabled states, and deterministic summaries.
Update the lighter CLI profile editor and shared fallback fields too.
Use visible localized copy and existing error presentation for strict+empty
validation. Save errors retain the draft. Implement UI-01/UI-02 with shared state,
existing page scrolling, touch drawer help, focus return, and target sizing.
Translate en/pt-pt/zh-cn, generate zh-hk/zh-tw and pseudo; adjust summaries that
currently imply all auto=false profiles are strict. Keep host warnings advisory.
## Out of scope
Global policy, provider authentication, Office post-start routing redesign,
unrelated cleanup, and publication.
## Acceptance
- True, false, and omitted fields round-trip through both editors; Save/Cancel,
reload hydration, dirty state, and partial updates preserve the intended value.
- Strictness overrides dormant settings in summaries and disabled controls;
toggling it off restores them. Validation errors keep drafts open.
- Both editor paths satisfy UI-01/UI-02, localization, and focused component
tests. No global setting or second mobile policy is introduced.
## ASCII UI preview
### UI-01: Desktop profile, expanded Fallback settings
Entry: Settings > Agents > profile. Default state; strictness is off.
```text
Start model [ saved model v ]
Fallback settings v Executor default allowed
+------------------------------------------------------------+
| Require exact model [ OFF ] |
| Stop before starting if the selected model cannot be used. |
| Fallback settings do not apply while this is on. |
+-----------------------------+------------------------------+
| Automatic fallback [ OFF ] | Explicit fallback [ OFF ] |
| Existing help and controls | Existing help and controls |
+-----------------------------+------------------------------+
[ Cancel ] [ Save ]
```
Strict on: summary becomes "Exact model required". Both fallback cards remain
visible and disabled, including their switches. Existing values remain saved.
Strict off restores their prior states. The fallback selector appears only when
its existing enable switch is on.
A strict+empty-model validation error appears beside the model field; Save
keeps the draft open. Collapsed state retains the summary and dirty indicator.
### UI-02: Phone profile, expanded Fallback settings
```text
< Agent profile
Start model
[ saved model v ]
Fallback settings v
Executor default allowed
+----------------------------------+
| Require exact model [ OFF ] |
| Stop before starting if the |
| selected model cannot be used. |
| Fallback settings do not apply |
| while this is on. |
+----------------------------------+
| Automatic fallback [ OFF ] |
| Visible helper text (i) |
+----------------------------------+
| Explicit fallback [ OFF ] |
| Visible helper text (i) |
+----------------------------------+
[ Cancel ] [ Save ]
```
The existing page/editor scrolls as one form. Help opens the shared inset
bottom drawer and returns focus on close. Switch rows and help targets have
at least 44px touch hit areas; desktop ordinary controls keep 28px sizing.
Strict-on, collapsed, and validation states have the same semantics on phone.
Long translations wrap without horizontal overflow or hiding Save.
Order, grouping, visible disabled values, and shared state are requirements;
ASCII spacing and the illustrative model names are not pixel specifications.
UI-01/UI-02 map to AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6 and .7.
Full context: [plan previews](plan.md#ascii-ui-preview). Rendered desktop/mobile
acceptance runs in Task 04 after this work order.
## Verification
Run from the repository root. Use TDD for changed logic; first record the
behavioral failure, then run the listed checks after implementation.
```bash
(cd apps && pnpm install --frozen-lockfile)
(cd apps/web && pnpm run i18n:zh-hant && pnpm run i18n:pseudo)
(cd apps/web && pnpm exec vitest run lib/api/domains/agent-profile-normalize.test.ts components/settings/profile-form-fields.test.tsx components/settings/agent-profile-dirty.test.ts components/settings/agent-profile-reconciliation.test.ts components/agent/cli-profile-editor.test.tsx lib/settings-discovery)
(cd apps/web && pnpm run typecheck && pnpm run i18n:check && pnpm run i18n:ratchet)
(cd apps/web && pnpm exec eslint components/settings/profile-model-fields.tsx components/settings/profile-form-fields.tsx components/settings/model-fallback-settings-shell.tsx components/settings/profile-capability-helpers.tsx components/settings/agent-profile-page.tsx components/settings/agent-profile-page-state.ts components/settings/agent-profile-dirty.ts components/settings/agent-profile-reconciliation.ts components/agent/cli-profile-editor.tsx components/agent/cli-profile-fallback-fields.tsx lib/types/agent-profile.ts lib/api/domains/agent-profile-normalize.ts lib/state/slices/settings/types.ts lib/settings-discovery)
git diff --check
```
## Files likely touched
- `apps/web/lib/types/agent-profile.ts`
- `apps/web/lib/api/domains/agent-profile-normalize.ts` and tests.
- `apps/web/lib/state/slices/settings/types.ts`
- `apps/web/lib/settings-discovery/{profile-contract,coverage-inventory}.ts` and tests.
- `apps/web/components/settings/profile-{form-fields,model-fields,capability-helpers}.tsx`
- `apps/web/components/settings/model-fallback-settings-shell.tsx`
- `apps/web/components/settings/agent-profile-{page,page-state,dirty,reconciliation}.ts*`
- `apps/web/components/agent/cli-profile-{editor,fallback-fields}.tsx`
- Existing component tests and new `apps/web/components/settings/agent-profile-dirty.test.ts`.
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw,pseudo}/settings.json`
## Dependencies
['02-explicit-profile-policy']; preserve Task 01 transport and candidate-lookup fixes.
## Risks
The two editor paths have separate form data; a shared shell alone does not
prove payload parity. A dormant auto=true value must not override strictness.
Record generated locale changes and avoid unrelated translation drift.
## Parallelism
`sequential`
## Inputs
- [Requirements](../../specs/agents/requirements/no-silent-model-fallback.md)
- [Policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
- [Recovery/UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
- [Plan and regression matrix](plan.md)
- Scoped AGENTS.md, existing tests beside the affected code, and compatibility
behavior at `ba960f973205854733e0dcd9afa355bdda3dddf6`.
## Results
Implemented on 2026-09-15. Desktop and CLI profile editors now share the
localized strictness row, preserve dormant fallback values, disable fallback
controls while strictness is enabled, and include the field in dirty state,
normalization, reconciliation, save payloads, and settings discovery. The
mobile layout keeps the existing drawer and form scroll owner.
Typecheck, i18n checks, targeted lint, and 83 focused frontend tests passed.
@@ -0,0 +1,144 @@
---
id: "04-compatibility-acceptance"
title: "Prove user flows and update public guidance"
status: done
wave: 3
depends_on: ['03-profile-strictness-controls']
plan: "plan.md"
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
acceptance_criteria:
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.7
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.8
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.9
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10
system_design:
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
---
# Task 04: Prove user flows and update public guidance
## Summary
Complete desktop/mobile acceptance and align public guidance with the implementation.
## In scope
Complete desktop/mobile acceptance and align public guidance with the implementation.
Extend all four existing specs named in the plan's E2E matrix. Keep strict
fixtures explicit and add omitted-field compatible fixtures. Edit/save/reload
through the UI; inspect visible errors and one persisted warning. Retain backend
pre-prompt assertions from Task 02; chat visibility alone does not prove no inference.
Cover both editor surfaces, dormant fallback restoration, strict+empty validation,
keyboard interactions, drawer dismissal/focus, touch bounds, and overflow.
Update the reference sections in `docs/public/agents-and-profiles.md` and the
explanation in `docs/public/executors.md`. Explain per-profile default off, upgrade
compatibility, exact full-ID selection, and ordinary apply errors vs automatic
fallback. Search README/screenshots and linked specs/decisions for old implicit
strict claims. Keep completed transport fixes and managed-runtime documentation.
Reconcile historical Task 01's scope notice, all new work-order results, and
specification status after actual implementation checks pass. Refresh PR head/base
read-only before handoff. Do not push, comment, or commit under this work order.
## Out of scope
Global policy, provider authentication, Office post-start routing redesign,
unrelated cleanup, and publication.
## Acceptance
- Desktop and phone users can save strictness and observe the correct launch
result; compatible warnings survive reload exactly once. Touch and keyboard
interactions meet the design and both editor paths have rendered coverage.
- Public profile/executor guidance matches the new default, fallback precedence,
and error matrix, including legacy upgrade behavior.
- Every required task check has a recorded result; pending or skipped Postgres
evidence remains explicit. Completed transport/reuse regressions still pass.
## ASCII UI preview
Apply [UI-01 and UI-02](plan.md#ascii-ui-preview). This work order verifies those
views and updates guide text; it does not introduce another layout.
```text
Desktop: Strict [off/on] above [Automatic] [Explicit] cards -> Save
Phone: Strict [off/on] -> Automatic -> Explicit -> Save
Strict on: both fallback cards disabled, saved values visible.
Help: tap -> inset drawer -> dismiss -> focus returns -> save draft.
```
These views map to AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6 and .7.
## Verification
Run from the repository root. Use TDD for changed logic; first record the
behavioral failure, then run the listed checks after implementation.
```bash
(cd apps/web && pnpm e2e:run tests/settings/no-silent-model-fallback.spec.ts tests/session/model-mismatch-warning.spec.ts -- --retries=0)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/settings/mobile-no-silent-model-fallback.spec.ts tests/session/mobile-model-mismatch-warning.spec.ts -- --retries=0)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
git diff --check
```
## Files likely touched
- `apps/web/e2e/tests/settings/no-silent-model-fallback.spec.ts`
- `apps/web/e2e/tests/settings/mobile-no-silent-model-fallback.spec.ts`
- `apps/web/e2e/tests/session/model-mismatch-warning.spec.ts`
- `apps/web/e2e/tests/session/mobile-model-mismatch-warning.spec.ts`
- `apps/web/e2e/tests/session/model-mismatch-warning-helpers.ts`
- `docs/public/agents-and-profiles.md`, `docs/public/executors.md`
- This plan, work orders, and paired requirement/design status and results.
## Dependencies
['03-profile-strictness-controls']; preserve Task 01 transport and candidate-lookup fixes.
## Risks
Use fresh managed production builds: do not pass --no-build after code changes.
Run E2E commands sequentially with the guarded worker budget. Restore shared
fixture mutations. Mock browser results cannot certify external provider auth.
## Parallelism
`sequential`
## Inputs
- [Requirements](../../specs/agents/requirements/no-silent-model-fallback.md)
- [Policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
- [Recovery/UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
- [Plan and regression matrix](plan.md)
- Scoped AGENTS.md, existing tests beside the affected code, and compatibility
behavior at `ba960f973205854733e0dcd9afa355bdda3dddf6`.
## Results
Implemented on 2026-09-15. Public agent/profile and executor guidance now
describes compatible-by-default behavior, explicit strict opt-in, fallback
precedence, host-probe advisories, and upgrade compatibility. The existing
desktop and mobile settings and session mismatch specs passed with fresh
production builds:
- desktop settings: 3 passed;
- mobile settings: 3 passed;
- desktop session mismatch: 2 passed;
- mobile session mismatch: 2 passed.
Public-doc and specification validators passed. The Postgres check remains
pending until an isolated test database is available.
+27 -39
View File
@@ -161,6 +161,8 @@ Select an agent, create a profile, then open **Settings > Agents > _Agent_ > _Pr
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Label shown in workflow, session, and automation selectors. |
| Model | Requested through ACP when the agent supports model selection. Leaving it unset uses the agent's default where the form allows that. |
| Require exact model | Per-profile opt-in. When enabled, Kandev stops before inference unless the executor advertises and accepts the saved model. It disables fallback controls without erasing their saved values. |
| Fallback settings | Compatible profiles can use an advertised explicit fallback or automatic provider-default continuation. If the saved model is absent and exactly one bracketed variation is advertised, Kandev can use that variation with a warning. |
| Mode | Requested with ACP `session/set_mode`. The choices come from the installed agent. |
| Configuration options | Dynamic ACP values requested with `session/set_config_option`. |
| CLI flags | Enabled entries are tokenized and appended to the ACP launch command. |
@@ -187,31 +189,6 @@ change makes a saved option value unsupported, Kandev removes that value after
a successful resolution; a failed resolution keeps the draft unchanged so you
can retry it.
### Model IDs and executor catalogs
The host model probe is an editing hint. The selected executor owns the model
catalog at launch. Kandev resolves a saved model in this order:
1. Use the exact requested model when the executor advertises it.
2. Use the advertised explicit fallback when the requested model is absent.
3. Use one unique bracketed variation when the requested model is absent and
the executor advertises exactly one matching ID.
4. Use the agent's current or default model when no earlier choice applies.
Profiles with automatic fallback enabled keep the legacy behavior when the
saved model is absent: Kandev ignores the explicit fallback and does not infer
a variation. It uses the agent's current or default model instead.
For example, a saved `opus` model can launch as `opus[1m]` when that is the
only advertised `opus[...]` ID. If the executor advertises both
`opus[270k]` and `opus[1m, fast]`, Kandev does not choose either variation.
Variation text is opaque and model IDs remain case-sensitive.
Kandev shows a warning when the launch result differs from the saved model.
The saved profile remains `opus`; Kandev does not rewrite it after applying a
unique variation or using the agent default. Recheck the executor catalog when
the warning repeats after credentials, copied configuration, or agent updates.
### Use a dynamic profile
> [!EXPERIMENTAL]
@@ -267,22 +244,33 @@ stale browser action does not replace a newer route decision.
The model list shown while editing a profile comes from a host probe. It is an
editing hint, not a launch gate. A profile remains selectable when its saved
model is missing from that host list. Profile selectors do not show a model
warning for this difference. Inspect the model list in profile settings for
discovery details. Authentication, installation, and probe-failure indicators
remain visible on profile selectors.
model is missing from that host list. Profile selectors show an amber warning
icon for this difference. On a desktop pointer, hover or focus the icon to
read its tooltip. On a touch device, select the icon to open its warning
drawer. Inspect the model list in profile settings for discovery details.
Authentication, installation, and probe-failure indicators remain visible on
profile selectors.
At task launch, the selected executor's ACP catalog is authoritative. For
profiles without automatic fallback, Kandev follows the four-step order above.
For profiles with automatic fallback enabled, an absent saved model causes no
model request, and Kandev ignores the explicit fallback and any variation.
Kandev stores one warning in task chat with the requested model and the
effective model when known. The warning also identifies the agent and executor
and asks you to check credentials, copied configuration, and the agent version.
At task launch, the selected executor's ACP catalog is authoritative. Kandev
sends the requested model only when the executor advertises it. Profiles are
compatible by default, so an unavailable saved model can use an advertised
explicit fallback, one unique bracketed variation, or the executor's current
or default model. Kandev records one warning with the requested and effective
models when it continues with a different model. Automatic fallback allows
provider-default continuation and ignores the saved explicit fallback.
The saved profile model is not changed. Optional portable configuration can
copy selected allowlisted files into a remote executor, but it cannot guarantee
that the host and executor expose the same model catalog.
Enable **Require exact model** when the profile must keep the saved model. The
executor must advertise and accept that model before the first prompt. An empty
or unsupported catalog, an unavailable model, or a failed apply stops the
session before inference. Kandev never sends an unadvertised model and never
rewrites the saved profile model.
The host model list is only an editing hint. A missing host-probe model keeps a
profile selectable and shows an advisory warning; the executor catalog decides
the launch result. Upgrades and omitted API fields keep existing profiles
compatible, with strictness off until a user enables it. Optional portable
configuration can copy selected allowlisted files to a remote executor, but it
cannot guarantee equal host and executor model catalogs.
### Monitor capability and subscription status
+16 -24
View File
@@ -101,32 +101,24 @@ Review the selected bundles before saving the profile.
### Model selection in remote executors
The host model probe helps edit a profile, but it is not the launch authority.
At launch, the selected executor's advertised ACP catalog decides the model.
For profiles without automatic fallback, Kandev applies this deterministic
order:
At launch, the selected executor's advertised ACP catalog decides whether
Kandev sends the saved model. Profiles are compatible by default. When the
saved model is absent, Kandev can use an advertised explicit fallback, one
unique bracketed variation, or the executor's current or default model. An
automatic-fallback profile continues with the provider default and ignores its
saved explicit fallback. Kandev writes one warning to task chat when it uses a
different model.
1. An exact advertised model ID.
2. An advertised explicit fallback.
3. One unique advertised bracketed variation of the saved model.
4. The agent's current or default model.
Enable **Require exact model** on a profile when a substitution is not allowed.
The executor must advertise and accept the saved model before the first prompt.
An unavailable model, empty or unsupported catalog, or failed apply stops the
session before inference. The session error reports the requested model, the
effective model when known, and a stable reason. Kandev does not send an
unadvertised model or rewrite the saved profile model.
For profiles with automatic fallback enabled, an absent saved model keeps the
legacy behavior: Kandev ignores the explicit fallback and does not infer a
variation. It uses the agent's current or default model instead.
For example, a saved `opus` model uses `opus[1m]` when that is the only
advertised variation. With both `opus[270k]` and `opus[1m, fast]`, Kandev
does not infer a choice and uses the agent's current or default model instead.
It treats model IDs as case-sensitive and variation text as opaque.
Kandev writes one warning to task chat when the effective model differs from
the saved model. The warning can list the requested model, effective model,
agent, executor, and executor profile. It also tells you to check executor
credentials, copied agent configuration, and the agent version. Kandev does
not rewrite the saved profile model, including after applying a unique
variation.
Portable configuration can improve parity, but it does not guarantee equal
host and executor model catalogs.
A missing host-probe model remains an advisory warning and does not disable
profile selection. Portable configuration can improve parity, but it does not
guarantee equal host and executor model catalogs.
### Script behavior is runtime-specific
@@ -5,131 +5,107 @@ created: 2026-08-23
owners:
- kandev
---
# No Silent Model Fallback Requirements
## Overview
Kandev applies an agent profile model against the model catalog from the
selected executor. A different effective model must be deterministic and
visible to the user. The agent system owns this contract because it owns
profiles, ACP session startup, and model-selection warnings.
Profiles retain their model choices when executor capabilities differ from the
host. Users can require exact selection for an individual profile. Upgrading
Kandev must not turn existing fallback behavior into strict launch failures.
The agent system owns this contract because it owns persisted profile policy.
Task and Office execution consume that policy. This specification amends
PR #3473 and is implemented by the profile policy and recovery designs.
## Terminology
- **Requested model:** The model ID stored in the agent profile.
- **Explicit fallback:** The optional fallback model ID stored in the profile.
- **Bare model ID:** A model ID that contains no `[` or `]` character.
- **Model variation:** An advertised model ID with the exact form
`<bare-model-id>[<non-empty-variant>]`. The variant contains no bracket
character. Its content is otherwise opaque.
- **Unique variation:** The only distinct advertised variation for a requested
bare model ID.
- **Strict profile:** a profile with Require exact model explicitly enabled.
- **Compatible profile:** a profile with Require exact model disabled or absent.
- **Requested model:** the effective model for the launch, including an
intentional session override where the existing session contract permits it.
- **Fallback:** a different model selected or retained for the current launch.
## Requirements
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001: Use executor-authoritative model selection
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001: Explicit strictness and visible fallback
**Intent:** Keep task launch operational without hiding a difference between
the saved model and the effective executor model.
**Intent:** Prevent unwanted substitutions when explicitly requested, while
preserving working executor launches for existing profiles.
**User story:** As a user, I want Kandev to use the selected executor's model
catalog and report any fallback, so that I can understand which model runs.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1:** When Require exact model is
enabled, the executor shall advertise and apply the requested model before
the initial prompt. Otherwise the attempt shall fail before inference.
A fallback setting or advertised variation shall not bypass this rule.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2:** When a compatible profile uses
a different model, the session shall show one durable warning for that
selection decision. It shall include the requested and effective model when known.
Reload and event replay shall not duplicate the warning.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3:** Existing profiles and newly
created profiles shall have Require exact model off unless explicitly set.
An upgrade shall preserve the model, fallback model, automatic fallback,
and compatible launch outcomes. An absent setting shall not imply strictness.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4:** For compatible profiles, an
advertised requested model shall take priority. With automatic fallback off,
an advertised explicit fallback shall take priority over variation matching.
If no alternate selection is available, the session shall continue on the
executor current/default model with a warning. An empty catalog or unsupported
model-selection method shall also permit this continuation.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5:** Compatible profiles shall retain
existing apply-error behavior. An ordinary error applying an advertised model
shall fail unless automatic fallback is enabled. Automatic fallback shall
continue with a warning and ignore the configured explicit fallback.
Initialization failures, disconnections, and cancellation shall remain errors.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6:** Require exact model shall be a
per-profile setting in Fallback settings, available on desktop and mobile.
It shall default off. Enabling it shall disable the fallback controls without
erasing their values. Disabling it shall restore their previous behavior.
Save, reload, duplication, and supported profile export/import shall preserve
the setting. Omitted fields in partial updates shall preserve a saved choice.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.7:** A collapsed Fallback settings
section shall summarize the effective policy and expose unsaved changes.
Strictness shall be keyboard and touch operable with visible explanatory copy.
Phone help shall use the existing drawer interaction, with reachable touch
targets, focus return, and no horizontal document overflow.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.8:** Launch, reset, fresh workspace
rebind, and replacement-executor recovery shall apply the same profile policy.
Replacement selection shall use only replacement-session evidence. Cancellation
shall stop the attempt. A strict attempt without a ready replacement catalog
shall fail; an initialized compatible attempt may continue with a warning.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.9:** Across different workflow steps,
an explicitly strict destination shall replace a session whose effective model
is different or unknown. Compatible destinations shall not force replacement
solely because the effective model differs. Same-step intentional overrides
shall keep their existing behavior. A validated empty reuse lookup shall create
a fresh session without an unvalidated second lookup.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10:** A missing host-probe model shall
remain an advisory and shall not disable profile selection. Runtime selection
shall not send an unadvertised model or rewrite the saved profile model.
Enabling strictness without a concrete model shall produce a validation error.
#### Acceptance criteria
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002: Compatible advertised variation selection
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1:** When the executor advertises
the requested model, the system shall apply that exact model.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2:** When the requested model is
absent and the executor advertises the configured explicit fallback, the
system shall apply the explicit fallback.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3:** When no permitted advertised
model applies, the system shall make no speculative model-selection call and
shall continue with the provider current or default model.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4:** When the effective model differs
from the requested model, the system shall persist one structured warning
that identifies the requested and effective models when known.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5:** The system shall not rewrite the
saved profile model from an executor model-selection decision.
**Intent:** Preserve the pre-PR compatible selection order without treating a
variation as an exact identity. This amendment restores the scoped behavior
removed by the strict-by-default PR.
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002: Resolve one advertised model variation
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.1:** This rule applies when strictness
and automatic fallback are off. The bare requested ID must be absent, and no
advertised explicit fallback must be available. Under these conditions, exactly
one distinct advertised bracketed variation shall be selectable with a warning. Zero or multiple matches, malformed
variations, and already-bracketed requests shall not authorize a guessed ID;
the session shall use the executor default with a warning. Saved IDs shall
remain unchanged. Strict profiles shall never infer a variation.
**Intent:** Preserve a user's bare model choice when a CLI replaces that model
ID with one unambiguous bracketed variation.
## Exclusions
**User story:** As a user, I want `opus` to resolve to `opus[1m]` when that is
the only advertised variation, so that a provider catalog change does not move
my session to an unrelated default model.
No global, workspace, executor, environment, or release-toggle setting. No
provider switching caused by this new field. Office post-start routing remains
workspace-owned. No retroactive interruption or model change of running turns.
No guarantee that invalid credentials, missing executables, or network failures
can launch successfully. No new global enforcement system for model costs.
#### Acceptance criteria
## System design and delivery
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.1:** When automatic fallback is
disabled, the exact requested model is absent, and an advertised explicit
fallback exists, the system shall apply the explicit fallback before it
considers an inferred variation. Automatic-fallback profiles shall retain
their legacy no-selection behavior for an absent requested model.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.2:** When no advertised explicit
fallback exists and the catalog contains exactly one distinct variation of a
requested bare model ID, the system shall apply that advertised variation.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.3:** When the catalog contains zero
or more than one distinct variation, the system shall not infer a model.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.4:** When the requested ID contains a
bracket, the system shall treat it as an exact ID and shall not infer another
variation.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.5:** Matching shall be case-sensitive
and shall not parse, rank, or assign meaning to variation text.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.6:** When Kandev applies a unique
variation, it shall keep the saved model unchanged and shall persist a
warning that identifies the inferred effective model.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.7:** The host profile probe shall
present unique-variation resolution as an advisory in the profile editor.
It shall not become the launch authority or add a model warning to a profile
selector. It shall not disable the profile.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.8:** The same resolution order shall
apply at initial launch, context reset, and workspace rebind.
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003: Show model warnings at the point of action
**Intent:** Let users select a saved profile without treating a host discovery
difference as evidence of an executor failure.
#### Acceptance criteria
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.1:** A host model-catalog difference
shall not add an icon, message, tooltip, or help action to a profile selector.
This applies to its options and its selected label, including missing models,
one or several model variations, and empty or pending catalogs.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.2:** On desktop and mobile, an
otherwise eligible profile shall remain selectable by keyboard or pointer.
On touch devices, tapping its row shall select it without opening model help.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.3:** Existing authentication,
installation, and capability-probe failure indicators shall remain visible.
Their presence shall not depend on whether the saved model is advertised.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.4:** The profile editor shall retain
its missing-model treatment, unique-variation advisory, and fallback controls.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.5:** When the executor applies the
requested model successfully, a host catalog difference shall not cause a
model-selection warning in task chat. Actual fallback warnings shall retain
the persistence and visibility defined by requirement 001.
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.6:** Selecting a profile shall not
rewrite its saved model, reasoning configuration, or fallback settings.
## Compatibility
The September 2026 selector amendment removes host model advisories from
profile selection. It preserves executor model selection and profile editing.
Delivery is tracked in the [implementation package](../../../plans/profile-selector-model-warnings/plan.md).
## Out of scope
- Ranking multiple variations by context size, speed, price, or display order.
- Parsing provider-specific variation syntax beyond the bracketed ID shape.
- Inferring a base model from an already bracketed request.
- Rewriting the profile model to the current executor's advertised variation.
- Changing Office post-start provider routing or mid-turn model switching.
- Changing host discovery refresh, cache invalidation, or ACP model normalization.
## System design
The technical source is split into [part 1](../system-design/no-silent-model-fallback-01.md)
and [part 2](../system-design/no-silent-model-fallback-02.md).
- [Policy and persistence](../system-design/no-silent-model-fallback-01.md)
- [Recovery and profile surfaces](../system-design/no-silent-model-fallback-02.md)
- [PR implementation package](../../../plans/exact-profile-model-identity/plan.md)
@@ -4,640 +4,146 @@ system: agents
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003
created: 2026-08-23
owners:
- kandev
---
# No Silent Model Fallback System Design Part 1
# No Silent Model Fallback: Policy and Persistence
## Purpose and boundaries
## Scope and mapping
This design defines executor-authoritative model fallback, including safe
resolution from a bare requested model to one advertised bracketed variation.
This design amends the strict-by-default implementation in PR #3473. The agents
system owns profile policy; lifecycle applies it using executor evidence.
[Part 2](no-silent-model-fallback-02.md) covers recovery and rendered surfaces.
## Requirement mapping
| Requirement | Design section |
| Requirement | Design sections |
| --- | --- |
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001` | [Migrated source detail](#migrated-source-detail) |
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002` | [Unique model-variation resolution](#unique-model-variation-resolution) |
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003` | [Profile selection and warning placement](#8-profile-selection-and-warning-placement) |
## Migrated source detail
**Status**: implemented (executor-authority amendment 2026-08-15)
**Date**: 2026-08-04
**Slug**: `no-silent-model-fallback`
## Problem
Agents such as OMP are configured with models from multiple providers (e.g.
Claude + GPT). When a provider's login/auth expires (e.g. Claude), its models
become unavailable. Today Kandev silently compensates in several places:
1. **Session start (agentctl runtime)** — `SessionManager.InitializeSession`
applies the profile's start model via ACP `SetModel` as *best-effort*:
on failure it logs a warning and continues the session on the provider
default model. `SetModel` itself fails fast when the model is not in the
agent's advertised model list (`validateAvailableModel`), so the failure
is known but ignored.
2. **Profile reconciler (boot)** — `healProfile` overwrites a profile's
start model with the probe's `CurrentModelID` when the configured model
is no longer advertised. The user's explicit model choice is silently
replaced.
3. **Office post-start fallback** — when a launched run fails mid-session
with a fallback-allowed error (`auth_required`, `model_unavailable`,
…), `HandlePostStartFailure` silently re-dispatches the run to the next
provider in the workspace routing order.
4. **Frontend model lists** — model pickers have no concept of an
unavailable ("gone") model; `clearStaleActiveModel` silently drops an
active model that disappeared from the ACP list, so the session continues
on whatever the agent picks.
**Bottom line: the host and executor can advertise different model catalogs.
Kandev must keep the task operational and explain the effective model.**
## Goals
- A configured model that the executor does not advertise is never applied.
The agent continues with its current or default model.
- Every default or explicit fallback creates a persisted warning in task chat.
The warning survives reload and shows the effective model when known.
- A Claude model that is valid for the user's account can start in a cold,
isolated executor even when the initial Claude ACP model list omits it.
- "Gone" models render **greyed out and unselectable** in every model
picker, while remaining visible so the user can see what was configured.
- Agent profiles **keep** their previously configured start model even when
gone (shown red + unselectable in the editor) instead of having it
auto-healed.
- Profiles remain selectable when the host probe does not advertise the saved
model. The host probe is an editing hint, not an executor launch gate.
- A new optional per-profile **agent fallback model** allows an explicit,
single-model automatic switch when the start model becomes unavailable at
session start. Kandev applies it only when the executor advertises it.
Office post-start routing is unchanged and remains governed
by the workspace routing configuration (see ADR
`2026-08-08-provider-neutral-agent-error-recovery.md`): the profile's
model policy is the owner of the session-start decision, not of office
post-start provider fallback.
- A new explicit per-profile toggle **"Fallback automatically to next
model"** restores the legacy automatic-fallback behavior (session start
best-effort + office routing re-dispatch). A failed apply continues with the
agent default and creates a persisted warning. Enabling the toggle disables the
optional fallback-model controls without clearing their saved value (the two
are mutually exclusive opt-ins).
- Agent-profile editors group both fallback choices in a collapsed **Fallback
settings** disclosure. Expanding it shows the two choices side by side on
desktop and as one vertical flow on phone-sized screens. Each choice keeps a
short visible explanation and adds contextual help that works by hover or
keyboard focus with a fine pointer and by tap on a coarse pointer.
## Non-Goals
- Changing the workspace provider-routing configuration model (tiers,
provider order, execution profiles) itself.
- Provider-level auth flows (login/refresh UI) — only the *consequence* of
auth expiry (unavailable models) is addressed.
- Requiring equal model catalogs on the Kandev host and executor.
- Requiring portable configuration copying before a task can start.
- Mid-turn model switching on the live ACP session (retry the current turn
on a different model) — fallback applies to the next attempt/launch, not
to an in-flight turn.
## Definitions
- **Available models**: the model IDs an agent currently advertises —
`hostutility.AgentCapabilities.Models` (probe cache, surfaced via
`GET /api/v1/agents/available` and `GET /api/v1/agent-models/:agentName`)
or the ACP session's `models_updated` list.
- **Gone model**: a model ID that is configured (profile start model, active
session model, fallback model) but absent from the currently advertised
list. Deterministic on the frontend: `configured ∉ advertised`.
- **Default-on-mismatch mode**: profile has `auto_fallback = false` and no
`fallback_model`. If the executor omits the start model, Kandev skips model
selection and the agent uses its default. Kandev persists a warning.
- **Fallback-model mode**: profile has `auto_fallback = false` and a
non-empty `fallback_model`. The only permitted automatic switch is to
that single model when the executor advertises it. Otherwise, the agent uses
its default and Kandev persists a warning.
- **Auto-fallback mode**: profile has `auto_fallback = true`. Legacy
behavior (session-start best-effort; office routing re-dispatch to next
candidate). Every session-start deviation creates a warning.
`fallback_model` is ignored.
- **Cold isolated executor**: a non-standalone executor that does not share the
host probe's Claude settings or model cache. Docker, remote Docker, Sprites,
and SSH executors can have this property.
## Behavior Matrix
Per agent profile, one of three modes (precedence: `auto_fallback` wins
over `fallback_model`):
| Scenario | Default-on-mismatch | Fallback-model | Auto-fallback |
|---|---|---|---|
| Session start, start model not advertised | Do not call `SetModel`. Continue on the agent default and persist a warning. | If the fallback is advertised, apply it and persist a warning. Otherwise, use the agent default and persist a warning. | Do not call `SetModel`. Continue on the agent default and persist a warning. |
| Session start, advertised start model fails to apply | Fail explicitly. | Fail explicitly. | Continue on the agent default and persist a warning. |
| Session start, model selection unsupported | Continue on the agent default and persist a warning. | Same | Same |
| Mid-session model/auth failure (office run, post-start) | Unchanged ADR behavior: office re-dispatches via the workspace routing chain (`routingerr.Decide(ContextOffice)`; availability codes → `DecisionFallback`). The profile's model policy does **not** gate office fallback — the workspace routing configuration is the office authorization owner. | Same as default-on-mismatch: `fallback_model` is a session-start policy, not an office routing input. | Legacy: re-dispatch to next candidate in the provider order (unchanged). |
| Boot reconciliation | Never overwrite a gone start model (keep it; UI shows it red). Same for a gone `fallback_model`. | Same | Same (reconciler is mode-independent). |
| New-task / new-agent profile picker | Profile selectable without a host model advisory. | Same. | Same. |
| Model picker (profile editor, session toolbar) | Gone models greyed out, unselectable, visible. | Same. | Same. |
`SetModel` failures that mean "this agent does not support model selection"
(JSON-RPC `-32601`, `sessionmodel.MethodNone` / `IsMethodNotFound`) do not stop
the launch. The agent uses its default and Kandev persists a warning.
The executor ACP catalog is authoritative for launch.
The host probe remains an editing hint and does not block profile selection.
## Unique model-variation resolution
### Matching contract
ACP model IDs remain opaque and case-sensitive. Kandev recognizes only this
structural relationship:
```text
<requested>[<variant>]
```
The requested ID must contain no `[` or `]` character. The advertised ID must
start with the complete requested ID followed by `[`, end with `]`, and contain
a non-empty variant with no bracket character. Kandev does not trim, parse, or
rank the variant.
Examples:
| Requested | Advertised candidates | Result |
| --- | --- | --- |
| `opus` | `opus[1m]` | Apply `opus[1m]`. |
| `opus` | `opus[270k]`, `opus[1m, fast]` | Do not infer. |
| `opus[1m]` | `opus[270k]` | Do not infer. |
| `opus` | `myopus[1m]`, `opus-extra[1m]` | Do not infer. |
| `opus` | `opus[]`, `opus[1m][fast]` | Do not infer. |
Duplicate catalog rows with the same model ID count as one distinct candidate.
This rule keeps the outcome stable when an agent repeats a catalog entry.
### Resolution order
For profiles with `auto_fallback = false`, the lifecycle applies this order
after ACP initialization:
1. Apply the exact requested model when advertised.
2. Apply the configured explicit fallback when advertised.
3. Apply the requested model's unique advertised variation when one exists.
4. Otherwise, make no model-selection call and keep the provider current or
default model.
An unadvertised explicit fallback does not block step 3. More than one distinct
variation blocks inference even when one candidate appears first or is the
provider current model.
When `auto_fallback = true`, the legacy path takes precedence when the
requested model is absent: Kandev ignores the explicit fallback and does not
infer a variation. It makes no model-selection call and continues on the
provider current or default model with a warning. Apply errors for an
advertised model remain best-effort in that mode.
`applyStartModelPolicy` remains the single runtime owner. A pure helper returns
the unique candidate or no candidate. Initial launch, context reset, and
workspace rebind continue to call the same policy.
### Decision and warning contract
The typed decision adds the outcome `unique_variation` and the stable reason
`unique_variation_applied`. `EffectiveModel` contains the advertised variation.
`FallbackModel` remains reserved for a configured explicit fallback and is not
overloaded with an inferred value.
Kandev calls `SetModel` only with the candidate's exact advertised ID. A failed
call follows the existing advertised-model rule: fail the operation unless
legacy `auto_fallback` permits provider-default continuation. A
method-not-supported response also follows the current provider-default path.
The persisted `model_selection_warning` event uses the new reason and existing
requested and effective model fields. The profile remains unchanged. The
decision ID continues to include the requested model, reason, and effective
model, so the warning stays idempotent for one session decision.
### Host advisory and mobile behavior
The frontend uses a small pure helper with the same case-sensitive matching
table. This calculation is advisory because the host catalog can differ from
the selected executor catalog.
When the host advertises one variation, the task profile option remains
selectable without a host model advisory. The profile editor keeps the saved
bare ID visible and describes the unique
host variation instead of reporting that the model is simply gone. Selecting
the advertised variation remains an explicit way to update the profile.
When the host advertises zero or multiple variations, the profile editor's
missing-model presentation remains. The runtime can still reach a different decision from
the selected executor catalog.
The task-create selector has no host model tooltip or help drawer.
The profile editor uses its existing responsive selector. The durable
chat warning uses the existing status-message layout on desktop and mobile.
This change adds no nested scroll area or hover-only information.
### Tests and operational evidence
Backend table tests cover exact precedence, explicit-fallback precedence,
one variation, duplicate rows, multiple variations, bracketed requests,
case differences, malformed IDs, method-not-supported, and apply errors.
Existing launch, reset, rebind, warning persistence, and reload tests cover the
new decision outcome.
Frontend unit tests mirror the matching table and cover the task picker,
profile editor, and localized status warning. Existing desktop and mobile model
mismatch E2E flows add the unique and ambiguous catalog cases.
Structured lifecycle logs record the requested model, effective model, outcome,
and distinct candidate count. They do not record credentials or configuration
file contents.
No database migration is required.
## Related decisions
- [Let the Executor Own Model Selection](../../../decisions/2026-08-15-executor-authoritative-model-selection.md)
- [Resolve Only One Advertised Model Variation](../../../decisions/2026-09-07-unique-model-variation-resolution.md)
## Backend Changes
### 1. Agent profile schema (new columns)
`agent_profiles` gains:
- `fallback_model TEXT NOT NULL DEFAULT ''` — optional single fallback model
ID (ACP model ID, same vocabulary as `model`).
- `auto_fallback INTEGER NOT NULL DEFAULT 0` — explicit opt-in to legacy
automatic fallback.
Migration follows the existing `r.migrate.Apply("agent_profiles.<col>",
"ALTER TABLE ... ADD COLUMN ...")` pattern in
`apps/backend/internal/agent/settings/store/sqlite.go`. Wire through:
- `models.AgentProfile` (`internal/agent/settings/models/models.go`)
- store scan/insert paths (`settings/store/sqlite.go`)
- `dto.AgentProfileDTO` + create/update request structs
(`settings/dto/dto.go`, `settings/controller/profile_crud.go`)
- frontend `AgentProfile` type, `normalizeAgentProfile` /
`toAgentProfilePayload` (`apps/web/lib/types/agent-profile.ts`,
`apps/web/lib/api/domains/agent-profile-normalize.ts`)
Validation: `fallback_model` may be set independently; when `auto_fallback`
is enabled the UI hides/disables the field and the backend ignores
`fallback_model` at runtime (precedence rule). No cross-field rejection —
saving both is allowed; runtime precedence is `auto_fallback`.
### 2. Reconciler stops healing gone models
`healProfile` in `internal/agent/settings/controller/reconciler.go` currently
replaces a gone `p.Model` with `caps.CurrentModelID`. Change: keep the
user-configured model when it is gone (log an info line; do not overwrite).
The `p.Model == ""` seed-default branch is unchanged. Apply the same
keep-when-gone rule to `fallback_model` (no auto-heal; UI surfaces it).
Mode healing is unchanged (modes are not part of this feature).
### 3. Session start: executor-authoritative model application
In `internal/agent/runtime/lifecycle/session.go`, the start-model policy uses
the executor session state after `InitializeSession`.
The policy returns a typed model decision with these values:
- Requested model.
- Advertised fallback model, when one is applied.
- Effective model, when the agent reports it.
- Outcome and warning reason.
- Whether Kandev called `SetModel`.
The policy applies this order:
1. If the start model is advertised, call `SetModel(start_model)`.
2. If the start model is absent and the explicit fallback is advertised, call `SetModel(fallback_model)`.
3. Otherwise, do not call `SetModel` and continue with the agent default.
An empty advertised list follows step 3.
It does not authorize a speculative `SetModel` request.
If an advertised start or fallback model fails to apply, fail the launch.
Transport and protocol errors remain explicit.
If `auto_fallback` is enabled, an apply error remains best-effort.
The launch continues with the agent default and persists a warning.
If `sessionmodel.IsMethodNotFound(err)` is true, continue with the agent default.
Persist a warning because the profile requested a model that Kandev could not apply.
The start-model policy owns every model-selection attempt.
Later profile or configuration layers must not repeat a handled attempt.
The same policy applies after a context reset.
A reset cannot send a model that the new executor session does not advertise.
### 3a. Persisted model-selection warning
If Kandev does not apply the requested model, it emits a provider-neutral
`session_model_selection_warning` event.
The orchestrator persists one `status` message for the session-start decision.
The message uses `metadata.variant = "warning"` and
`metadata.kind = "model_selection_warning"`.
The metadata contains the reason, requested model, effective model, fallback
model, agent ID, executor type, and executor profile ID.
The message content is structured and localized by the frontend status renderer.
If the agent reports no effective model, the UI shows
`provider default, model not reported`.
The warning includes this remediation guidance:
- Inspect the executor credentials.
- Inspect copied agent configuration.
- Inspect the agent version in the executor.
Message persistence is best-effort and does not stop the agent launch.
Persistence errors are logged without model data from configuration files.
The persistence path uses an idempotency key for the session-start decision.
Reconnect, replay, and browser reload do not create duplicate warning messages.
The existing ephemeral `session.model_fallback` signal becomes a compatibility
projection of the provider-neutral decision event.
### 3b. Claude ACP model exposure in cold executors
The host probe can advertise a Claude model from its warm settings or model
cache. A cold isolated executor can start with only the bridge's baseline model
list. This difference does not prove that the configured model is unavailable
to the user's account.
Before the initial Claude ACP process starts in a non-standalone executor, the
lifecycle exposes the effective start model through Claude's documented launch
environment. The effective model is the request model override when present.
Otherwise, it is the profile start model. The lifecycle exposes an explicit
profile fallback as a selectable custom model when `auto_fallback` is false.
During workspace recovery, a persisted session runtime model is treated as the
selected model for launch-environment derivation and takes precedence over the
profile start model.
Provider launch environment values use fill-missing precedence. Request,
executor, and profile environment values remain authoritative. The lifecycle
does not replace an existing `ANTHROPIC_MODEL` or
`ANTHROPIC_CUSTOM_MODEL_OPTION` value.
This behavior is an optional agent capability. Other agents receive no Claude
environment values. A standalone Claude process keeps the current host behavior
because it shares the settings and cache used by the probe.
SSH keeps its credential allowlist unchanged, but projects these non-secret
Claude model values into the remote agent controller so its child process sees
the same launch environment. Recovery fails before environment construction if
the execution profile cannot be resolved, rather than silently dropping its
model and environment values.
Kandev does not relax model validation after the ACP session starts.
If Claude still omits the model, the executor-authoritative policy uses the default and warns.
Kandev does not copy the bridge private cache.
The separate portable-configuration feature can copy `settings.json` after explicit user selection.
### 4. Office post-start failure gating (unchanged, ADR-governed)
`HandlePostStartFailure` in
`internal/office/scheduler/routing_lifecycle.go` is **not** modified by this
feature. Office post-start fallback authorization stays with the workspace
routing configuration and provider chain
(`routingerr.Decide(ContextOffice)`), per ADR
`2026-08-08-provider-neutral-agent-error-recovery.md`. Rationale: the
feature's model policy is owned by the session-start decision
(`execution.AgentProfileID`); the office post-start path sees the stable
office identity (`run.AgentProfileID`), and the two can disagree. Reading
`agent.FallbackModel` / `agent.AutoFallback` there would create a second,
conflicting policy owner. Office runs still get the session-start guarantee.
Kandev does not send an unadvertised model, and it persists a warning.
Mid-session Office failures keep the workspace-configured routing behavior.
Terminal office failures (for example after max attempts) surface an
actionable "provider/model unavailable — change the model" hint: map
`model_unavailable` / `auth_required` / `missing_credentials` /
`subscription_required` codes onto the failure message via
`routingerr.ModelUnavailableMessage` when composing it.
### 5. Error message mapping
Add a small helper (backend) that renders an actionable message for
model/auth failure codes, e.g. `"Model unavailable: the configured model
<id> is no longer available. Change the model in the agent profile."` Used
by the session-start failure and the office terminal-failure path so both
chat and run detail show the request-to-change-model copy. The frontend may
additionally map the same codes to a banner (see frontend).
## Frontend Changes
### 6. Model pickers: disabled ("gone") support
`apps/web/components/model-config-selector.tsx`:
- `ModelSelectorOption` gains `disabled?: boolean` and
`disabledReason?: string`.
- `ModelRow` renders disabled options greyed (`opacity-40`,
`cursor-not-allowed`), with the reason in a tooltip, and `onSelect` is
guarded (`!option.disabled`). Follow the existing disabled pattern from
`apps/web/components/combobox.tsx` (separate visual treatment + tooltip).
Session toolbar picker (`apps/web/components/task/model-selector.tsx`):
- `clearStaleActiveModel` in `apps/web/lib/ws/handlers/session-models.ts`
stops clearing the active model when it disappears from the ACP list.
Instead the active model is **kept and marked gone**: the picker shows it
greyed out with a reason ("model no longer available — select a new
model"), so the user is explicitly asked to change it.
- `buildModelOptions` / `resolveAvailableModels` mark configured-but-absent
models (profile model, active model) as `disabled`.
### 7. Profile editor rows
`apps/web/components/settings/profile-form-fields.tsx` (`CapabilitiesRow` /
`ModelPicker`):
- **Start model**: when `profile.model` is not in the current model list,
keep it as the current value but render it red
(`text-destructive`) + disabled with a reason ("no longer available").
- **Agent fallback row** (new, under Start model): optional select of the
same model list bound to `profile.fallback_model`. It remains visible but is
disabled when `auto_fallback` is ON, preserving the configured value while
making the mutual exclusion understandable. It uses the same
gone-red/disabled treatment if the fallback model itself is gone.
- **"Fallback automatically to next model" toggle** (new row): a switch
bound to `profile.auto_fallback`. When ON, the fallback-model controls are
disabled. Helper text explains the semantics.
- **Fallback settings disclosure**: both choices sit inside a semantic
collapsible section that is closed on initial render. Its closed header
summarizes the effective mode (executor default, automatic, or the configured explicit
fallback) so saved state and hidden dirty state remain discoverable. The
trigger is keyboard-operable, reports expanded state, and has a touch target
of at least 44px.
- **Responsive layout and help**: the expanded choices use two equal columns at
the desktop breakpoint and one column below it. Each label has an info-icon
button. Fine pointers expose localized help through a tooltip on hover and
focus; coarse pointers open the same help in an inset bottom drawer. The
visible helper sentence remains in the option card, so the icon is
supplementary rather than the only explanation.
- The lighter editor `apps/web/components/agent/cli-profile-editor.tsx`
(`ModelModeFields`) gets the same disclosure, layout, help, and mutual
exclusion behavior for parity.
All new copy is externalized via `t()` into the `settings` i18n namespace
(`apps/web/src/locales/{en,pseudo,pt-pt,zh-cn}/settings.json`) — the i18n ratchet
judges added lines even in unmigrated files.
### 8. Profile selection and warning placement
`apps/web/lib/state/slices/settings/types.ts` — `AgentProfileOption` gains
`model`, `fallbackModel`, `autoFallback` (populated in
`toAgentProfileOption`).
`apps/web/components/task-create-dialog-options.tsx`
(`useAgentProfileOptions`) derives profile labels and eligibility without
comparing the saved model with the host model catalog. Remove
`advertisedModelIDs`, `ModelProbeWarning`, and `ModelProbeWarningIndicator` from
this module, plus imports used only by those helpers. The hook no longer needs
`useAvailableAgents` solely to produce model advisories.
Both `renderLabel` and `renderTriggerLabel` use the same profile presentation.
Keep the option interface compatible with its consumers. Preserve profile
eligibility, recent-use ordering, names, logos, and CLI passthrough indicators.
Keep `getCapabilityWarning` and its authentication, installation, and probe
failure states. Those states describe agent health rather than a model mismatch.
Consumers include task creation, new subtasks, new sessions, quick chat,
automation configuration, and Office setup. All receive this behavior from the
shared hook. Do not add consumer-specific warning suppression flags.
Retain profile model/configuration fields and the editor's
`findUniqueModelVariation`. After checking references, remove these unused
selector keys from every locale:
`profileStartModelNotAdvertisedOnHost` and
`profileStartModelUniqueVariationOnHost`.
`apps/web/app/office/setup/agent-profile-setup-controls.tsx`
(`useSelectableProfileOptions`) retains its Office eligibility filtering around
the shared profile options.
#### Desktop and mobile composition
Keep the touch-usable combobox and shared selection logic. A row tap completes
the temporary profile choice without another help drawer or an empty hit area.
Preserve keyboard selection, focus return, picker-owned scrolling, and safe-area
constraints. Assert no document horizontal overflow.
Use `e2e/tests/settings/mobile-no-silent-model-fallback.spec.ts` as the shipped
flow and `components/task/mobile/mobile-picker-sheet.tsx` as the curated
temporary-choice precedent. No picker-shell replacement is needed.
#### Rationale and compatibility
A host observation cannot establish the executor outcome. A neutral icon or
better ID comparison would still report valid catalog differences during
selection. Keep the existing executor-authority ADR and runtime behavior.
This change needs no resolver, cache, schema, or new ADR. Explain warning
placement in `docs/public/agents-and-profiles.md` when implementation ships.
The persisted `model_selection_warning` chat message renders through
`apps/web/components/task/chat/messages/status-message.tsx`.
The renderer uses localized copy and structured metadata.
The message appears in the normal chat flow on desktop and mobile.
It does not require a new drawer or a hover-only control.
### 9. i18n
New keys in `apps/web/src/locales/{en,pseudo}/settings.json` (camelCase,
`settings:` namespace), cover the gone-model hint and fallback controls.
New keys in the chat namespace cover the persisted model-selection warning.
No added or edited line contains hardcoded user copy.
## Tests
Backend (Go, `*_test.go` beside source):
- Store: `fallback_model` / `auto_fallback` round-trip + migration.
- Reconciler: gone start model is kept, not overwritten; empty model still
seeded; gone fallback_model kept.
- Runtime session start: an unadvertised start model causes no `SetModel` call.
The session continues with the reported current or default model.
- Runtime session start: an advertised explicit fallback is applied.
An unadvertised fallback causes no call and the agent default remains active.
- Runtime session start: an empty catalog and method-not-supported both continue
with the agent default and create a model-selection warning.
- Runtime session start: an advertised model apply error fails explicitly.
Auto-fallback keeps best-effort behavior and creates a warning.
- Runtime session start: each decision produces at most one model-selection
attempt with no profile-layer retry.
- Runtime launch environment: a non-standalone Claude launch exposes the
effective start model before ACP initialization. It exposes an explicit
fallback only when auto fallback is off. Request, executor, and profile
environment values take precedence. Standalone Claude launches and other
agents receive no new environment values.
- Office post-start: unchanged — availability failures requeue via the
workspace routing chain regardless of the profile's fallback settings
(regression test pins that the profile policy does not gate office).
- Model-decision event and warning metadata tests.
- Orchestrator persistence tests for message type, warning metadata,
idempotency, reload hydration, and persistence errors.
Frontend (Vitest, `*.test.ts(x)`):
- `model-config-selector`: disabled option not selectable; greyed class.
- `session-models` WS handler: stale active model is kept (not cleared).
- `useAgentProfileOptions`: every otherwise eligible host-mismatch profile
remains selectable with no model advisory in either label. Cover canonical
IDs, legacy bracketed IDs, unique and multiple variations, and empty catalogs.
- Capability health warnings, recent-use ordering, disabled-profile filtering,
and saved profile values remain unchanged by selector rendering.
- Profile editor: gone start model renders red + disabled; auto-fallback keeps
the explicit fallback choice visible but disables its controls.
- Profile editors: fallback settings start collapsed; expanding exposes both
choices, auto-fallback disables rather than removes the explicit fallback,
and desktop tooltip help is available through pointer and keyboard focus.
- `agent-profile-normalize`: new fields round-trip.
- Status message: structured model-selection metadata renders localized
requested, effective, agent, executor, and remediation text.
E2E (Playwright, `apps/web/e2e`):
- Mock backend (`KANDEV_E2E_MOCK=true`): create a profile whose start model
is not in the host catalog. Make sure that the task-create picker keeps the
profile selectable without a host model warning in the option or selected
label. Select the profile with keyboard on desktop and a row tap on mobile.
- Launch a profile whose executor advertises its exact model while the host
omits it. Verify the selected model, no model-selection warning, and unchanged
profile values after reload.
- Launch with an executor catalog that omits the profile model. Make sure that
no model-selection call occurs, the task continues, and chat shows one warning.
- Reload the task page. Make sure that the warning remains in chat.
- Desktop profile settings: the disclosure starts closed, expands to two
horizontally aligned option columns, summarizes the current fallback mode,
and exposes each info explanation on hover/focus.
- Mobile profile settings: tapping the same disclosure reveals one stacked
flow; tapping either 44px info target opens the localized help drawer without
horizontal document overflow.
## Persistence & Migration
- `agent_profiles.fallback_model TEXT NOT NULL DEFAULT ''`
- `agent_profiles.auto_fallback INTEGER NOT NULL DEFAULT 0`
Existing rows use `auto_fallback = 0` and no fallback model.
This state means default-on-mismatch behavior.
If the executor omits the saved model, the agent uses its default and Kandev
persists a warning. The saved profile model does not change.
| REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001 | Persistence, policy, warnings, boundaries |
| REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002 | Compatible selection order |
## Persistence and API
Add `RequireExactModel bool` to `settings/models.AgentProfile`, represented as
`require_exact_model` in JSON/storage and `requireExactModel` in normalized web
profile data. Use an additive `agent_profiles.require_exact_model INTEGER NOT
NULL DEFAULT 0` migration through the existing dialect-aware migration path in
`settings/store/sqlite.go`. Cover SQLite and Postgres. Do not rewrite existing
`model`, `fallback_model`, or `auto_fallback` columns or reinterpret their values.
New profiles and seeds also default false. Reopening the store is idempotent.
Wire create/read/update, scans/inserts, clone/duplicate, reconciler preservation,
profile export/import, and the canonical settings discovery contract. Use pointer
presence on partial updates, including the enabled-only fast path. An omitted
field preserves an existing value; explicit false clears strictness. Create and
legacy import without the field use false. Old clients must not accidentally
clear an existing true value when editing another field. The response includes
an explicit boolean. Use the existing profile contract generator for snapshots.
Validation uses the merged profile on updates: strictness requires a non-empty
model on a concrete ACP profile. A dynamic selector or terminal-passthrough
profile cannot provide this guarantee and rejects an explicit strict request;
existing such profiles remain valid with false. Dynamic selection passes the
chosen concrete candidate's policy through existing execution resolution.
Do not redesign dynamic eligibility or Office routing.
Saved fallback choices may coexist with strictness as dormant values. Runtime
precedence is `require_exact_model` first, then existing `auto_fallback`, then
explicit fallback/compatible selection. This preserves values across toggling
and avoids destructive normalization. UI prevents simultaneous active modes;
API precedence makes combinations deterministic without extra booleans.
## Profile transport
Propagate the field through `settings/dto`, handlers/controller mappings,
`lifecycle.AgentProfileInfo`, `profile_resolver.go`, both policy constructors in
`manager_profile.go`, and `StartModelPolicy`. Propagate it through the internal
`orchestrator/executor.AgentProfileInfo` projection and `backendapp/adapters.go`.
Include it in the existing profile snapshot produced by
`executor.resolveAgentProfileSnapshot`; missing legacy snapshot fields mean
false. A snapshot is evidence, not a new competing source of profile policy.
Keep current profile-resolution timing: saving affects the next launch/reset/
rebind or cross-step decision, not an already-running turn. Preserve existing
model override precedence within a session.
Frontend mappings include `lib/types/agent-profile.ts`, API normalization and
serialization, settings store option conversion, editor drafts, dirty checks,
reconciliation, and settings discovery. Trace every existing `auto_fallback`
producer/consumer to check whether it also carries the new profile field.
Do not add strictness to provider wire protocols: the host owns this policy.
## Shared policy
`applyStartModelPolicy` remains the single owner of `SetModel` decisions.
Never send an ID absent from the current executor catalog. Later config layers
must not repeat a handled selection. Exactness compares full IDs, including
provider prefixes and bracketed suffixes.
For strict profiles, ignore dormant fallback choices. Require a non-empty
requested ID, advertise it, and apply it before ready/initial prompt. Empty
catalog, absent requested ID, unsupported selection, or selection error fails
with sanitized evidence. Runtime guards also reject strict+empty if storage
validation was bypassed. An intentional session override supplies the effective
requested ID under the existing override contract; this setting is not a lock
against explicit user model changes.
### Compatible selection order
Use merge base `ba960f973205854733e0dcd9afa355bdda3dddf6` as the compatibility
oracle for selection, not the PR's new strict tests:
1. Empty requested model means no explicit selection and no mismatch warning.
2. Apply the requested model if advertised.
3. With automatic fallback on and the requested model absent, continue on the
executor current/default model. Ignore saved explicit fallback and variations.
4. Otherwise apply an advertised explicit fallback when available.
5. Otherwise resolve one distinct advertised bracketed variation of a bare ID.
Restore the removed `uniqueAdvertisedModelVariation` runtime behavior only
here. Deduplicate matching IDs; reject empty/nested brackets, ambiguous
matches, and already-bracketed requests. Do not rank suffixes or catalog order.
6. Otherwise keep the executor current/default model and warn.
An empty catalog follows step 6. Unsupported model selection retains the
provider default and warns for compatible profiles. Other advertised apply
errors still fail unless existing automatic fallback permits continuation.
Do not catch initialization failure, transport disconnect, or cancellation as a
catalog mismatch. The setting does not make all failures recoverable.
| Runtime case | Strict on | Strict off, auto off | Strict off, auto on |
| --- | --- | --- | --- |
| Requested advertised and applies | Requested | Requested | Requested |
| Requested absent, fallback advertised | Error | Explicit fallback | Executor default |
| No fallback, unique variation | Error | Variation | Executor default |
| Missing/empty catalog or no match | Error | Executor default | Executor default |
| Selection method unsupported | Error | Executor default | Executor default |
| Ordinary advertised apply error | Error | Error | Executor default |
| Initialization fails/cancelled | Error | Error | Error |
The stricter PR behavior remains valuable when selected explicitly. Its tests
must set the new field instead of relying on `auto_fallback=false`.
## Warnings and existing boundaries
Reuse `ModelSelectionDecision`, the lifecycle warning event, and the persisted
`status` message with `metadata.kind=model_selection_warning`. Restore the
`unique_variation` decision outcome and existing effective-model warning path
for compatible variation selection. Preserve one warning per selection decision,
requested/effective model attribution, unknown-effective-model text, and reload
idempotency. Failed strict attempts emit errors, not successful fallback notices.
No credentials or provider configuration content belongs in metadata.
Keep gone saved models visible and unselectable in editors without rewriting
profile values. Host probes remain advisory. Do not restore editor-side ID
replacement to achieve runtime compatibility. Office post-start routing remains
owned by workspace policy; never repurpose `auto_fallback` or strictness as a
new workspace routing gate. Existing authorization and secret sanitization apply.
Preserve existing provider-specific launch preparation, including cold Claude
model exposure and request/executor/profile environment precedence. Dormant
fallback choices must not authorize strict selection. This package adds no
provider-specific environment contract, cache copying, or unadvertised selection.
## Decision
[Explicit per-profile exact model policy](../../../decisions/2026-09-15-explicit-profile-model-strictness.md)
supersedes the implicit strict default and records why a global setting and a
bulk automatic-fallback migration are not used.
@@ -3,73 +3,108 @@ status: current
system: agents
requirements:
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003
created: 2026-08-23
owners:
- kandev
---
# No Silent Model Fallback System Design Part 2
# No Silent Model Fallback: Recovery and Profile Surfaces
## Purpose and boundaries
## Mapping and scope
This design records risks for executor-authoritative model fallback and unique
variation resolution.
This design completes [the policy design](no-silent-model-fallback-01.md).
REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001 acceptance criteria .6/.7 map to profile
surfaces, .8/.9 to recovery/workflow, and .2/.10 to warnings/advisories.
## Requirement mapping
## Recovery and session ownership
| Requirement | Design section |
| --- | --- |
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001` | [Migrated source detail](#migrated-source-detail) |
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002` | [Risks & Open Questions](#risks--open-questions) |
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003` | [Risks & Open Questions](#risks--open-questions) |
Initial launch, context reset (`manager_interaction.go`), workspace rebind
(`manager_workspace_rebind.go`), and Kubernetes replacement
(`manager_kubernetes_refresh.go`) use the same resolved `StartModelPolicy`.
Preserve completed PR transport staging and delayed `session_models` handling.
A strict replacement waits for its own usable catalog, including an async
catalog after an empty session response. Timeout with no usable catalog fails
before inference. Never select from the previous published client on timeout.
## Migrated source detail
A compatible replacement may continue after a bounded catalog wait when its
session initialized successfully but advertised no usable models. Pass only
replacement evidence (including absent/empty state) to the shared policy and
persist its warning. Distinguish catalog absence from initialization/stream
failure and context cancellation. Cancellation always stops the attempt.
An empty non-nil snapshot is not proof of catalog readiness. Keep replacement
publication, rollback, and conversation identity ordering already fixed by the PR.
## Risks & Open Questions
In `sessionHasUnauthorizedExactModelDrift`, apply exact-model eligibility only
when the destination profile explicitly requires exactness. Dormant auto/fallback
values cannot authorize a different model for strict destinations. Unknown or
missing effective model also requires a fresh cross-step strict session.
Compatible destinations keep normal workflow reuse policy; model drift alone
is no longer a replacement reason. Profile changes and other existing session
eligibility rules still apply. Same-step explicit overrides remain intact.
- **Behavior change for existing profiles**: an unadvertised start model no
longer stops the launch. Kandev uses the executor agent default and persists
an actionable warning.
- **Office post-start fallback remains workspace-routing-governed**: a
default-mode profile's Office run can still be re-dispatched to another
provider mid-session by the ADR office policy (availability codes →
`DecisionFallback`). This is intentional — office authorization is the
workspace routing configuration, not the execution profile — and is
documented in the behavior matrix above.
- **Probe staleness**: the advertised list can be stale (probe cached).
The profile editor uses it only as a hint. Profile selectors do not render
host model advisories. The executor session catalog owns the launch decision.
- **Cold Claude model lists**: a valid restricted model can be absent from a
cold bridge's initial list. Pre-session exposure lets the bridge include and
select the configured model. If the bridge still omits it, Kandev uses the
agent default and persists a warning.
- **Context reset model changes**: this amendment covers the model selected
before the initial process starts. It does not restart a live ACP bridge to
expose a newly selected hidden model during context reset.
- **Office vs. kanban surfaces**: both share the same agent-profile rows.
The shared selector behavior covers kanban task creation and Office setup.
Office run-detail routing surfaces are unchanged.
- **Collapsed controls remain legible**: the disclosure header summarizes the
effective mode, and dirty-state decoration is applied to the disclosure
container so a collapsed section cannot conceal that it has unsaved changes.
- **Hover is supplementary**: every info icon is focusable, and coarse-pointer
devices receive the same content in a drawer. The visible option helper copy
remains the baseline explanation.
- **Provider-specific labels remain opaque**: `1m`, `270k`, and `fast` have no
Kandev-defined order. More than one variation therefore fails closed to the
existing provider-default path.
- **Host and executor decisions can differ**: a unique host variation is only
an advisory. The selected executor can advertise zero, one, or multiple
variations at launch.
- **Bracketed requests do not drift sideways**: a request such as `opus[1m]`
does not infer `opus[270k]`. The user must select another explicit model.
- **Legacy automatic fallback remains unchanged**: when `auto_fallback` is
enabled and the requested model is absent, Kandev does not apply an explicit
fallback or infer a variation. It continues with the provider default.
- **Removal must be narrow**: authentication, missing-CLI, and failed-probe
indicators remain. Profile-editor advisories and persisted task warnings
retain their existing behavior.
- **Evidence has limits**: a model warning does not prove a cache defect.
Discovery refresh or normalization changes require separate root-cause
evidence; this amendment does not change those contracts.
Retain the validated candidate passed to the switch path and the one-lookup
empty-candidate fix. Profile-read errors do not silently downgrade strictness.
Test all callers of the shared drift check, including human-to-work transitions.
A new conversation must not inherit a rejected provider resume identity.
## Profile surfaces
Entry point: Settings > Agents > concrete agent profile > Fallback settings.
Also update the shared controls used by `components/agent/cli-profile-editor.tsx`.
The setting applies to that profile on any executor. There is no global,
workspace, or executor override and no added item under System Feature Toggles.
Extend `ModelFallbackSection` and `ModelFallbackSettingsShell`:
- Place Require exact model first, as a full-width row in the expanded section.
- Show a visible helper: "Stop before starting if the selected model cannot be
used. Fallback settings do not apply while this is on."
- Strict on disables automatic and explicit fallback controls without clearing
them. Strict off restores the old automatic/explicit interaction. A dormant
auto=true must not win in the summary or control disabled state.
- Keep the disclosure initially collapsed, with effective summaries such as
"Exact model required", "Automatic fallback", "Fallback: {model}", or
"Executor default allowed". Summaries and helper copy must agree with the
compatible selection/error matrix, including default continuation when an
explicit fallback is also absent.
- Include the new field in dirty state, Save/Cancel, optimistic reconciliation,
normalization, and reload hydration. Updating only strictness must not be
mistaken for an enabled-only edit. Empty-model validation keeps the draft open.
- Keep the saved start model unchanged. An unavailable host model does not
disable the strict switch if the profile already has a concrete saved ID.
- Use `t()` and settings namespace keys for all copy. Translate English,
Portuguese, Simplified Chinese, and generated Traditional Chinese catalogs;
regenerate pseudo. Do not publish copy that describes every auto=false profile
as strict or promises a configured fallback is always the final alternative.
## Mobile contract
Nearest shipped exemplar: `ModelFallbackSettingsShell` with `FallbackOptionHelp`.
Reuse its shared form state, collapsed disclosure, and `useTouchDrawer` help.
Desktop keeps the strict row above two fallback columns. Phone uses one ordered
vertical flow: strictness, automatic fallback, explicit fallback, existing Save.
No separate phone policy or copied business logic.
This is an occasional settings edit; it remains inline on the profile page.
Use an inset bottom drawer only for supplementary help. The existing page or
editor scroll container remains the sole form scroll owner. Shared drawer
primitives handle dynamic viewport height and safe-area spacing. Close help
returns focus to its trigger without closing the form or losing draft values.
Ordinary desktop controls keep 28px sizing; touch row/help hit targets are at
least 44px (both dimensions for icon buttons), scoped to phone/coarse pointers.
Measure actual bounds and hit testing. Check long translated labels, disabled
states, keyboard toggle/save, document overflow, and coarse-pointer tablets.
The plan's UI-01/UI-02 previews define order and grouping, not pixel geometry.
## Verification and remaining limits
Use real store migrations for upgrade evidence, policy unit tests for the full
matrix, and lifecycle transport tests for delayed replacement catalogs and
cancellation. Pair model-policy tests with an actual migrated profile launch;
a fabricated zero-value policy alone does not prove upgrade compatibility.
Desktop and mobile E2E cover saved toggles, launch continuation/error, drawer
interaction, and persisted warnings. A mock E2E catalog mismatch does not prove
provider credentials or every external executor integration.
Keep public docs updates in the implementation work orders. The existing public
pages now describe the implemented compatible-by-default policy.