@selesai/code 0.13.22 → 0.13.24

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

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+import type { AskPayload } from "./cli.ts";
+import {
+	buildInjectionPack,
+	classifyTask,
+	createInjectionGuard,
+	describeStrategy,
+	injectionBudget,
+	injectionMessage,
+	MAX_QUERY_CHARS,
+	planInjection,
+	retrievalQuery,
+} from "./prompt.ts";
+import { DEFAULT_MIN_COVERAGE, type GraftState } from "./state.ts";
+
+const FRESH: GraftState = { name: "fresh-structural", version: "0.18.0" };
+
+function payload(overrides: Partial<AskPayload> = {}): AskPayload {
+	return {
+		hits: [
+			{
+				kind: "symbol",
+				title: "verify · function",
+				pointer: "src/auth.ts:L10-L20",
+				snippet: "checks the token",
+				code: "export function verify() {}",
+			},
+		],
+		mode: "lexical",
+		...overrides,
+	};
+}
+
+describe("classifyTask", () => {
+	it("recognizes the repository work that warrants context", () => {
+		const coding = [
+			"Fix the login crash when the token is expired",
+			"Refactor the retry logic in the HTTP client",
+			"Add a migration for the new column",
+			"Review this diff before I merge it",
+			"Why does `parseRequest` throw on empty input?",
+			"Update the build to include the new package",
+			"Write tests for src/core/exec.ts",
+			"Verify the release changes before deployment",
+			"Check implementations of subagent: is it compatible with Graft?",
+			"debug the flaky retryIntervals helper",
+		];
+		for (const prompt of coding) expect(classifyTask(prompt), prompt).toBe("coding");
+	});
+
+	it("leaves conversation, meta questions and commands alone", () => {
+		const other = [
+			"hi",
+			"Thanks!",
+			"what can you do",
+			"/graft doctor",
+			"   ",
+			"Tell me a joke about databases",
+		];
+		for (const prompt of other) expect(classifyTask(prompt), prompt).toBe("other");
+	});
+
+	it("treats an explicit path or identifier as a task even without an action verb", () => {
+		expect(classifyTask("src/extensions/pi-graft/index.ts")).toBe("coding");
+		expect(classifyTask("What does buildGraphIfMissing return?")).toBe("coding");
+	});
+});
+
+describe("retrievalQuery", () => {
+	it("strips fenced code so a pasted snippet does not become the query", () => {
+		expect(retrievalQuery("Fix this\n```ts\nconst a = 1;\n```\nplease")).toBe("Fix this please");
+	});
+
+	it("collapses whitespace and bounds the length", () => {
+		expect(retrievalQuery("  a\n\n  b  ")).toBe("a b");
+		const long = retrievalQuery("word ".repeat(1000));
+		expect(long.length).toBe(MAX_QUERY_CHARS + 1);
+		expect(long.endsWith("…")).toBe(true);
+	});
+});
+
+describe("planInjection", () => {
+	const eligible = { mode: "push" as const, prompt: "Fix the login crash", state: FRESH, enabled: true };
+
+	it("injects nothing in pull mode, whatever the prompt", () => {
+		const plan = planInjection({ ...eligible, mode: "pull" });
+		expect(plan.inject).toBe(false);
+		expect(plan.reason).toContain("pull");
+	});
+
+	it("injects one bounded pack for an eligible repository task", () => {
+		expect(planInjection(eligible)).toEqual({
+			inject: true,
+			mode: "push",
+			query: "Fix the login crash",
+			reason: "eligible repository task",
+		});
+	});
+
+	it("skips prompts that are not repository work, so no latency is paid for chat", () => {
+		expect(planInjection({ ...eligible, prompt: "hey there" }).inject).toBe(false);
+		expect(planInjection({ ...eligible, prompt: "  " }).inject).toBe(false);
+	});
+
+	it("skips turns where Graft cannot answer", () => {
+		for (const state of [{ name: "unbuilt" }, { name: "unavailable" }, { name: "unsupported" }] as GraftState[]) {
+			const plan = planInjection({ ...eligible, state });
+			expect(plan.inject, state.name).toBe(false);
+			expect(plan.reason).toContain(state.name);
+		}
+	});
+
+	it("still injects for a graph marked changed, because Graft refreshes on query", () => {
+		expect(planInjection({ ...eligible, state: { name: "changed" } }).inject).toBe(true);
+	});
+
+	it("injects nothing when the extension is disabled", () => {
+		expect(planInjection({ ...eligible, enabled: false }).inject).toBe(false);
+	});
+});
+
+describe("injectionBudget", () => {
+	it("lets push spend the configured budget and keeps hybrid to a small orientation pack", () => {
+		expect(injectionBudget("push", 12_000)).toEqual({ limit: 8, maxBytes: 12_000 });
+		expect(injectionBudget("hybrid", 12_000)).toEqual({ limit: 3, maxBytes: 6 * 1024 });
+		expect(injectionBudget("hybrid", 2_000)).toEqual({ limit: 3, maxBytes: 2_000 });
+	});
+});
+
+describe("buildInjectionPack", () => {
+	it("refuses an empty result rather than injecting an empty block", () => {
+		expect(buildInjectionPack(payload({ hits: [] }), { maxBytes: 4096 })).toBeUndefined();
+	});
+
+	it("refuses a pack whose terms barely overlap the graph", () => {
+		expect(buildInjectionPack(payload({ coverage: 0.05 }), { maxBytes: 4096 })).toBeUndefined();
+		expect(buildInjectionPack(payload({ coverage: DEFAULT_MIN_COVERAGE }), { maxBytes: 4096 })).toBeDefined();
+	});
+
+	it("accepts a pack when the CLI reported no coverage at all", () => {
+		expect(buildInjectionPack(payload(), { maxBytes: 4096 })).toBeDefined();
+	});
+
+	it("bounds the pack and records its references and truncation", () => {
+		const pack = buildInjectionPack(
+			payload({
+				hits: [
+					{
+						kind: "symbol",
+						title: "big",
+						pointer: "src/big.ts:L1-L2",
+						snippet: "",
+						code: "x".repeat(100_000),
+					},
+				],
+				coverage: 0.9,
+			}),
+			{ maxBytes: 2_000, minCoverage: 0.25 },
+		)!;
+		expect(pack.truncated).toBe(true);
+		expect(pack.bytes).toBeLessThanOrEqual(2_000 + 200);
+		expect(pack.references).toEqual([{ path: "src/big.ts", span: "L1-L2" }]);
+		expect(pack.coverage).toBe(0.9);
+	});
+});
+
+describe("injectionMessage", () => {
+	it("declares its source, its mode, the graph quality, and that source files win", () => {
+		const pack = buildInjectionPack(payload({ coverage: 0.9 }), { maxBytes: 4096 })!;
+		const message = injectionMessage({ pack, mode: "hybrid", state: "fresh-structural" });
+		expect(message).toContain('<graft-context source="graft" mode="hybrid" graph="fresh-structural" references="1">');
+		expect(message).toContain("derived summary");
+		expect(message).toContain("authoritative");
+		expect(message).toContain("src/auth.ts:L10-L20");
+		expect(message).toContain("</graft-context>");
+	});
+
+	it("says a deep graph is deep, so the reader knows the provenance", () => {
+		const pack = buildInjectionPack(payload(), { maxBytes: 4096 })!;
+		expect(injectionMessage({ pack, mode: "push", state: "fresh-deep" })).toContain('graph="fresh-deep"');
+	});
+});
+
+describe("createInjectionGuard", () => {
+	it("injects at most once per turn even if the hook runs again", () => {
+		const guard = createInjectionGuard();
+		expect(guard.shouldInject()).toBe(true);
+		guard.markInjected();
+		expect(guard.shouldInject()).toBe(false);
+		guard.markInjected();
+		expect(guard.shouldInject()).toBe(false);
+	});
+
+	it("allows a new injection once the next turn begins", () => {
+		const guard = createInjectionGuard();
+		guard.markInjected();
+		guard.beginTurn();
+		expect(guard.shouldInject()).toBe(true);
+	});
+});
+
+describe("describeStrategy", () => {
+	it("explains each mode in the user's terms", () => {
+		expect(describeStrategy("pull")).toContain("nothing is injected");
+		expect(describeStrategy("push")).toContain("source-backed");
+		expect(describeStrategy("hybrid")).toContain("orientation");
+	});
+
+	it("never claims injection happens in pull mode", () => {
+		expect(describeStrategy("pull")).not.toContain("starts from");
+		expect(describeStrategy("push")).not.toContain("nothing is injected");
+	});
+});

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

@@ -0,0 +1,216 @@
+/**
+ * Retrieval strategy: when Graft context reaches the model, and how much.
+ *
+ * Three genuinely different behaviors, not one behavior with a flag:
+ *
+ * - `pull`   — inject nothing. The model calls the Graft tools when it wants
+ *              repository context.
+ * - `push`   — before an eligible coding turn, inject a bounded source-backed
+ *              pack so the turn can start from repository understanding. Default.
+ * - `hybrid` — inject a small orientation pack for eligible coding turns and
+ *              keep the precise tools for follow-up.
+ *
+ * Injection happens through the turn lifecycle as a custom message. User text
+ * is never rewritten, and the injected block says it is derived and that the
+ * source files remain authoritative.
+ */
+
+import type { AskPayload, GraftReference } from "./cli.ts";
+import {
+	askReferences,
+	boundText,
+	renderAsk,
+	DEFAULT_FIND_LIMIT,
+} from "./cli.ts";
+import {
+	DEFAULT_MAX_INJECTION_BYTES,
+	DEFAULT_MIN_COVERAGE,
+	type GraftState,
+	type GraftStateName,
+	isQueryable,
+	type RetrievalMode,
+} from "./state.ts";
+
+/** Longest prompt text handed to Graft as a retrieval query. */
+export const MAX_QUERY_CHARS = 600;
+
+/**
+ * Intent words that mean "this turn touches the repository". Kept deliberately
+ * concrete: a false positive costs a wasted Graft query and prompt noise, so
+ * the list is about *acting on code*, not about mentioning it.
+ */
+const CODING_INTENT =
+	/\b(add|implement(?:ation)?s?|fix|bug|debug|refactor|rename|migrate|port|upgrade|remove|delete|replace|extract|move|rewrite|optimize|optimi[sz]e|revert|patch|wire|hook up|support|handle|test|spec|regression|verif(?:y|ication)|validat(?:e|ion)|crash|error|exception|stack ?trace|type ?error|lint|compile|build failure|review|diff|pull request|\bpr\b|commit|branch|merge|conflict|api|schema|migration|endpoint|component|function|class|method|module|package|dependency|config|performance|memory leak|deadlock|race)\b/i;
+
+/** A path, an identifier, or an explicitly quoted symbol is a strong signal on its own. */
+const CODE_SHAPE = /(`[^`]+`|\b[\w.-]+\.(ts|tsx|js|jsx|py|go|java|kt|php|swift|rs|c|cc|cpp|cs|rb|scala|ex|sol|ml|zig|dart|clj|nix|lua|R)\b|\b[a-z]+[A-Z][A-Za-z0-9]*\b|\b[A-Z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*\b|\b[\w-]+\/[\w./-]+\.\w+\b)/;
+
+/** Prompts that are conversational or meta never warrant repository context. */
+const NON_CODING =
+	/^(hi|hey|hello|thanks|thank you|ok|okay|cool|nice|great|yes|no|stop|never mind|nevermind|what (do you think|can you do)|who are you)\b[\s!.?]*$/i;
+
+export type TaskClass = "coding" | "other";
+
+/**
+ * Classify a user prompt as a repository task or not.
+ *
+ * `ponytail:` a lexical heuristic, not a model call — it exists so non-coding
+ * turns pay no Graft latency at all. It has a known ceiling: an indirect
+ * request ("the login flow feels slow") classifies as `other` and simply
+ * falls back to `pull` behavior. Upgrade path is a provider-backed classifier
+ * once the cheap gate measurably costs us turns.
+ */
+export function classifyTask(prompt: string): TaskClass {
+	const text = prompt.trim();
+	if (!text) return "other";
+	if (NON_CODING.test(text)) return "other";
+	if (text.startsWith("/")) return "other";
+	if (CODING_INTENT.test(text) || CODE_SHAPE.test(text)) return "coding";
+	return "other";
+}
+
+/** Collapse a prompt into a bounded plain-text retrieval query. */
+export function retrievalQuery(prompt: string): string {
+	const text = prompt
+		.replace(/```[\s\S]*?```/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	return text.length > MAX_QUERY_CHARS ? `${text.slice(0, MAX_QUERY_CHARS)}…` : text;
+}
+
+export interface InjectionPlan {
+	inject: boolean;
+	mode: RetrievalMode;
+	query: string;
+	/** Why nothing was injected; used by tests and by `/graft doctor`. */
+	reason: string;
+}
+
+/**
+ * Decide whether this turn gets an injected pack.
+ *
+ * Pure: the caller supplies the mode, the prompt, and the current graph state.
+ */
+export function planInjection(input: {
+	mode: RetrievalMode;
+	prompt: string;
+	state: GraftState;
+	enabled: boolean;
+}): InjectionPlan {
+	const base = { mode: input.mode, query: "" } as const;
+	if (!input.enabled) return { ...base, inject: false, reason: "extension disabled by settings" };
+	if (input.mode === "pull") return { ...base, inject: false, reason: "pull mode: the model retrieves on demand" };
+	if (!isQueryable(input.state)) {
+		return { ...base, inject: false, reason: `no usable graph (${input.state.name})` };
+	}
+	const query = retrievalQuery(input.prompt);
+	if (!query) return { ...base, inject: false, reason: "empty prompt" };
+	if (classifyTask(query) !== "coding") {
+		return { ...base, inject: false, reason: "prompt does not look like a repository task" };
+	}
+	return { inject: true, mode: input.mode, query, reason: "eligible repository task" };
+}
+
+/** Per-mode shape of the injected pack. Push spends more; hybrid orients. */
+export function injectionBudget(mode: RetrievalMode, maxInjectionBytes: number): { limit: number; maxBytes: number } {
+	if (mode === "push") return { limit: DEFAULT_FIND_LIMIT, maxBytes: maxInjectionBytes };
+	return { limit: 3, maxBytes: Math.min(maxInjectionBytes, 6 * 1024) };
+}
+
+export interface InjectionPack {
+	text: string;
+	references: GraftReference[];
+	bytes: number;
+	truncated: boolean;
+	coverage?: number;
+}
+
+/**
+ * Turn an `ask` payload into a bounded pack, or refuse it.
+ *
+ * Refusal is the important half: an unprompted pack whose terms barely overlap
+ * the graph is noise that the model then has to reason around. Graft reports
+ * `coverage` for exactly this gate, so a low-coverage result is dropped rather
+ * than injected.
+ */
+export function buildInjectionPack(
+	payload: AskPayload,
+	budget: { maxBytes: number; minCoverage?: number },
+): InjectionPack | undefined {
+	if (payload.hits.length === 0) return undefined;
+	const minCoverage = budget.minCoverage ?? DEFAULT_MIN_COVERAGE;
+	if (typeof payload.coverage === "number" && payload.coverage < minCoverage) return undefined;
+
+	const bounded = boundText(renderAsk(payload), { maxBytes: budget.maxBytes, maxLines: 300 });
+	if (!bounded.text.trim()) return undefined;
+	return {
+		text: bounded.text,
+		references: askReferences(payload),
+		bytes: Buffer.byteLength(bounded.text, "utf-8"),
+		truncated: bounded.truncated,
+		coverage: payload.coverage,
+	};
+}
+
+/**
+ * The injected message body.
+ *
+ * Three properties are load-bearing, so they are stated in the text itself:
+ * where it came from, that it is derived rather than authoritative, and that
+ * the model should verify before editing.
+ */
+export function injectionMessage(input: {
+	pack: InjectionPack;
+	mode: RetrievalMode;
+	state: GraftStateName;
+}): string {
+	const { pack, mode, state } = input;
+	const header =
+		`<graft-context source="graft" mode="${mode}" graph="${state}" references="${pack.references.length}">`;
+	return [
+		header,
+		"Repository context prepared by the Graft code-context extension before this turn.",
+		"It is a derived summary of the working tree, not the source of truth: files in the",
+		"repository are authoritative, so read them before changing anything, and treat a",
+		"reachability claim here as a lead rather than proof.",
+		"",
+		pack.text,
+		"</graft-context>",
+	].join("\n");
+}
+
+/**
+ * At-most-once injection per turn.
+ *
+ * `before_agent_start` runs once per user prompt, but a retried or replayed run
+ * can reach it again, and a reload re-registers handlers. The guard makes the
+ * seam idempotent regardless of how many times the hook fires.
+ */
+export function createInjectionGuard(): {
+	shouldInject(): boolean;
+	markInjected(): void;
+	beginTurn(): void;
+} {
+	let injected = false;
+	return {
+		shouldInject: () => !injected,
+		markInjected: () => {
+			injected = true;
+		},
+		beginTurn: () => {
+			injected = false;
+		},
+	};
+}
+
+/** One-line explanation of the current retrieval strategy, for `/graft status`. */
+export function describeStrategy(mode: RetrievalMode): string {
+	switch (mode) {
+		case "pull":
+			return "pull — the model calls Graft tools when it needs repository context (nothing is injected).";
+		case "push":
+			return "push — an eligible repository task starts from a bounded source-backed Graft pack.";
+		case "hybrid":
+			return "hybrid — an eligible repository task starts from a small orientation pack; tools stay available.";
+	}
+}

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

@@ -0,0 +1,258 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { SessionEntry } from "@selesai/code";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+	ABSENT_GRAPH,
+	DEFAULT_MIN_COVERAGE,
+	DEFAULT_RETRIEVAL_MODE,
+	INITIAL_GRAFT_STATE,
+	MODE_ENTRY_TYPE,
+	readBranchMode,
+	readGraftSettings,
+	recoveryFor,
+	reduceGraftState,
+	statusDetail,
+	statusText,
+	isQueryable,
+	isRetrievalMode,
+	isSetupProblem,
+	type GraftState,
+} from "./state.ts";
+
+const UNBUILT: GraftState = { name: "unbuilt", detail: "no graph yet" };
+const FRESH: GraftState = { name: "fresh-structural", version: "0.18.0", deep: false };
+const DEEP: GraftState = { name: "fresh-deep", version: "0.18.0", deep: true };
+
+describe("reduceGraftState", () => {
+	it("only claims a repository once root resolution says there is a Git working tree", () => {
+		const notGit = reduceGraftState(INITIAL_GRAFT_STATE, { type: "resolved", gitRepo: false });
+		expect(notGit.name).toBe("unsupported");
+		expect(notGit.detail).toContain("Git");
+
+		const git = reduceGraftState(INITIAL_GRAFT_STATE, { type: "resolved", gitRepo: true });
+		expect(git.name).toBe("unavailable");
+	});
+
+	it("derives built/fresh/deep from what is actually on disk", () => {
+		expect(reduceGraftState(gitState(), { type: "probe-ok", version: "0.18.0", graph: ABSENT_GRAPH })).toEqual({
+			name: "unbuilt",
+			version: "0.18.0",
+			detail: expect.stringContaining("/graft build"),
+		});
+		expect(
+			reduceGraftState(gitState(), { type: "probe-ok", version: "0.18.0", graph: { built: true, deep: false } }),
+		).toEqual(FRESH);
+		expect(
+			reduceGraftState(gitState(), { type: "probe-ok", version: "0.18.0", graph: { built: true, deep: true } }),
+		).toMatchObject({ name: "fresh-deep", deep: true });
+	});
+
+	it("records why the executable is unusable", () => {
+		const missing = reduceGraftState(gitState(), { type: "probe-missing", detail: "spawn graft ENOENT" });
+		expect(missing).toMatchObject({ name: "unavailable", detail: "spawn graft ENOENT" });
+
+		const old = reduceGraftState(gitState(), {
+			type: "probe-incompatible",
+			version: "0.4.0",
+			detail: "too old",
+		});
+		expect(old).toMatchObject({ name: "incompatible", version: "0.4.0" });
+	});
+
+	it("marks a graph stale only when there is a graph to go stale", () => {
+		expect(reduceGraftState(FRESH, { type: "mutation-observed" }).name).toBe("changed");
+		expect(reduceGraftState(DEEP, { type: "mutation-observed" }).name).toBe("changed");
+		expect(reduceGraftState(UNBUILT, { type: "mutation-observed" }).name).toBe("unbuilt");
+		expect(reduceGraftState({ name: "failed" }, { type: "mutation-observed" }).name).toBe("failed");
+	});
+
+	it("returns to fresh after a query, because Graft refreshes before answering", () => {
+		const changed = reduceGraftState(FRESH, { type: "mutation-observed" });
+		expect(changed.name).toBe("changed");
+		expect(reduceGraftState(changed, { type: "query-succeeded", presence: { built: true, deep: false } })).toEqual(
+			FRESH,
+		);
+		expect(reduceGraftState(changed, { type: "query-succeeded", presence: { built: true, deep: true } })).toMatchObject(
+			{ name: "fresh-deep" },
+		);
+	});
+
+	it("keeps a failed build distinct from an unbuilt repository", () => {
+		const failed = reduceGraftState(UNBUILT, { type: "build-failed", detail: "exit 1" });
+		expect(failed).toMatchObject({ name: "failed", detail: "exit 1" });
+		expect(reduceGraftState({ name: "building", deep: true }, { type: "build-succeeded", deep: true, presence: { built: true, deep: true } })).toMatchObject({
+			name: "fresh-deep",
+		});
+	});
+
+	it("announces the build phase so the status line can show work in progress", () => {
+		expect(reduceGraftState(FRESH, { type: "build-started", deep: true })).toMatchObject({
+			name: "building",
+			deep: true,
+			version: "0.18.0",
+		});
+	});
+
+	it("only shows a refresh phase for a graph that was actually stale", () => {
+		const changed = reduceGraftState(FRESH, { type: "mutation-observed" });
+		expect(reduceGraftState(changed, { type: "refresh-started" }).name).toBe("refreshing");
+		expect(reduceGraftState(FRESH, { type: "refresh-started" }).name).toBe("fresh-structural");
+	});
+
+	it("resets to the initial state", () => {
+		expect(reduceGraftState(FRESH, { type: "reset" })).toEqual(INITIAL_GRAFT_STATE);
+	});
+});
+
+function gitState(): GraftState {
+	return reduceGraftState(INITIAL_GRAFT_STATE, { type: "resolved", gitRepo: true });
+}
+
+/** A session entry with the fields `readBranchMode` reads, and the base fields above them. */
+function customEntry(customType: string, data: unknown): SessionEntry {
+	return {
+		type: "custom",
+		id: `entry-${customType}-${String((data as { mode?: string } | undefined)?.mode ?? "none")}`,
+		parentId: null,
+		timestamp: new Date(0).toISOString(),
+		customType,
+		data,
+	} as SessionEntry;
+}
+
+describe("state predicates and rendering", () => {
+	it("distinguishes states a query can answer from states it cannot", () => {
+		expect(isQueryable(FRESH)).toBe(true);
+		expect(isQueryable(DEEP)).toBe(true);
+		expect(isQueryable({ name: "changed" })).toBe(true);
+		expect(isQueryable(UNBUILT)).toBe(false);
+		expect(isQueryable({ name: "unavailable" })).toBe(false);
+		expect(isQueryable({ name: "incompatible" })).toBe(false);
+		expect(isQueryable({ name: "unsupported" })).toBe(false);
+	});
+
+	it("separates setup problems from runtime failures", () => {
+		expect(isSetupProblem({ name: "unavailable" })).toBe(true);
+		expect(isSetupProblem({ name: "incompatible" })).toBe(true);
+		expect(isSetupProblem({ name: "failed" })).toBe(false);
+	});
+
+	it("renders a compact status line with the version when it is known", () => {
+		expect(statusText(FRESH)).toBe("graft: ● structural v0.18.0");
+		expect(statusText(DEEP)).toBe("graft: ● deep v0.18.0");
+		expect(statusText({ name: "unavailable" })).toBe("graft: ✕ no cli");
+		expect(statusText({ name: "changed" })).toBe("graft: ◐ changed");
+	});
+
+	it("gives every broken state an actionable recovery step and healthy states none", () => {
+		expect(recoveryFor({ name: "unavailable" })).toContain("/graft setup");
+		expect(recoveryFor({ name: "incompatible" })).toContain("npm install -g @nanonets/graft");
+		expect(recoveryFor({ name: "unbuilt" })).toContain("/graft build");
+		expect(recoveryFor({ name: "unsupported" })).toContain("git init");
+		expect(recoveryFor({ name: "failed" })).toContain("/graft doctor");
+		expect(recoveryFor(FRESH)).toBeUndefined();
+	});
+
+	it("falls back to the state label when there is no detail", () => {
+		expect(statusDetail({ name: "changed" })).toBe("◐ changed");
+		expect(statusDetail({ name: "unbuilt", detail: "custom" })).toBe("custom");
+	});
+});
+
+describe("retrieval mode", () => {
+	it("accepts only the three documented strategies", () => {
+		expect(isRetrievalMode("pull")).toBe(true);
+		expect(isRetrievalMode("push")).toBe(true);
+		expect(isRetrievalMode("hybrid")).toBe(true);
+		expect(isRetrievalMode("auto")).toBe(false);
+		expect(isRetrievalMode(undefined)).toBe(false);
+	});
+
+	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", () => {
+		const branch = [
+			customEntry(MODE_ENTRY_TYPE, { mode: "hybrid" }),
+			customEntry("graft-injection", { mode: "push" }),
+			customEntry(MODE_ENTRY_TYPE, { mode: "push" }),
+		];
+		expect(readBranchMode(branch)).toBe("push");
+		expect(readBranchMode([])).toBeUndefined();
+		expect(readBranchMode([customEntry(MODE_ENTRY_TYPE, { mode: "auto" })])).toBeUndefined();
+		expect(readBranchMode([customEntry(MODE_ENTRY_TYPE, undefined)])).toBeUndefined();
+		expect(readBranchMode([customEntry("other", { mode: "push" })])).toBeUndefined();
+		expect(readBranchMode([{ type: "message" } as never])).toBeUndefined();
+	});
+});
+
+describe("readGraftSettings", () => {
+	let root: string;
+	let agentDir: string;
+	let projectDir: string;
+
+	beforeAll(() => {
+		root = mkdtempSync(join(tmpdir(), "graft-settings-"));
+		agentDir = join(root, "agent");
+		projectDir = join(root, "project");
+		mkdirSync(agentDir, { recursive: true });
+		mkdirSync(join(projectDir, ".selesai"), { recursive: true });
+	});
+
+	afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+	const write = (path: string, value: unknown) => writeFileSync(path, JSON.stringify(value), "utf-8");
+	const read = (trusted: boolean, cwd = projectDir) => readGraftSettings({ cwd, trusted, agentDir });
+
+	it("returns defaults when no settings file exists", () => {
+		expect(read(false, join(root, "nowhere"))).toEqual({});
+		expect(read(true, join(root, "nowhere"))).toEqual({});
+	});
+
+	it("ignores a malformed settings file instead of breaking a session", () => {
+		const brokenDir = join(root, "broken");
+		mkdirSync(join(brokenDir, ".selesai"), { recursive: true });
+		writeFileSync(join(brokenDir, ".selesai", "settings.json"), "{ not json", "utf-8");
+		expect(read(true, brokenDir)).toEqual({});
+	});
+
+	it("reads the global graft section", () => {
+		write(join(agentDir, "settings.json"), { graft: { mode: "hybrid", minCoverage: 0.4, in: " packages/api " } });
+		expect(read(false)).toEqual({ mode: "hybrid", minCoverage: 0.4, in: "packages/api" });
+	});
+
+	it("ignores project settings until the project is trusted", () => {
+		write(join(projectDir, ".selesai", "settings.json"), { graft: { mode: "push" } });
+		expect(read(false).mode).toBe("hybrid");
+		expect(read(true).mode).toBe("push");
+	});
+
+	it("drops values that are not the documented shape", () => {
+		write(join(agentDir, "settings.json"), {
+			graft: {
+				enabled: "yes",
+				mode: "auto",
+				telemetry: "maybe",
+				minCoverage: 1.5,
+				maxInjectionBytes: -1,
+				maxResultBytes: 0,
+				refreshDebounceSeconds: "60",
+				in: "   ",
+			},
+		});
+		expect(read(false)).toEqual({});
+	});
+
+	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" });
+	});
+
+	it("defaults the injection gate to a value a real pack can clear", () => {
+		expect(DEFAULT_MIN_COVERAGE).toBeGreaterThan(0);
+		expect(DEFAULT_MIN_COVERAGE).toBeLessThan(1);
+	});
+});