agent-dealer 1.1.2 → 1.1.3

package/bundle/server/dist/coordinator/commands.js

@@ -1,3 +1,4 @@
+import { canTransitionIssue } from "@agent-dealer/shared";
 import { getDb } from "../db/index.js";
 import { getIssue, incrementIssueRound, incrementIssueInfraAttempts, resetIssueInfraAttempts, grantReviewRetry, transitionIssue, } from "../repository/issues.js";
 import { appendWorkflowEvent, completeWorkflowInstance, getActiveWorkflowInstance, getWorkflowInstance, listWorkflowEventsForIssue, startWorkflowInstance, WorkflowAlreadyActiveError, } from "../repository/workflow-events.js";
@@ -15,10 +16,11 @@ import { workerSessionPayload } from "./session-progress.js";
 import { reasonForWorkerFailedEvent } from "./failure-reason.js";
 import { routeDeveloperOutcome, routeReviewerOutcome, } from "./routing.js";
 import { projectDeveloperRoute, projectReviewerRoute } from "./projection.js";
-import { parseHumanResolution, resolveHumanActionOutcome } from "./human-resolution.js";
+import { MERGE_FAILURE_EVIDENCE_KEY, MERGE_FAILURE_RESPONSE_OPTIONS, parseHumanResolution, resolveHumanActionOutcome, } from "./human-resolution.js";
 import { AUTO_MERGE_INTENT, finalizeAutoMerge } from "./auto-merge.js";
+import { externalMergeStateForIssue } from "./external-merge.js";
 import { detectNonConvergence, formatNonConvergenceReason, reviewHistoryFromEvents, } from "./non-convergence.js";
-import { capEscalationEvents, deferLeasedWorkItemForDeckOutage, deferLeasedWorkItemForUsageCap, formatCapEscalationReason, usageCapDeferralStartedAt, } from "./usage-cap-defer.js";
+import { capEscalationEvents, deferLeasedWorkItemForBaseFetch, deferLeasedWorkItemForDeckOutage, deferLeasedWorkItemForUsageCap, formatCapEscalationReason, usageCapDeferralStartedAt, } from "./usage-cap-defer.js";
 import { markQueueEntryAdmitted } from "../repository/queue-entries.js";
 import { getWorkflow } from "./workflows/registry.js";
 import { DEV_REVIEWER_V1_VERSION } from "./workflows/dev-reviewer-v1.js";
@@ -284,6 +286,11 @@ export async function applyCompletion(workItemId, leaseToken, outcome) {
     if (outcome.kind === "deck_unavailable") {
         return applyDeckOutageCompletion(workItemId, leaseToken, outcome);
     }
+    // NOT-197: same shape as a deck outage — the start never happened (no branch, no
+    // spawn), so the work item waits for the network instead of spending an attempt.
+    if (outcome.kind === "base_fetch_failed") {
+        return applyBaseFetchDeferralCompletion(workItemId, leaseToken, outcome);
+    }
     const routed = getDb().transaction(() => {
         const before = getWorkItem(workItemId);
         if (!before)
@@ -368,6 +375,10 @@ function applyUsageCapCompletion(workItemId, leaseToken, cap) {
 function applyDeckOutageCompletion(workItemId, leaseToken, outage) {
     return applyDeferralCompletion(workItemId, leaseToken, outage, (item, issue, instance) => deferLeasedWorkItemForDeckOutage(item, leaseToken, outage, issue, instance));
 }
+/** NOT-197: no escalation arm — the item waits for the network for as long as it takes. */
+function applyBaseFetchDeferralCompletion(workItemId, leaseToken, failure) {
+    return applyDeferralCompletion(workItemId, leaseToken, failure, (item, issue, instance) => deferLeasedWorkItemForBaseFetch(item, leaseToken, failure, issue, instance));
+}
 /**
  * Deferral ceiling exceeded — escalate with cap evidence without spending infra attempts.
  * Used when applyCompletion or the worker loop cannot defer any longer.
@@ -728,13 +739,30 @@ function applyEffect(issue, instance, effect, route, issueNow, ev, causativeItem
     }
     return base;
 }
-function questionFor(actionType, reason, resumeAsReviewer = false) {
+/**
+ * NOT-194: true when the action is a merge-failure escalation (evidence carries
+ * `mergeFailure: true`). Pre-NOT-194 open merge-failure actions have no such evidence and
+ * read as ordinary policy_escalations — that is what keeps their `resume` path working.
+ */
+export function isMergeFailureAction(action) {
+    if (!action.evidenceJson)
+        return false;
+    try {
+        return JSON.parse(action.evidenceJson)[MERGE_FAILURE_EVIDENCE_KEY] === true;
+    }
+    catch {
+        return false;
+    }
+}
+function questionFor(actionType, reason, resumeAsReviewer = false, mergeFailure = false) {
     switch (actionType) {
         case "final_review":
             return "Merge this work, send it back for another repair round, or close it?";
         case "attempts_exhausted":
             return "The review-round limit is reached. Retry with a fresh round, or close the issue?";
         case "policy_escalation":
+            if (mergeFailure)
+                return `${reason} Retry the merge, queue another repair round, or close the issue?`;
             return resumeAsReviewer
                 ? `${reason} Retry the review, or close the issue?`
                 : `${reason} Resume development, or close the issue?`;
@@ -760,7 +788,7 @@ function questionFor(actionType, reason, resumeAsReviewer = false) {
 /** Exported for db/migrate-to-issues.ts, which must populate the same response options on
  * a migrated final_review/attempts_exhausted action — otherwise the UI parses a null
  * response_options_json as no options and renders nothing to resolve it with. */
-export function responseOptionsFor(actionType, resumeAsReviewer = false) {
+export function responseOptionsFor(actionType, resumeAsReviewer = false, opts = {}) {
     switch (actionType) {
         case "final_review":
             return [
@@ -774,6 +802,9 @@ export function responseOptionsFor(actionType, resumeAsReviewer = false) {
                 { choice: "close", label: "Close" },
             ];
         case "policy_escalation":
+            // NOT-194: a merge failure after approval offers retry/repair/close — never resume.
+            if (opts.mergeFailure)
+                return [...MERGE_FAILURE_RESPONSE_OPTIONS];
             return [
                 { choice: "resume", label: resumeAsReviewer ? "Retry review" : "Resume development" },
                 { choice: "close", label: "Close" },
@@ -809,8 +840,14 @@ function parseContinuationPreview(json) {
  * `final_review:complete` parks for undraft+merge (same finalize as auto-merge) and
  * returns `pendingMerge: true` — callers that need the merge to finish must use
  * `resolveHumanActionAndAdvanceAsync` (HTTP/CLI) rather than this sync entry point alone.
+ *
+ * NOT-196: a `close` choice finishes as `done` instead of `closed` when
+ * `opts.externalMergeState` is "merged" — the PR landed outside Dealer, so the work is
+ * landed and dependents must be released. Any other state (or no pre-read at all)
+ * keeps today's `closed`. The `gh` read itself lives in the async wrapper
+ * (`resolveHumanActionAndAdvanceAsync`), never inside this transaction.
  */
-export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
+export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts) {
     const action = getHumanAction(actionId);
     if (!action)
         return { ok: false, code: 404, error: "Human action not found" };
@@ -820,6 +857,21 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
     if (!resolution) {
         return { ok: false, code: 400, error: `Invalid choice "${choice}" for ${action.actionType}` };
     }
+    // NOT-194: narrow policy_escalation choices per action. A merge-failure action offers
+    // retry_merge/repair/close only (resume would re-run development on approved work);
+    // every other policy_escalation keeps resume/close only. Pre-NOT-194 open merge-failure
+    // actions carry no mergeFailure evidence, so they still accept resume here.
+    if (resolution.actionType === "policy_escalation") {
+        const mergeFailure = isMergeFailureAction(action);
+        const allowed = mergeFailure ? ["retry_merge", "repair", "close"] : ["resume", "close"];
+        if (!allowed.includes(resolution.choice)) {
+            return {
+                ok: false,
+                code: 400,
+                error: `Invalid choice "${choice}" for ${mergeFailure ? "a merge-failure" : "this"} policy_escalation`,
+            };
+        }
+    }
     // parseHumanResolution already rejects every Run-scoped action type (NOT-95) above, so
     // every action reaching here is Issue-scoped — this narrows action.issueId for TS.
     if (!action.issueId)
@@ -830,9 +882,12 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
     const instance = getActiveWorkflowInstance(action.issueId);
     // NOT-102 / NOT-150: human Merge (or legacy "complete") must undraft+merge.
     // Park like auto-merge, then the async wrapper runs finalizeAutoMerge outside this txn.
+    // NOT-194: a merge-failure retry_merge parks the same way — the old action is resolved
+    // first, so a second failure escalates exactly one fresh action with the new reason.
     if (instance &&
-        resolution.actionType === "final_review" &&
-        (resolution.choice === "merge" || resolution.choice === "complete")) {
+        ((resolution.actionType === "final_review" &&
+            (resolution.choice === "merge" || resolution.choice === "complete")) ||
+            (resolution.actionType === "policy_escalation" && resolution.choice === "retry_merge"))) {
         return getDb().transaction(() => {
             resolveHumanAction(actionId, resolvedBy, { choice });
             appendWorkflowEvent({
@@ -841,9 +896,9 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
                 type: "human_action.resolved",
                 actorType: "human",
                 actorRef: resolvedBy,
-                stage: "final_review",
+                stage: resolution.actionType === "final_review" ? "final_review" : issue.status,
                 round: issue.currentRound,
-                payload: { actionType: "final_review", choice: resolution.choice, pendingMerge: true },
+                payload: { actionType: action.actionType, choice: resolution.choice, pendingMerge: true },
             });
             transitionIssue(issue.id, "final_review", {
                 currentOwner: "system",
@@ -929,37 +984,90 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
         ? issue.currentRound + 1
         : issue.currentRound;
     const resumeStatus = resumeAsReviewer ? "reviewing" : outcome.issueStatus;
+    // NOT-196: a close on an issue whose PR is MERGED on GitHub lands as done — the
+    // code is on the base branch, so dependents must be released. Only a confirmed merge
+    // upgrades; open / closed-unmerged / unreadable ("unknown") / no pre-read all stay
+    // closed. The PR number gates the upgrade so a merged state can never apply to an
+    // issue that never had a PR, and the status-machine gate keeps it to statuses with
+    // a →done edge (close actions park at needs_human/final_review, both of which have
+    // one) so the upgrade can never throw inside the transaction.
+    const prMerged = outcome.workflowOutcome === "closed" && opts?.externalMergeState === "merged" && issue.prNumber != null;
+    const externallyMerged = prMerged && canTransitionIssue(issue.status, "done");
+    const closeHasPr = outcome.workflowOutcome === "closed" && issue.prNumber != null;
+    // Extra audit keys on the close resolution only — every other outcome keeps today's
+    // exact payload.
+    const closeResolutionExtra = !closeHasPr
+        ? {}
+        : externallyMerged
+            ? { prNumber: issue.prNumber, prState: "MERGED", externalMerge: true }
+            : opts?.externalMergeState === "unknown"
+                ? { prNumber: issue.prNumber, prMergeStateUnknown: true }
+                : prMerged
+                    ? {
+                        prNumber: issue.prNumber,
+                        prState: "MERGED",
+                        doneTransitionBlocked: `no ${issue.status} → done edge`,
+                    }
+                    : {};
     return getDb().transaction(() => {
         resolveHumanAction(actionId, resolvedBy, { choice });
-        // stage must be the status this resolution actually lands on (resumeStatus), not the
+        // stage must be the status this resolution actually lands on (finalStatus), not the
         // generic developer-resume outcome.issueStatus — otherwise a reviewer resume's own
         // human_action.resolved/repair.started events would be recorded under "developing"
         // even though the issue transitions to "reviewing".
-        const ev = eventEmitter(issue, instance, null, resumeStatus, issue.currentRound);
+        const finalStatus = externallyMerged ? "done" : resumeStatus;
+        const ev = eventEmitter(issue, instance, null, finalStatus, issue.currentRound);
         ev.emit("human_action.resolved", {
             actorType: "human",
-            payload: { actionType: action.actionType, choice },
+            payload: { actionType: action.actionType, choice, ...closeResolutionExtra },
         });
-        transitionIssue(issue.id, resumeStatus, {
-            currentOwner: resumeStatus === "done" || resumeStatus === "closed" ? "system" : resumeAsReviewer ? "reviewer" : "developer",
-            currentIntent: resumeStatus === "done"
-                ? "Complete"
-                : resumeStatus === "closed"
+        transitionIssue(issue.id, finalStatus, {
+            currentOwner: finalStatus === "done" || finalStatus === "closed" ? "system" : resumeAsReviewer ? "reviewer" : "developer",
+            currentIntent: finalStatus === "done"
+                ? externallyMerged
+                    ? "Merged outside Dealer"
+                    : "Complete"
+                : finalStatus === "closed"
                     ? "Closed"
                     : resumeAsReviewer
                         ? `Reviewer re-evaluating at ${continuation.resumeHeadSha.slice(0, 8)}`
                         : `Developer implementing round ${nextRound}`,
         });
         if (outcome.workflowOutcome) {
-            completeWorkflowInstance(instance.id, outcome.workflowOutcome);
-            ev.emit(outcome.workflowOutcome === "done" ? "issue.completed" : "issue.closed");
+            const finalOutcome = externallyMerged ? "done" : outcome.workflowOutcome;
+            completeWorkflowInstance(instance.id, finalOutcome);
+            if (externallyMerged) {
+                ev.emit("issue.completed", {
+                    payload: { externalMerge: true, prNumber: issue.prNumber, prState: "MERGED" },
+                });
+            }
+            else if (finalOutcome === "done") {
+                ev.emit("issue.completed");
+            }
+            else if (opts?.externalMergeState === "unknown" && issue.prNumber != null) {
+                ev.emit("issue.closed", {
+                    payload: { prNumber: issue.prNumber, prMergeStateUnknown: true },
+                });
+            }
+            else if (prMerged) {
+                ev.emit("issue.closed", {
+                    payload: {
+                        prNumber: issue.prNumber,
+                        prState: "MERGED",
+                        doneTransitionBlocked: `no ${issue.status} → done edge`,
+                    },
+                });
+            }
+            else {
+                ev.emit("issue.closed");
+            }
             return {
                 ok: true,
                 issueStatus: getIssue(issue.id).status,
                 nextWorkItemId: null,
                 instanceCompleted: true,
                 restarted: false,
-                triggerReflect: outcome.triggerReflect === true,
+                triggerReflect: outcome.triggerReflect === true || externallyMerged,
             };
         }
         // Another round: spend the budget this resolution's roundKind names, then queue the
@@ -1029,7 +1137,12 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
  * parks for merge, awaits undraft+merge (`finalizeAutoMerge`) before returning.
  */
 export async function resolveHumanActionAndAdvanceAsync(actionId, resolvedBy, choice) {
-    const result = resolveHumanActionAndAdvance(actionId, resolvedBy, choice);
+    // NOT-196: the `gh` PR-state read runs here, outside any DB transaction — the sync
+    // core below only consumes the pre-read state. Only close choices on issues with a
+    // PR number pay for the call; anything unreadable resolves to "unknown" (or
+    // undefined when there is nothing to check), both of which keep today's `closed`.
+    const externalMergeState = await preReadExternalMergeState(actionId, choice);
+    const result = resolveHumanActionAndAdvance(actionId, resolvedBy, choice, { externalMergeState });
     if (!result.ok || !result.pendingMerge)
         return result;
     const action = getHumanAction(actionId);
@@ -1135,7 +1248,7 @@ const defaultAbortDeps = { killProcess: killRunProcess };
  * own lease-token-fenced finishWorkItem CAS simply stops matching when it eventually calls
  * applyCompletion.
  */
-export function abortIssue(issueId, resolvedBy, deps = defaultAbortDeps) {
+export function abortIssue(issueId, resolvedBy, deps = defaultAbortDeps, opts) {
     if (!getIssue(issueId))
         return { ok: false, code: 404, error: "Issue not found" };
     const tx = getDb().transaction(() => {
@@ -1165,19 +1278,44 @@ export function abortIssue(issueId, resolvedBy, deps = defaultAbortDeps) {
                 });
             }
         }
-        transitionIssue(issueId, "closed", { currentOwner: "system", currentIntent: "Aborted by operator" });
+        // NOT-196: aborting an issue whose PR already merged outside Dealer lands it as
+        // done so dependents are released. Only a confirmed merge upgrades — an unreadable
+        // state ("unknown") or no PR keeps today's `closed`, with the unknown case noted
+        // in the event. The PR number gates the upgrade, as in the resolve path, and the
+        // status-machine gate keeps it to statuses with a →done edge (abort, unlike the
+        // resolve path, can fire from any status — e.g. developing — where no such edge
+        // exists; there the abort stays closed but the event still names the merged PR so
+        // the operator can see why, and a follow-up could add the edge).
+        const prMerged = opts?.externalMergeState === "merged" && issue.prNumber != null;
+        const externallyMerged = prMerged && canTransitionIssue(issue.status, "done");
+        const finalStatus = externallyMerged ? "done" : "closed";
+        transitionIssue(issueId, finalStatus, {
+            currentOwner: "system",
+            currentIntent: externallyMerged ? "Merged outside Dealer" : "Aborted by operator",
+        });
         if (instance)
-            completeWorkflowInstance(instance.id, "closed");
+            completeWorkflowInstance(instance.id, externallyMerged ? "done" : "closed");
         appendWorkflowEvent({
             issueId,
             workflowInstanceId: instance?.id ?? null,
-            type: "issue.closed",
+            type: externallyMerged ? "issue.completed" : "issue.closed",
             actorType: "human",
             actorRef: resolvedBy,
-            stage: "closed",
-            payload: { reason: "aborted_by_user" },
+            stage: finalStatus,
+            payload: externallyMerged
+                ? { reason: "aborted_by_user", externalMerge: true, prNumber: issue.prNumber, prState: "MERGED" }
+                : prMerged
+                    ? {
+                        reason: "aborted_by_user",
+                        prNumber: issue.prNumber,
+                        prState: "MERGED",
+                        doneTransitionBlocked: `no ${issue.status} → done edge`,
+                    }
+                    : opts?.externalMergeState === "unknown" && issue.prNumber != null
+                        ? { reason: "aborted_by_user", prNumber: issue.prNumber, prMergeStateUnknown: true }
+                        : { reason: "aborted_by_user" },
         });
-        return { alreadyClosed: false, issueStatus: "closed", runningSessionIds: running };
+        return { alreadyClosed: false, issueStatus: finalStatus, runningSessionIds: running };
     })();
     // Outside the transaction, per the ticket contract: terminating a child process is not
     // a DB write, and must happen only once the abort itself is durably committed.
@@ -1185,3 +1323,44 @@ export function abortIssue(issueId, resolvedBy, deps = defaultAbortDeps) {
         deps.killProcess(sessionId);
     return { ok: true, issueStatus: tx.issueStatus, alreadyClosed: tx.alreadyClosed };
 }
+/**
+ * NOT-196 HTTP/CLI entry for abort: same as `abortIssue`, but pre-reads the PR merge
+ * state outside the transaction first so an externally-merged PR lands the issue as
+ * `done`. Issues without a PR number skip the `gh` call entirely.
+ */
+export async function abortIssueAsync(issueId, resolvedBy, deps = defaultAbortDeps) {
+    let externalMergeState;
+    try {
+        const issue = getIssue(issueId);
+        if (issue && issue.prNumber != null) {
+            externalMergeState = await externalMergeStateForIssue(issue);
+        }
+    }
+    catch {
+        externalMergeState = undefined;
+    }
+    return abortIssue(issueId, resolvedBy, deps, { externalMergeState });
+}
+/**
+ * NOT-196 pre-read for the async close entry: returns a PR merge state only when this
+ * resolution is a `close` choice on an issue that actually has a PR number — otherwise
+ * undefined, which keeps the sync core on today's behavior with no `gh` call. Never
+ * throws: lookup failures mean "nothing to check".
+ */
+async function preReadExternalMergeState(actionId, choice) {
+    try {
+        const action = getHumanAction(actionId);
+        if (!action || action.status !== "open" || !action.issueId)
+            return undefined;
+        const resolution = parseHumanResolution(action.actionType, choice);
+        if (!resolution || resolution.choice !== "close")
+            return undefined;
+        const issue = getIssue(action.issueId);
+        if (!issue || issue.prNumber == null)
+            return undefined;
+        return await externalMergeStateForIssue(issue);
+    }
+    catch {
+        return undefined;
+    }
+}

package/bundle/server/dist/coordinator/developer-effect.js

@@ -21,7 +21,8 @@ import { getTaskSnapshot } from "./commands.js";
 import { buildDeveloperPrompt } from "./prompts.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realDeveloperSpawn, developerSessionLogPath } from "./spawn.js";
-import { resolveDeveloperWorktree, safeRemoveWorktree, isWorktreeClean, commitsAhead, pushBranch, mergeBase, branchExists, pushBranchRef, revParseHead, revParseRef, fetchRef, salvageDirtyWorktree, dirtyWorktreeRecoveryCommands, withRepoLock, } from "../adapters/git-worktree.js";
+import { DEFAULT_BASE_FETCH_TIMEOUT_MS, resolveDeveloperWorktree, safeRemoveWorktree, isWorktreeClean, commitsAhead, pushBranch, mergeBase, branchExists, pushBranchRef, revParseHead, revParseRef, fetchRef, salvageDirtyWorktree, dirtyWorktreeRecoveryCommands, withRepoLock, } from "../adapters/git-worktree.js";
+import { recordIssueBaseSha } from "../repository/issues.js";
 import { ensureIssueRepoCheckout, roleWorktreePathForResolution, resolveCheckoutBaseBranch, } from "../adapters/managed-repo.js";
 import { baseRefCandidates, inspectBranchProgress } from "./branch-progress.js";
 import { prepareWorkerDeckConnection, releaseWorkerDeckConnection } from "../adapters/agent-deck-bind.js";
@@ -93,6 +94,10 @@ export const developerEffectConfig = {
     get checksPollIntervalMs() {
         return num("CHECKS_POLL_INTERVAL_MS", 15_000);
     },
+    /** NOT-197: bound for the pre-branch `git fetch origin <base>` on a fresh issue branch. */
+    get baseFetchTimeoutMs() {
+        return num("BASE_FETCH_TIMEOUT_MS", DEFAULT_BASE_FETCH_TIMEOUT_MS);
+    },
     /** NOT-110: bounded window to let a lagging `gh pr view` catch up to a just-pushed HEAD. */
     get headReconcileTimeoutMs() {
         return num("HEAD_RECONCILE_TIMEOUT_MS", 30_000);
@@ -528,7 +533,14 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             reuseBranch,
             worktreePath: desiredWorktreePath,
             ownerLiveness: checkDeveloperWorktreeOwnerLiveness,
+            fetchTimeoutMs: developerEffectConfig.baseFetchTimeoutMs,
         });
+        if (resolved.kind === "base_unavailable") {
+            // NOT-197: the pre-branch fetch failed or timed out — defer the start (no branch
+            // was created, nothing spawned, no attempt spent) instead of falling back to the
+            // stale local base.
+            return { kind: "base_fetch_failed", reason: resolved.reason };
+        }
         if (resolved.kind === "conflict") {
             return { kind: "worktree_conflict", path: resolved.path, reason: resolved.reason, recoveryCommands: resolved.recoveryCommands };
         }
@@ -541,6 +553,13 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             };
         }
         worktreePath = resolved.path;
+        if (resolved.kind === "created" && resolved.baseSha) {
+            // NOT-197: record the true branch point while it is known — the verified handoff
+            // re-checks it via merge-base, but crash/timeout progress inspection below already
+            // reads issue.baseSha.
+            recordIssueBaseSha(issue.id, resolved.baseSha);
+            issue.baseSha = resolved.baseSha;
+        }
     }
     catch (err) {
         return { kind: "adapter_failure", reason: `worktree setup failed: ${String(err)}` };

package/bundle/server/dist/coordinator/developer-effect.test.js

@@ -27,7 +27,7 @@ const { listWorkItemsForIssue, claimWorkItem, bindWorkItemSession, cancelWorkIte
 const { listArtifactsForIssue } = await import("../repository/artifacts-for-issue.js");
 const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
 const { listUsageEventsForIssue } = await import("../repository/usage-events.js");
-const { getActiveWorkflowInstance } = await import("../repository/workflow-events.js");
+const { getActiveWorkflowInstance, listWorkflowEventsForIssue } = await import("../repository/workflow-events.js");
 const { startWorkflow, resolveHumanActionAndAdvance } = await import("./commands.js");
 const { registerEffectHandler, resetEffectHandlers } = await import("./effect-registry.js");
 const { runCoordinatorTick, drainCoordinator } = await import("./worker-loop.js");
@@ -808,6 +808,153 @@ test("baseSha is resolved against the fetched base ref, not a stale local branch
         fs.rmSync(isoRemote, { recursive: true, force: true });
     }
 });
+test("NOT-197: with a lagging local main, a new developer branch starts at the origin/main tip", async () => {
+    // The NOT-197 incident: the cached clone's local main lagged origin/main, so branches
+    // cut from it conflicted with already-merged work. Unlike the test above, the fake
+    // agent does NOT merge origin/main itself — the branch must already start there.
+    const isoRepo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-197-repo-"));
+    const isoRemote = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-197-remote-"));
+    try {
+        git(isoRepo, "init", "-q", "-b", "main");
+        git(isoRepo, "config", "user.email", "test@example.com");
+        git(isoRepo, "config", "user.name", "Test");
+        fs.writeFileSync(path.join(isoRepo, "README.md"), "hello\n");
+        git(isoRepo, "add", ".");
+        git(isoRepo, "commit", "-q", "-m", "init");
+        execFileSync("git", ["init", "-q", "--bare", "-b", "main", isoRemote]);
+        git(isoRepo, "remote", "add", "origin", isoRemote);
+        git(isoRepo, "push", "-q", "origin", "main");
+        const staleLocalMain = git(isoRepo, "rev-parse", "main");
+        const other = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-197-other-"));
+        execFileSync("git", ["clone", "-q", isoRemote, other]);
+        git(other, "config", "user.email", "test@example.com");
+        git(other, "config", "user.name", "Test");
+        fs.writeFileSync(path.join(other, "upstream-change.txt"), "z");
+        git(other, "add", ".");
+        git(other, "commit", "-q", "-m", "upstream change");
+        git(other, "push", "-q", "origin", "main");
+        const originTip = git(other, "rev-parse", "HEAD");
+        fs.rmSync(other, { recursive: true, force: true });
+        assert.notEqual(staleLocalMain, originTip, "the local main must lag origin/main for this test to mean anything");
+        const dev = createAgent({ name: `dev-197-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const rev = createAgent({ name: `rev-197-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const issueId = createIssue({
+            title: "Fresh base",
+            acceptanceCriteria: "works",
+            repo: isoRepo,
+            baseBranch: "main",
+            developerAgentId: dev.id,
+            reviewerAgentId: rev.id,
+            maxReviewRounds: 3,
+            maxInfraAttempts: 3,
+            source: "manual"
+        }).id;
+        const isoPrs = new Map();
+        const isoGithub = {
+            async viewPr({ branch }) {
+                if (!branch)
+                    throw new Error("isoGithub.viewPr requires an explicit branch — bare current-branch lookup is the NOT-82 bug");
+                const pr = isoPrs.get(branch);
+                if (!pr)
+                    return null;
+                return { number: pr.number, url: pr.url, baseRefName: pr.base, headRefName: branch, headRefOid: git(isoRemote, "rev-parse", branch), isDraft: true };
+            },
+            async createDraftPr({ base, head }) {
+                if (!head)
+                    throw new Error("isoGithub.createDraftPr requires an explicit --head — bare create is the NOT-82 bug");
+                isoPrs.set(head, { number: 1, url: "https://github.com/o/r/pull/1", base });
+                return { ok: true, number: 1, url: "https://github.com/o/r/pull/1" };
+            },
+            async checksSnapshot() {
+                return "success";
+            },
+            async publishReview() {
+                throw new Error("publishReview is unused by the developer effect");
+            }
+        };
+        registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github: isoGithub }));
+        startWorkflow(issueId);
+        await pump(1);
+        const issue = getIssue(issueId);
+        assert.equal(issue.status, "reviewing");
+        const branch = `issue-${issueId}`;
+        assert.equal(issue.branch, branch);
+        assert.equal(git(isoRepo, "rev-parse", `${branch}^`), originTip, "the new branch must be cut from the origin/main tip, not the stale local main");
+        assert.equal(issue.baseSha, originTip, "base_sha must equal the fetched origin/main tip");
+        assert.equal(git(isoRepo, "rev-parse", "main"), staleLocalMain, "sanity: the local main is still stale — the fix fetches, it does not move local branches");
+    }
+    finally {
+        fs.rmSync(isoRepo, { recursive: true, force: true });
+        fs.rmSync(isoRemote, { recursive: true, force: true });
+    }
+});
+test("NOT-197: a failed pre-branch fetch defers the start without a branch, a spawn, or an attempt", async () => {
+    // origin points at nothing fetchable: the effect must defer (worker.deferred, item
+    // pending, budgets untouched) instead of cutting the branch from the stale local base.
+    const isoRepo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-197fail-repo-"));
+    const isoRemote = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-197fail-remote-"));
+    try {
+        git(isoRepo, "init", "-q", "-b", "main");
+        git(isoRepo, "config", "user.email", "test@example.com");
+        git(isoRepo, "config", "user.name", "Test");
+        fs.writeFileSync(path.join(isoRepo, "README.md"), "hello\n");
+        git(isoRepo, "add", ".");
+        git(isoRepo, "commit", "-q", "-m", "init");
+        execFileSync("git", ["init", "-q", "--bare", "-b", "main", isoRemote]);
+        git(isoRepo, "remote", "add", "origin", isoRemote);
+        git(isoRepo, "push", "-q", "origin", "main");
+        git(isoRepo, "remote", "set-url", "origin", path.join(isoRemote, "does-not-exist.git"));
+        const dev = createAgent({ name: `dev-197f-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const rev = createAgent({ name: `rev-197f-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const issueId = createIssue({
+            title: "Fetch fails",
+            acceptanceCriteria: "works",
+            repo: isoRepo,
+            baseBranch: "main",
+            developerAgentId: dev.id,
+            reviewerAgentId: rev.id,
+            maxReviewRounds: 3,
+            maxInfraAttempts: 3,
+            source: "manual"
+        }).id;
+        let spawnCalled = false;
+        const spySpawn = async () => {
+            spawnCalled = true;
+            return { exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false };
+        };
+        registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: spySpawn, github: fakeGithub() }));
+        startWorkflow(issueId);
+        await pump(1);
+        assert.equal(spawnCalled, false, "nothing may spawn when the base could not be fetched");
+        assert.equal(await branchExists(isoRepo, `issue-${issueId}`), false, "no branch may be created from a base that was never confirmed");
+        const issue = getIssue(issueId);
+        assert.equal(issue.branch, null);
+        assert.equal(issue.baseSha, null);
+        assert.equal(issue.infraAttempts, 0, "a deferred start spends no infra attempt");
+        assert.equal(issue.currentRound, 1);
+        assert.notEqual(issue.status, "needs_human");
+        assert.match(issue.currentIntent ?? "", /Waiting for network/);
+        const { listWorkItemsForIssue } = await import("../repository/work-items.js");
+        const items = listWorkItemsForIssue(issueId);
+        assert.equal(items.length, 1);
+        assert.equal(items[0].status, "pending", "the item waits, it is not finished or dead-lettered");
+        assert.equal(items[0].attemptCount, 0, "the claim-time attempt bump is reverted");
+        assert.ok(Date.parse(items[0].availableAt) > Date.parse(items[0].updatedAt), "the next start is gated behind a wait");
+        assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0);
+        const events = listWorkflowEventsForIssue(issueId);
+        const deferrals = events.filter((e) => e.type === "worker.deferred");
+        assert.ok(deferrals.length > 0);
+        const payload = JSON.parse(deferrals[0].payloadJson ?? "{}");
+        assert.equal(payload.outcome, "base_fetch_failed");
+        assert.equal(events.some((e) => e.type === "worker.failed"), false, "a deferred start is not a failure");
+        const { listWorkerSessionsForIssue } = await import("../repository/worker-sessions.js");
+        assert.equal(listWorkerSessionsForIssue(issueId).every((s) => s.status === "cancelled"), true);
+    }
+    finally {
+        fs.rmSync(isoRepo, { recursive: true, force: true });
+        fs.rmSync(isoRemote, { recursive: true, force: true });
+    }
+});
 test("NOT-83 review: an item cancelled during worktree/deck-bind setup (before spawn) is never spawned", async () => {
     const { buildProfileSnapshot, serializeProfileSnapshot } = await import("./profile-snapshot.js");
     const issueId = await makeIssue();