@pinet/broker-core 0.2.4 → 0.2.7

package/dist/hibernation-projection.d.ts

@@ -0,0 +1,20 @@
+import { type AgentLifecycleStatus } from "./hibernation-status.js";
+import type { BrokerDB } from "./schema.js";
+import type { AgentInfo } from "./types.js";
+/** True when an agent's lifecycle state is worth surfacing in operator reads. */
+export declare function isHibernationRelevantAgent(agent: Pick<AgentInfo, "lifecycleState">): boolean;
+export interface CollectLifecycleStatusesOptions {
+    now?: number;
+    /** Restrict to these agent ids (e.g. the currently visible set). */
+    agentIds?: string[];
+    /** Include live/active agents too. Defaults false (hibernation-relevant only). */
+    includeAll?: boolean;
+    /** Wake capacity ceilings; when provided, capacity counters are included. */
+    maxConcurrentWakes?: number;
+    maxConcurrentWakesPerRepo?: number;
+}
+/**
+ * Build lifecycle statuses from the broker DB. Pure read: performs no
+ * mutations and never activates hibernation.
+ */
+export declare function collectAgentLifecycleStatuses(db: BrokerDB, options?: CollectLifecycleStatusesOptions): AgentLifecycleStatus[];

package/dist/hibernation-projection.js

@@ -0,0 +1,60 @@
+import { buildAgentLifecycleStatus } from "./hibernation-status.js";
+/**
+ * Read-only lifecycle projection for the existing `agents`/`sessions` operator
+ * read paths. Assembles the sanitized {@link AgentLifecycleStatus} for agents
+ * that are in a hibernation-relevant lifecycle state, using only durable broker
+ * reads. Every field is redaction-by-construction safe (see
+ * {@link buildAgentLifecycleStatus} / redactRuntimeSpec): no argv, env values,
+ * message bodies, tokens, or filesystem/socket paths.
+ */
+const HIBERNATION_RELEVANT_STATES = new Set([
+    "grace",
+    "idle",
+    "hibernating",
+    "hibernated",
+    "waking",
+    "reap-candidate",
+]);
+/** True when an agent's lifecycle state is worth surfacing in operator reads. */
+export function isHibernationRelevantAgent(agent) {
+    return HIBERNATION_RELEVANT_STATES.has(agent.lifecycleState ?? "live");
+}
+/**
+ * Build lifecycle statuses from the broker DB. Pure read: performs no
+ * mutations and never activates hibernation.
+ */
+export function collectAgentLifecycleStatuses(db, options = {}) {
+    const now = options.now ?? Date.now();
+    const idFilter = options.agentIds ? new Set(options.agentIds) : null;
+    const orderedWakeQueue = [...db.listWakeQueue("queued")].sort((a, b) => a.priority - b.priority || a.enqueuedAt.localeCompare(b.enqueuedAt));
+    const recentEvents = db.getRecentAgentLifecycleEvents(undefined, 200);
+    const globalInflight = db.countInflightWakes();
+    const includeCapacity = options.maxConcurrentWakes != null && options.maxConcurrentWakesPerRepo != null;
+    const statuses = [];
+    for (const agent of db.getAllAgents()) {
+        if (idFilter && !idFilter.has(agent.id))
+            continue;
+        if (!options.includeAll && !isHibernationRelevantAgent(agent))
+            continue;
+        const repoRootRaw = agent.metadata?.repoRoot;
+        const repoRoot = typeof repoRootRaw === "string" ? repoRootRaw : null;
+        const capacity = includeCapacity
+            ? {
+                maxConcurrentWakes: options.maxConcurrentWakes,
+                inflightWakes: globalInflight,
+                maxConcurrentWakesPerRepo: options.maxConcurrentWakesPerRepo,
+                inflightWakesForRepo: db.countInflightWakes(repoRoot),
+            }
+            : undefined;
+        statuses.push(buildAgentLifecycleStatus({
+            agent,
+            now,
+            latestCheckpoint: db.getLatestAgentCheckpointReceipt(agent.id),
+            runtimeSpec: db.getAgentRuntimeSpec(agent.id),
+            orderedWakeQueue,
+            recentEvents,
+            capacity,
+        }));
+    }
+    return statuses;
+}

package/dist/hibernation-status.d.ts

@@ -0,0 +1,141 @@
+import type { AgentCheckpointReceipt, AgentHibernatePolicy, AgentInfo, AgentLifecycleEvent, AgentLifecycleState, AgentRuntimeSpec, AgentWakeQueueEntry, RedactedAgentRuntimeSpec, WakeTriggerKind } from "./types.js";
+/**
+ * Short, stable, non-reversible FNV-1a digest. Lets operators correlate an
+ * opaque identity (session ref, unresolved command target) across reads without
+ * exposing the underlying payload — which may be a filesystem path or secret.
+ */
+export declare function fingerprintToken(value: string): string;
+export declare function redactRuntimeSpec(spec: AgentRuntimeSpec): RedactedAgentRuntimeSpec;
+export interface AgentLifecycleStatusCapacityInput {
+    maxConcurrentWakes: number;
+    inflightWakes: number;
+    maxConcurrentWakesPerRepo: number;
+    inflightWakesForRepo: number;
+}
+export interface AgentLifecycleStatusInput {
+    agent: Pick<AgentInfo, "id" | "lifecycleState" | "lifecycleVersion" | "runtimeGeneration" | "hibernatePolicy" | "hibernatedAt" | "graceUntil" | "idleEligibleAt" | "hibernateReason" | "lastWakeReason">;
+    /** Epoch ms used for age math. Defaults to Date.now(). */
+    now?: number;
+    latestCheckpoint?: AgentCheckpointReceipt | null;
+    runtimeSpec?: AgentRuntimeSpec | null;
+    /**
+     * Wake queue ordered exactly as the dispatcher consumes it (priority then
+     * oldest). Used to compute this agent's 1-based queue position.
+     */
+    orderedWakeQueue?: AgentWakeQueueEntry[];
+    capacity?: AgentLifecycleStatusCapacityInput;
+    /** Recent lifecycle events (any order); used to surface refusal/quarantine cause. */
+    recentEvents?: AgentLifecycleEvent[];
+}
+export interface AgentLifecycleStatus {
+    agentId: string;
+    state: AgentLifecycleState;
+    lifecycleVersion: number;
+    runtimeGeneration: number | null;
+    hibernatePolicy: AgentHibernatePolicy | null;
+    hibernatedAt: string | null;
+    hibernateReason: string | null;
+    lastWakeReason: string | null;
+    graceUntil: string | null;
+    idleEligibleAt: string | null;
+    quarantined: boolean;
+    checkpoint: {
+        present: boolean;
+        hibernateSafe: boolean | null;
+        ageMs: number | null;
+        pendingInboxCount: number | null;
+        runtimeGeneration: number | null;
+    };
+    /** Presence + redacted summary of the durable runtime spec; never raw argv/env. */
+    runtimeSpec: RedactedAgentRuntimeSpec | null;
+    wake: {
+        queued: boolean;
+        position: number | null;
+        triggerKind: WakeTriggerKind | null;
+        reason: string | null;
+        attempt: number | null;
+    };
+    capacity: {
+        global: {
+            inflight: number;
+            max: number;
+            atCapacity: boolean;
+        };
+        repo: {
+            inflight: number;
+            max: number;
+            atCapacity: boolean;
+        };
+    } | null;
+    /** Most recent non-accepted lifecycle outcome (refusal/stale fence/abort). */
+    refusal: {
+        reason: string;
+        outcome: string;
+        at: string;
+    } | null;
+}
+/**
+ * Bound and control-strip a free-form reason string for operator-safe display.
+ * Reasons can originate from operator input (hibernate/wake commands) and flow
+ * durably into lifecycle rows; this is the redaction-by-construction boundary
+ * that keeps such strings single-line, control-char free, and length-bounded
+ * before they reach any operator/status/JSON surface. Returns null for
+ * empty/whitespace-only input.
+ */
+export declare function sanitizeOperatorReason(value: string | null | undefined): string | null;
+/**
+ * Sanitize an operator-authored hibernation/wake TARGET before it reaches the
+ * confirmation-policy / prompt surface. Unlike a free-form reason, a target can
+ * be a durable stable id (`host:session:<ref>`, `host:cwd:<path>`) whose tail
+ * embeds the session-resume identity — the same value {@link redactRuntimeSpec}
+ * fingerprints — so it must never be echoed verbatim. Fail-closed by shape: only
+ * a plain broker-safe identifier slug (an agent name/id with no separators that
+ * could embed a session/path/secret identity) is passed through; ANY other shape
+ * (stable-id triple, session/cwd/worktree token, path, `KEY=value`, quotes,
+ * whitespace) collapses to an opaque, non-reversible `target:#<fingerprint>`
+ * (matching {@link unknownHibernationTarget}). The RAW target is unaffected — the
+ * broker still resolves it server-side; only the operator-facing echo is redacted.
+ */
+export declare function sanitizeOperatorTarget(target: string | null | undefined): string;
+/**
+ * Replace filesystem-path-like tokens with `<path>` so operator-authored
+ * free-form strings (reasons, echoed targets) can never surface private
+ * absolute paths, unix socket paths, or repo-relative paths in operator/JSON
+ * output. Conservative but fail-closed on ambiguous relative paths: any
+ * single-separator token that is not a known prose connective (see
+ * `PROSE_SLASH_TOKENS`) is redacted, so `accounts/acme` is caught while
+ * "and/or" survives. This is a redaction-by-construction boundary, not a
+ * security parser.
+ */
+export declare function redactPathLikeTokens(value: string): string;
+/**
+ * Redaction-by-construction for RUNTIME-authored checkpoint reasons. A checkpoint
+ * reason is authored by the worker runtime, so — unlike the trusted-operator
+ * reason path (which only redacts obvious path-like tokens) — it must NOT be able
+ * to smuggle argv, env assignments (`TOKEN=secret`), CLI flags (`--api-key x`),
+ * extensionless relative paths (`accounts/acme`), or other free prose onto any
+ * operator/telemetry/JSON surface. We therefore allowlist by *shape*: only a
+ * short single-token machine code (`active_port_lease`, `checkpoint_timeout`, …)
+ * is passed through; anything containing whitespace, separators, or exotic
+ * characters collapses to the static `unspecified` code. Diagnostic prose belongs
+ * in the worker's own logs, not the broker's operator surface.
+ */
+export declare function sanitizeCheckpointReasonCode(value: string | null | undefined): string;
+/**
+ * Compose an operator-safe, actionable per-agent lifecycle status from already
+ * sanitized inputs. Pure: it performs no IO and never emits raw argv, env
+ * values, or filesystem/socket paths.
+ */
+export declare function buildAgentLifecycleStatus(input: AgentLifecycleStatusInput): AgentLifecycleStatus;
+/**
+ * Render a single scannable, operator-safe lifecycle tag for inline use in the
+ * `agents`/`sessions` compact read paths. Sanitized: state, generation, queue
+ * position, checkpoint age/safety, and refusal/quarantine reason code only.
+ */
+export declare function formatAgentLifecycleTag(status: AgentLifecycleStatus): string;
+/**
+ * Render a compact, operator-safe status block. Contains only sanitized
+ * lifecycle facts — never prompts, message bodies, tokens, argv, env values, or
+ * filesystem paths.
+ */
+export declare function formatAgentLifecycleStatus(status: AgentLifecycleStatus): string;

package/dist/hibernation-status.js

@@ -0,0 +1,390 @@
+/**
+ * Short, stable, non-reversible FNV-1a digest. Lets operators correlate an
+ * opaque identity (session ref, unresolved command target) across reads without
+ * exposing the underlying payload — which may be a filesystem path or secret.
+ */
+export function fingerprintToken(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * Redact a durable runtime spec into an operator-safe view: presence flags,
+ * counts, and opaque references only. Raw argv, environment values, filesystem
+ * paths, and private socket paths are never surfaced. This is the sanctioned
+ * redaction-by-construction boundary for any operator/status/inspect surface.
+ */
+/**
+ * Fail-closed sanitizer for an otherwise-unconstrained runtime-spec facet
+ * (`configFingerprint`, `expectedHost`, `launchSource`). `AgentRuntimeSpec` puts
+ * no shape constraint on these adapter-authored strings, so a path, unix socket
+ * path, `KEY=value` assignment, quoted span, or other secret-bearing value could
+ * be persisted into one and then copied verbatim onto an operator/JSON surface,
+ * bypassing the redaction-by-construction boundary. Only a strict machine token
+ * (hostname / hash / short machine code: an alphanumeric-anchored run of
+ * `[A-Za-z0-9_.-]`, no separator/quote/assignment/whitespace) is passed through;
+ * ANY other shape collapses to an opaque, non-reversible `#<fingerprint>` so an
+ * operator can still correlate the value across reads without exposing it.
+ */
+function sanitizeSpecFacet(value) {
+    const raw = (value ?? "").trim();
+    if (raw.length === 0)
+        return "";
+    if (/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(raw))
+        return raw;
+    return `#${fingerprintToken(raw)}`;
+}
+export function redactRuntimeSpec(spec) {
+    const rawRef = spec.sessionResumeRef;
+    const separatorIndex = rawRef.indexOf(":");
+    const kindHint = separatorIndex > 0 ? rawRef.slice(0, separatorIndex) : "";
+    const knownKinds = ["session", "leaf", "cwd", "broker"];
+    const kind = knownKinds.includes(kindHint)
+        ? kindHint
+        : "unknown";
+    // The session ref payload is NEVER surfaced verbatim: for `cwd`/`leaf` kinds
+    // (and unrecognized producers) it can be a filesystem path or otherwise
+    // sensitive. Instead emit `<kind>:#<fingerprint>` — a stable, short,
+    // non-reversible FNV-1a digest that lets operators correlate identity across
+    // reads without exposing the payload — and flag whether it looked path-like.
+    const payload = separatorIndex > 0 ? rawRef.slice(separatorIndex + 1) : rawRef;
+    const hasPath = /[\\/]/.test(payload) || payload.startsWith("~");
+    const ref = `${kind}:#${fingerprintToken(rawRef)}`;
+    // Repo is reported as a path-free basename so operators can group agents
+    // without exposing the worktree/repo-root filesystem path. Split on BOTH
+    // separators so a Windows repo root (e.g. `C:\\Users\\alice\\secret-repo`) is
+    // never emitted verbatim as its own "basename".
+    const repoSegments = spec.repoRoot.split(/[\\/]/).filter(Boolean);
+    const repo = repoSegments.length > 0 ? repoSegments[repoSegments.length - 1] : null;
+    // These adapter-authored facets are shape-unconstrained on the spec, so they
+    // are sanitized fail-closed before reaching any operator/JSON surface: a strict
+    // machine token passes through, anything else is fingerprinted (see
+    // `sanitizeSpecFacet`). Applies to the mirrored `session.host` too.
+    const expectedHost = sanitizeSpecFacet(spec.expectedHost);
+    return {
+        agentId: spec.agentId,
+        session: {
+            kind,
+            ref,
+            host: expectedHost,
+            hasPath,
+        },
+        repo,
+        hasWorktree: Boolean(spec.worktreePath),
+        runtimeKind: spec.runtimeKind,
+        hasTmuxSession: spec.runtimeKind === "tmux" && Boolean(spec.tmuxSession),
+        configFingerprint: sanitizeSpecFacet(spec.configFingerprint),
+        expectedHost,
+        launchSource: sanitizeSpecFacet(spec.launchSource),
+        envAllowlistCount: spec.envAllowlist.length,
+        updatedAt: spec.updatedAt,
+    };
+}
+const DURABLE_HIBERNATION_STATES = new Set(["hibernated", "waking"]);
+/**
+ * Bound and control-strip a free-form reason string for operator-safe display.
+ * Reasons can originate from operator input (hibernate/wake commands) and flow
+ * durably into lifecycle rows; this is the redaction-by-construction boundary
+ * that keeps such strings single-line, control-char free, and length-bounded
+ * before they reach any operator/status/JSON surface. Returns null for
+ * empty/whitespace-only input.
+ */
+export function sanitizeOperatorReason(value) {
+    if (value == null)
+        return null;
+    const cleaned = Array.from(value)
+        .map((ch) => {
+        const code = ch.codePointAt(0) ?? 0;
+        return code <= 0x1f || code === 0x7f ? " " : ch;
+    })
+        .join("")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (cleaned.length === 0)
+        return null;
+    // Two composed passes: first strip secret-bearing shapes (env assignments and
+    // CLI flag values) that are not paths, then redact path-like tokens. Ordering
+    // matters — a flag's value that is itself a path is caught by the first pass.
+    const redacted = redactPathLikeTokens(redactSecretAssignments(cleaned));
+    return redacted.length > 120 ? `${redacted.slice(0, 117)}\u2026` : redacted;
+}
+/**
+ * Sanitize an operator-authored hibernation/wake TARGET before it reaches the
+ * confirmation-policy / prompt surface. Unlike a free-form reason, a target can
+ * be a durable stable id (`host:session:<ref>`, `host:cwd:<path>`) whose tail
+ * embeds the session-resume identity — the same value {@link redactRuntimeSpec}
+ * fingerprints — so it must never be echoed verbatim. Fail-closed by shape: only
+ * a plain broker-safe identifier slug (an agent name/id with no separators that
+ * could embed a session/path/secret identity) is passed through; ANY other shape
+ * (stable-id triple, session/cwd/worktree token, path, `KEY=value`, quotes,
+ * whitespace) collapses to an opaque, non-reversible `target:#<fingerprint>`
+ * (matching {@link unknownHibernationTarget}). The RAW target is unaffected — the
+ * broker still resolves it server-side; only the operator-facing echo is redacted.
+ */
+export function sanitizeOperatorTarget(target) {
+    const raw = (target ?? "").trim();
+    if (raw.length === 0)
+        return "(unnamed)";
+    // Broker-safe plain identifier (agent name/id): a leading optional `@`, then an
+    // alphanumeric-anchored slug of `[A-Za-z0-9_.-]`. No colon, slash, backslash,
+    // `=`, quote, or whitespace — so it cannot carry a stable-id/session/path/secret
+    // identity and is safe to echo.
+    if (/^@?[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(raw))
+        return raw;
+    return `target:#${fingerprintToken(raw)}`;
+}
+// Common prose that uses a single "/" and must NOT be treated as a path. Bare
+// two-token connectives only; anything path-shaped (multi-segment, file-like,
+// absolute, or relative-prefixed) is still redacted by `redactPathLikeTokens`.
+const PROSE_SLASH_TOKENS = new Set([
+    "and/or",
+    "or/and",
+    "he/she",
+    "she/he",
+    "w/",
+    "w/o",
+    "n/a",
+    "i/o",
+    "km/h",
+    "tcp/ip",
+    "24/7",
+]);
+/**
+ * Redact secret-bearing NON-path shapes from an operator free-form string:
+ * environment/CLI assignments (`TOKEN=deadbeef` → `TOKEN=<redacted>`) and CLI
+ * flag values (`--api-key secret` / `--api-key=secret` → `--api-key <redacted>`).
+ * The env var name / flag name is kept (it is not itself the secret) so the
+ * reason stays actionable, while the value can never reach an operator surface.
+ *
+ * Whole-string, quote- and punctuation-aware, and fail-closed. Earlier
+ * whitespace tokenization leaked on quoted (`TOKEN="dead beef"`), spaced
+ * (`TOKEN = deadbeef`), and punctuation-wrapped (`(--api-key sk-123)`) secrets,
+ * and a naive per-token pass leaked the tail of a spaced value after a flag
+ * (`--api-key "sk live 123`). Two ordered passes consume each secret VALUE
+ * through its end — a possibly-unterminated quoted span OR a non-space run:
+ *   1. `key=value` / `key = value` keeps the key name and redacts the value; the
+ *      key matcher starts at the first identifier char, so a leading `--` or
+ *      punctuation (`(--api-key=…`, `TOKEN = …`) is ignored and still caught.
+ *   2. A flag followed by a separate value (`--flag value` / `-f value`, with any
+ *      leading punctuation) redacts the value — including a quoted span with
+ *      internal spaces, even if the closing quote is missing — unless the value
+ *      is itself another flag.
+ * A value is matched by `VALUE` below: a single/double/back-quoted span whose
+ * closing quote is optional (so an unterminated quote is consumed to the value's
+ * end, never leaking its spaced tail), otherwise a run of non-space characters.
+ */
+// agent-standards-ignore prefer-inline-single-use-helper: distinct multi-pass
+// secret-redaction (key=value assignments, flag values, quoted/unterminated
+// spans); composed with the path-redaction pass in sanitizeOperatorReason and
+// kept separate for readability of each fail-closed pass.
+function redactSecretAssignments(value) {
+    // A secret value: a (possibly unterminated) quoted span, else a non-space run.
+    const VALUE = `(?:"(?:\\\\.|[^"])*"?|'(?:\\\\.|[^'])*'?|\`(?:\\\\.|[^\`])*\`?|\\S+)`;
+    let out = value;
+    // 1) key=value / key = value → keep the key name, redact the value.
+    out = out.replace(new RegExp(`([A-Za-z_][A-Za-z0-9_.-]*)\\s*=\\s*${VALUE}`, "g"), (_match, key) => `${key}=<redacted>`);
+    // 2) `--flag value` / `-f value` (any leading punctuation) → redact the value
+    //    unless it is itself another flag.
+    out = out.replace(new RegExp(`(--?[A-Za-z][A-Za-z0-9_-]*)\\s+(?!--?[A-Za-z])${VALUE}`, "g"), (_match, flag) => `${flag} <redacted>`);
+    return out;
+}
+/**
+ * Replace filesystem-path-like tokens with `<path>` so operator-authored
+ * free-form strings (reasons, echoed targets) can never surface private
+ * absolute paths, unix socket paths, or repo-relative paths in operator/JSON
+ * output. Conservative but fail-closed on ambiguous relative paths: any
+ * single-separator token that is not a known prose connective (see
+ * `PROSE_SLASH_TOKENS`) is redacted, so `accounts/acme` is caught while
+ * "and/or" survives. This is a redaction-by-construction boundary, not a
+ * security parser.
+ */
+export function redactPathLikeTokens(value) {
+    return value
+        .split(/(\s+)/)
+        .map((token) => {
+        if (token.length === 0 || /\s/.test(token))
+            return token;
+        const slashCount = (token.match(/[/\\]/g) ?? []).length;
+        // Strip trailing sentence punctuation before the prose-allowlist check so
+        // "and/or," is still recognized as prose.
+        const bare = token.replace(/[.,;:!?)\]]+$/, "").toLowerCase();
+        const isProse = slashCount === 1 && PROSE_SLASH_TOKENS.has(bare);
+        const pathLike = !isProse &&
+            (/^[~/]/.test(token) || // /abs or ~/home
+                /^\.\.?[/\\]/.test(token) || // ./rel or ../rel
+                /^[A-Za-z]:[\\/]/.test(token) || // C:\ or C:/ (Windows)
+                slashCount >= 1); // any relative/absolute separator (fail-closed)
+        return pathLike ? "<path>" : token;
+    })
+        .join("");
+}
+/**
+ * Redaction-by-construction for RUNTIME-authored checkpoint reasons. A checkpoint
+ * reason is authored by the worker runtime, so — unlike the trusted-operator
+ * reason path (which only redacts obvious path-like tokens) — it must NOT be able
+ * to smuggle argv, env assignments (`TOKEN=secret`), CLI flags (`--api-key x`),
+ * extensionless relative paths (`accounts/acme`), or other free prose onto any
+ * operator/telemetry/JSON surface. We therefore allowlist by *shape*: only a
+ * short single-token machine code (`active_port_lease`, `checkpoint_timeout`, …)
+ * is passed through; anything containing whitespace, separators, or exotic
+ * characters collapses to the static `unspecified` code. Diagnostic prose belongs
+ * in the worker's own logs, not the broker's operator surface.
+ */
+export function sanitizeCheckpointReasonCode(value) {
+    if (value == null)
+        return "unspecified";
+    const trimmed = value.trim();
+    return /^[A-Za-z][A-Za-z0-9_]{0,47}$/.test(trimmed) ? trimmed.toLowerCase() : "unspecified";
+}
+/**
+ * Compose an operator-safe, actionable per-agent lifecycle status from already
+ * sanitized inputs. Pure: it performs no IO and never emits raw argv, env
+ * values, or filesystem/socket paths.
+ */
+export function buildAgentLifecycleStatus(input) {
+    const now = input.now ?? Date.now();
+    const state = input.agent.lifecycleState ?? "live";
+    const checkpoint = input.latestCheckpoint;
+    const checkpointCreatedMs = checkpoint ? Date.parse(checkpoint.createdAt) : Number.NaN;
+    const checkpointAgeMs = checkpoint && Number.isFinite(checkpointCreatedMs)
+        ? Math.max(now - checkpointCreatedMs, 0)
+        : null;
+    let queuePosition = null;
+    let queuedEntry = null;
+    const orderedQueue = input.orderedWakeQueue ?? [];
+    for (let index = 0; index < orderedQueue.length; index += 1) {
+        const entry = orderedQueue[index];
+        if (entry.agentId === input.agent.id && entry.status === "queued") {
+            queuePosition = index + 1;
+            queuedEntry = entry;
+            break;
+        }
+    }
+    let refusal = null;
+    for (const event of input.recentEvents ?? []) {
+        if (event.agentId !== input.agent.id || event.outcome === "accepted")
+            continue;
+        if (refusal === null || event.createdAt > refusal.at) {
+            refusal = {
+                reason: sanitizeOperatorReason(event.errorCode ?? event.reason) ?? "unknown",
+                outcome: event.outcome,
+                at: event.createdAt,
+            };
+        }
+    }
+    const capacity = input.capacity
+        ? {
+            global: {
+                inflight: input.capacity.inflightWakes,
+                max: input.capacity.maxConcurrentWakes,
+                atCapacity: input.capacity.inflightWakes >= input.capacity.maxConcurrentWakes,
+            },
+            repo: {
+                inflight: input.capacity.inflightWakesForRepo,
+                max: input.capacity.maxConcurrentWakesPerRepo,
+                atCapacity: input.capacity.inflightWakesForRepo >= input.capacity.maxConcurrentWakesPerRepo,
+            },
+        }
+        : null;
+    return {
+        agentId: input.agent.id,
+        state,
+        lifecycleVersion: input.agent.lifecycleVersion ?? 0,
+        runtimeGeneration: input.agent.runtimeGeneration ?? null,
+        hibernatePolicy: input.agent.hibernatePolicy ?? null,
+        hibernatedAt: input.agent.hibernatedAt ?? null,
+        hibernateReason: sanitizeOperatorReason(input.agent.hibernateReason),
+        lastWakeReason: sanitizeOperatorReason(input.agent.lastWakeReason),
+        graceUntil: input.agent.graceUntil ?? null,
+        idleEligibleAt: input.agent.idleEligibleAt ?? null,
+        quarantined: state === "reap-candidate",
+        checkpoint: {
+            present: Boolean(checkpoint),
+            hibernateSafe: checkpoint ? checkpoint.hibernateSafe : null,
+            ageMs: checkpointAgeMs,
+            pendingInboxCount: checkpoint ? checkpoint.pendingInboxCount : null,
+            runtimeGeneration: checkpoint ? checkpoint.runtimeGeneration : null,
+        },
+        runtimeSpec: input.runtimeSpec ? redactRuntimeSpec(input.runtimeSpec) : null,
+        wake: {
+            queued: queuedEntry !== null,
+            position: queuePosition,
+            triggerKind: queuedEntry ? queuedEntry.triggerKind : null,
+            reason: queuedEntry ? sanitizeOperatorReason(queuedEntry.reason) : null,
+            attempt: queuedEntry ? queuedEntry.attempt : null,
+        },
+        capacity,
+        refusal,
+    };
+}
+/**
+ * Render a single scannable, operator-safe lifecycle tag for inline use in the
+ * `agents`/`sessions` compact read paths. Sanitized: state, generation, queue
+ * position, checkpoint age/safety, and refusal/quarantine reason code only.
+ */
+export function formatAgentLifecycleTag(status) {
+    const parts = [status.state];
+    if (status.runtimeGeneration !== null)
+        parts.push(`gen${status.runtimeGeneration}`);
+    if (status.wake.queued && status.wake.position !== null)
+        parts.push(`q#${status.wake.position}`);
+    if (status.checkpoint.present) {
+        const age = status.checkpoint.ageMs === null ? "?" : `${Math.round(status.checkpoint.ageMs / 1000)}s`;
+        parts.push(`ckpt ${age}${status.checkpoint.hibernateSafe === false ? " unsafe" : ""}`);
+    }
+    if (status.quarantined) {
+        parts.push(`\u26a0${status.refusal ? ` ${status.refusal.reason}` : ""}`);
+    }
+    else if (status.refusal) {
+        parts.push(`refused:${status.refusal.reason}`);
+    }
+    return parts.join(" \u00b7 ");
+}
+/**
+ * Render a compact, operator-safe status block. Contains only sanitized
+ * lifecycle facts — never prompts, message bodies, tokens, argv, env values, or
+ * filesystem paths.
+ */
+export function formatAgentLifecycleStatus(status) {
+    const lines = [];
+    const generation = status.runtimeGeneration === null ? "-" : String(status.runtimeGeneration);
+    lines.push(`${status.agentId}: ${status.state} (v${status.lifecycleVersion}, gen ${generation}, policy ${status.hibernatePolicy ?? "-"})`);
+    if (status.quarantined) {
+        lines.push(`  \u26a0 quarantined as reap-candidate${status.hibernateReason ? ` — ${status.hibernateReason}` : ""}`);
+    }
+    if (status.checkpoint.present) {
+        const ageSeconds = status.checkpoint.ageMs === null ? "?" : Math.round(status.checkpoint.ageMs / 1000);
+        const safe = status.checkpoint.hibernateSafe === false ? "unsafe" : "safe";
+        lines.push(`  checkpoint: ${safe}, age=${ageSeconds}s, pending_inbox=${status.checkpoint.pendingInboxCount ?? 0}, gen=${status.checkpoint.runtimeGeneration ?? "-"}`);
+    }
+    else if (DURABLE_HIBERNATION_STATES.has(status.state)) {
+        lines.push("  checkpoint: none recorded");
+    }
+    if (status.runtimeSpec) {
+        const spec = status.runtimeSpec;
+        lines.push(`  runtime spec: present (repo=${spec.repo ?? "-"}, worktree=${spec.hasWorktree ? "yes" : "no"}, runtime=${spec.runtimeKind}, env_allow=${spec.envAllowlistCount}, fingerprint=${spec.configFingerprint})`);
+    }
+    else if (DURABLE_HIBERNATION_STATES.has(status.state)) {
+        lines.push("  runtime spec: MISSING");
+    }
+    if (status.wake.queued) {
+        const position = status.wake.position === null ? "?" : String(status.wake.position);
+        lines.push(`  wake queued: position ${position}, trigger=${status.wake.triggerKind ?? "-"}, reason=${status.wake.reason ?? "-"}, attempt=${status.wake.attempt ?? 0}`);
+    }
+    if (status.capacity) {
+        const { global, repo } = status.capacity;
+        const globalMark = global.atCapacity ? " (at capacity)" : "";
+        const repoMark = repo.atCapacity ? " (at capacity)" : "";
+        lines.push(`  wake capacity: global ${global.inflight}/${global.max}${globalMark}, repo ${repo.inflight}/${repo.max}${repoMark}`);
+    }
+    if (status.refusal) {
+        lines.push(`  last refusal: ${status.refusal.reason} (${status.refusal.outcome}) at ${status.refusal.at}`);
+    }
+    if (status.lastWakeReason) {
+        lines.push(`  last wake reason: ${status.lastWakeReason}`);
+    }
+    return lines.join("\n");
+}

package/dist/hibernation-telemetry.d.ts

@@ -0,0 +1,54 @@
+import type { AgentLifecycleEvent, AgentLifecycleRetentionInfo } from "./types.js";
+/**
+ * Read-only, sanitized rollup of hibernation lifecycle telemetry.
+ *
+ * This is the operable status surface over the append-only
+ * `agent_lifecycle_events` table (see `getRecentAgentLifecycleEvents`). It is a
+ * pure derivation of already-sanitized events — it never reads prompts, message
+ * bodies, tokens, or environment values — so it is safe to render in a CLI,
+ * dashboard, or Slack status reply without touching the live broker.
+ *
+ * The counts mirror the documented dogfood report query so a fleet operator can
+ * reconcile this in-process summary against the raw SQL.
+ */
+export interface HibernationTelemetrySummary {
+    /** Total events considered. */
+    totalEvents: number;
+    /** Accepted transitions into `hibernated`. */
+    hibernations: number;
+    /** Accepted `waking -> live` transitions. */
+    wakeSuccesses: number;
+    /** Events whose outcome was not `accepted` (refusals, stale fences, aborts). */
+    failures: number;
+    /** Mean accepted wake latency in ms, or null when no accepted wake is present. */
+    meanWakeMs: number | null;
+    /** Nearest-rank 95th percentile accepted wake latency in ms, or null. */
+    p95WakeMs: number | null;
+    /** Largest observed queue depth across events. */
+    maxQueueDepth: number;
+    /** Largest observed oldest-queued-message age in ms across events. */
+    maxOldestQueueAgeMs: number;
+    /** Sum of max(rssBefore - rssAfter, 0) over accepted hibernations, in bytes. */
+    recoveredRssBytes: number;
+    /** Non-accepted outcome reasons, most frequent first. */
+    refusalReasons: Array<{
+        reason: string;
+        count: number;
+    }>;
+    /** Distinct agents represented in the event window. */
+    agentCount: number;
+    /** Retained/pruned counters when retention info is provided. */
+    retainedCount: number | null;
+    prunedCount: number | null;
+    lastPrunedAt: string | null;
+}
+/**
+ * Summarize a window of lifecycle events into an operable status rollup. Pass
+ * the newest events (any order); retention info is optional passthrough.
+ */
+export declare function summarizeHibernationTelemetry(events: AgentLifecycleEvent[], retention?: AgentLifecycleRetentionInfo): HibernationTelemetrySummary;
+/**
+ * Render a compact, human-readable status block from a telemetry summary. Safe
+ * for CLI/Slack output: it contains only aggregate counters, never bodies.
+ */
+export declare function formatHibernationTelemetry(summary: HibernationTelemetrySummary): string;