@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/session/session-storage.ts

@@ -4,6 +4,13 @@ import * as path from "node:path";
 import { isEnoent, pathIsWithin, peekFile, toError } from "@gajae-code/utils";
 
 const utf8Decoder = new TextDecoder("utf-8");
+function canonicalPathSync(value: string): string {
+	try {
+		return fs.realpathSync.native(value);
+	} catch {
+		return path.resolve(value);
+	}
+}
 
 export interface SessionStorageStat {
 	dev: bigint;
@@ -614,7 +621,7 @@ export class FileSessionStorage implements SessionStorage {
 		if (typeof header.cwd !== "string") {
 			throw new SessionDeleteVerificationError("cwd", "Transcript header is missing a cwd");
 		}
-		if (path.resolve(header.cwd) !== path.resolve(expectedCwd)) {
+		if (canonicalPathSync(header.cwd) !== canonicalPathSync(expectedCwd)) {
 			throw new SessionDeleteVerificationError("cwd", "Transcript header cwd does not match authorization");
 		}
 		return { snapshot };

package/src/setup/credential-auto-import.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type {
@@ -7,8 +8,8 @@ import type {
 	AuthStorage,
 } from "@gajae-code/ai";
 import { getAgentDir, logger, VERSION } from "@gajae-code/utils";
+import { withFileLock } from "../config/file-lock";
 import type { ModelRegistry } from "../config/model-registry";
-
 import {
 	type CredentialDiscoveryResult,
 	type CredentialOrigin,
@@ -23,42 +24,206 @@ import {
 
 export const CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING =
 	"Refreshing in gjc may log out the Claude/Codex CLI because OAuth refresh tokens can rotate.";
+export const CREDENTIAL_AUTO_IMPORT_PERSISTENCE_WARNING =
+	"Credential import preference could not be saved; external credentials may be offered again.";
+export const CREDENTIAL_AUTO_IMPORT_REFRESH_WARNING =
+	"Imported credentials were saved, but provider availability could not be refreshed.";
+export const CREDENTIAL_AUTO_IMPORT_DISCOVERY_WARNING =
+	"External credential discovery could not be completed. Use /provider to import credentials manually.";
+export const CREDENTIAL_AUTO_IMPORT_RETRY_WARNING =
+	"Some external credentials could not be imported. Use /provider to retry.";
+
+export const CREDENTIAL_AUTO_IMPORT_STATE_UNREADABLE_WARNING =
+	"Credential import preference could not be read. External credential discovery was skipped; use /provider to import credentials manually.";
 
 export type CredentialAutoImportSourceLabel = "claude-code-file" | "claude-code-keychain" | "codex-file";
 export type CredentialAutoImportTrigger = "startup" | "bare-login" | "setup-cli";
+export type InitialImportResolution = "accepted" | "declined";
+export type CredentialAutoImportStateProblem =
+	| "invalid-initial-import-resolution"
+	| "invalid-last-import-version"
+	| "malformed-json"
+	| "malformed-root";
 
 const CREDENTIAL_AUTO_IMPORT_STATE_FILENAME = "credential-auto-import-state.json";
+const VERSION_MARKER_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export interface CredentialAutoImportStateFile {
+	lastImportVersion?: string;
+	initialImportResolution?: InitialImportResolution;
+}
+
+export interface CredentialAutoImportStateReadResult {
+	state: CredentialAutoImportStateFile;
+	problems: CredentialAutoImportStateProblem[];
+	unreadable: boolean;
+}
 
-interface CredentialAutoImportStateFile {
-	lastImportVersion?: unknown;
+export interface CredentialAutoImportStateMutation {
+	lastImportVersion?: string;
+	initialImportResolution?: InitialImportResolution;
+}
+
+export interface CredentialAutoImportStateStore {
+	read: () => Promise<CredentialAutoImportStateReadResult>;
+	write: (mutation: CredentialAutoImportStateMutation) => Promise<boolean>;
+}
+
+export interface CredentialAutoImportStateStoreDependencies {
+	withFileLock?: <T>(filePath: string, transaction: () => Promise<T>) => Promise<T>;
+	rename?: (oldPath: string, newPath: string) => Promise<void>;
 }
 
 export function getCredentialAutoImportStatePath(agentDir: string = getAgentDir()): string {
 	return path.join(agentDir, CREDENTIAL_AUTO_IMPORT_STATE_FILENAME);
 }
 
-export async function readCredentialImportMarker(agentDir?: string): Promise<string | undefined> {
+function isEnoent(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+}
+
+function isValidVersionMarker(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.trim() === value &&
+		value.length <= 128 &&
+		VERSION_MARKER_PATTERN.test(value)
+	);
+}
+
+function isInitialImportResolution(value: unknown): value is InitialImportResolution {
+	return value === "accepted" || value === "declined";
+}
+
+function projectCredentialAutoImportState(value: unknown): CredentialAutoImportStateReadResult {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return { state: {}, problems: ["malformed-root"], unreadable: false };
+	}
+
+	const record = value as Record<string, unknown>;
+	const state: CredentialAutoImportStateFile = {};
+	const problems: CredentialAutoImportStateProblem[] = [];
+	if (Object.hasOwn(record, "initialImportResolution")) {
+		if (isInitialImportResolution(record.initialImportResolution)) {
+			state.initialImportResolution = record.initialImportResolution;
+		} else {
+			problems.push("invalid-initial-import-resolution");
+		}
+	}
+	if (Object.hasOwn(record, "lastImportVersion")) {
+		if (isValidVersionMarker(record.lastImportVersion)) {
+			state.lastImportVersion = record.lastImportVersion;
+		} else {
+			problems.push("invalid-last-import-version");
+		}
+	}
+	return { state, problems, unreadable: false };
+}
+
+async function readCredentialAutoImportStateAtPath(statePath: string): Promise<CredentialAutoImportStateReadResult> {
 	try {
-		const raw = await fs.readFile(getCredentialAutoImportStatePath(agentDir), "utf-8");
-		const parsed = JSON.parse(raw) as CredentialAutoImportStateFile;
-		return typeof parsed.lastImportVersion === "string" ? parsed.lastImportVersion : undefined;
-	} catch {
-		return undefined;
+		const raw = await fs.readFile(statePath, "utf-8");
+		try {
+			return projectCredentialAutoImportState(JSON.parse(raw) as unknown);
+		} catch {
+			return { state: {}, problems: ["malformed-json"], unreadable: false };
+		}
+	} catch (error: unknown) {
+		if (isEnoent(error)) return { state: {}, problems: [], unreadable: false };
+		return { state: {}, problems: [], unreadable: true };
 	}
 }
 
-export async function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean> {
+function serializeCredentialAutoImportState(state: CredentialAutoImportStateFile): string {
+	const serialized: CredentialAutoImportStateFile = {};
+	if (isValidVersionMarker(state.lastImportVersion)) serialized.lastImportVersion = state.lastImportVersion;
+	if (isInitialImportResolution(state.initialImportResolution)) {
+		serialized.initialImportResolution = state.initialImportResolution;
+	}
+	return `${JSON.stringify(serialized)}\n`;
+}
+
+async function writeCredentialAutoImportStateAtomic(
+	statePath: string,
+	state: CredentialAutoImportStateFile,
+	rename: (oldPath: string, newPath: string) => Promise<void> = fs.rename,
+): Promise<void> {
+	const temporaryPath = `${statePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
 	try {
-		const statePath = getCredentialAutoImportStatePath(agentDir);
-		await fs.mkdir(path.dirname(statePath), { recursive: true });
-		await fs.writeFile(statePath, `${JSON.stringify({ lastImportVersion: version })}\n`);
-		return true;
+		const handle = await fs.open(temporaryPath, "wx", 0o600);
+		try {
+			await handle.writeFile(serializeCredentialAutoImportState(state));
+		} finally {
+			await handle.close();
+		}
+		await rename(temporaryPath, statePath);
 	} catch (error: unknown) {
-		logger.warn("Failed to persist credential auto-import state", { error });
-		return false;
+		await fs.rm(temporaryPath, { force: true }).catch(() => {});
+		throw error;
 	}
 }
 
+export function createCredentialAutoImportStateStore(
+	agentDir: string = getAgentDir(),
+	dependencies: CredentialAutoImportStateStoreDependencies = {},
+): CredentialAutoImportStateStore {
+	const statePath = getCredentialAutoImportStatePath(agentDir);
+	const lock = dependencies.withFileLock ?? withFileLock;
+	const rename = dependencies.rename ?? fs.rename;
+	return {
+		read: () => readCredentialAutoImportStateAtPath(statePath),
+		write: async mutation => {
+			if (
+				(mutation.lastImportVersion !== undefined && !isValidVersionMarker(mutation.lastImportVersion)) ||
+				(mutation.initialImportResolution !== undefined &&
+					!isInitialImportResolution(mutation.initialImportResolution))
+			) {
+				return false;
+			}
+			try {
+				await fs.mkdir(path.dirname(statePath), { recursive: true, mode: 0o700 });
+				await lock(statePath, async () => {
+					const current = await readCredentialAutoImportStateAtPath(statePath);
+					if (current.unreadable) throw new Error("Credential auto-import state became unreadable");
+					const next: CredentialAutoImportStateFile = { ...current.state };
+					if (mutation.lastImportVersion !== undefined) next.lastImportVersion = mutation.lastImportVersion;
+					if (next.initialImportResolution === undefined && mutation.initialImportResolution !== undefined) {
+						next.initialImportResolution = mutation.initialImportResolution;
+					}
+					await writeCredentialAutoImportStateAtomic(statePath, next, rename);
+				});
+				return true;
+			} catch {
+				logger.warn("Credential auto-import state persistence failed", { classification: "state-write-failed" });
+				return false;
+			}
+		},
+	};
+}
+
+export async function readCredentialAutoImportState(agentDir?: string): Promise<CredentialAutoImportStateReadResult> {
+	return createCredentialAutoImportStateStore(agentDir).read();
+}
+
+export function isCredentialAutoImportStateResolvedForVersion(
+	state: CredentialAutoImportStateFile,
+	version: string,
+): boolean {
+	return (
+		state.initialImportResolution !== undefined ||
+		(state.lastImportVersion !== undefined && state.lastImportVersion === version)
+	);
+}
+
+export async function readCredentialImportMarker(agentDir?: string): Promise<string | undefined> {
+	return (await readCredentialAutoImportState(agentDir)).state.lastImportVersion;
+}
+
+export async function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean> {
+	return createCredentialAutoImportStateStore(agentDir).write({ lastImportVersion: version });
+}
+
 export enum CredentialAutoImportFailureClass {
 	DiscoveryUnavailable = "discovery-unavailable",
 	SourceUnreadable = "source-unreadable",
@@ -93,6 +258,63 @@ export interface CredentialAutoImportResult {
 	globalDiscoveryFailure?: CredentialAutoImportFailure;
 }
 
+const CREDENTIAL_AUTO_IMPORT_PROMPT_PROVIDERS: readonly ExternalProvider[] = ["anthropic", "openai-codex"];
+const CREDENTIAL_AUTO_IMPORT_PROMPT_ORIGINS: readonly CredentialOrigin[] = [
+	"claude-code-file",
+	"claude-code-keychain",
+	"codex-file",
+];
+const CREDENTIAL_AUTO_IMPORT_ORIGIN_LABELS: Record<CredentialOrigin, string> = {
+	"claude-code-file": "Claude Code file",
+	"claude-code-keychain": "Claude Code Keychain",
+	"codex-file": "Codex CLI file",
+};
+const CREDENTIAL_AUTO_IMPORT_FAILURE_CLASSES = new Set(Object.values(CredentialAutoImportFailureClass));
+
+export function formatCredentialAutoImportCandidateLabel(
+	candidate: Pick<ImportableCredential, "provider" | "origin">,
+): string {
+	const provider = CREDENTIAL_AUTO_IMPORT_PROMPT_PROVIDERS.includes(candidate.provider)
+		? EXTERNAL_PROVIDER_LABELS[candidate.provider]
+		: undefined;
+	const origin = CREDENTIAL_AUTO_IMPORT_PROMPT_ORIGINS.includes(candidate.origin)
+		? CREDENTIAL_AUTO_IMPORT_ORIGIN_LABELS[candidate.origin]
+		: undefined;
+	return provider && origin ? `${provider} · ${origin}` : "External OAuth credential";
+}
+
+export function formatCredentialAutoImportPrompt(
+	candidates: readonly Pick<ImportableCredential, "provider" | "origin">[],
+): string {
+	const lines: string[] = [];
+	for (const provider of CREDENTIAL_AUTO_IMPORT_PROMPT_PROVIDERS) {
+		for (const origin of CREDENTIAL_AUTO_IMPORT_PROMPT_ORIGINS) {
+			const count = candidates.filter(
+				candidate => candidate.provider === provider && candidate.origin === origin,
+			).length;
+			if (count > 0)
+				lines.push(
+					`${EXTERNAL_PROVIDER_LABELS[provider]} · ${CREDENTIAL_AUTO_IMPORT_ORIGIN_LABELS[origin]}: ${count}`,
+				);
+		}
+	}
+	return `External OAuth credentials found: ${candidates.length}\n${lines.join("\n")}`;
+}
+
+export function logCredentialAutoImportFailures(
+	trigger: CredentialAutoImportTrigger,
+	failures: readonly Pick<CredentialAutoImportFailure, "failureClass">[],
+): void {
+	const failureCounts: Partial<Record<CredentialAutoImportFailureClass, number>> = {};
+	for (const failure of failures) {
+		if (!CREDENTIAL_AUTO_IMPORT_FAILURE_CLASSES.has(failure.failureClass)) continue;
+		failureCounts[failure.failureClass] = (failureCounts[failure.failureClass] ?? 0) + 1;
+	}
+	if (Object.keys(failureCounts).length > 0) {
+		logger.warn("Credential auto-import completed with failures", { trigger, failureCounts });
+	}
+}
+
 export type CredentialAutoImportAuthStorage = Pick<AuthStorage, "importCredentialIfAbsent">;
 
 export interface CredentialAutoImportOptions {
@@ -204,18 +426,38 @@ export function formatCredentialAutoImportResult(result: CredentialAutoImportRes
 	return lines;
 }
 
-export interface CredentialImportMarkerStore {
-	read: () => Promise<string | undefined> | string | undefined;
-	write: (version: string) => Promise<boolean> | boolean;
-}
-
 export interface StartupCredentialAutoImportOptions {
 	authStorage: CredentialAutoImportOptions["authStorage"];
 	modelRegistry: Pick<ModelRegistry, "refresh">;
 	discover?: CredentialAutoImportOptions["discover"];
 	version?: string;
 	agentDir?: string;
-	markerStore?: CredentialImportMarkerStore;
+	stateStore?: CredentialAutoImportStateStore;
+}
+
+function appendNoticeLine(notice: string | undefined, line: string): string {
+	return notice ? `${notice}\n${line}` : line;
+}
+
+async function readStateSafely(store: CredentialAutoImportStateStore): Promise<CredentialAutoImportStateReadResult> {
+	try {
+		return await store.read();
+	} catch {
+		logger.warn("Credential auto-import state read failed", { classification: "state-read-failed" });
+		return { state: {}, problems: [], unreadable: true };
+	}
+}
+
+async function writeStateSafely(
+	store: CredentialAutoImportStateStore,
+	mutation: CredentialAutoImportStateMutation,
+): Promise<boolean> {
+	try {
+		return await store.write(mutation);
+	} catch {
+		logger.warn("Credential auto-import state persistence failed", { classification: "state-write-failed" });
+		return false;
+	}
 }
 
 export async function runStartupCredentialAutoImportIfNeeded({
@@ -224,17 +466,15 @@ export async function runStartupCredentialAutoImportIfNeeded({
 	discover,
 	version = VERSION,
 	agentDir,
-	markerStore,
+	stateStore,
 }: StartupCredentialAutoImportOptions): Promise<string | undefined> {
-	const store = markerStore ?? {
-		read: () => readCredentialImportMarker(agentDir),
-		write: (nextVersion: string) => writeCredentialImportMarker(nextVersion, agentDir),
-	};
-	const lastVersion = await store.read();
-	if (lastVersion === version) {
-		// Steady state: user already completed this version's auto-import gate. Skip all file/Keychain reads.
+	const store = stateStore ?? createCredentialAutoImportStateStore(agentDir);
+	const stateRead = await readStateSafely(store);
+	if (stateRead.unreadable) {
+		logger.warn("Credential auto-import state unavailable", { classification: "state-unreadable" });
 		return undefined;
 	}
+	if (isCredentialAutoImportStateResolvedForVersion(stateRead.state, version)) return undefined;
 
 	const result = await runExternalCredentialAutoImport({
 		authStorage: activeAuthStorage,
@@ -242,17 +482,32 @@ export async function runStartupCredentialAutoImportIfNeeded({
 		trigger: "startup",
 	});
 	if (!result.discovered) {
+		logCredentialAutoImportFailures("startup", result.failures);
 		return undefined;
 	}
 
 	const candidates = filterAutoImportOAuthCredentials(result.discovery?.importable ?? []);
-	if (candidates.length > 0 && result.imported.length === 0 && result.skipped.length === 0) {
-		return undefined;
+	const handledCandidates = result.imported.length + result.skipped.length > 0;
+	if (result.failures.length > 0) logCredentialAutoImportFailures("startup", result.failures);
+	let persisted = true;
+	if (handledCandidates) {
+		persisted = await writeStateSafely(store, {
+			lastImportVersion: version,
+			initialImportResolution: "accepted",
+		});
+	} else if (candidates.length === 0 && result.failures.length === 0) {
+		persisted = await writeStateSafely(store, { lastImportVersion: version });
 	}
-	await store.write(version);
 
+	let notice = buildCredentialAutoImportNotice(result);
+	if (!persisted) notice = appendNoticeLine(notice, CREDENTIAL_AUTO_IMPORT_PERSISTENCE_WARNING);
 	if (result.imported.length > 0) {
-		await activeModelRegistry.refresh("offline");
+		try {
+			await activeModelRegistry.refresh("offline");
+		} catch {
+			logger.warn("Credential auto-import refresh failed", { classification: "refresh-failed" });
+			notice = appendNoticeLine(notice, CREDENTIAL_AUTO_IMPORT_REFRESH_WARNING);
+		}
 	}
-	return buildCredentialAutoImportNotice(result);
+	return notice;
 }

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -13,7 +13,7 @@ These instructions teach a Hermes-style coordinator how to operate GJC through t
    If a second task is needed while one turn is active, pass `queue: true`; the next queued turn is promoted after the active turn is reported terminal.
 5. If GJC asks a structured question, use `{{TOOL_PREFIX}}_list_questions` and answer with `{{TOOL_PREFIX}}_submit_question_answer`.
 6. Use `{{TOOL_PREFIX}}_report_status` for coordinator-visible status and final reports.
-7. Use `{{TOOL_PREFIX}}_read_tail` only as advisory debug output when structured turn state is insufficient.
+7. Use `{{TOOL_PREFIX}}_read_tail` only to inspect the latest assistant response through the SDK when structured turn state is insufficient; it never reads terminal output.
 
 ## Prefer high-level delegation
 
@@ -39,11 +39,9 @@ The Hermes bridge does not choose a model/provider. Generated setup configures `
 
 Provider-specific commands are examples only, never product defaults.
 
-## Visible routed-session fallback
+## Human-visible TUI boundary
 
-If a Hermes/OpenClaw/Clawhip-style operator needs a human-visible, channel-routed GJC pane instead of a pure Coordinator MCP session, use the visible session pattern in [`docs/gjc-session-clawhip-routing.md`](../../../../../../docs/gjc-session-clawhip-routing.md).
-
-Use that pattern only when the router must watch tmux output, send stale-session alerts, or inject follow-up prompts into the same visible pane. The short version is: prepare a dedicated worktree, register a stable tmux session through the host router, start interactive `gjc`, wait for TUI readiness, inject the task prompt separately, and verify actual tool/work activity before reporting acceptance.
+A human may choose to run the local TUI in tmux for terminal visibility. That terminal is not a controller API: Hermes/OpenClaw/Clawhip-style operators must not inject prompts into, scrape, or route machine decisions through a tmux pane. Use the Coordinator MCP tools above for every external control and viewing operation.
 
 Do not put private channel ids, mention targets, socket names, tokens, or local routing policy into portable setup output. Keep those in the host/operator deployment.
 

package/src/slash-commands/builtin-registry.ts

@@ -3,15 +3,7 @@ import * as path from "node:path";
 import { ThinkingLevel } from "@gajae-code/agent-core";
 import { type Model, modelsAreEqual } from "@gajae-code/ai";
 import { getOAuthProviders } from "@gajae-code/ai/utils/oauth";
-import {
-	isPetMode,
-	isUnderTerminalMultiplexer,
-	PET_MODE_IDS,
-	PET_SKIN_IDS,
-	PET_SKINS,
-	Spacer,
-	Text,
-} from "@gajae-code/tui";
+import { PET_SKINS, type PetMode, Spacer, Text } from "@gajae-code/tui";
 import { setProjectDir } from "@gajae-code/utils";
 import { jobElapsedMs } from "../async";
 import { materializeActiveModelProfileAssignments } from "../config/model-profile-activation";
@@ -30,7 +22,6 @@ import {
 import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../discovery/helpers.js";
 import { resolveMemoryBackend } from "../memory-backend";
 import { DynamicBorder } from "../modes/components/dynamic-border";
-import { GajaePetWidget } from "../modes/components/gajae-pet-widget";
 import { theme } from "../modes/theme/theme";
 import type { InteractiveModeContext } from "../modes/types";
 import {
@@ -42,7 +33,7 @@ import {
 	formatNotificationTestResult,
 	recoverNotifications,
 	sendNotificationTest,
-} from "../notifications/notification-service";
+} from "../sdk/bus/notification-service";
 import { computeCacheMissCostSummary, formatCacheMissSummaryLines } from "../session/cache-economics";
 import { formatModelOnboardingGuidance } from "../setup/model-onboarding-guidance";
 import {
@@ -73,6 +64,22 @@ export type { BuiltinSlashCommand, SubcommandDef } from "./types";
 /** TUI-specific runtime accepted by `executeBuiltinSlashCommand`. */
 export type BuiltinSlashCommandRuntime = TuiSlashCommandRuntime;
 
+const PET_COMMAND_OPTIONS: ReadonlyArray<{ name: string; mode: PetMode; description: string }> = [
+	{ name: "off", mode: "off", description: "Hide the pet" },
+	{ name: "RedGajae", mode: "red", description: PET_SKINS.red.description },
+	{ name: "BlueGajae", mode: "blue", description: PET_SKINS.blue.description },
+];
+const PET_COMMAND_HINT = `[${PET_COMMAND_OPTIONS.map(option => option.name).join("|")}]`;
+/**
+ * Deprecated inputs kept accepted for compatibility (`/pet on|red|blue`).
+ * Display, completion, and inline hints stay canonical (`PET_COMMAND_OPTIONS`).
+ */
+const PET_COMMAND_DEPRECATED_INPUTS: Readonly<Record<string, PetMode>> = {
+	on: "red",
+	red: "red",
+	blue: "blue",
+};
+
 type GjcModelBatchAssignmentTargetId = "all-role-agents" | "all-targets";
 type ParsedModelCommandArgs =
 	| { kind: "summary" }
@@ -570,34 +577,29 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	{
 		name: "pet",
 		description: "Gajae pet living beside the composer",
-		subcommands: [
-			{ name: "off", description: "Hide the pet" },
-			...PET_SKIN_IDS.map(id => ({ name: id, description: PET_SKINS[id].description })),
-		],
-		inlineHint: `[${PET_MODE_IDS.join("|")}]`,
+		subcommands: PET_COMMAND_OPTIONS.map(option => ({ name: option.name, description: option.description })),
+		inlineHint: PET_COMMAND_HINT,
 		allowArgs: true,
 		handleTui: (command, runtime) => {
 			const ctx = runtime.ctx;
 			const raw = command.args?.trim().toLowerCase() ?? "";
-			const arg = raw === "on" ? "red" : raw;
-			if (!arg) {
+			const arg =
+				PET_COMMAND_OPTIONS.find(option => option.name.toLowerCase() === raw)?.mode ??
+				PET_COMMAND_DEPRECATED_INPUTS[raw];
+			if (!raw) {
 				ctx.showPetSelector();
 				ctx.editor.setText("");
 				return;
 			}
-			if (arg !== "off" && !GajaePetWidget.pixelProtocol()) {
-				ctx.showStatus(
-					isUnderTerminalMultiplexer()
-						? "Gajae pet: graphics are suppressed inside tmux/screen/zellij — escapes are not forwarded end-to-end. Run gjc outside the multiplexer in a sixel/kitty-graphics terminal, or set PI_FORCE_IMAGE_PROTOCOL=sixel when your multiplexer+client chain renders sixel."
-						: "Gajae pet needs a sixel/kitty-graphics terminal (Windows Terminal 1.22+, kitty, Ghostty, WezTerm)",
-					{ dim: true },
-				);
-			} else if (isPetMode(arg)) {
-				ctx.setPetMode(arg);
-				const name = arg === "off" ? "Gajae pet hidden" : `${PET_SKINS[arg].label} is here`;
-				ctx.showStatus(name);
+			if (arg) {
+				// The shared commit policy rechecks capability, persists only on
+				// acceptance, and surfaces the actionable warning on rejection.
+				if (ctx.setPetMode(arg)) {
+					const name = arg === "off" ? "Gajae pet hidden" : `${PET_SKINS[arg].label} is here`;
+					ctx.showStatus(name);
+				}
 			} else {
-				ctx.showStatus(`Usage: /pet [${PET_MODE_IDS.join("|")}]`, { dim: true });
+				ctx.showStatus(`Usage: /pet ${PET_COMMAND_HINT}`, { dim: true });
 			}
 			ctx.editor.setText("");
 		},
@@ -695,6 +697,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 						await runtime.session.setModel(selection.model, "default", {
 							selector: selection.selector,
 							thinkingLevel: existingDefaultThinkingLevel,
+							cause: "user-selection",
 						});
 						if (existingDefaultThinkingLevel) {
 							runtime.session.setThinkingLevel(existingDefaultThinkingLevel);