agent-dealer 1.2.6 → 1.2.8

package/bundle/server/dist/adapters/muse-visual-qa.js

@@ -0,0 +1,114 @@
+// packages/server/src/adapters/muse-visual-qa.ts
+//
+// NOT-303: Muse Dev visual-QA screenshot-path preflight.
+//
+// `Google Chrome.app` headless cannot run inside a Muse developer session: every
+// launch aborts at macOS process registration
+// (`TransformProcessType -> _RegisterApplication`, SIGABRT/exit 134, no output, no
+// file) under the Muse sandbox, and `--no-sandbox` only disables Chrome's own
+// sandbox so it cannot help. Evidence:
+// `docs/evaluations/muse-code/chrome-headless-screenshot.md`.
+//
+// This module resolves, coordinator-side and before the session starts, which
+// screenshot path a Muse developer worker gets. It never launches a browser and
+// never touches the sandbox: the default verdict is unusable-with-reason (fail
+// loud, so the worker reads it in its prompt instead of discovering the abort
+// mid-session). Only an operator pre-installed non-AppKit headless shell,
+// pointed at by `MUSE_HEADLESS_SHELL_BIN`, flips the verdict — the binary cannot
+// be fetched in-session because the developer sandbox network is `restricted`.
+//
+// Deliberately NOT covered: widening the Muse sandbox, a coordinator-side
+// screenshot step, and how Cursor/Claude/Codex workers run Chrome.
+import fs from "node:fs";
+import path from "node:path";
+/** Operator override: absolute path to a pre-installed headless shell binary. */
+export const MUSE_HEADLESS_SHELL_BIN_ENV = "MUSE_HEADLESS_SHELL_BIN";
+/** Phase 1 evidence behind the default verdict. */
+export const MUSE_VISUAL_QA_DOC = "docs/evaluations/muse-code/chrome-headless-screenshot.md";
+/** The abort every `Google Chrome.app` headless launch dies with in-sandbox. */
+export const MUSE_CHROME_APP_ABORT = "TransformProcessType -> _RegisterApplication (SIGABRT, exit 134)";
+/**
+ * Resolve the screenshot path for a Muse developer worker. Pure apart from the
+ * injected `exists` probe; never spawns anything (probing `Google Chrome.app`
+ * would only mint another crash report).
+ */
+export function checkMuseVisualQa(opts = {}) {
+    const env = opts.env ?? process.env;
+    const exists = opts.exists ?? fs.existsSync;
+    const configured = env[MUSE_HEADLESS_SHELL_BIN_ENV]?.trim() || null;
+    if (configured) {
+        if (!path.isAbsolute(configured)) {
+            return {
+                usable: false,
+                binary: null,
+                args: [],
+                reason: `${MUSE_HEADLESS_SHELL_BIN_ENV} must be an absolute path (got a non-absolute value) — ` +
+                    `no headless shell configured, and Google Chrome.app headless aborts in-session ` +
+                    `(${MUSE_CHROME_APP_ABORT}); see ${MUSE_VISUAL_QA_DOC}`,
+            };
+        }
+        if (!exists(configured)) {
+            return {
+                usable: false,
+                binary: null,
+                args: [],
+                reason: `headless shell not found at ${MUSE_HEADLESS_SHELL_BIN_ENV} (${configured}) — ` +
+                    `no screenshot path is installed, and Google Chrome.app headless aborts in-session ` +
+                    `(${MUSE_CHROME_APP_ABORT}); see ${MUSE_VISUAL_QA_DOC}`,
+            };
+        }
+        return {
+            usable: true,
+            binary: configured,
+            args: ["--screenshot=<png>", "--window-size=1280,800"],
+            reason: `pre-installed headless shell at ${configured}`,
+        };
+    }
+    return {
+        usable: false,
+        binary: null,
+        args: [],
+        reason: `no headless shell installed (${MUSE_HEADLESS_SHELL_BIN_ENV} is unset — it must be ` +
+            `pre-installed on the host because the developer sandbox network is restricted), and ` +
+            `Google Chrome.app headless aborts in-session (${MUSE_CHROME_APP_ABORT}); ` +
+            `see ${MUSE_VISUAL_QA_DOC}`,
+    };
+}
+function chromeAppWarningLines() {
+    return [
+        `- Never launch \`Google Chrome.app\` headless here: every launch aborts at startup`,
+        `  (${MUSE_CHROME_APP_ABORT}, no output, no file) under the Muse sandbox.`,
+        `  \`--no-sandbox\` only disables Chrome's own sandbox and cannot help.`,
+    ];
+}
+/**
+ * Worker-prompt section for a Muse developer session. The unusable variant tells
+ * the worker not to burn steps probing and to close with an explicit
+ * `Visual QA: not run` conclusion line, so review evidence states it instead of
+ * reading a missing screenshot as a pass.
+ */
+export function museVisualQaPromptSection(status) {
+    if (status.usable && status.binary) {
+        return [
+            `## Visual QA (screenshots)`,
+            `A pre-installed headless shell is available: \`${status.binary}\`. For UI-visible`,
+            `changes, capture a screenshot with`,
+            `\`${status.binary} ${[...status.args, "<page-url>"].join(" ")}\``,
+            `saving the PNG into the worktree, and commit it with your change.`,
+            ...chromeAppWarningLines(),
+            `End your implementation conclusion with a \`Visual QA:\` line —`,
+            `\`Visual QA: verified (<png path>, exit <code>)\` or \`Visual QA: not run (<reason>)\`.`,
+            ``,
+        ];
+    }
+    return [
+        `## Visual QA (screenshots)`,
+        `Headless visual QA does not work inside this session — do not spend steps probing it:`,
+        ...chromeAppWarningLines(),
+        `- ${status.reason}`,
+        `Visual QA is out of scope for this session: never read the absence of a screenshot as`,
+        `a pass. End your implementation conclusion with a \`Visual QA:\` line —`,
+        `\`Visual QA: not run (<short reason>)\` — so the review evidence states it explicitly.`,
+        ``,
+    ];
+}

package/bundle/server/dist/adapters/muse-visual-qa.test.js

@@ -0,0 +1,68 @@
+// packages/server/src/adapters/muse-visual-qa.test.ts
+//
+// NOT-303: the Muse Dev screenshot-path preflight. The unusable verdict must fail
+// loudly — naming the RegisterApplication abort and the missing binary — instead
+// of letting the worker discover it mid-session.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { checkMuseVisualQa, MUSE_HEADLESS_SHELL_BIN_ENV, museVisualQaPromptSection, } from "./muse-visual-qa.js";
+test("unset override: unusable, naming the Chrome.app abort and the missing binary", () => {
+    const status = checkMuseVisualQa({ env: {}, exists: () => false });
+    assert.equal(status.usable, false);
+    assert.equal(status.binary, null);
+    assert.match(status.reason, /RegisterApplication/);
+    assert.match(status.reason, /MUSE_HEADLESS_SHELL_BIN/);
+});
+test("configured but absent binary: unusable, naming the path", () => {
+    const status = checkMuseVisualQa({
+        env: { [MUSE_HEADLESS_SHELL_BIN_ENV]: "/opt/headless/chrome-headless-shell" },
+        exists: () => false,
+    });
+    assert.equal(status.usable, false);
+    assert.equal(status.binary, null);
+    assert.match(status.reason, /\/opt\/headless\/chrome-headless-shell/);
+    assert.match(status.reason, /RegisterApplication/);
+});
+test("configured but non-absolute value: unusable, not treated as a binary", () => {
+    const status = checkMuseVisualQa({
+        env: { [MUSE_HEADLESS_SHELL_BIN_ENV]: "relative/bin" },
+        exists: () => true,
+    });
+    assert.equal(status.usable, false);
+    assert.equal(status.binary, null);
+    assert.match(status.reason, /absolute path/);
+});
+test("pre-installed binary present: usable with binary and screenshot flags", () => {
+    const status = checkMuseVisualQa({
+        env: { [MUSE_HEADLESS_SHELL_BIN_ENV]: "/opt/headless/chrome-headless-shell" },
+        exists: (p) => p === "/opt/headless/chrome-headless-shell",
+    });
+    assert.equal(status.usable, true);
+    assert.equal(status.binary, "/opt/headless/chrome-headless-shell");
+    assert.ok(status.args.some((a) => a.startsWith("--screenshot=")));
+});
+test("unusable prompt section: forbids Chrome.app probing, declares out of scope, requires the conclusion line", () => {
+    const lines = museVisualQaPromptSection(checkMuseVisualQa({ env: {}, exists: () => false }));
+    const text = lines.join("\n");
+    assert.match(text, /## Visual QA/);
+    assert.match(text, /Google Chrome\.app/);
+    assert.match(text, /RegisterApplication/);
+    assert.match(text, /do not spend steps probing/i);
+    assert.match(text, /out of scope/i);
+    assert.match(text, /Visual QA: not run/);
+    assert.doesNotMatch(text, /--disable-sandbox/);
+    assert.doesNotMatch(text, /--yolo/);
+});
+test("usable prompt section: names the binary and still forbids Google Chrome.app", () => {
+    const lines = museVisualQaPromptSection({
+        usable: true,
+        binary: "/opt/headless/chrome-headless-shell",
+        args: ["--screenshot=<png>", "--window-size=1280,800"],
+        reason: "pre-installed headless shell",
+    });
+    const text = lines.join("\n");
+    assert.match(text, /\/opt\/headless\/chrome-headless-shell/);
+    assert.match(text, /--screenshot=<png>/);
+    assert.match(text, /Google Chrome\.app/);
+    assert.match(text, /Visual QA:/);
+});

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

@@ -91,6 +91,44 @@ export function hasFreshMuseCapacityPair(nowMs = Date.now()) {
 function museProbeDiagnosticLogPath() {
     return path.join(getDataDir(), "capacity", "muse-probe.log");
 }
+const MUSE_PROBE_FAILURE_MESSAGE_MAX = 300;
+const MUSE_PROBE_FAILURE_KIND_MAX = 100;
+/** Keep the diagnostic log one JSON object per line and free of anything
+ * beyond kind + message: strip control characters, then truncate. */
+function sanitizeFailureText(value, max) {
+    return value.replace(/[\x00-\x1f\x7f]/g, "").slice(0, max);
+}
+function failureDetailFromTurn(failure) {
+    if (!failure)
+        return null;
+    return {
+        kind: sanitizeFailureText(failure.kind, MUSE_PROBE_FAILURE_KIND_MAX),
+        message: sanitizeFailureText(failure.message, MUSE_PROBE_FAILURE_MESSAGE_MAX),
+    };
+}
+function failureDetailFromError(err) {
+    let message;
+    if (err instanceof Error) {
+        message = err.message;
+    }
+    else if (typeof err === "string") {
+        message = err;
+    }
+    else {
+        try {
+            message = JSON.stringify(err) ?? "unknown error";
+        }
+        catch {
+            message = "unknown error";
+        }
+    }
+    if (!message)
+        message = "unknown error";
+    return {
+        kind: "exception",
+        message: sanitizeFailureText(message, MUSE_PROBE_FAILURE_MESSAGE_MAX),
+    };
+}
 function appendMuseProbeDiagnostic(nowMs, result) {
     try {
         const file = museProbeDiagnosticLogPath();
@@ -134,6 +172,7 @@ export async function runMuseCapacityProbe(nowMs = Date.now(), opts = {}) {
                 admitted: false,
                 terminal: null,
                 failureKind: "unadmitted",
+                failureDetail: null,
                 windowsUpdated: [],
                 durationMs: Date.now() - startedRealMs,
             };
@@ -142,28 +181,33 @@ export async function runMuseCapacityProbe(nowMs = Date.now(), opts = {}) {
             await host.readUsage();
             const checkNowMs = Math.max(nowMs, Date.now());
             const ok = hasFreshMuseCapacityPair(checkNowMs);
+            const failureKind = ok
+                ? null
+                : turn.timedOut
+                    ? "timeout"
+                    : turn.failure !== null
+                        ? "turn_failed"
+                        : "no_windows";
             result = {
                 ok,
                 admitted: true,
                 terminal: turn.terminal,
-                failureKind: ok
-                    ? null
-                    : turn.timedOut
-                        ? "timeout"
-                        : turn.failure !== null
-                            ? "turn_failed"
-                            : "no_windows",
+                failureKind,
+                failureDetail: failureKind === "turn_failed" || failureKind === "timeout"
+                    ? failureDetailFromTurn(turn.failure)
+                    : null,
                 windowsUpdated: ok ? ["rolling_all_models", "weekly_all_models"] : [],
                 durationMs: Date.now() - startedRealMs,
             };
         }
     }
-    catch {
+    catch (err) {
         result = {
             ok: false,
             admitted: false,
             terminal: null,
             failureKind: "exception",
+            failureDetail: failureDetailFromError(err),
             windowsUpdated: [],
             durationMs: Date.now() - startedRealMs,
         };
@@ -173,7 +217,10 @@ export async function runMuseCapacityProbe(nowMs = Date.now(), opts = {}) {
             await host.shutdown().catch(() => undefined);
     }
     appendMuseProbeDiagnostic(nowMs, result);
-    const outcome = result.ok ? "ok" : `failed: ${result.failureKind ?? "unknown"}`;
+    const detail = result.failureDetail !== null
+        ? ` (${result.failureDetail.kind}: ${result.failureDetail.message})`
+        : "";
+    const outcome = result.ok ? "ok" : `failed: ${result.failureKind ?? "unknown"}${detail}`;
     console.error(`[muse-capacity] fallback ${outcome}`);
     return result;
 }

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

@@ -6,10 +6,11 @@ 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-probe-"));
+import { MUSE_CODE_CONTRIBUTOR_MODEL } from "@agent-dealer/shared";
 import { MuseCapacityHost } from "./muse-host.js";
 import { hasFreshMuseCapacityPair, isMusePaidFallbackEnabled, maybeProbeMuseCapacity, MUSE_CAPACITY_PROBE_SERVE_ARGV, MUSE_CAPACITY_REFRESH_ENV, resetMuseCapacityProbeStateForTests, runMuseCapacityProbe, } from "./muse-probe.js";
 import { ingestMuseUsagePayload } from "./muse.js";
-const { migrate } = await import("../db/index.js");
+const { migrate, getDataDir } = await import("../db/index.js");
 const { createAgent } = await import("../repository/agents.js");
 const { clearAllCapacitySnapshots, listCapacitySnapshots } = await import("../repository/runtime-capacity.js");
 const FAKE = new URL("./fixtures/fake-muse-serve.mjs", import.meta.url).pathname;
@@ -181,3 +182,189 @@ test("direct probe success requires the complete pair", async () => {
         await host.shutdown();
     }
 });
+// NOT-300: the probe log must explain the next failure. A stub host drives
+// runMuseServeTurn to the exact turn outcome — no live model call.
+function stubProbeHost(opts = {}) {
+    const sessionId = "sess-stub-1";
+    const session = { sessionId, modelId: MUSE_CODE_CONTRIBUTOR_MODEL };
+    let notifications = 0;
+    return {
+        ensureStarted: async () => {
+            if (opts.failStart)
+                throw opts.failStart;
+            return true;
+        },
+        execRequest: async (_id, method) => {
+            if (method === "session/start")
+                return { result: { session } };
+            if (method === "turn/start")
+                return { result: { turnId: "turn-stub-1" } };
+            if (method === "session/read") {
+                return { result: { session, history: { items: [] } } };
+            }
+            return { result: {} };
+        },
+        waitForHostNotification: async () => {
+            notifications += 1;
+            if (opts.hangTurnMs !== undefined && notifications === 1) {
+                await new Promise((r) => setTimeout(r, opts.hangTurnMs));
+                return null;
+            }
+            if (opts.turnParams !== undefined || opts.hangTurnMs === undefined) {
+                return {
+                    method: "turn/completed",
+                    params: opts.turnParams ??
+                        {
+                            sessionId,
+                            terminal: "failed",
+                            error: { kind: "other", message: "boom" },
+                            durationMs: 982,
+                        },
+                };
+            }
+            return {
+                method: "turn/completed",
+                params: { sessionId, terminal: "cancelled", reason: "cancel requested" },
+            };
+        },
+        isConnected: () => true,
+        cancelExecTurn: async () => { },
+        readUsage: async () => ({ ok: false, reason: "missing" }),
+        shutdown: async () => { },
+    };
+}
+function probeLogPath() {
+    return path.join(getDataDir(), "capacity", "muse-probe.log");
+}
+function probeLogSize() {
+    return fs.existsSync(probeLogPath()) ? fs.statSync(probeLogPath()).size : 0;
+}
+function probeLogLinesSince(bytes) {
+    const text = fs.existsSync(probeLogPath())
+        ? fs.readFileSync(probeLogPath(), "utf8").slice(bytes)
+        : "";
+    return text
+        .split("\n")
+        .filter((l) => l.trim())
+        .map((l) => JSON.parse(l));
+}
+const PROBE_LOG_ALLOWED_KEYS = [
+    "admitted",
+    "durationMs",
+    "event",
+    "failureDetail",
+    "failureKind",
+    "model",
+    "ok",
+    "terminal",
+    "trigger",
+    "ts",
+    "windowsUpdated",
+];
+function assertProbeLogShape(line) {
+    assert.deepEqual(Object.keys(line).sort(), [...PROBE_LOG_ALLOWED_KEYS].sort());
+    const detail = line.failureDetail;
+    if (detail !== null) {
+        assert.deepEqual(Object.keys(detail).sort(), ["kind", "message"]);
+    }
+    const raw = JSON.stringify(line);
+    for (const secret of ["Reply with exactly", "transcript", "META_API_KEY", "password"]) {
+        assert.ok(!raw.includes(secret), `log line leaks ${secret}`);
+    }
+}
+test("failed turn records failureDetail kind+message in the probe log", async () => {
+    const before = probeLogSize();
+    const stderr = [];
+    const origError = console.error;
+    console.error = (...args) => {
+        stderr.push(args.map(String).join(" "));
+    };
+    try {
+        const host = stubProbeHost();
+        const result = await runMuseCapacityProbe(Date.now(), { host, timeoutMs: 10_000 });
+        assert.equal(result.ok, false);
+        assert.equal(result.failureKind, "turn_failed");
+        assert.deepEqual(result.failureDetail, { kind: "other", message: "boom" });
+    }
+    finally {
+        console.error = origError;
+    }
+    assert.match(stderr.join("\n"), /fallback failed: turn_failed \(other: boom\)/);
+    const lines = probeLogLinesSince(before);
+    assert.equal(lines.length, 1);
+    assertProbeLogShape(lines[0]);
+    assert.equal(lines[0].failureKind, "turn_failed");
+    assert.deepEqual(lines[0].failureDetail, { kind: "other", message: "boom" });
+});
+test("thrown probe error records failureDetail with the error message", async () => {
+    const before = probeLogSize();
+    const host = stubProbeHost({ failStart: new Error("x") });
+    const result = await runMuseCapacityProbe(Date.now(), { host, timeoutMs: 10_000 });
+    assert.equal(result.ok, false);
+    assert.equal(result.failureKind, "exception");
+    assert.equal(result.failureDetail?.kind, "exception");
+    assert.ok(result.failureDetail?.message.includes("x"));
+    const lines = probeLogLinesSince(before);
+    assert.equal(lines.length, 1);
+    assertProbeLogShape(lines[0]);
+    assert.equal(lines[0].failureKind, "exception");
+    assert.ok(String(lines[0].failureDetail.message).includes("x"));
+});
+test("timed-out turn records the timeout failureDetail", async () => {
+    const before = probeLogSize();
+    const host = stubProbeHost({ hangTurnMs: 400 });
+    const result = await runMuseCapacityProbe(Date.now(), { host, timeoutMs: 200 });
+    assert.equal(result.ok, false);
+    assert.equal(result.failureKind, "timeout");
+    assert.deepEqual(result.failureDetail, {
+        kind: "other",
+        message: "turn timed out and was cancelled",
+    });
+    const lines = probeLogLinesSince(before);
+    assert.equal(lines.length, 1);
+    assertProbeLogShape(lines[0]);
+    assert.equal(lines[0].failureKind, "timeout");
+    assert.deepEqual(lines[0].failureDetail, result.failureDetail);
+});
+test("failureDetail message is truncated to 300 chars with controls stripped", async () => {
+    const before = probeLogSize();
+    const long = `AB\nCD\t${"x".repeat(1000)}\u0000\u001f END`;
+    const host = stubProbeHost({
+        turnParams: {
+            sessionId: "sess-stub-1",
+            terminal: "failed",
+            error: { kind: "other", message: long },
+            durationMs: 5,
+        },
+    });
+    const result = await runMuseCapacityProbe(Date.now(), { host, timeoutMs: 10_000 });
+    assert.equal(result.failureKind, "turn_failed");
+    const message = result.failureDetail?.message ?? "";
+    assert.equal(message.length, 300);
+    assert.ok(!/[\x00-\x1f\x7f]/.test(message));
+    assert.ok(message.startsWith("ABCD"));
+    const lines = probeLogLinesSince(before);
+    assert.equal(lines.length, 1);
+    assertProbeLogShape(lines[0]);
+    assert.equal(lines[0].failureDetail.message, message);
+});
+test("successful probe logs failureDetail null with existing fields unchanged", async () => {
+    const before = probeLogSize();
+    const host = new MuseCapacityHost(hostOpts("serve-turn-full"));
+    try {
+        const result = await runMuseCapacityProbe(Date.now(), { host, timeoutMs: 10_000 });
+        assert.equal(result.ok, true);
+        assert.equal(result.failureDetail, null);
+    }
+    finally {
+        await host.shutdown();
+    }
+    const lines = probeLogLinesSince(before);
+    assert.equal(lines.length, 1);
+    assertProbeLogShape(lines[0]);
+    assert.equal(lines[0].failureDetail, null);
+    assert.equal(lines[0].event, "muse_capacity_probe");
+    assert.equal(lines[0].trigger, "stale_60m");
+    assert.equal(lines[0].failureKind, null);
+    assert.equal(lines[0].ok, true);
+});

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

@@ -10,6 +10,7 @@
 import { admissionLimitOptions, getEffectiveMaxActiveIssues, getMaxActiveIssues, workerSpawnCeiling, } from "../repository/admission-settings.js";
 import { checkAgentDeckHealth } from "../adapters/agent-deck.js";
 import { healthForAgent } from "../adapters/agent-health.js";
+import { ensureMuseCapabilityEscalation } from "../adapters/muse-capability.js";
 import { getDb } from "../db/index.js";
 import { getAgent } from "../repository/agents.js";
 import { getIssue, listIssues } from "../repository/issues.js";
@@ -150,7 +151,19 @@ export async function checkRoleAgentHealthy(issue, role, ctx) {
     if (!agent)
         return { ok: false, reason: `${role} agent not found` };
     const check = healthChecker ?? ((a, r) => defaultAgentHealth(a, r, ctx.deckOnline));
-    return check(agent, role);
+    const result = await check(agent, role);
+    // NOT-308: a Muse verdict the gate cannot clear by itself (`missing`, or an exhausted
+    // `error`) must reach the operator as a human action on this issue — deduped per
+    // version and verdict kind, so repeated polls never pile up. Best-effort: escalation never fails health.
+    if (role === "developer" && agent.runtime === "muse_code") {
+        try {
+            ensureMuseCapabilityEscalation(issue.id);
+        }
+        catch {
+            // The gate already reported; a failed escalation must not flip it.
+        }
+    }
+    return result;
 }
 async function checkAgentsHealthy(issue, ctx) {
     // Admit always starts a developer round — do not require reviewer health yet (NOT-156).