pi-delegation-policy 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-06
+
+### Added
+
+- Add the `orchestrator` intensity with `/delegate orchestrator` and `D:ORCH`. It delegates transferable research, detailed planning, implementation, testing, writing, review, and integration mechanics while keeping objectives, critical decisions, coordination, evidence, and final acceptance with the main agent.
+- Add orchestrator guidance for batching small work, concise briefs and results with file references, and avoiding duplicate inspection without a concrete gap or risk.
+
+## 0.6.0 - 2026-08-29
+
+### Added
+
+- Allow Small, Medium, and Large to be explicitly disabled independently while requiring one enabled ordinary role for an active policy.
+- Add schema 3 defaults and session state, with in-memory schema 2 migration and guarded session writes for safer downgrade behavior. Downgrading after saving schema 3 defaults or manually editing them requires `/delegate off` in each active branch and manual conversion of ordinary `null` values.
+
+### Changed
+
+- Select only enabled ordinary roles that can satisfy the task, leaving work with the main agent when none can; Small/Medium preferences are inactive when either role is disabled.
+
 ## 0.5.0 - 2026-08-28
 
 ### Added

package/README.md

@@ -1,25 +1,27 @@
 # pi-delegation-policy
 
-A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for the Small, Medium, Large, and optional Visual Design roles. It provides guidance; it is not a subagent runner.
+A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for Small, Medium, Large, and optional Visual Design. It provides guidance; it is not a subagent runner.
 
-> **Status:** Version **0.5.0** is the latest published package. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline (newer versions are not claimed as tested). The repository and npm package describe the same published behavior.
+> **Status:** Version **0.7.0** is the latest published package and supports `off`, `normal`, `aggressive`, and `orchestrator`. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline.
 >
 > **Docs:** [Read the documentation site](https://yivas.github.io/pi-delegation-policy/).
 
 ## Value and boundary
 
-- Choose `off`, `normal`, or `aggressive` delegation intensity globally or for the current session branch.
-- Configure exact provider/model references for Small, Medium, Large, and optionally Visual Design.
+- Choose `off`, `normal`, `aggressive`, or `orchestrator` globally or for the current session branch.
+- Configure an exact provider/model reference or explicitly disable each ordinary role.
 - Keep global defaults and session-branch overrides across reload, resume, and tree navigation.
 - Validate active configurations before injecting one policy block through Pi's public `before_agent_start` event.
 
-The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
+The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. `orchestrator` delegates transferable execution detail and batches small work while the main agent retains objectives, critical decisions, coordination, integration responsibility, requested evidence, and final acceptance. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
 
-Visual Design is an optional specialist for direction, assets, bounded presentation-layer implementation, and visual review. Use it only when behavior and data contracts are already defined and unchanged, the affected surface is bounded, and visual quality or user experience is the primary acceptance criterion. Route business logic, data, APIs, routes, application architecture, tooling, interaction behavior, and cross-system integration to Small, Medium, or Large by task fit. The main agent retains final integration and acceptance.
+A valid active policy requires an explicit decision for Small, Medium, and Large: an exact model reference or disabled. At least one ordinary role must remain enabled. A disabled role is not validated. An absent role, an invalid enabled reference, or no enabled ordinary role produces `D:ERR` and injects no policy. `off` always produces `D:OFF` without injection.
 
-## Install and start
+The policy considers only enabled ordinary roles, chooses the least costly role that can satisfy the task's acceptance criteria and evidence, and keeps work with the main agent when none can. It never invents a model or role. `efficient` and `intensive` are tie-breaks only when both Small and Medium are enabled; otherwise their bias is inactive.
+
+Visual Design is an independent optional specialist for direction, assets, bounded presentation-layer implementation, and visual review. Use it only when behavior and data contracts are already defined and unchanged, the affected surface is bounded, and visual quality or user experience is the primary acceptance criterion. It does not count as an ordinary role or replace one. Route business logic, data, APIs, routes, application architecture, tooling, interaction behavior, and cross-system integration to an enabled ordinary role by task fit. The main agent retains final integration and acceptance.
 
-Install the published package in Pi's user settings, then reload Pi:
+## Install and start
 
 ```bash
 pi install npm:pi-delegation-policy
@@ -27,12 +29,16 @@ pi install npm:pi-delegation-policy
 ```
 
 1. Open `/delegate` (or press `Alt+G` in Pi's TUI).
-2. Configure exact, authenticated Small, Medium, and Large provider/model references. Visual Design is optional.
-3. Select `normal` or `aggressive`, then choose **Apply changes**.
-4. Run `/delegate status` and inspect the exact role references and their sources. `D:ERR` means an active required role is invalid; no policy is injected.
-5. The applied state affects the **next** agent run. An agent already running is not rewritten.
+2. For Small, Medium, and Large, select an exact authenticated provider/model or **Disable for this session**. Keep at least one enabled.
+3. Select `normal`, `aggressive`, or `orchestrator`, then choose **Apply changes**.
+4. Run `/delegate status`. `disabled`, `not configured`, and exact references remain distinct. `D:ERR` means no policy is injected.
+5. The applied state affects the **next** agent run.
+
+Global defaults are stored at `~/.pi/agent/delegation-policy.json` and use schema version 3. Schema 2 defaults and session entries are read and normalized in memory without rewriting them. Schema 3 stores `null` for an explicitly disabled ordinary role. Session changes write a schema 2 `off` guard before the schema 3 state; saving defaults changes only the global file.
 
-See the [end-to-end getting-started guide](https://yivas.github.io/pi-delegation-policy/getting-started/) and [configuration reference](https://yivas.github.io/pi-delegation-policy/configuration/) for details.
+Before downgrading to `0.6.0`, change the global intensity to `off`, `normal`, or `aggressive` and run `/delegate off` in every active branch. For `<=0.5.0`, also convert global defaults to schema 2 and replace ordinary `null` values with exact model references. Schema 2 never accepts `orchestrator`. See the configuration reference for details.
+
+See the [getting-started guide](https://yivas.github.io/pi-delegation-policy/getting-started/) and [configuration reference](https://yivas.github.io/pi-delegation-policy/configuration/).
 
 ## Essential commands
 
@@ -41,17 +47,12 @@ See the [end-to-end getting-started guide](https://yivas.github.io/pi-delegation
 /delegate off                     Disable policy for this session branch
 /delegate normal                  Enable balanced delegation guidance
 /delegate aggressive              Enable delegation-first guidance
+/delegate orchestrator             Minimize main-agent execution and narration
 /delegate status                  Show effective session state
 /delegate reset                   Reset this branch to off and other fields to global defaults
 ```
 
-The editor is a bounded, keyboard-first panel. It shows model ID first and `[provider]` last, fuzzy-searches provider, model ID, and display name, and shows at most 10 model rows. It also shows a compact effective-policy preview, field explanations, and public model metadata when Pi supplies it. Changes are drafts until **Apply changes**; saving effective configuration as defaults updates the global file without applying the draft, and closing a modified draft requires explicit discard.
-
-## Configuration and safety
-
-Global defaults are stored at `~/.pi/agent/delegation-policy.json` (schema version 2). The file stores optional intensity, preference, exact role references, and an optional Visual Design reference under the stable `uiDesign` key; it never stores thinking. A valid active mode requires exact, available, in-scope, authenticated Small, Medium, and Large references. Before every delegated launch, the policy requires the selected role's exact `provider/model` base and a thinking level chosen for that task instead of relying on ambient defaults. With `pi-subagents`, the main agent passes both as `model: "provider/model:LEVEL"`; other launchers may expose a separate per-run thinking field. Invalid active configuration fails closed as `D:ERR` with no policy injection; `off` is always `D:OFF`.
-
-The extension stores only policy settings and provider/model identifiers in local defaults and session entries. Review local configuration before sharing diagnostics, and remove credentials, prompts, personal paths, session files, and unredacted logs from reports. See the [limits and privacy reference](https://yivas.github.io/pi-delegation-policy/limits-and-privacy/) and [security policy](https://github.com/Yivas/pi-delegation-policy/blob/main/SECURITY.md).
+The editor is a bounded, keyboard-first panel. Every model selector pins **Use global default** and **Disable for this session** before searchable models. It shows model ID first and `[provider]` last, fuzzy-searches provider, model ID, and display name, and shows at most 10 model rows. It also shows a compact effective-policy preview, field explanations, and public model metadata when Pi supplies it. Changes are drafts until **Apply changes**; saving effective configuration as defaults updates only the global file without applying the draft, and closing a modified draft requires explicit discard.
 
 ## Development
 
@@ -65,8 +66,8 @@ npm run build
 npm run pack:check
 ```
 
-Tests use local mocks and do not make paid model calls or network requests. See [CONTRIBUTING.md](https://github.com/Yivas/pi-delegation-policy/blob/main/CONTRIBUTING.md) for contribution guidance.
+Tests use local mocks and do not make paid model calls or network requests. See [CONTRIBUTING.md](https://github.com/Yivas/pi-delegation-policy/blob/main/CONTRIBUTING.md).
 
 ## License
 
-MIT. See [LICENSE](https://github.com/Yivas/pi-delegation-policy/blob/main/LICENSE).
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -14,4 +14,4 @@ Include the affected version or commit, operating system, Pi version, reproducti
 
 ## Supported versions
 
-Only the latest published version is supported. Version 0.5.0 is the current supported release.
+Only the latest published version is supported. Version 0.7.0 is the current supported release.

package/examples/global.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "intensity": "normal",
   "preference": "standard",
   "small": {
@@ -10,10 +10,7 @@
     "provider": "example-provider",
     "model": "example-medium"
   },
-  "large": {
-    "provider": "example-provider",
-    "model": "example-large"
-  },
+  "large": null,
   "uiDesign": {
     "provider": "example-provider",
     "model": "example-ui-design"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",
@@ -44,10 +44,10 @@
     "@earendil-works/pi-ai": "0.84.3",
     "@earendil-works/pi-coding-agent": "0.84.3",
     "@earendil-works/pi-tui": "0.84.3",
-    "@eslint/js": "^9.39.5",
-    "@types/node": "^22.0.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.2.0",
     "ajv": "^8.20.0",
-    "eslint": "^9.0.0",
+    "eslint": "^10.9.1",
     "prettier": "^3.0.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.68.0"

package/schema/delegation-policy.schema.json

@@ -5,12 +5,12 @@
   "type": "object",
   "required": ["schemaVersion"],
   "properties": {
-    "schemaVersion": { "const": 2 },
-    "intensity": { "enum": ["off", "normal", "aggressive"] },
+    "schemaVersion": { "const": 3 },
+    "intensity": { "enum": ["off", "normal", "aggressive", "orchestrator"] },
     "preference": { "enum": ["efficient", "standard", "intensive"] },
-    "small": { "$ref": "#/$defs/modelRef" },
-    "medium": { "$ref": "#/$defs/modelRef" },
-    "large": { "$ref": "#/$defs/modelRef" },
+    "small": { "$ref": "#/$defs/ordinaryRole" },
+    "medium": { "$ref": "#/$defs/ordinaryRole" },
+    "large": { "$ref": "#/$defs/ordinaryRole" },
     "uiDesign": { "$ref": "#/$defs/modelRef" }
   },
   "$defs": {
@@ -22,6 +22,9 @@
         "model": { "type": "string", "minLength": 1 }
       },
       "additionalProperties": false
+    },
+    "ordinaryRole": {
+      "anyOf": [{ "$ref": "#/$defs/modelRef" }, { "type": "null" }]
     }
   },
   "additionalProperties": false

package/src/config.ts

@@ -2,12 +2,16 @@ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import {
+  CURRENT_SCHEMA_VERSION,
+  INTENSITIES,
   emptyGlobalDefaults,
   emptySessionState,
   type EffectiveDelegateState,
   type GlobalDefaults,
   type Intensity,
   type ModelRef,
+  type ModelRole,
+  type OrdinaryRoleSetting,
   type Preference,
   type SessionDelegateState,
   type ValueSource,
@@ -19,11 +23,23 @@ export const SESSION_ENTRY_TYPE = "pi-delegation-policy:session";
 export const GLOBAL_CONFIG_NAME = "delegation-policy.json";
 
 const LEGACY_SCHEMA_MESSAGE =
-  "Global defaults use schema version 1. Configure schema version 2 with /delegate before activating delegation.";
+  "Global defaults use schema version 1. Configure schema version 3 with /delegate before activating delegation.";
 const INVALID_CONFIG_MESSAGE = "Global defaults are invalid. Configure them again with /delegate.";
+const INVALID_SESSION_MESSAGE =
+  "The latest delegation session state is invalid or unsupported. Delegation is off for safety.";
+const CONFIG_KEYS = [
+  "schemaVersion",
+  "intensity",
+  "preference",
+  "small",
+  "medium",
+  "large",
+  "uiDesign",
+] as const;
 
 export type ConfigDiagnostic = {
   message: string;
+  reportWhenOff?: boolean;
 };
 
 export type LoadedDefaults = {
@@ -31,6 +47,26 @@ export type LoadedDefaults = {
   diagnostics: ConfigDiagnostic[];
 };
 
+export type RestoredSessionState = {
+  session: SessionDelegateState;
+  diagnostics: ConfigDiagnostic[];
+};
+
+export type SessionEntryWriter = { appendEntry: (type: string, data?: unknown) => void };
+export type GuardedAppendResult = "success" | "guard-failed" | "state-failed";
+
+type Schema2GlobalDefaults = {
+  schemaVersion: 2;
+  intensity?: LegacyIntensity;
+  preference?: Preference;
+  small?: ModelRef;
+  medium?: ModelRef;
+  large?: ModelRef;
+  uiDesign?: ModelRef;
+};
+
+type Schema2SessionState = Omit<Schema2GlobalDefaults, "uiDesign"> & { uiDesign?: ModelRef | null };
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -40,7 +76,14 @@ function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly strin
 }
 
 function isIntensity(value: unknown): value is Intensity {
-  return value === "off" || value === "normal" || value === "aggressive";
+  return INTENSITIES.some((intensity) => intensity === value);
+}
+
+const LEGACY_INTENSITIES = ["off", "normal", "aggressive"] as const;
+type LegacyIntensity = (typeof LEGACY_INTENSITIES)[number];
+
+function isLegacyIntensity(value: unknown): value is LegacyIntensity {
+  return LEGACY_INTENSITIES.some((intensity) => intensity === value);
 }
 
 function isPreference(value: unknown): value is Preference {
@@ -60,33 +103,31 @@ function parseModelRef(value: unknown): ModelRef | undefined {
   return { provider: value.provider, model: value.model };
 }
 
-function copyModelRef(value: ModelRef | undefined): ModelRef | undefined {
-  return value ? { ...value } : undefined;
+function copyRoleSetting(value: OrdinaryRoleSetting | undefined): OrdinaryRoleSetting | undefined {
+  return value === null ? null : value ? { ...value } : undefined;
 }
 
-export function parseConfig(value: unknown): GlobalDefaults | undefined {
-  if (
-    !isRecord(value) ||
-    !hasOnlyKeys(value, [
-      "schemaVersion",
-      "intensity",
-      "preference",
-      "small",
-      "medium",
-      "large",
-      "uiDesign",
-    ]) ||
-    value.schemaVersion !== 2 ||
-    (value.intensity !== undefined && !isIntensity(value.intensity)) ||
-    (value.preference !== undefined && !isPreference(value.preference))
-  )
-    return undefined;
+function hasValidEnvelope(
+  value: unknown,
+  schemaVersion: 2 | 3,
+  intensityValidator: (value: unknown) => boolean = isIntensity,
+): value is Record<string, unknown> {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, CONFIG_KEYS) &&
+    value.schemaVersion === schemaVersion &&
+    (value.intensity === undefined || intensityValidator(value.intensity)) &&
+    (value.preference === undefined || isPreference(value.preference))
+  );
+}
 
+function parseSchema2Roles(
+  value: Record<string, unknown>,
+): Pick<Schema2GlobalDefaults, "small" | "medium" | "large" | "uiDesign"> | undefined {
   const small = value.small === undefined ? undefined : parseModelRef(value.small);
   const medium = value.medium === undefined ? undefined : parseModelRef(value.medium);
   const large = value.large === undefined ? undefined : parseModelRef(value.large);
   const uiDesign = value.uiDesign === undefined ? undefined : parseModelRef(value.uiDesign);
-
   if (
     (value.small !== undefined && !small) ||
     (value.medium !== undefined && !medium) ||
@@ -94,11 +135,7 @@ export function parseConfig(value: unknown): GlobalDefaults | undefined {
     (value.uiDesign !== undefined && !uiDesign)
   )
     return undefined;
-
   return {
-    schemaVersion: 2,
-    ...(value.intensity ? { intensity: value.intensity } : {}),
-    ...(value.preference ? { preference: value.preference } : {}),
     ...(small ? { small } : {}),
     ...(medium ? { medium } : {}),
     ...(large ? { large } : {}),
@@ -106,51 +143,147 @@ export function parseConfig(value: unknown): GlobalDefaults | undefined {
   };
 }
 
-export function parseSessionState(value: unknown): SessionDelegateState | undefined {
+export function parseSchema2Config(value: unknown): Schema2GlobalDefaults | undefined {
+  if (!hasValidEnvelope(value, 2, isLegacyIntensity)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isLegacyIntensity(intensity)) return undefined;
+  const roles = parseSchema2Roles(value);
+  if (!roles) return undefined;
+  return {
+    schemaVersion: 2,
+    ...(intensity ? { intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...roles,
+  };
+}
+
+export function parseSchema3Config(value: unknown): GlobalDefaults | undefined {
+  if (!hasValidEnvelope(value, CURRENT_SCHEMA_VERSION)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isIntensity(intensity)) return undefined;
+  const parseOrdinary = (setting: unknown): OrdinaryRoleSetting | undefined =>
+    setting === null ? null : parseModelRef(setting);
+  const small = value.small === undefined ? undefined : parseOrdinary(value.small);
+  const medium = value.medium === undefined ? undefined : parseOrdinary(value.medium);
+  const large = value.large === undefined ? undefined : parseOrdinary(value.large);
+  const uiDesign = value.uiDesign === undefined ? undefined : parseModelRef(value.uiDesign);
   if (
-    !isRecord(value) ||
-    !hasOnlyKeys(value, [
-      "schemaVersion",
-      "intensity",
-      "preference",
-      "small",
-      "medium",
-      "large",
-      "uiDesign",
-    ]) ||
-    value.schemaVersion !== 2 ||
-    (value.intensity !== undefined && !isIntensity(value.intensity)) ||
-    (value.preference !== undefined && !isPreference(value.preference))
+    (value.small !== undefined && small === undefined) ||
+    (value.medium !== undefined && medium === undefined) ||
+    (value.large !== undefined && large === undefined) ||
+    (value.uiDesign !== undefined && !uiDesign)
   )
     return undefined;
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(intensity ? { intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(small !== undefined ? { small } : {}),
+    ...(medium !== undefined ? { medium } : {}),
+    ...(large !== undefined ? { large } : {}),
+    ...(uiDesign ? { uiDesign } : {}),
+  };
+}
 
-  const small = value.small === undefined ? undefined : parseModelRef(value.small);
-  const medium = value.medium === undefined ? undefined : parseModelRef(value.medium);
-  const large = value.large === undefined ? undefined : parseModelRef(value.large);
+function migrateSchema2Config(value: Schema2GlobalDefaults): GlobalDefaults {
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(value.intensity ? { intensity: value.intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(value.small ? { small: { ...value.small } } : {}),
+    ...(value.medium ? { medium: { ...value.medium } } : {}),
+    ...(value.large ? { large: { ...value.large } } : {}),
+    ...(value.uiDesign ? { uiDesign: { ...value.uiDesign } } : {}),
+  };
+}
+
+export function parseConfig(value: unknown): GlobalDefaults | undefined {
+  return (
+    parseSchema3Config(value) ??
+    (() => {
+      const schema2 = parseSchema2Config(value);
+      return schema2 ? migrateSchema2Config(schema2) : undefined;
+    })()
+  );
+}
+
+function parseSchema2SessionState(value: unknown): Schema2SessionState | undefined {
+  if (!hasValidEnvelope(value, 2, isLegacyIntensity)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isLegacyIntensity(intensity)) return undefined;
   const uiDesign =
     value.uiDesign === undefined || value.uiDesign === null
       ? value.uiDesign
       : parseModelRef(value.uiDesign);
+  const roles = parseSchema2Roles({ ...value, uiDesign: undefined });
+  if (!roles || (value.uiDesign !== undefined && value.uiDesign !== null && !uiDesign))
+    return undefined;
+  return {
+    schemaVersion: 2,
+    ...(intensity ? { intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...roles,
+    ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
+  };
+}
 
+function parseSchema3SessionState(value: unknown): SessionDelegateState | undefined {
+  if (!hasValidEnvelope(value, CURRENT_SCHEMA_VERSION)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isIntensity(intensity)) return undefined;
+  const parseOrdinary = (setting: unknown): OrdinaryRoleSetting | undefined =>
+    setting === null ? null : parseModelRef(setting);
+  const small = value.small === undefined ? undefined : parseOrdinary(value.small);
+  const medium = value.medium === undefined ? undefined : parseOrdinary(value.medium);
+  const large = value.large === undefined ? undefined : parseOrdinary(value.large);
+  const uiDesign =
+    value.uiDesign === undefined || value.uiDesign === null
+      ? value.uiDesign
+      : parseModelRef(value.uiDesign);
   if (
-    (value.small !== undefined && !small) ||
-    (value.medium !== undefined && !medium) ||
-    (value.large !== undefined && !large) ||
+    (value.small !== undefined && small === undefined) ||
+    (value.medium !== undefined && medium === undefined) ||
+    (value.large !== undefined && large === undefined) ||
     (value.uiDesign !== undefined && value.uiDesign !== null && !uiDesign)
   )
     return undefined;
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(intensity ? { intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(small !== undefined ? { small } : {}),
+    ...(medium !== undefined ? { medium } : {}),
+    ...(large !== undefined ? { large } : {}),
+    ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
+  };
+}
 
+function migrateSchema2SessionState(value: Schema2SessionState): SessionDelegateState {
   return {
-    schemaVersion: 2,
+    schemaVersion: CURRENT_SCHEMA_VERSION,
     ...(value.intensity ? { intensity: value.intensity } : {}),
-    ...(value.preference ? { preference: value.preference } : {}),
-    ...(small ? { small } : {}),
-    ...(medium ? { medium } : {}),
-    ...(large ? { large } : {}),
-    ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(value.small ? { small: { ...value.small } } : {}),
+    ...(value.medium ? { medium: { ...value.medium } } : {}),
+    ...(value.large ? { large: { ...value.large } } : {}),
+    ...(value.uiDesign === null
+      ? { uiDesign: null }
+      : value.uiDesign
+        ? { uiDesign: { ...value.uiDesign } }
+        : {}),
   };
 }
 
+export function parseSessionState(value: unknown): SessionDelegateState | undefined {
+  return (
+    parseSchema3SessionState(value) ??
+    (() => {
+      const schema2 = parseSchema2SessionState(value);
+      return schema2 ? migrateSchema2SessionState(schema2) : undefined;
+    })()
+  );
+}
+
 function isLegacyConfig(value: unknown): boolean {
   return isRecord(value) && value.schemaVersion === 1;
 }
@@ -195,64 +328,111 @@ async function atomicWrite(path: string, value: unknown): Promise<void> {
 }
 
 export async function writeConfig(path: string, defaults: GlobalDefaults): Promise<void> {
-  const parsed = parseConfig(defaults);
+  const parsed = parseSchema3Config(defaults);
   if (!parsed) throw new Error("Refusing to write invalid delegation policy defaults.");
   await atomicWrite(path, parsed);
 }
 
-export function restoreSessionState(entries: unknown[]): SessionDelegateState {
+export function restoreSessionStateWithDiagnostics(entries: unknown[]): RestoredSessionState {
   for (let index = entries.length - 1; index >= 0; index -= 1) {
     const entry = entries[index] as Record<string, unknown> | undefined;
     if (entry?.type !== "custom" || entry.customType !== SESSION_ENTRY_TYPE) continue;
-    const state = parseSessionState(entry.data);
-    if (state) return state;
+    const session = parseSessionState(entry.data);
+    if (session) return { session, diagnostics: [] };
+    return {
+      session: { schemaVersion: CURRENT_SCHEMA_VERSION, intensity: "off" },
+      diagnostics: [{ message: INVALID_SESSION_MESSAGE, reportWhenOff: true }],
+    };
   }
-  return emptySessionState();
+  return { session: emptySessionState(), diagnostics: [] };
 }
 
-function sourceFor<T>(sessionValue: T | undefined, globalValue: T | undefined): ValueSource {
-  if (sessionValue !== undefined) return "session";
+export function restoreSessionState(entries: unknown[]): SessionDelegateState {
+  return restoreSessionStateWithDiagnostics(entries).session;
+}
+
+function sourceFor<T>(
+  session: Record<string, unknown>,
+  globalValue: T | undefined,
+  key: string,
+): ValueSource {
+  if (Object.hasOwn(session, key)) return "session";
   if (globalValue !== undefined) return "global";
   return "default";
 }
 
+function resolveRole(
+  globalValue: OrdinaryRoleSetting | undefined,
+  session: SessionDelegateState,
+  role: ModelRole,
+): OrdinaryRoleSetting | undefined {
+  return copyRoleSetting(Object.hasOwn(session, role) ? session[role] : globalValue);
+}
+
 export function resolveDelegateState(
   defaults: GlobalDefaults,
   session: SessionDelegateState,
 ): EffectiveDelegateState {
   const uiDesign =
     session.uiDesign === undefined
-      ? copyModelRef(defaults.uiDesign)
+      ? defaults.uiDesign
+        ? { ...defaults.uiDesign }
+        : undefined
       : session.uiDesign === null
         ? undefined
-        : copyModelRef(session.uiDesign);
+        : { ...session.uiDesign };
+  const small = resolveRole(defaults.small, session, "small");
+  const medium = resolveRole(defaults.medium, session, "medium");
+  const large = resolveRole(defaults.large, session, "large");
 
   return {
     intensity: session.intensity ?? defaults.intensity ?? "off",
     preference: session.preference ?? defaults.preference ?? "standard",
-    small: copyModelRef(session.small ?? defaults.small),
-    medium: copyModelRef(session.medium ?? defaults.medium),
-    large: copyModelRef(session.large ?? defaults.large),
+    ...(small !== undefined ? { small } : {}),
+    ...(medium !== undefined ? { medium } : {}),
+    ...(large !== undefined ? { large } : {}),
     ...(uiDesign ? { uiDesign } : {}),
     source: {
-      intensity: sourceFor(session.intensity, defaults.intensity),
-      preference: sourceFor(session.preference, defaults.preference),
-      small: sourceFor(session.small, defaults.small),
-      medium: sourceFor(session.medium, defaults.medium),
-      large: sourceFor(session.large, defaults.large),
-      uiDesign: sourceFor(session.uiDesign, defaults.uiDesign),
+      intensity: sourceFor(session, defaults.intensity, "intensity"),
+      preference: sourceFor(session, defaults.preference, "preference"),
+      small: sourceFor(session, defaults.small, "small"),
+      medium: sourceFor(session, defaults.medium, "medium"),
+      large: sourceFor(session, defaults.large, "large"),
+      uiDesign: sourceFor(session, defaults.uiDesign, "uiDesign"),
     },
   };
 }
 
 export function defaultsFromEffectiveState(state: EffectiveDelegateState): GlobalDefaults {
+  const role = (setting: OrdinaryRoleSetting | undefined) =>
+    setting === undefined ? {} : setting === null ? { value: null } : { value: { ...setting } };
+  const small = role(state.small);
+  const medium = role(state.medium);
+  const large = role(state.large);
   return {
-    schemaVersion: 2,
+    schemaVersion: CURRENT_SCHEMA_VERSION,
     intensity: state.intensity,
     preference: state.preference,
-    ...(state.small ? { small: { ...state.small } } : {}),
-    ...(state.medium ? { medium: { ...state.medium } } : {}),
-    ...(state.large ? { large: { ...state.large } } : {}),
+    ...("value" in small ? { small: small.value } : {}),
+    ...("value" in medium ? { medium: medium.value } : {}),
+    ...("value" in large ? { large: large.value } : {}),
     ...(state.uiDesign ? { uiDesign: { ...state.uiDesign } } : {}),
   };
 }
+
+export function appendGuardedSessionState(
+  pi: SessionEntryWriter,
+  session: SessionDelegateState,
+): GuardedAppendResult {
+  try {
+    pi.appendEntry(SESSION_ENTRY_TYPE, { schemaVersion: 2, intensity: "off" });
+  } catch {
+    return "guard-failed";
+  }
+  try {
+    pi.appendEntry(SESSION_ENTRY_TYPE, session);
+    return "success";
+  } catch {
+    return "state-failed";
+  }
+}