@sayknow-cli/coding-agent 0.5.0 → 0.5.2

package/dist/types/skc-runtime/tmux-owner-isolation.d.ts

@@ -302,6 +302,166 @@ export declare function replaceOwnerGenerationSync(stateDir: string, sessionId:
 /** Publishes a raw-owner generation through the canonical SQLite-serialized CAS path. */
 export declare function publishOwnerGenerationSync(request: PublishGenerationRequest): PublishGenerationResult;
 export declare function createOwnerIntent(stateDir: string, input: Omit<OwnerIntent, "schema_version" | "intent_id" | "state">): Promise<OwnerIntent>;
+/**
+ * Shared identity create fence (frozen contract F1'-F9''', architect-approved).
+ *
+ * Concurrent creators of the SAME canonical `(stateDir, sessionId)` identity must
+ * not both spawn a child: `SessionManager` opens transcripts with append flags and
+ * has no inter-process single-writer lock, so two owners on one transcript is a
+ * data-integrity failure rather than a recoverable skip.
+ *
+ * The fence deliberately does NOT hold the SQLite writer transaction across the
+ * spawn. `bootstrapTmuxOwnerIsolation()` runs in a separate process and acquires
+ * this very database twice itself, and the synchronous creator blocks on that
+ * helper through `Bun.spawnSync`, so a held transaction would deadlock the helper
+ * against its own parent. A long hold would also starve the 250 ms verdict path
+ * that shares this database. Instead each transition takes a short (target 50 ms)
+ * transaction that only reads and writes a durable reservation row; mutual
+ * exclusion outlives the transaction as row state, not as a held lock.
+ */
+export type IdentityCreatePhase = "reserved" | "helper_invoked" | "spawned" | "tagged" | "published";
+/** Phases at or beyond which an untagged child may already exist on the server. */
+export declare function identityCreatePhaseMayHaveChild(phase: IdentityCreatePhase): boolean;
+export interface IdentityCreateKey {
+    stateDir: string;
+    sessionId: string;
+    stateFile: string;
+}
+export interface IdentityCreateReservation {
+    reservationId: string;
+    stateDir: string;
+    sessionId: string;
+    stateFile: string;
+    ownerPid: number;
+    ownerIncarnation: string;
+    phase: IdentityCreatePhase;
+    attemptSessionName: string | null;
+    nativeSessionId: string | null;
+    serverPid: number | null;
+    serverStartTime: string | null;
+    claimedAt: string;
+    updatedAt: string;
+    leaseDeadline: string;
+}
+export type IdentityCreateReservationResult = {
+    ok: true;
+    reservation: IdentityCreateReservation;
+    recovered: IdentityCreateReservation | null;
+} | {
+    ok: false;
+    code: "identity_reserved_live" | "identity_reserved_unknown" | "identity_fence_contended" | "identity_incarnation_unavailable" | "identity_orphan_unresolved" | "identity_existing_owner";
+    existing: IdentityCreateReservation | null;
+    diagnostic: string;
+};
+/** Owner liveness is tri-state: only a proven-dead owner may be displaced. */
+export type OwnerLiveness = "alive" | "dead" | "unknown";
+/**
+ * `processIncarnation()` returns `undefined` both for a vanished process and for a
+ * failed probe, so existence is resolved first. Signal 0 distinguishes them:
+ * `ESRCH` proves absence, `EPERM` proves a live process owned by another user, and
+ * anything else is unknown. Only then does the incarnation discriminate PID reuse.
+ */
+export declare function probeOwnerLiveness(pid: number, recordedIncarnation: string, deps?: {
+    readIncarnation?: (pid: number) => string | undefined;
+    signal?: (pid: number) => void;
+}): OwnerLiveness;
+/** @internal Test seam for the incarnation reader. */
+export declare function __setOwnerIncarnationReaderForTests(reader: ((pid: number) => string | undefined) | null): void;
+export declare function canonicalIdentityCreateKey(key: IdentityCreateKey): IdentityCreateKey;
+/**
+ * Ends the attempt while KEEPING the durable row.
+ *
+ * Used when cleanup after a spawn was uncertain: a child may survive that we
+ * could not remove, so the evidence must outlive the attempt. Unlike
+ * `releaseIdentityCreate` this leaves the row for authority-first recovery.
+ */
+export declare function abandonIdentityCreate(reservation: IdentityCreateReservation): void;
+export interface ReserveIdentityCreateOptions {
+    ttlMs?: number;
+    ownerPid?: number;
+    ownerIncarnation?: string;
+    now?: () => Date;
+    probeLiveness?: (pid: number, incarnation: string) => OwnerLiveness;
+}
+/**
+ * Claims the identity when it is free, and otherwise reports why not.
+ *
+ * A dead previous owner is deliberately NOT displaced here: authority-first
+ * recovery has to census live tmux, which shells out and must never run inside
+ * the fence window. The caller performs that census and then calls
+ * {@link reclaimIdentityCreate}.
+ *
+ * The lease deadline is diagnostic only. Expiry never authorizes takeover; only a
+ * proven-dead owner does, because real creator paths block in unbounded
+ * `Bun.spawnSync` and cannot heartbeat while blocked.
+ */
+export declare function reserveIdentityCreate(rawKey: IdentityCreateKey, options?: ReserveIdentityCreateOptions): IdentityCreateReservationResult;
+/**
+ * Completes authority-first recovery after the caller proved, outside the fence
+ * window, that the abandoned reservation left no authoritative child behind.
+ *
+ * `expectedReservationId` pins the exact abandoned row: if another process already
+ * recovered it, the row no longer matches and this fails closed rather than
+ * producing a second child.
+ */
+export declare function reclaimIdentityCreate(rawKey: IdentityCreateKey, expectedReservationId: string, options?: ReserveIdentityCreateOptions): IdentityCreateReservationResult;
+/**
+ * What a live-tmux census concluded about the child an abandoned reservation may
+ * have left behind. `unknown` is not a soft failure: it is the fail-closed case.
+ */
+export type AbandonedIdentityVerdict = {
+    kind: "authoritative";
+    nativeSessionId: string;
+} | {
+    kind: "orphan";
+    nativeSessionId: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "unknown";
+    reason: string;
+};
+/**
+ * Injected so this module never imports the tmux session helpers (which already
+ * depend on it). The census shells out and therefore runs OUTSIDE the fence
+ * window, by construction.
+ */
+export interface AbandonedIdentityCensus {
+    inspect(evidence: {
+        stateDir: string;
+        sessionId: string;
+        attemptSessionName: string | null;
+        nativeSessionId: string | null;
+    }): AbandonedIdentityVerdict;
+    cleanupOrphan(nativeSessionId: string, attemptSessionName: string | null): void;
+}
+/**
+ * Authority-first recovery for a reservation whose owner is proven dead and that
+ * reached at least `helper_invoked`, so an untagged child may exist.
+ *
+ * The reservation's own `phase` is a hint, never the authority: a creator can
+ * publish its generation and die before recording `published`. The census reads
+ * the live canonical tags and the current published generation instead, so a
+ * valid child is preserved rather than killed — which is what keeps a
+ * tag-before-report crash from producing a successor.
+ */
+export declare function recoverAbandonedIdentityCreate(key: IdentityCreateKey, existing: IdentityCreateReservation, census: AbandonedIdentityCensus, options?: ReserveIdentityCreateOptions): IdentityCreateReservationResult;
+export interface IdentityCreatePhasePatch {
+    attemptSessionName?: string | null;
+    nativeSessionId?: string | null;
+    serverPid?: number | null;
+    serverStartTime?: string | null;
+}
+/**
+ * Records a create-progress transition and renews the lease.
+ *
+ * Returns `null` when the reservation is no longer ours. The caller MUST treat
+ * that as a lost fence and perform no tmux mutation: another process has already
+ * recovered this identity.
+ */
+export declare function advanceIdentityCreatePhase(reservation: IdentityCreateReservation, phase: IdentityCreatePhase, patch?: IdentityCreatePhasePatch, options?: Pick<ReserveIdentityCreateOptions, "ttlMs" | "now">): IdentityCreateReservation | null;
+/** Releases the reservation. Idempotent, and never deletes a successor's row. */
+export declare function releaseIdentityCreate(reservation: IdentityCreateReservation): void;
 /** Publish exactly one terminal verdict. Existing valid verdicts always win. */
 export declare function observeOwnerTerminal(request: ObserveTerminalRequest): Promise<OwnerVerdict>;
 /** Strictly validate the persisted authorization, optionally against its terminal observation. */

package/dist/types/skc-runtime/tmux-sessions.d.ts

@@ -1,4 +1,4 @@
-import { type OwnerIsolationProbeSync, type PlanResponse, type TmuxOwnerIsolationExecutionDependencies, type TmuxOwnerIsolationExecutionResult } from "./tmux-owner-isolation";
+import { type AbandonedIdentityCensus, type IdentityCreateKey, type IdentityCreateReservationResult, type OwnerIsolationProbeSync, type PlanResponse, type TmuxOwnerIsolationExecutionDependencies, type TmuxOwnerIsolationExecutionResult } from "./tmux-owner-isolation";
 export interface SkcTmuxSessionStatus {
     name: string;
     attached: boolean;
@@ -67,6 +67,17 @@ export interface ForceCloseOwnerDependencies {
 }
 export interface CreateSkcTmuxSessionOptions {
     platform?: NodeJS.Platform;
+    /**
+     * Restore only: run the child in the session's recorded directory instead of
+     * this process's cwd.
+     */
+    cwd?: string;
+    /**
+     * Restore only: argv appended to the `skc` child, e.g. `["--resume", "<id>"]`.
+     * Restore reuses this creator verbatim so it inherits the same identity fence
+     * and owner-isolation proof as an ordinary create.
+     */
+    childArgs?: string[];
 }
 export type CreateOwnerIsolationTestDependencies = {
     probe?: Partial<OwnerIsolationProbeSync>;
@@ -83,6 +94,20 @@ export declare function findSkcTmuxSessionByBranch(branch: string, env?: NodeJS.
 export declare function findSkcTmuxSessionByName(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus | undefined;
 export declare function findSkcTmuxSessionByScope(project: string, branch: string | null | undefined, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus | undefined;
 export declare function statusSkcTmuxSession(sessionName: string, env?: NodeJS.ProcessEnv): SkcTmuxSessionStatus;
+/**
+ * Live-tmux census for authority-first recovery of an abandoned reservation.
+ *
+ * Authority is the CURRENT published generation on disk compared against the
+ * live session's canonical tags — never the reservation's own `phase`, because a
+ * creator can publish and then die before recording that it published.
+ */
+/**
+ * Resolves a reservation refused because its previous owner died after reaching
+ * the helper. Shared by every producer so none of them can brick an identity by
+ * treating an abandoned row as a permanent collision.
+ */
+export declare function settleAbandonedIdentity(reserved: IdentityCreateReservationResult, identityKey: IdentityCreateKey, census: AbandonedIdentityCensus): IdentityCreateReservationResult;
+export declare function abandonedIdentityCensus(tmuxCommand: string, env: NodeJS.ProcessEnv, stateFile: string): AbandonedIdentityCensus;
 export declare function createSkcTmuxSession(env?: NodeJS.ProcessEnv, options?: CreateSkcTmuxSessionOptions): SkcTmuxSessionStatus;
 /** Proves a managed reusable name still resolves to one immutable session on one server. */
 export declare function proveSkcTmuxSessionMutationTarget(sessionName: string, env?: NodeJS.ProcessEnv): ProvenTmuxSessionIdentity;

package/dist/types/tools/ask.d.ts

@@ -29,13 +29,92 @@ export declare const askSchema: z.ZodObject<{
         }, z.core.$strip>>;
         multi: z.ZodOptional<z.ZodBoolean>;
         recommended: z.ZodOptional<z.ZodNumber>;
-        deepInterview: z.ZodOptional<z.ZodObject<{
+        workflowGate: z.ZodOptional<z.ZodObject<{
+            stage: z.ZodEnum<{
+                "deep-interview": "deep-interview";
+                ralplan: "ralplan";
+                ultragoal: "ultragoal";
+            }>;
+            kind: z.ZodEnum<{
+                question: "question";
+                approval: "approval";
+                execution: "execution";
+            }>;
+        }, z.core.$strip>>;
+        deepInterview: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            round: z.ZodLiteral<0>;
+            component: z.ZodLiteral<"review-topology">;
+            intent_contract: z.ZodObject<{
+                items: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    category: z.ZodEnum<{
+                        surface: "surface";
+                        artifact: "artifact";
+                        integration: "integration";
+                        constraint: "constraint";
+                    }>;
+                    statement: z.ZodString;
+                }, z.core.$strict>>;
+                confirmation_options: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
             round_id: z.ZodOptional<z.ZodString>;
+            dimension: z.ZodString;
+            ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
             round: z.ZodNumber;
+            intent_review: z.ZodObject<{
+                observed_items: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    category: z.ZodEnum<{
+                        surface: "surface";
+                        artifact: "artifact";
+                        integration: "integration";
+                        constraint: "constraint";
+                    }>;
+                    statement: z.ZodString;
+                }, z.core.$strict>>;
+                supporting_substitutions: z.ZodArray<z.ZodObject<{
+                    removed_id: z.ZodString;
+                    replacement_ids: z.ZodArray<z.ZodString>;
+                    rationale: z.ZodString;
+                }, z.core.$strict>>;
+                approval_options: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+            round_id: z.ZodOptional<z.ZodString>;
             component: z.ZodString;
             dimension: z.ZodString;
             ambiguity: z.ZodNumber;
-        }, z.core.$strip>>;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodObject<{
+            round_id: z.ZodOptional<z.ZodString>;
+            round: z.ZodNumber;
+            component: z.ZodString;
+            dimension: z.ZodString;
+            ambiguity: z.ZodNumber;
+            confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                reference_id: z.ZodString;
+                label: z.ZodString;
+                origin: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+                excerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>]>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type AskToolInput = z.infer<typeof askSchema>;
@@ -54,6 +133,8 @@ export interface AskToolDetails {
     multi?: boolean;
     selectedOptions?: string[];
     customInput?: string;
+    /** Set when the user answered with a clarification question instead of a choice. */
+    clarificationQuestion?: string;
     /** Multi-part question mode */
     results?: QuestionResult[];
 }
@@ -80,13 +161,92 @@ export declare class AskTool implements AgentTool<typeof askSchema, AskToolDetai
             }, z.core.$strip>>;
             multi: z.ZodOptional<z.ZodBoolean>;
             recommended: z.ZodOptional<z.ZodNumber>;
-            deepInterview: z.ZodOptional<z.ZodObject<{
+            workflowGate: z.ZodOptional<z.ZodObject<{
+                stage: z.ZodEnum<{
+                    "deep-interview": "deep-interview";
+                    ralplan: "ralplan";
+                    ultragoal: "ultragoal";
+                }>;
+                kind: z.ZodEnum<{
+                    question: "question";
+                    approval: "approval";
+                    execution: "execution";
+                }>;
+            }, z.core.$strip>>;
+            deepInterview: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                round: z.ZodLiteral<0>;
+                component: z.ZodLiteral<"review-topology">;
+                intent_contract: z.ZodObject<{
+                    items: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        category: z.ZodEnum<{
+                            surface: "surface";
+                            artifact: "artifact";
+                            integration: "integration";
+                            constraint: "constraint";
+                        }>;
+                        statement: z.ZodString;
+                    }, z.core.$strict>>;
+                    confirmation_options: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>;
                 round_id: z.ZodOptional<z.ZodString>;
+                dimension: z.ZodString;
+                ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>, z.ZodObject<{
                 round: z.ZodNumber;
+                intent_review: z.ZodObject<{
+                    observed_items: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        category: z.ZodEnum<{
+                            surface: "surface";
+                            artifact: "artifact";
+                            integration: "integration";
+                            constraint: "constraint";
+                        }>;
+                        statement: z.ZodString;
+                    }, z.core.$strict>>;
+                    supporting_substitutions: z.ZodArray<z.ZodObject<{
+                        removed_id: z.ZodString;
+                        replacement_ids: z.ZodArray<z.ZodString>;
+                        rationale: z.ZodString;
+                    }, z.core.$strict>>;
+                    approval_options: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>;
+                round_id: z.ZodOptional<z.ZodString>;
                 component: z.ZodString;
                 dimension: z.ZodString;
                 ambiguity: z.ZodNumber;
-            }, z.core.$strip>>;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>, z.ZodObject<{
+                round_id: z.ZodOptional<z.ZodString>;
+                round: z.ZodNumber;
+                component: z.ZodString;
+                dimension: z.ZodString;
+                ambiguity: z.ZodNumber;
+                confused_terms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    reference_id: z.ZodString;
+                    label: z.ZodString;
+                    origin: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    excerpt: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>]>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly strict = true;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -52,12 +52,12 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.5.0",
-		"@sayknow-cli/agent-core": "0.5.0",
-		"@sayknow-cli/ai": "0.5.0",
-		"@sayknow-cli/natives": "0.5.0",
-		"@sayknow-cli/tui": "0.5.0",
-		"@sayknow-cli/utils": "0.5.0",
+		"@sayknow-cli/stats": "0.5.2",
+		"@sayknow-cli/agent-core": "0.5.2",
+		"@sayknow-cli/ai": "0.5.2",
+		"@sayknow-cli/natives": "0.5.2",
+		"@sayknow-cli/tui": "0.5.2",
+		"@sayknow-cli/utils": "0.5.2",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
@@ -124,6 +124,9 @@
 		"./commands/skc-runtime-bridge": null,
 		"./capability/mcp": null,
 		"./config/mcp-schema": null,
+		"./config/model-auth": null,
+		"./config/model-bindings-applier": null,
+		"./config/model-discovery-manager": null,
 		"./discovery/mcp-json": null,
 		"./exa": null,
 		"./exa/*": null,

package/src/commands/session.ts

@@ -1,4 +1,13 @@
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { readBootGeneration } from "../skc-runtime/boot-generation";
+import {
+	decodeRestoreReference,
+	encodeRestoreReference,
+	evaluateRestoreCandidates,
+	listRestorePointers,
+	type RestoreCandidateVerdict,
+} from "../skc-runtime/session-restore";
+import { buildRestoreCandidateDeps, restoreSession } from "../skc-runtime/session-restore-runtime";
 import {
 	attachSkcTmuxSession,
 	createSkcTmuxSession,
@@ -45,12 +54,13 @@ function sessionJson(session: SessionJsonDto): SessionJsonDto {
 }
 
 export default class Session extends Command {
-	static description = "List, inspect, attach, and remove tagged SKC-managed tmux sessions";
+	static description =
+		"List, inspect, attach, and remove tagged SKC-managed tmux sessions. `restore` is a manual, opt-in recovery step that only ever restores sessions this machine can prove died in a REBOOT: nothing starts automatically at login, a session that is still live is never duplicated, and running tools or background work are not recovered — only the tmux session, its directory, and its conversation.";
 	static strict = false;
 
 	static args = {
 		action: Args.string({
-			description: "list (default), status, create, attach, or remove",
+			description: "list (default), status, create, attach, remove, or restore",
 			required: false,
 		}),
 		session: Args.string({
@@ -67,6 +77,15 @@ export default class Session extends Command {
 		"state-file": Flags.string({
 			description: "Expected @skc-session-state-file tag for force-close (defense-in-depth match)",
 		}),
+		"dry-run": Flags.boolean({
+			description:
+				"restore: list candidates and their verdicts. Changes nothing at all (no tmux command, no lock, no database, no pointer write). This is the default when no --reference is given.",
+			default: false,
+		}),
+		reference: Flags.string({
+			description:
+				"restore: restore exactly one candidate by the opaque reference shown in --dry-run output. Refused unless that candidate is still reboot-eligible at this moment.",
+		}),
 	};
 
 	static examples = [
@@ -76,6 +95,8 @@ export default class Session extends Command {
 		"skc session attach <session>",
 		"skc session remove <session>",
 		"skc session force-close <session> --session-id <id>",
+		"skc session restore --dry-run   # list what a reboot left behind",
+		"skc session restore --reference <ref>   # restore exactly that one",
 	];
 
 	async run(): Promise<void> {
@@ -105,6 +126,71 @@ export default class Session extends Command {
 				return;
 			}
 
+			if (action === "restore") {
+				// Manual, reboot-proven, opt-in. Nothing here starts automatically at
+				// login, and a session is only ever restored when this host can prove
+				// the machine rebooted since that session was recorded.
+				const reference = flags.reference;
+				const decoded = reference ? decodeRestoreReference(reference) : null;
+				if (reference && !decoded) throw new Error("invalid_restore_reference");
+				const pointers = listRestorePointers().filter(
+					pointer =>
+						!decoded ||
+						(pointer.coordinator_session_id === decoded.coordinatorSessionId &&
+							pointer.state_file === decoded.stateFile),
+				);
+				if (reference && pointers.length === 0) throw new Error("restore_reference_not_found");
+				const verdicts = evaluateRestoreCandidates(pointers, buildRestoreCandidateDeps(readBootGeneration()));
+				const describe = (verdict: RestoreCandidateVerdict) => ({
+					reference: encodeRestoreReference(verdict.pointer.coordinator_session_id, verdict.pointer.state_file),
+					sessionId: verdict.pointer.skc_session_id,
+					cwd: verdict.pointer.cwd,
+					branch: verdict.pointer.branch,
+					eligible: verdict.eligible,
+					...(verdict.eligible ? {} : { reason: verdict.reason }),
+				});
+				// Dry run is the default reporting surface and performs zero mutation:
+				// no pointer write, no lock, no SQLite, no tmux command.
+				if (flags["dry-run"] || !reference) {
+					const rows = verdicts.map(describe);
+					if (json) {
+						writeJson({ ok: true, dryRun: true, candidates: rows });
+						return;
+					}
+					writeText(
+						rows.length === 0
+							? ["no restore candidates"]
+							: rows.map(row =>
+									[
+										row.eligible ? "restorable" : `skipped(${row.reason})`,
+										row.sessionId,
+										row.cwd,
+										row.reference,
+									].join("\t"),
+								),
+					);
+					return;
+				}
+				const verdict = verdicts[0];
+				if (!verdict) throw new Error("restore_reference_not_found");
+				if (!verdict.eligible) throw new Error(`restore_ineligible_${verdict.reason}`);
+				const outcome = restoreSession(verdict.pointer);
+				if (!outcome.ok) throw new Error(outcome.detail);
+				if (json) {
+					writeJson({
+						ok: true,
+						restored: {
+							sessionId: outcome.pointer.skc_session_id,
+							cwd: outcome.pointer.cwd,
+							tmuxSession: outcome.tmuxSession,
+						},
+					});
+					return;
+				}
+				writeText([`restored: ${outcome.tmuxSession} (${outcome.pointer.skc_session_id})`]);
+				return;
+			}
+
 			if (action === "create") {
 				const session = createSkcTmuxSession();
 				if (json) {

package/src/config/model-registry.ts

@@ -1032,6 +1032,13 @@ export class ModelRegistry {
 	#lastStaticLoadMtime: number | null = null;
 	#registeredProviderSources: Set<string> = new Set();
 	#providerDiscoveryStates: Map<string, ProviderDiscoveryState> = new Map();
+	/**
+	 * Monotonic per-provider discovery sequence. Overlapping refreshes for the
+	 * same provider can complete out of order; only the newest-started refresh
+	 * may publish discovery state or contribute models, so a slow stale fetch
+	 * never overwrites a fresher result.
+	 */
+	#providerDiscoverySequences: Map<string, number> = new Map();
 	#cacheDbPath?: string;
 	#suppressedSelectors: Map<string, number> = new Map();
 	#backgroundRefresh?: Promise<void>;
@@ -1815,11 +1822,15 @@ export class ModelRegistry {
 		providerConfig: DiscoveryProviderConfig,
 		strategy: ModelRefreshStrategy,
 	): Promise<Model<Api>[]> {
+		const sequence = (this.#providerDiscoverySequences.get(providerConfig.provider) ?? 0) + 1;
+		this.#providerDiscoverySequences.set(providerConfig.provider, sequence);
+		const isCurrentDiscovery = () => this.#providerDiscoverySequences.get(providerConfig.provider) === sequence;
 		const cached = readModelCache<Api>(providerConfig.provider, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
 		const requiresAuth = !this.#keylessProviders.has(providerConfig.provider);
 		if (requiresAuth) {
 			const apiKey = await this.#peekApiKeyForProvider(providerConfig.provider);
 			if (!isAuthenticated(apiKey)) {
+				if (!isCurrentDiscovery()) return [];
 				this.#providerDiscoveryStates.set(providerConfig.provider, {
 					provider: providerConfig.provider,
 					status: "unauthenticated",
@@ -1865,6 +1876,7 @@ export class ModelRegistry {
 				: result.models.length > 0
 					? "ok"
 					: "empty";
+		if (!isCurrentDiscovery()) return [];
 		this.#providerDiscoveryStates.set(providerId, {
 			provider: providerId,
 			status,

package/src/config/telegram-autostart.ts

@@ -10,11 +10,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getConfigRootDir, isCompiledBinary, logger } from "@sayknow-cli/utils";
-import { settings } from "./settings";
+import { settings as globalSettings, type Settings } from "./settings";
 import type { TelegramSettings } from "./settings-schema";
 import { telegramSettingsToEnv, validateTelegramSettings } from "./telegram-env-bridge";
 
-function readTelegramSettings(): TelegramSettings {
+/**
+ * The startup command runs against an explicit Settings instance (tests and
+ * embedders inject one), so read through it instead of the global proxy —
+ * which may not be initialized at all on those paths.
+ */
+type TelegramSettingsSource = Pick<Settings, "get">;
+
+function readTelegramSettings(settings: TelegramSettingsSource): TelegramSettings {
 	return {
 		enabled: settings.get("telegram.enabled"),
 		botToken: settings.get("telegram.botToken"),
@@ -69,10 +76,10 @@ function isAlreadyRunning(pidFile: string): boolean {
  * it in the background. Never throws — failures are logged as warnings so the
  * main skc session is unaffected.
  */
-export async function maybeAutostartTelegramRemote(): Promise<void> {
+export async function maybeAutostartTelegramRemote(settings: TelegramSettingsSource = globalSettings): Promise<void> {
 	if (!settings.get("telegram.enabled")) return;
 
-	const config = readTelegramSettings();
+	const config = readTelegramSettings(settings);
 	const errors = validateTelegramSettings(config);
 	if (errors.length > 0) {
 		logger.warn("Telegram Remote enabled but misconfigured, skipping autostart", { errors });