@selesai/code 0.13.22 → 0.13.24

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [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
+- **Bundled Graft code context.** Selesai now ships native integration for `@nanonets/graft`: it installs a compatible CLI when missing, builds a consent-gated local graph, injects bounded source-backed context for eligible coding turns, and exposes six read-only semantic retrieval tools plus `/graft` lifecycle commands. Structural builds stay local and offline; deep provider-backed builds require separate confirmation.
+- **Graft-aware builtin subagents.** The `scout`, `reviewer`, `worker`, `delegate`, and `oracle` builtins automatically receive Graft's read-only code-context tools and child-only extension when Graft is loaded. Explicit user tool or extension overrides retain precedence.
+
+### Changed
+- **Capability gateway Graft exemption.** Graft's code-context tools remain active rather than becoming dormant, preserving its pre-turn retrieval and precise follow-ups.
+
 ## [0.13.22] - 2026-09-12
 
 ### Fixed

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/capability-gateway/index.ts

@@ -6,9 +6,9 @@
  *
  * Behavior:
  * - On by default; disable via SELESAI_CAPABILITY_GATEWAY=0.
- * - At session start, extension tools (except the gateway's own tools) become
- *   dormant: they stay registered but are removed from the active tool set.
- *   Built-in tools are never touched.
+ * - At session start, extension tools become dormant except the gateway's own
+ *   tools and Graft's code-context tools: they stay registered but are removed
+ *   from the active tool set. Built-in tools are never touched.
  * - A compact catalog tool lists eligible tools/skills with one-line summaries.
  * - capability_discover validates one catalogued tool and activates its native
  *   definition for the current agent run; capability_skill_show loads exactly
@@ -40,6 +40,17 @@ import {
 export const GATEWAY_ENV = "SELESAI_CAPABILITY_GATEWAY";
 export const GATEWAY_TOOLS = new Set(["capability_catalog", "capability_discover", "capability_skill_show"]);
 
+// Graft supplies pre-turn hybrid context and must remain callable for precise
+// follow-ups; making it dormant defeats both paths.
+const ALWAYS_ACTIVE_EXTENSION_TOOLS = new Set([
+	"graft_check_freshness",
+	"graft_file_api",
+	"graft_find_all",
+	"graft_find_code",
+	"graft_repo_map",
+	"graft_trace_calls",
+]);
+
 export const CAPABILITY_INSTRUCTION = `Optional capabilities (extension tools and skills) are not listed here by default. To use one:
 - Search the compact catalog with capability_catalog (kind: "tool" or "skill", natural-language query) when no active tool fits or a specialized integration/workflow is requested.
 - Activate a catalogued tool with capability_discover, then call it normally on the next turn.
@@ -53,7 +64,7 @@ function isEnabled(): boolean {
 function eligibleTools(pi: ExtensionAPI): ToolInfo[] {
 	return pi
 		.getAllTools()
-		.filter((tool) => !GATEWAY_TOOLS.has(tool.name) && !BUILTIN_TOOL_NAMES.has(tool.name));
+		.filter((tool) => !GATEWAY_TOOLS.has(tool.name) && !ALWAYS_ACTIVE_EXTENSION_TOOLS.has(tool.name) && !BUILTIN_TOOL_NAMES.has(tool.name));
 }
 
 function catalogEntries(pi: ExtensionAPI): CatalogEntry[] {

package/dist/extensions/capability-gateway/integration.test.ts

@@ -16,6 +16,7 @@ import {
 const EXTENSIONS_DIR = fileURLToPath(new URL("../../", import.meta.url));
 const GATEWAY_DIR = fileURLToPath(new URL(".", import.meta.url));
 const GREP_APP_DIR = fileURLToPath(new URL("../grep-app", import.meta.url));
+const GRAFT_DIR = fileURLToPath(new URL("../pi-graft", import.meta.url));
 const INLINE_SKILLS_FILE = fileURLToPath(new URL("../inline-skills.ts", import.meta.url));
 
 interface Harness {
@@ -134,6 +135,20 @@ describe("capability gateway integration", () => {
 		expect(active).toContain("capability_catalog");
 	});
 
+	it("keeps all Graft tools active for hybrid context and precise follow-ups", async () => {
+		const h = await createGatewaySession({ enabled: true, extensions: [GATEWAY_DIR, GRAFT_DIR] });
+		harnesses.push(h);
+		const active = h.session.getActiveToolNames();
+		for (const name of [
+			"graft_check_freshness",
+			"graft_file_api",
+			"graft_find_all",
+			"graft_find_code",
+			"graft_repo_map",
+			"graft_trace_calls",
+		]) expect(active).toContain(name);
+	});
+
 	it("keeps all-visible behavior when disabled (compatibility mode)", async () => {
 		const h = await createGatewaySession({ enabled: false });
 		harnesses.push(h);

package/dist/extensions/package.json

@@ -2,6 +2,7 @@
 	"name": "@selesai/bundled-extensions",
 	"version": "0.0.0",
 	"private": true,
+	"type": "module",
 	"description": "Built-in extensions shipped with @selesai/code, loaded via additionalExtensionPaths at boot.",
 	"pi": {
 		"extensions": [
@@ -19,6 +20,7 @@
 			"./inline-skills.ts",
 			"./rtk.ts",
 			"./tokenin-onboarding.ts",
+			"./pi-graft",
 			"./undo.ts",
 			"./pi-subagents",
 			"./pi-tool-display",

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

@@ -0,0 +1,431 @@
+import { describe, expect, it, vi } from "vitest";
+import { execCommand } from "../../core/exec.ts";
+import {
+	applyTelemetryDefault,
+	askReferences,
+	boundText,
+	compareVersions,
+	DEFAULT_FIND_LIMIT,
+	GRAFT_INSTALL_SPEC,
+	graftArgs,
+	graftCommand,
+	INSTALL_COMMAND,
+	INSTALL_TIMEOUT_MS,
+	installGraft,
+	graftFailureMessage,
+	isCompatibleVersion,
+	MAX_GRAFT_VERSION_EXCLUSIVE,
+	MIN_GRAFT_VERSION,
+	parseAskJson,
+	parsePointer,
+	npmCommand,
+	parseVersion,
+	probeGraft,
+	renderAsk,
+	runGraft,
+	TELEMETRY_ENV,
+	type GraftOp,
+	type GraftRun,
+} from "./cli.ts";
+import { FAILED, makePi, OK, type StubExecResult } from "./test-support.ts";
+
+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;
+		if (original === "win32") return;
+		expect(graftCommand(["ask", "hi"])).toEqual({ command: "graft", args: ["ask", "hi"] });
+	});
+
+	it("routes through cmd.exe on win32 so the .cmd shim can be spawned without a shell", () => {
+		const original = process.platform;
+		Object.defineProperty(process, "platform", { value: "win32" });
+		try {
+			expect(graftCommand(["build"])).toEqual({ command: "cmd", args: ["/c", "graft", "build"] });
+		} finally {
+			Object.defineProperty(process, "platform", { value: original });
+		}
+	});
+});
+
+describe("installGraft", () => {
+	it("runs the compatible global npm install without a shell off Windows", async () => {
+		const { pi } = makePi(async () => execReturning(OK));
+		const run = await installGraft(pi.exec as never, "/repo");
+		expect(GRAFT_INSTALL_SPEC).toBe("@nanonets/graft@^0.18");
+		expect(INSTALL_COMMAND).toBe("npm install -g @nanonets/graft@^0.18");
+		const [command, args, options] = pi.exec.mock.calls[0] as [string, string[], { cwd: string; timeout: number }];
+		expect(command).toBe(process.platform === "win32" ? "cmd" : "npm");
+		expect(args).toContain("install");
+		expect(args).toContain(GRAFT_INSTALL_SPEC);
+		expect(options).toMatchObject({ cwd: "/repo", timeout: INSTALL_TIMEOUT_MS });
+		expect(run.code).toBe(0);
+	});
+
+	it("routes npm through cmd.exe on win32", () => {
+		const original = process.platform;
+		Object.defineProperty(process, "platform", { value: "win32" });
+		try {
+			expect(npmCommand(["install", "-g", GRAFT_INSTALL_SPEC])).toEqual({
+				command: "cmd",
+				args: ["/c", "npm", "install", "-g", GRAFT_INSTALL_SPEC],
+			});
+		} finally {
+			Object.defineProperty(process, "platform", { value: original });
+		}
+	});
+
+	it("normalizes install spawn failures", async () => {
+		const { pi } = makePi(async () => {
+			throw new Error("spawn npm ENOENT");
+		});
+		const run = await installGraft(pi.exec as never, "/repo");
+		expect(run.code).toBe(1);
+		expect(run.stderr).toContain("ENOENT");
+	});
+});
+
+describe("version handling", () => {
+	it("reads a semantic version out of arbitrary CLI output", () => {
+		expect(parseVersion("0.18.0")).toBe("0.18.0");
+		expect(parseVersion("graft v0.18.3\nlatest on npm: 0.19.0")).toBe("0.18.3");
+		expect(parseVersion("0.18.0-beta.2")).toBe("0.18.0-beta.2");
+		expect(parseVersion("no version here")).toBeUndefined();
+	});
+
+	it("compares numeric segments, ignoring suffixes", () => {
+		expect(compareVersions("0.18.0", "0.18.0")).toBe(0);
+		expect(compareVersions("0.17.9", "0.18.0")).toBeLessThan(0);
+		expect(compareVersions("0.18.1-beta.1", "0.18.0")).toBeGreaterThan(0);
+		expect(compareVersions("1.0.0", "0.99.99")).toBeGreaterThan(0);
+	});
+
+	it("accepts the verified range and rejects the boundaries", () => {
+		expect(isCompatibleVersion(MIN_GRAFT_VERSION)).toBe(true);
+		expect(isCompatibleVersion("0.18.4")).toBe(true);
+		expect(isCompatibleVersion("0.99.0")).toBe(true);
+		expect(isCompatibleVersion("0.17.9")).toBe(false);
+		expect(isCompatibleVersion(MAX_GRAFT_VERSION_EXCLUSIVE)).toBe(false);
+		expect(isCompatibleVersion("1.2.0")).toBe(false);
+	});
+});
+
+describe("probeGraft", () => {
+	it("accepts a supported version and reports it", async () => {
+		const { pi } = makePi(async () => execReturning({ ...OK, stdout: "0.18.0\n" }));
+		const probe = await probeGraft(pi.exec as never, "/repo");
+		expect(probe).toMatchObject({ kind: "ok", version: "0.18.0" });
+		if (probe.kind === "ok") expect(probe.argv.at(-1)).toBe("--version");
+	});
+
+	it("reports a missing executable when the spawn throws", async () => {
+		const { pi } = makePi(async () => {
+			throw new Error("spawn graft ENOENT");
+		});
+		const probe = await probeGraft(pi.exec as never, "/repo");
+		expect(probe.kind).toBe("missing");
+		if (probe.kind === "missing") expect(probe.detail).toContain("ENOENT");
+	});
+
+	it("reports a missing executable when the probe is killed", async () => {
+		const { pi } = makePi(async () => execReturning({ ...OK, killed: true }));
+		const probe = await probeGraft(pi.exec as never, "/repo");
+		expect(probe.kind).toBe("missing");
+	});
+
+	it("refuses to accept an out-of-range version", async () => {
+		const { pi } = makePi(async () => execReturning({ ...OK, stdout: "0.4.0\n" }));
+		const probe = await probeGraft(pi.exec as never, "/repo");
+		expect(probe.kind).toBe("incompatible");
+		if (probe.kind === "incompatible") {
+			expect(probe.version).toBe("0.4.0");
+			expect(probe.detail).toContain(MIN_GRAFT_VERSION);
+		}
+	});
+
+	it("treats an unreadable version as incompatible rather than assuming compatibility", async () => {
+		const { pi } = makePi(async () => execReturning({ ...OK, stdout: "graft (unknown build)\n" }));
+		const probe = await probeGraft(pi.exec as never, "/repo");
+		expect(probe.kind).toBe("incompatible");
+		if (probe.kind === "incompatible") expect(probe.version).toBeUndefined();
+	});
+});
+
+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[]][] = [
+			[{ kind: "find-code", question: "how does auth work" }, ["ask", "how does auth work", "--source", "--json"]],
+			[
+				{ kind: "find-code", question: "auth", limit: 3, in: "packages/api" },
+				["ask", "auth", "--source", "--json", "-n", "3", "--in", "packages/api"],
+			],
+			[{ kind: "file-api", path: "src/app.ts" }, ["skeleton", "src/app.ts"]],
+			[{ kind: "trace-calls", symbol: "build", direction: "in" }, ["callers", "build"]],
+			[
+				{ kind: "trace-calls", symbol: "build", direction: "out", depth: 3 },
+				["callers", "build", "--direction", "out", "-d", "3"],
+			],
+			[
+				{ kind: "find-all", pattern: "TODO", ignoreCase: true, fixed: true, in: "src" },
+				["grep", "TODO", "-i", "--fixed", "--in", "src"],
+			],
+			[{ kind: "repo-map", maxDirs: 12 }, ["map", "--max-dirs", "12"]],
+			[{ kind: "check-freshness" }, ["check", "--json"]],
+			[{ kind: "build", deep: false }, ["build"]],
+			[{ kind: "build", deep: true }, ["build", "--deep"]],
+		];
+		for (const [op, expected] of cases) expect(graftArgs(op)).toEqual(expected);
+	});
+
+	it("keeps the default depth implicit so the CLI's own default applies", () => {
+		expect(graftArgs({ kind: "trace-calls", symbol: "x", direction: "in", depth: 1 })).toEqual(["callers", "x"]);
+	});
+
+	it("passes hostile input as one verbatim argv entry, never as shell text", () => {
+		const question = 'rm -rf / && echo "pwned"; `whoami`';
+		// The whole string survives as exactly one argv element: there is no shell to
+		// reinterpret the metacharacters, and nothing splices it into another argument.
+		expect(graftArgs({ kind: "find-code", question })).toEqual(["ask", question, "--source", "--json"]);
+
+		const hostilePattern = '"; rm -rf $HOME; "';
+		expect(graftArgs({ kind: "find-all", pattern: hostilePattern })).toEqual(["grep", hostilePattern]);
+
+		expect(graftArgs({ kind: "file-api", path: "src/with space/and;rm.ts" })).toEqual([
+			"skeleton",
+			"src/with space/and;rm.ts",
+		]);
+	});
+});
+
+describe("runGraft", () => {
+	it("runs in the resolved repository root and reports the full argv", async () => {
+		const { pi } = makePi(async () => execReturning({ ...OK, stdout: "ok" }));
+		const run = await runGraft(pi.exec as never, "/repo/root", { kind: "repo-map" });
+		expect(pi.exec).toHaveBeenCalledTimes(1);
+		const [command, args, options] = pi.exec.mock.calls[0] as [string, string[], { cwd: string; timeout: number }];
+		expect(command).toBe(process.platform === "win32" ? "cmd" : "graft");
+		expect(args).toContain("map");
+		expect(options.cwd).toBe("/repo/root");
+		expect(options.timeout).toBe(60_000);
+		expect(run.cwd).toBe("/repo/root");
+		expect(run.argv.at(-1)).toBe("map");
+	});
+
+	it("uses the long build timeout for builds", async () => {
+		const { pi } = makePi(async () => execReturning(OK));
+		await runGraft(pi.exec as never, "/repo", { kind: "build", deep: true });
+		const [, , options] = pi.exec.mock.calls[0] as [string, string[], { timeout: number }];
+		expect(options.timeout).toBe(1_800_000);
+	});
+
+	it("distinguishes a caller abort from a timeout", async () => {
+		const { pi } = makePi(async () => execReturning({ ...OK, killed: true }));
+		const controller = new AbortController();
+		controller.abort();
+		const cancelled = await runGraft(pi.exec as never, "/repo", { kind: "repo-map" }, { signal: controller.signal });
+		expect(cancelled.cancelled).toBe(true);
+		expect(cancelled.timedOut).toBe(false);
+
+		const noSignal = await runGraft(pi.exec as never, "/repo", { kind: "repo-map" });
+		expect(noSignal.timedOut).toBe(true);
+		expect(noSignal.cancelled).toBe(false);
+	});
+
+	it("normalizes a spawn failure into a failed run instead of throwing", async () => {
+		const { pi } = makePi(async () => {
+			throw new Error("spawn graft ENOENT");
+		});
+		const run = await runGraft(pi.exec as never, "/repo", { kind: "repo-map" });
+		expect(run.code).toBe(1);
+		expect(run.stderr).toContain("ENOENT");
+	});
+});
+
+describe("graftFailureMessage", () => {
+	const base: GraftRun = {
+		op: { kind: "repo-map" },
+		argv: ["graft", "map"],
+		cwd: "/repo",
+		code: 1,
+		stdout: "",
+		stderr: "",
+		killed: false,
+		cancelled: false,
+		timedOut: false,
+	};
+
+	it("names the command and its exit status, taking the first stderr line", () => {
+		expect(graftFailureMessage({ ...base, stderr: "boom\ndetails" })).toBe("graft map failed (exit 1): boom");
+	});
+
+	it("falls back to stdout when stderr is empty", () => {
+		expect(graftFailureMessage({ ...base, stdout: "✗ no graft/ here" })).toContain("no graft/ here");
+	});
+
+	it("reports cancellation and timeouts distinctly", () => {
+		expect(graftFailureMessage({ ...base, cancelled: true })).toContain("cancelled");
+		expect(graftFailureMessage({ ...base, timedOut: true })).toContain("timed out");
+	});
+});
+
+describe("boundText", () => {
+	it("passes short output through untouched", () => {
+		const bounded = boundText("one\ntwo");
+		expect(bounded).toEqual({ text: "one\ntwo", truncated: false, truncatedBy: null, totalBytes: 7 });
+	});
+
+	it("truncates by lines and says how to see the rest", () => {
+		const bounded = boundText(Array.from({ length: 50 }, (_, i) => `line ${i}`).join("\n"), { maxLines: 10 });
+		expect(bounded.truncated).toBe(true);
+		expect(bounded.truncatedBy).toBe("lines");
+		expect(bounded.text).toContain("line 0");
+		expect(bounded.text).not.toContain("line 20");
+		expect(bounded.text).toContain("[graft] output truncated (10 of 50 lines)");
+	});
+
+	it("truncates by bytes and reports the byte ceiling", () => {
+		const bounded = boundText("x".repeat(500), { maxBytes: 100, maxLines: 100 });
+		expect(bounded.truncated).toBe(true);
+		expect(bounded.truncatedBy).toBe("bytes");
+		expect(bounded.text).toContain("of 500 bytes");
+	});
+});
+
+describe("parseAskJson", () => {
+	const valid = JSON.stringify({
+		query: "auth",
+		mode: "lexical",
+		hits: [
+			{ kind: "symbol", title: "verify · function", pointer: "src/auth.ts:L10-L20", snippet: "checks", score: 3, code: "x" },
+			{ kind: "concept", title: "Auth", pointer: "src/auth.ts", related: ["a"], score: 1 },
+		],
+		coverage: 0.6,
+		coverageStrong: 0.5,
+		saved: { files: 2, baselineChars: 4000 },
+		rules: [{ text: "always verify" }],
+	});
+
+	it("reads the documented hit shape", () => {
+		const payload = parseAskJson(valid);
+		expect(payload?.mode).toBe("lexical");
+		expect(payload?.coverage).toBe(0.6);
+		expect(payload?.saved).toEqual({ files: 2, baselineChars: 4000 });
+		expect(payload?.hits).toHaveLength(2);
+		expect(payload?.hits[0]).toMatchObject({ pointer: "src/auth.ts:L10-L20", code: "x" });
+		expect(payload?.rules).toEqual([{ id: undefined, text: "always verify" }]);
+	});
+
+	it("returns undefined for anything it cannot trust", () => {
+		expect(parseAskJson("not json")).toBeUndefined();
+		expect(parseAskJson("[]")).toBeUndefined();
+		expect(parseAskJson(JSON.stringify({ query: "x" }))).toBeUndefined();
+	});
+
+	it("skips malformed hits instead of failing the whole parse", () => {
+		const payload = parseAskJson(JSON.stringify({ hits: [{ title: "no pointer" }, { pointer: "src/a.ts" }, 7] }));
+		expect(payload?.hits).toHaveLength(1);
+		expect(payload?.hits[0]?.title).toBe("src/a.ts");
+	});
+
+	it("drops a malformed saved block rather than surfacing wrong numbers", () => {
+		expect(parseAskJson(JSON.stringify({ hits: [], saved: { files: "two" } }))?.saved).toBeUndefined();
+	});
+});
+
+describe("parsePointer", () => {
+	it("splits a file:span pointer", () => {
+		expect(parsePointer("src/a.ts:L1-L9")).toEqual({ path: "src/a.ts", span: "L1-L9" });
+		expect(parsePointer("src/a.ts:12")).toEqual({ path: "src/a.ts:12" });
+		expect(parsePointer("src/a.ts")).toEqual({ path: "src/a.ts" });
+	});
+});
+
+describe("renderAsk", () => {
+	it("renders a compact ranked pack with pointers, snippets, source and receipts", () => {
+		const payload = parseAskJson(
+			JSON.stringify({
+				mode: "lexical",
+				note: "ranked by relevance",
+				hits: [
+					{ kind: "symbol", title: "verify · function", pointer: "src/auth.ts:L10-L20", snippet: "checks the token", code: "return true;" },
+					{ kind: "caller", title: "login", pointer: "src/login.ts:L1-L4", snippet: "", relation: "calls" },
+				],
+				saved: { files: 2, baselineChars: 4000 },
+				rules: [{ text: "always verify" }],
+			}),
+		)!;
+		const text = renderAsk(payload);
+		expect(text).toContain("graft ask (lexical) — 2 hit(s)");
+		expect(text).toContain("1. verify · function — src/auth.ts:L10-L20");
+		expect(text).toContain("return true;");
+		expect(text).toContain("2. login (calls) — src/login.ts:L1-L4");
+		expect(text).toContain("governing rules:");
+		expect(text).toContain("reading them instead would cost ~1000 tokens");
+		expect(askReferences(payload)).toEqual([
+			{ path: "src/auth.ts", span: "L10-L20" },
+			{ path: "src/login.ts", span: "L1-L4" },
+		]);
+	});
+
+	it("labels a scoped hit with its sub-project", () => {
+		const payload = parseAskJson(JSON.stringify({ hits: [{ pointer: "src/a.ts", scope: "packages/api" }] }))!;
+		expect(renderAsk(payload)).toContain("packages/api/src/a.ts");
+	});
+});
+
+describe("applyTelemetryDefault", () => {
+	it("sets DO_NOT_TRACK and restores the prior absence on session shutdown", () => {
+		const env: NodeJS.ProcessEnv = {};
+		const handle = applyTelemetryDefault(env);
+		expect(env[TELEMETRY_ENV]).toBe("1");
+		handle.restore();
+		expect(env[TELEMETRY_ENV]).toBeUndefined();
+	});
+
+	it("leaves an explicit user preference alone", () => {
+		const env: NodeJS.ProcessEnv = { [TELEMETRY_ENV]: "0" };
+		const handle = applyTelemetryDefault(env);
+		expect(env[TELEMETRY_ENV]).toBe("0");
+		handle.restore();
+		expect(env[TELEMETRY_ENV]).toBe("0");
+	});
+});
+
+describe("modest defaults", () => {
+	it("keeps the ask limit aligned with the CLI default", () => {
+		expect(DEFAULT_FIND_LIMIT).toBe(8);
+	});
+
+	it("never calls the executable through a shell", async () => {
+		const { pi } = makePi(async () => execReturning(FAILED));
+		await runGraft(pi.exec as never, "/repo", { kind: "find-all", pattern: "a|b" });
+		const [command] = pi.exec.mock.calls[0] as [string];
+		expect(["graft", "cmd"]).toContain(command);
+		expect(vi.isMockFunction(pi.exec)).toBe(true);
+	});
+});