@sayknow-cli/coding-agent 0.5.1 → 0.5.6

package/dist/types/session/agent-session.d.ts

@@ -244,6 +244,8 @@ export interface AgentSessionConfig {
     /** Rebuild the SSH tool from current capability discovery results. */
     reloadSshTool?: () => Promise<AgentTool | null>;
     requestedToolNames?: ReadonlySet<string>;
+    /** True only when the caller explicitly selected no tools. */
+    explicitlyDisabledTools?: boolean;
     /** Optional per-session allowlist for tools exposed through search_tool_bm25. */
     discoverableToolAllowedNames?: readonly string[];
     /** Optional accessor for live MCP server instructions, injected as untrusted user-role request data. */
@@ -528,6 +530,7 @@ export declare class StreamingEditFileCache {
     has(path: string): boolean;
     get totalBytes(): number;
 }
+export declare function buildTodoWriteFailureReminder(errorText: string | undefined, failureCount: number): string;
 export declare class AgentSession {
     #private;
     readonly agent: Agent;
@@ -757,6 +760,8 @@ export declare class AgentSession {
     refreshSshTool(options?: {
         activateIfAvailable?: boolean;
     }): Promise<void>;
+    /** Whether the caller explicitly selected no tools for this session. */
+    hasExplicitlyDisabledTools(): boolean;
     /**
      * Set active tools by name.
      * Only tools in the registry can be enabled. Unknown tool names are ignored.
@@ -1208,6 +1213,8 @@ export declare class AgentSession {
     prepareContributionPrep(options?: ContributionPrepOptions): Promise<ContributionPrepResult>;
     /** Test seam: override the emergency-compaction resource sampler so tests never read real RSS. */
     setResourceSampler(sampler: () => EmergencyCompactionSample): void;
+    /** Test seam: drive the pre-prompt emergency/threshold check directly. */
+    runPrePromptContextCheckForTests(pendingMessages?: readonly AgentMessage[]): Promise<void>;
     setRetainedMemorySampler(sampler: (() => RetainedMemorySample) | undefined): void;
     /**
      * Toggle auto-compaction setting.
@@ -1346,10 +1353,12 @@ export declare class AgentSession {
      * Switch to a different session file.
      * Aborts current operation, loads messages, restores model/thinking.
      * Listeners are preserved and will continue receiving events.
+     * `requireIdle` rejects an active turn and fences new admissions for the transition.
      * @returns true if switch completed, false if cancelled by hook
      */
     switchSession(sessionPath: string, options?: {
         transition?: SessionSwitchEvent["transition"];
+        requireIdle?: boolean;
     }): Promise<boolean>;
     /**
      * Create a branch from a specific entry.

package/dist/types/session/internal/managed-session-scope.d.ts

@@ -120,7 +120,9 @@ export declare function fsyncCanonicalBinding(bindingPath: string, expected: str
 export declare function ensureManagedScope(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy): Promise<ManagedScopeResolution>;
 /** Synchronously create and validate the v2 binding before a default session writer exists. */
 export declare function prepareManagedSessionScopeForWriteSync(scope: ManagedScope, policy?: ManagedSessionSecurityPolicy, authority?: ManagedCandidateWriteAuthority): ManagedScopeResolution;
-export declare function listManagedCandidates(scope: ManagedScope): ManagedCandidateListing;
+export declare function listManagedCandidates(scope: ManagedScope, options?: {
+    maxCandidates?: number;
+}): ManagedCandidateListing;
 type DetachedArtifactRoot = {
     originalPath: string;
     detachedPath: string;

package/dist/types/session/internal/managed-session-storage.d.ts

@@ -74,6 +74,8 @@ export declare class ManagedSessionDescendantStore {
     appendSync(relativePath: string, bytes: Uint8Array): void;
     /** Read an exact managed file without exposing its pathname as authority. */
     readExpected(relativePath: string): ManagedFileSnapshot | null;
+    /** Read only the exact managed file size through the retained root authority. */
+    sizeSync(relativePath: string): number | null;
     /** Remove an exact captured file without reopening its pathname as authority. */
     removeExpected(relativePath: string, expected: ManagedFileSnapshot): void;
     /** Read and remove one managed descendant through retained authority. */

package/dist/types/session/session-manager.d.ts

@@ -705,6 +705,12 @@ export declare class SessionManager {
     listForResumePickerReadOnly(): Promise<SessionInfo[]>;
     getSessionId(): string;
     getSessionFile(): string | undefined;
+    /**
+     * Managed on-disk transcript size in bytes. Returns undefined when the
+     * destination is explicit, the file does not exist yet, or its identity
+     * cannot be verified.
+     */
+    getTranscriptFileBytes(): number | undefined;
     acquireMemoryGuardParticipantIngressLease(): MemoryGuardParticipantIngressLease;
     createMemoryGuardCheckpoint(input: MemoryGuardCreateCheckpointInput): Promise<MemoryGuardSessionManagerCheckpointV1>;
     /**
@@ -1048,6 +1054,9 @@ export declare class SessionManager {
         sessionDir?: string;
         storage?: SessionStorage;
         destination?: SessionDestination;
+        maxCandidates?: number;
+        maxTotalBytes?: number;
+        filterOtherWorkspaces?: boolean;
     }): StrictInventoryResult;
     /**
      * Propagate the storage-layer verified hard delete bound to exact identity evidence.

package/dist/types/session/session-storage.d.ts

@@ -110,6 +110,8 @@ export interface SessionStorage {
     readBytesSync?(path: string): Uint8Array;
     /** Exact bytes and descriptor-bound identity captured from one opened regular file. */
     readSnapshotSync?(path: string): SessionStorageSnapshot;
+    /** Exact descriptor-bound bytes, refusing growth or allocation beyond maxBytes. */
+    readSnapshotBoundedSync?(path: string, maxBytes: number): SessionStorageSnapshot;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     /** List matching files with mtimes without issuing one JavaScript stat call per path. */
@@ -122,6 +124,11 @@ export interface SessionStorage {
      * authorization inventory; the forgiving {@link listFilesSync} stays display-only.
      */
     listFilesStrictSync?(dir: string, pattern: string): string[];
+    /** Strict bounded scan; `truncated` means completeness was not granted. */
+    listFilesStrictBoundedSync?(dir: string, pattern: string, maxFiles: number): {
+        files: string[];
+        truncated: boolean;
+    };
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     readTextPrefix(path: string, maxBytes: number): Promise<string>;
@@ -270,6 +277,7 @@ export declare class FileSessionStorage implements SessionStorage {
     readTextSync(fpath: string): string;
     readBytesSync(fpath: string): Uint8Array;
     readSnapshotSync(fpath: string): SessionStorageSnapshot;
+    readSnapshotBoundedSync(fpath: string, maxBytes: number): SessionStorageSnapshot;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     listFilesByMtime(dir: string, pattern: string): Promise<Array<{
@@ -277,6 +285,10 @@ export declare class FileSessionStorage implements SessionStorage {
         mtimeMs: number;
     }>>;
     listFilesStrictSync(dir: string, pattern: string): string[];
+    listFilesStrictBoundedSync(dir: string, pattern: string, maxFiles: number): {
+        files: string[];
+        truncated: boolean;
+    };
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     readTextPrefix(path: string, maxBytes: number): Promise<string>;
@@ -306,6 +318,7 @@ export declare class MemorySessionStorage implements SessionStorage {
     readTextSync(path: string): string;
     readBytesSync(path: string): Uint8Array;
     readSnapshotSync(path: string): SessionStorageSnapshot;
+    readSnapshotBoundedSync(path: string, maxBytes: number): SessionStorageSnapshot;
     statSync(path: string): SessionStorageStat;
     listFilesSync(dir: string, pattern: string): string[];
     listFilesByMtime(dir: string, pattern: string): Promise<Array<{
@@ -313,6 +326,10 @@ export declare class MemorySessionStorage implements SessionStorage {
         mtimeMs: number;
     }>>;
     listFilesStrictSync(dir: string, pattern: string): string[];
+    listFilesStrictBoundedSync(dir: string, pattern: string, maxFiles: number): {
+        files: string[];
+        truncated: boolean;
+    };
     exists(path: string): Promise<boolean>;
     readText(path: string): Promise<string>;
     readTextPrefix(path: string, maxBytes: number): Promise<string>;

package/dist/types/session-import/claude.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Claude adapter (issue #3709).
+ *
+ * Parses two first-party observable Claude transcript/export shapes:
+ *
+ * 1. `claude-code-jsonl` — Claude Code session transcripts
+ *    (`~/.claude/projects/<project-slug>/<session-uuid>.jsonl`), one JSON object
+ *    per line with `type: "user" | "assistant" | "summary" | "system" | …`.
+ * 2. `claude-export-json` — the claude.ai data export (`conversations.json`):
+ *    a JSON array of conversations (or a single conversation object) whose
+ *    `chat_messages` carry `sender: "human" | "assistant"` and `content` blocks.
+ *
+ * The same quarantine contract as the Codex adapter applies: unmappable
+ * records/messages are counted and digested, never silently dropped.
+ */
+import { type ImportedConversation, type ImportQuarantineRecord, type SessionImportCounts } from "./types";
+export interface ClaudeParseResult {
+    conversation: ImportedConversation;
+    quarantine: ImportQuarantineRecord[];
+    counts: SessionImportCounts;
+    redactionKinds: string[];
+}
+/** Parse a Claude Code session JSONL transcript. */
+export declare function parseClaudeCodeTranscript(text: string): ClaudeParseResult;
+/** Parse a claude.ai data-export conversation (array or single object). */
+export declare function parseClaudeExport(text: string): ClaudeParseResult;

package/dist/types/session-import/codex.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Codex adapter (issue #3709).
+ *
+ * Parses the Codex CLI rollout transcript: one JSON object per line
+ * (`rollout-*.jsonl`, e.g. `~/.codex/sessions/2026/08/01/rollout-….jsonl`).
+ * This is Codex's own observable transcript format; the file the user passes is
+ * treated as an explicit export and is only read.
+ *
+ * Strictness contract: records that fail to parse or lack required fields are
+ * quarantined with deterministic digests — never silently dropped. Unknown
+ * record/event types are mapped when their payload shape is recognized and
+ * quarantined otherwise.
+ */
+import { type ImportedConversation, type ImportQuarantineRecord, type SessionImportCounts } from "./types";
+export interface CodexParseResult {
+    conversation: ImportedConversation;
+    quarantine: ImportQuarantineRecord[];
+    counts: SessionImportCounts;
+    redactionKinds: string[];
+}
+/** Parse a Codex rollout JSONL transcript into the provider-neutral IR. */
+export declare function parseCodexRollout(text: string): CodexParseResult;

package/dist/types/session-import/command.d.ts

@@ -0,0 +1,20 @@
+import type { SessionImportCompleted, SessionImportProviderId } from "./types";
+export declare const IMPORT_SESSION_USAGE = "Usage: /import-session <transcript-file> [--provider codex|claude]";
+export type ParsedImportSessionArgs = {
+    kind: "ok";
+    sourcePath: string;
+    provider?: SessionImportProviderId;
+} | {
+    kind: "error";
+    message: string;
+};
+export declare function parseImportSessionArgs(args: string): ParsedImportSessionArgs;
+export type SessionImportCommandOutcome = {
+    kind: "imported";
+    result: SessionImportCompleted;
+} | {
+    kind: "error";
+    message: string;
+};
+/** Imports a new session only. The caller owns the current-session switch/resume seam. */
+export declare function runSessionImportCommand(args: string, cwd: string): Promise<SessionImportCommandOutcome>;

package/dist/types/session-import/detect.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Deterministic source-format detection (issue #3709).
+ *
+ * Detection inspects only the already-read source bytes: a bounded leading
+ * sample decides JSONL-vs-JSON and provider by envelope markers. An explicit
+ * `--provider` selection narrows candidates; a sample that matches a different
+ * provider than requested fails closed with `format_mismatch`. Detection never
+ * guesses: a sample matching no supported envelope fails with
+ * `unsupported_format` rather than falling back to a speculative parse.
+ */
+import { type SessionImportFormatId, type SessionImportProviderId } from "./types";
+export interface SessionImportDetection {
+    provider: SessionImportProviderId;
+    format: SessionImportFormatId;
+}
+/**
+ * Detect the provider/format of an explicit transcript file.
+ *
+ * @param text Full source text (already size-bounded by the caller).
+ * @param requestedProvider Explicit provider selection; undefined = auto.
+ */
+export declare function detectSessionImportFormat(text: string, requestedProvider?: SessionImportProviderId): SessionImportDetection;

package/dist/types/session-import/index.d.ts

@@ -0,0 +1,7 @@
+export { type ClaudeParseResult, parseClaudeCodeTranscript, parseClaudeExport } from "./claude";
+export { type CodexParseResult, parseCodexRollout } from "./codex";
+export { IMPORT_SESSION_USAGE, type ParsedImportSessionArgs, parseImportSessionArgs, runSessionImportCommand, type SessionImportCommandOutcome, } from "./command";
+export { detectSessionImportFormat, type SessionImportDetection } from "./detect";
+export { IMPORT_SANITIZER_VERSION, redactImportedText, sanitizeImportedString } from "./redact";
+export { formatSessionImportError, formatSessionImportSummary, IMPORT_CONVERTER_VERSION, importExternalSession, materializeSessionImport, prepareSessionImport, SESSION_IMPORT_COMPLETION_CUSTOM_TYPE, SESSION_IMPORT_CONTEXT_CUSTOM_TYPE, SESSION_IMPORT_PROVENANCE_CUSTOM_TYPE, SESSION_IMPORT_QUARANTINE_CUSTOM_TYPE, SESSION_IMPORT_SOURCE_MAX_BYTES, type SessionImportRequest, type SessionImportTestProbe, } from "./service";
+export * from "./types";

package/dist/types/session-import/redact.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fail-closed secret redaction for imported session content (issue #3709).
+ *
+ * Every string that crosses the import boundary passes through
+ * {@link redactImportedText}. Patterns are conservative: a false positive costs
+ * one `[REDACTED]` span in reconstructed context, a false negative leaks a
+ * credential into a new session transcript, so the balance favors redaction.
+ */
+export declare const IMPORT_REDACTED_PLACEHOLDER = "[REDACTED]";
+/** Bumped when patterns change; persisted in import provenance. */
+export declare const IMPORT_SANITIZER_VERSION = 3;
+export interface ImportRedactionResult {
+    value: string;
+    redacted: number;
+    kinds: string[];
+}
+/**
+ * Redact every known credential shape from imported text. The same placeholder
+ * is used for all kinds so a partial pattern overlap cannot leak fragments.
+ */
+export declare function redactImportedText(input: string): ImportRedactionResult;
+/** Redact a string, returning only the sanitized value. */
+export declare function sanitizeImportedString(input: string): string;

package/dist/types/session-import/service.d.ts

@@ -0,0 +1,28 @@
+import { type SessionDestinationInput } from "../session/session-manager";
+import { type PreparedSessionImport, type SessionImportCompleted, type SessionImportProviderId } from "./types";
+export declare const IMPORT_CONVERTER_VERSION = 1;
+/** Durable metadata only; it is not added to model context. */
+export declare const SESSION_IMPORT_PROVENANCE_CUSTOM_TYPE = "session-import";
+export declare const SESSION_IMPORT_QUARANTINE_CUSTOM_TYPE = "session-import-quarantine";
+export declare const SESSION_IMPORT_COMPLETION_CUSTOM_TYPE = "session-import-complete";
+/** Displayed custom-message context reconstructed from the imported transcript. */
+export declare const SESSION_IMPORT_CONTEXT_CUSTOM_TYPE = "session-import";
+export declare const SESSION_IMPORT_SOURCE_MAX_BYTES: number;
+export interface SessionImportRequest {
+    sourcePath: string;
+    provider?: SessionImportProviderId;
+    cwd: string;
+    destination?: SessionDestinationInput;
+    now?: () => Date;
+}
+/** Invocation-scoped mutation seam used only by TOCTOU regression tests. */
+export interface SessionImportTestProbe {
+    afterSourceOpen?: (resolvedSourcePath: string) => void | Promise<void>;
+    afterSourceIdentityCheck?: (resolvedSourcePath: string) => void | Promise<void>;
+}
+/** Read, detect, parse, normalize, redact, and bound without session mutation. */
+export declare function prepareSessionImport(request: Pick<SessionImportRequest, "sourcePath" | "provider">, testProbe?: SessionImportTestProbe): Promise<PreparedSessionImport>;
+export declare function importExternalSession(request: SessionImportRequest): Promise<SessionImportCompleted>;
+export declare function materializeSessionImport(prepared: PreparedSessionImport, options: Pick<SessionImportRequest, "cwd" | "destination" | "now">): Promise<SessionImportCompleted>;
+export declare function formatSessionImportSummary(result: SessionImportCompleted): string;
+export declare function formatSessionImportError(error: unknown): string;

package/dist/types/session-import/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Provider-neutral session-import contract (issue #3709).
+ *
+ * An import accepts ONE explicit user-selected Codex or Claude transcript/export
+ * file, normalizes it into the intermediate representation below, and rebuilds a
+ * bounded, redacted continuation context in one workspace-scoped native SKC
+ * session. A verified identical import is reused; otherwise a new session is
+ * published. The source file is only ever read; provider process state is never scraped.
+ */
+/** Providers with a first-party observable transcript/export format. */
+export type SessionImportProviderId = "codex" | "claude";
+/** Concrete on-disk format variants the adapters understand. */
+export type SessionImportFormatId = "codex-rollout-jsonl" | "claude-code-jsonl" | "claude-export-json";
+/** Maximum quarantined-record digests retained in memory during import. */
+export declare const SESSION_IMPORT_QUARANTINE_MAX_RECORDS = 512;
+/** One normalized conversational unit produced by a provider adapter. */
+export interface ImportedMessage {
+    /** Conversational role. Tool evidence is attached to assistant turns. */
+    role: "user" | "assistant";
+    /** Visible text (may be empty when only tool evidence exists). */
+    text: string;
+    /** ISO-8601 source timestamp when the record carried one. */
+    timestamp?: string;
+    /**
+     * Bounded, already redacted tool/file evidence lines (e.g. `$ ls` → `ok`).
+     * Rendered inline after the text so completed work stays visible.
+     */
+    toolEvidence?: string[];
+}
+/** Provider-neutral normalized conversation. */
+export interface ImportedConversation {
+    provider: SessionImportProviderId;
+    format: SessionImportFormatId;
+    /** Source-side session/conversation identifier when the format carries one. */
+    sourceSessionId?: string;
+    /** Source title when the format carries one. */
+    title?: string;
+    /** Source workspace cwd when the format carries one. */
+    cwd?: string;
+    messages: ImportedMessage[];
+}
+/** Deterministic, actionable import failure codes. */
+export type SessionImportErrorCode = "invalid_request" | "source_not_found" | "source_unreadable" | "source_changed" | "unsupported_format" | "format_mismatch" | "malformed_input" | "content_too_large" | "destination_conflict" | "io_failed";
+/** Import pipeline phase a failure belongs to. */
+export type SessionImportPhase = "request" | "read" | "detect" | "parse" | "normalize" | "persist" | "cleanup" | "switch";
+export declare class SessionImportError extends Error {
+    readonly code: SessionImportErrorCode;
+    readonly phase: SessionImportPhase;
+    readonly retryable: boolean;
+    readonly limitBytes?: number;
+    readonly observedBytes?: number;
+    constructor(code: SessionImportErrorCode, phase: SessionImportPhase, message: string, options?: {
+        retryable?: boolean;
+        limitBytes?: number;
+        observedBytes?: number;
+    });
+}
+/** One record the adapter could not map. Never carries raw content. */
+export interface ImportQuarantineRecord {
+    /** 1-based record/line number in the source. */
+    record: number;
+    byteLength: number;
+    sha256: string;
+    reason: "invalid_json" | "unknown_record" | "missing_fields" | "oversized_record";
+}
+/** Bounded tallies reported to the user and persisted in provenance. */
+export interface SessionImportCounts {
+    /** Records successfully mapped into the normalized conversation. */
+    mapped: number;
+    /** Records quarantined (never silently dropped). */
+    quarantined: number;
+    /** Secret/credential redactions applied to imported text. */
+    redacted: number;
+    /** Messages omitted from the rendered context by head/tail bounding. */
+    omitted: number;
+}
+/** Provenance persisted as a `custom` session entry on the import target. */
+export interface SessionImportProvenance {
+    schemaVersion: 1;
+    customType: "session-import";
+    provider: SessionImportProviderId;
+    format: SessionImportFormatId;
+    /** Basename of the explicit user-selected source file (never a full path). */
+    sourceFileName: string;
+    sourceSessionId?: string;
+    sourceTitle?: string;
+    /** SHA-256 over the exact source bytes that were imported. */
+    sourceSha256: string;
+    sourceBytes: number;
+    /** RFC 4122 UUID of the SKC session that received the import. */
+    targetSessionId: string;
+    importedAt: string;
+    converterVersion: number;
+    sanitizerVersion: number;
+    counts: SessionImportCounts;
+    /** True when head/tail bounding elided part of the conversation. */
+    truncated: boolean;
+    quarantine: {
+        present: boolean;
+        truncated: boolean;
+    };
+}
+/** Fully prepared import: parsed, normalized, redacted, bounded. No session state mutated yet. */
+export interface PreparedSessionImport {
+    conversation: ImportedConversation;
+    /** Rendered continuation context for the `custom_message` entry. */
+    contextText: string;
+    provenance: Omit<SessionImportProvenance, "targetSessionId" | "importedAt">;
+    counts: SessionImportCounts;
+    /** Distinct redaction pattern ids that fired (for the user-facing summary). */
+    redactionKinds: string[];
+    /** Bounded digest-only records for durable quarantine metadata. */
+    quarantineRecords: ImportQuarantineRecord[];
+    sourceSha256: string;
+    sourceBytes: number;
+}
+/** Result of a completed or idempotently reused imported session. */
+export interface SessionImportCompleted {
+    targetSessionId: string;
+    targetPath: string;
+    title: string;
+    prepared: PreparedSessionImport;
+    /** True when the same source/version import already existed in this workspace. */
+    reused: boolean;
+}

package/dist/types/skc-runtime/boot-generation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Boot-generation evidence for reboot-only session restore.
+ *
+ * Restore exists to survive a reboot, and only a reboot. The eligibility rule is
+ * therefore narrow on purpose: a session may be restored only when the recorded
+ * and current boot values come from the SAME source and differ. Anything else —
+ * equal values, a missing or malformed record, an unreadable probe, or two
+ * different sources — is inconclusive and must never spawn.
+ *
+ * The same-source requirement is not pedantry. Linux can report `boot-id` at
+ * record time and fall back to `proc-btime` later; those two values are always
+ * unequal even on one boot, so comparing across sources would read every launch
+ * as a reboot and duplicate live sessions.
+ */
+/** Where a boot value came from. Values are only ever compared within one source. */
+export type BootGenerationSource = "darwin-kern-boottime" | "linux-boot-id" | "linux-proc-btime" | "unavailable";
+export interface BootGeneration {
+    source: BootGenerationSource;
+    /** Opaque; only equality within the same source is meaningful. */
+    value: string | null;
+}
+export type BootComparison = "changed" | "same_boot" | "boot_unknown";
+export interface RecordedBootGeneration {
+    schema_version: number;
+    source: string;
+    value: string;
+}
+export interface BootGenerationProbeDeps {
+    platform?: NodeJS.Platform;
+    readFile?: (file: string) => string;
+    runCommand?: (command: string, args: string[]) => {
+        exitCode: number | null;
+        stdout: string;
+    };
+}
+/** `{ sec = 1785305532, usec = 377197 } Wed Jul 29 ...` -> `1785305532.377197`. */
+export declare function parseDarwinBootTime(raw: string): string | null;
+/** A boot id is a UUID that changes on every boot; anything else is not usable. */
+export declare function parseLinuxBootId(raw: string): string | null;
+/** `/proc/stat` carries `btime <seconds>` once, as the kernel boot wall-clock. */
+export declare function parseLinuxProcBtime(raw: string): string | null;
+/**
+ * Reads the strongest boot evidence this platform offers.
+ *
+ * Windows returns `unavailable`: restore is unsupported there (no immutable
+ * native tmux session identity), so there is nothing to gate.
+ */
+export declare function readBootGeneration(deps?: BootGenerationProbeDeps): BootGeneration;
+export declare function isBootValueWellFormed(source: string, value: string): boolean;
+export declare function isRecordedBootGeneration(value: unknown): value is RecordedBootGeneration;
+export declare function recordBootGeneration(current: BootGeneration): RecordedBootGeneration | null;
+/**
+ * Decides whether the machine rebooted since the session was recorded.
+ *
+ * `changed` is the ONLY executable answer. It requires a well-formed record, a
+ * readable current probe, an identical source, and different values. Source
+ * mismatch is deliberately `boot_unknown` rather than `changed`.
+ */
+export declare function compareBootGeneration(recorded: unknown, current: BootGeneration): BootComparison;

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

@@ -30,14 +30,16 @@ export interface TmuxSpawnResult {
     exitCode: number | null;
     signalCode?: string | null;
     stderr?: string;
+    /** Populated only when the caller asked for `stdout: "pipe"`. */
+    stdout?: string;
 }
 export type TmuxSpawnSync = (command: string, args: string[], options: TmuxSpawnOptions) => TmuxSpawnResult;
 export interface TmuxSpawnOptions {
     cwd: string;
     env: NodeJS.ProcessEnv;
     stdin: "inherit";
-    stdout: "inherit";
-    stderr: "inherit";
+    stdout: "inherit" | "pipe";
+    stderr: "inherit" | "pipe";
 }
 export interface TmuxLaunchPlan {
     tmuxCommand: string;
@@ -50,6 +52,12 @@ export interface TmuxLaunchPlan {
     project?: string | null;
     sessionId?: string | null;
     sessionStateFile?: string | null;
+    /**
+     * Capability of the RESOLVED provider, not a platform guess. psmux has no
+     * immutable native session identity, so it stays outside the native-proof
+     * create fence and keeps its existing spawn/profile/attach behavior.
+     */
+    isPsmux: boolean;
 }
 export interface SkcTmuxProfileResult {
     skipped: boolean;

package/dist/types/skc-runtime/launch-worktree.d.ts

@@ -20,6 +20,9 @@ export interface SkcLaunchWorktreePlan {
     detached: boolean;
     baseRef: string;
     branchName: string | null;
+    sourceCheckoutRoot: string;
+    relativeCwd: string;
+    relativeDependencyRoot: string | null;
 }
 export interface SkcLaunchWorktreeResult extends SkcLaunchWorktreePlan {
     created: boolean;
@@ -36,7 +39,19 @@ export declare function ensureLaunchWorktree(plan: SkcLaunchWorktreePlan | {
 }): SkcLaunchWorktreeResult | {
     enabled: false;
 };
-export declare function ensureReusableNodeModules(sourceRoot: string, worktreePath: string): "symlink" | "present" | "missing";
+type WorktreePackageManager = "bun" | "npm" | "pnpm";
+interface WorktreeDependencyProbes {
+    isExecutableAvailable?: (name: Exclude<WorktreePackageManager, "bun">) => boolean;
+    version?: (name: WorktreePackageManager) => string;
+    spawnInstall?: (command: readonly string[], cwd: string) => {
+        exitCode: number;
+        stderr: string;
+    };
+}
+/** Package worktrees own their complete lockfile-resolved dependency graph. */
+export declare function ensureReusableNodeModules(sourceRoot: string, worktreePath: string, probes?: WorktreeDependencyProbes): "symlink" | "present" | "missing";
+export declare function launchWorktreeCwd(plan: SkcLaunchWorktreePlan): string;
+export declare function ensureLaunchWorktreeDependencies(plan: SkcLaunchWorktreePlan): "symlink" | "present" | "missing";
 /** Result of {@link prepareLaunchWorktree}: the effective working directory, remaining args, and resolved worktree plan. */
 export interface PreparedLaunchWorktree {
     cwd: string;
@@ -46,3 +61,4 @@ export interface PreparedLaunchWorktree {
     };
 }
 export declare function prepareLaunchWorktree(cwd: string, args: string[]): PreparedLaunchWorktree;
+export {};

package/dist/types/skc-runtime/session-restore-runtime.d.ts

@@ -0,0 +1,41 @@
+import type { BootGeneration } from "./boot-generation";
+import { type RestoreCandidateDeps, type RestorePointer, type RestoreSidecarFacts } from "./session-restore";
+/**
+ * Strict re-read of the sidecar a pointer names.
+ *
+ * Returns null for missing, unreadable, or malformed content: restore must never
+ * infer a session's identity from the pointer alone.
+ */
+export declare function readSidecarFacts(pointer: RestorePointer): RestoreSidecarFacts | null;
+/**
+ * True when a tmux session already carries this exact coordinator identity.
+ *
+ * An unreadable tmux is reported as a collision on purpose: not being able to
+ * see the server is not evidence that the identity is free.
+ */
+export declare function hasLiveIdentity(pointer: RestorePointer, env?: NodeJS.ProcessEnv): boolean;
+/** psmux exposes no immutable native session identity, so restore cannot prove ownership there. */
+export declare function ownerProofAvailable(env?: NodeJS.ProcessEnv): boolean;
+export declare function buildRestoreCandidateDeps(currentBoot: BootGeneration, env?: NodeJS.ProcessEnv): RestoreCandidateDeps;
+export type RestoreOutcome = {
+    ok: true;
+    pointer: RestorePointer;
+    tmuxSession: string;
+} | {
+    ok: false;
+    pointer: RestorePointer;
+    code: string;
+    detail: string;
+};
+/**
+ * Restores exactly one eligible candidate.
+ *
+ * Deliberately goes through the ordinary fenced creator rather than spawning
+ * tmux directly: restore must inherit the same identity fence, owner-isolation
+ * proof, and exact cleanup as every other producer. The only differences are the
+ * working directory and the `--resume` argv handed to the child.
+ *
+ * Never cleans up another owner's session. A fence refusal is reported and the
+ * candidate is skipped.
+ */
+export declare function restoreSession(pointer: RestorePointer, env?: NodeJS.ProcessEnv): RestoreOutcome;