@humwick/server 0.0.0-stage → 0.130.1

package/src/branch-landed.ts

@@ -0,0 +1,761 @@
+import { errMessage, isHumanAgentId, type BaseWorktreeSyncResult } from "@humwick/sdk";
+import { emitRelayEvent } from "./events";
+import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
+import { stampLifecycleSignal, taskSignalKey } from "./lifecycle-signal-registry";
+import { registerDefaultAudienceRules, audiencePredicates } from "./notification-rules";
+import { createActivityEvent, getAgent, getOrchestrator, getProject, getTaskDetail, insertLandingReceipt, markWorkspaceLanded, patchWorkspaceMetadataAsync, resolveProjectForCwd, updateWorkspaceStatusAsync, markWorkspaceLandedAsync} from "./db";
+import { renderTemplate } from "./prompt-resolver";
+import { resolveCoordinatorAgentId } from "./steward-identity";
+import { stewardFallbackTarget } from "./config";
+import { handleLandedIssueLifecycle } from "./services/issue-lifecycle";
+import { handleLandedTaskLifecycle } from "./services/task-lifecycle"; import { trackLandLifecycleDrive } from "./land-lifecycle-drives";
+import { resolveLandedTaskIds, type LandedTaskAttributionInput } from "./services/landed-task-attribution";
+import { runGit } from "./services/git-process";
+import { repoFromGitRemote } from "./services/git-remote";
+import { isOwnerAlive } from "./workspace-merge";
+import { landFailureEventKey } from "./land-failure-event-key";
+import { CLEAR_MERGE_NO_PROGRESS } from "./workspace-merge-progress";
+import { LAND_OWED_STATUSES } from "./workspace-phase"; import { resolveTaskOwnerAgentId } from "./task-owner"; import { audienceWithTaskOwnerRole, withWorkspaceTaskOwnerRoles } from "./task-owner-notices";
+import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
+import { finishWorkspaceStewardHandoff } from "./steward-handoff";
+
+// #2837 — the "merged" notice goes to the owner's lineage/Task/team coordinators only; other agents
+// (shared-checkout ones included) opt in via a subscription.
+registerDefaultAudienceRules("branch.landed", [audiencePredicates.scopeCoordinators(), audiencePredicates.teamCoordinator()]);
+
+export interface BranchLandedInput extends LandedTaskAttributionInput {
+  /**
+   * The workspace as it was AT land time — `branch` must be the branch that landed,
+   * captured before any land-and-continue recycle repoints the row (#206). `ownerAgentId`
+   * is the author the "landed" notice is pushed to.
+   */
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "baseSha" | "ownerAgentId" | "orchestratorId">;
+  /** SHA the base now points at after the land. */
+  mergedSha?: string;
+  /** Original command settlement clock when recovering an older land. */
+  landedAt?: number;
+  /** Subject line of the landed commit, when the orchestrator reported it. */
+  subject?: string;
+  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;
+  /**
+   * The land came in via a pull request — the subject's trailing `(#NNN)` is the PR
+   * number, not an issue. Forwarded to the issue-lifecycle hook so it doesn't mistake
+   * the PR number for an issue to close (#482).
+   */
+  prLand?: boolean;
+  /** Base boundary immediately before this land; defaults to the workspace's recorded base. */
+  landedBaseSha?: string;
+  /** Base ref tip immediately after this land; defaults to mergedSha. */
+  landedTipSha?: string;
+  /** Exact commits introduced by this branch, supplied by the authoritative host when available. */
+  commitShas?: string[];
+  /**
+   * #1620 — how many commits this land actually put on the base, when the caller can PROVE it.
+   * `0` means the land contributed nothing: the base ref is byte-identical before and after, so
+   * there is no merge to announce and no deliverable to re-record. `undefined` means "not known"
+   * (an older host that doesn't report it, a path that can't count) and is treated as a real
+   * land — this fails OPEN, because silencing a genuine land is far worse than a noisy no-op.
+   */
+  landedCommitCount?: number;
+}
+
+type BranchLandedLogFn = (message: string) => void;
+type LandedCommitSubjectResolver = (input: BranchLandedInput, log: BranchLandedLogFn) => string[] | undefined | Promise<string[] | undefined>;
+
+let landedCommitSubjectResolverForTests: LandedCommitSubjectResolver | undefined;
+
+export function __setLandedCommitSubjectResolverForTests(resolver: LandedCommitSubjectResolver | undefined): void {
+  landedCommitSubjectResolverForTests = resolver;
+}
+
+function cleanRef(value: string | undefined): string | undefined {
+  const cleaned = value?.trim();
+  return cleaned || undefined;
+}
+
+function subjectsFromNulLog(stdout: string): string[] | undefined {
+  const subjects = stdout.split("\x00").map((msg) => msg.trim()).filter(Boolean);
+  return subjects.length > 0 ? subjects : undefined;
+}
+
+export interface LandedCommitScanInput {
+  repoRoot: string;
+  /** SHA the base now points at after the land. */
+  tipSha: string;
+  /** Exact commits the authoritative host says this branch introduced, when known. */
+  commitShas?: string[];
+  /** The actual base tip immediately BEFORE this land (previousBaseSha) — the tight, valid boundary. */
+  landedBaseSha?: string;
+  /** The workspace's recorded fork point — a legacy last-resort base (may be pre-rewrite/absent). */
+  baseSha?: string;
+  workspaceId: string;
+}
+
+/**
+ * Enumerate the commit messages the land introduced, for per-commit issue backlinks.
+ *
+ * Base derivation is the crux: the original scan built its range from the workspace's
+ * recorded fork point (`baseSha`), but on a plain-git rebase-ff land that commit is a
+ * PRE-rewrite base — frequently absent from the merge/relay host's `repoRoot` object store
+ * entirely — so `git log <baseSha>..<tip>` dies with "unknown revision" and every rebased
+ * land silently degrades to the single tip subject (noisy `Invalid revision range`, worse
+ * issue↔commit linking). We now prefer, in order, signals the land already carries:
+ *   1. the EXACT commit SHAs the authoritative host reported (`commitShas`) — enumerated
+ *      with `--no-walk`, so there is no revision range and no base to resolve at all;
+ *   2. `landedBaseSha..tip` — the actual pre-merge boundary (previousBaseSha) that exists
+ *      in the repo and scopes the range tightly to THIS land's commits;
+ *   3. `baseSha..tip` — the legacy fork point, kept as a last resort.
+ * Each git-backed candidate is guarded: an unresolvable base/sha is non-fatal and we move
+ * to the next candidate; if nothing resolves we return undefined → clean fall-back to the
+ * tip subject. A candidate that resolves cleanly (exit 0) is authoritative for the land, so
+ * an empty tight range is NOT widened to the looser fork point (which would over-count).
+ */
+export async function resolveLandedCommitSubjects(input: LandedCommitScanInput, log: BranchLandedLogFn): Promise<string[] | undefined> {
+  const { repoRoot, tipSha, workspaceId } = input;
+  if (!repoRoot || !tipSha) return undefined;
+
+  // 1. Exact commits reported by the authoritative host — direct enumeration, no range/base.
+  const commitShas = [...new Set((input.commitShas ?? []).map(cleanRef).filter((sha): sha is string => Boolean(sha)))];
+  if (commitShas.length > 0) {
+    try {
+      const { stdout, exitCode } = await runGit(["-C", repoRoot, "log", "--no-walk", "--format=%B%x00", ...commitShas]);
+      if (exitCode === 0) {
+        const subjects = subjectsFromNulLog(stdout);
+        if (subjects) return subjects;
+      }
+      // A bad/absent sha in the set fails the whole command — fall through to a range.
+    } catch (error) {
+      log(`issue lifecycle commit enumeration failed for ${workspaceId} (${commitShas.length} sha(s)): ${errMessage(error)}; trying range`);
+    }
+  }
+
+  // 2/3. Range candidates: the tight pre-merge boundary first, the legacy fork point last.
+  const candidateBases = [...new Set([cleanRef(input.landedBaseSha), cleanRef(input.baseSha)]
+    .filter((sha): sha is string => Boolean(sha) && sha !== tipSha))];
+  for (const base of candidateBases) {
+    try {
+      const { stdout, stderr, exitCode, timedOut } = await runGit(["-C", repoRoot, "log", "--format=%B%x00", `${base}..${tipSha}`]);
+      if (exitCode === 0) return subjectsFromNulLog(stdout);
+      const error = timedOut ? "timed out" : stderr.trim() || `exit ${exitCode}`;
+      log(`issue lifecycle commit range scan failed for ${workspaceId} (${base.slice(0, 12)}..${tipSha.slice(0, 12)}): ${error}; trying next base`);
+    } catch (error) {
+      log(`issue lifecycle commit range scan failed for ${workspaceId} (${base.slice(0, 12)}..${tipSha.slice(0, 12)}): ${errMessage(error)}; trying next base`);
+    }
+  }
+  return undefined;
+}
+
+async function landedCommitSubjects(input: BranchLandedInput, log: BranchLandedLogFn): Promise<string[] | undefined> {
+  if (landedCommitSubjectResolverForTests) return landedCommitSubjectResolverForTests(input, log);
+  if (input.prLand) return undefined;
+  const repoRoot = cleanRef(input.workspace.repoRoot);
+  const tipSha = cleanRef(input.mergedSha);
+  if (!repoRoot || !tipSha) return undefined;
+  return resolveLandedCommitSubjects({
+    repoRoot,
+    tipSha,
+    commitShas: input.commitShas,
+    landedBaseSha: cleanRef(input.landedBaseSha),
+    baseSha: cleanRef(input.workspace.baseSha),
+    workspaceId: input.workspace.id,
+  }, log);
+}
+
+function resolveLandedTask(input: LandedTaskAttributionInput): {
+  taskId: number;
+  taskLabel: string;
+  projectId?: string;
+  repo?: string;
+  teamId?: string;
+} | undefined {
+  const taskIds = resolveLandedTaskIds(input);
+  const taskId = taskIds.length === 1 ? taskIds[0] : undefined;
+  if (!taskId) return undefined;
+  const task = getTaskDetail(taskId);
+  return task ? {
+    taskId: task.id,
+    taskLabel: task.title,
+    ...(task.projectId ? { projectId: task.projectId } : {}),
+    ...(task.repo ? { repo: task.repo } : {}),
+    ...(task.teamId ? { teamId: task.teamId } : {}),
+  } : undefined;
+}
+
+function landedNotificationIdempotencyKey(input: BranchLandedInput, landedTask: { taskId: number } | undefined, base: string): string | undefined {
+  const sha = cleanRef(input.mergedSha);
+  if (sha) return `branch-landed:${sha}`;
+  if (landedTask) return `branch-landed:task:${landedTask.taskId}:${base}`;
+  return undefined;
+}
+
+/**
+ * #239 — turn an authoritative land completion into a relay-driven push so the author stops polling
+ * to learn it merged, plus the durable receipt and the issue/Task lifecycle drives.
+ *
+ * #1790 — this is split into a SYNCHRONOUS {@link recordLandingReceipt} (one indexed INSERT — the
+ * durable proof the branch landed) and a deferrable {@link announceBranchLanded} (the bus events,
+ * per-recipient fan-out and lifecycle drives — the 6–12 serialized writes that amplified event-loop
+ * lag). The settle path runs the receipt inline BEFORE it marks the workspace landed and defers only
+ * the announcement; this combined entry preserves the original all-synchronous behavior for the
+ * maintenance reconcile path (reconcileLandedWorkspace) and direct callers/tests.
+ */
+export function notifyBranchLanded(input: BranchLandedInput): void {
+  recordLandingReceipt(input);
+  announceBranchLanded(input);
+}
+
+/**
+ * #1790 — persist the durable landing receipt SYNCHRONOUSLY. #1355 — the attribution snapshot must
+ * be taken while the worker's `spawnedBy` row still exists; the settle path calls this on the
+ * synchronous critical path BEFORE `markWorkspaceLanded` arms the #1696 "already recorded" guard, so
+ * a crash / SIGTERM between the state write and the deferred announcement can never strand a merged
+ * row with no receipt. The branch is already landed, so a receipt failure is loud (CRITICAL log) but
+ * can never unwind or mask it.
+ */
+export function recordLandingReceipt(input: BranchLandedInput): void {
+  const { workspace } = input;
+  // #1620 — a land that introduced ZERO commits is not a land: no receipt (see announceBranchLanded).
+  if (input.landedCommitCount === 0) return;
+  const landedTask = resolveLandedTask(input);
+  try {
+    const worker = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+    const coordinatorAgentId = resolveCoordinatorAgentId(workspace.ownerAgentId) ?? undefined;
+    const project = landedTask?.projectId
+      ? getProject(landedTask.projectId)
+      : resolveProjectForCwd(workspace.repoRoot);
+    const orchestrator = workspace.orchestratorId ? getOrchestrator(workspace.orchestratorId) : null;
+    const mergedSha = cleanRef(input.mergedSha);
+    const commitShas = [...new Set((input.commitShas ?? []).map(cleanRef).filter((sha): sha is string => Boolean(sha)))];
+    if (commitShas.length === 0 && mergedSha) commitShas.push(mergedSha);
+    insertLandingReceipt({
+      ...(landedTask?.projectId ?? project?.id ? { projectId: landedTask?.projectId ?? project!.id } : {}),
+      repo: landedTask?.repo ?? project?.issueRepo ?? repoFromGitRemote(workspace.repoRoot) ?? workspace.repoRoot,
+      ref: workspace.baseRef ?? "base",
+      ...(workspace.branch ? { branch: workspace.branch } : {}),
+      ...(cleanRef(input.landedBaseSha) ?? cleanRef(workspace.baseSha) ? { baseSha: cleanRef(input.landedBaseSha) ?? cleanRef(workspace.baseSha) } : {}),
+      ...(cleanRef(input.landedTipSha) ?? mergedSha ? { tipSha: cleanRef(input.landedTipSha) ?? mergedSha } : {}),
+      commitShas,
+      workspaceId: workspace.id,
+      ...(input.landedAt !== undefined ? { landedAt: input.landedAt } : {}),
+      ...(landedTask ? { taskId: landedTask.taskId } : {}),
+      ...(workspace.ownerAgentId ? { workerAgentId: workspace.ownerAgentId } : {}),
+      ...(coordinatorAgentId ? { coordinatorAgentId } : {}),
+      ...(landedTask?.teamId ?? worker?.teamId ? { teamId: landedTask?.teamId ?? worker!.teamId } : {}),
+      ...(workspace.orchestratorId ? { orchestratorId: workspace.orchestratorId } : {}),
+      ...(orchestrator?.hostname ?? worker?.machine ?? worker?.rig ? { host: orchestrator?.hostname ?? worker?.machine ?? worker!.rig } : {}),
+    });
+  } catch (error) {
+    console.error(`[landing-receipt] CRITICAL: failed to persist landed branch ${workspace.id}: ${errMessage(error)}`);
+  }
+}
+
+/**
+ * #239 — the land ANNOUNCEMENT: the durable `branch.landed`/`landed-success` bus events, the gated
+ * agent-facing pushes (author + agents-on-main fan-out, #234 store-ahead for offline authors), and
+ * the issue/Task lifecycle drives. #1790 — the settle path DEFERS this off its synchronous critical
+ * path; the durable receipt is recorded separately + synchronously by {@link recordLandingReceipt}.
+ */
+export function announceBranchLanded(input: BranchLandedInput): void {
+  const { workspace } = input;
+  const base = workspace.baseRef ?? "base";
+  // #1620 — a land that introduced ZERO commits is not a land. It happens when a reconciliation
+  // path re-reads a workspace whose branch carries no commits at all (a land-and-continue recycle
+  // cuts a fresh `<branch>-N` from base, so "already contained in base" is vacuously true) and
+  // concludes it landed. A no-op is neither an announcement of work reaching the base nor a record
+  // of WHICH branch/commits delivered it: the "🔀 merged to main" fan-out is a coordinator's cue to
+  // verify work and advance a plan, and the Task drive would repoint the deliverable's recorded
+  // branch at a branch with no content. So the no-op leaves one quiet, durable audit event — no
+  // landed-success wake, no merge notice, no Task mutation (and recordLandingReceipt wrote nothing).
+  if (input.landedCommitCount === 0) {
+    const noop = { workspaceId: workspace.id, repoRoot: workspace.repoRoot, branch: workspace.branch, base, author: workspace.ownerAgentId, reason: "land contributed zero commits" };
+    emitRelayEvent({ type: "workspace.land_noop", source: "server", subject: workspace.id, data: noop });
+    return;
+  }
+  const landedBranch = workspace.branch;
+  const shortSha = input.mergedSha ? input.mergedSha.slice(0, 12) : undefined;
+  const lifecycleLog = (message: string) => console.warn(message);
+  const landedTask = resolveLandedTask(input);
+  const idempotencyKey = landedNotificationIdempotencyKey(input, landedTask, base);
+  const landedTaskPayload = landedTask ? { taskId: landedTask.taskId, taskLabel: landedTask.taskLabel } : {};
+
+  // #1553/T1385 — `branch.landed` is the first-class land money-moment source for
+  // the Cosmos visualization (a shockwave from the agent → the galaxy core flares).
+  // Its frontend onLand handler reads `{agentId, repoRoot, headline, branch, sha}`;
+  // `agentId` (the landing author) and `headline` (a legible one-liner for the
+  // ticker) are added here alongside the existing `author`/`subject` so Cosmos no
+  // longer has to fragile-title-match `activity.created` for /landed|merge/i.
+  const landHeadline = input.subject?.trim() || `${landedBranch ?? "branch"} landed`;
+  emitRelayEvent({
+    type: "branch.landed",
+    source: "server",
+    subject: workspace.id,
+    data: {
+      workspaceId: workspace.id,
+      agentId: workspace.ownerAgentId,
+      headline: landHeadline,
+      repoRoot: workspace.repoRoot,
+      branch: landedBranch,
+      base,
+      sha: input.mergedSha,
+      subject: input.subject,
+      author: workspace.ownerAgentId,
+      newBranch: input.newBranch,
+      pushed: input.pushed,
+      ...landedTaskPayload,
+    },
+  });
+  emitRelayEvent({
+    type: "landed-success",
+    source: "server",
+    subject: workspace.id,
+    data: {
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      branch: landedBranch,
+      base,
+      sha: input.mergedSha,
+      subject: input.subject,
+      author: workspace.ownerAgentId,
+      newBranch: input.newBranch,
+      pushed: input.pushed,
+      notification: "landed-success",
+      ...landedTaskPayload,
+    },
+  });
+  // #482/#833 issue close FIRST, then the #831 Task drive: the Task's close PROJECTION
+  // (taskCloseBridge) reads the canonical close ledger the issue hook writes, so chaining makes the
+  // receipt accurate. Both are best-effort + isolated — a throw in either can never fail the merge
+  // (it already landed before notifyBranchLanded runs). A non-task branch makes the Task drive a no-op.
+  trackLandLifecycleDrive((async () => {
+    const taskIds = resolveLandedTaskIds(input);
+    const commitSubjects = await landedCommitSubjects(input, lifecycleLog);
+    try {
+      await handleLandedIssueLifecycle({ ...input, taskIds, commitSubjects }, { log: lifecycleLog });
+    } catch (error) {
+      console.warn(`issue lifecycle land hook failed for ${workspace.id}: ${errMessage(error)}`);
+    }
+    try {
+      await handleLandedTaskLifecycle({ ...input, taskIds, commitSubjects }, { log: lifecycleLog });
+    } catch (error) {
+      console.warn(`task lifecycle land hook failed for ${workspace.id}: ${errMessage(error)}`);
+    }
+  })());
+
+  const author = workspace.ownerAgentId;
+  const shaLabel = shortSha ? ` as \`${shortSha}\`` : "";
+  const subjectLabel = input.subject ? ` — "${input.subject}"` : "";
+  const payload = {
+    kind: "branch.landed",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: landedBranch,
+    base,
+    sha: input.mergedSha,
+    author,
+    newBranch: input.newBranch,
+    pushed: input.pushed,
+    ...landedTaskPayload,
+  };
+
+  // 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). A live owner continues in its worktree.
+  if (author) {
+    const branchLabel = landedBranch ? `\`${landedBranch}\`` : "Your branch";
+    const continueLabel = input.newBranch
+      ? ` You're now on \`${input.newBranch}\` — keep working there.`
+      : " Worktree reclaimed.";
+    // Durable (ttl null): the author's own branch landing must reach them even after they go
+    // offline (store-ahead #234) — not a bystander notice that goes stale.
+    const notices = routeNotification({
+      type: "branch.landed",
+      scope: { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+      recipients: [author],
+      ttlMs: null,
+      message: {
+        subject: "Your branch landed",
+        body: renderTemplate("notify.land.success", {
+          branch: branchLabel,
+          base,
+          sha: `${shaLabel}${subjectLabel}`,
+          publishLabel,
+          continueLabel,
+        }),
+        payload: { ...payload, notification: "landed-success" },
+        idempotencyKey,
+        replyExpected: false,
+      },
+    });
+    if (landedTask && input.mergedSha) {
+      for (const notice of notices) stampLifecycleSignal(notice.to, taskSignalKey(landedTask.taskId, "landed-on-main", input.mergedSha));
+    }
+  }
+
+  // Coordinator copy (#2837), informational. No explicit recipients: the router records the rule decision (#446).
+  const mainScope = { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id, teamId: landedTask?.teamId ?? (author ? getAgent(author)?.teamId : undefined), coordinatorAgentIds: [...new Set([resolveCoordinatorAgentId(author), landedTask && resolveTaskOwnerAgentId(getTaskDetail(landedTask.taskId))].filter((id): id is string => !!id && !isHumanAgentId(id)))] };
+  const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
+  const authorLabel = author ? ` by \`${author}\`` : "";
+  const notices = routeNotification({
+    type: "branch.landed",
+    scope: mainScope, ...audienceWithTaskOwnerRole("branch.landed", mainScope, landedTask?.taskId), // #2862
+    ttlMs: INFORMATIONAL_TTL_MS,
+    message: {
+      subject: `Merged to ${base}`,
+      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
+      payload: { ...payload, notification: "landed-success" },
+      idempotencyKey,
+      replyExpected: false,
+    },
+  });
+  if (landedTask && input.mergedSha) {
+    for (const notice of notices) stampLifecycleSignal(notice.to, taskSignalKey(landedTask.taskId, "landed-on-main", input.mergedSha));
+  }
+}
+
+/**
+ * #824 — a dirty base checkout left in a MIXED state after a land (HEAD advanced via ref
+ * plumbing, but the shared/primary working files did NOT catch up for some landed paths).
+ * The land itself SUCCEEDED — this is not a land failure — but the shared checkout now serves
+ * STALE content for those paths, which previously shipped a reverted file into a bootstrap
+ * publish (#823). The old behavior was a swallowed host-side `console.error`; this raises a
+ * LOUD, operator-visible signal (activity alert + a durable push to the owner and its
+ * coordinator) so the mixed state is reconciled before anything reads/builds/publishes from
+ * the checkout. Human WIP is never auto-clobbered; `preservedWipPaths` flags paths to merge by
+ * hand rather than blind-restore.
+ */
+export function notifyBaseWorktreeStrand(input: {
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+  sync: BaseWorktreeSyncResult;
+}): void {
+  const { workspace, sync } = input;
+  if (sync.reconciled) return;
+  const base = workspace.baseRef ?? "base";
+  const owner = workspace.ownerAgentId;
+  const coordinator = resolveCoordinatorAgentId(owner ?? undefined);
+  const fallback = stewardFallbackTarget();
+  const unsynced = sync.unsyncedPaths ?? [];
+  const preservedWip = sync.preservedWipPaths ?? [];
+  const pathLabel = unsynced.length ? unsynced.map((p) => `\`${p}\``).join(", ") : "(unknown paths)";
+  const wipLabel = preservedWip.length
+    ? ` Some carry uncommitted human WIP and were preserved (merge by hand, do NOT blind-restore): ${preservedWip.map((p) => `\`${p}\``).join(", ")}.`
+    : "";
+  const body = `⚠️ The shared \`${base}\` checkout under \`${workspace.repoRoot}\` is in a MIXED state after a land: HEAD advanced but these working files did NOT catch up — ${pathLabel}. Reads/builds/publishes from this checkout will see STALE content until reconciled (\`git -C ${workspace.repoRoot} restore --staged --worktree -- <path>\` for non-WIP paths).${wipLabel}`;
+
+  const payload = {
+    kind: "workspace.base-checkout-strand",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: workspace.branch,
+    base,
+    author: owner,
+    unsyncedPaths: unsynced,
+    preservedWipPaths: preservedWip,
+    reconciled: false,
+  };
+
+  emitRelayEvent({ type: "workspace.base_checkout_strand", source: "server", subject: workspace.id, data: payload });
+
+  createActivityEvent({
+    clientId: `workspace-base-strand-${workspace.id}-${Date.now()}`,
+    kind: "state",
+    title: "Base checkout stranded after land (mixed state)",
+    body: `${base} (${workspace.repoRoot}) — ${unsynced.length} landed path(s) out of sync with HEAD${preservedWip.length ? `, ${preservedWip.length} with human WIP` : ""}: ${unsynced.join(", ")}`,
+    meta: workspace.branch ?? workspace.id,
+    icon: "ti-alert-octagon",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-base-strand", workspaceId: workspace.id, repoRoot: workspace.repoRoot, unsyncedPaths: unsynced, preservedWipPaths: preservedWip },
+  });
+
+  // Durable (ttl null) push to the owner and its coordinator — whoever works in the shared
+  // checkout must learn it's stale before acting on it. Fallback steward covers a teamless land.
+  const recipients = [...new Set([owner, coordinator, fallback].filter((r): r is string => Boolean(r)))];
+  if (recipients.length) {
+    routeNotification({
+      type: "workspace.base_checkout_strand",
+      scope: { author: owner, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+      recipients,
+      ttlMs: null,
+      message: {
+        subject: "Base checkout left stale after land — reconcile before publishing",
+        body,
+        payload: { ...payload, notification: "base-checkout-strand" },
+        replyExpected: false,
+      },
+    });
+  }
+}
+
+/**
+ * Fatal land failure wake-up for the branch owner (#538). This is intentionally separate from
+ * steward-task/conflict pings: it tells the worker that its post-ready idle wait ended without
+ * a completed land, so it can inspect/report instead of silently staying parked forever.
+ */
+export function notifyBranchLandFailed(input: {
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+  commandId?: string;
+  recipients?: string[];
+  reason?: string;
+}): void {
+  const { workspace } = input;
+  const base = workspace.baseRef ?? "base";
+  const author = workspace.ownerAgentId;
+  const coordinator = resolveCoordinatorAgentId(author);
+  const reason = input.reason?.trim() || "workspace land failed";
+  const payload = {
+    kind: "landed-failure",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: workspace.branch,
+    base,
+    author,
+    commandId: input.commandId,
+    reason,
+  };
+
+  emitRelayEvent({
+    type: "landed-failure",
+    source: "server",
+    subject: workspace.id,
+    data: payload,
+  });
+
+  const recipients = withWorkspaceTaskOwnerRoles(input.recipients ?? [author, coordinator], workspace); // #2862
+  if (!recipients.length) return;
+  const branchLabel = workspace.branch ? `\`${workspace.branch}\`` : "Your branch";
+  routeNotification({
+    type: "landed-failure",
+    scope: { author, parent: coordinator ?? undefined, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+    recipients,
+    forceDelivery: true,
+    ttlMs: null,
+    message: {
+      subject: "Workspace land failed",
+      body: renderTemplate("notify.land.failure", { branch: branchLabel, base, reason }),
+      payload,
+      idempotencyKey: landFailureEventKey(workspace, input.commandId),
+      replyExpected: false,
+    },
+  });
+}
+
+export { notifyLandGateFailed, notifyLandGateWarnings, notifyLandGateSkipped } from "./land-gate-notifications";
+
+/**
+ * Steward-handoff awareness wake (#641/#642). When the relay can't auto-merge a branch and
+ * hands the workspace to a steward, the two ends used to be mutually blind: the branch agent
+ * was told only that land failed (never which steward holds it), and its coordinator — the
+ * agent responsible for the merge landing — was never looped in at all. This fires BOTH
+ * notices off one handoff event:
+ *   - the OWNER branch agent learns which steward took over (#641), and
+ *   - the branch agent's COORDINATOR (owner's `spawnedBy`, resolved in steward-identity.ts)
+ *     is proactively notified so it keeps the big picture (#642).
+ * The steward id is the managed steward's policy name (reachable via `policy:<name>`) or an
+ * elected steward's agent id, whichever the caller has in scope.
+ */
+export function notifyStewardHandoff(input: {
+  workspace: Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+  /** The steward now holding the merge — managed steward policy name or elected agent id. */
+  stewardId: string;
+  /** The branch agent's coordinator (owner's `spawnedBy` lineage), or null when none resolves. */
+  coordinatorAgentId?: string | null;
+  /** Why it was handed over ("conflict", "merge state unknown", auto-merge back-off, …). */
+  reason?: string;
+}): void {
+  const { workspace } = input;
+  const base = workspace.baseRef ?? "base";
+  const owner = workspace.ownerAgentId;
+  const coordinator = input.coordinatorAgentId?.trim() || undefined;
+  const branchLabel = workspace.branch ? `\`${workspace.branch}\`` : "Your branch";
+  const reasonLabel = input.reason ? ` (${input.reason})` : "";
+  const payload = {
+    kind: "workspace.steward-handoff",
+    workspaceId: workspace.id,
+    repoRoot: workspace.repoRoot,
+    branch: workspace.branch,
+    base,
+    author: owner,
+    stewardId: input.stewardId,
+    coordinatorAgentId: coordinator,
+    reason: input.reason,
+  };
+
+  emitRelayEvent({ type: "workspace.steward_handoff", source: "server", subject: workspace.id, data: payload });
+
+  // #641 — tell the owner branch agent which steward now holds its merge, so it stops
+  // thinking the branch silently failed. Durable (ttl null): the owner must learn this
+  // even if it went idle. Mirror the "don't touch main" guardrail of the landed-failure wake.
+  if (owner) {
+    routeNotification({
+      type: "workspace.steward_handoff",
+      scope: { author: owner, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+      recipients: [owner],
+      ttlMs: null,
+      message: {
+        subject: "Your merge is now with a steward",
+        body: renderTemplate("notify.land.steward-taken", {
+          branch: branchLabel,
+          base,
+          stewardId: input.stewardId,
+          reasonLabel,
+        }),
+        payload: { ...payload, notification: "steward-handoff" },
+        replyExpected: false,
+      },
+    });
+  }
+
+  // #642 — proactively loop in the branch agent's coordinator so it keeps the big picture
+  // (it spawned the branch agent and owns the merge landing). Skip when the coordinator IS
+  // the owner (no real lineage) to avoid a duplicate ping.
+  if (coordinator && coordinator !== owner) {
+    routeNotification({
+      type: "workspace.steward_handoff",
+      scope: { author: owner, parent: coordinator, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+      recipients: [coordinator],
+      ttlMs: null,
+      message: {
+        subject: "A branch agent's merge is now with a steward",
+        body: renderTemplate("notify.land.steward-taken.coordinator", {
+          owner: owner ?? "?",
+          branch: branchLabel,
+          base,
+          stewardId: input.stewardId,
+          reasonLabel,
+        }),
+        payload: { ...payload, notification: "steward-handoff", audience: "coordinator" },
+        replyExpected: false,
+      },
+    });
+  }
+}
+
+/**
+ * What the reconciliation did with the row: retired it (`merged`), or — when the owning
+ * agent is still alive — left it usable and only drained the steward/strand queues (#1631).
+ */
+export type LandedWorkspaceReconciliation = "merged" | "kept-live";
+
+// #1631 — every anchor that says "someone still owes this branch a land". Once the base contains
+// the branch's work there is nothing left for a steward to land, so a reconciliation that does NOT
+// retire the row must still drop these, or the hand-off watchdog would re-probe it every sweep
+// forever (and a stale strand anchor could re-page a coordinator about a settled branch).
+// #1662 — …and the loop-breaker is one of those anchors. `autoMergeNoProgressCount` kept
+// incrementing PAST the detection, which is what escalated to the auto-merge back-off and then woke
+// a steward for a branch with nothing to land; `mergeError` kept the last failed attempt's reason
+// live on a row that had since landed. Both are strictly about a land that is still owed, so the
+// detection that retires the land must retire them too.
+const DRAINED_LAND_STRAND_BOOKKEEPING = {
+  strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: undefined,
+  stewardWokenAt: undefined, stewardPolicy: undefined, stewardHandoffFirstAt: undefined, stewardWakeError: undefined, stewardWakeErrorAt: undefined, stewardWakeFailureNotifiedAt: undefined, stewardWakeFailureId: undefined,
+  stewardRewakeCount: undefined, stewardHandoffEscalatedAt: undefined,
+  ...CLEAR_MERGE_NO_PROGRESS, mergeError: undefined,
+};
+
+/**
+ * Finalize a workspace whose work landed in base out-of-band — a pr-strategy land whose
+ * PR merged (by anyone, incl. `gh pr merge`), or a squash/cherry-pick already in base
+ * (#304). Marks it terminal `merged`, records the merge SHA, and fires the same
+ * branch.landed push the local land path emits — a pr land never runs through the
+ * workspace.merge result handler, so without this the author never learns it shipped.
+ * Lives here (not maintenance.ts) so the giant doesn't grow and land-notify has one home.
+ *
+ * #1631 — with ONE exception, and it is the same one the orchestrator's no-op land already
+ * makes (#327, orchestrator/src/workspace-probe/merge.ts → resolveNoopMerge): liveness splits
+ * the outcome. Terminal `merged` is a RETIREMENT — the worktree becomes reclaimable and every
+ * lane stops treating the row as a place work can still land — so applying it to a workspace
+ * whose owning agent is still running bricks that agent's checkout out from under it: it keeps
+ * working, looks healthy, and can no longer commit or land. The host refuses that for a live
+ * owner (`deleteBranch === false` → recycle-to-continue, never terminal); this out-of-band
+ * sibling must refuse it too, or the sweeps quietly undo the host's guarantee. A live owner
+ * therefore keeps its non-terminal status here; the reconciliation still does its OTHER job
+ * (record the receipt, announce a real land, drain the steward/strand bookkeeping so no
+ * watchdog re-wakes or re-pages a branch with nothing left to land).
+ */
+export async function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: WorkspaceMergePreview): Promise<LandedWorkspaceReconciliation> {
+  const observedSha = typeof preview.prMergeSha === "string"
+    ? preview.prMergeSha
+    : typeof preview.landedSha === "string"
+      ? preview.landedSha
+      : undefined;
+  // #2558 — a "landed" sha equal to the workspace's OWN base sha is the base itself, never branch
+  // work. The strand settlement can confirm ancestry vacuously (tip == base, base already on main)
+  // and the host's landed proof reports the base-tip sha it used (git-state.ts); either shape
+  // arriving here must not be attributed. Retract it so nothing below stamps, receipts, announces,
+  // or drives a Task with the base sha.
+  const vacuousBaseSha = observedSha !== undefined && observedSha === ws.baseSha;
+  const sha = vacuousBaseSha ? undefined : observedSha;
+  // #1620 — `previewShowsNothingToLand` accepts "clean worktree, zero commits ahead", which is
+  // equally true of a branch whose work landed and of a branch that never carried work at all.
+  // With no merge sha AND a host-reported `ahead: 0` there is provably nothing on this branch, so
+  // the reconciliation contributed zero commits: still close the workspace out (that's this
+  // function's job — drain it from the steward/strand queues), but tell notifyBranchLanded not to
+  // announce a merge or rewrite the Task's deliverable record. #2558 — the vacuous base-sha
+  // attribution above is zero-commit regardless of what the preview reports for `ahead`.
+  const landedCommitCount = (!sha && preview.ahead === 0) || vacuousBaseSha ? 0 : undefined;
+  // #1631 — the same owner-liveness predicate (#204) the host's land path rides on, so the two
+  // sides cannot drift into disagreeing about whether a checkout may be retired.
+  const ownerAlive = isOwnerAlive(ws.ownerAgentId);
+  // #1696 — a durable receipt says this exact row was already landed. A later maintenance probe
+  // can still observe its clean, zero-unlanded-commit worktree, but that is reconciliation of a
+  // stale queue status, not a second landing: preserve the original receipt and do not replay the
+  // landed event/issue lifecycle. (A land-and-continue branch clears this receipt before it can
+  // become ready again, so a new hand-off remains detectable.)
+  const landedMeta = ws.landedAt !== undefined && ws.landedSha ? {} : { landedDetectedAt: Date.now(), landedVia: preview.prMerged === true ? "pr" : "git", ...(sha ? { landedSha: sha } : {}) };
+  if (sha && (ws.landedAt === undefined || !ws.landedSha)) await markWorkspaceLandedAsync(ws.id, sha);
+  // #1662 — a live owner must come OUT of the land queue, not merely carry a receipt saying it
+  // landed. `active` is the state chosen: the only status that is both outside LAND_OWED_STATUSES
+  // (so `landableWorkspaces` stops re-selecting it — re-selection is what re-dispatched a merge
+  // against an already-landed branch once per cycle) and still the live agent's own usable
+  // workspace. It is also exactly where the host's in-band land-and-continue recycle leaves a live
+  // owner (#423), so this out-of-band sibling now converges on the same state rather than inventing
+  // one, and `landReceipt` already reads ready→active as a successful land. The two other
+  // non-terminal candidates are both wrong: `merge_planned` has an in-flight watchdog that re-drives
+  // the merge, and `conflict` IS the steward escalation this bug ended in.
+  const nextStatus = ownerAlive && LAND_OWED_STATUSES.has(ws.status) ? "active" : ws.status;
+  if (ownerAlive) {
+    // The row stays non-terminal and still the agent's workspace; only the status that claims a land
+    // is still owed, plus the bookkeeping that made this reconciliation necessary, are cleared.
+    // `autoConflict`/`conflict` are deliberately left alone — the conflict scan owns restoring the
+    // pre-conflict status.
+    const livePatch = { ...landedMeta, ownerLiveLandReconciledAt: Date.now(), ...DRAINED_LAND_STRAND_BOOKKEEPING };
+    if (nextStatus === ws.status) await patchWorkspaceMetadataAsync(ws.id, livePatch);
+    else await updateWorkspaceStatusAsync(ws.id, nextStatus, { ...livePatch, landedFromStatus: ws.status });
+  } else {
+    await updateWorkspaceStatusAsync(ws.id, "merged", { ...landedMeta, autoMerged: true, mergedFromStatus: ws.status, autoConflict: false });
+  }
+  await finishWorkspaceStewardHandoff(ws);
+  if (ws.landedAt !== undefined && ws.landedSha) return ownerAlive ? "kept-live" : "merged";
+  const landedLabel = landedCommitCount === 0 ? "carries no commits" : preview.prMerged === true ? "is merged on the remote (PR)" : "is already merged into base";
+  const closure = ownerAlive
+    ? `owner \`${ws.ownerAgentId}\` is still running, so the workspace stays non-terminal and usable at ${nextStatus}${nextStatus === ws.status ? "" : ` (was ${ws.status} — out of the land queue, #1662)`} (#1631); steward/strand and no-progress bookkeeping cleared`
+    : `marking merged${landedCommitCount === 0 ? "; nothing was landed" : ""}`;
+  createActivityEvent({
+    clientId: "server-workspace-" + ws.id + "-merged-" + Date.now(),
+    kind: "state",
+    title: ownerAlive
+      ? "Workspace reconciled but kept live (owner still running)"
+      : landedCommitCount === 0 ? "Workspace closed out with nothing to land" : "Workspace work landed in base",
+    body: `${ws.branch ?? ws.id} ${landedLabel} ${preview.baseRef ? `(${preview.baseRef})` : ""} — ${closure}`,
+    meta: ws.branch ?? ws.id,
+    icon: "ti-git-merge",
+    view: "orchestrators",
+    metadata: { source: "server", maintenanceJobId: "workspace-conflict-scan", workspaceId: ws.id, fromStatus: ws.status, toStatus: nextStatus, ...(ownerAlive ? { ownerAlive: true, keptLive: true } : {}), ...(sha ? { landedSha: sha } : {}), ...(landedCommitCount === 0 ? { landedCommitCount: 0 } : {}) },
+  });
+  try {
+    notifyBranchLanded({ workspace: ws, mergedSha: sha, landedTipSha: sha, commitShas: sha ? [sha] : [], pushed: true, prLand: preview.prMerged === true, ...(landedCommitCount === 0 ? { landedCommitCount } : {}) });
+  } catch {
+    // Notification is best-effort; the status change + activity event still stand.
+  }
+  return ownerAlive ? "kept-live" : "merged";
+}