@vostride/agent-qa-dashboard 0.1.21 → 0.2.1

package/dist/index-Ds4Lv4mT.d.cts

@@ -0,0 +1,2094 @@
+import { IncomingMessage, ServerResponse, Server } from 'node:http';
+import { RunAttributes, ResolvedWorkspacePaths, ResolvedAppiumExecutable, HookDefinition, AuthStateMetadata } from '@vostride/agent-qa-core';
+import { RunDetailMember, RunDetailStep, RunDetailSubAction, RunDetailRows, RunStatus, RunArtifactKind, RunArtifactStageInput, RunArtifactPayload, RunArtifactFinalizeInput, LiveStreamDeclaration, LiveFrame, LiveFrameEndReason, LiveFrameSubscription, FunctionCaller, RunEventEnvelope, RunStartAcknowledgement, RunSession, RunServiceReadiness, RunsLiveUrlResult, RunServiceDenialBody, MaskFn, LiveViewSubjectRef, LiveUrlVerdict, EditorLiveUrlResult, ConfigWriteIssue, ConfigChange, ConfigPathSegment, ConfigWriteRefusal, PlannerLimits } from '@vostride/agent-qa-schema';
+import { EventEmitter } from 'node:events';
+import { SecretStore, SecretRedactor, ConsoleLogEntry, NetworkLogEntry, StepAnnotation, StepPhaseEvent, StepResult } from '@vostride/agent-qa-runner';
+import { Node } from 'yaml';
+
+interface RunOwner {
+    readonly pid: number;
+    readonly incarnation: string | null;
+    readonly host: string;
+}
+interface RunOwnerProbe {
+    isAlive(pid: number): boolean;
+    incarnationOf(pid: number): string | undefined;
+}
+interface RunOwnership {
+    readonly self: RunOwner;
+    readonly probe: RunOwnerProbe;
+}
+interface RunOwnershipInput {
+    readonly self: Omit<RunOwner, 'host'> & {
+        readonly host?: string;
+    };
+    readonly probe: RunOwnerProbe;
+}
+declare function completeRunOwnership(input: RunOwnershipInput): RunOwnership;
+type RunOwnerState = 'self' | 'alive' | 'gone' | 'unknown';
+declare function classifyRunOwner(owner: RunOwner, ownership: RunOwnership): RunOwnerState;
+declare const orphanSummary: (pid: number) => string;
+declare const ownedElsewhere: (pid: number) => string;
+declare function defaultRunOwnership(): RunOwnership;
+
+interface RunRow {
+    id: string;
+    name: string;
+    filePath: string | null;
+    status: string;
+    priority: number;
+    duration: number;
+    attributes: RunAttributes;
+    environment: string | null;
+    metadata: Record<string, unknown> | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    failureSummary: string | null;
+    errorLog: string | null;
+    memoryLog: string | null;
+    testId: string | null;
+    suiteId: string | null;
+    platform: string;
+    testFileContent: string | null;
+    modelName: string | null;
+    llmProvider: string | null;
+    parallel: boolean;
+    createdAt: string;
+    members?: RunMemberSummary[];
+    memberOutcome?: string | null;
+}
+interface TestRef {
+    testId?: string;
+    filePath?: string;
+}
+interface RunMemberSummary {
+    testIndex: number;
+    testId: string | null;
+    filePath: string | null;
+    suiteId: string | null;
+    name: string | null;
+    outcome: string | null;
+}
+interface RunArtifactRow {
+    runId: string;
+    kind: RunArtifactKind;
+    schemaVersion: number;
+    payload: RunArtifactPayload;
+    finalizedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * ONE RUN'S ARTIFACT, AND NOTHING ELSE (405-07, D-02).
+ *
+ * `children` stood here and is gone. It walked the run row's now-deleted parent link for the child
+ * rows of a suite parent — a shape nothing has written since 402-09 put ONE `runs` row per run and moved member
+ * identity onto `run_members`. A structurally-always-empty array on a response is worse than an
+ * absent one: a reader cannot tell "this run has no children" from "children stopped being a fact
+ * this product records", so the page renders an empty section forever and nobody notices.
+ */
+interface RunArtifactBundle {
+    artifact: RunArtifactRow | null;
+}
+interface ExecutionLogRow {
+    id: string;
+    runId: string;
+    stepId: string | null;
+    /**
+     * 405 D-01: where in the run tree this hook ran, from `HookFinishedPayload`'s own optional
+     * fields. `null` means a RUN-SCOPED hook — a real state, not a missing value.
+     */
+    testIndex: number | null;
+    stepIndex: number | null;
+    type: 'hook' | 'appium-script' | 'runjs';
+    name: string;
+    hookId: string | null;
+    phase: 'setup' | 'teardown' | 'inline';
+    status: 'passed' | 'failed';
+    duration: number;
+    stdout: string | null;
+    stderr: string | null;
+    returnData: unknown | null;
+    variables: Record<string, string> | null;
+    createdAt: string;
+}
+interface InsertExecutionLogInput {
+    id: string;
+    runId: string;
+    stepId?: string | null;
+    /** 405 D-01: the handle and step this hook belongs to; absent means run-scoped. */
+    testIndex?: number | null;
+    stepIndex?: number | null;
+    type: 'hook' | 'appium-script' | 'runjs';
+    name: string;
+    hookId?: string | null;
+    phase: 'setup' | 'teardown' | 'inline';
+    status: 'passed' | 'failed';
+    duration: number;
+    stdout?: string | null;
+    stderr?: string | null;
+    returnData?: unknown | null;
+    variables?: Record<string, string> | null;
+}
+interface RunsFilter {
+    statuses?: readonly string[];
+    name?: string;
+    platform?: string;
+    from?: string;
+    to?: string;
+    attributePredicates?: AttributePredicate[];
+    limit?: number;
+    offset?: number;
+}
+interface StatsOptions {
+    from?: string;
+    to?: string;
+    attributePredicates?: AttributePredicate[];
+}
+type InsightsBreakdownDimension = 'test' | 'suite' | 'platform';
+interface InsightsBreakdownRow {
+    key: string;
+    label: string;
+    runs: number;
+    passRate: number | null;
+    flakeRate: number;
+    avgDuration: number;
+    passed: number;
+    failed: number;
+    filePath?: string;
+    suiteId?: string;
+}
+/**
+ * What a run deletion removed (405-07, D-14 · T-405-27).
+ *
+ * ROWS ONLY. The two path arrays that stood here fed the router's filesystem cleanup, and both the
+ * cleanup and the columns it read are gone: refs are the only artifact addressing now, and the run
+ * directory under `.agent-qa/runs/` is the run's own record — the event log and the blobs — which
+ * the dashboard never owned and must not delete. `deletedRunIds` survives as a one-element list
+ * rather than collapsing to a boolean, because it is the shape the response already publishes.
+ */
+interface DeleteRunResult {
+    deleted: boolean;
+    deletedRunIds: string[];
+}
+interface AttributePredicate {
+    key: string;
+    value: string;
+    mode: 'exact' | 'regex';
+}
+interface AttributeKeySuggestion {
+    key: string;
+    count: number;
+}
+interface AttributeValueSuggestion {
+    value: string;
+    count: number;
+}
+declare class UnsupportedUserVersionError extends Error {
+    readonly version: number;
+    readonly schemaVersion: number;
+    constructor(version: number, schemaVersion: number);
+}
+declare class RunsDatabaseVersionRefusedError extends Error {
+    readonly dbPath: string;
+    readonly version: number;
+    constructor(dbPath: string, refusal: UnsupportedUserVersionError);
+}
+declare class DashboardDatabase {
+    private db;
+    readonly runOwnership: RunOwnership;
+    readonly dbPath: string;
+    private readonly ownStamps;
+    constructor({ dbPath, runOwnership, }?: {
+        dbPath?: string;
+        runOwnership?: RunOwnershipInput;
+    });
+    private runMigrations;
+    insertRun(run: {
+        id?: string;
+        name: string;
+        filePath?: string;
+        status: string;
+        duration: number;
+        attributes?: RunAttributes;
+        environment?: string;
+        metadata?: Record<string, unknown>;
+        startedAt: string;
+        endedAt: string;
+        failureSummary?: string;
+        platform?: string;
+        testFileContent?: string;
+        modelName?: string;
+        llmProvider?: string;
+        testId?: string;
+        suiteId?: string;
+    }): string;
+    claimRunningRow(id: string, fields: {
+        name?: string;
+        filePath?: string;
+        attributes?: RunAttributes;
+        startedAt: string;
+        platform?: string;
+        testId?: string;
+        suiteId?: string;
+    }): boolean;
+    updateRun(id: string, updates: {
+        name?: string;
+        status?: string;
+        duration?: number;
+        startedAt?: string;
+        endedAt?: string;
+        failureSummary?: string;
+        errorLog?: string;
+        memoryLog?: string;
+        attributes?: RunAttributes;
+        platform?: string;
+        testId?: string;
+        suiteId?: string;
+    }): void;
+    updateRunMetadata(id: string, updates: {
+        attributes?: RunAttributes;
+        metadata?: Record<string, unknown>;
+        platform?: string;
+        testFileContent?: string;
+        modelName?: string;
+        llmProvider?: string;
+    }): void;
+    insertPendingRun(run: {
+        id?: string;
+        name: string;
+        filePath?: string;
+        attributes?: RunAttributes;
+        priority?: number;
+        platform?: string;
+        testFileContent?: string;
+        modelName?: string;
+        llmProvider?: string;
+        metadata?: Record<string, unknown>;
+        parallel?: boolean;
+    }): string;
+    getNextPendingRun(): RunRow | undefined;
+    getPendingRuns(): RunRow[];
+    updateRunStatus(id: string, status: string): boolean;
+    /**
+     * Write or refresh ONE member row, keyed by the handle `(run_id, test_index)`.
+     *
+     * AN UPSERT AND NOT TWO WRITES, because the member row is fed by two events at two times:
+     * `testStarted` knows the identity fields and `testFinished` knows the outcome — and D-18
+     * requires a member whose stream begins with a terminal event to render anyway, so the second
+     * one alone has to be able to create the row.
+     *
+     * ONLY SUPPLIED FIELDS MOVE. `COALESCE(excluded.x, run_members.x)` on every optional column, so
+     * a `testFinished` that carries no name cannot blank the name `testStarted` wrote. `attempts` is
+     * excluded from the update entirely: it is the D-17 retry ordinal, owned by
+     * `incrementRunMemberAttempts`, and an upsert that reset it would erase the fact the header
+     * renders.
+     */
+    upsertRunMember(member: {
+        runId: string;
+        testIndex: number;
+        testId?: string;
+        name?: string;
+        filePath?: string;
+        suiteId?: string;
+        suiteName?: string;
+        suiteIndex?: number;
+        totalSteps?: number;
+        outcome?: string;
+        durationMs?: number;
+        failureSummary?: string;
+        retryCount?: number;
+        recording?: RunDetailMember['recording'];
+    }): void;
+    /**
+     * Raise ONE member's attempt ordinal (D-17). A no-op when the member row does not exist yet —
+     * a retry scheduled before any identity event is a real ordering, and inventing a row here
+     * would put a member on the page that nothing has said anything about.
+     */
+    incrementRunMemberAttempts(runId: string, testIndex: number): void;
+    /**
+     * Drop ONE HANDLE's projected step and sub-action rows (D-17).
+     *
+     * SCOPED TO THE HANDLE, which was the whole change from the v1 run-wide step delete this
+     * replaced (deleted outright by 405-07's census): that member wiped every step of the RUN on any
+     * member's retry, so in a suite the abandoned attempt of test 3 deleted the completed history of
+     * tests 0-2. The member row itself survives — its outcome and its attempt count are facts about
+     * the member, not about the attempt. So do its setup and teardown hook rows, which run once per
+     * member outside the retry loop; only the attempt's `inline` hook rows go (433-41, CR-01).
+     */
+    deleteMemberProjection(runId: string, testIndex: number): void;
+    /**
+     * Write ONE finalized step row. `INSERT OR REPLACE` because a re-run of the same handle re-emits
+     * the same `(test_index, step_index)` and the LAST attempt is the one the page renders (D-17).
+     *
+     * The three token columns stay NULL when `tokenUsage` is absent — never 0 (D-05).
+     */
+    insertRunStep(step: {
+        runId: string;
+        testIndex: number;
+        stepIndex: number;
+        stepText?: string;
+        cacheStatus: string;
+        verifierVerdict: unknown;
+        selfHealOccurred: boolean;
+        briefDigest: string;
+        status?: string;
+        durationMs?: number;
+        error?: string;
+        tokenUsage?: RunDetailStep['tokenUsage'];
+        modelUsage?: RunDetailStep['modelUsage'];
+        evidence?: RunDetailStep['evidence'];
+        variableSnapshot?: RunDetailStep['variableSnapshot'];
+    }): void;
+    /**
+     * Write ONE sub-action row. The four nested payload fields are stringified VERBATIM — this
+     * method never reaches inside `plannedAction`, `grounding`, `result` or `artifactRefs`.
+     */
+    insertRunSubAction(subAction: {
+        runId: string;
+        testIndex: number;
+        stepIndex: number;
+        subActionIndex: number;
+        plan: string;
+        plannedAction: unknown;
+        grounding?: unknown;
+        result: unknown;
+        screenStateHash: string;
+        screenStateHashAfter?: string;
+        artifactRefs?: readonly unknown[];
+        ariaEvidence?: RunDetailSubAction['ariaEvidence'];
+        recordingOffsetMs?: RunDetailSubAction['recordingOffsetMs'];
+    }): void;
+    /**
+     * THE run-detail read (D-03). `undefined` when no `runs` row exists — absence is a RESULT here,
+     * and turning it into a typed refusal is the `runs.detail` op's job, so the "not found"
+     * vocabulary lives in the function layer rather than in this store.
+     *
+     * A run that exists and projected nothing answers three empty arrays, which is a DIFFERENT fact
+     * and stays a different answer.
+     */
+    readRunDetailRows(runId: string): RunDetailRows | undefined;
+    private appendAttributePredicateConditions;
+    private applyRegexAttributePredicates;
+    private queryRunsWithAttributePredicates;
+    private buildTrendsFromRuns;
+    getRuns(opts?: RunsFilter): RunRow[];
+    private withMemberSummaries;
+    readRunOwner(id: string): RunOwner | undefined;
+    listRunningRunOwners(): Array<{
+        id: string;
+        startedAt?: string;
+        owner: RunOwner;
+    }>;
+    finalizeOwnRun(id: string, updates: {
+        status: RunStatus;
+        endedAt: string;
+        duration?: number;
+        failureSummary?: string;
+    }): boolean;
+    closeOwnRun(id: string, updates: {
+        status: RunStatus;
+        endedAt: string;
+    }): boolean;
+    isOwnStamp(id: string, owner: RunOwner): boolean;
+    private readOwnStamp;
+    finalizeOrphanRun(id: string, owner: RunOwner): boolean;
+    getRun(id: string): RunRow | undefined;
+    /** Read-only repair for old last-member totals. Complete measured member work is cumulative,
+     * including parallel members; it is neither recording length nor run wall-clock time.
+     * Incomplete legacy projections retain their stored fallback. Bound queries to returned rows,
+     * after pagination, with one aggregate per batch rather than a lookup for every list row.
+     */
+    private withMemberExecutionDuration;
+    listRunAttributeKeys(opts?: {
+        limit?: number;
+        q?: string;
+    }): AttributeKeySuggestion[];
+    listRunAttributeValues(key: string, opts?: {
+        limit?: number;
+        q?: string;
+    }): AttributeValueSuggestion[];
+    /**
+     * Delete ONE run and everything the schema hangs off it (405-07, D-02/D-14 · T-405-27).
+     *
+     * ONE ID, AND THE CASCADE DOES THE REST. This used to open with a recursive `run_tree` CTE that
+     * walked the child rows of a suite parent, then hand-delete their step and trace rows in a
+     * transaction. Nothing has written a child row since 402-09 — one `runs` row per run, member
+     * identity on `run_members` — so the walk could only ever return the one row it was seeded with,
+     * and the hand-deletes named tables this schema no longer has. Every table that references a run
+     * declares `ON DELETE CASCADE`, so the single statement below is the whole deletion.
+     *
+     * AND IT TOUCHES NO FILE. The two path arrays it used to collect fed the router's artifact
+     * cleanup; both are gone. The run's directory under `.agent-qa/runs/` — its event log and its
+     * content-addressed blobs — is the run's own record and is not the dashboard's to remove.
+     */
+    deleteRun(id: string): DeleteRunResult;
+    insertRunArtifact(input: {
+        runId: string;
+        kind?: RunArtifactKind;
+        payload?: RunArtifactStageInput;
+    }): RunArtifactRow;
+    stageRunArtifact(runId: string, patch: RunArtifactStageInput): RunArtifactRow;
+    finalizeRunArtifact(runId: string, updates?: RunArtifactFinalizeInput): RunArtifactRow;
+    getRunArtifact(runId: string): RunArtifactRow | null;
+    getRunArtifactBundle(runId: string): RunArtifactBundle;
+    /**
+     * The runs a self-heal happened on (405-07, D-02).
+     *
+     * READ OFF `run_steps.self_heal_occurred`, WHICH IS THE SURVIVING HEALING FACT. This scanned the
+     * v1 wide step table for `status = 'healed'`; that table had no producer left and its readers
+     * went with it. `selfHealOccurred` is the bus payload's own boolean, projected verbatim by the
+     * subscriber — so the flake rate below is now computed from what the runner actually reported
+     * rather than from a status word a retired projection wrote.
+     */
+    private getHealedRunIds;
+    private summarizeAnalyticsRuns;
+    private listRunsForInsights;
+    getStats(opts?: StatsOptions): {
+        totalRuns: number;
+        passed: number;
+        failed: number;
+        flaky: number;
+        flakeRate: number;
+        avgDuration: number;
+        totalTokens: number;
+        runs: {
+            date: string;
+            passed: number;
+            failed: number;
+            healed: number;
+            duration: number;
+        }[];
+        memory: {
+            runs: number;
+            added: number;
+            confirmed: number;
+            deprecated: number;
+            deleted: number;
+            curatorTokens: number;
+        };
+    };
+    getCostStats(opts?: StatsOptions): {
+        runs: {
+            runId: string;
+            name: string;
+            startedAt: string | null;
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        }[];
+        totals: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+    };
+    insertTokenEvent(event: {
+        modelName: string;
+        promptTokens: number;
+        completionTokens: number;
+        source: 'test-run' | 'live-editor';
+    }): string;
+    getTokenEventStats(opts?: {
+        from?: string;
+        to?: string;
+    }): {
+        byModel: {
+            date: string;
+            model: string;
+            promptTokens: number;
+            completionTokens: number;
+        }[];
+        bySource: Record<string, {
+            promptTokens: number;
+            completionTokens: number;
+        }>;
+        totals: {
+            promptTokens: number;
+            completionTokens: number;
+        };
+        testRunUnmeasuredSteps: number;
+    };
+    /**
+     * The window's settled run ids, newest first, capped at `limit`, with their full count, and the
+     * count of the window's runs still in flight (433-30, 433-42). A settled run has started and is
+     * neither `pending` nor `running`; every other row in the window is in flight. Ids only: the
+     * Insights knowledge-change read dispatches each through the agent host.
+     */
+    listInsightsWindowRunIds(opts: {
+        from?: string;
+        to?: string;
+        limit: number;
+    }): {
+        runIds: string[];
+        total: number;
+        inFlight: number;
+    };
+    getRunsByTest(test: TestRef, opts?: {
+        limit?: number;
+        offset?: number;
+        attributePredicates?: AttributePredicate[];
+    }): RunRow[];
+    getRunsByTestCount(test: TestRef, opts?: {
+        attributePredicates?: AttributePredicate[];
+    }): number;
+    getTestTrends(test: TestRef, opts?: {
+        from?: string;
+        attributePredicates?: AttributePredicate[];
+    }): {
+        daily: {
+            date: string;
+            passed: number;
+            failed: number;
+            total: number;
+            avgDuration: number;
+        }[];
+        passRate: number | null;
+        totalRuns: number;
+        avgDuration: number;
+    };
+    private withMemberOutcome;
+    getRunsBySuiteId(suiteId: string, opts?: {
+        limit?: number;
+        offset?: number;
+        attributePredicates?: AttributePredicate[];
+    }): RunRow[];
+    getRunsBySuiteIdCount(suiteId: string, opts?: {
+        attributePredicates?: AttributePredicate[];
+    }): number;
+    getSuiteTrends(suiteId: string, opts?: {
+        from?: string;
+        attributePredicates?: AttributePredicate[];
+    }): {
+        daily: {
+            date: string;
+            passed: number;
+            failed: number;
+            total: number;
+            avgDuration: number;
+        }[];
+        passRate: number | null;
+        totalRuns: number;
+        avgDuration: number;
+    };
+    getInsightsBreakdown(dimension: InsightsBreakdownDimension, opts?: StatsOptions & {
+        limit?: number;
+    }): InsightsBreakdownRow[];
+    getFlakyTests(opts?: {
+        minRuns?: number;
+        limit?: number;
+    }): {
+        name: string;
+        filePath: string | null;
+        totalRuns: number;
+        passRate: number;
+        flakyScore: number;
+    }[];
+    insertExecutionLog(data: InsertExecutionLogInput): void;
+    getExecutionLogs(filter: {
+        runId?: string;
+        stepId?: string;
+        type?: string;
+    }): ExecutionLogRow[];
+    close(): void;
+    private parseRunAttributes;
+    private mapRunRow;
+    private mapRunArtifactRow;
+}
+
+interface ExecuteOptions {
+    runId: string;
+    args: string[];
+    source: string;
+    attributes?: RunAttributes;
+    timeout?: number;
+    /**
+     * The Appium lease URL for a mobile run, AS DATA (401-07, D-01/D-12).
+     *
+     * The bundled Appium spawn is design-of-record and stays exactly where it is; what changed is the
+     * DELIVERY. It used to ride `AGENT_QA_APPIUM_URL` in a child's environment, and a child env is
+     * something only a child has. The run happens in this process now, so the lease travels as an
+     * argument and is handed to the run through an injected resolver.
+     */
+    appiumUrl?: string;
+}
+/**
+ * A run has reached a terminal state (401-07, D-04/D-12).
+ *
+ * THE TYPED SUCCESSOR TO THE CHILD'S `close` EVENT. The host reconciles a db row still reading
+ * `running`, releases the run's Appium lease and frees the queue slot off this — exactly what it did
+ * off the process exit — but the status is now the bus's own ground truth and the `details` carry
+ * the failure's REASON rather than a scraped tail of stderr.
+ *
+ * `'run-settled'` is now the WHOLE of this emitter's contract. A second event carried the retired
+ * live feed's frames and went with it (405-07, D-19).
+ */
+interface RunSettledDetails {
+    /**
+     * A human-readable reason when the run did not simply finish. 2026-09-30, 432-09 (D-15): a
+     * refusal is this plain reason. No remedy list rides the settle; nothing asks the reader to act.
+     */
+    readonly reason?: string;
+    /**
+     * The run NEVER BEGAN — the gate or the host refused it (401-18, G-401-16).
+     *
+     * A FACT, NOT AN INFERENCE. `settle` has always known this — a rejection with no started session
+     * is a denial, a refused request field or an input error — and threw the knowledge away, leaving
+     * the host's reconciliation to guess from a regex over the diagnostic lines. It guessed
+     * `Process exited before test completed`, which is a sentence about a process, for a run where
+     * nothing was ever started to exit.
+     *
+     * DELIBERATELY A BOOLEAN AND NOT A CLASS. Which refusal it was — `fail-closed-denied`, `blocked`,
+     * `session-pin-denied`, an unrecognised request field, a plain input error — is not something the
+     * reconciliation branches on, and a prose name for it here would be the same defect one layer
+     * down. If a class is ever needed it arrives as a closed-set value owned by `schema`.
+     *
+     * ABSENT ON A RUN THAT STARTED, including one that started and then failed. That asymmetry is the
+     * scope guarantee: every other arm of the reconciliation reads exactly what it read before.
+     */
+    readonly refusedBeforeStart?: true;
+    /**
+     * The refusal said without naming any surface's affordance (401-18, G-401-16).
+     *
+     * The gate composed two sentences per decision: the canonical one, which named the session trust
+     * flag and landed in the execution-audit row, and the neutral one, which stops at the classification and the outcome.
+     * A browser reader was being handed the first, so the record's only account of why a run never
+     * happened told them to pass a flag to a command they were not running.
+     *
+     * READ STRUCTURALLY OFF THE REJECTION, and ABSENT where the
+     * rejection carries no neutral form — an input error is not a gate decision and has no second
+     * phrasing. The consumer then falls back to the rejection's own message, which for those refusals
+     * names no surface's affordance either.
+     */
+    readonly neutralReason?: string;
+    /** Diagnostic lines — a rejection's own message. The typed successor to scraped stderr. */
+    readonly output: readonly string[];
+}
+type RunSettledStatus = 'completed' | 'failed' | 'cancelled' | 'timeout';
+/** A trigger's request as the queue would carry it, before anything is recorded (433-34). */
+interface PreflightOptions {
+    readonly args: string[];
+    readonly source: 'dashboard' | 'suite';
+}
+interface ExecutionBackend extends EventEmitter {
+    execute(opts: ExecuteOptions): void;
+    /**
+     * Ask the run core whether this request may start, before a row is minted or anything enqueued
+     * (433-34, G-433-10).
+     *
+     * The composing host answers with the core's own production rule over the members' declared
+     * targets; this package decides nothing about production. A refusal rejects with the core's
+     * denial, which carries `neutralReason`. Absent on a backend whose host composes no preflight.
+     */
+    preflight?(opts: PreflightOptions): Promise<void>;
+    kill(runId: string): boolean;
+    killAll(): void;
+    /**
+     * The runs this backend currently has in flight, as `GET /api/execution/active` serves them.
+     *
+     * `testName` IS ON THE INTERFACE (405-07, D-19). It used to be produced by scanning a per-run
+     * event buffer for a `testStarted` frame — a read that only the concrete class could perform,
+     * through a member the interface did not declare. It is now recorded on the run handle by the
+     * backend's own bus subscription, so the field is part of the contract every implementation
+     * answers rather than a property of one implementation's internal storage.
+     *
+     * ABSENT MEANS NO MEMBER HAS STARTED YET, which is a real state on a run between its start and
+     * its first `testStarted`; it is never filled with the run id or a placeholder.
+     */
+    getActiveExecutions(): {
+        runId: string;
+        status: string;
+        startedAt: string;
+        duration: number;
+        testName?: string;
+    }[];
+}
+
+/** The frame-facing slice of a `RunSession`, for an editor session. */
+interface LiveEditorAttachment {
+    streamCapabilityOf(handle: number): LiveStreamDeclaration;
+    subscribeFrames(handle: number, onFrame: (frame: LiveFrame) => void, onEnd?: (reason: LiveFrameEndReason) => void): LiveFrameSubscription | undefined;
+    /** Settles when the editor session is over. The frame socket then says `sessionEnded`. */
+    readonly ended: Promise<void>;
+}
+interface LiveEditorSubjects {
+    register(sessionId: string, attachment: LiveEditorAttachment): void;
+    unregister(sessionId: string): void;
+    attach(sessionId: string): LiveEditorAttachment | undefined;
+    /** The session's declared stream (its handle 0), or undefined when no such session is held. */
+    capabilityOf(sessionId: string): LiveStreamDeclaration | undefined;
+}
+declare function createLiveEditorSubjects(): LiveEditorSubjects;
+
+type ModelAdapter = 'openai-responses' | 'anthropic-messages';
+interface DashboardLLMConfig {
+    provider: string;
+    model: string;
+    baseURL?: string;
+    providerHeaders?: Record<string, string>;
+    apiKey?: string;
+    authToken?: string;
+    modelAdapter?: ModelAdapter;
+}
+
+/**
+ * The composed function registry, OPAQUE to this package.
+ *
+ * Deliberately not structurally described. The registry's real type lives in `agent`, this package
+ * may not name it, and a hand-written mirror of its shape here would be a second declaration of
+ * somebody else's contract — stale on the day `agent` changes it, and silently so, because nothing
+ * would compare the two. What this package does with the value is hand it straight back to the
+ * functions below, which is all an opaque handle has to support.
+ */
+type AgentRegistryHandle = object;
+/**
+ * The whole of what the run-detail and mark routes may ask of the process that started them.
+ *
+ * A single object rather than loose options, because the members are one decision: they all come
+ * from ONE composition, and a server holding an invoke from one host and a registry from another is
+ * a state nobody should be able to construct.
+ */
+interface AgentHost {
+    /** The composed registry every call goes through. Opaque here. */
+    readonly registry: AgentRegistryHandle;
+    /**
+     * The caller this door dispatches as, MINTED by the composition root and never by this package.
+     *
+     * Attribution and grants both. The composer derives it from the CLI chat door's own mint with
+     * only the surface name changed (D-08/Pitfall 9) — a hand-typed scope list here would be the
+     * drift vector the parity legs exist to catch, and this package could not type-check one anyway.
+     */
+    readonly caller: FunctionCaller;
+    /**
+     * The agent package's `runs.postprocessing` id (404 D-16/D-18).
+     *
+     * SUPPLIED BY THE COMPOSITION, NEVER SPELLED HERE. The post-processing read route dispatches
+     * chip truth through this door, and the op id is the agent package's constant: a string literal
+     * in this package would be a second declaration of a capability's name, free to drift from the
+     * spec that answers to it. This package also may not import `@vostride/agent-qa-agent`
+     * (validate:arch), so there is nowhere here the real constant could come from.
+     */
+    readonly runsPostProcessingFunctionId: string;
+    /**
+     * The agent package's `runs.events` id, on the line above's footing (404 D-22).
+     *
+     * A SECOND ID BECAUSE THE READ ROUTE JOINS TWO FACTS from two different records: the chain's
+     * chips live in the durable job store, and the run's POSTURE — who was going to drain it — lives
+     * on the `runFinished` line of the run's own event log, beside the last per-stage failure text.
+     * Reading the log any other way would mean this package opening a file the function layer owns.
+     */
+    readonly runsEventsFunctionId: string;
+    /**
+     * The agent package's `runs.detail` id, on `runsPostProcessingFunctionId`'s exact footing (405
+     * D-03).
+     *
+     * SUPPLIED BY THE COMPOSITION, NEVER SPELLED HERE, for the reason its two neighbours are: the
+     * op id is the agent package's constant, a string literal in this package would be a second
+     * declaration of a capability's name free to drift from the spec that answers to it, and this
+     * package may not import `@vostride/agent-qa-agent` at all (validate:arch) — so there is nowhere
+     * here the real constant could come from.
+     *
+     * WHAT IT REPLACES is worth naming: run detail used to be assembled by reading SQLite from
+     * inside the router. Routing it through this id is what makes the same durable read available
+     * to the CLI, MCP and chat instead of to the browser alone.
+     */
+    readonly runsDetailFunctionId: string;
+    /** The evidence op identity supplied by the same composition as the detail reader. */
+    readonly runsEvidenceFunctionId: string;
+    /**
+     * The agent package's `runs.artifact` id, on `runsDetailFunctionId`'s exact footing (405 D-13).
+     *
+     * SUPPLIED BY THE COMPOSITION, NEVER SPELLED HERE, for the reason its four neighbours are — and
+     * for one more that is specific to this route: the artifact arm serves BYTES, and the alternative
+     * to dispatching them through the function layer is this package constructing the evidence store
+     * and reading a file. That would be a private store read no roster row covers and no audit sink
+     * sees, on a path whose two inputs both arrive from a URL. Routing it through an id is what makes
+     * the containment rule the store's own and the capability one the CLI, MCP and 408's embed reach
+     * the same way.
+     */
+    readonly runsArtifactFunctionId: string;
+    /**
+     * The agent package's `analysis.get` id, on `runsArtifactFunctionId`'s exact footing (406 D-04).
+     *
+     * SUPPLIED BY THE COMPOSITION, NEVER SPELLED HERE, for the reason its five neighbours are: the
+     * op id is the agent package's constant, a string literal in this package would be a second
+     * declaration of a capability's name free to drift from the spec that answers to it, and this
+     * package may not import `@vostride/agent-qa-agent` at all (validate:arch) — so there is nowhere
+     * here the real constant could come from.
+     *
+     * WHAT IT SERVES is the failure view: the resolved verdicts and rendered sentences a person
+     * reads inside each failed member's group, on BOTH doors through one adapter. `analysis.get` is
+     * the single producer of those sentences (389 D-11), so routing the page's read through this id
+     * is what keeps the browser, the CLI, chat and 408's embed reading one answer.
+     */
+    readonly analysisGetFunctionId: string;
+    /**
+     * The agent package's `runs.knowledge` id, on `analysisGetFunctionId`'s exact footing
+     * (2026-08-29, 407-01 D-05).
+     *
+     * THE SIXTH ID THE RUN-SERVICE ROUTES DISPATCH, supplied by the composition and never spelled
+     * here, for the reason its five neighbours are: the op id is the agent package's constant, a
+     * string literal in this package would be a second declaration of a capability's name free to
+     * drift from the spec that answers to it, and this package may not import
+     * `@vostride/agent-qa-agent` at all (validate:arch) — so there is nowhere here the real constant
+     * could come from.
+     *
+     * WHAT IT SERVES is the Knowledge panel: what a run USED (the brief channels served per step,
+     * the serve-time trace behind each, procedure replay and hint use, the recorded retrieval rung)
+     * and what it LEARNED (curation counts, the record changes attributable to it, canary outcomes).
+     * `runs.knowledge` is the single producer of that whole view (407 D-05), so routing the page's
+     * read through this id is what keeps the browser, the CLI, MCP and chat reading one answer
+     * instead of a page composing it from N per-step calls that can disagree.
+     */
+    readonly runsKnowledgeFunctionId: string;
+    /** 2026-09-08, 419 D-13: the eighth op id arrives as data, on the knowledge id's footing. */
+    readonly runsMarkFunctionId: string;
+    /** 2026-09-15, 423-21 D-18: the marks-history read id, supplied as data like its neighbours. */
+    readonly runsMarksHistoryFunctionId: string;
+    /** 2026-09-15, 423-21 D-18: the read-tier mark consequence preview id. */
+    readonly runsMarkPreviewFunctionId: string;
+    /**
+     * `invokeFunction`, bound by the composer. THE one door call.
+     *
+     * `input` IS `unknown` (404-05). Every op this seam carries has its own strict input schema.
+     * Narrowing here would mean this package describing other packages' input contracts — and the
+     * real `invokeFunction` has always taken `unknown`, because the op's own schema is what validates
+     * it, once, inside the invocation.
+     */
+    invokeFunction(registry: AgentRegistryHandle, functionId: string, input: unknown, caller: FunctionCaller): Promise<unknown>;
+}
+
+/** One viewer's callback. Runs on the EMITTER'S thread — see `publish`. */
+type PostProcessingListener = (envelope: RunEventEnvelope) => void;
+interface PostProcessingRelay {
+    /**
+     * Hand one chip envelope to whoever is watching THAT run.
+     *
+     * NEVER THROWS. The caller is the chip emitter, mid-`append`, immediately after the line is on
+     * disk: the trail is the record and a viewer's fault is not the emitter's problem (the run bus's
+     * own subscriber-fault discipline, applied one layer out). A listener that throws is skipped for
+     * this delivery and the remaining listeners still receive it — dropping the rest would let one
+     * broken page silence every other page watching the same run.
+     */
+    publish(envelope: RunEventEnvelope): void;
+    /** Watch one run. Returns its own disposer, which is idempotent. */
+    subscribe(runId: string, listener: PostProcessingListener): () => void;
+    /** How many listeners that run has — so a host can assert a closed stream released its own. */
+    listenerCount(runId: string): number;
+}
+declare function createPostProcessingRelay(): PostProcessingRelay;
+
+/**
+ * What starting a run needs from the composition, as data rather than as a live handle.
+ *
+ * 2026-10-01 (432-21, D-12): the matched token's `trustScope` and `clientId` are deleted with the
+ * token. A start carries the caller's pattern set and nothing about who the caller is.
+ */
+interface RunServiceStartInput {
+    /** The pattern set the caller asked for; absent means the configured default set. */
+    readonly patterns?: readonly string[];
+}
+/**
+ * Everything this door reaches the world through (D-02).
+ *
+ * ALL ARE INJECTED, and the injection is what makes the module mountable: the implementations name
+ * `invokeFunction`, `runs.start` and a composed local host, all of it vocabulary this package may
+ * not import. `InProcessRunStarter` is the shape precedent one directory over. 2026-10-01 (432-21,
+ * D-12): `verifyBearer` is deleted; the same-site guard needs no port.
+ */
+interface RunServicePorts {
+    /**
+     * Start a run and return the acknowledgment.
+     *
+     * REJECTION IS NOT "the run failed" — a failing run still acknowledges. A rejection is a denial,
+     * a refused request field, an input error or a crash.
+     */
+    invokeRunStart(input: RunServiceStartInput): Promise<RunStartAcknowledgement>;
+    /** The started run's session, or nothing if this process never started that run. */
+    attach(runId: string): RunSession | undefined;
+    /** The measured readiness facts `/ok` reports (D-15). */
+    readiness(): RunServiceReadiness;
+    /**
+     * Mint a live-view URL for one handle of a run (403 D-03).
+     *
+     * REQUIRED, NOT OPTIONAL, and that is a decision rather than an oversight. An optional member is
+     * a member a composition can forget, and the failure mode of forgetting it here is a 404 that
+     * reads exactly like "no such route" — which is what a door with no live view is indistinguishable
+     * from. A composition that cannot mint supplies a function that REJECTS with a
+     * `LiveViewUnavailableError`-named error, which the arm maps to 503 `live_view_unavailable`: an
+     * honest host fact, said out loud, once, in the vocabulary the local door already uses.
+     *
+     * The minted token's own subject (run, handle) and expiry are checked by the live-view validator
+     * independently of who asked (D-13). 2026-10-01 (432-21, D-12): the bearer's trust scope this mint
+     * used to run under is deleted; the composition supplies the one caller it runs under.
+     */
+    mintLiveUrl(input: MintLiveUrlInput): Promise<RunsLiveUrlResult>;
+    /**
+     * The injected agent host the two READ rows dispatch through (405-05, D-12/D-13).
+     *
+     * OPTIONAL, unlike `mintLiveUrl` above, and the asymmetry is deliberate rather than an
+     * oversight. `mintLiveUrl` is required because a composition that forgot it would answer a 404
+     * indistinguishable from an unserved path — but the argument runs the other way here: a host
+     * genuinely composed without a function registry (a bare mount, this file's own fixtures) has no
+     * capability to reach, and the honest answer is the SAME 503 `agent_host_unavailable` the local
+     * door already gives for exactly this state. One word, one meaning, both doors.
+     *
+     * It is a HANDLE and nothing else — this package may not name the agent packages, so what
+     * crosses is the seam `chat/host.ts` declares and the op ids the composition supplies as data.
+     */
+    readonly agentHost?: AgentHost;
+}
+/** What minting one `liveUrl` needs from a request, as data: the subject, and nothing else. */
+interface MintLiveUrlInput {
+    readonly runId: string;
+    readonly handle: number;
+}
+/** Which handler a table row reaches. A closed union, so a row with no arm is a type error. */
+type RunServiceRouteHandlerName = 'start' | 'events' | 'liveUrl' | 'detail' | 'evidence' | 'artifact' | 'analysis' | 'marks' | 'markPreview' | 'ok';
+interface RunServiceRouteRow {
+    readonly method: 'GET' | 'POST';
+    /** The literal path, or — for a templated route — its `:param` shape. */
+    readonly path: string;
+    readonly handler: RunServiceRouteHandlerName;
+    /** Present only on a templated route; the matcher uses it instead of `path`. */
+    readonly pattern?: RegExp;
+}
+declare const RUN_SERVICE_START_ROUTE = "/run";
+declare const RUN_SERVICE_EVENTS_TEMPLATE = "/run/:runId/events";
+/**
+ * The MINT (403 D-03, Q3) — the remote half of the pair whose local half is
+ * `GET /api/runs/:runId/live-url`.
+ *
+ * SAME SHAPE AS THE EVENTS ROUTE ONE LINE UP, deliberately: a caller addresses a run it started by
+ * id and asks this door for one thing about it per route. Since 432-21 the two doors differ in
+ * nothing but the path — the same op, the same caller shape, the same result and fragment carriage.
+ */
+declare const RUN_SERVICE_LIVE_URL_TEMPLATE = "/run/:runId/live-url";
+/**
+ * Readiness (D-15) — behind the same-site guard, like every other route on this door.
+ *
+ * An `/ok` that answered before the guard would tell a page on another origin that this process is
+ * an agent-qa run service and that it is up. (Until 432-21 the guard here was the bearer verdict,
+ * and the preflight was liveness and early token validation in one round-trip.)
+ */
+/**
+ * The durable run-detail READ (405-05, D-12 / 402 D-16) — the remote twin of the local door's
+ * `GET /api/runs/:id/detail`.
+ *
+ * IT DISPATCHES THROUGH THE SAME ADAPTER THE LOCAL DOOR CALLS. `serveRunDetailRead` is one
+ * function, so the two doors cannot come to disagree about what a run's projection is; a second
+ * spelling here would agree on the day it was written and be a wire-contract fork thereafter.
+ *
+ * THIS ROW IS MASKED, and deliberately. It is a machine wire like `/run/:runId/events` one line up
+ * — its consumer (the CLI's own `emitHuman`, 408's embed) is where a person meets the text, and
+ * that consumer is the display boundary. The alternative would restore declared secrets onto a
+ * machine wire, extending the disclosure surface to every client and every intermediary, which is
+ * not what "the browser is never the boundary" (400-06) asks for. 405-10
+ * applies the unmask seam to the LOCAL door only and enrols this row on the masked side.
+ */
+declare const RUN_SERVICE_DETAIL_TEMPLATE = "/run/:runId/detail";
+declare const RUN_SERVICE_EVIDENCE_TEMPLATE = "/run/:runId/evidence";
+/**
+ * The ref-resolving artifact READ (405-05, D-12 / 402 D-16) — the remote twin of the local door's
+ * `GET /api/runs/:runId/artifacts/:sha`, and the row 402 D-16 named by anticipation.
+ *
+ * TWO CAPTURES, `[^/]+` ON BOTH. The runId is decoded and the sha is not: a content address is 64
+ * characters from `[0-9a-f]`, none of which percent-encoding can represent differently, so a sha
+ * segment that needed decoding is already not one.
+ *
+ * MASKED, LIKE ITS SIBLING AND MORE SO: these are BYTES. The unmask seam never touches an artifact
+ * body on any door (D-09) — a screenshot is not text and there is nothing in it to restore.
+ */
+declare const RUN_SERVICE_ARTIFACT_TEMPLATE = "/run/:runId/artifacts/:sha";
+/**
+ * The run-ANALYSIS read (406-01, D-04) — the remote twin of the local door's
+ * `GET /api/runs/:id/analysis`.
+ *
+ * IT DISPATCHES THROUGH THE SAME ADAPTER THE LOCAL DOOR CALLS, for the reason its detail sibling
+ * does: `serveRunAnalysisRead` is one function, so the two doors cannot come to disagree about
+ * what a run's analysis is.
+ *
+ * THIS ROW IS MASKED, AND FOR THE REASON ITS SIBLING IS. The verdict sentence quotes the failing
+ * step's recorded error, which carries declared placeholders at rest; restoring them onto a
+ * machine wire would hand them to every client and every intermediary, and this row's
+ * consumer — the CLI's own emit, 408's embed — is where a person meets the text. The dispatch
+ * below passes no `boundary`, and the option's `'machine'` default is what keeps it masked.
+ */
+declare const RUN_SERVICE_ANALYSIS_TEMPLATE = "/run/:runId/analysis";
+/** 2026-09-15, 423-21 D-18: runs.marks.history and runs.mark.preview behind the same guard. */
+declare const RUN_SERVICE_MARKS_TEMPLATE = "/run/:runId/marks";
+declare const RUN_SERVICE_MARK_PREVIEW_TEMPLATE = "/run/:runId/mark-preview";
+declare const RUN_SERVICE_OK_ROUTE = "/ok";
+/**
+ * EVERY PATH THIS DOOR ANSWERS, as data the dispatch reads (the chat door's own idiom).
+ *
+ * WHY A TABLE AND NOT THREE ARMS. The same-site guard below is applied to the REQUEST, above this
+ * table, so a route added tomorrow inherits it by construction. The table is what makes that
+ * inheritance AUDITABLE from outside: because dispatch reads it, a route not in it is unreachable,
+ * so a census cell can enumerate this array and drive every row cross-site — and a newly added
+ * route cannot escape that corpus by nobody noticing it.
+ */
+declare const RUN_SERVICE_ROUTE_TABLE: readonly RunServiceRouteRow[];
+/** What a matched row carries: the row itself and whatever its pattern captured. */
+interface RunServiceRouteMatch {
+    readonly row: RunServiceRouteRow;
+    /** The raw, still-ENCODED capture groups. Decoding is the handler's business, and it can throw. */
+    readonly params: readonly string[];
+}
+/** Resolve a request to a table row, or to nothing. The dispatch's only route lookup. */
+declare function matchRunServiceRoute(method: string | undefined, path: string): RunServiceRouteMatch | undefined;
+/**
+ * Whether a path belongs to this door — the MOUNT's whole question, and method-blind on purpose.
+ *
+ * A host consults this before its own routing so that every request to a service path, including
+ * an `OPTIONS` preflight and a method this table has no row for, is answered by this door rather
+ * than by the host's generic handling. That is what keeps the host's wildcard CORS preflight and
+ * its SPA fallback away from this surface.
+ *
+ * DERIVED FROM THE TABLE, never a second list: the prefixes are read off the rows, so a route
+ * added above is mounted the same commit.
+ */
+declare function ownsRunServicePath(path: string): boolean;
+interface RunServiceRouter {
+    (req: IncomingMessage, res: ServerResponse): void;
+    /** Live SSE connections — so a host can assert this door leaks none on teardown. */
+    openStreamCount(): number;
+}
+/**
+ * Where a stream request asked to resume from. Three arms, and the count is the contract.
+ *
+ * `start` is "the caller has observed nothing", `after` carries the last seq it DID observe, and
+ * `invalid` is a fact about the caller's own input. There is deliberately no fourth arm meaning
+ * "unparseable, serve them from the beginning": silently restarting a resume at seq 1 would
+ * re-deliver every envelope the caller already has, and silently serving from the floor would hide
+ * a gap — the two answers D-13 refuses by name.
+ */
+type ResumePoint = {
+    readonly kind: 'start';
+} | {
+    readonly kind: 'after';
+    readonly seq: number;
+} | {
+    readonly kind: 'invalid';
+};
+/**
+ * The DENIAL this rejection is, if it is one — read structurally, never by class (402-06, T-402-22).
+ *
+ * ON `dashboardNeutralReasonOf`'S EXACT PRECEDENT (`execution/in-process-backend.ts`), and for the
+ * same architectural reason: the rejection is a `RunDeniedError` minted in `agent-local`, and this
+ * package may not import `agent`, `agent-local` or `safety` — `pnpm validate:arch` is the
+ * mechanical proof.
+ *
+ * THE DISCRIMINATOR IS `neutralReason`, DELIBERATELY. Only a run denial carries it: an
+ * unrecognised request field, an input error and "the host was asked to start a run before it was
+ * composed" carry none, and those are exactly the rejections that must stay a 500 with no words on
+ * them. Keying on the class NAME would be a string compare against another package's private
+ * vocabulary.
+ *
+ * 2026-10-01 (432-19, D-15): there is no remedy list to validate or project. The production refusal
+ * never carried one, and the remedy vocabulary left with the execution gate.
+ */
+declare function runDenialOf(error: unknown): RunServiceDenialBody | undefined;
+declare function createRunServiceRoutes(ports: RunServicePorts): RunServiceRouter;
+
+interface StartServerOptions {
+    db: DashboardDatabase;
+    port?: number;
+    /**
+     * The interface this server binds (402-05, D-07 — INVK-03).
+     *
+     * DEFAULTS TO LOOPBACK, and a non-loopback value is REFUSED before anything listens — with no
+     * exemption. This is BREAKING for anyone who relied on the previous `server.listen(port)`, which
+     * bound every interface, and there is no migration flag: the v2 ethos ships no back-compat shim
+     * for a hole. Remote access goes through an authenticating proxy (432 D-13's forward note).
+     */
+    host?: string;
+    uiDir?: string;
+    /**
+     * Where this workspace writes run artifacts (`services.dashboard.artifactsDir`).
+     *
+     * ACCEPTED AND NOT READ BY THIS SERVER SINCE 405-07 (D-14). It used to be resolved into a
+     * screenshots and a videos root that two path-serving routes and the run-deletion sweep read.
+     * Refs are the only artifact addressing now, and the bytes are reached through the
+     * `runs.artifact` op over the evidence store's own layout. The option stays declared because it
+     * is a user-facing config key the RECORDING path still writes under; the dashboard simply no
+     * longer serves or deletes anything by path.
+     */
+    artifactsDir?: string;
+    workspacePaths?: ResolvedWorkspacePaths;
+    configPath?: string;
+    declaredSecretMask: MaskFn;
+    llmConfig?: DashboardLLMConfig & {
+        vision?: {
+            screenshotSize?: number;
+            effectiveResolution?: number;
+        };
+    };
+    authFetch?: typeof globalThis.fetch;
+    /**
+     * The composed agent host the chat door dispatches through (400-01, D-01).
+     *
+     * INJECTED by whoever starts this server — in production `agent-qa dashboard`, which composes the
+     * SAME port set `agent-qa chat` does and hands it over, so the two interactive doors have one
+     * answer to "what can a conversation do" (D-08). Absent leaves the chat routes answering 501 by
+     * name: the door exists, this process was started without a host. See `chat/host.ts`.
+     */
+    agentHost?: AgentHost;
+    /**
+     * The backend every dashboard run executes through (401-07, D-01/D-09/D-10 — INVK-01).
+     *
+     * INJECTED, ON `agentHost`'s OWN IDIOM AND FOR ITS OWN REASON. The implementation that starts a
+     * run names `runs.start`, `invokeFunction` and the composed local host — all of it
+     * `@vostride/agent-qa-agent*` vocabulary this package may not import (validate:arch). So
+     * `agent-qa dashboard` composes it in the process that runs this server and hands it over, which
+     * is what makes the run button one more caller of the op chat already uses rather than a
+     * dashboard carve-out around the gates.
+     *
+     * ABSENT DEGRADES BY NAME, exactly as it did when the CLI binary could not be resolved: the
+     * execution routes answer 503 and the queue's execute handler does nothing. A dashboard started
+     * without a run door is a dashboard that cannot run tests, and it says so.
+     */
+    executionBackend?: ExecutionBackend;
+    /**
+     * The run service's ports (402-01, D-02/D-06 — INVK-03).
+     *
+     * INJECTED, ON `agentHost`'s AND `executionBackend`'s OWN IDIOM AND FOR THEIR OWN REASON. The
+     * implementations name `runs.start`, `invokeFunction` and the composed local host — all of it
+     * vocabulary this package may not import (validate:arch). So `agent-qa dashboard` composes them
+     * in the process that runs this server and hands them over, which is what makes the run service
+     * a mountable module rather than a fourth process.
+     *
+     * ABSENT MEANS THE SERVICE IS NOT MOUNTED, and `/run` and its neighbours reach whatever the
+     * static/SPA handling below does with an unknown path. 2026-10-01 (432-21, D-12): `agent-qa
+     * dashboard` supplies it unconditionally now. It used to mount only when a run-service credential
+     * was declared, and those credentials are deleted; the door is guarded by the same-site check
+     * and the loopback bind like every other door here. Absent is a bare in-process mount's posture.
+     */
+    runService?: RunServicePorts;
+    /**
+     * The run service's readiness predicate, served WITHOUT a token on the local dashboard API
+     * (402-05, D-15 — `GET /api/run-readiness`).
+     *
+     * SEPARATE FROM `runService` ABOVE AND NOT DERIVED FROM IT, because a mount without the service
+     * still has a browser that needs an honest readiness answer rather than a 404. `agent-qa
+     * dashboard` supplies the very same function object it put on `runService.readiness`: one
+     * predicate, two doors. (Until 432-21 the service was absent whenever no credential was declared.)
+     */
+    runServiceReadiness?: () => RunServiceReadiness;
+    /**
+     * The run id → live `RunSession` lookup, as a FIRST-CLASS option (403 D-14 — WINDOWS #264).
+     *
+     * SEPARATE FROM `runService` AND NOT DERIVED FROM IT, on `runServiceReadiness`'s exact argument
+     * one field up. The derivation `runService?.attach` is what made the local run-stream door
+     * answer 503 about runs this very process was executing: until 432-21 `composeRunServicePorts`
+     * ran only when `runServiceTokens` were declared, so the DEFAULT zero-token dashboard composed no
+     * registry at all and the local door had nothing to attach to. `agent-qa dashboard` supplies this
+     * from a registry hoisted above the door.
+     *
+     * The legacy derivation still applies when this is absent, so an in-process caller that only
+     * passes `runService` keeps working byte-for-byte.
+     */
+    runServiceAttach?: (runId: string) => RunSession | undefined;
+    /**
+     * The live-view seam (403 D-03/D-06): the function layer's validator, by reference, and the
+     * mint dispatched through the registry.
+     *
+     * ABSENT MEANS NO LIVE VIEW IS SERVED — the embed route is not registered, the frame socket
+     * refuses the upgrade, and `GET /api/runs/:runId/live-url` answers 503 by name. This server
+     * holds NO signing key and NO token parse of its own; both are the function layer's, handed in.
+     */
+    liveView?: {
+        validate(token: string, expect: {
+            subject: LiveViewSubjectRef;
+            now: number;
+        }): LiveUrlVerdict;
+        mintLiveUrl(runId: string, handle: number): Promise<RunsLiveUrlResult>;
+        /**
+         * The `editor.liveurl` mint, dispatched through the registry (428 D-07). ABSENT MEANS NO
+         * EDITOR VIEW IS MINTED, and `GET /api/live-editor/sessions/:id/live-url` answers 503 by name.
+         */
+        mintEditorLiveUrl?(sessionId: string): Promise<EditorLiveUrlResult>;
+    };
+    /**
+     * The editor-subject registry (428 D-07): the session manager registers each live editor session
+     * here and the frame socket attaches editor subjects through it.
+     *
+     * ABSENT MEANS NO EDITOR SUBJECT IS SERVED ON THE FRAME SOCKET. `agent-qa dashboard` creates one
+     * registry and hands the same object to the live-view composition and to this server.
+     */
+    liveEditorSubjects?: LiveEditorSubjects;
+    /**
+     * The in-process post-processing chip relay (404-05, D-16).
+     *
+     * INJECTED, ON `agentHost`'s OWN IDIOM AND FOR ITS OWN REASON. The PUBLISHER is the CLI's
+     * post-run chip emitter, in this same process, and this package may not import it — so
+     * `agent-qa dashboard` creates one relay, hands `relay.publish` to the run door's bridge as the
+     * emitter's second sink and hands the relay itself here. It has to be the SAME object: a relay
+     * built inside this function would be a registry nothing publishes to, and the stream door would
+     * heartbeat forever at a page whose chips are demonstrably moving.
+     *
+     * ABSENT MEANS NO PUSH CHANNEL, and `GET /api/runs/:id/post-processing/stream` answers 503 by
+     * name. The READ route needs none of this and keeps working: polling is the floor the whole
+     * design rests on, and the stream is the optimisation over it.
+     */
+    postProcessingRelay?: PostProcessingRelay;
+}
+declare function startServer(opts: StartServerOptions): Promise<{
+    server: Server;
+    port: number;
+    close: () => void;
+}>;
+
+interface AppiumLeaseOwner {
+    runId: string;
+    platform: 'android' | 'ios';
+}
+interface AppiumLease extends AppiumLeaseOwner {
+    acquiredAt: string;
+}
+declare class AppiumManager {
+    private process;
+    private port;
+    private ready;
+    private startPromise;
+    private managed;
+    private startupTimeoutMs;
+    private pollIntervalMs;
+    private anonymousRefCount;
+    private leases;
+    private logLevel;
+    private appiumResolver;
+    constructor(opts?: {
+        port?: number;
+        startupTimeoutMs?: number;
+        pollIntervalMs?: number;
+        logLevel?: 'normal' | 'debug';
+        appiumResolver?: () => ResolvedAppiumExecutable;
+    });
+    acquire(): Promise<void>;
+    release(): void;
+    acquireLease(owner: AppiumLeaseOwner): Promise<void>;
+    releaseLease(runId: string, reason?: string): boolean;
+    releaseAllLeases(reason?: string): string[];
+    ensureRunning(): Promise<void>;
+    checkStatus(): Promise<boolean>;
+    private startAndWait;
+    private performShutdown;
+    private maybeShutdownAfterRelease;
+    shutdown(): void;
+    getUrl(): string;
+    getPort(): number;
+    isManaged(): boolean;
+    getRefCount(): number;
+    getLeaseCount(): number;
+    getLeases(): AppiumLease[];
+    hasLease(runId: string): boolean;
+}
+
+type ApplyChangesOutcome = {
+    kind: 'ok';
+    revision: string;
+    baseRevision: string;
+    priors?: ConfigPriors;
+} | {
+    kind: 'refused';
+    error: Exclude<ConfigWriteRefusal, 'write_failed'>;
+    issues?: ConfigWriteIssue[];
+    /** The field an `expect` found changed. */
+    path?: ConfigPathSegment[];
+};
+type FieldState = {
+    present: false;
+} | {
+    present: true;
+    value: unknown;
+};
+/**
+ * What one change found and left at the field it touched (429-11 D-24). The nodes are the file's
+ * own, so a restore brings back real secrets and comments rather than anything the page holds.
+ */
+type ConfigPrior = {
+    kind: 'entry';
+    array: ConfigPathSegment[];
+    name: string;
+    index: number;
+    node: Node;
+} | {
+    kind: 'path';
+    path: ConfigPathSegment[];
+    before: Node | null | undefined;
+    after: FieldState;
+};
+type ConfigPriors = readonly ConfigPrior[];
+/** A whole-document replacement, checked against the bytes the caller read (432-07 D-05). */
+type ReplaceDocumentOutcome = {
+    kind: 'ok';
+    revision: string;
+    baseRevision: string;
+} | {
+    kind: 'refused';
+    error: 'file_changed';
+    revision: string;
+} | {
+    kind: 'refused';
+    error: 'marker_written_back';
+    message: string;
+};
+type RestorePriorsOutcome = {
+    kind: 'ok';
+    revision: string;
+} | {
+    kind: 'refused';
+    error: 'undo_conflict' | 'file_invalid';
+};
+type ConfigReadOutcome = {
+    kind: 'ok';
+    config: Record<string, unknown>;
+    raw: string;
+    revision: string;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'file_invalid';
+    message: string;
+    revision: string;
+};
+/** One line of the config file, as the declared mask shows it. */
+interface ConfigFileLine {
+    n: number;
+    text: string;
+}
+type MaskedConfigOutcome = {
+    kind: 'ok';
+    config: Record<string, unknown>;
+    revision: string;
+    lines: ConfigFileLine[];
+    fileIssues: ConfigWriteIssue[];
+} | {
+    kind: 'file_invalid';
+    message: string;
+    revision: string;
+};
+/** Run `work` in this path's turn. The queue moves on however `work` settles. */
+declare function serializeConfigWrite<T>(configPath: string, work: () => Promise<T>): Promise<T>;
+declare class ConfigFileInvalidError extends Error {
+    constructor(message: string);
+}
+/**
+ * The config's values for a reader that only needs them (429-32, Pitfall 3): a missing file reads
+ * as empty, and a file that does not parse is an error rather than the part of it yaml recovers.
+ */
+declare function readConfigValues(manager: ConfigManager): Promise<Record<string, unknown>>;
+declare class ConfigManager {
+    private configPath;
+    readonly mask: MaskFn;
+    constructor(configPath: string, mask: MaskFn);
+    static addsShownMarker(current: Uint8Array | undefined, next: Uint8Array): boolean;
+    readWithRevision(): Promise<ConfigReadOutcome>;
+    readMasked(): Promise<MaskedConfigOutcome>;
+    private maskSummary;
+    private readParsed;
+    applyChanges(changes: readonly ConfigChange[], options?: {
+        capturePriors?: boolean;
+    }): Promise<ApplyChangesOutcome>;
+    restorePriors(priors: ConfigPriors): Promise<RestorePriorsOutcome>;
+    replaceDocument(expectedRevision: string, content: Uint8Array): Promise<ReplaceDocumentOutcome>;
+    private serialized;
+    private restorePriorsOnce;
+    private applyChangesOnce;
+    private writeAtomic;
+    private writeTarget;
+}
+
+type LiveSessionLLMConfig = DashboardLLMConfig & {
+    vision?: {
+        screenshotSize?: number;
+        effectiveResolution?: number;
+    };
+    /** The model entry's own `vision` flag, when the config sets it (439 D-19). */
+    modelVision?: boolean;
+};
+interface LiveDraftMetadata {
+    testName: string;
+    testContext?: string;
+}
+interface EntityRef {
+    type: 'suite' | 'test';
+    id: string;
+}
+interface LiveExecutionLog {
+    id: string;
+    type: 'hook' | 'appium-script' | 'runjs';
+    name: string;
+    hookId?: string | null;
+    phase: 'setup' | 'teardown' | 'inline';
+    status: 'passed' | 'failed';
+    duration: number;
+    stdout: string | null;
+    stderr: string | null;
+    returnData: unknown | null;
+    variables: Record<string, string> | null;
+    createdAt: string;
+}
+interface LiveSubActionData {
+    index: number;
+    observation: string;
+    reasoning: string;
+    plannedAction: unknown;
+    result: 'success' | 'failure' | 'no-input' | 'in-progress';
+    error?: string;
+    screenStateBefore: string;
+    screenStateAfter?: string;
+    confidence?: number;
+    verifierReasoning?: string;
+    cached: boolean;
+    tokenUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    phaseDurations?: {
+        observe?: number;
+        plan?: number;
+        execute?: number;
+        verify?: number;
+    };
+    annotation?: StepAnnotation;
+    screenContextBefore?: string;
+    screenContextAfter?: string;
+    data?: unknown;
+}
+interface LiveStepResultPayload {
+    status: 'passed' | 'failed' | 'cancelled';
+    duration?: number;
+    error?: string;
+    capturedVariables?: Record<string, string>;
+    variableSnapshot?: Record<string, {
+        value: string;
+        source: string;
+    }>;
+    originalStepName?: string;
+    consoleLogs?: ConsoleLogEntry[];
+    networkLogs?: NetworkLogEntry[];
+    executionLogs?: LiveExecutionLog[];
+    subActionsData?: LiveSubActionData[];
+}
+interface LiveSuiteHookOwner {
+    scope: 'suite';
+}
+interface LiveTestOwner {
+    scope: 'test';
+    testExecutionId: string;
+    testIndex: number;
+    testId: string;
+    testName: string;
+}
+type LiveHookOwner = LiveSuiteHookOwner | LiveTestOwner;
+interface LiveHookPayload {
+    executionId: string;
+    hookId: string;
+    hookName: string;
+    phase: 'setup' | 'teardown';
+    owner: LiveHookOwner;
+    status: 'running' | 'passed' | 'failed';
+    duration?: number;
+    stdout?: string | null;
+    stderr?: string | null;
+    variables?: Record<string, string> | null;
+    error?: string;
+    createdAt: string;
+}
+interface LiveTestExecutionPayload {
+    testExecutionId: string;
+    testIndex: number;
+    testId: string;
+    testName: string;
+}
+interface LiveTestStepPayload extends LiveTestExecutionPayload {
+    stepIndex: number;
+    stepInstruction: string;
+}
+interface LiveTestResultPayload {
+    status: 'passed' | 'failed' | 'cancelled';
+    duration: number;
+    error?: string;
+    setupHookExecutions: LiveHookPayload[];
+    stepResults: LiveStepResultPayload[];
+    teardownHookExecutions: LiveHookPayload[];
+}
+type ServerMessage = {
+    type: 'session-ready';
+    sessionId: string;
+    platform: string;
+    interactive: boolean;
+    error?: string | null;
+} | {
+    type: 'hook-start';
+    hook: LiveHookPayload;
+} | {
+    type: 'hook-complete';
+    hook: LiveHookPayload;
+} | {
+    type: 'step-phase';
+    phase: string;
+    data?: unknown;
+} | {
+    type: 'step-complete';
+    result: LiveStepResultPayload;
+} | {
+    type: 'step-cancelled';
+} | {
+    type: 'step-error';
+    error: string;
+} | {
+    type: 'test-start';
+    test: LiveTestExecutionPayload;
+} | {
+    type: 'test-step-start';
+    step: LiveTestStepPayload;
+} | {
+    type: 'test-step-phase';
+    step: LiveTestStepPayload;
+    phase: string;
+    data?: unknown;
+} | {
+    type: 'test-step-complete';
+    step: LiveTestStepPayload;
+    result: LiveStepResultPayload;
+} | {
+    type: 'test-step-cancelled';
+    step: LiveTestStepPayload;
+} | {
+    type: 'test-step-error';
+    step: LiveTestStepPayload;
+    error: string;
+} | {
+    type: 'test-complete';
+    test: LiveTestExecutionPayload;
+    result: LiveTestResultPayload;
+} | {
+    type: 'test-error';
+    test: LiveTestExecutionPayload;
+    error: string;
+} | {
+    type: 'session-state';
+    state: SessionState;
+} | {
+    type: 'session-terminated';
+} | {
+    type: 'browser-disconnected';
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'step-busy';
+    currentStep: string;
+} | {
+    type: 'navigate-complete';
+    url: string | null;
+} | {
+    type: 'device-logs';
+    entries: Array<{
+        level: string;
+        message: string;
+        timestamp: number;
+    }>;
+} | {
+    type: 'aria-tree';
+    tree: string;
+};
+interface SessionState {
+    sessionId: string;
+    platform: 'web' | 'android' | 'ios';
+    targetName?: string | null;
+    status: 'idle' | 'executing' | 'disconnected';
+    currentStep: string | null;
+    currentUrl: string | null;
+    stepsExecuted: number;
+    createdAt: number;
+    interactive: boolean;
+    terminalError: string | null;
+}
+/**
+ * What the create door found the current config declares about the session's target (432 D-18).
+ *
+ * It can only add a refusal: `initialize` refuses any name here unless the config it reads itself
+ * opts in. There is deliberately no opt-in field, so nothing a caller passes can allow production.
+ */
+interface LiveProductionFinding {
+    readonly productionTargetNames: readonly string[];
+}
+interface LiveSessionConfig {
+    platform: 'web' | 'android' | 'ios';
+    targetName?: string;
+    production?: LiveProductionFinding;
+    /** 436 D-03: resolved at the create door from the project config and the edited entity. */
+    plannerLimits?: PlannerLimits;
+    /** 436 D-03: per executed test, project then suite then the test's own `use`. */
+    plannerLimitsForTest?: (testId: string) => Promise<PlannerLimits>;
+    llmConfig: LiveSessionLLMConfig;
+    authFetch?: typeof globalThis.fetch;
+    envVars?: Record<string, string>;
+    secretStore?: SecretStore;
+    secretRedactor?: SecretRedactor;
+    setupHooks?: string[];
+    teardownHooks?: string[];
+    resolvedHooks?: Map<string, HookDefinition>;
+    hookRegistryError?: string;
+    url?: string;
+    headless?: boolean;
+    useDeviceName?: string;
+    appState?: 'preserve' | 'reset';
+    bundleId?: string;
+    appPackage?: string;
+    appActivity?: string;
+    device?: {
+        name: string;
+        platformVersion?: string;
+        appPath?: string;
+        browserName?: string;
+        appPackage?: string;
+        appActivity?: string;
+        bundleId?: string;
+        udid?: string;
+        avd?: string;
+        appiumUrl?: string;
+    };
+}
+/**
+ * The close code the control socket uses for a session this process does not hold (428 P5), so the
+ * page can say the session ended instead of "Disconnected". The dashboard UI spells the same number;
+ * Plan 23 pins the two equal.
+ */
+declare const LIVE_EDITOR_UNKNOWN_SESSION_CLOSE_CODE = 4404;
+/**
+ * The close code for a control socket a newer one has replaced (428 WR-01). The session is still
+ * held; this socket no longer drives it, so the page must not reconnect and take it back. The
+ * dashboard UI spells the same number.
+ */
+declare const LIVE_EDITOR_SUPERSEDED_CLOSE_CODE = 4409;
+
+/** Why the session let go of a control socket: a newer one replaced it, or the session ended. */
+type LiveAttachmentRelease = 'superseded' | 'ended';
+interface LiveSessionDeps {
+    appiumManager?: AppiumManager;
+    configManager?: ConfigManager;
+    configPath?: string;
+}
+interface LiveStepExecutionResult extends StepResult {
+    executionLogs?: LiveExecutionLog[];
+    subActionsData?: LiveSubActionData[];
+}
+declare class LiveSession {
+    private deps;
+    readonly sessionId: string;
+    status: 'idle' | 'executing' | 'disconnected' | 'terminated';
+    private abortController;
+    stepsExecuted: number;
+    createdAt: number;
+    private adapter;
+    private planner;
+    private verifier;
+    private modelProfiles;
+    private storageStateStore;
+    private model;
+    private variableStore;
+    private previousSteps;
+    private currentStep;
+    private platform;
+    private targetName;
+    private currentUrl;
+    private executing;
+    private idleTimer;
+    private _modelName;
+    private vision;
+    private visionGate;
+    private plannerLimits;
+    private plannerLimitsForTest;
+    private readyForInteraction;
+    private terminalError;
+    private setupHooks;
+    private teardownHooks;
+    private resolvedHooks;
+    private hookRegistryError;
+    private pendingMessages;
+    private messageSink;
+    private hookCaptures;
+    private mobileAppiumLease;
+    private secretStore;
+    private secretRedactor;
+    private liveHub;
+    private attachment;
+    private resolveEnded;
+    private readonly ended;
+    private cleanupRun;
+    private attachmentGeneration;
+    private releaseAttachment;
+    constructor(sessionId: string, deps?: LiveSessionDeps);
+    get modelName(): string;
+    /** What the editor-subject registry holds for this session: its hub, read at call time. */
+    liveAttachment(): LiveEditorAttachment;
+    private openLiveHub;
+    /**
+     * Make a control socket the current one. `release` is how the session lets go of it later: the
+     * previous attachment's is called with `superseded` here (428 WR-01), so one socket drives the
+     * session at a time.
+     */
+    beginAttachment(release?: (reason: LiveAttachmentRelease) => void): number;
+    isCurrentAttachment(generation: number): boolean;
+    attachMessageSink(sink: ((message: ServerMessage) => void) | null): void;
+    /**
+     * A command's reply, for whichever control socket is attached now (428 CR-01). A command can
+     * outlive the socket that issued it, and its outcome belongs to the page, not to that socket:
+     * with none attached it is held and flushed to the next one.
+     */
+    deliver(message: ServerMessage): void;
+    private dispatch;
+    private redact;
+    private resolveSecrets;
+    private emitHookStart;
+    private emitHookComplete;
+    private emitTestStepStart;
+    private emitTestStepPhase;
+    private emitTestStepComplete;
+    private emitTestStepError;
+    private getHookEnvVars;
+    private runLifecycleHooks;
+    executeHookCommand(phase: 'setup' | 'teardown', hookId: string): Promise<LiveExecutionLog>;
+    private releaseMobileAppiumLease;
+    private legacyMobilePlatformConfig;
+    private resolveMobilePlatformConfig;
+    private setupMobileAdapter;
+    initialize(config: LiveSessionConfig): Promise<void>;
+    private resolveStepInstruction;
+    private buildPreparationFailureResult;
+    private getStorageStateStore;
+    private executeStepInternal;
+    executeStepCommand(stepInstruction: string, stepIndex?: number, onPhase?: (event: StepPhaseEvent) => void, draft?: LiveDraftMetadata): Promise<LiveStepExecutionResult>;
+    executeTestCommand(testExecutionId: string, testDraft: {
+        testIndex: number;
+        testId: string;
+        testName: string;
+        testContext?: string;
+        steps: string[];
+        setup: string[];
+        teardown: string[];
+    }, onPhase?: (event: StepPhaseEvent) => void): Promise<LiveTestResultPayload>;
+    private runLifecycleHooksCapturing;
+    captureWebAuthState(name: string, options?: {
+        replace?: boolean;
+    }): Promise<AuthStateMetadata>;
+    cancelStep(): void;
+    navigate(url: string): Promise<string | null>;
+    refreshPage(): Promise<string | null>;
+    goBack(): Promise<string | null>;
+    goForward(): Promise<string | null>;
+    drainDeviceLogs(): Promise<Array<{
+        level: string;
+        message: string;
+        timestamp: number;
+    }>>;
+    getState(): SessionState;
+    getAriaTree(): Promise<string | null>;
+    startIdleTimer(onExpire: () => void): void;
+    clearIdleTimer(): void;
+    /** Idempotent: every later or concurrent call shares the first run, so teardown happens once. */
+    cleanup(): Promise<void>;
+    private runCleanup;
+}
+
+interface SessionManagerDeps {
+    appiumManager?: AppiumManager;
+    configManager?: ConfigManager;
+    configPath?: string;
+    liveEditorSubjects?: LiveEditorSubjects;
+}
+declare class SessionManager {
+    private deps;
+    private sessions;
+    private counters;
+    constructor(deps?: SessionManagerDeps);
+    createSession(config: LiveSessionConfig, entity?: EntityRef): Promise<{
+        sessionId: string;
+        sessionNumber: number | null;
+    }>;
+    getSession(sessionId: string): LiveSession | undefined;
+    listSessions(): SessionState[];
+    terminateSession(sessionId: string): Promise<boolean>;
+    cleanupAll(): Promise<void>;
+    getCounter(entity: EntityRef): number;
+    get size(): number;
+}
+
+interface EnqueueOptions {
+    name: string;
+    filePath?: string;
+    kind?: RunArtifactKind;
+    attributes?: RunAttributes;
+    priority?: number;
+    platform?: string;
+    testFileContent?: string;
+    modelName?: string;
+    llmProvider?: string;
+    metadata?: Record<string, unknown>;
+    parallel?: boolean;
+}
+type RunCancelOutcome = {
+    kind: 'cancelled';
+} | {
+    kind: 'stop-requested';
+} | {
+    kind: 'not-stoppable-here';
+} | {
+    kind: 'finished';
+    status: string;
+} | {
+    kind: 'orphan-finalized';
+    message: string;
+} | {
+    kind: 'owned-elsewhere';
+    message: string;
+    ownerPid: number;
+} | {
+    kind: 'not-cancellable';
+};
+declare class JobQueue extends EventEmitter {
+    private db;
+    private pollInterval;
+    private isProcessing;
+    private concurrency;
+    private activeCount;
+    private activePlatforms;
+    private activeRuns;
+    private requestStop;
+    private stopped;
+    constructor(opts: {
+        db: DashboardDatabase;
+        concurrency?: number;
+        requestStop?: (runId: string) => boolean;
+    });
+    start(intervalMs?: number): void;
+    stop(): void;
+    enqueue(opts: EnqueueOptions): string;
+    processNext(): void;
+    onSlotFreed(runId: string): void;
+    private dispatchReported;
+    getActiveCount(): number;
+    getConcurrency(): number;
+    cancel(runId: string): RunCancelOutcome;
+    private finishedOrMissing;
+    private findNextEligible;
+}
+
+interface TestFileInfo {
+    path: string;
+    name: string;
+    testId: string | null;
+    targetName: string | null;
+    platform: string | null;
+    modified: string;
+}
+interface TestValidationError {
+    message: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+}
+interface TestValidationResult {
+    valid: boolean;
+    errors: TestValidationError[];
+}
+declare class TestFileManager {
+    private readonly workspace;
+    constructor(workspace: ResolvedWorkspacePaths);
+    private readonly underLock;
+    list(): Promise<TestFileInfo[]>;
+    read(relativePath: string): Promise<string>;
+    findByTestId(testId: string): Promise<{
+        path: string;
+        content: string;
+    } | null>;
+    write(relativePath: string, content: string): Promise<void>;
+    delete(relativePath: string): Promise<void>;
+    validate(content: string): Promise<TestValidationResult>;
+    private resolveTarget;
+}
+
+interface SuiteFileInfo {
+    path: string;
+    suiteId: string | null;
+    name: string;
+    testCount: number;
+    modified: string;
+    platform: string | null;
+}
+interface SuiteValidationResult {
+    valid: boolean;
+    errors: {
+        message: string;
+        line?: number;
+        column?: number;
+        suggestion?: string;
+    }[];
+    missingTests?: Array<{
+        index: number;
+        test: string;
+        id: string;
+    }>;
+}
+declare class SuiteFileManager {
+    private readonly workspace;
+    private testFileManager;
+    constructor(workspace: ResolvedWorkspacePaths, testFileManager?: TestFileManager);
+    private readonly underLock;
+    list(): Promise<SuiteFileInfo[]>;
+    findBySuiteId(suiteId: string): Promise<{
+        path: string;
+        content: string;
+    } | null>;
+    resolvePath(filePath: string, requireExisting?: boolean): Promise<{
+        storagePath: string;
+        executionPath: string;
+    }>;
+    read(relativePath: string): Promise<string>;
+    write(relativePath: string, content: string): Promise<void>;
+    delete(relativePath: string): Promise<void>;
+    validate(content: string): Promise<SuiteValidationResult>;
+    private resolveTarget;
+}
+
+type DashboardRuntimeLLMConfig = DashboardLLMConfig & {
+    vision?: DashboardVisionConfig;
+    modelVision?: boolean;
+};
+type DashboardVisionConfig = {
+    screenshotSize?: number;
+    effectiveResolution?: number;
+};
+interface RouterDeps {
+    db: DashboardDatabase;
+    workspacePaths?: ResolvedWorkspacePaths;
+    /**
+     * The injected run backend (401-07, D-09).
+     *
+     * TYPED AGAINST THE INTERFACE, AND NOW ACTUALLY SEPARABLE. It always meant to be, and was not:
+     * the retired live-event route reached past the interface for a per-run replay buffer only the
+     * concrete class declared, so the seam had exactly one possible implementation. That route and
+     * that buffer are gone (405-07, D-19); what this router asks of a backend is the interface.
+     */
+    executionBackend?: ExecutionBackend;
+    jobQueue?: JobQueue;
+    testFileManager?: TestFileManager;
+    suiteFileManager?: SuiteFileManager;
+    configManager?: ConfigManager;
+    configPath?: string;
+    declaredSecretMask?: MaskFn;
+    llmConfig?: DashboardRuntimeLLMConfig;
+    authFetch?: typeof globalThis.fetch;
+    sessionManager?: SessionManager;
+    /**
+     * The composed agent host (400-01, D-01). It serves run detail, marks, analysis, knowledge and
+     * post-processing. (The run-confirm pair it also served is deleted, 432-14.)
+     *
+     * INJECTED, and optional because a router built the legacy two-argument way
+     * (`createRouter(db)`) has none. Each arm that needs it then answers by name rather than 404 —
+     * the route exists, this server was started without a host. See `chat/host.ts` for why the
+     * composition happens in the CLI command that starts this server rather than here.
+     */
+    agentHost?: AgentHost;
+    /**
+     * The run service's readiness predicate, served on the LOCAL door (402-05, D-15).
+     *
+     * THE SAME FUNCTION THE RUN SERVICE'S `/ok` SERVES — one readiness spelling behind two doors,
+     * which is the whole of D-15. It is passed in rather than computed here for the reason `agentHost`
+     * is: every fact in it (is a host composed) is known only to the process that composed it, and a
+     * copy made here is how the run service and the dashboard start disagreeing about whether this
+     * process can run anything.
+     *
+     * ABSENT IS THE LEGACY MOUNT, NOT AN UNCONFIGURED SERVICE. `agent-qa dashboard` ALWAYS supplies
+     * this, because the browser preflight needs an honest answer and a 404 is not one. A router built the legacy
+     * two-argument way has none, and that arm answers 503 by name on `agentHost`'s idiom.
+     */
+    runServiceReadiness?: () => RunServiceReadiness;
+    /**
+     * The started run's session, or nothing — the LOCAL door's attach port (402-08, D-01).
+     *
+     * THE SAME PORT THE AUTHED DOOR USES, and `server.ts` supplies it by reading
+     * `runService.attach` rather than by composing a second lookup: one session registry serves both
+     * doors, so a run the remote door can attach to is a run this door can attach to, and there is
+     * no second retention window to disagree about.
+     *
+     * ABSENT MEANS NO RUN SERVICE WAS MOUNTED, which is the same fact as "this process composed no
+     * session registry" — unlike `runServiceReadiness` above, whose absence is a legacy mount rather
+     * than an unconfigured service. The route then answers 503 BY NAME on the execution routes' own
+     * degradation idiom, never a 404 (the route exists) and never an empty stream (which would look
+     * like a run that emitted nothing).
+     */
+    runServiceAttach?: (runId: string) => RunSession | undefined;
+    /**
+     * The `runs.liveurl` mint, DISPATCHED THROUGH THE REGISTRY by the composition root (403 D-03).
+     *
+     * A FUNCTION, not a signer: this router holds no key and mints nothing. What it does is turn one
+     * HTTP shape into one op call and the op's refusals into status codes — which is the whole of a
+     * thin client over the function layer.
+     *
+     * ABSENT MEANS THIS HOST SERVES NO LIVE VIEW, and the route answers 503 BY NAME on
+     * `runServiceReadiness`'s idiom — never a 404 (the route exists) and never a URL to nowhere.
+     */
+    mintLiveUrl?: (runId: string, handle: number) => Promise<RunsLiveUrlResult>;
+    /**
+     * The `editor.liveurl` mint, dispatched through the registry by the composition root (428 D-07).
+     * The editor counterpart of `mintLiveUrl`: a function, never a signer. ABSENT MEANS THIS HOST
+     * MINTS NO EDITOR VIEW, and the route answers 503 by name.
+     */
+    mintEditorLiveUrl?: (sessionId: string) => Promise<EditorLiveUrlResult>;
+    /**
+     * The in-process chip sink the post-processing stream relays from (404-05, D-16).
+     *
+     * INJECTED ON `agentHost`'s OWN IDIOM. The publisher is the CLI's post-run chip emitter — a
+     * package this one may not import — so `agent-qa dashboard` creates the relay, hands
+     * `relay.publish` to the run door's bridge and hands the relay itself here. One object, two
+     * halves of the same process; a relay composed here instead would be a registry the emitter
+     * never reaches, and the stream would heartbeat forever at a page whose chips do move.
+     *
+     * ABSENT MEANS THIS SERVER HAS NO PUSH CHANNEL and the stream arm answers 503 BY NAME — never a
+     * 404 (the route exists) and never an empty stream, which would look like a chain that never
+     * ticked. The READ route is unaffected: polling works with no relay at all.
+     */
+    postProcessingRelay?: PostProcessingRelay;
+}
+declare function createRouter(deps: RouterDeps): (req: IncomingMessage, res: ServerResponse) => void;
+declare function createRouter(db: DashboardDatabase): (req: IncomingMessage, res: ServerResponse) => void;
+
+declare function readJsonBody<T>(req: IncomingMessage, maxBytes?: number): Promise<T>;
+
+/**
+ * The request URL, or `undefined` when the request line is not one.
+ *
+ * THE ONE PRODUCER. Its whole contract is that it never throws, which is what lets each caller
+ * answer in its own vocabulary — a 400 body, a JSON envelope, a destroyed socket — instead of
+ * every frame growing its own `try`.
+ */
+declare function tryParseRequestUrl(req: Pick<IncomingMessage, 'url'>): URL | undefined;
+/**
+ * Refuse a request whose target could not be parsed, in FIXED BYTES.
+ *
+ * NOTHING FROM THE REQUEST REACHES THIS RESPONSE, and that is deliberate rather than terse. The
+ * refusal exists precisely because the request target is malformed and attacker-chosen; echoing it
+ * would put attacker bytes into a body, and formatting it would give the refusal its own way to
+ * throw. The previous round recorded the same lesson one layer down: a backstop that answers
+ * through the door's own responder can re-enter the fault it was catching.
+ */
+declare function refuseUnparseableRequest(res: ServerResponse): void;
+/**
+ * The process-level backstop's answer: a 500 in fixed bytes, or a destroyed socket if it is late.
+ *
+ * THE ERROR IS NOT PRINTED AND NOT SERIALIZED. Phase 395 measured a planted credential leaving this
+ * product through an error's serialization rather than its `message`, so what goes to stderr here
+ * is the error's CONSTRUCTOR NAME and the request METHOD — two values with no attacker- or
+ * secret-derived content — and never the URL, which is attacker-chosen, or the error itself, whose
+ * `cause` chain is exactly the surface that leaked.
+ */
+declare function backstopServerError(res: ServerResponse, req: Pick<IncomingMessage, 'method'>, error: unknown): void;
+
+export { createRouter as $, type AgentHost as A, type RunRow as B, ConfigFileInvalidError as C, DashboardDatabase as D, type ExecutionBackend as E, type RunServicePorts as F, type RunServiceRouteHandlerName as G, type RunServiceRouteMatch as H, type RunServiceRouteRow as I, type RunServiceRouter as J, type RunServiceStartInput as K, type LiveEditorAttachment as L, type MintLiveUrlInput as M, type RunSettledDetails as N, type RunSettledStatus as O, type PreflightOptions as P, RunsDatabaseVersionRefusedError as Q, RUN_SERVICE_ANALYSIS_TEMPLATE as R, TestFileManager as S, type TestFileInfo as T, type TestValidationError as U, type TestValidationResult as V, backstopServerError as W, classifyRunOwner as X, completeRunOwnership as Y, createLiveEditorSubjects as Z, createPostProcessingRelay as _, type ExecuteOptions as a, createRunServiceRoutes as a0, defaultRunOwnership as a1, matchRunServiceRoute as a2, orphanSummary as a3, ownedElsewhere as a4, ownsRunServicePath as a5, readConfigValues as a6, readJsonBody as a7, refuseUnparseableRequest as a8, runDenialOf as a9, serializeConfigWrite as aa, startServer as ab, tryParseRequestUrl as ac, type PostProcessingRelay as b, type AgentRegistryHandle as c, AppiumManager as d, ConfigManager as e, LIVE_EDITOR_SUPERSEDED_CLOSE_CODE as f, LIVE_EDITOR_UNKNOWN_SESSION_CLOSE_CODE as g, type LiveEditorSubjects as h, type PostProcessingListener as i, RUN_SERVICE_ARTIFACT_TEMPLATE as j, RUN_SERVICE_DETAIL_TEMPLATE as k, RUN_SERVICE_EVENTS_TEMPLATE as l, RUN_SERVICE_EVIDENCE_TEMPLATE as m, RUN_SERVICE_LIVE_URL_TEMPLATE as n, RUN_SERVICE_MARKS_TEMPLATE as o, RUN_SERVICE_MARK_PREVIEW_TEMPLATE as p, RUN_SERVICE_OK_ROUTE as q, RUN_SERVICE_ROUTE_TABLE as r, RUN_SERVICE_START_ROUTE as s, type ReplaceDocumentOutcome as t, type ResumePoint as u, type RunOwner as v, type RunOwnerProbe as w, type RunOwnerState as x, type RunOwnership as y, type RunOwnershipInput as z };