@humwick/server 0.0.0-stage → 0.130.1

package/src/workspace-command-settle.ts

@@ -0,0 +1,589 @@
+import { commandFailureReason, settleWorkspaceCleanupCommand, type WorkspaceCommandSettleResult } from "./workspace-cleanup-settle";
+export { type WorkspaceCommandSettleResult } from "./workspace-cleanup-settle";
+import { fireAndForget, isRecord, sanitizeFsName, stringValue, type LandGateAttestation, type LandGateRunResult } from "@humwick/sdk";
+import { storeTextArtifact } from "./artifact-text";
+import { announceBranchLanded, notifyBaseWorktreeStrand, notifyBranchLandFailed, notifyLandGateFailed, notifyLandGateSkipped, notifyLandGateWarnings, recordLandingReceipt } from "./branch-landed";
+import { getWorkspace, getArtifactAsync, insertLandGateAttestation, listOrchestrators, markWorkspaceLanded, patchWorkspaceMetadataAsync, releaseMergeLease, setWorkspaceBranchAsync, updateWorkspaceStatusAsync, markWorkspaceLandedAsync} from "./db";
+import { parseOwnerRepoFromRemote, repoFromGitRemote } from "./services/git-remote";
+import { deferLandSettleSideEffect } from "./land-settle-dispatch";
+import { recordConfirmedLandBoundary } from "./services/land-boundary-settle";
+import { handleReviewerMergeResult } from "./reviewer-pipeline";
+import { notifyLandUnconfirmed, verifyWorkspaceLandedAncestry } from "./services/landed-ancestry";
+import { VALID_WORKSPACE_STATUSES, cleanString, optionalEnum } from "./validation";
+import { CLEAR_MERGE_NO_PROGRESS, CLEAR_MERGE_RETRY, mergeCommandKilledWithoutVerdict, mergeRetryEnqueuedAtPatch, mergeRetryScopeForLand, noteMergeNoProgress, noteMergeRetryAttempt, retryableMergeResultCause } from "./workspace-merge-progress";
+import { settleRestartKilledLand } from "./services/land-restart-retry";
+import { claimMetadataPatch, landGraceMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import { finishWorkspaceStewardHandoff } from "./steward-handoff";
+import { commandTargetsWorkspaceOwner } from "./workspace-host";
+import { workspaceMergeProvesLand } from "./workspace-land-result";
+import { workspaceShowsDetectedLand } from "./workspace-phase";
+import type { Command, WorkspaceStatus } from "./types";
+import { reconcileLegacyLandingExecution } from "./services/legacy-landing-recovery";
+import { recordLandGateQueueProgress } from "./land-gate-queue-progress";
+import { emitWorkspaceTaskSemanticNotifications } from "./services/task-lifecycle";
+import { resolveLandedTaskIds } from "./services/landed-task-attribution";
+import { landFailureEventKey } from "./land-failure-event-key";
+import { recordLandStopped } from "./workspace-land-stopped";
+import { landConflictPathsPatch, superviseLandConflictLater } from "./workspace-conflict-resolver";
+import { notifyNothingToLand } from "./workspace-nothing-to-land-notice";
+import { recordLandingTiming } from "./land-telemetry";
+
+export interface WorkspaceCommandSettleOptions {
+  /** Recover a missing receipt using the original command settlement clock. */
+  recoverLandedIngress?: boolean;
+  // #1473 — baseRef is the branch that just settled its OWN merge attempt (succeeded or not);
+  // callers use it to target a re-sweep at only the workspaces sharing that base, instead of
+  // flooding every ready-to-land workspace in the repo on every single settle.
+  onMergeSettled?: (repoRoot: string | undefined, baseRef: string | undefined) => void;
+}
+
+const WORKSPACE_MERGE_SETTLED_STATUSES = new Set(["succeeded", "failed", "timed_out", "rejected", "canceled"]);
+const WORKSPACE_MERGE_FAILED_STATUSES = new Set(["failed", "timed_out", "rejected", "canceled"]);
+const WORKSPACE_LAND_PROGRESS_STATUSES = new Set<WorkspaceStatus>(["gate_running", "merging"]);
+const WORKSPACE_MERGE_ACTIVE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "gate_running", "merging"]);
+const WORKSPACE_LAND_PROGRESS_TRANSITIONS = new Map<WorkspaceStatus, ReadonlySet<WorkspaceStatus>>([
+  ["merge_planned", new Set<WorkspaceStatus>(["gate_running"])],
+  ["gate_running", new Set<WorkspaceStatus>(["merging"])],
+]);
+
+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,
+    ...(value.failureReason === "gate-run-cap" || value.failureReason === "gate-slot-hold-cap" ? { failureReason: value.failureReason } : {}),
+    durationMs: typeof value.durationMs === "number" ? value.durationMs : 0,
+    ...(typeof value.queuedMs === "number" && value.queuedMs >= 0 ? { queuedMs: value.queuedMs } : {}),
+    outputTail: typeof value.outputTail === "string" ? value.outputTail : "",
+    output: typeof value.output === "string" ? value.output : (typeof value.outputTail === "string" ? value.outputTail : ""),
+    outputArtifactId: typeof value.outputArtifactId === "string" ? value.outputArtifactId : undefined,
+    outputTruncated: value.outputTruncated === true ? true : undefined,
+  };
+}
+
+function normalizeGateWarnings(value: unknown): LandGateRunResult[] {
+  if (!Array.isArray(value)) return [];
+  return value.map(normalizeGateRunResult).filter((g): g is LandGateRunResult => Boolean(g));
+}
+
+function normalizeCommitShas(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const shas = [...new Set(value.map((sha) => cleanString(sha, "result.landedCommitShas[]", { max: 64 })).filter((sha): sha is string => Boolean(sha)))];
+  return shas.length > 0 ? shas : undefined;
+}
+
+// The host reports every commit this attempt introduced onto the base. An explicit empty list is
+// conclusive evidence that the push was a Git no-op, even if an older host incorrectly marked it
+// as merged and copied the base tip's SHA/subject into the result. Normalize at the server boundary
+// so such a receipt cannot persist as a landed merge or reach task-delivery notifications.
+function normalizeNoProgressMergeResult(result: Record<string, unknown>): Record<string, unknown> {
+  if (result.merged !== true || !Array.isArray(result.landedCommitShas) || result.landedCommitShas.length !== 0) return result;
+  const normalized = { ...result };
+  normalized.merged = false;
+  normalized.noop = true;
+  normalized.status = "review_requested";
+  normalized.landedCommitShas = [];
+  normalized.error = cleanString(result.error, "result.error", { max: 500 })
+    ?? "merge made no progress: no commits were introduced onto the base";
+  delete normalized.mergedSha;
+  delete normalized.subject;
+  delete normalized.pushed;
+  return normalized;
+}
+
+/**
+ * #1744 F1 — parse the orchestrator's tree-keyed land-gate attestation at the SERVER boundary.
+ *
+ * Every field is re-validated here rather than trusted: this record is what lets cd-watcher deploy a
+ * tree to the fleet without its own CI run, so a malformed, partial or downgraded claim must decode
+ * to `undefined` (→ no row → the pre-existing green-ci.yml path) and never to a weaker-but-accepted
+ * pass. `level` is checked against the literal "full" for the same reason `gatesRan > 0` is required:
+ * the only thing that may stand in for a full CI run is a full gate that actually executed.
+ */
+function normalizeLandGateAttestation(value: unknown): LandGateAttestation | undefined {
+  if (!isRecord(value)) return undefined;
+  const treeSha = typeof value.treeSha === "string" ? value.treeSha.trim().toLowerCase() : "";
+  if (!/^[0-9a-f]{40}$/.test(treeSha)) return undefined;
+  if (value.level !== "full") return undefined;
+  // The digest is what a consumer actually compares against the LANDED tree's own required-gate
+  // definitions, so an absent or malformed one must decode to nothing rather than to an attestation
+  // that can only be checked by name (which a branch can keep while swapping a gate's command).
+  const gatesDigest = typeof value.gatesDigest === "string" ? value.gatesDigest.trim().toLowerCase() : "";
+  if (!/^[0-9a-f]{64}$/.test(gatesDigest)) return undefined;
+  const gatesRan = typeof value.gatesRan === "number" && Number.isSafeInteger(value.gatesRan) ? value.gatesRan : 0;
+  if (gatesRan <= 0) return undefined;
+  if (!Array.isArray(value.gateNames)) return undefined;
+  const gateNames = value.gateNames.map((name) => (typeof name === "string" ? name.trim() : "")).filter(Boolean);
+  if (gateNames.length === 0) return undefined;
+  // #3362 — an unknown coverage value must never decode as the absent (full) one.
+  if (value.suiteCoverage !== undefined && value.suiteCoverage !== "full" && value.suiteCoverage !== "partial") return undefined;
+  return { treeSha, level: "full", gatesDigest, gateNames, gatesRan, ...(value.suiteCoverage === "partial" ? { suiteCoverage: "partial" as const } : {}) };
+}
+
+function normalizeGateSkipped(value: unknown): { level: "subset" | "none"; reason: string; by: string; commit?: string } | undefined {
+  if (!isRecord(value)) return undefined;
+  const level = value.level === "subset" || value.level === "none" ? value.level : undefined;
+  const reason = typeof value.reason === "string" ? value.reason : undefined;
+  const by = typeof value.by === "string" ? value.by : undefined;
+  const commit = typeof value.commit === "string" ? value.commit : undefined;
+  return level && reason && by ? { level, reason, by, commit } : undefined;
+}
+
+/** #2474 — a linked gate-log artifact is only trustworthy when it IS this gate's log. The
+ * shipped `outputArtifactId` arrives over the authenticated orchestrator command channel, but
+ * existence alone proves nothing: any valid, unrelated `art_*` id would otherwise be emitted to
+ * the worker as the gate's full log (a forged/broken link). Require the land-gate identity —
+ * kind + workspaceId + gate name/command — and, when the workspace names its orchestrator, that
+ * the reporting orchestrator component uploaded it; anything else falls back to the tail upload. */
+function linkedGateOutputArtifactMatches(
+  linked: NonNullable<Awaited<ReturnType<typeof getArtifactAsync>>>,
+  workspaceId: string,
+  gate: LandGateRunResult,
+  orchestratorId: string | undefined,
+  expectedKind: "land-gate-output" | "land-gate-warning-output" = "land-gate-output",
+): boolean {
+  const metadata = isRecord(linked.metadata) ? linked.metadata : {};
+  if (metadata.kind !== expectedKind) return false;
+  if (metadata.workspaceId !== workspaceId) return false;
+  if (metadata.gateName !== gate.name) return false;
+  // #2474 R2 — UNCONDITIONAL: `gate.command` may legitimately be "" (normalizeGateRunResult), and
+  // gating the comparison on truthiness let a same-name artifact carrying a DIFFERENT command —
+  // a different gate reusing the name — link as this gate's log. cleanMeta preserves empty
+  // strings, so the orchestrator's own upload for an empty-command gate round-trips "" and links.
+  if (metadata.gateCommand !== gate.command) return false;
+  if (orchestratorId) return linked.createdBy === `orchestrator:${orchestratorId}`;
+  return typeof linked.createdBy === "string" && linked.createdBy.startsWith("orchestrator:");
+}
+
+async function uploadGateOutputArtifact(workspaceId: string, gate: LandGateRunResult, orchestratorId: string | undefined): Promise<string | undefined> {
+  // #2474 — when the orchestrator offloaded the FULL output before its pre-PATCH clip, it arrives
+  // as `outputArtifactId` and `gate.output` is only the ~6 KiB tail. Link the orchestrator's
+  // artifact by id — after the provenance check above — instead of re-uploading the tail as a
+  // fake "full log" (that re-upload is exactly what blinded failed-gate diagnosis). Older
+  // orchestrators, a dangling id, or a mismatched/unrelated artifact all fall back to storing
+  // `gate.output` verbatim, the pre-#2474 behavior.
+  if (gate.outputArtifactId) {
+    try {
+      const linked = await getArtifactAsync(gate.outputArtifactId);
+      if (linked && linkedGateOutputArtifactMatches(linked, workspaceId, gate, orchestratorId)) return linked.id;
+      console.warn(`land-gate artifact link rejected for ${workspaceId} gate "${gate.name}": artifact ${gate.outputArtifactId} ${linked ? "does not match this gate's identity" : "not found"}; falling back to tail upload`);
+    } catch (error) {
+      console.warn(`land-gate artifact link failed for ${workspaceId} gate "${gate.name}" (${gate.outputArtifactId}): ${String(error)}; falling back to tail upload`);
+    }
+  }
+  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;
+  }
+}
+
+export async function settleWorkspaceMergeCommand(command: Command, opts: WorkspaceCommandSettleOptions = {}): Promise<WorkspaceCommandSettleResult> {
+  if (command.type !== "workspace.merge") return { settled: false };
+  // A fenced legacy terminal is actionable only with positive execution proof written by the same
+  // ownership-aware transaction that terminalized it. TTL alone, a generic status patch, or an
+  // unclassified pre-hardening row cannot release the lane/lease or schedule a replacement land.
+  if (WORKSPACE_MERGE_SETTLED_STATUSES.has(command.status)
+    && command.landingContainmentMode === "cgroup-v2-close-v1" && !command.terminalProcessProof) {
+    const proven = await reconcileLegacyLandingExecution(command, listOrchestrators(), Date.now());
+    if (!proven) return { settled: false };
+    command = proven;
+  }
+  const terminalSettled = WORKSPACE_MERGE_SETTLED_STATUSES.has(command.status);
+  if (terminalSettled && command.landingContainmentMode === "legacy-unfenced-v0") releaseMergeLease({ commandId: command.id });
+  const settledRepoRoot = typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined;
+  const settledBaseRef = typeof command.params.baseRef === "string" ? command.params.baseRef : undefined;
+  let transitionCompleted = false;
+  try {
+    return await settleWorkspaceMergeCommandResult(command, () => { transitionCompleted = true; }, opts);
+  } finally {
+    if (terminalSettled) recordLandingTiming(command);
+    // Snapshotting the event-driven candidate list is synchronous. Fire only after every terminal
+    // branch below has durably moved the row out of merge_planned and recorded its retry attempt.
+    if (terminalSettled && transitionCompleted) opts.onMergeSettled?.(settledRepoRoot, settledBaseRef);
+  }
+}
+
+async function settleWorkspaceMergeCommandResult(command: Command, markTransitionCompleted: () => void, opts: WorkspaceCommandSettleOptions): Promise<WorkspaceCommandSettleResult> {
+  if (command.status === "running" && isRecord(command.result)) {
+    const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+    const progressStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+    if (!workspaceId || !progressStatus || !WORKSPACE_LAND_PROGRESS_STATUSES.has(progressStatus)) return { settled: false };
+    const workspace = getWorkspace(workspaceId);
+    if (!workspace || !WORKSPACE_MERGE_ACTIVE_STATUSES.has(workspace.status)) return { settled: true };
+    if (!commandTargetsWorkspaceOwner(command, workspace)) return { settled: true, ignoredWrongOwner: true };
+    // Progress belongs to the command recorded when this land attempt was claimed. A delayed PATCH
+    // from an older attempt must not take over the row, and phases may only advance through the
+    // pipeline (never merging -> gate_running, for example).
+    if (workspace.metadata.mergeCommandId !== command.id) return { settled: true };
+    await recordLandGateQueueProgress(workspace, command.id, command.result);
+    if (!WORKSPACE_LAND_PROGRESS_TRANSITIONS.get(workspace.status)?.has(progressStatus)) return { settled: true };
+    await updateWorkspaceStatusAsync(workspaceId, progressStatus);
+    return { settled: true };
+  }
+  if (command.status === "succeeded" && isRecord(command.result)) {
+    const mergeResult = normalizeNoProgressMergeResult(command.result);
+    if (await handleReviewerMergeResult(command, mergeResult, markTransitionCompleted)) return { settled: true };
+    const workspaceId = cleanString(mergeResult.workspaceId, "result.workspaceId", { max: 160 });
+    const resultStatus = optionalEnum(mergeResult.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+    if (!workspaceId || !resultStatus) return { settled: true };
+    const landedWorkspace = getWorkspace(workspaceId);
+    if (landedWorkspace && !commandTargetsWorkspaceOwner(command, landedWorkspace)) return { settled: true, ignoredWrongOwner: true };
+    if (landedWorkspace && typeof landedWorkspace.metadata.mergeCommandId === "string"
+      && landedWorkspace.metadata.mergeCommandId !== command.id) return { settled: true };
+    const newBranch = cleanString(mergeResult.newBranch, "result.newBranch", { max: 240 });
+    const resultError = cleanString(mergeResult.error, "result.error", { max: 500 });
+    const errorNonLand = mergeResult.merged !== true && Boolean(resultError);
+    // #1713 — extract the landed shas up front: the ancestry gate below must run BEFORE we decide
+    // whether this "merged" result may advance any land-state.
+    const mergedSha = cleanString(mergeResult.mergedSha, "result.mergedSha", { max: 64 });
+    const baseSha = cleanString(mergeResult.baseSha, "result.baseSha", { max: 64 });
+    const previousBaseSha = cleanString(mergeResult.previousBaseSha, "result.previousBaseSha", { max: 64 });
+    const nothingBase = isRecord(mergeResult.nothingToLand) && typeof mergeResult.nothingToLand.onBaseSha === "string"
+      && /^[0-9a-f]{40,64}$/.test(mergeResult.nothingToLand.onBaseSha) && mergeResult.noop === true && !resultError
+      ? mergeResult.nothingToLand.onBaseSha : undefined;
+    const landedCommitShas = normalizeCommitShas(mergeResult.landedCommitShas);
+    // #1620 — an EXPLICIT empty array means the land put NO commits on the base (a vacuous rebase of a
+    // commitless branch): a no-op, not a land. An absent field stays undefined so a real land is never
+    // silenced.
+    const landedCommitCount = Array.isArray(mergeResult.landedCommitShas) ? landedCommitShas?.length ?? 0 : undefined;
+    const prLanded = isRecord(command.params.prLanded) ? command.params.prLanded : undefined;
+    const authoritativeLandedSha = prLanded
+      ? cleanString(prLanded.sha, "params.prLanded.sha", { max: 64 }) ?? baseSha ?? mergedSha
+      // `mergedSha` is the rebased/cherry-picked worker tip; `baseSha` is the exact base tip the
+      // orchestrator advanced main to and PUSHED (orchestrator merge.ts `baseSha: baseTip`, where
+      // baseTip is main's NEW tip — headSha on a fast-forward, the merge commit on a no-ff), so it is
+      // the real on-main sha and the durable receipt. `previousBaseSha` is main's OLD tip (never used here).
+      : baseSha ?? mergedSha;
+    // #1713 — "the host said merged: true" is a STATUS claim, and every status claim in this area has
+    // been wrong at least once. Verify the sha is genuinely an ancestor of the target ref BEFORE any
+    // land-state is written. A PR land is verified out-of-band by the remote, and a proven zero-commit
+    // no-op is a non-land handled below — both skip the git check. A merged:true the ref cannot CONFIRM
+    // is treated exactly like a retryable non-land: NO land-state is written (no `merged`, no landed
+    // stamp, no receipt/reap), an explicit unconfirmed signal fires, and the workspace stays
+    // re-probeable so the auto-merge sweep (reconcileLandedWorkspace is git-preview-derived) recovers a
+    // genuine-but-unverifiable land on its next pass instead of it being stranded as falsely-landed.
+    const landTargetRef = landedWorkspace?.baseRef ?? "main";
+    const landAncestry = mergeResult.merged === true && !prLanded && landedCommitCount !== 0 && landedWorkspace
+      ? await verifyWorkspaceLandedAncestry(landedWorkspace.repoRoot, authoritativeLandedSha, landTargetRef, cleanString(mergeResult.landVerifiedSha, "result.landVerifiedSha", { max: 64 }))
+      : "confirmed";
+    const ancestryUnconfirmed = landAncestry !== "confirmed";
+    const normalizedStatus = ancestryUnconfirmed
+      ? "review_requested"
+      : errorNonLand && resultStatus === "merge_planned"
+      ? "review_requested"
+      : mergeResult.merged === true
+      && !newBranch
+      && ["review_requested", "merge_planned", "gate_running", "merging", "landed", "merged", "conflict"].includes(resultStatus)
+      ? "landed"
+      : resultStatus;
+    // #1249/#1242 — a merge command can "succeed" (the executor returned a result) while the land
+    // did NOT happen: a plain-git rebase conflict or push-rejected-after-retries returns
+    // `merged:false` with `landMechanism:"plain-git"`. Managed conflicts get re-detected by the
+    // periodic conflict scan, but plain-git (now the instance default) has no such re-detection —
+    // its re-preview looks landable, so the land silently loops with no steward. Gate strictly on a
+    // plain-git non-land (a legitimately in-flight PR land is merged:false but managed, so it is
+    // untouched): preserve the no-progress loop-breaker + the merge error instead of clearing them,
+    // so the auto-merge lane escalates via escalateNoProgressMerge → wakeRepoSteward (which also
+    // wakes the owner, cooldown-guarded) once the plain-git land keeps failing. #1713 folds an
+    // ancestry-unconfirmed merged:true into the same loop-breaker: a host that keeps reporting a land
+    // the ref never shows should escalate, not silently loop.
+    // #2718 — an error-free noop is an already-landed re-fire (the executor proved the tip is on
+    // origin/<base>), never a non-land.
+    const plainGitNonLand = mergeResult.merged !== true && mergeResult.landMechanism === "plain-git"
+      && !(mergeResult.noop === true && !resultError);
+    // Queue waits, superseded gates and transport outages use bounded retries instead of
+    // no-progress strikes: none produced a gate verdict (#2473, #2613, #2808).
+    const retryCause = retryableMergeResultCause({ mergeResult });
+    const queueRefusal = retryCause !== undefined;
+    const retryableNonLand = plainGitNonLand || errorNonLand || ancestryUnconfirmed || queueRefusal;
+    const nonLandReason = resultError
+      ?? (landAncestry === "not-ancestor"
+        ? `merge reported success but ${authoritativeLandedSha ?? "the landed sha"} is not on ${landTargetRef}`
+        : landAncestry === "unresolvable"
+        ? `could not verify ${authoritativeLandedSha ?? "the landed sha"} reached ${landTargetRef}`
+        : mergeResult.conflict === true ? "plain-git rebase conflict" : "plain-git land did not land");
+    // #1474 facet 1 — a real land consumes the steward's claim and thereby its claim-bound
+    // authorization to report the outcome. Capture the (unexpired) claim holder BEFORE clearing it
+    // and hand it a bounded post-land grace so it can still summarize what landed to the coordinator.
+    // A plain-git non-land didn't actually land, so it gets a plain claim clear — no grace.
+    const landConsumedClaimBy = retryableNonLand ? undefined : workspaceActiveClaim(landedWorkspace ?? { metadata: {} })?.by;
+    const retryScope = retryCause
+      ? mergeRetryScopeForLand(
+        landedWorkspace?.metadata ?? {},
+        retryCause,
+        command.params.expectedHeadSha,
+      )
+      : undefined;
+    if (nothingBase) await recordLandStopped(workspaceId, "nothing-to-land", undefined, { final: true, onBaseSha: nothingBase, headSha: typeof command.params.expectedHeadSha === "string" ? command.params.expectedHeadSha : undefined });
+    // #2718 — the landing host's own remote identity first; the hub's checkout as a fallback.
+    const landRepo = (repoRoot: string) => parseOwnerRepoFromRemote(typeof command.params.remoteIdentity === "string"
+      && command.params.remoteIdentity.startsWith("remote:") ? command.params.remoteIdentity : undefined) ?? repoFromGitRemote(repoRoot);
+    if (!ancestryUnconfirmed && mergeResult.merged === true && !prLanded && landedCommitCount !== 0 && landedWorkspace) {
+      await recordConfirmedLandBoundary({ command, workspace: landedWorkspace, result: mergeResult,
+        remote: () => landRepo(landedWorkspace.repoRoot), previousBaseSha, tipSha: authoritativeLandedSha,
+        taskIds: resolveLandedTaskIds({ workspace: landedWorkspace,
+          sourceHeadSha: typeof command.params.expectedHeadSha === "string" ? command.params.expectedHeadSha : undefined }) });
+    }
+    const transitioned = await updateWorkspaceStatusAsync(workspaceId, normalizedStatus, {
+      ...(!retryableNonLand ? CLEAR_MERGE_RETRY : {}),
+      mergeResult,
+      mergeCommandId: command.id,
+      landGateQueue: undefined,
+      mergedAt: opts.recoverLandedIngress ? command.updatedAt : Date.now(),
+      ...(retryableNonLand
+        ? queueRefusal
+          ? { ...noteMergeRetryAttempt(landedWorkspace?.metadata ?? {}, Date.now(), retryScope), mergeError: nonLandReason, ...mergeRetryEnqueuedAtPatch(mergeResult, command) }
+          : { ...noteMergeNoProgress(landedWorkspace?.metadata ?? {}), mergeError: nonLandReason, ...(plainGitNonLand ? { lastPlainGitLandFailAt: Date.now() } : {}),
+              // #2772 — a retryable non-queue outcome starts a fresh queue entry: never carry a stale keep-place time.
+              mergeRetryEnqueuedAt: undefined }
+        : { ...CLEAR_MERGE_NO_PROGRESS, mergeError: undefined }),
+      ...(normalizedStatus !== resultStatus ? { mergeStatusNormalizedFrom: resultStatus } : {}),
+      ...(landConsumedClaimBy ? landGraceMetadataPatch(landConsumedClaimBy) : claimMetadataPatch(true)),
+    });
+    if (transitioned) markTransitionCompleted();
+    if (retryableNonLand) {
+      if (ancestryUnconfirmed && landedWorkspace) {
+        const ws = transitioned ?? landedWorkspace;
+        deferLandSettleSideEffect("land-unconfirmed", () => notifyLandUnconfirmed({ workspace: ws, commandId: command.id, sha: authoritativeLandedSha, targetRef: landTargetRef, kind: landAncestry }));
+      }
+      return { settled: true };
+    }
+    const noopBase = nothingBase ?? (mergeResult.noop === true && !resultError && mergeResult.landMechanism !== "plain-git" && (resultStatus === "merged" || resultStatus === "active") && typeof baseSha === "string" && /^[0-9a-f]{40,64}$/.test(baseSha) ? baseSha : undefined);
+    if (noopBase && landedWorkspace) await finishWorkspaceStewardHandoff(landedWorkspace);
+    if (noopBase && landedWorkspace) deferLandSettleSideEffect("nothing-to-land", () => notifyNothingToLand(landedWorkspace, noopBase, command.id, typeof command.params.expectedHeadSha === "string" ? command.params.expectedHeadSha : undefined));
+    const landConfirmed = !nothingBase && workspaceMergeProvesLand(mergeResult, command.params);
+    const continuationBranch = normalizedStatus === "active" ? landedWorkspace?.branch : undefined;
+    // #1790 F1 — build the land notice up front so the durable RECEIPT can be written SYNCHRONOUSLY,
+    // BEFORE markWorkspaceLanded below arms the #1696 "already recorded" guard (branch-landed.ts). A
+    // crash / graceful SIGTERM between the state write and the deferred announcement can then never
+    // strand a `merged` row with no receipt. The heavy announcement fan-out still defers off the hot
+    // path. (`merged:true` is confirmed here; an unconfirmed verdict already returned above, #1713.)
+    const landedNotice = (mergeResult.merged === true || prLanded) && landedWorkspace
+      ? {
+        workspace: landedWorkspace,
+        ...(opts.recoverLandedIngress ? { landedAt: command.updatedAt } : {}),
+        taskIds: resolveLandedTaskIds({ workspace: landedWorkspace,
+          sourceHeadSha: typeof command.params.expectedHeadSha === "string" ? command.params.expectedHeadSha : undefined }),
+        mergedSha: authoritativeLandedSha,
+        // Git/PR titles have no 200-character limit. Bound display text without rejecting the land (#3244).
+        subject: stringValue(prLanded ? prLanded.subject : mergeResult.subject)?.slice(0, 200),
+        prLand: Boolean(prLanded),
+        landedBaseSha: prLanded ? landedWorkspace.baseSha : previousBaseSha ?? landedWorkspace.baseSha,
+        landedTipSha: prLanded ? cleanString(prLanded.sha, "params.prLanded.sha", { max: 64 }) ?? mergedSha : baseSha ?? mergedSha,
+        commitShas: prLanded ? [cleanString(prLanded.sha, "params.prLanded.sha", { max: 64 }) ?? mergedSha].filter((sha): sha is string => Boolean(sha)) : landedCommitShas,
+        newBranch: newBranch ?? continuationBranch,
+        pushed: prLanded ? true : typeof mergeResult.pushed === "boolean" ? mergeResult.pushed : undefined,
+        ...(prLanded || landedCommitCount === undefined ? {} : { landedCommitCount }),
+      }
+      : undefined;
+    if (landedNotice) recordLandingReceipt(landedNotice);
+    // #1744 F1 — record the tree-keyed land-gate attestation. Placed HERE, not at the executor, so
+    // that "the full gate passed on tree T" only becomes deployable evidence once the relay has
+    // CONFIRMED (ancestry-gated above, #1713) that T actually reached the base ref: a gated attempt
+    // whose push lost the lease, or a merged:true the ref cannot show, returned as a retryable
+    // non-land long before this point and leaves no attestation behind. A PR land is excluded by
+    // construction — `prLanded` never carries one, because the remote (not this gate) composed the
+    // tree that merged. Failures are swallowed: the branch already landed, and the only cost of a
+    // missing attestation is that cd-watcher falls back to waiting for its own ci.yml run.
+    const attestation = mergeResult.merged === true && !prLanded ? normalizeLandGateAttestation(mergeResult.landGateAttestation) : undefined;
+    if (attestation && landedWorkspace && authoritativeLandedSha && landedCommitCount !== 0) {
+      try {
+        const repo = landRepo(landedWorkspace.repoRoot);
+        // No resolvable origin ⇒ no shared identity with cd-watcher's detection clone ⇒ no row.
+        if (repo) {
+          insertLandGateAttestation({
+            repo,
+            treeSha: attestation.treeSha,
+            commitSha: authoritativeLandedSha,
+            baseRef: landTargetRef,
+            level: attestation.level,
+            gatesDigest: attestation.gatesDigest,
+            gateNames: attestation.gateNames,
+            gatesRan: attestation.gatesRan,
+            workspaceId: landedWorkspace.id,
+            ...(attestation.suiteCoverage ? { suiteCoverage: attestation.suiteCoverage } : {}),
+          });
+        }
+      } catch (error) {
+        console.warn(`[land-gate-attestation] failed to record tree ${attestation.treeSha.slice(0, 12)} for ${workspaceId}: ${String(error)}`);
+      }
+    }
+    if (landConfirmed && (normalizedStatus === "landed" || normalizedStatus === "merged") && authoritativeLandedSha) {
+      await markWorkspaceLandedAsync(workspaceId, authoritativeLandedSha, opts.recoverLandedIngress ? command.updatedAt : undefined);
+      if (landedWorkspace) await finishWorkspaceStewardHandoff(landedWorkspace);
+    }
+    if (newBranch && newBranch !== landedWorkspace?.branch) await setWorkspaceBranchAsync(workspaceId, newBranch, baseSha ?? mergedSha);
+    const baseWorktreeSync = isRecord(mergeResult.baseWorktreeSync) ? mergeResult.baseWorktreeSync : undefined;
+    if (baseWorktreeSync && baseWorktreeSync.reconciled === false && landedWorkspace) {
+      const ws = landedWorkspace;
+      const strandSync = {
+        reconciled: false as const,
+        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,
+      };
+      deferLandSettleSideEffect("base-worktree-strand", () => notifyBaseWorktreeStrand({ workspace: ws, sync: strandSync }));
+    }
+    // #1713 — reaching here means the land is either ancestry-CONFIRMED, a remote-verified PR land, or
+    // a proven zero-commit no-op (handled inside announceBranchLanded, #1620); an unconfirmed
+    // merged:true already returned early above as a retryable non-land, so this land signal is ref-backed.
+    // #1790 — the land STATE (status → merged, landed-sha stamp) and the durable RECEIPT are already
+    // written synchronously above; announceBranchLanded is the announcement fan-out (branch.landed +
+    // landed-success events, per-recipient author + on-main pushes, the issue/Task lifecycle drives),
+    // i.e. the serialized writes this issue is about — so it runs off the settle hot path.
+    if (landedNotice) {
+      const notice = landedNotice;
+      deferLandSettleSideEffect("branch-landed", () => announceBranchLanded(notice));
+    }
+    const gateSkipped = normalizeGateSkipped(mergeResult.gateSkipped);
+    if (gateSkipped && landedWorkspace) {
+      await patchWorkspaceMetadataAsync(landedWorkspace.id, {
+        landGateOverride: {
+          ...(isRecord(landedWorkspace.metadata.landGateOverride) ? landedWorkspace.metadata.landGateOverride : {}),
+          ...gateSkipped,
+          notifiedAt: Date.now(),
+        },
+      });
+      const ws = landedWorkspace;
+      deferLandSettleSideEffect("land-gate-skipped", () => notifyLandGateSkipped({ workspace: ws, ...gateSkipped }));
+    }
+    const gateWarnings = mergeResult.merged === true ? normalizeGateWarnings(mergeResult.gateWarnings) : [];
+    if (gateWarnings.length && landedWorkspace) {
+      const warnWorkspace = landedWorkspace;
+      void fireAndForget(`land-gate-warnings for ${warnWorkspace.id}`, async () => {
+        // #2474 R3 — a warning's wire output may be a folded tail while its full log lives in an
+        // orchestrator-banked artifact. Validate each link through the same provenance check the
+        // gateFailure path uses, render an explicit per-gate ref (or an honest truncation note
+        // when nothing was retained) into the combined artifact, and tell the notification whether
+        // the combined artifact is genuinely FULL output so it never overclaims.
+        const sections: string[] = [];
+        for (const g of gateWarnings) {
+          let ref = "";
+          if (g.outputArtifactId) {
+            const linked = await getArtifactAsync(g.outputArtifactId).catch(() => undefined);
+            if (linked && linkedGateOutputArtifactMatches(linked, warnWorkspace.id, g, typeof warnWorkspace.metadata.gateOrchestratorId === "string" ? warnWorkspace.metadata.gateOrchestratorId : warnWorkspace.orchestratorId, "land-gate-warning-output")) {
+              ref = ` — full log: artifact \`${linked.id}\``;
+            } else {
+              ref = " — full log unavailable";
+            }
+          } else if (g.outputTruncated === true) {
+            ref = " — output truncated, full log not retained";
+          }
+          sections.push(`### ${g.name} (${g.command}) - ${g.timedOut ? "timed out" : g.exitCode === null ? "could not run" : `exited ${g.exitCode}`}${ref}\n${g.output || g.outputTail || "(no output)"}`);
+        }
+        const combined = sections.join("\n\n");
+        // The combined artifact is genuinely FULL output only when nothing was folded; when any
+        // warning is truncated it is an index (tails + per-gate full-log refs), and the
+        // notification label must say so rather than claim "Full output".
+        const anyTruncated = gateWarnings.some((g) => g.outputTruncated === true);
+        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, fullOutput: !anyTruncated });
+        } catch (error) {
+          console.warn(`land-gate-warnings notify threw for ${warnWorkspace.id}: ${String(error)}`);
+        }
+      });
+    }
+    return { settled: true };
+  }
+  if (WORKSPACE_MERGE_FAILED_STATUSES.has(command.status) && command.correlationId) {
+    const current = getWorkspace(command.correlationId);
+    if (!current || !WORKSPACE_MERGE_ACTIVE_STATUSES.has(current.status)) return { settled: true };
+    if (!commandTargetsWorkspaceOwner(command, current)) return { settled: true, ignoredWrongOwner: true };
+    // Once a retry has claimed the row, a delayed terminal PATCH from the prior command must not
+    // overwrite the new attempt. Pre-correlation rows remain settleable for upgrade compatibility.
+    if (typeof current.metadata.mergeCommandId === "string" && current.metadata.mergeCommandId !== command.id) return { settled: true };
+    const failedResultStatus = isRecord(command.result)
+      ? optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined
+      : undefined;
+    const gateFailure = isRecord(command.result) ? normalizeGateRunResult(command.result.gateFailure) : undefined;
+    const nextStatus: WorkspaceStatus = gateFailure
+      ? "gate_failed"
+      : failedResultStatus && !WORKSPACE_MERGE_ACTIVE_STATUSES.has(failedResultStatus)
+      ? failedResultStatus
+      : "review_requested";
+    const reason = commandFailureReason(command, "merge failed");
+    const landedHead = stringValue(command.params?.expectedHeadSha) ?? stringValue(current.metadata.landRequestHeadSha);
+    // #1662 — the row may already hold its OWN detection that this branch landed (by a PR, a squash,
+    // or another path), written by `reconcileLandedWorkspace` while this merge was in flight. Then
+    // this failure is moot: there was nothing left for it to land. Treating it as a real failure is
+    // what produced four false landed-failure wakes to the owner and drove the no-progress counter
+    // to its cap, which woke a steward for an already-landed branch. Keep the audit trail, but no
+    // failure notice, no strike, and no stale `mergeError` on a row that has landed.
+    const alreadyLanded = workspaceShowsDetectedLand(current);
+    if (!alreadyLanded && mergeCommandKilledWithoutVerdict(command)) {
+      if (await settleRestartKilledLand(command, current)) markTransitionCompleted();
+      return { settled: true };
+    }
+    const transitioned = await updateWorkspaceStatusAsync(command.correlationId, nextStatus, {
+      mergeCommandId: command.id,
+      landGateQueue: undefined,
+      // #2772 — a failed command never carries a queue refusal; any keep-place time from an
+      // earlier incident is stale for the fresh queue entry the next dispatch takes.
+      mergeRetryEnqueuedAt: undefined,
+      ...(alreadyLanded
+        ? { mergeError: undefined, landedMergeFailureIgnoredAt: Date.now(), landedMergeFailureIgnoredReason: reason }
+        : { mergeError: reason, ...noteMergeNoProgress(current.metadata) }),
+      ...(nextStatus === "conflict" && isRecord(command.result) ? landConflictPathsPatch(command.result.conflictPaths, landedHead) : {}),
+    });
+    if (transitioned) markTransitionCompleted();
+    // #1790 — the status transition above is the synchronous land STATE; the failure wakes below are
+    // announcements off it, so they run off the settle hot path (same as the success path's fan-out).
+    if (nextStatus === "conflict" && !alreadyLanded) {
+      // #2704 — the settle is the one conflict entry that never woke a steward (case A): give it its resolver.
+      deferLandSettleSideEffect("land-conflict-resolver", () => superviseLandConflictLater(current.id, reason, landedHead ? { tip: landedHead } : {}));
+      deferLandSettleSideEffect("land-conflict-semantic", () => emitWorkspaceTaskSemanticNotifications({
+        workspace: current, transition: "land-conflict", actor: "workspace-merge",
+        idempotencyKey: landFailureEventKey(current, command.id),
+        outcome: { reason, commandId: command.id, status: nextStatus },
+      }));
+    }
+    if (gateFailure) {
+      const gateFailedAt = Date.now();
+      void fireAndForget(`land-gate-failed for ${current.id}`, async () => {
+        const artifactId = await uploadGateOutputArtifact(current.id, gateFailure, typeof current.metadata.gateOrchestratorId === "string" ? current.metadata.gateOrchestratorId : current.orchestratorId);
+        try {
+          await notifyLandGateFailed({ workspace: current, gate: gateFailure, artifactId, failedAt: gateFailedAt });
+        } catch (error) {
+          console.warn(`land-gate-failed notify threw for ${current.id}: ${String(error)}`);
+        }
+      });
+    } else if (!alreadyLanded && nextStatus !== "conflict") {
+      // A conflict's owner hears from its resolver instead: the steward hand-off, or the hand-back (#2704).
+      deferLandSettleSideEffect("land-failed", () => {
+        notifyBranchLandFailed({ workspace: current, commandId: command.id, reason });
+        notifyLandUnconfirmed({ workspace: current, commandId: command.id, targetRef: current.baseRef ?? "main", kind: "merge-failed", detail: reason });
+      });
+    }
+    return { settled: true };
+  }
+  return { settled: false };
+}
+
+export async function settleWorkspaceCommand(command: Command, opts: WorkspaceCommandSettleOptions = {}): Promise<WorkspaceCommandSettleResult> {
+  if (command.type === "workspace.rekey") return (await import("./workspace-rekey")).settleWorkspaceRekeyCommand(command);
+  if (command.type === "workspace.merge") return settleWorkspaceMergeCommand(command, opts);
+  if (command.type === "workspace.cleanup") return await settleWorkspaceCleanupCommand(command);
+  return { settled: false };
+}

package/src/workspace-config.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceConfig } from "@humwick/sdk";
+
+// Single source for the isolated-worktree symlink default (config-store + settings registry).
+// Only the untracked rig config is linked; AGENTS.md is tracked (#3516), so a worktree gets it from git.
+export const WORKSPACE_CONFIG_DEFAULTS: WorkspaceConfig = {
+  symlinkPaths: [".claude-rig"],
+};