agent-relay-server 0.120.6 → 0.121.1

package/src/agent-card-projection.ts

@@ -1,19 +1,30 @@
-// The ONE projection applied to an AgentCard before it leaves the relay over SSE or REST:
+// The ONE projection source for agent cards before they leave the relay:
 // branch-state badge fields (#236) + the resolved `issueRepo` for chat #NNN linkify (#533).
 //
 // Every `agent.status` emitter MUST route through this — the direct dashboard emitter
-// (sse.ts) AND the bus lifecycle emitter (bus.ts). The dashboard's agent.status handler
-// FULL-REPLACES its cached agent card with whatever arrives, so a single emitter sending a
-// raw (un-enriched) card silently blanks these derived fields until the next REST poll —
-// which made #NNN links and branch badges flicker on/off every few seconds (#560). Keeping
-// one projection here is the structural guarantee that projection == reality on every
-// surface; a new emitter can't reintroduce the drift without going around this function.
+// (sse.ts) AND the bus lifecycle emitter (bus.ts). The dashboard merges the slim status
+// projection into its cached card, so a raw (un-enriched) status tick would still blank
+// derived fields on fresh/new cards until the next REST poll (#560).
 
+import { isRecord } from "agent-relay-sdk";
 import { attachBranchState } from "./agent-branch-state";
 import { deriveAgentBusyHealth } from "./agent-busy-health";
 import { attachIssueRepo } from "./agent-issue-repo";
 import type { AgentCard } from "./types";
 
+const OMITTED_STATUS_META_KEYS = new Set([
+  "agentProfile",
+  "auth",
+  "providerCapabilities",
+  "lifecycleCapabilities",
+]);
+
+const OMITTED_STATUS_WORKSPACE_KEYS = new Set([
+  "deps",
+  "probe",
+  "symlinks",
+]);
+
 /** Enrich an AgentCard with the derived fields the dashboard expects on every surface. */
 export function projectAgentCard(agent: AgentCard): AgentCard {
   const projected = attachIssueRepo(attachBranchState(agent));
@@ -21,11 +32,30 @@ export function projectAgentCard(agent: AgentCard): AgentCard {
   return busyHealth ? { ...projected, meta: { ...(projected.meta ?? {}), busyHealth } } : projected;
 }
 
+function projectStatusMeta(meta: AgentCard["meta"]): AgentCard["meta"] | undefined {
+  if (!meta) return undefined;
+  const projected: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(meta)) {
+    if (OMITTED_STATUS_META_KEYS.has(key)) continue;
+    if (key === "workspace" && isRecord(value)) {
+      projected.workspace = Object.fromEntries(Object.entries(value).filter(([workspaceKey]) => !OMITTED_STATUS_WORKSPACE_KEYS.has(workspaceKey)));
+      continue;
+    }
+    projected[key] = value;
+  }
+  return projected;
+}
+
 /** The `agent.status` SSE payload: the enriched card when the agent is known, else the
- *  minimal offline stub the dashboard treats as "agent gone". Shared by both emitters. */
+ *  minimal offline stub the dashboard treats as "agent gone". Shared by both emitters.
+ *  Runtime status stays live, while bulky static/secret launch projection fields stay
+ *  behind GET /api/agents/:id and the normal dashboard polling path. */
 export function projectAgentStatusData(
   agentId: string,
   agent: AgentCard | null | undefined,
 ): AgentCard | { id: string; status: string } {
-  return agent ? projectAgentCard(agent) : { id: agentId, status: "offline" };
+  if (!agent) return { id: agentId, status: "offline" };
+  const projected = projectAgentCard(agent);
+  const meta = projectStatusMeta(projected.meta);
+  return meta ? { ...projected, meta } : { ...projected, meta: undefined };
 }

package/src/agent-issue-repo.ts

@@ -13,11 +13,18 @@ function agentCwd(agent: AgentCard): string | undefined {
   return typeof cwd === "string" && cwd ? cwd : undefined;
 }
 
+/** Resolve an agent's project issueRepo via its cwd, or undefined if it has no cwd or no
+ *  matching project/issueRepo. Exported so other callers needing a caller-scoped default repo
+ *  (e.g. plan-graph's bare `#NNN` issue ref resolution) reuse this instead of re-deriving cwd
+ *  → project → issueRepo themselves. */
+export function issueRepoForAgent(agent: AgentCard): string | undefined {
+  const cwd = agentCwd(agent);
+  return cwd ? resolveProjectForCwd(cwd)?.issueRepo : undefined;
+}
+
 /** Enrich a single agent with its resolved project issueRepo (one project_roots scan). */
 export function attachIssueRepo(agent: AgentCard): AgentCard {
-  const cwd = agentCwd(agent);
-  if (!cwd) return agent;
-  const repo = resolveProjectForCwd(cwd)?.issueRepo;
+  const repo = issueRepoForAgent(agent);
   return repo ? { ...agent, issueRepo: repo } : agent;
 }
 

package/src/agent-lifecycle-events.ts

@@ -1,6 +1,7 @@
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
-import { getAgent, markAgentReadyNotified, recordCrashReport, recordTerminalEvent } from "./db";
+import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "./lifecycle-signal-registry";
+import { deliverableTaskIdsBySpawnRequestId, getAgent, markAgentReadyNotified, recordCrashReport, recordTerminalEvent } from "./db";
 import { crashReportFor } from "./agent-death-diagnosis";
 import { renderTemplate } from "./prompt-resolver";
 import type { AgentCard, AgentDeathDiagnosis } from "./types";
@@ -82,6 +83,26 @@ function spawnRequestIdOf(child: AgentCard): string | undefined {
   return typeof s === "string" ? s : undefined;
 }
 
+// #1032b — record that a first-class lifecycle event (ready/exit) told the parent about this child,
+// so a redundant "Task status pulse" for the same child/task is suppressed instead of double-waking.
+// #1038 — agent.ready means the child is coming up to work its task, so it is state-keyed to
+// `working` (same as a report-up): it supersedes a redundant `working` pulse only, never a later
+// distinct-state transition for the same task within the TTL.
+function stampChildLifecycleSignal(parent: string, child: AgentCard): void {
+  stampLifecycleSignal(parent, childSignalKey(child.id));
+  const direct = child.meta?.taskId;
+  const directNum = typeof direct === "string" ? Number(direct) : direct;
+  if (typeof directNum === "number" && Number.isSafeInteger(directNum) && directNum > 0) {
+    stampLifecycleSignal(parent, taskSignalKey(directNum, LIFECYCLE_STATE_WORKING));
+  }
+  const spawnRequestId = spawnRequestIdOf(child);
+  if (spawnRequestId) {
+    for (const taskId of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) {
+      stampLifecycleSignal(parent, taskSignalKey(taskId, LIFECYCLE_STATE_WORKING));
+    }
+  }
+}
+
 /**
  * A spawned child became genuinely ready (registered AND past onboarding — ready+idle, not merely
  * process-started). Emits the durable `agent.ready` event and, unless suppressed, pushes the
@@ -152,6 +173,7 @@ export function notifyAgentReady(childId: string): void {
       replyExpected: false,
     },
   });
+  stampChildLifecycleSignal(parent, child);
 }
 
 /**

package/src/agent-ref.ts

@@ -99,9 +99,19 @@ function idMatchesSegment(id: string, ref: string): boolean {
 export function matchAgents(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): AgentCard[] {
   const trimmed = ref.trim();
   if (!trimmed) return [];
-  const pool = opts.excludeId ? agents.filter((a) => a.id !== opts.excludeId) : agents;
 
   const selector = parseSelector(trimmed);
+  // An exact id reference — a bare full id, or an `id:` selector — names ONE agent unambiguously,
+  // so it is honored even when it targets the excluded (self) agent: addressing your own full id
+  // is a deliberate self/peer send, NOT the #290 bare-ref self-loop that `excludeId` guards
+  // against. Without this exemption an exact self-id is refused by the matcher yet still offered by
+  // the "did you mean" hint — the resolver suggesting the very id it just rejected (#1035).
+  const exactId = selector ? (selector.field === "id" ? selector.value : null) : trimmed;
+  const selfExact = opts.excludeId && exactId
+    ? agents.find((a) => a.id === opts.excludeId && a.id === exactId)
+    : undefined;
+  const pool = opts.excludeId && !selfExact ? agents.filter((a) => a.id !== opts.excludeId) : agents;
+
   if (selector) return selector.value ? pool.filter((a) => matchesSelector(a, selector)) : [];
 
   const exact = pool.filter((a) => matchesExact(a, trimmed));
@@ -207,9 +217,14 @@ function ambiguousMessage(ref: string, candidates: AgentCard[]): string {
   return `agent reference "${ref}" is ambiguous — matches ${candidates.length}: ${list}${more}. Use a full id, label, or a fan-out selector (tag:/cap:/label:/team:).`;
 }
 
-function notFoundMessage(ref: string, agents: AgentCard[]): string {
+function notFoundMessage(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): string {
   const needle = ref.toLowerCase();
   const near = agents
+    // Canonicalize the suggestion pool to the SAME identity the matcher used: never offer the
+    // excluded (self) agent, and never suggest an id/label that EQUALS the ref — if it were an
+    // exact match it would have resolved, so surfacing it means offering the id we just rejected
+    // (#1035, the "Did you mean: <the id you typed>?" self-suggestion).
+    .filter((a) => a.id !== opts.excludeId && a.id !== ref && a.label !== ref)
     .filter((a) => isPseudoAgent(a) && (a.id.toLowerCase().includes(needle) || a.label?.toLowerCase().includes(needle)))
     .slice(0, 3)
     .map(describeAgent);
@@ -261,7 +276,7 @@ export function planSend(to: string, agents: AgentCard[], opts: ResolveOptions =
   if (offline.length > 1) {
     return { kind: "ambiguous", message: ambiguousMessage(target, offline), candidates: offline };
   }
-  return { kind: "not_found", message: notFoundMessage(target, agents) };
+  return { kind: "not_found", message: notFoundMessage(target, agents, opts) };
 }
 
 /**

package/src/bus-outbox.ts

@@ -20,6 +20,23 @@ interface OutboxRow {
 
 export function appendEvent(type: string, source: string, data: unknown, subject?: string): number {
   const timestamp = Date.now();
+  if (type === "message.batch") {
+    const messages = batchMessages(data);
+    if (messages.length > 0) {
+      return getDb().transaction(() => {
+        let firstSeq = 0;
+        const insert = getDb().query(`
+          INSERT INTO bus_outbox (event_type, source, subject, data, timestamp)
+          VALUES (?, ?, ?, ?, ?)
+        `);
+        for (const message of messages) {
+          const result = insert.run("message.new", message.from, String(message.id), JSON.stringify(message), timestamp);
+          if (firstSeq === 0) firstSeq = Number(result.lastInsertRowid);
+        }
+        return firstSeq;
+      })();
+    }
+  }
   const result = getDb().query(`
     INSERT INTO bus_outbox (event_type, source, subject, data, timestamp)
     VALUES (?, ?, ?, ?, ?)
@@ -28,6 +45,24 @@ export function appendEvent(type: string, source: string, data: unknown, subject
 }
 
 export function replayEvents(since: number, limit = 500): BusEvent[] {
+  return replayEventsSlice(since, limit).events;
+}
+
+export interface ReplaySlice {
+  events: BusEvent[];
+  /** The highest real outbox row seq in this slice (or `since` when empty). Resume from here to
+   * continue past the slice — driven by the raw row seq, not the (possibly batch-expanded) payload
+   * seq, so a legacy `message.batch` row can't be half-skipped. */
+  lastSeq: number;
+  /** More retained events exist beyond `lastSeq` — the caller MUST fetch the next slice, or the
+   * backlog tail between this slice and the outbox head is silently dropped (#1022 F1). */
+  truncated: boolean;
+}
+
+/** One page of the resume backlog plus whether more remains. `replayEvents`' 500-row cap used to
+ * be a silent ceiling: a resume returning exactly `limit` rows dropped everything between the last
+ * replayed event and the outbox head. Callers loop on `truncated`, resuming from `lastSeq`. */
+export function replayEventsSlice(since: number, limit = 500): ReplaySlice {
   const rows = getDb().query(`
     SELECT seq, event_type, source, subject, data, timestamp
     FROM bus_outbox
@@ -35,7 +70,10 @@ export function replayEvents(since: number, limit = 500): BusEvent[] {
     ORDER BY seq ASC
     LIMIT ?
   `).all(since, limit) as OutboxRow[];
-  return rows.map(rowToEvent);
+  const events = rows.map(rowToEvent);
+  const lastSeq = rows.length > 0 ? rows[rows.length - 1]!.seq : since;
+  const truncated = rows.length === limit && getOutboxCursor() > lastSeq;
+  return { events, lastSeq, truncated };
 }
 
 export function pruneOutbox(retentionMs = 60 * 60 * 1000): number {
@@ -54,6 +92,28 @@ export function getOldestOutboxCursor(): number {
   return row.cursor ?? 0;
 }
 
+/** The highest seq ever assigned to the outbox — read from `sqlite_sequence`, so it survives the
+ * retention prune that empties the table. Needed for gap detection: once the outbox is fully
+ * pruned `getOldestOutboxCursor()` returns 0, which read as "no gap" and let a reconnecting client
+ * believe it was caught up while its post-cursor events had aged out (#1022 F2). */
+export function getOutboxHighWater(): number {
+  const row = getDb().query("SELECT seq FROM sqlite_sequence WHERE name = 'bus_outbox'").get() as { seq: number } | undefined;
+  return row?.seq ?? 0;
+}
+
+/** Whether a resume from `since` has lost events to the retention prune. Two cases:
+ *   - outbox non-empty: the oldest retained event is newer than `since + 1` → the events between
+ *     were pruned.
+ *   - outbox fully pruned (oldest = 0): a gap exists iff events after `since` were ever assigned
+ *     (`since` is behind the high-water mark) and have since aged out.
+ * A client that hits a gap must reconcile from scratch rather than resume from a stale cursor. */
+export function hasReplayGap(since: number): boolean {
+  if (since <= 0) return false;
+  const oldest = getOldestOutboxCursor();
+  if (oldest > 0) return oldest > since + 1;
+  return since < getOutboxHighWater();
+}
+
 function rowToEvent(row: OutboxRow): BusEvent {
   return {
     seq: row.seq,
@@ -73,3 +133,16 @@ function parseData(raw: string): Record<string, unknown> {
     return {};
   }
 }
+
+function batchMessages(data: unknown): Array<{ id: number; from: string } & Record<string, unknown>> {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return [];
+  const messages = (data as { messages?: unknown }).messages;
+  if (!Array.isArray(messages)) return [];
+  return messages.filter((message): message is { id: number; from: string } & Record<string, unknown> =>
+    Boolean(message) &&
+    typeof message === "object" &&
+    !Array.isArray(message) &&
+    typeof (message as { id?: unknown }).id === "number" &&
+    typeof (message as { from?: unknown }).from === "string"
+  );
+}

package/src/bus.ts

@@ -1,6 +1,6 @@
 import type { Server, ServerWebSocket } from "bun";
 import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
-import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
+import { getOutboxCursor, hasReplayGap, replayEventsSlice, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { getCommand, updateCommand } from "./commands-db";
@@ -15,6 +15,7 @@ import { agentProviderTimelineEvent, auditRunnerTimelineEvent } from "./provider
 import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { flushQueuedDirectMessages } from "./services/managed-running";
+import { flushIdleLineageReport } from "./services/send-message";
 import { isAgentUnavailable } from "./db/agent-predicates";
 import { applyCommandToRecipe } from "./recipe-runner";
 import { enqueueContinuationInjectionAfterSelfResume } from "./self-resume";
@@ -105,6 +106,10 @@ export function busHandleClose(ws: BusWebSocket): void {
     if (!conn.transportReconnect) {
       setStatus(conn.agentId, "stale", { instanceId: conn.instanceId, epoch: conn.epoch });
       emitAgentStatusEvent(conn.agentId);
+      // #1040 — a WS close is a busy→exit edge (the runner crashed/dropped before its stop-hook
+      // status frame). Flush any held turn-final report-up so it still reaches the spawner instead
+      // of dying with the socket. No-op when nothing was deferred.
+      flushIdleLineageReport(conn.agentId);
     }
   }
 }
@@ -123,6 +128,9 @@ export function expireStaleBusAgents(graceMs = busStaleGraceMs()): { agentIds: s
     revokeRuntimeTokensForAgent(row.id, Date.now(), "stale");
     setStatus(row.id, "offline");
     emitAgentStatusEvent(row.id);
+    // #1040 — the stale sweep is the terminal busy→offline edge for a runner that dropped without a
+    // clean idle transition. Flush any held turn-final report-up before the agent ages out.
+    flushIdleLineageReport(row.id);
     const tasks = orphanTasksForAgent(row.id);
     for (const task of tasks) {
       orphanedTasks.push(task);
@@ -156,7 +164,14 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
             const wasUnavailable = current ? isAgentUnavailable(current) : false;
             const runtime = runtimeFromMeta(frame.payload.meta);
             heartbeat(conn.agentId, { instanceId: conn.instanceId, epoch: conn.epoch }, runtime);
-            if (frame.payload.status) setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
+            if (frame.payload.status) {
+              setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
+              // #1040 — a heartbeat frame can carry the busy→idle transition instead of a `status`
+              // frame. Flush the held report-up on THIS edge too, else `before.status` is already
+              // non-busy at the next status frame → the flush never fires → the child deadlocks idle
+              // with its verdict held and the coordinator waits forever.
+              if (current?.status === "busy" && frame.payload.status !== "busy") flushIdleLineageReport(conn.agentId);
+            }
             emitAgentStatusEvent(conn.agentId);
             // #416 — flush queued messages if the agent transitioned from unavailable to available.
             if (wasUnavailable) {
@@ -200,6 +215,9 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         emitAgentStatusEvent(conn.agentId);
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
+        // #1037 — the same busy→idle turn-end edge flushes a quiet child's deferred turn-final
+        // report-up to its spawner (held back while the child was mid-work).
+        if (before?.status === "busy" && after && after.status !== "busy") flushIdleLineageReport(conn.agentId);
         // #633 — silent clean-exit: a runner that stays alive after its provider terminally exited
         // marks the offline edge with `terminalProviderExit`; the owning service turns that into a
         // terminal event + #636 diagnosis (and clears the hold on a genuine resume).
@@ -466,18 +484,23 @@ function hasRunnerLifecycleCapabilities(capabilities: string[], meta: Record<str
 }
 
 function handleResume(ws: BusWebSocket, frameId: string, since: number): void {
-  const oldest = getOldestOutboxCursor();
-  if (since > 0 && oldest > 0 && oldest > since + 1) {
+  if (hasReplayGap(since)) {
     sendError(ws, frameId, "REPLAY_GAP", "requested cursor is older than retained bus outbox events");
     return;
   }
-  const events = replayEvents(since).map(outboxToPayload);
+  // One page only. The replay cap silently dropped the backlog tail between item 500 and the head
+  // (#1022 F1); we now report `truncated` + the raw `nextSince` row seq so the client loops resume
+  // until it has drained the whole backlog rather than lurching to the live head on the next event.
+  const slice = replayEventsSlice(since);
+  const events = slice.events.flatMap(outboxToPayloads);
   send(ws, {
     type: "resumed",
     payload: {
       events,
       fromSeq: events[0]?.seq ?? since,
       toSeq: events.at(-1)?.seq ?? since,
+      nextSince: slice.lastSeq,
+      truncated: slice.truncated,
     },
   });
 }
@@ -503,6 +526,10 @@ function withRegistered(
 }
 
 function broadcastRelayEvent(event: RelayEvent): void {
+  if (event.type === "message.batch") {
+    broadcastMessageBatch(event);
+    return;
+  }
   const frame = JSON.stringify({
     type: "event",
     payload: {
@@ -521,6 +548,41 @@ function broadcastRelayEvent(event: RelayEvent): void {
   }
 }
 
+function broadcastMessageBatch(event: RelayEvent): void {
+  const messages = batchMessages(event.data);
+  const messageEvents = messages.map((message, index) => {
+    const messageEvent: RelayEvent = {
+      ...event,
+      seq: event.seq + index,
+      type: "message.new",
+      source: message.from,
+      subject: String(message.id),
+      data: message as unknown as Record<string, unknown>,
+    };
+    return {
+      event: messageEvent,
+      frame: JSON.stringify({
+        type: "event",
+        payload: {
+          seq: messageEvent.seq,
+          eventType: "message.new",
+          source: message.from,
+          subject: String(message.id),
+          data: message,
+          timestamp: event.timestamp,
+        },
+      }),
+    };
+  });
+  const agentCache = new Map<string, AgentCard | null>();
+  for (const conn of busConnections.values()) {
+    for (const { event: messageEvent, frame } of messageEvents) {
+      if (!connectionWantsEvent(conn, messageEvent, agentCache)) continue;
+      conn.ws.send(frame);
+    }
+  }
+}
+
 function fanoutAgent(agentId: string, cache: Map<string, AgentCard | null>): AgentCard | null {
   if (!cache.has(agentId)) cache.set(agentId, getAgent(agentId));
   return cache.get(agentId) ?? null;
@@ -565,6 +627,23 @@ function outboxToPayload(event: BusEvent) {
   };
 }
 
+function outboxToPayloads(event: BusEvent) {
+  if (event.eventType !== "message.batch") return [outboxToPayload(event)];
+  return batchMessages(event.data).map((message, index) => ({
+    seq: event.seq + index,
+    eventType: "message.new",
+    source: message.from,
+    subject: String(message.id),
+    data: message as unknown as Record<string, unknown>,
+    timestamp: event.timestamp,
+  }));
+}
+
+function batchMessages(data: Record<string, unknown>): Message[] {
+  const messages = (data as { messages?: unknown }).messages;
+  return Array.isArray(messages) ? messages as Message[] : [];
+}
+
 function emitAgentStatusEvent(agentId: string): void {
   const agent = getAgent(agentId);
   // Same enriched projection as sse.ts's emitAgentStatus — without this the bus lifecycle

package/src/channel-target.ts

@@ -19,6 +19,10 @@ export function parseChannelRouteTarget(target: string): ChannelRouteTarget {
   if (target.startsWith("label:")) return { type: "label", id: target.slice("label:".length) };
   if (target.startsWith("tag:")) return { type: "tag", id: target.slice("tag:".length) };
   if (target.startsWith("cap:")) return { type: "capability", id: target.slice("cap:".length) };
+  // `capability:` is an accepted alias of `cap:` at send time (planSend/FANOUT_PREFIXES + the SDK
+  // matcher both honor it). Parse it here too so channel routing, broadcast scoping and the
+  // claimable gate don't silently treat a `capability:` message as a bare agent id (#1022 F3).
+  if (target.startsWith("capability:")) return { type: "capability", id: target.slice("capability:".length) };
   if (target === "broadcast") return { type: "broadcast" };
   if (target.startsWith("orchestrator:")) return { type: "orchestrator", id: target.slice("orchestrator:".length) };
   return { type: "agent", id: target };

package/src/cli/steward.ts

@@ -1,6 +1,7 @@
 // Steward commands — auto-split from cli.ts (#294). Briefing rail for the steward
 // (#208): the attention queue, per-workspace diagnostics, and check suggestions.
 import { apiRequest } from "./_shared";
+import { resolveStewardChecks } from "../gate-resolver";
 
 // Steward briefing commands (#208): queue of workspaces needing attention, a
 // per-workspace diagnostics inspection, and a check-command suggestion.
@@ -39,21 +40,21 @@ export async function handleStewardCommand(args: string[]): Promise<void> {
     return;
   }
 
-  // checks: suggest validation commands from the workspace's changed files.
+  // checks: suggest validation commands from the workspace's changed files. Derive
+  // the gate from the repo (#1036) — hardcoding `bun test` produced bogus failures in
+  // non-bun repos. Resolve the worktree to read its package.json / land-gates pin:
+  // an explicit `--repo` wins, else the workspace's own worktreePath/repoRoot.
   const diff = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diff?patch=0`) as any;
   const files: string[] = Array.isArray(diff?.files) ? diff.files.map((f: any) => f.path) : [];
-  const checks = suggestStewardChecks(files);
+  let repoRoot = repo;
+  if (!repoRoot) {
+    try {
+      const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`) as any;
+      repoRoot = ws?.worktreePath ?? ws?.repoRoot;
+    } catch {
+      // Best-effort: without a resolvable path the resolver falls back to its default.
+    }
+  }
+  const checks = resolveStewardChecks(files, repoRoot);
   console.log(JSON.stringify({ workspaceId: id, changedFiles: files.length, checks }, null, 2));
 }
-
-// Heuristic check suggestions from changed file paths. Repo-agnostic defaults a
-// steward can refine; cheaper than re-deriving from project docs every run.
-function suggestStewardChecks(files: string[]): Array<{ command: string; reason: string }> {
-  const checks: Array<{ command: string; reason: string }> = [];
-  const has = (re: RegExp) => files.some((f) => re.test(f));
-  if (has(/\.(ts|tsx|mts|cts)$/)) checks.push({ command: "bun run typecheck", reason: "TypeScript files changed" });
-  if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
-  else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
-  if (has(/(^|\/)dashboard\//)) checks.push({ command: "bun run build:dashboard", reason: "dashboard sources changed" });
-  return checks;
-}

package/src/commands-db.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { STALE_TTL_MS } from "./config";
 import { getAgent, getDb, getTerminalEvent, recordTerminalEvent } from "./db";
 import { stringValue } from "agent-relay-sdk";
 import type { Command, CommandStatus, CreateCommandInput, UpdateCommandInput } from "./types";
@@ -63,6 +64,14 @@ function isTerminalStatus(status: CommandStatus): boolean {
 function isLegitimateTerminalCorrection(type: string, from: CommandStatus, to: CommandStatus): boolean {
   if (type === "agent.spawn" && from === "succeeded" && to === "failed") return true;
   if (type === "orchestrator.upgrade" && from === "failed" && to === "succeeded") return true;
+  // #1025 A7 — a lost merge RESULT: the orchestrator lands the branch (base pushed,
+  // worktree recycled onto `<branch>-N`) but dies before POSTing, so the command ages to
+  // `timed_out`. When it finally reports the real `succeeded` result, that late correction
+  // must be applied — otherwise setWorkspaceBranch never runs, the row keeps the old
+  // (deleted) branch, the worktree sits on `-N`, and every later preview reports `missing`
+  // → the lane degrades into a silent previewUnavailable strand (A5). The merge already
+  // happened, so there is no double-land hazard: applying the result only reconciles state.
+  if (type === "workspace.merge" && from === "timed_out" && to === "succeeded") return true;
   return false;
 }
 
@@ -162,16 +171,34 @@ export function findLatestCommandByCorrelation(type: string, correlationId: stri
   return row ? rowToCommand(row) : null;
 }
 
-export function countInFlightSpawnCommands(parentId: string): number {
+// #1034 — count a parent's still-in-flight spawn commands, EXCLUDING any whose child has
+// already registered as a live agent. Spawn commands settle to a terminal status
+// asynchronously (the orchestrator reports back AFTER the child registers), so between
+// registration and settlement a child is otherwise double-counted: once by
+// `countLiveSpawnedAgents` (ready=1) and once here (command still running). Combined into
+// `occupied = live + inFlight`, that transient over-count could push a parent at its quota
+// boundary over the limit and spuriously reject a concurrent spawn — which then "succeeded
+// seconds later" once the command settled. The `NOT EXISTS` dedup mirrors the live-child
+// liveness predicate in `countLiveSpawnedAgents` (and the display-side dedup already in
+// relay_my_agents) so each child counts exactly once.
+export function countInFlightSpawnCommands(parentId: string, now: number = Date.now()): number {
   const row = getDb()
     .query(
       `SELECT count(*) AS n
-       FROM commands
-       WHERE type = 'agent.spawn'
-         AND status IN (${SPAWN_IN_FLIGHT_STATUSES.map(() => "?").join(",")})
-         AND json_extract(params, '$.spawnedBy') = ?`,
+       FROM commands c
+       WHERE c.type = 'agent.spawn'
+         AND c.status IN (${SPAWN_IN_FLIGHT_STATUSES.map(() => "?").join(",")})
+         AND json_extract(c.params, '$.spawnedBy') = ?
+         AND NOT EXISTS (
+           SELECT 1 FROM agents a
+           WHERE a.spawned_by = ?
+             AND a.status NOT IN ('offline', 'stale')
+             AND a.ready = 1
+             AND a.last_seen > ?
+             AND json_extract(a.meta, '$.spawnRequestId') = coalesce(json_extract(c.params, '$.spawnRequestId'), c.correlation_id)
+         )`,
     )
-    .get(...SPAWN_IN_FLIGHT_STATUSES, parentId) as { n: number };
+    .get(...SPAWN_IN_FLIGHT_STATUSES, parentId, parentId, now - STALE_TTL_MS) as { n: number };
   return row.n;
 }
 
@@ -244,11 +271,38 @@ export function deleteCommand(id: string): boolean {
   return true;
 }
 
-export function expireCommands(now: number = Date.now()): Command[] {
-  const rows = getDb()
+// #1025 A6 — sweep both claimed/active leases past their deadline AND pending commands
+// whose target orchestrator is permanently gone. Pending commands are normally left for a
+// busy host to poll (#930/#953), but a `workspace.merge` (or `agent.spawn`) whose target
+// host was decommissioned / re-registered under a new agent id will NEVER poll again — the
+// command lingers forever, `recoverAgedInFlightWorkspaces` files the workspace under
+// `stillActive` indefinitely, and the parked worker waits on a `landed-success` that can't
+// fire. The `isTargetGone` predicate (supplied by the caller, which knows agent liveness)
+// gates the pending sweep so a merely-busy host is untouched; a gone target's expired
+// pending command is timed out, then settled → the workspace returns to review_requested
+// and re-schedules, and the spawn parent is told. Opt-in: callers without the predicate
+// keep the historical claimed/active-only behavior.
+export function expireCommands(
+  now: number = Date.now(),
+  opts: { isTargetGone?: (command: Command) => boolean } = {},
+): Command[] {
+  const activeRows = getDb()
     .query(`SELECT * FROM commands WHERE expires_at IS NOT NULL AND expires_at <= ? AND status IN (${CLAIMED_ACTIVE_STATUSES.map(() => "?").join(",")})`)
     .all(now, ...CLAIMED_ACTIVE_STATUSES) as CommandRow[];
-  for (const row of rows) updateCommand(row.id, { status: "timed_out", error: "command timed out" });
+  let pendingRows: CommandRow[] = [];
+  if (opts.isTargetGone) {
+    const candidates = getDb()
+      .query(`SELECT * FROM commands WHERE expires_at IS NOT NULL AND expires_at <= ? AND status = 'pending'`)
+      .all(now) as CommandRow[];
+    pendingRows = candidates.filter((row) => opts.isTargetGone!(rowToCommand(row)));
+  }
+  const rows = [...activeRows, ...pendingRows];
+  for (const row of rows) {
+    updateCommand(row.id, {
+      status: "timed_out",
+      error: row.status === "pending" ? "command target gone; expired before dispatch" : "command timed out",
+    });
+  }
   return rows.map((row) => getCommand(row.id)).filter((command): command is Command => Boolean(command));
 }
 

package/src/config-store.ts

@@ -9,6 +9,7 @@ import {
   validateNotificationsConfig,
 } from "./notification-settings";
 import { DEFAULT_SELF_RESUME_CONFIG, validateSelfResumeConfig } from "./self-resume-config";
+import { RETENTION_NAMESPACE, validateRetentionConfig } from "./retention-config";
 import { TEAM_TEMPLATE_NAMESPACE, validateTeamTemplate } from "./team-template-config";
 import { PROJECT_INSTRUCTION_POLICY_NAMES } from "./project-instructions";
 import { renderTemplate } from "./prompt-resolver";
@@ -674,6 +675,7 @@ function normalizeValue(namespace: string, key: string, value: unknown): unknown
   if (namespace === SELF_RESUME_NAMESPACE) return validateSelfResumeConfig(value);
   if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
   if (namespace === LANDING_NAMESPACE) return validateLandingConfig(value);
+  if (namespace === RETENTION_NAMESPACE) return validateRetentionConfig(value);
   if (namespace === TEAM_TEMPLATE_NAMESPACE) return validateTeamTemplate(key, value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
   return value;