agent-relay-server 0.36.2 → 0.38.0

package/src/agent-ref.ts

@@ -12,7 +12,7 @@
 // never silently picks among several — it reports candidates instead.
 
 import { STALE_TTL_MS } from "./config";
-import type { AgentCard, Message } from "./types";
+import type { AgentCard, Message, TokenConstraints } from "./types";
 
 interface ResolveOptions {
   /** Exclude this agent id from matches (e.g. the requester, when pairing). */
@@ -255,6 +255,33 @@ export function planSend(to: string, agents: AgentCard[], opts: ResolveOptions =
   return { kind: "not_found", message: notFoundMessage(target, agents) };
 }
 
+/**
+ * THE caller-identity resolver: the agent id behind a token's signed constraints, for
+ * `from`-autofill, whoami, and spawn/shutdown gating (#221/#243/#323). Two cases, in order:
+ *   - an identity-bearing token (`constraints.agents` with a single id) → that id, no db.
+ *   - a managed/spawned agent's runner token (no `agents` constraint, but a single
+ *     `spawnRequestId` or `policy`) → matched back to its registered agent card.
+ * Returns undefined for admin/server tokens (no constraints → unrestricted by design) and
+ * multi-agent tokens. `getAgents` is LAZY — the live-agent scan runs only when a single
+ * spawnRequestId/policy actually needs resolving, so identity-bearing and admin tokens (and
+ * the hot registration path) pay no db cost. One home so the #243 "managed agents silently
+ * lose implicit identity" drift can't recur across the transport-convergence services.
+ */
+export function resolveCallerAgentId(
+  constraints: TokenConstraints | undefined,
+  getAgents: () => AgentCard[],
+): string | undefined {
+  const agents = constraints?.agents;
+  if (agents?.length === 1) return agents[0];
+  const spawnRequestId = constraints?.spawnRequestIds?.length === 1 ? constraints.spawnRequestIds[0] : undefined;
+  const policyName = constraints?.policies?.length === 1 ? constraints.policies[0] : undefined;
+  if (!spawnRequestId && !policyName) return undefined;
+  const match = getAgents().find((a) =>
+    (spawnRequestId !== undefined && a.meta?.spawnRequestId === spawnRequestId) ||
+    (policyName !== undefined && a.meta?.policyName === policyName));
+  return match?.id;
+}
+
 function fanoutReceipt(recipients: string[]): DeliveryReceipt {
   if (recipients.length === 0) return { delivered: false, expectReply: false, recipients: [], queued: true, reason: "no online members — queued" };
   return { delivered: true, expectReply: true, recipients };

package/src/automations.ts

@@ -487,7 +487,10 @@ function dispatchAutomationRun(automation: Automation, run: AutomationRun, now:
     if (automation.targetPolicy.mode === "existing_agent") {
       const agent = resolveExistingAgent(automation.targetPolicy, orchestrator);
       if (!agent && automation.targetPolicy.ifNoMatch !== "spawn") throw new ValidationError("no matching managed agent for automation");
-      if (agent) return createRunTask(automation, run, agent.id, now, { targetMode: "existing_agent" });
+      if (agent) {
+        const durableTarget = durableExistingAgentTarget(automation.targetPolicy);
+        return createRunTask(automation, run, durableTarget, now, { targetMode: "existing_agent", resolvedAgentId: agent.id });
+      }
       const fallbackPolicy: AutomationTargetPolicy = { mode: "on_demand_agent", provider: orchestrator.providers[0] ?? "codex", keepAlive: false };
       return dispatchOnDemandAutomation(automation, run, orchestrator, fallbackPolicy, now);
     }
@@ -582,7 +585,11 @@ function createRunTask(
   updateRun(run.id, {
     status: meta.targetMode === "on_demand_agent" ? "waiting_agent" : "running",
     startedAt: now,
-    targetAgentId: target.startsWith("label:") ? undefined : target,
+    targetAgentId: typeof meta.resolvedAgentId === "string"
+      ? meta.resolvedAgentId
+      : target.startsWith("label:") || target.startsWith("cap:")
+        ? undefined
+        : target,
     taskId: result.task.id,
     messageId: result.message?.id,
     meta,
@@ -590,6 +597,14 @@ function createRunTask(
   return { automation, run: getAutomationRun(run.id)!, task: result.task, message: result.message };
 }
 
+function durableExistingAgentTarget(policy: Extract<AutomationTargetPolicy, { mode: "existing_agent" }>): string {
+  const label = policy.selector.label?.trim();
+  if (label) return `label:${label}`;
+  const cap = policy.selector.capabilities?.find((item) => item.trim().length > 0)?.trim();
+  if (cap) return `cap:${cap}`;
+  throw new ValidationError("existing-agent automation target selector must include a label or capability");
+}
+
 function insertRun(automation: Automation, scheduledFor: number, now: number): AutomationRun {
   const id = randomUUID();
   db().query(`

package/src/bus.ts

@@ -1,11 +1,16 @@
 import type { Server, ServerWebSocket } from "bun";
-import { createActivityEvent, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, upsertAgent, validateAgentSession } from "./db";
+import { ValidationError, createActivityEvent, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
 import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
-import { createCommand, getCommand, updateCommand } from "./commands-db";
+import { getCommand, updateCommand } from "./commands-db";
 import { emitCommandEvent } from "./command-events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { noteAgentTimelineEvent, noteCompactionCommandCompleted } from "./compaction-watch";
+import { registerAgent } from "./services/register-agent";
+import { authContextFromBus } from "./services/auth-context";
+import { commandAuthorizationResource, dispatchCommand } from "./services/dispatch-command";
+import { ServiceAuthError } from "./services/errors";
+import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { applyCommandToRecipe } from "./recipe-runner";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import {
@@ -16,8 +21,8 @@ import {
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
 import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
-import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, resolveSpawnLineage, unauthorized } from "./security";
-import type { AgentCard, Command, ComponentToken, ContextState, Message, ProviderCapabilities, Task } from "./types";
+import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
+import type { AgentCard, Command, ComponentToken, ContextState, Message, ProviderCapabilities, RegisterAgentInput, Task } from "./types";
 
 interface BusSocketData {
   kind: "bus";
@@ -219,19 +224,42 @@ function handleCommandFrame(
     return;
   }
 
-  if (!busCommandAuthorized(conn, { target, params })) {
-    sendCommandResult(ws, frameId, "rejected", undefined, "component token lacks command scope");
+  // agent.shutdown converges on the shutdownAgent service (#342/#347): the #221 parent→child
+  // gate + canonical payload, identical to HTTP + MCP. The coarse command:write check above
+  // stays; the service adds the fine parent→child gate the bus path previously LACKED.
+  if (commandType === "agent.shutdown") {
+    if (conn.componentAuth && !isComponentAuthorizedFor(conn.componentAuth, { scope: "command:write", resource: commandAuthorizationResource({ target, params }) })) {
+      sendCommandResult(ws, frameId, "rejected", undefined, "component token lacks command scope");
+      return;
+    }
+    try {
+      const input = shutdownInputFromBusFrame(target, params, conn.agentId ?? conn.componentId);
+      const result = shutdownAgent(input, authContextFromBus(conn.componentAuth));
+      sendCommandResult(ws, frameId, "succeeded", { command: result.command });
+    } catch (e) {
+      if (e instanceof ShutdownAuthError) sendCommandResult(ws, frameId, "rejected", undefined, e.message);
+      else if (e instanceof ShutdownTargetError || e instanceof ValidationError) sendCommandResult(ws, frameId, "failed", undefined, e.message);
+      else throw e;
+    }
     return;
   }
 
-  const command = createCommand({
-    type: commandType,
-    source: conn.agentId ?? conn.componentId,
-    target,
-    params,
-  });
-  emitCommandEvent(command, "command.requested");
-  sendCommandResult(ws, frameId, "succeeded", { command });
+  // Dispatch through the shared service — it owns authorization (identical to the old
+  // busCommandAuthorized gate), createCommand, and the "command.requested" emit. The bus
+  // adapter only translates the typed ServiceAuthError into a rejected result frame.
+  try {
+    const command = dispatchCommand(
+      { type: commandType, source: conn.agentId ?? conn.componentId, target, params },
+      authContextFromBus(conn.componentAuth),
+    );
+    sendCommandResult(ws, frameId, "succeeded", { command });
+  } catch (e) {
+    if (e instanceof ServiceAuthError) {
+      sendCommandResult(ws, frameId, "rejected", undefined, "component token lacks command scope");
+      return;
+    }
+    throw e;
+  }
 }
 
 function busCommandAuthorized(
@@ -245,18 +273,6 @@ function busCommandAuthorized(
   });
 }
 
-function commandAuthorizationResource(command: Pick<Command, "target" | "params">) {
-  const params = isRecord(command.params) ? command.params : {};
-  return {
-    target: command.target,
-    agentId: stringValue(params.agentId) ?? command.target,
-    policyName: stringValue(params.policyName),
-    orchestratorId: stringValue(params.orchestratorId),
-    cwd: stringValue(params.cwd),
-    spawnRequestId: stringValue(params.spawnRequestId),
-  };
-}
-
 function handleRegister(ws: BusWebSocket, frame: RegisterFrame): void {
   const payload = frame.payload;
   const runnerManaged = payload.meta?.runnerManaged === true || typeof payload.meta?.runnerId === "string";
@@ -273,14 +289,16 @@ function handleRegister(ws: BusWebSocket, frame: RegisterFrame): void {
   if (payload.agentId) {
     const label = stringMeta(payload.meta, "label");
     const context = contextFromMeta(payload.meta);
-    // Authoritative parent lineage — spawned/managed agents register over THIS bus path, not the
-    // HTTP `postAgent` route, so `spawned_by` must be set here too or it stays NULL (breaking the
-    // parent→child shutdown gate, the `spawnedBy:` filter, and the live-children quota).
-    const lineage = resolveSpawnLineage(ws.data.componentAuth?.constraints);
-    const agent = upsertAgent({
+    // Thin transport: build the unified RegisterAgentInput from the wire frame and hand it to
+    // the registerAgent service. ALL registration side effects — authoritative parent lineage
+    // (resolved from the token constraints inside the service, never the wire body), the managed
+    // came-up-running reconcile, the status broadcast, the timeline note, the parent-wake (#351),
+    // and the audit row — live in src/services/register-agent.ts so this bus path can never drift
+    // from the HTTP path again (the #342 `spawned_by`-NULL class of bug).
+    const input: RegisterAgentInput = {
       id: payload.agentId,
       name: stringMeta(payload.meta, "name") ?? payload.componentId,
-      kind: payload.role === "integration" ? "provider" : payload.role,
+      kind: (payload.role === "integration" ? "provider" : payload.role) as RegisterAgentInput["kind"],
       ...(label ? { label } : {}),
       tags: payload.tags,
       machine: payload.machine,
@@ -290,17 +308,10 @@ function handleRegister(ws: BusWebSocket, frame: RegisterFrame): void {
       instanceId: payload.instanceId,
       ...(providerCapabilities ? { providerCapabilities } : {}),
       ...(context ? { context } : {}),
-      ...(lineage ? { spawnedBy: lineage } : {}),
       meta: payload.meta,
-    });
+    };
+    const agent = registerAgent(input, authContextFromBus(ws.data.componentAuth));
     epoch = agent.epoch;
-    getLifecycleManager().onAgentRegistered(agent.id, {
-      policyName: stringMeta(payload.meta, "policyName"),
-      spawnRequestId: stringMeta(payload.meta, "spawnRequestId"),
-      tmuxSession: stringMeta(payload.meta, "tmuxSession"),
-    });
-    noteAgentTimelineEvent(agent.id, agent.meta?.timelineEvent);
-    emitAgentStatusEvent(agent.id);
   }
 
   busConnections.set(ws.data.id, {

package/src/cli/index.ts

@@ -44,7 +44,7 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
-  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--auto-merge on-green|on-approval|manual] [--reviewer HANDLE] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
   agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
   agent-relay get-message <messageId> [--json|--body]

package/src/cli/workspace.ts

@@ -5,8 +5,11 @@ import { apiRequest } from "./_shared";
 import { detectAgentId } from "./agent-detect";
 import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "../workspace-phase";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
+import { AUTO_MERGE_POLICIES, resolveLandStrategy } from "../workspace-merge";
+import { getLandingConfig } from "../config-store";
+import type { WorkspaceAutoMergePolicy } from "../types";
 
-export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
+export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--auto-merge on-green|on-approval|manual] [--reviewer HANDLE] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
 
 // The agent's own isolated-workspace id, published in AGENT_RELAY_WORKSPACE_JSON
 // by the orchestrator at spawn. Undefined for shared-workspace / non-managed agents.
@@ -98,6 +101,8 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
 
   let id = currentWorkspaceId(), idExplicit = false; // idExplicit: --id was passed, not the ambient default (#307)
   let strategy: string | undefined;
+  let autoMerge: WorkspaceAutoMergePolicy | undefined;
+  let reviewer: string | undefined;
   let purpose: string | undefined;
   let repo: string | undefined;
   let execute = false;
@@ -109,6 +114,14 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
     const arg = args[i];
     if (arg === "--id" && i + 1 < args.length) { id = args[++i]; idExplicit = true; }
     else if (arg === "--strategy" && i + 1 < args.length) strategy = args[++i];
+    else if (arg === "--auto-merge" && i + 1 < args.length) {
+      const val = args[++i] as string;
+      if (!(AUTO_MERGE_POLICIES as readonly string[]).includes(val)) {
+        throw new Error(`--auto-merge must be one of: ${AUTO_MERGE_POLICIES.join(", ")}`);
+      }
+      autoMerge = val as WorkspaceAutoMergePolicy;
+    }
+    else if (arg === "--reviewer" && i + 1 < args.length) reviewer = args[++i];
     else if (arg === "--purpose" && i + 1 < args.length) purpose = args[++i];
     else if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
     else if (arg === "--execute") execute = true;
@@ -190,11 +203,31 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
   }
 
   const from = await detectAgentId();
+
+  // For the `land` action, resolve the effective strategy via the three-level chain
+  // (explicit > instance config > default) so a bare `land` with no --strategy still
+  // picks up the operator's landing.strategy setting. The strategy is passed verbatim
+  // to the server; requestWorkspaceMerge is the single resolution point for the default.
+  let resolvedStrategy: string | undefined = strategy;
+  if (action === "land") {
+    const instanceConfig = getLandingConfig();
+    resolvedStrategy = resolveLandStrategy({
+      explicit: strategy,
+      instanceStrategy: instanceConfig.strategy,
+    });
+  }
+
   const actionBody: Record<string, unknown> =
     action === "ready" ? { action: "request-review", agentId: from }
     : action === "claim" ? { action: "claim", agentId: from, purpose }
     : action === "release" ? { action: "release-claim", agentId: from }
-    : { action: "merge", agentId: from, ...(strategy ? { strategy } : {}) };
+    : {
+        action: "merge",
+        agentId: from,
+        ...(resolvedStrategy ? { strategy: resolvedStrategy } : {}),
+        ...(autoMerge ? { autoMerge } : {}),
+        ...(reviewer ? { reviewer } : {}),
+      };
   const result = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, actionBody);
   if (json) {
     console.log(JSON.stringify(result, null, 2));
@@ -210,6 +243,6 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
   console.log(
     action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
     : action === "release" ? `Workspace ${id} claim released.`
-    : `Workspace ${id} merge requested (${strategy ?? "auto"}).`,
+    : `Workspace ${id} merge requested (${resolvedStrategy ?? "auto"}${autoMerge ? `, autoMerge: ${autoMerge}` : ""}${reviewer ? `, reviewer: ${reviewer}` : ""}).`,
   );
 }

package/src/compaction-watch.ts

@@ -151,6 +151,13 @@ export function getCompactionWatch(): CompactionWatch {
   return singleton;
 }
 
+/** Test seam: stop and drop the singleton so each parity run starts with no
+ * armed watches. */
+export function __resetCompactionWatch(): void {
+  singleton?.stop();
+  singleton = null;
+}
+
 // Feed an agent's latched timelineEvent (from meta) to the watch. Called from
 // every path that updates an agent's meta — bus status/register frames and the
 // HTTP register route — so a real provider hook clears the watch regardless of

package/src/config-store.ts

@@ -8,6 +8,7 @@ import type {
   ConfigEntry,
   ConfigHistoryEntry,
   InsightsConfig,
+  LandingConfig,
   ManagedAgentState,
   ManagedAgentStatus,
   NotificationsConfig,
@@ -16,6 +17,7 @@ import type {
   SpawnProvider,
   StewardConfig,
   WorkspaceConfig,
+  WorkspaceLandingPolicy,
 } from "./types";
 
 const CONFIG_HISTORY_LIMIT = 50;
@@ -29,6 +31,9 @@ const NOTIFICATIONS_NAMESPACE = "notifications";
 const NOTIFICATIONS_KEY = "default";
 const WORKSPACE_NAMESPACE = "workspace";
 const WORKSPACE_KEY = "default";
+const LANDING_NAMESPACE = "landing";
+const LANDING_KEY = "default";
+const VALID_LANDING_STRATEGIES = ["direct", "pr"] as const;
 const VALID_PROFILE_PROVIDERS = ["any", "claude", "codex"] as const;
 const VALID_PROFILE_BASES = ["host", "minimal", "isolated"] as const;
 const VALID_PROFILE_INSTRUCTION_POLICIES = ["allow", "ignore"] as const;
@@ -239,6 +244,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
     env: input.env ?? {},
     providerOptions: input.providerOptions ?? {},
     ...(input.maxSpawnedAgents === undefined ? {} : { maxSpawnedAgents: input.maxSpawnedAgents }),
+    ...(input.landingStrategy === undefined ? {} : { landingStrategy: input.landingStrategy }),
   };
 }
 
@@ -317,6 +323,9 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
     maxSpawnedAgents: value.maxSpawnedAgents === undefined || value.maxSpawnedAgents === null
       ? undefined
       : cleanNumber(value.maxSpawnedAgents, "maxSpawnedAgents", { min: 0, max: 100 }),
+    landingStrategy: value.landingStrategy === undefined || value.landingStrategy === null
+      ? undefined
+      : cleanEnum(value.landingStrategy, "landingStrategy", VALID_LANDING_STRATEGIES) as WorkspaceLandingPolicy,
   });
 }
 
@@ -508,6 +517,19 @@ function validateWorkspaceConfig(value: unknown): WorkspaceConfig {
   return { symlinkPaths };
 }
 
+const LANDING_CONFIG_DEFAULTS: LandingConfig = {
+  strategy: "direct",
+};
+
+function validateLandingConfig(value: unknown): LandingConfig {
+  if (!isRecord(value)) throw new ValidationError("landing config value must be an object");
+  return {
+    strategy: value.strategy === undefined || value.strategy === null
+      ? LANDING_CONFIG_DEFAULTS.strategy
+      : cleanEnum(value.strategy, "strategy", VALID_LANDING_STRATEGIES) as WorkspaceLandingPolicy,
+  };
+}
+
 function normalizeValue(namespace: string, key: string, value: unknown): unknown {
   if (value === undefined) throw new ValidationError("value required");
   if (namespace === SPAWN_POLICY_NAMESPACE) return validateSpawnPolicy(key, value);
@@ -516,6 +538,7 @@ function normalizeValue(namespace: string, key: string, value: unknown): unknown
   if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
   if (namespace === NOTIFICATIONS_NAMESPACE) return validateNotificationsConfig(value);
   if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
+  if (namespace === LANDING_NAMESPACE) return validateLandingConfig(value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
   return value;
 }
@@ -682,6 +705,29 @@ export function setWorkspaceConfig(value: unknown, updatedBy?: string): ConfigEn
   return setConfig(WORKSPACE_NAMESPACE, WORKSPACE_KEY, value as WorkspaceConfig, updatedBy);
 }
 
+/** Instance-wide landing config, merged over defaults (always returns a usable value). */
+export function getLandingConfig(): LandingConfig {
+  const entry = getConfig<Partial<LandingConfig>>(LANDING_NAMESPACE, LANDING_KEY);
+  if (!entry) return { ...LANDING_CONFIG_DEFAULTS };
+  return validateLandingConfig({ ...LANDING_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function getLandingConfigEntry(): ConfigEntry<LandingConfig> {
+  const entry = getConfig<LandingConfig>(LANDING_NAMESPACE, LANDING_KEY);
+  return entry ?? {
+    namespace: LANDING_NAMESPACE,
+    key: LANDING_KEY,
+    value: { ...LANDING_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setLandingConfig(value: unknown, updatedBy?: string): ConfigEntry<LandingConfig> {
+  return setConfig(LANDING_NAMESPACE, LANDING_KEY, value as LandingConfig, updatedBy);
+}
+
 /**
  * Spawn-param fragment carrying the global workspace symlink list to the orchestrator.
  * Spread into every spawn command's params next to `agentProfile` so any isolated

package/src/index.ts

@@ -15,6 +15,7 @@ import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:z
 import {
   VERSION,
 } from "./config";
+import { CONTRACT_VERSIONS } from "./contracts";
 import {
   applyCors,
   assertSafeNetworkConfig,
@@ -38,12 +39,28 @@ async function main(): Promise<void> {
   startServer();
 }
 
-// On a version change, flag restart-on-update policies so they cycle when idle.
-function reconcileRelayVersion(): void {
-  const stored = getConfig<string>("system", "relay-version")?.value;
-  if (stored === VERSION) return;
-  if (stored) getLifecycleManager().onRelayUpdated(VERSION);
-  setConfig("system", "relay-version", VERSION, "server-startup");
+// Restart-on-update gating (issue #341).
+//
+// A `restartOnUpdate` policy should cycle its managed agent only when the agent's
+// running runner code is now protocol-INCOMPATIBLE with the relay — i.e. on a
+// runner-protocol bump — NOT on every package version change. Gating on the package
+// version churned the always-on Telegram agent ~12×/day (one restart per patch
+// redeploy), dropping in-flight work (surfaced #340). The runner protocol
+// (CONTRACT_VERSIONS.runnerProtocol) only moves on a breaking runner change, so this
+// fires ~never during normal releases.
+//
+// `relay-version` is still tracked for observability/telemetry, but it no longer
+// triggers restarts.
+export function reconcileRelayVersion(): void {
+  const storedVersion = getConfig<string>("system", "relay-version")?.value;
+  if (storedVersion !== VERSION) setConfig("system", "relay-version", VERSION, "server-startup");
+
+  const storedProtocol = getConfig<string>("system", "runner-protocol-version")?.value;
+  const currentProtocol = String(CONTRACT_VERSIONS.runnerProtocol);
+  if (storedProtocol === currentProtocol) return;
+  // Skip the very first run (no stored protocol yet) — that's initial bootstrap, not an upgrade.
+  if (storedProtocol) getLifecycleManager().onRelayUpdated(VERSION);
+  setConfig("system", "runner-protocol-version", currentProtocol, "server-startup");
 }
 
 function startServer(): void {

package/src/lifecycle-manager.ts

@@ -1,6 +1,6 @@
 import { createCommand } from "./commands-db";
 import { isPathWithinBase } from "./utils";
-import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces, resolveQueuedPolicyMessages } from "./db";
+import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces } from "./db";
 import {
   getManagedAgentState,
   listSpawnPolicies,
@@ -8,7 +8,8 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
-import { emitMessageDeliveryUpdated } from "./sse";
+import { markManagedAgentRunning, emitManagedState } from "./services/managed-running";
+import { authContextFromSystem } from "./services/auth-context";
 import { emitCommandEvent } from "./command-events";
 import { buildManagedSpawnParams } from "./managed-policy";
 import { generateSpawnRequestId } from "./spawn-command";
@@ -75,50 +76,30 @@ export class LifecycleManager {
     this.spawnAgent(policy, "message-trigger");
   }
 
-  onAgentRegistered(agentId: string, meta: { policyName?: string; spawnRequestId?: string; tmuxSession?: string | null }): void {
-    if (!meta.policyName || !meta.spawnRequestId) return;
-    const state = getManagedAgentState(meta.policyName);
-    if (!state || state.spawnRequestId !== meta.spawnRequestId) return;
-    const next = updateManagedAgentState(meta.policyName, {
-      status: "running",
-      agentId,
-      tmuxSession: meta.tmuxSession ?? state.tmuxSession,
-      healthySince: this.now(),
-      backoffUntil: undefined,
-      lastError: undefined,
-    });
-    if (next) this.emitState(next);
-    const available = resolveQueuedPolicyMessages(meta.policyName, agentId);
-    if (available.length) {
-      emitRelayEvent({
-        type: "message.available",
-        source: "server",
-        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);
-    }
-  }
+  // NOTE: the bus registration path used to call `onAgentRegistered` here for the
+  // came-up-running transition + queue flush. That logic now lives in the
+  // registerAgent service (src/services/register-agent.ts → markManagedAgentRunning),
+  // which the bus `handleRegister` calls directly — collapsing the second of the three
+  // drifted registration copies (epic #342). Only the orchestrator-report projection
+  // below still enters managed-running from the lifecycle manager.
 
   onOrchestratorManagedAgentsReported(orchestratorId: string, agents: ManagedAgent[], exitedAgents: ManagedSessionExitDiagnostics[] = []): void {
     for (const agent of agents) {
       if (!agent.policyName || !agent.spawnRequestId) continue;
       const state = getManagedAgentState(agent.policyName);
       if (!state || state.spawnRequestId !== agent.spawnRequestId) continue;
-      const next = updateManagedAgentState(agent.policyName, {
-        status: "running",
-        agentId: agent.agentId || state.agentId,
-        tmuxSession: agent.tmuxSession,
-        workspaceId: agent.workspace?.id,
-        workspacePath: agent.workspace?.worktreePath,
-        workspaceBranch: agent.workspace?.branch,
-        healthySince: state.healthySince ?? this.now(),
-        backoffUntil: undefined,
-        lastError: undefined,
-      });
-      if (next) this.emitState(next);
+      // Same came-up-running core the registration transports use — one home, no drift.
+      markManagedAgentRunning(
+        {
+          policyName: agent.policyName,
+          spawnRequestId: agent.spawnRequestId,
+          agentId: agent.agentId || state.agentId || "",
+          tmuxSession: agent.tmuxSession,
+          workspace: agent.workspace,
+        },
+        authContextFromSystem(),
+        { now: this.now },
+      );
 
       // Liveness reconciliation: the orchestrator just reported this process as
       // running. If the relay record says offline, the two truths disagree
@@ -511,40 +492,14 @@ export class LifecycleManager {
       context.utilization > DEFAULT_COMPACT_TARGET;
   }
 
+  // The managed-state emit + activity-transition record lives in the shared
+  // emitManagedState (src/services/managed-running.ts) so the registration service
+  // and this lifecycle reconciler emit identically (epic #342). We track the prior
+  // status per policy here only to compute the from→to for the transition row.
   private emitState(state: ManagedAgentState, reason?: string): void {
-    emitRelayEvent({
-      type: "policy.state.changed",
-      source: "lifecycle-manager",
-      subject: state.policyName,
-      data: state as unknown as Record<string, unknown>,
-    });
     const previous = this.lastStatusByPolicy.get(state.policyName);
     this.lastStatusByPolicy.set(state.policyName, state.status);
-    if (previous !== state.status) this.recordTransition(state, previous, reason);
-  }
-
-  // Persist a managed-state transition so it shows on the activity feed and the
-  // per-agent timeline — the "what changed, why, and when" record for a policy.
-  private recordTransition(state: ManagedAgentState, fromState: string | undefined, reason?: string): void {
-    const why = reason ?? state.lastError ?? undefined;
-    const seq = ++this.transitionSeq;
-    createActivityEvent({
-      clientId: `lifecycle-${state.policyName}-${state.status}-${this.now()}-${seq}`,
-      kind: "state",
-      title: `${state.policyName}: ${fromState ?? "—"} → ${state.status}`,
-      body: why,
-      icon: "ti-arrows-exchange",
-      view: "managed-agents",
-      agentId: state.agentId,
-      metadata: {
-        source: "lifecycle-manager",
-        policyName: state.policyName,
-        spawnRequestId: state.spawnRequestId,
-        fromState: fromState ?? null,
-        toState: state.status,
-        reason: why ?? null,
-      },
-    });
+    emitManagedState(state, previous, reason, this.now);
   }
 
   // Surface a disagreement between relay status and real process liveness so the
@@ -624,6 +579,13 @@ export function getLifecycleManager(): LifecycleManager {
   return singleton;
 }
 
+/** Test seam: stop and drop the singleton so each parity run starts with clean
+ * in-memory state (the per-policy last-status map, timers). */
+export function __resetLifecycleManager(): void {
+  singleton?.stop();
+  singleton = null;
+}
+
 function alwaysReloadTags(tags: string[]): string[] {
   return tags
     .filter((tag) => tag.startsWith("memory-reload:"))

package/src/maintenance.ts

@@ -37,7 +37,7 @@ import { reconcileLandedWorkspace } from "./branch-landed";
 import { notifyAgentOffline } from "./agent-lifecycle-events";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
-import { deriveBranchState, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { deriveBranchState, DIRTY_WORKTREE_LAND_SKIP_REASON, 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";
@@ -716,6 +716,11 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     if (!preview || (preview as { available?: false }).available === false) continue;
     const p = preview as WorkspaceMergePreview;
     if (p.error || p.missing) continue;
+    if (p.reason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
+      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: p.reason, lastLandSkipAt: Date.now() });
+    } else if (ws.metadata.lastLandSkipReason === DIRTY_WORKTREE_LAND_SKIP_REASON) {
+      patchWorkspaceMetadata(ws.id, { lastLandSkipReason: undefined, lastLandSkipAt: undefined });
+    }
 
     const ahead = p.unmergedAhead ?? p.ahead ?? 0;
     const behind = p.behind ?? 0;