@scp-dev/core 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -387,6 +387,14 @@ declare const LIMITS: {
     readonly policyLoadsKept: 8;
     /** the prompts between two refreshes of a title a hook inferred */
     readonly titleRefreshTurns: 5;
+    /** the least time between two wake hook runs for one hibernated endpoint */
+    readonly wakeDebounceS: 60;
+    /** the longest backoff after failed wake hook runs */
+    readonly wakeBackoffMaxS: 900;
+    /** the longest opaque wake reference a provider stores with a hibernation */
+    readonly wakeRefChars: 512;
+    /** the longest wake time a provider may announce with a hibernation */
+    readonly wakeEtaMaxS: 3600;
 };
 type ErrorCode = "not_found" | "inbox_full" | "rate_limited" | "loop_guard" | "data_class_refused" | "secret_refused" | "policy_refused" | "too_large" | "invalid_params" | "unauthorized" | "method_not_found" | "scope_refused" | "unavailable" | "judge_refused" | "not_live";
 declare class RelayError extends Error {
@@ -401,11 +409,21 @@ declare class RelayError extends Error {
 type EndpointKind = "agent" | "human" | "system";
 type MessageKind = "message" | "request" | "reply" | "status";
 type DataClass = "public" | "private";
-type Presence = "online" | "idle" | "offline";
+/** `hibernated`: a provider suspended the session; a message runs its wake hook and the session drains its queue once it is back */
+type Presence = "online" | "idle" | "offline" | "hibernated";
+declare const PRESENCES: readonly Presence[];
 type StatusState = "working" | "waiting" | "blocked" | "done";
-/** how an idle agent is woken by a message: a channel push, the pi extension, the OpenCode plugin's waiter, codex app-server, the session inbox, a headless resume or muse serve; `none` reads at its next turn */
-type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "agy-resume" | "grok-resume" | "muse-serve" | "none";
+/**
+ * how an idle agent is woken by a message: a channel push, the pi extension, the OpenCode plugin's waiter, codex app-server, the session inbox,
+ * a headless resume or muse serve; `none` reads at its next turn; `hook:<provider>` (shown only, never set this way) a hibernated agent's provider wake hook
+ */
+type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "agy-resume" | "grok-resume" | "muse-serve" | "none" | `hook:${string}`;
 declare const WAKES: readonly Wake[];
+/** why a provider declined to wake a hibernated agent, a short token it picks (e.g. `policy`, `budget`): not a failure, and not retried for the same message */
+type WakeDecline = string;
+declare const WAKE_DECLINE: RegExp;
+/** `value` when it is a decline reason, else null */
+declare function wakeDeclineOf(value: unknown): WakeDecline | null;
 type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end";
 declare const ACTIVITY_KINDS: readonly ActivityKind[];
 interface ActivityRow {
@@ -462,6 +480,8 @@ interface Claim {
     in?: string[];
     out?: string[];
     groups?: string[];
+    /** an agent address a root claim links under, as a join under does; a refused link keeps the claim, audited */
+    under?: string;
 }
 type ScopeDirection = "in" | "out";
 type ScopePreset = "open" | "tree" | "parent" | "none";
@@ -581,6 +601,10 @@ interface EndpointView {
     peekable?: PeekLevel;
     /** an agent's: how an idle agent is woken by a message; null or `none`: it reads at its next turn */
     wake?: Wake | null;
+    /** a hibernated agent's last wake hook failure: the reason */
+    wake_failed?: string;
+    /** a hibernated agent's provider declined the last wake */
+    wake_declined?: WakeDecline;
 }
 type PeekLevel = "local";
 interface PeekTurn {
@@ -756,7 +780,8 @@ interface SendResult {
     /**
      * `queued`: the recipient is not connected now; `offline`: it has been gone past a short grace, so a client polling between waits is not
      * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out); `wake`: how it is woken, only when
-     * it can be; `idle`: its presence is idle
+     * it can be, `declined` when its provider declined the last wake; `idle`: its presence is idle; `hibernated`: it is hibernated and
+     * queued, its provider's wake hook resumes it; `wake_eta_s`: how long its provider said a wake takes
      */
     deliveries: {
         endpoint: string;
@@ -766,8 +791,10 @@ interface SendResult {
         queued?: boolean;
         last_seen: string | null;
         state?: Reach;
-        wake?: Wake;
+        wake?: Wake | "declined";
         idle?: true;
+        hibernated?: true;
+        wake_eta_s?: number;
     }[];
     /** one line per agent recipient no live session holds: `queued: no live session holds <address>` */
     warnings?: string[];
@@ -1128,6 +1155,40 @@ interface EndpointRow {
     wakers: number;
     /** when the last hook connection that set the wake closed */
     waker_left: number | null;
+    /** the provider whose wake hook resumes the hibernated session; null when it is not hibernated */
+    hibernate: string | null;
+    /** the provider's opaque reference to the suspended session, handed to its wake hook */
+    wake_ref: string | null;
+    hibernated_at: number | null;
+    /** when a wake hook last ran for it */
+    wake_tried: number | null;
+    /** the wake hook runs that failed in a row */
+    wake_fails: number;
+    /** `wake_failed: <reason>` after a failed run */
+    wake_note: string | null;
+    /** the seconds the provider said a wake takes */
+    wake_eta: number | null;
+    /** the reason the provider declined a wake, a short token such as `policy` or `budget` */
+    wake_declined: string | null;
+    /** the message, and its sender, the decline was for */
+    declined_message: string | null;
+    declined_from: string | null;
+}
+/** a wake hook run that is due: the hibernated endpoint, its provider and ref, and the newest unread message's metadata (never a body) */
+interface WakeJob {
+    endpoint: string;
+    address: string;
+    handle: string;
+    provider: string;
+    ref: string | null;
+    message: {
+        id: string;
+        from: string | null;
+        kind: MessageKind;
+        thread: string;
+        created_at: string;
+    };
+    unread: number;
 }
 interface MessageRow {
     id: string;
@@ -1167,6 +1228,8 @@ interface CoreOptions {
     /** the short hostname, matched by `machine:` selectors when `machine` is not set */
     hostname?: string;
 }
+/** a wake provider's name, as hibernate takes it and a waker is configured under */
+declare const WAKE_PROVIDER: RegExp;
 declare function randomHex(bytes: number): string;
 declare function newId(prefix: string, now?: number): string;
 declare function cleanText(value: unknown, field: string, max?: number): string | null;
@@ -1228,6 +1291,8 @@ declare class RelayCore {
         created?: true;
         subagent?: true;
     };
+    /** links a claimed root under `under` as a join under does; a refusal keeps the claim and is audited `claim_under_refused` */
+    private claimUnder;
     /** a claim's own rules per direction, as its `scope`, `allow`, `in` and `out` expand */
     protected claimRules(claim: Claim): ScopeRules;
     /**
@@ -1492,6 +1557,58 @@ declare class RelayCore {
     };
     /** the harness session key an endpoint holds, if any */
     sessionOf(endpoint: string): string | null;
+    /**
+     * marks a local agent hibernated by `wake`, the provider whose wake hook resumes it, with its opaque `ref` and the seconds a wake takes
+     * (`eta_s`); `none` clears it. The agent's own session or the human (no terminal needed: a provider's daemon has none) naming the endpoint.
+     * `known` is whether a waker is configured for a provider
+     */
+    hibernate(actor: ScopeActor, params: {
+        endpoint?: unknown;
+        wake?: unknown;
+        ref?: unknown;
+        eta_s?: unknown;
+    }, options?: {
+        known?: (provider: string) => boolean;
+    }): {
+        endpoint: EndpointView;
+    };
+    /** the human marks every live local agent but subagents hibernated by one provider, as before suspending the machine they run on */
+    hibernateAll(actor: ScopeActor, params: {
+        wake?: unknown;
+        ref?: unknown;
+        eta_s?: unknown;
+    }, options?: {
+        known?: (provider: string) => boolean;
+    }): {
+        endpoints: EndpointView[];
+    };
+    private hibernation;
+    private setHibernation;
+    /**
+     * the wake hook run a delivery to a hibernated local agent is due, recorded as tried: none while it is not hibernated, has no unread
+     * message, ran within LIMITS.wakeDebounceS (after failures, a doubling backoff up to LIMITS.wakeBackoffMaxS), or the provider declined a
+     * wake for the newest unread message or for another from its sender. The newest unread message's metadata only, never its body
+     */
+    wakeDue(endpoint: string, now?: number): WakeJob | null;
+    /**
+     * how a wake hook run ended, audited without the ref: a failure counts toward the backoff and shows `wake_failed` while the message stays
+     * queued; a decline (`declined`, for the message `message`) shows `wake_declined`, counts toward nothing and holds further runs for that
+     * message and its sender until a newer message of another sender or a new hibernate; a success resets both (the hibernation clears once the
+     * session claims its endpoint again). Whether the shown note changed
+     */
+    wakeResult(endpoint: string, result: {
+        ok: boolean;
+        code?: number | null;
+        error?: string | null;
+        ms: number;
+        declined?: WakeDecline;
+        message?: string;
+    }): boolean;
+    /** whether the row shows hibernated: a subclass also counts what another machine mirrored */
+    protected hibernated(row: EndpointRow): boolean;
+    /** the hibernated session is back, or gone: its hibernation clears */
+    private wakeDone;
+    private clearHibernation;
     /**
      * `origin.tty` is recorded on messages the human inbox sends: whether its client said a terminal was attached. `origin.unverified`: the human
      * sends without a terminal, so the scopes check it like any unplaced sender
@@ -2214,7 +2331,7 @@ type Delivery = Pick<SendResult["deliveries"][number], "address" | "offline" | "
  * when the broker named no state. With `late`, only those that will not see it at their next turn boundary
  */
 declare function reachLines(deliveries: Delivery[], late?: boolean): string[];
-/** an endpoint's presence as a line shows it: an idle agent no message wakes reads at its next turn */
+/** an endpoint's presence as a line shows it: an idle agent no message wakes reads at its next turn; a hibernated one is wakeable */
 declare function presenceText(e: Pick<EndpointView, "kind" | "presence" | "wake">): string;
 /** an agent's wake as a column shows it, `turn` when it reads at its next turn; `-` for any other endpoint */
 declare function wakeText(e: Pick<EndpointView, "kind" | "wake">): string;
@@ -2575,4 +2692,4 @@ declare function sha256Hex(text: string): string;
 /** the UTF-8 byte length of text, the unit every byte limit counts in */
 declare function utf8Bytes(text: string): number;
 
-export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AdoptResult, type AskResult, type Attachment, type AuditRow, BROKER_CAPABILITIES, type BreakerAdmission, CAPABILITIES, CLI_NAME, type Claim, type CoreOptions, type CrossAccountGate, type CrossAccountLink, DEFAULT_IMPLEMENTATION_PREFIXES, DEFAULT_JUDGE_BUDGET, DEFAULT_JUDGE_EFFORT, type DataClass, ERROR_CODES, type EndpointKind, type EndpointRow, type EndpointView, type Envelope, type ErrorCode, FakeJudgeClient, GENERIC_HARNESSES, GONE_PREFIX, GROUP_NAME, type GateContext, type GateVerdict, HANDBACK_CUT, HUMAN_HANDLE, HttpJudgeClient, type HttpJudgeOptions, JUDGE_BREAKER_DEFAULTS, JUDGE_CATEGORIES, JUDGE_EFFORTS, JUDGE_FALLBACK_NOTE, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_PROMPT_VERSION, JUDGE_PROVIDERS, JUDGE_VERDICTS, type JudgeAuditDetail, type JudgeAuditEvent, type JudgeBoundary, JudgeBreaker, type JudgeBreakerOptions, type JudgeBudget, type JudgeCategory, type JudgeClient, type JudgeContext, type JudgeEffort, type JudgeHeld, type JudgeModelConfig, type JudgePolicy, type JudgeProvider, JudgeProviderError, type JudgeRedacted, type JudgeSide, type JudgeStats, type JudgeVerdict, LIMITS, MESSAGE_KINDS, type MessageKind, type MessageReceipts, type MessageRow, OMITTED, PASS_GATE, PEEK, PREAMBLE, PREAMBLE_BRIEF, PRESET_LISTS, PROTOCOL, type PeekLevel, type PeekResult, type PeekSeen, type PeekState, type PeekTurn, type PeerView, type PiiHit, type Policy, type PolicyDefaults, type PolicyGroup, type PolicyRule, type PolicySubject, type Prefiltered, type Presence, REDACTION_KINDS, type Reach, type Redaction, RelayCore, RelayError, type RunJudgeInput, SCOPE_PRESETS, SERVER_FIELDS, SHORT_ID, STATUS_STATES, SYSTEM_HANDLE, type ScopeActor, type ScopeCap, type ScopeCaps, type ScopeChange, type ScopeDecision, type ScopeDirection, type ScopeEntry, type ScopeGroupIdentity, type ScopeGroupRules, type ScopeList, type ScopeNode, type ScopePolicyCap, type ScopePreset, type ScopeRules, type ScopeSubject, type ScopeView, type ScopeWorld, type SecretScanner, type Selector, type SendParams, type SendResult, type Sql, type SqlValue, type StatusState, type StopNudge, type StopWaitResult, TITLE_CHARS, type ThreadMessage, type Verdict, VerdictCache, WAKES, type Wake, type WhyResult, type XAllow, type XContact, XCounters, type XDelivered, type XEnvelopeFrom, XLIMITS, type XLimitConfig, type XLimits, type XListed, type XMessage, type XRelease, admits, allowlisted, applyRedactions, canonicalPolicy, cleanLabels, cleanText, clip, clipPasses, clipped, clock, collapseTools, createSecretScanner, crossFleet, dayStart, declaredLimits, deliveryText, digestText, dropQuoted, effectiveSelector, expandRules, findPii, findSecret, gateRefusal, groupCapKey, handbackOutput, harnessFits, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, keptHarness, leavesFleet, matches, mergeVerdicts, narrower, newId, newJudgeStats, one, parseJudgePolicy, parsePolicy, parseVerdict, parseXMessage, peekLevel, policyRefusal, prefilter, presenceText, presetOf, randomHex, reachLines, readText, receiptLines, redactPii, redactSecrets, redactionKind, relation, relationText, replyGrant, runJudge, sameSecret, scopeDecision, scopeLists, seqList, setImplementationPrefixes, sha256Hex, shortId, steerNote, stripControl, stripRelaySpans, stripSteerNote, unreachable, untilTomorrow, utf8Bytes, validHandle, validHarness, validSelector, wakeText, widenText, wrapMessage, wrapPeek, xlimits };
+export { ACCOUNT_HANDLE, ACTIVITY_KINDS, type ActivityKind, type ActivityRow, type Admission, type AdoptResult, type AskResult, type Attachment, type AuditRow, BROKER_CAPABILITIES, type BreakerAdmission, CAPABILITIES, CLI_NAME, type Claim, type CoreOptions, type CrossAccountGate, type CrossAccountLink, DEFAULT_IMPLEMENTATION_PREFIXES, DEFAULT_JUDGE_BUDGET, DEFAULT_JUDGE_EFFORT, type DataClass, ERROR_CODES, type EndpointKind, type EndpointRow, type EndpointView, type Envelope, type ErrorCode, FakeJudgeClient, GENERIC_HARNESSES, GONE_PREFIX, GROUP_NAME, type GateContext, type GateVerdict, HANDBACK_CUT, HUMAN_HANDLE, HttpJudgeClient, type HttpJudgeOptions, JUDGE_BREAKER_DEFAULTS, JUDGE_CATEGORIES, JUDGE_EFFORTS, JUDGE_FALLBACK_NOTE, JUDGE_MAX_OUTPUT_TOKENS, JUDGE_PROMPT_VERSION, JUDGE_PROVIDERS, JUDGE_VERDICTS, type JudgeAuditDetail, type JudgeAuditEvent, type JudgeBoundary, JudgeBreaker, type JudgeBreakerOptions, type JudgeBudget, type JudgeCategory, type JudgeClient, type JudgeContext, type JudgeEffort, type JudgeHeld, type JudgeModelConfig, type JudgePolicy, type JudgeProvider, JudgeProviderError, type JudgeRedacted, type JudgeSide, type JudgeStats, type JudgeVerdict, LIMITS, MESSAGE_KINDS, type MessageKind, type MessageReceipts, type MessageRow, OMITTED, PASS_GATE, PEEK, PREAMBLE, PREAMBLE_BRIEF, PRESENCES, PRESET_LISTS, PROTOCOL, type PeekLevel, type PeekResult, type PeekSeen, type PeekState, type PeekTurn, type PeerView, type PiiHit, type Policy, type PolicyDefaults, type PolicyGroup, type PolicyRule, type PolicySubject, type Prefiltered, type Presence, REDACTION_KINDS, type Reach, type Redaction, RelayCore, RelayError, type RunJudgeInput, SCOPE_PRESETS, SERVER_FIELDS, SHORT_ID, STATUS_STATES, SYSTEM_HANDLE, type ScopeActor, type ScopeCap, type ScopeCaps, type ScopeChange, type ScopeDecision, type ScopeDirection, type ScopeEntry, type ScopeGroupIdentity, type ScopeGroupRules, type ScopeList, type ScopeNode, type ScopePolicyCap, type ScopePreset, type ScopeRules, type ScopeSubject, type ScopeView, type ScopeWorld, type SecretScanner, type Selector, type SendParams, type SendResult, type Sql, type SqlValue, type StatusState, type StopNudge, type StopWaitResult, TITLE_CHARS, type ThreadMessage, type Verdict, VerdictCache, WAKES, WAKE_DECLINE, WAKE_PROVIDER, type Wake, type WakeDecline, type WakeJob, type WhyResult, type XAllow, type XContact, XCounters, type XDelivered, type XEnvelopeFrom, XLIMITS, type XLimitConfig, type XLimits, type XListed, type XMessage, type XRelease, admits, allowlisted, applyRedactions, canonicalPolicy, cleanLabels, cleanText, clip, clipPasses, clipped, clock, collapseTools, createSecretScanner, crossFleet, dayStart, declaredLimits, deliveryText, digestText, dropQuoted, effectiveSelector, expandRules, findPii, findSecret, gateRefusal, groupCapKey, handbackOutput, harnessFits, hasScope, honestSender, isLeaving, joinRedacted, judgeBoundary, judgeDetailForAgents, judgeFellBack, judgeModel, judgePrompt, keepLast, keptHarness, leavesFleet, matches, mergeVerdicts, narrower, newId, newJudgeStats, one, parseJudgePolicy, parsePolicy, parseVerdict, parseXMessage, peekLevel, policyRefusal, prefilter, presenceText, presetOf, randomHex, reachLines, readText, receiptLines, redactPii, redactSecrets, redactionKind, relation, relationText, replyGrant, runJudge, sameSecret, scopeDecision, scopeLists, seqList, setImplementationPrefixes, sha256Hex, shortId, steerNote, stripControl, stripRelaySpans, stripSteerNote, unreachable, untilTomorrow, utf8Bytes, validHandle, validHarness, validSelector, wakeDeclineOf, wakeText, widenText, wrapMessage, wrapPeek, xlimits };

package/dist/index.js

@@ -166,7 +166,15 @@ var LIMITS = {
   groupIdleS: 86400,
   policyLoadsKept: 8,
   /** the prompts between two refreshes of a title a hook inferred */
-  titleRefreshTurns: 5
+  titleRefreshTurns: 5,
+  /** the least time between two wake hook runs for one hibernated endpoint */
+  wakeDebounceS: 60,
+  /** the longest backoff after failed wake hook runs */
+  wakeBackoffMaxS: 900,
+  /** the longest opaque wake reference a provider stores with a hibernation */
+  wakeRefChars: 512,
+  /** the longest wake time a provider may announce with a hibernation */
+  wakeEtaMaxS: 3600
 };
 var RelayError = class extends Error {
   constructor(code, message, retryAfterS, detail) {
@@ -179,6 +187,7 @@ var RelayError = class extends Error {
   retryAfterS;
   detail;
 };
+var PRESENCES = ["online", "idle", "offline", "hibernated"];
 var WAKES = [
   "channels",
   "pi",
@@ -190,6 +199,10 @@ var WAKES = [
   "muse-serve",
   "none"
 ];
+var WAKE_DECLINE = /^[a-z][a-z0-9_-]{0,31}$/;
+function wakeDeclineOf(value) {
+  return typeof value === "string" && WAKE_DECLINE.test(value) ? value : null;
+}
 var ACTIVITY_KINDS = ["session_start", "tool", "stop", "note", "session_end"];
 var MESSAGE_KINDS = ["message", "request", "reply", "status"];
 var STATUS_STATES = ["working", "waiting", "blocked", "done"];
@@ -905,6 +918,7 @@ function reachLines(deliveries, late = false) {
   return deliveries.filter((d) => !late || d.state && d.state !== "running").map((d) => d.state ? `${d.address}: ${reachText({ ...d, state: d.state })}` : deliveryText(d));
 }
 function presenceText(e) {
+  if (e.presence === "hibernated") return "hibernated (wakeable)";
   return e.kind === "agent" && e.presence === "idle" && (!e.wake || e.wake === "none") ? "idle (next turn)" : e.presence;
 }
 function wakeText(e) {
@@ -1234,6 +1248,7 @@ var MIGRATION = [
 ];
 var GRANT_TOKEN = /^krt_[0-9a-f]{64}$/;
 var HARNESS_SESSION = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+var WAKE_PROVIDER = /^[a-z0-9][a-z0-9-]{0,31}$/;
 var TRANSCRIPT_CHARS = 4096;
 function transcriptPath(path, session) {
   if (typeof path !== "string" || path.length > TRANSCRIPT_CHARS || !path.startsWith("/") || /[\u0000-\u001f\u007f]/.test(path)) return null;
@@ -1372,7 +1387,17 @@ var RelayCore = class {
       ["linked", "INTEGER"],
       ["wake", "TEXT"],
       ["wakers", "INTEGER NOT NULL DEFAULT 0"],
-      ["waker_left", "INTEGER"]
+      ["waker_left", "INTEGER"],
+      ["hibernate", "TEXT"],
+      ["wake_ref", "TEXT"],
+      ["hibernated_at", "INTEGER"],
+      ["wake_tried", "INTEGER"],
+      ["wake_fails", "INTEGER NOT NULL DEFAULT 0"],
+      ["wake_note", "TEXT"],
+      ["wake_eta", "INTEGER"],
+      ["wake_declined", "TEXT"],
+      ["declined_message", "TEXT"],
+      ["declined_from", "TEXT"]
     ]) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`);
     }
@@ -1537,7 +1562,8 @@ var RelayCore = class {
     if (fields.process !== null && !ANY_PROCESS_KEY.test(fields.process)) throw new RelayError("invalid_params", "process is a key pid:<pid>[:<start time>]");
     if (fields.harness_session !== null && !HARNESS_SESSION.test(fields.harness_session))
       throw new RelayError("invalid_params", "harness_session is a harness's session id: letters, digits, . _ : -");
-    const leaked = [wanted, fields.model, fields.cwd, fields.parent, fields.labels, fields.session, fields.harness_session].map((v) => v ? findSecret(v) : null).find(Boolean);
+    const under = cleanText(claim.under, "under", 128) || null;
+    const leaked = [wanted, fields.model, fields.cwd, fields.parent, fields.labels, fields.session, fields.harness_session, under].map((v) => v ? findSecret(v) : null).find(Boolean);
     if (leaked) throw new RelayError("secret_refused", `the claim looks like it carries a credential (${leaked})`);
     if (claim.grant !== void 0 && (typeof claim.grant !== "string" || !GRANT_TOKEN.test(claim.grant)))
       throw new RelayError("invalid_params", "grant is a krt_ token");
@@ -1567,17 +1593,33 @@ var RelayCore = class {
           root.id
         );
         if (subagent.stop && !had) throw new RelayError("not_found", "that subagent has no endpoint: it never ran a tool");
-        const claimed = this.claimRow(scope.handle, harness, fields, true, scope);
-        const titled = this.takeSubagentTitle(root.id, subagent.id, claimed.endpoint.id);
-        const resumed = !subagent.stop && one(this.sql, `UPDATE endpoints SET status_state = 'working' WHERE id = ? AND status_state = 'done' RETURNING id`, claimed.endpoint.id);
-        if (!titled && !resumed) return { ...claimed, subagent: true };
-        return { ...claimed, endpoint: this.view(this.byId(claimed.endpoint.id)), subagent: true };
+        const claimed2 = this.claimRow(scope.handle, harness, fields, true, scope);
+        const titled = this.takeSubagentTitle(root.id, subagent.id, claimed2.endpoint.id);
+        const resumed = !subagent.stop && one(this.sql, `UPDATE endpoints SET status_state = 'working' WHERE id = ? AND status_state = 'done' RETURNING id`, claimed2.endpoint.id);
+        if (!titled && !resumed) return { ...claimed2, subagent: true };
+        return { ...claimed2, endpoint: this.view(this.byId(claimed2.endpoint.id)), subagent: true };
       }
       const bound = scope.grant === null && !scope.exact ? this.boundGrant(scope, fields.process) : void 0;
       if (bound) Object.assign(scope, { grant: bound.token_hash, handle: bound.name ?? wanted });
-      return this.claimRow(scope.handle, harness, fields, options.transient === true, scope);
+      const claimed = this.claimRow(scope.handle, harness, fields, options.transient === true, scope);
+      return under === null ? claimed : this.claimUnder(claimed, under);
     });
   }
+  /** links a claimed root under `under` as a join under does; a refusal keeps the claim and is audited `claim_under_refused` */
+  claimUnder(claimed, under) {
+    const me = this.mustEndpoint(claimed.endpoint.id);
+    if (me.kind !== "agent" || !this.localRow(me) || me.parent_ep !== null || me.parent_addr !== null) return claimed;
+    try {
+      const parent = this.resolve(under);
+      if (parent.kind === "agent" && !this.mayMessage(me, parent)) throw unreachable(under);
+      this.link(me, parent, { by: this.address(me), auth: "session" });
+    } catch (error) {
+      if (!(error instanceof RelayError)) throw error;
+      this.audit("claim_under_refused", me.id, null, { target: this.address(me), under, code: error.code });
+      return claimed;
+    }
+    return { ...claimed, endpoint: this.view(this.byId(me.id)) };
+  }
   /** a claim's own rules per direction, as its `scope`, `allow`, `in` and `out` expand */
   claimRules(claim) {
     const rules = {};
@@ -1768,6 +1810,7 @@ var RelayCore = class {
     if (created || fresh === "grant") this.place(this.byId(row.id), scope, now);
     else if (scope.grant !== null) this.redeem(this.byId(row.id), scope, now);
     if (scope.grant !== null) this.takePending(row.id);
+    if (!transient) this.wakeDone(row.id, "claim");
     return { endpoint: this.view(this.byId(row.id)), ...token ? { token } : {}, ...created ? { created: true } : {} };
   }
   /**
@@ -1840,6 +1883,7 @@ var RelayCore = class {
         row.id
       );
     this.sql.all(`DELETE FROM peek_turns WHERE endpoint = ?`, row.id);
+    this.wakeDone(row.id, "reset");
     let dropped = 0;
     if (kind === "grant") {
       const spawned = one(this.sql, `SELECT issuer, created_at FROM grants WHERE token_hash = ?`, scope.grant);
@@ -2132,7 +2176,7 @@ var RelayCore = class {
     const viewer = filters.viewer === void 0 ? void 0 : this.mustEndpoint(filters.viewer);
     const shown = viewer ? new Set(this.visibleRows(viewer).map((row) => row.id)) : void 0;
     const peeker = viewer ?? (filters.peekable === true ? this.byHandle(HUMAN_HANDLE) : void 0);
-    return this.listed().filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff || waking(row, now)).filter((row) => !filters.harness || row.harness === filters.harness).filter((row) => !filters.kind || row.kind === filters.kind).filter((row) => !viewer || row.id === viewer.id || this.mayMessage(viewer, row, viewer.kind === "human")).map((row) => {
+    return this.listed().filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff || waking(row, now) || this.hibernated(row)).filter((row) => !filters.harness || row.harness === filters.harness).filter((row) => !filters.kind || row.kind === filters.kind).filter((row) => !viewer || row.id === viewer.id || this.mayMessage(viewer, row, viewer.kind === "human")).map((row) => {
       const view = this.view(row, shown);
       return peeker && this.peekableBy(peeker, row, viewer?.kind === "human") ? { ...view, peekable: row.peek } : view;
     }).filter((view) => !filters.presence || view.presence === filters.presence);
@@ -2309,6 +2353,7 @@ var RelayCore = class {
       const row = this.mustEndpoint(endpoint.id);
       if (handle !== void 0 && handle !== null && handle !== "") this.renameRow(row, handle, false);
       this.sql.all(`UPDATE endpoints SET hook_seen = ?, hook_ended = NULL WHERE id = ?`, this.now(), row.id);
+      this.wakeDone(row.id, "join");
       this.audit("join", row.id, null, { handle: this.byId(row.id).handle });
       if (under !== void 0 && under !== null && under !== "") {
         const me = this.byId(row.id);
@@ -2586,6 +2631,7 @@ var RelayCore = class {
       row.id
     );
     this.sql.all(`UPDATE endpoints SET handle = ?, session = NULL, token_hash = NULL WHERE id = ?`, `${GONE_PREFIX}${held.id}`, held.id);
+    this.wakeDone(held.id, "retired");
     this.dropPeek(held.id);
     this.scopeMemo?.ancestors.clear();
     this.scopeMemo?.limited.clear();
@@ -2612,6 +2658,7 @@ var RelayCore = class {
         throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; a spawned worker stays joined while it runs`);
       }
       this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ?, wake = NULL WHERE id = ?`, this.now(), target.id);
+      this.wakeDone(target.id, "leave");
       this.audit("leave", target.id, null, { handle: target.handle });
       return { endpoint: this.whoami(target.id), session: target.session };
     });
@@ -2620,6 +2667,171 @@ var RelayCore = class {
   sessionOf(endpoint) {
     return this.byId(endpoint)?.session ?? null;
   }
+  /**
+   * marks a local agent hibernated by `wake`, the provider whose wake hook resumes it, with its opaque `ref` and the seconds a wake takes
+   * (`eta_s`); `none` clears it. The agent's own session or the human (no terminal needed: a provider's daemon has none) naming the endpoint.
+   * `known` is whether a waker is configured for a provider
+   */
+  hibernate(actor, params, options = {}) {
+    const me = this.actorRow(actor);
+    const set = this.hibernation(params, options);
+    if (actor.kind === "endpoint" && actor.auth === "lineage")
+      throw new RelayError("scope_refused", "only the session itself hibernates: run this from the session's own shell");
+    if (params.endpoint === void 0 && me.kind !== "agent") throw new RelayError("invalid_params", "the human names the endpoint");
+    const target = params.endpoint === void 0 ? me : this.resolve(params.endpoint);
+    if (actor.kind === "endpoint" && target.id !== me.id) throw new RelayError("scope_refused", "an agent hibernates only itself");
+    if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint hibernates");
+    return { endpoint: this.setHibernation(me, target, set) };
+  }
+  /** the human marks every live local agent but subagents hibernated by one provider, as before suspending the machine they run on */
+  hibernateAll(actor, params, options = {}) {
+    const me = this.actorRow(actor);
+    if (actor.kind !== "human") throw new RelayError("scope_refused", "only the human hibernates every agent");
+    const set = this.hibernation(params, options);
+    const now = this.now();
+    const targets = this.sql.all(
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND substr(handle, 1, ${GONE_PREFIX.length}) != '${GONE_PREFIX}'
+         AND (session IS NULL OR substr(session, 1, 4) != 'sub:') ORDER BY handle`
+    ).filter((row) => this.localRow(row) && (set.wake === "none" ? row.hibernate !== null : presenceOf(row, now) !== "offline"));
+    return { endpoints: targets.map((row) => this.setHibernation(me, row, set)) };
+  }
+  hibernation(params, options) {
+    const wake = params?.wake;
+    if (typeof wake !== "string" || wake !== "none" && !WAKE_PROVIDER.test(wake))
+      throw new RelayError("invalid_params", "wake is a provider name (lowercase letters, digits and hyphens, at most 32) or none");
+    let ref = null;
+    if (params.ref !== void 0 && params.ref !== null) {
+      if (typeof params.ref !== "string" || params.ref.length > LIMITS.wakeRefChars || /[\u0000-\u001f\u007f]/.test(params.ref))
+        throw new RelayError("invalid_params", `ref is a string of at most ${LIMITS.wakeRefChars} characters with no control characters`);
+      if (findSecret(params.ref)) throw new RelayError("secret_refused", "the wake ref looks like it carries a credential");
+      ref = params.ref;
+    }
+    let eta = null;
+    if (params.eta_s !== void 0 && params.eta_s !== null) {
+      if (typeof params.eta_s !== "number" || !Number.isInteger(params.eta_s) || params.eta_s < 1 || params.eta_s > LIMITS.wakeEtaMaxS)
+        throw new RelayError("invalid_params", `eta_s is a whole number of seconds from 1 to ${LIMITS.wakeEtaMaxS}`);
+      eta = params.eta_s;
+    }
+    if (wake !== "none" && options.known && !options.known(wake)) throw new RelayError("invalid_params", `no waker ${wake} is configured`);
+    return { wake, ref, eta };
+  }
+  setHibernation(me, target, set) {
+    const address = this.address(target);
+    if (set.wake === "none") {
+      if (target.hibernate !== null) {
+        this.clearHibernation(target.id);
+        this.audit("unhibernate", target.id, null, { by: this.address(me), target: address });
+      }
+      return this.view(this.byId(target.id));
+    }
+    this.clearHibernation(target.id);
+    this.sql.all(
+      `UPDATE endpoints SET hibernate = ?, wake_ref = ?, wake_eta = ?, hibernated_at = ? WHERE id = ?`,
+      set.wake,
+      set.ref,
+      set.eta,
+      this.now(),
+      target.id
+    );
+    this.audit("hibernate", target.id, null, { by: this.address(me), target: address, provider: set.wake });
+    return this.view(this.byId(target.id));
+  }
+  /**
+   * the wake hook run a delivery to a hibernated local agent is due, recorded as tried: none while it is not hibernated, has no unread
+   * message, ran within LIMITS.wakeDebounceS (after failures, a doubling backoff up to LIMITS.wakeBackoffMaxS), or the provider declined a
+   * wake for the newest unread message or for another from its sender. The newest unread message's metadata only, never its body
+   */
+  wakeDue(endpoint, now = this.now()) {
+    const row = this.byId(endpoint);
+    if (!row?.hibernate || row.kind !== "agent" || !this.localRow(row)) return null;
+    if (row.wake_tried !== null) {
+      const waitS = row.wake_fails > 0 ? Math.min(LIMITS.wakeDebounceS * 2 ** row.wake_fails, LIMITS.wakeBackoffMaxS) : LIMITS.wakeDebounceS;
+      if (now - row.wake_tried < waitS * 1e3) return null;
+    }
+    const newest = one(
+      this.sql,
+      `SELECT m.id, m.from_ep, m.kind, m.thread, m.created_at FROM deliveries d JOIN messages m ON m.id = d.message_id
+       WHERE d.endpoint = ? AND d.acked_at IS NULL AND d.expires_at > ? ORDER BY d.seq DESC LIMIT 1`,
+      endpoint,
+      now
+    );
+    if (!newest) return null;
+    if (row.wake_declined !== null && (newest.id === row.declined_message || newest.from_ep === row.declined_from)) return null;
+    const unread = one(
+      this.sql,
+      `SELECT COUNT(*) AS n FROM deliveries WHERE endpoint = ? AND acked_at IS NULL AND expires_at > ?`,
+      endpoint,
+      now
+    ).n;
+    this.sql.all(`UPDATE endpoints SET wake_tried = ? WHERE id = ?`, now, endpoint);
+    const sender = this.byId(newest.from_ep);
+    return {
+      endpoint,
+      address: this.address(row),
+      handle: row.handle,
+      provider: row.hibernate,
+      ref: row.wake_ref,
+      message: { id: newest.id, from: sender ? this.address(sender) : null, kind: newest.kind, thread: newest.thread, created_at: iso(newest.created_at) },
+      unread
+    };
+  }
+  /**
+   * how a wake hook run ended, audited without the ref: a failure counts toward the backoff and shows `wake_failed` while the message stays
+   * queued; a decline (`declined`, for the message `message`) shows `wake_declined`, counts toward nothing and holds further runs for that
+   * message and its sender until a newer message of another sender or a new hibernate; a success resets both (the hibernation clears once the
+   * session claims its endpoint again). Whether the shown note changed
+   */
+  wakeResult(endpoint, result) {
+    const row = this.byId(endpoint);
+    if (!row) return false;
+    const error = result.error ? redactSecrets(stripControl(result.error).replace(/\s+/g, " ").trim()).slice(0, 200) : null;
+    const declined = result.ok ? null : wakeDeclineOf(result.declined);
+    this.audit("wake", endpoint, null, {
+      target: this.address(row),
+      provider: row.hibernate,
+      ok: result.ok,
+      ...result.code !== void 0 && result.code !== null ? { code: result.code } : {},
+      ms: Math.max(0, Math.round(result.ms)),
+      ...declined ? { declined } : error ? { error } : {}
+    });
+    if (!row.hibernate) return false;
+    if (declined) {
+      const message = result.message ? one(this.sql, `SELECT from_ep FROM messages WHERE id = ?`, result.message) : void 0;
+      this.sql.all(
+        `UPDATE endpoints SET wake_declined = ?, declined_message = ?, declined_from = ?, wake_note = NULL, wake_tried = NULL WHERE id = ?`,
+        declined,
+        result.message ?? null,
+        message?.from_ep ?? null,
+        endpoint
+      );
+      return declined !== row.wake_declined || row.wake_note !== null;
+    }
+    const note = result.ok ? null : `wake_failed: ${(error ?? (result.code !== void 0 && result.code !== null ? `exit ${result.code}` : "failed")).slice(0, 120)}`;
+    this.sql.all(
+      `UPDATE endpoints SET wake_fails = ${result.ok ? "0" : "wake_fails + 1"}, wake_note = ?, wake_declined = NULL, declined_message = NULL, declined_from = NULL WHERE id = ?`,
+      note,
+      endpoint
+    );
+    return note !== row.wake_note || row.wake_declined !== null;
+  }
+  /** whether the row shows hibernated: a subclass also counts what another machine mirrored */
+  hibernated(row) {
+    return row.hibernate !== null;
+  }
+  /** the hibernated session is back, or gone: its hibernation clears */
+  wakeDone(endpoint, how) {
+    const row = this.byId(endpoint);
+    if (!row?.hibernate) return;
+    this.clearHibernation(endpoint);
+    this.audit("wake_done", endpoint, null, { target: this.address(row), how });
+  }
+  clearHibernation(endpoint) {
+    this.sql.all(
+      `UPDATE endpoints SET hibernate = NULL, wake_ref = NULL, wake_eta = NULL, hibernated_at = NULL, wake_tried = NULL, wake_fails = 0, wake_note = NULL,
+       wake_declined = NULL, declined_message = NULL, declined_from = NULL WHERE id = ?`,
+      endpoint
+    );
+  }
   // messages
   /**
    * `origin.tty` is recorded on messages the human inbox sends: whether its client said a terminal was attached. `origin.unverified`: the human
@@ -2682,8 +2894,9 @@ var RelayCore = class {
     const dark = recipients.filter(
       (r) => r.kind === "agent" && shownPresence(r, now) === "offline" && (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || r.session === null && r.token_hash === null && r.hook_ended !== null) && !this.unjoinedSpawn(sender, r.handle, now)
     );
-    if (params.live === true && dark.length)
-      throw new RelayError("not_live", `no live session holds ${dark.map((r) => this.address(r)).join(", ")}: nothing was queued`);
+    const asleep = params.live === true ? recipients.filter((r) => r.kind === "agent" && r.hibernate !== null) : [];
+    if (params.live === true && (dark.length || asleep.length))
+      throw new RelayError("not_live", `no live session holds ${[...dark, ...asleep].map((r) => this.address(r)).join(", ")}: nothing was queued`);
     const warnings = dark.map((r) => `queued: no live session holds ${this.address(r)}`);
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }));
     const reached = recipients.length + pending.length;
@@ -2888,8 +3101,9 @@ var RelayCore = class {
         this.sql.all(`INSERT INTO pair_events (from_ep, to_ep, at) VALUES (?, ?, ?)`, from, recipient.id, now);
         if (treeSends && recipient.kind !== "human") this.sql.all(`INSERT INTO tree_events (tree, at) VALUES (?, ?)`, tree, now);
         const view = this.view(recipient);
-        const queued = view.presence === "offline";
-        const offline = queued && now - Math.max(recipient.last_seen ?? 0, recipient.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS;
+        const hibernated = view.presence === "hibernated";
+        const queued = view.presence === "offline" || hibernated;
+        const offline = view.presence === "offline" && now - Math.max(recipient.last_seen ?? 0, recipient.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS;
         const state = this.reach(sender, recipient, offline, now);
         deliveries.push({
           endpoint: recipient.id,
@@ -2899,8 +3113,10 @@ var RelayCore = class {
           ...queued ? { queued } : {},
           last_seen: view.last_seen,
           ...state ? { state } : {},
-          ...view.wake ? { wake: view.wake } : {},
-          ...view.presence === "idle" ? { idle: true } : {}
+          ...hibernated && recipient.wake_declined ? { wake: "declined" } : view.wake ? { wake: view.wake } : {},
+          ...view.presence === "idle" ? { idle: true } : {},
+          ...hibernated ? { hibernated: true } : {},
+          ...hibernated && recipient.wake_eta ? { wake_eta_s: recipient.wake_eta } : {}
         });
       }
       for (const { key, address } of pending) {
@@ -3854,6 +4070,7 @@ var RelayCore = class {
           endpoint
         );
     } else if (params.kind === "session_start") {
+      this.wakeDone(endpoint, "session_start");
       const fresh = own && summary !== "compact" && summary !== "resume";
       this.sql.all(
         `UPDATE endpoints SET hook_seen = COALESCE(?, hook_seen), hook_ended = NULL, stop_blocks = CASE WHEN ? THEN 0 ELSE stop_blocks END, pushes = CASE WHEN ? THEN 0 ELSE pushes END,
@@ -5630,7 +5847,9 @@ ${stderr}` : "";
       presence,
       status: row.status_state ? { state: row.status_state, note: row.status_note ?? "" } : null,
       last_seen: iso(row.last_seen),
-      ...row.kind === "agent" ? { ...this.placeView(row, shown), wake: wakeOf(row) } : {}
+      ...row.kind === "agent" ? { ...this.placeView(row, shown), wake: row.hibernate ? `hook:${row.hibernate}` : wakeOf(row) } : {},
+      ...row.hibernate && row.wake_note ? { wake_failed: row.wake_note.replace(/^wake_failed: /, "") } : {},
+      ...row.hibernate && row.wake_declined ? { wake_declined: row.wake_declined } : {}
     };
   }
   placeView(row, shown) {
@@ -5859,6 +6078,7 @@ function waking(row, now) {
   return wakeOf(row) !== null && (row.wakers > 0 || (row.waker_left ?? 0) >= now - LIMITS.restartGraceS * 1e3);
 }
 function shownPresence(row, now) {
+  if (row.hibernate) return "hibernated";
   const presence = presenceOf(row, now);
   return presence === "offline" && waking(row, now) ? "idle" : presence;
 }
@@ -6666,6 +6886,7 @@ export {
   PEEK,
   PREAMBLE,
   PREAMBLE_BRIEF,
+  PRESENCES,
   PRESET_LISTS,
   PROTOCOL,
   REDACTION_KINDS,
@@ -6679,6 +6900,8 @@ export {
   TITLE_CHARS,
   VerdictCache,
   WAKES,
+  WAKE_DECLINE,
+  WAKE_PROVIDER,
   XCounters,
   XLIMITS,
   admits,
@@ -6762,6 +6985,7 @@ export {
   validHandle,
   validHarness,
   validSelector,
+  wakeDeclineOf,
   wakeText,
   widenText,
   wrapMessage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Swarm Communication Protocol core: wire types, framing, scopes, policy, judge and the relay core.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",

package/src/core.ts

@@ -45,6 +45,8 @@ import {
   validHandle,
   validHarness,
   type Wake,
+  type WakeDecline,
+  wakeDeclineOf,
   WAKES,
   type WhyResult,
 } from "./protocol"
@@ -274,6 +276,35 @@ export interface EndpointRow {
   wakers: number
   /** when the last hook connection that set the wake closed */
   waker_left: number | null
+  /** the provider whose wake hook resumes the hibernated session; null when it is not hibernated */
+  hibernate: string | null
+  /** the provider's opaque reference to the suspended session, handed to its wake hook */
+  wake_ref: string | null
+  hibernated_at: number | null
+  /** when a wake hook last ran for it */
+  wake_tried: number | null
+  /** the wake hook runs that failed in a row */
+  wake_fails: number
+  /** `wake_failed: <reason>` after a failed run */
+  wake_note: string | null
+  /** the seconds the provider said a wake takes */
+  wake_eta: number | null
+  /** the reason the provider declined a wake, a short token such as `policy` or `budget` */
+  wake_declined: string | null
+  /** the message, and its sender, the decline was for */
+  declined_message: string | null
+  declined_from: string | null
+}
+
+/** a wake hook run that is due: the hibernated endpoint, its provider and ref, and the newest unread message's metadata (never a body) */
+export interface WakeJob {
+  endpoint: string
+  address: string
+  handle: string
+  provider: string
+  ref: string | null
+  message: { id: string; from: string | null; kind: MessageKind; thread: string; created_at: string }
+  unread: number
 }
 
 export interface MessageRow {
@@ -405,6 +436,8 @@ interface ClaimScope {
 const GRANT_TOKEN = /^krt_[0-9a-f]{64}$/
 /** a harness's session id as its hooks name it: a UUID or a similar token */
 const HARNESS_SESSION = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+/** a wake provider's name, as hibernate takes it and a waker is configured under */
+export const WAKE_PROVIDER = /^[a-z0-9][a-z0-9-]{0,31}$/
 const TRANSCRIPT_CHARS = 4096
 
 /** a hook's transcript path for harness session `session`: an absolute path without control characters whose file is `<session>.jsonl` */
@@ -563,6 +596,16 @@ export class RelayCore {
       ["wake", "TEXT"],
       ["wakers", "INTEGER NOT NULL DEFAULT 0"],
       ["waker_left", "INTEGER"],
+      ["hibernate", "TEXT"],
+      ["wake_ref", "TEXT"],
+      ["hibernated_at", "INTEGER"],
+      ["wake_tried", "INTEGER"],
+      ["wake_fails", "INTEGER NOT NULL DEFAULT 0"],
+      ["wake_note", "TEXT"],
+      ["wake_eta", "INTEGER"],
+      ["wake_declined", "TEXT"],
+      ["declined_message", "TEXT"],
+      ["declined_from", "TEXT"],
     ] as const) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`)
     }
@@ -733,7 +776,8 @@ export class RelayCore {
     if (fields.process !== null && !ANY_PROCESS_KEY.test(fields.process)) throw new RelayError("invalid_params", "process is a key pid:<pid>[:<start time>]")
     if (fields.harness_session !== null && !HARNESS_SESSION.test(fields.harness_session))
       throw new RelayError("invalid_params", "harness_session is a harness's session id: letters, digits, . _ : -")
-    const leaked = [wanted, fields.model, fields.cwd, fields.parent, fields.labels, fields.session, fields.harness_session]
+    const under = cleanText(claim.under, "under", 128) || null
+    const leaked = [wanted, fields.model, fields.cwd, fields.parent, fields.labels, fields.session, fields.harness_session, under]
       .map((v) => (v ? findSecret(v) : null))
       .find(Boolean)
     if (leaked) throw new RelayError("secret_refused", `the claim looks like it carries a credential (${leaked})`)
@@ -775,10 +819,27 @@ export class RelayCore {
       }
       const bound = scope.grant === null && !scope.exact ? this.boundGrant(scope, fields.process) : undefined
       if (bound) Object.assign(scope, { grant: bound.token_hash, handle: bound.name ?? wanted })
-      return this.claimRow(scope.handle, harness, fields, options.transient === true, scope)
+      const claimed = this.claimRow(scope.handle, harness, fields, options.transient === true, scope)
+      return under === null ? claimed : this.claimUnder(claimed, under)
     })
   }
 
+  /** links a claimed root under `under` as a join under does; a refusal keeps the claim and is audited `claim_under_refused` */
+  private claimUnder<T extends { endpoint: EndpointView }>(claimed: T, under: string): T {
+    const me = this.mustEndpoint(claimed.endpoint.id)
+    if (me.kind !== "agent" || !this.localRow(me) || me.parent_ep !== null || me.parent_addr !== null) return claimed
+    try {
+      const parent = this.resolve(under)
+      if (parent.kind === "agent" && !this.mayMessage(me, parent)) throw unreachable(under)
+      this.link(me, parent, { by: this.address(me), auth: "session" })
+    } catch (error) {
+      if (!(error instanceof RelayError)) throw error
+      this.audit("claim_under_refused", me.id, null, { target: this.address(me), under, code: error.code })
+      return claimed
+    }
+    return { ...claimed, endpoint: this.view(this.byId(me.id)!) }
+  }
+
   /** a claim's own rules per direction, as its `scope`, `allow`, `in` and `out` expand */
   protected claimRules(claim: Claim): ScopeRules {
     const rules: ScopeRules = {}
@@ -1016,6 +1077,7 @@ export class RelayCore {
     if (created || fresh === "grant") this.place(this.byId(row.id)!, scope, now)
     else if (scope.grant !== null) this.redeem(this.byId(row.id)!, scope, now)
     if (scope.grant !== null) this.takePending(row.id)
+    if (!transient) this.wakeDone(row.id, "claim")
     return { endpoint: this.view(this.byId(row.id)!), ...(token ? { token } : {}), ...(created ? { created: true as const } : {}) }
   }
 
@@ -1108,6 +1170,7 @@ export class RelayCore {
         row.id,
       )
     this.sql.all(`DELETE FROM peek_turns WHERE endpoint = ?`, row.id)
+    this.wakeDone(row.id, "reset")
     let dropped = 0
     if (kind === "grant") {
       const spawned = one<{ issuer: string; created_at: number }>(this.sql, `SELECT issuer, created_at FROM grants WHERE token_hash = ?`, scope.grant!)
@@ -1440,7 +1503,7 @@ export class RelayCore {
     const shown = viewer ? new Set(this.visibleRows(viewer).map((row) => row.id)) : undefined
     const peeker = viewer ?? (filters.peekable === true ? this.byHandle(HUMAN_HANDLE)! : undefined)
     return this.listed()
-      .filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff || waking(row, now))
+      .filter((row) => filters.all || row.connections > 0 || row.kind === "human" || (row.last_seen ?? 0) >= cutoff || waking(row, now) || this.hibernated(row))
       .filter((row) => !filters.harness || row.harness === filters.harness)
       .filter((row) => !filters.kind || row.kind === filters.kind)
       .filter((row) => !viewer || row.id === viewer.id || this.mayMessage(viewer, row, viewer.kind === "human"))
@@ -1641,6 +1704,7 @@ export class RelayCore {
       const row = this.mustEndpoint(endpoint.id)
       if (handle !== undefined && handle !== null && handle !== "") this.renameRow(row, handle, false)
       this.sql.all(`UPDATE endpoints SET hook_seen = ?, hook_ended = NULL WHERE id = ?`, this.now(), row.id)
+      this.wakeDone(row.id, "join")
       this.audit("join", row.id, null, { handle: this.byId(row.id)!.handle })
       if (under !== undefined && under !== null && under !== "") {
         const me = this.byId(row.id)!
@@ -1939,6 +2003,7 @@ export class RelayCore {
       row.id,
     )
     this.sql.all(`UPDATE endpoints SET handle = ?, session = NULL, token_hash = NULL WHERE id = ?`, `${GONE_PREFIX}${held.id}`, held.id)
+    this.wakeDone(held.id, "retired")
     this.dropPeek(held.id)
     this.scopeMemo?.ancestors.clear()
     this.scopeMemo?.limited.clear()
@@ -1966,6 +2031,7 @@ export class RelayCore {
         throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; a spawned worker stays joined while it runs`)
       }
       this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ?, wake = NULL WHERE id = ?`, this.now(), target.id)
+      this.wakeDone(target.id, "leave")
       this.audit("leave", target.id, null, { handle: target.handle })
       return { endpoint: this.whoami(target.id), session: target.session }
     })
@@ -1976,6 +2042,198 @@ export class RelayCore {
     return this.byId(endpoint)?.session ?? null
   }
 
+  /**
+   * marks a local agent hibernated by `wake`, the provider whose wake hook resumes it, with its opaque `ref` and the seconds a wake takes
+   * (`eta_s`); `none` clears it. The agent's own session or the human (no terminal needed: a provider's daemon has none) naming the endpoint.
+   * `known` is whether a waker is configured for a provider
+   */
+  hibernate(
+    actor: ScopeActor,
+    params: { endpoint?: unknown; wake?: unknown; ref?: unknown; eta_s?: unknown },
+    options: { known?: (provider: string) => boolean } = {},
+  ): { endpoint: EndpointView } {
+    const me = this.actorRow(actor)
+    const set = this.hibernation(params, options)
+    if (actor.kind === "endpoint" && actor.auth === "lineage")
+      throw new RelayError("scope_refused", "only the session itself hibernates: run this from the session's own shell")
+    if (params.endpoint === undefined && me.kind !== "agent") throw new RelayError("invalid_params", "the human names the endpoint")
+    const target = params.endpoint === undefined ? me : this.resolve(params.endpoint)
+    if (actor.kind === "endpoint" && target.id !== me.id) throw new RelayError("scope_refused", "an agent hibernates only itself")
+    if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint hibernates")
+    return { endpoint: this.setHibernation(me, target, set) }
+  }
+
+  /** the human marks every live local agent but subagents hibernated by one provider, as before suspending the machine they run on */
+  hibernateAll(
+    actor: ScopeActor,
+    params: { wake?: unknown; ref?: unknown; eta_s?: unknown },
+    options: { known?: (provider: string) => boolean } = {},
+  ): { endpoints: EndpointView[] } {
+    const me = this.actorRow(actor)
+    if (actor.kind !== "human") throw new RelayError("scope_refused", "only the human hibernates every agent")
+    const set = this.hibernation(params, options)
+    const now = this.now()
+    const targets = this.sql
+      .all<EndpointRow>(
+        `SELECT * FROM endpoints WHERE kind = 'agent' AND substr(handle, 1, ${GONE_PREFIX.length}) != '${GONE_PREFIX}'
+         AND (session IS NULL OR substr(session, 1, 4) != 'sub:') ORDER BY handle`,
+      )
+      .filter((row) => this.localRow(row) && (set.wake === "none" ? row.hibernate !== null : presenceOf(row, now) !== "offline"))
+    return { endpoints: targets.map((row) => this.setHibernation(me, row, set)) }
+  }
+
+  private hibernation(
+    params: { wake?: unknown; ref?: unknown; eta_s?: unknown },
+    options: { known?: (provider: string) => boolean },
+  ): { wake: string; ref: string | null; eta: number | null } {
+    const wake = params?.wake
+    if (typeof wake !== "string" || (wake !== "none" && !WAKE_PROVIDER.test(wake)))
+      throw new RelayError("invalid_params", "wake is a provider name (lowercase letters, digits and hyphens, at most 32) or none")
+    let ref: string | null = null
+    if (params.ref !== undefined && params.ref !== null) {
+      if (typeof params.ref !== "string" || params.ref.length > LIMITS.wakeRefChars || /[\u0000-\u001f\u007f]/.test(params.ref))
+        throw new RelayError("invalid_params", `ref is a string of at most ${LIMITS.wakeRefChars} characters with no control characters`)
+      if (findSecret(params.ref)) throw new RelayError("secret_refused", "the wake ref looks like it carries a credential")
+      ref = params.ref
+    }
+    let eta: number | null = null
+    if (params.eta_s !== undefined && params.eta_s !== null) {
+      if (typeof params.eta_s !== "number" || !Number.isInteger(params.eta_s) || params.eta_s < 1 || params.eta_s > LIMITS.wakeEtaMaxS)
+        throw new RelayError("invalid_params", `eta_s is a whole number of seconds from 1 to ${LIMITS.wakeEtaMaxS}`)
+      eta = params.eta_s
+    }
+    if (wake !== "none" && options.known && !options.known(wake)) throw new RelayError("invalid_params", `no waker ${wake} is configured`)
+    return { wake, ref, eta }
+  }
+
+  private setHibernation(me: EndpointRow, target: EndpointRow, set: { wake: string; ref: string | null; eta: number | null }): EndpointView {
+    const address = this.address(target)
+    if (set.wake === "none") {
+      if (target.hibernate !== null) {
+        this.clearHibernation(target.id)
+        this.audit("unhibernate", target.id, null, { by: this.address(me), target: address })
+      }
+      return this.view(this.byId(target.id)!)
+    }
+    this.clearHibernation(target.id)
+    this.sql.all(
+      `UPDATE endpoints SET hibernate = ?, wake_ref = ?, wake_eta = ?, hibernated_at = ? WHERE id = ?`,
+      set.wake,
+      set.ref,
+      set.eta,
+      this.now(),
+      target.id,
+    )
+    this.audit("hibernate", target.id, null, { by: this.address(me), target: address, provider: set.wake })
+    return this.view(this.byId(target.id)!)
+  }
+
+  /**
+   * the wake hook run a delivery to a hibernated local agent is due, recorded as tried: none while it is not hibernated, has no unread
+   * message, ran within LIMITS.wakeDebounceS (after failures, a doubling backoff up to LIMITS.wakeBackoffMaxS), or the provider declined a
+   * wake for the newest unread message or for another from its sender. The newest unread message's metadata only, never its body
+   */
+  wakeDue(endpoint: string, now = this.now()): WakeJob | null {
+    const row = this.byId(endpoint)
+    if (!row?.hibernate || row.kind !== "agent" || !this.localRow(row)) return null
+    if (row.wake_tried !== null) {
+      const waitS = row.wake_fails > 0 ? Math.min(LIMITS.wakeDebounceS * 2 ** row.wake_fails, LIMITS.wakeBackoffMaxS) : LIMITS.wakeDebounceS
+      if (now - row.wake_tried < waitS * 1000) return null
+    }
+    const newest = one<{ id: string; from_ep: string; kind: MessageKind; thread: string; created_at: number }>(
+      this.sql,
+      `SELECT m.id, m.from_ep, m.kind, m.thread, m.created_at FROM deliveries d JOIN messages m ON m.id = d.message_id
+       WHERE d.endpoint = ? AND d.acked_at IS NULL AND d.expires_at > ? ORDER BY d.seq DESC LIMIT 1`,
+      endpoint,
+      now,
+    )
+    if (!newest) return null
+    if (row.wake_declined !== null && (newest.id === row.declined_message || newest.from_ep === row.declined_from)) return null
+    const unread = one<{ n: number }>(
+      this.sql,
+      `SELECT COUNT(*) AS n FROM deliveries WHERE endpoint = ? AND acked_at IS NULL AND expires_at > ?`,
+      endpoint,
+      now,
+    )!.n
+    this.sql.all(`UPDATE endpoints SET wake_tried = ? WHERE id = ?`, now, endpoint)
+    const sender = this.byId(newest.from_ep)
+    return {
+      endpoint,
+      address: this.address(row),
+      handle: row.handle,
+      provider: row.hibernate,
+      ref: row.wake_ref,
+      message: { id: newest.id, from: sender ? this.address(sender) : null, kind: newest.kind, thread: newest.thread, created_at: iso(newest.created_at)! },
+      unread,
+    }
+  }
+
+  /**
+   * how a wake hook run ended, audited without the ref: a failure counts toward the backoff and shows `wake_failed` while the message stays
+   * queued; a decline (`declined`, for the message `message`) shows `wake_declined`, counts toward nothing and holds further runs for that
+   * message and its sender until a newer message of another sender or a new hibernate; a success resets both (the hibernation clears once the
+   * session claims its endpoint again). Whether the shown note changed
+   */
+  wakeResult(
+    endpoint: string,
+    result: { ok: boolean; code?: number | null; error?: string | null; ms: number; declined?: WakeDecline; message?: string },
+  ): boolean {
+    const row = this.byId(endpoint)
+    if (!row) return false
+    const error = result.error ? redactSecrets(stripControl(result.error).replace(/\s+/g, " ").trim()).slice(0, 200) : null
+    const declined = result.ok ? null : wakeDeclineOf(result.declined)
+    this.audit("wake", endpoint, null, {
+      target: this.address(row),
+      provider: row.hibernate,
+      ok: result.ok,
+      ...(result.code !== undefined && result.code !== null ? { code: result.code } : {}),
+      ms: Math.max(0, Math.round(result.ms)),
+      ...(declined ? { declined } : error ? { error } : {}),
+    })
+    if (!row.hibernate) return false
+    if (declined) {
+      const message = result.message ? one<{ from_ep: string }>(this.sql, `SELECT from_ep FROM messages WHERE id = ?`, result.message) : undefined
+      this.sql.all(
+        `UPDATE endpoints SET wake_declined = ?, declined_message = ?, declined_from = ?, wake_note = NULL, wake_tried = NULL WHERE id = ?`,
+        declined,
+        result.message ?? null,
+        message?.from_ep ?? null,
+        endpoint,
+      )
+      return declined !== row.wake_declined || row.wake_note !== null
+    }
+    const note = result.ok
+      ? null
+      : `wake_failed: ${(error ?? (result.code !== undefined && result.code !== null ? `exit ${result.code}` : "failed")).slice(0, 120)}`
+    this.sql.all(
+      `UPDATE endpoints SET wake_fails = ${result.ok ? "0" : "wake_fails + 1"}, wake_note = ?, wake_declined = NULL, declined_message = NULL, declined_from = NULL WHERE id = ?`,
+      note,
+      endpoint,
+    )
+    return note !== row.wake_note || row.wake_declined !== null
+  }
+
+  /** whether the row shows hibernated: a subclass also counts what another machine mirrored */
+  protected hibernated(row: EndpointRow): boolean {
+    return row.hibernate !== null
+  }
+
+  /** the hibernated session is back, or gone: its hibernation clears */
+  private wakeDone(endpoint: string, how: string): void {
+    const row = this.byId(endpoint)
+    if (!row?.hibernate) return
+    this.clearHibernation(endpoint)
+    this.audit("wake_done", endpoint, null, { target: this.address(row), how })
+  }
+
+  private clearHibernation(endpoint: string): void {
+    this.sql.all(
+      `UPDATE endpoints SET hibernate = NULL, wake_ref = NULL, wake_eta = NULL, hibernated_at = NULL, wake_tried = NULL, wake_fails = 0, wake_note = NULL,
+       wake_declined = NULL, declined_message = NULL, declined_from = NULL WHERE id = ?`,
+      endpoint,
+    )
+  }
+
   // messages
 
   /**
@@ -2045,8 +2303,9 @@ export class RelayCore {
         (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || (r.session === null && r.token_hash === null && r.hook_ended !== null)) &&
         !this.unjoinedSpawn(sender, r.handle, now),
     )
-    if (params.live === true && dark.length)
-      throw new RelayError("not_live", `no live session holds ${dark.map((r) => this.address(r)).join(", ")}: nothing was queued`)
+    const asleep = params.live === true ? recipients.filter((r) => r.kind === "agent" && r.hibernate !== null) : []
+    if (params.live === true && (dark.length || asleep.length))
+      throw new RelayError("not_live", `no live session holds ${[...dark, ...asleep].map((r) => this.address(r)).join(", ")}: nothing was queued`)
     const warnings = dark.map((r) => `queued: no live session holds ${this.address(r)}`)
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }))
     const reached = recipients.length + pending.length
@@ -2271,8 +2530,9 @@ export class RelayCore {
         this.sql.all(`INSERT INTO pair_events (from_ep, to_ep, at) VALUES (?, ?, ?)`, from, recipient.id, now)
         if (treeSends && recipient.kind !== "human") this.sql.all(`INSERT INTO tree_events (tree, at) VALUES (?, ?)`, tree, now)
         const view = this.view(recipient)
-        const queued = view.presence === "offline"
-        const offline = queued && now - Math.max(recipient.last_seen ?? 0, recipient.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS
+        const hibernated = view.presence === "hibernated"
+        const queued = view.presence === "offline" || hibernated
+        const offline = view.presence === "offline" && now - Math.max(recipient.last_seen ?? 0, recipient.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS
         const state = this.reach(sender, recipient, offline, now)
         deliveries.push({
           endpoint: recipient.id,
@@ -2282,8 +2542,10 @@ export class RelayCore {
           ...(queued ? { queued } : {}),
           last_seen: view.last_seen,
           ...(state ? { state } : {}),
-          ...(view.wake ? { wake: view.wake } : {}),
+          ...(hibernated && recipient.wake_declined ? { wake: "declined" as const } : view.wake ? { wake: view.wake } : {}),
           ...(view.presence === "idle" ? { idle: true as const } : {}),
+          ...(hibernated ? { hibernated: true as const } : {}),
+          ...(hibernated && recipient.wake_eta ? { wake_eta_s: recipient.wake_eta } : {}),
         })
       }
       for (const { key, address } of pending) {
@@ -3357,6 +3619,7 @@ export class RelayCore {
           endpoint,
         )
     } else if (params.kind === "session_start") {
+      this.wakeDone(endpoint, "session_start")
       const fresh = own && summary !== "compact" && summary !== "resume"
       this.sql.all(
         `UPDATE endpoints SET hook_seen = COALESCE(?, hook_seen), hook_ended = NULL, stop_blocks = CASE WHEN ? THEN 0 ELSE stop_blocks END, pushes = CASE WHEN ? THEN 0 ELSE pushes END,
@@ -5378,7 +5641,9 @@ export class RelayCore {
       presence,
       status: row.status_state ? { state: row.status_state, note: row.status_note ?? "" } : null,
       last_seen: iso(row.last_seen),
-      ...(row.kind === "agent" ? { ...this.placeView(row, shown), wake: wakeOf(row) } : {}),
+      ...(row.kind === "agent" ? { ...this.placeView(row, shown), wake: row.hibernate ? (`hook:${row.hibernate}` as const) : wakeOf(row) } : {}),
+      ...(row.hibernate && row.wake_note ? { wake_failed: row.wake_note.replace(/^wake_failed: /, "") } : {}),
+      ...(row.hibernate && row.wake_declined ? { wake_declined: row.wake_declined } : {}),
     }
   }
 
@@ -5677,8 +5942,12 @@ function waking(row: EndpointRow, now: number): boolean {
   return wakeOf(row) !== null && (row.wakers > 0 || (row.waker_left ?? 0) >= now - LIMITS.restartGraceS * 1000)
 }
 
-/** the presence an endpoint shows: one its waker can wake is at least idle, though its session's own presence decayed */
+/**
+ * the presence an endpoint shows: a provider's hibernated session is `hibernated` whatever its connections say; one its waker can wake is at
+ * least idle, though its session's own presence decayed
+ */
 function shownPresence(row: EndpointRow, now: number): Presence {
+  if (row.hibernate) return "hibernated"
   const presence = presenceOf(row, now)
   return presence === "offline" && waking(row, now) ? "idle" : presence
 }

package/src/index.ts

@@ -11,9 +11,11 @@ export {
   SYSTEM_HANDLE,
   TITLE_CHARS,
   unreachable,
+  WAKE_PROVIDER,
   type CoreOptions,
   type EndpointRow,
   type MessageRow,
+  type WakeJob,
 } from "./core"
 export * from "./protocol"
 export {

package/src/protocol.ts

@@ -75,6 +75,14 @@ export const LIMITS = {
   policyLoadsKept: 8,
   /** the prompts between two refreshes of a title a hook inferred */
   titleRefreshTurns: 5,
+  /** the least time between two wake hook runs for one hibernated endpoint */
+  wakeDebounceS: 60,
+  /** the longest backoff after failed wake hook runs */
+  wakeBackoffMaxS: 900,
+  /** the longest opaque wake reference a provider stores with a hibernation */
+  wakeRefChars: 512,
+  /** the longest wake time a provider may announce with a hibernation */
+  wakeEtaMaxS: 3600,
 } as const
 
 export type ErrorCode =
@@ -109,10 +117,25 @@ export class RelayError extends Error {
 export type EndpointKind = "agent" | "human" | "system"
 export type MessageKind = "message" | "request" | "reply" | "status"
 export type DataClass = "public" | "private"
-export type Presence = "online" | "idle" | "offline"
+/** `hibernated`: a provider suspended the session; a message runs its wake hook and the session drains its queue once it is back */
+export type Presence = "online" | "idle" | "offline" | "hibernated"
+export const PRESENCES: readonly Presence[] = ["online", "idle", "offline", "hibernated"]
 export type StatusState = "working" | "waiting" | "blocked" | "done"
-/** how an idle agent is woken by a message: a channel push, the pi extension, the OpenCode plugin's waiter, codex app-server, the session inbox, a headless resume or muse serve; `none` reads at its next turn */
-export type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "agy-resume" | "grok-resume" | "muse-serve" | "none"
+/**
+ * how an idle agent is woken by a message: a channel push, the pi extension, the OpenCode plugin's waiter, codex app-server, the session inbox,
+ * a headless resume or muse serve; `none` reads at its next turn; `hook:<provider>` (shown only, never set this way) a hibernated agent's provider wake hook
+ */
+export type Wake =
+  | "channels"
+  | "pi"
+  | "opencode-plugin"
+  | "codex-app-server"
+  | "claude-inbox"
+  | "agy-resume"
+  | "grok-resume"
+  | "muse-serve"
+  | "none"
+  | `hook:${string}`
 export const WAKES: readonly Wake[] = [
   "channels",
   "pi",
@@ -124,6 +147,14 @@ export const WAKES: readonly Wake[] = [
   "muse-serve",
   "none",
 ]
+/** why a provider declined to wake a hibernated agent, a short token it picks (e.g. `policy`, `budget`): not a failure, and not retried for the same message */
+export type WakeDecline = string
+export const WAKE_DECLINE = /^[a-z][a-z0-9_-]{0,31}$/
+
+/** `value` when it is a decline reason, else null */
+export function wakeDeclineOf(value: unknown): WakeDecline | null {
+  return typeof value === "string" && WAKE_DECLINE.test(value) ? value : null
+}
 
 export type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end"
 export const ACTIVITY_KINDS: readonly ActivityKind[] = ["session_start", "tool", "stop", "note", "session_end"]
@@ -199,6 +230,8 @@ export interface Claim {
   in?: string[]
   out?: string[]
   groups?: string[]
+  /** an agent address a root claim links under, as a join under does; a refused link keeps the claim, audited */
+  under?: string
 }
 
 export type ScopeDirection = "in" | "out"
@@ -290,6 +323,10 @@ export interface EndpointView {
   peekable?: PeekLevel
   /** an agent's: how an idle agent is woken by a message; null or `none`: it reads at its next turn */
   wake?: Wake | null
+  /** a hibernated agent's last wake hook failure: the reason */
+  wake_failed?: string
+  /** a hibernated agent's provider declined the last wake */
+  wake_declined?: WakeDecline
 }
 
 export type PeekLevel = "local"
@@ -467,7 +504,8 @@ export interface SendResult {
   /**
    * `queued`: the recipient is not connected now; `offline`: it has been gone past a short grace, so a client polling between waits is not
    * offline; `state`: an agent recipient's {@link Reach} on this machine (an older broker leaves it out); `wake`: how it is woken, only when
-   * it can be; `idle`: its presence is idle
+   * it can be, `declined` when its provider declined the last wake; `idle`: its presence is idle; `hibernated`: it is hibernated and
+   * queued, its provider's wake hook resumes it; `wake_eta_s`: how long its provider said a wake takes
    */
   deliveries: {
     endpoint: string
@@ -477,8 +515,10 @@ export interface SendResult {
     queued?: boolean
     last_seen: string | null
     state?: Reach
-    wake?: Wake
+    wake?: Wake | "declined"
     idle?: true
+    hibernated?: true
+    wake_eta_s?: number
   }[]
   /** one line per agent recipient no live session holds: `queued: no live session holds <address>` */
   warnings?: string[]

package/src/render.ts

@@ -135,8 +135,9 @@ export function reachLines(deliveries: Delivery[], late = false): string[] {
     .map((d) => (d.state ? `${d.address}: ${reachText({ ...d, state: d.state })}` : deliveryText(d)))
 }
 
-/** an endpoint's presence as a line shows it: an idle agent no message wakes reads at its next turn */
+/** an endpoint's presence as a line shows it: an idle agent no message wakes reads at its next turn; a hibernated one is wakeable */
 export function presenceText(e: Pick<EndpointView, "kind" | "presence" | "wake">): string {
+  if (e.presence === "hibernated") return "hibernated (wakeable)"
   return e.kind === "agent" && e.presence === "idle" && (!e.wake || e.wake === "none") ? "idle (next turn)" : e.presence
 }