agent-dealer 1.2.15 → 1.2.16

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

@@ -29,7 +29,13 @@ export function projectDeveloperRoute(route, currentStatus, round) {
                         : `Developer retrying (infra attempt) — ${route.reason}`,
                     events: ["worker.failed"],
                 },
-                effect: { kind: "enqueue", workItem: "developer", retryReason: route.reason },
+                effect: {
+                    kind: "enqueue",
+                    workItem: "developer",
+                    retryReason: route.reason,
+                    // NOT-368: mark the work item so a second high-confidence auth failure parks.
+                    ...(route.authTransientRetry ? { authTransientRetry: true } : {}),
+                },
                 advance: isCiRepair ? "ci" : "infra",
             };
         }
@@ -67,6 +73,9 @@ export function projectDeveloperRoute(route, currentStatus, round) {
                         ? { pushDivergence: route.pushDivergence }
                         : {}),
                     ...(route.blockerFingerprint ? { blockerFingerprint: route.blockerFingerprint } : {}),
+                    ...("runtimeAuthPark" in route && route.runtimeAuthPark
+                        ? { runtimeAuthPark: route.runtimeAuthPark }
+                        : {}),
                 },
                 advance: "none",
             };
@@ -140,7 +149,14 @@ export function projectReviewerRoute(route, round, hasVerdict) {
                     currentIntent: `Reviewer retrying (infra attempt) at ${route.headSha.slice(0, 8)} — ${route.reason}`,
                     events: ["worker.failed"],
                 },
-                effect: { kind: "enqueue", workItem: "reviewer", atHeadSha: route.headSha },
+                effect: {
+                    kind: "enqueue",
+                    workItem: "reviewer",
+                    atHeadSha: route.headSha,
+                    retryReason: route.reason,
+                    // NOT-368: mark the work item so a second high-confidence auth failure parks.
+                    ...(route.authTransientRetry ? { authTransientRetry: true } : {}),
+                },
                 advance: "infra",
                 hasVerdict,
             };
@@ -152,7 +168,14 @@ export function projectReviewerRoute(route, round, hasVerdict) {
                     currentIntent: route.reason,
                     events: [hasVerdict ? "worker.completed" : "worker.failed", ...verdictEvents],
                 },
-                effect: { kind: "human_action", actionType: route.actionType, reason: route.reason },
+                effect: {
+                    kind: "human_action",
+                    actionType: route.actionType,
+                    reason: route.reason,
+                    ...("runtimeAuthPark" in route && route.runtimeAuthPark
+                        ? { runtimeAuthPark: route.runtimeAuthPark }
+                        : {}),
+                },
                 advance: "none",
                 hasVerdict,
             };

package/bundle/server/dist/coordinator/projection.test.js

@@ -113,7 +113,14 @@ test("infra-class retries — including a stale re-review — spend the infra bu
     const reviewerRetry = projectReviewerRoute(routeReviewerOutcome({ kind: "publish_failed" }, REVIEW_ROUNDS_LEFT, PINNED_HEAD), 1, false);
     assert.equal(reviewerRetry.advance, "infra");
     // The infra retry re-pins the SAME head — it is not a "the head moved" stale re-review.
-    assert.deepStrictEqual(reviewerRetry.effect, { kind: "enqueue", workItem: "reviewer", atHeadSha: PINNED_HEAD });
+    // retryReason is threaded so the next reviewer session (and auth-transient marker) can
+    // show why this infra attempt was spent.
+    assert.deepStrictEqual(reviewerRetry.effect, {
+        kind: "enqueue",
+        workItem: "reviewer",
+        atHeadSha: PINNED_HEAD,
+        retryReason: "Review publication to GitHub failed.",
+    });
     // A stale re-review (the head genuinely moved) is also bounded on the infra budget —
     // an unbounded chain of these could otherwise spawn reviewer sessions indefinitely.
     const stale = projectReviewerRoute(routeReviewerOutcome({ kind: "stale", currentHeadSha: "new" }, REVIEW_ROUNDS_LEFT, PINNED_HEAD), 1, false);

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

@@ -1,6 +1,7 @@
 // packages/server/src/coordinator/routing.ts
 import { DEFAULT_MAX_CI_ATTEMPTS } from "@agent-dealer/shared";
 import { normalizeReviewerResult } from "./reviewer-result.js";
+import { authParkReason, MAX_CONSECUTIVE_AUTH_PARKS, repeatedAuthEscalationReason, } from "./runtime-auth-park.js";
 /** Default N for NOT-147: escalate empty-tip timeout/crash after this many failures (one auto-retry). */
 export const DEFAULT_NO_PROGRESS_INFRA_ATTEMPTS = 2;
 function roundsRemain(limits) {
@@ -148,6 +149,11 @@ export function routeDeveloperOutcome(outcome, limits) {
         case "timed_out": {
             // Same infra budget as above, plus NOT-147: empty tip after N timeout/crashes → human
             // gate so we do not burn attempts 3–4 on a branch that never moved.
+            // NOT-368: a high-confidence runtime auth failure with a still-failing (or already
+            // spent) probe parks for login remediation instead of charging infra.
+            const authPark = routeHighConfidenceAuthFailure(limits);
+            if (authPark)
+                return authPark;
             const reason = infraFailureReason(outcome);
             if (!infraAttemptsRemain(limits)) {
                 return {
@@ -217,6 +223,72 @@ function infraFailureReason(outcome) {
 function checksFailedDetails(outcome) {
     return outcome.details?.trim() ? outcome.details : "Developer's PR checks failed.";
 }
+/**
+ * NOT-368: high-confidence attributed auth failure → live-probe tie-breaker.
+ * Probe still failing (or the one transient retry already spent) → park with remediation,
+ * no infra charge. Probe passing on the first such failure → one infra retry. After
+ * {@link MAX_CONSECUTIVE_AUTH_PARKS} parks, the next confirmed failure escalates as a
+ * distinct "repeated login failures" policy_escalation (not another auth park).
+ * Medium / unattributed auth never sets `limits.authFailure`, so those stay on the
+ * generic infra-retry path below.
+ */
+function routeHighConfidenceAuthFailure(limits) {
+    const auth = limits.authFailure;
+    if (!auth || auth.confidence !== "high")
+        return null;
+    if (auth.consecutiveAuthParks >= MAX_CONSECUTIVE_AUTH_PARKS) {
+        return {
+            next: "human_action",
+            actionType: "policy_escalation",
+            reason: repeatedAuthEscalationReason({
+                runtime: auth.runtime,
+                remediation: auth.remediation,
+                rawCause: auth.rawCause,
+                priorParks: auth.consecutiveAuthParks,
+            }),
+        };
+    }
+    const shouldPark = auth.probeStillFailing || auth.authTransientRetrySpent;
+    if (shouldPark) {
+        const consecutivePark = auth.consecutiveAuthParks + 1;
+        return {
+            next: "human_action",
+            actionType: "policy_escalation",
+            reason: authParkReason({
+                runtime: auth.runtime,
+                remediation: auth.remediation,
+                rawCause: auth.rawCause,
+            }),
+            runtimeAuthPark: {
+                runtime: auth.runtime,
+                remediation: auth.remediation,
+                rawCause: auth.rawCause,
+                consecutivePark,
+            },
+        };
+    }
+    // Probe passed and the one transient retry is still available — charge infra like today.
+    if (!infraAttemptsRemain(limits)) {
+        return {
+            next: "human_action",
+            actionType: "policy_escalation",
+            reason: `${authParkReason({
+                runtime: auth.runtime,
+                remediation: auth.remediation,
+                rawCause: auth.rawCause,
+            })} (infra-attempt limit reached).`,
+        };
+    }
+    return {
+        next: "retry_developer",
+        reason: authParkReason({
+            runtime: auth.runtime,
+            remediation: auth.remediation,
+            rawCause: auth.rawCause,
+        }),
+        authTransientRetry: true,
+    };
+}
 /**
  * NOT-147: when a timeout/crash left the branch with zero commits ahead of base, stop
  * burning full agent spawns after N failures (default 2 = one auto-retry). Only trips when
@@ -254,6 +326,30 @@ export function routeReviewerOutcome(outcome, limits, pinnedHeadSha) {
         case "session_failed":
         case "deck_failure":
         case "publish_failed": {
+            // NOT-368: reviewer login deaths use the same auth-park tie-breaker as developers.
+            // Only session_failed carries auth (timed_out is folded into session_failed for reviewers).
+            if (outcome.kind === "session_failed") {
+                const authPark = routeHighConfidenceAuthFailure(limits);
+                if (authPark) {
+                    if (authPark.next === "human_action") {
+                        return {
+                            next: "human_action",
+                            actionType: authPark.actionType,
+                            reason: authPark.reason,
+                            ...("runtimeAuthPark" in authPark && authPark.runtimeAuthPark
+                                ? { runtimeAuthPark: authPark.runtimeAuthPark }
+                                : {}),
+                        };
+                    }
+                    // Transient auth retry → fresh reviewer at the pinned head (not a developer round).
+                    return {
+                        next: "retry_reviewer",
+                        headSha: pinnedHeadSha,
+                        reason: authPark.reason,
+                        ...(authPark.authTransientRetry ? { authTransientRetry: true } : {}),
+                    };
+                }
+            }
             const reason = outcome.kind === "deck_failure"
                 ? `Agent Deck ${outcome.reason}`
                 : outcome.kind === "session_failed"

package/bundle/server/dist/coordinator/routing.test.js

@@ -1,7 +1,36 @@
 // packages/server/src/coordinator/routing.test.ts
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLAUDE_AUTH_REMEDIATION, CODEX_AUTH_REMEDIATION, CURSOR_KEYCHAIN_REMEDIATION, MUSE_AUTH_REMEDIATION, runtimeAuthClassificationForLog, } from "@agent-dealer/shared";
 import { routeDeveloperOutcome, routeReviewerOutcome, } from "./routing.js";
+import { MAX_CONSECUTIVE_AUTH_PARKS } from "./runtime-auth-park.js";
+const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../shared/src/fixtures/runtime-auth");
+function fixtureText(name) {
+    return readFileSync(join(FIXTURE_DIR, name), "utf8");
+}
+/** NOT-114 keychain has no capture file — same reconstruction used by runtime-auth-health tests. */
+const CURSOR_KEYCHAIN_STDERR = `Cursor couldn't save your login to the macOS keychain (errSecDuplicateItem, security exit code 45).
+The keychain item is stuck. Delete it and sign in again:
+  security delete-generic-password -s cursor-access-token -a cursor-user
+  agent login
+`;
+function highConfAuthFromLog(runtime, logText, opts = {}) {
+    const classified = runtimeAuthClassificationForLog(logText, runtime);
+    assert.ok(classified, `expected auth classification for ${runtime}`);
+    assert.ok(classified.runtime, `expected attributed runtime for ${runtime}`);
+    return {
+        confidence: "high",
+        runtime: classified.runtime,
+        remediation: opts.remediation ?? classified.issue.message,
+        rawCause: logText.trim().slice(0, 500),
+        probeStillFailing: opts.probeStillFailing ?? true,
+        consecutiveAuthParks: opts.consecutiveAuthParks ?? 0,
+        authTransientRetrySpent: opts.authTransientRetrySpent ?? false,
+    };
+}
 const REVIEW_ROUNDS_LEFT = { currentRound: 1, maxReviewRounds: 3, infraAttempts: 0, maxInfraAttempts: 3 };
 const REVIEW_AT_LIMIT = { currentRound: 3, maxReviewRounds: 3, infraAttempts: 0, maxInfraAttempts: 3 };
 // NOT-313: CI-repair budget fixtures — infra counters stay at 0/3 throughout so
@@ -531,3 +560,137 @@ test("muse_cron_used escalates to the operator without spending any budget, even
         });
     }
 });
+// --- NOT-368: high-confidence runtime auth park (probe tie-breaker) ---
+const AUTH_PARK_CASES = [
+    {
+        runtime: "muse_code",
+        log: fixtureText("muse-exec-missing-credentials.txt"),
+        remediation: MUSE_AUTH_REMEDIATION,
+    },
+    {
+        runtime: "codex_local",
+        log: fixtureText("codex-exec-logged-out.txt"),
+        remediation: CODEX_AUTH_REMEDIATION,
+    },
+    {
+        runtime: "claude_code",
+        log: fixtureText("claude-print-logged-out.txt"),
+        remediation: CLAUDE_AUTH_REMEDIATION,
+    },
+    {
+        runtime: "cursor_local",
+        log: CURSOR_KEYCHAIN_STDERR,
+        remediation: CURSOR_KEYCHAIN_REMEDIATION,
+    },
+];
+test("NOT-368: high-confidence auth + probe still failing parks with remediation; infraAttempts unchanged", () => {
+    const infraBefore = INFRA_ATTEMPTS_LEFT.infraAttempts;
+    for (const { runtime, log, remediation } of AUTH_PARK_CASES) {
+        const authFailure = highConfAuthFromLog(runtime, log, { probeStillFailing: true });
+        const outcome = { kind: "session_failed", reason: log.trim().slice(0, 200) };
+        const result = routeDeveloperOutcome(outcome, { ...INFRA_ATTEMPTS_LEFT, authFailure });
+        assert.equal(result.next, "human_action", runtime);
+        assert.equal(result.actionType, "policy_escalation", runtime);
+        const reason = result.reason;
+        assert.match(reason, new RegExp(remediation.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), runtime);
+        assert.ok(result.runtimeAuthPark, runtime);
+        assert.equal(result.runtimeAuthPark.remediation, remediation, runtime);
+        // Routing never mutates limits — park means projection advance:none (no infra charge).
+        assert.equal(INFRA_ATTEMPTS_LEFT.infraAttempts, infraBefore, runtime);
+    }
+});
+test("NOT-368: high-confidence auth + probe passing takes one infra retry; second parks even when probe passes", () => {
+    const log = fixtureText("muse-exec-missing-credentials.txt");
+    const outcome = { kind: "session_failed", reason: "missing meta credentials" };
+    const first = routeDeveloperOutcome(outcome, {
+        ...INFRA_ATTEMPTS_LEFT,
+        authFailure: highConfAuthFromLog("muse_code", log, {
+            probeStillFailing: false,
+            authTransientRetrySpent: false,
+        }),
+    });
+    assert.equal(first.next, "retry_developer");
+    assert.equal(first.authTransientRetry, true);
+    // Projection would increment infraAttempts by exactly 1 on retry_developer (advance:infra).
+    const second = routeDeveloperOutcome(outcome, {
+        ...INFRA_ATTEMPTS_LEFT,
+        infraAttempts: INFRA_ATTEMPTS_LEFT.infraAttempts + 1,
+        authFailure: highConfAuthFromLog("muse_code", log, {
+            probeStillFailing: false,
+            authTransientRetrySpent: true,
+        }),
+    });
+    assert.equal(second.next, "human_action");
+    assert.equal(second.actionType, "policy_escalation");
+    assert.ok(second.runtimeAuthPark);
+    assert.match(second.reason, /muse login|META_API_KEY/i);
+});
+test("NOT-368: medium-confidence / unattributed auth keeps retry_developer and infra charge", () => {
+    // Shared "Not logged in" with no vendor anchor and no recorded runtime → medium cause;
+    // prepareAuthFailureRouting omits authFailure, so routing is unchanged from today.
+    const outcome = { kind: "session_failed", reason: "Not logged in" };
+    const result = routeDeveloperOutcome(outcome, INFRA_ATTEMPTS_LEFT);
+    assert.deepStrictEqual(result, {
+        next: "retry_developer",
+        reason: "Not logged in",
+    });
+});
+test("NOT-368: 4th consecutive confirmed auth park escalates as repeated login failures", () => {
+    const log = fixtureText("muse-exec-missing-credentials.txt");
+    const outcome = { kind: "session_failed", reason: "missing meta credentials" };
+    const result = routeDeveloperOutcome(outcome, {
+        ...INFRA_ATTEMPTS_LEFT,
+        authFailure: highConfAuthFromLog("muse_code", log, {
+            probeStillFailing: true,
+            consecutiveAuthParks: MAX_CONSECUTIVE_AUTH_PARKS,
+        }),
+    });
+    assert.equal(result.next, "human_action");
+    assert.equal(result.actionType, "policy_escalation");
+    assert.match(result.reason, /Repeated .* login failures/i);
+    assert.equal(result.runtimeAuthPark, undefined);
+});
+test("NOT-368: reviewer high-confidence auth + probe still failing parks with remediation (no infra retry)", () => {
+    for (const { runtime, log, remediation } of AUTH_PARK_CASES) {
+        const authFailure = highConfAuthFromLog(runtime, log, { probeStillFailing: true });
+        const outcome = { kind: "session_failed", reason: log.trim().slice(0, 200) };
+        const result = routeReviewerOutcome(outcome, { ...INFRA_ATTEMPTS_LEFT, authFailure }, PINNED_HEAD);
+        assert.equal(result.next, "human_action", runtime);
+        assert.equal(result.actionType, "policy_escalation", runtime);
+        assert.match(result.reason, new RegExp(remediation.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), runtime);
+        assert.ok(result.runtimeAuthPark, runtime);
+    }
+});
+test("NOT-368: reviewer high-confidence auth + probe passing takes one infra retry_reviewer; second parks", () => {
+    const log = fixtureText("muse-exec-missing-credentials.txt");
+    const outcome = { kind: "session_failed", reason: "missing meta credentials" };
+    const first = routeReviewerOutcome(outcome, {
+        ...INFRA_ATTEMPTS_LEFT,
+        authFailure: highConfAuthFromLog("muse_code", log, {
+            probeStillFailing: false,
+            authTransientRetrySpent: false,
+        }),
+    }, PINNED_HEAD);
+    assert.equal(first.next, "retry_reviewer");
+    assert.equal(first.headSha, PINNED_HEAD);
+    assert.equal(first.authTransientRetry, true);
+    const second = routeReviewerOutcome(outcome, {
+        ...INFRA_ATTEMPTS_LEFT,
+        infraAttempts: INFRA_ATTEMPTS_LEFT.infraAttempts + 1,
+        authFailure: highConfAuthFromLog("muse_code", log, {
+            probeStillFailing: false,
+            authTransientRetrySpent: true,
+        }),
+    }, PINNED_HEAD);
+    assert.equal(second.next, "human_action");
+    assert.ok(second.runtimeAuthPark);
+});
+test("NOT-368: reviewer medium-confidence / unattributed auth keeps retry_reviewer", () => {
+    const outcome = { kind: "session_failed", reason: "Not logged in" };
+    const result = routeReviewerOutcome(outcome, INFRA_ATTEMPTS_LEFT, PINNED_HEAD);
+    assert.deepStrictEqual(result, {
+        next: "retry_reviewer",
+        headSha: PINNED_HEAD,
+        reason: "Not logged in",
+    });
+});

package/bundle/server/dist/coordinator/runtime-auth-park.js

@@ -0,0 +1,97 @@
+import { CLAUDE_AUTH_REMEDIATION, CODEX_AUTH_REMEDIATION, CURSOR_AUTH_REMEDIATION, CURSOR_KEYCHAIN_REMEDIATION, MUSE_AUTH_REMEDIATION, RUNTIME_AUTH_LABEL, } from "@agent-dealer/shared";
+/** Cap on consecutive confirmed auth parks per issue before a distinct escalation. */
+export const MAX_CONSECUTIVE_AUTH_PARKS = 3;
+/** Evidence key on a policy_escalation raised for a confirmed runtime login failure. */
+export const RUNTIME_AUTH_PARK_EVIDENCE_KEY = "runtimeAuthPark";
+/** Work-item payload flag: this developer/reviewer retry spent the one transient auth retry. */
+export const AUTH_TRANSIENT_RETRY_PAYLOAD_KEY = "authTransientRetry";
+const REMEDIATION_BY_RUNTIME = {
+    cursor_local: CURSOR_AUTH_REMEDIATION,
+    codex_local: CODEX_AUTH_REMEDIATION,
+    claude_code: CLAUDE_AUTH_REMEDIATION,
+    muse_code: MUSE_AUTH_REMEDIATION,
+};
+/** True when the live auth probe still says the runtime cannot authenticate. */
+export function authProbeConfirmsFailure(issues) {
+    return issues.some((i) => i.code === "runtime_auth" || i.code === "cursor_keychain");
+}
+/**
+ * Prefer the probe's own remediation text when present; else the classified one.
+ *
+ * Exception (NOT-368 repair): a classified / parked Cursor keychain remediation must
+ * not be replaced by ordinary `runtime_auth` probe copy. `cursor-agent status` often
+ * reports a plain login failure while the stuck keychain still blocks `agent login` —
+ * swapping in generic login instructions tells the operator to do exactly what remains
+ * impossible. Only a probe that itself reports `cursor_keychain` may update that text.
+ */
+export function remediationFromProbe(issues, fallback) {
+    const keychainHit = issues.find((i) => i.code === "cursor_keychain");
+    if (keychainHit?.message?.trim())
+        return keychainHit.message;
+    if (fallback.trim() === CURSOR_KEYCHAIN_REMEDIATION) {
+        return fallback;
+    }
+    const authHit = issues.find((i) => i.code === "runtime_auth");
+    return authHit?.message?.trim() ? authHit.message : fallback;
+}
+export function defaultRemediationForRuntime(runtime, keychain = false) {
+    if (runtime === "cursor_local" && keychain)
+        return CURSOR_KEYCHAIN_REMEDIATION;
+    return REMEDIATION_BY_RUNTIME[runtime];
+}
+export function parseRuntimeAuthParkEvidence(evidenceJson) {
+    if (!evidenceJson)
+        return null;
+    try {
+        const parsed = JSON.parse(evidenceJson);
+        const raw = parsed[RUNTIME_AUTH_PARK_EVIDENCE_KEY];
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const ev = raw;
+        if ((ev.runtime !== "cursor_local" &&
+            ev.runtime !== "codex_local" &&
+            ev.runtime !== "claude_code" &&
+            ev.runtime !== "muse_code") ||
+            typeof ev.remediation !== "string" ||
+            typeof ev.rawCause !== "string" ||
+            typeof ev.consecutivePark !== "number") {
+            return null;
+        }
+        return {
+            runtime: ev.runtime,
+            remediation: ev.remediation,
+            rawCause: ev.rawCause,
+            consecutivePark: ev.consecutivePark,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isRuntimeAuthParkAction(action) {
+    return parseRuntimeAuthParkEvidence(action.evidenceJson) != null;
+}
+export function gateRuntimeAuthParkResume(opts) {
+    if (!opts.probeStillFailing)
+        return { proceed: true };
+    const remediation = opts.probeRemediation?.trim() || opts.evidence.remediation;
+    const label = RUNTIME_AUTH_LABEL[opts.evidence.runtime];
+    return {
+        proceed: false,
+        remediation,
+        message: `${label} is still not authenticated — ${remediation}`,
+    };
+}
+/** Operator-facing reason for a confirmed auth park (parks 1–3). */
+export function authParkReason(opts) {
+    const label = RUNTIME_AUTH_LABEL[opts.runtime];
+    return (`${label} is not logged in — ${opts.remediation}` +
+        (opts.rawCause.trim() ? `\n\nCause: ${opts.rawCause.trim()}` : ""));
+}
+/** Distinct escalation after MAX consecutive auth parks (the 4th confirmed failure). */
+export function repeatedAuthEscalationReason(opts) {
+    const label = RUNTIME_AUTH_LABEL[opts.runtime];
+    return (`Repeated ${label} login failures after ${opts.priorParks} parks — ` +
+        `fix authentication before resuming. ${opts.remediation}` +
+        (opts.rawCause.trim() ? `\n\nCause: ${opts.rawCause.trim()}` : ""));
+}

package/bundle/server/dist/coordinator/worker-loop.js

@@ -24,6 +24,7 @@ import { observeClockJump } from "./clock-jump.js";
 import { admitNext, checkRoleAgentHealthy } from "./admission.js";
 import { workerSessionPayload } from "./session-progress.js";
 import { runtimeAvailability } from "../repository/runtime-availability.js";
+import { runHeldWork } from "../power/host-awake-lifecycle.js";
 import { deferLeasedWorkItemForUsageCap, deferLeasedWorkItemForAgentUnhealthy, } from "./usage-cap-defer.js";
 import { outcomeShouldRecordError, reasonForWorkerFailedEvent } from "./failure-reason.js";
 import { checkAgentDeckHealth } from "../adapters/agent-deck.js";
@@ -123,10 +124,24 @@ function handleEffectFailure(itemId, leaseToken, error) {
         }
     })();
 }
+/** Test seam: replace the body inside the host-awake hold (lifecycle tests). */
+let processWorkItemHeldForTests = null;
+export function setProcessWorkItemHeldForTests(fn) {
+    processWorkItemHeldForTests = fn;
+}
 async function processWorkItem(claimed) {
     const leaseToken = claimed.leaseToken;
     if (!leaseToken)
         return; // not actually leased — defensive
+    // NOT-369: hold idle-sleep for the whole leased attempt (session + publish).
+    // runHeldWork releases on every outcome — clean exit, crash, timeout, kill.
+    await runHeldWork(() => (processWorkItemHeldForTests ?? processWorkItemHeld)(claimed, leaseToken));
+}
+/** Drive the real processWorkItem path from lifecycle tests (fake held body). */
+export async function processWorkItemForTests(claimed) {
+    await processWorkItem(claimed);
+}
+async function processWorkItemHeld(claimed, leaseToken) {
     const issue = getIssue(claimed.issueId);
     const instance = getWorkflowInstance(claimed.workflowInstanceId);
     if (!issue || !instance) {

package/bundle/server/dist/docs-host-awake.test.js

@@ -0,0 +1,16 @@
+// NOT-369: product docs describe the caffeinate hold, pmset advice, and limits.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const doc = fs.readFileSync(path.join(repoRoot, "docs/TROUBLESHOOTING.md"), "utf8");
+test("TROUBLESHOOTING documents caffeinate hold and pmset advice", () => {
+    assert.match(doc, /caffeinate/);
+    assert.match(doc, /pmset/);
+    assert.match(doc, /sudo pmset -c sleep 0/);
+    assert.match(doc, /Closing the lid/);
+    assert.match(doc, /Logging out/);
+    assert.match(doc, /NOT-369/);
+});

package/bundle/server/dist/index.js

@@ -19,6 +19,8 @@ import { runDeveloperEffect } from "./coordinator/developer-effect.js";
 import { runReviewerEffect } from "./coordinator/reviewer-effect.js";
 import { registerStaticUi } from "./static-ui.js";
 import { cleanupOrphanedWorkerMcpConfig } from "./paths.js";
+import { registerHostAwakeShutdownCleanup } from "./power/host-awake-lifecycle.js";
+import { ensureSleepTimerCheckedAtStartup } from "./power/sleep-timer.js";
 import net from "node:net";
 const { mode, envFile } = loadAgentDealerEnv();
 console.log(formatEnvStartupLine(mode, envFile));
@@ -59,6 +61,10 @@ async function main() {
             // Best-effort: shutdown must never block process exit.
         }
     };
+    // NOT-369: drop any idle-sleep assertion so a clean exit does not leave caffeinate behind.
+    // (caffeinate -w also dies if this process dies uncleanly.)
+    // Registered via the lifecycle seam so tests can emit SIGINT/SIGTERM/exit on a fake process.
+    registerHostAwakeShutdownCleanup(process);
     process.on("SIGINT", () => {
         removeServerPidFile();
         void shutdownCapacityHosts().finally(() => process.exit(0));
@@ -67,9 +73,16 @@ async function main() {
         removeServerPidFile();
         void shutdownCapacityHosts().finally(() => process.exit(0));
     });
-    process.on("exit", removeServerPidFile);
+    process.on("exit", () => {
+        removeServerPidFile();
+    });
     migrate();
     cleanupOrphanedWorkerMcpConfig();
+    // NOT-369: one-time AC sleep-timer advice (never changes settings; never sudo).
+    const sleepNotice = ensureSleepTimerCheckedAtStartup();
+    if (sleepNotice) {
+        console.warn(`[startup] ${sleepNotice.message}`);
+    }
     const app = Fastify({ logger: true });
     await app.register(cors, { origin: true });
     await registerRoutes(app);

package/bundle/server/dist/power/host-awake-lifecycle.js

@@ -0,0 +1,30 @@
+// NOT-369: production lifecycle seam for host-awake holds.
+//
+// Worker-loop / auto-merge call `runHeldWork`. Server startup calls
+// `registerHostAwakeShutdownCleanup`. Lifecycle tests drive those same
+// entry points (via processWorkItem / finalizeAutoMerge / a fake process)
+// so a removed finally or an unwired shutdown handler fails the suite.
+import { releaseAllHostAwake, withHostAwakeHold } from "./host-awake.js";
+/** Acquire → work → release. Used by worker-loop and auto-merge. */
+export async function runHeldWork(work) {
+    return withHostAwakeHold(work);
+}
+/**
+ * Register releaseAll on SIGINT, SIGTERM, and exit — the same events index.ts
+ * must cover so a clean server stop does not leave caffeinate behind.
+ * Returns the cleanup function (idempotent; safe to invoke more than once).
+ */
+export function registerHostAwakeShutdownCleanup(target = process) {
+    const cleanup = () => {
+        try {
+            releaseAllHostAwake();
+        }
+        catch {
+            // Best-effort — never block process exit.
+        }
+    };
+    target.on("SIGINT", cleanup);
+    target.on("SIGTERM", cleanup);
+    target.on("exit", cleanup);
+    return cleanup;
+}