@scp-dev/core 0.1.0 → 0.1.2

package/src/core.ts

@@ -13,6 +13,7 @@ import {
   LIMITS,
   MESSAGE_KINDS,
   type MessageKind,
+  type MessageReceipts,
   type PeekLevel,
   type PeekResult,
   type PeekSeen,
@@ -42,7 +43,7 @@ import {
   type WhyResult,
 } from "./protocol"
 import { digestText, PEEK, peekLevel, readText } from "./peek"
-import { shortId, stripControl, wrapMessage } from "./render"
+import { clock, shortId, stripControl, wrapMessage } from "./render"
 import {
   clipped,
   expandRules,
@@ -68,6 +69,8 @@ import { one, type Sql, type SqlValue } from "./sql"
 import { utf8Bytes } from "./utf8"
 
 export const HUMAN_HANDLE = "_human"
+/** an agent title's length cap */
+export const TITLE_CHARS = 64
 export const SYSTEM_HANDLE = "_relay"
 export const GONE_PREFIX = "_gone_"
 
@@ -125,7 +128,9 @@ const 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)`,
@@ -237,12 +242,20 @@ export interface EndpointRow {
   /** JSON {@link ScopeCaps} */
   caps: string | null
   title: string | null
+  /** the title a hook last inferred: the title is inferred while it equals this */
+  title_auto: string | null
+  /** the prompt count when a summary last set the inferred title; null when the first prompt set it */
+  title_turn: number | null
+  /** the prompt count when the status note last changed or a hook last reminded the agent to refresh it */
+  tldr_turn: number | null
   /** when a new spawn last took the endpoint over: mail and messages from before it were the earlier holder's */
   reset_at: number | null
   /** when a new spawn last took the endpoint over: with its id, names the holder another machine sees */
   spawned_at: number | null
   /** who may peek: null is off */
   peek: PeekLevel | null
+  /** when the session last set its handle itself (join or rename): a later claim with another handle does not rename it back */
+  named: number | null
 }
 
 export interface MessageRow {
@@ -269,7 +282,7 @@ export interface CoreOptions {
   now?: () => number
   /** a synchronous hash for resume tokens (sha256 hex) */
   hash: (value: string) => string
-  /** runs `fn` atomically: bun:sqlite's db.transaction, a Durable Object's transactionSync */
+  /** runs `fn` atomically: a local SQLite transaction, a Durable Object's transactionSync */
   transaction?: <T>(fn: () => T) => T
   /** count every sender but the relay itself, humans included, against LIMITS.userPerDay, and trust no client's terminal claim for a hop reset (default: agents and non-terminal humans count) */
   capEverySender?: boolean
@@ -439,6 +452,8 @@ export class RelayCore {
   private readonly capEverySender: boolean
   private readonly alive: (pid: number) => boolean
   private readonly hostMachine: string | null
+  private readonly namedMachine: string | null
+  private readonly hostname: string | null
   private policy: Policy | null = 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` */
   private policyBinds = new Map<string, string>()
@@ -458,6 +473,14 @@ export class RelayCore {
     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
+  }
+
+  /** a `machine` label naming this host by its hostname, as clients default it, names it by its machine name when one is set */
+  private machineLabel(labels: Record<string, string>): Record<string, string> {
+    if (this.namedMachine !== null && labels.machine !== undefined && labels.machine === this.hostname) labels.machine = this.namedMachine
+    return labels
   }
 
   migrate(): void {
@@ -493,6 +516,10 @@ export class RelayCore {
       ["directive_holds", "INTEGER"],
       ["harness_session", "TEXT"],
       ["harness_transcript", "TEXT"],
+      ["title_auto", "TEXT"],
+      ["title_turn", "INTEGER"],
+      ["tldr_turn", "INTEGER"],
+      ["named", "INTEGER"],
     ] as const) {
       if (!endpointColumns.includes(column)) this.sql.all(`ALTER TABLE endpoints ADD COLUMN ${column} ${type}`)
     }
@@ -521,6 +548,8 @@ export class RelayCore {
     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<{ name: string }>(`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)) {
@@ -653,7 +682,7 @@ export class RelayCore {
       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),
     }
@@ -768,6 +797,7 @@ export class RelayCore {
     scope: ClaimScope = { handle: wanted, lineage: [], grant: null, rules: {}, groups: [], cwd: fields.cwd },
   ): { endpoint: EndpointView; token?: string; created?: true } {
     const now = this.now()
+    this.endExited(now)
     const bare = transient && fields.session !== null && BARE_PID_KEY.test(fields.session)
     let row = fields.session
       ? one<EndpointRow>(
@@ -793,7 +823,14 @@ export class RelayCore {
     } else if (row && !transient && !sameProcess(row, fields.process)) {
       row = undefined
       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 : 1000) && !settled; n++) {
@@ -1292,6 +1329,7 @@ export class RelayCore {
     } = {},
   ): EndpointView[] {
     const now = this.now()
+    this.endExited(now)
     this.settleOffline(now)
     const cutoff = now - LIMITS.listOfflineWithinS * 1000
     const viewer = filters.viewer === undefined ? undefined : this.mustEndpoint(filters.viewer)
@@ -1359,10 +1397,12 @@ export class RelayCore {
     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,
     )
   }
@@ -1373,11 +1413,126 @@ export class RelayCore {
     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: string, params: { text?: unknown; from?: unknown }, options: { transient?: boolean; process?: string } = {}): boolean {
+    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: Claim, handle?: unknown): EndpointView {
+    return this.scopeTx(() => {
+      const { endpoint } = this.claim(claim, { transient: true })
+      const row = this.mustEndpoint(endpoint.id)
+      if (handle !== undefined && handle !== null && handle !== "") this.renameRow(row, handle, false)
+      this.sql.all(`UPDATE endpoints SET hook_seen = ?, hook_ended = NULL WHERE id = ?`, this.now(), row.id)
+      this.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: ScopeActor, params: { endpoint?: unknown; handle: unknown }): { endpoint: EndpointView; from: string; session: string | null } {
+    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 === 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 }
+    })
+  }
+
+  /** 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 {
+    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"],
+      ] as const)
+        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: ScopeActor, params: { endpoint?: unknown } = {}): { endpoint: EndpointView; session: string | null } {
+    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 === undefined ? 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: string): string | null {
+    return this.byId(endpoint)?.session ?? null
+  }
+
   // messages
 
   /**
@@ -1438,6 +1593,17 @@ export class RelayCore {
       resolved.push(row)
     }
     const recipients = [...new Map(resolved.map((row) => [row.id, row])).values()]
+    if (params.live !== undefined && 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}`)
@@ -1667,7 +1833,7 @@ export class RelayCore {
         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: SendResult = { id, thread, hop, deliveries }
+      const sent: SendResult = { 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 (?, ?, ?, ?, ?)`,
@@ -1749,21 +1915,29 @@ export class RelayCore {
     }
   }
 
-  /** 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: string, options: { after?: number | undefined; limit?: number | undefined } = {}): Envelope[] {
     const now = this.now()
     const limit = Math.min(Math.max(1, Math.floor(options.limit ?? LIMITS.inboxPage)), LIMITS.inboxPage)
-    const rows = this.sql.all<MessageRow & { seq: number }>(
-      `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 > ?
+    const rows = this.sql.all<MessageRow & { seq: number; deferred_at: number | null; acked_at: number | null }>(
+      `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 * 1000,
       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
+    })
   }
 
   /**
@@ -1806,10 +1980,11 @@ export class RelayCore {
    * `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: string,
-    options: { stop?: boolean; count?: boolean; holdUnread?: boolean; directives?: boolean; transient?: boolean; process?: string } = {},
+    options: { stop?: boolean; count?: boolean; holdUnread?: boolean; directives?: boolean; transient?: boolean; process?: string; wake?: boolean } = {},
   ): {
     messages: Envelope[]
     offered: number[]
@@ -1899,7 +2074,7 @@ export class RelayCore {
       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 ? undefined : () => 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 }
@@ -1984,13 +2159,15 @@ export class RelayCore {
    * 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: string, options: { transient?: boolean; process?: string; prompts?: number } = {}): StopWaitResult {
+  stopWait(endpoint: string, options: { transient?: boolean; process?: string; prompts?: number; peek?: boolean } = {}): StopWaitResult {
     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<MessageRow & { seq: number }>(`SELECT m.*, d.seq AS seq ${where} ORDER BY d.seq LIMIT ?`, ...params, LIMITS.inboxPage) : []
@@ -2004,8 +2181,8 @@ export class RelayCore {
     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)],
@@ -2013,6 +2190,7 @@ export class RelayCore {
       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,
@@ -2080,9 +2258,29 @@ export class RelayCore {
   prompted(endpoint: string, options: { transient?: boolean; process?: string } = {}): boolean {
     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: string, every: number): boolean {
+    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 */
+  private settle(endpoint: string): void {
+    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
@@ -2091,22 +2289,22 @@ export class RelayCore {
    * 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.
    */
-  private liveWorkers(me: EndpointRow, now: number): { workers: EndpointRow[]; starting: number; paced: string[] } {
-    const grants = this.sql.all<Pick<GrantRow, "token_hash" | "used_by" | "bound_process" | "pushed_at" | "handback">>(
-      `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`,
+  private liveWorkers(me: EndpointRow, now: number, noPush = false): { workers: EndpointRow[]; starting: number; paced: string[]; unjoined: string[] } {
+    const grants = this.sql.all<Pick<GrantRow, "token_hash" | "used_by" | "bound_process" | "pushed_at" | "handback" | "name">>(
+      `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 = new Map<string, EndpointRow>()
     const paced = new Set<string>()
-    let starting = 0
+    const unjoined: string[] = []
     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)
@@ -2114,7 +2312,7 @@ export class RelayCore {
       workers.set(row.id, row)
       if (grant.pushed_at !== null && grant.pushed_at > now - LIMITS.pushGapS * 1000) paced.add(row.id)
     }
-    return { workers: [...workers.values()], starting, paced: [...paced] }
+    return { workers: [...workers.values()], starting: unjoined.length, paced: [...paced], unjoined }
   }
 
   /**
@@ -2216,9 +2414,11 @@ export class RelayCore {
 
   /**
    * 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: unknown, hold: unknown, options: { endpoint?: string; read?: unknown } = {}): number {
+  injected(seqs: unknown, hold: unknown, options: { endpoint?: string; read?: unknown; deferred?: boolean } = {}): number {
     const list = seqList(seqs)
     if (typeof hold !== "string") return 0
     const read = new Set(options.read === undefined || options.endpoint === undefined ? [] : seqList(options.read))
@@ -2233,13 +2433,17 @@ export class RelayCore {
         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
@@ -2305,6 +2509,51 @@ export class RelayCore {
     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: string, id: unknown): MessageReceipts {
+    if (typeof id !== "string" || !id.trim()) throw new RelayError("invalid_params", "id is a message id")
+    type Row = { id: string; thread: string }
+    const sent = `SELECT id, thread FROM messages WHERE from_ep = ?`
+    let rows =
+      id === "last" ? this.sql.all<Row>(`${sent} ORDER BY created_at DESC, id DESC LIMIT 1`, endpoint) : this.sql.all<Row>(`${sent} AND id = ?`, endpoint, id)
+    if (!rows.length && MESSAGE_SUFFIX.test(id))
+      rows = this.sql.all<Row>(`${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<{ endpoint: string; acked_at: number | null; injected_at: number | null; deferred_ack: number | null }>(
+      `SELECT endpoint, acked_at, injected_at, deferred_ack FROM deliveries WHERE message_id = ? ORDER BY seq`,
+      message.id,
+    )
+    const address = (key: string) => {
+      const pending = key.startsWith(pendingKey(""))
+        ? one<{ name: string | null }>(this.sql, `SELECT name FROM grants WHERE token_hash = ?`, key.slice(pendingKey("").length))
+        : undefined
+      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
@@ -2399,6 +2648,7 @@ export class RelayCore {
     )
   }
 
+  /** marks these deliveries to `endpoint` read, one a background hook's showing acked ({@link injected}) read now too; how many were unread */
   ack(endpoint: string, seqs: unknown): number {
     let acked = 0
     for (const seq of seqList(seqs)) {
@@ -2408,6 +2658,13 @@ export class RelayCore {
         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
@@ -2527,6 +2784,7 @@ export class RelayCore {
     this.sql.all(`DELETE FROM idempotency WHERE created_at <= ?`, now - LIMITS.idempotencyS * 1000)
     this.sql.all(`DELETE FROM pair_events WHERE at <= ?`, now - 3600 * 1000)
     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) <= ?
@@ -2553,6 +2811,17 @@ export class RelayCore {
     }
   }
 
+  /** ends the hook presence of local agent endpoints whose harness process exited without a session_end, as one would */
+  endExited(now = this.now()): void {
+    for (const row of this.sql.all<EndpointRow>(
+      `SELECT * FROM endpoints WHERE kind = 'agent' AND connections = 0 AND hook_seen IS NOT NULL AND process IS NOT NULL`,
+    )) {
+      const pid = Number(/^pid:(\d+)/.exec(row.process!)?.[1])
+      if (!pid || !this.localRow(row) || this.alive(pid)) continue
+      this.sql.all(`UPDATE endpoints SET hook_seen = NULL, hook_ended = ?, session = NULL WHERE id = ? AND connections = 0`, now, row.id)
+    }
+  }
+
   /** an agent endpoint left offline drops a working or waiting status, which no one is left to keep current */
   private settleOffline(now: number): void {
     for (const row of this.sql.all<EndpointRow>(
@@ -2595,6 +2864,7 @@ export class RelayCore {
     )!
     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 = ?`,
@@ -2611,15 +2881,19 @@ export class RelayCore {
           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) {
@@ -2997,6 +3271,20 @@ export class RelayCore {
     })
   }
 
+  /** 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 */
+  private readSteers(grant: GrantRow, spender: EndpointRow, unapplied: string[]): { id: string; acked_at: number; deferred_ack: number | null }[] {
+    return this.sql.all<{ id: string; acked_at: number; deferred_ack: number | null }>(
+      `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.
@@ -3370,8 +3658,9 @@ export class RelayCore {
   /**
    * 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
    */
   private handback(
@@ -3435,7 +3724,13 @@ export class RelayCore {
         ]
     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 * 1000
     const hop = causal ? Math.min((spender.last_received_hop ?? 0) + 1, LIMITS.hopMax) : 0
@@ -4550,7 +4845,7 @@ export class RelayCore {
 
   /** the user parts an address of this core may carry */
   protected addressUsers(): string[] {
-    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 */
@@ -4564,7 +4859,7 @@ export class RelayCore {
     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) : undefined
     if (!row) throw unreachable(text)
     return row