agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/pid-marker.js

@@ -0,0 +1,141 @@
+// packages/server/src/pid-marker.ts
+//
+// A generic, path-parameterized exclusive pid marker: a JSON file naming the pid that
+// currently "owns" whatever it's guarding, claimed via an atomic exclusive create and
+// released only by its own owner. Two independent callers build on this:
+//
+//   - server-liveness.ts: the server's own entrypoint claims a marker at
+//     AGENT_DEALER_HOME/server.pid for its whole running lifetime.
+//   - db/migrate-to-issues.ts: the cutover script claims that SAME file for the duration
+//     of the migration, so a server trying to start concurrently sees the migration's own
+//     (live) pid as the current owner and refuses to start, and the migration's claim
+//     itself fails if a server is already running — the same primitive closes the race
+//     from both directions instead of one side merely observing the other's state.
+//
+// Kept path-parameterized (not bound to AGENT_DEALER_HOME/getDataDir()) so the migration
+// script — which operates on an arbitrary caller-supplied database path, not necessarily
+// this process's own AGENT_DEALER_HOME — can guard the directory the target database
+// actually lives in.
+import fs from "node:fs";
+import Database from "better-sqlite3";
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readRaw(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Whoever currently owns this marker, or null if the file is absent or unreadable.
+ * `alive` reflects a live process.kill(pid, 0) probe against the recorded pid — a
+ * present-but-stale marker (dead pid) still returns a result, with `alive: false`, so a
+ * caller can distinguish "nothing here" from "something here, but it's stale." */
+export function readPidMarkerOwner(filePath) {
+    const raw = readRaw(filePath);
+    if (!raw)
+        return null;
+    const pid = raw.pid;
+    if (typeof pid !== "number" || !Number.isFinite(pid) || pid <= 0)
+        return null;
+    return { pid, alive: isPidAlive(pid), raw };
+}
+/**
+ * Runs `fn` under a real OS-level advisory lock scoped to this marker, via a tiny
+ * dedicated SQLite file (`<filePath>.arbiter`) and a `BEGIN EXCLUSIVE` transaction —
+ * not a hand-rolled lock *file*, which would face the exact same "check it, decide it's
+ * stale, delete it, recreate it" race this exists to close, just one level further down
+ * (a prior version of this code tried exactly that with a `.reclaim-lock` file, and it
+ * had the identical bug: two processes could both observe the lock file as abandoned and
+ * both "steal" it, one destroying the other's fresh claim).
+ *
+ * SQLite's `BEGIN EXCLUSIVE` acquires a real filesystem advisory lock (fcntl/flock under
+ * the hood in rollback-journal mode) that a second connection's own `BEGIN EXCLUSIVE`
+ * genuinely blocks on — `busy_timeout` only bounds how long a live contender waits its
+ * turn. Critically, this sidesteps the entire "how do I tell a stale lock from a held one"
+ * problem: if the holding process dies for any reason (including a crash), the OS
+ * releases the underlying advisory lock immediately, so there is no lease/timeout
+ * heuristic to get wrong here at all.
+ */
+function withArbiterLock(filePath, fn) {
+    const db = new Database(`${filePath}.arbiter`);
+    try {
+        db.pragma("busy_timeout = 3000");
+        return db.transaction(fn).exclusive();
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Claims the marker for this process (process.pid), refusing only when a *different*,
+ * still-alive pid already holds it. A stale marker (dead pid, or unreadable content) is
+ * reclaimed rather than treated as a blocker — a crashed prior owner must never
+ * permanently wedge this lock. `extra` fields (e.g. `port`, `role`) are merged into the
+ * written state alongside `pid`/`startedAt`.
+ *
+ * The fast path (nobody home) is a single atomic exclusive create (`wx`), so two processes
+ * racing an *absent* marker cannot both believe they claimed it. Reclaiming a *stale*
+ * marker is different: "read it, decide it's dead, replace it" is not one atomic step on
+ * its own, so the decide-and-replace sequence runs under withArbiterLock — a real OS-level
+ * advisory lock, not a second hand-rolled lock file with the same race one level down.
+ */
+export function claimPidMarker(filePath, extra = {}) {
+    const state = { pid: process.pid, startedAt: new Date().toISOString(), ...extra };
+    const payload = JSON.stringify(state, null, 2);
+    try {
+        fs.writeFileSync(filePath, payload, { flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    const owner = readPidMarkerOwner(filePath);
+    if (owner && owner.pid !== process.pid && owner.alive) {
+        return false; // a different, live owner holds this marker — do not touch it
+    }
+    if (owner && owner.pid === process.pid) {
+        return true; // already ours (e.g. a re-entrant claim) — nothing to replace
+    }
+    // Stale (dead pid) or unreadable — the destructive replace happens under the arbiter
+    // lock, not on the strength of the read above alone.
+    return withArbiterLock(filePath, () => {
+        // Re-check under the lock: the marker may have been legitimately reclaimed by whoever
+        // held this lock just before us.
+        const ownerUnderLock = readPidMarkerOwner(filePath);
+        if (ownerUnderLock && ownerUnderLock.pid !== process.pid && ownerUnderLock.alive) {
+            return false;
+        }
+        // No `wx` here: holding the arbiter lock is what makes this replace exclusive, not the
+        // create flag — the destination may legitimately still exist (the stale file itself).
+        fs.writeFileSync(filePath, payload);
+        return true;
+    });
+}
+/** Releases the marker only if it currently names *this* process — never a different
+ * (possibly still-alive) owner's marker, including one this process never actually claimed
+ * because claimPidMarker() returned false for it. */
+export function releasePidMarker(filePath) {
+    const owner = readPidMarkerOwner(filePath);
+    if (!owner || owner.pid !== process.pid)
+        return;
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // already gone — fine on a second release call
+    }
+}

package/bundle/server/dist/pid-marker.test.js

@@ -0,0 +1,208 @@
+// packages/server/src/pid-marker.test.ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { claimPidMarker, releasePidMarker, readPidMarkerOwner } from "./pid-marker.js";
+import { resolveTsxBin } from "./resolve-tsx-bin.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const childScript = path.join(__dirname, "pid-marker-claim-child.ts");
+const holdArbiterScript = path.join(__dirname, "pid-marker-hold-arbiter-child.ts");
+const tsxBin = resolveTsxBin(path.resolve(__dirname, "..", "..", ".."));
+/** Resolves once the child has actually exited — killing it alone isn't enough to keep
+ * the test process from hanging afterward: an unresolved 'exit' event leaves the child's
+ * handle open, and node:test won't let the process exit while one is outstanding. */
+function waitForExit(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve();
+    return new Promise((resolve) => child.once("exit", () => resolve()));
+}
+function tempMarkerPath() {
+    return path.join(fs.mkdtempSync(path.join(os.tmpdir(), "dealer-pid-marker-")), "marker.json");
+}
+/** A genuinely alive, same-user child pid — safe to signal, unlike e.g. pid 1 (which is
+ * alive but throws EPERM rather than ESRCH for an unprivileged process.kill probe). */
+function spawnLiveChild() {
+    const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "ignore" });
+    return { pid: child.pid, kill: () => child.kill("SIGKILL") };
+}
+test("claimPidMarker claims an absent marker", () => {
+    const filePath = tempMarkerPath();
+    assert.equal(claimPidMarker(filePath), true);
+    const owner = readPidMarkerOwner(filePath);
+    assert.equal(owner?.pid, process.pid);
+    assert.equal(owner?.alive, true);
+});
+test("claimPidMarker stores extra fields alongside pid/startedAt", () => {
+    const filePath = tempMarkerPath();
+    claimPidMarker(filePath, { role: "migration", port: 1234 });
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    assert.equal(raw.role, "migration");
+    assert.equal(raw.port, 1234);
+    assert.equal(typeof raw.startedAt, "string");
+});
+test("claimPidMarker refuses a marker owned by a different, live pid — and does not touch it", () => {
+    const filePath = tempMarkerPath();
+    const other = spawnLiveChild();
+    try {
+        fs.writeFileSync(filePath, JSON.stringify({ pid: other.pid, startedAt: "x" }));
+        assert.equal(claimPidMarker(filePath), false);
+        const owner = readPidMarkerOwner(filePath);
+        assert.equal(owner?.pid, other.pid);
+        assert.equal(owner?.alive, true);
+    }
+    finally {
+        other.kill();
+    }
+});
+test("claimPidMarker reclaims a stale marker (dead pid)", () => {
+    const filePath = tempMarkerPath();
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999999, startedAt: "x" }));
+    assert.equal(claimPidMarker(filePath), true);
+    assert.equal(readPidMarkerOwner(filePath)?.pid, process.pid);
+});
+test("claimPidMarker reclaims unreadable/corrupt content", () => {
+    const filePath = tempMarkerPath();
+    fs.writeFileSync(filePath, "not json");
+    assert.equal(claimPidMarker(filePath), true);
+    assert.equal(readPidMarkerOwner(filePath)?.pid, process.pid);
+});
+test("releasePidMarker removes a marker this process owns", () => {
+    const filePath = tempMarkerPath();
+    claimPidMarker(filePath);
+    releasePidMarker(filePath);
+    assert.equal(fs.existsSync(filePath), false);
+});
+test("releasePidMarker never removes a marker owned by a different pid", () => {
+    const filePath = tempMarkerPath();
+    const other = spawnLiveChild();
+    try {
+        fs.writeFileSync(filePath, JSON.stringify({ pid: other.pid, startedAt: "x" }));
+        releasePidMarker(filePath);
+        assert.ok(fs.existsSync(filePath));
+        assert.equal(readPidMarkerOwner(filePath)?.pid, other.pid);
+    }
+    finally {
+        other.kill();
+    }
+});
+test("releasePidMarker on an absent file is a no-op", () => {
+    const filePath = tempMarkerPath();
+    assert.doesNotThrow(() => releasePidMarker(filePath));
+});
+test("readPidMarkerOwner distinguishes absent from stale", () => {
+    const filePath = tempMarkerPath();
+    assert.equal(readPidMarkerOwner(filePath), null);
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999999, startedAt: "x" }));
+    const owner = readPidMarkerOwner(filePath);
+    assert.equal(owner?.pid, 999999);
+    assert.equal(owner?.alive, false);
+});
+test("concurrent reclaim of the same stale marker: exactly one real process wins, never a corrupted mix of both", { timeout: 20000 }, () => {
+    // Real child processes, not an in-process simulation — a fake interleaving inside one
+    // JS event loop can't actually exercise the OS-level race between two independent
+    // processes both reading "stale", both deciding to reclaim, and both replacing the
+    // marker. Before the reclaim-lock fix, this reliably produced runs where more than one
+    // child reported claimed:true for the same marker.
+    const filePath = tempMarkerPath();
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999999, startedAt: "x" })); // stale
+    const N = 8;
+    const children = Array.from({ length: N }, () => spawn(tsxBin, [childScript, filePath], { stdio: ["ignore", "pipe", "inherit"] }));
+    // The winner(s) stay alive on purpose (see the helper script) — so wait for each
+    // child's single result line, not for the process to exit.
+    const firstLines = children.map((child) => new Promise((resolve) => {
+        let buf = "";
+        child.stdout.on("data", (d) => {
+            buf += d.toString();
+            const nl = buf.indexOf("\n");
+            if (nl !== -1)
+                resolve(buf.slice(0, nl));
+        });
+    }));
+    return Promise.all(firstLines)
+        .then((lines) => {
+        const results = lines.map((l) => JSON.parse(l));
+        const winners = results.filter((r) => r.claimed);
+        assert.equal(winners.length, 1, `expected exactly one winner, got: ${JSON.stringify(results)}`);
+        const finalOwner = readPidMarkerOwner(filePath);
+        assert.equal(finalOwner?.pid, winners[0].pid, "the file must name the one process that actually won");
+    })
+        .finally(() => {
+        // SIGTERM, not SIGKILL: the tsx launcher forwards SIGTERM to the real node process
+        // it forks to actually run the script before exiting; SIGKILL only kills the
+        // launcher itself (an unblockable signal it never gets to react to), orphaning
+        // that grandchild — which is exactly the live process holding server.pid's
+        // real-world equivalent open, so it (and this whole test process) would hang.
+        for (const child of children)
+            child.kill("SIGTERM");
+        return Promise.all(children.map(waitForExit));
+    });
+});
+test("the arbiter lock does not linger after a normal claim — a second claim proceeds immediately", () => {
+    const filePath = tempMarkerPath();
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999999, startedAt: "x" }));
+    claimPidMarker(filePath);
+    releasePidMarker(filePath);
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999998, startedAt: "x" }));
+    const start = Date.now();
+    assert.equal(claimPidMarker(filePath), true);
+    assert.ok(Date.now() - start < 500, "a second claim must not be blocked by a stale arbiter lock");
+});
+test("a process that crashes while holding the arbiter lock does not wedge it — the OS releases it, no lease timeout needed", { timeout: 20000 }, async () => {
+    // This is the regression the reviewer asked for: instead of a hand-rolled
+    // ".reclaim-lock" file with its own "is it stale" heuristic (which had the exact same
+    // check-then-delete race the main marker's reclaim did), the arbiter lock is a real
+    // OS-level advisory lock (via SQLite's BEGIN EXCLUSIVE) that the kernel releases the
+    // instant its holder dies, for any reason — including SIGKILL, simulating a crash
+    // mid-decision. Proves this empirically rather than by argument: hold the lock in a
+    // real child process, kill it, and confirm a subsequent claim succeeds promptly
+    // instead of waiting out the full busy_timeout (or hanging forever).
+    const filePath = tempMarkerPath();
+    fs.writeFileSync(filePath, JSON.stringify({ pid: 999999, startedAt: "x" })); // stale main marker
+    const holder = spawn(tsxBin, [holdArbiterScript, filePath], { stdio: ["ignore", "pipe", "inherit"] });
+    const realHolderPid = await new Promise((resolve) => {
+        let buf = "";
+        holder.stdout.on("data", (d) => {
+            buf += d.toString();
+            const nl = buf.indexOf("\n");
+            if (nl === -1)
+                return;
+            const msg = JSON.parse(buf.slice(0, nl));
+            resolve(msg.pid);
+        });
+    });
+    // Kill the *actual* process holding the lock, not the tsx launcher — see the helper
+    // script's comment for why those are different pids and why SIGKILL specifically
+    // (an unblockable signal the launcher cannot forward) has to target the real one.
+    process.kill(realHolderPid, "SIGKILL");
+    holder.kill("SIGTERM"); // clean up the launcher wrapper too
+    await waitForExit(holder);
+    const start = Date.now();
+    const claimed = claimPidMarker(filePath);
+    const elapsedMs = Date.now() - start;
+    assert.equal(claimed, true);
+    assert.equal(readPidMarkerOwner(filePath)?.pid, process.pid);
+    assert.ok(elapsedMs < 1000, `claim should succeed promptly once the OS releases the dead holder's lock, took ${elapsedMs}ms`);
+});
+test("sanity: the child helper script actually claims when run alone", async () => {
+    const filePath = tempMarkerPath();
+    const child = spawn(tsxBin, [childScript, filePath], { stdio: ["ignore", "pipe", "inherit"] });
+    await new Promise((resolve) => {
+        let buf = "";
+        child.stdout.on("data", (d) => {
+            buf += d.toString();
+            const nl = buf.indexOf("\n");
+            if (nl === -1)
+                return;
+            const parsed = JSON.parse(buf.slice(0, nl));
+            assert.equal(parsed.claimed, true);
+            assert.equal(readPidMarkerOwner(filePath)?.pid, parsed.pid);
+            resolve();
+        });
+    });
+    child.kill("SIGTERM"); // see the concurrent-reclaim test for why SIGTERM, not SIGKILL
+    await waitForExit(child);
+});

package/bundle/server/dist/queue/approve-deliver.js

@@ -1,9 +1,62 @@
-import { deliverOutboundDraft } from "../adapters/agent-deck.js";
+import { deliverOutboundDraft } from "../adapters/outbound-delivery.js";
 import { syncLinearForRun } from "../adapters/linear-sync.js";
-import { workspaceForRun } from "../runners/prompts.js";
-import { addArtifact, appendEvent, getRun, transitionRun, } from "../repository/runs.js";
-import { deliverInFlight, getPendingOutboundDraft, markOutboundDraftSent, patchPendingOutboundBody, revertOutboundDraftToPending, } from "../repository/outbound-drafts.js";
-import { scheduleReflect } from "./dispatcher.js";
+import { addArtifact, appendEvent, getRun, transitionRun } from "../repository/runs.js";
+import { deliverInFlight, getPendingOutboundDraft, markOutboundDraftSent, patchPendingOutboundBody, rejectPendingOutboundDrafts, revertOutboundDraftToPending, } from "../repository/outbound-drafts.js";
+import { createHumanAction, findOpenHumanActionForRun, getHumanAction, resolveHumanAction, } from "../repository/human-actions.js";
+import { scheduleReflect } from "./reflect-schedule.js";
+/** Who/what resolved a parked `outbound_delivery_interaction_required` action when
+ * `finalizeRunWithoutDelivery` auto-closes it — `resolveOutboundDeliveryAction`'s
+ * `retry_send` passes the real operator + "retry_send" through; every other caller (a plain
+ * caller with no operator identity) gets this generic marker. */
+const DEFAULT_ACTION_RESOLUTION = { resolvedBy: "system", choice: "resolved_via_approve" };
+/**
+ * Resolves a run's open `outbound_delivery_interaction_required` action, if any — a no-op
+ * otherwise. Any code path that terminalizes a run (finalize-on-success below, but also
+ * `resolveOutboundDeliveryAction`'s `reject`) must call this, or a
+ * parked action is left open forever: once the run leaves `review`, `resolveOutboundDeliveryAction`'s
+ * `retry_send` 400s on "Run must be in review" and there is no other way to close the item.
+ */
+export function resolveOpenDeliveryParkForRun(runId, actionResolution) {
+    const openAction = findOpenHumanActionForRun(runId, "outbound_delivery_interaction_required");
+    if (openAction) {
+        resolveHumanAction(openAction.id, actionResolution.resolvedBy, { choice: actionResolution.choice });
+    }
+}
+/**
+ * Finalizes a run that has no more delivery work to do (no pending draft, or the pending
+ * draft was just sent). Also auto-resolves any still-open `outbound_delivery_interaction_required`
+ * action for this run: an operator can clear a park either by resolving it directly
+ * (`retry_send`/`reject`) or by an approve path that finds nothing left to deliver — either
+ * must close the queue item, not just the run.
+ */
+function finalizeRunWithoutDelivery(runId, actionResolution = DEFAULT_ACTION_RESOLUTION) {
+    resolveOpenDeliveryParkForRun(runId, actionResolution);
+    const updated = transitionRun(runId, "done");
+    syncLinearForRun(updated, "done").catch((e) => console.error("[linear-sync] done:", e));
+    scheduleReflect(updated, { trigger: "approve" });
+    return updated;
+}
+/** Raises the one operator action this run's ambiguous-delivery blockage calls for — at most
+ * one open `outbound_delivery_interaction_required` action per run at a time (same idempotent
+ * re-raise convention as `product_scope_decision`'s `findOpenHumanAction`). Action type kept
+ * for existing parks even though the trigger is now ambiguous-only (NOT-106). */
+function parkOnAmbiguousDelivery(runId, draftArtifactId, toolCall, reason) {
+    const existing = findOpenHumanActionForRun(runId, "outbound_delivery_interaction_required");
+    if (existing)
+        return;
+    createHumanAction({
+        runId,
+        actionType: "outbound_delivery_interaction_required",
+        reason,
+        question: "Outbound delivery may have already reached the provider. Retry the send or reject the draft?",
+        evidence: { draftArtifactId, serviceId: toolCall.serviceName, toolName: toolCall.toolName },
+        responseOptions: [
+            { choice: "retry_send", label: "Retry send" },
+            { choice: "reject", label: "Reject draft" },
+        ],
+        requestId: null,
+    });
+}
 export async function approveRunWithDeliver(runId, deps) {
     const run = getRun(runId);
     if (!run)
@@ -29,48 +82,95 @@ export async function approveRunWithDeliver(runId, deps) {
         }
     }
     if (!pending) {
-        const updated = transitionRun(runId, "done");
-        syncLinearForRun(updated, "done").catch((e) => console.error("[linear-sync] done:", e));
-        scheduleReflect(updated, { trigger: "approve" });
-        return { ok: true, run: updated, delivered: false };
+        return { ok: true, run: finalizeRunWithoutDelivery(runId, deps?.actionResolution), delivered: false };
     }
     if (!run.deckId) {
         return { ok: false, code: 502, error: "No deck bound — cannot deliver outbound draft" };
     }
     const deliver = deps?.deliver ?? deliverOutboundDraft;
+    const draftArtifactId = pending.artifact.id;
+    const toolCall = pending.content.draft.toolCall;
+    const deckId = run.deckId;
     deliverInFlight.add(runId);
     try {
-        const claimed = markOutboundDraftSent(pending.artifact.id);
+        const claimed = markOutboundDraftSent(draftArtifactId);
         if (!claimed) {
             return { ok: false, code: 409, error: "Draft already sent or rejected" };
         }
-        let toolResult;
-        let permalink;
+        let result;
         try {
-            const result = await deliver(run.deckId, pending.content.draft.toolCall, {
-                workspaceRoot: workspaceForRun(run),
-            });
-            toolResult = result.toolResult;
-            permalink = result.permalink;
+            result = await deliver(deckId, toolCall);
         }
         catch (err) {
-            revertOutboundDraftToPending(pending.artifact.id);
-            const message = err instanceof Error ? err.message : String(err);
-            appendEvent(runId, "deliver_failed", { error: message });
-            return { ok: false, code: 502, error: message };
+            revertOutboundDraftToPending(draftArtifactId);
+            const reason = err instanceof Error ? err.message : String(err);
+            appendEvent(runId, "deliver_failed", { error: reason, errorCode: "DELIVERY_FAILED" });
+            return { ok: false, code: 502, error: reason, errorCode: "DELIVERY_FAILED" };
+        }
+        if (!result.ok) {
+            revertOutboundDraftToPending(draftArtifactId);
+            const errorCode = result.kind === "ambiguous" ? "AMBIGUOUS_RESULT" : "DELIVERY_FAILED";
+            appendEvent(runId, "deliver_failed", { error: result.reason, errorCode });
+            // Ambiguous timeout is never safe to silently bounded-retry (NOT-91) — it needs an
+            // explicit "retry send or reject" human decision.
+            if (result.kind === "ambiguous") {
+                parkOnAmbiguousDelivery(runId, draftArtifactId, toolCall, result.reason);
+            }
+            return { ok: false, code: 502, error: result.reason, errorCode };
         }
         addArtifact(runId, "send_receipt", {
-            draftArtifactId: pending.artifact.id,
+            draftArtifactId,
             sentAt: new Date().toISOString(),
-            toolResult: toolResult,
-            permalink,
+            toolResult: result.toolResult,
+            permalink: result.permalink,
         }, "system");
-        const updated = transitionRun(runId, "done");
-        syncLinearForRun(updated, "done").catch((e) => console.error("[linear-sync] done:", e));
-        scheduleReflect(updated, { trigger: "approve" });
-        return { ok: true, run: updated, delivered: true };
+        return { ok: true, run: finalizeRunWithoutDelivery(runId, deps?.actionResolution), delivered: true };
     }
     finally {
         deliverInFlight.delete(runId);
     }
 }
+/**
+ * Resolves an open `outbound_delivery_interaction_required` action — Run-scoped, so this
+ * (like NOT-94's `resolveReflectionInteractionAction`) never goes through
+ * `resolveHumanActionAndAdvance`, which assumes an Issue + workflow_instance.
+ *
+ * `reject` is always terminal: no provider call, action resolved immediately, run finalized
+ * without delivering.
+ *
+ * `retry_send` re-attempts delivery of the still-pending draft. The action is resolved only
+ * once that attempt actually *succeeds* — on any failure (ordinary infra, or another
+ * ambiguous result) the action is left open rather than resolved out from under the
+ * operator. `approveRunWithDeliver`'s own park dedup (`findOpenHumanActionForRun`) finds
+ * this same still-open action on a repeat ambiguous result and does not raise a second one.
+ */
+export async function resolveOutboundDeliveryAction(actionId, resolvedBy, choice, deps) {
+    const action = getHumanAction(actionId);
+    if (!action)
+        return { ok: false, code: 404, error: "Human action not found" };
+    if (action.actionType !== "outbound_delivery_interaction_required") {
+        return { ok: false, code: 400, error: `Action ${actionId} is not an outbound_delivery_interaction_required action` };
+    }
+    if (!action.runId)
+        return { ok: false, code: 500, error: "Human action has no run" };
+    if (action.status !== "open")
+        return { ok: false, code: 409, error: "Human action already resolved" };
+    if (choice !== "retry_send" && choice !== "reject") {
+        return { ok: false, code: 400, error: `Invalid choice "${choice}" for outbound_delivery_interaction_required` };
+    }
+    if (choice === "reject") {
+        resolveHumanAction(actionId, resolvedBy, { choice });
+        rejectPendingOutboundDrafts(action.runId);
+        const updated = finalizeRunWithoutDelivery(action.runId);
+        return { ok: true, runStatus: updated.status, delivered: false };
+    }
+    // retry_send — the draft is still pending; re-attempt under the run's deck header.
+    // actionResolution carries the real operator identity through to
+    // finalizeRunWithoutDelivery's auto-close on success.
+    const result = await approveRunWithDeliver(action.runId, { ...deps, actionResolution: { resolvedBy, choice } });
+    if (!result.ok) {
+        // Left open on purpose — see the doc comment above.
+        return { ok: false, code: result.code, error: result.error };
+    }
+    return { ok: true, runStatus: result.run.status, delivered: result.delivered };
+}

package/bundle/server/dist/queue/reflect-schedule.js

@@ -0,0 +1,25 @@
+import { checkAgentDeckHealth } from "../adapters/agent-deck.js";
+import { runReflect } from "../runners/reflect.js";
+const activeReflects = new Set();
+/** Fire-and-forget: post-review playbook reflect (D3 learning loop). */
+export function scheduleReflect(run, opts) {
+    if (!run.playbookId || !run.deckId)
+        return;
+    if (activeReflects.has(run.id))
+        return;
+    void (async () => {
+        const online = await checkAgentDeckHealth();
+        if (!online)
+            return;
+        activeReflects.add(run.id);
+        try {
+            await runReflect(run, opts);
+        }
+        catch (e) {
+            console.error("[reflect]", run.id, e);
+        }
+        finally {
+            activeReflects.delete(run.id);
+        }
+    })();
+}

package/bundle/server/dist/queue/result-qa.js

@@ -3,7 +3,7 @@ import { addArtifact, getRun } from "../repository/runs.js";
 import { hasPendingQaExchange, latestExecuteSessionId } from "../repository/result-qa.js";
 import { runQa } from "../runners/qa.js";
 const ASKABLE_STATUSES = new Set(["review", "done"]);
-const QA_RUNTIMES = new Set(["claude_code", "cursor_local"]);
+const QA_RUNTIMES = new Set(["claude_code", "cursor_local", "codex_local"]);
 /** Ask the run's agent about its finished result. Read-only; never changes run status. */
 export function askResultQuestion(runId, question, opts) {
     // An empty question would persist a result_qa artifact that ResultQaContent then