@scp-dev/core 0.1.6 → 0.3.0

package/dist/index.d.ts

@@ -404,7 +404,7 @@ type DataClass = "public" | "private";
 type Presence = "online" | "idle" | "offline";
 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 or codex app-server; `none` reads at its next turn */
-type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "none";
+type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "none";
 declare const WAKES: readonly Wake[];
 type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end";
 declare const ACTIVITY_KINDS: readonly ActivityKind[];
@@ -658,6 +658,10 @@ interface Envelope {
     expires_at: string;
     /** a request whose sender holds the recipient's stop until it replies */
     require_reply?: true;
+    /** a broker-issued request to link under its sender */
+    link?: {
+        parent: string;
+    };
     /** set by inbox on a message a background hook already showed (and marked read), whose text may reach the agent only after this call */
     shown_at?: string;
     /**
@@ -769,6 +773,12 @@ interface SendResult {
     held?: JudgeHeld;
     redacted?: JudgeRedacted;
 }
+interface AdoptResult {
+    endpoint: EndpointView;
+    parent: string;
+    requested?: string;
+    held?: JudgeHeld;
+}
 /**
  * a message the caller sent and, per recipient, when it read the message (acked), or when a background hook delivered it (acked by that
  * showing; the agent gets it with its next request), and when a hook or channel showed it: ISO times, or null
@@ -792,7 +802,7 @@ interface AuditRow {
     detail: Record<string, unknown>;
 }
 /** fields only the server sets: a client that sends them gets invalid_params */
-declare const SERVER_FIELDS: readonly ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"];
+declare const SERVER_FIELDS: readonly ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation", "link"];
 
 /**
  * `*`, `ep:<handle>` (that one agent), `handle:<glob>`, `harness:<name>`, `kind:<agent|human>` or `label:<key>=<value>`, plus the scope selectors: `tree:self|root|parent|siblings|children`,
@@ -998,11 +1008,12 @@ declare function relationText(peer: PolicySubject, me: PolicySubject): string;
 /**
  * The scope check for a message from `a` to `b`: `out(a)` admits `b` and `in(b)` admits `a`. Either side the account's human (with `humanAlways`)
  * or the system endpoint passes, except an `unverified` human sender (one without a terminal), which is checked like any unplaced sender; an
- * ancestor of `b` (unless `strict`) and a solicited reply pass both.
+ * ancestor of `b` (unless `strict`), a solicited reply and a parent and child `linked` across machines pass both.
  */
 declare function scopeDecision(world: ScopeWorld, a: ScopeNode, b: ScopeNode, options: {
     humanAlways: boolean;
     solicited?: boolean;
+    linked?: boolean;
     unverified?: boolean;
     strict?: boolean;
 }): ScopeDecision;
@@ -1085,6 +1096,8 @@ interface EndpointRow {
     /** the root endpoint's id; null for a root */
     tree: string | null;
     parent_ep: string | null;
+    /** a parent on another machine of the account, `<machine>/<handle>`: the row stays a root of its own tree */
+    parent_addr: string | null;
     depth: number | null;
     /** JSON {@link ScopeRules} */
     rules: string | null;
@@ -1130,7 +1143,11 @@ interface MessageRow {
     expires_at: number;
     sender_tty: number | null;
     require_reply: number | null;
+    link_parent: string | null;
 }
+type AdoptSend = (from: string, params: SendParams, origin: {
+    link: "session" | "self";
+}) => Promise<SendResult>;
 interface CoreOptions {
     /** the local user's address part; `me` until a login names one */
     user?: string;
@@ -1359,6 +1376,8 @@ declare class RelayCore {
     waker(endpoint: string, live: boolean, options?: {
         grace?: boolean;
     }): void;
+    /** clears a wake no waker holds once a hook waker's grace ran out too: nothing is left to wake the endpoint */
+    private lapseWake;
     /**
      * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
      * It fills only a title nobody set, as an inferred one, and waits for the subagent's claim when it has no endpoint yet
@@ -1379,16 +1398,23 @@ declare class RelayCore {
      * when given, renames it in place ({@link rename}'s rules). Nothing is kept when the rename is refused
      */
     joinSession(claim: Claim, handle?: unknown, under?: unknown): EndpointView;
-    /**
-     * links a local root agent under `parent`, as a spawned worker sits: in the parent's tree one level down, under the policy's child scope.
-     * Only the human at a terminal links another session, or an agent from its own shell with a terminal attached, under itself by default.
-     * A session links itself with {@link joinSession}'s `under`
-     */
+    /** the human links a local root directly; an agent asks it to consent through the normal send path */
     adopt(actor: ScopeActor, params: {
         endpoint: unknown;
         parent?: unknown;
     }, options?: {
         tty?: boolean;
+    }): AdoptResult;
+    adopt(actor: ScopeActor, params: {
+        endpoint: unknown;
+        parent?: unknown;
+    }, options: {
+        tty?: boolean;
+        send: AdoptSend;
+    }): AdoptResult | Promise<AdoptResult>;
+    /** accepts a broker-issued request delivered to the caller's own session */
+    linkAccept(actor: ScopeActor, params: {
+        id: unknown;
     }): {
         endpoint: EndpointView;
         parent: string;
@@ -1403,8 +1429,22 @@ declare class RelayCore {
         endpoint: EndpointView;
         parent: string;
     };
-    /** `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants */
+    /**
+     * `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants; a parent on another
+     * machine goes to {@link linkAcross}
+     */
     private link;
+    /** a link of `row`, which already sits under a parent, to another one */
+    private alreadyLinked;
+    /**
+     * the key `<machine>/<handle>` that links `row`, a local agent, under `parent`, an agent on another machine, once the parent is checked; no
+     * inherited or child-default caps come with it. A relay of one machine has no such parent
+     */
+    protected linkAcross(_row: EndpointRow, _parent: EndpointRow): string;
+    /** whether `a` and `b` are a parent and its child on different machines */
+    protected linkedAcross(_a: EndpointRow, _b: EndpointRow): boolean;
+    /** the address of `row`'s parent on another machine, null when it has none; with `shown`, null for a parent outside it */
+    protected linkedParent(_row: EndpointRow, _shown?: Set<string>): string | null;
     /**
      * renames an agent in place: its id, mail, threads, status, title and relations stay. An agent renames only itself, and only a root unless
      * the policy's `defaults.rename` is `self`; the human at a terminal renames any local agent. The new handle is valid and held by no other endpoint
@@ -1419,6 +1459,8 @@ declare class RelayCore {
     };
     /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
     private renameRow;
+    /** a local agent's handle moved from `from` to `to`: a subclass updates what names it on another machine's rows */
+    protected renamedHandle(_from: string, _to: string): void;
     /**
      * a session leaves: it lets go of its session and token and shows offline, its mail kept; a later join takes it back. An agent leaves only
      * itself, the human at a terminal any local root or linked agent. A spawned worker stays joined while it runs
@@ -1438,6 +1480,7 @@ declare class RelayCore {
     send(from: string, params: SendParams, origin?: {
         tty?: boolean;
         unverified?: boolean;
+        link?: "session" | "self";
     }): SendResult;
     /** a local agent recipient's {@link Reach} for a send from `sender`; none for a human, the relay or another machine's row */
     private reach;
@@ -1700,7 +1743,7 @@ declare class RelayCore {
     }): AuditRow[];
     /** drops what expired: deliveries, message bodies past their grace, old guard state and old audit rows */
     sweep(): void;
-    /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+    /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would, and lapses wakes whose hook waker never came back */
     endExited(now?: number): void;
     /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
     private settleOffline;
@@ -2513,4 +2556,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 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, 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 };

package/dist/index.js

@@ -179,7 +179,7 @@ var RelayError = class extends Error {
   retryAfterS;
   detail;
 };
-var WAKES = ["channels", "pi", "opencode-plugin", "codex-app-server", "none"];
+var WAKES = ["channels", "pi", "opencode-plugin", "codex-app-server", "claude-inbox", "none"];
 var ACTIVITY_KINDS = ["session_start", "tool", "stop", "note", "session_end"];
 var MESSAGE_KINDS = ["message", "request", "reply", "status"];
 var STATUS_STATES = ["working", "waiting", "blocked", "done"];
@@ -201,7 +201,7 @@ function keptHarness(held, claimed) {
   return generic(claimed) && !generic(held) ? held : claimed;
 }
 var SCOPE_PRESETS = ["open", "tree", "parent", "none"];
-var SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"];
+var SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation", "link"];
 
 // src/scrub.ts
 var KEY_KIND = "[A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----";
@@ -558,6 +558,7 @@ function scopeDecision(world, a, b, options) {
   if (options.humanAlways && (b.human || a.human && !options.unverified)) return { allowed: true, reasons: ["the human is always reachable"] };
   if (!options.strict && isAncestor(a, b)) return { allowed: true, reasons: [`${a.address} is an ancestor of ${b.address}: scopes never stop it`] };
   if (options.solicited) return { allowed: true, reasons: [`a reply to ${b.address}'s message in its thread`] };
+  if (options.linked) return { allowed: true, reasons: [`${a.address} and ${b.address} are parent and child across machines`] };
   const memo = /* @__PURE__ */ new Map();
   const out = admits(world, a, "out", b, memo);
   if (!out.ok) return { allowed: false, dir: "out", reasons: [out.why] };
@@ -1326,6 +1327,7 @@ var RelayCore = class {
     const messageColumns = this.sql.all(`PRAGMA table_info(messages)`).map((c) => c.name);
     if (!messageColumns.includes("sender_tty")) this.sql.all(`ALTER TABLE messages ADD COLUMN sender_tty INTEGER`);
     if (!messageColumns.includes("require_reply")) this.sql.all(`ALTER TABLE messages ADD COLUMN require_reply INTEGER`);
+    if (!messageColumns.includes("link_parent")) this.sql.all(`ALTER TABLE messages ADD COLUMN link_parent TEXT`);
     const endpointColumns = this.sql.all(`PRAGMA table_info(endpoints)`).map((c) => c.name);
     if (!endpointColumns.includes("session")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN session TEXT`);
     if (!endpointColumns.includes("hook_seen")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN hook_seen INTEGER`);
@@ -1338,6 +1340,7 @@ var RelayCore = class {
     for (const [column, type] of [
       ["tree", "TEXT"],
       ["parent_ep", "TEXT"],
+      ["parent_addr", "TEXT"],
       ["depth", "INTEGER"],
       ["rules", "TEXT"],
       ["caps", "TEXT"],
@@ -1942,7 +1945,7 @@ var RelayCore = class {
     }
     caps.caps.push(...this.capsOf(row).caps);
     this.sql.all(
-      `UPDATE endpoints SET tree = ?, parent_ep = ?, depth = ?, rules = ?, caps = ? WHERE id = ?`,
+      `UPDATE endpoints SET tree = ?, parent_ep = ?, parent_addr = NULL, depth = ?, rules = ?, caps = ? WHERE id = ?`,
       parent ? parent.tree ?? parent.id : null,
       parent?.id ?? null,
       depth,
@@ -2195,13 +2198,20 @@ var RelayCore = class {
    */
   waker(endpoint, live, options = {}) {
     if (live) this.sql.all(`UPDATE endpoints SET wakers = wakers + 1 WHERE id = ?`, endpoint);
-    else
+    else {
+      const now = this.now();
       this.sql.all(
         `UPDATE endpoints SET wakers = MAX(wakers - 1, 0), waker_left = CASE WHEN ? THEN ? ELSE waker_left END WHERE id = ?`,
         options.grace ? 1 : 0,
-        this.now(),
+        now,
         endpoint
       );
+      if (!options.grace) this.lapseWake(endpoint, now);
+    }
+  }
+  /** clears a wake no waker holds once a hook waker's grace ran out too: nothing is left to wake the endpoint */
+  lapseWake(endpoint, now) {
+    this.sql.all(`UPDATE endpoints SET wake = NULL WHERE id = ? AND wakers = 0 AND COALESCE(waker_left, 0) < ?`, endpoint, now - LIMITS.restartGraceS * 1e3);
   }
   /**
    * a title for the caller's in-process subagent `id` from the description its parent gave it; the subagent's endpoint id when it changed one.
@@ -2269,30 +2279,52 @@ var RelayCore = class {
       return this.whoami(row.id);
     });
   }
-  /**
-   * links a local root agent under `parent`, as a spawned worker sits: in the parent's tree one level down, under the policy's child scope.
-   * Only the human at a terminal links another session, or an agent from its own shell with a terminal attached, under itself by default.
-   * A session links itself with {@link joinSession}'s `under`
-   */
   adopt(actor, params, options = {}) {
-    return this.scopeTx(() => {
+    const prepared = this.scopeTx(() => {
       const me = this.actorRow(actor);
       if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
-      else if (options.tty !== true)
-        throw this.scopeRefused(
-          actor,
-          me,
-          { target: String(params.endpoint), reason: "adopt" },
-          `only the human at a terminal links another session under a parent; the session links itself with ${CLI_NAME} join --under`
-        );
+      else if (actor.auth === "lineage")
+        throw this.scopeRefused(actor, me, { target: String(params.endpoint), reason: "adopt" }, "only the session itself may request a link");
       const target = this.resolve(params.endpoint);
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be linked");
       const parentAddress = params.parent ?? (actor.kind === "human" ? void 0 : this.address(me));
       if (parentAddress === void 0 || parentAddress === null || parentAddress === "")
         throw new RelayError("invalid_params", "the human names the parent to link under");
       const parent = this.resolve(parentAddress);
-      this.link(target, parent, this.actorDetail(actor, me));
-      return { endpoint: this.whoami(target.id), parent: this.address(parent) };
+      if (actor.kind !== "human" && parent.id !== me.id)
+        throw this.scopeRefused(actor, me, { target: this.address(target), reason: "adopt" }, "an agent may request a link only under itself");
+      const result2 = { endpoint: this.whoami(target.id), parent: this.address(parent) };
+      if (actor.kind === "human" || options.tty === true) {
+        this.link(target, parent, this.actorDetail(actor, me));
+        return { result: { ...result2, endpoint: this.whoami(target.id) } };
+      }
+      if (target.parent_ep !== null || target.parent_addr !== null) throw this.alreadyLinked(target);
+      const auth2 = actor.auth === "self" ? "self" : "session";
+      return { result: result2, sender: { from: me.id, auth: auth2 } };
+    });
+    if (!prepared.sender) return prepared.result;
+    const { result } = prepared;
+    const { from, auth } = prepared.sender;
+    const send = {
+      to: result.endpoint.address,
+      kind: "request",
+      ttl_s: 86400,
+      body: `${result.parent} asks you to link under it as its worker. To accept, run ${CLI_NAME} link accept <id> with this message's id, or ${CLI_NAME} join --under ${result.parent} (relay_link_accept {id} or relay_join {under: "${result.parent}"}).`
+    };
+    const requested = (sent) => ({ ...result, ...sent.held ? { held: sent.held } : { requested: sent.id } });
+    return options.send ? options.send(from, send, { link: auth }).then(requested) : requested(this.send(from, send, { link: auth }));
+  }
+  /** accepts a broker-issued request delivered to the caller's own session */
+  linkAccept(actor, params) {
+    return this.scopeTx(() => {
+      if (actor.kind !== "endpoint" || actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself accepts a link request");
+      const me = this.actorRow(actor);
+      const request = this.delivered(me.id, params.id);
+      if (!request?.link || request.kind !== "request") throw new RelayError("not_found", "no link request delivered to this endpoint");
+      const parent = this.mustEndpoint(request.from.endpoint);
+      if (parent.kind !== "agent") throw new RelayError("invalid_params", "the requesting parent is no longer an agent");
+      this.link(me, parent, { ...this.actorDetail(actor, me), request: request.id });
+      return { endpoint: this.whoami(me.id), parent: this.address(parent) };
     });
   }
   /**
@@ -2307,7 +2339,8 @@ var RelayCore = class {
       const target = params.endpoint === void 0 ? me : this.resolve(params.endpoint);
       if (actor.kind !== "human" && target.id !== me.id) throw new RelayError("scope_refused", "an agent unlinks only itself");
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be unlinked");
-      if (target.parent_ep === null) throw new RelayError("invalid_params", `${this.address(target)} is a root: it has no parent`);
+      if (target.parent_ep === null && target.parent_addr === null)
+        throw new RelayError("invalid_params", `${this.address(target)} is a root: it has no parent`);
       if (actor.kind !== "human" && this.policy?.defaults?.unlink !== "self")
         throw this.scopeRefused(
           actor,
@@ -2315,6 +2348,14 @@ var RelayCore = class {
           { target: this.address(target), reason: "unlink" },
           "unlinking widens a worker's scope: only the human at a terminal unlinks it (policy defaults.unlink: self lets it)"
         );
+      if (target.parent_ep === null) {
+        const from2 = this.linkedParent(target) ?? target.parent_addr;
+        this.sql.all(`UPDATE endpoints SET parent_addr = NULL, linked = NULL WHERE id = ?`, target.id);
+        this.scopeMemo?.ancestors.clear();
+        this.scopeMemo?.limited.clear();
+        this.audit("unlink", target.id, null, { ...this.actorDetail(actor, me), target: this.address(target), parent: from2 });
+        return { endpoint: this.whoami(target.id), parent: from2 };
+      }
       const parent = this.byId(target.parent_ep);
       const from = parent ? this.address(parent) : target.parent_ep;
       const shift = target.depth ?? 0;
@@ -2338,16 +2379,26 @@ var RelayCore = class {
       return { endpoint: this.whoami(target.id), parent: from };
     });
   }
-  /** `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants */
+  /**
+   * `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants; a parent on another
+   * machine goes to {@link linkAcross}
+   */
   link(row, parent, by) {
-    if (parent.kind !== "agent" || !this.localRow(parent)) throw new RelayError("invalid_params", "the parent is a local agent endpoint");
+    if (!this.localRow(parent)) {
+      const key = this.linkAcross(row, parent);
+      if (row.parent_addr === key) return;
+      if (row.parent_ep !== null || row.parent_addr !== null) throw this.alreadyLinked(row);
+      this.sql.all(`UPDATE endpoints SET parent_addr = ?, linked = ? WHERE id = ?`, key, this.now(), row.id);
+      this.scopeMemo?.ancestors.clear();
+      this.scopeMemo?.limited.clear();
+      this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) });
+      return;
+    }
+    if (parent.kind !== "agent") throw new RelayError("invalid_params", "the parent is an agent endpoint");
     if (row.parent_ep === parent.id) return;
     if (parent.id === row.id || this.ancestorsOf(parent).includes(row.id))
       throw new RelayError("scope_refused", `${this.address(parent)} sits under ${this.address(row)}: a session cannot go under its own descendant`);
-    if (row.parent_ep !== null) {
-      const now = this.byId(row.parent_ep);
-      throw new RelayError("scope_refused", `${this.address(row)} already sits under ${now ? this.address(now) : "another agent"}; unlink it first`);
-    }
+    if (row.parent_ep !== null || row.parent_addr !== null) throw this.alreadyLinked(row);
     const depth = (parent.depth ?? 0) + 1;
     const deepest = one(this.sql, `SELECT MAX(depth) AS d FROM endpoints WHERE tree = ?`, row.id)?.d ?? 0;
     if (deepest + depth > LIMITS.depthMax)
@@ -2369,7 +2420,28 @@ var RelayCore = class {
     );
     this.scopeMemo?.ancestors.clear();
     this.scopeMemo?.limited.clear();
-    this.audit("adopt", row.id, null, { ...by, target: this.address(row), parent: this.address(parent) });
+    this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) });
+  }
+  /** a link of `row`, which already sits under a parent, to another one */
+  alreadyLinked(row) {
+    const local = row.parent_ep ? this.byId(row.parent_ep) : void 0;
+    const now = local ? this.address(local) : row.parent_addr !== null ? this.linkedParent(row) ?? row.parent_addr : "another agent";
+    return new RelayError("scope_refused", `${this.address(row)} already sits under ${now}; unlink it first`);
+  }
+  /**
+   * the key `<machine>/<handle>` that links `row`, a local agent, under `parent`, an agent on another machine, once the parent is checked; no
+   * inherited or child-default caps come with it. A relay of one machine has no such parent
+   */
+  linkAcross(_row, _parent) {
+    throw new RelayError("invalid_params", "the parent is a local agent endpoint");
+  }
+  /** whether `a` and `b` are a parent and its child on different machines */
+  linkedAcross(_a, _b) {
+    return false;
+  }
+  /** the address of `row`'s parent on another machine, null when it has none; with `shown`, null for a parent outside it */
+  linkedParent(_row, _shown) {
+    return null;
   }
   /**
    * renames an agent in place: its id, mail, threads, status, title and relations stay. An agent renames only itself, and only a root unless
@@ -2418,8 +2490,12 @@ var RelayCore = class {
       ])
         this.sql.all(`UPDATE ${table} SET ${column} = REPLACE(${column}, ?, ?) WHERE instr(${column}, ?) > 0`, a, b, a);
     }
+    this.renamedHandle(from, handle);
     this.audit("rename", row.id, null, { from, to: handle });
   }
+  /** a local agent's handle moved from `from` to `to`: a subclass updates what names it on another machine's rows */
+  renamedHandle(_from, _to) {
+  }
   /**
    * a session leaves: it lets go of its session and token and shows offline, its mail kept; a later join takes it back. An agent leaves only
    * itself, the human at a terminal any local root or linked agent. A spawned worker stays joined while it runs
@@ -2451,6 +2527,7 @@ var RelayCore = class {
    * sends without a terminal, so the scopes check it like any unplaced sender
    */
   send(from, params, origin = {}) {
+    if ("link" in params) throw new RelayError("invalid_params", "link is set by the relay, not the sender");
     const sender = this.mustEndpoint(from);
     const senderTty = sender.kind === "human" ? origin.tty === true ? 1 : 0 : null;
     const unverified = sender.kind === "human" && origin.unverified === true;
@@ -2512,6 +2589,9 @@ var RelayCore = class {
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }));
     const reached = recipients.length + pending.length;
     if (reached > LIMITS.fanOutTotal) throw new RelayError("too_large", `the send reaches ${reached} endpoints, more than ${LIMITS.fanOutTotal}`);
+    if (origin.link && (sender.kind !== "agent" || kind !== "request" || recipients.length !== 1 || pending.length || recipients[0].kind !== "agent" || !this.localRow(recipients[0])))
+      throw new RelayError("invalid_params", "a link request is from an agent to one local root agent");
+    if (origin.link && (recipients[0].parent_ep !== null || recipients[0].parent_addr !== null)) throw this.alreadyLinked(recipients[0]);
     const requestedThread = this.threadRef(from, cleanText(params.thread, "thread", 64));
     const payloadHash = this.hash(
       JSON.stringify([
@@ -2524,7 +2604,8 @@ var RelayCore = class {
         attachments.map((a) => a.path).sort(),
         mime,
         ttl,
-        params.require_reply === true
+        params.require_reply === true,
+        ...origin.link ? [origin.link] : []
       ])
     );
     if (clientId) {
@@ -2682,8 +2763,8 @@ var RelayCore = class {
       const expires = now + ttl * 1e3;
       const to = targets.length === 1 ? String(targets[0]) : targets.join(",");
       this.sql.all(
-        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply, link_parent)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         id,
         thread,
         parent?.id ?? null,
@@ -2698,7 +2779,8 @@ var RelayCore = class {
         now,
         expires,
         senderTty,
-        params.require_reply === true ? 1 : null
+        params.require_reply === true ? 1 : null,
+        origin.link ? this.address(sender) : null
       );
       if (parent) this.sql.all(`UPDATE deliveries SET acked_at = ? WHERE message_id = ? AND endpoint = ? AND acked_at IS NULL`, now, parent.id, from);
       const deliveries = [];
@@ -2740,6 +2822,13 @@ var RelayCore = class {
         );
       }
       this.audit("send", from, id, { to: deliveries.map((d) => d.address), kind, bytes, hop, thread, data_class: dataClass });
+      if (origin.link)
+        this.audit("adopt_request", from, id, {
+          by: this.address(sender),
+          auth: origin.link,
+          target: this.address(recipients[0]),
+          parent: this.address(sender)
+        });
       for (const recipient of recipients) this.detectPingPong(sender, recipient);
       return sent;
     });
@@ -3593,15 +3682,24 @@ var RelayCore = class {
       if (!root || root.handle.startsWith(GONE_PREFIX) || !seen) this.dropGroup(group.name);
     }
   }
-  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would, and lapses wakes whose hook waker never came back */
   endExited(now = this.now()) {
     for (const row of this.sql.all(
       `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND hook_seen IS NOT NULL AND process IS NOT NULL`
     )) {
       const pid = Number(/^pid:(\d+)/.exec(row.process)?.[1]);
       if (!pid || !this.localRow(row) || this.alive(pid)) continue;
-      this.sql.all(`UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL WHERE id = ? AND connections = 0`, now, row.id);
+      this.sql.all(
+        `UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL, wake = CASE WHEN wakers = 0 THEN NULL ELSE wake END WHERE id = ? AND connections = 0`,
+        now,
+        row.id
+      );
     }
+    for (const row of this.sql.all(
+      `SELECT * FROM endpoints WHERE wake IS NOT NULL AND wakers = 0 AND waker_left < ?`,
+      now - LIMITS.restartGraceS * 1e3
+    ))
+      if (this.localRow(row)) this.lapseWake(row.id, now);
   }
   /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
   settleOffline(now) {
@@ -3651,7 +3749,8 @@ var RelayCore = class {
     if (params.kind === "session_end") {
       if (own)
         this.sql.all(
-          `UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END WHERE id = ?`,
+          `UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END,
+           wake = CASE WHEN wakers = 0 THEN NULL ELSE wake END WHERE id = ?`,
           now,
           endpoint
         );
@@ -4280,7 +4379,8 @@ var RelayCore = class {
       }
       const note = [`exited ${p.code}`, spender.status_note].filter(Boolean).join("; ").slice(0, LIMITS.noteChars);
       this.sql.all(
-        `UPDATE endpoints SET status_state = 'done', status_note = ?, hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END WHERE id = ?`,
+        `UPDATE endpoints SET status_state = 'done', status_note = ?, hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END,
+         wake = CASE WHEN wakers = 0 THEN NULL ELSE wake END WHERE id = ?`,
         note,
         now,
         spender.id
@@ -4705,6 +4805,7 @@ ${stderr}` : "";
     return scopeDecision(world, world.node(a.id) ?? this.scopeNode(a), world.node(b.id) ?? this.scopeNode(b), {
       humanAlways: this.defaults().humanAlways,
       solicited,
+      linked: a.id !== b.id && this.linkedAcross(a, b),
       unverified,
       strict
     });
@@ -5435,7 +5536,8 @@ ${stderr}` : "";
   }
   placeView(row, shown) {
     const parent = row.parent_ep && (!shown || shown.has(row.parent_ep)) ? this.byId(row.parent_ep) : void 0;
-    return { parent: parent ? this.address(parent) : null, depth: row.depth ?? 0, scope: presetOf(this.scopeNode(row), this.defaults().symmetric) };
+    const across = !parent && row.parent_ep === null && row.parent_addr ? this.linkedParent(row, shown) : null;
+    return { parent: parent ? this.address(parent) : across, depth: row.depth ?? 0, scope: presetOf(this.scopeNode(row), this.defaults().symmetric) };
   }
   /** `recipient` names the delivery's endpoint when there is no `seq`: a send to several addresses shows each recipient only itself */
   envelope(row, seq, recipient) {
@@ -5472,6 +5574,7 @@ ${stderr}` : "";
       created_at: iso(row.created_at),
       expires_at: iso(row.expires_at),
       ...row.require_reply === 1 ? { require_reply: true } : {},
+      ...row.link_parent ? { link: { parent: row.link_parent } } : {},
       ...kin
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/core",
-  "version": "0.1.6",
+  "version": "0.3.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

@@ -4,6 +4,7 @@ import {
   CLI_NAME,
   type ActivityKind,
   type ActivityRow,
+  type AdoptResult,
   type AuditRow,
   type Claim,
   type DataClass,
@@ -243,6 +244,8 @@ export interface EndpointRow {
   /** the root endpoint's id; null for a root */
   tree: string | null
   parent_ep: string | null
+  /** a parent on another machine of the account, `<machine>/<handle>`: the row stays a root of its own tree */
+  parent_addr: string | null
   depth: number | null
   /** JSON {@link ScopeRules} */
   rules: string | null
@@ -289,8 +292,11 @@ export interface MessageRow {
   expires_at: number
   sender_tty: number | null
   require_reply: number | null
+  link_parent: string | null
 }
 
+type AdoptSend = (from: string, params: SendParams, origin: { link: "session" | "self" }) => Promise<SendResult>
+
 export interface CoreOptions {
   /** the local user's address part; `me` until a login names one */
   user?: string
@@ -521,6 +527,7 @@ export class RelayCore {
     const messageColumns = this.sql.all<{ name: string }>(`PRAGMA table_info(messages)`).map((c) => c.name)
     if (!messageColumns.includes("sender_tty")) this.sql.all(`ALTER TABLE messages ADD COLUMN sender_tty INTEGER`)
     if (!messageColumns.includes("require_reply")) this.sql.all(`ALTER TABLE messages ADD COLUMN require_reply INTEGER`)
+    if (!messageColumns.includes("link_parent")) this.sql.all(`ALTER TABLE messages ADD COLUMN link_parent TEXT`)
     const endpointColumns = this.sql.all<{ name: string }>(`PRAGMA table_info(endpoints)`).map((c) => c.name)
     if (!endpointColumns.includes("session")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN session TEXT`)
     if (!endpointColumns.includes("hook_seen")) this.sql.all(`ALTER TABLE endpoints ADD COLUMN hook_seen INTEGER`)
@@ -533,6 +540,7 @@ export class RelayCore {
     for (const [column, type] of [
       ["tree", "TEXT"],
       ["parent_ep", "TEXT"],
+      ["parent_addr", "TEXT"],
       ["depth", "INTEGER"],
       ["rules", "TEXT"],
       ["caps", "TEXT"],
@@ -1203,7 +1211,7 @@ export class RelayCore {
     }
     caps.caps.push(...this.capsOf(row).caps)
     this.sql.all(
-      `UPDATE endpoints SET tree = ?, parent_ep = ?, depth = ?, rules = ?, caps = ? WHERE id = ?`,
+      `UPDATE endpoints SET tree = ?, parent_ep = ?, parent_addr = NULL, depth = ?, rules = ?, caps = ? WHERE id = ?`,
       parent ? (parent.tree ?? parent.id) : null,
       parent?.id ?? null,
       depth,
@@ -1500,13 +1508,21 @@ export class RelayCore {
    */
   waker(endpoint: string, live: boolean, options: { grace?: boolean } = {}): void {
     if (live) this.sql.all(`UPDATE endpoints SET wakers = wakers + 1 WHERE id = ?`, endpoint)
-    else
+    else {
+      const now = this.now()
       this.sql.all(
         `UPDATE endpoints SET wakers = MAX(wakers - 1, 0), waker_left = CASE WHEN ? THEN ? ELSE waker_left END WHERE id = ?`,
         options.grace ? 1 : 0,
-        this.now(),
+        now,
         endpoint,
       )
+      if (!options.grace) this.lapseWake(endpoint, now)
+    }
+  }
+
+  /** clears a wake no waker holds once a hook waker's grace ran out too: nothing is left to wake the endpoint */
+  private lapseWake(endpoint: string, now: number): void {
+    this.sql.all(`UPDATE endpoints SET wake = NULL WHERE id = ? AND wakers = 0 AND COALESCE(waker_left, 0) < ?`, endpoint, now - LIMITS.restartGraceS * 1000)
   }
 
   /**
@@ -1581,30 +1597,60 @@ export class RelayCore {
     })
   }
 
-  /**
-   * links a local root agent under `parent`, as a spawned worker sits: in the parent's tree one level down, under the policy's child scope.
-   * Only the human at a terminal links another session, or an agent from its own shell with a terminal attached, under itself by default.
-   * A session links itself with {@link joinSession}'s `under`
-   */
-  adopt(actor: ScopeActor, params: { endpoint: unknown; parent?: unknown }, options: { tty?: boolean } = {}): { endpoint: EndpointView; parent: string } {
-    return this.scopeTx(() => {
+  /** the human links a local root directly; an agent asks it to consent through the normal send path */
+  adopt(actor: ScopeActor, params: { endpoint: unknown; parent?: unknown }, options?: { tty?: boolean }): AdoptResult
+  adopt(actor: ScopeActor, params: { endpoint: unknown; parent?: unknown }, options: { tty?: boolean; send: AdoptSend }): AdoptResult | Promise<AdoptResult>
+  adopt(
+    actor: ScopeActor,
+    params: { endpoint: unknown; parent?: unknown },
+    options: { tty?: boolean; send?: AdoptSend } = {},
+  ): AdoptResult | Promise<AdoptResult> {
+    const prepared: { result: AdoptResult; sender?: { from: string; auth: "session" | "self" } } = this.scopeTx(() => {
       const me = this.actorRow(actor)
       if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint)
-      else if (options.tty !== true)
-        throw this.scopeRefused(
-          actor,
-          me,
-          { target: String(params.endpoint), reason: "adopt" },
-          `only the human at a terminal links another session under a parent; the session links itself with ${CLI_NAME} join --under`,
-        )
+      else if (actor.auth === "lineage")
+        throw this.scopeRefused(actor, me, { target: String(params.endpoint), reason: "adopt" }, "only the session itself may request a link")
       const target = this.resolve(params.endpoint)
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be linked")
       const parentAddress = params.parent ?? (actor.kind === "human" ? undefined : this.address(me))
       if (parentAddress === undefined || parentAddress === null || parentAddress === "")
         throw new RelayError("invalid_params", "the human names the parent to link under")
       const parent = this.resolve(parentAddress)
-      this.link(target, parent, this.actorDetail(actor, me))
-      return { endpoint: this.whoami(target.id), parent: this.address(parent) }
+      if (actor.kind !== "human" && parent.id !== me.id)
+        throw this.scopeRefused(actor, me, { target: this.address(target), reason: "adopt" }, "an agent may request a link only under itself")
+      const result: AdoptResult = { endpoint: this.whoami(target.id), parent: this.address(parent) }
+      if (actor.kind === "human" || options.tty === true) {
+        this.link(target, parent, this.actorDetail(actor, me))
+        return { result: { ...result, endpoint: this.whoami(target.id) } }
+      }
+      if (target.parent_ep !== null || target.parent_addr !== null) throw this.alreadyLinked(target)
+      const auth = actor.auth === "self" ? "self" : "session"
+      return { result, sender: { from: me.id, auth } }
+    })
+    if (!prepared.sender) return prepared.result
+    const { result } = prepared
+    const { from, auth } = prepared.sender
+    const send: SendParams = {
+      to: result.endpoint.address,
+      kind: "request",
+      ttl_s: 86_400,
+      body: `${result.parent} asks you to link under it as its worker. To accept, run ${CLI_NAME} link accept <id> with this message's id, or ${CLI_NAME} join --under ${result.parent} (relay_link_accept {id} or relay_join {under: "${result.parent}"}).`,
+    }
+    const requested = (sent: SendResult): AdoptResult => ({ ...result, ...(sent.held ? { held: sent.held } : { requested: sent.id }) })
+    return options.send ? options.send(from, send, { link: auth }).then(requested) : requested(this.send(from, send, { link: auth }))
+  }
+
+  /** accepts a broker-issued request delivered to the caller's own session */
+  linkAccept(actor: ScopeActor, params: { id: unknown }): { endpoint: EndpointView; parent: string } {
+    return this.scopeTx(() => {
+      if (actor.kind !== "endpoint" || actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself accepts a link request")
+      const me = this.actorRow(actor)
+      const request = this.delivered(me.id, params.id)
+      if (!request?.link || request.kind !== "request") throw new RelayError("not_found", "no link request delivered to this endpoint")
+      const parent = this.mustEndpoint(request.from.endpoint)
+      if (parent.kind !== "agent") throw new RelayError("invalid_params", "the requesting parent is no longer an agent")
+      this.link(me, parent, { ...this.actorDetail(actor, me), request: request.id })
+      return { endpoint: this.whoami(me.id), parent: this.address(parent) }
     })
   }
 
@@ -1620,7 +1666,8 @@ export class RelayCore {
       const target = params.endpoint === undefined ? me : this.resolve(params.endpoint)
       if (actor.kind !== "human" && target.id !== me.id) throw new RelayError("scope_refused", "an agent unlinks only itself")
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be unlinked")
-      if (target.parent_ep === null) throw new RelayError("invalid_params", `${this.address(target)} is a root: it has no parent`)
+      if (target.parent_ep === null && target.parent_addr === null)
+        throw new RelayError("invalid_params", `${this.address(target)} is a root: it has no parent`)
       if (actor.kind !== "human" && this.policy?.defaults?.unlink !== "self")
         throw this.scopeRefused(
           actor,
@@ -1628,6 +1675,14 @@ export class RelayCore {
           { target: this.address(target), reason: "unlink" },
           "unlinking widens a worker's scope: only the human at a terminal unlinks it (policy defaults.unlink: self lets it)",
         )
+      if (target.parent_ep === null) {
+        const from = this.linkedParent(target) ?? target.parent_addr!
+        this.sql.all(`UPDATE endpoints SET parent_addr = NULL, linked = NULL WHERE id = ?`, target.id)
+        this.scopeMemo?.ancestors.clear()
+        this.scopeMemo?.limited.clear()
+        this.audit("unlink", target.id, null, { ...this.actorDetail(actor, me), target: this.address(target), parent: from })
+        return { endpoint: this.whoami(target.id), parent: from }
+      }
       const parent = this.byId(target.parent_ep)
       const from = parent ? this.address(parent) : target.parent_ep
       const shift = target.depth ?? 0
@@ -1652,16 +1707,26 @@ export class RelayCore {
     })
   }
 
-  /** `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants */
-  private link(row: EndpointRow, parent: EndpointRow, by: { by: string; auth: string }): void {
-    if (parent.kind !== "agent" || !this.localRow(parent)) throw new RelayError("invalid_params", "the parent is a local agent endpoint")
+  /**
+   * `row`, a root, and its subtree moved under `parent`, a local agent that is neither `row` nor one of its descendants; a parent on another
+   * machine goes to {@link linkAcross}
+   */
+  private link(row: EndpointRow, parent: EndpointRow, by: { by: string; auth: string; request?: string }): void {
+    if (!this.localRow(parent)) {
+      const key = this.linkAcross(row, parent)
+      if (row.parent_addr === key) return
+      if (row.parent_ep !== null || row.parent_addr !== null) throw this.alreadyLinked(row)
+      this.sql.all(`UPDATE endpoints SET parent_addr = ?, linked = ? WHERE id = ?`, key, this.now(), row.id)
+      this.scopeMemo?.ancestors.clear()
+      this.scopeMemo?.limited.clear()
+      this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) })
+      return
+    }
+    if (parent.kind !== "agent") throw new RelayError("invalid_params", "the parent is an agent endpoint")
     if (row.parent_ep === parent.id) return
     if (parent.id === row.id || this.ancestorsOf(parent).includes(row.id))
       throw new RelayError("scope_refused", `${this.address(parent)} sits under ${this.address(row)}: a session cannot go under its own descendant`)
-    if (row.parent_ep !== null) {
-      const now = this.byId(row.parent_ep)
-      throw new RelayError("scope_refused", `${this.address(row)} already sits under ${now ? this.address(now) : "another agent"}; unlink it first`)
-    }
+    if (row.parent_ep !== null || row.parent_addr !== null) throw this.alreadyLinked(row)
     const depth = (parent.depth ?? 0) + 1
     const deepest = one<{ d: number | null }>(this.sql, `SELECT MAX(depth) AS d FROM endpoints WHERE tree = ?`, row.id)?.d ?? 0
     if (deepest + depth > LIMITS.depthMax)
@@ -1683,7 +1748,32 @@ export class RelayCore {
     )
     this.scopeMemo?.ancestors.clear()
     this.scopeMemo?.limited.clear()
-    this.audit("adopt", row.id, null, { ...by, target: this.address(row), parent: this.address(parent) })
+    this.audit("adopt", row.id, by.request ?? null, { ...by, target: this.address(row), parent: this.address(parent) })
+  }
+
+  /** a link of `row`, which already sits under a parent, to another one */
+  private alreadyLinked(row: EndpointRow): RelayError {
+    const local = row.parent_ep ? this.byId(row.parent_ep) : undefined
+    const now = local ? this.address(local) : row.parent_addr !== null ? (this.linkedParent(row) ?? row.parent_addr) : "another agent"
+    return new RelayError("scope_refused", `${this.address(row)} already sits under ${now}; unlink it first`)
+  }
+
+  /**
+   * the key `<machine>/<handle>` that links `row`, a local agent, under `parent`, an agent on another machine, once the parent is checked; no
+   * inherited or child-default caps come with it. A relay of one machine has no such parent
+   */
+  protected linkAcross(_row: EndpointRow, _parent: EndpointRow): string {
+    throw new RelayError("invalid_params", "the parent is a local agent endpoint")
+  }
+
+  /** whether `a` and `b` are a parent and its child on different machines */
+  protected linkedAcross(_a: EndpointRow, _b: EndpointRow): boolean {
+    return false
+  }
+
+  /** the address of `row`'s parent on another machine, null when it has none; with `shown`, null for a parent outside it */
+  protected linkedParent(_row: EndpointRow, _shown?: Set<string>): string | null {
+    return null
   }
 
   /**
@@ -1734,9 +1824,13 @@ export class RelayCore {
       ] as const)
         this.sql.all(`UPDATE ${table} SET ${column} = REPLACE(${column}, ?, ?) WHERE instr(${column}, ?) > 0`, a, b, a)
     }
+    this.renamedHandle(from, handle)
     this.audit("rename", row.id, null, { from, to: handle })
   }
 
+  /** a local agent's handle moved from `from` to `to`: a subclass updates what names it on another machine's rows */
+  protected renamedHandle(_from: string, _to: string): void {}
+
   /**
    * a session leaves: it lets go of its session and token and shows offline, its mail kept; a later join takes it back. An agent leaves only
    * itself, the human at a terminal any local root or linked agent. A spawned worker stays joined while it runs
@@ -1770,7 +1864,8 @@ export class RelayCore {
    * `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
    */
-  send(from: string, params: SendParams, origin: { tty?: boolean; unverified?: boolean } = {}): SendResult {
+  send(from: string, params: SendParams, origin: { tty?: boolean; unverified?: boolean; link?: "session" | "self" } = {}): SendResult {
+    if ("link" in params) throw new RelayError("invalid_params", "link is set by the relay, not the sender")
     const sender = this.mustEndpoint(from)
     const senderTty = sender.kind === "human" ? (origin.tty === true ? 1 : 0) : null
     const unverified = sender.kind === "human" && origin.unverified === true
@@ -1838,6 +1933,17 @@ export class RelayCore {
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }))
     const reached = recipients.length + pending.length
     if (reached > LIMITS.fanOutTotal) throw new RelayError("too_large", `the send reaches ${reached} endpoints, more than ${LIMITS.fanOutTotal}`)
+    if (
+      origin.link &&
+      (sender.kind !== "agent" ||
+        kind !== "request" ||
+        recipients.length !== 1 ||
+        pending.length ||
+        recipients[0]!.kind !== "agent" ||
+        !this.localRow(recipients[0]!))
+    )
+      throw new RelayError("invalid_params", "a link request is from an agent to one local root agent")
+    if (origin.link && (recipients[0]!.parent_ep !== null || recipients[0]!.parent_addr !== null)) throw this.alreadyLinked(recipients[0]!)
     const requestedThread = this.threadRef(from, cleanText(params.thread, "thread", 64))
     const payloadHash = this.hash(
       JSON.stringify([
@@ -1851,6 +1957,7 @@ export class RelayCore {
         mime,
         ttl,
         params.require_reply === true,
+        ...(origin.link ? [origin.link] : []),
       ]),
     )
     if (clientId) {
@@ -2020,8 +2127,8 @@ export class RelayCore {
       const expires = now + ttl * 1000
       const to = targets.length === 1 ? String(targets[0]) : targets.join(",")
       this.sql.all(
-        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        `INSERT INTO messages (id, thread, reply_to, kind, from_ep, to_addr, body, mime, data_class, attachments, hop, created_at, expires_at, sender_tty, require_reply, link_parent)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         id,
         thread,
         parent?.id ?? null,
@@ -2037,6 +2144,7 @@ export class RelayCore {
         expires,
         senderTty,
         params.require_reply === true ? 1 : null,
+        origin.link ? this.address(sender) : null,
       )
       if (parent) this.sql.all(`UPDATE deliveries SET acked_at = ? WHERE message_id = ? AND endpoint = ? AND acked_at IS NULL`, now, parent.id, from)
       const deliveries: SendResult["deliveries"] = []
@@ -2078,6 +2186,13 @@ export class RelayCore {
         )
       }
       this.audit("send", from, id, { to: deliveries.map((d) => d.address), kind, bytes, hop, thread, data_class: dataClass })
+      if (origin.link)
+        this.audit("adopt_request", from, id, {
+          by: this.address(sender),
+          auth: origin.link,
+          target: this.address(recipients[0]!),
+          parent: this.address(sender),
+        })
       for (const recipient of recipients) this.detectPingPong(sender, recipient)
       return sent
     })
@@ -3044,15 +3159,24 @@ export class RelayCore {
     }
   }
 
-  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would, and lapses wakes whose hook waker never came back */
   endExited(now = this.now()): void {
     for (const row of this.sql.all<EndpointRow>(
       `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND hook_seen IS NOT NULL AND process IS NOT NULL`,
     )) {
       const pid = Number(/^pid:(\d+)/.exec(row.process!)?.[1])
       if (!pid || !this.localRow(row) || this.alive(pid)) continue
-      this.sql.all(`UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL WHERE id = ? AND connections = 0`, now, row.id)
+      this.sql.all(
+        `UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL, wake = CASE WHEN wakers = 0 THEN NULL ELSE wake END WHERE id = ? AND connections = 0`,
+        now,
+        row.id,
+      )
     }
+    for (const row of this.sql.all<EndpointRow>(
+      `SELECT * FROM endpoints WHERE wake IS NOT NULL AND wakers = 0 AND waker_left < ?`,
+      now - LIMITS.restartGraceS * 1000,
+    ))
+      if (this.localRow(row)) this.lapseWake(row.id, now)
   }
 
   /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
@@ -3109,7 +3233,8 @@ export class RelayCore {
     if (params.kind === "session_end") {
       if (own)
         this.sql.all(
-          `UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END WHERE id = ?`,
+          `UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END,
+           wake = CASE WHEN wakers = 0 THEN NULL ELSE wake END WHERE id = ?`,
           now,
           endpoint,
         )
@@ -3821,7 +3946,8 @@ export class RelayCore {
       }
       const note = [`exited ${p.code}`, spender.status_note].filter(Boolean).join("; ").slice(0, LIMITS.noteChars)
       this.sql.all(
-        `UPDATE endpoints SET status_state = 'done', status_note = ?, hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END WHERE id = ?`,
+        `UPDATE endpoints SET status_state = 'done', status_note = ?, hook_seen = NULL, hook_ended = ?, session = CASE WHEN connections = 0 THEN NULL ELSE session END,
+         wake = CASE WHEN wakers = 0 THEN NULL ELSE wake END WHERE id = ?`,
         note,
         now,
         spender.id,
@@ -4310,6 +4436,7 @@ export class RelayCore {
     return scopeDecision(world, world.node(a.id) ?? this.scopeNode(a), world.node(b.id) ?? this.scopeNode(b), {
       humanAlways: this.defaults().humanAlways,
       solicited,
+      linked: a.id !== b.id && this.linkedAcross(a, b),
       unverified,
       strict,
     })
@@ -5139,7 +5266,8 @@ export class RelayCore {
 
   private placeView(row: EndpointRow, shown?: Set<string>): Pick<EndpointView, "parent" | "depth" | "scope"> {
     const parent = row.parent_ep && (!shown || shown.has(row.parent_ep)) ? this.byId(row.parent_ep) : undefined
-    return { parent: parent ? this.address(parent) : null, depth: row.depth ?? 0, scope: presetOf(this.scopeNode(row), this.defaults().symmetric) }
+    const across = !parent && row.parent_ep === null && row.parent_addr ? this.linkedParent(row, shown) : null
+    return { parent: parent ? this.address(parent) : across, depth: row.depth ?? 0, scope: presetOf(this.scopeNode(row), this.defaults().symmetric) }
   }
 
   /** `recipient` names the delivery's endpoint when there is no `seq`: a send to several addresses shows each recipient only itself */
@@ -5177,6 +5305,7 @@ export class RelayCore {
       created_at: iso(row.created_at)!,
       expires_at: iso(row.expires_at)!,
       ...(row.require_reply === 1 ? { require_reply: true as const } : {}),
+      ...(row.link_parent ? { link: { parent: row.link_parent } } : {}),
       ...kin,
     }
   }

package/src/protocol.ts

@@ -112,8 +112,8 @@ export type DataClass = "public" | "private"
 export type Presence = "online" | "idle" | "offline"
 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 or codex app-server; `none` reads at its next turn */
-export type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "none"
-export const WAKES: readonly Wake[] = ["channels", "pi", "opencode-plugin", "codex-app-server", "none"]
+export type Wake = "channels" | "pi" | "opencode-plugin" | "codex-app-server" | "claude-inbox" | "none"
+export const WAKES: readonly Wake[] = ["channels", "pi", "opencode-plugin", "codex-app-server", "claude-inbox", "none"]
 
 export type ActivityKind = "session_start" | "tool" | "stop" | "note" | "session_end"
 export const ACTIVITY_KINDS: readonly ActivityKind[] = ["session_start", "tool", "stop", "note", "session_end"]
@@ -358,6 +358,8 @@ export interface Envelope {
   expires_at: string
   /** a request whose sender holds the recipient's stop until it replies */
   require_reply?: true
+  /** a broker-issued request to link under its sender */
+  link?: { parent: string }
   /** set by inbox on a message a background hook already showed (and marked read), whose text may reach the agent only after this call */
   shown_at?: string
   /**
@@ -473,6 +475,13 @@ export interface SendResult {
   redacted?: JudgeRedacted
 }
 
+export interface AdoptResult {
+  endpoint: EndpointView
+  parent: string
+  requested?: string
+  held?: JudgeHeld
+}
+
 /**
  * a message the caller sent and, per recipient, when it read the message (acked), or when a background hook delivered it (acked by that
  * showing; the agent gets it with its next request), and when a hook or channel showed it: ISO times, or null
@@ -493,4 +502,4 @@ export interface AuditRow {
 }
 
 /** fields only the server sets: a client that sends them gets invalid_params */
-export const SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation"] as const
+export const SERVER_FIELDS = ["from", "id", "seq", "hop", "created_at", "auth", "expires_at", "relation", "link"] as const

package/src/scopes.ts

@@ -293,19 +293,20 @@ export function relationText(peer: PolicySubject, me: PolicySubject): string {
 /**
  * The scope check for a message from `a` to `b`: `out(a)` admits `b` and `in(b)` admits `a`. Either side the account's human (with `humanAlways`)
  * or the system endpoint passes, except an `unverified` human sender (one without a terminal), which is checked like any unplaced sender; an
- * ancestor of `b` (unless `strict`) and a solicited reply pass both.
+ * ancestor of `b` (unless `strict`), a solicited reply and a parent and child `linked` across machines pass both.
  */
 export function scopeDecision(
   world: ScopeWorld,
   a: ScopeNode,
   b: ScopeNode,
-  options: { humanAlways: boolean; solicited?: boolean; unverified?: boolean; strict?: boolean },
+  options: { humanAlways: boolean; solicited?: boolean; linked?: boolean; unverified?: boolean; strict?: boolean },
 ): ScopeDecision {
   const kinds = [a.subject.kind, b.subject.kind]
   if (kinds.includes("system")) return { allowed: true, reasons: ["the relay itself"] }
   if (options.humanAlways && (b.human || (a.human && !options.unverified))) return { allowed: true, reasons: ["the human is always reachable"] }
   if (!options.strict && isAncestor(a, b)) return { allowed: true, reasons: [`${a.address} is an ancestor of ${b.address}: scopes never stop it`] }
   if (options.solicited) return { allowed: true, reasons: [`a reply to ${b.address}'s message in its thread`] }
+  if (options.linked) return { allowed: true, reasons: [`${a.address} and ${b.address} are parent and child across machines`] }
   const memo: Memo = new Map()
   const out = admits(world, a, "out", b, memo)
   if (!out.ok) return { allowed: false, dir: "out", reasons: [out.why] }