@selesai/code 0.13.23 → 0.13.25

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [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
+- **Self-building Graft graph.** Graft now creates the initial graph itself instead of waiting for a manual build: the first session start, the first read-only tool call, and a completed CLI install each trigger one build for the repository. A compatible active Selesai model (TokenIn, LiteLLM, OpenAI, Anthropic, or OrcaRouter) adds the deep tier; otherwise the build stays local and structural.
+- **Active-model deep builds.** Deep enrichment now runs on the active Selesai model instead of Graft's own provider configuration. The credential is resolved per build and passed only to the Graft child process, which never inherits it through the host environment.
+
+### Changed
+- **Graft's default retrieval mode is `hybrid`.** Eligible coding turns start from a smaller orientation pack while precise Graft tools stay available; set `graft.mode: "push"` for the previous full-pack behavior.
+- **Deep is the default build.** `/graft build` and `/graft setup` now run the provider-backed deep build, with the new `/graft build --structural` as the explicit local, offline escape hatch.
+- **Graft doctor and recovery hints.** Provider reporting now describes active-model deep builds and the child-process credential boundary instead of asking for Graft's own provider environment variables.
+
 ## [0.13.23] - 2026-09-13
 
 ### Added

package/dist/core/exec.d.ts

@@ -11,6 +11,8 @@ export interface ExecOptions {
     timeout?: number;
     /** Working directory */
     cwd?: string;
+    /** Environment for this child process (defaults to the host environment). */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Result of executing a shell command.

package/dist/core/exec.js

@@ -11,6 +11,7 @@ export async function execCommand(command, args, cwd, options) {
     return new Promise((resolve) => {
         const proc = spawn(command, args, {
             cwd,
+            env: options?.env,
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
         });

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

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { execCommand } from "../../core/exec.ts";
 import {
 	applyTelemetryDefault,
 	askReferences,
@@ -32,6 +33,19 @@ function execReturning(result: StubExecResult) {
 	return { ...result };
 }
 
+describe("execCommand environment", () => {
+	it("passes a supplied credential only to its child process", async () => {
+		const result = await execCommand(
+			process.execPath,
+			["-e", "process.stdout.write(process.env.GRAFT_TEST_TOKEN ?? '')"],
+			process.cwd(),
+			{ env: { ...process.env, GRAFT_TEST_TOKEN: "child-only" } },
+		);
+		expect(result).toMatchObject({ code: 0, stdout: "child-only" });
+		expect(process.env.GRAFT_TEST_TOKEN).toBeUndefined();
+	});
+});
+
 describe("graftCommand", () => {
 	it("invokes the executable directly off Windows", () => {
 		const original = process.platform;
@@ -153,6 +167,15 @@ describe("probeGraft", () => {
 	});
 });
 
+describe("runGraft", () => {
+	it("forwards a private provider environment only to the Graft child", async () => {
+		const { pi } = makePi(async () => execReturning(OK));
+		const env = { ...process.env, GRAFT_PROVIDER: "litellm", GRAFT_MODEL: "deepseek-v4-flash", GRAFT_API_KEY: "secret" };
+		await runGraft(pi.exec as never, "/repo", { kind: "build", deep: true }, { env });
+		expect(pi.exec.mock.calls[0]![2]).toMatchObject({ env });
+	});
+});
+
 describe("graftArgs", () => {
 	it("maps every read-only operation to its documented CLI invocation", () => {
 		const cases: [GraftOp, string[]][] = [

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

@@ -11,8 +11,8 @@
  *   paths, regexes, symbols, and question text cannot become shell injection.
  * - Graft's upstream agent-wiring command (`init`) is never invoked. A missing
  *   compatible CLI is installed once through npm; incompatible CLIs are left alone.
- * - Semantic tools are read-only. Graph builds are command operations gated
- *   behind explicit consent; CLI provisioning is automatic.
+ * - Semantic tools are read-only. Automatic builds use the active compatible
+ *   Selesai model for deep enrichment, otherwise stay structural and local.
  * - Extension-spawned commands default to telemetry opt-out (`DO_NOT_TRACK=1`).
  *
  * Verified against @nanonets/graft 0.18.0 (see {@link MIN_GRAFT_VERSION}).
@@ -144,8 +144,8 @@ export async function probeGraft(exec: ExecLike, cwd: string, signal?: AbortSign
 // ---------------------------------------------------------------------------
 
 /**
- * The read-only operations this adapter exposes, plus the two consent-gated
- * build operations. Every other Graft subcommand (including `init`, `viz`, and
+ * The read-only operations this adapter exposes, plus structural and deep
+ * builds. Every other Graft subcommand (including `init`, `viz`, and
  * `uninstall`) is deliberately unreachable from tool calls.
  */
 export type GraftOp =
@@ -286,7 +286,7 @@ export async function runGraft(
 	exec: ExecLike,
 	repoRoot: string,
 	op: GraftOp,
-	options: { signal?: AbortSignal; timeout?: number } = {},
+	options: { signal?: AbortSignal; timeout?: number; env?: NodeJS.ProcessEnv } = {},
 ): Promise<GraftRun> {
 	const args = graftArgs(op);
 	const { command, args: argv } = graftCommand(args);
@@ -297,6 +297,7 @@ export async function runGraft(
 			cwd: repoRoot,
 			timeout: options.timeout ?? timeoutFor(op),
 			signal: options.signal,
+			env: options.env,
 		});
 	} catch (error) {
 		return {

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

@@ -139,14 +139,14 @@ describe("formatDoctor", () => {
 		expect(text).toContain("fresh-structural");
 		expect(text).toContain("nothing is injected");
 		expect(text).toContain("DO_NOT_TRACK=1 set by this extension");
-		expect(text).toContain("deep builds would need Graft's own provider configuration");
+		expect(text).toContain("automatic deep builds use Selesai's active compatible model");
 		expect(text).toContain("graft deep adds provider-backed summaries");
 	});
 
 	it("shows only which provider variables are set, never their values", () => {
 		const text = formatDoctor({ ...base, providerEnv: ["GRAFT_PROVIDER", "GRAFT_MODEL"] });
 		expect(text).toContain("GRAFT_PROVIDER, GRAFT_MODEL set");
-		expect(text).toContain("values never read or copied");
+		expect(text).toContain("values never shown");
 	});
 
 	it("reports whether this session actually applied the telemetry default", () => {
@@ -205,8 +205,8 @@ describe("buildEffects", () => {
 
 	it("states the provider boundary and the cache for a deep build", () => {
 		const text = buildEffects(true);
-		expect(text).toContain("GRAFT_PROVIDER");
-		expect(text).toContain("Graft's own environment");
+		expect(text).toContain("Selesai's active compatible model");
+		expect(text).toContain("Graft child process");
 		expect(text).toContain("caches those summaries under graft/");
 	});
 });
@@ -289,7 +289,7 @@ describe("mutation-capable commands", () => {
 		}
 	});
 
-	it("installs a missing CLI, rechecks it, then asks only before building", async () => {
+	it("installs a missing CLI, rechecks it, then asks before the default deep build", async () => {
 		const harness = makeRuntime({ state: { name: "unavailable", detail: "ENOENT" }, built: false });
 		const ctx = makeCtx();
 		await invoke(harness.runtime, "setup", ctx);
@@ -297,8 +297,8 @@ describe("mutation-capable commands", () => {
 		expect(harness.installCli).toHaveBeenCalledWith(ctx);
 		expect(harness.recheck).toHaveBeenCalledTimes(3);
 		expect(ctx.ui.confirm).toHaveBeenCalledTimes(1);
-		expect(ctx.ui.confirm.mock.calls[0]![0]).toBe("Set up Graft for this repository?");
-		expect(harness.runBuild).toHaveBeenCalledWith(false, ctx);
+		expect(ctx.ui.confirm.mock.calls[0]![0]).toBe("Run the provider-backed deep build?");
+		expect(harness.runBuild).toHaveBeenCalledWith(true, ctx);
 	});
 
 	it("does not build when installing the missing CLI fails", async () => {
@@ -345,14 +345,16 @@ describe("mutation-capable commands", () => {
 		expect(message).toContain(".gitignore");
 		expect(message).toContain("init");
 		expect(message).toContain("never run");
-		expect(harness.runBuild).toHaveBeenCalledWith(false, ctx);
+		expect(harness.runBuild).toHaveBeenCalledWith(true, ctx);
 		expect(notified(ctx)).toContain("Done.");
 	});
 
-	it("does not run a deep build when the structural build was confirmed", async () => {
+	it("defaults build to deep, with an explicit structural escape hatch", async () => {
 		const harness = makeRuntime();
 		await invoke(harness.runtime, "build", makeCtx());
-		expect(harness.runBuild).toHaveBeenCalledWith(false, expect.anything());
+		expect(harness.runBuild).toHaveBeenCalledWith(true, expect.anything());
+		await invoke(harness.runtime, "build --structural", makeCtx());
+		expect(harness.runBuild).toHaveBeenLastCalledWith(false, expect.anything());
 	});
 
 	it("gives `build --deep` the same provider consent as `/graft deep`", async () => {
@@ -371,10 +373,10 @@ describe("mutation-capable commands", () => {
 		expect(harness.runBuild).toHaveBeenNthCalledWith(2, true, viaDeep);
 	});
 
-	it("treats setup as the structural build", async () => {
+	it("treats setup as the default deep build", async () => {
 		const harness = makeRuntime();
 		await invoke(harness.runtime, "setup", makeCtx());
-		expect(harness.runBuild).toHaveBeenCalledWith(false, expect.anything());
+		expect(harness.runBuild).toHaveBeenCalledWith(true, expect.anything());
 	});
 
 	it("shows the provider boundary before a deep build and only sends source off-machine after consent", async () => {
@@ -385,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("does not read, copy, or forward");
+		expect(message).toContain("Credentials are passed only to this Graft child process");
 		expect(harness.runBuild).toHaveBeenCalledWith(true, ctx);
 	});
 
@@ -472,7 +474,7 @@ describe("runtime contract", () => {
 		const ctx = makeCtx();
 		await invoke(harness.runtime, "status", ctx);
 		expect(PROVIDER_ENV_NAMES).toContain("GRAFT_API_KEY");
-		expect(DEEP_PROVIDER_HINT).toContain("never forwards Selesai credentials");
+		expect(DEEP_PROVIDER_HINT).toContain("active Selesai model");
 		expect(DOCTOR_USAGE).toContain("mode [pull|push|hybrid]");
 	});
 });

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

@@ -1,10 +1,9 @@
 /**
  * The `/graft` command surface: setup, build, deep, refresh, status, doctor, mode.
  *
- * Command handlers own two things the tools never touch: consent, and honest
- * reporting. A command that can write to the repository says exactly which
- * files it may create or change and asks first; with no dialog UI it refuses
- * and prints the exact manual command instead.
+ * Command handlers own reporting and the explicit deep-build confirmation.
+ * They say exactly which repository files may change; with no dialog UI a
+ * manual deep build refuses and prints the exact command instead.
  *
  * Nothing here ever invokes Graft's upstream agent-wiring command. Selesai's
  * setup installs a missing CLI automatically, explains local effects, and builds
@@ -61,7 +60,7 @@ export interface GraftCommandRuntime {
 	graphPresence(): GraphPresence;
 	/** Install the compatible CLI when probing found none. */
 	installCli(ctx: ExtensionContext): Promise<GraftInstallRun>;
-	/** Structural or deep build. Call only after consent. */
+	/** Structural or deep build. Deep calls only after consent. */
 	runBuild(deep: boolean, ctx: ExtensionContext): Promise<GraftRun>;
 	/** Proactive refresh of an existing graph; undefined when there is nothing to refresh. */
 	runRefresh(ctx: ExtensionContext): Promise<GraftRun | undefined>;
@@ -75,8 +74,8 @@ export const DOCTOR_USAGE = `/graft <command>
 
   status          current availability, graph state, and retrieval mode
   doctor          full health report with a recovery step for each problem
-  setup           install the CLI if needed, then explain build effects and ask for consent
-  build           build graft/ for this repository (structural; no model, no key)
+  setup           install the CLI if needed, then build the deep graph with the active model
+  build [--structural]   build graft/ (deep by default; structural stays local)
   deep            provider-backed build: adds summaries and per-symbol crux
   refresh         re-index an existing graph after edits
   mode [pull|push|hybrid]   show or set the retrieval strategy
@@ -145,8 +144,8 @@ export function formatDoctor(input: DoctorInput): string {
 	row(
 		"provider env",
 		input.providerEnv.length > 0
-			? `${input.providerEnv.join(", ")} set (values never read or copied) — deep builds use Graft's own provider configuration`
-			: `none of ${PROVIDER_ENV_NAMES.join(", ")} set — deep builds would need Graft's own provider configuration`,
+			? `${input.providerEnv.join(", ")} set (values never shown) — manual Graft CLI configuration is available`
+			: `none of ${PROVIDER_ENV_NAMES.join(", ")} set — automatic deep builds use Selesai's active compatible model`,
 	);
 
 	const recovery = recoveryFor(input.state);
@@ -185,7 +184,7 @@ export function buildEffects(deep: boolean): string {
 	];
 	if (deep) {
 		effects.push(
-			"  • sends source-derived file summaries and symbol cruxes through the LLM provider configured in Graft's own environment (GRAFT_PROVIDER / GRAFT_MODEL / GRAFT_BASE_URL / GRAFT_API_KEY)",
+			"  • sends source-derived file summaries and symbol cruxes through Selesai's active compatible model; credentials are passed only to the Graft child process",
 			"  • caches those summaries under graft/ so later deep builds are incremental",
 		);
 	}
@@ -259,9 +258,10 @@ export function registerGraftCommands(pi: ExtensionAPI, runtime: GraftCommandRun
 			const items: ArgumentCompletion[] = [
 				{ value: "status", label: "status", description: "availability, graph state, retrieval mode" },
 				{ value: "doctor", label: "doctor", description: "full health report and recovery steps" },
-				{ value: "setup", label: "setup", description: "install CLI if needed, then build graft/" },
-				{ value: "build", label: "build", description: "build graft/ (structural; no model, no key)" },
-				{ value: "deep", label: "deep", description: "provider-backed build (needs Graft provider config)" },
+				{ value: "setup", label: "setup", description: "install CLI if needed, then build the deep graph" },
+				{ value: "build", label: "build", description: "build graft/ with the active model (default deep)" },
+				{ value: "build --structural", label: "build --structural", description: "build graft/ locally without model enrichment" },
+				{ value: "deep", label: "deep", description: "provider-backed build with the active model" },
 				{ value: "refresh", label: "refresh", description: "re-index an existing graph after edits" },
 				{ value: "mode", label: "mode", description: "show or set pull | push | hybrid" },
 				{ value: "help", label: "help", description: "usage" },
@@ -317,7 +317,7 @@ export function registerGraftCommands(pi: ExtensionAPI, runtime: GraftCommandRun
 				case "setup":
 				case "build":
 				case "deep": {
-					const deep = subcommand === "deep" || rest.includes("--deep");
+					const deep = subcommand === "deep" || !rest.includes("--structural");
 					await runtime.recheck(ctx);
 					if (!(await ensureCli(ctx, runtime))) return;
 					const repo = runtime.repoRoot() ?? "this repository";
@@ -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 is different: Graft summarizes each changed file and extracts per-symbol cruxes using the LLM provider configured in Graft's own environment, so source-derived content leaves this machine.\n\nSelesai does not read, copy, or forward its own provider credentials to Graft.\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,
 					);
@@ -388,5 +388,5 @@ async function runAndReport(
 
 /** Where the deep-build guidance points a user whose provider is not configured. */
 export const DEEP_PROVIDER_HINT =
-	`Set GRAFT_PROVIDER, GRAFT_MODEL, and GRAFT_API_KEY in your own environment (or a repo .env), then re-run /graft deep. ` +
-	`${GRAFT_PACKAGE} reads them itself; this extension never forwards Selesai credentials.`;
+	`Select a compatible active Selesai model (TokenIn, LiteLLM, OpenAI, Anthropic, or OrcaRouter), then re-run /graft deep. ` +
+	`${GRAFT_PACKAGE} receives its credential only in that child process.`;

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

@@ -12,7 +12,7 @@
  * - Graft's upstream agent-wiring command (`init`) is never invoked.
  * - A missing compatible CLI is automatically installed once through npm;
  *   incompatible user installations are never overwritten.
- * - Builds require explicit consent; deep (provider-backed) builds need their own.
+ * - The first build uses Selesai's active compatible model for deep enrichment; otherwise it stays local and structural.
  * - Every tool is read-only; the graph is a local cache, not a committed artifact.
  * - Graft processes default to telemetry opt-out without touching Graft's settings.
  *
@@ -175,11 +175,109 @@ export function isMutatingResult(event: { toolName: string; input: Record<string
 	return false;
 }
 
+const GRAFT_PROVIDER_FOR_SELESAI_PROVIDER: Record<string, "openai" | "anthropic" | "litellm" | "orcarouter"> = {
+	anthropic: "anthropic",
+	litellm: "litellm",
+	openai: "openai",
+	orcarouter: "orcarouter",
+	tokenin: "litellm",
+};
+
+/**
+ * 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;
+	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 apiKey: string | undefined;
+	let authBaseUrl: string | undefined;
+	try {
+		const auth = await ctx.modelRegistry.getProviderAuth(model.provider);
+		apiKey = auth?.auth.apiKey;
+		authBaseUrl = auth?.auth.baseUrl;
+	} catch {
+		// 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 { GRAFT_PROVIDER: _p, GRAFT_MODEL: _m, GRAFT_API_KEY: _k, GRAFT_BASE_URL: _u, ...env } = process.env;
+	return {
+		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);
 	let session = freshSession();
 	let installPromise: Promise<GraftInstallRun> | undefined;
+	let structuralBuildPromise: Promise<GraftRun> | undefined;
+	let structuralBuildSession: GraftSession | undefined;
 	const guard = createInjectionGuard();
 
 	const applyEvent = (ctx: ExtensionContext | undefined, event: GraftEvent): void => {
@@ -241,6 +339,82 @@ 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.
+	 */
+	const autoBuild = (ctx: ExtensionContext, activeSession: GraftSession): Promise<GraftRun> | undefined => {
+		if (structuralBuildPromise && structuralBuildSession === activeSession) return structuralBuildPromise;
+		if (
+			!activeSession.repoRoot ||
+			activeSession.probe?.kind !== "ok" ||
+			activeSession.presence.built ||
+			activeSession.state.name === "failed"
+		) return undefined;
+
+		const pending = buildGraph(ctx, activeSession);
+		structuralBuildPromise = pending;
+		structuralBuildSession = activeSession;
+		void pending.then(
+			(run) => {
+				if (session === activeSession && !activeSession.disposed) recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
+			},
+			(error) => {
+				if (session === activeSession && !activeSession.disposed) {
+					applyEvent(ctx, { type: "build-failed", detail: error instanceof Error ? error.message : String(error) });
+				}
+			},
+		).finally(() => {
+			if (structuralBuildPromise === pending && structuralBuildSession === activeSession) {
+				structuralBuildPromise = undefined;
+				structuralBuildSession = undefined;
+			}
+		});
+		return pending;
+	};
+
 	/** Install a missing CLI without blocking session startup or racing another session. */
 	const autoInstall = (ctx: ExtensionContext, activeSession: GraftSession): void => {
 		if (ctx.hasUI) ctx.ui.notify("Installing Graft CLI…", "info");
@@ -258,6 +432,7 @@ export default function graftExtension(pi: ExtensionAPI): void {
 				if (ctx.hasUI) ctx.ui.notify("Graft CLI installed, but is not yet usable. Restart Selesai and run /graft doctor.", "warning");
 				return;
 			}
+			autoBuild(ctx, activeSession);
 			if (ctx.hasUI) ctx.ui.notify("Graft CLI installed.", "info");
 		})();
 	};
@@ -285,11 +460,14 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			throw new Error(`Graft is not usable here: ${detail} Run /graft doctor for a recovery step.`);
 		}
 		if (!session.presence.built && op.kind !== "check-freshness" && op.kind !== "build") {
-			throw new Error(
-				`There is no ${GRAPH_DIR_NAME}/ graph in ${session.repoRoot} yet. ${
-					recoveryFor(session.state) ?? "Run /graft build to index this repository."
-				}`,
-			);
+			await autoBuild(ctx, session);
+			if (!session.presence.built) {
+				throw new Error(
+					`There is no ${GRAPH_DIR_NAME}/ graph in ${session.repoRoot} yet. ${
+						recoveryFor(session.state) ?? "Run /graft build to retry the structural index."
+					}`,
+				);
+			}
 		}
 	};
 
@@ -337,6 +515,7 @@ export default function graftExtension(pi: ExtensionAPI): void {
 
 		await recheck(ctx);
 		if (session.state.name === "unavailable") autoInstall(ctx, session);
+		else autoBuild(ctx, session);
 	});
 
 	pi.on("session_shutdown", (_event: SessionShutdownEvent, ctx: ExtensionContext) => {
@@ -450,9 +629,8 @@ export default function graftExtension(pi: ExtensionAPI): void {
 	 * Debounced, idle-aware proactive refresh.
 	 *
 	 * `agent_end` is the runtime's own idle boundary, so this needs no timer: a
-	 * burst of edits inside one turn costs at most one rebuild, and a structural
-	 * rebuild is free and offline. Refresh never *creates* a graph — an unbuilt
-	 * repository stays unbuilt until the user consents to a build.
+	 * burst of edits inside one turn costs at most one rebuild. A compatible
+	 * active Selesai model adds the deep tier; otherwise refresh stays local.
 	 */
 	pi.on("agent_end", (_event, ctx) => {
 		if (!session.enabled || session.disposed) return;
@@ -466,9 +644,9 @@ export default function graftExtension(pi: ExtensionAPI): void {
 
 		void (async () => {
 			try {
-				const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep: false });
+				const run = await buildGraph(ctx, session, "refresh");
 				if (session.disposed) return;
-				recordBuild(ctx, run, false);
+				recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			} catch (error) {
 				if (session.disposed) return;
 				applyEvent(ctx, {
@@ -501,9 +679,30 @@ export default function graftExtension(pi: ExtensionAPI): void {
 		installCli,
 		runBuild: async (deep, ctx) => {
 			await ensureReady(ctx, { kind: "build", deep });
-			applyEvent(ctx, { type: "build-started", deep });
-			const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep });
-			recordBuild(ctx, run, deep);
+			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 plan = await resolveDeepBuildPlan(ctx, session.settings);
+			if (!plan.ok) {
+				return {
+					op: { kind: "build", deep: true },
+					argv: ["graft", "build", "--deep"],
+					cwd: session.repoRoot!,
+					code: 1,
+					stdout: "",
+					stderr: `No deep build is possible for the active model: ${plan.reason}.`,
+					killed: false,
+					cancelled: false,
+					timedOut: false,
+				};
+			}
+			const run = await buildGraph(ctx, session);
+			recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			return run;
 		},
 		runRefresh: async (ctx) => {
@@ -511,8 +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 run = await runGraft(exec, session.repoRoot!, { kind: "build", deep: false });
-			recordBuild(ctx, run, false);
+			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

@@ -263,7 +263,7 @@ describe("proactive refresh", () => {
 		await session.reset();
 	});
 
-	it("never creates a graph that does not exist", async () => {
+	it("automatically creates the initial local structural graph", async () => {
 		process.env.PI_CODING_AGENT_DIR = agentDir;
 		const bare = join(root, "bare-repo");
 		mkdirSync(join(bare, ".selesai"), { recursive: true });
@@ -271,6 +271,10 @@ describe("proactive refresh", () => {
 		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);
@@ -279,10 +283,114 @@ describe("proactive refresh", () => {
 			{ type: "session_start", reason: "startup" },
 			ctx,
 		);
-		expect(ctx.statuses.get("graft")).toBe("graft: ○ unbuilt v0.18.0");
-		const before = harness.exec.mock.calls.length;
-		await (handlerFor(harness, "agent_end") as (e: unknown, c: unknown) => Promise<void>)({}, ctx);
-		expect(harness.exec.mock.calls.length).toBe(before);
+		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● structural v0.18.0"));
+		expect(harness.commandsRun()).toContain("graft build");
+	});
+
+	it("uses the active TokenIn model for the default deep build", async () => {
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+		const bare = join(root, "deep-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");
+				writeFileSync(join(bare, "graft", "concept.md"), "# Concept", "utf-8");
+			}
+			return { ...OK, stdout: ASK_JSON };
+		});
+		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.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" },
+			ctx,
+		);
+		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.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 () => {
@@ -352,7 +460,7 @@ describe("retrieval strategy", () => {
 			session.ctx,
 		);
 
-	it("injects a source-backed pack in push mode, which is the default", async () => {
+	it("injects a source-backed orientation pack in the default hybrid mode", async () => {
 		const session = await bootSession();
 		const result = await beforeAgentStart(session, "Fix the login crash");
 		expect(result).toBeDefined();
@@ -450,7 +558,7 @@ describe("retrieval strategy", () => {
 		expect(notified(ctx)).toContain("Graft context unavailable");
 	});
 
-	it("injects nothing when the graph has never been built, and says how to fix it", async () => {
+	it("waits for the initial structural build before injecting context", async () => {
 		process.env.PI_CODING_AGENT_DIR = agentDir;
 		const bare = join(root, "unbuilt-repo");
 		mkdirSync(join(bare, ".selesai"), { recursive: true });
@@ -458,6 +566,10 @@ describe("retrieval strategy", () => {
 		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);
@@ -471,7 +583,7 @@ describe("retrieval strategy", () => {
 				{ type: "before_agent_start", prompt: "Fix the login crash" },
 				ctx,
 			),
-		).toBeUndefined();
+		).toMatchObject({ message: { customType: "graft-context" } });
 	});
 });
 
@@ -523,7 +635,7 @@ describe("tool readiness", () => {
 		).rejects.toThrow(/Run \/graft doctor/);
 	});
 
-	it("tells the user to build before answering from a graph that is not there", async () => {
+	it("builds before answering from a graph that is not there", async () => {
 		process.env.PI_CODING_AGENT_DIR = agentDir;
 		const bare = join(root, "unbuilt-tools");
 		mkdirSync(join(bare, ".selesai"), { recursive: true });
@@ -531,6 +643,10 @@ describe("tool readiness", () => {
 		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);
@@ -542,7 +658,8 @@ describe("tool readiness", () => {
 		const tool = toolFor(harness, "graft_find_code");
 		await expect(
 			(tool.execute as (...args: unknown[]) => Promise<unknown>)("c", { question: "x" }, undefined, undefined, ctx),
-		).rejects.toThrow(/graft build/);
+		).resolves.toBeDefined();
+		expect(harness.commandsRun()).toContain("graft build");
 	});
 
 	it("re-resolves lazily when an earlier attempt found no repository", async () => {

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

@@ -170,8 +170,8 @@ describe("retrieval mode", () => {
 		expect(isRetrievalMode(undefined)).toBe(false);
 	});
 
-	it("defaults to push, the source-backed context mode", () => {
-		expect(DEFAULT_RETRIEVAL_MODE).toBe("push");
+	it("defaults to hybrid, the relevance-gated context mode", () => {
+		expect(DEFAULT_RETRIEVAL_MODE).toBe("hybrid");
 	});
 
 	it("restores the newest mode chosen on this branch, ignoring other custom entries", () => {
@@ -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

@@ -30,7 +30,7 @@ import { INSTALL_COMMAND } from "./cli.ts";
 export type RetrievalMode = "pull" | "push" | "hybrid";
 
 export const RETRIEVAL_MODES: readonly RetrievalMode[] = ["pull", "push", "hybrid"];
-export const DEFAULT_RETRIEVAL_MODE: RetrievalMode = "push";
+export const DEFAULT_RETRIEVAL_MODE: RetrievalMode = "hybrid";
 
 export function isRetrievalMode(value: unknown): value is RetrievalMode {
 	return typeof value === "string" && (RETRIEVAL_MODES as readonly string[]).includes(value);
@@ -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/extensions/pi-graft/tools.ts

@@ -12,8 +12,9 @@
  *   graft_check_freshness → graft check --json
  *
  * Every one of them is read-only under Selesai's capability model. Nothing here
- * can build, mutate, install, or configure anything — the build operations live
- * behind the consent-gated commands in `commands.ts`.
+ * can build, mutate, install, or configure anything — the extension builds the
+ * graph during session setup, using the active compatible Selesai model for the
+ * optional deep tier.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";

package/package.json

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