gentle-pi 4.1.0 → 4.2.0

package/lib/destructive-command-guard.ts

@@ -15,14 +15,18 @@ interface Token {
 }
 const separators = new Set([";", "&&", "||", "|", "&", "\n", "(", ")"]);
 
-/** Keep quoted arguments intact so harmless prose is never treated as a command. */
-function tokenize(command: string): Token[] {
-	const tokens: Token[] = [];
-	// Literal, named heredocs are data, not executable shell segments.
-	command = command.replace(/<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g, (raw) => {
+/** Literal, named heredocs are data, not executable shell segments; offsets are preserved. */
+function blankHeredocs(command: string): string {
+	return command.replace(/<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g, (raw) => {
 		const headerLength = raw.indexOf("\n") + 1;
 		return raw.slice(0, headerLength) + " ".repeat(raw.length - headerLength);
 	});
+}
+
+/** Keep quoted arguments intact so harmless prose is never treated as a command. */
+function tokenize(command: string, blank = true): Token[] {
+	const tokens: Token[] = [];
+	if (blank) command = blankHeredocs(command);
 	const pattern = /(?:"(?:\\.|[^"\\])*"|'[^']*'|\\.|[^\s;&|()'"\\])+|&&|\|\||[;&|()\n]/g;
 	for (const match of command.matchAll(pattern)) {
 		const raw = match[0];
@@ -38,6 +42,100 @@ function tokenize(command: string): Token[] {
 }
 const executable = (value: string) => value.split("/").at(-1) ?? value;
 
+const WRAPPER_VALUE_OPTIONS: Record<string, readonly string[]> = {
+	env: ["-u", "--unset", "-C", "--chdir"],
+	sudo: ["-u", "-g", "-h", "-p", "-C", "--user", "--group", "--host", "--prompt", "--chdir"],
+	timeout: ["-s", "--signal", "-k", "--kill-after"],
+	xargs: ["-n", "-I", "-P", "--max-args", "--replace", "--max-procs"],
+};
+const WRAPPERS = ["env", "sudo", "command", "exec", "nohup", "timeout", "xargs"];
+
+/** Index of the executable token after assignments and familiar wrappers. */
+function headCursor(segment: readonly Token[]): number {
+	let cursor = 0;
+	while (cursor < segment.length) {
+		const value = segment[cursor].value;
+		if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(value)) {
+			cursor++;
+			continue;
+		}
+		const name = executable(value);
+		if (!WRAPPERS.includes(name)) break;
+		cursor++;
+		while (cursor < segment.length && segment[cursor].value.startsWith("-")) {
+			const flag = segment[cursor++].value;
+			if (flag === "--") break;
+			if (WRAPPER_VALUE_OPTIONS[name]?.includes(flag)) cursor++;
+		}
+		if (name === "timeout") cursor++;
+	}
+	return cursor;
+}
+
+// gentle-shell#2174: commands whose arguments are searched, printed or viewed
+// text, never executed and never fed to an executor. `sed` is absent on
+// purpose: GNU sed executes scripts through `e` with any delimiter or address.
+// The exemption applies only when EVERY segment head is in DATA_COMMANDS or
+// INERT_COMMANDS, so an unknown consumer (`| at now`, `&& ./x.sh`) keeps the
+// lexical guard: a missing entry costs a dialog, never a bypass.
+const DATA_COMMANDS = new Set([
+	"grep", "egrep", "fgrep", "rg", "ag", "ack", "echo", "printf", "cat", "head", "tail", "less", "more",
+	"wc", "sort", "uniq", "cut", "tr", "jq", "diff", "ls", "file", "stat",
+]);
+const INERT_COMMANDS = new Set(["cd", "pwd", "true", "false", "test", "[", "mkdir", "touch"]);
+const HEREDOC_RE = /<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g;
+
+/**
+ * Byte ranges of the command that are plain arguments of a known data command
+ * (gentle-shell#2174). A guarded or denied pattern matching only inside these
+ * ranges is prose, not an operation. Returns no ranges, keeping every lexical
+ * match, when the command is opaque: command or process substitution, an
+ * interpreter or remote shell anywhere, or quoting the tokenizer cannot
+ * account for.
+ */
+export function dataArgumentRanges(command: string): Array<readonly [number, number]> {
+	if (/\$\(|`|[<>]\(/.test(command)) return [];
+	// A heredoc counts only when its `<<` starts an unquoted token of the raw
+	// command; quoted text such as `echo '<<x'` must not blank following lines.
+	const rawStarts = new Set(tokenize(command, false).filter((token) => token.raw.startsWith("<<")).map((token) => token.index));
+	const heredocs = [...command.matchAll(HEREDOC_RE)];
+	if (heredocs.some((heredoc) => !rawStarts.has(heredoc.index))) return [];
+	const blanked = blankHeredocs(command);
+	const tokens = tokenize(command);
+	const covered = new Uint8Array(blanked.length);
+	for (const token of tokens) covered.fill(1, token.index, token.index + token.raw.length);
+	for (let index = 0; index < blanked.length; index++) {
+		if (!covered[index] && !/\s/.test(blanked[index])) return [];
+	}
+	const ranges: Array<readonly [number, number]> = [];
+	let start = 0;
+	for (let end = 0; end <= tokens.length; end++) {
+		if (end < tokens.length && !tokens[end].operator) continue;
+		const segment = tokens.slice(start, end);
+		start = end + 1;
+		if (segment.length === 0) continue;
+		// Only plain assignments, optionally after a flagless `env`, may precede
+		// the head; every other wrapper or wrapper flag can change what runs.
+		let cursor = 0;
+		if (segment[0].value === "env") cursor++;
+		while (cursor < segment.length && /^[A-Za-z_][A-Za-z_0-9]*=/.test(segment[cursor].value)) cursor++;
+		const head = segment[cursor];
+		if (head === undefined || head.value !== head.raw) return [];
+		const name = head.value;
+		if (INERT_COMMANDS.has(name)) continue;
+		if (!DATA_COMMANDS.has(name)) return [];
+		ranges.push([head.index + head.raw.length, tokens[end]?.index ?? command.length]);
+	}
+	// A heredoc body belongs to the segment of its `<<` header, which the
+	// header's trailing newline would otherwise split off. Only the body is
+	// covered: the rest of the header line can hold further commands.
+	for (const heredoc of heredocs) {
+		const bodyStart = heredoc.index + heredoc[0].indexOf("\n") + 1;
+		if (ranges.some(([from, to]) => heredoc.index >= from && heredoc.index < to)) ranges.push([bodyStart, heredoc.index + heredoc[0].length]);
+	}
+	return ranges;
+}
+
 function sqlDestroys(sql: string): boolean {
 	// Mask quoted identifiers as non-keyword atoms, and remove comments and
 	// strings. A table named "where" is not a predicate or a statement boundary.
@@ -60,30 +158,8 @@ export function recognizeDestructiveCommands(command: string, depth = 0): Destru
 	for (let end = 0; end <= tokens.length; end++) {
 		if (end < tokens.length && !tokens[end].operator) continue;
 		const segment = tokens.slice(start, end);
-		let cursor = 0;
 		// Assignments and familiar executable wrappers preserve command position.
-		while (cursor < segment.length) {
-			const value = segment[cursor].value;
-			if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(value)) {
-				cursor++;
-				continue;
-			}
-			const name = executable(value);
-			if (!["env", "sudo", "command", "exec", "nohup", "timeout", "xargs"].includes(name)) break;
-			const valueOptions: Record<string, readonly string[]> = {
-				env: ["-u", "--unset", "-C", "--chdir"],
-				sudo: ["-u", "-g", "-h", "-p", "-C", "--user", "--group", "--host", "--prompt", "--chdir"],
-				timeout: ["-s", "--signal", "-k", "--kill-after"],
-				xargs: ["-n", "-I", "-P", "--max-args", "--replace", "--max-procs"],
-			};
-			cursor++;
-			while (cursor < segment.length && segment[cursor].value.startsWith("-")) {
-				const flag = segment[cursor++].value;
-				if (flag === "--") break;
-				if (valueOptions[name]?.includes(flag)) cursor++;
-			}
-			if (name === "timeout") cursor++;
-		}
+		const cursor = headCursor(segment);
 		const head = segment[cursor];
 		const name = executable(head?.value ?? "");
 		const args = segment.slice(cursor + 1).map((token) => token.value);

package/lib/gentle-shell-bundled.ts

@@ -213,10 +213,26 @@ export function bundledPi(install: BundledInstall, input: { platform: string; fs
 // memory is allowed locally; otherwise the Shell-owned guard, so no provider,
 // whatever loaded it, runs an Engram binary against an unverified store.
 export const ENGRAM_COMPANION_SOURCE = "npm:gentle-engram@0.4.2";
-export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: the existing Engram data's compatibility is unknown. Back up your existing Engram data, update Engram and restart its server, then restart Shell to recheck memory safety (it rechecks on every launch). Shell remains usable without memory.";
+export const ENGRAM_RECOVERY_NOTICE = "Engram memory disabled: Shell could not verify safe store or server reuse. Matching versions or updating alone do not prove compatibility. Reuse requires a server with verified /compatibility evidence or matching Shell-provisioned store identity. Back up existing Engram data before manual changes; do not delete it or bypass the safety check. Shell rechecks on every launch and remains usable without memory.";
 // `gentle-shell setup` publishes the verified core (ensureEngram) on every run.
 export const ENGRAM_PROVISION_FAILED_NOTICE = "Engram memory disabled for this launch: Shell could not provision a new Engram store identity, so it cannot vouch for that store. Restart Shell to retry. If Shell keeps reporting unknown compatibility and ~/.engram holds only .instance-id files, back it up and remove it, then restart Shell. Shell remains usable without memory.";
 export const ENGRAM_CORE_MISSING_NOTICE = "Engram memory disabled: the bundled Engram core is not installed yet. Run 'gentle-shell setup' to install the verified core, then restart Shell. Shell remains usable without memory.";
+// The first Engram release whose server answers GET /compatibility (PR #1792).
+export const ENGRAM_COMPATIBILITY_MIN_VERSION = "3.4.0";
+export function engramOutdatedServerNotice(version: string): string {
+	return `Engram memory disabled: the running Engram server reports version ${version}, which cannot prove store compatibility. Back up your Engram data, update that server to ${ENGRAM_COMPATIBILITY_MIN_VERSION} or later with the method you installed it with, and restart it; updating Shell alone does not replace a running server. Shell rechecks on every launch and remains usable without memory.`;
+}
+// A canonical numeric x.y.z (optionally v-prefixed, no leading zeros) older than
+// the minimum. The version comes from the server, so anything else is never
+// echoed to the user.
+function outdatedServerVersion(version: string | undefined): string | undefined {
+	const match = /^v?(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,3})$/.exec(version ?? "");
+	if (match === null) return undefined;
+	const parts = match.slice(1).map(Number);
+	const minimum = ENGRAM_COMPATIBILITY_MIN_VERSION.split(".").map(Number);
+	const index = parts.findIndex((part, i) => part !== minimum[i]);
+	return index >= 0 && parts[index] < minimum[index] ? parts.join(".") : undefined;
+}
 // The default endpoint gentle-engram uses without ENGRAM_URL or ENGRAM_PORT.
 export const ENGRAM_DEFAULT_PORT = 7437;
 export const ENGRAM_DEFAULT_URL = `http://127.0.0.1:${ENGRAM_DEFAULT_PORT}`;
@@ -238,11 +254,13 @@ export function engramProbeAllowed(env: Env): boolean {
 // Evidence only: never run an executable, open SQLite or infer compatibility
 // from versions. `provenance` means Shell's own record matched the store
 // (directory, .instance-id, core digest) and its header showed no newer schema.
+// A server version only selects the wording of a disabled decision.
 export function classifyEngramStartup(input: { env: Env; store: "absent" | "present" | "unknown"; endpoint: EngramProbe; core: boolean;
 	coreVersion: string; provenance?: { instanceId: string } }): EngramStartup {
-	const unknown: EngramStartup = { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
-	if (!engramProbeAllowed(input.env)) return unknown;
+	if (!engramProbeAllowed(input.env)) return { policy: "disabled", notice: ENGRAM_RECOVERY_NOTICE };
 	const endpoint = input.endpoint;
+	const outdated = endpoint.kind === "listening" && !endpoint.compatible ? outdatedServerVersion(endpoint.healthVersion) : undefined;
+	const unknown: EngramStartup = { policy: "disabled", notice: outdated === undefined ? ENGRAM_RECOVERY_NOTICE : engramOutdatedServerNotice(outdated) };
 	if (endpoint.kind === "listening" && endpoint.compatible) return { policy: "allow", url: ENGRAM_DEFAULT_URL };
 	if (endpoint.kind === "refused" && input.store === "absent") {
 		return input.core ? { policy: "allow", fresh: true } : { policy: "disabled", notice: ENGRAM_CORE_MISSING_NOTICE };
@@ -333,9 +351,9 @@ export function engramProvenanceMatches(record: EngramProvenance | undefined, ob
 }
 
 // The bundled core's own schema (SQLite user_version), verified from the
-// tagged source: v3.3.2:internal/store/store.go `const schemaVersion = 1`.
+// tagged sources v3.3.2 and v3.4.0: internal/store/store.go `const schemaVersion = 1`.
 // A pin without a verified entry leaves the header check unavailable.
-const BUNDLED_ENGRAM_SCHEMA: Record<string, number> = { "3.3.2": 1 };
+const BUNDLED_ENGRAM_SCHEMA: Record<string, number> = { "3.3.2": 1, "3.4.0": 1 };
 
 export function bundledEngramSchema(coreVersion: string): number | undefined {
 	return Object.hasOwn(BUNDLED_ENGRAM_SCHEMA, coreVersion) ? BUNDLED_ENGRAM_SCHEMA[coreVersion] : undefined;

package/lib/gentle-shell-launcher.ts

@@ -392,7 +392,7 @@ export function missingPiMessage(): string {
 
 // --- pi version gate ---------------------------------------------------------
 
-export const MIN_PI_VERSION = "0.99.1";
+export const MIN_PI_VERSION = "1.2.0";
 
 export type PiVersionCheck = { ok: true; version: string } | { ok: false; message: string; version?: string };
 

package/lib/model-routing-authority.ts

@@ -28,6 +28,11 @@ export type ModelConfigFileResult =
 export const SAFE_MODEL_ID_PATTERN = /^[A-Za-z0-9._~:@/+%-]+$/;
 const SAFE_AGENT_NAME_PATTERN = /^[A-Za-z0-9._:@/+%-]+$/;
 
+/** Shared agent-name policy; the same test normalizeModelConfig applies per key. */
+export function isSafeAgentName(name: string): boolean {
+	return SAFE_AGENT_NAME_PATTERN.test(name);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -78,7 +83,7 @@ export function normalizeModelConfig(value: unknown): AgentModelConfig | undefin
 	if (!isRecord(value)) return undefined;
 	const cleaned: AgentModelConfig = {};
 	for (const [name, entryValue] of Object.entries(value)) {
-		if (!SAFE_AGENT_NAME_PATTERN.test(name)) continue;
+		if (!isSafeAgentName(name)) continue;
 		const entry = normalizeRoutingEntry(entryValue);
 		if (entry) cleaned[name] = entry;
 	}

package/lib/selection-engine.ts

@@ -131,7 +131,10 @@ export function withReverseSpan(row: string, startCu: number, endCu: number): st
 			// A nested SGR reset (e.g. the cursor block's own, when the cursor
 			// sits inside the span) clears reverse for everything after it:
 			// re-arm reverse right after it.
-			if (opened && cu < endCu && isSgrReset(seq)) out += "\x1b[7m";
+			// Pi 1.2 resolves the APC fake-cursor end to SGR 27 later in
+			// the host TUI. Preserve the marker for hardware-cursor suppression,
+			// but rearm our selection after it just as after a legacy reset.
+			if (opened && cu < endCu && (isSgrReset(seq) || seq === "\x1b_pi:/fc\x07")) out += "\x1b[7m";
 			i += seq.length;
 			continue;
 		}

package/lib/session-profile-freeze.ts

@@ -16,8 +16,8 @@
 // The live resolution applies only in `follow` mode (GENTLE_PI_PROFILE_FOLLOW=1,
 // for CI and headless runs), in subagent children (their routing comes from the
 // parent through --model), and when no session id is available. In `follow`
-// mode the orchestrator still comes from the startup profile while children
-// follow later defaults: an accepted, documented limitation.
+// mode the orchestrator is still chosen at startup while children follow later
+// defaults: an accepted, documented limitation.
 //
 // The frozen state is in-process only, like the explicit binding of slice 2: it
 // lives on `globalThis` behind a `Symbol.for` key because Pi evaluates this
@@ -114,19 +114,14 @@ function isChildSession(env: NodeJS.ProcessEnv): boolean {
  * is never part of the routing. `undefined` means no layer has a profile.
  */
 export function resolveInheritedProfile(options: InheritedProfileOptions): InheritedProfile | undefined {
-	// One worktree lookup serves both the pin layers and the non-Git check.
-	let resolved = false;
-	let identity: WorktreeIdentity | undefined;
-	const resolveWorktree: WorktreeResolver | undefined = options.resolveWorktree === undefined ? undefined : (cwd, base) => {
-		if (!resolved) {
-			resolved = true;
-			identity = options.resolveWorktree!(cwd, base);
-		}
-		return identity;
-	};
-	const pin = resolveProfilePin({ cwd: options.cwd, configHome: options.configHome, resolveWorktree });
-	if (pin !== undefined) return { name: pin.profile, origin: pin.source, modelProfiles: pin.modelProfiles };
-	if (readProfilePinStatus(options.cwd, resolveWorktree) === undefined) {
+	// One worktree lookup serves both the pin layers and the non-Git check,
+	// whether the caller passes a resolver or the pin module's default runs.
+	const status = readProfilePinStatus(options.cwd, options.resolveWorktree);
+	if (status !== undefined) {
+		const identity: WorktreeIdentity = { root: status.root, commonDir: status.commonDir };
+		const pin = resolveProfilePin({ cwd: options.cwd, configHome: options.configHome, resolveWorktree: () => identity });
+		if (pin !== undefined) return { name: pin.profile, origin: pin.source, modelProfiles: pin.modelProfiles };
+	} else {
 		const declaration = resolveUnversionedProjectProfile(options.cwd, options.configHome);
 		if (declaration !== undefined) return { name: declaration.profile, origin: "repo", modelProfiles: declaration.modelProfiles };
 	}

package/lib/session-profile-persistence.ts

@@ -0,0 +1,187 @@
+// Standalone v1 codec and pure active-branch replay (gentle-shell#1064).
+// No Pi API, disk access, shared binding store, or orchestrator application.
+import { isValidProfileName } from "./agent-profiles.ts";
+import {
+	isSafeAgentName,
+	isThinkingLevel,
+	normalizeModelId,
+	normalizeRoutingEntry,
+	type AgentModelConfig,
+	type AgentRoutingEntry,
+} from "./model-routing-authority.ts";
+
+export const SESSION_PROFILE_CUSTOM_TYPE = "gentle-pi.session-profile/v1";
+const SESSION_PROFILE_FAMILY = "gentle-pi.session-profile/";
+
+export type SessionProfileOrigin = "user" | "local" | "repo" | "global";
+
+export interface SessionProfileBindPayload {
+	kind: "bind";
+	origin: SessionProfileOrigin;
+	name: string;
+	modelProfiles: AgentModelConfig;
+}
+
+export interface SessionProfileClearPayload {
+	kind: "clear";
+}
+
+/** Public structural entry shape only; ordinary messages need no custom fields. */
+export interface SessionProfileEntry {
+	type: string;
+	customType?: string;
+	data?: unknown;
+}
+
+export type SessionProfileReadResult =
+	| { status: "absent" }
+	| { status: "bound"; binding: SessionProfileBindPayload }
+	| { status: "cleared" }
+	| { status: "invalid" }
+	| { status: "unsupported" };
+
+export type SessionProfileReplayResult =
+	| { status: "absent" }
+	| (Exclude<SessionProfileReadResult, { status: "absent" }> & {
+			entryIndex: number;
+	  });
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+	return Object.hasOwn(value, key);
+}
+
+function isOrigin(value: unknown): value is SessionProfileOrigin {
+	return (
+		value === "user" ||
+		value === "local" ||
+		value === "repo" ||
+		value === "global"
+	);
+}
+
+/** Validate known fields before the permissive routing helper can drop them. */
+function readRoute(
+	value: unknown,
+	encoderInput = false,
+): AgentRoutingEntry | undefined {
+	if (typeof value === "string") return normalizeRoutingEntry(value);
+	if (!isRecord(value)) return undefined;
+	// Typed normalized routes can own optional undefined fields. Omit only those
+	// encoder fields; persisted fields and legacy effort retain strict validation.
+	const route = encoderInput
+		? Object.fromEntries(
+				Object.entries(value).filter(
+					([key, field]) =>
+						!((key === "model" || key === "thinking") && field === undefined),
+				),
+			)
+		: value;
+	if (hasOwn(route, "model") && normalizeModelId(route.model) === undefined)
+		return undefined;
+	if (hasOwn(route, "thinking") && !isThinkingLevel(route.thinking))
+		return undefined;
+	if (hasOwn(route, "effort") && !isThinkingLevel(route.effort))
+		return undefined;
+	// Project only own known fields. Unknown extras, even an unknown-only route,
+	// carry no routing meaning. Thinking wins over legacy effort as elsewhere.
+	const known = Object.fromEntries(
+		["model", "thinking", "effort"]
+			.filter((key) => hasOwn(route, key))
+			.map((key) => [key, route[key]]),
+	);
+	const normalized = normalizeRoutingEntry(known);
+	if (!normalized) return undefined;
+	return Object.fromEntries(
+		Object.entries(normalized).filter(([, field]) => field !== undefined),
+	);
+}
+
+function readSnapshot(
+	value: unknown,
+	encoderInput = false,
+): AgentModelConfig | undefined {
+	if (!isRecord(value)) return undefined;
+	const entries: Array<[string, AgentRoutingEntry]> = [];
+	for (const [name, rawRoute] of Object.entries(value)) {
+		// Shared agent-name policy, applied here without the forgiving whole-config
+		// normalization that would silently discard a bad route. Output below uses
+		// own data properties, never prototype setters.
+		if (!isSafeAgentName(name)) return undefined;
+		const route = readRoute(rawRoute, encoderInput);
+		if (route === undefined) return undefined;
+		entries.push([name, route]);
+	}
+	return Object.fromEntries(entries);
+}
+
+function readBind(
+	data: Record<string, unknown>,
+	encoderInput = false,
+): SessionProfileBindPayload | undefined {
+	if (!["origin", "name", "modelProfiles"].every((key) => hasOwn(data, key)))
+		return undefined;
+	if (!isOrigin(data.origin) || !isValidProfileName(data.name)) return undefined;
+	const modelProfiles = readSnapshot(data.modelProfiles, encoderInput);
+	if (modelProfiles === undefined) return undefined;
+	return { kind: "bind", origin: data.origin, name: data.name, modelProfiles };
+}
+
+/** Create a detached user selection payload; never appends or claims durability. */
+export function createSessionProfileBind(
+	name: string,
+	modelProfiles: AgentModelConfig,
+): SessionProfileBindPayload {
+	const binding = readBind({ origin: "user", name, modelProfiles }, true);
+	if (!binding) throw new TypeError("Invalid session profile binding");
+	return binding;
+}
+
+export function createSessionProfileClear(): SessionProfileClearPayload {
+	return { kind: "clear" };
+}
+
+/** Unknown family identifiers are terminal unsupported states, regardless of data. */
+export function readSessionProfileEntry(
+	entry: SessionProfileEntry,
+): SessionProfileReadResult {
+	if (
+		entry.type !== "custom" ||
+		typeof entry.customType !== "string" ||
+		!entry.customType.startsWith(SESSION_PROFILE_FAMILY)
+	)
+		return { status: "absent" };
+	if (entry.customType !== SESSION_PROFILE_CUSTOM_TYPE)
+		return { status: "unsupported" };
+	const data = entry.data;
+	if (!isRecord(data) || !hasOwn(data, "kind")) return { status: "invalid" };
+	if (data.kind === "clear") return { status: "cleared" };
+	if (data.kind !== "bind") return { status: "invalid" };
+	const binding = readBind(data);
+	return binding ? { status: "bound", binding } : { status: "invalid" };
+}
+
+/**
+ * Caller MUST supply ALREADY disk-corroborated active-branch entries, in branch
+ * order (oldest to newest). This function cannot establish that precondition:
+ * it does not read disk, call Pi, enforce append-failure recovery, establish
+ * durability, or update the shared map. In-memory getBranch() alone is NOT
+ * corroboration. Sibling and future paths must be excluded by the caller.
+ *
+ * The newest family entry wins even when invalid or unsupported; never revive
+ * an older binding. Cleared permits current fallback at a later consumer,
+ * whereas invalid/unsupported must remain distinct from absent. entryIndex is
+ * the actual supplied branch offset for a later adapter's location warning.
+ */
+export function replaySessionProfileBranch(
+	entries: readonly SessionProfileEntry[],
+): SessionProfileReplayResult {
+	for (let entryIndex = entries.length - 1; entryIndex >= 0; entryIndex--) {
+		const result = readSessionProfileEntry(entries[entryIndex]);
+		if (result.status !== "absent") return { ...result, entryIndex };
+	}
+	return { status: "absent" };
+}

package/lib/shell-changes.ts

@@ -110,6 +110,8 @@ export function snapshotChanges(snapshot: ChangesSnapshot): ChangedFile[] {
 	const counts = new Map(parseNumstat(snapshot.numstat).map((entry) => [entry.path, entry]));
 	const files: ChangedFile[] = [];
 	for (const [path, status] of parsePorcelain(snapshot.porcelain)) {
+		// Dependency backups are local artifacts; tracked files remain visible.
+		if (status === CHANGE_STATUS.UNTRACKED && /(?:^|\/)node_modules\.backup-[^/]+\//.test(path)) continue;
 		const entry = counts.get(path);
 		files.push({ path, added: entry?.added ?? 0, deleted: entry?.deleted ?? 0, status });
 	}

package/lib/shell-prompt.ts

@@ -74,7 +74,9 @@ export const DOUBLE_ESC_CANCEL_HINT = "esc again to cancel";
 export const IDLE_ESC_CLEAR_HINT = "esc again to clear";
 const LABEL_ROLE = "muted";
 const HINT_ROLE = "dim";
-const FAKE_CURSOR = "\x1b[7m \x1b[0m";
+// Audited legacy SGR and Pi 1.2 APC cursors. Do not resolve the latter
+// here: the host TUI owns hardware-cursor suppression after composition.
+const EMPTY_FAKE_CURSORS = ["\x1b[7m \x1b[0m", "\x1b_pi:fc\x07 \x1b_pi:/fc\x07"];
 const SCROLL_INDICATOR = /[↑↓] \d+ more/;
 const STATE_LABEL: Record<PromptState, string | undefined> = {
 	[PROMPT_STATE.IDLE]: undefined,
@@ -228,9 +230,9 @@ export function framePromptLines(lines: string[], width: number, options: Prompt
 }
 
 export function withPromptHint(line: string, hint: string, fg: PromptFrameOptions["fg"]): string {
-	const cursorAt = line.indexOf(FAKE_CURSOR);
-	if (cursorAt === -1) return line;
-	const afterCursor = cursorAt + FAKE_CURSOR.length;
+	const cursor = EMPTY_FAKE_CURSORS.find((marker) => line.includes(marker));
+	if (!cursor) return line;
+	const afterCursor = line.indexOf(cursor) + cursor.length;
 	const trailing = line.slice(afterCursor);
 	if (trailing.trim() !== "" || trailing.length < hint.length + 1) return line;
 	return `${line.slice(0, afterCursor)} ${fg(HINT_ROLE, hint)}${" ".repeat(trailing.length - hint.length - 1)}`;

package/lib/shell-todo.ts

@@ -258,16 +258,28 @@ export function replayTodo(entries: readonly unknown[]): TodoState {
 	return state;
 }
 
-export function todoPromptBlock(state: TodoState, stale: number): string | undefined {
+// gentle-shell#1367, #1662: the system prompt is a cached prefix for every
+// provider, so the block it carries is byte-stable for the whole session:
+// rules only, no task content and no counters. The current list travels as a
+// request-local message at the end of the conversation (todoStateMessage),
+// where a change costs only the tail of the request, never the prefix.
+const TODO_PROMPT_BLOCK = [
+	"## Todo list",
+	"Keep it current with the `todo` tool: mark a task in_progress before starting it, done right after finishing it, and rewrite the whole list with `write` whenever the plan changes. Update it before you end the turn.",
+	"A blocked task waits on something outside the list: do not work on it until its condition holds. When the plan changes, mark the tasks it made obsolete dropped instead of leaving them pending or marking them done.",
+	"While tasks stay open, the current list arrives as the last message of each request; it is not repeated here.",
+].join("\n");
+
+/** The byte-stable rules block appended to every system prompt. */
+export function todoPromptBlock(): string {
+	return TODO_PROMPT_BLOCK;
+}
+
+/** The open-task snapshot delivered as a request-local message; undefined when nothing is open. */
+export function todoStateMessage(state: TodoState): string | undefined {
 	if (todoSummary(state).open === 0) return undefined;
 	const lines = state.tasks.map((task, index) => `${index + 1}. [${task.status}] ${task.title}${task.note ? ` — ${task.note}` : ""}`);
-	const staleLine = stale >= STALE_AFTER_TURNS ? `\n(stale: ${stale} turns without an update — bring the list up to date now)` : "";
-	return [
-		"## Todo list",
-		"Keep it current with the `todo` tool: mark a task in_progress before starting it, done right after finishing it, and rewrite the whole list with `write` whenever the plan changes. Update it before you end the turn.",
-		"A blocked task waits on something outside the list: do not work on it until its condition holds. When the plan changes, mark the tasks it made obsolete dropped instead of leaving them pending or marking them done.",
-		...lines,
-	].join("\n") + staleLine;
+	return ["Current todo list:", ...lines].join("\n");
 }
 
 function taskRow(task: TodoTask, theme: TodoTheme, inner: number): string {

package/lib/vim-editor-adapter.ts

@@ -1,7 +1,7 @@
 import { CURSOR_MARKER, Editor, visibleWidth } from "@earendil-works/pi-tui";
 import { createRequire } from "node:module";
 
-// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2, 1.0.0 and 1.1.0:
+// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2, 1.0.0, 1.1.0 and 1.2.0:
 // editor.js state/pastes/history, sticky cursor reset, layoutText/render geometry,
 // autocomplete cancellation and { state, pastes, pasteCounter } undo restoration;
 // undo-stack.js clone-on-push/pop snapshots. The two 0.99 releases ship identical
@@ -13,6 +13,10 @@ import { createRequire } from "node:module";
 // Actual installed bundled/unbundled tests exercise identity, edit/undo, paste,
 // selection, wrapping/scroll and autocomplete; fabricated metadata tests only
 // prove exact-version admission for the older audited releases.
+// 1.2.0 changes only editor cursor rendering to paired pi:fc/pi:/fc APC
+// markers resolved by the host TUI (including hardware-cursor suppression).
+// Keep these markers intact and rearm selection after their reverse-off;
+// state, undo, paste, layout and autocomplete contracts remain unchanged.
 // Never silently adapt another build: undo also owns the paste registry.
 interface Position { line: number; col: number }
 interface State { lines: string[]; cursorLine: number; cursorCol: number }
@@ -51,7 +55,7 @@ interface PrivateEditor {
 
 // The single audited-release source for the adapter and Gentle Shell's runtime
 // identity gates. Add a release only after re-auditing the files named above.
-export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0", "1.1.0"] as const);
+export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0", "1.1.0", "1.2.0"] as const);
 export type AuditedPiEditorVersion = (typeof AUDITED_PI_EDITOR_VERSIONS)[number];
 
 export function isAuditedPiEditorVersion(version: unknown): version is AuditedPiEditorVersion {
@@ -83,7 +87,7 @@ function hasEditorIdentity(value: unknown, version: string, editorClass: typeof
 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 const marker = /\[paste #(\d+)(?: (?:\+\d+ lines|\d+ chars))?\]/g;
 
-// Only CSI SGR and Pi's own zero-width cursor marker are expected in editor
+// Only CSI SGR and Pi's own zero-width cursor markers are expected in editor
 // text. Unknown escapes leave the unmodified frame intact (fail closed).
 function highlightRenderedRow(row: string, chunk: LayoutLine, left: number, right: number, padding: number): string | undefined {
   const cursor = chunk.hasCursor ? chunk.cursorPos : undefined;
@@ -114,8 +118,22 @@ function highlightRenderedRow(row: string, chunk: LayoutLine, left: number, righ
       result += token;
       if (selected && !inverse) { result += "\x1b[7m"; inverse = true; }
     } else if (token.startsWith("\x1b")) {
-      if (token !== CURSOR_MARKER) return undefined;
+      if (token !== CURSOR_MARKER && token !== "\x1b_pi:fc\x07" && token !== "\x1b_pi:/fc\x07") return undefined;
+      // Close selection *before* the cursor pair, never inside its cell:
+      // otherwise a later host SGR 7 would immediately meet our SGR 27.
+      // Closing before CURSOR_MARKER also keeps it adjacent to pi:fc so
+      // hardware-cursor suppression can still recognize the focused pair.
+      const local = col - padding;
+      if ((token === CURSOR_MARKER || token === "\x1b_pi:fc\x07") && selected &&
+          !(local >= left && local < right && local < chunk.text.length)) {
+        if (!nativeInverse && inverse) result += "\x1b[27m";
+        selected = false;
+        inverse = nativeInverse;
+      }
       result += token;
+      // The host resolves pi:/fc to SGR 27, or drops the pair when the
+      // hardware cursor owns this cell. Selection must survive either path.
+      if (token === "\x1b_pi:/fc\x07" && selected) result += "\x1b[7m";
     } else {
       const local = col - padding;
       const shouldSelect = local >= left && local < right && local < chunk.text.length;