@fastagent-sh/fastagent 0.16.1 → 0.17.0

package/dist/engines/pi/report.js

@@ -1,4 +1,34 @@
 import { log } from "../../log.js";
+/** Stable identity of a definition's non-fatal findings — the dedup key below. */
+function findingsSignature(def) {
+    const collisions = def.collisions.map((c) => `c:${c.name}:${c.winnerPath}:${c.loserPath}`);
+    const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
+    return [...collisions, ...diagnostics].sort().join("\n");
+}
+/**
+ * The last reported finding set PER DEFINITION DIR. One memo for every reader of a definition (the
+ * per-turn live read, the control plane's command list), because the thing being deduped is the
+ * FINDING, not the reader: a newly broken skill deserves one warning, not one per code path that
+ * noticed it, and a static one deserves none at all.
+ */
+const lastFindings = new Map();
+/**
+ * THE door for definition findings: warns only when this dir's set CHANGED since the last report.
+ * Every reader calls it — boot, the per-turn live read, the control plane's command list — so a
+ * finding is announced when it appears and never repeated. There is deliberately no "record without
+ * printing" variant: a memo entry that trusts some other caller to have printed would silently
+ * swallow findings for a caller that does not.
+ *
+ * `dir` must be the RESOLVED definition root (`LoadedDefinition.dir`), or two spellings of one path
+ * become two memos and warn twice.
+ */
+export function reportFindingsIfChanged(dir, def) {
+    const sig = findingsSignature(def);
+    if (lastFindings.get(dir) === sig)
+        return;
+    lastFindings.set(dir, sig);
+    reportDefinitionWarnings(def.collisions, def.diagnostics);
+}
 export function reportDefinitionWarnings(collisions, diagnostics) {
     for (const c of collisions) {
         log.warn(`[fastagent] skill "${c.name}" collision — using ${c.winnerPath}, ignoring ${c.loserPath}`);

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

@@ -37,7 +37,7 @@ import { canonicalPath, loadAgentDefinition } from "./definition.js";
 import { createPiModelRuntime, probeAuthSource } from "./models.js";
 import { log } from "../../log.js";
 import { additiveActivation, turnContext } from "./tool-context.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
 import { resolveAgentAssembly } from "./open.js";
 /** Adapt coding-agent's resident SessionManager to FastAgent's shared tool-runtime manager port. */
 function toolChatSessionManager(session) {
@@ -119,7 +119,7 @@ sessionManager) {
         const model = resolveModel(modelRuntime, modelSpec);
         const env = new NodeExecutionEnv({ cwd });
         const definition = await loadAgentDefinition(agentDir, { cwd, env });
-        reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+        reportFindingsIfChanged(definition.dir, definition);
         const defaultNames = piDefaultTools().map((t) => t.name);
         const customTools = tools.filter((t) => !defaultNames.includes(t.name));
         // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts

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 AgentCommand, 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). */
@@ -30,6 +39,16 @@ export interface CreatePiSessionControlOptions {
      *  (assembly completes before any dispatch can arrive). Absent / undefined → boundary commands
      *  are gated off in `capabilities()` and rejected `unsupported_capability`. */
     boundary?: () => PiBoundaryWiring | undefined;
+    /** The definition's names, as a LAZY thunk for the same reason {@link boundary} is one (the hub
+     *  exists before the assembly that can read a definition) — and async because the definition is
+     *  live: this must re-read it, not close over a boot snapshot, or `commands()` would advertise a
+     *  list the next turn no longer runs.
+     *
+     *  OPTIONAL because absence is a TRUE answer for the assembly that omits it: a hub over an L1
+     *  agent (`createPiAgent({ model, instructions, tools })`) has no definition and therefore no
+     *  names, and `[]` says exactly that. Wire it whenever the agent came from a DIRECTORY — there
+     *  `[]` would be a lie; the directory constructor (`createPiAgentFromDir`) always does. */
+    commands?: () => Promise<AgentCommand[]>;
     /** Tap for the events the HUB ITSELF generates (boundary mutations: `state_changed`,
      *  `compaction_*`) — those never pass through the data plane's observer seam, so a consumer
      *  composing a full-vocabulary tap wires the run events via the observer AND this. Called after

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)
@@ -188,6 +200,9 @@ export function createPiSessionControl(options) {
         fanOut(session, event);
     };
     const control = {
+        async commands() {
+            return (await options.commands?.()) ?? [];
+        },
         capabilities: () => {
             const b = boundary?.();
             return {
@@ -195,7 +210,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 +224,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 +259,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 +394,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 +410,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 +428,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 +457,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 +514,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 +699,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;

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

@@ -0,0 +1,73 @@
+import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+/** Which strings are levels at all — the vocabulary. What a MODEL supports is
+ *  `getSupportedThinkingLevels`. The `satisfies` anchor keeps this exhaustive against pi's union: a
+ *  level pi adds becomes a type error here rather than a value `set_thinking` silently rejects. */
+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 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 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 };
+}
+/** `defaults` is the assembly's configured pair — what a session with no overrides runs on. */
+export function resolveSessionSettings(entries, models, defaults) {
+    const recorded = lastOverrideEntries(entries);
+    const dropped = {};
+    // A registry change across deploys must not brick the conversation.
+    let model = defaults.model;
+    if (recorded.model) {
+        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
+        if (found)
+            model = found;
+        else
+            dropped.model = `${recorded.model.provider}/${recorded.model.modelId}`;
+    }
+    const availableThinkingLevels = getSupportedThinkingLevels(model);
+    let thinkingLevel = defaults.thinkingLevel;
+    if (recorded.thinkingLevel !== undefined) {
+        const level = recorded.thinkingLevel;
+        if (!THINKING_LEVELS.has(level)) {
+            dropped.thinkingLevel = { recorded: level, running: thinkingLevel, known: false };
+        }
+        else {
+            // pi's clamp takes the lowest supported level AT OR ABOVE the recorded one, falling back
+            // downward only when nothing is above: a gap resolves UPWARD and costs more, not less. Which is
+            // why `dropped` names both levels rather than reporting a substitution.
+            thinkingLevel = clampThinkingLevel(model, level);
+            if (thinkingLevel !== level) {
+                dropped.thinkingLevel = { recorded: level, running: thinkingLevel, known: true };
+            }
+        }
+    }
+    return {
+        model,
+        thinkingLevel,
+        availableThinkingLevels,
+        ...(dropped.model || dropped.thinkingLevel ? { dropped } : {}),
+    };
+}

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

@@ -1,4 +1,4 @@
-import type { Session } from "@earendil-works/pi-agent-core";
+import type { Session, SessionTreeEntry } from "@earendil-works/pi-agent-core";
 /** What fastagent needs from a session backend: open-or-create by opaque id. */
 export interface PiSessionStore {
     openOrCreate(sessionId: string): Promise<Session>;
@@ -7,17 +7,31 @@ export interface PiSessionStore {
  * OPEN-EXISTING sibling of {@link PiSessionStore} (session-control.ts): an unknown session answers
  * `undefined`, never creates one — sessions are the data plane's monopoly. Two consumers:
  * - the OBSERVATION plane (`state()`/`entries()`), strictly read-only (design §16 invariant 4);
- * - the control plane's BOUNDARY writers (`set_model`/`set_thinking`), which append override
- *   records to the returned handle after an existence check, under the run lease.
+ * - the control plane's BOUNDARY writers (`set_model`/`set_thinking` append override records to the
+ *   returned handle; `navigate` moves its leaf) after an existence check, under the run lease.
  * `openIfExists` skips the open-time crash reconciliation (that appends repair entries — a write
- * the observation plane must not perform). The boundary writers are safe WITHOUT it only because
- * override records are not messages — they cannot create or interact with a dangling tool_use
- * pair. Writing MESSAGE-class records through this handle would bypass that repair: use
- * `openOrCreate` for anything that enters the transcript.
+ * the observation plane must not perform). The boundary writers are safe WITHOUT it for two
+ * different reasons: an override record is not a message, so it cannot create or pair with a
+ * dangling tool_use; a `navigate` writes no message either, but it CAN expose one — parking the
+ * leaf on an assistant entry whose tool results are now off-path is the dangling-pair state
+ * {@link reconcileInterruptedToolCalls} exists for. That is repaired at the next `openOrCreate`,
+ * which repairs AT THE LEAF — exactly where a move puts it.
+ *
+ * Writing MESSAGE-class records through this handle would bypass that repair: use `openOrCreate`
+ * for anything that enters the transcript.
  */
 export interface PiSessionReader {
     openIfExists(sessionId: string): Promise<Session | undefined>;
 }
+/**
+ * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
+ * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
+ * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
+ * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
+ * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
+ * recorded before a compaction is a preference, and it still governs the session after one.
+ */
+export declare function activePathEntries(session: Session): Promise<SessionTreeEntry[]>;
 /** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
 export declare function inMemorySessionStore(): PiSessionStore & PiSessionReader;
 /**

package/dist/engines/pi/sessions.js

@@ -88,6 +88,49 @@ async function reconcileInterruptedToolCalls(session) {
         await session.appendMessage(result);
     }
 }
+/**
+ * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
+ * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
+ * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
+ * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
+ * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
+ * recorded before a compaction is a preference, and it still governs the session after one.
+ */
+export async function activePathEntries(session) {
+    // LEAF FIRST, then the journal — the order is load-bearing, not incidental: `getEntries()` is a
+    // SNAPSHOT, so reading it first would let any concurrent append (i.e. any turn in progress) leave
+    // a leaf the snapshot cannot contain, and the integrity throw below would fire on a live session
+    // instead of a corrupt one. This way the snapshot is always a superset of the leaf's chain.
+    const leafId = await session.getLeafId();
+    const entries = await session.getEntries();
+    // A null leaf is pi's ROOT position (what `moveTo(null)` sets), so the active path is EMPTY — not
+    // "the whole journal", which on a branched session would mean every abandoned branch at once.
+    if (leafId === null)
+        return [];
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    // A chain that is not intact THROWS: any other disposition returns a short path that reads like a
+    // short session (every override and activation above the gap gone, the next turn silently on
+    // assembly defaults). pi's storages already reject a leaf outside the journal in `getLeafId()`,
+    // but the port is swappable — so the walk names it here rather than dying on `undefined.parentId`.
+    const start = byId.get(leafId);
+    if (!start)
+        throw new Error(`session leaf "${leafId}" is missing from the journal`);
+    const path = [];
+    for (let cur = start;;) {
+        path.push(cur);
+        // A path cannot be longer than the journal it walks; anything more is a parentId cycle, which
+        // would otherwise hang the turn with no `failed` event at all.
+        if (path.length > entries.length)
+            throw new Error(`session entry "${cur.id}" cycles through its parents`);
+        if (!cur.parentId)
+            break;
+        const parent = byId.get(cur.parentId);
+        if (!parent)
+            throw new Error(`session entry "${cur.parentId}" is missing from the journal (parent of "${cur.id}")`);
+        cur = parent;
+    }
+    return path.reverse(); // walked leaf→root; every consumer reads it root→leaf
+}
 /** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
 export function inMemorySessionStore() {
     const repo = new InMemorySessionRepo();