agent-dealer 1.2.8 → 1.2.9

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

@@ -18,15 +18,18 @@ import os from "node:os";
 import path from "node:path";
 import { parsePhaseBudget, parseProfileSnapshot, roleCeiling } from "@agent-dealer/shared";
 import { getTaskSnapshot } from "./commands.js";
+import { extractOperatorCriteria } from "./operator-criteria.js";
 import { buildDeveloperPrompt } from "./prompts.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realDeveloperSpawn, developerSessionLogPath } from "./spawn.js";
+import { ensureWorktreeDeps, worktreeDepsTimeoutMs, } from "../adapters/worktree-deps.js";
 import { DEFAULT_BASE_FETCH_TIMEOUT_MS, fastForwardLocalBranchToSha, resolveDeveloperWorktree, safeRemoveWorktree, isWorktreeClean, commitsAhead, pushBranch, mergeBase, branchExists, pushBranchRef, revParseHead, revParseRef, fetchRef, salvageDirtyWorktree, dirtyWorktreeRecoveryCommands, withRepoLock, leftoverFingerprint, } 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, verifyWorkerDeckConnection } from "../adapters/agent-deck-bind.js";
-import { realGithubAdapter, pollPrChecks } from "../adapters/github.js";
+import { realGithubAdapter, pollPrChecksDetailed } from "../adapters/github.js";
+import { checksWaitCeilingExceeded, checksWaitCeilingMs } from "./checks-wait-config.js";
 import { museCapabilitySafetyNetAfterSession } from "../adapters/muse-capability.js";
 import { getOrAssignSessionCorrelationId, getWorkerSession, mergeSessionMetadata, patchRunningSession, recordSessionProcess, setSessionInputSha } from "../repository/worker-sessions.js";
 import { museIdleMinutes, museStallMetadata } from "./muse-spawn.js";
@@ -117,10 +120,18 @@ export const developerEffectConfig = {
     get checksPollIntervalMs() {
         return num("CHECKS_POLL_INTERVAL_MS", 15_000);
     },
+    /** NOT-311: overall CI-wait ceiling measured from the first poll, across deferrals. */
+    get checksWaitCeilingMs() {
+        return checksWaitCeilingMs();
+    },
     /** 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-315: bound for `npm ci` in the fresh worktree (coordinator side, with network). */
+    get worktreeDepsTimeoutMs() {
+        return worktreeDepsTimeoutMs();
+    },
     /** 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);
@@ -290,6 +301,69 @@ async function checksFailedOutcome(opts) {
     });
     return details ? { kind: "checks_failed", details } : { kind: "checks_failed" };
 }
+/**
+ * NOT-311: the `checksWaitStartedAt` persisted by a prior `checks_pending` deferral,
+ * anchoring the overall wait ceiling across re-polls. Null on a first wait (or an
+ * unparseable payload) — the caller then anchors at its own poll start.
+ */
+function checksWaitStartedAtFromPayload(payloadJson) {
+    if (!payloadJson)
+        return null;
+    try {
+        const v = JSON.parse(payloadJson).checksWaitStartedAt;
+        return typeof v === "string" && v ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * NOT-311: decide what a finished checks poll means. Returns a `checks_pending`
+ * outcome when CI is still queued/running at the timeout (or reports no checks while
+ * the base branch has a `pull_request` workflow — "not yet registered", never "no
+ * CI"), and null when the caller stays on today's path (success, failure, an aborted
+ * wait, or `none` with no workflow configured). Also yields the `checks.completed`
+ * milestone reason for the wait cases.
+ *
+ * A missing/unknown workflow answer (no adapter method, unreadable base ref) waits
+ * fail-closed: sending an unverified PR to review is the outcome this exists to
+ * prevent, and the wait ceiling still bounds it.
+ */
+async function resolveChecksWait(opts) {
+    const waitStartedAt = checksWaitStartedAtFromPayload(opts.payloadJson) ?? opts.pollStartedAt;
+    const base = {
+        kind: "checks_pending",
+        branch: opts.branch,
+        prNumber: opts.prNumber,
+        headSha: opts.headSha,
+        waitStartedAt,
+    };
+    const noChecks = opts.poll.result === "none" || (opts.poll.result === "timeout" && opts.poll.lastSnapshot === "none");
+    if (noChecks) {
+        let hasWorkflow = null;
+        try {
+            hasWorkflow = (await opts.github.hasPullRequestWorkflow?.({ cwd: opts.cwd, baseRef: opts.baseRef })) ?? null;
+        }
+        catch {
+            hasWorkflow = null;
+        }
+        if (hasWorkflow === false) {
+            return { pending: null, milestoneReason: "none_no_workflow" };
+        }
+        return {
+            pending: { ...base, reason: "Waiting for CI (queued) - no attempt spent" },
+            milestoneReason: "none_with_workflow",
+        };
+    }
+    if (opts.poll.result === "timeout" && opts.poll.lastSnapshot === "pending" && !opts.poll.aborted && !opts.signal?.aborted) {
+        const milestoneReason = checksWaitCeilingExceeded(waitStartedAt) ? "pending_ceiling" : undefined;
+        return {
+            pending: { ...base, reason: "Waiting for CI (running) - no attempt spent" },
+            ...(milestoneReason ? { milestoneReason } : {}),
+        };
+    }
+    return { pending: null };
+}
 /**
  * Infra retry that skips the agent: publish whatever the branch already carries. Uses the
  * issue repo as `gh` cwd and `origin/<branch>` as the verified head (any worktree was
@@ -528,17 +602,35 @@ async function runPublishOnlyHandoff(ctx, deps, branchName) {
             prNumber: prView.number,
             headSha: prView.headRefOid,
         });
-        const checks = await pollPrChecks(deps.github, {
+        const pollStartedAt = new Date().toISOString();
+        const poll = await pollPrChecksDetailed(deps.github, {
             cwd,
             timeoutMs: developerEffectConfig.checksPollTimeoutMs,
             intervalMs: developerEffectConfig.checksPollIntervalMs,
             signal: ctx.signal,
             number: prView.number,
         });
+        // NOT-311: pending/queued CI at the timeout (or no checks yet with a
+        // `pull_request` workflow on the base) waits with backoff instead of spending
+        // an infra attempt — resolved here so the milestone carries the wait reason.
+        const wait = await resolveChecksWait({
+            github: deps.github,
+            cwd,
+            prNumber: prView.number,
+            baseRef: prView.baseRefName,
+            headSha: prView.headRefOid,
+            branch: branchName,
+            poll,
+            signal: ctx.signal,
+            payloadJson: workItem.payloadJson,
+            pollStartedAt,
+        });
+        const checks = poll.result;
         milestone("checks.completed", `Developer · checks ${checks}`, {
             snapshot: checks,
             prNumber: prView.number,
             headSha: prView.headRefOid,
+            ...(wait.milestoneReason ? { reason: wait.milestoneReason } : {}),
         });
         const postPollView = await deps.github.viewPr({ cwd, branch: branchName });
         if (!postPollView) {
@@ -575,6 +667,10 @@ async function runPublishOnlyHandoff(ctx, deps, branchName) {
             author: "system",
             content: { snapshot: checks, prNumber: prView.number, headSha: prView.headRefOid },
         });
+        // NOT-311: still-waiting CI defers with backoff (no attempt spent) instead of
+        // timing out the session. An aborted wait keeps today's `timed_out`.
+        if (wait.pending)
+            return wait.pending;
         if (checks === "timeout")
             return { kind: "timed_out" };
         await fetchRef(cwd, prView.baseRefName);
@@ -773,6 +869,18 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             recordIssueBaseSha(issue.id, resolved.baseSha);
             issue.baseSha = resolved.baseSha;
         }
+        // NOT-315: provision dependencies here, outside the sandbox, with network — the
+        // builder sandbox has none, so an in-session install can never work. A throw
+        // lands in the worktree-setup adapter_failure below: visible and
+        // infra-retryable, never a silent hour-long stall. The session is not spawned.
+        const depsResult = await ensureWorktreeDeps(worktreePath, {
+            runner: deps.depsRunner,
+            timeoutMs: developerEffectConfig.worktreeDepsTimeoutMs,
+        });
+        milestone("worktree.deps_ready", `Developer · dependencies ready (round ${round})`, {
+            ...(depsResult.ran ? { ran: true } : { ran: false, reason: depsResult.reason }),
+            durationMs: depsResult.durationMs,
+        });
     }
     catch (err) {
         return { kind: "adapter_failure", reason: `worktree setup failed: ${String(err)}` };
@@ -886,6 +994,14 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
         const scopeDecisionNote = typeof payload.scopeDecisionNote === "string" && payload.scopeDecisionNote.trim()
             ? payload.scopeDecisionNote.trim()
             : undefined;
+        // NOT-314: same one-shot ride for an operator_verification repair note.
+        const operatorRepairNote = typeof payload.operatorRepairNote === "string" && payload.operatorRepairNote.trim()
+            ? payload.operatorRepairNote.trim()
+            : undefined;
+        // NOT-314: the frozen snapshot's operator criteria, parsed here so the
+        // worker never re-derives them — the section renders only when non-empty.
+        const operatorCriteria = extractOperatorCriteria(taskSnapshot.acceptanceCriteria);
+        const hasOperatorCriteria = operatorCriteria.length > 0 ? operatorCriteria : undefined;
         // NOT-310: the conflict directive rides only the work item queued by the merge
         // path — exactly this round reads it; nothing is re-read from the DB. Shaped
         // defensively: a malformed directive renders nothing rather than breaking the
@@ -938,6 +1054,8 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             guidance: guidance.length ? guidance : undefined,
             scopeDecisionNote,
             conflictRepair,
+            operatorCriteria: hasOperatorCriteria,
+            operatorRepairNote,
         });
         // NOT-83 review finding: the session is marked `running` (worker-loop.ts) before this
         // handler ever runs, so an abort landing during worktree setup/deck-bind above already
@@ -1614,7 +1732,8 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             prNumber: prView.number,
             headSha: prView.headRefOid,
         });
-        const checks = await pollPrChecks(deps.github, {
+        const pollStartedAt = new Date().toISOString();
+        const poll = await pollPrChecksDetailed(deps.github, {
             cwd: worktreePath,
             timeoutMs: developerEffectConfig.checksPollTimeoutMs,
             intervalMs: developerEffectConfig.checksPollIntervalMs,
@@ -1624,10 +1743,27 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             // back to a bare `gh pr view` either).
             number: prView.number,
         });
+        // NOT-311: pending/queued CI at the timeout (or no checks yet with a
+        // `pull_request` workflow on the base) waits with backoff instead of spending
+        // an infra attempt — resolved here so the milestone carries the wait reason.
+        const wait = await resolveChecksWait({
+            github: deps.github,
+            cwd: worktreePath,
+            prNumber: prView.number,
+            baseRef: prView.baseRefName,
+            headSha: prView.headRefOid,
+            branch: branchName,
+            poll,
+            signal: ctx.signal,
+            payloadJson: workItem.payloadJson,
+            pollStartedAt,
+        });
+        const checks = poll.result;
         milestone("checks.completed", `Developer · checks ${checks}`, {
             snapshot: checks,
             prNumber: prView.number,
             headSha: prView.headRefOid,
+            ...(wait.milestoneReason ? { reason: wait.milestoneReason } : {}),
         });
         // The poll can run for up to checksPollTimeoutMs (default 10 minutes) — re-fetch and
         // re-validate identity against the SAME localHead before trusting either the checks
@@ -1675,6 +1811,12 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             author: "system",
             content: { snapshot: checks, prNumber: prView.number, headSha: prView.headRefOid },
         });
+        // NOT-311: still-waiting CI defers with backoff (no attempt spent) instead of
+        // timing out the session. An aborted wait keeps today's `timed_out`.
+        if (wait.pending) {
+            await bestEffortRemove(repoPath, worktreePath);
+            return wait.pending;
+        }
         if (checks === "timeout") {
             await bestEffortRemove(repoPath, worktreePath);
             return { kind: "timed_out" };

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

@@ -151,7 +151,12 @@ function fakeGithub(opts = {}) {
             if (number == null && !branch) {
                 throw new Error("fakeGithub.checksSnapshot requires an explicit number or branch — bare checks lookup is the NOT-82 bug");
             }
-            return opts.checks ?? "success";
+            // NOT-311: a function lets one test flip CI mid-wait (pending → success) so the
+            // deferred re-poll can prove the wait closes without a fresh agent session.
+            return typeof opts.checks === "function" ? opts.checks() : (opts.checks ?? "success");
+        },
+        async hasPullRequestWorkflow() {
+            return opts.pullRequestWorkflow ?? null;
         },
         async publishReview() {
             throw new Error("publishReview is unused by the developer effect");
@@ -530,6 +535,8 @@ test("checks_failed: CI failure after a clean push/PR retries without a human ac
     await pump(1);
     const issue = getIssue(issueId);
     assert.equal(issue.status, "developing");
+    assert.equal(issue.ciAttempts, 1, "a checks_failed retry spends the CI budget");
+    assert.equal(issue.infraAttempts, 0, "a checks_failed retry never touches the infra budget");
     assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer").length, 0);
     const kinds = listArtifactsForIssue(issueId).map((a) => a.kind);
     const evidence = listArtifactsForIssue(issueId).find((a) => a.kind === "checks_evidence");
@@ -540,12 +547,159 @@ test("checks_failed: CI failure after a clean push/PR retries without a human ac
     assert.ok(kinds.includes("implementation_conclusion"), "conclusion must survive a post-session verification failure");
     assert.ok(kinds.includes("developer_transcript"), "raw trace must survive a post-session verification failure");
 });
-test("timed_out (checks poll): checks stay pending past the poll deadline", async () => {
+test("NOT-311: checks_pending — checks still pending at the poll deadline defers, spending no attempt", async () => {
+    // Previously this returned `timed_out`, spending an infra attempt on a session that
+    // had already ended cleanly. Now the item waits on backoff and re-polls.
     const issueId = await makeIssue();
     registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github: fakeGithub({ checks: "pending" }) }));
     startWorkflow(issueId);
     await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "developing");
+    assert.equal(issue.infraAttempts, 0, "a CI wait spends no infra attempt");
+    assert.equal(issue.currentRound, 1, "a CI wait must not spend a review round");
+    assert.match(issue.currentIntent ?? "", /Waiting for CI \(running\) - no attempt spent/);
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer").length, 0, "no review handoff on unverified CI");
+    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 re-poll is gated behind a backoff");
+    const deferredPayload = JSON.parse(items[0].payloadJson ?? "{}");
+    assert.equal(deferredPayload.publishOnly, true, "the re-poll takes the no-agent publish path, not a fresh spawn");
+    assert.equal(deferredPayload.branch, issueBranchName(issueId));
+    assert.ok(deferredPayload.checksWaitStartedAt, "the wait anchors its ceiling at the first poll");
+    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);
+    assert.equal(JSON.parse(deferrals[0].payloadJson ?? "{}").outcome, "checks_pending");
+    assert.equal(events.some((e) => e.type === "worker.failed"), false, "a CI wait is not a failure");
+    const completed = events.find((e) => e.type === "checks.completed");
+    assert.ok(completed, "the wait still records a checks.completed milestone");
+    assert.equal(JSON.parse(completed.payloadJson ?? "{}").snapshot, "timeout");
+});
+test("NOT-311: the deferred CI wait re-polls through publish-only and hands off once CI passes", async () => {
+    // First run waits (pending), the deferred re-poll sees success and reaches review —
+    // all without spawning a second agent session and without spending infra attempts.
+    let ci = "pending";
+    let spawns = 0;
+    const countingSpawn = async (input) => {
+        spawns++;
+        return commitingSpawn(input);
+    };
+    // A short backoff (set before the first deferral computes its `until`) lets the
+    // second pump actually pick the waiting item back up.
+    const prevBase = process.env.DECK_OUTAGE_BACKOFF_BASE_MS;
+    const prevMax = process.env.DECK_OUTAGE_BACKOFF_MAX_MS;
+    process.env.DECK_OUTAGE_BACKOFF_BASE_MS = "10";
+    process.env.DECK_OUTAGE_BACKOFF_MAX_MS = "10";
+    try {
+        const issueId = await makeIssue();
+        registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: countingSpawn, github: fakeGithub({ checks: () => ci }) }));
+        startWorkflow(issueId);
+        await pump(1);
+        assert.equal(getIssue(issueId).status, "developing");
+        assert.equal(getIssue(issueId).infraAttempts, 0);
+        const deferred = listWorkItemsForIssue(issueId)[0];
+        assert.equal(deferred.status, "pending");
+        // Fast-forward past the deferral backoff, then let CI pass.
+        await new Promise((resolve) => setTimeout(resolve, 60));
+        ci = "success";
+        await pump(1);
+        const issue = getIssue(issueId);
+        assert.equal(issue.status, "reviewing", "the re-poll hands off once CI passes");
+        assert.equal(issue.infraAttempts, 0, "waiting plus a passing re-poll still spends nothing");
+        assert.equal(spawns, 1, "the re-poll must not spawn a second agent session");
+        assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer" && i.status === "pending").length, 1);
+    }
+    finally {
+        if (prevBase === undefined)
+            delete process.env.DECK_OUTAGE_BACKOFF_BASE_MS;
+        else
+            process.env.DECK_OUTAGE_BACKOFF_BASE_MS = prevBase;
+        if (prevMax === undefined)
+            delete process.env.DECK_OUTAGE_BACKOFF_MAX_MS;
+        else
+            process.env.DECK_OUTAGE_BACKOFF_MAX_MS = prevMax;
+    }
+});
+test("NOT-311: none with a pull_request workflow on the base waits (no review handoff)", async () => {
+    const issueId = await makeIssue();
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github: fakeGithub({ checks: "none", pullRequestWorkflow: true }) }));
+    startWorkflow(issueId);
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "developing");
+    assert.equal(issue.infraAttempts, 0, "an unregistered-CI wait spends no infra attempt");
+    assert.match(issue.currentIntent ?? "", /Waiting for CI \(queued\) - no attempt spent/);
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer").length, 0, "no review handoff on 'no checks yet'");
+    const completed = listWorkflowEventsForIssue(issueId).find((e) => e.type === "checks.completed");
+    assert.ok(completed);
+    const payload = JSON.parse(completed.payloadJson ?? "{}");
+    assert.equal(payload.snapshot, "none");
+    assert.equal(payload.reason, "none_with_workflow");
+});
+test("NOT-311: none with no pull_request workflow on the base proceeds as today", async () => {
+    const issueId = await makeIssue();
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github: fakeGithub({ checks: "none", pullRequestWorkflow: false }) }));
+    startWorkflow(issueId);
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "reviewing", "no configured CI still hands off");
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer" && i.status === "pending").length, 1);
+    const completed = listWorkflowEventsForIssue(issueId).find((e) => e.type === "checks.completed");
+    assert.ok(completed);
+    const payload = JSON.parse(completed.payloadJson ?? "{}");
+    assert.equal(payload.snapshot, "none");
+    assert.equal(payload.reason, "none_no_workflow");
+});
+test("NOT-311: none with an unknown workflow answer waits fail-closed", async () => {
+    // The adapter cannot read the base (or has no such method): 'no checks yet' must
+    // never read as a pass.
+    const issueId = await makeIssue();
+    const github = fakeGithub({ checks: "none", pullRequestWorkflow: null });
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github }));
+    startWorkflow(issueId);
+    await pump(1);
     assert.equal(getIssue(issueId).status, "developing");
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer").length, 0);
+    const completed = listWorkflowEventsForIssue(issueId).find((e) => e.type === "checks.completed");
+    assert.equal(JSON.parse(completed.payloadJson ?? "{}").reason, "none_with_workflow");
+});
+test("NOT-311: past CHECKS_WAIT_CEILING_MS the wait escalates naming the PR and head SHA", async () => {
+    // A zero ceiling makes the very first wait already past it — no clock to inject,
+    // no sleeping: the deferral reports escalated and a policy_escalation lands.
+    const prev = process.env.CHECKS_WAIT_CEILING_MS;
+    process.env.CHECKS_WAIT_CEILING_MS = "0";
+    try {
+        const issueId = await makeIssue();
+        registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github: fakeGithub({ checks: "pending" }) }));
+        startWorkflow(issueId);
+        await pump(1);
+        const issue = getIssue(issueId);
+        assert.equal(issue.status, "needs_human");
+        assert.equal(issue.infraAttempts, 0, "a ceiling escalation spends no infra attempt");
+        const actions = listHumanActionsForIssue(issueId).filter((a) => a.status === "open");
+        assert.equal(actions.length, 1);
+        assert.equal(actions[0].actionType, "policy_escalation");
+        // The wait never hands off, so the issue row carries no PR/SHA — the milestone
+        // and the human action do.
+        const completed = listWorkflowEventsForIssue(issueId).find((e) => e.type === "checks.completed");
+        assert.ok(completed);
+        const msPayload = JSON.parse(completed.payloadJson ?? "{}");
+        assert.equal(msPayload.reason, "pending_ceiling");
+        assert.ok(msPayload.prNumber, "the milestone names the PR");
+        assert.ok(msPayload.headSha, "the milestone names the head SHA");
+        assert.match(actions[0].reason, new RegExp(`CI did not complete on ${msPayload.headSha}`));
+        assert.match(actions[0].reason, new RegExp(`PR #${msPayload.prNumber}`));
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.CHECKS_WAIT_CEILING_MS;
+        else
+            process.env.CHECKS_WAIT_CEILING_MS = prev;
+    }
 });
 test("NOT-255: a non-draft PR with otherwise-verified identity hands off cleanly (just-failed retry_merge)", async () => {
     // A merge-failure escalation is reachable from `retry_merge`, which undrafts the PR
@@ -2079,7 +2233,9 @@ test("NOT-252: checks_failed enriches checks_evidence and the retry prompt with
     registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: evolvingSpawn, github }));
     startWorkflow(issueId);
     await pump(1);
-    assert.equal(getIssue(issueId).status, "developing", "enriched checks_failed still retries on the infra budget");
+    assert.equal(getIssue(issueId).status, "developing", "enriched checks_failed still retries on the CI budget");
+    assert.equal(getIssue(issueId).ciAttempts, 1, "the enriched retry spends ci_attempts");
+    assert.equal(getIssue(issueId).infraAttempts, 0, "the enriched retry leaves infra_attempts alone");
     const evidence = listArtifactsForIssue(issueId).find((a) => a.kind === "checks_evidence");
     assert.ok(evidence, "enriched checks_failed persists checks_evidence");
     const content = JSON.parse(evidence.contentJson);
@@ -2138,3 +2294,132 @@ test("NOT-252: publish-only retry on checks_failed enriches evidence and the nex
     assert.match(prompts[1], /publish-checks/);
     assert.match(prompts[1], /is not in this registry/);
 });
+test("NOT-313: three CI repair attempts then a CI-specific escalation — infra_attempts stays 0", async () => {
+    // Exit-predicate loop: the CI budget (default 3) buys three repair attempts;
+    // the fourth consecutive checks_failed escalates with a CI-specific reason.
+    const issueId = await makeIssue();
+    const prompts = [];
+    let call = 0;
+    const evolvingSpawn = async (input) => {
+        call++;
+        prompts.push(input.prompt);
+        fs.writeFileSync(path.join(input.cwd, "feature.txt"), `implemented attempt ${call}\n`);
+        git(input.cwd, "add", ".");
+        git(input.cwd, "-c", "user.email=agent@test", "-c", "user.name=Agent", "commit", "-q", "-m", `implement ${call}`);
+        return { exitCode: 0, transcript: "Implementation conclusion: added the widget.", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: evolvingSpawn, github: fakeGithub({ checks: "failure" }) }));
+    startWorkflow(issueId);
+    await pump(1); // failure #1 → CI repair attempt 1
+    assert.equal(getIssue(issueId).status, "developing");
+    assert.equal(getIssue(issueId).ciAttempts, 1);
+    assert.equal(getIssue(issueId).infraAttempts, 0);
+    await pump(1); // failure #2 → CI repair attempt 2
+    assert.equal(getIssue(issueId).status, "developing");
+    assert.equal(getIssue(issueId).ciAttempts, 2);
+    assert.equal(getIssue(issueId).infraAttempts, 0);
+    assert.match(prompts[1], /CI repair attempt 1 of 3/);
+    await pump(1); // failure #3 → CI repair attempt 3
+    assert.equal(getIssue(issueId).status, "developing");
+    assert.equal(getIssue(issueId).ciAttempts, 3);
+    assert.equal(getIssue(issueId).infraAttempts, 0);
+    assert.match(prompts[2], /CI repair attempt 2 of 3/);
+    await pump(1); // failure #4 → budget spent → escalate
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "needs_human");
+    assert.equal(issue.ciAttempts, 3, "the escalation itself spends no further CI attempt");
+    assert.equal(issue.infraAttempts, 0, "four CI failures never touched the infra budget");
+    assert.match(prompts[3], /CI repair attempt 3 of 3/);
+    const action = listHumanActionsForIssue(issueId).find((a) => a.status === "open");
+    assert.ok(action, "the exhausted CI budget raises a human action");
+    assert.equal(action.actionType, "policy_escalation");
+    assert.match(action.reason, /CI checks still failing after 3 repair attempts \(limit 3\)/);
+    assert.doesNotMatch(action.reason, /infra-attempt limit reached/);
+});
+test("NOT-315: a failing dependency install is a worktree-setup failure with the stderr tail — the session is not spawned", async () => {
+    // Hermetic repo: the shared fixture carries no package.json (so the step would skip
+    // before the runner is ever invoked), so this test cuts its own repo + remote whose
+    // main tip declares npm dependencies — the fresh worktree then really triggers the install.
+    const npmRepo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-npm-repo-"));
+    const npmRemote = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deveff-npm-remote-"));
+    try {
+        git(npmRepo, "init", "-q", "-b", "main");
+        git(npmRepo, "config", "user.email", "test@example.com");
+        git(npmRepo, "config", "user.name", "Test");
+        fs.writeFileSync(path.join(npmRepo, "README.md"), "hello\n");
+        fs.writeFileSync(path.join(npmRepo, "package.json"), JSON.stringify({ name: "wt", version: "1.0.0" }));
+        fs.writeFileSync(path.join(npmRepo, "package-lock.json"), JSON.stringify({ name: "wt", lockfileVersion: 3, packages: {} }));
+        git(npmRepo, "add", ".");
+        git(npmRepo, "commit", "-q", "-m", "init");
+        execFileSync("git", ["init", "-q", "--bare", "-b", "main", npmRemote]);
+        git(npmRepo, "remote", "add", "origin", npmRemote);
+        git(npmRepo, "push", "-q", "origin", "main");
+        const devAgent = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const revAgent = createAgent({ name: `rev-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const issueId = createIssue({
+            title: "Add widget",
+            description: "Build the widget.",
+            acceptanceCriteria: "Widget renders.",
+            repo: npmRepo,
+            baseBranch: "main",
+            developerAgentId: devAgent.id,
+            reviewerAgentId: revAgent.id,
+            maxReviewRounds: 3,
+            maxInfraAttempts: 3,
+            source: "manual"
+        }).id;
+        let spawnCalls = 0;
+        const neverSpawn = async () => {
+            spawnCalls++;
+            return { exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false };
+        };
+        let depsCalls = 0;
+        const failingDeps = async () => {
+            depsCalls++;
+            const err = new Error("npm ci exited");
+            err.stderr = "npm error code EAI_AGAIN\nnpm error registry unreachable (sandbox has no network)\n";
+            throw err;
+        };
+        registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: neverSpawn, github: fakeGithub(), depsRunner: failingDeps }));
+        startWorkflow(issueId);
+        await pump(1);
+        assert.equal(depsCalls, 1, "the worktree declares npm deps, so the install must run exactly once");
+        assert.equal(spawnCalls, 0, "the session must not spawn when dependency provisioning fails");
+        const issue = getIssue(issueId);
+        assert.equal(issue.status, "developing", "adapter_failure retries on the infra budget");
+        const dev = listWorkerSessionsForIssue(issueId).find((s) => s.role === "developer");
+        // adapter_failure never spawned, so the session row goes terminal (done) with the
+        // setup failure recorded as its reason — like every other adapter_failure.
+        assert.ok(dev.status === "done" || dev.status === "failed", `terminal session, got ${dev.status}`);
+        const reason = JSON.parse(dev.errorJson ?? "{}").reason ?? dev.errorJson ?? "";
+        assert.match(reason, /worktree setup failed/);
+        assert.match(reason, /dependency install failed: /);
+        assert.match(reason, /registry unreachable/);
+    }
+    finally {
+        fs.rmSync(npmRepo, { recursive: true, force: true });
+        fs.rmSync(npmRemote, { recursive: true, force: true });
+    }
+});
+test("NOT-315: a skipped dependency install still emits worktree.deps_ready with ran/skipped and durationMs", async () => {
+    // The fixture repo carries no package.json, so the step skips (no package.json) and
+    // the fake runner is never called — the milestone must still record the skip.
+    const issueId = await makeIssue();
+    let depsCalls = 0;
+    const countingDeps = async () => {
+        depsCalls++;
+        return { stdout: "", stderr: "" };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github: fakeGithub(), depsRunner: countingDeps }));
+    startWorkflow(issueId);
+    await pump(1);
+    assert.equal(getIssue(issueId).status, "reviewing", "a skipped install must not block handoff");
+    assert.equal(depsCalls, 0, "no package.json means the runner is never invoked");
+    const { listWorkflowEventsForIssue: listEvents } = await import("../repository/workflow-events.js");
+    const depsEvent = listEvents(issueId).find((e) => e.type === "worktree.deps_ready");
+    assert.ok(depsEvent, "expected a worktree.deps_ready milestone");
+    const payload = JSON.parse(depsEvent.payloadJson);
+    assert.equal(payload.ran, false);
+    assert.match(String(payload.reason ?? ""), /no package\.json/);
+    assert.ok(typeof payload.durationMs === "number" && payload.durationMs >= 0);
+});

package/bundle/server/dist/coordinator/human-resolution.js

@@ -82,6 +82,7 @@ const VALID_CHOICES = {
     // below and the only legal resolver is commands.ts's dedicated muse_capability branch
     // (acknowledge records a per-version override; there is no workflow outcome to map).
     muse_capability: ["acknowledge"],
+    operator_verification: ["verified", "waive", "repair"],
 };
 /**
  * Validates a raw (actionType, choice) pair against that action type's allowed response
@@ -114,6 +115,16 @@ export function parseHumanResolution(actionType, choice, note) {
     if (actionType === "product_scope_decision" && note) {
         return { actionType, choice, note };
     }
+    // NOT-314: operator_verification always carries a required non-empty note (the
+    // recorded result, the waiver reason, or the repair instruction). A missing or
+    // blank note is a caller error — resolveHumanActionAndAdvance 400s, never stores.
+    if (actionType === "operator_verification") {
+        if (!VALID_CHOICES.operator_verification.includes(choice))
+            return null;
+        if (!note || !note.trim())
+            return null;
+        return { actionType, choice, note: note.trim() };
+    }
     return { actionType, choice };
 }
 /**
@@ -164,6 +175,14 @@ export function resolveHumanActionOutcome(resolution) {
             throw new Error(`Unrecognized policy_escalation choice: ${resolution.choice}`);
         case "product_scope_decision":
             return { issueStatus: "developing", startNewRound: true, roundKind: "none" };
+        case "operator_verification":
+            // NOT-314: `repair` is a genuine repair cycle (same shape as
+            // final_review:repair). `verified` / `waive` never reach here — the sync
+            // core parks them for undraft+merge before consulting this outcome map
+            // (same as policy_escalation:retry_merge).
+            if (resolution.choice === "repair")
+                return { issueStatus: "repairing", startNewRound: true, roundKind: "review" };
+            throw new Error(`Unrecognized operator_verification choice: ${resolution.choice}`);
         case "deck_interaction_required":
             // Same semantics as policy_escalation:resume — an authority/control-plane hiccup is
             // not a review-round spend; a fresh attempt mints its own new authority when it runs.

package/bundle/server/dist/coordinator/human-resolution.test.js

@@ -82,3 +82,36 @@ test("deck_interaction_required close ends the issue", () => {
     assert.equal(result.issueStatus, "closed");
     assert.equal(result.workflowOutcome, "closed");
 });
+// NOT-314: operator_verification parses only with a non-empty note.
+test("parseHumanResolution accepts operator_verification choices only with a note", () => {
+    assert.deepStrictEqual(parseHumanResolution("operator_verification", "verified", "SSO login OK"), {
+        actionType: "operator_verification",
+        choice: "verified",
+        note: "SSO login OK",
+    });
+    assert.deepStrictEqual(parseHumanResolution("operator_verification", "waive", "  waiver reason  "), {
+        actionType: "operator_verification",
+        choice: "waive",
+        note: "waiver reason",
+    });
+    assert.deepStrictEqual(parseHumanResolution("operator_verification", "repair", "fix the probe"), {
+        actionType: "operator_verification",
+        choice: "repair",
+        note: "fix the probe",
+    });
+    assert.equal(parseHumanResolution("operator_verification", "verified"), null);
+    assert.equal(parseHumanResolution("operator_verification", "verified", ""), null);
+    assert.equal(parseHumanResolution("operator_verification", "verified", "   "), null);
+    assert.equal(parseHumanResolution("operator_verification", "merge", "a note"), null);
+});
+test("operator_verification repair queues another repair round; verified/waive never map here", () => {
+    const result = resolveHumanActionOutcome({
+        actionType: "operator_verification",
+        choice: "repair",
+        note: "fix the probe",
+    });
+    assert.equal(result.issueStatus, "repairing");
+    assert.equal(result.startNewRound, true);
+    assert.equal(result.roundKind, "review");
+    assert.throws(() => resolveHumanActionOutcome({ actionType: "operator_verification", choice: "verified", note: "ok" }), /Unrecognized operator_verification choice/);
+});