@vostride/agent-qa-agent-local 0.0.1 → 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,2087 @@
+import { EvidenceBlobReaderPort, JobStorePort, ConfigReaderPort, JobModelCapability, StartedRun, ConfigFilesPortLike, ConfigValidatePortLike, ConfigScaffoldContentPortLike, FunctionDeps, CapabilityCatalogPort, LiveViewPort, RunDetailReaderPort, ClockPort, JobIdSource, JobKindRegistry, PostRunJobCapabilities, ReconcileStrategy, ChatLanguageModel, ChatTokenAccounting, FunctionRegistry, ChatStateSnapshot, AgentJobQueue, KnowledgeReaderPort, KnowledgeReviewPort, RunInvocationPort, RunsReaderPort, JobStoreFence, RecoverAbandonedClaimsOutcome, RunNextJobOutcome, PersistencePort } from '@vostride/agent-qa-agent';
+import { TokenAccounting } from '@vostride/agent-qa-model';
+import { ModelCapabilities, TrustPriorTable, ScopeKey, RecordedRetrievalRung, RecordId, ReadTrace, RunEventEnvelope, RunsStartInput, RunSession, RunId, EvidenceBlobLookup, EvidenceBlobPresence, QuarantineAppliedEntry, RunNotification, ExecutionContext, ResolvePromotionPosture, FunctionCaller, MaskFn, FeedbackPort, FeedbackReadsPort, TestEditPatchSet, TestFileWrite, ChatSessionEvent, ArtifactRef, GateReceipt, GateReceiptRecordOutcome, PromotionOutcome, JobKind, SessionLogPort, OpenedChatSession } from '@vostride/agent-qa-schema';
+export { ALLOW_PRODUCTION_OPT_IN, buildProductionRefusal } from '@vostride/agent-qa-schema';
+import { ScreenshotCompressorLogger } from '@vostride/agent-qa-runner-local';
+export { BuildOrdinalReservationError, latestBuildOrdinal, reserveBuildOrdinalForProducts, resolveBuildTag } from '@vostride/agent-qa-runner-local';
+import { KnowledgeHintReader, PlatformAdapter, Planner, Verifier, ActionPlanCache, WorkingMemoryPort, StorageStatePort, ScreenshotCompressor, RecordLedger, ConfigDigests, MemberRunConfig, HookDefinition, SandboxRunnerOptions, SecretStore, SecretRedactorPort, MemberEventSink, EvidenceArtifactStorePort, PlannerConfig, LoopLogger, EventLogPort, HandoffStorePort, RunArtifactStorePort, PostVerdictPort, NonActionToolMap, MemberTestRunContext, TestResult, MemberTestExecutor, MemberTest, RunConfig } from '@vostride/agent-qa-runner';
+export { BaselineProbeResult, ConfigDigests, MemberTestExecutor, PostVerdictOutcome, PostVerdictPort, PostVerdictStepInput, RunConfig, RunMemberDescriptor, mapVerdictToExitCode } from '@vostride/agent-qa-runner';
+export { runSafetyScope } from '@vostride/agent-qa-safety-local';
+import { planMarkEvidence, projectMarkEvidenceOutcome, canaryOutcomeObservationId } from '@vostride/agent-qa-knowledge-local/reader';
+export { QUARANTINE_CLASS_DISPOSITIONS, QUARANTINE_FLOOR_ELIGIBILITY, QuarantineDisposition, QuarantineFloorEligibility } from '@vostride/agent-qa-knowledge-local/reader';
+import { ExplicitReviewRequest, CreateLocalKnowledgeStoreConfig, ExplicitReviewDelegate, ServedRecordFacts, appendMarkEvidence, triageMark, servedIdsOn, procedureReadOn, applyFeedback, openKnowledgeReader, drainQueue, foldRunOutcomes, reconcileRunOutcomesProjection, enqueueCurationCandidateProjection, readCanonicalBundleAnchors, readCanonicalBundleStateDigests, canaryPostureFactsFor, standingReceiptDigestsFor, lowerTrustSharesFor, RUN_OUTCOMES_PROJECTION_VERSION, acquireWriterLease, refreshWriterLeaseAuthority, releaseLease, rebuildIndex, purgeRecord, resolvePurgeAffectedSet, purgeAffectedSetFingerprint, rollbackCampaign, rollbackCurationJob, resolveRollbackAffectedSet, rollbackAffectedSetFingerprint, heartbeatLease, readWriterLease, isLeaseStale, deriveWriterLeaseFreshness, countPendingCurationJobs, countRemainingCurationWork, inspectDrainableCurationWork, listQueuedCandidates, acquireEmbedder, runMaintenanceTail, readEmbedderWorkerRegistration, embedderWorkerProcessIsAlive, embedderWorkerSocketPath, probeEmbedderWorkerSocket, verifyEmbedderWorkerIncarnation, resolveProcessIncarnation, EmbedderWorkerRegistration, removeEmbedderWorkerRegistration, classifyIndexFace, foldRetrievalRung, indexDbPath, resolveEmbedderCapability, EntityIndexSweepReport, ExplicitReviewResult } from '@vostride/agent-qa-knowledge-local';
+export { AcquireEmbedderOutcome, AcquireWriterLeaseOutcome, ApplyFeedbackInput, AuthorOutcome, AuthoringTestRef, CurationCandidateProjection, CurationJobView, CurationProjectionArtifactSource, CuratorAuthor, DRAIN_BUDGET_MS, EMBEDDER_WORKER_REGISTRATION_FILE, EMBEDDER_WORKER_START_TIMEOUT_MS, EMBEDDER_WORKER_TERM_GRACE_MS, ENTITY_INDEX_SWEEP_INTERVAL_MS, EmbedderWorkerTimeoutError, EnqueueCurationCandidateProjectionOutcome, ExplicitReviewDelegate, ExplicitReviewDelegation, ExplicitReviewRequest, ExplicitReviewResult, HeartbeatLeaseOutcome, IndexFace, LeaseOperationOptions, MarkTriage, NeighborRecord, OpenServingKnowledgeReaderConfig, PurgeAffectedSet, PurgeReceipt, ReadEmbedderWorkerRegistrationOutcome, ReadWriterLeaseOutcome, RebuildReport, ReleaseLeaseOutcome, RollbackAffectedSet, RollbackCampaignInput, RollbackCurationJobInput, RollbackReport, ServedRecordFacts, WriterLease, WriterLeaseAuthority, WriterLeaseFreshness } from '@vostride/agent-qa-knowledge-local';
+
+/** Provisional share of usable model context reserved for the frozen Channel-1 brief. */
+declare const BRIEF_FRACTION = 0.05;
+/** Provisional share of usable model context reserved for one-shot Channel-3 cautions. */
+declare const CAUTION_FRACTION = 0.01;
+/** Provisional non-zero Channel-1 floor; field evidence may tune it in a later milestone. */
+declare const MIN_BRIEF = 256;
+/** Provisional non-zero Channel-3 floor sized to preserve at least one concise caution line. */
+declare const MIN_CAUTION = 64;
+/** Provisional upper bound for learned Channel-1 brief tokens, independent of model size. */
+declare const BRIEF_CEILING = 2048;
+/** Provisional share of usable context available to cumulative Channel-2 record bodies per turn. */
+declare const READ_BODY_FRACTION = 0.1;
+/** Provisional hard cap on distinct records admitted across all three channels in one turn. */
+declare const GLOBAL_RECORD_CAP = 24;
+/** Provisional multiplier applied to the distinct-record cap for gate-failing weak models. */
+declare const WEAK_MODEL_CAP_SCALE = 0.5;
+/** Provisional minimum context window required before the optional Channel-2 tool surface is useful. */
+declare const MIN_MEMORY_TOOL_CONTEXT_WINDOW = 16384;
+interface KnowledgeBudgets {
+    brief: number;
+    /** Wrapper-fixed Channel-2 search-result budget; never exposed in the tool schema. */
+    searchResults: number;
+    caution: number;
+    readBody: number;
+    recordCap: number;
+}
+interface ComputeKnowledgeBudgetsInput {
+    contextWindow: number;
+    reservedOutput: number;
+    qaRulesTokens: number;
+    workingContextTokens: number;
+}
+/**
+ * Derive every learned-knowledge budget beside model token accounting. The raw fraction is
+ * floored before any floor/ceiling clamp, preserving D-02's exact boundary behavior. The reader
+ * and provider-neutral loop receive only the resulting plain numbers.
+ */
+declare function computeKnowledgeBudgets(input: ComputeKnowledgeBudgetsInput): KnowledgeBudgets;
+/**
+ * Provisional D-09 predicate pinned by Phase 380 research. Channel 2 is absent when the model
+ * cannot call tools, is text-only, or has too little context; Channels 1 and 3 remain available.
+ */
+declare function memoryToolGate(capabilities: ModelCapabilities): boolean;
+/** Apply D-17's weak-model cap reduction through the exact D-09 gate predicate. */
+declare function scaledRecordCap(capabilities: ModelCapabilities): number;
+
+/** Inputs the composition root resolves when opening the run-scoped knowledge reader. */
+interface ConstructKnowledgeReaderInput {
+    resolveTrustPriors?: () => TrustPriorTable | undefined;
+    knowledgeRoot: string;
+    product?: string;
+    /** Known containing scopes for a member (the suite scope on prepared-suite runs). */
+    parentScopes?: readonly ScopeKey[];
+    asOfBuild: number;
+    recordCap: number;
+}
+/**
+ * Freeze Channel 1 at the composition root. The budget is deliberately absent from the key:
+ * budgets are run-fixed, while canonical `[tier,key]` material gives one immutable memo entry per
+ * scope. All other reader methods remain live pass-throughs for Channels 2, 3, and canary output.
+ *
+ * KREV-02 · D-13: the memo holds the WHOLE composite, so a repeat serve returns the trace captured
+ * at the moment the brief was actually assembled — not a fresh trace describing the cache hit.
+ * That is the deliberate choice and it is what makes the why-verb answer about *then*: a step that
+ * replans four times against one frozen brief was served that brief once, and the attribution that
+ * explains its lines is the one from that single serve. A "hit"-flavoured trace would describe the
+ * memo rather than the retrieval, and there would be no honest rank or score to put in it. The
+ * value type is written out rather than inferred so this stays a decision instead of a side effect
+ * of `ReturnType`; `knowledge-budgets.test.ts` pins that a repeat carries the original trace.
+ */
+declare function createFrozenKnowledgeReader(reader: KnowledgeHintReader): KnowledgeHintReader;
+/**
+ * Construct the run-scoped reader through the physically read-only package subpath, then freeze
+ * its Channel-1 brief for the lifetime of the run.
+ */
+declare function constructKnowledgeReader(input: ConstructKnowledgeReaderInput): KnowledgeHintReader;
+
+/** Mirror of schema's ExecutionContext union (safety-local's detectExecutionContext returns it). */
+type RunExecutionContext = 'local-interactive' | 'local-headless' | 'ci' | 'cloud';
+/**
+ * The provider-substrate model handle, named through the runner's own config rather than through
+ * the substrate package. It is the identical type — the runner types both model slots with it —
+ * and taking it this way keeps a provider-substrate edge off a package whose declared external
+ * dependency set is empty and whose whole point is that it installs nothing (JOBQ-02).
+ */
+type RunLanguageModel = MemberRunConfig['plannerModel'];
+type KnowledgeAccounting = Pick<TokenAccounting, 'estimate' | 'getCeilings'>;
+/**
+ * 407 D-13/D-17 — the shape of THE retrieval-rung resolver, declared structurally here and
+ * INJECTED rather than imported.
+ *
+ * knowledge-local's main entry has exactly ONE importer in this workspace by ratified rule
+ * (385 D-14/SC5, enforced at file granularity by `findKnowledgeWriterSingletonOffenders`), and
+ * that importer is `compose-local-agent.ts` — the local composition root. `resolveRetrievalRung`
+ * lives on the main entry deliberately (407-03: it opens an index probe and may load a model, so
+ * it is not `./reader` material), so naming it from this file would have made a second importer
+ * and quietly retired the invariant. The seam keeps the singleton intact while leaving exactly
+ * one implementation in the tree: `compose-local-agent.ts` re-exports the real resolver as
+ * `resolveHostRetrievalRung`, and both CLI doors pass THAT.
+ *
+ * It is REQUIRED, not optional-with-a-default. A default would be a second place the production
+ * resolver could be chosen from, and an omission at a new door would show up as a run with no
+ * rung — a banner that silently says nothing — rather than as a compile error.
+ */
+type RetrievalRungResolver = (options: {
+    knowledgeRoot: string;
+    agentQaRoot?: string;
+}) => Promise<RecordedRetrievalRung>;
+interface RunKnowledgeComposition {
+    reader: KnowledgeHintReader;
+    budgets: KnowledgeBudgets;
+    /**
+     * 407 D-13 — the HOST's retrieval ladder at THIS run's serve time, started here and awaited
+     * exactly once by the first step's evidence recorder. It is a promise rather than a value
+     * because the resolver's embedder probe can cost a model load, and overlapping that with run
+     * start keeps it off the critical path (T-407-16). Never re-probed per step: a run's rung is a
+     * fact about when it was served, not a live indicator of the machine.
+     */
+    retrievalRung: Promise<RecordedRetrievalRung>;
+    recordLedger: RecordLedger;
+    nonActionTools?: NonActionToolMap;
+    beginMemoryTurn?: (scope?: ScopeKey, exposedIds?: readonly RecordId[]) => void;
+    drainMemoryReadTraces?: () => ReadTrace[];
+}
+interface OpenRunKnowledgeCompositionInput {
+    resolveTrustPriors?: ConstructKnowledgeReaderInput['resolveTrustPriors'];
+    knowledgeRoot: string;
+    product?: string;
+    scope: ScopeKey;
+    /** Known containing scopes for a member (the suite scope on prepared-suite runs). */
+    parentScopes?: readonly ScopeKey[];
+    asOfBuild: number;
+    capabilities: ModelCapabilities;
+    accounting: KnowledgeAccounting;
+    qaRulesText: string;
+    workingContextText: string;
+    /**
+     * 407 D-13 — the hosted runtime root (`<configDir>/.agent-qa`) the embedder probe discovers its
+     * worker under. Absent falls back to the acquirer's own rule, so a caller that does not know the
+     * root still gets an honest answer rather than an error.
+     */
+    agentQaRoot?: string;
+    /**
+     * 407 D-17 — the injected rung resolver. Production callers pass `resolveHostRetrievalRung`
+     * (the composition root's binding of THE one knowledge-local resolver); tests pass a fake and
+     * never touch the host. See {@link RetrievalRungResolver} for why it is injected and required.
+     */
+    resolveRetrievalRung: RetrievalRungResolver;
+}
+/**
+ * Open and bind the complete serving stack once per run/planner scope. The composition root can
+ * estimate only prompt material it owns, so `qaRulesText` is the run-start capability/rules appendix
+ * and `workingContextText` is the resolved suite/test context plus steps. Both ride the same model
+ * accounting estimator as planning calls; static runner rules remain covered by the reserved
+ * output and conservative fractional allocation rather than a second character heuristic.
+ */
+declare function openRunKnowledgeComposition(input: OpenRunKnowledgeCompositionInput): RunKnowledgeComposition;
+/** One member's file inputs to the digest mint. `suiteFileContent` is absent on the single-test path. */
+interface RunDigestMemberInput {
+    testFileContent: string;
+    suiteFileContent?: string;
+}
+/**
+ * The per-member cache pair AND the run-level handoff pair, both produced by the SINGLE call
+ * below (D-20). The cache-key threading consumes `perMember[i]`; the handoff header carries
+ * `runLevel`. Because both draw from one mint, run identity and handoff identity cannot fork.
+ */
+interface RunConfigDigests {
+    runLevel: ConfigDigests;
+    perMember: ConfigDigests[];
+}
+/**
+ * Mint the run's config digests ONCE (D-20; RESEARCH A1 pinning).
+ *
+ * - Per-member cache pair:
+ *     suiteConfigDigest = sha256hex16(configContent + '\n' + (suiteFileContent ?? ''))
+ *     testConfigDigest  = sha256hex16(testFileContent)
+ * - Run-level handoff pair:
+ *     suiteConfigDigest = sha256hex16(ordered DISTINCT per-member suite digests joined by '\n')
+ *     testConfigDigest  = sha256hex16(ordered per-member test digests joined by '\n')
+ *   A single-member run collapses the run-level pair to the member's values.
+ *
+ * Both consumers (per-member cache, run-level handoff) draw from this one call — identities
+ * cannot fork. This is the ONLY digest computation in the composition layer.
+ */
+declare function computeRunConfigDigests(input: {
+    configContent: string;
+    members: readonly RunDigestMemberInput[];
+}): RunConfigDigests;
+/**
+ * Resolve the run's execution context via safety-local's canonical `detectExecutionContext`
+ * (RESEARCH Q1.4 recommendation (a) — already tested; an explicit override wins). Carried into
+ * `RunConfig.executionContext` and the handoff header.
+ */
+declare function resolveRunExecutionContext(override?: RunExecutionContext): RunExecutionContext;
+/** The durable run ports the shell wires behind `RunConfig.ports` (event log + handoff + artifact). */
+interface RunPersistencePorts {
+    eventLog: EventLogPort;
+    handoffStore: HandoffStorePort;
+    runArtifactStore: RunArtifactStorePort;
+    /**
+     * CASS-02 run-scoped decision-screenshot store (Plan 13). Constructed once here from the SAME
+     * persistence root + runId as the other adapters; the shell hands this exact instance to every
+     * member so Plan 12's live-decision producer persists into one durable, run-addressable namespace.
+     */
+    evidenceArtifacts: EvidenceArtifactStorePort;
+    /**
+     * 403-13 (WR-06, LIVE-03): where a live-frame VIEWER's fault is reported. Declared here as well
+     * as on the runner's `RunPorts`, because `assembleCliRun` spreads THIS interface into
+     * `RunConfig.ports` — a member declared on only one side is invisible in the type across that
+     * hop. Non-durable and off the bus by construction; the run's transcript never records a viewer.
+     */
+    onSubscriberFault?: (code: string, message: string) => void;
+    /**
+     * 404-01 (D-05/D-10): the host-composed post-verdict step the shell awaits between `verdict` and
+     * `runFinished`. Declared here for the SAME reason `onSubscriberFault` is — `assembleCliRun`
+     * spreads THIS interface into `RunConfig.ports`, so a member declared on only one side of that
+     * hop is invisible in the type and would silently never reach `startRun`.
+     *
+     * It is NOT built by `buildRunPorts`: this package's runner seam names no queue and no writer
+     * lease, and inventing a second spelling of either here is what D-05 exists to prevent. The core
+     * threads whatever the HOST handed it (`RunInvocationCoreOptions.postVerdict`) and nothing else.
+     */
+    postVerdict?: PostVerdictPort;
+}
+/**
+ * Construct the runner-local persistence ports rooted at the run's `.agent-qa` runtime dir (the
+ * FsActionCache rooting idiom). `FsEventLog`/`FsHandoffStore`/`FsRunArtifactStore`/
+ * `FsEvidenceArtifactStore` all write under the SAME `<configDir>/.agent-qa/runs/<slug(runId)>/…`
+ * family (D-08 — one self-contained run dir).
+ */
+declare function buildRunPorts(input: {
+    configDir: string;
+    runId: string;
+}): RunPersistencePorts;
+/**
+ * Construct the D-08/Q10 screenshot compressor at the composition root (sharp's host-adapter home).
+ * The runner-local `SharpScreenshotCompressor` is injected into every member's runner loop via
+ * `RunSuiteConfig.compressor` / `RunTestConfig.compressor` — core no longer constructs one.
+ */
+declare function buildScreenshotCompressor(logger?: ScreenshotCompressorLogger): ScreenshotCompressor;
+/** Resolve D-16 build-tag precedence without reading ambient process state. */
+declare function resolveBuildTagSetting(input: {
+    flag?: string;
+    env?: string;
+    use?: {
+        buildTag?: string;
+    };
+}): string | undefined;
+/**
+ * Advance the per-product buildOrdinal counter under the same `.agent-qa` root (D-18), then
+ * record D-14/D-16's first-seen tag mapping beside it when supplied. Both files are lock-free,
+ * best-effort runtime truth; the resolved ordinal rides `RunConfig.buildOrdinal` into the handoff.
+ */
+declare function resolveRunBuildOrdinal(input: {
+    configDir: string;
+    product: string;
+    buildTag?: string;
+}): Promise<number>;
+/**
+ * The ONE exclusive lane every suite member declares (402-02, D-09). The runner's bounded member
+ * pool never runs two members of the same lane concurrently, and the suite path needs that for two
+ * independent reasons, either of which alone would be sufficient:
+ *
+ *  1. Every member of a suite drives the ONE `PlatformAdapter` its suite set up — one browser, one
+ *     page. Two members on it at once would interleave navigations and clicks on a shared surface.
+ *     D-09 requires each concurrent member its own browser/CDP handle; the suite path does not
+ *     supply that today, so it does not get concurrency today.
+ *  2. `createSuiteLifecycle` admits ONE ACTIVE SUITE at a time. Two suites live at once is a
+ *     lifecycle violation, not a scheduling preference.
+ *
+ * A single lane string (rather than one lane per suite) is what encodes BOTH: it serializes within
+ * a suite and across suites. When a producer starts handing each member its own session AND the
+ * lifecycle admits concurrent suites, this becomes a per-suite key — or disappears — and the shell
+ * needs no argument re-litigated for that to be safe.
+ *
+ * STATUS 2026-08-24 (402-02): reason (2) is CLOSED — `createSuiteLifecycle` below is now a
+ * once-latch with member reference counting, so two members of one suite merge into one setup and
+ * a boundary crossed while members are live is a named error rather than a mid-flight teardown.
+ * Reason (1) is OPEN and is what still holds the lane: `suiteConfig.adapter` is per-SUITE, so
+ * within-suite concurrency would still put two tests on one browser page. Giving each suite member
+ * its own session is a change to what a suite MEANS (suite setup navigates once and members
+ * inherit that page state, per-test hooks run against it, auth state is captured from it) and is
+ * not this plan's to make. Do not drop this lane until that is decided.
+ */
+declare const SUITE_LIFECYCLE_LANE = "suite-lifecycle";
+/** The setup/teardown pair a suite runs when it first becomes active / when it is torn down. */
+interface SuiteLifecycleHooks {
+    /** Suite-level setup: setup hooks + adapter.setup + suite-URL navigation. */
+    setup(): Promise<void>;
+    /** Suite-level teardown: teardown hooks + auth-state capture (when all passed) + adapter.cleanup. */
+    teardown(): Promise<void>;
+}
+/**
+ * One member's hold on the active suite (402-02). Held from the moment `ensureReady` admits the
+ * member until the member settles; the suite cannot be torn down while any hold is outstanding.
+ */
+interface SuiteMemberLease {
+    /** Drop this member's hold. Idempotent — a double release never double-decrements. */
+    release(): void;
+}
+/**
+ * Thrown when `ensureReady` is asked for a suite while a DIFFERENT suite still has live members
+ * (402-02). This is the one-active-suite invariant made loud. The alternative — tearing the live
+ * suite down to make room — closes the browser out from under a test that is still running in it,
+ * and does so silently. The shell's exclusive lane (`SUITE_LIFECYCLE_LANE`) means no shipped
+ * composition can reach this, so it reads as an assertion rather than a runtime condition; that is
+ * exactly the point of naming it instead of assuming it.
+ */
+declare class SuiteBoundaryWhileLiveError extends Error {
+    readonly activeSuiteKey: string;
+    readonly requestedSuiteKey: string;
+    readonly liveMembers: number;
+    constructor(activeSuiteKey: string, requestedSuiteKey: string, liveMembers: number);
+}
+interface SuiteLifecycle {
+    /**
+     * Admit a member to `suiteKey` and resolve once the suite is ready. The FIRST member to arrive
+     * starts the suite's setup; every other member of that suite awaits the SAME setup promise
+     * rather than starting a second one. Crossing a suite boundary tears down the previous suite —
+     * but only once its last member has released; a boundary crossed while members are live is a
+     * {@link SuiteBoundaryWhileLiveError}, never a silent teardown.
+     *
+     * The returned {@link SuiteMemberLease} MUST be released when the member settles (pass or fail);
+     * `buildSuiteMemberExecutor` does it in a `finally`.
+     */
+    ensureReady(suiteKey: string, hooks: SuiteLifecycleHooks): Promise<SuiteMemberLease>;
+    /** Tear down the last active suite (if any). Called once at run end after `session.done`. */
+    finalize(): Promise<void>;
+}
+/**
+ * A lazy, CONCURRENCY-SAFE suite-lifecycle manager (the Q1.2 "pre/post-run composition" rows,
+ * redesigned for the 402-02 member pool). A wholly SKIPPED suite never sets up — the shell only
+ * invokes the executor (hence `ensureReady`) for non-skipped members, so a suite whose members are
+ * all fail-fast/cancel skips is never touched.
+ *
+ * WHAT CHANGED AND WHY. The pre-402 version read the active key, awaited `hooks.setup()`, and THEN
+ * assigned the key — three steps with awaits between them. Under a `for` loop that is fine because
+ * only one member is ever inside it. Under a pool, two members of one suite both observe "no active
+ * suite" and both run setup: two browsers for one suite, and the second teardown handle silently
+ * overwriting the first, so the first suite's browser is never closed. The fix is not a lock; it is
+ * to make the state transition SYNCHRONOUS and let the promise be the shared thing:
+ *
+ *  - the once-latch: `activeKey`, `activeTeardown` and `activeSetup` are all assigned in the same
+ *    synchronous region, BEFORE any await, so there is no window in which a second member can
+ *    observe the pre-setup state. Every later member of the suite awaits `activeSetup` itself.
+ *  - member reference counting: the count is incremented before awaiting setup, so a concurrent
+ *    boundary crossing sees the hold. Teardown fires at a BOUNDARY (or at `finalize`) and only
+ *    when the count is zero — never merely because it hit zero, which would tear the suite down
+ *    and set it back up between every pair of members.
+ *  - a failed setup poisons the suite: the rejected latch is kept and re-thrown to every later
+ *    member, so setup is attempted exactly once and no member half-starts against a suite that
+ *    never came up. Such a suite is never torn down — nothing came up to take down.
+ */
+declare function createSuiteLifecycle(): SuiteLifecycle;
+/**
+ * One prepared suite member: its suite key + lifecycle hooks (setup runs on the first member of
+ * that suite) and a `run(ctx)` that builds the member's bound `SuiteMemberInput` around core's
+ * per-test machinery and returns `executeSuiteMember(...)` with the shell-provided ctx seams
+ * (abortSignal, events, per-member configDigests) threaded in.
+ */
+interface SuiteMemberBinding {
+    suiteKey: string;
+    hooks: SuiteLifecycleHooks;
+    /**
+     * 403 D-05: the suite's ONE adapter, read only for its live-stream declaration. Present so the
+     * executor can register the capability AFTER `ensureReady` has resolved the suite's `setup()`
+     * (which is where `adapter.setup()` runs, so `this.page` exists) and BEFORE the first step.
+     */
+    adapter?: PlatformAdapter;
+    run(ctx: MemberTestRunContext): Promise<TestResult>;
+}
+/**
+ * Declare (or withdraw) a member's live stream on the shell-provided context (403 D-05), by the one
+ * selection rule `liveStreamFor` (428 D-11/D-12). A continuous stream is registered with the
+ * labelled 1s snapshot producer over `screenshot()` as its fallback, which the hub starts when the
+ * stream fails to start. An adapter with no continuous stream but a `screenshot()` registers the
+ * snapshot producer itself; an adapter whose own stream is already a snapshot registers that alone;
+ * an adapter with neither registers `undefined` and its handle reads `{ kind: 'none' }`.
+ * The `ctx.registerLiveStream?.()` call is itself optional so a composition that predates the port
+ * is a no-op rather than a crash.
+ */
+declare function registerAdapterLiveStream(ctx: MemberTestRunContext, adapter: PlatformAdapter | undefined): void;
+/**
+ * Build the injected `MemberTestExecutor` (D-01). Per member the closure looks up the prepared
+ * binding by the shell-derived `testIndex` (array position — authoritative), calls
+ * `lifecycle.ensureReady(...)` to lazily set up / cross-boundary tear down the member's suite,
+ * then runs the member behind `executeSuiteMember`. Wrapping ONE audited function instead of
+ * replicating the loop body.
+ */
+declare function buildSuiteMemberExecutor(input: {
+    lifecycle: SuiteLifecycle;
+    bindings: readonly SuiteMemberBinding[];
+}): MemberTestExecutor;
+/** The runner-owned `MemberTest` shape derived from a resolved (already suite-patched) TestDefinition.
+ * `filePath` is the member's own file. A suite-patched test carries no `url` (the suite owns nav), so
+ * `runMemberTest` skips the per-test navigate for suite members. */
+declare function toMemberTest(test: any, filePath: string): MemberTest;
+/** Everything both executor closures resolve at the composition root and hand to
+ * {@link buildMemberRunConfig}. The adapter-backed injected handlers are constructed here from
+ * `adapter` + `secretStore` so the two sites never drift (Pitfall 8). */
+interface BuildMemberRunConfigInput {
+    adapter: PlatformAdapter;
+    planner: Planner;
+    verifier: Verifier;
+    cache?: ActionPlanCache;
+    workingMemory?: WorkingMemoryPort;
+    storageState?: StorageStatePort;
+    compressor?: ScreenshotCompressor;
+    knowledgeReader?: KnowledgeHintReader;
+    /** 407 D-13 — the composed rung, carried through untouched to the loop's evidence recorder. */
+    knowledgeRetrievalRung?: Promise<RecordedRetrievalRung>;
+    knowledgeBudgets?: KnowledgeBudgets;
+    knowledgeAsOfBuild?: number;
+    recordLedger?: RecordLedger;
+    beginMemoryTurn?: (scope?: ScopeKey, exposedIds?: readonly RecordId[]) => void;
+    drainMemoryReadTraces?: () => ReadTrace[];
+    configDigests?: ConfigDigests;
+    plannerModel: RunLanguageModel;
+    verifierModel: RunLanguageModel;
+    stepModelScope?: MemberRunConfig['stepModelScope'];
+    envFileVars?: Record<string, string>;
+    inlineVars?: Record<string, string>;
+    suiteVars?: Record<string, string>;
+    cliVars?: Record<string, string>;
+    hookSetupVars?: Record<string, string>;
+    inlineHookDefs?: Map<string, HookDefinition>;
+    sandboxOptions?: SandboxRunnerOptions;
+    secretStore?: SecretStore;
+    secretRedactor?: SecretRedactorPort;
+    sink: MemberEventSink;
+    testIndex: number;
+    abortSignal: AbortSignal;
+    /** CASS-02 run-scoped evidence store the shell threads onto the member ctx (Plan 13). */
+    evidenceArtifacts?: EvidenceArtifactStorePort;
+    captureScreenshots?: boolean;
+    accessibility?: MemberRunConfig['accessibility'];
+    timeouts?: MemberRunConfig['timeouts'];
+    plannerConfig?: PlannerConfig;
+    logger?: LoopLogger;
+    logCapture?: {
+        console?: boolean;
+        network?: boolean;
+    };
+    vision?: {
+        screenshotSize?: number;
+        effectiveResolution?: number;
+    };
+    visionGate?: {
+        attachImage: boolean;
+        captureMode: 'full' | 'textOnly';
+        promptNote: string;
+    };
+    contextWindow?: number;
+    suiteContext?: string;
+    /** The member's own file, for the core-parity fileUpload path resolver. */
+    filePath: string;
+}
+/**
+ * Assemble the {@link MemberRunConfig} `runMemberTest` slots behind, wiring the adapter-backed
+ * injected handlers (runJS/appium/a11y/failure-shot), the store-neutral secret resolver, and the
+ * fileUpload path resolver — reproducing core's `runTest` per-test behavior on runner soil (D-05).
+ */
+declare function buildMemberRunConfig(input: BuildMemberRunConfigInput): MemberRunConfig;
+
+/** A bus subscriber a host attaches: an envelope `handler` plus an optional post-run `flush`. */
+interface RunSubscriberHandle {
+    handler: (envelope: RunEventEnvelope) => void;
+    flush?: () => Promise<void>;
+}
+/** The minimal RunSession surface a subscriber attachment needs (subscribe replay-then-live). */
+interface AttachableRunSession {
+    subscribe(fromSeq: number | undefined, handler: (envelope: RunEventEnvelope) => void): () => void;
+}
+
+/**
+ * A target's declared environment, as the config carries it (`TargetSchema.environment`).
+ *
+ * `undefined` is a first-class member and means UNDECLARED — not "unknown, assume harmless".
+ *
+ * `production` (432-03, D-18) outranks every other class in a fold. A production run is refused
+ * before any effect unless the config opts in (`refuseProductionWithoutOptIn`); one that is opted
+ * in starts like any other run (432-13).
+ */
+type RunTargetClass = 'local' | 'shared' | 'production' | undefined;
+
+/**
+ * The request fields this seam refuses, and the reason is not the one the CLI host had.
+ *
+ * `createCliRunExecution` refused these because the `run` COMMAND had no argv to express them
+ * (`local-agent-host.ts`). This core can express both — and honouring either would be the defect
+ * RESEARCH Pitfall 7 names:
+ *
+ *   `executionContext` — the context a run records comes from the composition that owns the door
+ *     (D-07) and from nowhere else. The FIELD survives on the contract as the label a run RECORDS,
+ *     and it is refused here until some door has a use for recording a label that differs from the
+ *     context it was started in.
+ *
+ *   `scope` — resolves from the config's own target/product resolution. Accepting an override
+ *     would let a caller address one product's run ledger while running another's.
+ *
+ * Read OFF the request rather than enumerated positively, so a field added to `RunsStartInput`
+ * with no plan for carrying it shows up here as a refusal instead of as a silent drop.
+ */
+declare const REFUSED_RUN_REQUEST_FIELDS: readonly ["scope", "executionContext"];
+/**
+ * The request named a field this seam refuses, so the request is refused rather than reshaped.
+ *
+ * The successor to `UnsupportedRunRequestError` (cli `local-agent-host.ts`), which dies with the
+ * spawn port in 401-05. Same class of refusal, different rationale: that one could not express the
+ * fields, this one declines to.
+ */
+declare class RunRequestFieldRefusedError extends Error {
+    readonly refusedFields: readonly string[];
+    constructor(refusedFields: readonly string[]);
+}
+/**
+ * The request named a run id this system would not have minted (2026-08-23, 401-20 · CR-04).
+ *
+ * A DECISION, NOT A FAULT, and it joins `RunRequestFieldRefusedError` under the same rule: the
+ * caller asked for something this seam declines, and says so by name before anything happens.
+ *
+ * WHY IT IS ASKED HERE AND NOT IN THE SCHEMA. `packages/schema` owns PATH-SAFETY on the id — the
+ * id becomes a directory name and that is judgeable with no dependencies — but it may not name
+ * `@vostride/agent-qa-ids` and must not re-spell the canonical id shape. So "is this an id this
+ * system would have minted" is asked here, through a predicate supplied beside `mintRunId` and for
+ * `mintRunId`'s stated reason: a locally invented answer would be a second spelling of a run's
+ * identity. Measured pre-fix: `runId: 'not-a-minted-id'` was acknowledged, and `runId: ''` ran a
+ * whole run into a shared `runs/default/` directory before the op reported `RunNotRecordedError`.
+ */
+declare class RunIdNotMintedError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * The request named a run id that already belongs to a run (2026-08-23, 401-20 · CR-04).
+ *
+ * WHAT A COLLISION COSTS, measured rather than reasoned about. Pre-fix, a second `runs.start`
+ * naming a completed run's id APPENDED seven more envelopes to that run's `events.jsonl`
+ * (2111 → 4221 bytes), OVERWROTE its `handoff.json`, and added a second row to its
+ * `execution_audit.jsonl` — and then acknowledged the caller with the victim's own id. The
+ * acknowledgment law makes that worse rather than better: `runs.start` reads every ack field back
+ * off the run's durable record specifically so a host cannot fabricate one, and a colliding id
+ * satisfies that read with a PRIOR run's record. So the refusal has to land before the record is
+ * touched at all — which is why it sits in the identity step, above assembly.
+ *
+ * THE TEST IS THE RUN'S OWN DIRECTORY, derived through `runDirFor` — the same composition the
+ * run's ports use — because every artifact a collision could tamper with lives inside it.
+ * Asking after `handoff.json` alone would let a run that crashed before writing one be silently
+ * appended to.
+ */
+declare class RunIdAlreadyInUseError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * This run was refused before it started.
+ *
+ * Since 432-13 the one producer is the production refusal (`refuseProductionWithoutOptIn`): its
+ * reason is the plain sentence naming the target and the config line. 2026-10-01 (432-19, D-15):
+ * it carries no remedy list, because the remedy vocabulary left with the execution gate.
+ * `neutralReason` is the same sentence; the dashboard and run-service doors read that member to
+ * tell a run denial from any other rejection, and a door renders it and never composes its own.
+ */
+declare class RunDeniedError extends Error {
+    readonly runId: string;
+    readonly reason: string;
+    readonly neutralReason: string;
+    constructor(runId: string, reason: string);
+}
+/**
+ * What one resolution of this request's targets answers (401-14).
+ *
+ * THE CLASS AND THE NAMES COME BACK TOGETHER because they are two renderings of ONE pass over the
+ * run's members: `targetClass` is the most-restrictive fold over them, `targetNames` the declared
+ * names of the members it folded over. A door that answered them from two passes could refuse on
+ * one reading of the config while the run it describes came from another.
+ */
+interface RunTargetDeclaration {
+    /** The DECLARED class of the run's members — a config read, never a probe (D-06). */
+    readonly targetClass: RunTargetClass;
+    /**
+     * The distinct declared target names, in first-appearance member order.
+     *
+     * DISPLAY-ONLY (T-401-G3b). Members that declare no target contribute nothing, which is how an
+     * all-undeclared run arrives here as an empty list rather than as a list of invented names.
+     */
+    readonly targetNames: readonly string[];
+    /**
+     * The members' targets DECLARED `environment: production`, in first-appearance member order
+     * (432-03, D-18). Repeats are allowed; the refusal names each target once.
+     *
+     * REQUIRED, so a door that forgets it does not compile. It comes from the SAME resolution as
+     * `targetClass` and `targetNames`, which is what keeps a mixed run from hiding a production member
+     * behind its siblings.
+     */
+    readonly productionTargetNames: readonly string[];
+    /**
+     * The config's top-level `allowProduction`, read from the same config the targets resolved
+     * against. Only the literal `true` opts in; absence and `false` do not. No request field and no
+     * CLI flag reaches this.
+     */
+    readonly allowProduction?: boolean;
+}
+/**
+ * Refuse a run that drives a production target the config has not opted into (432-03, D-18).
+ *
+ * A production CLASS with no names still refuses, so a producer that folded the class but lost the
+ * names fails closed. The refusal is a plain `RunDeniedError` carrying the sentence from
+ * `buildProductionRefusal`.
+ *
+ * EXPORTED because a producer that must acquire a device or an adapter before the core runs (the
+ * suite half) calls it first, so production is refused before that acquisition too.
+ */
+declare function refuseProductionWithoutOptIn(runId: string, declaration: Pick<RunTargetDeclaration, 'productionTargetNames' | 'allowProduction'> & {
+    readonly targetClass?: RunTargetClass;
+}): void;
+/**
+ * The identity refusals, asked against the run's own directory (401-20, CR-04).
+ *
+ * EXPORTED for the same producers `refuseProductionWithoutOptIn` is: a door that refuses production
+ * ahead of the core asks these first, so a duplicate or unminted id keeps its own refusal on every
+ * path.
+ */
+declare function refuseUnavailableRunId(input: {
+    readonly configDir: string;
+    readonly runId: string;
+    readonly isMintedRunId: (value: string) => boolean;
+}): void;
+/** What the assembler is handed: everything the core resolved, and nothing it did not. */
+interface RunAssemblyContext {
+    /** The run's identity, already resolved. The core starts the run under THIS id and no other. */
+    readonly runId: string;
+    /** The caller's request, refused fields already rejected. */
+    readonly request: RunsStartInput;
+    /** The context the door carried — the same value, so a run cannot record a different one. */
+    readonly executionContext: RunExecutionContext;
+    /** The durable ports, rooted at `<configDir>/.agent-qa` (Pitfall 5 — the evidence check's root). */
+    readonly ports: RunPersistencePorts;
+    /** `dirname(agentQaRoot)` — the project directory the config sits in. */
+    readonly configDir: string;
+    /** The config file this run resolves against (request override honoured). */
+    readonly configPath: string;
+    /** The declared class the door resolved. Handed over so an assembler need not re-resolve it. */
+    readonly targetClass: RunTargetClass;
+}
+/**
+ * Build the `RunConfig` the runner shell starts.
+ *
+ * A PORT rather than shared code, on `RunExecutionPort`'s own argument: members, executor,
+ * reporters and masking are decisions a host answers differently. What crosses into the core is
+ * the type; what stays with the door is the assembly. The core supplies the identity fields
+ * (`runId` and the markers) over whatever the assembler returns, so a door cannot start a run
+ * under an id the caller was not acknowledged with.
+ *
+ * EVERYTHING WITH A SIDE EFFECT BELONGS HERE, not in the door's pre-flight: the baseline probe
+ * (network), the build-ordinal advance (a durable write), the quarantine fold. This function is
+ * called below every refusal, so a refused run costs the target nothing.
+ */
+type RunAssembler = (context: RunAssemblyContext) => Promise<RunConfig> | RunConfig;
+interface RunInvocationCoreOptions {
+    /** The config file runs resolve against unless the request names another. */
+    readonly configPath: string;
+    /** The project's runtime root, i.e. `<configDir>/.agent-qa`. */
+    readonly agentQaRoot: string;
+    /**
+     * The context this door's runs are started in and record (D-07).
+     *
+     * CALLER-RESOLVED, NEVER SNIFFED. The CLI resolves its TTY posture, the daemon carries
+     * `local-headless`, CI passes its own. A core that detected this itself would be answering a
+     * question about the machine when the question is about the door.
+     */
+    readonly executionContext: RunExecutionContext;
+    /**
+     * Resolve what this request's targets DECLARE (D-06; names added 401-14).
+     *
+     * INJECTED BECAUSE THE CONFIG LIVES BEHIND THE DOOR, not because any of it is negotiable. Target
+     * resolution needs the CLI's `resolveTarget`/`AgentQaConfig` vocabulary, which this package may
+     * not name. `undefined` is undeclared, which is not production.
+     *
+     * ONE RESOLUTION, ALL FIELDS, AND THAT IS THE POINT OF THE SHAPE. The class, the names, the
+     * production members and the opt-in come back from one pass, so the production refusal is asked
+     * about the members the run will actually drive.
+     *
+     * Must not touch the target, and must not probe. A resolver that read a URL would put a network
+     * call before the production refusal, which is the one ordering this file exists to hold.
+     */
+    readonly resolveTargetDeclaration: (request: RunsStartInput) => RunTargetDeclaration | Promise<RunTargetDeclaration>;
+    /** Build the `RunConfig`. Called ONLY once every refusal has passed. */
+    readonly assembleRun: RunAssembler;
+    /**
+     * Mint a run id when the request carries none.
+     *
+     * REQUIRED rather than defaulted: the id generator lives in `@vostride/agent-qa-ids` (via core),
+     * which this package does not depend on, and a locally invented id shape would be a second
+     * spelling of a run's identity. Every shipped door already holds `generateRunId`.
+     */
+    readonly mintRunId: () => string;
+    /**
+     * Is this a run id this system would have minted? (2026-08-23, 401-20 · CR-04)
+     *
+     * REQUIRED, WITH NO DEFAULT AND NO FALLBACK, for exactly `mintRunId`'s reason and one more. The
+     * canonical predicate lives in `@vostride/agent-qa-ids`, which this package does not depend on,
+     * and a locally invented shape check would be a second spelling of a run's identity — the same
+     * argument that made minting an option. The extra reason is that an OPTIONAL predicate with a
+     * permissive fallback is this defect wearing a type: every composition that forgot it would be
+     * back to accepting any string, and the build would say nothing. A composition that omits this
+     * does not compile.
+     *
+     * It answers about the SHAPE only. Whether the id is free is this file's own question, asked
+     * against the run's own directory.
+     */
+    readonly isMintedRunId: (value: string) => boolean;
+    /**
+     * Notified with the started session, synchronously, before the core awaits it (D-09's bridge
+     * hook). Subscribers attach here; the bus replays from seq 1, so nothing is missed.
+     */
+    readonly onSession?: (session: RunSession) => void;
+    /**
+     * Build this run's post-verdict step (404 D-05/D-10) — the durable `analyze-run` enqueue plus
+     * ONE writer-lease consult, awaited by the shell between `verdict` and `runFinished`, whose
+     * answer becomes `runFinished.disposition`.
+     *
+     * HOST-COMPOSED, CORE-THREADED, and both halves are load-bearing. It is host-composed because
+     * the step speaks queue and writer-lease vocabulary this package's runner seam may not name —
+     * the same argument that made `mintRunId` an option rather than a local. It is threaded HERE
+     * rather than left to each door because the enqueue is precisely what the `runs.start` door and
+     * the daemon door forgot: a door that supplies no factory gets a run whose wire honestly reads
+     * `detached`, and a door that supplies one cannot then forget to wire it in.
+     *
+     * Called ONCE per run, after every refusal has passed and the persistence ports exist, so a
+     * refused run never composes one. Absent ⇒ no `postVerdict` member reaches `RunConfig.ports` at all
+     * (conditional spread, never an `undefined` field), and the shell reports `detached` with no
+     * warning — which is the truth about a host from which nothing will be drained.
+     */
+    readonly postVerdict?: (input: {
+        readonly runId: string;
+        readonly configDir: string;
+    }) => PostVerdictPort;
+    /** The door's first third-party code, awaited once the request is allowed and before any port. */
+    readonly afterRefusal?: () => Promise<void>;
+}
+/**
+ * The one in-process run execution core.
+ *
+ * Returns a `RunExecutionPort` (the shape `createLocalRunInvocation` binds `runs.start` over), so
+ * the op's evidence check — read the run's own event log back, refuse an empty one — applies to
+ * this seam unchanged.
+ *
+ * NO DEFENSIVE CATCH ANYWHERE (D-03). A run that crashes hard takes its host with it, on purpose:
+ * crash-through surfaces bugs instead of absorbing them, and the runner's budget/abort machinery
+ * is the orderly containment. The only `throw`s this file introduces are the two refusals above,
+ * which are decisions rather than faults.
+ */
+declare function createRunInvocationCore(options: RunInvocationCoreOptions): {
+    execute(request: RunsStartInput): Promise<{
+        runId: RunId;
+    }>;
+};
+
+interface CreateEvidenceBlobReaderInput {
+    /** The runtime root, i.e. `<configDir>/.agent-qa` — the parent of `runs/`. */
+    readonly agentQaRoot: string;
+}
+declare function lookupEvidenceBlob(input: CreateEvidenceBlobReaderInput, runId: string, sha: string): EvidenceBlobLookup;
+/**
+ * THE SAME RULE, MINUS THE BYTES (Phase 406, D-17) — presence for a whole run's artifact refs.
+ *
+ * WHY NOT `lookupEvidenceBlob(...).status`: a run page annotates every ref it is about to render,
+ * and the read arm loads a screenshot into memory to reach the status it then discards. This
+ * shaping walks the identical three-way split — malformed sha, unknown run, then the store's own
+ * answer — and asks the store to STAT instead of read. The two arms above `runDirectoryExists`
+ * are shared code, not a copy, so `found` here and `found` there are the same claim.
+ */
+declare function statEvidenceBlob(input: CreateEvidenceBlobReaderInput, runId: string, sha: string): EvidenceBlobPresence;
+/**
+ * The op's PORT over {@link lookupEvidenceBlob}.
+ *
+ * BOTH MEMBERS ARE BOUND HERE (406, D-17): this host holds run directories, so it can honestly
+ * answer the optional presence member, and an op reading it gets `present` for every ref rather
+ * than the omitted key a host without local storage would leave.
+ *
+ * ASYNC EVEN THOUGH THE STORE IS NOT, because the port is the shape a host that does not hold its
+ * blobs on a local disk would also have to satisfy — and a synchronous contract is one such a host
+ * could never implement without lying about it. The local answer is simply already resolved.
+ */
+declare function createEvidenceBlobReader(input: CreateEvidenceBlobReaderInput): EvidenceBlobReaderPort;
+/**
+ * The analysis job's shaping: the bytes, or nothing, with the two absences collapsed.
+ *
+ * THE COLLAPSE IS THIS CALLER'S, not the rule's. An evidence-diet pass has the same work to do
+ * whether a run is unknown or its blob was already collected — there is no screenshot either way —
+ * so it takes the narrower answer rather than making the shared rule narrower for everyone.
+ */
+declare function readEvidenceBlobBytes(input: CreateEvidenceBlobReaderInput, runId: string, sha: string): Uint8Array | undefined;
+
+interface RunQuarantineSnapshotInput {
+    /** The committed knowledge root, already resolved (`resolveKnowledgeRoot`). */
+    knowledgeRoot: string;
+    /** The run's RAW product / scope key; slugged here to match the projection partition law. */
+    product: string;
+    /** Run-start instant as an ISO-8601 string — the ONE clock read, made by the caller. */
+    now: string;
+    warn?: (message: string) => void;
+}
+/**
+ * Resolve the entries this run will apply: active (`'quarantined'`) and belonging to this run's
+ * product. Expired entries are deliberately EXCLUDED — a lapsed entry's test fails builds again
+ * (D-11) — and released entries are gone.
+ *
+ * Measured consequence worth knowing at THIS seam, because this is where the exclusion is decided:
+ * for a test still crossing the threshold that is exactly ONE red build. The snapshot below is
+ * taken at run start (entry lapsed ⇒ not applied ⇒ red), and that same run's post-run fold
+ * re-enters it with a fresh full-lifetime deadline before the next run takes its own snapshot. No
+ * human is scheduled into that loop at any point, and nothing bounds the repetition
+ * (measured 2026-08-06).
+ */
+declare function resolveRunQuarantineSnapshot(input: RunQuarantineSnapshotInput): readonly QuarantineAppliedEntry[];
+
+/**
+ * Hand every entity id an output surfaced to the addressing ledger's sighting seam.
+ *
+ * Fire-and-forget by contract: it resolves when the sighting is recorded, and a rejection is
+ * not the read's problem. An address is a permanent fact about an entity and a listing is a
+ * question about the store; failing the question because the bookkeeping failed would let the
+ * ledger take down the answer it exists to annotate.
+ */
+type SightMemoryEntities = (bundleIds: readonly string[]) => Promise<void>;
+
+interface LogicalDumpTable {
+    readonly table: string;
+    readonly orderBy: readonly string[];
+    readonly rows: readonly Record<string, unknown>[];
+}
+interface LogicalDumpCheckpoint {
+    /** Relative to the checkpoint root, so two runs under different temp roots compare. */
+    readonly path: string;
+    readonly digest: string;
+}
+interface LogicalDump {
+    readonly schemaVersion: number;
+    readonly tables: readonly LogicalDumpTable[];
+    readonly checkpoints: readonly LogicalDumpCheckpoint[];
+}
+
+/** One chain-terminal notification row, with its payload guarded on the way out (388 D-09). */
+interface JobStoreNotification {
+    readonly runId: string;
+    readonly payload: RunNotification;
+    readonly createdAt: string;
+}
+interface SqliteJobStore extends JobStorePort {
+    close(): void;
+    /**
+     * The chain-terminal notifications this database holds, ordered by run.
+     *
+     * On the implementation rather than the neutral port, beside `logicalDump`, and for the
+     * same reason: the port is the ENGINE's vocabulary and the engine never reads a
+     * notification — it writes one, once, as part of ending a job. Every reader of these rows
+     * is a surface, and 388 D-14 routes surfaces through the function layer, not through here.
+     *
+     * The payload is parsed through the schema guard rather than handed back as text: the
+     * column is bytes another build could have written, and a row that lost a stage cannot be
+     * allowed to travel as a `RunNotification`.
+     */
+    listNotifications(): Promise<readonly JobStoreNotification[]>;
+    /**
+     * The D-03 comparison basis, in full: every table this database holds plus a digest per
+     * checkpoint file.
+     *
+     * Kept beside `dumpState()` rather than replacing it, because the two answer different
+     * questions and collapsing them would weaken both. `dumpState()` is the typed, engine-facing
+     * projection of the job rows and it is part of the neutral port. This one is the storage
+     * implementation's own full-state instrument: it knows about the checkpoint directory and
+     * about tables the port has no vocabulary for, and it is the thing a crash comparison holds
+     * up against another run.
+     */
+    logicalDump(): Promise<LogicalDump>;
+    /** The same dump as one comparable string. Byte equality here is state equality. */
+    dumpLogicalState(): Promise<string>;
+}
+
+/**
+ * 407 D-13/D-17 — THE retrieval-rung resolver, bound at the one edge that may name the writer
+ * entry (385 D-14/SC5) and handed to `openRunKnowledgeComposition` by every run door.
+ *
+ * The binding exists so there is exactly ONE resolver in the tree with exactly ONE importer of
+ * the package that owns it. `run-composition.ts` declares the seam's shape structurally and takes
+ * the function as a required input rather than importing it — naming knowledge-local's main entry
+ * from a second file would retire the singleton the arch gate enforces, and the fix would look
+ * like relaxing the gate.
+ *
+ * Typed as {@link RetrievalRungResolver} rather than by its own signature, so the pass-through
+ * that reaches the CLI is the narrow two-root contract the doors actually use — the embedder
+ * `probes` seam and the preferred profile stay knowledge-local's business.
+ */
+declare const resolveHostRetrievalRung: RetrievalRungResolver;
+/**
+ * 407 D-18/D-20 — the READ-ONLY knowledge probes a diagnostic grades a host with.
+ *
+ * `doctor` needs the two axes SEPARATELY, not just the folded word: its `Knowledge store` row is
+ * about the index face, its `Embedder` row is about the capability outcome, and only its third row
+ * is the fold. {@link resolveHostRetrievalRung} above hands back the fold alone, so a surface that
+ * had only that would have to re-derive the other two — which is a second fold in everything but
+ * name, and exactly what D-17's one-resolver rule exists to prevent.
+ *
+ * Published as its own frozen table rather than folded into {@link LOCAL_DAEMON_CAPABILITIES}
+ * because every member here is a READ. Nothing in it acquires a lease, spawns a worker, downloads
+ * an artifact or writes to the knowledge root, and a caller that holds this object cannot mutate
+ * the thing it is reporting on. That is the whole mitigation for T-407-19: the boundary is the
+ * shape of the capability, not a promise in a doc comment at the call site.
+ *
+ * `foldRetrievalRung` rides along for the same reason the resolver does — one fold table in one
+ * package, reached through the one edge that may name the writer entry (385 D-14/SC5).
+ */
+interface LocalKnowledgeProbeCapabilities {
+    readonly classifyIndexFace: typeof classifyIndexFace;
+    readonly foldRetrievalRung: typeof foldRetrievalRung;
+    readonly indexDbPath: typeof indexDbPath;
+    readonly readEmbedderWorkerRegistration: typeof readEmbedderWorkerRegistration;
+    readonly readWriterLease: typeof readWriterLease;
+    readonly resolveEmbedderCapability: typeof resolveEmbedderCapability;
+}
+declare const LOCAL_KNOWLEDGE_PROBES: LocalKnowledgeProbeCapabilities;
+
+/**
+ * The standing daemon's writer-authority substrate, published through the same one composition
+ * edge as every other local writer capability. Surface packages may import agent-local, but the
+ * architecture firewall deliberately forbids them from naming knowledge-local or safety
+ * directly; keeping this frozen table here preserves that boundary without duplicating lease
+ * behavior in the CLI host.
+ */
+interface LocalDaemonCapabilities {
+    readonly acquireWriterLease: typeof acquireWriterLease;
+    readonly heartbeatLease: typeof heartbeatLease;
+    readonly releaseLease: typeof releaseLease;
+    readonly readWriterLease: typeof readWriterLease;
+    readonly isLeaseStale: typeof isLeaseStale;
+    /**
+     * CR-01/CR-08: the one three-valued freshness verdict — fresh, reclaimable, or unknown.
+     *
+     * Any surface that classifies a holder as recoverable must read this and not the lease file
+     * alone, and must name what it does with `unknown` rather than inheriting a boolean it never
+     * chose. An authority state that cannot be read is not evidence that nobody holds it.
+     */
+    readonly deriveWriterLeaseFreshness: typeof deriveWriterLeaseFreshness;
+    readonly countPendingCurationJobs: typeof countPendingCurationJobs;
+    readonly countRemainingCurationWork: typeof countRemainingCurationWork;
+    readonly inspectDrainableCurationWork: typeof inspectDrainableCurationWork;
+    readonly listQueuedCandidates: typeof listQueuedCandidates;
+    readonly acquireEmbedder: typeof acquireEmbedder;
+    readonly drainQueue: typeof drainQueue;
+    readonly runMaintenanceTail: typeof runMaintenanceTail;
+    readonly resolveEmbedderWorkerEntryPath: () => string;
+    readonly readEmbedderWorkerRegistration: typeof readEmbedderWorkerRegistration;
+    readonly embedderWorkerProcessIsAlive: typeof embedderWorkerProcessIsAlive;
+    readonly embedderWorkerSocketPath: typeof embedderWorkerSocketPath;
+    readonly probeEmbedderWorkerSocket: typeof probeEmbedderWorkerSocket;
+    /** CR-05: no surface may signal a registered worker pid without this verdict returning 'match'. */
+    readonly verifyEmbedderWorkerIncarnation: typeof verifyEmbedderWorkerIncarnation;
+    readonly resolveProcessIncarnation: typeof resolveProcessIncarnation;
+    readonly removeEmbedderWorkerRegistration: (agentQaRoot: string, expected: EmbedderWorkerRegistration) => ReturnType<typeof removeEmbedderWorkerRegistration>;
+    readonly resetEmbedderCapability: () => void;
+    readonly pinLocalHeadlessExecutionContext: () => void;
+}
+declare const LOCAL_DAEMON_CAPABILITIES: LocalDaemonCapabilities;
+/**
+ * Index maintenance and the campaign/job rollback verbs, plus the lease every one of them is only
+ * legal to hold under. Grouped rather than flattened because they share that precondition: a host
+ * reaching for `purgeRecord` without a lease is the mistake the grouping makes visible.
+ */
+interface LocalKnowledgeMaintenanceCapabilities {
+    readonly acquireWriterLease: typeof acquireWriterLease;
+    readonly refreshWriterLeaseAuthority: typeof refreshWriterLeaseAuthority;
+    readonly releaseLease: typeof releaseLease;
+    readonly rebuildIndex: typeof rebuildIndex;
+    readonly purgeRecord: typeof purgeRecord;
+    readonly resolvePurgeAffectedSet: typeof resolvePurgeAffectedSet;
+    readonly purgeAffectedSetFingerprint: typeof purgeAffectedSetFingerprint;
+    readonly rollbackCampaign: typeof rollbackCampaign;
+    readonly rollbackCurationJob: typeof rollbackCurationJob;
+    readonly resolveRollbackAffectedSet: typeof resolveRollbackAffectedSet;
+    readonly rollbackAffectedSetFingerprint: typeof rollbackAffectedSetFingerprint;
+}
+interface ReceiptWriterInput extends Pick<CreateLocalKnowledgeStoreConfig, 'knowledgeRoot' | 'executionContext' | 'resolvePromotionPosture' | 'resolveTrustPriors' | 'sourceBuildOrdinal' | 'sourceRunId'> {
+    /** The caller already holds this authority; these capabilities never acquire a lease. */
+    lease: {
+        leaseId: string;
+        epoch: number;
+    };
+}
+interface RecordGateReceiptInput extends ReceiptWriterInput {
+    receipt: GateReceipt;
+}
+interface PromoteWithReceiptsInput extends ReceiptWriterInput {
+    candidateId: RecordId;
+    receipts?: readonly GateReceipt[];
+}
+declare function recordGateReceipt(input: RecordGateReceiptInput): Promise<GateReceiptRecordOutcome>;
+declare function promoteWithReceipts(input: PromoteWithReceiptsInput): Promise<PromotionOutcome>;
+/** Internal facts only: public showRecord deliberately omits bundle construction fields. */
+declare function readFeedbackRecord(input: {
+    knowledgeRoot: string;
+    recordId: string;
+    evidenceRef?: ArtifactRef;
+}): ServedRecordFacts | undefined;
+interface LocalCurationCapabilities {
+    readonly readFeedbackRecord: typeof readFeedbackRecord;
+    readonly appendMarkEvidence: typeof appendMarkEvidence;
+    /**
+     * 2026-09-15, 423 D-16/D-17: the lease-free planning half appendMarkEvidence executes, so a
+     * consequence preview names every confirm/overturn effect without the writer. Reads only.
+     */
+    readonly planMarkEvidence: typeof planMarkEvidence;
+    readonly projectMarkEvidenceOutcome: typeof projectMarkEvidenceOutcome;
+    readonly triageMark: typeof triageMark;
+    readonly servedIdsOn: typeof servedIdsOn;
+    readonly procedureReadOn: typeof procedureReadOn;
+    readonly applyFeedback: typeof applyFeedback;
+    readonly recordGateReceipt: typeof recordGateReceipt;
+    readonly promoteWithReceipts: typeof promoteWithReceipts;
+    /** Serving-side reader the tail folds against; read-only despite arriving on the writer edge. */
+    readonly openKnowledgeReader: typeof openKnowledgeReader;
+    readonly drainQueue: typeof drainQueue;
+    readonly foldRunOutcomes: typeof foldRunOutcomes;
+    /**
+     * THE mechanism a version bump rides (393 CR-02). The per-run receipt below carries the
+     * version, but invalidating receipts only re-runs folds that answer 'already-applied' on the
+     * durable marker — so the refold a bump promises happens through THIS capability, as a rebuild
+     * of the derived family, and nowhere else.
+     *
+     * It is invoked at exactly two sites, one per supported host (393 round 6, CR-02-daemon): once
+     * per CLI curation-tail sweep, and once per daemon lease acquisition. Both, because the CLI
+     * tail is unreachable whenever a standing daemon takes the hand-off — a promise true of one
+     * host is, on the other host, a projection that never converges.
+     */
+    readonly reconcileRunOutcomesProjection: typeof reconcileRunOutcomesProjection;
+    readonly enqueueCurationCandidateProjection: typeof enqueueCurationCandidateProjection;
+    readonly readCanonicalBundleAnchors: typeof readCanonicalBundleAnchors;
+    readonly readCanonicalBundleStateDigests: typeof readCanonicalBundleStateDigests;
+    readonly readCanaryPostureFacts: typeof canaryPostureFactsFor;
+    readonly readStandingGateReceipts: typeof standingReceiptDigestsFor;
+    readonly readLowerTrustShares: typeof lowerTrustSharesFor;
+    /** 418 D-07: reuse the writer's observation identity through the existing CLI bridge. */
+    readonly canaryOutcomeObservationId: typeof canaryOutcomeObservationId;
+    /**
+     * Component of the tail's receipt: a bump refolds runs already receipted at the old version.
+     * The receipt is the per-run half of that promise; `reconcileRunOutcomesProjection` above is
+     * the half that actually re-derives the rows.
+     */
+    readonly runOutcomesProjectionVersion: typeof RUN_OUTCOMES_PROJECTION_VERSION;
+    readonly maintenance: LocalKnowledgeMaintenanceCapabilities;
+}
+declare const LOCAL_CURATION_CAPABILITIES: LocalCurationCapabilities;
+/**
+ * Enumerate `<agentQaRoot>/runs/<slug>/handoff.json`. A project with no runs directory is an
+ * ordinary empty result, not an error; an individual unreadable or version-rejected document is
+ * skipped so one bad run never hides every other run.
+ */
+declare function createRunsReader(agentQaRoot: string): RunsReaderPort;
+/**
+ * The knowledge READ port, served through the PHYSICALLY read-only `/reader` package entry.
+ *
+ * The five read verbs live in `knowledge-review-reader.ts`, which is registered in the arch
+ * reader carve-out's pinned file list and therefore CANNOT name the writer-gated entry. This
+ * file can (it also binds the curator), so keeping the verbs here would have put them in the
+ * one place in the workspace where a write import is legal — separation by discipline instead
+ * of by rule. What stays here is the half that genuinely belongs to a composition root: the
+ * D-01 sighting site, which mints into the durable addressing ledger and so must live where
+ * the writer entry may be named.
+ *
+ * The knowledge ROOT arrives as a host-supplied resolver rather than being derived here: deciding
+ * which configuration file is in force, layering an environment over it and choosing whether to
+ * load and execute auth plugins are three decisions a daemon makes differently from a terminal,
+ * and by the plan-08 dissection rule a thing a headless host would substitute is a port.
+ */
+declare function createKnowledgeReader(resolveKnowledgeRoot: () => Promise<string> | string, sightMemoryEntities?: SightMemoryEntities, resolvePromotionPosture?: () => Promise<ResolvePromotionPosture | undefined>, resolveTrustPriors?: CreateLocalKnowledgeStoreConfig['resolveTrustPriors']): KnowledgeReaderPort;
+interface CreateKnowledgeReviewInput {
+    readonly resolveTrustPriors?: CreateLocalKnowledgeStoreConfig['resolveTrustPriors'];
+    readonly resolvePromotionPosture?: () => Promise<ResolvePromotionPosture | undefined>;
+    readonly agentQaRoot: string;
+    readonly resolveKnowledgeRoot: () => Promise<string> | string;
+    /**
+     * The writer lease this host ALREADY holds, when it is the holder (D-18).
+     *
+     * The daemon's half of the routing rule. A holder cannot acquire its own lease a second time, so
+     * it hands the authority it owns to the change; supplying this is mutually exclusive with
+     * supplying a delegate, and a host that supplies both is a host claiming to be two places.
+     */
+    readonly resolveWriterAuthority?: () => {
+        readonly leaseId: string;
+        readonly epoch: number;
+    } | undefined;
+    /**
+     * 432-12 (D-05): how a direct change reaches a live writer-lease holder. The holder receives the
+     * validated request and the change's stable identity, bounded; the lease is never taken. Absent,
+     * a held lease refuses the change by name. Exclusive with {@link resolveWriterAuthority}: a holder
+     * never delegates. The daemon supplies none, which is why its own changes cannot recurse.
+     */
+    readonly knowledgeChangeDelegate?: ExplicitReviewDelegate;
+    /**
+     * 432-12: the context a direct change is recorded under. Absent means the process resolver, the
+     * default every registry in this composition already reads. The context is recorded as-is; an
+     * explicit change applies in every context (D-04/D-08).
+     */
+    readonly resolveExecutionContext?: () => ExecutionContext;
+}
+/**
+ * Bind the mutating review verbs over the review modules and the Curator's one commit path.
+ *
+ * A SEPARATE factory from `createKnowledgeReader`, mirroring the port split it implements: this
+ * is the object whose presence makes accept/reject/forget report `bound`, and a host that wants
+ * only the read verbs simply does not build one. The `MEM-` short-ID leg resolves through the
+ * addressing ledger, opened per call and closed again on exactly the reasoning the entity
+ * directory uses — a durable file the composition root owns, never a handle a review module holds.
+ */
+declare function createKnowledgeReview(input: CreateKnowledgeReviewInput): KnowledgeReviewPort;
+interface ApplyKnowledgeChangeInput {
+    readonly agentQaRoot: string;
+    readonly knowledgeRoot: string;
+    readonly request: ExplicitReviewRequest;
+    /** The caller's stable identity for this change: a retry with the same identity lands nothing twice. */
+    readonly operationId: string;
+    /** The op making the change, stamped on its Gate-3 receipts. */
+    readonly opId: string;
+    /** The caller's actual context, recorded as-is. An explicit change applies in every context. */
+    readonly executionContext: ExecutionContext;
+    readonly resolveTrustPriors?: CreateLocalKnowledgeStoreConfig['resolveTrustPriors'];
+    readonly resolvePromotionPosture?: () => Promise<ResolvePromotionPosture | undefined>;
+    /**
+     * How this host reaches a live writer-lease holder. The holder receives exactly the validated
+     * request and identity, bounded; the lease is never taken. Absent, a held lease refuses by name.
+     */
+    readonly delegate?: ExplicitReviewDelegate;
+    /** The lease this host already holds, when it is the holder. Exclusive with {@link delegate}. */
+    readonly writerAuthority?: {
+        readonly leaseId: string;
+        readonly epoch: number;
+    };
+}
+/**
+ * Apply one explicit knowledge change through the direct writer (432-06), with this host's short-id
+ * resolver. Nothing is filed: the change is committed, or it is refused by type.
+ */
+declare function applyKnowledgeChange(input: ApplyKnowledgeChangeInput): Promise<ExplicitReviewResult>;
+interface CreateEntityDirectoryInput {
+    readonly agentQaRoot: string;
+    readonly resolveKnowledgeRoot: () => Promise<string> | string;
+}
+interface SweepEntityIndexInput extends CreateEntityDirectoryInput {
+    /**
+     * Test seam ONLY. Production omission runs the real acquisition ladder, which is what makes
+     * the dense rung appear on hosts that have a model and stay absent on hosts that do not.
+     */
+    readonly acquireEmbedderCapability?: typeof acquireEmbedder;
+}
+interface SweepEntityIndexOutcome extends EntityIndexSweepReport {
+    /** How many renderings gained a vector this sweep. Zero on a floor host, by design. */
+    readonly embedded: number;
+}
+/**
+ * The daemon's maintenance-cadence sweep over the D-06 projection.
+ *
+ * Three properties, and each is a deliberate refusal rather than an omission:
+ *
+ *  - it takes NO writer lease. Everything it writes lives in the entity index's own file, and
+ *    a projection that needed the lease could not be maintained by a host that does not hold
+ *    one — which is every one-shot CLI process.
+ *  - it never writes the addressing ledger. It READS the ledger to know what exists (D-02: the
+ *    ledger is the durable truth, not a projection) and writes only the rendering of it.
+ *  - it embeds only what a host can already embed. `acquireEmbedder` with no download is the
+ *    same ladder the retrieval legs ride: ready means the dense rung joins the resolver on this
+ *    host, and anything else leaves the projection lexical-only rather than blocking the sweep.
+ */
+declare function sweepEntityIndexProjection(input: SweepEntityIndexInput): Promise<SweepEntityIndexOutcome>;
+/**
+ * The host's run-execution capability: run this request to completion, and say which run it was.
+ *
+ * A PORT rather than shared code, by the plan-08 dissection rule. Would a headless drainer
+ * execute a suite the way a terminal host does? It would substitute — the process model
+ * (in-process, a child, a worker pool), the signal handling, the reporters and the exit
+ * discipline are all decisions the host owns and answers differently. What crosses into the
+ * composition is the type; what stays with the host is the orchestration.
+ *
+ * The verb resolves the IDENTITY of the run and nothing else. Anything richer would be the
+ * host telling the composition what happened, and the whole point of the binding below is
+ * that the composition does not take the host's word for it.
+ */
+interface RunExecutionPort {
+    /**
+     * 2026-10-01 (432-18, D-15): the optional `gate` argument (401-08, D-08) carried the standing
+     * approvals in force — the durable ledger's answer unioned with any dispatch-scoped grant — to a
+     * run gate behind the port. The run gate went in 432-13 and the ledger and the dispatch overlay
+     * go in 432-18, so a host is handed the request and nothing else.
+     */
+    execute(request: RunsStartInput): Promise<StartedRun>;
+}
+/**
+ * The run this host reported did not leave a durable event log behind.
+ *
+ * The composition's evidence check, and the reason `runs.start` cannot be satisfied by a host
+ * that returns a plausible run id without running anything. The v49 bus writes `runStarted`
+ * before anything else can happen, so a run that began at all has a non-empty log; an empty
+ * one means no run took place under that id. Read through {@link buildRunPorts} — the same
+ * `FsEventLog` family the runner appends with — so what is inspected is the run's own record
+ * rather than a path this file re-derives.
+ */
+declare class RunProducedNoEventsError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * Bind `runs.start` over a host's run execution.
+ *
+ * The composition contributes the half a host must not be trusted with: after the host says a
+ * run happened, the run's own durable event log is read back and an empty one is refused. The
+ * op then builds its acknowledgment from the completed-run record through the SAME reader
+ * `runs.get` answers from, so "the run is real" and "the run is addressable" are one fact.
+ */
+declare function createLocalRunInvocation(input: {
+    readonly agentQaRoot: string;
+    readonly execution: RunExecutionPort;
+}): RunInvocationPort;
+/**
+ * A parsed draft, as the HOST hands it over.
+ *
+ * Structurally identical to `packages/agent`'s `ParsedDraftLike`, and mirrored here rather than
+ * imported for the reason every mirror in this graph exists: that type lives inside `agent`'s
+ * `authoring/` and is not on its barrel, and publishing it to give a composition a name would put
+ * a gate-orchestration type on the surface that publishes exactly one dispatch.
+ *
+ * `filePath` MUST be the workspace-relative identity the runner records on
+ * `PerTestOutcome.filePath` — `workspaceRelativeIdentityPath`, the one spelling of that recipe.
+ * Gates 1-2 find the draft's own member inside each run document by comparing against those bytes,
+ * so a path spelled any other way makes every gate-run report `absent` for its own draft and gate
+ * 1 fail for a join reason wearing a draft reason's clothes.
+ */
+interface ParsedDraftDescriptor {
+    readonly testId: string;
+    readonly filePath: string;
+    readonly testName: string;
+    /**
+     * The parsed test's `target`. REQUIRED, exactly as `ParsedDraftLike.target` and
+     * `TestDefinitionSchema` require it (394-37, WR-04).
+     *
+     * A mirror that dropped it would hand `packages/agent` a draft whose target the compile stage
+     * cannot check against the vocabulary it just served — and the cost of not checking is paid as
+     * real child gate runs on a name `resolveTarget` throws on, against a key no repair patch may
+     * edit.
+     */
+    readonly target: string;
+    readonly steps: readonly string[];
+    /**
+     * The parsed test's `context` block — an EDITABLE root, and therefore one the credential gate
+     * scans. Structurally identical to `ParsedDraftLike.context`; a mirror that dropped it would
+     * hand `packages/agent` a draft whose context can no longer be screened.
+     */
+    readonly context?: string;
+    readonly contentDigest: string;
+}
+/**
+ * What a host can say about a caller-supplied draft path.
+ *
+ * Four refusal arms and one success, because `packages/agent` is `storageNeutral` and genuinely
+ * cannot answer any of them: it can neither stat a path nor know where the workspace ends. The op
+ * turns each arm into its own NAMED error, so the refusal a caller catches is declared beside the
+ * capability while the syscall stays with the host that owns a filesystem (T-393-01).
+ */
+type DraftParseOutcome = {
+    readonly kind: 'parsed';
+    readonly draft: ParsedDraftDescriptor;
+} | {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'not-a-file';
+} | {
+    readonly kind: 'outside-workspace';
+} | {
+    readonly kind: 'unparsable';
+    readonly reason: string;
+};
+/** One authored suite test as TEXT, for gate 3's degraded lane (D-16). */
+interface SuiteTextEntry {
+    readonly filePath: string;
+    readonly testName: string;
+    readonly stepsText: readonly string[];
+}
+/**
+ * The host's authoring capability: parse ONE draft, and enumerate the authored-test universe.
+ *
+ * BOTH VERBS OR NEITHER, and the bundling is a report rather than a convenience. A host that
+ * supplied only the parse would bind a capability whose gate-3 text lane is permanently empty —
+ * evidence-less suite tests would silently stop joining the comparison, and a draft would look
+ * novel purely because whatever it duplicates has never been run. That is D-16's unsafe direction
+ * arrived at by omission, and the only way to make it un-omittable is to make the two arrive
+ * together.
+ *
+ * Both verbs live at the HOST because both need `parseTestFile` from `@vostride/agent-qa-core`,
+ * which neither this package nor `agent` may import (the FUNC-02 firewall) — the parse-at-host
+ * precedent `cli/src/curation/authoring-test-discovery.ts` established.
+ */
+interface DraftAuthoringPort {
+    parseDraft(filePath: string): Promise<DraftParseOutcome>;
+    suiteTextCorpus(): Promise<readonly SuiteTextEntry[]>;
+    /**
+     * 394-33 · WR-07: the names a `target` may legally take in this project.
+     *
+     * ON THIS PORT for the reason `deriveDefaultScope` is: both hosts build their authoring
+     * capability from ONE factory, so a verb that lives here is reached by the CLI `fn` surface and
+     * the chat/daemon host without a second binding either could forget. A vocabulary served by only
+     * one of the two hosts would make "does stage 3 guess at `target`" depend on which surface a
+     * person happened to author from.
+     *
+     * IT ENUMERATES AND NEVER REFUSES — the opposite posture to `deriveDefaultScope` right below it,
+     * which throws when the answer is not unique. There is no such thing as an ambiguous list, and a
+     * project declaring no targets has an honest empty answer rather than a failure.
+     */
+    configuredTargetNames(): Promise<readonly string[]>;
+    /**
+     * 394-26 · WINDOWS 110: which scope this project authors for, when the caller named none.
+     *
+     * ON THIS PORT rather than beside it, and that placement is the guarantee. Both hosts build
+     * their authoring capability from one factory, so a verb that lives here is reached by the CLI
+     * `fn` surface and the chat/daemon host without a second binding either could forget — which is
+     * what makes "there is ONE derivation" a fact about the wiring rather than a convention.
+     *
+     * IT THROWS RATHER THAN ANSWERING `undefined` when the project has no unique product: the host
+     * is the only side that knows which candidates it saw, and a refusal that cannot name them
+     * leaves an author with no way to write the `scope` that would have worked.
+     */
+    deriveDefaultScope(): Promise<ScopeKey>;
+    /**
+     * 394 D-01 · WTST-01: PARSE the compiled draft, then WRITE it to the shelf — in that order, as
+     * one verb, joining for exactly the reason the two above bundle.
+     *
+     * ONE VERB AND NOT TWO, because the order is the mitigation (T-394-06). Model-authored YAML is
+     * the one input on the authoring path that no schema at the op boundary can vet, and separate
+     * verbs would let a caller write first and discover the parse failure afterwards — with bytes
+     * already on this workspace's disk. Here an unparsable draft answers `unparsable` having
+     * created nothing at all.
+     *
+     * THE DIGEST IS THE HOST'S, over the bytes it is writing, and it is the caller's only
+     * addressing: the shelf path is minted from it, so nothing the model emitted reaches the
+     * filesystem as a path component. `DraftRef.contentDigest`'s whole promise — a later edit
+     * cannot inherit an earlier receipt — is only true while the digest is over what was stored.
+     */
+    stageDraft(contents: string): Promise<DraftStageOutcome>;
+    /**
+     * 394-06 D-09/D-20: apply an RFC-6902 patch set to a staged draft and stage the result.
+     *
+     * AT THE HOST for the same reason its two neighbours are: `applyPatchSetToTestDoc` needs the
+     * yaml CST from `@vostride/agent-qa-core`, which neither this package nor `agent` may import.
+     * It answers the same `DraftStageOutcome`, so a patch that renders an unrunnable document is
+     * refused with the shelf untouched rather than written and discovered later.
+     */
+    applyPatchesToDraft(draft: ParsedDraftDescriptor, patchSet: TestEditPatchSet): Promise<DraftStageOutcome>;
+    /**
+     * 432 D-06/D-07: write a staged draft's bytes to its test path — the direct final-test writer.
+     *
+     * AT THE HOST for its neighbours' reason: the workspace identity mint lives in
+     * `@vostride/agent-qa-core`. The host checks the boundary and that the target still holds the
+     * bytes the caller read (absent for a new test), writes through a sibling temp and a rename, runs
+     * no git, and answers `not-written` with its reason whenever the bytes did not land.
+     */
+    publishDraft(request: DraftPublishRequest): Promise<TestFileWrite>;
+}
+/** One draft to write: its shelf path, its target, and what the target held when it was read. */
+interface DraftPublishRequest {
+    readonly draftPath: string;
+    readonly targetPath: string;
+    readonly sourceDigest?: string;
+}
+/**
+ * What staging produced: a parsed draft that IS on the shelf, or a refusal that wrote nothing.
+ *
+ * Structurally the mirror of `agent`'s `DraftStageOutcome`, on this file's own mirror discipline
+ * — that type lives inside `agent`'s `authoring/` and the value crossing this seam is assignable
+ * to it unchanged.
+ */
+type DraftStageOutcome = {
+    readonly kind: 'staged';
+    readonly draft: ParsedDraftDescriptor;
+} | {
+    readonly kind: 'unparsable';
+    readonly reason: string;
+};
+/** Wall-clock in the one format every store column and dump row is written in. */
+declare const SYSTEM_CLOCK: ClockPort;
+declare const DIGEST_JOB_ID_SOURCE: JobIdSource;
+/**
+ * The durable half of the host, opened on demand.
+ *
+ * `store` is the concrete sqlite store rather than the neutral port: the host that opened the
+ * database is the one entitled to close it and to take the D-03 logical dump, and both verbs live
+ * on the implementation. Nothing else in the package publishes it.
+ */
+interface LocalAgentJobs {
+    readonly queue: AgentJobQueue;
+    readonly store: SqliteJobStore;
+    readonly kinds: JobKindRegistry;
+    /** The capability the queue was constructed with, exposed so a host can assert what it bound. */
+    readonly model: JobModelCapability;
+    /**
+     * The id source the queue was constructed with.
+     *
+     * Exposed because a caller that watches this queue's outcomes must be able to derive the same
+     * ids the enqueue addressed — the push half of a run's chip trail and the pull half of its
+     * status have to agree about which rows belong to which run. Publishing the SOURCE makes that
+     * agreement structural; re-deriving a default at the call site would make it a convention, and
+     * a convention is exactly what breaks the first time a host is composed with a different one.
+     */
+    readonly idSource: JobIdSource;
+    /**
+     * The kind exclusion the queue was constructed with, resolved from
+     * `UNCLAIMABLE_BY_PROSE_POSTURE` and published for the same stated reason `idSource` is:
+     * a caller that must assert what its queue was constructed with should read the value
+     * rather than re-derive a default. Empty when the host declared `'masker-active'` or was
+     * composed with no `postRun` at all.
+     */
+    readonly unclaimableKinds: readonly JobKind[];
+}
+/** Refusal returned when durable capabilities are requested after their composition was closed. */
+declare class LocalAgentClosedError extends Error {
+    readonly agentQaRoot: string;
+    readonly name = "LocalAgentClosedError";
+    constructor(agentQaRoot: string);
+}
+interface LocalAgentHost {
+    /** The 384 function registry with every seed capability bound over local storage. */
+    readonly registry: FunctionRegistry;
+    /**
+     * The live chat session composed beside the registry (392 plan 08).
+     *
+     * Present on EVERY host, because the turn engine is (D-24) — a host whose chat session were
+     * optional would make `agent.ask` bound and its state absent, which is two answers to whether
+     * this host can hold a conversation.
+     */
+    readonly chat: LocalAgentChatSession;
+    /** The knowledge-writer powers this host grants — the same frozen object for every host. */
+    readonly curation: LocalCurationCapabilities;
+    /** The clock every store column, dump row and audit stamp in this host is written against. */
+    readonly clock: ClockPort;
+    /**
+     * Open (once) the durable job queue and its sqlite store over this host's runtime root.
+     *
+     * A method rather than an eager member, and the reason is a behaviour rather than a taste:
+     * constructing the store CREATES `<agentQaRoot>/agent-jobs.db` and the checkpoint directory. A
+     * host that only lists the registry — `agent-qa fn --list` is exactly that — would otherwise
+     * bring a queue database into existence in a project that has never enqueued anything. Repeated
+     * calls return the same instance, so "opened once" is a property of the handle and not of the
+     * caller's discipline.
+     */
+    jobs(): Promise<LocalAgentJobs>;
+    /** Close whatever was opened and join an open already in flight. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * What a host's curation binding does with candidate prose (388-10, UF-388-01 / D-11).
+ *
+ * A closed union, REQUIRED wherever `postRun` is supplied: a host that cannot say what its
+ * fold does with candidate prose has not been reviewed for UF-388-01, and the typechecker is
+ * what makes that review mandatory rather than customary.
+ *
+ * - `'masker-active'` — the fold has the declared-secret mask bound (441-01 decision 10), or the
+ *   binding never reaches candidate emission at all.
+ * - `'no-masker'` — the binding folds with NO declared mask. A statement about DISCLOSURE, not
+ *   about capability: the fold would run, but its prose masking would degrade to a pass-through,
+ *   so a host declaring this may not claim the kind that runs it.
+ */
+type CandidateProsePosture = 'masker-active' | 'no-masker';
+/**
+ * The chain kinds a host of each posture MAY NOT CLAIM — one table, no second spelling.
+ *
+ * A `Record` over the union rather than a condition, deliberately: this phase's named defect
+ * class is a guard whose input domain is written in prose while the code ranges over a
+ * subset, and a total `Record` stops compiling the day a third posture is added. The queue's
+ * `unclaimableKinds` is derived from this table and from nothing else.
+ */
+declare const UNCLAIMABLE_BY_PROSE_POSTURE: Record<CandidateProsePosture, readonly JobKind[]>;
+interface ComposeLocalAgentInput {
+    readonly mask: MaskFn;
+    /** Immutable neutral data resolved by the host, reused until recomposition. */
+    readonly resolveTrustPriors?: CreateLocalKnowledgeStoreConfig['resolveTrustPriors'];
+    readonly feedback?: FeedbackPort;
+    /**
+     * 423 D-19/D-16: read-only mark history and consequence preview; absent leaves runs.marks.history
+     * and runs.mark.preview unbound by name, and a port without `preview` leaves only the preview unbound.
+     */
+    readonly feedbackReads?: FeedbackReadsPort;
+    /** DATA across the wall: host preparation may await; candidate evaluation is synchronous. */
+    readonly resolvePromotionPosture?: () => Promise<ResolvePromotionPosture | undefined>;
+    /** The project's runtime root, i.e. `<configDir>/.agent-qa`. Absolute. */
+    readonly agentQaRoot: string;
+    /**
+     * Masked configuration reads. Injected because flattening and masking a resolved configuration
+     * needs the host's own loader — its file layering, its environment, its plugin policy — and the
+     * masking decision is a disclosure boundary the host owns (T-384-07 / T-384-17).
+     */
+    readonly config: ConfigReaderPort;
+    /** Resolves the knowledge root this invocation serves from. See `createKnowledgeReader`. */
+    readonly knowledgeRoot: () => Promise<string> | string;
+    /**
+     * The model a job may author with (D-10, plan 05).
+     *
+     * A required factory. REQUIRED because the queue's own `model` option is required and not
+     * defaultable — an optional capability means a queue can be built with none, and the only place
+     * to discover that is inside an author callback far from the composition that forgot it. A
+     * FACTORY because `jobs()` is deferred, and resolving a provider handle costs a configuration
+     * read and an auth resolution that a host listing the registry must not pay.
+     *
+     * It is called at most once, when the queue is opened. `agent-local` never constructs a model:
+     * its ownership contract forbids provider invocation, so the handle arrives already built and no
+     * provider name is named here.
+     */
+    readonly model: () => JobModelCapability | Promise<JobModelCapability>;
+    /**
+     * How this host executes a run (D-16). OPTIONAL, and the optionality is the reporting
+     * mechanism rather than a convenience: a host that supplies it lists `runs.start` as
+     * `bound` and can run it; a host that does not lists the same capability as `unbound` and
+     * refuses it by name. Not every composition can start a run — a listing, a read-only
+     * surface, 386's daemon before it wires an executor — and D-09 requires that to be a
+     * visible state rather than a call that fails somewhere far from the composition.
+     */
+    readonly runExecution?: RunExecutionPort;
+    /**
+     * How this host parses a draft and enumerates its authored suite (393 D-01), on the exact
+     * optional-operation idiom `runExecution` above uses.
+     *
+     * OPTIONAL, and — like its neighbour — the optionality is the reporting mechanism rather than a
+     * convenience. `authoring.draft.verify` is bound only where this AND `runExecution` are both
+     * present, because a host that cannot parse a test file and a host that cannot start a run are
+     * both hosts that cannot verify a draft. Either one missing lists the capability `unbound` BY
+     * NAME, which is the honest answer; the alternative is a receipt whose four booleans were
+     * computed from no runs at all, and a refusal wearing a verdict's clothes is the one answer that
+     * could get a draft kept on the strength of nothing.
+     *
+     * Host-supplied for the reason `mintQuarantineIdentityPath` is: it needs `parseTestFile` and the
+     * CHECKOUT ROOT, and neither this package nor `agent` may name `@vostride/agent-qa-core`.
+     */
+    readonly draftAuthoring?: DraftAuthoringPort;
+    /**
+     * 395-01 D-03/D-17 · CFGM-01/04: the committed config file SET as RAW BYTES, plus the
+     * comment-preserving field edit over them.
+     *
+     * Host-supplied because the edit is `yaml`'s Document API, and neither this package nor `agent`
+     * may name that dependency under their ownership contracts. The CLI host already depends on it and already owns the file format.
+     */
+    readonly configFiles?: ConfigFilesPortLike;
+    /**
+     * 395-01 CFGM-01: whole-config validation, run BEFORE a proposal surfaces.
+     *
+     * Host-supplied because `AgentQaConfigSchema` lives in `@vostride/agent-qa-core`, which neither
+     * this package nor `agent` may name — the `mintQuarantineIdentityPath` arrangement exactly.
+     */
+    readonly configValidate?: ConfigValidatePortLike;
+    /**
+     * 395-08 D-04 · CFGM-05: the shared scaffold CONTENT, rendered by the host that owns it.
+     *
+     * A SEPARATE OPTIONAL BINDING. The substance lives beside
+     * `init`'s own write path in `packages/cli`, which neither this package nor `packages/agent` may
+     * import; its absence leaves `config.project.scaffold` — and only that op — unbound, which is the
+     * honest catalogue answer for a host that can edit a configuration but cannot create one.
+     */
+    readonly scaffoldContent?: ConfigScaffoldContentPortLike;
+    /**
+     * 2026-09-30, 432-07 D-05/D-07: the direct config writer. Host-supplied because its transaction
+     * is the dashboard's config file transaction, shared per path with the dashboard's own writes.
+     */
+    readonly configWrite?: FunctionDeps['configWrite'];
+    /**
+     * 2026-08-17 (398 D-09 / D-11 · XPLN-02): the four host halves `agent.explain` needs — the
+     * committed capability catalog as data, the model's citation over it, and the two coverage hooks.
+     *
+     * Host-supplied for the reason `scaffoldContent` is, and the boundary is harder here rather than
+     * softer: the artifact is read by `loadCapabilityCatalog` in `packages/cli`, which walks the
+     * package root and touches `fs`, and this package is host-neutral. The citation call needs the
+     * model the chat host already composed through `createModel`, which is a resolution neither this
+     * package nor `packages/agent` may perform. The coverage append is a file write.
+     *
+     * OPTIONAL, and the absence is the report. A composition that omits it lists `agent.explain`
+     * `unbound` BY NAME rather than degrading to a model-only answer — which is the one behaviour
+     * XPLN-02 exists to forbid, and the one that would be hardest to notice, because an explain
+     * answering from model memory still sounds exactly like an explain.
+     */
+    readonly capabilityCatalog?: CapabilityCatalogPort;
+    /**
+     * 403 D-03: the live-view mint seam `runs.liveurl` binds through, handed straight through from
+     * the host — this composition decides nothing about it.
+     *
+     * OPTIONAL because the absence is a genuine host fact and not a degradation: a host serving no
+     * HTTP origin has no URL it could honestly mint, so the op lists `unbound` BY NAME rather than
+     * returning a link that resolves to nothing.
+     */
+    readonly liveView?: LiveViewPort;
+    /**
+     * 405 D-03: the durable run-detail projection read `runs.detail` binds through, handed straight
+     * through from the host — this composition decides nothing about it and constructs no database.
+     *
+     * OPTIONAL because a host may have no projection to read, and then `runs.detail` lists `unbound`
+     * BY NAME. The CLI host binds a reader over the configured or default runs database path whenever
+     * its config parses (a read before that file exists answers not recorded in the runs database);
+     * the dashboard passes its own handle.
+     */
+    readonly runDetail?: RunDetailReaderPort;
+    /**
+     * 432-12 (D-05): how a direct knowledge change reaches the writer-lease holder when one is alive,
+     * as an OPTIONAL operation on the input bag rather than a new production seam (the 386-41 D-2
+     * idiom): `agent-local` cannot name a socket and does not. The CLI host injects a closure
+     * over `invokeViaDaemon` that invokes the change op there with the same identity; the daemon's
+     * own composition injects nothing, because it holds the lease.
+     */
+    readonly knowledgeChangeDelegate?: ExplicitReviewDelegate;
+    /** The writer lease a leaseholding host already owns (387-08 D-18). See `createKnowledgeReview`. */
+    readonly resolveWriterAuthority?: () => {
+        readonly leaseId: string;
+        readonly epoch: number;
+    } | undefined;
+    /**
+     * Mints the durable workspace-relative identity the quarantine ledger keys `filePath` on
+     * (390-12 / D-01). Core's `workspaceRelativeIdentityPath`, pre-bound by the host to its own
+     * config directory.
+     *
+     * Host-supplied for the same reason `resolveWriterAuthority` one field up is: the CHECKOUT ROOT is
+     * a fact only a host knows. Neither this composition nor the verbs beneath it can discover it, and
+     * a layer that guessed would mint identities against the wrong root.
+     *
+     * REQUIRED, and — unlike its neighbour — not conditionally spread. The optionality of the writer
+     * authority is a real report about a real difference between hosts: one holds the lease, one does
+     * not. There is no host that can legitimately lack a checkout root, so an absent mint is not a
+     * posture, it is exactly the unvalidated pass-through that let the write verbs author permanently
+     * unreadable lines into a committed artifact. It belongs at compile time, at the composition that
+     * forgot it.
+     */
+    readonly mintQuarantineIdentityPath: (filePath: string) => string;
+    readonly clock?: ClockPort;
+    readonly idSource?: JobIdSource;
+    /** The kind registry the queue dispatches through. Defaults to the six real declarations. */
+    readonly jobKinds?: JobKindRegistry;
+    /**
+     * What the post-run chain's real handlers may do (388 D-01), on the optional-operation
+     * idiom `runExecution` and `applyDelegate` already use.
+     *
+     * OPTIONAL, and the optionality is the report rather than a convenience: a host that
+     * supplies it dispatches the REAL analyze-run and curate-memory bodies, and a host that
+     * does not keeps the scripted stand-ins. Only `curateRun` is asked for — the handoff read
+     * is built here, from `agentQaRoot`, because it is a path derivation this package already
+     * owns and a caller-supplied one would be a second layout to keep in step with the writer's.
+     *
+     * `curateRun` is the caller's because it is not a local concern at all: it needs the writer
+     * lease, a knowledge root and the v51 drain, and the CLI's run tail is where all three
+     * already meet (plan 02 binds it).
+     */
+    readonly postRun?: {
+        readonly curateRun: PostRunJobCapabilities['curateRun'];
+        /**
+         * REQUIRED beside the binding it describes: a `postRun` that omits it must stop
+         * typechecking, because the posture is the UF-388-01 review of this binding and an
+         * unreviewed binding is exactly what let the daemon fold unmasked. See
+         * `CandidateProsePosture` for what each member does and does not certify.
+         */
+        readonly candidateProse: CandidateProsePosture;
+        /**
+         * The 422 D-13 proposal stage's staging port, passed straight through.
+         *
+         * OPTIONAL beside a REQUIRED `curateRun`, and the asymmetry is the contract: without
+         * `curateRun` there is no real fold and therefore no real chain, whereas a host that binds
+         * no staging port still runs the third stage — it stages nothing, records no counts, and
+         * the terminal says exactly that. Passed through rather than built here for the same reason
+         * `curateRun` is: the adversarial staging is not a local concern, and this package may not
+         * name the seam it lives behind.
+         */
+        readonly stageAdversarialProposal?: PostRunJobCapabilities['stageAdversarialProposal'];
+        /**
+         * The 422 D-14 Gate-1 leg's four ports, passed straight through (422-09).
+         *
+         * NEUTRAL FORWARDING, and the neutrality is the contract rather than a style note: every one
+         * of these needs a committed corpus, a screening run and a writer this package may not name,
+         * and a version of this file that could construct them could not be this file. What crosses
+         * here is four closures and a number; what stays on the other side is every fact about where
+         * they read from.
+         *
+         * Each is OPTIONAL and each is spread on presence, because a host that binds none is the
+         * shipped posture — the stage runs, screens nothing, and says so by omitting the member.
+         */
+        readonly runReplayGate?: PostRunJobCapabilities['runReplayGate'];
+        readonly listBundles?: PostRunJobCapabilities['listBundles'];
+        readonly gateReceiptsFor?: PostRunJobCapabilities['gateReceiptsFor'];
+        readonly readProposeCorpusPosture?: PostRunJobCapabilities['readProposeCorpusPosture'];
+        /**
+         * 2026-09-13, 422 D-19, gap plan 422-27: the host's durable per-run evaluation-root
+         * posture, forwarded as a neutral closure. Absence leaves the handler's fail-closed
+         * default in force; this composition neither resolves nor interprets the posture.
+         */
+        readonly readMisdirectionRootPosture?: PostRunJobCapabilities['readMisdirectionRootPosture'];
+        /**
+         * The operator's per-job Gate-1 bound, as a FACTORY resolved once at queue open.
+         *
+         * A factory on the exact `model` / `analysisTokenBudget` idiom, for the same reason those are:
+         * reading it needs a configuration read, and paying for one at composition would charge every
+         * host that only lists the registry. The capability itself is plain data — a number the
+         * handler reads and never a reader it calls.
+         */
+        readonly proposeGate1MaxPerJob?: () => Promise<number | undefined> | number | undefined;
+    };
+    /**
+     * D-01's TokenAccounting substrate for the analyze-run author (389 plan 06). OPTIONAL
+     * and host-resolved: both production hosts derive it from the SAME model-profile
+     * resolution as the job model itself (one source of truth, no second config surface —
+     * 386 D-15), and `composeLocalAgent` only passes the resolved value through. A FACTORY
+     * on the exact `model` idiom — resolution may need a configuration read, and it is paid
+     * once, at queue open, never by a host that only lists the registry. A factory that
+     * answers `undefined` composes the plan-04 no-ladder posture: packs travel whole.
+     */
+    readonly analysisTokenBudget?: () => Promise<PostRunJobCapabilities['analysisTokenBudget']> | PostRunJobCapabilities['analysisTokenBudget'];
+    /**
+     * The host's execution context for this composition (400-01, D-05).
+     *
+     * 2026-10-02 (432-39, D-12): it reaches the knowledge review, which records a direct change under
+     * it, and nothing else here; the registry option it was also forwarded to is deleted, because no
+     * op decides in a context. The history below explains why it is injected per composition.
+     *
+     * INJECTED RATHER THAN PINNED ON THE PROCESS, and that is the whole reason this field exists.
+     * The registry accepted a `resolveExecutionContext` from 384 until 432-39; what it did NOT have
+     * was a way for a host to supply one, so the only lever a host had was
+     * `setActiveExecutionContextResolver` — a PROCESS GLOBAL. Reaching for it changes the answer
+     * for everything composed in that process, including compositions the host does not own, and a
+     * host that forgot to restore it leaks its posture into every later caller. The dashboard door
+     * is the first host that has to state a posture per composition rather than per process
+     * (D-01/D-05: the browser confirm channel is what makes the context interactive, and it is a
+     * property of a server, not of the machine), so the injected form is what it binds.
+     *
+     * ABSENT MEANS THE SHIPPED AMBIENT RESOLVER, unchanged: the knowledge review's own default reads
+     * safety's process resolver, so every existing host composes exactly as it did before. This is
+     * a passthrough and nothing here decides what a context MEANS. (432-19: `requiresFailClosed`, the
+     * gate's reading of a context, is deleted; the four-member vocabulary stays.)
+     */
+    readonly resolveExecutionContext?: () => ExecutionContext;
+    /**
+     * Notified AFTER one session event has been appended to its log (400-01, D-03).
+     *
+     * AN OBSERVER, AND EVERY WORD OF THAT IS THE CONTRACT. It is called with an event that is
+     * ALREADY ON THE FILE — after `append` resolves, never before and never instead — so a host
+     * pushing these somewhere cannot show a person an event the durable log does not carry. It
+     * cannot append, cannot rewrite and cannot refuse: the return value is discarded and a throw is
+     * swallowed at the notify site, because a surface's push channel failing must not fail the turn
+     * that produced the event.
+     *
+     * WHY THIS AND NOT A HOST-SUPPLIED `SessionLogPort`. The obvious alternative — let a host wrap
+     * or replace the log — is exactly what D-04 forbids: sessions belong to the agent, not to a
+     * surface, and a replaceable log is a second store one conversation at a time. This seam widens
+     * nothing. The log stays the single producer and the single writer; what a host gets is a
+     * carbon copy of what was written.
+     *
+     * The SESSION ID travels with the event because the event itself carries only a `turnId` — the
+     * grammar's exact-key guard means it never will carry more (Pitfall 4), so the fact a subscriber
+     * needs is supplied beside the record rather than smuggled into it.
+     */
+    readonly observeSessionEvent?: (sessionId: string, event: ChatSessionEvent) => void;
+    /**
+     * The turn engine's reconciliation strategy (392 D-16).
+     *
+     * AN INTERNAL COMPOSITION OPTION, and every word of that is load-bearing. It is here so the
+     * mutation proof can assemble the REAL host twice — override on, override off — and read the
+     * difference off a named compound scenario, which is the only differential that measures what
+     * production actually wires (Pitfall 3, the produced-not-literal law).
+     *
+     * IT IS NOT, AND MUST NEVER BECOME, CONFIG-REACHABLE. No field of `AgentQaConfig` names it and
+     * none may: the deterministic override is the mechanism that stops a model's plan from beating
+     * a proven mapping, so a production knob that switched it off would be a supported way to
+     * disable a safety property. Absent, the shipped strategy is used — which is what makes the
+     * absence the safe default rather than an unconfigured state.
+     */
+    readonly chatReconcile?: ReconcileStrategy;
+    /**
+     * The model stage 2 plans with, ALREADY BUILT by the host through `createModel` (CHAT-06).
+     *
+     * A model OBJECT and never a model id: the SDK's own type also admits an id it resolves by
+     * constructing a client, which would put a provider client behind chat without the masking
+     * middleware and the profile resolution `createModel` owns. The type closes that door here.
+     *
+     * ABSENT IS A REAL POSTURE, NOT AN UNCONFIGURED ONE. A host with no model bound is HEADLESS: any
+     * clause the deterministic table cannot resolve fails the turn closed by name (D-08), which is
+     * the correct behaviour rather than a degraded one. That is also why no planner is stubbed in —
+     * a stub answering "I could not plan that" would say the same words about an entirely different
+     * fact, that a model was asked and declined.
+     */
+    readonly chatModel?: ChatLanguageModel;
+    /**
+     * The accounting instance chat's degrade pass measures against (CHAT-04, plan 06).
+     *
+     * HOST-RESOLVED and passed through untouched, on `analysisTokenBudget`'s precedent and for its
+     * reason: the ceilings must come from the SAME capability resolution as the chat model itself,
+     * or a session would compact against a window the model does not have. This composition adds no
+     * knob of its own and cannot construct one — `agent-local` reaches no provider.
+     *
+     * Absent ⇒ no degrade pass runs and the `compaction` seat stays empty, which is the posture
+     * every host had before a model was bound.
+     */
+    readonly chatAccounting?: ChatTokenAccounting;
+    /**
+     * How this host resolves a model NAMED by `/model <name>` (D-04, plan 08).
+     *
+     * Supplied by the host for the same reason `chatModel` is, and enforced by the same rule: the
+     * chat subtree may not construct a model, so a session-scoped switch has to arrive as a
+     * capability the composition was handed. Absent ⇒ `/model` still records the session's declared
+     * model and emits its `model_change` (the header, the prompt and the drift check all follow it),
+     * and no new client is resolved — the honest behaviour for a host that composed one model.
+     */
+    readonly chatModelFor?: (name: string) => ChatLanguageModel | Promise<ChatLanguageModel>;
+    /**
+     * Where a chat session PRINTS a mid-turn artifact a person reads (395-13, D-14).
+     *
+     * A PLAIN FUNCTION: printing needs nothing from this composition. The surface is handed text and
+     * writes it. (432-16 deleted the `chatConfirm` factory that used to sit beside it.)
+     *
+     * PASSED THROUGH UNTOUCHED to the turn engine's `present`. Absent ⇒ the engine renders nothing
+     * mid-turn, which is every host that is not a REPL — and no gate, receipt or session row moves.
+     */
+    readonly chatPresent?: (text: string) => void | Promise<void>;
+}
+/**
+ * The live chat session a host holds beside the registry (plan 08, RESEARCH Open Q2).
+ *
+ * Exposed because two of its facts have no other route to a surface: the state a REPL renders
+ * from, and the ability to close an interrupted turn honestly. Everything else a conversation does
+ * goes through `agent.ask` like every other capability (D-24).
+ */
+interface LocalAgentChatSession {
+    /**
+     * The live state of ONE conversation, or `undefined` for a session this host has not opened
+     * (392 plan 13, CR-02).
+     *
+     * A LOOKUP RATHER THAN A CONTAINER, because the facts inside it — the turn in flight, the
+     * conversation, the model in force, what `/pin` denies, whether `/quit` was typed — are facts
+     * about a session and never about a host. A composition serving two conversations that handed
+     * out one container was answering both of them with whichever turn wrote last, which is what
+     * let a planner read the wrong history (CR-02) and a pin outlive its session (W-03).
+     *
+     * `undefined` is the honest answer for an id nobody here is holding, and reading NEVER creates
+     * a scope: a surface asking about a session cannot bring one into being by asking.
+     */
+    stateFor(sessionId: string): ChatStateSnapshot | undefined;
+    /**
+     * Write the explicit `aborted` event for the turn in flight, and fsync (D-19's graceful arm).
+     *
+     * A no-op between turns, deliberately: an `aborted` row for a turn that already carries its
+     * `turn_complete` would make the repair on the next open trim a turn that finished.
+     */
+    abortActiveTurn(): Promise<void>;
+}
+/** Compose the local agent host. */
+/**
+ * The two callers chat mints, one per stage (392, RESEARCH Pitfall 1 / 391 D-06).
+ *
+ * IDENTICAL BUT FOR `origin`. `FunctionCaller.origin` answers "did a person decide this", and inside
+ * ONE turn both answers occur: a person typing a canonical alias decided that call, and a model
+ * planning one did not. The receipts a turn logs record that origin per clause.
+ *
+ * `surface` is `'chat'` on both and is ATTRIBUTION ONLY. Nothing in the function layer may branch
+ * on it (`invoke.ts:28-29`).
+ *
+ * 2026-10-01 (432-20/432-21, D-12): no scope set and no safe-mode flag. `CHAT_STAGE_SCOPES`, the
+ * whole closed scope union both stages held, is deleted: every caller can call every operation, and
+ * the human-origin restriction the origin split once protected is deleted with `requiresHumanOrigin`.
+ */
+declare const CHAT_RESOLVER_CALLER: FunctionCaller;
+declare const CHAT_PLANNER_CALLER: FunctionCaller;
+declare function composeLocalAgent(input: ComposeLocalAgentInput): LocalAgentHost;
+
+/**
+ * How many jobs one `resumePending` call will run before it refuses to continue.
+ *
+ * A bound rather than a loop that trusts the queue to empty: recovery runs against a store any
+ * process may have written, and a chain that keeps enqueuing successors would otherwise turn a
+ * recovery call into an unbounded drain. Exceeding it raises rather than truncating — a resume that
+ * quietly stopped early would report success over work it left behind.
+ */
+declare const JOB_RECOVERY_MAX_RESUMED_JOBS = 64;
+interface ComposeJobRecoveryInput {
+    /** The project's runtime root, i.e. `<configDir>/.agent-qa`. Absolute. */
+    readonly agentQaRoot: string;
+    /** Every column and dump row this host writes is stamped from here (D-03). */
+    readonly clock: ClockPort;
+    /** Ids derived from `(kind, idempotencyKey)`, so a resumed chain addresses the same rows. */
+    readonly idSource: JobIdSource;
+    /**
+     * The capability a resumed job may author with, supplied by the host.
+     *
+     * Required and not defaultable, on the same reasoning as the queue's own option: an optional
+     * capability means a host can compose recovery with none, and the only place to discover that is
+     * inside an author callback far from the composition that forgot it.
+     */
+    readonly model: JobModelCapability;
+    /** Defaults to the six real declarations. Injected so a harness can drive its own handlers. */
+    readonly jobKinds?: JobKindRegistry;
+}
+interface JobRecoveryHost {
+    readonly store: SqliteJobStore;
+    readonly kinds: JobKindRegistry;
+    readonly queue: AgentJobQueue;
+    /**
+     * Return every outstanding claim to the queue, keeping the attempt each one spent.
+     *
+     * Call this FIRST. Only one process drains under a given fence, so at the moment authority is
+     * adopted every outstanding claim belongs to a host that is gone; calling it beside a live pump
+     * would reclaim a job from the handler still running it.
+     */
+    recoverAbandonedClaims(fence: JobStoreFence): Promise<RecoverAbandonedClaimsOutcome>;
+    /** Pump until no row is claimable. No timers, no sleeping — not a dispatcher. */
+    resumePending(fence: JobStoreFence, maxJobs?: number): Promise<readonly RunNextJobOutcome[]>;
+    close(): void;
+}
+declare function composeJobRecovery(input: ComposeJobRecoveryInput): JobRecoveryHost;
+
+/** Directory segment under the agent-qa runtime root. Gitignored, per D-17. */
+declare const CHAT_SESSIONS_SUBDIR = "sessions";
+/** A caller-supplied session id that could not be a path segment (T-392-01). */
+declare class InvalidChatSessionIdError extends Error {
+    readonly sessionId: string;
+    readonly name = "InvalidChatSessionIdError";
+    constructor(sessionId: string);
+}
+/**
+ * A session id that names no session.
+ *
+ * A REFUSAL and never a create (D-17, RESEARCH Open Q4). Creating a fresh session for a mistyped
+ * `--session` would tell a person their history was lost when in fact it was never looked at, and
+ * would do so in the one direction no later read can undo.
+ */
+declare class UnknownChatSessionError extends Error {
+    readonly sessionId: string;
+    readonly name = "UnknownChatSessionError";
+    constructor(sessionId: string);
+}
+/**
+ * A session somebody is already holding open (Phase 392 plan 12, T-392-BUSY).
+ *
+ * A REFUSAL BY NAME rather than a second descriptor. Two handles on one file would interleave two
+ * turns inside a single conversation — the same damage the cross-session aliasing did, one level
+ * down — and it is exactly what a double-submit of one `sessionId` over the daemon socket asks for.
+ * The remedy is to wait for the holder, which is why the id is on the error rather than only in
+ * the message.
+ */
+declare class ChatSessionBusyError extends Error {
+    readonly sessionId: string;
+    readonly name = "ChatSessionBusyError";
+    constructor(sessionId: string);
+}
+/** Bytes that do not describe a session this build can append to. */
+declare class ChatSessionHeaderError extends Error {
+    readonly sessionId: string;
+    readonly detail: string;
+    readonly name = "ChatSessionHeaderError";
+    constructor(sessionId: string, detail: string);
+}
+/**
+ * What a production caller supplies: a root and the session's opening context.
+ *
+ * The absence of an fs member is the guarantee, exactly as it is on `CreateJobCheckpointStoreOptions`.
+ */
+interface CreateJsonlSessionLogOptions {
+    /** Absolute path to the agent-qa runtime root, typically `<project>/.agent-qa`. */
+    readonly root: string;
+    /** ISO instant source — the composition's clock, never `Date.now()` reached for here. */
+    readonly now: () => string;
+    /**
+     * The model in force when the session opens. Drift is `model_change` events, never a rewrite.
+     *
+     * A THUNK rather than a string, because a composition root resolves its model lazily — a host
+     * that only lists the registry must not pay a provider resolution — and a header built from a
+     * value captured at construction would name whatever was true before that resolution ran.
+     */
+    readonly model: () => string;
+    /** The toolset fingerprint at open, on the same thunk reasoning as `model` above. */
+    readonly toolsetHash: () => string;
+    /**
+     * WHICH DOOR THIS LOG BELONGS TO (Phase 400 plan 03, D-04). Absent ⇒ no tag is written.
+     *
+     * A VALUE AND NOT A THUNK, which is the opposite of `model` and `toolsetHash` above and for the
+     * mirror of their reason. Those are resolved lazily because a composition's model can arrive
+     * after the log does and can drift afterwards; a surface cannot. Which door composed this host is
+     * decided at the composition root and is a constant for the life of the process, so a thunk would
+     * be a seam for a value to change through — and a header is written once and never rewritten,
+     * so a changing surface has nowhere to go.
+     *
+     * ABSENT IS THE PRE-400 CLI-CHAT POSTURE, stated in `ChatSessionHeader.surface` and preserved
+     * here: a host that names no surface writes a header byte-identical to the ones every build
+     * before this one wrote.
+     */
+    readonly surface?: string;
+    /** Random source for the id suffix, injectable so a test can pin an id. */
+    readonly random?: () => number;
+}
+/** One session, as a listing knows it: everything the header line says, plus how long the log is. */
+interface ChatSessionListEntry {
+    readonly sessionId: string;
+    readonly createdAt: string;
+    /** The model in force when the session OPENED. Drift after that is `model_change` events. */
+    readonly model: string;
+    /**
+     * Event lines on the file, counted without parsing one.
+     *
+     * An EVENT count and not a turn count, and the difference is not a shortcut. A turn count is not
+     * a header fact and cannot become one — the header is written once and never rewritten, which is
+     * the property CHAT-05 asks for by name — so the only way to produce one is to parse every line
+     * of every log, which is the work a listing exists to avoid. The line count answers "is there
+     * anything in here" for a fraction of the cost, and `open()` answers everything else.
+     */
+    readonly eventCount: number;
+}
+/** One session file the listing could not read, surfaced as data rather than thrown over. */
+interface RefusedChatSessionFile {
+    /** The file's own name, which is what a person has to go and look at. */
+    readonly file: string;
+    readonly reason: string;
+}
+interface ChatSessionListing {
+    readonly sessions: readonly ChatSessionListEntry[];
+    readonly refused: readonly RefusedChatSessionFile[];
+}
+/**
+ * `chat-<UTCyyyymmdd-HHMMSS>-<4 base36>`.
+ *
+ * Sorted-by-name equals sorted-by-time, which is what makes a plain directory listing the session
+ * list; the random tail is what keeps two sessions opened in the same second distinct. Every
+ * character is in `SAFE_PATH_SEGMENT` by construction, so a minted id can never be refused by the
+ * guard that protects a supplied one.
+ */
+declare function mintChatSessionId(nowIso: string, random: () => number): string;
+/**
+ * Every session under one runtime root, read from headers alone (D-17).
+ *
+ * A DAMAGED FILE IS DATA, NOT AN EXCEPTION — the posture the grant ledger had (391; deleted in 432-18).
+ * A corrupt neighbour costs the caller that one entry and nothing else; throwing would let a single
+ * unreadable file hide every healthy session from the person trying to find their conversation.
+ *
+ * It reads through the real filesystem with no injection seam, and that absence is on purpose: the
+ * seam beside `createJsonlSessionLogOn` exists because syscall ORDER is a durability property no
+ * crash test can observe. A listing has no such property. What it returns is its whole contract,
+ * and a temp directory proves that directly.
+ */
+declare function listSessions(root: string): ChatSessionListing;
+declare function createJsonlSessionLog(options: CreateJsonlSessionLogOptions): SessionLogPort;
+
+interface CreateMemorySessionLogOptions {
+    readonly now: () => string;
+    readonly model: () => string;
+    readonly toolsetHash: () => string;
+    readonly random?: () => number;
+}
+interface MemorySessionLog extends SessionLogPort {
+    /** Everything written, for assertions. A copy, so a caller cannot edit the log through it. */
+    snapshot(sessionId: string): OpenedChatSession | undefined;
+}
+declare function createMemorySessionLog(options: CreateMemorySessionLogOptions): MemorySessionLog;
+
+/**
+ * The local implementation of the neutral persistence port.
+ *
+ * 2026-07-29 (Phase 385 plan 02, D-06): this alias now covers approvals and patches ONLY.
+ * Job rows and checkpoints left the port for the agent job queue's own store, whose verbs are
+ * compound and transactional rather than generic CRUD, and the conversation surface left it
+ * entirely. The alias is deliberately narrower than the package's name suggests, and saying
+ * so here is cheaper than letting a later reader infer that anything job-shaped belongs
+ * behind it.
+ *
+ * The job store itself is not on this barrel. It is reachable by relative path within the
+ * package and is published, if at all, by the composition root — a store that any importer
+ * can construct is a second way to open the database beside the one the host owns.
+ */
+type LocalPersistenceStore = PersistencePort;
+
+export { type ApplyKnowledgeChangeInput, type AttachableRunSession, BRIEF_CEILING, BRIEF_FRACTION, type BuildMemberRunConfigInput, CAUTION_FRACTION, CHAT_PLANNER_CALLER, CHAT_RESOLVER_CALLER, CHAT_SESSIONS_SUBDIR, type CandidateProsePosture, ChatSessionBusyError, ChatSessionHeaderError, type ChatSessionListEntry, type ChatSessionListing, type ComposeJobRecoveryInput, type ComposeLocalAgentInput, type ComputeKnowledgeBudgetsInput, type ConstructKnowledgeReaderInput, type CreateEvidenceBlobReaderInput, type CreateJsonlSessionLogOptions, type CreateKnowledgeReviewInput, type CreateMemorySessionLogOptions, DIGEST_JOB_ID_SOURCE, type DraftAuthoringPort, type DraftParseOutcome, type DraftStageOutcome, GLOBAL_RECORD_CAP, InvalidChatSessionIdError, JOB_RECOVERY_MAX_RESUMED_JOBS, type JobRecoveryHost, type KnowledgeBudgets, LOCAL_CURATION_CAPABILITIES, LOCAL_DAEMON_CAPABILITIES, LOCAL_KNOWLEDGE_PROBES, LocalAgentClosedError, type LocalAgentHost, type LocalAgentJobs, type LocalCurationCapabilities, type LocalDaemonCapabilities, type LocalKnowledgeMaintenanceCapabilities, type LocalKnowledgeProbeCapabilities, type LocalPersistenceStore, MIN_BRIEF, MIN_CAUTION, MIN_MEMORY_TOOL_CONTEXT_WINDOW, type MemorySessionLog, type OpenRunKnowledgeCompositionInput, type ParsedDraftDescriptor, type PromoteWithReceiptsInput, READ_BODY_FRACTION, REFUSED_RUN_REQUEST_FIELDS, type RecordGateReceiptInput, type RefusedChatSessionFile, type RetrievalRungResolver, type RunAssembler, type RunAssemblyContext, type RunConfigDigests, RunDeniedError, type RunDigestMemberInput, type RunExecutionContext, type RunExecutionPort, RunIdAlreadyInUseError, RunIdNotMintedError, type RunInvocationCoreOptions, type RunKnowledgeComposition, type RunPersistencePorts, RunProducedNoEventsError, type RunQuarantineSnapshotInput, RunRequestFieldRefusedError, type RunSubscriberHandle, type RunTargetClass, type RunTargetDeclaration, SUITE_LIFECYCLE_LANE, SYSTEM_CLOCK, SuiteBoundaryWhileLiveError, type SuiteLifecycle, type SuiteLifecycleHooks, type SuiteMemberBinding, type SuiteMemberLease, type SuiteTextEntry, type SweepEntityIndexInput, type SweepEntityIndexOutcome, UNCLAIMABLE_BY_PROSE_POSTURE, UnknownChatSessionError, WEAK_MODEL_CAP_SCALE, applyKnowledgeChange, buildMemberRunConfig, buildRunPorts, buildScreenshotCompressor, buildSuiteMemberExecutor, composeJobRecovery, composeLocalAgent, computeKnowledgeBudgets, computeRunConfigDigests, constructKnowledgeReader, createEvidenceBlobReader, createFrozenKnowledgeReader, createJsonlSessionLog, createKnowledgeReader, createKnowledgeReview, createLocalRunInvocation, createMemorySessionLog, createRunInvocationCore, createRunsReader, createSuiteLifecycle, listSessions, lookupEvidenceBlob, memoryToolGate, mintChatSessionId, openRunKnowledgeComposition, readEvidenceBlobBytes, refuseProductionWithoutOptIn, refuseUnavailableRunId, registerAdapterLiveStream, resolveBuildTagSetting, resolveHostRetrievalRung, resolveRunBuildOrdinal, resolveRunExecutionContext, resolveRunQuarantineSnapshot, scaledRecordCap, statEvidenceBlob, sweepEntityIndexProjection, toMemberTest };