agent-relay-server 0.120.4 → 0.120.6

package/src/routes/commands.ts

@@ -1,76 +1,28 @@
 // Auto-split from routes.ts (#299). Domain: commands.
 import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authorizeRoute, emitCommand, error, json, parseBody, parseQueryInt, type AgentControlAction, type Handler } from "./_shared";
 import { VALID_WORKSPACE_STATUSES, cleanParams, cleanString, optionalEnum } from "../validation";
-import { ValidationError, deleteWorkspace, getOrchestrator, getWorkspace, patchWorkspaceMetadata, releaseMergeLease, setOrchestratorUpgradeState, setWorkspaceBranch, updateWorkspaceStatus } from "../db";
+import { ValidationError, deleteWorkspace, getOrchestrator, getWorkspace, patchWorkspaceMetadata, setOrchestratorUpgradeState, updateWorkspaceStatus } from "../db";
 import { applyCommandToRecipe } from "../recipe-runner";
-import { claimMetadataPatch } from "../workspace-claim";
 import { clearActiveMemories, injectAlwaysReloadMemories } from "../memory-service";
 import { getCommand, listCommands, updateCommand } from "../commands-db";
 import { emitOrchestratorStatus } from "../sse";
 import { getCompactionWatch } from "../compaction-watch";
-import { isRecord, sanitizeFsName, type LandGateRunResult } from "agent-relay-sdk";
-import { storeTextArtifact } from "../artifact-text";
+import { isRecord } from "agent-relay-sdk";
 import { authContextFromRequest } from "../services/auth-context";
 import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
 import { prepareScheduledCommandResultForStorage, settleScheduledCommandTimer } from "../services/scheduler-command";
-import { emitWorkspaceTaskSemanticNotifications } from "../services/task-lifecycle";
 import { ServiceAuthError } from "../services/errors";
-import { notifyBaseWorktreeStrand, notifyBranchLandFailed, notifyBranchLanded, notifyLandGateFailed, notifyLandGateWarnings } from "../branch-landed";
 import { applyIdleRefreshResult } from "../maintenance/workspaces";
 import { seedProviderConfigs } from "../provider-config-store";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
-import { handleReviewerMergeResult } from "../reviewer-pipeline";
-import { CLEAR_MERGE_NO_PROGRESS, noteMergeNoProgress, scheduleRepoMerge } from "../workspace-auto-merge";
+import { scheduleRepoMerge } from "../workspace-auto-merge";
 import { enqueueContinuationInjectionAfterSelfResume } from "../self-resume";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
 import { commandTargetsWorkspaceOwner } from "../workspace-host";
+import { settleWorkspaceCommand } from "../workspace-command-settle";
 
 const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
 
-// #902 — normalize a land-gate run result that round-tripped through the command bus
-// (JSON, loosely typed) back into a LandGateRunResult. Returns undefined when the value
-// isn't a gate result, so the caller falls back to the generic land-failed path.
-function normalizeGateRunResult(value: unknown): LandGateRunResult | undefined {
-  if (!isRecord(value)) return undefined;
-  const name = typeof value.name === "string" ? value.name : undefined;
-  const command = typeof value.command === "string" ? value.command : "";
-  if (!name) return undefined;
-  return {
-    name,
-    command,
-    optional: value.optional === true,
-    passed: value.passed === true,
-    exitCode: typeof value.exitCode === "number" ? value.exitCode : null,
-    timedOut: value.timedOut === true,
-    durationMs: typeof value.durationMs === "number" ? value.durationMs : 0,
-    outputTail: typeof value.outputTail === "string" ? value.outputTail : "",
-    output: typeof value.output === "string" ? value.output : (typeof value.outputTail === "string" ? value.outputTail : ""),
-  };
-}
-
-function normalizeGateWarnings(value: unknown): LandGateRunResult[] {
-  if (!Array.isArray(value)) return [];
-  return value.map(normalizeGateRunResult).filter((g): g is LandGateRunResult => Boolean(g));
-}
-
-// Upload a gate's full output to a relay artifact; returns its id, or undefined on any
-// failure (artifact upload is best-effort — the tail still rides in the notification).
-async function uploadGateOutputArtifact(workspaceId: string, gate: LandGateRunResult): Promise<string | undefined> {
-  try {
-    const safeName = sanitizeFsName(gate.name, { replacement: "-", maxLen: 60, trimEdge: true, fallback: "gate" });
-    const stored = await storeTextArtifact({
-      text: gate.output || gate.outputTail || "(no output)",
-      filename: `land-gate-${safeName}-${workspaceId}.log`,
-      createdBy: "server",
-      metadata: { kind: "land-gate-output", workspaceId, gateName: gate.name, gateCommand: gate.command, exitCode: gate.exitCode, timedOut: gate.timedOut },
-    });
-    return stored.id;
-  } catch (error) {
-    console.warn(`land-gate artifact upload failed for ${workspaceId} gate "${gate.name}": ${String(error)}`);
-    return undefined;
-  }
-}
-
 function auditCommandOutcome(command: Command): void {
   if (command.status !== "succeeded" && command.status !== "failed") return;
   if (command.type !== "agent.restart" && command.type !== "agent.shutdown" && command.type !== "agent.reconnect") return;
@@ -232,204 +184,15 @@ export const patchCommand: Handler = async (req, params) => {
     if (command.type === "scheduler.command") {
       await settleScheduledCommandTimer(command);
     }
-    if (command.type === "workspace.cleanup" && command.status === "succeeded" && isRecord(command.result)) {
-      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
-      if (workspaceId) {
-        const workspace = getWorkspace(workspaceId);
-        if (workspace && commandTargetsWorkspaceOwner(command, workspace)) {
-          updateWorkspaceStatus(workspaceId, "cleaned", {
-            cleanupResult: command.result,
-            cleanupCommandId: command.id,
-          });
-        }
-      }
+    const workspaceSettle = settleWorkspaceCommand(command, { onMergeSettled: scheduleRepoMerge });
+    if (workspaceSettle.ignoredWrongOwner) {
+      auditCommandOutcome(command);
+      return json(command);
     }
     if (command.type === "workspace.idle-refresh" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
       if (workspaceId) applyIdleRefreshResult(workspaceId, command.result);
     }
-    if (command.type === "workspace.merge") {
-      // Merge settled (either way) — free the per-repo merge lease so the next
-      // base merge can proceed (issue #157).
-      if (command.status === "succeeded" || command.status === "failed") {
-        releaseMergeLease({ commandId: command.id });
-        // #237: the lease just freed — drain the next ready/review_requested row for
-        // this repo right now instead of waiting for the backstop sweep. This is the
-        // on-settle link of the sequential per-repo drain chain (no-op if nothing else
-        // is queued, or if AUTO_MERGE is disabled).
-        const settledRepoRoot = typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined;
-        scheduleRepoMerge(settledRepoRoot);
-      }
-      if (command.status === "succeeded" && isRecord(command.result)) {
-        if (handleReviewerMergeResult(command, command.result)) {
-          emitCommand(command);
-          auditCommandOutcome(command);
-          return json(command);
-        }
-        const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
-        const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
-        if (workspaceId && resultStatus) {
-          // Snapshot the row BEFORE the recycle repoints `branch` (#206) — the landed
-          // branch name + author (#239 branch.landed push) come from this pre-mutation state.
-          const landedWorkspace = getWorkspace(workspaceId);
-          if (landedWorkspace && !commandTargetsWorkspaceOwner(command, landedWorkspace)) {
-            auditCommandOutcome(command);
-            return json(command);
-          }
-          const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
-          const normalizedStatus = command.result.merged === true
-            && !newBranch
-            && ["review_requested", "merge_planned", "conflict"].includes(resultStatus)
-            ? "merged"
-            : resultStatus;
-          updateWorkspaceStatus(workspaceId, normalizedStatus, {
-            mergeResult: command.result,
-            mergeCommandId: command.id,
-            mergedAt: Date.now(),
-            // A merge that settles `succeeded` made genuine progress (land / recycle /
-            // noop-resolve / PR-opened) — clear any prior no-progress back-off so the lane
-            // is attempted normally next time (#638).
-            ...CLEAR_MERGE_NO_PROGRESS,
-            mergeError: undefined,
-            ...(normalizedStatus !== resultStatus ? { mergeStatusNormalizedFrom: resultStatus } : {}),
-            // The land consumes the steward's claim (#208 steward contract / vent
-            // #62): a successful land must release it, or `steward inspect` keeps
-            // showing a stale claim on the recycled workspace and blocks the next
-            // automation. Clearing a null claim (auto-merge path) is a harmless no-op.
-            ...claimMetadataPatch(true),
-          });
-          // Land-and-continue (#206): the worktree was recycled onto a fresh branch.
-          // Repoint the row so the next merge targets the live branch, not the deleted one.
-          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, baseSha ?? mergedSha);
-          }
-          // #239 — push the author a "your branch landed" notice (no polling). Fires on a
-          // real land; a no-op resolution (#230) merged nothing, so it earns no notice.
-          // #423 — a PR-land RECYCLE is a no-op merge (`merged:false`) but a land DID happen
-          // on the remote: the relay carries that ground truth in `params.prLanded`, so the
-          // notice fires from it with the recycled `newBranch` — full rebase-ff parity.
-          const prLanded = isRecord(command.params.prLanded) ? command.params.prLanded : undefined;
-          // #824 — the land advanced a DIRTY base by ref plumbing and the shared checkout was
-          // left in a MIXED state (HEAD moved, some landed working files didn't). The land
-          // succeeded, but surface the strand LOUDLY so it's reconciled before anything reads/
-          // builds/publishes from the stale checkout — never silently as before.
-          const baseWorktreeSync = isRecord(command.result.baseWorktreeSync) ? command.result.baseWorktreeSync : undefined;
-          if (baseWorktreeSync && baseWorktreeSync.reconciled === false && landedWorkspace) {
-            notifyBaseWorktreeStrand({
-              workspace: landedWorkspace,
-              sync: {
-                reconciled: false,
-                unsyncedPaths: Array.isArray(baseWorktreeSync.unsyncedPaths) ? baseWorktreeSync.unsyncedPaths.filter((p): p is string => typeof p === "string") : undefined,
-                preservedWipPaths: Array.isArray(baseWorktreeSync.preservedWipPaths) ? baseWorktreeSync.preservedWipPaths.filter((p): p is string => typeof p === "string") : undefined,
-                message: typeof baseWorktreeSync.message === "string" ? baseWorktreeSync.message : undefined,
-              },
-            });
-          }
-          if ((command.result.merged === true || prLanded) && landedWorkspace) {
-            notifyBranchLanded({
-              workspace: landedWorkspace,
-              mergedSha: prLanded ? cleanString(prLanded.sha, "params.prLanded.sha", { max: 64 }) ?? mergedSha : mergedSha,
-              subject: prLanded
-                ? cleanString(prLanded.subject, "params.prLanded.subject", { max: 200 })
-                : cleanString(command.result.subject, "result.subject", { max: 200 }),
-              // PR-land subjects carry a trailing `(#PR)` GitHub stamps on the squash — not an
-              // issue. Tell the lifecycle hook so it won't close the PR number as an issue (#482).
-              prLand: Boolean(prLanded),
-              newBranch,
-              pushed: prLanded ? true : typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
-            });
-          }
-          // #902 — OPTIONAL land gates that failed on a SUCCESSFUL land (merged:true, ref
-          // advanced). Warn the worker (tail + combined-output artifact) without blocking.
-          // Best-effort + isolated so a warn-notify throw can't undo the completed land.
-          const gateWarnings = command.result.merged === true ? normalizeGateWarnings(command.result.gateWarnings) : [];
-          if (gateWarnings.length && landedWorkspace) {
-            const warnWorkspace = landedWorkspace;
-            void (async () => {
-              const combined = gateWarnings.map((g) => `### ${g.name} (${g.command}) — ${g.timedOut ? "timed out" : g.exitCode === null ? "could not run" : `exited ${g.exitCode}`}\n${g.output || g.outputTail || "(no output)"}`).join("\n\n");
-              let artifactId: string | undefined;
-              try {
-                artifactId = (await storeTextArtifact({ text: combined, filename: `land-gate-warnings-${warnWorkspace.id}.log`, createdBy: "server", metadata: { kind: "land-gate-warnings", workspaceId: warnWorkspace.id, gateNames: gateWarnings.map((g) => g.name) } })).id;
-              } catch (error) {
-                console.warn(`land-gate-warnings artifact upload failed for ${warnWorkspace.id}: ${String(error)}`);
-              }
-              try {
-                notifyLandGateWarnings({ workspace: warnWorkspace, warnings: gateWarnings, artifactId });
-              } catch (error) {
-                console.warn(`land-gate-warnings notify threw for ${warnWorkspace.id}: ${String(error)}`);
-              }
-            })();
-          }
-        }
-      } else if (command.status === "failed" && command.correlationId) {
-        // Merge couldn't complete — don't leave it stuck in merge_planned. A no-progress
-        // merge now settles `failed` (orchestrator #638) carrying the result; honor the
-        // orchestrator's intended target status when it gave a valid one so a real
-        // `conflict` routes to the steward (a non-landable status the auto-merge job
-        // skips, which itself stops the loop) rather than bouncing back to the landable
-        // `review_requested`. Surface the error and count the no-progress attempt so the
-        // auto-merge job backs off after N instead of busy-looping (#638).
-        const current = getWorkspace(command.correlationId);
-        if (current && current.status === "merge_planned") {
-          if (!commandTargetsWorkspaceOwner(command, current)) {
-            auditCommandOutcome(command);
-            return json(command);
-          }
-          const failedResultStatus = isRecord(command.result)
-            ? optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined
-            : undefined;
-          const nextStatus: WorkspaceStatus = failedResultStatus && failedResultStatus !== "merge_planned"
-            ? failedResultStatus
-            : "review_requested";
-          updateWorkspaceStatus(command.correlationId, nextStatus, {
-            mergeCommandId: command.id,
-            mergeError: command.error ?? "merge failed",
-            ...noteMergeNoProgress(current.metadata),
-          });
-          if (nextStatus === "conflict") {
-            emitWorkspaceTaskSemanticNotifications({
-              workspace: current,
-              transition: "land-conflict",
-              actor: "workspace-merge",
-              occurrenceKey: `workspace-merge-conflict:${current.id}:${command.id}`,
-              outcome: {
-                reason: command.error ?? "merge failed",
-                commandId: command.id,
-                status: nextStatus,
-              },
-            });
-          }
-          const gateFailure = isRecord(command.result) ? normalizeGateRunResult(command.result.gateFailure) : undefined;
-          if (gateFailure) {
-            // #902 — a REQUIRED land gate failed: the orchestrator aborted WITHOUT advancing
-            // the ref and settled status "review_requested" (not "conflict", so the steward
-            // path above is never taken). Send the richer worker+coordinator notice (gate name
-            // + output tail + full-output artifact) INSTEAD of the generic land-failed wake.
-            // Best-effort + isolated: the land already (didn't) happen; a notify/upload throw
-            // must not break command settling.
-            void (async () => {
-              const artifactId = await uploadGateOutputArtifact(current.id, gateFailure);
-              try {
-                notifyLandGateFailed({ workspace: current, gate: gateFailure, artifactId });
-              } catch (error) {
-                console.warn(`land-gate-failed notify threw for ${current.id}: ${String(error)}`);
-              }
-            })();
-          } else {
-            notifyBranchLandFailed({
-              workspace: current,
-              commandId: command.id,
-              reason: command.error ?? "merge failed",
-            });
-          }
-        }
-      }
-    }
     if (command.type === "workspace.reconcile" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
       const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;

package/src/routes/tasks.ts

@@ -130,14 +130,12 @@ export const postTaskCreate: Handler = async (req) => {
       teamId: cleanString(body.teamId, "teamId", { max: 200 }),
       projectId: cleanString(body.projectId, "projectId", { max: 120 }),
       repo: cleanString(body.repo, "repo", { max: 500 }),
+      branch: cleanString(body.branch, "branch", { max: 500 }),
       dispatch: body.dispatch as TaskDispatch | undefined,
+      issueRefs: Array.isArray(body.issueRefs) ? body.issueRefs.filter((ref): ref is string => typeof ref === "string") : undefined,
+      defaultRepo: cleanString(body.defaultRepo, "defaultRepo", { max: 500 }),
       createdBy: actorOf(req, body.createdBy),
     });
-    if (Array.isArray(body.issueRefs)) {
-      for (const ref of body.issueRefs) {
-        if (typeof ref === "string" && ref.trim()) addTaskEntityRef(created.id, { issue: ref, defaultRepo: cleanString(body.defaultRepo, "defaultRepo", { max: 500 }), actor: actorOf(req, body.createdBy) });
-      }
-    }
     if (Array.isArray(body.dependsOn)) {
       for (const dep of body.dependsOn) {
         const depId = parseId(String(dep));

package/src/routes/workspaces.ts

@@ -104,12 +104,27 @@ function latestWorkspaceByBranch(workspaces: WorkspaceRecord[]): Map<string, Wor
   return byBranch;
 }
 
-function owningOrchestratorForRepo(repoRoot: string) {
-  return listOrchestrators().find((candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
+function owningOrchestratorsForRepo(repoRoot: string, orchestratorId?: string) {
+  const candidates = listOrchestrators().filter((candidate) => candidate.status === "online" && candidate.apiUrl);
+  if (orchestratorId) {
+    return candidates.filter((candidate) => candidate.id === orchestratorId);
+  }
+  const ownerIds = new Set(
+    listWorkspaces()
+      .filter((workspace) => workspace.orchestratorId && resolve(workspace.repoRoot) === resolve(repoRoot))
+      .map((workspace) => workspace.orchestratorId!),
+  );
+  const owners = candidates.filter((candidate) => ownerIds.has(candidate.id));
+  if (owners.length > 0) return owners;
+  const legacy = candidates.find((candidate) => isPathWithinBase(repoRoot, candidate.baseDir));
+  return legacy ? [legacy] : [];
+}
+
+function owningOrchestratorForRepo(repoRoot: string, orchestratorId?: string) {
+  return owningOrchestratorsForRepo(repoRoot, orchestratorId)[0];
 }
 
-async function fetchRecoveryBranchesForRepo(repoRoot: string, opts: { baseRef?: string; baseSha?: string } = {}): Promise<{ branches: WorkspaceRecoveryBranch[]; unavailable?: string }> {
-  const orch = owningOrchestratorForRepo(repoRoot);
+async function fetchRecoveryBranchesFromOrchestrator(repoRoot: string, orch: NonNullable<ReturnType<typeof owningOrchestratorForRepo>>, opts: { baseRef?: string; baseSha?: string } = {}): Promise<{ branches: WorkspaceRecoveryBranch[]; unavailable?: string }> {
   if (!orch?.apiUrl) return { branches: [], unavailable: "owning orchestrator offline" };
   const query = new URLSearchParams({ repoRoot });
   if (opts.baseRef) query.set("baseRef", opts.baseRef);
@@ -122,16 +137,36 @@ async function fetchRecoveryBranchesForRepo(repoRoot: string, opts: { baseRef?:
     if (!res.ok) return { branches: [], unavailable: `host returned ${res.status}` };
     const payload = await res.json() as unknown;
     if (!isRecord(payload) || !Array.isArray(payload.branches)) return { branches: [], unavailable: "host returned malformed recovery branch list" };
-    return { branches: payload.branches.filter(isRecord) as unknown as WorkspaceRecoveryBranch[] };
+    return {
+      branches: (payload.branches.filter(isRecord) as unknown as WorkspaceRecoveryBranch[]).map((branch) => ({
+        ...branch,
+        orchestratorId: orch.id,
+        orchestratorAgentId: orch.agentId,
+      })),
+    };
   } catch (e) {
     return { branches: [], unavailable: `orchestrator unreachable: ${(e as Error).message}` };
   }
 }
 
+async function fetchRecoveryBranchesForRepo(repoRoot: string, opts: { baseRef?: string; baseSha?: string; orchestratorId?: string } = {}): Promise<{ branches: WorkspaceRecoveryBranch[]; unavailable?: string }> {
+  const hosts = owningOrchestratorsForRepo(repoRoot, opts.orchestratorId);
+  if (hosts.length === 0) return { branches: [], unavailable: "owning orchestrator offline" };
+  const branches: WorkspaceRecoveryBranch[] = [];
+  const unavailable: string[] = [];
+  for (const orch of hosts) {
+    const fetched = await fetchRecoveryBranchesFromOrchestrator(repoRoot, orch, opts);
+    branches.push(...fetched.branches);
+    if (fetched.unavailable) unavailable.push(`${orch.id}: ${fetched.unavailable}`);
+  }
+  return { branches, ...(branches.length === 0 && unavailable.length > 0 ? { unavailable: unavailable.join("; ") } : {}) };
+}
+
 export const getWorkspaceRecoveryBranches: Handler = async (req) => {
   try {
     const url = new URL(req.url);
     const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
+    const orchestratorId = cleanString(url.searchParams.get("orchestratorId") ?? undefined, "orchestratorId", { max: 200 });
     const baseRef = cleanString(url.searchParams.get("baseRef") ?? undefined, "baseRef", { max: 240 });
     const baseSha = cleanString(url.searchParams.get("baseSha") ?? undefined, "baseSha", { max: 80 });
     const includeActive = url.searchParams.get("includeActive") === "1";
@@ -142,7 +177,7 @@ export const getWorkspaceRecoveryBranches: Handler = async (req) => {
     const unavailable: Record<string, string> = {};
 
     for (const repo of repoRoots) {
-      const fetched = await fetchRecoveryBranchesForRepo(repo, { baseRef, baseSha });
+      const fetched = await fetchRecoveryBranchesForRepo(repo, { baseRef, baseSha, orchestratorId });
       if (fetched.unavailable) {
         unavailable[repo] = fetched.unavailable;
         continue;
@@ -186,6 +221,7 @@ export const postWorkspaceRecoveryBranchDiscard: Handler = async (req) => {
     if (!isRecord(parsed.body)) return error("body required");
     const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
     const branch = cleanString(parsed.body.branch, "branch", { max: 240 });
+    const requestedOrchestratorId = cleanString(parsed.body.orchestratorId, "orchestratorId", { max: 200 });
     const baseRef = cleanString(parsed.body.baseRef, "baseRef", { max: 240 });
     const baseSha = cleanString(parsed.body.baseSha, "baseSha", { max: 80 });
     const reason = cleanString(parsed.body.reason, "reason", { max: 1000 });
@@ -193,11 +229,11 @@ export const postWorkspaceRecoveryBranchDiscard: Handler = async (req) => {
     if (!repoRoot || !branch) return error("repoRoot and branch required", 400);
     if (!branch.startsWith("agent/")) return error("only agent/* branches can be discarded through recovery cleanup", 400);
     if (force && !reason) return error("reason required for forced recovery branch discard", 400);
-    const orch = owningOrchestratorForRepo(repoRoot);
+    const fetched = await fetchRecoveryBranchesForRepo(repoRoot, { baseRef, baseSha, orchestratorId: requestedOrchestratorId });
+    const target = fetched.branches.find((item) => item.branch === branch);
+    const orch = target?.orchestratorId ? owningOrchestratorForRepo(repoRoot, target.orchestratorId) : owningOrchestratorForRepo(repoRoot);
     if (!orch?.agentId) return error("no online orchestrator owns this repo", 409);
-    const fetched = await fetchRecoveryBranchesForRepo(repoRoot, { baseRef, baseSha });
     if (fetched.unavailable) return error(fetched.unavailable, 409);
-    const target = fetched.branches.find((item) => item.branch === branch);
     if (!target) return error("recovery branch not found", 404);
     if (target.safeToDelete !== true && !force) {
       return error(`branch holds work or cannot be proven safe (${target.preserveReason ?? `${target.unmergedAhead ?? target.ahead ?? "?"} unlanded commit(s)`}); land it first or pass force:true with reason to discard`, 409);
@@ -242,25 +278,25 @@ export const postWorkspaceOrphanReclaim: Handler = async (req) => {
     // Refuse to reclaim a path that still backs a live workspace row.
     const live = listWorkspaces().find((ws) => ws.worktreePath && resolve(ws.worktreePath) === resolve(worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
     if (live) return error(`path backs live workspace ${live.id}; clean it through the workspace, not orphan reclaim`, 409);
-    const orch = listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(repoRoot, candidate.baseDir));
-    if (!orch) return error("no online orchestrator owns this path", 409);
     // Land-safety gate (#244): reclaim force-removes the worktree, so refuse when
     // it holds un-landed work unless the caller explicitly opts into discarding
     // it. Mirrors the scheduled reaper — never destroy work on uncertainty.
     let baseRef: string | undefined;
     let baseSha: string | undefined;
-    if (!force) {
-      const { orphans } = await collectWorkspaceOrphans();
-      const target = orphans.find((o) => resolve(o.worktreePath) === resolve(worktreePath));
-      if (target && target.safeToReap !== true) {
-        const why = target.safeToReap === undefined
-          ? "land-state could not be determined"
-          : target.dirty ? "uncommitted changes" : `${target.unmergedAhead ?? target.ahead ?? "?"} un-landed commit(s)`;
-        return error(`worktree holds un-landed work (${why}); recover it first, or pass {"force":true} to discard`, 409);
-      }
-      baseRef = target?.baseRef;
-      baseSha = target?.baseSha;
+    const { orphans } = await collectWorkspaceOrphans();
+    const target = orphans.find((o) => resolve(o.worktreePath) === resolve(worktreePath));
+    if (target && !force && target.safeToReap !== true) {
+      const why = target.safeToReap === undefined
+        ? "land-state could not be determined"
+        : target.dirty ? "uncommitted changes" : `${target.unmergedAhead ?? target.ahead ?? "?"} un-landed commit(s)`;
+      return error(`worktree holds un-landed work (${why}); recover it first, or pass {"force":true} to discard`, 409);
     }
+    baseRef = target?.baseRef;
+    baseSha = target?.baseSha;
+    const orch = target?.orchestratorId
+      ? listOrchestrators().find((candidate) => candidate.id === target.orchestratorId && candidate.status === "online")
+      : listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(repoRoot, candidate.baseDir));
+    if (!orch) return error("no online orchestrator owns this path", 409);
     const command = createCommand({
       type: "workspace.cleanup",
       source: "system",

package/src/services/issue-lifecycle.ts

@@ -1,5 +1,5 @@
 import { errMessage } from "agent-relay-sdk";
-import { getAgent, listPlansWithBoundOwner, deliverableTaskIdsByBranch } from "../db";
+import { getAgent, listPlansWithBoundOwner, deliverableTaskIdsByBranch, deliverableTaskIdsByOwnerAgent, deliverableTaskIdsBySpawnRequestId } from "../db";
 import { listIssuesForEntity, planNodeIssueEntityId } from "../db/issue-associations";
 import {
   getSuccessfulIssueLifecycleAction,
@@ -142,17 +142,28 @@ function associatedIssueRefs(workspace: LifecycleWorkspace): IssueRef[] {
       }
     }
   }
-  // #834 — task-aware resolution: a deliverable Task owns its branch, so the landed branch
-  // resolves to its linked issue(s). This is the resolution PATH; lifecycle automation that
-  // advances the Task itself on land is #831.
-  if (workspace.branch) {
-    for (const taskId of deliverableTaskIdsByBranch(workspace.branch)) {
-      refs.push(...listIssuesForEntity("task", String(taskId)).map((item) => item.issueRef));
-    }
+  for (const taskId of associatedTaskIds(workspace)) {
+    refs.push(...listIssuesForEntity("task", String(taskId)).map((item) => item.issueRef));
   }
   return issueRefMap(refs);
 }
 
+function associatedTaskIds(workspace: LifecycleWorkspace): number[] {
+  const ids = new Set<number>();
+  const ownerId = workspace.ownerAgentId?.trim();
+  if (ownerId) {
+    for (const id of deliverableTaskIdsByOwnerAgent(ownerId)) ids.add(id);
+    const spawnRequestId = getAgent(ownerId)?.meta?.spawnRequestId;
+    if (typeof spawnRequestId === "string" && spawnRequestId.trim()) {
+      for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
+    }
+  }
+  if (workspace.branch) {
+    for (const id of deliverableTaskIdsByBranch(workspace.branch)) ids.add(id);
+  }
+  return [...ids].sort((a, b) => a - b);
+}
+
 const CLOSING_KEYWORD_RE = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+([^\n\r]+)/gi;
 const ISSUE_REF_AT_START_RE = /^(https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/issues\/[0-9]+(?:[/?#][^\s,)]*)?|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[0-9]+|#[0-9]+)/;
 const REF_SEPARATOR_RE = /^(?:\s*,\s*|\s+(?:and|&)\s+)/i;
@@ -400,6 +411,10 @@ export async function handleLandedIssueLifecycle(input: LandedIssueLifecycleInpu
 }> {
   if ((input.workspace.baseRef ?? "main") !== "main") return { source: "commit", closed: [], reopened: [], skipped: ["non-default-branch"] };
   const resolved = await resolveIssueRefsForLand(input);
+  const taskIds = associatedTaskIds(input.workspace);
+  if (resolved.refs.length === 0 && taskIds.length > 0) {
+    logFailure(opts, `issue lifecycle found landed task(s) without linked issue refs: tasks=${taskIds.join(",")} workspace=${input.workspace.id} branch=${input.workspace.branch ?? "unknown"}`);
+  }
   const closed: CloseIssueLifecycleResult[] = [];
   for (const ref of resolved.refs) {
     closed.push(await closeIssueRefForLand(ref, resolved.source, input, opts));

package/src/services/task-entity.ts

@@ -34,7 +34,9 @@ import {
   type SetTaskStatusInput,
   type UpdateDeliverableTaskInput,
 } from "../db";
+import { errMessage } from "agent-relay-sdk";
 import { findSpawnCommandByRequestId } from "../commands-db";
+import { defaultIssueRepo } from "../config";
 import { emitTaskChanged } from "../sse";
 import type { CommandStatus, Task, TaskDetail, TaskEvent, TaskGateState, TaskListItem, TaskStatus, WorkspaceRecord } from "../types";
 import { removeSubscriptionsForTask } from "../db/notification-subscriptions";
@@ -43,8 +45,58 @@ import { routeNotification } from "../notification-router";
 import { isAgentExitDoneWhen, stageSatisfiesDoneWhen } from "./task-done-when";
 import { autoSubscribeTaskCoordinator, emitTaskSemanticNotification, taskTransitionForStage, taskTransitionForStatus } from "./task-semantic-events";
 
-export function createTaskEntity(input: CreateDeliverableTaskInput): TaskDetail {
-  const detail = createDeliverableTask(input);
+type CreateTaskEntityInput = CreateDeliverableTaskInput & {
+  issueRefs?: string[];
+  defaultRepo?: string;
+};
+
+const EXPLICIT_ISSUE_REF_RE = /(https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/issues\/[0-9]+(?:[/?#][^\s,)]*)?|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[0-9]+|#[0-9]+)/;
+const ISSUE_SLUG_RE = /(?:^|[\/_\-\s])(?:fix|feat|bug|issue|debug|chore|reverify|reenable)-([1-9][0-9]{0,6})(?=$|[\/_\-\s])/i;
+
+function explicitIssueRefIn(text: string | undefined): string | undefined {
+  return text?.match(EXPLICIT_ISSUE_REF_RE)?.[1];
+}
+
+function slugIssueRefIn(text: string | undefined): string | undefined {
+  const match = text?.match(ISSUE_SLUG_RE)?.[1];
+  return match ? `#${match}` : undefined;
+}
+
+function explicitIssueRefs(input: CreateTaskEntityInput): string[] {
+  return (input.issueRefs ?? []).map((ref) => ref.trim()).filter(Boolean);
+}
+
+function inferIssueRef(input: CreateTaskEntityInput): string | undefined {
+  for (const text of [input.title, input.branch, input.intent, input.context, input.latestSteer]) {
+    const explicit = explicitIssueRefIn(text);
+    if (explicit) return explicit;
+  }
+  for (const text of [input.title, input.branch]) {
+    const slug = slugIssueRefIn(text);
+    if (slug) return slug;
+  }
+  return undefined;
+}
+
+function addInitialIssueRefs(taskId: number, input: CreateTaskEntityInput): TaskDetail {
+  const refs = explicitIssueRefs(input);
+  const inferred = refs.length > 0 ? undefined : inferIssueRef(input);
+  const issueRefs = refs.length > 0 ? refs : inferred ? [inferred] : [];
+  const defaultRepo = input.defaultRepo?.trim() || input.repo?.trim() || defaultIssueRepo();
+  let detail = getTaskDetail(taskId)!;
+  for (const issue of issueRefs) {
+    try {
+      detail = addTaskRef(taskId, { issue, defaultRepo, actor: input.createdBy });
+    } catch (error) {
+      console.warn(`task ${taskId} issue ref '${issue}' could not be linked on create: ${errMessage(error)}`);
+    }
+  }
+  return detail;
+}
+
+export function createTaskEntity(input: CreateTaskEntityInput): TaskDetail {
+  const created = createDeliverableTask(input);
+  const detail = addInitialIssueRefs(created.id, input);
   autoSubscribeTaskCoordinator(input.createdBy, detail.id);
   emitTaskChanged(detail, "task.created");
   emitTaskSemanticNotification({

package/src/task-dispatcher.ts

@@ -382,7 +382,8 @@ function rerouteForBand(
 // no burn data yet. Prefer "prefer" band, then "normal"; never a blocked one.
 //
 // When mustResolveAvailable is set (#901 degrade-never-refuse), widens search in tiers when
-// no prefer/normal provider is available: caution → avoid-large → least-utilized blockedNow.
+// no prefer/normal provider is available: caution → avoid-large → hard-avoid-but-not-blocked
+// → least-utilized blockedNow.
 // A `degraded` flag + `degradedReason` signals to the caller to emit a louder warning.
 function healthiestAlternative(
   avoid: SpawnProvider,
@@ -415,11 +416,19 @@ function healthiestAlternative(
     .sort((a, b) => bandRank(a.band) - bandRank(b.band));
   if (avoidLargeAlt[0]) return { ...avoidLargeAlt[0], degraded: true, degradedReason: "avoid-large band (tier 2 degraded)" };
 
-  // Tier 3 degradation: least-utilized blockedNow (last resort — emit the loudest warning).
+  // Tier 3 degradation: hard-avoid is still better than a provider that is actively blocked.
+  // This is the exact shape a release auto-heal can hit: Claude session limit is blockedNow,
+  // Codex is over pace (hard-avoid) but still runnable.
+  const hardAvoidAlt = all
+    .filter((c) => !c.blockedNow && c.band === "hard-avoid")
+    .sort((a, b) => bandRank(a.band) - bandRank(b.band));
+  if (hardAvoidAlt[0]) return { ...hardAvoidAlt[0], degraded: true, degradedReason: "hard-avoid band (tier 3 degraded)" };
+
+  // Tier 4 degradation: least-utilized blockedNow (last resort — emit the loudest warning).
   // Sort by bandRank so the healthiest (lowest penalty) blocked provider is picked first,
   // not whichever happens to be earliest in catalog order.
   const blockedAlts = all.filter((c) => c.blockedNow).sort((a, b) => bandRank(a.band) - bandRank(b.band));
-  if (blockedAlts[0]) return { ...blockedAlts[0], degraded: true, degradedReason: "blockedNow provider (tier 3 last-resort — ALL providers at capacity)" };
+  if (blockedAlts[0]) return { ...blockedAlts[0], degraded: true, degradedReason: "blockedNow provider (tier 4 last-resort — ALL providers at capacity)" };
 
   return undefined;
 }