@vostride/agent-qa-dashboard 0.1.21 → 0.2.2

package/dist/index.d.ts

@@ -1,43 +1,27 @@
-import { D as DashboardDatabase } from './index-ygQLgXzT.js';
-export { A as AppiumManager, C as ConfigManager, L as LiveExecutionEvent, R as RunRow, S as StepRow, T as TestFileInfo, a as TestFileManager, b as TestRunHandle, c as TestRunner, d as TestValidationError, e as TestValidationResult, f as createRouter, r as readJsonBody, s as startServer } from './index-ygQLgXzT.js';
-import { Reporter, SecretRedactor, SuiteDefinition, RunArtifactReporterContext, SuiteSummary, TestDefinition, StepResult, TestResult, RunSummary, HookResultEvent } from '@vostride/agent-qa-core';
-import 'node:http';
-import '@vostride/agent-qa-mcp';
+import { D as DashboardDatabase, E as ExecutionBackend, a as ExecuteOptions, P as PreflightOptions, A as AgentHost, b as PostProcessingRelay, L as LiveEditorAttachment } from './index-Ds4Lv4mT.js';
+export { c as AgentRegistryHandle, d as AppiumManager, C as ConfigFileInvalidError, e as ConfigManager, f as LIVE_EDITOR_SUPERSEDED_CLOSE_CODE, g as LIVE_EDITOR_UNKNOWN_SESSION_CLOSE_CODE, h as LiveEditorSubjects, M as MintLiveUrlInput, i as PostProcessingListener, R as RUN_SERVICE_ANALYSIS_TEMPLATE, j as RUN_SERVICE_ARTIFACT_TEMPLATE, k as RUN_SERVICE_DETAIL_TEMPLATE, l as RUN_SERVICE_EVENTS_TEMPLATE, m as RUN_SERVICE_EVIDENCE_TEMPLATE, n as RUN_SERVICE_LIVE_URL_TEMPLATE, o as RUN_SERVICE_MARKS_TEMPLATE, p as RUN_SERVICE_MARK_PREVIEW_TEMPLATE, q as RUN_SERVICE_OK_ROUTE, r as RUN_SERVICE_ROUTE_TABLE, s as RUN_SERVICE_START_ROUTE, t as ReplaceDocumentOutcome, u as ResumePoint, v as RunOwner, w as RunOwnerProbe, x as RunOwnerState, y as RunOwnership, z as RunOwnershipInput, B as RunRow, F as RunServicePorts, G as RunServiceRouteHandlerName, H as RunServiceRouteMatch, I as RunServiceRouteRow, J as RunServiceRouter, K as RunServiceStartInput, N as RunSettledDetails, O as RunSettledStatus, Q as RunsDatabaseVersionRefusedError, T as TestFileInfo, S as TestFileManager, U as TestValidationError, V as TestValidationResult, W as backstopServerError, X as classifyRunOwner, Y as completeRunOwnership, Z as createLiveEditorSubjects, _ as createPostProcessingRelay, $ as createRouter, a0 as createRunServiceRoutes, a1 as defaultRunOwnership, a2 as matchRunServiceRoute, a3 as orphanSummary, a4 as ownedElsewhere, a5 as ownsRunServicePath, a6 as readConfigValues, a7 as readJsonBody, a8 as refuseUnparseableRequest, a9 as runDenialOf, aa as serializeConfigWrite, ab as startServer, ac as tryParseRequestUrl } from './index-Ds4Lv4mT.js';
+import { RunAttributes } from '@vostride/agent-qa-core';
+import { RunEventEnvelope, RunArtifactConfigSnapshot, ArtifactRecord, RunArtifactTestSourceSnapshot, RunArtifactSuiteSourceSnapshot, RunArtifactTestsSourceSnapshot, RunSession, PostProcessingStatus, PostProcessingDisposition, RunId, RunDetailRows, RunsArtifactResult, RunDetailProjection, RunsArtifactInput, LiveViewSubjectRef, LiveUrlVerdict, LiveUrlRefusalReason, LiveStreamDeclaration, LiveStreamKind, RunsMarkOutcome } from '@vostride/agent-qa-schema';
+import { EventEmitter } from 'node:events';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import WebSocket from 'ws';
+import '@vostride/agent-qa-runner';
 import 'yaml';
-import 'node:events';
-import 'node:child_process';
 
-declare const SCHEMA_VERSION = 1;
+declare const SCHEMA_VERSION = 2;
 interface DashboardMigration {
     version: number;
     sql: string[];
 }
 declare const MIGRATIONS: DashboardMigration[];
 
-interface RunIdMigrationOptions {
-    dbPath: string;
-    screenshotsDir?: string;
-    videosDir?: string;
-    logger?: (message: string) => void;
-}
-interface RunIdMigrationResult {
-    migratedRunCount: number;
-    totalRunCount: number;
-    runIdMap: Record<string, string>;
-    preservedRunIds: string[];
-    updatedScreenshotRows: number;
-    updatedVideoRows: number;
-    renamedScreenshotDirs: Array<{
-        from: string;
-        to: string;
-    }>;
-    renamedVideoDirs: Array<{
-        from: string;
-        to: string;
-    }>;
-    missingArtifacts: string[];
-}
-declare function migrateWorkspaceRunIds({ dbPath, screenshotsDir, videosDir, logger, }: RunIdMigrationOptions): Promise<RunIdMigrationResult>;
+declare function createRunOwnerHostResolver({ platform, hostname, readPlatformUuid, readPidNamespace, }?: {
+    platform?: NodeJS.Platform;
+    hostname?: () => string;
+    readPlatformUuid?: () => string | undefined;
+    readPidNamespace?: () => string | undefined;
+}): () => string;
+declare const resolveRunOwnerHost: () => string;
 
 interface ResolveDashboardDbPathOptions {
     configDir: string;
@@ -45,56 +29,535 @@ interface ResolveDashboardDbPathOptions {
 }
 declare function resolveDashboardDbPath({ configDir, configuredDbPath, }: ResolveDashboardDbPathOptions): string;
 
-type ArtifactReporterContext = RunArtifactReporterContext;
-declare class DashboardReporter implements Reporter {
-    private db;
-    private artifactsDir;
-    private suiteRunId;
-    private currentSuiteId;
-    private runIdToState;
-    private executionKeyToRunId;
-    private nameToCurrentRunId;
-    private completedResultRunIds;
-    private runStartTime;
-    private onRunCreated?;
-    private redactor?;
-    constructor({ db, artifactsDir, onRunCreated, redactor, }: {
-        db: DashboardDatabase;
-        artifactsDir?: string;
-        onRunCreated?: (runId: string) => void;
-        redactor?: SecretRedactor;
-    });
-    private redactValue;
-    private redactString;
-    private sanitizeSecretsFileMetadata;
-    private sanitizeArtifactPayload;
-    private fallbackAttributes;
-    private readAttributesFromEnv;
-    private resolveAttributes;
-    private withAttributeMetadata;
-    onSuiteStart(suite: SuiteDefinition, context?: ArtifactReporterContext): void;
-    onSuiteEnd(summary: SuiteSummary): void;
-    onRunStart(_tests: TestDefinition[]): void;
-    onTestStart(test: TestDefinition, filePath: string, context?: ArtifactReporterContext): Promise<void>;
-    onStepEnd(result: StepResult, testName: string): Promise<void>;
-    onTestEnd(result: TestResult): Promise<void>;
-    onRunEnd(summary: RunSummary): void;
-    onHookEnd(event: HookResultEvent): void;
-    private getCurrentRunId;
-    private createExecutionKey;
-    private getStateByTestName;
-    private getStateForResult;
-    private deleteState;
-    private resultKey;
-    private buildResultErrorLog;
-    private writeArtifact;
-    private stageSuiteChildLink;
-    private stageSuiteSummary;
-    private buildSuiteMemoryAggregate;
-    private persistStep;
-    private saveScreenshot;
-    private saveHealingScreenshot;
-    private saveSubActionScreenshot;
+interface RunIdentityMember {
+    name: string;
+    testId: string;
+    filePath: string;
+    suiteId?: string;
+    suiteName?: string;
 }
+interface RunRowIdentity {
+    name: string;
+    testId?: string;
+    filePath?: string;
+    suiteId?: string;
+}
+declare function formatRunTitle(names: readonly string[]): string;
+declare function runRowIdentity(members: readonly RunIdentityMember[]): RunRowIdentity;
+
+/**
+ * `createDashboardRunIngest` — the dashboard's DB ingestion (RESEARCH Pitfall 1's
+ * "unnamed fifth consumer") rewired from the deleted `DashboardReporter` into a bus
+ * subscriber (Open Q-1 resolved as option (a): one envelope vocabulary, D-16 precedent).
+ *
+ * The bus deliberately does not carry the resolved config/source snapshots or the run's
+ * own id; those ride construction. Envelopes drive lifecycle/status.
+ * The `runs` + `run_artifacts` rows this writes stay shape-compatible with what
+ * `GET /api/runs/:id/artifact` and the queue read today — the spawn must survive
+ * until M5 (Pitfall 1's hard requirement). This module implements no Reporter
+ * interface — pure envelope consumption.
+ *
+ * NOTE: Plan 06 (363-06) relocated the `RunArtifact*` payload family from core to
+ * @vostride/agent-qa-schema (D-08); these imports now point at their canonical home.
+ *
+ * 2026-08-27 (Phase 405 plan 01, D-01/D-17/D-18): THE PROJECTION IS REBUILT ON THE BUS'S OWN
+ * SHAPE. Until this date every step landed in the v1 wide `steps` row through `insertStep`, which
+ * kept five of `StepFinalizedPayload`'s fields and dropped the rest — because the local `*Like`
+ * interfaces this module declared only named five. There was no `subActionRecorded` arm at all, so
+ * the sub-action timeline, the screenshots and the screen-state hashes reached no reader.
+ *
+ * What replaced them: the real schema payload types (so a field added to a payload is a compile
+ * error here rather than a silent drop), `run_members` per handle from `testStarted`/`testFinished`
+ * (D-18: a thin member whose stream begins with a terminal event still gets a row), `run_steps`
+ * carrying the WHOLE `stepFinalized` payload with `status` stored as the payload's own word, and
+ * `run_sub_actions` carrying the whole `subActionRecorded` payload with its nested objects
+ * stringified verbatim (no field is re-interpreted on the way in). The run row stores the verdict's
+ * own word too.
+ *
+ * `testRetryScheduled` now drops only THAT HANDLE's rows (D-17). It used to call the v1
+ * whole-run step delete, which wiped every step of the RUN — so in a suite, one member's
+ * abandoned attempt deleted the completed history of every member before it.
+ *
+ * THE NON-DARKENING `try {} catch {}` AROUND EVERY PROJECTION INSERT IS UNCHANGED and is
+ * load-bearing: a projection row that fails to write must never darken the `runs` row. A dropped
+ * step is visible as an absent step; a darkened run is a wrong verdict.
+ *
+ * 2026-08-28 (Phase 405 plan 13, D-21): phase 405 removed tables, columns, routes and fields from
+ * around this module and deliberately kept others. Check the repository history before restoring
+ * anything that looks missing here.
+ */
+type SourceSnapshot = RunArtifactTestSourceSnapshot | RunArtifactSuiteSourceSnapshot | RunArtifactTestsSourceSnapshot | ArtifactRecord;
+type ConfigSnapshot = RunArtifactConfigSnapshot | ArtifactRecord;
+/**
+ * A run's loaded test/suite and config snapshot, handed over by the producer that resolved them
+ * (433-29, G-433-5). It arrives out-of-band, like `finalize()`'s runtime: the bus carries no snapshots.
+ */
+interface DashboardRunIngestSnapshots {
+    config?: ConfigSnapshot;
+    source?: SourceSnapshot;
+}
+interface DashboardRunIngestDeps {
+    db: DashboardDatabase;
+    runId: string;
+    /** Resolved config snapshot (RunArtifactPayload-compatible) — the bus never carries it. */
+    configSnapshot?: ConfigSnapshot;
+    /** Resolved test/suite source snapshot — the bus never carries it. */
+    sourceSnapshot?: SourceSnapshot;
+    members?: readonly RunIdentityMember[];
+    /** Trusted run attributes, written to the run row + artifact metadata. */
+    attributes?: RunAttributes;
+    /** Fired once the primary DB row exists (log correlation / live-view wiring). */
+    onRunCreated?: (runId: string) => void;
+    /** Injectable clock for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * The post-run section the CLI closure supplies to `finalize()` — data the bus never carries,
+ * so it arrives out-of-band at flush.
+ *
+ * The v1 `memory` member is DELETED (407-05 · D-02). It was the last writer feeding the dead
+ * artifact-drawer memory tab, no producer in `packages/cli` or `packages/runner-local` has passed
+ * it since v1, and a field only a test could supply is a contract claiming a producer that does
+ * not exist. `runs.memory_log` has NO remaining production writer either (407-16 corrects 407-05's
+ * claim of a second writer): its insights reader is historical-only, reporting zeroes on every
+ * install created since, and its retirement belongs to the insights v1 sweep.
+ */
+interface DashboardRunIngestFinalizeExtra {
+    runtime?: ArtifactRecord;
+}
+interface DashboardRunIngest {
+    handler(envelope: RunEventEnvelope): void;
+    /**
+     * Stage a loaded snapshot onto this run's own artifact (433-29, F-433-15). A section is written
+     * only where it is absent or still the queue's `loadStatus: 'queued'` placeholder, so the first
+     * snapshot wins and a finalized artifact is never touched. A call before `runStarted` is held.
+     * A run of several members outside one suite instead files each snapshot under its member
+     * (444-03, D-07).
+     */
+    stageSnapshots(input: DashboardRunIngestSnapshots): void;
+    finalize(extra?: DashboardRunIngestFinalizeExtra): Promise<void>;
+}
+declare function createDashboardRunIngest(deps: DashboardRunIngestDeps): DashboardRunIngest;
+
+type InProcessRunStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'timeout';
+/** What the injected starter is handed: the request as data, and where to hand the session back. */
+interface InProcessRunStartInput {
+    readonly opts: ExecuteOptions;
+    /**
+     * Called with the started session, as early as the run door can name it.
+     *
+     * A run that is DENIED never calls this, and that asymmetry is load-bearing: it is the only way
+     * the backend can tell a policy refusal apart from a run that started and then failed.
+     *
+     * (Phrased without a quoted clause after the word `from`: `validate:arch`'s dependency scanner
+     * reads that shape as an import specifier and reported this comment as an undeclared external
+     * dependency of `packages/dashboard-server`.)
+     */
+    readonly onSession: (session: RunSession) => void;
+}
+/**
+ * Start one run and resolve when it is over.
+ *
+ * REJECTION IS NOT "the run failed" — a failing run resolves. A rejection is a denial, a refused
+ * request field, an input error or a crash, and its message is what the dashboard shows as the
+ * failure summary. That is the whole user-visible win of the retirement: on the retiring wire a
+ * policy denial and a run that never started were the same nothing.
+ */
+type InProcessRunStarter = (input: InProcessRunStartInput) => Promise<void>;
+interface InProcessExecutionBackendOptions {
+    /**
+     * How this backend actually starts a run.
+     *
+     * NAMED `invokeRun` AND NOT `startRun`, which is not a stylistic choice. `startRun` is the RUN
+     * SHELL's entry point in `@vostride/agent-qa-runner`, and `run-door-invocation-census.test.ts`
+     * makes a complete-set claim over the whole CLI package that no file acquires it — the one legal
+     * call site is inside the invocation core, one line below the one `evaluate()`. A second thing
+     * called `startRun`, in the CLI file that composes this option, REDS that census; and the census
+     * is right to red, because a second spelling of somebody else's symbol is exactly what it exists
+     * to refuse. `invokeRun` also says what this one does: it invokes the `runs.start` OP (D-10).
+     */
+    readonly invokeRun: InProcessRunStarter;
+    /**
+     * The host's pre-enqueue check, forwarded as `preflight` (433-34, G-433-10). It runs the run
+     * core's production rule over the request; a rejection carrying `neutralReason` is a denial.
+     */
+    readonly preflightRun?: (opts: PreflightOptions) => Promise<void>;
+    /** Applied when an `ExecuteOptions` carries no `timeout` of its own. */
+    readonly defaultTimeout?: number;
+    /** How long a settled run's handle survives before it is dropped. */
+    readonly retentionMs?: number;
+}
+/**
+ * The dashboard's in-process `ExecutionBackend`.
+ *
+ * A CLASS, matching the shape the interface already declared (`extends EventEmitter`), with a
+ * factory beside it so a composing host names a function rather than a constructor — nothing here
+ * is meant to be subclassed, and nothing needs the `resolveCliBin`-style static the retiring class
+ * carried for its binary.
+ */
+declare class InProcessExecutionBackend extends EventEmitter implements ExecutionBackend {
+    private readonly options;
+    private readonly handles;
+    private readonly retentionMs;
+    constructor(options: InProcessExecutionBackendOptions);
+    preflight(opts: PreflightOptions): Promise<void>;
+    execute(opts: ExecuteOptions): void;
+    kill(runId: string): boolean;
+    killAll(): void;
+    getActiveExecutions(): {
+        runId: string;
+        status: string;
+        startedAt: string;
+        duration: number;
+        testName?: string;
+    }[];
+    private settle;
+}
+declare function createInProcessExecutionBackend(options: InProcessExecutionBackendOptions): InProcessExecutionBackend;
+
+/**
+ * The comment-frame keepalive interval, matching every other SSE this package serves.
+ *
+ * EXPORTED so a cell can name the number rather than sleep past it, and so the client (404-07)
+ * can size its own liveness expectation off the server's constant instead of a second guess.
+ */
+declare const POST_PROCESSING_STREAM_HEARTBEAT_MS = 15000;
+/** The last failure the record holds for one stage — the emitter's masked, bounded text, forwarded. */
+interface PostProcessingStageFailure {
+    readonly error?: string;
+    readonly willRetry?: boolean;
+}
+/** What both doors answer with: the op result, plus what the run's own record says about it. */
+interface PostProcessingReadBody {
+    /** The `runs.postprocessing` result, VERBATIM. A reshaping here would be a second contract. */
+    readonly status: PostProcessingStatus;
+    /** The `runFinished` posture, when the record has one. Absent while the run is still in flight. */
+    readonly disposition?: PostProcessingDisposition;
+    /**
+     * The last `analysisFailed` / `curationFailed` payload per stage.
+     *
+     * PRESENT AND POSSIBLY EMPTY when the record was read; ABSENT ENTIRELY when the events read
+     * refused. The difference is a fact a client can act on — "this run wrote no failure line" is not
+     * the same claim as "this door could not read the log".
+     */
+    readonly failures?: {
+        readonly analysis?: PostProcessingStageFailure;
+        readonly curation?: PostProcessingStageFailure;
+    };
+}
+/** A refusal, already carrying its status and its single-key body. */
+interface PostProcessingRefusal {
+    readonly kind: 'refused';
+    readonly status: number;
+    readonly body: Record<string, string>;
+}
+type PostProcessingReadOutcome = {
+    readonly kind: 'ok';
+    readonly body: PostProcessingReadBody;
+} | PostProcessingRefusal;
+/**
+ * Has this chain finished, whatever became of it?
+ *
+ * TWO CLAUSES BECAUSE THERE ARE TWO TERMINALS AND THE ROW OUTRANKS THE CHIPS. A chain that wrote
+ * its one `RunNotification` is over by definition — that row IS the chain's terminal receipt — and
+ * a projection that disagreed with it would be a chain that ended twice. Absent the row, both chips
+ * having settled (`complete` or `failed`, the only two settled words in the four-word vocabulary) is
+ * the same fact read one layer down.
+ */
+declare function isPostProcessingTerminal(status: PostProcessingStatus): boolean;
+/**
+ * THE JOINED READ — the one place chip truth and run posture are put beside each other.
+ *
+ * Exported so the stream door and the read door answer with byte-identical bodies by CALLING one
+ * function rather than by two spellings that agree today. `routes.post-processing-stream.test.ts`
+ * compares the snapshot frame against the read route's body for exactly that reason.
+ */
+declare function readPostProcessing(host: AgentHost, runId: string): Promise<PostProcessingReadOutcome>;
+interface PostProcessingReadDeps {
+    /** The DECODED run id. Decoding can throw, and that throw is the caller's refusal to answer. */
+    readonly runId: string;
+    /** The injected host. Its absence is the ROUTER'S 503, not this function's. */
+    readonly host: AgentHost;
+}
+/** `GET /api/runs/:id/post-processing` — what the page polls (D-18). */
+declare function servePostProcessingRead(_req: IncomingMessage, res: ServerResponse, deps: PostProcessingReadDeps): void;
+interface PostProcessingStreamDeps extends PostProcessingReadDeps {
+    /** The in-process chip sink this browser's frames come from. */
+    readonly relay: PostProcessingRelay;
+    /** Live teardowns, so a host can count open streams and a close removes exactly one. */
+    readonly openStreams?: {
+        add(teardown: () => void): void;
+        delete(teardown: () => void): void;
+    };
+}
+/**
+ * `GET /api/runs/:id/post-processing/stream` — the DEDICATED live channel (D-16).
+ *
+ * THE ORDER IS THE CONTRACT, on `serveRunEventStream`'s own law: every refusal happens before
+ * `writeHead`, because a response that has already written `200 text/event-stream` cannot be told
+ * it failed. So the joined read runs FIRST — it is the snapshot's content and the open-time
+ * decision both — and only then does a head go out.
+ *
+ * THE 204 IS THE SSE SPEC'S NO-RECONNECT CLOSE, and it is the whole answer to Pitfall 6. An
+ * `EventSource` reconnects after ANY close except a 204, so a door that answered `200` with an
+ * immediate end to a run whose chain is over would be answering the same request every few seconds
+ * for as long as the tab is open. Three states get it:
+ *
+ *   - the chain is already terminal — there is nothing left to relay, ever;
+ *   - the run says `handedOff` — a lease-holder in ANOTHER process is draining it, and this
+ *     process's emitter will therefore never publish a single envelope for it;
+ *   - the run says `detached` — nothing is draining it in-process either.
+ *
+ * The last two are D-16's "closes immediately on hand-off / detach" and they are one decision with
+ * two words, because the fact that matters is identical: this relay cannot ever fire for that run,
+ * so the honest channel is the page's poll and holding a socket open would be a promise this
+ * process cannot keep. A snapshot with NO disposition at all is the opposite case — the run has not
+ * reached `runFinished` yet, which is exactly when a live channel is worth having — and it opens.
+ */
+declare function servePostProcessingStream(req: IncomingMessage, res: ServerResponse, deps: PostProcessingStreamDeps): void;
+
+/**
+ * What a run-detail reader is, spelled in this package's own vocabulary.
+ *
+ * Absence is a RESULT — `undefined` means no run is recorded under that id — and it
+ * is deliberately not a refusal: turning it into one is the op's job, so the "not found" word is
+ * minted once, in the layer every surface shares, rather than once per adapter.
+ */
+interface DashboardRunDetailReader {
+    read(runId: RunId): Promise<RunDetailRows | undefined>;
+    readRecord(runId: RunId): Promise<{
+        status: string;
+    } | undefined>;
+}
+/**
+ * Bind a reader to THIS server's one database handle.
+ *
+ * The read is synchronous underneath (better-sqlite3) and the method is `async` anyway, because
+ * the port's contract is a promise and a composition root that had to know which implementations
+ * were synchronous would be a composition root that knows too much.
+ *
+ * THE ID IS NEVER JOINED ONTO A PATH. It is a bound parameter of a prepared statement, resolved
+ * against rows the database already holds — the T-405-01 mitigation, and the same law
+ * `RunsReaderPort.get` states for the handoff store.
+ */
+declare function createDashboardRunDetailReader(db: DashboardDatabase): DashboardRunDetailReader;
+
+/** A refusal, already carrying its status and its single-key body. */
+interface RunDetailRefusal {
+    readonly kind: 'refused';
+    readonly status: number;
+    readonly body: Record<string, string>;
+}
+type RunDetailReadOutcome = {
+    readonly kind: 'ok';
+    readonly body: RunDetailProjection;
+} | RunDetailRefusal;
+/**
+ * THE READ. Exported so a cell can measure the outcome without a socket, and so any second door
+ * (405-05's authed remote row) answers with byte-identical bytes by CALLING this rather than by a
+ * second spelling that agrees today.
+ */
+declare function readRunDetail(host: AgentHost, runId: string): Promise<RunDetailReadOutcome>;
+interface RunDetailReadDeps {
+    /** The DECODED run id. Decoding can throw, and that throw is the caller's refusal to answer. */
+    readonly runId: string;
+    /** The injected host. Its absence is the ROUTER'S 503, not this function's. */
+    readonly host: AgentHost;
+    /**
+     * WHO IS ON THE OTHER END OF THIS SOCKET (405-10, D-09). Both doors serve the same body, masked
+     * at write, and nothing restores it (441 D-07); `'human'` only turns on the same-site guard.
+     *
+     * `'human'` IS PASSED BY THE LOCAL door's arms in `routes.ts`. The authed REMOTE door's
+     * `GET /run/:runId/detail` (`run-service-routes.ts`, 405-05) passes nothing, because it is
+     * legitimately reached at a non-loopback Host.
+     */
+    readonly boundary?: 'human' | 'machine';
+}
+/** `GET /api/runs/:id/detail` — what the rebuilt run-detail page reads (D-03). */
+declare function serveRunDetailRead(req: IncomingMessage, res: ServerResponse, deps: RunDetailReadDeps): void;
+type RunArtifactReadOutcome = {
+    readonly kind: 'ok';
+    readonly sha: string;
+    readonly contentType: string;
+    readonly bytes: Buffer;
+    readonly range?: RunsArtifactResult['range'];
+    readonly totalLength?: number;
+} | {
+    readonly kind: 'range-not-satisfiable';
+    readonly totalLength: number;
+} | RunDetailRefusal;
+/**
+ * THE READ. Exported so a cell can measure the outcome without a socket, and so the authed remote
+ * door answers with byte-identical bytes by CALLING this rather than by a second spelling.
+ */
+declare function readRunArtifact(host: AgentHost, runId: string, sha: string, range?: RunsArtifactInput['range']): Promise<RunArtifactReadOutcome>;
+interface RunArtifactReadDeps {
+    /** The DECODED run id. Decoding can throw, and that throw is the caller's refusal to answer. */
+    readonly runId: string;
+    /** The RAW sha segment. Never decoded: a content address contains nothing percent-encoding
+     * could represent, so a segment that needed decoding is already not one. */
+    readonly sha: string;
+    /** The injected host. Its absence is the ROUTER'S 503, not this function's. */
+    readonly host: AgentHost;
+}
+/**
+ * `GET /api/runs/:runId/artifacts/:sha` — a ref, resolved (D-12).
+ *
+ * THE HEADERS ARE THE FEATURE AS MUCH AS THE BYTES.
+ * - `ETag: "<sha>"` — the content address IS the validator; there is nothing else it could be, and
+ *   nothing that could make it stale, because bytes cannot change under a hash of themselves.
+ * - `Cache-Control: public, max-age=31536000, immutable` — for the same reason. A revalidation of
+ *   an immutable resource is a round trip that can only ever answer "yes, still".
+ * - `X-Content-Type-Options: nosniff` — the second half of the T-405-15 mitigation. The op refuses
+ *   to NAME a type a browser executes; this refuses to let the browser guess one anyway.
+ * - `Content-Length` — from the op's own declared `byteLength` by way of the decoded buffer.
+ *
+ * `If-None-Match` IS HONOURED because it is three lines against a header set that promises a year
+ * of caching, and a client that revalidates anyway should not be made to re-download a screenshot.
+ */
+declare function serveRunArtifact(req: IncomingMessage, res: ServerResponse, deps: RunArtifactReadDeps): void;
+
+/** Every value `[data-embed-state]` can take. */
+type LiveEmbedState = 'connecting' | 'live' | 'no-stream' | 'expired' | 'refused' | 'stream-ended' | 'session-ended' | 'ended' | 'lost';
+/** Every value `[data-embed-state]` can take. The 403-02 DOM cells range this list. */
+declare const LIVE_EMBED_STATES: readonly ["connecting", "live", "no-stream", "expired", "refused", "stream-ended", "session-ended", "ended", "lost"];
+/** Every fact the page reports to its host (428 D-15). */
+type LiveEmbedReportEvent = 'ready' | 'frame' | 'ended' | 'refused' | 'lost';
+declare const LIVE_EMBED_REPORT_EVENTS: readonly ["ready", "frame", "ended", "refused", "lost"];
+/**
+ * The query parameter a host sets when it draws its own status chrome (`/live/<id>?host=dashboard`).
+ * Any non-empty value lands on `main[data-embed-host]` and hides the page's centred text.
+ */
+declare const LIVE_EMBED_HOST_PARAM = "host";
+/** At most one `frame` report per this many milliseconds; the report carries the newest frame. */
+declare const LIVE_EMBED_REPORT_INTERVAL_MS = 500;
+/**
+ * What an EXPIRED link says, exactly (D-02).
+ *
+ * Exported so the tracer cell and 403-02's DOM cells assert the SAME string the page renders — a
+ * literal spelled twice is a literal that can drift, and this one is the difference between a
+ * person seeing "your link timed out" and a person seeing nothing at all.
+ */
+declare const LIVE_EMBED_EXPIRED_MESSAGE = "link expired";
+/**
+ * What a target that declared NO live stream says, exactly (D-08).
+ *
+ * This document owns no step list, and its host — the dashboard iframe today, the 408 MCP App
+ * later — is invisible to it, so the sentence claims nothing about where or whether steps are
+ * shown. Exported so the served bytes are pinned against the constant (frame-proxy cell 25).
+ */
+declare const LIVE_EMBED_NO_STREAM_MESSAGE = "no live preview for this target";
+/** What an ended editor session says, exactly (428 D-07/D-09; frame-proxy cell 34). */
+declare const LIVE_EMBED_SESSION_ENDED_MESSAGE = "session ended";
+/**
+ * Render the page for one run.
+ *
+ * `nonce` is minted per response by the caller and appears in both the CSP header and the two
+ * inline elements; a page served twice never reuses one.
+ */
+declare function renderLiveEmbedPage(input: {
+    runId: string;
+    nonce: string;
+}): string;
+
+interface FrameProxyDeps {
+    validate(token: string, expect: {
+        subject: LiveViewSubjectRef;
+        now: number;
+    }): LiveUrlVerdict;
+    attach(runId: string): RunSession | undefined;
+    /** 428 D-07: the editor-subject lookup. Absent means no editor subject is served on this socket. */
+    attachEditor?(sessionId: string): LiveEditorAttachment | undefined;
+    now?: () => number;
+}
+declare function createFrameProxy(deps: FrameProxyDeps): (ws: WebSocket, runId: string) => void;
+
+/** The frame socket. A query carries the run id ONLY — never the token (D-04). */
+declare const LIVE_VIEW_WS_PATH = "/api/live-view/ws";
+/** The served embed page's prefix. Bare, so a host's `/api/` allowlist is not involved. */
+declare const LIVE_EMBED_PATH_PREFIX = "/live/";
+/** The largest first message this socket will read. A hello is a few hundred bytes. */
+declare const LIVE_VIEW_HELLO_MAX_BYTES = 4096;
+/** Above this much buffered, a frame is DROPPED and acked — a slow viewer must not stall CDP. */
+declare const LIVE_VIEW_SLOW_VIEWER_BYTES: number;
+/** Keepalive cadence. */
+declare const LIVE_VIEW_PING_MS = 15000;
+/** The close code every refusal uses. In the 4000-4999 application range. */
+declare const LIVE_VIEW_REFUSAL_CLOSE_CODE = 4400;
+/**
+ * Every reason this socket can refuse a viewer, BY NAME.
+ *
+ * The four token verdicts plus the three this layer alone can answer: a run this process never
+ * started, a handle that run does not have, and an editor session this process does not hold
+ * (428 D-07). Extending the token's list rather than restating it is what stops the two
+ * vocabularies from drifting.
+ */
+type LiveViewRefusalReason = LiveUrlRefusalReason | 'unknown_run' | 'unknown_handle' | 'unknown_session';
+declare const LIVE_VIEW_REFUSAL_REASONS: readonly ["malformed", "bad_signature", "expired", "scope_mismatch", "unknown_run", "unknown_handle", "unknown_session"];
+/**
+ * Every reason an `ended` message can carry, each naming a different fact (403 CR-03, 428 D-07/D-09).
+ * `runFinished`: the run is over. `handleFinished`: this member's stream is over while its run
+ * continues. `sessionEnded`: an editor session is over.
+ */
+type LiveViewEndReason = 'runFinished' | 'handleFinished' | 'sessionEnded';
+declare const LIVE_VIEW_END_REASONS: readonly ["runFinished", "handleFinished", "sessionEnded"];
+/** What the PAGE sends. `hello` must be first; `ack` and `renew` are valid only after `ready`. */
+type LiveViewClientMessage = {
+    type: 'hello';
+    token: string;
+} | {
+    type: 'ack';
+    id: number;
+} | {
+    type: 'renew';
+    token: string;
+};
+/**
+ * What the SERVER sends.
+ *
+ * A `frame` is a TEXT header immediately followed by ONE BINARY message carrying the JPEG bytes.
+ * Two messages rather than a length-prefixed binary frame so a consumer needs no custom header
+ * parser — `JSON.parse` and a `Blob` are all an embed page has to know.
+ */
+type LiveViewServerMessage = {
+    type: 'ready';
+    runId: string;
+    handle: number;
+    stream: LiveStreamDeclaration;
+    expiresAt: number;
+} | {
+    type: 'refused';
+    reason: LiveViewRefusalReason;
+} | {
+    type: 'frame';
+    id: number;
+    width: number;
+    height: number;
+    ts?: number;
+    kind?: LiveStreamKind;
+} | {
+    type: 'renewed';
+    expiresAt: number;
+} | {
+    type: 'ended';
+    reason: LiveViewEndReason;
+};
+
+type RunMarkOutcome = {
+    readonly kind: 'ok';
+    readonly body: RunsMarkOutcome;
+} | RunDetailRefusal;
+/**
+ * Address comes from the route; the body may never replace it or claim a caller identity. The body
+ * is the op's own strict input minus `runId`, so a field the op does not declare is refused here
+ * before anything is dispatched.
+ */
+declare function markRun(host: AgentHost, runId: string, body: unknown): Promise<RunMarkOutcome>;
+/** POST /api/runs/:id/mark. Both doors answer the op's outcome as it is; `'human'` adds the same-site guard. */
+declare function registerRunMarkRoute(req: IncomingMessage, res: ServerResponse, deps: {
+    readonly host: AgentHost;
+    readonly runId: string;
+    readonly boundary?: 'human' | 'machine';
+}): void;
 
-export { DashboardDatabase, DashboardReporter, MIGRATIONS, type ResolveDashboardDbPathOptions, type RunIdMigrationOptions, type RunIdMigrationResult, SCHEMA_VERSION, migrateWorkspaceRunIds, resolveDashboardDbPath };
+export { AgentHost, DashboardDatabase, type DashboardRunDetailReader, type DashboardRunIngest, type DashboardRunIngestDeps, type DashboardRunIngestFinalizeExtra, ExecuteOptions, ExecutionBackend, InProcessExecutionBackend, type InProcessExecutionBackendOptions, type InProcessRunStartInput, type InProcessRunStarter, type InProcessRunStatus, LIVE_EMBED_EXPIRED_MESSAGE, LIVE_EMBED_HOST_PARAM, LIVE_EMBED_NO_STREAM_MESSAGE, LIVE_EMBED_PATH_PREFIX, LIVE_EMBED_REPORT_EVENTS, LIVE_EMBED_REPORT_INTERVAL_MS, LIVE_EMBED_SESSION_ENDED_MESSAGE, LIVE_EMBED_STATES, LIVE_VIEW_END_REASONS, LIVE_VIEW_HELLO_MAX_BYTES, LIVE_VIEW_PING_MS, LIVE_VIEW_REFUSAL_CLOSE_CODE, LIVE_VIEW_REFUSAL_REASONS, LIVE_VIEW_SLOW_VIEWER_BYTES, LIVE_VIEW_WS_PATH, LiveEditorAttachment, type LiveEmbedReportEvent, type LiveEmbedState, type LiveViewClientMessage, type LiveViewRefusalReason, type LiveViewServerMessage, MIGRATIONS, POST_PROCESSING_STREAM_HEARTBEAT_MS, type PostProcessingReadBody, PostProcessingRelay, type PostProcessingStageFailure, type ResolveDashboardDbPathOptions, type RunArtifactReadOutcome, type RunDetailReadOutcome, type RunIdentityMember, type RunMarkOutcome, type RunRowIdentity, SCHEMA_VERSION, createDashboardRunDetailReader, createDashboardRunIngest, createFrameProxy, createInProcessExecutionBackend, createRunOwnerHostResolver, formatRunTitle, isPostProcessingTerminal, markRun, readPostProcessing, readRunArtifact, readRunDetail, registerRunMarkRoute, renderLiveEmbedPage, resolveDashboardDbPath, resolveRunOwnerHost, runRowIdentity, servePostProcessingRead, servePostProcessingStream, serveRunArtifact, serveRunDetailRead };