@scp-dev/core 0.2.0 → 0.3.1

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[];
@@ -439,6 +439,8 @@ interface Claim {
     session?: string;
     /** the harness process the claim comes from, `pid:<pid>:<start time>`: a shim restarted in that process may rejoin its endpoint */
     process?: string;
+    /** the harness's own stable session id (Claude Code's): a resumed session in a new harness process takes back the offline endpoint of that id */
+    harness_session?: string;
     /** process keys of the claimant's harness process and its ancestors, nearest first: the nearest endpoint holding one places the claim under it */
     lineage?: string[];
     /** a `krt_` grant from `spawn-env`: places the claim at or below its lineage placement, with the grant's caps and groups */
@@ -658,6 +660,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 +775,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 +804,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`,
@@ -1133,7 +1145,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;
@@ -1226,6 +1242,12 @@ declare class RelayCore {
      */
     private boundGrant;
     private claimRow;
+    /**
+     * the offline local row a claim of harness session `harnessSession` from a new harness process takes back, as a restart of that session:
+     * of a fitting harness, no subagent's, and restarted where it sits or redeemed with its grant. A claim with a grant that row did not spend
+     * is a new spawn and takes none. A named row first, then the latest seen
+     */
+    private resumable;
     /** a session's hook endpoint left for `to`: its unread mail moves there and it lets go of the session; the moved seqs and its stop budget */
     private leaveHooks;
     /**
@@ -1384,16 +1406,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;
@@ -1426,18 +1455,29 @@ declare class RelayCore {
     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
+     * 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,
+     * except an offline one {@link renameRow} takes over
      */
     rename(actor: ScopeActor, params: {
         endpoint?: unknown;
         handle: unknown;
+        take_over?: unknown;
     }): {
         endpoint: EndpointView;
         from: string;
         session: string | null;
+        retired?: string;
     };
-    /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
+    /**
+     * the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it. A local offline agent holding the handle
+     * is taken over when it held the same harness session, or with `takeOver` by the human at a terminal: the id of the row retired
+     */
     private renameRow;
+    /**
+     * `row` takes over `held`, an offline local agent, and retires it: `held`'s subtree, unread mail, grants, groups and harness session move to
+     * `row`, which takes `held`'s hand-made link when it is an unlinked root itself. Its handle is then free for `row`
+     */
+    private takeOver;
     /** 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;
     /**
@@ -1459,6 +1499,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;
@@ -2534,4 +2575,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)?-----";
@@ -1327,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`);
@@ -1520,10 +1521,13 @@ var RelayCore = class {
       parent: cleanText(claim.parent, "parent", 128),
       labels: JSON.stringify(this.machineLabel(cleanLabels(claim.labels))),
       session: cleanText(claim.session, "session", 128),
-      process: cleanText(claim.process, "process", 128)
+      process: cleanText(claim.process, "process", 128),
+      harness_session: cleanText(claim.harness_session, "harness_session", 128)
     };
     if (fields.process !== null && !ANY_PROCESS_KEY.test(fields.process)) throw new RelayError("invalid_params", "process is a key pid:<pid>[:<start time>]");
-    const leaked = [wanted, fields.model, fields.cwd, fields.parent, fields.labels, fields.session].map((v) => v ? findSecret(v) : null).find(Boolean);
+    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);
     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");
@@ -1635,6 +1639,7 @@ var RelayCore = class {
     let stopBlocks = null;
     let moved = [];
     let exactFrom;
+    const open = !row || presenceOf(row, now) === "offline";
     if (row && presenceOf(row, now) === "offline") {
       this.sql.all(`UPDATE endpoints SET session = NULL WHERE id = ?`, row.id);
       row = void 0;
@@ -1668,7 +1673,9 @@ var RelayCore = class {
         exactFrom = hooks;
       }
     } else if (row && transient) session = row.session;
-    let joined = row !== void 0;
+    const resumed = !row && open && !scope.exact && !scope.subagent && fields.harness_session ? this.resumable(harness, fields.harness_session, scope, fields, now) : void 0;
+    if (resumed) row = resumed;
+    let joined = row !== void 0 && !resumed;
     let own = false;
     let live = false;
     let created = false;
@@ -1698,7 +1705,7 @@ var RelayCore = class {
     if (!row)
       throw scope.exact ? this.exactRefusal(this.byHandle(wanted), wanted, harness, now) : new RelayError("invalid_params", `no free handle for ${wanted}`);
     if (exactFrom && exactFrom.id !== row.id) ({ moved, stopBlocks } = this.leaveHooks(exactFrom, row.id));
-    const fresh = created || joined ? null : this.incarnates(row, scope, fields.process, now);
+    const fresh = created || joined || resumed ? null : this.incarnates(row, scope, fields.process, now);
     const token = transient || live ? void 0 : `kre_${randomHex(32)}`;
     const field = (column) => transient ? `COALESCE(?, ${column})` : "?";
     if (session) this.sql.all(`UPDATE endpoints SET session = NULL WHERE session = ? AND harness = ? AND id != ?`, session, harness, row.id);
@@ -1738,7 +1745,14 @@ var RelayCore = class {
     if (!transient && fields.cwd !== null) this.sql.all(`UPDATE grants SET spent_cwd = ? WHERE used_by = ?`, fields.cwd, row.id);
     if (!(transient && joined)) {
       const sub = scope.subagent ? { subagent: scope.subagent.type ?? "agent", parent: this.addressOf(scope.subagent.root) } : {};
-      this.audit("claim", row.id, null, { handle: row.handle, harness, ...joined ? { joined: true } : {}, ...transient ? { transient: true } : {}, ...sub });
+      this.audit("claim", row.id, null, {
+        handle: row.handle,
+        harness,
+        ...joined ? { joined: true } : {},
+        ...resumed ? { resumed: true } : {},
+        ...transient ? { transient: true } : {},
+        ...sub
+      });
     }
     if (fresh) this.reset(row, scope, fresh, moved, now);
     if (created || fresh === "grant") this.place(this.byId(row.id), scope, now);
@@ -1746,6 +1760,23 @@ var RelayCore = class {
     if (scope.grant !== null) this.takePending(row.id);
     return { endpoint: this.view(this.byId(row.id)), ...token ? { token } : {}, ...created ? { created: true } : {} };
   }
+  /**
+   * the offline local row a claim of harness session `harnessSession` from a new harness process takes back, as a restart of that session:
+   * of a fitting harness, no subagent's, and restarted where it sits or redeemed with its grant. A claim with a grant that row did not spend
+   * is a new spawn and takes none. A named row first, then the latest seen
+   */
+  resumable(harness, harnessSession, scope, fields, now) {
+    const rows = this.sql.all(
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND harness_session = ? AND connections = 0 AND (session IS NULL OR substr(session, 1, 4) != 'sub:')
+       AND substr(handle, 1, ${GONE_PREFIX.length}) != '${GONE_PREFIX}' ORDER BY named IS NULL, COALESCE(last_seen, created_at) DESC`,
+      harnessSession
+    );
+    const parent = rows.length ? this.placement(scope, now).parent : null;
+    const spender = scope.grant === null ? null : this.spentGrant(scope)?.used_by ?? "";
+    return rows.find(
+      (row) => (spender === null || spender === row.id) && this.localRow(row) && harnessFits(row.harness, harness) && presenceOf(row, now) === "offline" && (this.restarts(row, parent, fields.process) || this.redeems(row, scope, { harness, ...fields }))
+    );
+  }
   /** a session's hook endpoint left for `to`: its unread mail moves there and it lets go of the session; the moved seqs and its stop budget */
   leaveHooks(hooks, to) {
     const moved = this.sql.all(`UPDATE deliveries SET endpoint = ? WHERE endpoint = ? AND acked_at IS NULL RETURNING seq`, to, hooks.id).map((d) => d.seq);
@@ -2278,30 +2309,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) };
     });
   }
   /**
@@ -2368,7 +2421,7 @@ var RelayCore = class {
       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, 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) });
       return;
     }
     if (parent.kind !== "agent") throw new RelayError("invalid_params", "the parent is an agent endpoint");
@@ -2397,7 +2450,7 @@ 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) {
@@ -2422,9 +2475,11 @@ var RelayCore = class {
   }
   /**
    * 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
+   * 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,
+   * except an offline one {@link renameRow} takes over
    */
   rename(actor, params) {
+    if (params.take_over !== void 0 && typeof params.take_over !== "boolean") throw new RelayError("invalid_params", "take_over is true or false");
     return this.scopeTx(() => {
       const me = this.actorRow(actor);
       if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
@@ -2432,12 +2487,15 @@ 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 renames only itself");
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be renamed");
-      this.renameRow(target, params.handle, actor.kind === "human");
-      return { endpoint: this.whoami(target.id), from: target.handle, session: target.session };
+      const retired = this.renameRow(target, params.handle, actor.kind === "human", params.take_over === true);
+      return { endpoint: this.whoami(target.id), from: target.handle, session: target.session, ...retired ? { retired } : {} };
     });
   }
-  /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
-  renameRow(row, value, byHuman) {
+  /**
+   * the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it. A local offline agent holding the handle
+   * is taken over when it held the same harness session, or with `takeOver` by the human at a terminal: the id of the row retired
+   */
+  renameRow(row, value, byHuman, takeOver = false) {
     const handle = typeof value === "string" ? value.trim().replace(/^me\//, "") : "";
     if (!validHandle(handle)) throw new RelayError("invalid_params", `handle ${JSON.stringify(handle)} is not valid: lowercase letters, digits, . _ -`);
     if (findSecret(handle)) throw new RelayError("secret_refused", "the handle looks like it carries a credential");
@@ -2450,14 +2508,23 @@ var RelayCore = class {
       throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; its name is set by the spawner`);
     }
     const held = this.byHandle(handle);
+    let retired;
     if (held) {
-      const how = held.kind !== "agent" ? "reserved" : presenceOf(held, this.now()) === "offline" ? "held by an offline endpoint" : "held by a live endpoint";
-      throw new RelayError("invalid_params", `${handle} is ${how}: pick another name`);
+      const offline = held.kind === "agent" && held.connections === 0 && presenceOf(held, this.now()) === "offline" && this.localRow(held);
+      const same = held.harness_session !== null && held.harness_session === row.harness_session;
+      if (takeOver && !byHuman && !same) throw new RelayError("scope_refused", "only the human at a terminal takes over another endpoint");
+      if (takeOver && offline && !same && !harnessFits(held.harness, row.harness ?? "cli"))
+        throw new RelayError("invalid_params", `${handle} is a ${held.harness} endpoint: only an endpoint of the same harness is taken over`);
+      if (!offline || held.session?.startsWith("sub:") || !(same || takeOver && harnessFits(held.harness, row.harness ?? "cli"))) {
+        const how = held.kind !== "agent" ? "reserved" : presenceOf(held, this.now()) === "offline" ? "held by an offline endpoint" : "held by a live endpoint";
+        throw new RelayError("invalid_params", `${handle} is ${how}: pick another name${offline ? ", or take it over with --take-over from a terminal" : ""}`);
+      }
+      retired = this.takeOver(row, held, same ? "session" : "human");
     }
     const from = row.handle;
     this.sql.all(`UPDATE endpoints SET handle = ?, named = ? WHERE id = ?`, handle, this.now(), row.id);
     this.sql.all(`UPDATE grants SET name = ? WHERE used_by = ? AND name = ?`, handle, row.id, from);
-    for (const prefix of row.parent_ep === null ? ["ep:", "fleet:"] : ["ep:"]) {
+    for (const prefix of this.byId(row.id).parent_ep === null ? ["ep:", "fleet:"] : ["ep:"]) {
       const [a, b] = [JSON.stringify(`${prefix}${from}`), JSON.stringify(`${prefix}${handle}`)];
       for (const [table, column] of [
         ["endpoints", "rules"],
@@ -2469,6 +2536,51 @@ var RelayCore = class {
     }
     this.renamedHandle(from, handle);
     this.audit("rename", row.id, null, { from, to: handle });
+    return retired;
+  }
+  /**
+   * `row` takes over `held`, an offline local agent, and retires it: `held`'s subtree, unread mail, grants, groups and harness session move to
+   * `row`, which takes `held`'s hand-made link when it is an unlinked root itself. Its handle is then free for `row`
+   */
+  takeOver(row, held, by) {
+    if (this.ancestorsOf(row).includes(held.id))
+      throw new RelayError("scope_refused", `${this.address(row)} sits under ${this.address(held)}: it cannot take over its own ancestor`);
+    if (row.parent_ep === null && row.parent_addr === null && held.linked !== null && held.parent_addr !== null)
+      this.sql.all(`UPDATE endpoints SET parent_addr = ?, linked = ? WHERE id = ?`, held.parent_addr, held.linked, row.id);
+    else if (row.parent_ep === null && row.parent_addr === null && held.linked !== null && held.parent_ep !== null) {
+      const parent = this.byId(held.parent_ep);
+      if (parent) this.link(row, parent, { by: this.address(row), auth: by });
+    }
+    const place = this.byId(row.id);
+    const shift = (place.depth ?? 0) - (held.depth ?? 0);
+    const below = `WITH RECURSIVE below(id) AS (SELECT id FROM endpoints WHERE parent_ep = ? UNION SELECT e.id FROM endpoints e JOIN below b ON e.parent_ep = b.id)`;
+    const deepest = one(this.sql, `${below} SELECT MAX(depth) AS d FROM endpoints WHERE id IN (SELECT id FROM below)`, held.id)?.d;
+    if (deepest != null && deepest + shift > LIMITS.depthMax)
+      throw new RelayError("scope_refused", `${this.address(held)}'s children would sit deeper than ${LIMITS.depthMax} under ${this.address(place)}`);
+    this.sql.all(`${below} UPDATE endpoints SET tree = ?, depth = depth + ? WHERE id IN (SELECT id FROM below)`, held.id, place.tree ?? place.id, shift);
+    const children = this.sql.all(`UPDATE endpoints SET parent_ep = ? WHERE parent_ep = ? RETURNING id`, row.id, held.id).length;
+    this.sql.all(`UPDATE deliveries SET endpoint = ? WHERE endpoint = ? AND acked_at IS NULL`, row.id, held.id);
+    this.sql.all(`UPDATE grants SET issuer = ? WHERE issuer = ?`, row.id, held.id);
+    this.sql.all(`UPDATE grants SET under = ? WHERE under = ?`, row.id, held.id);
+    this.sql.all(`UPDATE groups SET owner = ? WHERE owner = ?`, row.id, held.id);
+    this.sql.all(
+      `INSERT OR IGNORE INTO group_members (name, endpoint, added_by, at) SELECT name, ?, added_by, at FROM group_members WHERE endpoint = ?`,
+      row.id,
+      held.id
+    );
+    this.sql.all(`DELETE FROM group_members WHERE endpoint = ?`, held.id);
+    this.sql.all(
+      `UPDATE endpoints SET harness_session = ?, harness_transcript = ? WHERE id = ? AND harness_session IS NULL`,
+      held.harness_session,
+      held.harness_transcript,
+      row.id
+    );
+    this.sql.all(`UPDATE endpoints SET handle = ?, session = NULL, token_hash = NULL WHERE id = ?`, `${GONE_PREFIX}${held.id}`, held.id);
+    this.dropPeek(held.id);
+    this.scopeMemo?.ancestors.clear();
+    this.scopeMemo?.limited.clear();
+    this.audit("take_over", row.id, null, { from: row.handle, to: held.handle, retired: held.id, children, by });
+    return held.id;
   }
   /** a local agent's handle moved from `from` to `to`: a subclass updates what names it on another machine's rows */
   renamedHandle(_from, _to) {
@@ -2504,6 +2616,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;
@@ -2565,6 +2678,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([
@@ -2577,7 +2693,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) {
@@ -2735,8 +2852,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,
@@ -2751,7 +2868,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 = [];
@@ -2793,6 +2911,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;
     });
@@ -5538,6 +5663,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.2.0",
+  "version": "0.3.1",
   "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,
@@ -291,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
@@ -523,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`)
@@ -723,9 +728,14 @@ export class RelayCore {
       labels: JSON.stringify(this.machineLabel(cleanLabels(claim.labels))),
       session: cleanText(claim.session, "session", 128),
       process: cleanText(claim.process, "process", 128),
+      harness_session: cleanText(claim.harness_session, "harness_session", 128),
     }
     if (fields.process !== null && !ANY_PROCESS_KEY.test(fields.process)) throw new RelayError("invalid_params", "process is a key pid:<pid>[:<start time>]")
-    const leaked = [wanted, fields.model, fields.cwd, fields.parent, fields.labels, fields.session].map((v) => (v ? findSecret(v) : null)).find(Boolean)
+    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)
     if (leaked) throw new RelayError("secret_refused", `the claim looks like it carries a credential (${leaked})`)
     if (claim.grant !== undefined && (typeof claim.grant !== "string" || !GRANT_TOKEN.test(claim.grant)))
       throw new RelayError("invalid_params", "grant is a krt_ token")
@@ -829,7 +839,15 @@ export class RelayCore {
   private claimRow(
     wanted: string,
     harness: string,
-    fields: { model: string | null; cwd: string | null; parent: string | null; labels: string; session: string | null; process: string | null },
+    fields: {
+      model: string | null
+      cwd: string | null
+      parent: string | null
+      labels: string
+      session: string | null
+      process: string | null
+      harness_session?: string | null
+    },
     transient: boolean,
     scope: ClaimScope = { handle: wanted, lineage: [], grant: null, rules: {}, groups: [], cwd: fields.cwd },
   ): { endpoint: EndpointView; token?: string; created?: true } {
@@ -854,6 +872,7 @@ export class RelayCore {
     let stopBlocks: number | null = null
     let moved: number[] = []
     let exactFrom: EndpointRow | undefined
+    const open = !row || presenceOf(row, now) === "offline"
     if (row && presenceOf(row, now) === "offline") {
       this.sql.all(`UPDATE endpoints SET session = NULL WHERE id = ?`, row.id)
       row = undefined
@@ -893,7 +912,12 @@ export class RelayCore {
         exactFrom = hooks
       }
     } else if (row && transient) session = row.session
-    let joined = row !== undefined
+    const resumed =
+      !row && open && !scope.exact && !scope.subagent && fields.harness_session
+        ? this.resumable(harness, fields.harness_session, scope, fields, now)
+        : undefined
+    if (resumed) row = resumed
+    let joined = row !== undefined && !resumed
     let own = false
     let live = false
     let created = false
@@ -939,7 +963,7 @@ export class RelayCore {
     if (!row)
       throw scope.exact ? this.exactRefusal(this.byHandle(wanted)!, wanted, harness, now) : new RelayError("invalid_params", `no free handle for ${wanted}`)
     if (exactFrom && exactFrom.id !== row.id) ({ moved, stopBlocks } = this.leaveHooks(exactFrom, row.id))
-    const fresh = created || joined ? null : this.incarnates(row, scope, fields.process, now)
+    const fresh = created || joined || resumed ? null : this.incarnates(row, scope, fields.process, now)
     const token = transient || live ? undefined : `kre_${randomHex(32)}`
     const field = (column: string) => (transient ? `COALESCE(?, ${column})` : "?")
     if (session) this.sql.all(`UPDATE endpoints SET session = NULL WHERE session = ? AND harness = ? AND id != ?`, session, harness, row.id)
@@ -979,7 +1003,14 @@ export class RelayCore {
     if (!transient && fields.cwd !== null) this.sql.all(`UPDATE grants SET spent_cwd = ? WHERE used_by = ?`, fields.cwd, row.id)
     if (!(transient && joined)) {
       const sub = scope.subagent ? { subagent: scope.subagent.type ?? "agent", parent: this.addressOf(scope.subagent.root) } : {}
-      this.audit("claim", row.id, null, { handle: row.handle, harness, ...(joined ? { joined: true } : {}), ...(transient ? { transient: true } : {}), ...sub })
+      this.audit("claim", row.id, null, {
+        handle: row.handle,
+        harness,
+        ...(joined ? { joined: true } : {}),
+        ...(resumed ? { resumed: true } : {}),
+        ...(transient ? { transient: true } : {}),
+        ...sub,
+      })
     }
     if (fresh) this.reset(row, scope, fresh, moved, now)
     if (created || fresh === "grant") this.place(this.byId(row.id)!, scope, now)
@@ -988,6 +1019,35 @@ export class RelayCore {
     return { endpoint: this.view(this.byId(row.id)!), ...(token ? { token } : {}), ...(created ? { created: true as const } : {}) }
   }
 
+  /**
+   * the offline local row a claim of harness session `harnessSession` from a new harness process takes back, as a restart of that session:
+   * of a fitting harness, no subagent's, and restarted where it sits or redeemed with its grant. A claim with a grant that row did not spend
+   * is a new spawn and takes none. A named row first, then the latest seen
+   */
+  private resumable(
+    harness: string,
+    harnessSession: string,
+    scope: ClaimScope,
+    fields: { cwd: string | null; process: string | null },
+    now: number,
+  ): EndpointRow | undefined {
+    const rows = this.sql.all<EndpointRow>(
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND harness_session = ? AND connections = 0 AND (session IS NULL OR substr(session, 1, 4) != 'sub:')
+       AND substr(handle, 1, ${GONE_PREFIX.length}) != '${GONE_PREFIX}' ORDER BY named IS NULL, COALESCE(last_seen, created_at) DESC`,
+      harnessSession,
+    )
+    const parent = rows.length ? this.placement(scope, now).parent : null
+    const spender = scope.grant === null ? null : (this.spentGrant(scope)?.used_by ?? "")
+    return rows.find(
+      (row) =>
+        (spender === null || spender === row.id) &&
+        this.localRow(row) &&
+        harnessFits(row.harness, harness) &&
+        presenceOf(row, now) === "offline" &&
+        (this.restarts(row, parent, fields.process) || this.redeems(row, scope, { harness, ...fields })),
+    )
+  }
+
   /** a session's hook endpoint left for `to`: its unread mail moves there and it lets go of the session; the moved seqs and its stop budget */
   private leaveHooks(hooks: EndpointRow, to: string): { moved: number[]; stopBlocks: number } {
     const moved = this.sql
@@ -1592,30 +1652,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) }
     })
   }
 
@@ -1676,7 +1766,7 @@ export class RelayCore {
    * `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 }): void {
+  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
@@ -1684,7 +1774,7 @@ export class RelayCore {
       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, 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) })
       return
     }
     if (parent.kind !== "agent") throw new RelayError("invalid_params", "the parent is an agent endpoint")
@@ -1713,7 +1803,7 @@ 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 */
@@ -1743,9 +1833,14 @@ export class RelayCore {
 
   /**
    * 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
+   * 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,
+   * except an offline one {@link renameRow} takes over
    */
-  rename(actor: ScopeActor, params: { endpoint?: unknown; handle: unknown }): { endpoint: EndpointView; from: string; session: string | null } {
+  rename(
+    actor: ScopeActor,
+    params: { endpoint?: unknown; handle: unknown; take_over?: unknown },
+  ): { endpoint: EndpointView; from: string; session: string | null; retired?: string } {
+    if (params.take_over !== undefined && typeof params.take_over !== "boolean") throw new RelayError("invalid_params", "take_over is true or false")
     return this.scopeTx(() => {
       const me = this.actorRow(actor)
       if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint)
@@ -1753,13 +1848,16 @@ 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 renames only itself")
       if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can be renamed")
-      this.renameRow(target, params.handle, actor.kind === "human")
-      return { endpoint: this.whoami(target.id), from: target.handle, session: target.session }
+      const retired = this.renameRow(target, params.handle, actor.kind === "human", params.take_over === true)
+      return { endpoint: this.whoami(target.id), from: target.handle, session: target.session, ...(retired ? { retired } : {}) }
     })
   }
 
-  /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
-  private renameRow(row: EndpointRow, value: unknown, byHuman: boolean): void {
+  /**
+   * the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it. A local offline agent holding the handle
+   * is taken over when it held the same harness session, or with `takeOver` by the human at a terminal: the id of the row retired
+   */
+  private renameRow(row: EndpointRow, value: unknown, byHuman: boolean, takeOver = false): string | undefined {
     const handle = typeof value === "string" ? value.trim().replace(/^me\//, "") : ""
     if (!validHandle(handle)) throw new RelayError("invalid_params", `handle ${JSON.stringify(handle)} is not valid: lowercase letters, digits, . _ -`)
     if (findSecret(handle)) throw new RelayError("secret_refused", "the handle looks like it carries a credential")
@@ -1772,14 +1870,23 @@ export class RelayCore {
       throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; its name is set by the spawner`)
     }
     const held = this.byHandle(handle)
+    let retired: string | undefined
     if (held) {
-      const how = held.kind !== "agent" ? "reserved" : presenceOf(held, this.now()) === "offline" ? "held by an offline endpoint" : "held by a live endpoint"
-      throw new RelayError("invalid_params", `${handle} is ${how}: pick another name`)
+      const offline = held.kind === "agent" && held.connections === 0 && presenceOf(held, this.now()) === "offline" && this.localRow(held)
+      const same = held.harness_session !== null && held.harness_session === row.harness_session
+      if (takeOver && !byHuman && !same) throw new RelayError("scope_refused", "only the human at a terminal takes over another endpoint")
+      if (takeOver && offline && !same && !harnessFits(held.harness, row.harness ?? "cli"))
+        throw new RelayError("invalid_params", `${handle} is a ${held.harness} endpoint: only an endpoint of the same harness is taken over`)
+      if (!offline || held.session?.startsWith("sub:") || !(same || (takeOver && harnessFits(held.harness, row.harness ?? "cli")))) {
+        const how = held.kind !== "agent" ? "reserved" : presenceOf(held, this.now()) === "offline" ? "held by an offline endpoint" : "held by a live endpoint"
+        throw new RelayError("invalid_params", `${handle} is ${how}: pick another name${offline ? ", or take it over with --take-over from a terminal" : ""}`)
+      }
+      retired = this.takeOver(row, held, same ? "session" : "human")
     }
     const from = row.handle
     this.sql.all(`UPDATE endpoints SET handle = ?, named = ? WHERE id = ?`, handle, this.now(), row.id)
     this.sql.all(`UPDATE grants SET name = ? WHERE used_by = ? AND name = ?`, handle, row.id, from)
-    for (const prefix of row.parent_ep === null ? ["ep:", "fleet:"] : ["ep:"]) {
+    for (const prefix of this.byId(row.id)!.parent_ep === null ? ["ep:", "fleet:"] : ["ep:"]) {
       const [a, b] = [JSON.stringify(`${prefix}${from}`), JSON.stringify(`${prefix}${handle}`)]
       for (const [table, column] of [
         ["endpoints", "rules"],
@@ -1791,6 +1898,52 @@ export class RelayCore {
     }
     this.renamedHandle(from, handle)
     this.audit("rename", row.id, null, { from, to: handle })
+    return retired
+  }
+
+  /**
+   * `row` takes over `held`, an offline local agent, and retires it: `held`'s subtree, unread mail, grants, groups and harness session move to
+   * `row`, which takes `held`'s hand-made link when it is an unlinked root itself. Its handle is then free for `row`
+   */
+  private takeOver(row: EndpointRow, held: EndpointRow, by: "human" | "session"): string {
+    if (this.ancestorsOf(row).includes(held.id))
+      throw new RelayError("scope_refused", `${this.address(row)} sits under ${this.address(held)}: it cannot take over its own ancestor`)
+    if (row.parent_ep === null && row.parent_addr === null && held.linked !== null && held.parent_addr !== null)
+      this.sql.all(`UPDATE endpoints SET parent_addr = ?, linked = ? WHERE id = ?`, held.parent_addr, held.linked, row.id)
+    else if (row.parent_ep === null && row.parent_addr === null && held.linked !== null && held.parent_ep !== null) {
+      const parent = this.byId(held.parent_ep)
+      if (parent) this.link(row, parent, { by: this.address(row), auth: by })
+    }
+    const place = this.byId(row.id)!
+    const shift = (place.depth ?? 0) - (held.depth ?? 0)
+    const below = `WITH RECURSIVE below(id) AS (SELECT id FROM endpoints WHERE parent_ep = ? UNION SELECT e.id FROM endpoints e JOIN below b ON e.parent_ep = b.id)`
+    const deepest = one<{ d: number | null }>(this.sql, `${below} SELECT MAX(depth) AS d FROM endpoints WHERE id IN (SELECT id FROM below)`, held.id)?.d
+    if (deepest != null && deepest + shift > LIMITS.depthMax)
+      throw new RelayError("scope_refused", `${this.address(held)}'s children would sit deeper than ${LIMITS.depthMax} under ${this.address(place)}`)
+    this.sql.all(`${below} UPDATE endpoints SET tree = ?, depth = depth + ? WHERE id IN (SELECT id FROM below)`, held.id, place.tree ?? place.id, shift)
+    const children = this.sql.all<{ id: string }>(`UPDATE endpoints SET parent_ep = ? WHERE parent_ep = ? RETURNING id`, row.id, held.id).length
+    this.sql.all(`UPDATE deliveries SET endpoint = ? WHERE endpoint = ? AND acked_at IS NULL`, row.id, held.id)
+    this.sql.all(`UPDATE grants SET issuer = ? WHERE issuer = ?`, row.id, held.id)
+    this.sql.all(`UPDATE grants SET under = ? WHERE under = ?`, row.id, held.id)
+    this.sql.all(`UPDATE groups SET owner = ? WHERE owner = ?`, row.id, held.id)
+    this.sql.all(
+      `INSERT OR IGNORE INTO group_members (name, endpoint, added_by, at) SELECT name, ?, added_by, at FROM group_members WHERE endpoint = ?`,
+      row.id,
+      held.id,
+    )
+    this.sql.all(`DELETE FROM group_members WHERE endpoint = ?`, held.id)
+    this.sql.all(
+      `UPDATE endpoints SET harness_session = ?, harness_transcript = ? WHERE id = ? AND harness_session IS NULL`,
+      held.harness_session,
+      held.harness_transcript,
+      row.id,
+    )
+    this.sql.all(`UPDATE endpoints SET handle = ?, session = NULL, token_hash = NULL WHERE id = ?`, `${GONE_PREFIX}${held.id}`, held.id)
+    this.dropPeek(held.id)
+    this.scopeMemo?.ancestors.clear()
+    this.scopeMemo?.limited.clear()
+    this.audit("take_over", row.id, null, { from: row.handle, to: held.handle, retired: held.id, children, by })
+    return held.id
   }
 
   /** a local agent's handle moved from `from` to `to`: a subclass updates what names it on another machine's rows */
@@ -1829,7 +1982,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
@@ -1897,6 +2051,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([
@@ -1910,6 +2075,7 @@ export class RelayCore {
         mime,
         ttl,
         params.require_reply === true,
+        ...(origin.link ? [origin.link] : []),
       ]),
     )
     if (clientId) {
@@ -2079,8 +2245,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,
@@ -2096,6 +2262,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"] = []
@@ -2137,6 +2304,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
     })
@@ -5249,6 +5423,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"]
@@ -170,6 +170,8 @@ export interface Claim {
   session?: string
   /** the harness process the claim comes from, `pid:<pid>:<start time>`: a shim restarted in that process may rejoin its endpoint */
   process?: string
+  /** the harness's own stable session id (Claude Code's): a resumed session in a new harness process takes back the offline endpoint of that id */
+  harness_session?: string
   /** process keys of the claimant's harness process and its ancestors, nearest first: the nearest endpoint holding one places the claim under it */
   lineage?: string[]
   /** a `krt_` grant from `spawn-env`: places the claim at or below its lineage placement, with the grant's caps and groups */
@@ -358,6 +360,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 +477,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 +504,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