@sayknow-cli/coding-agent 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,138 @@ 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**.

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[];

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. */