agent-relay-server 0.121.4 → 0.122.0

package/runner/src/adapter.ts

@@ -1,8 +1,8 @@
 import type { AgentProfile, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
-import { isRecord } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk/types/guards";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
-import { messageBodyMaxCharsFromEnv } from "./config";
+import { messageBodyMaxCharsFromEnv } from "./message-body-config";
 import { relayReplyReminderText } from "./relay-instructions";
 import { renderRunnerTemplate } from "./template-resolver";
 
@@ -250,6 +250,53 @@ export function providerMessageBodyMaxChars(): number {
   return DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS;
 }
 
+export interface DeliveredBodyPreview {
+  body: string;
+  truncated: boolean;
+  /** Retrieval-guidance lines (empty when not truncated). Call sites may append provider extras. */
+  guidance: string[];
+}
+
+// #1058 — one home for the delivered-body cap. Head-only truncation silently ate the TAIL, which is
+// exactly where a report-up final puts its verdict / SHIP recommendation. Preserve BOTH ends: keep a
+// head slice for opening context and a tail slice for the conclusion, eliding the middle and pointing
+// at the untrimmed body. The tail is favored (it holds the verdict). Slices snap to whitespace so we
+// don't deliver a half-word at either seam. Grep before adding another truncation site — this is it.
+export function previewDeliveredBody(
+  rawBody: string,
+  messageId: number,
+  maxChars: number = providerMessageBodyMaxChars(),
+): DeliveredBodyPreview {
+  if (rawBody.length <= maxChars) return { body: rawBody, truncated: false, guidance: [] };
+  const fetchLines = [
+    `Read full: agent-relay get-message ${messageId}`,
+    `Body only: agent-relay get-message ${messageId} --body`,
+  ];
+  const marker = (elided: number) => `[… ${elided} chars elided from the middle — full report: relay_get_message #${messageId} …]`;
+  // Reserve room for the marker and its two blank-line joins; upper-bound the marker length by using
+  // the (always-larger) full body length so the reserved budget can never underflow the real marker.
+  const budget = maxChars - marker(rawBody.length).length - 4;
+  if (budget < 200) {
+    // Cap too small to keep a useful head — front-truncate, preserving the tail/verdict whole.
+    const tail = rawBody.slice(rawBody.length - maxChars).replace(/^\S*\s+/, "").trimStart();
+    return {
+      body: tail,
+      truncated: true,
+      guidance: [`[truncated: showing last ${tail.length} of ${rawBody.length} chars — head trimmed, tail/verdict preserved]`, ...fetchLines],
+    };
+  }
+  const headChars = Math.floor(budget * 0.35);
+  const tailChars = budget - headChars;
+  const head = rawBody.slice(0, headChars).replace(/\s+\S*$/, "").trimEnd();
+  const tail = rawBody.slice(rawBody.length - tailChars).replace(/^\S*\s+/, "").trimStart();
+  const elided = rawBody.length - head.length - tail.length;
+  return {
+    body: `${head}\n\n${marker(elided)}\n\n${tail}`,
+    truncated: true,
+    guidance: [`[truncated: showing first ${head.length} + last ${tail.length} of ${rawBody.length} chars — tail/verdict preserved]`, ...fetchLines],
+  };
+}
+
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;
   const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;
@@ -375,23 +422,11 @@ export function providerMessageText(messages: Message[]): string {
       const subject = message.subject ? `Subject: ${message.subject}\n` : "";
       const isMemoryContext = isMemoryInjection(message);
       const canReferenceMessage = isPersistedRelayMessage(message) && !isMemoryContext && !isReactionNotification(message);
-      const shouldPreview = canReferenceMessage && message.body.length > maxChars;
-      const preview = shouldPreview
-        ? {
-          body: message.body.slice(0, maxChars),
-          truncated: true,
-        }
-        : {
-          body: message.body,
-          truncated: false,
-        };
+      const preview = canReferenceMessage
+        ? previewDeliveredBody(message.body, message.id, maxChars)
+        : { body: message.body, truncated: false, guidance: [] };
       const truncationGuidance = preview.truncated
-        ? [
-          `[truncated: showing first ${maxChars} of ${message.body.length} chars]`,
-          `Read full: agent-relay get-message ${message.id}`,
-          `Body only: agent-relay get-message ${message.id} --body`,
-          `Long reply CLI fallback: agent-relay /reply ${message.id} --body-file response.md`,
-        ].join("\n")
+        ? [...preview.guidance, `Long reply CLI fallback: agent-relay /reply ${message.id} --body-file response.md`].join("\n")
         : undefined;
       if (isMemoryContext) {
         return [

package/runner/src/config.ts

@@ -6,6 +6,7 @@ import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER, errMessage, stringValue } from "
 import type { SettingEntry, WorkspaceMetadata } from "agent-relay-sdk";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { getManifest } from "agent-relay-providers";
+export { messageBodyMaxCharsFromEnv } from "./message-body-config";
 
 interface ProviderConfig {
   command: string;
@@ -241,10 +242,6 @@ export function providerHomeRootFromEnv(): string {
   return process.env.AGENT_RELAY_PROVIDER_HOME_ROOT || join(homedir(), ".agent-relay", "provider-homes");
 }
 
-export function messageBodyMaxCharsFromEnv(): string | undefined {
-  return process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
-}
-
 export function loadProviderConfig(provider: string, home = agentRelayHome()): LoadedProviderConfig {
   const path = join(providersDir(home), `${provider}.json`);
   const raw = readJson(path);

package/src/agent-card-projection.ts

@@ -9,6 +9,7 @@
 import { isRecord } from "agent-relay-sdk";
 import { attachBranchState } from "./agent-branch-state";
 import { deriveAgentBusyHealth } from "./agent-busy-health";
+import { attachCommandActivity } from "./agent-command-activity";
 import { attachIssueRepo } from "./agent-issue-repo";
 import type { AgentCard } from "./types";
 
@@ -28,8 +29,11 @@ const OMITTED_STATUS_WORKSPACE_KEYS = new Set([
 /** Enrich an AgentCard with the derived fields the dashboard expects on every surface. */
 export function projectAgentCard(agent: AgentCard): AgentCard {
   const projected = attachIssueRepo(attachBranchState(agent));
+  // busy-health derives from the RAW provider status, so read it before the #1004 command-busy
+  // overlay — a running background command must not make the agent look stuck-busy.
   const busyHealth = deriveAgentBusyHealth(projected);
-  return busyHealth ? { ...projected, meta: { ...(projected.meta ?? {}), busyHealth } } : projected;
+  const enriched = busyHealth ? { ...projected, meta: { ...(projected.meta ?? {}), busyHealth } } : projected;
+  return attachCommandActivity(enriched);
 }
 
 function projectStatusMeta(meta: AgentCard["meta"]): AgentCard["meta"] | undefined {

package/src/agent-command-activity.ts

@@ -0,0 +1,39 @@
+// #1004 — the single home for the running-command → busy DISPLAY rule.
+//
+// A background command scheduled via relay_schedule_timer runs on the creating agent's behalf
+// (on an orchestrator). The provider reports that agent `idle` the instant its own turn ends,
+// so the still-running command is invisible on the dashboard — it reads idle while a real shell
+// command (e.g. a release) executes. Reflect it as `busy` for the command's lifetime.
+//
+// Every agent-card serialization boundary routes through here — the SSE projection
+// (agent-card-projection.ts) AND the REST reads (routes/agents.ts) — mirroring how
+// attachBranchState/attachIssueRepo enrich at those same boundaries, so live ticks and polls
+// agree. A prompt-wakeup timer (no command) is a plain future alarm and never triggers this.
+//
+// Override only a resting `idle`/`online`: never mask a genuine offline/stale/error, and never
+// fabricate work the provider itself already reports (busy stays busy). The busy-ness is derived
+// live from the timer/command rows (the source of truth via agentHasRunningCommandTimer), not a
+// duplicated status flag — so it self-heals when the command settles and can't leak a
+// permanently-busy agent. It is a display overlay only: the stored provider status the reconcilers
+// read (getAgent/listAgents) is untouched, so stuck-busy health and lifecycle gating are unaffected.
+import { agentHasRunningCommandTimer, agentsWithRunningCommandTimers } from "./db";
+import type { AgentCard } from "./types";
+
+function applyCommandBusy(agent: AgentCard, running: boolean): AgentCard {
+  if (!running) return agent;
+  if (agent.status !== "idle" && agent.status !== "online") return agent;
+  return { ...agent, status: "busy" };
+}
+
+/** Overlay running-command busy on a single card (SSE projection + REST get-by-id). */
+export function attachCommandActivity(agent: AgentCard): AgentCard {
+  return applyCommandBusy(agent, agentHasRunningCommandTimer(agent.id));
+}
+
+/** Batch variant for list endpoints: one query, then map (REST get-many). */
+export function attachCommandActivities(agents: AgentCard[]): AgentCard[] {
+  if (agents.length === 0) return agents;
+  const running = agentsWithRunningCommandTimers();
+  if (running.size === 0) return agents;
+  return agents.map((agent) => applyCommandBusy(agent, running.has(agent.id)));
+}

package/src/automations/reconcile.ts

@@ -202,7 +202,7 @@ function maybeFailNeverReadyOfflineTarget(run: AutomationRun, task: Task, now: n
       automationTargetNeverReady: true,
       agentId,
     },
-  });
+  }, { privileged: true });
   const updatedTask = taskResult.task ?? getTask(task.id) ?? task;
   updateRun(run.id, {
     status: "failed",
@@ -248,7 +248,7 @@ function maybeTimeoutRuntimeBudget(run: AutomationRun, task: Task, now: number):
       maxRuntimeMs: budget.maxRuntimeMs,
       deadlineAt: deadline,
     },
-  });
+  }, { privileged: true });
   const updatedTask = taskResult.task ?? getTask(task.id) ?? task;
   const command = requestOnDemandAgentShutdown(run, updatedTask, now, "runtime-budget-timeout");
   updateRun(run.id, {

package/src/bus.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
+import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, setStatus, validateAgentSession } from "./db";
 import { getOutboxCursor, hasReplayGap, replayEventsSlice, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
@@ -127,9 +127,11 @@ export function expireStaleBusAgents(graceMs = busStaleGraceMs(), lagGraceMs = 0
   const rows = getDb().query("SELECT id FROM agents WHERE status = 'stale' AND last_seen < ? AND id NOT IN ('user', 'system')").all(cutoff) as Array<{ id: string }>;
   const orphanedTasks: Task[] = [];
   for (const row of rows) {
-    // Bus-grace staleness across a relay restart/reconnect — the process may be alive.
-    // Tag "stale" so a live runner self-heals via orchestrator re-mint (#484).
-    revokeRuntimeTokensForAgent(row.id, Date.now(), "stale");
+    // #1051 — bus-grace staleness is a liveness observation, not a credential fact: the
+    // process may still be alive (relay stall / network blip). Mark offline for routing,
+    // but do NOT revoke the token — a reconnect accepts the EXISTING token and re-marks
+    // live. The #484 restart-strand revoke now fires on instance takeover in registerAgent
+    // (a fresh instanceId → epoch bump), never on a heartbeat lapse.
     setStatus(row.id, "offline");
     emitAgentStatusEvent(row.id);
     // #1040 — the stale sweep is the terminal busy→offline edge for a runner that dropped without a

package/src/cli/workspace.ts

@@ -150,7 +150,9 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
   }
 
   if (action === "cleanup-stale") {
-    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, ...(idExplicit && id ? { workspaceId: id } : {}) });
+    // #965 — --force discards an abandoned offline-owner worktree even when its git state is a
+    // conflict/unlanded (the land-safety gate is right for live work, wrong for a dead branch).
+    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, force, ...(idExplicit && id ? { workspaceId: id } : {}) });
     console.log(JSON.stringify(result, null, 2));
     return;
   }

package/src/config.ts

@@ -65,7 +65,16 @@ export const STUCK_BUSY_STARTUP_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_STAR
 export const STUCK_BUSY_RECONNECT_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_RECONNECT_MS", STUCK_BUSY_THRESHOLD_MS);
 export const STUCK_BUSY_SHUTDOWN_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_SHUTDOWN_MS", STUCK_BUSY_THRESHOLD_MS);
 export const EVENT_LOOP_LAG_SAMPLE_MS = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_SAMPLE_MS", 1_000);
-export const EVENT_LOOP_LAG_WINDOW_SAMPLES = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_WINDOW_SAMPLES", 60);
+// #1055 invariant: retain STRICTLY MORE than one reaper interval of lag history. The
+// stale/bus reaper reads the cumulative lag grace once per REAP_INTERVAL_MS; if the ring
+// held only one interval's worth (the old 60×1s == 60s == REAP_INTERVAL coincidence),
+// the oldest stall samples could rotate out the instant before the first post-recovery
+// reaper run and collapse the grace exactly when it's needed. Keep a half-interval margin
+// (1.5× reaper interval) so recent overload always survives to the next reaper tick.
+export const EVENT_LOOP_LAG_WINDOW_SAMPLES = envPositiveInt(
+  "AGENT_RELAY_EVENT_LOOP_LAG_WINDOW_SAMPLES",
+  Math.ceil((REAP_INTERVAL_MS / EVENT_LOOP_LAG_SAMPLE_MS) * 1.5),
+);
 export const EVENT_LOOP_LAG_WARN_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_WARN_MS", 250);
 export const EVENT_LOOP_LAG_LOG_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_LOG_MS", EVENT_LOOP_LAG_WARN_MS);
 // #713 — provider-token silence ALONE is not a wedge signal for Claude (long turns, extended

package/src/db/agents.ts

@@ -145,7 +145,7 @@ function tagsWithProvider(input: RegisterAgentInput): string[] {
 }
 
 
-export function upsertAgent(input: RegisterAgentInput): AgentCard {
+export function upsertAgent(input: RegisterAgentInput, opts?: { verifiedKeepJtis?: string[] }): AgentCard {
   const now = Date.now();
   const kind = inferAgentKind(input);
   if (kind === "channel") {
@@ -190,35 +190,48 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
       last_seen = $now
   `);
 
-  stmt.run({
-    $id: input.id,
-    $name: input.name,
-    $kind: kind,
-    $label: input.label ?? null,
-    $labelProvided: labelProvided ? 1 : 0,
-    $tags: JSON.stringify(tags),
-    $machine: input.machine ?? null,
-    $rig: input.rig ?? null,
-    $capabilities: JSON.stringify(input.capabilities ?? []),
-    $ready: input.ready ? 1 : 0,
-    $readyProvided: readyProvided ? 1 : 0,
-    $status: input.status ?? "idle",
-    $instanceId: input.instanceId ?? null,
-    $instanceProvided: instanceProvided ? 1 : 0,
-    $initialEpoch: instanceProvided ? 1 : 0,
-    $providerCapabilities: input.providerCapabilities ? JSON.stringify(input.providerCapabilities) : null,
-    $contextState: contextState ? JSON.stringify(contextState) : null,
-    $quotaState: input.quota ? JSON.stringify(input.quota) : null,
-    $meta: JSON.stringify(input.meta ?? {}),
-    $lifecycle: input.lifecycle ?? "persistent",
-    $lifecycleProvided: lifecycleProvided ? 1 : 0,
-    $spawnedBy: input.spawnedBy ?? null,
-    $teamId: input.teamId ?? null,
-    $now: now,
-  });
+  // #1057(2) — the takeover revoke fires on the SAME predicate as the epoch bump, by observing
+  // the bump itself (prior.epoch !== next.epoch) rather than re-deriving the SQL's instance-
+  // transition condition. The old guard in registerAgent required a truthy prior instanceId, so a
+  // NULL→instanceId takeover bumped the epoch yet skipped the revoke, stranding the prior token
+  // until the 24h prune. #1057(4) — write + revoke share one transaction: a revoke failure rolls
+  // the epoch bump back, so registration fails loudly with no committed bump / un-revoked token.
+  const agent = getDb().transaction(() => {
+    const prior = getAgent(input.id);
+    stmt.run({
+      $id: input.id,
+      $name: input.name,
+      $kind: kind,
+      $label: input.label ?? null,
+      $labelProvided: labelProvided ? 1 : 0,
+      $tags: JSON.stringify(tags),
+      $machine: input.machine ?? null,
+      $rig: input.rig ?? null,
+      $capabilities: JSON.stringify(input.capabilities ?? []),
+      $ready: input.ready ? 1 : 0,
+      $readyProvided: readyProvided ? 1 : 0,
+      $status: input.status ?? "idle",
+      $instanceId: input.instanceId ?? null,
+      $instanceProvided: instanceProvided ? 1 : 0,
+      $initialEpoch: instanceProvided ? 1 : 0,
+      $providerCapabilities: input.providerCapabilities ? JSON.stringify(input.providerCapabilities) : null,
+      $contextState: contextState ? JSON.stringify(contextState) : null,
+      $quotaState: input.quota ? JSON.stringify(input.quota) : null,
+      $meta: JSON.stringify(input.meta ?? {}),
+      $lifecycle: input.lifecycle ?? "persistent",
+      $lifecycleProvided: lifecycleProvided ? 1 : 0,
+      $spawnedBy: input.spawnedBy ?? null,
+      $teamId: input.teamId ?? null,
+      $now: now,
+    });
+    const next = getAgent(input.id)!;
+    if (prior && next.epoch !== prior.epoch) {
+      revokeSupersededRuntimeTokens(prior, opts?.verifiedKeepJtis ?? [], now);
+    }
+    return next;
+  })();
   if (contextState) recordContextSnapshot(input.id, contextState, now);
 
-  const agent = getAgent(input.id)!;
   seedContinuationObjectiveFromSpawnPrompt(agent.id, stringValue(agent.meta?.spawnRequestId), DEFAULT_SELF_RESUME_CONFIG, now);
   if (agent.kind === "channel") upsertChannelForAgent(agent);
   evaluatePoolBindings();
@@ -363,15 +376,49 @@ export function clearAgentMetaKeys(id: string, keys: string[]): boolean {
   return getDb().query("UPDATE agents SET meta = ? WHERE id = ?").run(JSON.stringify(meta), id).changes > 0;
 }
 
+/**
+ * #1059 — decide whether a process-exit certificate belongs to an agent row's CURRENT
+ * instance. A late/duplicate orchestrator exit report for a SUPERSEDED session (the agent id
+ * re-registered as a fresh instance after the report was generated) carries the prior session's
+ * `spawnRequestId`; the live successor's meta carries the new one. When both are known and
+ * differ, the certificate is for a dead predecessor and must never mark the successor gone.
+ * Unknown on either side (legacy / unmanaged sessions that never carried a spawnRequestId) can't
+ * be disproven, so it is treated as matching — preserving the pre-#1059 fast-exit path.
+ *
+ * The single home for the death-certificate/instance identity check, shared by the stamp site
+ * (recordAgentExitDiagnostics, below) and the reaper's death predicate (isOwnerProcessConfirmedGone
+ * in workspace-merge.ts) so the two can't drift.
+ */
+export function exitCertificateMatchesInstance(
+  currentMeta: Record<string, unknown> | undefined,
+  certificate: { spawnRequestId?: unknown } | undefined,
+): boolean {
+  const current = currentMeta ? stringValue(currentMeta.spawnRequestId) : undefined;
+  const cert = certificate ? stringValue(certificate.spawnRequestId) : undefined;
+  if (current && cert && current !== cert) return false;
+  return true;
+}
+
 export function recordAgentExitDiagnostics(id: string, diagnostics: ManagedSessionExitDiagnostics): AgentCard | null {
   const agent = getAgent(id);
   if (!agent) return null;
+  // #1059 — drop a stale/duplicate exit report for a SUPERSEDED instance. The agent id
+  // re-registered as a fresh session (new spawnRequestId) after this report was generated;
+  // stamping its predecessor's certificate here would poison the LIVE successor's row (false
+  // offline flip + false death notification via the caller + a certificate the dead-owner reaper
+  // would later act on — the #1054 reopener). Returning null makes the caller skip both the status
+  // emit and notifyAgentOffline, exactly as for an absent row.
+  if (!exitCertificateMatchesInstance(isRecord(agent.meta) ? agent.meta : undefined, diagnostics)) return null;
   const now = Date.now();
   const merged = {
     ...(agent.meta ?? {}),
     lastError: diagnostics.lastError,
     lastExit: diagnostics,
     lastExitAt: diagnostics.detectedAt || now,
+    // #1057(1) — RELAY-clock receipt of the process-confirmed death. The orphan-token sweep
+    // (revokeOrphanedRuntimeTokens) compares this against last_seen (also relay clock); the
+    // orchestrator-clock detectedAt in lastExitAt is not comparable across hosts.
+    lastExitReceivedAt: now,
   };
   // #636 — do NOT clobber last_seen with `now`: it is the agent's genuine last heartbeat, and the
   // death diagnosis derives the real heartbeat gap from it (the orchestrator exit path diagnoses
@@ -505,10 +552,13 @@ export function reapStaleAgents(ttlMs: number = STALE_TTL_MS, lagGraceMs = 0): s
     )
     .all(cutoff) as any[];
   for (const row of rows) {
-    // Staleness == last_seen lapsed, which is exactly the relay-restart strand: the
-    // process may still be alive. Tag "stale" so a live runner can self-heal via an
-    // orchestrator re-mint (#484); a genuinely-dead one never re-mints and is pruned.
-    revokeRuntimeTokensForAgent(row.id, now, "stale");
+    // #1051 — liveness ≠ credential validity. A lapsed heartbeat is a transient,
+    // recoverable observation (the relay may have stalled, or the network blipped);
+    // it marks status only and must NOT void a still-unexpired token. On reconnect the
+    // relay accepts the agent's EXISTING token and re-marks it live. The #484 restart-
+    // strand invariant (an orphaned prior-instance token must not stay usable) is now
+    // enforced on instance takeover instead — see revokeSupersededRuntimeTokens, fired
+    // from registerAgent when a fresh process re-registers under a new instanceId.
     closeOpenPairsForAgent(row.id, now);
   }
   return rows.map((r: any) => r.id);
@@ -582,6 +632,35 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
   return deleted ? { ok: true } : { ok: false, error: "agent not found" };
 }
 
+// #1057(1) — close the orphan-token window #1051 left open. A dead runner with no replacement
+// used to keep its token valid until the 24h offline prune (~720× the pre-#1051 ~2min horizon).
+// This sweep revokes ("stale", re-mintable — #484) the runtime tokens of agents whose process the
+// orchestrator CONFIRMED dead (meta.lastExit, the #1054 signal — never a liveness inference, so
+// the #1051 decouple holds) once a full grace has passed with no heartbeat since the relay
+// received the report. The two guards make a late exit report harmless to a live replacement:
+//   - a replacement registration replaces meta wholesale (no lastExitReceivedAt) → excluded;
+//   - a replacement that got the late report stamped ONTO its row keeps heartbeating, pushing
+//     last_seen past the receipt (heartbeat also flips it off 'offline') → excluded.
+// `lagGraceMs` mirrors the stale reaper's #1048/#1055 discipline: while the relay's own event
+// loop was stalled, a live claimant's heartbeats may not have been processed yet, so the window
+// widens by the observed lag rather than misreading the backlog as post-mortem silence.
+export function revokeOrphanedRuntimeTokens(graceMs: number = STALE_TTL_MS, lagGraceMs = 0, now = Date.now()): Array<{ agentId: string; jtis: string[] }> {
+  const cutoff = now - graceMs - Math.max(0, lagGraceMs);
+  const rows = getDb()
+    .query("SELECT id, meta, last_seen FROM agents WHERE status = 'offline' AND meta LIKE '%lastExitReceivedAt%' AND id NOT IN ('user', 'system')")
+    .all() as Array<{ id: string; meta: string | null; last_seen: number }>;
+  const revoked: Array<{ agentId: string; jtis: string[] }> = [];
+  for (const row of rows) {
+    const meta = parseJson<Record<string, unknown>>(row.meta ?? "{}", {});
+    const receivedAt = typeof meta.lastExitReceivedAt === "number" ? meta.lastExitReceivedAt : undefined;
+    if (receivedAt === undefined || receivedAt > cutoff) continue;
+    if (row.last_seen > receivedAt) continue;
+    const jtis = revokeProviderRuntimeTokensByJti(runtimeTokenJtisFromMeta(meta), "stale", now);
+    if (jtis.length > 0) revoked.push({ agentId: row.id, jtis });
+  }
+  return revoked;
+}
+
 // #484: `reason` is stamped on each revocation so a stale-on-restart revocation
 // (recoverable via orchestrator re-mint for a still-live process) is distinguishable
 // from a hard kill. Default "agent-removed" (hard) — callers that revoke a possibly-
@@ -589,6 +668,33 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
 export function revokeRuntimeTokensForAgent(agentId: string, now = Date.now(), reason: TokenRevokeReason = "agent-removed"): string[] {
   const row = getDb().query("SELECT meta FROM agents WHERE id = ?").get(agentId) as { meta?: string } | undefined;
   const jtis = runtimeTokenJtisFromMeta(parseJson(row?.meta ?? "{}", {}));
+  return revokeProviderRuntimeTokensByJti(jtis, reason, now);
+}
+
+// #1051 — the #484 restart-strand invariant, re-homed from heartbeat-lapse to instance
+// takeover. Staleness (a missed heartbeat) no longer revokes anything; instead, when a
+// FRESH runner process re-registers under an existing agent id — a new instanceId, which
+// bumps the agent epoch — the PRIOR instance's runtime tokens are revoked "stale" here,
+// atomically with the bump (fired from inside upsertAgent). "stale" (not a hard kill)
+// keeps them re-mintable via the orchestrator (#484), so a live process that merely
+// rotated instances still self-heals, while an orphaned prior-instance token can no
+// longer authenticate a request directly. A same-instance reconnect (relay-restart / lag
+// recovery) keeps its instanceId, does not bump the epoch, and so never reaches this
+// path — its token stays valid untouched.
+// #1057(3) — `keepJtis` must be SERVER-verified (the jti of the token that authenticated the
+// registration, resolved to this very agent — see registerAgent). It is never derived from the
+// incoming client meta: a takeover caller could otherwise list the prior jti in meta.auth.jtis
+// and spare it from revocation. The incoming instance's own token needs no keep entry — only
+// PRIOR jtis are ever revoked, so a fresh token is structurally never collateral.
+export function revokeSupersededRuntimeTokens(prior: AgentCard, keepJtis: string[] = [], now = Date.now()): string[] {
+  const priorJtis = runtimeTokenJtisFromMeta((prior.meta ?? {}) as Record<string, unknown>);
+  if (priorJtis.length === 0) return [];
+  const keep = new Set(keepJtis);
+  const superseded = priorJtis.filter((jti) => !keep.has(jti));
+  return revokeProviderRuntimeTokensByJti(superseded, "stale", now);
+}
+
+function revokeProviderRuntimeTokensByJti(jtis: string[], reason: TokenRevokeReason, now: number): string[] {
   if (jtis.length === 0) return [];
   const revokedAt = Math.floor(now / 1000);
   const placeholders = jtis.map(() => "?").join(",");

package/src/db/message-reads.ts

@@ -523,6 +523,19 @@ export function listPendingReplyObligations(agentId: string, limit = 20): ReplyO
  *
  * Returns the inbound message id this outbound answers, or null when nothing should be auto-linked.
  */
+/**
+ * #976 — the most recent message `fromId` addressed to `recipientId` (direct target OR resolved
+ * recipient). Used to anchor a suppressed standalone self→parent ack onto the conversation it
+ * belongs to, so a bare ack collapses onto the inbound it answers — mirroring the reply-path
+ * collapse (which returns the parent message being acked). Returns null when no such inbound exists.
+ */
+export function latestInboundMessage(recipientId: string, fromId: string): Message | null {
+  const sql = `${MSG_SELECT} WHERE m.from_agent = ? AND (m.to_target = ? OR m.resolved_to_agent = ?) ORDER BY m.id DESC LIMIT 1`;
+  const rows = timedQuery("latestInboundMessage", () =>
+    getDb().query(sql).all(fromId, recipientId, recipientId) as any[]);
+  return rows.length ? rowToMessage(rows[0]) : null;
+}
+
 export function channelObligationAnsweredBy(
   agentId: string,
   channelAgentId: string,
@@ -624,6 +637,43 @@ export function readSpawnReportVerbosity(spawnRequestId: string | undefined): Re
   }
 }
 
+/**
+ * #1062 — the RAW caller/parent brief a spawner supplied, read from the persisted `agent.spawn`
+ * command params by spawnRequestId. Mirrors {@link readSpawnReportVerbosity}: the dashboard
+ * (non-policy) restart path recovers this and re-threads it as `callerSystemPromptAppend` so a
+ * restarted spawned child keeps its parent's task brief while the rest of the projection
+ * (project/profile/scoped memory) is re-composed fresh. Returns undefined when absent/unparseable
+ * (pre-#1062 spawns never persisted it → the restart simply re-projects without a caller brief).
+ *
+ * #1067 — recovers across ANY number of dashboard restarts, not just one. #1065 rotates the
+ * spawnRequestId on every restart and never writes an agent.spawn row for the successor, so keying
+ * only on the original agent.spawn row lost the brief from the 2nd restart onward (the predecessor
+ * id was then the fresh id, which has no spawn row). The dashboard restart path re-persists the raw
+ * brief under each fresh id on the restart command's `restartSpawn.callerSystemPromptAppend`
+ * (agent-sessions.ts), so this lookup also matches an `agent.restart` row whose rotated id equals
+ * the query id — every generation has its own recoverable copy and the brief follows the agent.
+ */
+export function readSpawnCallerSystemPromptAppend(spawnRequestId: string | undefined): string | undefined {
+  if (!spawnRequestId) return undefined;
+  try {
+    const row = getDb().query(`
+      SELECT coalesce(
+               json_extract(params, '$.callerSystemPromptAppend'),
+               json_extract(params, '$.restartSpawn.callerSystemPromptAppend')
+             ) AS append
+      FROM commands
+      WHERE (type = 'agent.spawn' AND correlation_id = ?)
+         OR (type = 'agent.restart' AND json_extract(params, '$.restartSpawn.spawnRequestId') = ?)
+      ORDER BY created_at DESC
+      LIMIT 1
+    `).get(spawnRequestId, spawnRequestId) as { append: string | null } | undefined;
+    const append = row?.append;
+    return typeof append === "string" && append.trim() ? append : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function markRead(messageId: number, agentId: string): boolean {
   const exists = getDb().query("SELECT 1 FROM messages WHERE id = ?").get(messageId);
   if (!exists) return false;