@skrr-ai/cli 0.1.118 → 0.1.120

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/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;

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/guidedUpdate.js

@@ -0,0 +1,315 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var guidedUpdate_exports = {};
+__export(guidedUpdate_exports, {
+  GUIDED_HANDOFF_PHASES: () => GUIDED_HANDOFF_PHASES,
+  GUIDED_REFUSALS: () => GUIDED_REFUSALS,
+  GUIDED_SERVER_SOURCES: () => GUIDED_SERVER_SOURCES,
+  MAX_OWNER_BLOCKERS: () => MAX_OWNER_BLOCKERS,
+  acknowledgedLabels: () => acknowledgedLabels,
+  blockersFingerprint: () => blockersFingerprint,
+  classifyHandoffReply: () => classifyHandoffReply,
+  describeBlockers: () => describeBlockers,
+  evaluateReadiness: () => evaluateReadiness,
+  isGuidedRefusal: () => isGuidedRefusal,
+  isOurLiveHold: () => isOurLiveHold,
+  legacyRestartAllowed: () => legacyRestartAllowed,
+  noServerVeto: () => noServerVeto,
+  prepareBasis: () => prepareBasis,
+  sanitizeBlockerText: () => sanitizeBlockerText,
+  serverSawNewProcess: () => serverSawNewProcess,
+  verifyLegacyRestart: () => verifyLegacyRestart,
+  verifyReplacement: () => verifyReplacement
+});
+module.exports = __toCommonJS(guidedUpdate_exports);
+const GUIDED_SERVER_SOURCES = [
+  "claims",
+  "receipts",
+  "sessions",
+  "runs",
+  "leases",
+  "custody"
+];
+const GUIDED_REFUSALS = [
+  "managed_machine",
+  "no_stable_identity",
+  "not_found",
+  "ambiguous",
+  "generation_conflict",
+  "not_held",
+  "already_held",
+  "attestation_not_applicable",
+  "not_owner",
+  "held_by_other"
+];
+function isGuidedRefusal(value) {
+  return typeof value === "string" && GUIDED_REFUSALS.includes(value);
+}
+const GUIDED_HANDOFF_PHASES = [
+  "ready",
+  "deferred",
+  "reconnecting",
+  "verified",
+  "failed",
+  "rolled-back"
+];
+function noServerVeto(sources) {
+  if (!Array.isArray(sources))
+    return false;
+  const list = sources;
+  for (const name of GUIDED_SERVER_SOURCES) {
+    const source = list.find((s) => s && s.source === name);
+    if (!source || source.read !== "ok" || source.truncated === true)
+      return false;
+    const holders = Array.isArray(source.holders) ? source.holders : null;
+    if (!holders)
+      return false;
+    if (holders.some((h) => h && (h.class === "active" || h.class === "unproven")))
+      return false;
+  }
+  const report = list.find((s) => s && s.source === "daemon_report");
+  return report !== void 0 && report.read === "not_announced";
+}
+function evaluateReadiness(view, expectedGeneration) {
+  const hold = view?.hold;
+  if (!view || !hold || hold.lifecycle !== "held")
+    return { kind: "not_held" };
+  if (expectedGeneration !== null && hold.generation !== expectedGeneration) {
+    return { kind: "generation_changed", currentGeneration: hold.generation };
+  }
+  if (view.journey?.phase === "pausing")
+    return { kind: "pausing" };
+  const reading = view.reading;
+  if (!reading)
+    return { kind: "unknown", cause: "source_unreadable" };
+  if (reading.state === "ready")
+    return { kind: "ready", basis: "evidence" };
+  if (reading.state === "draining")
+    return { kind: "draining" };
+  if (reading.state !== "unknown")
+    return { kind: "unknown", cause: "source_unreadable" };
+  if (view.journey?.phase === "ready" && view.journey.modifiers?.includes("attested")) {
+    return { kind: "ready", basis: "attested" };
+  }
+  if (reading.cause === "no_inventory_capability" && noServerVeto(reading.sources)) {
+    return { kind: "no_report" };
+  }
+  return { kind: "unknown", cause: reading.cause ?? null };
+}
+function prepareBasis(readiness, opts) {
+  if (opts.legacy)
+    return null;
+  if (readiness.kind === "ready")
+    return readiness.basis;
+  if (readiness.kind === "no_report")
+    return "no_veto";
+  return null;
+}
+function legacyRestartAllowed(readiness) {
+  return readiness.kind === "ready" && readiness.basis === "attested";
+}
+const MAX_OWNER_BLOCKERS = 20;
+const BLOCKER_TEXT_MAX = 200;
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,120}$/;
+const PATHLIKE = /(?:^|[\s("'=])(?:~|\.{1,2})?[\\/](?:[\w.-]+[\\/])+|[A-Za-z]:[\\/]|\\\\|file:\/\/|\/(?:Users|home|var|tmp|private|opt|etc|usr)\//i;
+function sanitizeBlockerText(value, max = BLOCKER_TEXT_MAX) {
+  if (typeof value !== "string")
+    return void 0;
+  const cleaned = Array.from(value, (ch) => {
+    const code = ch.charCodeAt(0);
+    return code < 32 || code === 127 ? " " : ch;
+  }).join("").replace(/\s+/g, " ").trim();
+  if (!cleaned || PATHLIKE.test(cleaned))
+    return void 0;
+  return cleaned.length > max ? `${cleaned.slice(0, max - 1)}\u2026` : cleaned;
+}
+function boundedId(value) {
+  return typeof value === "string" && ID_PATTERN.test(value) ? value : void 0;
+}
+function describeBlockers(input) {
+  const out = [];
+  const serverByRef = /* @__PURE__ */ new Map();
+  const serverHolders = [];
+  for (const source of input.view?.reading?.sources ?? []) {
+    for (const holder of source?.holders ?? []) {
+      if (!holder || holder.class !== "active" && holder.class !== "unproven")
+        continue;
+      serverHolders.push(holder);
+      if (typeof holder.ref === "string")
+        serverByRef.set(holder.ref, holder);
+    }
+  }
+  const merged = /* @__PURE__ */ new Set();
+  for (const blocker of input.daemon ?? []) {
+    if (!blocker || typeof blocker.kind !== "string")
+      continue;
+    const id = boundedId(blocker.id);
+    const holder = blocker.id ? serverByRef.get(blocker.id) : void 0;
+    if (holder)
+      merged.add(holder);
+    const label = holder ? sanitizeBlockerText(holder.label, 120) : void 0;
+    out.push({
+      source: "daemon",
+      kind: blocker.kind.slice(0, 64),
+      text: sanitizeBlockerText(blocker.reason),
+      ...label ? { label } : {},
+      ...id ? { id } : {},
+      ...holder?.since !== void 0 ? { since: holder.since } : {}
+    });
+  }
+  for (const holder of serverHolders) {
+    if (merged.has(holder))
+      continue;
+    const id = boundedId(holder.ref);
+    out.push({
+      source: "server",
+      kind: String(holder.kind || "work").slice(0, 64),
+      text: sanitizeBlockerText(holder.label, 120),
+      ...id ? { id } : {},
+      ...holder.since !== void 0 ? { since: holder.since } : {}
+    });
+  }
+  const desktop = input.desktop;
+  if (desktop && desktop.localSessions > 0) {
+    out.push({ source: "desktop", kind: "desktop_local_sessions", count: desktop.localSessions });
+  }
+  if (desktop && desktop.agentBrowserWindows > 0) {
+    out.push({
+      source: "desktop",
+      kind: "desktop_agent_browser",
+      count: desktop.agentBrowserWindows
+    });
+  }
+  return out.slice(0, MAX_OWNER_BLOCKERS);
+}
+function blockersFingerprint(blockers) {
+  return blockers.map((b) => [b.source, b.kind, b.id ?? "", b.count ?? ""].join("|")).sort().join(";");
+}
+function acknowledgedLabels(blockers, max = 20) {
+  const labels = [];
+  for (const b of blockers) {
+    const detail = b.label ?? b.text;
+    const text = b.count ? `${b.kind} (${b.count})` : detail ? `${b.kind}: ${detail}` : b.kind;
+    labels.push(text.slice(0, 160));
+    if (labels.length >= max)
+      break;
+  }
+  return labels;
+}
+function isHandoffStatus(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  return v.protocolVersion === 1 && typeof v.handoffId === "string" && typeof v.phase === "string" && GUIDED_HANDOFF_PHASES.includes(v.phase) && typeof v.sourceProcessId === "string" && !!v.target && typeof v.target.sha256 === "string" && Array.isArray(v.blockers) && Array.isArray(v.expectedSessions);
+}
+function classifyHandoffReply(input) {
+  const { statusCode, body } = input;
+  if (statusCode === null)
+    return { kind: "unreachable" };
+  if (statusCode === 200) {
+    return isHandoffStatus(body) ? { kind: "ok", status: body } : { kind: "unreachable" };
+  }
+  if (statusCode === 404)
+    return { kind: "absent" };
+  if (statusCode === 401 || statusCode === 403)
+    return { kind: "unauthorized" };
+  if (statusCode === 400 || statusCode === 409 || statusCode === 413 || statusCode === 405) {
+    const code = body && typeof body === "object" && typeof body.error === "string" ? String(body.error).slice(0, 64) : void 0;
+    return { kind: "refused", ...code ? { code } : {} };
+  }
+  return { kind: "unreachable" };
+}
+function verifyReplacement(evidence) {
+  const { handoff, expect, identity } = evidence;
+  if (!handoff)
+    return { kind: "not_yet", missing: "daemon_status" };
+  if (handoff.phase === "failed" || handoff.phase === "rolled-back") {
+    return {
+      kind: "failed",
+      phase: handoff.phase,
+      reason: String(handoff.reason || handoff.phase).slice(0, 64),
+      // A failed handoff observed by the SAME process is a replacement that never
+      // happened: the old daemon is still the one running, and a retry is meaningful.
+      sameProcess: handoff.observer?.processId === expect.sourceProcessId
+    };
+  }
+  if (handoff.phase !== "verified")
+    return { kind: "not_yet", missing: "verified" };
+  const by = handoff.verifiedBy;
+  if (!by || by.processId === expect.sourceProcessId || handoff.target.sha256 !== expect.targetSha256 || expect.version !== null && by.version !== expect.version) {
+    return { kind: "not_yet", missing: "verified" };
+  }
+  if (identity.bootstrapDaemonId === null || identity.runtimeKeyNow === null) {
+    return { kind: "not_yet", missing: "identity_unreadable" };
+  }
+  if (identity.bootstrapDaemonId !== identity.recordedDaemonId) {
+    return { kind: "reinstall", what: "daemon_id" };
+  }
+  if (identity.runtimeKeyNow !== identity.recordedRuntimeKey) {
+    return { kind: "reinstall", what: "runtime_key" };
+  }
+  return { kind: "verified" };
+}
+function verifyLegacyRestart(evidence) {
+  const { before, after, expect } = evidence;
+  if (after.daemonId === null || after.startedAt === null || evidence.runtimeKeyNow === null) {
+    return { kind: "not_yet", missing: "identity_unreadable" };
+  }
+  const newProcess = before.startedAt === null ? after.processId !== null && after.processId !== before.processId : after.startedAt > before.startedAt && (after.processId === null || before.processId === null || after.processId !== before.processId);
+  if (!newProcess)
+    return { kind: "not_yet", missing: "verified" };
+  if (after.daemonId !== expect.daemonId)
+    return { kind: "reinstall", what: "daemon_id" };
+  if (evidence.runtimeKeyNow !== evidence.recordedRuntimeKey) {
+    return { kind: "reinstall", what: "runtime_key" };
+  }
+  if (expect.version !== null && after.version !== expect.version) {
+    return { kind: "not_yet", missing: "verified" };
+  }
+  return { kind: "verified" };
+}
+function serverSawNewProcess(input) {
+  if (input.backHeldAtCommit)
+    return "not_independent";
+  return input.journeyPhase === "back_held" ? "seen" : "not_yet";
+}
+function isOurLiveHold(view, generation) {
+  return generation !== null && !!view?.hold && view.hold.lifecycle === "held" && view.hold.generation === generation;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GUIDED_HANDOFF_PHASES,
+  GUIDED_REFUSALS,
+  GUIDED_SERVER_SOURCES,
+  MAX_OWNER_BLOCKERS,
+  acknowledgedLabels,
+  blockersFingerprint,
+  classifyHandoffReply,
+  describeBlockers,
+  evaluateReadiness,
+  isGuidedRefusal,
+  isOurLiveHold,
+  legacyRestartAllowed,
+  noServerVeto,
+  prepareBasis,
+  sanitizeBlockerText,
+  serverSawNewProcess,
+  verifyLegacyRestart,
+  verifyReplacement
+});