@sayknow-cli/coding-agent 0.6.4 → 0.6.5

package/src/modes/theme/defaults/ink-octopus.json

@@ -0,0 +1,114 @@
+{
+	"$schema": "https://raw.githubusercontent.com/jaybeyond/Sayknow_CLI/main/packages/coding-agent/theme-schema.json",
+	"name": "ink-octopus",
+	"vars": {
+		"ink": "#14110e",
+		"mantle": "#1b1712",
+		"surface": "#241e18",
+		"surfaceBright": "#322a21",
+		"text": "#ece4d6",
+		"muted": "#b3a794",
+		"dim": "#7d7264",
+		"accent": "#e8a23a",
+		"secondary": "#d4bd95",
+		"success": "#9fbf7a",
+		"error": "#e2664f",
+		"warning": "#f0c75e",
+		"link": "#e6b77c",
+		"keyword": "#e8a23a",
+		"function": "#e6cf9c",
+		"string": "#a9c58a",
+		"number": "#e59f78",
+		"type": "#d9b2d6",
+		"diffRemoved": "#d9695a",
+		"toolSuccessBg": "#1d2317",
+		"toolErrorBg": "#2d1915",
+		"think1": "#c9b28f",
+		"think2": "#e0b27a",
+		"think3": "#e8a23a",
+		"think4": "#e2664f"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "surfaceBright",
+		"borderAccent": "accent",
+		"borderMuted": "dim",
+		"success": "success",
+		"error": "error",
+		"warning": "warning",
+		"muted": "muted",
+		"dim": "dim",
+		"text": "text",
+		"thinkingText": "muted",
+		"selectedBg": "surfaceBright",
+		"userMessageBg": "surface",
+		"userMessageText": "text",
+		"customMessageBg": "mantle",
+		"customMessageText": "text",
+		"customMessageLabel": "accent",
+		"toolPendingBg": "mantle",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "text",
+		"toolOutput": "muted",
+		"mdHeading": "accent",
+		"mdLink": "link",
+		"mdLinkUrl": "dim",
+		"mdCode": "secondary",
+		"mdCodeBlock": "string",
+		"mdCodeBlockBorder": "surfaceBright",
+		"mdQuote": "muted",
+		"mdQuoteBorder": "surfaceBright",
+		"mdHr": "dim",
+		"mdListBullet": "accent",
+		"toolDiffAdded": "success",
+		"toolDiffRemoved": "diffRemoved",
+		"toolDiffContext": "muted",
+		"link": "link",
+		"syntaxComment": "dim",
+		"syntaxKeyword": "keyword",
+		"syntaxFunction": "function",
+		"syntaxVariable": "text",
+		"syntaxString": "string",
+		"syntaxNumber": "number",
+		"syntaxType": "type",
+		"syntaxOperator": "muted",
+		"syntaxPunctuation": "dim",
+		"thinkingOff": "dim",
+		"thinkingMinimal": "muted",
+		"thinkingLow": "think1",
+		"thinkingMedium": "think2",
+		"thinkingHigh": "think3",
+		"thinkingXhigh": "think4",
+		"bashMode": "accent",
+		"statusLineBg": "surfaceBright",
+		"statusLineSep": "dim",
+		"statusLineModel": "accent",
+		"statusLinePath": "secondary",
+		"statusLineGitClean": "success",
+		"statusLineGitDirty": "warning",
+		"statusLineContext": "string",
+		"statusLineSpend": "warning",
+		"statusLineStaged": "success",
+		"statusLineDirty": "warning",
+		"statusLineUntracked": "diffRemoved",
+		"statusLineOutput": "text",
+		"statusLineCost": "accent",
+		"statusLineSubagents": "secondary",
+		"pythonMode": "function"
+	},
+	"export": {
+		"pageBg": "#14110e",
+		"cardBg": "#1b1712",
+		"infoBg": "#241e18"
+	},
+	"symbols": {
+		"preset": "unicode",
+		"overrides": {
+			"icon.pi": "🐙",
+			"icon.agents": "🦑",
+			"status.running": "◐",
+			"md.bullet": "›"
+		}
+	}
+}

package/src/modes/theme/defaults/violet-octopus.json

@@ -0,0 +1,114 @@
+{
+	"$schema": "https://raw.githubusercontent.com/jaybeyond/Sayknow_CLI/main/packages/coding-agent/theme-schema.json",
+	"name": "violet-octopus",
+	"vars": {
+		"ink": "#110c17",
+		"mantle": "#191220",
+		"surface": "#221829",
+		"surfaceBright": "#2e2138",
+		"text": "#efe7f7",
+		"muted": "#bba9cf",
+		"dim": "#7a6a8c",
+		"accent": "#b692ff",
+		"secondary": "#ffb482",
+		"success": "#8fd6a8",
+		"error": "#ff6f91",
+		"warning": "#ffcf70",
+		"link": "#d3b8ff",
+		"keyword": "#b692ff",
+		"function": "#ffb482",
+		"string": "#8fd6a8",
+		"number": "#ffcf70",
+		"type": "#d3b8ff",
+		"diffRemoved": "#ff6f91",
+		"toolSuccessBg": "#17241c",
+		"toolErrorBg": "#2c1522",
+		"think1": "#d3b8ff",
+		"think2": "#c5a4ff",
+		"think3": "#b692ff",
+		"think4": "#ffb482"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "surfaceBright",
+		"borderAccent": "accent",
+		"borderMuted": "dim",
+		"success": "success",
+		"error": "error",
+		"warning": "warning",
+		"muted": "muted",
+		"dim": "dim",
+		"text": "text",
+		"thinkingText": "muted",
+		"selectedBg": "surfaceBright",
+		"userMessageBg": "surface",
+		"userMessageText": "text",
+		"customMessageBg": "mantle",
+		"customMessageText": "text",
+		"customMessageLabel": "accent",
+		"toolPendingBg": "mantle",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "text",
+		"toolOutput": "muted",
+		"mdHeading": "accent",
+		"mdLink": "link",
+		"mdLinkUrl": "dim",
+		"mdCode": "secondary",
+		"mdCodeBlock": "string",
+		"mdCodeBlockBorder": "surfaceBright",
+		"mdQuote": "muted",
+		"mdQuoteBorder": "surfaceBright",
+		"mdHr": "dim",
+		"mdListBullet": "accent",
+		"toolDiffAdded": "success",
+		"toolDiffRemoved": "diffRemoved",
+		"toolDiffContext": "muted",
+		"link": "link",
+		"syntaxComment": "dim",
+		"syntaxKeyword": "keyword",
+		"syntaxFunction": "function",
+		"syntaxVariable": "text",
+		"syntaxString": "string",
+		"syntaxNumber": "number",
+		"syntaxType": "type",
+		"syntaxOperator": "muted",
+		"syntaxPunctuation": "dim",
+		"thinkingOff": "dim",
+		"thinkingMinimal": "muted",
+		"thinkingLow": "think1",
+		"thinkingMedium": "think2",
+		"thinkingHigh": "think3",
+		"thinkingXhigh": "think4",
+		"bashMode": "accent",
+		"statusLineBg": "surfaceBright",
+		"statusLineSep": "dim",
+		"statusLineModel": "accent",
+		"statusLinePath": "secondary",
+		"statusLineGitClean": "success",
+		"statusLineGitDirty": "warning",
+		"statusLineContext": "string",
+		"statusLineSpend": "warning",
+		"statusLineStaged": "success",
+		"statusLineDirty": "warning",
+		"statusLineUntracked": "diffRemoved",
+		"statusLineOutput": "text",
+		"statusLineCost": "accent",
+		"statusLineSubagents": "secondary",
+		"pythonMode": "function"
+	},
+	"export": {
+		"pageBg": "#110c17",
+		"cardBg": "#191220",
+		"infoBg": "#221829"
+	},
+	"symbols": {
+		"preset": "unicode",
+		"overrides": {
+			"icon.pi": "🐙",
+			"icon.agents": "🦑",
+			"status.running": "◐",
+			"md.bullet": "▸"
+		}
+	}
+}

package/src/modes/theme/theme.ts

@@ -107,6 +107,7 @@ export type SymbolKey =
 	| "icon.output"
 	| "icon.host"
 	| "icon.session"
+	| "icon.star"
 	| "icon.package"
 	| "icon.warning"
 	| "icon.rewind"
@@ -142,6 +143,8 @@ export type SymbolKey =
 	| "md.quoteBorder"
 	| "md.hrChar"
 	| "md.bullet"
+	// Transcript rail marking the user's own prompts
+	| "rail.user"
 	// Language/file type icons
 	| "lang.default"
 	| "lang.typescript"
@@ -272,6 +275,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.output": "⤴",
 	"icon.host": "🖥",
 	"icon.session": "🆔",
+	"icon.star": "★",
 	"icon.package": "📦",
 	"icon.warning": "⚠",
 	"icon.rewind": "↶",
@@ -307,6 +311,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"md.quoteBorder": "▏",
 	"md.hrChar": "─",
 	"md.bullet": "•",
+	"rail.user": "▌",
 	// Language/file icons (emoji-centric, no Nerd Font required)
 	"lang.default": "⌘",
 	"lang.typescript": "🟦",
@@ -507,6 +512,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.host": "\uf109",
 	// pick:  | alt:  
 	"icon.session": "\uf550",
+	"icon.star": "\uf005",
 	// pick:  | alt: 
 	"icon.package": "\uf487",
 	// pick:  | alt:  
@@ -567,6 +573,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"md.hrChar": "─",
 	// pick:  | alt:  •
 	"md.bullet": "\uf111",
+	"rail.user": "▌",
 	// Language icons (nerd font devicons)
 	"lang.default": "",
 	"lang.typescript": "\u{E628}",
@@ -696,6 +703,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.output": "out:",
 	"icon.host": "host",
 	"icon.session": "id",
+	"icon.star": "*",
 	"icon.package": "[P]",
 	"icon.warning": "[!]",
 	"icon.rewind": "<-",
@@ -730,6 +738,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"md.quoteBorder": "|",
 	"md.hrChar": "-",
 	"md.bullet": "*",
+	"rail.user": "|",
 	// Language icons (ASCII uses abbreviations)
 	"lang.default": "code",
 	"lang.typescript": "ts",
@@ -1471,6 +1480,7 @@ export class Theme {
 			output: this.#symbols["icon.output"],
 			host: this.#symbols["icon.host"],
 			session: this.#symbols["icon.session"],
+			star: this.#symbols["icon.star"],
 			package: this.#symbols["icon.package"],
 			warning: this.#symbols["icon.warning"],
 			rewind: this.#symbols["icon.rewind"],
@@ -1516,6 +1526,12 @@ export class Theme {
 		};
 	}
 
+	get rail() {
+		return {
+			user: this.#symbols["rail.user"],
+		};
+	}
+
 	get md() {
 		return {
 			quoteBorder: this.#symbols["md.quoteBorder"],
@@ -1785,7 +1801,7 @@ var themeWatcher: fs.FSWatcher | undefined;
 var themeReloadTimer: NodeJS.Timeout | undefined;
 var sigwinchHandler: (() => void) | undefined;
 var autoDetectedTheme: boolean = false;
-var autoDarkTheme: string = "blue-octopus";
+var autoDarkTheme: string = "ink-octopus";
 var autoLightTheme: string = "blue-octopus";
 var onThemeChangeCallback: (() => void) | undefined;
 var themeLoadRequestId: number = 0;
@@ -1806,7 +1822,7 @@ export async function initTheme(
 	lightTheme?: string,
 ): Promise<void> {
 	autoDetectedTheme = true;
-	autoDarkTheme = darkTheme ?? "blue-octopus";
+	autoDarkTheme = darkTheme ?? "ink-octopus";
 	autoLightTheme = lightTheme ?? "blue-octopus";
 	const name = getDefaultTheme();
 	previewThemeActive = false;

package/src/modes/types.ts

@@ -289,7 +289,7 @@ export interface InteractiveModeContext {
 	handleHandoffCommand(customInstructions?: string): Promise<void>;
 	handleContributionPrepCommand(customInstructions?: string): Promise<void>;
 	handleMoveCommand(targetPath: string): Promise<void>;
-	handleRenameCommand(title: string): Promise<void>;
+	handleRenameCommand(title?: string): Promise<void>;
 	handleMemoryCommand(text: string): Promise<void>;
 	handleSTTToggle(): Promise<void>;
 	executeCompaction(

package/src/prompts/system/title-system.md

@@ -1,2 +1,2 @@
-Generate a 3-6 word title for a coding session from the user's first message. Capture the main task or topic.
+Generate a 3-6 word title for a coding session from the supplied user message or conversation digest. If multiple messages are supplied, identify the primary/current task from the digest, weighting the newest substantive message highest; do not assume the first message is the task. If one message is supplied, capture its main task or topic.
 Output ONLY the title. No quotes or trailing punctuation.

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2177,6 +2177,28 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "slash_command:star",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "exclude",
+		"rationale": "local session-discovery metadata command; no SDK operation counterpart or runtime/retention authority",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
+	{
+		"sourceId": "slash_command:unstar",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "exclude",
+		"rationale": "local session-discovery metadata command; no SDK operation counterpart or runtime/retention authority",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "slash_command:resume",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
@@ -2275,6 +2297,24 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "slash_command:fork",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "include",
+		"sdkId": "session.branch",
+		"adapterMappings": {
+			"telegram": "generic_safe",
+			"discord": "generic_safe",
+			"slack": "generic_safe",
+			"mcp": "generic_safe",
+			"acp": "generic_safe",
+			"daemonCli": "generic_safe"
+		},
+		"testIds": [
+			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
+		]
+	},
 	{
 		"sourceId": "slash_command:rename",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",

package/src/session/agent-session.ts

@@ -109,6 +109,7 @@ import {
 	type FallbackAttemptToken,
 	type FallbackTriggerClass,
 } from "@sayknow-cli/ai/utils/fallback-transport";
+import { REPETITION_GUARD_ERROR_CODE } from "@sayknow-cli/ai/utils/stream-repetition-guard";
 import {
 	BTW_MAX_ANSWER_UTF8_BYTES,
 	BTW_MAX_QUESTION_UTF8_BYTES,
@@ -360,6 +361,7 @@ import { parseCommandArgs } from "../utils/command-args";
 import { type EditMode, resolveEditMode } from "../utils/edit-mode";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { extractFileMentions, generateFileMentionMessages } from "../utils/file-mentions";
+import { invalidateSessionTitleGeneration } from "../utils/session-title-generation";
 import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-choice";
 import { buildWorkflowIntentDiff, WORKFLOW_INTENT_DIFF_CUSTOM_TYPE } from "../workflow/workflow-intent-diff";
 import { buildWorkspaceTree, type WorkspaceTree } from "../workspace-tree";
@@ -7717,6 +7719,9 @@ export class AgentSession {
 	}
 
 	async prompt(text: string, options?: PromptOptions): Promise<void> {
+		// A newer human prompt makes any in-flight /rename regeneration stale.
+		if (options?.synthetic !== true && options?.attribution !== "agent")
+			invalidateSessionTitleGeneration(this.sessionManager);
 		this.#assertRecoveryHydrationPromoted();
 		const expandPromptTemplates = options?.expandPromptTemplates ?? true;
 
@@ -8493,6 +8498,7 @@ export class AgentSession {
 	 * Queue a steering message to interrupt the agent mid-run.
 	 */
 	async steer(text: string, images?: ImageContent[]): Promise<void> {
+		invalidateSessionTitleGeneration(this.sessionManager);
 		this.#assertRecoveryHydrationPromoted();
 		if (text.startsWith("/")) {
 			this.#throwIfExtensionCommand(text);
@@ -8511,6 +8517,7 @@ export class AgentSession {
 		images?: ImageContent[],
 		options?: Pick<PromptOptions, "followUpQueuePolicy">,
 	): Promise<void> {
+		invalidateSessionTitleGeneration(this.sessionManager);
 		this.#assertRecoveryHydrationPromoted();
 		if (text.startsWith("/")) {
 			this.#throwIfExtensionCommand(text);
@@ -13726,6 +13733,11 @@ export class AgentSession {
 	#classifyErrorForRetry(message: AssistantMessage): RetryErrorClassification {
 		if (message.stopReason !== "error") return "none";
 		if (message.errorKind === "provider_safety_stop") return "terminal";
+		// A decode loop is deterministic for the submitted context: replaying the
+		// identical conversation re-trips the guard and re-bills the full context.
+		// Without this the message carries no transport facts and would fall
+		// through to "unknown", which is admitted for bounded retry (#5627).
+		if (message.errorCode === REPETITION_GUARD_ERROR_CODE) return "terminal";
 		if (!message.errorMessage) return "none";
 		const err = message.errorMessage;
 		// Provider safety refusals (e.g. Anthropic stop_reason "refusal" /

package/src/session/internal/managed-session-scope.ts

@@ -1215,6 +1215,16 @@ function receiptMatches(
 				tree?: unknown;
 			};
 		};
+		// A receipt is keyed by its source and names exactly one destination. The
+		// resume listing probes every (legacy source, v2 destination) pair, so reject
+		// on these cheap receipt fields before hashing both transcripts and walking
+		// the artifact manifest; the full conjunction below would be false anyway.
+		if (
+			record.destination?.path !== destination.path ||
+			record.source?.path !== source.path ||
+			record.source?.sha256 !== source.identity.sha256
+		)
+			return false;
 		const exact = (
 			recorded: { dev?: unknown; ino?: unknown; size?: unknown; mtimeNs?: unknown } | undefined,
 			candidate: ManagedCandidate,

package/src/session/session-manager.ts

@@ -35,6 +35,7 @@ import type { ManagedLegacyLocalMigrationSource } from "../internal-urls/local-p
 import { assertSafePathComponent } from "../skc-runtime/session-layout";
 import { writeTextAtomic } from "../skc-runtime/state-writer";
 import * as git from "../utils/git";
+import { invalidateSessionTitleGeneration } from "../utils/session-title-generation";
 import { ArtifactManager } from "./artifacts";
 import {
 	type BlobPutResult,
@@ -96,7 +97,6 @@ import {
 	memoryGuardCanonicalJson,
 	memoryGuardSha256Hex,
 } from "./memory-guard-checkpoint-participant";
-
 import {
 	type BashExecutionMessage,
 	type CustomMessage,
@@ -110,6 +110,7 @@ import {
 	stripInternalDetailsFields,
 } from "./messages";
 import { type SessionManagerReadAccess, sessionManagerReadCapability } from "./session-manager-internal";
+import { isSessionIdStarred, setSessionIdStarred } from "./session-stars";
 import type {
 	ManagedSessionSecurityContext,
 	SessionStorage,
@@ -889,6 +890,8 @@ export interface SessionInfo {
 	/** Working directory where the session was started. Empty string for old sessions. */
 	cwd: string;
 	title?: string;
+	/** Starred for discovery (see session-stars.ts); never affects resolution or retention. */
+	starred: boolean;
 	/** Path to the parent session (if this session was forked). */
 	parentSessionPath?: string;
 	created: Date;
@@ -3819,6 +3822,11 @@ async function collectProjectSessions(cwd: string, storage: FileSessionStorage):
 	return await collectSessionsFromFiles(listProjectSessionTranscriptFiles(cwd), storage);
 }
 
+/** Starred sessions first, each group keeping its incoming (recency) order. */
+export function prioritizeStarredSessions(sessions: readonly SessionInfo[]): SessionInfo[] {
+	return [...sessions.filter(session => session.starred), ...sessions.filter(session => !session.starred)];
+}
+
 function mergeSessionInventories(...inventories: SessionInfo[][]): SessionInfo[] {
 	const sessions = new Map<string, SessionInfo>();
 	for (const inventory of inventories) {
@@ -4229,6 +4237,7 @@ async function collectSessionFromFile(
 			id: header.id,
 			cwd: header.cwd ?? "",
 			title: header.title ?? shortSummary,
+			starred: isSessionIdStarred(header.id),
 			parentSessionPath: header.parentSession,
 			created: new Date(header.timestamp ?? ""),
 			modified: stats.mtime,
@@ -6998,6 +7007,20 @@ export class SessionManager {
 		return this.#sessionName;
 	}
 
+	isSessionStarred(): boolean {
+		return isSessionIdStarred(this.getSessionId());
+	}
+
+	/** Star or unstar this session. Returns `false` when it was already in that state. */
+	async setSessionStarred(starred: boolean): Promise<boolean> {
+		return setSessionIdStarred(this.getSessionId(), starred);
+	}
+
+	/** Star or unstar a session listed in the resume picker (not necessarily this one). */
+	async setSessionStarredForPicker(session: Pick<SessionInfo, "id">, starred: boolean): Promise<void> {
+		await setSessionIdStarred(session.id, starred);
+	}
+
 	/** Strip C0/C1 control characters (includes ESC, so removes ANSI sequences) and collapse whitespace. */
 	static #sanitizeName(name: string): string {
 		return name
@@ -7023,6 +7046,7 @@ export class SessionManager {
 		const sanitized = SessionManager.#sanitizeName(name);
 		if (!sanitized) return false;
 
+		invalidateSessionTitleGeneration(this);
 		this.#sessionName = sanitized;
 		this.#titleSource = source;
 		await this.#appendHeaderPatch({ title: sanitized, titleSource: source });
@@ -7219,6 +7243,7 @@ export class SessionManager {
 			| PythonExecutionMessage
 			| FileMentionMessage,
 	): string {
+		if (message.role === "user") invalidateSessionTitleGeneration(this);
 		const entry: SessionMessageEntry = {
 			type: "message",
 			id: generateId(this.#byId),

package/src/session/session-stars.ts

@@ -0,0 +1,104 @@
+/**
+ * Starred sessions: discovery-only metadata kept in one small index file under
+ * the agent directory, keyed by session id.
+ *
+ * Stars never touch transcripts. They sort sessions first in the resume picker
+ * and the sessions dashboard, and nothing else: `--continue`, ID-prefix
+ * resolution, deletion, and retention ignore them. A deleted session leaves a
+ * harmless stale id behind; a forked session gets a new id and starts unstarred.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, logger } from "@sayknow-cli/utils";
+import { withFileLock } from "../config/file-lock";
+
+const INDEX_FILE_NAME = "session-stars.json";
+
+interface StarIndexFile {
+	version: 1;
+	/** Session id → ISO time the star was added. */
+	starred: Record<string, string>;
+}
+
+let cache: { path: string; mtimeMs: number; size: number; ids: ReadonlySet<string> } | undefined;
+
+export function getSessionStarIndexPath(agentDir: string = getAgentDir()): string {
+	return path.join(agentDir, INDEX_FILE_NAME);
+}
+
+function parseIndex(text: string): StarIndexFile {
+	const parsed = JSON.parse(text) as Partial<StarIndexFile>;
+	const starred: Record<string, string> = {};
+	if (parsed && typeof parsed === "object" && parsed.starred && typeof parsed.starred === "object") {
+		for (const [id, at] of Object.entries(parsed.starred)) {
+			if (typeof at === "string") starred[id] = at;
+		}
+	}
+	return { version: 1, starred };
+}
+
+/**
+ * Ids of starred sessions. Cheap to call per listed session: the parsed index is
+ * cached until the file's mtime or size changes. A missing or unreadable index
+ * means nothing is starred; listing never fails because of stars.
+ */
+export function readStarredSessionIds(agentDir?: string): ReadonlySet<string> {
+	const indexPath = getSessionStarIndexPath(agentDir);
+	let stat: fs.Stats;
+	try {
+		stat = fs.statSync(indexPath);
+	} catch {
+		cache = undefined;
+		return new Set();
+	}
+	if (cache?.path === indexPath && cache.mtimeMs === stat.mtimeMs && cache.size === stat.size) return cache.ids;
+	try {
+		const ids = new Set(Object.keys(parseIndex(fs.readFileSync(indexPath, "utf8")).starred));
+		cache = { path: indexPath, mtimeMs: stat.mtimeMs, size: stat.size, ids };
+		return ids;
+	} catch (error) {
+		logger.warn("Ignoring unreadable session star index", { indexPath, error: String(error) });
+		return new Set();
+	}
+}
+
+export function isSessionIdStarred(sessionId: string, agentDir?: string): boolean {
+	return readStarredSessionIds(agentDir).has(sessionId);
+}
+
+/**
+ * Star or unstar a session by id. Returns `true` when the index changed and
+ * `false` when the session was already in the requested state. The
+ * read-modify-write runs under a cross-process lock and lands with an atomic
+ * rename, so two CLIs toggling different sessions cannot drop each other's star.
+ */
+export async function setSessionIdStarred(sessionId: string, starred: boolean, agentDir?: string): Promise<boolean> {
+	if (!sessionId) throw new Error("A session id is required to change its star.");
+	const indexPath = getSessionStarIndexPath(agentDir);
+	await fs.promises.mkdir(path.dirname(indexPath), { recursive: true });
+	return withFileLock(indexPath, async () => {
+		let index: StarIndexFile;
+		try {
+			index = parseIndex(await fs.promises.readFile(indexPath, "utf8"));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+				// Refuse to overwrite an index we cannot read: that would silently drop every other star.
+				throw new Error(`Cannot update session stars: ${indexPath} is unreadable (${String(error)}).`);
+			}
+			index = { version: 1, starred: {} };
+		}
+		if (sessionId in index.starred === starred) return false;
+		if (starred) index.starred[sessionId] = new Date().toISOString();
+		else delete index.starred[sessionId];
+		const tmpPath = `${indexPath}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await fs.promises.writeFile(tmpPath, `${JSON.stringify(index, null, "\t")}\n`, "utf8");
+			await fs.promises.rename(tmpPath, indexPath);
+		} catch (error) {
+			await fs.promises.rm(tmpPath, { force: true }).catch(() => undefined);
+			throw error;
+		}
+		cache = undefined;
+		return true;
+	});
+}