@sayknow-cli/coding-agent 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,163 @@ This file tracks the **fork's own releases**; upstream's full feature history li
 in that project. Each release notes the upstream version it is built on.
 
 
+## [Unreleased]
+
+## [0.5.2] — 2026-08-14
+
+Built on upstream **gajae-code v0.12.0**.
+
+### Fixed (unattended workflow gates were unanswerable through the control plane)
+
+`UnattendedSessionControlPlane.emitGate` opened gates without a broker
+continuation, so every gate it emitted was quarantined as
+`opened_without_continuation` and could never be answered; its `advance` hook
+also settled the waiter early, violating the broker's post-advance liveness
+check, and accepted gates then failed terminalization for lack of a proof. The
+control plane now registers a live continuation, settles waiters in
+`completeAccepted` (mirroring the session-side emitter), and declares the
+designed `not_published` terminal proof. The ask tool regained the fork's gate
+semantics on top of that: a negotiated unattended emitter wins over an attended
+UI, clarification answers surface the user's question instead of aborting as a
+cancel, multi-select keeps its empty-"Next" semantics through the gate schema,
+and gate metadata carries the Next/Done navigation label again.
+
+### Fixed (ask wire schema: deep-interview intent branches and gate addressing)
+
+The deep-interview intent contract is enforced **on the wire** again: ask's
+`deepInterview` metadata is a union of three mutually exclusive strict branches
+(ordinary round / Round-0 `intent_contract` locked to `component:
+"review-topology"` / post-Round-0 `intent_review` with `round >= 1`), so a
+provider that only sees the JSON schema cannot combine a manifest lock with a
+reduction review or attach either to the wrong round. Questions also regained
+the `workflowGate` stage/kind override for addressing non-deep-interview gates,
+and such overridden questions are excluded from the interview recorder.
+
+### Fixed (`SKC_PY` / `PI_PY` / `PI_JS` eval backend selection was ignored)
+
+`resolveEvalBackends` existed but the eval tool never called it: backend
+allowance was read from settings only, so `SKC_PY=js` still spawned the Python
+kernel. The tool now resolves allowance through the documented precedence
+(`SKC_PY`, then legacy `PI_PY`/`PI_JS`, then `eval.py`/`eval.js` settings).
+
+### Fixed (stale model discovery result could overwrite a fresher one)
+
+Overlapping `refreshProvider` calls for the same provider raced without any
+ordering guard: whichever fetch *completed* last published its discovery state
+and model list, so a slow stale response could erase the models a fresher
+refresh had just delivered. Discovery now carries a monotonic per-provider
+sequence and only the newest-started refresh may publish state or contribute
+models.
+
+### Fixed (post-merge repair: type-check and test contracts realigned)
+
+The upstream merges left the workspace `check` red for several releases: test
+files frozen at fork v0.4.7 kept exercising APIs their source had since dropped
+(session-sticky canonical model resolution, `getSelectorSuppressionStatus`,
+`refreshPresetProfiles`, the pre-broker in-process `AcpAgent`, the fork-era
+bridge-client `WorkflowGate` surface). Stale suites superseded by current
+coverage were removed, the survivors were realigned to the shipped APIs, the
+form-elicitation bridge kept its only coverage via a ported focused suite, the
+`node-pty` dev dependency the merge dropped from `@sayknow-cli/tui` is restored,
+and the extracted model helper modules (`config/model-auth`,
+`config/model-bindings-applier`, `config/model-discovery-manager`) are now
+explicitly unexported, matching the documented package surface.
+
+### Fixed (todo_write truncation and retry loops)
+
+Structurally complete JSON tool calls now execute even when a Responses provider
+hits its output-token limit before emitting the final item event. Invalid todo
+payloads retry at most once, while transport failures and repeated errors fail
+open so the requested work continues without visible todo tracking.
+
+### Fixed (v0.5.0 upstream merge reverted the fork's tmux graphics support)
+
+The v0.12.0 upstream merge overwrote `packages/tui/src/tui.ts` and silently
+dropped three fork-only behaviors, which is why the pet was unavailable in every
+tmux session and `packages/tui/test/sixel-probe.test.ts` shipped with three
+failing tests:
+
+- the capability probe refused to run under any multiplexer, so
+  `isSixelMultiplexerEnabled()` became dead code
+- the sixel probe was no longer wrapped in tmux's DCS passthrough envelope, so
+  tmux answered for a client it knows nothing about
+- the `CSI 16 t` cell-size query lost its passthrough wrapper (the v0.4.6 fix),
+  so tmux reported a cell size the outer terminal never uses
+
+All three are restored, with the probe deadline back at 600 ms under tmux to
+cover the passthrough round trip.
+
+### Fixed (transcript images stacked over the text under tmux)
+
+Enabling the sixel probe under tmux also switched INLINE graphics on, and the
+inline path wrapped every raster in the DCS passthrough envelope. Passthrough
+writes pixels straight into the OUTER terminal's image plane at its *physical*
+cursor: tmux neither positions that cursor for the pane nor records the pixels,
+so tool-result screenshots landed in the wrong row and survived every repaint —
+each render stacked another copy over the transcript.
+
+Inline placements now follow the same ownership rule the pet already used:
+
+- tmux advertising the `sixel` terminal-feature (which the SKC tmux profile sets
+  automatically) parses the raster into its own screen model, so the raster is
+  written raw and scroll / erase / resize move the image with its text.
+- Without that feature the inline render returns the `[image/png …]` placeholder
+  instead. An image welded to the outer terminal's physical cursor for the rest
+  of the session is worse than no image.
+- Absolutely positioned overlays (the pet) are unaffected: they carry their own
+  coordinates through the envelope and remain the only passthrough user.
+
+### Added (Sayknow Pet under tmux on kitty-protocol terminals)
+
+Ghostty, Kitty and WezTerm implement kitty graphics and no sixel at all, so the
+sixel probe alone left them with no pet inside tmux. SKC now also forwards a
+kitty capability query (`a=q`) through the passthrough envelope. tmux cannot
+answer it on the terminal's behalf — it does not implement the protocol — so an
+`OK` coming back is genuine end-to-end evidence, unlike tmux's compile-time DA1
+sixel claim.
+
+- A successful query enables a dedicated **overlay** channel
+  (`setTmuxOverlayImageProtocol`) rather than inline image rendering: absolutely
+  positioned art can carry its own cursor addressing through the envelope, while
+  inline placements would land at tmux's stale physical cursor.
+- Overlay payloads now carry the pane origin (`#{pane_top}`, `#{pane_left}`, and
+  top status lines), so a split window or a top status bar no longer draws the
+  pet in the wrong place. This also fixes the pre-existing sixel-fallback path.
+- `allow-passthrough` is requested pane-locally at startup, so a tmux pane the
+  user created by hand works without manual configuration.
+- Kill switch: `SKC_KITTY_MULTIPLEXER=0`.
+- The tmux-specific unavailable warning no longer tells users to leave the
+  multiplexer or to force sixel; it names the actual requirement.
+
+Verified end to end on Ghostty 1.3.1 + tmux 3.6b: pane passthrough is enabled
+automatically, the probe reports `ImageProtocol.Kitty`, and the outer terminal's
+real cell metrics (16x34) replace the 9x18 default.
+
+## [0.5.1] — 2026-07-29
+
+Built on upstream **gajae-code v0.12.0**.
+
+### Fixed (Sayknow Pet still left sixel residue under tmux)
+
+0.5.0 gave tmux ownership of the pet's sixel, which is the real fix — but it only
+takes effect for a client that attaches *after* the feature is set, because tmux
+computes client features at attach time. Every already-attached client kept
+falling back to DCS passthrough, and that fallback still erased at tmux level
+while its pixels lived in the outer terminal. So the residue persisted for
+exactly the people who already had a session open.
+
+- **The erase now rides the same envelope as the draw.** When the frame goes out
+  through passthrough, the erase does too, reaching the terminal that actually
+  holds the image; the absolute coordinates match because the draw used the same
+  ones. When tmux owns the sixel, the erase stays at tmux level as before.
+- **`terminal-features` is set with the correct scope.** It is a *server* option,
+  so the previous `set-option -aq -t <target>` silently ignored the target. Now
+  `set-option -saq`.
+- Added a regression test that pins the multiplexer environment and asserts draw
+  and erase share one envelope. The pet suite previously inherited whatever
+  terminal the developer ran it in, so it passed on CI and failed inside tmux;
+  the environment is now pinned per test.
+
 ## [0.5.0] — 2026-07-28
 
 Built on upstream **gajae-code v0.12.0** (previous fork release tracked v0.11.6).

package/dist/types/commands/session.d.ts

@@ -24,6 +24,13 @@ export default class Session extends Command {
         "state-file": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
+        "dry-run": import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        reference: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
     };
     static examples: string[];
     run(): Promise<void>;

package/dist/types/config/telegram-autostart.d.ts

@@ -6,9 +6,17 @@
  * process, tracks its PID so repeated skc invocations don't double-spawn,
  * and redirects output to a log file under the config root.
  */
+import { type Settings } from "./settings";
+/**
+ * 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">;
 /**
  * If `telegram.enabled` is true and the gateway is not already running, spawn
  * it in the background. Never throws — failures are logged as warnings so the
  * main skc session is unaffected.
  */
-export declare function maybeAutostartTelegramRemote(): Promise<void>;
+export declare function maybeAutostartTelegramRemote(settings?: TelegramSettingsSource): Promise<void>;
+export {};

package/dist/types/modes/components/pet-capability.d.ts

@@ -9,15 +9,16 @@ export declare function isPetAvailable(): boolean;
 export declare function createPetSelectItems(options: ReadonlyArray<SelectItem>, currentValue: string, available: boolean): SelectItem[];
 /**
  * Grace period before declaring the terminal pet-incapable at startup. The
- * asynchronous Sixel capability probe starts inside `TUI.start()` and answers
- * within its own 250 ms deadline; this margin covers probe scheduling so a
- * supported terminal is never told it is incompatible while the probe is
- * still in flight.
+ * asynchronous capability probes start inside `TUI.start()` and answer within
+ * their own deadline (250 ms directly, 600 ms through tmux passthrough); this
+ * margin covers probe scheduling so a supported terminal is never told it is
+ * incompatible while a probe is still in flight.
  */
-export declare const PET_CAPABILITY_SETTLE_MS = 1000;
+export declare const PET_CAPABILITY_SETTLE_MS = 1500;
 /**
- * Whether the asynchronous startup Sixel capability probe may still enable
- * graphics for this session, meaning current unavailability is not final.
+ * Whether an asynchronous startup capability probe (Sixel, or Kitty through
+ * tmux passthrough) may still enable graphics for this session, meaning current
+ * unavailability is not final.
  */
 export declare function isPetCapabilityProbePending(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**

package/dist/types/modes/components/pet-selector.d.ts

@@ -1,7 +1,7 @@
 import { Container, type SelectList } from "@sayknow-cli/tui";
 import type { PetMode } from "./sayknow-pet-widget";
 /**
- * Theme-style picker for the sayknow pet skin (Off / RedSayknow / BlueSayknow). Preview
+ * Theme-style picker for the sayknow pet skin (Off / RedOctopus / BlueOctopus). Preview
  * fires as the selection moves; select commits, cancel restores.
  */
 export declare class PetSelectorComponent extends Container {

package/dist/types/modes/components/sayknow-pet-widget.d.ts

@@ -50,7 +50,7 @@ export declare class SayknowPetWidget {
     setMode(mode: PetMode): void;
     /** Live preview during a selector: change the sprite without re-mounting the
      *  composer editor (that would tear down the open overlay). After a short idle
-     *  eye-roll it fires the signature burst once (RedSayknow flex, BlueSayknow para-para
+     *  eye-roll it fires the signature burst once (RedOctopus flex, BlueOctopus para-para
      *  then sob) so the selector demos the animation instead of waiting the random gap. */
     previewMode(mode: PetMode): void;
     commitPreviewMode(mode: PetMode): void;

package/dist/types/modes/shared/agent-wire/unattended-session.d.ts

@@ -67,6 +67,12 @@ export declare function modelSupportsTokenCostMetrics(model: Model | undefined):
 export interface WorkflowGateEmitter {
     /** True only when unattended mode has been negotiated. */
     isUnattended(): boolean;
+    /**
+     * True when gates emitted through this emitter can be answered remotely
+     * (workflow_gate_response over RPC/bridge). The ask tool refuses headless
+     * execution unless this reports true.
+     */
+    supportsRemoteGateAnswers(): boolean;
     /** Open + emit a gate; resolves with the agent's answer (from workflow_gate_response). */
     emitGate(input: OpenGateInput): Promise<unknown>;
     /**
@@ -107,6 +113,7 @@ export declare class UnattendedSessionControlPlane implements RpcUnattendedContr
     private readonly opts;
     constructor(opts: UnattendedSessionOptions);
     isUnattended(): boolean;
+    supportsRemoteGateAnswers(): boolean;
     /** Observe every emitted gate (e.g. so an extension can map an ask to its gate_id). */
     onGateEmitted(listener: (gate: RpcWorkflowGate) => void): () => void;
     get controller(): UnattendedRunController | undefined;

package/dist/types/modes/shared/agent-wire/workflow-gate-broker.d.ts

@@ -60,6 +60,8 @@ export interface AskSelectedAckRecoveryParticipant {
 /** SDK-native surface for emitting a workflow gate and awaiting its answer. */
 export interface WorkflowGateEmitter {
     supportsRemoteGateAnswers(): boolean;
+    /** True when an unattended run has been negotiated for this emitter (control-plane emitters). */
+    isUnattended?(): boolean;
     emitGate(input: OpenGateInput): Promise<unknown>;
     onGateEmitted?(listener: (gate: WorkflowGate) => void): () => void;
     resolveGate?(response: WorkflowGateResponse): Promise<WorkflowGateResolution>;

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

@@ -528,6 +528,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;

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/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;

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

@@ -0,0 +1,99 @@
+import { type BootGeneration, type RecordedBootGeneration } from "./boot-generation";
+export declare const RESTORE_POINTER_SCHEMA_VERSION = 1;
+export interface RestorePointer {
+    schema_version: number;
+    /** Coordinator identity: what the create fence and the sidecar are keyed by. */
+    coordinator_session_id: string;
+    state_file: string;
+    /** SKC session id whose transcript `skc --resume` would reopen. */
+    skc_session_id: string;
+    session_file: string;
+    cwd: string;
+    branch: string | null;
+    boot: RecordedBootGeneration;
+    updated_at: string;
+}
+/** Pointers live under SKC's own root so they are discoverable without scanning projects. */
+export declare function restorePointerDirectory(): string;
+export declare function restorePointerFile(coordinatorSessionId: string, stateFile: string): string;
+export declare function isRestorePointer(value: unknown): value is RestorePointer;
+/**
+ * The session id `skc --resume` resolves is the transcript header id, which is
+ * NOT the coordinator id: a normal `skc --tmux` child inherits only the
+ * coordinator identity and then mints its own session id. Reading it from the
+ * transcript is the only way a pointer can name the conversation that will
+ * actually be reopened.
+ */
+export declare function readTranscriptSessionId(sessionFile: string): string | null;
+export interface PublishRestorePointerInput {
+    coordinatorSessionId: string;
+    stateFile: string;
+    skcSessionId: string;
+    sessionFile: string;
+    cwd: string;
+    branch?: string | null;
+    bootGeneration?: BootGeneration;
+    now?: () => Date;
+}
+/**
+ * Publishes (or refreshes) the pointer for a live session.
+ *
+ * Returns false without writing when the platform cannot produce boot evidence:
+ * a pointer whose boot value is unusable could never be judged `changed`, so
+ * writing one would only add noise. Never throws — losing a pointer must not
+ * break the session that was trying to publish it.
+ */
+export declare function publishRestorePointer(input: PublishRestorePointerInput): boolean;
+/** Lists candidate pointers. Unreadable or malformed entries are skipped, never guessed at. */
+export declare function listRestorePointers(): RestorePointer[];
+/**
+ * Exact reference to one candidate, for `skc session restore --reference`.
+ *
+ * base64url of the identity pair, so a reference cannot be confused with a
+ * session id, a path, or a prefix. It selects a candidate; it never overrides
+ * any eligibility check.
+ */
+export declare function encodeRestoreReference(coordinatorSessionId: string, stateFile: string): string;
+export declare function decodeRestoreReference(reference: string): {
+    coordinatorSessionId: string;
+    stateFile: string;
+} | null;
+export type RestoreIneligibleReason = "same_boot" | "boot_unknown" | "sidecar_missing" | "sidecar_identity_mismatch" | "sidecar_terminal" | "transcript_missing" | "cwd_missing" | "live_identity_collision" | "transcript_identity_mismatch" | "unsupported_owner_proof";
+export type RestoreCandidateVerdict = {
+    eligible: true;
+    pointer: RestorePointer;
+} | {
+    eligible: false;
+    pointer: RestorePointer;
+    reason: RestoreIneligibleReason;
+    detail?: string;
+};
+/** The sidecar fields restore is allowed to trust, read fresh at decision time. */
+export interface RestoreSidecarFacts {
+    sessionId: string;
+    stateFile: string;
+    sessionFile: string | null;
+    cwd: string | null;
+    terminal: boolean;
+}
+export interface RestoreCandidateDeps {
+    currentBoot: BootGeneration;
+    /** Strict re-read of the referenced sidecar. Null when absent or unparseable. */
+    readSidecar: (pointer: RestorePointer) => RestoreSidecarFacts | null;
+    pathExists: (target: string) => boolean;
+    /** True when a live tmux session already owns this identity. */
+    hasLiveIdentity: (pointer: RestorePointer) => boolean;
+    /** Header id of the transcript the pointer names, re-read at decision time. */
+    readTranscriptSessionId: (pointer: RestorePointer) => string | null;
+    /** False when this host cannot produce the owner proof restore requires (psmux). */
+    ownerProofAvailable: () => boolean;
+}
+/**
+ * Decides whether one candidate may be restored.
+ *
+ * Order matters: the reboot proof comes first because it is the cheapest and the
+ * most restrictive gate, and the pointer's own contents are never trusted beyond
+ * naming what to re-read.
+ */
+export declare function evaluateRestoreCandidate(pointer: RestorePointer, deps: RestoreCandidateDeps): RestoreCandidateVerdict;
+export declare function evaluateRestoreCandidates(pointers: readonly RestorePointer[], deps: RestoreCandidateDeps): RestoreCandidateVerdict[];