@claudexor/control-api 3.0.4 → 3.1.1

package/dist/daemon-server.js

@@ -8,7 +8,7 @@ import { safeArtifactPath, safeArtifactRoot } from "./artifact-paths.js";
 import { TERMINAL_STATES } from "./sse-shared.js";
 import { streamRunEvents } from "./run-events-stream.js";
 import { boundedArtifactText, outputReadyState, primaryOutput } from "./primary-output.js";
-import { controlWebEvidence, eventPayload, latestPlanProgress, readRunEvents, timelineEvents, } from "./run-timeline.js";
+import { controlWebEvidence, eventPayload, evidenceLevel, latestPlanProgress, readRunEvents, readRunEventsWithIntegrity, timelineEvents, } from "./run-timeline.js";
 import { projectSession, projectThread, projectTurn, turnRunCard } from "./thread-projection.js";
 import { chainThreadMutation, handleThreadTurnCreate, handleThreadTurnRetry, } from "./thread-turn-routes.js";
 import { assertThreadIdle, threadIdOfRun } from "./thread-mutation.js";
@@ -26,10 +26,11 @@ import { handleMaintenanceRoute } from "./maintenance-routes.js";
 import { handleResourceRoute } from "./resource-routes.js";
 import { handleArtifactServeRoute, listArtifacts, resolveProjectRoot, } from "./artifact-serve-routes.js";
 import { requiredGateSpecsFromTaskArtifact } from "./task-contract-gates.js";
-import { assertOnlyQueryParams, optionalBooleanQuery } from "./query.js";
-import { controlProblemError } from "./problem-response.js";
+import { assertOnlyQueryParams, optionalBooleanQuery, singleQuery } from "./query.js";
+import { lruGet, lruSet, parseRunListQuery, selectRunListPage, } from "./run-list.js";
+import { controlProblemError, normalizeRequestValidationError, revertRefusedProblem, thrownProblemCode, } from "./problem-response.js";
 import { handleSecurityRoute } from "./security-routes.js";
-import { PlanQuestionsArtifact, CouncilProjection, derivePlanReadiness, ControlAuthReadinessRefreshRequest, ControlAuthReadinessRefreshResponse, ControlProblem, AccessProfile, AgentCapabilityCatalog, ControlHarnessListResponse, ControlHarnessModelsResponse, ControlSetupJob, ControlSetupJobCreateRequest, ControlSetupJobEvent, ControlSetupJobSnapshot, isTerminalControlSetupJobState, ControlSetupJobListFilter, ControlSetupJobListResponse, ControlRunStartInfo, ControlQueuedRunInfo, ControlRunControlRequest, ControlRunControlResponse, ControlReviewerPanelEntry, ControlRunDetail, ControlRunListResponse, ControlRunSummary, ControlRunResult, ControlBudgetSnapshot, PaidBudget, ControlSettingsSnapshot, ControlSettingsUpdateRequest, ControlQuotaResponse, ControlCredentialProfilesResponse, ControlCredentialProfileCreateRequest, ControlCredentialProfileCreateResponse, ControlCredentialProfileUpdateRequest, ControlCredentialProfileUpdateResponse, ControlCredentialProfileDeleteResponse, ControlInteractionAnswerRequest, ControlInteractionAnswerResponse, ControlRunDecisionRequest, ControlRunDecisionResponse, ControlThreadCreateRequest, ControlThreadTurnRequest, ControlThreadUpdateRequest, ControlThreadDetail, ControlThreadListResponse, DecisionRecord, ModeKind, RoutingGoal, ReviewFinding, RunDeliveryState, RunFailure, RunTelemetry, StructuredOutputConformance, TaskContract, ProtectedPathApproval, isTerminalLifecycle, needsDecision, outcomeBanner, outcomeFactsFromFailure, TestCommandInvocation, WorkProduct, } from "@claudexor/schema";
+import { PlanQuestionsArtifact, CouncilProjection, derivePlanReadiness, ControlAuthReadinessRefreshRequest, ControlAuthReadinessRefreshResponse, ControlProblem, AccessProfile, AgentCapabilityCatalog, ControlHarnessListResponse, ControlHarnessModelsResponse, ControlSetupJob, ControlSetupJobCreateRequest, ControlSetupJobEvent, ControlSetupJobSnapshot, isTerminalControlSetupJobState, ControlSetupJobListFilter, ControlSetupJobListResponse, ControlRunStartInfo, ControlRunControlRequest, ControlRunControlResponse, ControlReviewerPanelEntry, ControlRunDetail, ControlRunListResponse, ControlRunSummary, ControlRunResult, ControlBudgetSnapshot, PaidBudget, ControlSettingsSnapshot, ControlSettingsUpdateRequest, ControlQuotaResponse, ControlCredentialProfilesResponse, ControlCredentialProfileCreateRequest, ControlCredentialProfileCreateResponse, ControlCredentialProfileUpdateRequest, ControlCredentialProfileUpdateResponse, ControlCredentialProfileDeleteResponse, ControlInteractionAnswerRequest, ControlInteractionAnswerResponse, ControlRunDecisionRequest, ControlRunDecisionResponse, ControlThreadCreateRequest, ControlThreadTurnRequest, ControlThreadUpdateRequest, ControlThreadDetail, ControlThreadListResponse, DecisionRecord, ModeKind, RoutingGoal, ReviewFinding, RunDeliveryState, RunFailure, RunTelemetry, StructuredOutputConformance, TaskContract, ProtectedPathApproval, isTerminalLifecycle, needsDecision, needsOperatorAttention, requiredActionsFor, outcomeBanner, outcomeFactsFromFailure, TestCommandInvocation, WorkProduct, } from "@claudexor/schema";
 import { resolveControlProtocol } from "./operation-catalog.js";
 import { assertNoInlineSecretValues, containsSecretLikeToken, errorCode, noProjectRepoRoot, nowIso, redactSecrets, sha256, } from "@claudexor/util";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
@@ -41,6 +42,13 @@ function setupEventProtocolError(message) {
         requiredActions: ["resnapshot"],
     });
 }
+function invalidRunCursor(message) {
+    return Object.assign(new Error(message), {
+        status: 400,
+        code: "invalid_run_event_cursor",
+        requiredActions: ["resnapshot"],
+    });
+}
 function finiteHttpStatus(error, fallback) {
     if (!error || typeof error !== "object" || !("status" in error))
         return fallback;
@@ -248,7 +256,11 @@ export class DaemonControlApiServer {
         return this.tokenMatches(m?.[1]?.trim());
     }
     requestError(res, err) {
-        this.problem(res, finiteHttpStatus(err, 400), err, "invalid_request", false, "bad request");
+        // QA-053: at the request boundary, project a raw ZodError into structured
+        // fieldErrors + a single-line human message (see normalizeRequestValidationError).
+        // Typed errors and non-Zod errors pass through unchanged.
+        const normalized = normalizeRequestValidationError(err);
+        this.problem(res, finiteHttpStatus(normalized, 400), normalized, "invalid_request", false, "bad request");
     }
     json(res, status, body, contentType = "application/json") {
         if (status >= 400 && contentType === "application/json") {
@@ -276,7 +288,25 @@ export class DaemonControlApiServer {
         }
         if (chunks.length === 0)
             return {};
-        const raw = Buffer.concat(chunks).toString("utf8").trim();
+        // QA-056: decode the complete byte body STRICTLY. `Buffer.toString("utf8")`
+        // is non-fatal — it silently replaces malformed bytes with U+FFFD, so an
+        // invalid octet (FF, a lone continuation byte, overlong/ truncated sequence)
+        // would slip through as a valid JS string and could pass Zod, the secret
+        // fence, idempotency hashing and a durable mutation storing a value that
+        // differs from the wire bytes. TextDecoder({fatal:true}) throws on any
+        // malformed byte; concatenating first keeps valid multibyte chars split
+        // across HTTP chunks intact.
+        let decoded;
+        try {
+            decoded = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+        }
+        catch {
+            throw Object.assign(new Error("request body must be valid UTF-8"), {
+                status: 400,
+                code: "invalid_encoding",
+            });
+        }
+        const raw = decoded.trim();
         if (!raw)
             return {};
         try {
@@ -287,12 +317,11 @@ export class DaemonControlApiServer {
         }
     }
     onRequest(req, res) {
-        let tracked;
-        tracked = this.handle(req, res)
+        const tracked = this.handle(req, res)
             .catch((err) => {
             try {
                 if (!res.headersSent) {
-                    this.problem(res, finiteHttpStatus(err, 500), err, "internal_error", false, "internal server error");
+                    this.problem(res, finiteHttpStatus(err, 500), err, thrownProblemCode(err), false, "internal server error");
                 }
                 else
                     res.end();
@@ -375,10 +404,7 @@ export class DaemonControlApiServer {
             }, req, res);
         }
         if (method === "GET" && path === "/runs") {
-            const runs = await this.opts.daemon.list();
-            return this.json(res, 200, ControlRunListResponse.parse({
-                runs: runs.map((r) => this.summarizeRunOrDiagnostic(r)),
-            }));
+            return this.handleRunList(url, res);
         }
         if (await handleRunRetryRoute({
             daemon: this.opts.daemon,
@@ -491,7 +517,7 @@ export class DaemonControlApiServer {
                 return this.json(res, 501, { error: "threads are not supported by this engine build" });
             const { threads, problems } = await svc();
             const runs = await this.opts.daemon.list();
-            const blocked = new Set(runs.filter((r) => this.runNeedsDecision(r)).map((r) => r.runId ?? r.id));
+            const blocked = new Set(runs.filter((r) => this.runNeedsAttention(r)).map((r) => r.runId ?? r.id));
             return this.json(res, 200, ControlThreadListResponse.parse({
                 threads: threads.map((t) => projectThread(t, blocked.has(t.head_run_id ?? ""))),
                 problems: problems ?? [],
@@ -517,7 +543,7 @@ export class DaemonControlApiServer {
                     }
                 }
                 const headRec = byRun.get(thread.head_run_id ?? "");
-                const headNeedsHuman = headRec ? this.runNeedsDecision(headRec) : false;
+                const headNeedsHuman = headRec ? this.runNeedsAttention(headRec) : false;
                 return this.json(res, 200, ControlThreadDetail.parse({
                     thread: projectThread(detail.thread, headNeedsHuman),
                     sessions: detail.sessions.map(projectSession),
@@ -584,6 +610,7 @@ export class DaemonControlApiServer {
         if (await handleArtifactServeRoute({
             findRun: (id) => this.findRun(id),
             resolveProjectRoot: (id) => resolveProjectRoot(this.opts.services?.listProjects, id),
+            resolveThreadWorkspace: (id) => this.resolveThreadWorkspace(id),
             json: (response, status, body) => this.json(response, status, body),
         }, method, path, res))
             return;
@@ -610,6 +637,20 @@ export class DaemonControlApiServer {
                 const decisionAction = body.action;
                 try {
                     return await this.chainRunMutation(rec, async () => {
+                        // D-16: a work_state veto (the model attested needs_input / incomplete)
+                        // is NON-OVERRIDABLE — a risk acceptance cannot supply missing input,
+                        // and the delivery gate refuses the override on that axis. Reject
+                        // accept_risk with a TYPED problem here instead of recording a false
+                        // "Apply is now available" ACK that the gate would then refuse.
+                        const workVeto = this.runWorkStateVeto(rec);
+                        if (workVeto) {
+                            return this.json(res, 409, {
+                                error: workVeto === "needs_input"
+                                    ? "run reported it needs more input; a risk override cannot supply the missing input — re-run with the input (rerun_with_feedback)"
+                                    : "run reported the work is incomplete; a risk override cannot finish it — re-run until it completes (rerun_with_feedback)",
+                                code: "work_state_needs_input",
+                            });
+                        }
                         // The override unblocks a NEEDS-DECISION run (review blocked /
                         // checks failed, D8); recording one elsewhere would claim an apply
                         // permission that does not exist.
@@ -650,7 +691,10 @@ export class DaemonControlApiServer {
                         return this.json(res, 200, ControlRunDecisionResponse.parse({
                             accepted: true,
                             status: "applied",
-                            message: `${decisionAction} recorded; apply is now permitted for this exact patch`,
+                            // Honest ACK (QA-032B): nothing is mutated at decision time. The
+                            // risk is accepted for this exact patch; Apply is now available
+                            // and a fresh final check runs just-in-time before any mutation.
+                            message: `${decisionAction} recorded for this exact patch; Apply is now available and will run a fresh final check before changing the project`,
                         }));
                     });
                 }
@@ -682,13 +726,23 @@ export class DaemonControlApiServer {
                             }
                             const revert = await revertInPlaceFromAnchor(repoRoot, result.revertAnchorId);
                             if (!revert.reverted) {
+                                // QA-051: emit a FULL ControlProblem. The raw workspace reason
+                                // concatenates a stable English explanation with locale-
+                                // dependent Git stderr; that vendor diagnostic must not BE the
+                                // semantic message. Present a stable English message + typed
+                                // reason code, and keep the redacted, bounded stderr as
+                                // context evidence the client can inspect deliberately.
+                                const problem = revertRefusedProblem(revert.reason, revert.reasonCode);
                                 appendRunAuditEvent(rec, "control.rejected", {
                                     decision: "revert_run",
-                                    reason: revert.reason ?? "revert refused",
+                                    reason: problem.context.reason,
+                                    detail: problem.context.detail,
                                 });
-                                throw Object.assign(new Error(revert.reason ?? "revert refused"), {
+                                throw Object.assign(new Error(problem.message), {
                                     status: 409,
                                     code: "revert_refused",
+                                    retryable: false,
+                                    context: problem.context,
                                 });
                             }
                             markRunApplyState(rec, "reverted");
@@ -874,7 +928,17 @@ export class DaemonControlApiServer {
         }
         const setupJobExtendMatch = /^\/setup\/jobs\/([^/]+)\/extend$/.exec(path);
         if (method === "POST" && setupJobExtendMatch) {
-            return this.service(res, "extendSetupJob", { jobId: decodeURIComponent(setupJobExtendMatch[1]) }, ControlSetupJob);
+            // QA-075/Ф2: Idempotency-Key is OPTIONAL (installed macOS Extend sends
+            // none): present → replay-safe, absent → non-idempotent, malformed → 400.
+            let idempotencyKey;
+            try {
+                idempotencyKey = runStart.optionalIdempotencyKey(req);
+            }
+            catch (err) {
+                return this.requestError(res, err);
+            }
+            const jobId = decodeURIComponent(setupJobExtendMatch[1]);
+            return this.service(res, "extendSetupJob", { jobId, ...(idempotencyKey !== undefined ? { idempotencyKey } : {}) }, ControlSetupJob);
         }
         const setupJobEventsMatch = /^\/setup\/jobs\/([^/]+)\/events$/.exec(path);
         if (method === "GET" && setupJobEventsMatch) {
@@ -988,7 +1052,15 @@ export class DaemonControlApiServer {
         const eventsMatch = /^\/runs\/([^/]+)\/events$/.exec(path);
         if (method === "GET" && eventsMatch) {
             const id = decodeURIComponent(eventsMatch[1]);
-            const last = this.lastEventId(req, url);
+            let last;
+            try {
+                last = this.lastEventId(req, url);
+            }
+            catch (err) {
+                // Validate the resume cursor BEFORE committing SSE headers so a
+                // malformed cursor is a typed 400, not a silent full replay (QA-061).
+                return this.requestError(res, err);
+            }
             return this.streamEvents(id, last, req, res);
         }
         return this.json(res, 404, { error: "not found" });
@@ -1003,7 +1075,7 @@ export class DaemonControlApiServer {
             value = await fn(arg);
         }
         catch (err) {
-            return this.problem(res, finiteHttpStatus(err, 500), err, "internal_error", false, "service failed");
+            return this.problem(res, finiteHttpStatus(err, 500), err, thrownProblemCode(err), false, "service failed");
         }
         try {
             return this.json(res, 200, schema ? schema.parse(value) : value);
@@ -1219,14 +1291,61 @@ export class DaemonControlApiServer {
                 runDir: rec.runDir,
             }));
         }
-        const status = TERMINAL_STATES.has(rec.state) ? 500 : 202;
-        const body = ControlQueuedRunInfo.parse({ jobId: rec.id, state: rec.state, error: rec.error });
+        const { status, body } = runStart.unboundRunStartResponse(rec, TERMINAL_STATES.has(rec.state));
         return this.json(res, status, body);
     }
     async findRun(id) {
         const runs = await this.opts.daemon.list();
         return runs.find((r) => r.id === id || r.runId === id) ?? null;
     }
+    /**
+     * GET /v2/runs (QA-052): a bounded, newest-first, keyset-paginated page of run
+     * summaries. Ordering, filtering, and slicing all happen on the raw daemon
+     * records BEFORE any summary is materialized, so the expensive per-run
+     * artifact fingerprint/projection work is bounded by `limit` (page size), not
+     * by the total retained-record count. `limit`/`state`/`cursor` are typed and
+     * strict — an unknown or malformed param is a typed 400, never silently
+     * ignored. The bare (unparametered) call is still valid and now returns the
+     * newest `RUN_LIST_DEFAULT_LIMIT` runs with `hasMore`/`nextCursor` to page the
+     * rest.
+     */
+    async handleRunList(url, res) {
+        let query;
+        try {
+            query = parseRunListQuery(url);
+        }
+        catch (error) {
+            return this.requestError(res, error);
+        }
+        const { page, hasMore, nextCursor } = selectRunListPage(await this.opts.daemon.list(), query);
+        return this.json(res, 200, ControlRunListResponse.parse({
+            runs: page.map((r) => this.summarizeRunOrDiagnostic(r)),
+            nextCursor,
+            hasMore,
+        }));
+    }
+    /** Resolve a thread's workspace record (mode + isolated worktree path) from the
+     * thread journal — the honest source for QA-038 isolated /produced resolution.
+     * Trashed/purged threads are retained by getThread (purge nulls worktree_path),
+     * so an isolated run's execution tree is diagnosable, never silently the live
+     * project. Absent service or an unknown thread ⇒ null (non-thread fallback). */
+    async resolveThreadWorkspace(threadId) {
+        const svc = this.opts.services?.threadDetail;
+        // No thread service / no workspace record ⇒ null (in-place / one-shot: live
+        // root is correct). A THROWN lookup is NOT swallowed to null: for a run bound
+        // to a thread that fails OPEN to the live project (QA-038), so it propagates
+        // and `resolveProducedRoot` fails CLOSED with a typed authority-unavailable.
+        if (!svc)
+            return null;
+        const { thread } = await svc(threadId);
+        const ws = thread?.workspace;
+        if (!ws)
+            return null;
+        return {
+            mode: ws.mode === "isolated" ? "isolated" : "in_place",
+            worktreePath: typeof ws.worktree_path === "string" && ws.worktree_path.trim() ? ws.worktree_path : null,
+        };
+    }
     operatorDecisionFor(rec) {
         return this.opts.services?.operatorDecision?.(rec.runId ?? rec.id, rec.params) ?? null;
     }
@@ -1237,16 +1356,40 @@ export class DaemonControlApiServer {
         const patch = readTextArtifact(rec, "final/patch.diff", false);
         return patch !== null && decision.patchSha256 === sha256(patch) ? decision : null;
     }
-    /** The needs-me / inbox signal (D8), via the ONE projection owner: a terminal
-     * run whose review is blocked or checks failed, with no valid operator
-     * decision recorded — the axes replacement for the ex state==="blocked". */
+    /** The RISK-OVERRIDABLE needs-decision signal: a terminal run whose review is
+     * blocked or checks failed, with no valid operator decision recorded. This is
+     * the gate for accept_risk / override_needs_human — a D-16 work_state veto is
+     * NOT included here (a risk override cannot supply missing input); see
+     * `runWorkStateVeto`. */
     runNeedsDecision(rec) {
         const arb = safeReadStructuredArtifact(rec, "arbitration/decision.yaml", DecisionRecord);
-        const facts = runOutcomeFacts(rec, arb, readFailure(rec));
+        const facts = runOutcomeFacts(rec, arb, readFailure(rec), winnerWorkStateFor(rec));
         if (!facts)
             return false;
         return needsDecision(facts, this.validOperatorDecisionFor(rec) !== null);
     }
+    /** The needs-me / inbox signal (D8): EITHER a risk-overridable needs-decision
+     * OR a non-overridable D-16 work_state needs-input veto. Inbox/head surfaces
+     * fold both so a needs_input run still surfaces as needing the operator. */
+    runNeedsAttention(rec) {
+        const arb = safeReadStructuredArtifact(rec, "arbitration/decision.yaml", DecisionRecord);
+        const facts = runOutcomeFacts(rec, arb, readFailure(rec), winnerWorkStateFor(rec));
+        if (!facts)
+            return false;
+        return needsOperatorAttention(facts, this.validOperatorDecisionFor(rec) !== null);
+    }
+    /** D-16: the non-overridable work_state veto on a succeeded run — the model
+     * attested it needs input / is incomplete. A risk override cannot resolve it,
+     * so the decision endpoint rejects accept_risk with a typed problem instead of
+     * a false "Apply is now available" ACK the delivery gate would then refuse. */
+    runWorkStateVeto(rec) {
+        const arb = safeReadStructuredArtifact(rec, "arbitration/decision.yaml", DecisionRecord);
+        const facts = runOutcomeFacts(rec, arb, readFailure(rec), winnerWorkStateFor(rec));
+        if (!facts || facts.lifecycle !== "succeeded")
+            return null;
+        const state = facts.work_state?.state;
+        return state === "needs_input" || state === "incomplete" ? state : null;
+    }
     recordOperatorDecision(rec, decision, idempotency) {
         const record = this.opts.services?.recordOperatorDecision;
         if (!record) {
@@ -1296,6 +1439,7 @@ export class DaemonControlApiServer {
             chainMutation: (record, work) => this.chainRunMutation(record, work),
             appendAudit: appendRunAuditEvent,
             markApplied: (record) => markRunApplyState(record, "applied"),
+            deliveredApplyState: (record) => controlRunResult(record).applyState,
         };
     }
     threadLifecycleRouteCtx() {
@@ -1339,17 +1483,24 @@ export class DaemonControlApiServer {
      * runs change only when their artifacts change, so summaries are cached on a
      * state+artifact-mtime fingerprint.
      */
+    static SUMMARY_CACHE_MAX = 1_000;
     summarizeRunCached(rec) {
         const fingerprint = summaryFingerprint(rec);
-        const hit = this.summaryCache.get(rec.id);
+        const hit = lruGet(this.summaryCache, rec.id);
         if (hit && hit.fingerprint === fingerprint)
             return hit.summary;
         const summary = summarizeRun(rec);
-        if (this.summaryCache.size > 1_000)
-            this.summaryCache.clear(); // bounded; repopulates on the next poll
-        this.summaryCache.set(rec.id, { fingerprint, summary });
+        // QA-052: LRU-bounded eviction (oldest entry drops) instead of the old
+        // wholesale clear at the guard, so a large retained set never pays a full
+        // cache rehydration wave.
+        lruSet(this.summaryCache, rec.id, { fingerprint, summary }, DaemonControlApiServer.SUMMARY_CACHE_MAX);
         return summary;
     }
+    /** Test-only observability: current summary-cache entry count. Proves QA-052
+     * LRU boundedness (the cache never grows past SUMMARY_CACHE_MAX). */
+    summaryCacheSizeForTests() {
+        return this.summaryCache.size;
+    }
     /**
      * Cached artifact projection + journal-backed waiting_on_user overlay. Pending
      * interactions are not part of the run artifact fingerprint, so they must
@@ -1378,12 +1529,30 @@ export class DaemonControlApiServer {
             });
         }
     }
+    /**
+     * Strict per-run SSE resume cursor (QA-061). The run cursor is the durable
+     * nonnegative integer event `seq` (ControlRunDetail.lastSeq). Mirrors the
+     * global/project/setup streams' typed contract instead of permissive
+     * `Number()` + fallback-0:
+     *   absent                -> 0 (intentional full replay)
+     *   canonical decimal 0+  -> that safe integer
+     *   present but invalid   -> typed HTTP 400 (before SSE headers)
+     * A present-but-invalid header is NOT silently erased in favour of the query
+     * alias; the header wins when present, the query is used only when it is absent.
+     */
     lastEventId(req, url) {
+        assertOnlyQueryParams(url, ["lastEventId"]);
         const rawHeader = req.headers["last-event-id"];
-        const headerId = rawHeader !== undefined ? Number(rawHeader) : Number.NaN;
-        const rawQuery = url.searchParams.get("lastEventId");
-        const queryId = rawQuery !== null ? Number(rawQuery) : Number.NaN;
-        return Number.isFinite(headerId) ? headerId : Number.isFinite(queryId) ? queryId : 0;
+        if (Array.isArray(rawHeader))
+            throw invalidRunCursor("Last-Event-ID may be specified only once");
+        const rawQuery = singleQuery(url, "lastEventId");
+        const raw = rawHeader !== undefined ? rawHeader : rawQuery;
+        if (raw === undefined)
+            return 0;
+        if (!/^(0|[1-9][0-9]*)$/.test(raw) || !Number.isSafeInteger(Number(raw))) {
+            throw invalidRunCursor("run event cursor must be a nonnegative integer event seq; refetch the run snapshot and resume from its lastSeq");
+        }
+        return Number(raw);
     }
     async streamEvents(id, lastEventId, req, res) {
         return streamRunEvents({
@@ -1459,8 +1628,23 @@ function appendRunAuditEvent(rec, type, payload) {
         /* audit append must not change control behavior */
     }
 }
+/**
+ * QA-052 observability: how many artifact-path probes the run-list fingerprinter
+ * has performed (each probe is a synchronous filesystem stat-family lookup). The
+ * single-parse test pattern (eventsParseCount) proves warm-list work is BOUNDED
+ * — by page size (only sliced records are fingerprinted) and, for terminal runs,
+ * by the one-probe short-circuit below (1 path instead of 12).
+ */
+let fingerprintProbeCount = 0;
+export function runListFingerprintProbeCountForTests() {
+    return fingerprintProbeCount;
+}
+export function resetRunListFingerprintProbeCountForTests() {
+    fingerprintProbeCount = 0;
+}
 function summaryFingerprint(rec) {
     const mtime = (rel) => {
+        fingerprintProbeCount++;
         if (!rec.runDir)
             return 0;
         const path = safeArtifactPath(rec.runDir, rel);
@@ -1473,11 +1657,22 @@ function summaryFingerprint(rec) {
             return 0;
         }
     };
+    const identity = [rec.state, paramsFingerprint(rec), rec.finishedAt ?? "", rec.error ?? ""];
+    // QA-052 terminal short-circuit: a TERMINAL run's every projected artifact
+    // (events.jsonl, arbitration, telemetry, failure, the final/* outputs,
+    // work_product) is written before the daemon marks the run terminal and never
+    // changes afterward. The SOLE post-terminal mutation is the delivery/apply
+    // overlay (final/delivery_state.yaml), which the apply/revert route is the one
+    // writer of [B7]. So a warm re-list of a terminal run fingerprints ONE path
+    // instead of twelve — the cheap probe still detects an apply/revert, and every
+    // other axis is frozen. Active (queued/running) runs keep the full
+    // artifact-mtime fingerprint because their events.jsonl and final/* land while
+    // the run is still live.
+    if (TERMINAL_STATES.has(rec.state)) {
+        return [...identity, mtime("final/delivery_state.yaml")].join("|");
+    }
     return [
-        rec.state,
-        paramsFingerprint(rec),
-        rec.finishedAt ?? "",
-        rec.error ?? "",
+        ...identity,
         mtime("events.jsonl"),
         mtime("arbitration/decision.yaml"),
         mtime("final/telemetry.yaml"),
@@ -1626,13 +1821,42 @@ function markRunApplyState(rec, state) {
  * lifecycle (a decision-less plan/readonly/crash terminal). Null while the run
  * is not terminal. Lives here as the ONE control-plane projection; surfaces
  * read `outcomeFacts`, never re-derive. */
-function runOutcomeFacts(rec, decision, failure) {
+function runOutcomeFacts(rec, decision, failure, 
+/** D-16: the winning read-only/plan attempt's work_state (from telemetry),
+ * folded into a DECISION-LESS terminal so a needs_input/incomplete ask
+ * carries its veto axis just like an arbitrated agent run. */
+workState = null) {
     if (!isTerminalLifecycle(rec.state))
         return null;
+    // Arbitrated runs already carry work_state on decision.facts (INV-116).
     if (decision)
         return decision.facts;
     const lifecycle = rec.state;
-    return outcomeFactsFromFailure(lifecycle, failure?.category);
+    const base = outcomeFactsFromFailure(lifecycle, failure?.category);
+    if (!workState || lifecycle !== "succeeded")
+        return base;
+    const vetoed = workState.state === "needs_input" || workState.state === "incomplete";
+    return {
+        ...base,
+        work_state: workState,
+        ...(vetoed
+            ? {
+                reason: base.reason ??
+                    (workState.state === "needs_input" ? "input_required" : "work_incomplete"),
+            }
+            : {}),
+    };
+}
+/** D-16: the winning attempt's work_state from a run's telemetry.yaml, used to
+ * fold the veto axis into a decision-less terminal's outcome facts. */
+function winnerWorkStateFor(rec) {
+    const telemetry = safeReadStructuredArtifact(rec, "final/telemetry.yaml", RunTelemetry);
+    if (!telemetry)
+        return null;
+    const winner = telemetry.final_attempt_id
+        ? telemetry.attempts.find((a) => a.attempt_id === telemetry.final_attempt_id)
+        : undefined;
+    return winner?.outcome.work_state ?? null;
 }
 function summarizeRun(rec, eventsSnapshot) {
     const p = paramsRecord(rec);
@@ -1725,8 +1949,14 @@ function summarizeRun(rec, eventsSnapshot) {
         outputReadyState: outputReadyState(rec, parsedMode.success ? parsedMode.data : null, readFailure(rec)),
         toolWarningsTotal: telemetry?.tool_warnings_total ?? 0,
         result: controlRunResult(rec),
-        outcomeFacts: runOutcomeFacts(rec, decision, readFailure(rec)),
+        outcomeFacts: runOutcomeFacts(rec, decision, readFailure(rec), telemetry?.final_attempt_id
+            ? (telemetry.attempts.find((a) => a.attempt_id === telemetry.final_attempt_id)?.outcome
+                .work_state ?? null)
+            : null),
         route: controlRoute(telemetry, p),
+        // QA-034: routing rationale projected verbatim from the engine telemetry —
+        // surfaces never reconstruct the order from prose.
+        routingRationale: telemetry?.routing_rationale ?? null,
         tests: requestTests ?? (contractTests?.length ? contractTests : undefined),
         createdAt: rec.createdAt,
         startedAt: rec.startedAt,
@@ -1776,7 +2006,9 @@ function detailFor(rec, pendingInteractions = [], cursor, operator = null) {
     // RunDetail perf (D15): parse events.jsonl ONCE per detail request and thread
     // the snapshot through every event-consuming projection (timeline, budget
     // fallback, plan progress) — before this each field re-parsed the whole log.
-    const events = rec.runDir ? readRunEvents(rec) : [];
+    const { events, integrity } = rec.runDir
+        ? readRunEventsWithIntegrity(rec)
+        : { events: [], integrity: undefined };
     const summary = summarizeRun(rec, events);
     // Non-null exactly when the run has an applyable patch — the authoritative
     // "something to apply" banner signal (a convergence patch may carry kind:patch
@@ -1794,8 +2026,8 @@ function detailFor(rec, pendingInteractions = [], cursor, operator = null) {
         lastSeq,
         artifacts: rec.runDir ? listArtifacts(rec.runDir) : [],
         primaryOutput: primaryOutput(rec, summary.mode, failure),
-        timeline: timelineEvents(rec, events),
-        budget: budgetSnapshot(rec, decision, events),
+        timeline: timelineEvents(rec, events, integrity),
+        budget: budgetSnapshot(rec, decision, events, integrity),
         finalSummary: boundedArtifactText(rec, "final/summary.md"),
         decision,
         operatorDecision: operatorDecisionRaw,
@@ -1812,8 +2044,13 @@ function detailFor(rec, pendingInteractions = [], cursor, operator = null) {
         // review artifacts; empty for single-envelope modes.
         candidates: rec.runDir ? candidatesFor(rec.runDir, decision) : [],
         // Live plan checklist: the winner's (else last) plan.progress items.
-        planProgress: latestPlanProgress(rec, decision?.winner ?? null, events),
+        planProgress: latestPlanProgress(rec, decision?.winner ?? null, events, integrity),
         failure,
+        // Minimal typed required-actions (GH #29) for a succeeded-but-blocked run,
+        // from the single status-projection owner: review-blocked / checks-failed /
+        // needs-decision / work_state needs_input, keyed to the same validated
+        // operator decision the needs-decision + apply gates consult.
+        requiredActions: requiredActionsFor(summary.outcomeFacts ?? null, operator !== null),
     });
 }
 function readTextArtifact(rec, relPath, redact = true) {
@@ -1837,8 +2074,44 @@ function parseAccessMaybe(value) {
     const parsed = AccessProfile.safeParse(value);
     return parsed.success ? parsed.data : undefined;
 }
+/**
+ * Pure subscription-VALUATION fold over a run's events (QA-023c/QA-017b),
+ * independent of the cash truth. The owner-locked ledger settles native-
+ * subscription work to cash $0 while accumulating its token valuation on
+ * `budget.cash.valuation_usd` (last-wins, cumulative). An UNKNOWN valuation (no
+ * usage ever reported — e.g. a Cursor draft) stays NULL and is never coerced to
+ * a fake $0. The legacy fallback for runs predating budget.cash is the summed
+ * `budget.observation` spend. Vendor token valuation is at best an estimate.
+ */
+export function budgetValuationFromEvents(events) {
+    let valuationUsd = null;
+    let observation = 0;
+    let sawObservation = false;
+    for (const ev of events) {
+        const payload = eventPayload(ev);
+        if (ev["type"] === "budget.cash") {
+            const val = payload["valuation_usd"];
+            if (typeof val === "number" && Number.isFinite(val))
+                valuationUsd = val;
+            continue;
+        }
+        if (ev["type"] === "budget.observation" && payload["kind"] === "spend") {
+            const usd = payload["usd"];
+            if (typeof usd === "number" && Number.isFinite(usd)) {
+                observation += usd;
+                sawObservation = true;
+            }
+        }
+    }
+    if (valuationUsd === null && sawObservation)
+        valuationUsd = observation;
+    return {
+        valuationUsd,
+        valuationKnowledge: valuationUsd === null ? "unknown" : "estimated",
+    };
+}
 /** Typed severity per event type — no string matching over event names. */
-function budgetSnapshot(rec, decision, eventsSnapshot) {
+function budgetSnapshot(rec, decision, eventsSnapshot, integrity) {
     const p = paramsRecord(rec);
     // The ENGINE-EFFECTIVE cap lives in the immutable contract (request input,
     // surface default, or the configured global per-run default); request params
@@ -1847,9 +2120,13 @@ function budgetSnapshot(rec, decision, eventsSnapshot) {
         .paid_budget;
     const paidBudget = PaidBudget.safeParse(p["paidBudget"]).data ??
         contractBudget ?? { kind: "unlimited" };
+    const evs = eventsSnapshot ?? readRunEvents(rec);
     let spendUsd = decision?.budget_summary?.spend_usd ?? null;
     let estimated = decision?.budget_summary?.estimated ?? false;
     let source = spendUsd === null ? "unknown" : "decision";
+    // Subscription VALUATION (QA-023c/QA-017b) beside cash — computed by the pure
+    // event fold so an UNKNOWN valuation stays null, never a fabricated $0.
+    const { valuationUsd, valuationKnowledge } = budgetValuationFromEvents(evs);
     if (spendUsd === null) {
         // The CASH truth for a decision-less run (plan/ask/explore — they never
         // write a decision record) is the ledger's own `budget.cash` disclosure:
@@ -1866,7 +2143,7 @@ function budgetSnapshot(rec, decision, eventsSnapshot) {
         let eventSpend = 0;
         let sawCost = false;
         let sawUsage = false;
-        for (const ev of eventsSnapshot ?? readRunEvents(rec)) {
+        for (const ev of evs) {
             const payload = eventPayload(ev);
             if (ev["type"] === "budget.cash") {
                 const cash = payload["cash_spend_usd"];
@@ -1921,7 +2198,20 @@ function budgetSnapshot(rec, decision, eventsSnapshot) {
     const remainingUsd = paidBudget.kind === "finite" && spendUsd !== null
         ? Math.max(0, paidBudget.maxUsd - spendUsd)
         : null;
-    return ControlBudgetSnapshot.parse({ paidBudget, spendUsd, remainingUsd, estimated, source });
+    // Disclose when the spend fallback read incomplete/unreadable canonical
+    // events (QA-074): a partial event set can silently drop a spend tick, so the
+    // projected spend must never present as clean when its evidence was not.
+    const evidence = integrity ? evidenceLevel(integrity) : "complete";
+    return ControlBudgetSnapshot.parse({
+        paidBudget,
+        spendUsd,
+        valuationUsd,
+        valuationKnowledge,
+        remainingUsd,
+        estimated,
+        source,
+        evidence,
+    });
 }
 function readStructured(text, ext, schema) {
     if (text === null)
@@ -1979,9 +2269,10 @@ function applyGateError(rec, patch, targetRepoRoot, operatorDecision, finalVerif
     });
 }
 function applyGateInputFor(rec, patch, targetRepoRoot, operatorDecision) {
+    const decision = safeReadStructuredArtifact(rec, "arbitration/decision.yaml", DecisionRecord);
     return {
         state: rec.state,
-        decision: safeReadStructuredArtifact(rec, "arbitration/decision.yaml", DecisionRecord),
+        decision,
         workProduct: safeReadStructuredArtifact(rec, "final/work_product.yaml", WorkProduct),
         patch,
         originalRepoRoot: runRepoRoot(rec),
@@ -1989,6 +2280,14 @@ function applyGateInputFor(rec, patch, targetRepoRoot, operatorDecision) {
         operatorDecision: operatorDecision
             ? { action: operatorDecision.action, patch_sha256: operatorDecision.patchSha256 }
             : null,
+        // Effective mutable delivery/apply state from the SAME owner that projects
+        // summary.result.applyState (delivery_state overlay → work_product snapshot):
+        // an already-applied / reverted run gets a terminal eligibility disposition
+        // instead of a stale "rerun a fresh check" (QA-021).
+        applyState: controlRunResult(rec).applyState,
+        // D-16 work_state veto (INV-116): thread the model-attested work outcome so
+        // the gate refuses a needs_input/incomplete winner even with a clean review.
+        workState: decision?.facts?.work_state ?? null,
     };
 }
 /**