agent-relay-server 0.28.0 → 0.30.0

package/runner/src/adapter.ts

@@ -174,7 +174,7 @@ export function profileAllowsRelayFeature(config: RunnerSpawnConfig, feature: ke
 
 export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present you can stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
 
-const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
+export const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
 
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;

package/runner/src/config.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join, resolve } from "node:path";
-import { stringValue } from "agent-relay-sdk";
+import { DEFAULT_RELAY_URL, stringValue } from "agent-relay-sdk";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { ProviderConfig } from "./adapter";
 
@@ -15,8 +15,6 @@ interface LoadedProviderConfig extends ProviderConfig {
   path: string;
 }
 
-const DEFAULT_RELAY_URL = "http://127.0.0.1:4850";
-
 function agentRelayHome(): string {
   return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
 }

package/src/agent-branch-state.ts

@@ -0,0 +1,36 @@
+// Branch-state enrichment for the agent payload (#236). The single server-side
+// place that hangs the derived `branchState` (+ owning `branchWorkspaceId`) onto an
+// AgentCard before it leaves over the API or SSE — so the dashboard never recomputes
+// it and the projection can't drift between surfaces. The mapping itself lives in
+// deriveBranchState (workspace-phase.ts, pure & CLI-importable); this module is just
+// the agent↔workspace join.
+
+import { listWorkspaces, ownedIsolatedWorkspace } from "./db";
+import type { AgentCard, WorkspaceRecord } from "./types";
+import { deriveBranchState, isLiveIsolatedWorkspace } from "./workspace-phase";
+
+function withWorkspace(agent: AgentCard, workspace: WorkspaceRecord | undefined): AgentCard {
+  const branchState = deriveBranchState(workspace);
+  if (!branchState || !workspace) return agent;
+  return { ...agent, branchState, branchWorkspaceId: workspace.id };
+}
+
+/** Enrich a single agent with its branch-state badge fields (one workspace query). */
+export function attachBranchState(agent: AgentCard): AgentCard {
+  return withWorkspace(agent, ownedIsolatedWorkspace(agent.id));
+}
+
+/**
+ * Batched enrichment for list endpoints: one workspace scan, mapped by owner, so a
+ * fleet of N agents costs a single query instead of N. listWorkspaces is ORDER BY
+ * updated_at DESC, so the first live isolated workspace seen per owner is the most
+ * recent one — same selection as ownedIsolatedWorkspace.
+ */
+export function attachBranchStates(agents: AgentCard[]): AgentCard[] {
+  const byOwner = new Map<string, WorkspaceRecord>();
+  for (const ws of listWorkspaces()) {
+    if (!ws.ownerAgentId || !isLiveIsolatedWorkspace(ws)) continue;
+    if (!byOwner.has(ws.ownerAgentId)) byOwner.set(ws.ownerAgentId, ws);
+  }
+  return agents.map((agent) => withWorkspace(agent, byOwner.get(agent.id)));
+}

package/src/agent-ref.ts

@@ -12,16 +12,16 @@
 // never silently picks among several — it reports candidates instead.
 
 import { STALE_TTL_MS } from "./config";
-import type { AgentCard } from "./types";
+import type { AgentCard, Message } from "./types";
 
-export interface ResolveOptions {
+interface ResolveOptions {
   /** Exclude this agent id from matches (e.g. the requester, when pairing). */
   excludeId?: string;
   /** Clock injection for tests. */
   now?: number;
 }
 
-export type ResolveResult =
+type ResolveResult =
   | { status: "resolved"; agent: AgentCard }
   | { status: "ambiguous"; candidates: AgentCard[] }
   | { status: "not_found"; offlineMatches: AgentCard[] };
@@ -121,6 +121,23 @@ export function resolveAgentRef(ref: string, agents: AgentCard[], opts: ResolveO
   return { status: "not_found", offlineMatches: matches };
 }
 
+export function targetMatchesAgent(target: string, agentId: string, agent?: AgentCard | null): boolean {
+  if (!agent) return false;
+  if (target === agentId || target === "broadcast") return true;
+  if (target.startsWith("tag:") && agent.tags.includes(target.slice(4))) return true;
+  if (target.startsWith("cap:") && agent.capabilities.includes(target.slice(4))) return true;
+  if (target.startsWith("label:") && agent.label === target.slice(6)) return true;
+  return false;
+}
+
+export function messageMatchesAgent(msg: Message, agentId: string, agent?: AgentCard | null): boolean {
+  if (!agent) return false;
+  if (msg.claimable && msg.claimedBy && msg.claimedBy !== agentId) return false;
+  if (msg.resolvedToAgent === agentId) return true;
+  if (msg.to === agentId || msg.from === agentId) return true;
+  return targetMatchesAgent(msg.to, agentId, agent);
+}
+
 // --- messaging send planning -------------------------------------------------
 
 export interface DeliveryReceipt {
@@ -136,7 +153,7 @@ export interface DeliveryReceipt {
   reason?: string;
 }
 
-export type SendPlan =
+type SendPlan =
   // resolved/fan-out/passthrough carry the (possibly rewritten) canonical `to`
   | { kind: "direct" | "fanout" | "passthrough"; to: string; receipt: DeliveryReceipt }
   | { kind: "not_found"; message: string }

package/src/branch-landed.ts

@@ -18,6 +18,13 @@ export interface BranchLandedInput {
   subject?: string;
   /** Fresh branch the worktree was recycled onto (land-and-continue), if any. */
   newBranch?: string;
+  /**
+   * Whether the advanced base was pushed to its remote. `false` means the land is
+   * local-only (push disabled, or the base has no upstream) and has NOT reached
+   * `origin` yet — the notice says so instead of implying a published merge (#285).
+   * `undefined` from older orchestrators that don't report it → message stays generic.
+   */
+  pushed?: boolean;
 }
 
 /**
@@ -47,6 +54,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       subject: input.subject,
       author: workspace.ownerAgentId,
       newBranch: input.newBranch,
+      pushed: input.pushed,
     },
   });
 
@@ -65,8 +73,14 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
     sha: input.mergedSha,
     author,
     newBranch: input.newBranch,
+    pushed: input.pushed,
   };
 
+  // A local-only land (push disabled, or base has no upstream) has NOT reached the
+  // remote — say so rather than implying a published merge an agent would report as
+  // shipped (#285). `undefined` (older orchestrators) keeps the message generic.
+  const publishLabel = input.pushed === false ? ` Not yet pushed to \`origin/${base}\` — local only.` : "";
+
   // The branch author cares most — push regardless of online (store-ahead delivers it on
   // next poll if they've moved on, #234). They land-and-continue onto the recycled branch.
   if (author) {
@@ -76,7 +90,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       : " Worktree reclaimed.";
     notifySystemMessage(author, {
       subject: "Your branch landed",
-      body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${continueLabel}`,
+      body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}${continueLabel}`,
       payload,
       replyExpected: false,
     });
@@ -92,7 +106,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
   for (const agent of agentsOnMain(workspace.repoRoot, author)) {
     notifySystemMessage(agent.id, {
       subject: `Merged to ${base}`,
-      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.`,
+      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
       payload,
       replyExpected: false,
     });

package/src/bus.ts

@@ -7,6 +7,7 @@ import { emitCommandEvent } from "./command-events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { noteAgentTimelineEvent, noteCompactionCommandCompleted } from "./compaction-watch";
 import { applyCommandToRecipe } from "./recipe-runner";
+import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import {
   BusProtocolError,
   parseBusFrame,
@@ -465,11 +466,11 @@ function broadcastRelayEvent(event: RelayEvent): void {
 function connectionWantsEvent(conn: BusConnection, event: RelayEvent): boolean {
   if (!matchesSubscription(conn.subscriptions, event.type)) return false;
   if (event.type === "message.new" && conn.agentId) {
-    return messageMatchesAgent(event.data as unknown as Message, conn.agentId);
+    return messageMatchesAgent(event.data as unknown as Message, conn.agentId, getAgent(conn.agentId));
   }
   if (event.type.startsWith("task.") && conn.agentId) {
     const target = typeof event.data.target === "string" ? event.data.target : "";
-    return targetMatchesAgent(target, conn.agentId);
+    return targetMatchesAgent(target, conn.agentId, getAgent(conn.agentId));
   }
   if (event.type.startsWith("command.")) {
     const command = isRecord(event.data.command) ? event.data.command : undefined;
@@ -490,25 +491,6 @@ function matchesSubscription(subscriptions: Set<string>, eventType: string): boo
   return false;
 }
 
-function messageMatchesAgent(msg: Message, agentId: string): boolean {
-  const agent = getAgent(agentId);
-  if (!agent) return false;
-  if (msg.claimable && msg.claimedBy && msg.claimedBy !== agentId) return false;
-  if (msg.resolvedToAgent === agentId) return true;
-  if (msg.to === agentId || msg.from === agentId) return true;
-  return targetMatchesAgent(msg.to, agentId, agent);
-}
-
-function targetMatchesAgent(target: string, agentId: string, knownAgent?: AgentCard): boolean {
-  const agent = knownAgent ?? getAgent(agentId);
-  if (!agent) return false;
-  if (target === agentId || target === "broadcast") return true;
-  if (target.startsWith("tag:") && agent.tags.includes(target.slice(4))) return true;
-  if (target.startsWith("cap:") && agent.capabilities.includes(target.slice(4))) return true;
-  if (target.startsWith("label:") && agent.label === target.slice(6)) return true;
-  return false;
-}
-
 function outboxToPayload(event: BusEvent) {
   return {
     seq: event.seq,

package/src/cli.ts

@@ -44,7 +44,7 @@ import {
 } from "./upgrade";
 import { formatMemoryBrokerSmokeResult, runMemoryBrokerSmoke } from "./memory-broker-smoke";
 import { MAX_BODY_BYTES, VERSION } from "./config";
-import { DEFAULT_CONTEXT_PROBE_STATE_DIR, runContextProbe } from "agent-relay-sdk/context-probe";
+import { runContextProbe } from "agent-relay-sdk/context-probe";
 import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
@@ -686,7 +686,7 @@ async function handleContextProbeCommand(args: string[]): Promise<void> {
   let wrapCommand: string | undefined;
   let wrapRequested = false;
   let agentId: string | undefined;
-  let stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR;
+  let stateDir: string | undefined;
   let standalone = false;
 
   for (let i = 0; i < inputArgs.length; i++) {
@@ -718,7 +718,7 @@ async function handleContextProbeCommand(args: string[]): Promise<void> {
       "context-probe",
       ...(wrapRequested ? ["--wrap", ...(wrapCommand ? [shellQuote(wrapCommand)] : [])] : ["--standalone"]),
       ...(agentId ? ["--agent-id", shellQuote(agentId)] : []),
-      ...(stateDir !== DEFAULT_CONTEXT_PROBE_STATE_DIR ? ["--state-dir", shellQuote(stateDir)] : []),
+      ...(stateDir ? ["--state-dir", shellQuote(stateDir)] : []),
     ].join(" ");
     console.log(command);
     return;

package/src/contracts.ts

@@ -21,7 +21,7 @@ export interface RuntimePackageMetadata {
   version: string;
 }
 
-export interface ContractRequirement {
+interface ContractRequirement {
   min: number;
   maxExclusive: number;
 }

package/src/db.ts

@@ -1,8 +1,9 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "./config.ts";
 import { parseJson } from "./utils";
+import { isLiveIsolatedWorkspace } from "./workspace-phase";
 import {
   CONTRACT_REQUIREMENTS,
   contractCompatibility,
@@ -4331,7 +4332,7 @@ function messageRequiresReply(message: Message): boolean {
   // Server-owned notification flag (#283) wins over every kind/sender heuristic below: an
   // explicit replyExpected:false is a fire-and-forget message that must never become an obligation.
   if (message.replyExpected === false) return false;
-  if (message.kind === "system" || message.kind === "control" || message.kind === "session") return false;
+  if (isMechanicalMessageKind(message.kind)) return false;
   if (message.from === "user") return true;
   if (message.kind === "task" || message.kind === "channel.event") return true;
   return Boolean(message.payload?.source);
@@ -4793,7 +4794,7 @@ export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
 // Message → category, the ONE place this mapping lives (server-side SQL). Order is
 // significant: a claimable/system/pair/channel message is classified as such even
 // when it is also a reply; only an otherwise-plain reply counts as "Replies".
-export const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
+const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
 export type AnalyticsCategory = (typeof ANALYTICS_CATEGORIES)[number];
 const ANALYTICS_CATEGORY_SQL = `
   CASE
@@ -5281,20 +5282,24 @@ function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceRecord |
     // preserved and metadata is merged, not replaced.
     const existing = getWorkspace(workspace.id);
     const preserveStatus = existing != null && existing.status !== "active";
-    // The branch (and advanced base) change ONLY via the relay's own land-and-continue
-    // recycle (setWorkspaceBranch repoints to `<branch>-N` and bumps base_sha). The
-    // runner keeps re-reporting its spawn-time branch on every heartbeat, and the
-    // recycle returns status to "active" — so without this the next heartbeat clobbers
-    // the repoint back to the original branch, and the next land targets a deleted
-    // branch and strands the work (vent #62 follow-up). Trust the existing row's
-    // branch/base over registration; only a brand-new row takes the runner's values.
+    // The branch and base change ONLY via the relay's own land-and-continue recycle
+    // (setWorkspaceBranch repoints to `<branch>-N` and bumps base_sha; base_ref is fixed
+    // at spawn and never re-targeted). The runner keeps re-reporting its spawn-time
+    // branch/base on every heartbeat, and the recycle returns status to "active" — so
+    // without this the next heartbeat clobbers the repoint back to the original branch,
+    // and the next land targets a deleted branch and strands the work (vent #62 follow-up).
+    // baseRef needs the same pin: a heartbeat carrying a stale/wrong base (e.g. a recycled
+    // `-N` branch when the agent was spawned from inside a managed worktree) would otherwise
+    // overwrite the true base, and the next land advances a local-only branch that never
+    // reaches origin/main (#285). Trust the existing row's branch/base over registration;
+    // only a brand-new row takes the runner's values.
     return upsertWorkspace({
       id: workspace.id,
       repoRoot: workspace.repoRoot,
       sourceCwd: workspace.sourceCwd ?? agent.cwd,
       worktreePath: workspace.worktreePath,
       branch: existing?.branch ?? workspace.branch,
-      baseRef: workspace.baseRef,
+      baseRef: existing?.baseRef ?? workspace.baseRef,
       baseSha: existing?.baseSha ?? workspace.baseSha,
       mode: workspace.mode,
       requestedMode: workspace.requestedMode,
@@ -5394,6 +5399,14 @@ export function deleteWorkspace(id: string): boolean {
   return db.query("DELETE FROM workspaces WHERE id = ?").run(id).changes > 0;
 }
 
+// The agent's current branch worktree: its most recent live (non-terminal) isolated
+// workspace, or undefined. SINGLE HOME for the agent→workspace link — the MCP
+// owner-resolver and the #236 branch-state badge both go through here. listWorkspaces
+// is ORDER BY updated_at DESC, so `.find` returns the most recently active one.
+export function ownedIsolatedWorkspace(agentId: string): WorkspaceRecord | undefined {
+  return listWorkspaces({ ownerAgentId: agentId }).find(isLiveIsolatedWorkspace);
+}
+
 // Shared-mode rows are pure occupancy markers (no worktree on disk) that only
 // mean something while their owner is online. Deletion is normally driven by
 // the reaper's onAgentDisappeared hook, but agents also leave via clean
@@ -5416,6 +5429,26 @@ export function pruneOrphanedSharedWorkspaces(): string[] {
   })();
 }
 
+// Late-bound listeners for "a workspace row changed in a way that may change its
+// owner's branch-state badge" (#236). A hook, not a direct emit, because db.ts is
+// the lowest layer — sse.ts imports db, so db can't import sse without a cycle. sse
+// registers a listener at startup that re-emits the owner agent's status over SSE.
+type WorkspaceChangeListener = (workspace: WorkspaceRecord) => void;
+const workspaceChangeListeners = new Set<WorkspaceChangeListener>();
+export function onWorkspaceChange(listener: WorkspaceChangeListener): void {
+  workspaceChangeListeners.add(listener);
+}
+export function emitWorkspaceChange(workspace: WorkspaceRecord | null | undefined): void {
+  if (!workspace) return;
+  for (const listener of workspaceChangeListeners) {
+    try {
+      listener(workspace);
+    } catch {
+      // A badge-refresh listener must never break a workspace write.
+    }
+  }
+}
+
 export function updateWorkspaceStatus(id: string, status: WorkspaceStatus, metadata: Record<string, unknown> = {}): WorkspaceRecord | null {
   const existing = getWorkspace(id);
   if (!existing) return null;
@@ -5434,7 +5467,11 @@ export function updateWorkspaceStatus(id: string, status: WorkspaceStatus, metad
     id,
   );
   electWorkspaceStewards(existing.repoRoot);
-  return getWorkspace(id);
+  const updated = getWorkspace(id);
+  // Every status transition can flip the owner's badge (active→ready→steward→merged),
+  // so refresh it regardless of caller. Fires on the row's CURRENT owner.
+  emitWorkspaceChange(updated);
+  return updated;
 }
 
 // Repoint a workspace row at a recycled branch after a land-and-continue merge
@@ -5453,7 +5490,7 @@ export function setWorkspaceBranch(id: string, branch: string, baseSha?: string)
 // of these is a candidate steward; the repo is worth coordinating.
 const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
 
-export interface RepoStewardRecord {
+interface RepoStewardRecord {
   repoRoot: string;
   stewardAgentId?: string;
   lastStewardAgentId?: string;
@@ -5570,7 +5607,7 @@ function electWorkspaceStewardsForAgent(agentId: string): void {
 
 // --- Per-repo merge serialization lease (issue #157) -----------------------
 
-export interface MergeLeaseRecord {
+interface MergeLeaseRecord {
   repoRoot: string;
   workspaceId: string;
   commandId?: string;

package/src/http-body.ts

@@ -1,5 +1,5 @@
 /** Concatenate body chunks into a single contiguous Uint8Array. */
-export function concatBytes(chunks: Uint8Array[]): Uint8Array {
+function concatBytes(chunks: Uint8Array[]): Uint8Array {
   const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
   const output = new Uint8Array(total);
   let offset = 0;

package/src/insights-db.ts

@@ -46,7 +46,7 @@ function rowToObservation(row: ObservationRow): InsightObservation {
   };
 }
 
-export interface RecordObservationInput {
+interface RecordObservationInput {
   sessionId: string;
   agentId?: string;
   project?: string;
@@ -99,7 +99,7 @@ export function getObservation(id: number): InsightObservation | null {
   return row ? rowToObservation(row) : null;
 }
 
-export interface ListObservationsQuery {
+interface ListObservationsQuery {
   project?: string;
   signal?: string;
   sessionId?: string;

package/src/lifecycle-manager.ts

@@ -8,6 +8,7 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
+import { emitMessageDeliveryUpdated } from "./sse";
 import { emitCommandEvent } from "./command-events";
 import { buildManagedSpawnParams } from "./managed-policy";
 import { generateSpawnRequestId } from "./spawn-command";
@@ -95,6 +96,9 @@ export class LifecycleManager {
         subject: `policy:${meta.policyName}`,
         data: { policyName: meta.policyName, agentId, messageIds: available.map((message) => message.id), count: available.length },
       });
+      // queued → pending changed delivery_status; refresh the dashboard delivery
+      // badge now rather than letting it sit stale until the next poll (#265).
+      for (const message of available) emitMessageDeliveryUpdated(message);
     }
   }
 

package/src/maintenance.ts

@@ -19,6 +19,7 @@ import {
   pruneOfflineAgents,
   pruneOldMessages,
   deleteWorkspace,
+  emitWorkspaceChange,
   pruneOrphanedSharedWorkspaces,
   reapStaleAgents,
   reapStaleOrchestrators,
@@ -34,7 +35,7 @@ import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
-import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { deriveBranchState, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
 import { ensureRepoSteward } from "./steward";
@@ -583,6 +584,20 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
 
     const meta = ws.metadata as Record<string, unknown>;
 
+    // #236: stash the latest ahead/dirty counts so deriveBranchState can tell idle
+    // (⚪) from changes (🟡) for an active worktree — the relay isn't in the git
+    // path, so this scan is its only window onto the tree. Only write (and refresh
+    // the owner's badge) when the derived state actually flips, to avoid SSE churn
+    // every 2 min on unchanged workspaces. Status-changing branches below own their
+    // own badge refresh via updateWorkspaceStatus.
+    const nextAhead = p.ahead ?? 0;
+    const nextDirty = p.dirtyCount ?? 0;
+    if (meta.gitAhead !== nextAhead || meta.gitDirtyCount !== nextDirty) {
+      const before = deriveBranchState(ws);
+      const patched = patchWorkspaceMetadata(ws.id, { gitAhead: nextAhead, gitDirtyCount: nextDirty, gitProbedAt: Date.now() });
+      if (patched && deriveBranchState(patched) !== before) emitWorkspaceChange(patched);
+    }
+
     // Landing wins over everything else. Once the work is in base — whether the
     // PR was squash/cherry-pick merged on GitHub or fast-forwarded locally — the
     // workspace is done, even if `git merge-tree` still predicts a textual

package/src/managed-policy.ts

@@ -20,7 +20,7 @@ export function effectiveManagedPolicyWorkspaceMode(policy: SpawnPolicy): Worksp
   return policy.binding?.type === "channel" ? "shared" : "inherit";
 }
 
-export interface ManagedSpawnContext {
+interface ManagedSpawnContext {
   createdBy: string;
   requestedAt?: number;
 }

package/src/mcp.ts

@@ -23,6 +23,7 @@ import {
   linkArtifact,
   listAgents,
   listWorkspaces,
+  ownedIsolatedWorkspace,
   searchAgents,
   type AgentSearchFilter,
   type AgentSearchSort,
@@ -45,7 +46,7 @@ import {
 } from "./security";
 import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
 import { applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
-import { describeWorkspacePhase, landReceipt, readyContract, TERMINAL_WORKSPACE_STATUSES, worktreeMcpInstructions } from "./workspace-phase";
+import { describeWorkspacePhase, landReceipt, readyContract, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
@@ -964,7 +965,7 @@ function resolveWorkspaceForCaller(auth: McpAuthContext, args: Record<string, un
 function callerIsolatedWorkspace(auth: McpAuthContext): WorkspaceRecord | undefined {
   const caller = callerAgentId(auth);
   if (!caller) return undefined;
-  return listWorkspaces({ ownerAgentId: caller }).find((w) => w.mode === "isolated" && !TERMINAL_WORKSPACE_STATUSES.has(w.status));
+  return ownedIsolatedWorkspace(caller);
 }
 
 async function relayWorkspaceStatus(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {

package/src/notify.ts

@@ -2,7 +2,7 @@ import { sendMessage } from "./db";
 import { emitNewMessage } from "./sse";
 import type { Message, MessageKind } from "./types";
 
-export interface SystemNotifyOptions {
+interface SystemNotifyOptions {
   subject?: string;
   body: string;
   payload?: Record<string, unknown>;

package/src/orchestrator-lookup.ts

@@ -1,6 +1,6 @@
 import { listOrchestrators } from "./db";
 
-export interface ManagedAgentMatch {
+interface ManagedAgentMatch {
   agentId?: string;
   sessionName?: string;
   tmuxSession?: string;

package/src/routes.ts

@@ -160,10 +160,11 @@ import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES
 import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, parseRuntimePackage, type RuntimeCapabilities, type RuntimeContracts, type RuntimePackageMetadata } from "./contracts";
 import { listHostDirectories } from "./agent-spawn";
 import { planSend } from "./agent-ref";
+import { attachBranchState, attachBranchStates } from "./agent-branch-state";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER, isMechanicalMessageKind, isReservedAgentId } from "agent-relay-sdk";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
@@ -1282,7 +1283,13 @@ const postAgent: Handler = async (req) => {
         const available = resolveQueuedPolicyMessages(policyName, agent.id);
         if (available.length) {
           emitMessageAvailable(policyName, agent.id, available);
-          for (const message of available) emitNewMessage(message);
+          for (const message of available) {
+            emitNewMessage(message);
+            // queued → pending flips delivery_status; the dashboard dedups message.new
+            // by id (the message already shows as "queued"), so without an explicit
+            // delivery_updated the badge stays stale until the next poll (#265).
+            emitMessageDeliveryUpdated(message);
+          }
         }
       }
     }
@@ -1321,7 +1328,7 @@ const getAgents: Handler = (req) => {
   const tag = url.searchParams.get("tag") ?? undefined;
   const machine = url.searchParams.get("machine") ?? undefined;
   const status = url.searchParams.get("status") ?? undefined;
-  return json(listAgents({ tag, machine, status }));
+  return json(attachBranchStates(listAgents({ tag, machine, status })));
 };
 
 const findAgents: Handler = (req) => {
@@ -1355,7 +1362,7 @@ const postRouteAdvice: Handler = async (req) => {
 
 const getAgentById: Handler = (_req, params) => {
   const agent = getAgent(params.id!);
-  return agent ? json(agent) : error("agent not found", 404);
+  return agent ? json(attachBranchState(agent)) : error("agent not found", 404);
 };
 
 const getAgentReplyObligations: Handler = (_req, params) => {
@@ -4489,8 +4496,12 @@ const patchCommand: Handler = async (req, params) => {
           // Repoint the row so the next merge targets the live branch, not the deleted one.
           const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
           const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
+          // base_sha tracks the tip the recycled workspace forks from. On a no-ff land
+          // (#287) that's the merge commit (result.baseSha), not the preserved landed
+          // commit (mergedSha); fall back to mergedSha for older orchestrators.
+          const baseSha = cleanString(command.result.baseSha, "result.baseSha", { max: 64 });
           if (newBranch) {
-            setWorkspaceBranch(workspaceId, newBranch, mergedSha);
+            setWorkspaceBranch(workspaceId, newBranch, baseSha ?? mergedSha);
           }
           // #239 — push the author a "your branch landed" notice (no polling). Only on a
           // real land; a no-op resolution (#230) merged nothing, so it earns no notice.
@@ -4500,6 +4511,7 @@ const patchCommand: Handler = async (req, params) => {
               mergedSha,
               subject: cleanString(command.result.subject, "result.subject", { max: 200 }),
               newBranch,
+              pushed: typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
             });
           }
         }
@@ -5181,9 +5193,20 @@ const postMessage: Handler = async (req) => {
     }
     applyReplyRouting(input);
     if (!input.to) return error("to is required (or provide replyTo to auto-route)");
+    // Mechanical lifecycle/observability posts (system/control/session) addressed to a
+    // reserved sink ("user"/"system") are the relay's own lane, not agent-directed
+    // messaging. A managed token's recipient constraints (targets/policies/agents) gate
+    // which *agents* it may message — they must NOT gate a session-mirror capture to the
+    // reserved sink, or constrained tokens (telegram policy, codex steward) 403 → the
+    // runner's outbox retries 12× and poisons the record → the dashboard silently loses
+    // the turn (#284, same outbox-poison failure mode as #184). The message:send scope
+    // and any channel constraint still apply; we only drop the target/agentId predicate.
+    const reservedSinkPost = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
     const denied = authorizeRoute(req, {
       scope: "message:send",
-      resource: { target: input.to, channel: input.channel, agentId: input.from },
+      resource: reservedSinkPost
+        ? { channel: input.channel }
+        : { target: input.to, channel: input.channel, agentId: input.from },
     });
     if (denied) return denied;
     // Resolve the target through the shared planner — the SAME matcher the MCP send tool
@@ -5198,8 +5221,7 @@ const postMessage: Handler = async (req) => {
     // "session" = observed assistant turn (Phase 1 live-session lane). It is captured
     // from the provider transcript and stored for the dashboard chat; it must persist
     // regardless of target liveness and never be re-delivered into a session.
-    const bypassKinds = ["system", "control", "session"];
-    if (!bypassKinds.includes(input.kind ?? "")) {
+    if (!isMechanicalMessageKind(input.kind)) {
       const plan = planSend(input.to, listAgents());
       if (plan.kind === "ambiguous") return error(plan.message, 409);
       if (plan.kind !== "not_found") input.to = plan.to;
@@ -5249,7 +5271,7 @@ const postMessage: Handler = async (req) => {
 };
 
 function automaticMemoryTarget(message: { to: string; resolvedToAgent?: string; kind: string }): string | null {
-  if (message.kind === "system" || message.kind === "control" || message.kind === "session") return null;
+  if (isMechanicalMessageKind(message.kind)) return null;
   const target = message.resolvedToAgent ?? message.to;
   if (!isDirectTarget(target)) return null;
   const agent = getAgent(target);