@scp-dev/core 0.1.0 → 0.1.2

package/dist/index.js

@@ -132,10 +132,18 @@ var LIMITS = {
   pushes: 20,
   /** how long a live worker's next message waits after a push showed one of its own */
   pushGapS: 30,
+  /** with other workers still running, how long a stop's push waits for one more worker result before it goes */
+  pushQuietS: 3,
+  /** the longest a stop's push gathers worker results, from the first it has to show */
+  pushGraceS: 6,
   stopBlocks: 3,
   /** the stops a session's late parent directives may hold */
   directiveHolds: 5,
   injectHoldS: 10,
+  /** how long inbox still lists a message a background hook showed, whose text the harness may hand the agent only after its next tool call */
+  deferredShowS: 600,
+  /** a deferred showing older than this settles at the session's next tool event or prompt: the harness has handed it over by then */
+  deferredSettleMs: 2e3,
   listOfflineWithinS: 86400,
   handleBoundS: 30 * 86400,
   idempotencyS: 86400,
@@ -156,7 +164,9 @@ var LIMITS = {
   groupPerMinute: 60,
   grantTtlS: 7 * 86400,
   groupIdleS: 86400,
-  policyLoadsKept: 8
+  policyLoadsKept: 8,
+  /** the prompts between two refreshes of a title a hook inferred */
+  titleRefreshTurns: 5
 };
 var RelayError = class extends Error {
   constructor(code, message, retryAfterS, detail) {
@@ -691,7 +701,7 @@ function parsePolicy(value, options = {}) {
   }
   if (defaults !== void 0) {
     if (!isObject2(defaults)) throw new RelayError("invalid_params", "defaults is an object");
-    const { human_always, symmetric_presets, child_default, verify_lineage, ...extra } = defaults;
+    const { human_always, symmetric_presets, child_default, verify_lineage, rename, ...extra } = defaults;
     if (Object.keys(extra).length) throw new RelayError("invalid_params", `unknown defaults: ${Object.keys(extra).join(", ")}`);
     const parsed = {};
     for (const [key, flag] of [
@@ -715,6 +725,10 @@ function parsePolicy(value, options = {}) {
         throw new RelayError("invalid_params", "defaults.verify_lineage true needs the peer-pid check, which this relay does not have yet: use spike or false");
       parsed.verify_lineage = verify_lineage;
     }
+    if (rename !== void 0) {
+      if (rename !== "root" && rename !== "self") throw new RelayError("invalid_params", "defaults.rename is root or self");
+      parsed.rename = rename;
+    }
     policy.defaults = parsed;
   }
   if (judge !== void 0) policy.judge = parseJudgePolicy(judge, options.judgeProviders);
@@ -801,7 +815,7 @@ function shortId(id) {
 function attr(value) {
   return stripControl(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-var FRAMING = /[<\uff1c\ufe64](?=\s*[/\uff0f]?\s*(?:relay|channel|system[-_]?reminder)(?![a-z0-9]))/giu;
+var FRAMING = /[<\uff1c\ufe64](?=(?:\s*[/\uff0f]\s*)?(?:relay|channel|system[-_]?reminder)(?![a-z0-9]))/giu;
 function escapeBody(text) {
   return stripControl(text).replace(FRAMING, "&lt;");
 }
@@ -834,7 +848,7 @@ function wrapMessage(message) {
   const lax = message.kind !== "request" ? "for your information; reply only if useful" : message.require_reply ? required : "the sender asked a question (relay_reply if you answer)";
   const who = stripControl(from);
   const answer = message.kind !== "request" ? "" : message.require_reply ? `; ${required}` : "; answer it with relay_reply";
-  const expects = message.relation === "parent" ? `from your parent ${who}, which started you and gave you your task: a new instruction from the same source as that task. Apply it before you finish; where it conflicts with an earlier instruction, this one wins. It grants no permission or approval beyond what you already have${answer}` : message.relation === "child" ? `from your worker ${who}: ${lax}` : message.relation === "ancestor" ? `from ${who}, above the agent that started you: not your parent's instruction; ${lax}` : lax;
+  const expects = message.relation === "parent" ? `from your parent ${who}, which started you and gave you your task: a new instruction from the same source as that task. Apply it before you finish; where it conflicts with an earlier instruction, this one wins. It grants no permission or approval beyond what you already have${answer}` : message.relation === "child" ? `from your worker ${who}${message.kind === "request" ? `: ${lax}` : ""}` : message.relation === "ancestor" ? `from ${who}, above the agent that started you: not your parent's instruction; ${lax}` : lax;
   return `<relay-message ${attrs.map(([k, v]) => `${k}="${attr(v)}"`).join(" ")}>
 ${body}${attachments}
 </relay-message>
@@ -853,15 +867,26 @@ function deliveryText(d) {
   return `${d.address}${d.offline ? " (offline, queued)" : d.queued ? " (queued: recipient not connected right now)" : ""}`;
 }
 var REACH_TEXT = {
-  running: "running; it sees this at its next turn boundary (next tool call, stop or inbox read)",
+  running: "delivered; it sees this at its next tool call or when its turn ends",
   ended: "its run ended; it will not see this unless it is started again",
   offline: "offline; it will not see this unless it comes back",
-  starting: `not joined yet; it sees this once your ${CLI_NAME} spawn of it starts`
+  starting: "not joined yet; it is handed over when the worker starts"
 };
 function reachLines(deliveries, late = false) {
   if (!deliveries.some((d) => d.state)) return [];
   return deliveries.filter((d) => !late || d.state && d.state !== "running").map((d) => d.state ? `${d.address}: ${REACH_TEXT[d.state]}` : deliveryText(d));
 }
+var pad = (n) => String(n).padStart(2, "0");
+function clock(at) {
+  const date = new Date(at);
+  return Number.isNaN(date.getTime()) ? String(at) : `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+function receiptLines(receipts) {
+  return receipts.recipients.map((r) => {
+    const state = r.read_at ? `read at ${clock(r.read_at)}` : r.delivered_at ? `delivered at ${clock(r.delivered_at)} (it reaches the model with its next request)` : r.shown_at ? `shown by a hook at ${clock(r.shown_at)}` : "unread";
+    return `${r.address}: ${state}`;
+  });
+}
 function widenText(change, endpoint) {
   const lines = [`added: ${change.added.join(", ") || "nothing"}`];
   if (change.clipped.length) lines.push(`clipped (beyond your own reach): ${change.clipped.join(", ")}`);
@@ -1015,9 +1040,11 @@ function keepLast(text, bytes, dropped = false) {
   if (!text || !dropped && encoded.length <= bytes) return text;
   const mark = bytes > HANDBACK_CUT.length + 1 ? `${HANDBACK_CUT}
 ` : "";
-  let start = Math.max(0, encoded.length - (bytes - mark.length));
+  const reach = bytes - mark.length;
+  let start = Math.max(0, encoded.length - reach);
   const nl = start > 0 && encoded[start - 1] !== 10 ? encoded.indexOf(10, start) : -1;
-  if (nl !== -1 && nl + 1 < encoded.length) start = nl + 1;
+  const long = nl !== -1 && nl - (encoded.lastIndexOf(10, start - 1) + 1) > reach && encoded.length - (nl + 1) < reach / 2;
+  if (nl !== -1 && nl + 1 < encoded.length && !long) start = nl + 1;
   while (start > 0 && start < encoded.length - 1 && encoded[start] === 10) start++;
   while (start < encoded.length && (encoded[start] & 192) === 128) start++;
   return `${mark}${new TextDecoder().decode(encoded.subarray(start))}`;
@@ -1044,6 +1071,7 @@ function utf8Bytes(text) {
 
 // src/core.ts
 var HUMAN_HANDLE = "_human";
+var TITLE_CHARS = 64;
 var SYSTEM_HANDLE = "_relay";
 var GONE_PREFIX = "_gone_";
 var MIGRATION = [
@@ -1100,7 +1128,9 @@ var MIGRATION = [
     offered_until INTEGER,
     offered_hold TEXT,
     injected_at INTEGER,
-    nudged_at INTEGER
+    nudged_at INTEGER,
+    deferred_at INTEGER,
+    deferred_ack INTEGER
   )`,
   `CREATE INDEX IF NOT EXISTS deliveries_inbox ON deliveries (endpoint, acked_at, seq)`,
   `CREATE INDEX IF NOT EXISTS deliveries_message ON deliveries (message_id)`,
@@ -1224,6 +1254,8 @@ var RelayCore = class {
     this.capEverySender = options.capEverySender === true;
     this.alive = options.alive ?? (() => true);
     this.hostMachine = options.machine ?? options.hostname ?? null;
+    this.namedMachine = options.machine ?? null;
+    this.hostname = options.hostname ?? null;
   }
   sql;
   user;
@@ -1233,6 +1265,8 @@ var RelayCore = class {
   capEverySender;
   alive;
   hostMachine;
+  namedMachine;
+  hostname;
   policy = null;
   /** the identity each policy `group:<name>` naming no policy group bound to when the policy's text first loaded: that group's then, or `none` */
   policyBinds = /* @__PURE__ */ new Map();
@@ -1240,6 +1274,11 @@ var RelayCore = class {
   /** while a scope world derives a node: what it already derived of ancestor lists and limits */
   scopeMemo = null;
   deferred = /* @__PURE__ */ new WeakMap();
+  /** a `machine` label naming this host by its hostname, as clients default it, names it by its machine name when one is set */
+  machineLabel(labels) {
+    if (this.namedMachine !== null && labels.machine !== void 0 && labels.machine === this.hostname) labels.machine = this.namedMachine;
+    return labels;
+  }
   migrate() {
     for (const statement of MIGRATION) this.sql.all(statement);
     const columns = this.sql.all(`PRAGMA table_info(idempotency)`).map((c) => c.name);
@@ -1272,7 +1311,11 @@ var RelayCore = class {
       ["introduced", "INTEGER"],
       ["directive_holds", "INTEGER"],
       ["harness_session", "TEXT"],
-      ["harness_transcript", "TEXT"]
+      ["harness_transcript", "TEXT"],
+      ["title_auto", "TEXT"],
+      ["title_turn", "INTEGER"],
+      ["tldr_turn", "INTEGER"],
+      ["named", "INTEGER"]
     ]) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`);
     }
@@ -1301,6 +1344,8 @@ var RelayCore = class {
     if (!deliveryColumns.includes("injected_at")) this.sql.all(`ALTER TABLE deliveries ADD COLUMN injected_at INTEGER`);
     if (!deliveryColumns.includes("nudged_at")) this.sql.all(`ALTER TABLE deliveries ADD COLUMN nudged_at INTEGER`);
     if (!deliveryColumns.includes("restated_at")) this.sql.all(`ALTER TABLE deliveries ADD COLUMN restated_at INTEGER`);
+    if (!deliveryColumns.includes("deferred_at")) this.sql.all(`ALTER TABLE deliveries ADD COLUMN deferred_at INTEGER`);
+    if (!deliveryColumns.includes("deferred_ack")) this.sql.all(`ALTER TABLE deliveries ADD COLUMN deferred_ack INTEGER`);
     const activityColumns = this.sql.all(`PRAGMA table_info(activity)`).map((c) => c.name);
     if (!activityColumns.includes("agent")) this.sql.all(`ALTER TABLE activity ADD COLUMN agent TEXT`);
     if (!this.byHandle(SYSTEM_HANDLE)) {
@@ -1427,7 +1472,7 @@ var RelayCore = class {
       model: cleanText(claim.model, "model", 128),
       cwd: cleanText(claim.cwd, "cwd", 1024),
       parent: cleanText(claim.parent, "parent", 128),
-      labels: JSON.stringify(cleanLabels(claim.labels)),
+      labels: JSON.stringify(this.machineLabel(cleanLabels(claim.labels))),
       session: cleanText(claim.session, "session", 128),
       process: cleanText(claim.process, "process", 128)
     };
@@ -1526,6 +1571,7 @@ var RelayCore = class {
   }
   claimRow(wanted, harness, fields, transient, scope = { handle: wanted, lineage: [], grant: null, rules: {}, groups: [], cwd: fields.cwd }) {
     const now = this.now();
+    this.endExited(now);
     const bare = transient && fields.session !== null && BARE_PID_KEY.test(fields.session);
     let row = fields.session ? one(
       this.sql,
@@ -1549,7 +1595,7 @@ var RelayCore = class {
     } else if (row && !transient && !sameProcess(row, fields.process)) {
       row = void 0;
       session = null;
-    } else if (row && !transient && row.token_hash === null && row.handle !== wanted && !row.handle.startsWith(`${wanted.slice(0, 58)}-`)) {
+    } else if (row && !transient && row.token_hash === null && row.named === null && row.handle !== wanted && !row.handle.startsWith(`${wanted.slice(0, 58)}-`)) {
       const hooks = row;
       let settled = false;
       for (let n = 1; n < (scope.exact ? 2 : 1e3) && !settled; n++) {
@@ -1987,6 +2033,7 @@ var RelayCore = class {
    */
   list(filters = {}) {
     const now = this.now();
+    this.endExited(now);
     this.settleOffline(now);
     const cutoff = now - LIMITS.listOfflineWithinS * 1e3;
     const viewer = filters.viewer === void 0 ? void 0 : this.mustEndpoint(filters.viewer);
@@ -2040,10 +2087,12 @@ var RelayCore = class {
     const text = oneLine(note, "note", LIMITS.noteChars);
     if (text && findSecret(text)) throw this.refuse(endpoint, "secret_refused", "the status note looks like it carries a credential");
     this.sql.all(
-      `UPDATE endpoints SET status_state = COALESCE(?, status_state, 'working'), status_note = COALESCE(?, status_note, ''), last_seen = ? WHERE id = ?`,
+      `UPDATE endpoints SET status_state = COALESCE(?, status_state, 'working'), status_note = COALESCE(?, status_note, ''), last_seen = ?,
+       tldr_turn = CASE WHEN ? THEN COALESCE(prompts, 0) ELSE tldr_turn END WHERE id = ?`,
       state ?? null,
       text,
       this.now(),
+      text === null ? 0 : 1,
       endpoint
     );
   }
@@ -2053,10 +2102,117 @@ var RelayCore = class {
     if (row.kind !== "agent") throw new RelayError("invalid_params", "only an agent endpoint has a title");
     const title = oneLine(value, "title", 64) || null;
     if (title && findSecret(title)) throw this.refuse(endpoint, "secret_refused", "the title looks like it carries a credential");
-    this.sql.all(`UPDATE endpoints SET title = ? WHERE id = ?`, title, endpoint);
+    this.sql.all(`UPDATE endpoints SET title = ?, title_auto = NULL, title_turn = NULL WHERE id = ?`, title, endpoint);
     this.audit("title", endpoint, null, { title });
     return this.whoami(endpoint);
   }
+  /**
+   * a hook's guess at the session's title, from the harness's own summary or the first prompt's first line; whether it changed the title.
+   * Never over a title set explicitly; the first prompt fills only an empty title, and a summary replaces an inferred one at most every
+   * ${LIMITS.titleRefreshTurns} prompts, or at once over the first prompt's
+   */
+  inferTitle(endpoint, params, options = {}) {
+    if (params.from !== "summary" && params.from !== "prompt") throw new RelayError("invalid_params", "from is summary or prompt");
+    if (typeof params.text !== "string") throw new RelayError("invalid_params", "text must be a string");
+    const row = this.mustEndpoint(endpoint);
+    if (row.kind !== "agent" || !this.holds(row, options)) return false;
+    const title = stripControl(redactSecrets(params.text.slice(0, 4096).replace(/\s+/g, " ").trim())).slice(0, TITLE_CHARS).trim();
+    if (!title || findSecret(title) || title === row.title) return false;
+    if (row.title !== null && row.title !== row.title_auto) return false;
+    const turn = row.prompts ?? 0;
+    if (params.from === "prompt" && row.title !== null) return false;
+    if (params.from === "summary" && row.title !== null && row.title_turn !== null && turn - row.title_turn < LIMITS.titleRefreshTurns) return false;
+    this.sql.all(`UPDATE endpoints SET title = ?, title_auto = ?, title_turn = ? WHERE id = ?`, title, title, params.from === "summary" ? turn : null, endpoint);
+    return true;
+  }
+  /**
+   * a session joins on demand: its hook claim registers or takes back its endpoint, marked seen now even right after a leave, and `handle`,
+   * when given, renames it in place ({@link rename}'s rules). Nothing is kept when the rename is refused
+   */
+  joinSession(claim, handle) {
+    return this.scopeTx(() => {
+      const { endpoint } = this.claim(claim, { transient: true });
+      const row = this.mustEndpoint(endpoint.id);
+      if (handle !== void 0 && handle !== null && handle !== "") this.renameRow(row, handle, false);
+      this.sql.all(`UPDATE endpoints SET hook_seen = ?, hook_ended = NULL WHERE id = ?`, this.now(), row.id);
+      this.audit("join", row.id, null, { handle: this.byId(row.id).handle });
+      return this.whoami(row.id);
+    });
+  }
+  /**
+   * 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
+   */
+  rename(actor, params) {
+    return this.scopeTx(() => {
+      const me = this.actorRow(actor);
+      if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
+      else if (actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself renames it: run this from the session's own shell");
+      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 };
+    });
+  }
+  /** the endpoint's handle set to `value`, with the stored `ep:` and `fleet:` selectors that named it */
+  renameRow(row, value, byHuman) {
+    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");
+    if (handle === row.handle) {
+      this.sql.all(`UPDATE endpoints SET named = COALESCE(named, ?) WHERE id = ?`, this.now(), row.id);
+      return;
+    }
+    if (!byHuman && row.parent_ep !== null && this.policy?.defaults?.rename !== "self") {
+      const parent = this.byId(row.parent_ep);
+      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);
+    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 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:"]) {
+      const [a, b] = [JSON.stringify(`${prefix}${from}`), JSON.stringify(`${prefix}${handle}`)];
+      for (const [table, column] of [
+        ["endpoints", "rules"],
+        ["endpoints", "caps"],
+        ["groups", "rules"],
+        ["grants", "caps"]
+      ])
+        this.sql.all(`UPDATE ${table} SET ${column} = REPLACE(${column}, ?, ?) WHERE instr(${column}, ?) > 0`, a, b, a);
+    }
+    this.audit("rename", row.id, null, { from, to: handle });
+  }
+  /**
+   * 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. A spawned worker stays joined while it runs
+   */
+  leaveSession(actor, params = {}) {
+    return this.scopeTx(() => {
+      const me = this.actorRow(actor);
+      if (actor.kind === "human") this.needTerminal(actor, me, params.endpoint);
+      else if (actor.auth === "lineage") throw new RelayError("scope_refused", "only the session itself leaves: run this from the session's own shell");
+      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 leaves only for itself");
+      if (target.kind !== "agent" || !this.localRow(target)) throw new RelayError("invalid_params", "only a local agent endpoint can leave");
+      if (target.parent_ep !== null) {
+        const parent = this.byId(target.parent_ep);
+        throw new RelayError("scope_refused", `spawned by ${parent ? this.address(parent) : "another agent"}; a spawned worker stays joined while it runs`);
+      }
+      this.sql.all(`UPDATE endpoints SET session = NULL, token_hash = NULL, hook_seen = NULL, hook_ended = ? WHERE id = ?`, this.now(), target.id);
+      this.audit("leave", target.id, null, { handle: target.handle });
+      return { endpoint: this.whoami(target.id), session: target.session };
+    });
+  }
+  /** the harness session key an endpoint holds, if any */
+  sessionOf(endpoint) {
+    return this.byId(endpoint)?.session ?? null;
+  }
   // messages
   /**
    * `origin.tty` is recorded on messages the human inbox sends: whether its client said a terminal was attached. `origin.unverified`: the human
@@ -2114,6 +2270,13 @@ var RelayCore = class {
       resolved.push(row);
     }
     const recipients = [...new Map(resolved.map((row) => [row.id, row])).values()];
+    if (params.live !== void 0 && typeof params.live !== "boolean") throw new RelayError("invalid_params", "live must be true or false");
+    const dark = recipients.filter(
+      (r) => r.kind === "agent" && presenceOf(r, now) === "offline" && (now - Math.max(r.last_seen ?? 0, r.hook_seen ?? 0) >= ASK_ENDED_GRACE_MS || r.session === null && r.token_hash === null && r.hook_ended !== null) && !this.unjoinedSpawn(sender, r.handle, now)
+    );
+    if (params.live === true && dark.length)
+      throw new RelayError("not_live", `no live session holds ${dark.map((r) => this.address(r)).join(", ")}: nothing was queued`);
+    const warnings = dark.map((r) => `queued: no live session holds ${this.address(r)}`);
     const pending = [...unjoined.values()].map((grant) => ({ key: pendingKey(grant.token_hash), address: `${this.user}/${grant.name}` }));
     const reached = recipients.length + pending.length;
     if (reached > LIMITS.fanOutTotal) throw new RelayError("too_large", `the send reaches ${reached} endpoints, more than ${LIMITS.fanOutTotal}`);
@@ -2331,7 +2494,7 @@ var RelayCore = class {
         deliveries.push({ endpoint: key, address, seq, offline: false, queued: true, last_seen: null, state: "starting" });
       }
       for (const name of fanOut) this.sql.all(`INSERT INTO tree_events (tree, at) VALUES (?, ?)`, `group:${name}`, now);
-      const sent = { id, thread, hop, deliveries };
+      const sent = { id, thread, hop, deliveries, ...warnings.length ? { warnings } : {} };
       if (clientId) {
         this.sql.all(
           `INSERT OR REPLACE INTO idempotency (from_ep, client_id, payload_hash, result, created_at) VALUES (?, ?, ?, ?, ?)`,
@@ -2406,21 +2569,29 @@ var RelayCore = class {
       });
     }
   }
-  /** the oldest unacked deliveries after the cursor; reading counts as receiving for the causal hop */
+  /**
+   * the oldest unacked deliveries after the cursor, and those a background hook showed in the last ${LIMITS.deferredShowS} s whose showing has
+   * not settled ({@link injected}), with `shown_at`: the harness may hand the agent that hook's text only after this call; reading counts as
+   * receiving for the causal hop
+   */
   inbox(endpoint, options = {}) {
     const now = this.now();
     const limit = Math.min(Math.max(1, Math.floor(options.limit ?? LIMITS.inboxPage)), LIMITS.inboxPage);
     const rows = this.sql.all(
-      `SELECT m.*, d.seq AS seq FROM deliveries d JOIN messages m ON m.id = d.message_id
-       WHERE d.endpoint = ? AND d.acked_at IS NULL AND d.expires_at > ? AND d.seq > ?
+      `SELECT m.*, d.seq AS seq, d.deferred_at AS deferred_at, d.acked_at AS acked_at FROM deliveries d JOIN messages m ON m.id = d.message_id
+       WHERE d.endpoint = ? AND (d.acked_at IS NULL OR d.deferred_at > ?) AND d.expires_at > ? AND d.seq > ?
        ORDER BY d.seq LIMIT ?`,
       endpoint,
+      now - LIMITS.deferredShowS * 1e3,
       now,
       Math.max(0, Math.floor(options.after ?? 0)),
       limit
     );
     this.received(endpoint, rows, now);
-    return rows.map((row) => this.envelope(row, row.seq));
+    return rows.map((row) => {
+      const envelope = this.envelope(row, row.seq);
+      return row.acked_at !== null && row.deferred_at !== null ? { ...envelope, shown_at: new Date(row.deferred_at).toISOString() } : envelope;
+    });
   }
   /**
    * A channel push's page: the oldest unacked deliveries no hook showed or holds, held from the hooks for ${LIMITS.injectHoldS} s under `hold`
@@ -2461,6 +2632,7 @@ var RelayCore = class {
    * `directive_seqs`. Any call says `brief` once the session was shown the full preamble ({@link briefed}), and one that is no stop names in
    * `intro` the spawner of an endpoint a `swarm spawn` grant placed, with the grant's steer key in `intro_key`, until a hook showed it
    * ({@link introduced}). A hook of another process than the one holding the endpoint (a child that inherited the session key) gets nothing.
+   * A wake also offers live workers' messages.
    */
   inject(endpoint, options = {}) {
     const now = this.now();
@@ -2528,7 +2700,7 @@ var RelayCore = class {
       now,
       LIMITS.inboxPage
     );
-    const { shown, offered } = this.budget(rows, LIMITS.injectBytes, () => this.pushable(me, now));
+    const { shown, offered } = this.budget(rows, LIMITS.injectBytes, options.wake ? void 0 : () => this.pushable(me, now));
     const hold = this.hold(offered, now);
     this.received(endpoint, shown, now);
     return { messages: shown.map((row) => this.envelope(row, row.seq)), offered, hold, more: waiting - shown.length, unread, block: false, ...brief, ...intro };
@@ -2602,13 +2774,15 @@ var RelayCore = class {
    * messages no hook has shown or holds follow theirs ({@link pushOthers}), `others_shown` of them, held with them; `others` counts the other
    * unread ones left. A live worker's messages wait ${LIMITS.pushGapS} s after a push showed one of its own ({@link pushed}), and with no
    * push left since the last prompt nothing is shown. `prompted` says a prompt came since inject handed out the `prompts` mark. A hook of
-   * another process than the one holding the endpoint gets nothing.
+   * another process than the one holding the endpoint gets nothing. `peek`: the same answer, nothing held (`hold` null) or marked received.
    */
   stopWait(endpoint, options = {}) {
     const now = this.now();
     const me = this.mustEndpoint(endpoint);
     if (!this.holds(me, options)) return { messages: [], offered: [], hold: null, more: 0, workers: [], starting: 0, others: 0, pushes_left: 0 };
     const { workers, starting, paced } = this.liveWorkers(me, now);
+    const live = this.liveWorkers(me, now, true);
+    const background = [...live.workers.map((row) => this.address(row)), ...live.unjoined.filter(Boolean).map((name) => `me/${name}`)];
     const left = this.pushesLeft(me);
     const { where, params } = this.workerMessages(me, now, true, paced);
     const rows = left ? this.sql.all(`SELECT m.*, d.seq AS seq ${where} ORDER BY d.seq LIMIT ?`, ...params, LIMITS.inboxPage) : [];
@@ -2622,8 +2796,8 @@ var RelayCore = class {
     const { shown, offered } = this.budget(rows, LIMITS.pushBytes);
     const used = shown.reduce((sum, row) => sum + utf8Bytes(wrapMessage(this.envelope(row, row.seq))), 0);
     const others = rows.length ? this.pushOthers(me, now, LIMITS.pushBytes - used) : [];
-    const hold = this.hold([...offered, ...others.map((row) => row.seq)], now);
-    this.received(endpoint, [...shown, ...others], now);
+    const hold = options.peek ? null : this.hold([...offered, ...others.map((row) => row.seq)], now);
+    if (!options.peek) this.received(endpoint, [...shown, ...others], now);
     return {
       messages: [...shown, ...others].map((row) => this.envelope(row, row.seq)),
       offered: [...offered, ...others.map((row) => row.seq)],
@@ -2631,6 +2805,7 @@ var RelayCore = class {
       more: waiting - shown.length,
       workers: workers.map((row) => this.address(row)),
       starting,
+      ...background.length ? { background } : {},
       others: unread - this.workerUnread(me, now, false) - others.length,
       ...others.length ? { others_shown: others.length } : {},
       pushes_left: left,
@@ -2692,8 +2867,26 @@ var RelayCore = class {
   prompted(endpoint, options = {}) {
     if (!this.holds(this.mustEndpoint(endpoint), options)) return false;
     this.sql.all(`UPDATE endpoints SET prompts = COALESCE(prompts, 0) + 1, pushes = 0 WHERE id = ?`, endpoint);
+    this.settle(endpoint);
     return true;
   }
+  /** whether a prompt should remind the agent to refresh its status note: `every` prompts passed since the note or the last reminder; counts the reminder */
+  tldrDue(endpoint, every) {
+    if (!Number.isInteger(every) || every <= 0) return false;
+    const row = this.mustEndpoint(endpoint);
+    const turn = row.prompts ?? 0;
+    if (row.kind !== "agent" || turn - (row.tldr_turn ?? 0) < every) return false;
+    this.sql.all(`UPDATE endpoints SET tldr_turn = ? WHERE id = ?`, turn, endpoint);
+    return true;
+  }
+  /** the background hooks' showings ({@link injected}) older than ${LIMITS.deferredSettleMs} ms reached the agent: inbox no longer lists them */
+  settle(endpoint) {
+    this.sql.all(
+      `UPDATE deliveries SET deferred_at = NULL WHERE endpoint = ? AND deferred_at IS NOT NULL AND deferred_at <= ?`,
+      endpoint,
+      this.now() - LIMITS.deferredSettleMs
+    );
+  }
   /**
    * The endpoint's live spawned workers: its unrevoked spawn grants (minted by `swarm spawn` without --no-push, never by spawn-env) from its
    * current spawn that are either unspent and unexpired (`starting`: the harness has not joined yet) or spent by an endpoint whose status is not
@@ -2702,22 +2895,22 @@ var RelayCore = class {
    * spender done and revokes an unspent grant, so a worker goes when its harness exits, else when its presence lapses or its grant expires; an
    * unspent grant whose `swarm spawn` process is gone (killed before it could report the exit) is revoked here.
    */
-  liveWorkers(me, now) {
+  liveWorkers(me, now, noPush = false) {
     const grants = this.sql.all(
-      `SELECT token_hash, used_by, bound_process, pushed_at, handback FROM grants WHERE issuer = ? AND spawn = 1 AND no_push IS NULL AND revoked_at IS NULL AND created_at >= ? AND (used_by IS NOT NULL OR expires_at > ?) ORDER BY created_at`,
+      `SELECT token_hash, used_by, bound_process, pushed_at, handback, name FROM grants WHERE issuer = ? AND spawn = 1 AND no_push IS ${noPush ? "NOT NULL" : "NULL"} AND revoked_at IS NULL AND created_at >= ? AND (used_by IS NOT NULL OR expires_at > ?) ORDER BY created_at`,
       me.id,
       me.spawned_at ?? 0,
       now
     );
     const workers = /* @__PURE__ */ new Map();
     const paced = /* @__PURE__ */ new Set();
-    let starting = 0;
+    const unjoined = [];
     for (const grant of grants) {
       const pid = Number(/^pid:(\d+):/.exec(grant.bound_process ?? "")?.[1]);
       if (grant.used_by === null) {
         if (pid && !this.alive(pid))
           this.sql.all(`UPDATE grants SET revoked_at = ? WHERE token_hash = ? AND revoked_at IS NULL AND used_by IS NULL`, now, grant.token_hash);
-        else starting++;
+        else unjoined.push(grant.name ?? "");
         continue;
       }
       const row = this.byId(grant.used_by);
@@ -2725,7 +2918,7 @@ var RelayCore = class {
       workers.set(row.id, row);
       if (grant.pushed_at !== null && grant.pushed_at > now - LIMITS.pushGapS * 1e3) paced.add(row.id);
     }
-    return { workers: [...workers.values()], starting, paced: [...paced] };
+    return { workers: [...workers.values()], starting: unjoined.length, paced: [...paced], unjoined };
   }
   /**
    * the unread deliveries to `me` from the endpoints that spent its spawn grants (while each held that grant) and the relay's `worker ` handbacks,
@@ -2816,7 +3009,9 @@ var RelayCore = class {
   }
   /**
    * a hook or channel showed these deliveries, offered to it under `hold`: no hook offers them again; those of them it marked that are `read`
-   * (printed in full) and delivered to `endpoint` are acked; how many it marked
+   * (printed in full) and delivered to `endpoint` are acked, and with `deferred` (a background hook, whose text the harness hands the agent
+   * later) still listed by {@link inbox} until that settles ({@link settle}) and marked delivered rather than read ({@link receipts}) until
+   * the agent acks it itself; how many it marked
    */
   injected(seqs, hold, options = {}) {
     const list = seqList(seqs);
@@ -2833,13 +3028,17 @@ var RelayCore = class {
         hold
       ).length;
       marked += hit;
-      if (hit && read.has(seq))
+      if (hit && read.has(seq)) {
+        const deferred = options.deferred === true ? now : null;
         acked += this.sql.all(
-          `UPDATE deliveries SET acked_at = ? WHERE seq = ? AND endpoint = ? AND acked_at IS NULL RETURNING seq`,
+          `UPDATE deliveries SET acked_at = ?, deferred_at = ?, deferred_ack = ? WHERE seq = ? AND endpoint = ? AND acked_at IS NULL RETURNING seq`,
           now,
+          deferred,
+          deferred && 1,
           seq,
           options.endpoint
         ).length;
+      }
     }
     if (acked) this.audit("ack", options.endpoint, null, { count: acked, via: "inject" });
     return marked;
@@ -2900,6 +3099,46 @@ var RelayCore = class {
       throw new RelayError("invalid_params", `${id} is the seq of one message and the short id of another (${shortId(rows[0].id)}); give the full id`);
     return envelope(seq ?? rows[0]);
   }
+  /**
+   * a message `endpoint` sent, by its id, a unique suffix of at least ${MESSAGE_SUFFIX_MIN} characters such as its {@link shortId}, or `last`
+   * (the newest it sent), with when each recipient read it (acked), or when a background hook delivered it (acked by that showing, the agent
+   * gets it with its next request, `delivered_at` and no `read_at`), and when a hook or channel showed it; a recipient still waiting for a
+   * `swarm spawn` to join is named by the spawn's address. not_found when it sent no such message; invalid_params when a suffix names more
+   * than one
+   */
+  receipts(endpoint, id) {
+    if (typeof id !== "string" || !id.trim()) throw new RelayError("invalid_params", "id is a message id");
+    const sent = `SELECT id, thread FROM messages WHERE from_ep = ?`;
+    let rows = id === "last" ? this.sql.all(`${sent} ORDER BY created_at DESC, id DESC LIMIT 1`, endpoint) : this.sql.all(`${sent} AND id = ?`, endpoint, id);
+    if (!rows.length && MESSAGE_SUFFIX.test(id))
+      rows = this.sql.all(`${sent} AND substr(id, -?) = ? ORDER BY created_at DESC LIMIT 6`, endpoint, id.length, id);
+    if (rows.length > 1) {
+      const named = rows.slice(0, 5).map((row) => `${shortId(row.id)} (${row.id})`);
+      throw new RelayError(
+        "invalid_params",
+        `${id} matches more than one message you sent, newest first: ${named.join(", ")}${rows.length > 5 ? ", ..." : ""}; give more of the id`
+      );
+    }
+    const message = rows[0];
+    if (!message) throw new RelayError("not_found", `no message ${id} that you sent`);
+    const deliveries = this.sql.all(
+      `SELECT endpoint, acked_at, injected_at, deferred_ack FROM deliveries WHERE message_id = ? ORDER BY seq`,
+      message.id
+    );
+    const address = (key) => {
+      const pending = key.startsWith(pendingKey("")) ? one(this.sql, `SELECT name FROM grants WHERE token_hash = ?`, key.slice(pendingKey("").length)) : void 0;
+      return pending?.name ? `${this.user}/${pending.name}` : this.addressOf(key);
+    };
+    return {
+      id: message.id,
+      thread: message.thread,
+      recipients: deliveries.map((d) => ({
+        address: address(d.endpoint),
+        ...d.deferred_ack ? { read_at: null, delivered_at: iso(d.acked_at) } : { read_at: iso(d.acked_at) },
+        shown_at: iso(d.injected_at)
+      }))
+    };
+  }
   /**
    * another endpoint's message in a thread `endpoint` sent or got a message in, by its id or a unique suffix of at least ${MESSAGE_SUFFIX_MIN}
    * characters: enough to reply to it, never its body. Null when there is none; invalid_params when the suffix names more than one
@@ -2982,6 +3221,7 @@ var RelayCore = class {
   hasUnread(endpoint, after = 0) {
     return one(this.sql, `SELECT 1 FROM deliveries WHERE endpoint = ? AND acked_at IS NULL AND expires_at > ? AND seq > ? LIMIT 1`, endpoint, this.now(), after) !== void 0;
   }
+  /** marks these deliveries to `endpoint` read, one a background hook's showing acked ({@link injected}) read now too; how many were unread */
   ack(endpoint, seqs) {
     let acked = 0;
     for (const seq of seqList(seqs)) {
@@ -2991,6 +3231,13 @@ var RelayCore = class {
         seq,
         endpoint
       ).length;
+      this.sql.all(
+        `UPDATE deliveries SET acked_at = ?, deferred_ack = NULL WHERE seq = ? AND endpoint = ? AND deferred_ack IS NOT NULL`,
+        this.now(),
+        seq,
+        endpoint
+      );
+      this.sql.all(`UPDATE deliveries SET deferred_at = NULL WHERE seq = ? AND endpoint = ? AND deferred_at IS NOT NULL`, seq, endpoint);
     }
     if (acked) this.audit("ack", endpoint, null, { count: acked });
     return acked;
@@ -3086,6 +3333,7 @@ var RelayCore = class {
     this.sql.all(`DELETE FROM idempotency WHERE created_at <= ?`, now - LIMITS.idempotencyS * 1e3);
     this.sql.all(`DELETE FROM pair_events WHERE at <= ?`, now - 3600 * 1e3);
     this.sql.all(`DELETE FROM blocks WHERE until <= ?`, now);
+    this.endExited(now);
     this.settleOffline(now);
     this.sql.all(
       `DELETE FROM endpoints WHERE kind = 'agent' AND connections = 0 AND COALESCE(last_seen, created_at) <= ?
@@ -3111,6 +3359,16 @@ 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 */
+  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);
+    }
+  }
   /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
   settleOffline(now) {
     for (const row of this.sql.all(
@@ -3147,6 +3405,7 @@ var RelayCore = class {
     );
     this.sql.all(`DELETE FROM activity WHERE id <= ?`, row.id - LIMITS.activityKeep);
     const own = this.holds(this.mustEndpoint(endpoint), options);
+    if (own && !agent && params.kind === "tool") this.settle(endpoint);
     if (own && !agent && typeof params.session_id === "string" && HARNESS_SESSION.test(params.session_id)) {
       this.sql.all(
         `UPDATE endpoints SET harness_session = ?, harness_transcript = ? WHERE id = ?`,
@@ -3163,15 +3422,19 @@ var RelayCore = class {
           endpoint
         );
     } else if (params.kind === "session_start") {
+      const fresh = own && summary !== "compact" && summary !== "resume";
       this.sql.all(
         `UPDATE endpoints SET hook_seen = COALESCE(?, hook_seen), hook_ended = NULL, stop_blocks = CASE WHEN ? THEN 0 ELSE stop_blocks END, pushes = CASE WHEN ? THEN 0 ELSE pushes END,
-         briefed = CASE WHEN ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? THEN NULL ELSE introduced END, directive_holds = CASE WHEN ? THEN NULL ELSE directive_holds END WHERE id = ?`,
+         briefed = CASE WHEN ? THEN NULL ELSE briefed END, introduced = CASE WHEN ? THEN NULL ELSE introduced END, directive_holds = CASE WHEN ? THEN NULL ELSE directive_holds END,
+         title = CASE WHEN ? AND title = title_auto THEN NULL ELSE title END, title_auto = CASE WHEN ? THEN NULL ELSE title_auto END WHERE id = ?`,
         options.transient ? now : null,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
         own ? 1 : 0,
+        fresh ? 1 : 0,
+        fresh ? 1 : 0,
         endpoint
       );
     } else if (options.transient) {
@@ -3502,6 +3765,19 @@ var RelayCore = class {
       return change;
     });
   }
+  /** the grant issuer's messages to the endpoint that spent it, sent since the grant, that it read, all but those among `unapplied`, oldest first */
+  readSteers(grant, spender, unapplied) {
+    return this.sql.all(
+      `SELECT m.id, d.acked_at, d.deferred_ack FROM deliveries d JOIN messages m ON m.id = d.message_id
+       WHERE d.endpoint = ? AND m.from_ep = ? AND m.created_at >= ? AND d.acked_at IS NOT NULL
+       ${unapplied.length ? `AND m.id NOT IN (${unapplied.map(() => "?").join(", ")})` : ""} ORDER BY d.seq LIMIT ?`,
+      spender.id,
+      grant.issuer,
+      grant.created_at,
+      ...unapplied,
+      LIMITS.inboxPage
+    );
+  }
   /**
    * a message needs both ends: for each `ep:` selector `widen` added on `target`, the other end's side is widened to admit `target` too when
    * `me` has authority over it, audited as its own widening; when that side still refuses, the change names it and the command that would fix it.
@@ -3836,8 +4112,9 @@ var RelayCore = class {
   /**
    * a spawn's handback to its spawner `me`, the grant's issuer, from the worker (the relay when it never joined): past scopes, pair limits and
    * the judge, since the spawner minted the grant and is the recipient. One per grant (null once sent), in the thread the two last wrote in,
-   * else one derived from the grant, naming by short id the spawner's messages the worker left unread; its hop follows the worker's causal
-   * hop, capped, and a full thread drops it (null). A worker that never joined or exited non-zero gets its `stderr` last, labelled, its
+   * else one derived from the grant, naming by short id the spawner's messages the worker read, with when (one a background hook showed only
+   * delivered, unless the worker then exited 0: its model had the next request), and those it left unread; its hop follows the worker's
+   * causal hop, capped, and a full thread drops it (null). A worker that never joined or exited non-zero gets its `stderr` last, labelled, its
    * output cut from the front so both stay within ${LIMITS.handbackBytes} bytes
    */
   handback(me, grant, spender, code, whole, taken, lost = 0, exits = [], stderr = "") {
@@ -3882,7 +4159,13 @@ ${stderr}` : "";
     ];
     if (spender) {
       const unapplied = this.steersOf(grant, spender, now, taken);
-      if (unapplied.length) body.push(this.unappliedLines(spender, grant, unapplied, now, exits).join("\n"));
+      const steers = [
+        ...this.readSteers(grant, spender, taken).map(
+          (row) => `your steer ${shortId(row.id)} was ${row.deferred_ack && code !== 0 ? "delivered" : "read"} at ${clock(row.acked_at)}`
+        ),
+        ...unapplied.length ? this.unappliedLines(spender, grant, unapplied, now, exits) : []
+      ];
+      if (steers.length) body.push(steers.join("\n"));
     }
     const causal = spender && spender.last_received_at !== null && spender.last_received_at >= now - LIMITS.causalWindowS * 1e3;
     const hop = causal ? Math.min((spender.last_received_hop ?? 0) + 1, LIMITS.hopMax) : 0;
@@ -4865,7 +5148,7 @@ ${stderr}` : "";
   }
   /** the user parts an address of this core may carry */
   addressUsers() {
-    return [this.user, "me"];
+    return [this.user, "me", "local"];
   }
   /** whether the row is this host's own, the only rows with a tree, groups, rules and caps here */
   localRow(_row) {
@@ -4877,7 +5160,7 @@ ${stderr}` : "";
     const slash = text.indexOf("/");
     const user = slash === -1 ? null : text.slice(0, slash);
     const handle = slash === -1 ? text : text.slice(slash + 1);
-    if (user !== null && user !== "me" && user !== this.user) throw unreachable(text);
+    if (user !== null && user !== "me" && user !== "local" && user !== this.user) throw unreachable(text);
     const row = handle === "" ? this.byHandle(HUMAN_HANDLE) : validHandle(handle) ? this.byHandle(handle) : void 0;
     if (!row) throw unreachable(text);
     return row;
@@ -5934,6 +6217,7 @@ export {
   SHORT_ID,
   STATUS_STATES,
   SYSTEM_HANDLE,
+  TITLE_CHARS,
   VerdictCache,
   XCounters,
   XLIMITS,
@@ -5946,6 +6230,7 @@ export {
   clip,
   clipPasses,
   clipped,
+  clock,
   collapseTools,
   createSecretScanner,
   crossFleet,
@@ -5989,6 +6274,7 @@ export {
   randomHex,
   reachLines,
   readText,
+  receiptLines,
   redactPii,
   redactSecrets,
   redactionKind,