@selesai/code 0.13.24 → 0.13.26

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.26] - 2026-09-18
+
+### Added
+- **Goal-preserving automatic handoff.** The automatic handoff now runs with the same goal text as an explicit `/handoff-new`, so the continuation prompt keeps the overarching objective, success criteria, key decisions, reference files, and the next concrete action. `AUTO_HANDOFF_GOAL` is exported from the core handoff module.
+
+### Changed
+- **Failed handoffs retry instead of silently stopping.** A failed or empty handoff generation now surfaces the underlying error (previously reported as "Cancelled") and rejects the command, and the automatic handoff retries on the next settled turn while the session stays above the threshold.
+- **RPC handoff keeps the session name.** `handoff_new` carries the current session name into the replacement session, matching `/handoff-new`.
+- **Default model catalog refreshed.** Added `glm-5.3` (1M context, text+image), `kimi-k3` (512K), and `gemini-3.7-flash`; `celestial-pro` now accepts images; `deepseek-v4.1-flash` uses 64K max output tokens.
+- **Retired default models.** `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`, `kimi-k2.7-code`, and `glm-5.2` are no longer in the bundled Token-In catalog (`glm-5.3` supersedes `glm-5.2`). User-level `models.json` entries are unaffected.
+
+## [0.13.25] - 2026-09-14
+
+### Added
+- **Graft deep-build model override.** Set `graft.deepModel` to pin a model on the active provider for Graft deep builds.
+
+### Changed
+- **Graft deep-build fallback.** When the active model returns no usable Graft summaries, the deep build retries up to two other models scoped to that provider before reporting the deep-build failure.
+
 ## [0.13.24] - 2026-09-13
 
 ### Added

package/dist/core/agent-session-auto-handoff.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { Type } from "typebox";
 import { AgentSession } from "./agent-session.js";
+import { AUTO_HANDOFF_GOAL } from "./handoff.js";
 import { SettingsManager } from "./settings-manager.js";
 function createMockSession({ enabled, threshold = 128_000, tokens, mode = "tui", command, customTools, allowedToolNames, }) {
     const settings = SettingsManager.inMemory({
@@ -78,6 +79,11 @@ describe("AgentSession tools", () => {
     });
 });
 describe("AgentSession auto handoff", () => {
+    it("uses a goal that preserves the overall objective and continuation details", () => {
+        expect(AUTO_HANDOFF_GOAL).toMatch(/overall objective/i);
+        expect(AUTO_HANDOFF_GOAL).toMatch(/next concrete action/i);
+        expect(AUTO_HANDOFF_GOAL).toMatch(/reference files/i);
+    });
     it("invokes handoff-new once when enabled and threshold reached in tui mode", async () => {
         const command = { handler: vi.fn() };
         const { session, getCommand, createCommandContext, emitError } = createMockSession({
@@ -90,7 +96,7 @@ describe("AgentSession auto handoff", () => {
         expect(getCommand).toHaveBeenCalledWith("handoff-new");
         expect(createCommandContext).toHaveBeenCalled();
         expect(command.handler).toHaveBeenCalledTimes(1);
-        expect(command.handler).toHaveBeenCalledWith("", expect.anything());
+        expect(command.handler).toHaveBeenCalledWith(AUTO_HANDOFF_GOAL, expect.anything());
         expect(emitError).not.toHaveBeenCalled();
     });
     it("dispatches auto handoff via _emitAgentSettled in tui mode", async () => {
@@ -156,13 +162,16 @@ describe("AgentSession auto handoff", () => {
         await session._checkAutoHandoff();
         expect(getCommand).toHaveBeenCalledWith("handoff-new");
     });
-    it("emits error when handoff-new throws but does not rethrow", async () => {
+    it("emits an error and retries on the next check when handoff-new fails", async () => {
         const command = {
             handler: vi.fn(() => Promise.reject(new Error("boom"))),
         };
         const { session, emitError } = createMockSession({ enabled: true, tokens: 200_000, command });
         await expect(session._checkAutoHandoff()).resolves.toBeUndefined();
-        expect(emitError).toHaveBeenCalledWith({
+        await expect(session._checkAutoHandoff()).resolves.toBeUndefined();
+        expect(command.handler).toHaveBeenCalledTimes(2);
+        expect(emitError).toHaveBeenCalledTimes(2);
+        expect(emitError).toHaveBeenLastCalledWith({
             extensionPath: "command:handoff-new",
             event: "auto-handoff",
             error: "boom",

package/dist/core/agent-session.js

@@ -27,6 +27,7 @@ import { calculateContextTokens, collectEntriesForBranchSummary, compact, estima
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
+import { AUTO_HANDOFF_GOAL } from "./handoff.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { ModelRegistry } from "./model-registry.js";
@@ -375,7 +376,6 @@ export class AgentSession {
         }
         if (this._autoHandoffTriggered)
             return;
-        this._autoHandoffTriggered = true;
         // Auto-handoff is TUI-only: it runs at agent_settled, and headless/print
         // modes should not churn sessions on their own. The handoff-new command
         // itself now also works in non-TUI modes (direct generation, no loader).
@@ -384,11 +384,14 @@ export class AgentSession {
         const command = this._extensionRunner.getCommand("handoff-new");
         if (!command)
             return;
+        this._autoHandoffTriggered = true;
         const ctx = this._extensionRunner.createCommandContext();
         try {
-            await command.handler("", ctx);
+            await command.handler(AUTO_HANDOFF_GOAL, ctx);
         }
         catch (err) {
+            // Retry on the next settled turn while the session remains above the threshold.
+            this._autoHandoffTriggered = false;
             this._extensionRunner.emitError({
                 extensionPath: "command:handoff-new",
                 event: "auto-handoff",

package/dist/core/handoff.d.ts

@@ -3,6 +3,7 @@ import type { AssistantMessage, Context } from "@earendil-works/pi-ai";
 import type { Model } from "@earendil-works/pi-ai";
 import type { SessionEntry } from "./session-manager.ts";
 export declare const DEFAULT_HANDOFF_GOAL = "Continue the previous session from this handoff.";
+export declare const AUTO_HANDOFF_GOAL = "Continue the previous session without losing its direction. Preserve the big picture: the overall objective, why the work matters, the intended outcome and success criteria, the current approach and key decisions, relevant constraints, exact reference files or artifacts, completed and remaining work, known failures or test results, and the next concrete action. Make clear how the immediate next step contributes to the overall goal.";
 export declare function entryToMessage(entry: SessionEntry): AgentMessage | undefined;
 export declare function getHandoffMessages(branch: SessionEntry[]): AgentMessage[];
 export declare function buildAiContext(conversationText: string, goal: string): Context;

package/dist/core/handoff.js

@@ -1,6 +1,7 @@
 import { serializeConversation } from "./compaction/utils.js";
 import { convertToLlm } from "./messages.js";
 export const DEFAULT_HANDOFF_GOAL = "Continue the previous session from this handoff.";
+export const AUTO_HANDOFF_GOAL = `Continue the previous session without losing its direction. Preserve the big picture: the overall objective, why the work matters, the intended outcome and success criteria, the current approach and key decisions, relevant constraints, exact reference files or artifacts, completed and remaining work, known failures or test results, and the next concrete action. Make clear how the immediate next step contributes to the overall goal.`;
 const SYSTEM_PROMPT = `Write a handoff document for a fresh agent to continue the current conversation. Return only the handoff document text; do not save a file or describe saving one. No question, no fluff, just write the handoff. Do not reproduce, quote, or reformat the conversation history or its tool calls — distill it into what matters; never emit transcript-style markup or raw tool-call text.
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.

package/dist/defaults/models.json

@@ -14,7 +14,7 @@
           "id": "celestial-pro",
           "name": "Celestial Pro",
           "reasoning": true,
-          "input": ["text"],
+          "input": ["text", "image"],
           "contextWindow": 393216,
           "maxTokens": 64000,
           "thinkingLevelMap": {
@@ -67,51 +67,13 @@
             "requiresReasoningContentOnAssistantMessages": true
             }
         },
-        {
-          "id": "deepseek-v4-flash",
-          "name": "DeepSeek V4 Flash",
-          "reasoning": true,
-          "input": ["text"],
-          "contextWindow": 512000,
-          "maxTokens": 64000,
-          "thinkingLevelMap": {
-            "minimal": null,
-            "low": null,
-            "medium": null,
-            "high": "high",
-            "xhigh": null,
-            "max": "max"
-          },
-          "compat": {
-            "requiresReasoningContentOnAssistantMessages": true
-            }
-        },
-        {
-          "id": "deepseek-v4-flash-vision-exp",
-          "name": "DeepSeek V4 Flash Vision Exp",
-          "reasoning": true,
-          "input": ["text", "image"],
-          "contextWindow": 512000,
-          "maxTokens": 128000,
-          "thinkingLevelMap": {
-            "minimal": null,
-            "low": null,
-            "medium": null,
-            "high": "high",
-            "xhigh": null,
-            "max": "max"
-          },
-          "compat": {
-            "requiresReasoningContentOnAssistantMessages": true
-            }
-        },
         {
           "id": "deepseek-v4.1-flash",
           "name": "DeepSeek V4.1 Flash",
           "reasoning": true,
           "input": ["text", "image"],
           "contextWindow": 512000,
-          "maxTokens": 128000,
+          "maxTokens": 64000,
           "thinkingLevelMap": {
             "minimal": null,
             "low": null,
@@ -207,38 +169,6 @@
             "max": "max"
           }
         },
-        {
-          "id": "kimi-k2.7-code",
-          "name": "Kimi K2.7 Code",
-          "reasoning": true,
-          "input": ["text", "image"],
-          "contextWindow": 262128,
-          "maxTokens": 64000,
-          "thinkingLevelMap": {
-            "minimal": null,
-            "low": "low",
-            "medium": null,
-            "high": "high",
-            "xhigh": null,
-            "max": "max"
-          }
-        },
-        {
-          "id": "glm-5.2",
-          "name": "GLM-5.2",
-          "reasoning": true,
-          "input": ["text"],
-          "contextWindow": 1000000,
-          "maxTokens": 64000,
-          "thinkingLevelMap": {
-            "minimal": null,
-            "low": "low",
-            "medium": null,
-            "high": "high",
-            "xhigh": null,
-            "max": null
-          }
-        },
         {
           "id": "glm-5.3-flash",
           "name": "GLM-5.3 Flash",

package/dist/extensions/handoff-new.test.ts

@@ -226,11 +226,11 @@ describe("handoff-new extension", () => {
 		expect(calls.newSession).not.toBeNull();
 	});
 
-	it("non-tui mode generation error notifies and opens no session", async () => {
+	it("non-tui mode generation error notifies, rejects, and opens no session", async () => {
 		(complete as any).mockRejectedValueOnce(new Error("api down"));
 		const { commands } = createPiHarness();
 		const { ctx, calls } = createCtx({ mode: "rpc" });
-		await commands.get("handoff-new")!.handler("goal", ctx);
+		await expect(commands.get("handoff-new")!.handler("goal", ctx)).rejects.toThrow("api down");
 		expect(calls.newSession).toBeNull();
 		expect(calls.notify.some((n) => /api down/.test(n.msg))).toBe(true);
 	});
@@ -259,10 +259,10 @@ describe("handoff-new extension", () => {
 		expect(calls.notify.some((n) => /Cancelled/.test(n.msg))).toBe(true);
 	});
 
-	it("empty generated handoff does not open a blank session", async () => {
+	it("empty generated handoff notifies, rejects, and opens no blank session", async () => {
 		const { commands } = createPiHarness();
 		const { ctx, calls } = createCtx({ customResult: "  " });
-		await commands.get("handoff-new")!.handler("goal", ctx);
+		await expect(commands.get("handoff-new")!.handler("goal", ctx)).rejects.toThrow("returned no text");
 		expect(calls.newSession).toBeNull();
 		expect(calls.notify.some((n) => /returned no text/.test(n.msg))).toBe(true);
 	});
@@ -358,29 +358,29 @@ describe("handoff-new extension", () => {
 		expect(calls.notify.some((n) => /Cancelled/.test(n.msg))).toBe(true);
 	});
 
-	it("factory: missing API key throws and notifies Cancelled", async () => {
+	it("factory: missing API key notifies and rejects", async () => {
 		const { commands } = createPiHarness();
 		const { ctx, calls } = createFactoryCtx({ auth: { ok: true, error: "no key" } });
-		await commands.get("handoff-new")!.handler("goal", ctx);
+		await expect(commands.get("handoff-new")!.handler("goal", ctx)).rejects.toThrow("No API key");
 		expect(calls.newSession).toBeNull();
-		expect(calls.notify.some((n) => /Cancelled/.test(n.msg))).toBe(true);
+		expect(calls.notify.some((n) => /No API key/.test(n.msg))).toBe(true);
 	});
 
-	it("factory: auth error throws and notifies Cancelled", async () => {
+	it("factory: auth error notifies and rejects", async () => {
 		const { commands } = createPiHarness();
 		const { ctx, calls } = createFactoryCtx({ auth: { ok: false, error: "auth failed" } });
-		await commands.get("handoff-new")!.handler("goal", ctx);
+		await expect(commands.get("handoff-new")!.handler("goal", ctx)).rejects.toThrow("auth failed");
 		expect(calls.newSession).toBeNull();
-		expect(calls.notify.some((n) => /Cancelled/.test(n.msg))).toBe(true);
+		expect(calls.notify.some((n) => /auth failed/.test(n.msg))).toBe(true);
 	});
 
-	it("factory: complete rejection is caught and notifies Cancelled", async () => {
+	it("factory: complete rejection notifies and rejects", async () => {
 		(complete as any).mockRejectedValueOnce(new Error("network down"));
 		const { commands } = createPiHarness();
 		const { ctx, calls } = createFactoryCtx({});
-		await commands.get("handoff-new")!.handler("goal", ctx);
+		await expect(commands.get("handoff-new")!.handler("goal", ctx)).rejects.toThrow("network down");
 		expect(calls.newSession).toBeNull();
-		expect(calls.notify.some((n) => /Cancelled/.test(n.msg))).toBe(true);
+		expect(calls.notify.some((n) => /network down/.test(n.msg))).toBe(true);
 	});
 
 	it("factory: loader onAbort resolves null", async () => {

package/dist/extensions/handoff-new.ts

@@ -74,15 +74,20 @@ async function handoffNew(args: string, ctx: ExtensionCommandContext) {
 	const aiContext = buildAiContext(conversationText, goal);
 
 	let result: string | null;
+	let generationError: unknown;
 	if (ctx.mode === "tui") {
+		let cancelled = false;
 		result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
 			const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
-			loader.onAbort = () => done(null);
+			loader.onAbort = () => {
+				cancelled = true;
+				done(null);
+			};
 
 			generateHandoffText(ctx, aiContext, loader.signal)
 				.then(done)
 				.catch((err) => {
-					console.error("handoff-new generation failed:", err);
+					if (!cancelled) generationError = err;
 					done(null);
 				});
 
@@ -94,18 +99,24 @@ async function handoffNew(args: string, ctx: ExtensionCommandContext) {
 		try {
 			result = await generateHandoffText(ctx, aiContext, ctx.signal);
 		} catch (err) {
-			ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
-			return;
+			generationError = err;
+			result = null;
 		}
 	}
 
+	if (generationError !== undefined) {
+		const error = generationError instanceof Error ? generationError : new Error(String(generationError));
+		ctx.ui.notify(error.message, "error");
+		throw error;
+	}
 	if (result === null) {
 		ctx.ui.notify("Cancelled", "info");
 		return;
 	}
 	if (!result.trim()) {
-		ctx.ui.notify("Handoff generation returned no text", "error");
-		return;
+		const error = new Error("Handoff generation returned no text");
+		ctx.ui.notify(error.message, "error");
+		throw error;
 	}
 
 	// Read the name before newSession: the original ctx is invalidated once

package/dist/extensions/pi-graft/commands.test.ts

@@ -387,7 +387,7 @@ describe("mutation-capable commands", () => {
 		const [title, message] = ctx.ui.confirm.mock.calls[0] as [string, string];
 		expect(title).toContain("provider-backed");
 		expect(message).toContain("leaves this machine");
-		expect(message).toContain("credential is passed only to this Graft child process");
+		expect(message).toContain("Credentials are passed only to this Graft child process");
 		expect(harness.runBuild).toHaveBeenCalledWith(true, ctx);
 	});
 

package/dist/extensions/pi-graft/commands.ts

@@ -330,7 +330,7 @@ export function registerGraftCommands(pi: ExtensionAPI, runtime: GraftCommandRun
 								? "Set up Graft for this repository?"
 								: "Build the Graft graph?",
 						deep
-							? `This runs \`graft build --deep\` in ${repo}.\n\nThe structural graph stays local and deterministic. The deep pass summarizes each changed file and extracts per-symbol cruxes using Selesai's active compatible model, so source-derived content leaves this machine. Its credential is passed only to this Graft child process.\n\nFiles it can write:\n${buildEffects(true)}`
+							? `This runs \`graft build --deep\` in ${repo}.\n\nThe structural graph stays local and deterministic. The deep pass summarizes each changed file and extracts per-symbol cruxes using Selesai's active compatible model, falling back to another model you scoped on the same provider when that model cannot produce Graft summaries. Source-derived content leaves this machine either way. Credentials are passed only to this Graft child process.\n\nFiles it can write:\n${buildEffects(true)}`
 							: `This runs \`graft build\` in ${repo} and can write:\n\n${buildEffects(false)}`,
 						manualCommand,
 					);

package/dist/extensions/pi-graft/index.ts

@@ -183,32 +183,94 @@ const GRAFT_PROVIDER_FOR_SELESAI_PROVIDER: Record<string, "openai" | "anthropic"
 	tokenin: "litellm",
 };
 
-/** Resolve the active Selesai model into the isolated environment Graft needs. */
-async function activeModelGraftEnvironment(ctx: ExtensionContext): Promise<NodeJS.ProcessEnv | undefined> {
+/**
+ * The deep tier either has a plan, or a human-readable reason it does not.
+ * Automatic builds fall back to the structural tier on `ok: false`; the
+ * explicit `/graft deep` command reports the reason instead.
+ */
+type DeepBuildPlan =
+	| { ok: true; env: NodeJS.ProcessEnv | undefined; models: readonly string[] }
+	| { ok: false; reason: string };
+
+/** Graft's per-symbol summary pass is model-sensitive; this is its failure signature. */
+const UNUSABLE_SUMMARIES = /no usable symbol summaries|empty-parsed/i;
+
+/**
+ * Deep-build candidates in order: an explicit `graft.deepModel` pin, the active
+ * model, then the models this session scoped on the same provider. No new
+ * setting is needed — models the user already chose are tried before giving up
+ * on the deep tier.
+ */
+function deepBuildModels(ctx: ExtensionContext, settings: { deepModel?: string }): readonly string[] {
+	const active = ctx.model;
+	const scoped = (ctx.scopedModels ?? [])
+		.map((entry) => entry.model)
+		.filter((candidate) => candidate.provider === active?.provider)
+		.map((candidate) => candidate.id);
+	const ordered = [settings.deepModel, active?.id, ...scoped].filter((id): id is string => Boolean(id));
+	return [...new Set(ordered)].slice(0, 3);
+}
+
+/**
+ * Resolve the active Selesai model into the isolated environment Graft needs.
+ *
+ * Credentials are read from Selesai's own auth storage — TokenIn keys live in
+ * `~/.selesai/agent`, not in the shell environment — and passed only to the
+ * Graft child process.
+ */
+async function resolveDeepBuildPlan(
+	ctx: ExtensionContext,
+	settings: { deepModel?: string } = {},
+): Promise<DeepBuildPlan> {
+	const models = deepBuildModels(ctx, settings);
+	// A user who already configured Graft's own provider environment outranks us.
+	if (process.env.GRAFT_PROVIDER && process.env.GRAFT_API_KEY) return { ok: true, env: undefined, models };
+
 	const model = ctx.model;
-	const provider = model ? GRAFT_PROVIDER_FOR_SELESAI_PROVIDER[model.provider] : undefined;
-	if (!provider) return undefined;
+	if (!model) return { ok: false, reason: "no active model is selected" };
+	const provider = GRAFT_PROVIDER_FOR_SELESAI_PROVIDER[model.provider];
+	if (!provider) {
+		return {
+			ok: false,
+			reason: `provider "${model.provider}" has no Graft wire format (use TokenIn, LiteLLM, OpenAI, Anthropic, or OrcaRouter)`,
+		};
+	}
 
-	let auth: Awaited<ReturnType<typeof ctx.modelRegistry.getProviderAuth>>;
+	let apiKey: string | undefined;
+	let authBaseUrl: string | undefined;
 	try {
-		auth = await ctx.modelRegistry.getProviderAuth(model.provider);
+		const auth = await ctx.modelRegistry.getProviderAuth(model.provider);
+		apiKey = auth?.auth.apiKey;
+		authBaseUrl = auth?.auth.baseUrl;
 	} catch {
-		return undefined;
+		// Fall through to the missing-credential reason below.
+	}
+	if (!apiKey) return { ok: false, reason: `no credential is stored for "${model.provider}"` };
+
+	// The composed model carries the endpoint; auth only sometimes does.
+	const baseUrl = authBaseUrl || model.baseUrl || ctx.modelRegistry.getProvider(model.provider)?.baseUrl;
+	if (provider === "litellm" && !baseUrl) {
+		return { ok: false, reason: `"${model.provider}" has no base URL to send Graft to` };
 	}
-	const apiKey = auth?.auth.apiKey;
-	const baseUrl = auth?.auth.baseUrl;
-	if (!apiKey || (provider === "litellm" && !baseUrl)) return undefined;
 
-	const { GRAFT_PROVIDER: _provider, GRAFT_MODEL: _model, GRAFT_API_KEY: _apiKey, GRAFT_BASE_URL: _baseUrl, ...env } = process.env;
+	const { GRAFT_PROVIDER: _p, GRAFT_MODEL: _m, GRAFT_API_KEY: _k, GRAFT_BASE_URL: _u, ...env } = process.env;
 	return {
-		...env,
-		GRAFT_PROVIDER: provider,
-		GRAFT_MODEL: model.id,
-		GRAFT_API_KEY: apiKey,
-		...(baseUrl ? { GRAFT_BASE_URL: baseUrl } : {}),
+		ok: true,
+		models,
+		env: {
+			...env,
+			GRAFT_PROVIDER: provider,
+			GRAFT_API_KEY: apiKey,
+			...(baseUrl ? { GRAFT_BASE_URL: baseUrl } : {}),
+		},
 	};
 }
 
+/** Graft's environment for one candidate model; undefined keeps the user's own GRAFT_* setup. */
+function deepEnvFor(plan: Extract<DeepBuildPlan, { ok: true }>, modelId: string): NodeJS.ProcessEnv | undefined {
+	return plan.env ? { ...plan.env, GRAFT_MODEL: modelId } : undefined;
+}
+
 export default function graftExtension(pi: ExtensionAPI): void {
 	registerBuiltinAgentAugmentation(pi);
 	const exec: ExecLike = (command, args, options) => pi.exec(command, args, options);
@@ -277,6 +339,48 @@ export default function graftExtension(pi: ExtensionAPI): void {
 		}
 	};
 
+	/**
+	 * Build the graph: deep with a compatible active model, structural otherwise.
+	 *
+	 * A model that cannot produce Graft-parsable summaries is not fatal — the
+	 * next candidate the session already offers is tried before downgrading.
+	 */
+	const buildGraph = async (
+		ctx: ExtensionContext,
+		activeSession: GraftSession,
+		phase: "build" | "refresh" = "build",
+	): Promise<GraftRun> => {
+		const repoRoot = activeSession.repoRoot!;
+		// A refresh has already announced its own "syncing" phase at the caller.
+		const started = (deep: boolean): void => {
+			if (phase === "refresh") return;
+			if (session === activeSession && !activeSession.disposed) applyEvent(ctx, { type: "build-started", deep });
+		};
+		const structural = async (): Promise<GraftRun> => {
+			started(false);
+			return runGraft(exec, repoRoot, { kind: "build", deep: false });
+		};
+
+		const plan = await resolveDeepBuildPlan(ctx, activeSession.settings);
+		if (!plan.ok) return structural();
+
+		// The user's own GRAFT_* environment names the model; never second-guess it.
+		const candidates = plan.env ? plan.models : plan.models.slice(0, 1);
+		let failed: GraftRun | undefined;
+		for (const [index, model] of candidates.entries()) {
+			started(true);
+			const run = await runGraft(exec, repoRoot, { kind: "build", deep: true }, { env: deepEnvFor(plan, model) });
+			if (run.code === 0 || !UNUSABLE_SUMMARIES.test(`${run.stderr}\n${run.stdout}`)) return run;
+			failed = run;
+			if (index === 0 && candidates.length > 1 && ctx.hasUI) {
+				ctx.ui.notify(`Graft cannot summarize with ${model}; retrying the deep pass with another scoped model.`, "info");
+			}
+		}
+		// Nothing left to try: report the last run rather than pretending the
+		// structural tier explained the failure.
+		return failed ?? (await structural());
+	};
+
 	/**
 	 * Start the graph once. Compatible active Selesai models add the deep tier;
 	 * otherwise the free local structural tier remains usable.
@@ -290,11 +394,7 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			activeSession.state.name === "failed"
 		) return undefined;
 
-		const pending = activeModelGraftEnvironment(ctx).then(async (env) => {
-			const deep = env !== undefined;
-			if (session === activeSession && !activeSession.disposed) applyEvent(ctx, { type: "build-started", deep });
-			return runGraft(exec, activeSession.repoRoot!, { kind: "build", deep }, { env });
-		});
+		const pending = buildGraph(ctx, activeSession);
 		structuralBuildPromise = pending;
 		structuralBuildSession = activeSession;
 		void pending.then(
@@ -544,11 +644,9 @@ export default function graftExtension(pi: ExtensionAPI): void {
 
 		void (async () => {
 			try {
-				const env = await activeModelGraftEnvironment(ctx);
-				const deep = env !== undefined;
-				const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep }, { env });
+				const run = await buildGraph(ctx, session, "refresh");
 				if (session.disposed) return;
-				recordBuild(ctx, run, deep);
+				recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			} catch (error) {
 				if (session.disposed) return;
 				applyEvent(ctx, {
@@ -584,24 +682,27 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			if (!deep) {
 				const pending = autoBuild(ctx, session);
 				if (pending) return pending;
+				applyEvent(ctx, { type: "build-started", deep: false });
+				const structural = await runGraft(exec, session.repoRoot!, { kind: "build", deep: false });
+				recordBuild(ctx, structural, false);
+				return structural;
 			}
-			const env = deep ? await activeModelGraftEnvironment(ctx) : undefined;
-			if (deep && !env) {
+			const plan = await resolveDeepBuildPlan(ctx, session.settings);
+			if (!plan.ok) {
 				return {
-					op: { kind: "build", deep },
+					op: { kind: "build", deep: true },
 					argv: ["graft", "build", "--deep"],
 					cwd: session.repoRoot!,
 					code: 1,
 					stdout: "",
-					stderr: "The active Selesai model cannot be used for Graft deep builds.",
+					stderr: `No deep build is possible for the active model: ${plan.reason}.`,
 					killed: false,
 					cancelled: false,
 					timedOut: false,
 				};
 			}
-			applyEvent(ctx, { type: "build-started", deep });
-			const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep }, { env });
-			recordBuild(ctx, run, deep);
+			const run = await buildGraph(ctx, session);
+			recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			return run;
 		},
 		runRefresh: async (ctx) => {
@@ -609,10 +710,8 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			await ensureReady(ctx, { kind: "build", deep: false });
 			session.lastRefreshAt = Date.now();
 			applyEvent(ctx, { type: "refresh-started" });
-			const env = await activeModelGraftEnvironment(ctx);
-			const deep = env !== undefined;
-			const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep }, { env });
-			recordBuild(ctx, run, deep);
+			const run = await buildGraph(ctx, session, "refresh");
+			recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			return run;
 		},
 		providerEnvNames: () => PROVIDER_ENV_NAMES.filter((name) => Boolean(process.env[name])),

package/dist/extensions/pi-graft/lifecycle.test.ts

@@ -304,11 +304,11 @@ describe("proactive refresh", () => {
 		});
 		graftExtension(harness.pi as never);
 		const ctx = makeCtx({ cwd: bare });
+		// Mirrors the real TokenIn shape: the key lives in ~/.selesai auth storage and
+		// the endpoint comes from the composed model, not from the auth resolution.
 		Object.assign(ctx, {
-			model: { provider: "tokenin", id: "deepseek-v4-flash" },
-			modelRegistry: {
-				getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-token", baseUrl: "https://lite.andlet.me/v1" } })),
-			},
+			model: { provider: "tokenin", id: "deepseek-v4.1-flash", baseUrl: "https://lite.andlet.me/v1" },
+			modelRegistry: { getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-token" } })) },
 		});
 		await (handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>)(
 			{ type: "session_start", reason: "startup" },
@@ -317,7 +317,80 @@ describe("proactive refresh", () => {
 		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● deep v0.18.0"));
 		const build = harness.exec.mock.calls.find((call) => (call[1] as string[]).includes("build"))!;
 		expect(build[1]).toEqual(["build", "--deep"]);
-		expect(build[2]).toMatchObject({ env: { GRAFT_PROVIDER: "litellm", GRAFT_MODEL: "deepseek-v4-flash" } });
+		expect(build[2]).toMatchObject({
+			env: {
+				GRAFT_PROVIDER: "litellm",
+				GRAFT_MODEL: "deepseek-v4.1-flash",
+				GRAFT_API_KEY: "test-token",
+				GRAFT_BASE_URL: "https://lite.andlet.me/v1",
+			},
+		});
+	});
+
+	it("retries the deep pass with another scoped model when the active one cannot summarize", async () => {
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+		const bare = join(root, "retry-repo");
+		mkdirSync(join(bare, ".selesai"), { recursive: true });
+		writeFileSync(join(bare, ".selesai", "settings.json"), JSON.stringify({ graft: {} }), "utf-8");
+		const models: string[] = [];
+		const harness = makePi(async (command: string, args: string[], options?: unknown) => {
+			if (command === "git") return { ...OK, stdout: `${bare}\n` };
+			if (args.includes("--version")) return { ...OK, stdout: "0.18.0\n" };
+			if (args.includes("build")) {
+				const model = (options as { env?: Record<string, string> }).env?.GRAFT_MODEL ?? "";
+				models.push(model);
+				if (model === "deepseek-v4.1-flash") {
+					return { ...OK, code: 1, stderr: "calc.ts: model returned no usable symbol summaries [empty-parsed]" };
+				}
+				mkdirSync(join(bare, "graft", ".graph"), { recursive: true });
+				writeFileSync(join(bare, "graft", ".graph", "wiring.json"), "{}", "utf-8");
+				writeFileSync(join(bare, "graft", "concept.md"), "# Concept", "utf-8");
+			}
+			return { ...OK, stdout: ASK_JSON };
+		});
+		graftExtension(harness.pi as never);
+		const ctx = makeCtx({ cwd: bare });
+		Object.assign(ctx, {
+			model: { provider: "tokenin", id: "deepseek-v4.1-flash", baseUrl: "https://lite.andlet.me/v1" },
+			modelRegistry: { getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-token" } })) },
+			scopedModels: [{ model: { provider: "tokenin", id: "glm-5.3-flash" } }],
+		});
+		await (handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>)(
+			{ type: "session_start", reason: "startup" },
+			ctx,
+		);
+		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● deep v0.18.0"));
+		expect(models).toEqual(["deepseek-v4.1-flash", "glm-5.3-flash"]);
+		expect(notified(ctx)).toContain("retrying the deep pass");
+	});
+
+	it("falls back to the structural build when the active model cannot go deep", async () => {
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+		const bare = join(root, "fallback-repo");
+		mkdirSync(join(bare, ".selesai"), { recursive: true });
+		writeFileSync(join(bare, ".selesai", "settings.json"), JSON.stringify({ graft: {} }), "utf-8");
+		const harness = makePi(async (command: string, args: string[]) => {
+			if (command === "git") return { ...OK, stdout: `${bare}\n` };
+			if (args.includes("--version")) return { ...OK, stdout: "0.18.0\n" };
+			if (args.includes("build")) {
+				mkdirSync(join(bare, "graft", ".graph"), { recursive: true });
+				writeFileSync(join(bare, "graft", ".graph", "wiring.json"), "{}", "utf-8");
+			}
+			return { ...OK, stdout: ASK_JSON };
+		});
+		graftExtension(harness.pi as never);
+		const ctx = makeCtx({ cwd: bare });
+		Object.assign(ctx, {
+			model: { provider: "google", id: "gemini-3-pro" },
+			modelRegistry: { getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-key" } })) },
+		});
+		await (handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>)(
+			{ type: "session_start", reason: "startup" },
+			ctx,
+		);
+		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● structural v0.18.0"));
+		const build = harness.exec.mock.calls.find((call) => (call[1] as string[]).includes("build"))!;
+		expect(build[1]).toEqual(["build"]);
 	});
 
 	it("re-indexes after edits, shows the sync phase, and returns to fresh", async () => {

package/dist/extensions/pi-graft/state.test.ts

@@ -240,12 +240,18 @@ describe("readGraftSettings", () => {
 				maxInjectionBytes: -1,
 				maxResultBytes: 0,
 				refreshDebounceSeconds: "60",
+				deepModel: "  ",
 				in: "   ",
 			},
 		});
 		expect(read(false)).toEqual({});
 	});
 
+	it("keeps a deep-build model override for the active provider", () => {
+		write(join(agentDir, "settings.json"), { graft: { deepModel: " glm-5.3-flash " } });
+		expect(read(false)).toEqual({ deepModel: "glm-5.3-flash" });
+	});
+
 	it("keeps a valid enabled flag and telemetry preference", () => {
 		write(join(agentDir, "settings.json"), { graft: { enabled: false, telemetry: "inherit" } });
 		expect(read(false)).toEqual({ enabled: false, telemetry: "inherit" });

package/dist/extensions/pi-graft/state.ts

@@ -57,6 +57,11 @@ export interface GraftSettings {
 	in?: string;
 	/** Seconds a mutation stays "changed" before a proactive refresh is attempted. */
 	refreshDebounceSeconds?: number;
+	/**
+	 * Model id for deep builds, on the active provider. Defaults to the active
+	 * model; set it when that model cannot produce Graft-parsable summaries.
+	 */
+	deepModel?: string;
 }
 
 export const SETTINGS_KEY = "graft";
@@ -97,6 +102,7 @@ function normalizeSettings(raw: unknown): GraftSettings {
 		if (typeof candidate === "number" && Number.isFinite(candidate) && candidate > 0) settings[key] = candidate;
 	}
 	if (typeof value.in === "string" && value.in.trim()) settings.in = value.in.trim();
+	if (typeof value.deepModel === "string" && value.deepModel.trim()) settings.deepModel = value.deepModel.trim();
 	return settings;
 }
 

package/dist/modes/rpc/rpc-mode.js

@@ -466,8 +466,13 @@ export async function runRpcMode(runtimeHost) {
                     return error(id, "handoff_new", "No model selected");
                 try {
                     const handoff = await generateHandoff(session.model, session.modelRuntime, session.sessionManager.getBranch(), command.goal);
+                    const sessionName = session.sessionManager.getSessionName();
                     const result = await runtimeHost.newSession({
                         parentSession: session.sessionManager.getSessionFile(),
+                        setup: async (replacementManager) => {
+                            if (sessionName)
+                                replacementManager.appendSessionInfo(sessionName);
+                        },
                         withSession: async (replacementSession) => replacementSession.sendUserMessage(handoff),
                     });
                     if (!result.cancelled)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selesai/code",
-  "version": "0.13.24",
+  "version": "0.13.26",
   "description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
   "type": "module",
   "repository": {