@skrr-ai/cli 0.1.119 → 0.1.121

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/deviceIdentityBridge.js

@@ -31,9 +31,10 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import lockfile from 'proper-lockfile';
 import { buildProof as buildDeviceProof, generateDeviceKeyPair, jwkThumbprint, } from './deviceKey.js';
 import { hasCredEnvelopePathConflict, isCredEnvelopeActive, maybeDecryptOnRead, splitKeyConvergencePolicy, wrapIfActiveOrPassthrough, } from './credentialEnvelopeBridge.js';
-import { consolidateProfileState, profileStateFilePathsToClear, resolveProfileStateDir, } from './profileStateDir.js';
+import { consolidateProfileState, profileStateFilePathsToClear, profileStateDir, resolveProfileStateDir, } from './profileStateDir.js';
 import { emitAuthTelemetry, getAuthLogger } from './runtime.js';
 const PUBLIC_KEY_FILENAME = 'device-public-key.jwk';
 const PRIVATE_KEY_FILENAME = 'device-private-key';
@@ -56,6 +57,34 @@ const DEVICE_IDENTITY_FILES = [
 // so every CLI command does not repeat the same guaranteed 404.
 const DAEMON_NOT_FOUND_BACKOFF_MS = 15 * 60 * 1000;
 let _state = { kind: 'uninit' };
+let _initializing = null;
+/**
+ * The CLI, daemon, and desktop's short-lived signer resolve the same canonical
+ * profile directory even when an older private key still lives in the nested
+ * legacy directory. Serialize the entire read/consolidate/create transaction;
+ * otherwise two first starts can each retain a different key in memory.
+ *
+ * Never proceed unlocked. The long stale interval favors preserving a pinned
+ * identity if a process is paused; a contended caller fails and can retry.
+ * Versions that predate this lock do not participate and still require an
+ * orderly upgrade before using the new-profile authorization path.
+ */
+async function withDeviceIdentityLock(profile, body) {
+    const dir = profileStateDir(profile);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const release = await lockfile.lock(dir, {
+        realpath: false,
+        lockfilePath: path.join(dir, '.device-identity.lock'),
+        stale: 10 * 60 * 1000,
+        retries: { retries: 20, minTimeout: 100, maxTimeout: 500, factor: 1.25 },
+    });
+    try {
+        return await body();
+    }
+    finally {
+        await release();
+    }
+}
 /** @internal Test seam — force-set state. */
 export function __setStateForTest(next) {
     const prev = _state;
@@ -72,6 +101,11 @@ export function __getStateForTest() {
  * that decides which copy the group is read from.
  */
 function profileConfigDir(profile) {
+    // A reserved independent profile has a server-pinned owner and device key.
+    // An older nested copy is not authority to replace or shadow its canonical
+    // key, even when generic profile-convergence policy favors that copy.
+    if (/^desktop-bg-[a-f0-9]{32}$/i.test(profile))
+        return profileStateDir(profile);
     return resolveProfileStateDir(profile, PRIVATE_KEY_FILENAME).dir;
 }
 function publicKeyPath(profile) {
@@ -177,6 +211,50 @@ function persistKeypair(profile, kp) {
     });
     return { envelopeProtected };
 }
+/** Reserved identities are read without following links or accepting an
+ * unbounded, shared, unsealed or concurrently replaced key file. */
+function readIndependentIdentityFile(file, sealed) {
+    if (typeof fs.constants.O_NOFOLLOW !== 'number' || typeof fs.constants.O_NONBLOCK !== 'number')
+        return null;
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const before = fs.fstatSync(fd);
+        if (!before.isFile() || before.nlink !== 1 || before.size > 16_384 || (before.mode & 0o077) !== 0 ||
+            (typeof process.getuid === 'function' && before.uid !== process.getuid()))
+            return null;
+        const bytes = Buffer.alloc(before.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (count <= 0)
+                return null;
+            offset += count;
+        }
+        const after = fs.fstatSync(fd);
+        const current = fs.lstatSync(file);
+        if (!current.isFile() || current.isSymbolicLink() || current.dev !== before.dev || current.ino !== before.ino ||
+            current.size !== before.size || current.nlink !== before.nlink || current.mode !== before.mode ||
+            current.uid !== before.uid || current.mtimeMs !== before.mtimeMs || current.ctimeMs !== before.ctimeMs ||
+            before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.nlink !== after.nlink ||
+            before.mode !== after.mode || before.uid !== after.uid || before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs)
+            return null;
+        const value = bytes.toString('utf8');
+        return sealed && !value.startsWith('osk-env1:') ? null : value;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * Load a previously-persisted keypair. Returns null on missing files,
  * decrypt failure, public/private mismatch (file-swap defense), or
@@ -185,11 +263,13 @@ function persistKeypair(profile, kp) {
 function loadKeypair(profile) {
     const pubPath = publicKeyPath(profile);
     const privPath = privateKeyPath(profile);
-    if (!fs.existsSync(pubPath) || !fs.existsSync(privPath)) {
+    const independent = /^desktop-bg-[a-f0-9]{32}$/i.test(profile);
+    if (!independent && (!fs.existsSync(pubPath) || !fs.existsSync(privPath)))
+        return null;
+    const pubRaw = independent ? readIndependentIdentityFile(pubPath, false) : fs.readFileSync(pubPath, 'utf-8');
+    const privRaw = independent ? readIndependentIdentityFile(privPath, true) : fs.readFileSync(privPath, 'utf-8');
+    if (pubRaw === null || privRaw === null)
         return null;
-    }
-    const pubRaw = fs.readFileSync(pubPath, 'utf-8');
-    const privRaw = fs.readFileSync(privPath, 'utf-8');
     let publicJwk;
     let storedThumbprint;
     try {
@@ -348,23 +428,47 @@ async function consolidateDeviceIdentity(profile) {
  * `createIfMissing: false` stops before step 2 (disabled+no_stored_key) and
  * never replaces anything: for a short-lived process that must only READ the
  * daemon's key while the daemon itself may be creating it (OSK-15990's
- * `skrrd device-proof`). The persist below is not an exclusive create, so a
- * second creator racing the daemon could leave the daemon holding one key in
- * memory and the disk another.
+ * `skrrd device-proof`). Readers and writers both take the profile lock so
+ * they cannot observe an incomplete write from another updated process.
  */
 export async function initDeviceIdentity(profile, options = {}) {
+    if (_initializing)
+        return _initializing;
     if (_state.kind !== 'uninit')
         return;
-    if (typeof profile !== 'string' || profile.length === 0) {
+    if (typeof profile !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(profile)) {
         _state = { kind: 'disabled', reason: 'init_failed' };
-        emit('init_failed', false, { reason: 'empty_profile' });
+        emit('init_failed', false, { reason: 'invalid_profile' });
         return;
     }
+    const job = withDeviceIdentityLock(profile, async () => {
+        if (_state.kind === 'uninit')
+            await initDeviceIdentityLocked(profile, options);
+    }).catch((err) => {
+        _state = { kind: 'disabled', reason: 'init_failed' };
+        emit('init_failed', false, {
+            profile,
+            reason: 'identity_lock_unavailable',
+            message: err instanceof Error ? err.message : 'unknown',
+        });
+    });
+    _initializing = job;
+    try {
+        await job;
+    }
+    finally {
+        if (_initializing === job)
+            _initializing = null;
+    }
+}
+async function initDeviceIdentityLocked(profile, options = {}) {
     // OSK-10314 — converge the two directories this profile may have before
     // resolving any of the four files. Must run after `initCredEnvelope`, which
     // both consumers already guarantee, because the private key's readability
     // depends on which DEK ended up active.
-    await consolidateDeviceIdentity(profile);
+    const independent = /^desktop-bg-[a-f0-9]{32}$/i.test(profile);
+    if (!independent)
+        await consolidateDeviceIdentity(profile);
     let keypair = null;
     try {
         keypair = loadKeypair(profile);
@@ -394,12 +498,12 @@ export async function initDeviceIdentity(profile, options = {}) {
     // DEVICE_KEY_MISMATCH. Only an explicit interactive login may replace it;
     // that login proves the new key and re-pins it before issuing credentials.
     const hasStoredKey = storedKeyMaterialExists(profile);
-    if (hasStoredKey && !options.recoverUnreadable) {
+    if (hasStoredKey && (!options.recoverUnreadable || independent)) {
         _state = { kind: 'disabled', reason: 'unreadable_key' };
         emit('recovery_required', false, { profile, reason: 'stored_key_unreadable' });
         return;
     }
-    if (options.createIfMissing === false) {
+    if (options.createIfMissing === false || (independent && options.createIfMissing !== true)) {
         _state = { kind: 'disabled', reason: 'no_stored_key' };
         emit('no_stored_key', false, { profile });
         return;
@@ -448,25 +552,29 @@ export async function initDeviceIdentity(profile, options = {}) {
  * the daemon's pinned identity.
  */
 export async function resetDeviceIdentity(opts) {
+    if (_initializing)
+        await _initializing;
     if (opts?.clearOnDisk && opts.profile) {
         // Every location, not just the resolved one. A reset that cleared only the
         // canonical copy would leave the pre-consolidation copy for the next init to
         // adopt — a deleted device key that reappears.
         const targets = [PUBLIC_KEY_FILENAME, PRIVATE_KEY_FILENAME].flatMap((name) => profileStateFilePathsToClear(opts.profile, name));
-        for (const p of targets) {
-            try {
-                fs.unlinkSync(p);
-            }
-            catch (err) {
-                if (err.code !== 'ENOENT') {
-                    emit('clear_failed', false, {
-                        profile: opts.profile,
-                        file: path.basename(p),
-                        message: err?.message ?? 'unknown',
-                    });
+        await withDeviceIdentityLock(opts.profile, async () => {
+            for (const p of targets) {
+                try {
+                    fs.unlinkSync(p);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT') {
+                        emit('clear_failed', false, {
+                            profile: opts.profile,
+                            file: path.basename(p),
+                            message: err?.message ?? 'unknown',
+                        });
+                    }
                 }
             }
-        }
+        });
     }
     _state = { kind: 'uninit' };
 }

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/guidedUpdate.d.ts

@@ -0,0 +1,370 @@
+/**
+ * The pure core of a GUIDED update (OSK-19107, Space OSK-S-524, tasks M51 to M53):
+ * hold the machine, wait for it to be quiet, update, verify, and give the machine
+ * back. The Desktop app and a standalone `skrr` install both run it, so what they
+ * decide on, and the words they use for what is in the way, cannot drift apart.
+ *
+ * This file is DECISIONS ONLY. It performs no I/O, reads no clock and holds no
+ * state, so every rule below is a table test. The orchestration (a persisted flow
+ * record, polling, the installer, the supervisor) lives with each caller, because
+ * that is the part that differs between a Desktop that quits mid-flow and a CLI that
+ * runs in the foreground.
+ *
+ * ## Why these rules (each names the failure it prevents)
+ *
+ * - **`prepare` is a probe that briefly refuses admitted work.** While it runs the
+ *   daemon refuses admitted tool calls with an infra-class error, and a tool-proxy Run
+ *   that sees one drops its tools to the Hosted Machine for good. So a guided flow
+ *   calls it ONLY when the server's reading says there is nothing admitted to refuse
+ *   ({@link prepareBasis}), never to find out whether there is.
+ * - **`unknown` is an answer.** A source nobody could read is never zero and never
+ *   ready. {@link noServerVeto} is deliberately strict: every server source must have
+ *   been read, and none may list active or unproven work.
+ * - **A server source can only veto.** Only the daemon's own positively announced
+ *   report grants `ready`; the owner's attestation and the daemon's own `prepare`
+ *   (labelled `no_veto`, D38) are the two other bases, and each is labelled as what
+ *   it is wherever it is shown.
+ * - **Blockers are shown in the words of whoever knows them.** The daemon's blocker
+ *   `reason` and the server's holder `label` are the vocabulary; nothing here
+ *   re-spells them. They are bounded and never a raw path, because a diagnostic can
+ *   carry one.
+ * - **A new PID, an exit code or a cloud connection is not a verified update.**
+ *   {@link verifyReplacement} requires the daemon's own `verified`, from a process
+ *   other than the one that was replaced, for the build that was asked for, and the
+ *   same machine identity afterwards. A different identity is the reinstall case: the
+ *   hold is left in place and shown, never resumed.
+ *
+ * The shapes are STRUCTURAL SUBSETS of `DaemonMaintenanceView` in
+ * `@skrr-ai/data-provider` (`daemonMaintenance.ts`), which is the one vocabulary.
+ * This package cannot import it (it sits below it), so `guidedUpdate.test.ts` reads
+ * that file and fails when a list mirrored here drifts from it.
+ */
+export type GuidedHolderClass = 'active' | 'pending_delivery' | 'unproven' | 'forensic';
+export interface GuidedHolder {
+    kind: string;
+    class: GuidedHolderClass | string;
+    ref?: string;
+    label?: string;
+    since?: string | null;
+    detail?: string;
+}
+export interface GuidedSourceReading {
+    source: string;
+    read: 'ok' | 'unreadable' | 'not_announced' | string;
+    cause?: string;
+    readAt?: string;
+    total?: number;
+    holders?: GuidedHolder[];
+    truncated?: boolean;
+}
+export interface GuidedViewLike {
+    runtimeKey?: string;
+    hold: {
+        generation: number;
+        lifecycle: 'held' | 'released' | string;
+        reason?: string;
+        requestedAt?: string;
+        heldBy?: {
+            kind?: string;
+            id?: string;
+            name?: string;
+        };
+        attestation?: {
+            at?: string;
+            by?: string;
+        } | null;
+    } | null;
+    reading: {
+        state: 'draining' | 'ready' | 'unknown' | string;
+        cause: string | null;
+        readAt?: string;
+        sources?: GuidedSourceReading[];
+    } | null;
+    journey: {
+        phase: string;
+        modifiers?: string[];
+        cause?: string | null;
+        controls?: string[];
+    };
+}
+/** The server sources that can only veto. `daemon_report` is the only one that grants. */
+export declare const GUIDED_SERVER_SOURCES: readonly ["claims", "receipts", "sessions", "runs", "leases", "custody"];
+/** The refusals the owner API names, mirrored from `DAEMON_MAINTENANCE_REFUSALS`. */
+export declare const GUIDED_REFUSALS: readonly ["managed_machine", "no_stable_identity", "not_found", "ambiguous", "generation_conflict", "not_held", "already_held", "attestation_not_applicable", "not_owner", "held_by_other"];
+export type GuidedRefusal = (typeof GUIDED_REFUSALS)[number];
+export declare function isGuidedRefusal(value: unknown): value is GuidedRefusal;
+/** The daemon handoff phases, mirrored from `daemon/src/update/handoff.ts`. */
+export declare const GUIDED_HANDOFF_PHASES: readonly ["ready", "deferred", "reconnecting", "verified", "failed", "rolled-back"];
+/**
+ * What a guided flow may do with the server's answer. The flow reads `reading` and
+ * the fence, never the Journey's phase alone: a Journey says `back_held` for any
+ * process that registered after the fence, and that masks the reading it would
+ * otherwise carry.
+ */
+export type Readiness = 
+/** No live hold on this machine (it was released, or never existed). */
+{
+    kind: 'not_held';
+}
+/** A live hold, but not the generation this flow took. Never adopted. */
+ | {
+    kind: 'generation_changed';
+    currentGeneration: number;
+}
+/** The fence is not confirmed on every row, so no reading means anything yet. */
+ | {
+    kind: 'pausing';
+}
+/** Nothing admitted is running: the daemon's report said so, or the owner vouched. */
+ | {
+    kind: 'ready';
+    basis: 'evidence' | 'attested';
+}
+/** The daemon cannot report. No server source vetoes. Only the daemon's own check may decide. */
+ | {
+    kind: 'no_report';
+} | {
+    kind: 'draining';
+} | {
+    kind: 'unknown';
+    cause: string | null;
+};
+/**
+ * Whether the server holds a reading that nothing vetoes, for a daemon that cannot
+ * report (D38). Strict on purpose: a source that is absent from the list, unreadable,
+ * truncated, or that names active or unproven work, is a veto. `daemon_report` must
+ * be `not_announced`: any other answer means the reading is not the
+ * `no_inventory_capability` case this is for.
+ */
+export declare function noServerVeto(sources: readonly GuidedSourceReading[] | undefined): boolean;
+/**
+ * Read the owner API's view for a flow that took `generation`.
+ *
+ * Order matters and is the rule set (each is a test):
+ *  1. No live hold: `not_held`. A different live generation: `generation_changed`.
+ *  2. The fence is not confirmed (`pausing`): nothing below it means anything.
+ *  3. The reading is `ready` (the daemon's own report): `ready` by evidence.
+ *  4. `draining`: work is running. Evidence, never overridden.
+ *  5. `unknown`: ready by attestation if the Journey says the owner vouched for this
+ *     cause; `no_report` if the daemon cannot report and no source vetoes; else
+ *     `unknown`. No reading at all is `unknown (source_unreadable)`, never ready.
+ */
+export declare function evaluateReadiness(view: GuidedViewLike | null | undefined, expectedGeneration: number | null): Readiness;
+/** How a `prepare` is justified. Labelled on every surface as exactly this. */
+export type PrepareBasis = 'evidence' | 'attested' | 'no_veto';
+/**
+ * Whether a guided flow may call the daemon's `prepare`, and on what basis. `null`
+ * means NO: `prepare` is never a way to find out. A legacy daemon never gets one:
+ * it has no endpoint, and its restart is the owner's attested decision, not a probe.
+ */
+export declare function prepareBasis(readiness: Readiness, opts: {
+    legacy: boolean;
+}): PrepareBasis | null;
+/**
+ * Whether a legacy daemon (no handoff endpoint) may be restarted by the supervisor.
+ * Only on the owner's attestation: the daemon cannot report what it is doing and a
+ * SIGTERM ends its wrappers, so nothing but the owner's word can vouch for it.
+ */
+export declare function legacyRestartAllowed(readiness: Readiness): boolean;
+export interface DaemonBlockerLike {
+    kind: string;
+    id?: string;
+    reason?: string;
+}
+export interface DesktopWorkLike {
+    localSessions: number;
+    agentBrowserWindows: number;
+}
+export type OwnerBlockerSource = 'server' | 'daemon' | 'desktop';
+export interface OwnerBlocker {
+    source: OwnerBlockerSource;
+    /** The holder or blocker kind as its owner spelled it, or a `desktop_*` id for the app's own work. */
+    kind: string;
+    /** The server's label, or the daemon's reason, verbatim after bounding. Absent when it was unsafe to show. */
+    text?: string;
+    /** A server label for a daemon blocker the server holds under the same ref. */
+    label?: string;
+    /** A bounded identifier (a session or request id), never a path. */
+    id?: string;
+    since?: string | null;
+    /** For the app's own work: how many. */
+    count?: number;
+}
+export declare const MAX_OWNER_BLOCKERS = 20;
+/** A sentence safe to put in front of the owner, or `undefined` when it is not. */
+export declare function sanitizeBlockerText(value: unknown, max?: number): string | undefined;
+/**
+ * Everything in the way, from the three places that know: the server's holders
+ * (active and unproven work: `pending_delivery` and `forensic` never block), the
+ * daemon's own refusal from `prepare`, and the work the Desktop app itself hosts and
+ * ends when it quits (`LocalSessionService` processes and agent browser windows,
+ * which the daemon's inventory cannot see).
+ *
+ * A daemon blocker whose id equals a server holder's ref is the same work seen twice:
+ * it is listed once, with the daemon's reason and the server's label. Whether the two
+ * ids are in fact comparable was never established (review §6.2 item 2), so a match
+ * only MERGES the wording and never hides a blocker that has no match.
+ */
+export declare function describeBlockers(input: {
+    view?: GuidedViewLike | null;
+    daemon?: readonly DaemonBlockerLike[] | null;
+    desktop?: DesktopWorkLike | null;
+}): OwnerBlocker[];
+/**
+ * A string that changes whenever the set of things in the way changes. The "update
+ * now anyway" confirmation carries the one it was shown, and the action is refused
+ * when it no longer matches: a confirmation that names what WAS running is not a
+ * confirmation of what is.
+ */
+export declare function blockersFingerprint(blockers: readonly OwnerBlocker[]): string;
+/**
+ * The labels the owner is shown, as the server records them in the outcome
+ * (`acknowledged`): each bounded to the server's 160-character limit.
+ */
+export declare function acknowledgedLabels(blockers: readonly OwnerBlocker[], max?: number): string[];
+export interface HandoffBlocker {
+    kind: string;
+    id?: string;
+    reason: string;
+}
+export interface HandoffStatusLike {
+    protocolVersion: 1;
+    handoffId: string;
+    phase: 'ready' | 'deferred' | 'reconnecting' | 'verified' | 'failed' | 'rolled-back';
+    reason: string;
+    sourceProcessId: string;
+    sourceVersion: string;
+    target: {
+        path?: string;
+        mtimeMs?: number;
+        sha256: string;
+    };
+    blockers: HandoffBlocker[];
+    expectedSessions: unknown[];
+    adoptedSessionCount?: number;
+    verifiedBy?: {
+        processId: string;
+        version: string;
+    };
+    observer?: {
+        processId: string;
+        version: string;
+        buildMatches: boolean;
+        ready: boolean;
+    };
+}
+/**
+ * What a call to the daemon's loopback `/v1/update-handoff` came back as.
+ *
+ * - `absent`: a 404. The daemon answered and has no such endpoint: it predates the
+ *   handoff (the installed 0.8.117 answers 404 to every path it does not serve). This
+ *   is the ONLY reply that means "legacy". A refused connection is not.
+ * - `unauthorized`: the bootstrap secret was refused (it rotates when the daemon
+ *   restarts). Re-read the bootstrap and try again.
+ * - `refused`: reachable, speaks the protocol, said no (409: no handoff owned, or the
+ *   lease expired; 400; 413). A refusal is a value the caller shows.
+ * - `unreachable`: no bootstrap file, a connection error, a timeout, a malformed or
+ *   unexpected body. Unknown: never `absent`, never `ready`.
+ */
+export type HandoffReply = {
+    kind: 'ok';
+    status: HandoffStatusLike;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'unauthorized';
+} | {
+    kind: 'refused';
+    code?: string;
+} | {
+    kind: 'unreachable';
+};
+export declare function classifyHandoffReply(input: {
+    /** `null` when no HTTP response arrived at all. */
+    statusCode: number | null;
+    /** The parsed JSON body, or `undefined` when there was none or it did not parse. */
+    body?: unknown;
+}): HandoffReply;
+export interface ReplacementEvidence {
+    /** The daemon's own answer to `status` for the handoff, or null when it did not answer. */
+    handoff: Pick<HandoffStatusLike, 'phase' | 'verifiedBy' | 'target' | 'reason' | 'observer'> | null;
+    expect: {
+        sourceProcessId: string;
+        targetSha256: string;
+        /** The bundled daemon's version, or null when it could not be read (the hash binds it anyway). */
+        version: string | null;
+    };
+    identity: {
+        recordedDaemonId: string;
+        recordedRuntimeKey: string;
+        /** The daemon id of the process now holding the loopback bootstrap, or null when unreadable. */
+        bootstrapDaemonId: string | null;
+        /** The runtimeKey the machine payload lists for `recordedDaemonId` now, or null when it lists none or could not be read. */
+        runtimeKeyNow: string | null;
+    };
+}
+export type ReplacementVerdict = 
+/** (1) the daemon's `verified` for this build by another process, and (2) the same identity. */
+{
+    kind: 'verified';
+} | {
+    kind: 'not_yet';
+    missing: 'daemon_status' | 'verified' | 'identity_unreadable';
+}
+/** The daemon id or the machine's runtimeKey changed: a reinstall. The hold is left and shown. */
+ | {
+    kind: 'reinstall';
+    what: 'daemon_id' | 'runtime_key';
+} | {
+    kind: 'failed';
+    phase: 'failed' | 'rolled-back';
+    reason: string;
+    sameProcess: boolean;
+};
+/**
+ * Decide whether a committed replacement is complete. All of (1) and (2) must hold
+ * before anything else is asked of the server (3, {@link serverSawNewProcess}), and
+ * nothing here resumes: the verdict only says what was seen.
+ *
+ * An identity that is merely UNREADABLE (the bootstrap is mid-rotation, the machine
+ * payload could not be fetched) is `not_yet`, never a reinstall and never verified.
+ */
+export declare function verifyReplacement(evidence: ReplacementEvidence): ReplacementVerdict;
+export interface LegacyRestartEvidence {
+    before: {
+        startedAt: number | null;
+        processId: number | null;
+    };
+    after: {
+        daemonId: string | null;
+        version: string | null;
+        startedAt: number | null;
+        processId: number | null;
+    };
+    expect: {
+        daemonId: string;
+        version: string | null;
+    };
+    runtimeKeyNow: string | null;
+    recordedRuntimeKey: string;
+}
+/**
+ * The legacy counterpart: a daemon with no handoff cannot say `verified`, so the copy
+ * claims only what was seen ("restarted on version X"), never "adopted N sessions".
+ * A new process (a different start time and, where known, a different PID), the same
+ * identity, and the version it announces equal to the bundled one.
+ */
+export declare function verifyLegacyRestart(evidence: LegacyRestartEvidence): ReplacementVerdict;
+/**
+ * Whether the server independently saw a new process register under the held key
+ * (condition 3). The Journey says `back_held` for ANY process that registered since
+ * the fence, so it can only corroborate THIS replacement when it did not already say
+ * so before the commit. When it did, the answer is `not_independent`: the flow rests
+ * on (1) and (2) and says so.
+ */
+export declare function serverSawNewProcess(input: {
+    journeyPhase: string | null | undefined;
+    backHeldAtCommit: boolean;
+}): 'seen' | 'not_yet' | 'not_independent';
+/** Whether an observed hold is the one this flow took, and still live. */
+export declare function isOurLiveHold(view: GuidedViewLike | null | undefined, generation: number | null): boolean;