@fastagent-sh/fastagent 0.16.1 → 0.16.2

package/dist/engines/pi/harness.d.ts

@@ -9,8 +9,9 @@
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import type { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
-import type { PiSessionStore } from "./sessions.ts";
+import { type PiSessionStore } from "./sessions.ts";
 import { type MountedTool } from "./tool.ts";
+import { type OverrideEntryLike } from "./session-settings.ts";
 /**
  * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
  * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
@@ -84,36 +85,19 @@ export declare const SUMMARIZATION_RETRY_POLICY: {
     readonly maxRetries: 3;
     readonly baseDelayMs: 2000;
 };
-export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
-/** The shape both override consumers walk — a session entry, structurally. */
-export interface OverrideEntryLike {
-    type: string;
-    provider?: string;
-    modelId?: string;
-    thinkingLevel?: string;
-}
 /**
- * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
- * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
- * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
- * skipped over to an earlier record: the reporting surface and the execution surface must agree on
- * which record is "the" override.
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
+ * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
+ * here means an upstream default change in either place cannot silently alter deployments. Models
+ * that don't support a level are clamped by pi per model.
  */
-export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
-    model?: {
-        provider: string;
-        modelId: string;
-    };
-    thinkingLevel?: string;
-};
+export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
 /**
- * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
- * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
- * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
- * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
- * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
- * back to the default with a deduped warn (fail visibly without bricking the session — the
- * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
+ * being executable with no control-plane command involved (pi appends these entries itself; a
+ * deployment's configured model can change between restarts). Deduped per session+cause — it would
+ * otherwise repeat every turn.
  */
 export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
     model: AnyModel;

package/dist/engines/pi/harness.js

@@ -8,7 +8,9 @@
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import { log } from "../../log.js";
+import { activePathEntries } from "./sessions.js";
 import { isDeferredTool } from "./tool.js";
+import { resolveSessionSettings } from "./session-settings.js";
 /**
  * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
  * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
@@ -48,7 +50,7 @@ export const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDe
  * here means an upstream default change in either place cannot silently alter deployments. Models
  * that don't support a level are clamped by pi per model.
  */
-const DEFAULT_THINKING_LEVEL = "medium";
+export const DEFAULT_THINKING_LEVEL = "medium";
 /**
  * Resolve the active-tool set for a fresh harness — the ONE place both fallbacks live. pi's harness
  * WRITES active-tool changes to the session (`setActiveTools` → `active_tools_change`) but its
@@ -72,83 +74,30 @@ const DEFAULT_THINKING_LEVEL = "medium";
  * (like L2's findings memo), not session state — the resolve stays derived from the session.
  */
 const warnedRestores = new Set();
-/** pi's ThinkingLevel scale as a checkable set — THE single source for fastagent (session entries
- *  store plain strings; session-control's dispatch validation and capabilities derive from this).
- *  The `satisfies Record<ThinkingLevel, …>` anchor makes it EXHAUSTIVE against pi's union: pi
- *  adding a level turns this into a type error instead of a silent drift where `set_thinking`
- *  rejects a value pi supports. */
-const ALL_THINKING_LEVELS = {
-    off: true,
-    minimal: true,
-    low: true,
-    medium: true,
-    high: true,
-    xhigh: true,
-    max: true,
-};
-export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
 /**
- * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
- * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
- * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
- * skipped over to an earlier record: the reporting surface and the execution surface must agree on
- * which record is "the" override.
- */
-export function lastOverrideEntries(entries) {
-    let model;
-    let modelSeen = false;
-    let thinkingLevel;
-    let thinkingSeen = false;
-    for (let i = entries.length - 1; i >= 0 && !(modelSeen && thinkingSeen); i--) {
-        const e = entries[i];
-        if (!modelSeen && e?.type === "model_change") {
-            modelSeen = true;
-            if (e.provider !== undefined && e.modelId !== undefined)
-                model = { provider: e.provider, modelId: e.modelId };
-        }
-        if (!thinkingSeen && e?.type === "thinking_level_change") {
-            thinkingSeen = true;
-            if (e.thinkingLevel !== undefined)
-                thinkingLevel = e.thinkingLevel;
-        }
-    }
-    return { model, thinkingLevel };
-}
-/**
- * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
- * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
- * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
- * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
- * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
- * back to the default with a deduped warn (fail visibly without bricking the session — the
- * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
+ * being executable with no control-plane command involved (pi appends these entries itself; a
+ * deployment's configured model can change between restarts). Deduped per session+cause — it would
+ * otherwise repeat every turn.
  */
 export function resolveHarnessOverrides(entries, models, defaults, sessionId) {
-    let model = defaults.model;
-    let thinkingLevel = defaults.thinkingLevel;
+    const settings = resolveSessionSettings(entries, models, defaults);
     const warnOnce = (key, message) => {
         const emit = warnedRestores.has(key) ? log.debug : log.warn;
         warnedRestores.add(key);
         emit(message);
     };
-    const recorded = lastOverrideEntries(entries);
-    if (recorded.model) {
-        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
-        if (found)
-            model = found;
-        else {
-            warnOnce(`${sessionId}\u0000model\u0000${recorded.model.provider}/${recorded.model.modelId}`, `[fastagent] session ${sessionId}: recorded model override ${recorded.model.provider}/${recorded.model.modelId} is not in this deployment's registry — using the configured default`);
-        }
+    const dropped = settings.dropped;
+    if (dropped?.model) {
+        warnOnce(`${sessionId}\u0000model\u0000${dropped.model}`, `[fastagent] session ${sessionId}: recorded model override ${dropped.model} is not in this deployment's registry — using the configured default`);
     }
-    if (recorded.thinkingLevel !== undefined) {
-        if (THINKING_LEVELS.has(recorded.thinkingLevel)) {
-            thinkingLevel = recorded.thinkingLevel;
-        }
-        else {
-            warnOnce(`${sessionId}\u0000thinking\u0000${recorded.thinkingLevel}`, `[fastagent] session ${sessionId}: recorded thinking level "${recorded.thinkingLevel}" is unknown — using the configured default`);
-        }
+    if (dropped?.thinkingLevel) {
+        const { recorded, running, known } = dropped.thinkingLevel;
+        warnOnce(`${sessionId}\u0000thinking\u0000${settings.model.provider}/${settings.model.id}\u0000${recorded}`, known
+            ? `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is not supported by ${settings.model.provider}/${settings.model.id} — running at "${running}"`
+            : `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is unknown — using the configured default`);
     }
-    return { model, thinkingLevel };
+    return { model: settings.model, thinkingLevel: settings.thinkingLevel };
 }
 export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     const anyDeferred = tools.some(isDeferredTool);
@@ -170,9 +119,10 @@ export function piHarnessFactory(options) {
     return async (sessionId) => {
         const session = await options.sessions.openOrCreate(sessionId);
         // One extra entry walk per invoke to collect the activation deltas — negligible against the model
-        // call, same trade as L2's per-invoke definition re-read. Serving sessions never branch, so a flat
-        // getEntries() read (no leaf-path walk) is correct.
-        const entries = await session.getEntries();
+        // call, same trade as L2's per-invoke definition re-read. The walk is over the ACTIVE PATH, not
+        // the flat journal: `navigate` moves the leaf, so the tree can hold an abandoned branch whose
+        // activations and overrides this session has left behind.
+        const entries = await activePathEntries(session);
         const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
             ? (e.data?.names ?? [])
             : []);

package/dist/engines/pi/open.js

@@ -102,6 +102,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
                     lease: parts.lease,
                     models: parts.models,
                     harnessFactory: parts.harnessFactory,
+                    defaults: parts.defaults,
                 };
             }
             : undefined,

package/dist/engines/pi/session-control.d.ts

@@ -1,8 +1,9 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Models } from "@earendil-works/pi-ai";
 import { type SessionControl, type SessionEvent } from "../../session.ts";
 import type { Lease, SessionObserver } from "./invoke.ts";
-import { type PiHarnessFactory } from "./harness.ts";
-import type { PiSessionReader } from "./sessions.ts";
+import { type AnyModel, type PiHarnessFactory } from "./harness.ts";
+import { type PiSessionReader } from "./sessions.ts";
 /** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
  *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
  *  has its buffer FROZEN at the cap (memory bounded — the actual goal: ≈10k small events ≈ a few
@@ -12,7 +13,7 @@ import type { PiSessionReader } from "./sessions.ts";
  *  permanently stalled one holds the frozen buffer until its TCP connection dies. Recovery either
  *  way is the standard reconnect+backfill, semantically lossless. */
 export declare const SUBSCRIBER_BUFFER_CAP = 10000;
-/** What boundary mutations (compact / set_model / set_thinking) need — the SAME instances the
+/** What boundary mutations (compact / set_model / set_thinking / navigate) need — the SAME instances the
  *  agent assembly uses: the lease (mutations must not race a run), the model registry (validation +
  *  allowedModels), and the harness factory (compaction is a model call). Writes go through the
  *  session the hub's reader opened — after an existence check, so the control plane never creates
@@ -21,6 +22,14 @@ export interface PiBoundaryWiring {
     lease: Lease;
     models: Models;
     harnessFactory: PiHarnessFactory;
+    /** The assembly's configured PAIR — what a session with no overrides runs on. One field because
+     *  model and thinking level are one setting: which levels exist is a property of the model, so a
+     *  wiring that could carry them apart could carry a pair no run uses. Must be what
+     *  {@link harnessFactory} was built with. */
+    defaults: {
+        model: AnyModel;
+        thinkingLevel: ThinkingLevel;
+    };
 }
 export interface CreatePiSessionControlOptions {
     /** Read-only access to the durable session repository (the same root the agent writes). */

package/dist/engines/pi/session-control.js

@@ -8,7 +8,7 @@
  * stays in the session repository (read via {@link PiSessionReader}), live truth in the events the
  * data plane emits, modulation in the controls the data plane registers.
  *
- * Boundary mutations (Phase 2b: compact/set_model/set_thinking) take the same lease as runs;
+ * Boundary mutations (Phase 2b: compact/set_model/set_thinking/navigate) take the same lease as runs;
  * without boundary wiring they are rejected before acceptance with `unsupported_capability` — a
  * client gating on `capabilities()` never sends them.
  */
@@ -16,8 +16,10 @@ import { DEFAULT_COMPACTION_SETTINGS, compact, prepareCompaction } from "@earend
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
 import { listModels } from "./config.js";
-import { SUMMARIZATION_RETRY_POLICY, THINKING_LEVELS, harnessSession, lastOverrideEntries, } from "./harness.js";
+import { SUMMARIZATION_RETRY_POLICY, harnessSession } from "./harness.js";
+import { THINKING_LEVELS, resolveSessionSettings } from "./session-settings.js";
 import { log } from "../../log.js";
+import { activePathEntries } from "./sessions.js";
 // ── Entry normalization (durable plane) ──────────────────────────────────────
 /** Concatenated plain text of a message's content blocks (the L0 rendering payload). A custom
  *  AgentMessage role may carry no `content` at all — that reads as empty, not a crash. */
@@ -73,6 +75,16 @@ function toSessionEntry(entry) {
     }
     return { ...base, kind: entry.type, data: {} };
 }
+/**
+ * THE invariant the client's rule rests on: everything `entries()` publishes is a legal `navigate`
+ * target. pi's `leaf` records are the exception — they journal a MOVE rather than mark a position
+ * (their parentId is the OLD leaf, nothing is ever chained onto them), so navigating to one would
+ * put the branch head off every conversation path. Withheld from the published plane and refused as
+ * a target THROUGH THIS ONE PREDICATE, so a second exclusion cannot make the two disagree.
+ */
+function isNavigable(entry) {
+    return entry.type !== "leaf";
+}
 // ── Live fan-out (events plane) ──────────────────────────────────────────────
 /** Ceiling for one subscriber's unconsumed backlog. A consumer this far behind (a stalled remote
  *  connection — the wire's ReadableStream backpressure stops pulling while invokes keep pushing)
@@ -195,7 +207,12 @@ export function createPiSessionControl(options) {
                 followUp: true,
                 manualCompaction: !!b,
                 modelSelection: b ? { allowedModels: listModels(b.models) } : false,
-                thinkingLevel: b ? { allowedLevels: [...THINKING_LEVELS] } : false,
+                // Servable or not. WHICH levels is a property of the session's model, so it rides
+                // `state().availableThinkingLevels` — a list here could only answer for one model.
+                thinkingLevel: !!b,
+                // Gated on the boundary wiring for its LEASE, not its models: moving the leaf is a write,
+                // and a write that races a run would hang the next turn off a stale branch.
+                navigate: !!b,
                 toolProgress: true, // tool_progress IS delivered (replace-semantics snapshots)
                 usage: false,
             };
@@ -204,24 +221,33 @@ export function createPiSessionControl(options) {
             const run = active.get(session);
             const opened = await sessions.openIfExists(session);
             const leafEntryId = opened ? ((await opened.getLeafId()) ?? undefined) : undefined;
-            // The durable overrides (set_model / set_thinking), via the SAME walk the harness resolve
-            // uses (lastOverrideEntries) — one physical implementation, so the reporting surface and the
-            // execution surface can never disagree on which record is "the" override. Reported as
-            // recorded, even if the current registry lacks the model (state reports session truth; the
-            // harness resolve owns the execution fallback).
-            let model;
-            let thinkingLevel;
-            if (opened) {
-                const recorded = lastOverrideEntries((await opened.getEntries()));
-                if (recorded.model)
-                    model = `${recorded.model.provider}/${recorded.model.modelId}`;
-                thinkingLevel = recorded.thinkingLevel;
+            // What will RUN, not the raw record: a client steering a session needs the pair that executes.
+            // Without a boundary there is no model to resolve against, and the fields are absent.
+            // OBSERVATION IS TOTAL: an unreadable entry chain leaves the pair absent too (the same shape a
+            // control-less deployment answers with) rather than rejecting a read that has no error-code
+            // channel to explain itself. The fault is not swallowed — it surfaces where codes exist: the
+            // next invoke fails (the harness build walks the same chain) and a boundary dispatch answers
+            // `boundary_command_failed`. Here it is a server-side warn.
+            const b = boundary?.();
+            let settings;
+            if (opened && b) {
+                try {
+                    settings = resolveSessionSettings((await activePathEntries(opened)), b.models, b.defaults);
+                }
+                catch (error) {
+                    log.warn(`[fastagent] session ${session}: settings unreadable (entry chain): ${String(error)}`);
+                }
             }
             return {
                 status: run ? "running" : compacting.has(session) ? "compacting" : "idle",
                 ...(run ? { activeRunId: run.runId } : {}),
-                ...(model !== undefined ? { model } : {}),
-                ...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
+                ...(settings
+                    ? {
+                        model: `${settings.model.provider}/${settings.model.id}`,
+                        thinkingLevel: settings.thinkingLevel,
+                        availableThinkingLevels: settings.availableThinkingLevels,
+                    }
+                    : {}),
                 pending: run ? { ...run.pending } : { steering: 0, followUp: 0 },
                 ...(leafEntryId ? { leafEntryId } : {}),
             };
@@ -230,8 +256,12 @@ export function createPiSessionControl(options) {
             const opened = await sessions.openIfExists(session);
             if (!opened)
                 return { entries: [] };
-            const all = (await opened.getEntries()).map(toSessionEntry);
+            // LEAF FIRST, then the journal: `getEntries()` hands back a SNAPSHOT, so reading it first
+            // would race any concurrent append into a leaf the snapshot cannot contain — a live turn
+            // reading as a dangling head. This order makes the journal a superset of the leaf's chain,
+            // which is what lets the published head be trusted as one of the published entries.
             const leafEntryId = (await opened.getLeafId()) ?? undefined;
+            const all = (await opened.getEntries()).filter(isNavigable).map(toSessionEntry);
             let entries = all;
             if (opts?.since !== undefined) {
                 const idx = all.findIndex((e) => e.id === opts.since);
@@ -361,7 +391,8 @@ export function createPiSessionControl(options) {
                 }
                 case "compact":
                 case "set_model":
-                case "set_thinking": {
+                case "set_thinking":
+                case "navigate": {
                     const b = boundary?.();
                     if (!b) {
                         // No boundary wiring: rejected before acceptance; a capability-gating client never
@@ -376,7 +407,8 @@ export function createPiSessionControl(options) {
                         };
                     }
                     // Payload validation BEFORE the lease — an invalid value must not briefly block a run.
-                    /** The entry-append for set_model/set_thinking — undefined for compact (harness path). */
+                    /** The durable write for set_model/set_thinking/navigate — undefined for compact (harness
+                     *  path). Answers the event to emit. */
                     let apply;
                     if (command.type === "set_model") {
                         const slash = command.model.indexOf("/");
@@ -393,18 +425,26 @@ export function createPiSessionControl(options) {
                         }
                         apply = async (s) => {
                             await s.appendModelChange(model.provider, model.id);
-                            // The CANONICAL spec, same string the durable entry and state() report — the event
-                            // must not echo a client alias the other two surfaces would disagree with.
-                            return { type: "state_changed", timestamp: Date.now(), data: { model: `${model.provider}/${model.id}` } };
+                            // Both halves: a new model can change which level executes. Nothing is re-recorded to
+                            // make that true — the resolve reports it, so the preference survives a round trip.
+                            const settings = resolveSessionSettings((await activePathEntries(s)), b.models, b.defaults);
+                            return {
+                                type: "state_changed",
+                                timestamp: Date.now(),
+                                // The CANONICAL spec, same string the durable entry and state() report — the event
+                                // must not echo a client alias the other two surfaces would disagree with.
+                                data: { model: `${model.provider}/${model.id}`, thinkingLevel: settings.thinkingLevel },
+                            };
                         };
                     }
                     else if (command.type === "set_thinking") {
+                        // A payload that is not a level at all — invalid before any session question.
                         if (!THINKING_LEVELS.has(command.level)) {
                             return {
                                 ok: false,
                                 error: {
                                     code: INVALID_COMMAND_CODE,
-                                    message: `unknown thinking level "${command.level}" — capabilities().thinkingLevel lists the allowed values`,
+                                    message: `unknown thinking level "${command.level}" — state().availableThinkingLevels lists what this session accepts`,
                                     retryable: false,
                                 },
                             };
@@ -414,10 +454,54 @@ export function createPiSessionControl(options) {
                             return { type: "state_changed", timestamp: Date.now(), data: { thinkingLevel: command.level } };
                         };
                     }
+                    else if (command.type === "navigate") {
+                        apply = async (s) => {
+                            // A move to where the leaf already is writes nothing: pi journals a move as a `leaf`
+                            // record, so an idempotent re-dispatch (a client retry, a UI firing on every
+                            // selection) would otherwise grow the session by a record no plane publishes. The
+                            // EVENT is emitted either way — it reports the resulting position, not the fact that
+                            // a record was written, and a client that dispatched must not have to poll for it.
+                            if ((await s.getLeafId()) !== command.targetId)
+                                await s.moveTo(command.targetId);
+                            // moveTo's postcondition IS "targetId is the leaf" (it validates, then sets); a
+                            // failure throws and travels as boundary_command_failed, so a read-back could only
+                            // re-report what this line already knows. The SETTINGS ride along because a move can
+                            // change them — an override recorded on the branch just left stops applying, and a
+                            // client tracking model/level from the event stream would otherwise show what the
+                            // next turn will not use.
+                            // The move is already durable here, so a settings read that throws (the new path is
+                            // above a gap) must NOT turn into "nothing took effect": report the position without
+                            // the settings and let `state()`'s rejection be where the broken chain surfaces.
+                            let settings;
+                            try {
+                                settings = resolveSessionSettings((await activePathEntries(s)), b.models, b.defaults);
+                            }
+                            catch (error) {
+                                // Absent rather than stale: the session cannot RUN with an unreadable chain either
+                                // (the harness build walks the same path), so the next invoke fails visibly — this
+                                // event does not need to carry a second signal for it.
+                                log.warn(`[fastagent] session ${session}: leaf moved, settings unreadable: ${String(error)}`);
+                            }
+                            return {
+                                type: "state_changed",
+                                timestamp: Date.now(),
+                                data: {
+                                    leafEntryId: command.targetId,
+                                    ...(settings
+                                        ? {
+                                            model: `${settings.model.provider}/${settings.model.id}`,
+                                            thinkingLevel: settings.thinkingLevel,
+                                        }
+                                        : {}),
+                                },
+                            };
+                        };
+                    }
                     // Sessions are created by invoke, never here: a mutation on an unknown id is rejected,
                     // not minted into a ghost record. (Existence check before the lease — read-only; the
                     // WRITE handle is re-opened under the lease below, this one is discarded.)
-                    if (!(await sessions.openIfExists(session))) {
+                    const existing = await sessions.openIfExists(session);
+                    if (!existing) {
                         return {
                             ok: false,
                             error: {
@@ -427,6 +511,51 @@ export function createPiSessionControl(options) {
                             },
                         };
                     }
+                    if (command.type === "navigate") {
+                        // A target that cannot BE a leaf is a permanent payload error, not a session error — the
+                        // same disposition as an unknown model spec. Same predicate `entries()` publishes by, so
+                        // "everything published is navigable" holds by construction rather than by two literals
+                        // agreeing.
+                        const entry = await existing.getEntry(command.targetId);
+                        if (!entry || !isNavigable(entry)) {
+                            return {
+                                ok: false,
+                                error: {
+                                    code: INVALID_COMMAND_CODE,
+                                    message: entry
+                                        ? `entry "${command.targetId}" is a leaf-move record — entries() does not publish those, and they are not positions; navigate to the entry it points at`
+                                        : `entry "${command.targetId}" does not exist in session "${session}" — entries() lists the navigable ids`,
+                                    retryable: false,
+                                },
+                            };
+                        }
+                    }
+                    if (command.type === "set_thinking") {
+                        // The same set `state()` showed the client. Reject here rather than record a level the
+                        // run would not use. The read is guarded because `dispatch` must never REJECT — the
+                        // transport promises a SessionResult, so an unreadable chain has to arrive as a code.
+                        let resolved;
+                        try {
+                            resolved = resolveSessionSettings((await activePathEntries(existing)), b.models, b.defaults);
+                        }
+                        catch (error) {
+                            return {
+                                ok: false,
+                                error: { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(error), retryable: true },
+                            };
+                        }
+                        const { model, availableThinkingLevels } = resolved;
+                        if (!availableThinkingLevels.includes(command.level)) {
+                            return {
+                                ok: false,
+                                error: {
+                                    code: INVALID_COMMAND_CODE,
+                                    message: `thinking level "${command.level}" is not supported by ${model.provider}/${model.id} (allowed: ${availableThinkingLevels.join(", ")})`,
+                                    retryable: false,
+                                },
+                            };
+                        }
+                    }
                     // Boundary mutations are the control plane's only writers: same lease as every run — a
                     // mutation must never race one (design §9).
                     const release = b.lease.tryAcquire(session);
@@ -567,8 +696,8 @@ export function createPiSessionControl(options) {
                                 },
                             };
                         }
-                        // Unreachable by construction: only set_model/set_thinking reach this branch, and
-                        // both assign `apply` in validation. Throw rather than silently skip (fail visibly).
+                        // Unreachable by construction: only set_model/set_thinking/navigate reach this branch,
+                        // and all three assign `apply` in validation. Throw rather than silently skip (fail visibly).
                         if (!apply)
                             throw new Error("apply unset outside the compact branch (dispatch invariant broken)");
                         emitOwn(session, await apply(fresh));

package/dist/engines/pi/session-settings.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a session is SET TO, and what it may be set to. Model and thinking level are ONE setting —
+ * which levels exist is a property of the model — so they resolve together, here, and `state()`, the
+ * `set_thinking` gate and the fresh-harness resolve all read this rather than deriving their own.
+ *
+ * Read-only by design. The durable record may hold a level the current model cannot do; that record
+ * is the user's PREFERENCE, so resolving per read restores it when the session returns to a capable
+ * model. (It could not be made unrepresentable anyway: `model_change`/`thinking_level_change` are
+ * pi's entries, and pi appends them itself.)
+ */
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type Models } from "@earendil-works/pi-ai";
+import type { AnyModel } from "./harness.ts";
+export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
+/** The shape both override consumers walk — a session entry, structurally. */
+export interface OverrideEntryLike {
+    type: string;
+    provider?: string;
+    modelId?: string;
+    thinkingLevel?: string;
+}
+/** The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through
+ *  to an earlier record — which record is "the" override must not depend on who is asking. */
+export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    thinkingLevel?: string;
+};
+export interface SessionSettings {
+    model: AnyModel;
+    /** Already clamped to what {@link model} supports. */
+    thinkingLevel: ThinkingLevel;
+    /** What `set_thinking` accepts for this session. */
+    availableThinkingLevels: string[];
+    /** Recorded but not honored — only the execution path reports it (as a warn). */
+    dropped?: {
+        model?: string;
+        thinkingLevel?: {
+            recorded: string;
+            running: string;
+            known: boolean;
+        };
+    };
+}
+/** `defaults` is the assembly's configured pair — what a session with no overrides runs on. */
+export declare function resolveSessionSettings(entries: OverrideEntryLike[], models: Models, defaults: {
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel;
+}): SessionSettings;