agent-dealer 1.2.0 → 1.2.2

package/bundle/server/dist/capacity/muse.js

@@ -1,29 +1,31 @@
 // packages/server/src/capacity/muse.ts
 //
 // NOT-247: Muse Code capacity adapter — read stable MSP usage windows.
+// NOT-263: handshake repaired against the stable schema embedded in the
+// shipped binary (`muse schema generate-json-schema`).
 //
-// Reads observed capacity through the versioned `muse serve` Session Protocol
-// (MSP 1.3) without sending a prompt and without consuming model tokens: a
-// single `usage/read` JSON-RPC request over a one-shot managed `muse serve`
-// stdio connection, then shutdown. `usage/changed` notifications received
-// while the connection is alive are recorded. The client enforces a read-only
-// allowlist (`usage/read`) — any other method throws before it is written, so
-// polling can never start a session, send a prompt, or run model work. It
-// never touches the Keychain or undocumented endpoints.
+// Reads observed capacity through the stable Muse Session Protocol without
+// sending a prompt and without consuming model tokens: `muse serve` over a
+// one-shot managed stdio connection, then `initialize` → `initialized` → one
+// `usage/read`, then shutdown. `usage/changed` notifications received while
+// the connection is alive are recorded. The client enforces a read-only
+// allowlist (`initialize`, `initialized`, `usage/read`) — any other method
+// throws before it is written, so polling can never start a session, send a
+// prompt, or run model work. It never touches the Keychain or undocumented
+// endpoints.
 //
-// MSP 1.3 `usage/read` shape (per the contract):
+// Stable `usage/read` shape:
 //   result: {
-//     protocol: "msp/1.3",
 //     usage?: {
 //       observedAtMs: number,
 //       tier: string,                       // dropped: never persisted, never served
-//       rolling?: { usedPercent, resetsAtMs, windowDurationMins },
+//       window?: { usedPercent, resetsAtMs, windowDurationMins },
 //       weekly?: { usedPercent, resetsAtMs }
 //     }
 //   }
 // `usage` may be omitted when Muse has no observation — preserved as N/A
-// (`missing`). The rolling label is derived from `windowDurationMins` by the
-// shared normalization, never hardcoded.
+// (`missing`). The rolling (`window`) label is derived from
+// `windowDurationMins` by the shared normalization, never hardcoded.
 //
 // Failure semantics (shared CapacityUnavailableReason enum only):
 // - No credential (no META_API_KEY and no login file) / `usage` omitted /
@@ -42,7 +44,16 @@ import { MUSE_CLI_ENV, resolveMuseAuthFile, resolveMuseBin } from "../cli-env.js
 import { normalizeAdapterWindow, normalizeUnavailableWindow, } from "./adapter.js";
 export const MUSE_RUNTIME = "muse_code";
 /** Methods this client may ever send. Anything else throws before write. */
-export const MSP_READ_ONLY_METHODS = ["usage/read"];
+export const MSP_READ_ONLY_METHODS = ["initialize", "initialized", "usage/read"];
+/**
+ * Client identity sent in the `initialize` handshake. The stable schema
+ * requires `clientInfo.name` to match `^[a-z0-9_]+$` plus a version string.
+ * Version is kept in sync with `packages/server/package.json`.
+ */
+export const MUSE_CLIENT_INFO = {
+    name: "agent_dealer",
+    version: "1.2.1",
+};
 /** Notification the client records (never sends) while connected. */
 export const MSP_USAGE_CHANGED = "usage/changed";
 /** Methods that would start billable model work — never sent, asserted in tests. */
@@ -61,21 +72,18 @@ function readOnlyRequest(id, method, params) {
     assertMuseReadOnlyMethod(method);
     return `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
 }
+function readOnlyNotification(method, params) {
+    assertMuseReadOnlyMethod(method);
+    return `${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`;
+}
 /**
- * Versioned Session Protocol argv. Fixed: capacity reads never `exec`.
- *
- * Caveat: this argv and the handshake-free single `usage/read` below were
- * built from the ticket contract brief — the official Muse Code docs were
- * unreachable at implementation time, so they are unverified against the
- * published MSP surface. The committed fake (`fixtures/fake-muse-serve.mjs`)
- * likewise enforces no handshake, so tests cannot catch a handshake
- * requirement either. If a live `muse serve` demands an `initialize` step,
- * the read-only allowlist will reject it and every live read will fail
- * closed as `missing`/`unparsable` (never billed); re-check the argv against
- * the docs before debugging any live failure.
+ * Stable Session Protocol argv. Fixed: capacity reads never `exec`, and the
+ * host takes no `--protocol` flag — `muse serve` with that flag exits 2
+ * against the shipped binary, so this stays exactly `["serve"]`.
  */
-export const MUSE_SERVE_ARGV = ["serve", "--protocol", "msp/1.3"];
-/** Single JSON-RPC request id for the one-shot read. */
+export const MUSE_SERVE_ARGV = ["serve"];
+/** JSON-RPC request ids for the one-shot read (init handshake, then usage). */
+export const MSP_INITIALIZE_ID = "muse-capacity-init";
 export const MSP_USAGE_READ_ID = "muse-capacity-1";
 /** Weekly windows carry no duration in MSP 1.3; a week in minutes. */
 export const MUSE_WEEKLY_DURATION_MINUTES = 10080;
@@ -133,6 +141,9 @@ function windowReadingFromEntry(kind, entry, observedAt) {
         resetAt,
         observedAt,
         source: "supported_protocol",
+        // Muse reports exactly this one rolling/weekly pair — it is always the
+        // account-wide critical window, never a model-specific extra.
+        criticalRole: kind === "rolling" ? "five_hour" : "weekly",
     };
 }
 /**
@@ -153,7 +164,7 @@ function extractUsageObject(payload) {
             return { error: "usage is not an object" };
         return { usage: usage };
     }
-    if ("observedAtMs" in result || "rolling" in result || "weekly" in result) {
+    if ("observedAtMs" in result || "window" in result || "rolling" in result || "weekly" in result) {
         return { usage: result };
     }
     const keys = Object.keys(result);
@@ -162,25 +173,27 @@ function extractUsageObject(payload) {
     return { error: "result carries no usage observation" };
 }
 /**
- * Normalize MSP 1.3 `usage` into adapter readings. Returns null when the
- * payload carries no observation or is malformed (callers needing the
- * distinction check the payload shape first). Entries that are individually
- * malformed are skipped — the caller re-reports present-but-bad keys as
- * per-window `unparsable` readings so a bad sibling never sinks a good
- * window.
+ * Normalize stable `usage` into adapter readings. The rolling window arrives
+ * as `usage.window` (a legacy `usage.rolling` spelling is tolerated and maps
+ * to the same `rolling_all_models` snapshot). Returns null when the payload
+ * carries no observation or is malformed (callers needing the distinction
+ * check the payload shape first). Entries that are individually malformed
+ * are skipped — the caller re-reports present-but-bad keys as per-window
+ * `unparsable` readings so a bad sibling never sinks a good window.
  */
 export function museUsageToReadings(payload, observedAt = new Date().toISOString()) {
     const { usage, error } = extractUsageObject(payload);
     if (error !== undefined || usage === undefined)
         return null;
     const u = usage;
-    const hasRolling = u.rolling !== undefined;
+    const rollingEntry = u.window !== undefined ? u.window : u.rolling;
+    const hasRolling = rollingEntry !== undefined;
     const hasWeekly = u.weekly !== undefined;
     const observedAtMs = typeof u.observedAtMs === "number" && Number.isFinite(u.observedAtMs) ? u.observedAtMs : null;
     const observed = observedAtMs !== null ? new Date(observedAtMs).toISOString() : observedAt;
     const out = [];
     if (hasRolling) {
-        const rolling = windowReadingFromEntry("rolling", u.rolling, observed);
+        const rolling = windowReadingFromEntry("rolling", rollingEntry, observed);
         if (rolling)
             out.push(rolling);
     }
@@ -200,11 +213,15 @@ export function museBadWindowKinds(payload) {
     if (error !== undefined || usage === undefined)
         return [];
     const u = usage;
+    const entries = {
+        rolling: u.window !== undefined ? u.window : u.rolling,
+        weekly: u.weekly,
+    };
     const bad = [];
     for (const kind of ["rolling", "weekly"]) {
-        if (u[kind] === undefined)
+        if (entries[kind] === undefined)
             continue;
-        const probe = windowReadingFromEntry(kind, u[kind], new Date().toISOString());
+        const probe = windowReadingFromEntry(kind, entries[kind], new Date().toISOString());
         if (!probe)
             bad.push(kind);
     }
@@ -253,10 +270,11 @@ function hasMuseCredential(env, authFilePath) {
     }
 }
 /**
- * Spawn `muse serve`, send one `usage/read`, record any `usage/changed`
- * notifications, then shut the connection down. Never throws for
- * provider-side failures — those come back as `failure.kind`. Never sends
- * anything outside MSP_READ_ONLY_METHODS.
+ * Spawn `muse serve`, run the stable handshake (`initialize` with a
+ * `clientInfo` identity, then the `initialized` notification), send one
+ * `usage/read`, record any `usage/changed` notifications, then shut the
+ * connection down. Never throws for provider-side failures — those come back
+ * as `failure.kind`. Never sends anything outside MSP_READ_ONLY_METHODS.
  */
 export function requestMuseUsage(opts = {}) {
     const command = opts.command ?? resolveMuseBin();
@@ -272,6 +290,7 @@ export function requestMuseUsage(opts = {}) {
         let settled = false;
         let child;
         let buffer = "";
+        let initResolve = null;
         let readResolve = null;
         const finish = (out) => {
             if (settled)
@@ -298,7 +317,12 @@ export function requestMuseUsage(opts = {}) {
                     updates.push(msg.params ?? null);
                 return;
             }
-            if (msg.id === MSP_USAGE_READ_ID && readResolve) {
+            if (msg.id === MSP_INITIALIZE_ID && initResolve) {
+                const cb = initResolve;
+                initResolve = null;
+                cb(msg);
+            }
+            else if (msg.id === MSP_USAGE_READ_ID && readResolve) {
                 const cb = readResolve;
                 readResolve = null;
                 cb(msg);
@@ -361,6 +385,28 @@ export function requestMuseUsage(opts = {}) {
             }
         };
         void (async () => {
+            if (!write(readOnlyRequest(MSP_INITIALIZE_ID, "initialize", { clientInfo: { ...MUSE_CLIENT_INFO } }))) {
+                fail("unavailable");
+                return;
+            }
+            const init = await new Promise((res) => {
+                initResolve = res;
+            });
+            if (settled)
+                return;
+            if (!init || init.error) {
+                if (init?.error && errorLooksAuth(init.error))
+                    fail("unauthenticated");
+                else if (init?.error && init.error.code === -32601)
+                    fail("unsupported");
+                else
+                    fail("unavailable");
+                return;
+            }
+            if (!write(readOnlyNotification("initialized", {}))) {
+                fail("unavailable");
+                return;
+            }
             if (!write(readOnlyRequest(MSP_USAGE_READ_ID, "usage/read", {}))) {
                 fail("unavailable");
                 return;
@@ -504,6 +550,11 @@ export async function readMuseCapacity(opts = {}) {
             durationMinutes: kind === "weekly" ? MUSE_WEEKLY_DURATION_MINUTES : null,
             reason: "unparsable",
             observedAt,
+            // This unavailable reading still stands in for the account-wide
+            // critical half it replaces — untagging it would make the client
+            // synthesize a second, duplicate N/A row for the same half (NOT-264
+            // review finding).
+            criticalRole: kind === "rolling" ? "five_hour" : "weekly",
         });
     }
     if (windows.length === 0 && unavailable.length === 0) {

package/bundle/server/dist/capacity/muse.test.js

@@ -1,19 +1,23 @@
 // packages/server/src/capacity/muse.test.ts
 //
 // NOT-247: Muse serve adapter — fake-subprocess coverage only, never a live
-// Muse request. A fake MSP 1.3 server returns rolling + weekly usage (two
+// Muse request. A fake stable MSP server returns window + weekly usage (two
 // independent snapshots with correct remaining percents and reset times), the
 // rolling label derives from `windowDurationMins` (never hardcoded),
 // failure modes map to explicit N/A reasons without touching runtime health,
-// and the recorded protocol traffic proves the client never sends a prompt.
+// and the recorded protocol traffic proves the client runs the
+// initialize → initialized → usage/read handshake and never sends a prompt.
+// NOT-263: the fake enforces the stable contract (no `--protocol` argv,
+// handshake order, `usage.window` field names).
 import { test, before } from "node:test";
 import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-cap-"));
-import { assertMuseReadOnlyMethod, createMuseCapacityAdapter, MSP_FORBIDDEN_MODEL_METHODS, museRefreshThrottleMs, museUsageToReadings, maybeRefreshMuseCapacityFromServe, normalizeMuseResetsAt, normalizeMuseUnavailable, readMuseCapacity, refreshMuseCapacityFromServe, requestMuseUsage, resetMuseCapacityRefreshState, } from "./muse.js";
-import { normalizeAdapterWindow } from "./adapter.js";
+import { assertMuseReadOnlyMethod, createMuseCapacityAdapter, MSP_FORBIDDEN_MODEL_METHODS, MUSE_CLIENT_INFO, MUSE_SERVE_ARGV, museRefreshThrottleMs, museUsageToReadings, maybeRefreshMuseCapacityFromServe, normalizeMuseResetsAt, normalizeMuseUnavailable, readMuseCapacity, refreshMuseCapacityFromServe, requestMuseUsage, resetMuseCapacityRefreshState, } from "./muse.js";
+import { normalizeAdapterWindow, normalizeUnavailableWindow } from "./adapter.js";
 const { migrate } = await import("../db/index.js");
 const { clearAllCapacitySnapshots, listCapacitySnapshots } = await import("../repository/runtime-capacity.js");
 const { clearAllRuntimeAvailability, runtimeAvailability, } = await import("../repository/runtime-availability.js");
@@ -40,6 +44,14 @@ function fakeOpts(mode, extra = {}) {
         },
     };
 }
+test("serve argv is the shipping contract: no --protocol flag", () => {
+    assert.deepEqual([...MUSE_SERVE_ARGV], ["serve"]);
+    assert.ok(!MUSE_SERVE_ARGV.includes("--protocol"), "muse serve takes no --protocol flag");
+});
+test("handshake identity matches the stable clientInfo shape", () => {
+    assert.match(MUSE_CLIENT_INFO.name, /^[a-z0-9_]+$/);
+    assert.ok(MUSE_CLIENT_INFO.version.length > 0, "versioned client identity required");
+});
 test("usage windows keep identity, percent, duration, and reset", () => {
     const now = Date.now();
     const parsed = museUsageToReadings({
@@ -47,7 +59,7 @@ test("usage windows keep identity, percent, duration, and reset", () => {
         usage: {
             observedAtMs: now,
             tier: "contributor",
-            rolling: { usedPercent: 60, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
+            window: { usedPercent: 60, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
             weekly: { usedPercent: 25, resetsAtMs: now + 3 * 24 * 3600_000 },
         },
     }, new Date(now).toISOString());
@@ -62,16 +74,30 @@ test("usage windows keep identity, percent, duration, and reset", () => {
     const normalized = normalizeAdapterWindow("muse_code", rolling, now);
     assert.equal(normalized.displayLabel, "5H");
     assert.equal(normalized.remainingPercent, 40);
+    assert.equal(normalized.criticalRole, "five_hour");
     const weekly = parsed.windows.find((w) => w.windowKey === "weekly_all_models");
     assert.equal(normalizeAdapterWindow("muse_code", weekly, now).displayLabel, "1W");
     assert.equal(normalizeAdapterWindow("muse_code", weekly, now).remainingPercent, 75);
+    assert.equal(normalizeAdapterWindow("muse_code", weekly, now).criticalRole, "weekly");
+});
+test("legacy rolling spelling maps to the same snapshot", () => {
+    const now = Date.now();
+    const parsed = museUsageToReadings({
+        usage: {
+            observedAtMs: now,
+            rolling: { usedPercent: 60, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
+        },
+    }, new Date(now).toISOString());
+    assert.ok(parsed);
+    assert.equal(parsed.windows.length, 1);
+    assert.equal(parsed.windows[0].windowKey, "rolling_all_models");
 });
 test("rolling label derives from windowDurationMins, never a hardcoded 5H", () => {
     const now = Date.now();
     const parsed = museUsageToReadings({
         usage: {
             observedAtMs: now,
-            rolling: { usedPercent: 10, resetsAtMs: now + 6 * 3600_000, windowDurationMins: 720 },
+            window: { usedPercent: 10, resetsAtMs: now + 6 * 3600_000, windowDurationMins: 720 },
         },
     }, new Date(now).toISOString());
     assert.ok(parsed);
@@ -86,7 +112,7 @@ test("payloads without an observation read null, not empty", () => {
     assert.equal(museUsageToReadings({ protocol: "msp/1.3" }), null);
     assert.equal(museUsageToReadings({ usage: null }), null);
     assert.equal(museUsageToReadings({ usage: { observedAtMs: Date.now() } }).windows.length, 0);
-    assert.equal(museUsageToReadings({ usage: { observedAtMs: Date.now(), rolling: { windowDurationMins: 300 } } })
+    assert.equal(museUsageToReadings({ usage: { observedAtMs: Date.now(), window: { windowDurationMins: 300 } } })
         .windows.length, 0);
 });
 test("resetsAtMs accepts ms, seconds, and ISO; rejects garbage", () => {
@@ -99,7 +125,9 @@ test("resetsAtMs accepts ms, seconds, and ISO; rejects garbage", () => {
     assert.equal(normalizeMuseResetsAt(null), null);
     assert.equal(normalizeMuseResetsAt(-5), null);
 });
-test("only usage/read can be sent; session prompts throw before write", () => {
+test("only the handshake and usage/read can be sent; session prompts throw before write", () => {
+    assertMuseReadOnlyMethod("initialize");
+    assertMuseReadOnlyMethod("initialized");
     assertMuseReadOnlyMethod("usage/read");
     for (const m of ["session/start", "session/prompt", "session/resume", "exec", "usage/write"]) {
         assert.throws(() => assertMuseReadOnlyMethod(m), /refusing non-read method/);
@@ -144,31 +172,85 @@ test("usage/changed notifications are consumed while the connection is alive", a
     assert.equal(read.failure, null);
     assert.equal(read.updates.length, 1);
 });
-test("protocol traffic is read-only: usage/read and nothing else", async () => {
+test("protocol traffic is the stable handshake then exactly one usage/read", async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-record-"));
     const recordPath = path.join(dir, "methods.jsonl");
     const { opts } = fakeOpts("full", { env: { FAKE_MSP_RECORD: recordPath } });
     await readMuseCapacity(opts);
-    const methods = fs
+    const lines = fs
         .readFileSync(recordPath, "utf8")
         .split("\n")
         .filter(Boolean)
-        .map((l) => String(JSON.parse(l).method));
-    assert.ok(methods.length >= 1, `expected a read, got ${methods}`);
+        .map((l) => JSON.parse(l));
+    const methods = lines.map((l) => String(l.method));
+    assert.deepEqual(methods, ["initialize", "initialized", "usage/read"]);
+    const init = lines[0];
+    assert.equal(init.params?.clientInfo?.name, MUSE_CLIENT_INFO.name);
+    assert.match(String(init.params?.clientInfo?.name ?? ""), /^[a-z0-9_]+$/);
+    assert.equal(init.params?.clientInfo?.version, MUSE_CLIENT_INFO.version);
     for (const m of methods) {
-        assert.equal(m, "usage/read");
         assert.ok(!/session|prompt|exec|message|turn|thread/i.test(m), `billable method ${m}`);
     }
 });
+test("fake rejects the removed --protocol argv like the shipped binary", async () => {
+    clearAllCapacitySnapshots();
+    const now = Date.now();
+    const result = await readMuseCapacity({
+        command: process.execPath,
+        args: [FAKE, "--protocol", "msp/1.3"],
+        env: { META_API_KEY: "test-fake-key", FAKE_MSP_MODE: "full" },
+        timeoutMs: 10_000,
+        nowMs: now,
+    });
+    assert.equal(result.windows.length, 0);
+    assert.equal(result.unavailable.length, 1);
+    assert.equal(result.unavailable[0].windowKey, "muse_account_usage");
+    assert.equal(result.unavailable[0].reason, "missing");
+});
+test("fake requires initialize before usage/read", async () => {
+    const child = spawn(process.execPath, [FAKE], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, FAKE_MSP_MODE: "full", META_API_KEY: "test-fake-key" },
+    });
+    try {
+        const first = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("timed out waiting for fake response")), 5000);
+            timer.unref?.();
+            let buf = "";
+            child.stdout.on("data", (chunk) => {
+                buf += chunk.toString();
+                const idx = buf.indexOf("\n");
+                if (idx >= 0) {
+                    clearTimeout(timer);
+                    resolve(buf.slice(0, idx));
+                }
+            });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: "bare-read", method: "usage/read", params: {} })}\n`);
+        });
+        const msg = JSON.parse(first);
+        assert.ok(msg.error, "bare usage/read is rejected before the handshake");
+        assert.match(String(msg.error?.message ?? ""), /initialize/i);
+    }
+    finally {
+        child.kill();
+    }
+});
 test("a malformed sibling window does not sink the good one", async () => {
     clearAllCapacitySnapshots();
     const { opts } = fakeOpts("partial-bad-weekly");
     const result = await readMuseCapacity(opts);
     assert.equal(result.windows.length, 1);
     assert.equal(result.windows[0].windowKey, "rolling_all_models");
+    assert.equal(result.windows[0].criticalRole, "five_hour");
     assert.equal(result.unavailable.length, 1);
     assert.equal(result.unavailable[0].windowKey, "weekly_all_models");
     assert.equal(result.unavailable[0].reason, "unparsable");
+    // NOT-264 review finding: the unavailable half must still carry its
+    // criticalRole, or the client can't find it and synthesizes a second,
+    // duplicate N/A row for the same half instead of one.
+    assert.equal(result.unavailable[0].criticalRole, "weekly");
+    const normalizedUnavailable = normalizeUnavailableWindow("muse_code", result.unavailable[0]);
+    assert.equal(normalizedUnavailable.criticalRole, "weekly");
 });
 async function expectUnavailable(mode, reason, extra = {}) {
     clearAllCapacitySnapshots();

package/bundle/server/dist/capacity/service.js

@@ -47,6 +47,7 @@ export async function ingestAdapterResult(result) {
         source: w.source,
         unavailableReason: w.unavailableReason,
         evidenceRef: w.evidenceRef,
+        criticalRole: w.criticalRole,
     })));
 }
 /** Classify a stored window at read time (freshness/expiry/reset, not just flags). */

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

@@ -176,15 +176,20 @@ function loadPriorVerificationReceipt(issueId, currentHeadSha) {
 /**
  * The ticket requires verifying "draft PR identity, base SHA, and current head SHA" —
  * not just accepting whatever `gh pr view` returns. A review round found the original
- * code took `prView` on faith: wrong base, a non-draft PR, a PR number that silently
- * changed between rounds, or a stale `headRefOid` would all have been accepted as a
- * clean handoff. `localHead` is this process's own `git rev-parse HEAD` right after the
- * push it just performed — the actual ground truth `gh`'s view is checked against.
+ * code took `prView` on faith: wrong base, a PR number that silently changed between
+ * rounds, or a stale `headRefOid` would all have been accepted as a clean handoff.
+ * `localHead` is this process's own `git rev-parse HEAD` right after the push it just
+ * performed — the actual ground truth `gh`'s view is checked against.
+ *
+ * NOT-255: draft-ness is deliberately NOT identity. A failed `retry_merge` undrafts
+ * the PR before attempting the squash-merge (`auto-merge.ts` runs `gh pr ready`
+ * first), so a merge-failure repair/resume round legitimately starts with a non-draft
+ * PR whose branch, base, number, and head still verify. Requiring `isDraft` here
+ * turned that legitimate state into an `adapter_failure` loop no repair round could
+ * exit. A non-draft PR whose branch/base/number/head all verify proceeds; the
+ * identity-drift cases above still fail exactly as before.
  */
 async function validatePrIdentity(prView, opts) {
-    if (!prView.isDraft) {
-        return { ok: false, reason: `PR #${prView.number} is not a draft PR` };
-    }
     if (prView.headRefName !== opts.branchName) {
         return { ok: false, reason: `PR head branch ${prView.headRefName} does not match the issue branch ${opts.branchName}` };
     }

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

@@ -457,8 +457,12 @@ test("timed_out (checks poll): checks stay pending past the poll deadline", asyn
     await pump(1);
     assert.equal(getIssue(issueId).status, "developing");
 });
-test("adapter_failure: a non-draft PR is rejected rather than accepted as a clean handoff", async () => {
-    const issueId = await makeIssue({ maxInfraAttempts: 0 });
+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
+    // before attempting the squash-merge. When that merge fails the PR is left non-draft
+    // — legitimately — so a repair/resume developer round must not fail identity on
+    // draft-ness alone when branch/base/number/head all verify.
+    const issueId = await makeIssue();
     const github = fakeGithub();
     const realViewPr = github.viewPr.bind(github);
     github.viewPr = async (opts) => {
@@ -469,9 +473,61 @@ test("adapter_failure: a non-draft PR is rejected rather than accepted as a clea
     startWorkflow(issueId);
     await pump(1);
     const issue = getIssue(issueId);
-    assert.equal(issue.status, "needs_human");
-    assert.equal(issue.currentRound, 1, "a rejected PR identity never consumes a round");
-    assert.equal(issue.prNumber, null, "a rejected identity must never be recorded as the verified handoff");
+    assert.equal(issue.status, "reviewing");
+    assert.ok(issue.prNumber, "a verified non-draft identity is still recorded as the handoff");
+});
+test("NOT-255: repair from a merge-failure escalation with a non-draft PR runs a round that hands off, not re-escalates", async () => {
+    // commands.ts routing: an open policy_escalation with mergeFailure evidence resolved
+    // with `repair` queues a developer round. That round starts with the non-draft PR
+    // the failed retry_merge left behind and must reach the reviewer instead of
+    // immediately re-escalating on "is not a draft PR".
+    const { transitionIssue } = await import("../repository/issues.js");
+    const { createHumanAction } = await import("../repository/human-actions.js");
+    const { responseOptionsFor } = await import("./commands.js");
+    const { MERGE_FAILURE_EVIDENCE_KEY } = await import("./human-resolution.js");
+    const issueId = await makeIssue();
+    const github = fakeGithub();
+    const realViewPr = github.viewPr.bind(github);
+    github.viewPr = async (opts) => {
+        const view = await realViewPr(opts);
+        return view ? { ...view, isDraft: false } : view;
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github }));
+    startWorkflow(issueId);
+    // A real merge failure happens after all work finished: clear the initial pending
+    // round (the coordinator enforces one pending/leased item per instance) to reach
+    // the parked state a failed retry_merge leaves behind.
+    for (const item of listWorkItemsForIssue(issueId)) {
+        if (item.status === "pending" || item.status === "leased")
+            cancelWorkItem(item.id);
+    }
+    transitionIssue(issueId, "needs_human", {
+        currentOwner: "human",
+        currentIntent: "Auto-merge failed: merge conflict",
+    });
+    const action = createHumanAction({
+        issueId,
+        workflowInstanceId: getActiveWorkflowInstance(issueId).id,
+        actionType: "policy_escalation",
+        reason: "Auto-merge failed: merge conflict",
+        question: "Auto-merge failed: merge conflict Retry the merge, queue another repair round, or close the issue?",
+        responseOptions: responseOptionsFor("policy_escalation", false, { mergeFailure: true }),
+        evidence: { [MERGE_FAILURE_EVIDENCE_KEY]: true },
+    });
+    const resolved = resolveHumanActionAndAdvance(action.id, "op", "repair");
+    assert.equal(resolved.ok, true);
+    if (resolved.ok) {
+        assert.equal(resolved.issueStatus, "repairing");
+        assert.ok(resolved.nextWorkItemId, "repair must queue a developer round");
+    }
+    // Only pump the developer item — the file's placeholder reviewer handler (always
+    // session_failed) would otherwise fail the just-queued reviewer round and mask the
+    // handoff this test actually checks.
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "reviewing", "the repair round must hand off, not immediately re-escalate");
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer" && i.status === "pending").length, 1, "the handoff must queue the reviewer round");
+    assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0, "no fresh escalation may be waiting");
 });
 test("adapter_failure: a PR based against the wrong branch is rejected rather than accepted", async () => {
     const issueId = await makeIssue({ maxInfraAttempts: 0 });
@@ -486,6 +542,87 @@ test("adapter_failure: a PR based against the wrong branch is rejected rather th
     await pump(1);
     assert.equal(getIssue(issueId).status, "needs_human");
 });
+test("adapter_failure: a PR on the wrong head branch is rejected rather than accepted", async () => {
+    // NOT-255 regression guard: tolerating non-draft must not weaken the branch check.
+    const issueId = await makeIssue({ maxInfraAttempts: 0 });
+    const github = fakeGithub();
+    const realViewPr = github.viewPr.bind(github);
+    github.viewPr = async (opts) => {
+        const view = await realViewPr(opts);
+        return view ? { ...view, headRefName: "someone-elses-branch" } : view;
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: commitingSpawn, github }));
+    startWorkflow(issueId);
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "needs_human");
+    assert.equal(issue.prNumber, null, "a rejected identity must never be recorded as the verified handoff");
+});
+test("adapter_failure: a PR number that changed between rounds is rejected rather than accepted", async () => {
+    // NOT-255 regression guard: tolerating non-draft must not weaken the number check.
+    // Round 1 hands off cleanly (recording the PR number on the issue); the reviewer
+    // requests changes; round 2 reports a different PR number for the same branch and
+    // must be rejected.
+    const { runReviewerEffect } = await import("./reviewer-effect.js");
+    const issueId = await makeIssue({ maxInfraAttempts: 0 });
+    // Round 2 must push a NEW commit — re-running the identical write+commit against
+    // an unchanged file would fail with "nothing to commit" in the fake, not the fix.
+    let devCalls = 0;
+    const twoRoundSpawn = async (input) => {
+        devCalls++;
+        if (devCalls === 1)
+            return commitingSpawn(input);
+        fs.writeFileSync(path.join(input.cwd, "followup.txt"), "follow-up\n");
+        git(input.cwd, "add", ".");
+        git(input.cwd, "-c", "user.email=agent@test", "-c", "user.name=Agent", "commit", "-q", "-m", "follow-up");
+        return { exitCode: 0, transcript: "Implementation conclusion: follow-up work.", logPath: "/dev/null", timedOut: false };
+    };
+    const github = fakeGithub();
+    // The shared fake's publishReview throws (developer-only use) — the reviewer
+    // round needs the success stub NOT-220's shared github carries.
+    github.publishReview = async ({ event }) => ({ ok: true, event, usedCommentFallback: false });
+    const realViewPr = github.viewPr.bind(github);
+    github.viewPr = async (opts) => {
+        // The reviewer selects by PR number alone, but the shared fake requires an
+        // explicit branch (NOT-82) — pin the number-only lookup to this issue's branch.
+        const view = await realViewPr(opts.branch == null && opts.number != null ? { ...opts, branch: issueBranchName(issueId) } : opts);
+        if (!view)
+            return view;
+        // Once round 1's handoff recorded the PR number, report a different one — but
+        // only on the developer's branch-pinned lookups (no `number` selector). The
+        // reviewer selects by PR number and must keep seeing the recorded one, or round
+        // 1 would never reach the repair round this test needs.
+        if (getIssue(issueId)?.prNumber != null && opts.number == null) {
+            return { ...view, number: view.number + 1000 };
+        }
+        return view;
+    };
+    const reviewerSpawn = async (input) => {
+        const baseSha = input.prompt.match(/"baseSha" to exactly "([0-9a-f]+)"/)?.[1];
+        const headSha = input.prompt.match(/"headSha" to exactly "([0-9a-f]+)"/)?.[1];
+        if (!baseSha || !headSha)
+            throw new Error("could not extract SHAs from reviewer prompt");
+        const body = {
+            verdict: "changes_requested",
+            baseSha,
+            headSha,
+            acceptanceCriteriaAssessment: "Not yet.",
+            evidenceAssessment: "Evidence checked.",
+            findings: [{ fingerprint: "missing-test", severity: "blocking", title: "No test", rationale: "Add a test." }],
+            risks: [],
+        };
+        return { exitCode: 0, transcript: "```json\n" + JSON.stringify(body) + "\n```\n", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: twoRoundSpawn, github }));
+    registerEffectHandler("reviewer", (ctx) => runReviewerEffect(ctx, { deckCallTool: okDeckCallTool, spawn: reviewerSpawn, github: github }));
+    startWorkflow(issueId);
+    await pump(20);
+    const issue = getIssue(issueId);
+    assert.equal(devCalls, 2, "the repair round must actually run against the changed PR number");
+    assert.equal(issue.status, "needs_human", "a changed PR number must escalate, not hand off");
+    assert.ok(listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"), "the number drift must surface as a policy escalation");
+    resetEffectHandlers();
+});
 test("clean handoff: a briefly stale headRefOid (gh's view lags the push) catches up within the reconcile window", async () => {
     // NOT-110: the first couple of `gh pr view` reads still show the pre-push head — exactly
     // the GraphQL-lag race observed in production — then GitHub catches up. This must be