audit-tools 0.32.19 → 0.32.22

package/dist/remediate/steps/dispatch.d.ts

@@ -1,864 +1,17 @@
-import { type RemediationState } from "../state/store.js";
-import { type RemediationBlock } from "../state/types.js";
-import type { SessionConfig, HostConcurrencyLimit, WaveSchedule, QuotaStateEntry, ResolvedProviderName, DispatchCapacityPoolSummary, HostModelRosterEntry, CapacityPool, ProviderSlot, RollingDispatchResult } from "audit-tools/shared";
-import { HostSessionQuotaSource } from "audit-tools/shared";
-import { type DispatchModelHint, type DispatchPhase, type ImplementWorkerResult, type RemediationDispatchPlan, type RemediationDispatchQuota } from "./types.js";
-import { resolveHostActiveSubagentLimit } from "../quota/index.js";
-export { resolveHostActiveSubagentLimit };
-export { detectHostActiveSubagentLimit as detectHostConcurrencyFromEnv, } from "../quota/hostLimits.js";
-export type { HostConcurrencyLimit };
-export interface ScheduleWaveInput {
-    hostMaxConcurrent?: number | null;
-    sessionConfig: SessionConfig | null;
-    itemCount: number;
-    estimatedSlotTokens?: number[];
-    providerName?: ResolvedProviderName;
-    hostModel?: string | null;
-    /** Context window the host reports for its dispatch model (handshake). */
-    hostContextTokens?: number | null;
-    /** Output cap the host reports for its dispatch model (handshake). */
-    hostOutputTokens?: number | null;
-    /**
-     * Ordered model roster (lowest rank first) from the multi-rank handshake
-     * (`--host-models`); outranks the scalar pair. One capacity pool is built per
-     * reported rank, each with its own discovered window.
-     */
-    hostModels?: HostModelRosterEntry[] | null;
-    /**
-     * Opaque model identity for the quota key when no model name resolves —
-     * a key segment ONLY (`provider/<id>`), never a window authority.
-     */
-    hostModelId?: string | null;
-    env?: NodeJS.ProcessEnv;
-}
-export declare function normalizeSlotTokens(tokens: number[] | undefined, count: number): number[];
-export interface WaveScheduleResult extends WaveSchedule {
-    host_concurrency_limit: HostConcurrencyLimit | null;
-    capacity_pools?: DispatchCapacityPoolSummary[];
-}
-export declare function resolveHostConcurrencyLimit(options: {
-    hostMaxConcurrent?: number | null;
-    sessionConfig: SessionConfig | null;
-    env?: NodeJS.ProcessEnv;
-}): HostConcurrencyLimit | null;
-export declare function scheduleWave(input: ScheduleWaveInput): Promise<WaveScheduleResult>;
-/**
- * Build the confirmed `CapacityPool[]` for a dispatch — one pool per reported
- * roster rank (each with its own discovered window + quota key), or a single
- * conservative pool for the scalar/absent handshake. This is the same pool shape
- * `scheduleWave` constructs internally; it is exposed so the rolling dispatch
- * engine (which is fed `confirmedPools` directly) sizes concurrency from the
- * identical quota inputs, never from a raw host flag. Reused by
- * `driveRollingImplementDispatch`.
- */
-export declare function buildConfirmedPools(input: {
-    sessionConfig: SessionConfig | null;
-    hostMaxConcurrent?: number | null;
-    hostContextTokens?: number | null;
-    hostOutputTokens?: number | null;
-    hostModels?: HostModelRosterEntry[] | null;
-    hostModelId?: string | null;
-    env?: NodeJS.ProcessEnv;
-    /**
-     * The host-session source the rolling driver RETAINS to feed `recordLimit` and
-     * read `isPacketEscalated`. Passed in (not constructed anonymously here) so the
-     * driver threads the SAME instance through pool sizing AND the dispatcher's
-     * write/read escalation hooks — otherwise the bounded-escalation chain is unfed.
-     * Omit on the proactive-sizing-only paths; one is constructed internally.
-     */
-    hostSession?: HostSessionQuotaSource;
-    /** Defect-1: demote the primary in-process backend to a source when an attended host drives. */
-    demotePrimaryInProcess?: boolean;
-}): Promise<CapacityPool[]>;
-export declare function buildDispatchQuota(runId: string, phase: DispatchPhase, schedule: WaveScheduleResult, admissionPackets: {
-    id: string;
-    inputTokens: number;
-    complexity: number;
-}[], 
-/**
- * Whether to LEASE the granted set against the shared reservation ledger. The
- * host-subagent path passes `true` (the host dispatches the grant across processes,
- * so the tool reserves-before-dispatch and reconciles at accept-node). The
- * in-process rolling engine passes `false`: it admits + leases per-packet itself, so
- * a host-grant lease here would double-count the same work. Mirrors audit's
- * `finalizeDispatchQuota` grantLeases parameterization.
- */
-grantLeases: boolean, quotaStateEntry?: QuotaStateEntry | null, 
-/**
- * Operator-confirmed cost ordering (rung 1 of costRank; spec/cost-first-routing.md),
- * keyed by model id → 0-based confirmed position. Absent ⇒ price then tier.
- */
-confirmedCostPositions?: Map<string, number> | null): Promise<RemediationDispatchQuota>;
-/** Module-level cache: repo root → formatted conventions string. */
-export declare const detectRepoConventionsCache: Map<string, string>;
-export interface WorktreeVerifyResult {
-    passed: boolean;
-    output: string;
-}
-/**
- * The git top-level directory containing `cwd`, or `null` when `cwd` is not
- * inside a git working tree (or git is unavailable). `git rev-parse
- * --show-toplevel` emits a forward-slash absolute path on every platform.
- */
-export declare function gitTopLevel(cwd: string): string | null;
-/**
- * Create an isolated git worktree on a fresh branch at HEAD. Throws on non-zero exit.
- *
- * Refuses when `root` is not ITSELF a git top-level: a bare `git worktree add`
- * with `cwd: root` walks UP to the nearest enclosing repo and silently creates
- * the worktree/branch in that ancestor (observed polluting the monorepo with
- * leaked `remediate-*` branches during the rolling_engine flip). The resolved
- * top-level must equal the target root, or we refuse rather than escape.
- */
-export declare function createWorktree(root: string, worktreePath: string, branchName: string): void;
-/**
- * Materialize into a fresh worktree any of the node's declared target paths that
- * exist in the main tree but are absent from the worktree — i.e. git-untracked or
- * gitignored files that `git worktree add HEAD` does not bring over. Without this
- * a node whose scope names an untracked config file (the dogfood hit
- * `opencode.json` and an uncommitted `.gemini/commands/*.toml`) cannot see its own
- * target, so the edit silently no-ops. The "absent in worktree" test is the
- * discriminator: a tracked path is already materialized from HEAD, so only the
- * genuinely-missing untracked/ignored declarations are copied — a tracked-but-dirty
- * file keeps its clean-from-HEAD worktree content and is never clobbered. Paths are
- * repo-relative (the declared scope contract); absolute/escaping paths are skipped.
- * Best-effort: a copy failure must not abort the dispatch (logged, not thrown).
- */
-export declare function seedUntrackedDeclaredPaths(root: string, worktreeRoot: string, declaredPaths: Iterable<string>): void;
-/** Remove a git worktree. Best-effort: logs but does not throw on failure. */
-export declare function removeWorktree(root: string, worktreePath: string): void;
-/**
- * Fully reset a node's isolated worktree + branch so a fresh `createWorktree -b`
- * can run, even when a prior attempt left either behind. This is the idempotent
- * cleanup the in-process driver needs across a `rate_limited` re-queue: the
- * engine re-enters the dispatcher for the SAME block while its branch (and maybe
- * a stale worktree admin entry) still exist, and `git worktree add -b <branch>`
- * would otherwise fail with "branch already exists". Removing the worktree,
- * pruning stale admin records, then force-deleting the branch makes every
- * (re-)dispatch start clean from HEAD. All steps are best-effort (a missing
- * worktree/branch is the expected first-attempt case, not an error). Any partial
- * edits from a throttled prior attempt are intentionally discarded — the
- * re-dispatch redoes the node from HEAD.
- */
-export declare function resetNodeWorktreeAndBranch(root: string, worktreePath: string, branchName: string): void;
-/**
- * Run each targeted command in the worktree directory. Returns pass/fail and
- * combined output.
- *
- * `targeted_commands` are opaque host-authored command *strings* (e.g.
- * `npm run build`, `grep -c '/packages/' .gitignore`, anything with pipes,
- * quotes, or redirections), NOT pre-tokenized argv. They are run through the
- * platform shell (`runShellCommand` → `spawnSync(..., { shell: true })`, the
- * same path `close.ts` uses for `test_command`/`e2e_command`) so the shell — not
- * a word-split + `spawnSync(shell:false)` — resolves the verb. That is what
- * makes this OS-agnostic: on win32 `cmd.exe` natively execs `.cmd` shims (npm,
- * npx, …) and resolves PATH commands; on darwin/linux `/bin/sh` does. The prior
- * argv path ENOENT'd the *spawn itself* for any verb that wasn't a bare
- * executable (e.g. `grep` on Windows), turning a correct fix into a phantom
- * contract failure that burned the retry budget.
- */
-export declare function verifyNodeInWorktree(worktreePath: string, targetedCommands: string[]): WorktreeVerifyResult;
-/** Merge the worktree branch into the current HEAD via cherry-pick. On failure, removes the worktree and returns the error. */
-export declare function mergeWorktree(root: string, worktreePath: string, branchName: string): {
-    success: true;
-} | {
-    success: false;
-    error: string;
-};
-/**
- * Repo-relative tracked paths in the MAIN checkout that have uncommitted changes
- * AND collide with a path the node's branch edits. A pre-existing dirty tracked
- * file the cherry-pick would touch makes `git cherry-pick` abort with the opaque
- * "Your local changes to the following files would be overwritten by merge" — a
- * condition the node itself cannot fix and that identically re-fails every
- * auto-retry (observed: a docs-only node routed to human triage over unrelated
- * uncommitted WIP on the same file). Detected here so `acceptNodeWorktree` can
- * surface the actionable cause (which file, commit-or-stash) instead of the raw
- * git error. Best-effort: an unavailable diff / status probe returns `[]` (fall
- * through to the normal cherry-pick, which reproduces the original behaviour).
- */
-export declare function dirtyMainTreeCollisions(root: string, branch: string): string[];
-/**
- * Rebase a node's worktree branch onto the main checkout's current HEAD (the
- * remediation branch tip) so a sibling that merged AFTER this worktree was created
- * is folded in before this node verifies and merges. Additive edits to a shared
- * file merge automatically (git's per-commit 3-way); a true hunk conflict is a
- * genuine seam that aborts cleanly so the node routes to triage instead of landing
- * a broken merge. The branch is checked out in the worktree, so the rebase runs
- * there. A no-op (branch already on HEAD — the common, no-sibling-merged case)
- * succeeds. Leaves the branch on its pre-rebase commit on abort (so the failed
- * node's work can still be quarantined).
- */
-export declare function rebaseBranchOntoHead(root: string, worktreePath: string, branch: string): {
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-};
-/** Worktree path for a remediation block. */
-export declare function worktreePath(root: string, blockId: string, runId: string): string;
-export declare function remediationBranchName(runId: string): string;
-/**
- * Lock path for the base-mutating accept critical section (INV-2/CE-001), keyed on
- * the base repo root + run's remediation branch. DISTINCT from the per-run
- * `rolling-session.lock` (`withFileLock` is non-reentrant — an exclusive `wx`
- * create — so the base lock MUST be a different path than the session lock
- * `advanceHostRolling` already holds, or the nested acquire would self-deadlock).
- * Both rolling drivers (host-subagent + in-process) serialize the rebase →
- * cherry-pick → cross-package check → reset sequence through this single lock.
- */
-export declare function baseBranchLockPath(root: string, runId: string): string;
-/** Durable ref under which a failed-but-committed node's commit is preserved. */
-export declare function quarantineRef(runId: string, blockId: string): string;
-/**
- * Preserve a failed-but-committed node's work so it can never be lost. A node that
- * committed real edits to its worktree branch but then failed verify / the
- * write-scope gate / the cherry-pick is about to have its worktree removed and (on
- * the next re-dispatch) its branch force-deleted — orphaning the commit. The dogfood
- * lost a verified fix exactly this way (the worktree was pruned before recovery).
- * Point a durable ref at the branch tip: a ref under refs/remediation-quarantine/
- * survives `git branch -D` and `git worktree prune`, so the work stays reachable for
- * a manual `git cherry-pick`. Best-effort; returns the ref + commit, or null.
- */
-export declare function quarantineFailedNodeCommit(root: string, branch: string, runId: string, blockId: string): {
-    ref: string;
-    commit: string;
-} | null;
-/**
- * Preserve a failed-but-UNCOMMITTED node's worktree edits before the worktree is
- * removed. The verify / scope / merge-fail paths quarantine an already-committed
- * branch tip; this is the missing twin for the commit-REFUSAL path: when
- * `commitWorktree` fails loudly (e.g. a generated artifact landed under the write
- * scope — the genuine CE-003 fail-loud), the worker's real source edits are still
- * sitting uncommitted in the worktree and would be destroyed by `removeWorktree`.
- * Stage everything and land a preservation commit on the node's ISOLATED branch
- * (never cherry-picked into main — it exists only so a durable quarantine ref can
- * point at the otherwise-lost work), then quarantine that commit. A guard that
- * destroys good work is worse than the bug it guards. Best-effort; returns the
- * quarantine ref + commit, or null when there was nothing to preserve / it failed.
- */
-export declare function quarantineUncommittedWorktreeEdits(root: string, worktreeRoot: string, branch: string, runId: string, blockId: string): {
-    ref: string;
-    commit: string;
-} | null;
-/** Clear a node's quarantine ref (e.g. once a later re-dispatch landed successfully). Best-effort. */
-export declare function clearQuarantinedCommit(root: string, runId: string, blockId: string): void;
-/** Quarantined failed-node commits still preserved for a run, for recovery surfacing in the report. */
-export declare function listQuarantinedCommits(root: string, runId: string): Array<{
-    block: string;
-    ref: string;
-    commit: string;
-}>;
-/**
- * Ensure the main checkout is on the dedicated remediation branch BEFORE any node
- * commit is cherry-picked, so accepted work lands there and the user's base branch
- * is NEVER modified — the run leaves a feature branch for review (it does not merge
- * back). Idempotent across waves: creates the branch from the current HEAD (the base)
- * the first time, checks it out on later waves. Best-effort on a non-git root (the
- * worktree dispatch flow can't run there anyway): returns null without throwing so
- * non-git callers/tests are unaffected. Returns the branch name on success.
- */
-/** Sidecar recording the base branch the run was launched from (B5). */
-export declare function remediationBaseBranchPath(artifactsDir: string): string;
-/**
- * The base branch this run was launched from, recorded when the remediation
- * branch was first created. `null` when unrecorded (e.g. a detached HEAD at
- * launch, or a branch created by a prior run) — the opt-in merge-to-base
- * closing action degrades to "merge manually" rather than guessing a target.
- */
-export declare function readRemediationBaseBranch(artifactsDir: string): string | null;
-export declare function ensureRemediationBranchCheckedOut(root: string, runId: string, artifactsDir?: string): string | null;
-export declare function commitWorktree(worktreeRoot: string, message: string, declaredWritePaths?: string[]): {
-    committed: boolean;
-    error?: string;
-};
-/**
- * Make the main checkout's installed `node_modules` available to a worktree. A
- * fresh `git worktree add` checks out only tracked files, and `node_modules` is
- * gitignored, so per-node verify commands (`npm run check`, focused tests) would
- * otherwise fail with missing dependencies. Best-effort junction/symlink to the
- * main root's `node_modules`; on failure it logs and the verify step surfaces the
- * missing-deps error rather than crashing the dispatch. NOTE: workspace package
- * symlinks inside `node_modules/@audit-tools/*` point back into the MAIN checkout,
- * so cross-package runtime resolution sees the main tree — the authoritative
- * cross-package re-check is the central post-merge build/gate, not this fast
- * per-node verify (which gates obvious breakage early).
- */
-export declare function ensureWorktreeNodeModules(mainRoot: string, worktreeRoot: string): void;
-/** Worker transport outcome (mirrors shared `RollingDispatchResult["outcome"]`). */
-export type NodeWorkerOutcome = "success" | "error" | "rate_limited" | "timeout";
-export interface AcceptNodeWorktreeParams {
-    root: string;
-    runId: string;
-    blockId: string;
-    /** The node's isolated worktree directory. */
-    worktreeRoot: string;
-    /** The node's worktree branch (`worktreeBranchForBlock`). */
-    branch: string;
-    /** The worker's transport outcome from the node dispatcher. */
-    workerOutcome: NodeWorkerOutcome;
-    /**
-     * Per-node verify commands. OMIT (leave `undefined`) for the real rolling drivers:
-     * the gate then DERIVES the verify from the node's actually-touched test files
-     * post-commit ({@link deriveVerifyCommandsFromBranch}) — correct paths/runner by
-     * construction, never the whole suite. Pass `[]` to skip the gate (lifecycle unit
-     * tests on a minimal temp repo), or an explicit list to force specific commands.
-     */
-    targetedCommands?: string[];
-    /**
-     * The node's own `targeted_commands` (the auditor/finding-specified verification),
-     * run IN ADDITION to the derived commands — filtered to the build-free subset and
-     * deduped against the derive. The derive gives correct-paths-by-construction; these
-     * add the fix-specific regression checks the derive misses when a fix touches no test
-     * (task_7d35176d). Omit / `[]` → derive-only (the prior behaviour). Ignored when
-     * `targetedCommands` is an explicit override (the lifecycle unit-test path).
-     */
-    additionalVerifyCommands?: string[];
-    /**
-     * Accept-time write-scope inputs (OBL-DS-06). The write-scope gate runs HERE —
-     * after the verify, BEFORE the cherry-pick — so an out-of-scope or seam-conflicting
-     * edit is PREVENTED from landing in the main tree rather than reported post-hoc once
-     * it is already merged. REQUIRED (not optional): both rolling drivers always derive
-     * it from the plan, so a production caller can never silently skip the gate — that
-     * enforcement is the type, not host discretion (E1). A lifecycle test that does not
-     * exercise scope passes `{ allBlockScopes: [] }`: an empty registry owns nothing, so
-     * every edit is unowned-and-granted → the gate is a sound no-op, never a skip.
-     */
-    scope: {
-        /** Every block's declared write scope, for amendment ownership adjudication. */
-        allBlockScopes: Array<{
-            block_id: string;
-            write_paths: string[];
-        }>;
-    };
-    /**
-     * The block's OWN declared write paths (INV-1). Threaded into `commitWorktree`
-     * so worker-created new SOURCE files under scope are force-added past
-     * `.gitignore` and a generated-artifact / out-of-scope new file fails loudly.
-     * Omit (lifecycle unit tests with no scope) → no new-file inclusion.
-     */
-    writePaths?: string[];
-    /**
-     * The cross-package check command (argv) run in the MAIN checkout AFTER the
-     * cherry-pick lands (INV-2): a RED check rolls the base back to its captured HEAD
-     * OID. When omitted, the command is PINNED — derived from the repo via
-     * `mergedBaseCheckArgv` (the `check`-layer of the tool-owned gate set), not a
-     * hardcoded string — and skipped (`null`) on a non-monorepo target. Tests inject a
-     * deterministic pass/fail argv (a `t.mock.module` seam is unusable under tsx/esm).
-     * Pass `null` to skip the merged-base check entirely (legacy lifecycle unit tests
-     * on a minimal repo with no check script).
-     */
-    mergedBaseCheckCommand?: string[] | null;
-}
-export interface AcceptNodeWorktreeResult {
-    /** The LIFECYCLE outcome (verify/merge applied), distinct from the worker transport outcome. */
-    outcome: NodeWorkerOutcome;
-    verifyPassed: boolean;
-    merged: boolean;
-    /**
-     * On a failure outcome, the captured failing command + its output — the verify
-     * stdout/stderr (`$ <cmd>\n<output>`), or the git commit / cherry-pick error text.
-     * Persisted into the accept-outcome sidecar so triage can see the root cause
-     * instead of an `outcome:error` with no captured stderr. Absent on success.
-     */
-    diagnostic?: string;
-}
-/**
- * The shared post-worker "accept node" lifecycle, extracted so BOTH rolling
- * drivers reuse identical correctness: the in-process provider engine
- * (`driveRollingImplementDispatch`) calls it inline once the worker returns; the
- * host-subagent driver calls it from the `accept-node` callback once a host
- * subagent finishes.
- *
- * Given a completed worker run in an isolated worktree, this: (1) TOOL-commits
- * the worker's edits onto the branch (deterministic, never the worker/host) so
- * the branch diff is the write-scope ground truth; (2) runs the per-node verify
- * IN the worktree BEFORE accepting; (3) merges via cherry-pick only on a passing
- * verify; and (4) drops the worktree on any failure so the main tree is never
- * dirtied by an unverified change. It returns the LIFECYCLE outcome (which the
- * caller records for the deterministic merge); the caller still returns the
- * worker's TRANSPORT outcome to the rolling engine (so a `rate_limited` worker
- * re-queues, while a verify-failure is adjudicated by the merge → triage).
- *
- * SAFETY: the main tree is touched only through `mergeWorktree` (cherry-pick of a
- * verified branch, aborts cleanly on conflict). No state mutation here — the
- * caller persists via `mergeImplementResults`.
- */
-export declare function acceptNodeWorktree(params: AcceptNodeWorktreeParams): Promise<AcceptNodeWorktreeResult>;
-/**
- * Sidecar path for a node's tool-owned accept (verify/merge) outcome. Written by
- * BOTH rolling drivers as each node is accepted, read by `mergeImplementResults`.
- * Block ids here follow the same filename-safe convention as the per-node result
- * files in the same dir.
- */
-export declare function nodeAcceptOutcomePath(artifactsDir: string, runId: string, blockId: string): string;
-/**
- * Persist a node's `acceptNodeWorktree` lifecycle outcome so finalization can tell
- * a node whose edits actually LANDED (merged) from one that self-reported "resolved"
- * but failed tool-owned verify / merge (OBL-DS-06: never trust the worker's self
- * report). Both rolling drivers (host-subagent `advanceHostRolling` and in-process
- * `driveRollingImplementDispatch`) call this; the interim main-tree path writes none,
- * so the merge-state gate is inert there.
- */
-export declare function recordNodeAcceptOutcome(artifactsDir: string, runId: string, blockId: string, result: AcceptNodeWorktreeResult): Promise<void>;
-/** Load a node's recorded accept outcome, or null when none was written. */
-export declare function loadNodeAcceptOutcome(artifactsDir: string, runId: string, blockId: string): Promise<AcceptNodeWorktreeResult | null>;
-/**
- * The per-node worktree worker an in-process driver launches: it edits within the
- * node's isolated worktree (cwd-confined), writes its result file, and returns the
- * transport outcome. `makeProviderNodeDispatcher` is the live implementation; tests
- * inject a stub. Structurally identical to `nextStep`'s `ProgrammaticNodeDispatcher`.
- */
-export type WorktreeNodeWorker = (args: {
-    block: RemediationBlock;
-    slot: ProviderSlot;
-    worktreeRoot: string;
-    resultPath: string;
-}) => Promise<RollingDispatchResult<{
-    block_id: string;
-}>>;
-/** One node's worktree-lifecycle result: the worker transport outcome + the accept lifecycle. */
-export interface NodeWorktreeExecution {
-    /** Worker transport outcome the rolling engine consumes (success/error/rate_limited/timeout). */
-    result: RollingDispatchResult<{
-        block_id: string;
-    }>;
-    /** Tool-owned accept outcome (commit→verify→merge), already persisted via recordNodeAcceptOutcome. */
-    accept: AcceptNodeWorktreeResult;
-}
-/**
- * Run ONE node's full in-process lifecycle in an isolated worktree — shared by BOTH
- * in-process callers (the reactive `driveRollingImplementDispatch` engine and the
- * A-8 hybrid executor) so they create / commit / verify / merge identically:
- *
- *   reset + create the node's worktree → link node_modules → seed declared targets →
- *   launch the worker (`dispatchNode`) → `acceptNodeWorktree` (tool-commit, rebase,
- *   verify, write-scope gate, cherry-pick) → persist the accept outcome.
- *
- * Claim ownership is the CALLER's concern (the reactive engine claims through the
- * shared registry; the hybrid executor is handed a coordinator-minted claim), so
- * this fn neither claims nor releases — it returns the worker transport result AND
- * the accept lifecycle outcome and lets the caller record `nodeOutcomes` / release.
- * Any thrown error degrades to a dropped worktree + a persisted `error` accept
- * outcome, never an unhandled rejection into the engine.
- */
-export declare function executeNodeInWorktree(args: {
-    block: RemediationBlock;
-    slot: ProviderSlot;
-    root: string;
-    artifactsDir: string;
-    runId: string;
-    resultPath: string;
-    /** Untracked declared targets to seed into the worktree (the node's write set or write∪read). */
-    seedPaths: string[];
-    /** Every block's declared write scope, for the accept-time write-scope gate (OBL-DS-06). */
-    allBlockScopes: Array<{
-        block_id: string;
-        write_paths: string[];
-    }>;
-    /** The node's own targeted_commands, run IN ADDITION to the derived verify (task_7d35176d). */
-    additionalVerifyCommands?: string[];
-    dispatchNode: WorktreeNodeWorker;
-}): Promise<NodeWorktreeExecution>;
-export interface DispatchOptions {
-    root: string;
-    artifactsDir: string;
-}
-/**
- * The implementation-DAG node fields `promoteImplementationDagToExtractedPlan`
- * writes onto each Finding (one node ↔ one finding ↔ one block in the contract
- * pipeline). The shared `Finding` type does not declare these overlay fields, so
- * they are read through this structural view rather than added to the shared
- * contract. Every field is optional: a finding sourced from a plain
- * `audit-findings.json` (not the contract pipeline) carries none of them and the
- * seam degrades to the block-level behavior.
- */
-export interface DagNodeFields {
-    /** Relative model rank for the node (small | standard | deep). Never a model name. */
-    model_tier?: "small" | "standard" | "deep";
-    /** Upstream contracts' declared outputs this node builds on. */
-    preconditions?: string[];
-    /** Human-readable description of the concrete changes the node is expected to produce. */
-    expected_changes?: string;
-    /** Human-readable verification checks beyond `targeted_commands`. */
-    verification?: string[];
-    /**
-     * Reconciliation expectations carried from seam reconciliation: what an
-     * upstream/neighbor contract agreed to provide this node, expressed either as
-     * a list of strings or, when richer, as the precondition list. Read tolerantly
-     * because the promotion shape can vary across pipeline versions.
-     */
-    reconciliation_expectations?: string[];
-}
-/**
- * The host manages the build centrally; a per-node verify command that runs
- * `npm run build` (or a `npm test` whose package script prepends a build) races
- * the central build's dist/ and is therefore forbidden. A command is build-free
- * only when it neither builds nor invokes a build-prepending test script.
- *
- * Forbidden (return false):
- *  - `npm run build` / `npm run build -w ...` / `tsc` emit (`tsc -b`, `tsc --build`)
- *  - bare `npm test` / `npm t` / `npm run test` (the package script prepends build)
- *
- * Allowed (return true):
- *  - `npm run check` (no emit)
- *  - `npx vitest run <path>` / `vitest run <path>`
- *  - `node --test <path>`
- */
-export declare function isBuildFreeVerifyCommand(cmd: string): boolean;
-/**
- * Inject the tsx ESM loader into a bare `node --test <file>` command so the `.mjs`
- * node:test suites (which import `audit-tools/shared` via tsconfig `paths`, honored
- * only by tsx) resolve in a per-node worktree with no built `dist/`. A host- or
- * DAG-authored `node --test tests/audit/x.test.mjs` would otherwise fail module
- * resolution; the tool normalizes it so correctness can't depend on the host
- * remembering to add the loader. Idempotent: a command already carrying
- * `--import tsx/esm` or a `--loader` is left untouched. Mirrors the runner the
- * derived verify uses ({@link verifyCommandsForEdits}), so the displayed per-node
- * command and the in-process verify match.
- */
-export declare function normalizeNodeTestCommand(cmd: string): string;
-/**
- * True when `cmd` is a test-runner invocation whose target is a whole directory
- * or the entire suite rather than specific test files — e.g. `npx vitest run
- * tests/remediate`, `vitest run` (no path), `node --test tests/audit/`. Such a
- * command, run as an *additional* per-node verify alongside the scoped derive,
- * re-enters the FULL suite inside a per-node worktree. That is the structural
- * deadlock proven 2026-06-30: a source node's whole-suite verify fails on a
- * stale test owned by a DIFFERENT node, and concurrent worktrees race shared
- * test temp dirs. The derived verify already runs this node's OWN touched
- * tests, so a host/DAG-authored whole-suite command adds only risk — the tool
- * drops it rather than relying on the author to scope it (enforce-in-tooling,
- * never host discretion). A command naming at least one concrete `.test.<ext>`
- * file is scoped and kept.
- */
-export declare function isWholeSuiteTestCommand(cmd: string): boolean;
-/**
- * Repo-relative path-like tokens in a shell command — tokens containing a `/` and a
- * file extension (e.g. `scripts/remediate/verify-hosts.mjs`, `tests/x.test.ts`).
- * Used to decide whether a targeted verify command is self-contained.
- */
-export declare function pathTokensInCommand(cmd: string): string[];
-/**
- * Keep only the targeted verify commands that are SELF-CONTAINED for this node:
- * every path-like token they reference is either one of the node's own paths (its
- * declared write set ∪ the files it actually edited on its branch) or already
- * present in the tree. A command referencing a path this node doesn't own and that
- * isn't in the tree depends on a SIBLING node's not-yet-created deliverable —
- * running it in per-node verify is a guaranteed-fail deadlock (proven 2026-07-03: a
- * node's `targeted_command` was `node scripts/remediate/verify-hosts.mjs`, another
- * node's pending output). Per-node verify must be self-contained; such a cross-node
- * command is dropped here and deferred to the integration/close gate. A command with
- * no path tokens (e.g. `npm run check`) is always kept.
- */
-export declare function selfContainedVerifyCommands(commands: string[], ownPaths: Iterable<string>, treeRoot: string): string[];
-/**
- * Derive a node's per-node verify commands from the test files it ACTUALLY touched
- * on its worktree branch (the git ground truth), instead of trusting host-authored
- * `targeted_commands` whose paths/runner can drift from where the worker put the
- * test. Always typechecks (`npm run check`, no emit), then runs ONLY this node's
- * own touched test files with the repo's runners — never the whole suite (which
- * would re-enter worktree-spawning tests inside a nested worktree). Build-free: the
- * host owns the central build; a node's own test imports the source it changed via
- * the tsx loader. Returns `[]` when there is no git ground truth so the caller can
- * skip the gate rather than fabricate a command.
- */
-/** Pure assembly (git-free) of the verify commands for a set of edited paths —
- *  the testable core of {@link deriveVerifyCommandsFromBranch}. */
-export declare function verifyCommandsForEdits(editedFiles: Iterable<string>): string[];
-export declare function deriveVerifyCommandsFromBranch(root: string, branch: string): string[];
-/**
- * A node's own `targeted_commands` for the per-node verify (task_7d35176d) — the union
- * of the block's `targeted_commands` and its findings' `targeted_commands` (the
- * auditor-specified, fix-specific verification). `acceptNodeWorktree` runs these IN
- * ADDITION to the derived touched-test commands (build-free subset, deduped), so a
- * fix-specific regression check is honoured even when the fix touches no test file.
- */
-export declare function targetedCommandsForBlock(state: RemediationState, blockId: string): string[];
-/**
- * Best-effort: repo-relative test files that reference any of `sourceFiles` (by
- * module basename). Pulling them into a block's access lets the worker that
- * changes or removes a symbol also fix the tests that assert it, instead of
- * leaving orphaned test breakage for a separate central mop-up. Matching is
- * deliberately loose (a false positive only grants slightly broader, harmless
- * write access; a false negative is the failure mode we want to avoid).
- */
-export interface TestFileEntry {
-    rel: string;
-    content: string;
-}
-/**
- * Walk the repo ONCE and read every test file's content (bounded). Built once per
- * dispatch and shared across all blocks so the filesystem walk + reads are not
- * repeated per block.
- */
-export declare function buildTestFileIndex(root: string): TestFileEntry[];
-/**
- * Collect test files from `index` that reference any of `sourceFiles` by
- * module basename. When `packageRoot` is supplied (repo-relative prefix, e.g.
- * `packages/foo`), only test files under that package are considered —
- * otherwise all test files in the index are matched (existing behavior).
- */
-export declare function collectReferencingTests(index: TestFileEntry[], sourceFiles: string[], packageRoot?: string): string[];
-export declare function buildImplementModelHint(block: RemediationBlock, state: RemediationState): DispatchModelHint;
-/**
- * Returns true when any path in `writePaths` is one of the live infra modules.
- * Paths are normalised to forward-slash form (win32 backslash → `/`) and matched
- * by trailing repo-relative segment so absolute/worktree/relative spellings all
- * resolve identically. Used to gate the live-surface verification section in the
- * implement prompt.
- */
-export declare function isInfraModifyingBlock(writePaths: string[]): boolean;
-export declare function prepareImplementDispatch(options: DispatchOptions, runId: string, onlyBlockId?: string, waveOptions?: {
-    hostMaxConcurrent?: number;
-    sessionConfig?: SessionConfig | null;
-    hostContextTokens?: number | null;
-    hostOutputTokens?: number | null;
-    hostModels?: HostModelRosterEntry[] | null;
-    hostModelId?: string | null;
-    /**
-     * Root each node's prompt at its isolated worktree (the deterministic
-     * `worktreePath(root, block_id, runId)`) rather than the main checkout. Set by
-     * the rolling engine (`driveRollingImplementDispatch`) so a worker told its
-     * repository root is the worktree edits there, not the shared main tree.
-     */
-    worktreeRootedPrompts?: boolean;
-    /**
-     * Lease the granted admitted set against the shared reservation ledger. The
-     * host-subagent rolling path leaves this unset (defaults true — it dispatches the
-     * grant across processes and reconciles at accept-node); the in-process rolling
-     * engine passes `false` (it admits + leases per-packet itself, so a host grant
-     * here would double-count). Threaded into `buildDispatchQuota`.
-     */
-    grantLeases?: boolean;
-}): Promise<RemediationDispatchPlan>;
-/** Outcome of resolving the worker's ACTUAL edited files from git. */
-export type GitEditedFiles = {
-    available: true;
-    files: Set<string>;
-}
-/** git is present but a probe failed against a real repo → fail closed. */
- | {
-    available: false;
-    reason: "probe_failed";
-    error: string;
-}
-/** root is not under version control at all → no ground truth, gate is skipped. */
- | {
-    available: false;
-    reason: "not_a_repo";
-    error: string;
-};
-/**
- * Files the worker edited (from git) that fall OUTSIDE the block's declared
- * write scope. Result-file artifacts and the agent-feedback file are excluded
- * (they are sanctioned side outputs, never source edits). Returns the offending
- * repo-relative paths (empty when the edits are fully within scope).
- */
-export declare function writeScopeViolations(declaredWritePaths: string[], editedFiles: Set<string>, root: string): string[];
-/** Branch name a block's isolated worktree is created on (mirrors `worktreePath`). */
-export declare function worktreeBranchForBlock(blockId: string, runId: string): string;
-/**
- * The files a worker's worktree branch changed relative to HEAD — the ground
- * truth for write-scope enforcement. Diffs `HEAD...<branch>` (the branch's own
- * commits). Fail-closed / not-a-repo semantics mirror `gitEditedFiles`.
- */
-export declare function gitEditedFilesForBranch(root: string, branch: string): GitEditedFiles;
-/** A single edited hunk on the NEW side of a branch diff (repo-relative path). */
-export interface GitBranchHunk {
-    /** Repo-relative forward-slash path the hunk belongs to. */
-    file: string;
-    /** 1-based first line of the hunk on the new side. */
-    startLine: number;
-    /** Number of new-side lines the hunk spans (a pure deletion has 0). */
-    lineCount: number;
-}
-/**
- * Outcome of resolving a branch's ACTUAL edited HUNKS from git. Fail-closed like
- * {@link gitEditedFilesForBranch}: on a non-repo, a failed probe, or a diff we
- * cannot parse, `available` is false and callers MUST treat hunk info as absent
- * (conservatively assume same-file blocks overlap — never silently drop a
- * collision).
- */
-export type GitBranchHunks = {
-    available: true;
-    hunks: GitBranchHunk[];
-} | {
-    available: false;
-    reason: "not_a_repo";
-    error: string;
-} | {
-    available: false;
-    reason: "probe_failed";
-    error: string;
-};
-/**
- * Parse `git diff HEAD...<branch>` into per-hunk NEW-side line ranges — the
- * ground truth for whether two same-file edits actually touch disjoint regions.
- * Mirrors {@link gitEditedFilesForBranch}'s fail-closed / not-a-repo semantics:
- * never throws; on a non-repo / failed probe / malformed diff returns a
- * discriminated result marking hunks unavailable so the caller can fail closed.
- *
- * Paths are normalised to repo-relative forward-slash (the same scheme
- * {@link gitEditedFilesForBranch} emits) so hunk files compare like-for-like
- * with the file set.
- */
-export declare function gitHunksForBranch(root: string, branch: string): GitBranchHunks;
-/**
- * Parse a unified-diff body into NEW-side hunk ranges. Extracted for testability
- * (no git spawn). Recognises `+++ b/<path>` file headers and
- * `@@ -a,b +c,d @@` hunk headers; a header we cannot parse fails the whole probe
- * closed (returns `probe_failed`) rather than silently producing partial hunks
- * that would let a real overlap slip through.
- */
-export declare function parseUnifiedDiffHunks(diffText: string): GitBranchHunks;
-/** The decision a write-scope gate makes given the resolved edit set. */
-export interface WriteScopeDecision {
-    blocked: boolean;
-    reason?: string;
-}
-/**
- * Pure write-scope gate decision (OBL-DS-06). Given the block's declared write
- * paths and the resolved git edit set:
- *  - `not_a_repo`   → no ground truth (no worktree workflow) → not blocked.
- *  - `probe_failed` → git is a repo but the diff failed → FAIL CLOSED (blocked).
- *  - available      → block iff any edited file is outside declared scope.
- * The worker's self-reported `amended_files` is never an input here.
- */
-export declare function enforceWriteScope(declaredWritePaths: string[], edited: GitEditedFiles, root: string): WriteScopeDecision;
-/** Each block's declared write scope from a dispatch plan — the seed for the
- *  accept-time write-scope gate's ownership registry (so an amended path owned by
- *  a sibling block is recognised as a seam conflict, not silently granted). */
-export declare function blockScopesFromPlan(plan: RemediationDispatchPlan): Array<{
-    block_id: string;
-    write_paths: string[];
-}>;
-/**
- * A block's declared target paths (write ∪ read) from the persisted dispatch plan
- * — the single source of the scope the worker actually received (same authority
- * the accept-time write-scope gate reads). Used to seed untracked declared targets
- * into a fresh worktree (see {@link seedUntrackedDeclaredPaths}).
- */
-export declare function declaredPathsFromPlan(plan: RemediationDispatchPlan, blockId: string): string[];
-/**
- * Pure write-scope adjudication (OBL-DS-06) — git-free so it is unit-testable with
- * a synthetic edit set. Seeds an ephemeral `OwnershipRegistry` from `allBlockScopes`
- * (normalised to repo-relative so ownership compares like-for-like) and routes the
- * node's ACTUAL out-of-declared edits — the git ground truth, never a self-report:
- *  - an edit to a file no sibling block owns is granted and widens this node's
- *    effective scope (a too-narrow — or empty — declared scope no longer blocks a
- *    correct fix; this is the sanctioned "extend into unowned files" path);
- *  - an edit to a file in another block's declared scope is a seam conflict that
- *    blocks until the seam protocol re-scopes or serialises the nodes.
- * Cross-sibling contention on a file two live nodes both touch (neither declared)
- * is left to the merge-time lost-update detector (`detectOverlappingEdits`), which
- * sees the full set of merged blocks a single accept cannot.
- */
-export declare function adjudicateWriteScope(allBlockScopes: Array<{
-    block_id: string;
-    write_paths: string[];
-}>, blockId: string, edited: GitEditedFiles, root: string): WriteScopeDecision;
-/**
- * Accept-time write-scope gate, run from `acceptNodeWorktree` AFTER the verify and
- * BEFORE the cherry-pick so a violation PREVENTS the merge rather than being
- * reported once the edit already landed in main. Thin git wrapper around
- * {@link adjudicateWriteScope}: resolves the branch's actual edits and adjudicates.
- */
-export declare function enforceAcceptWriteScope(params: {
-    root: string;
-    branch: string;
-    blockId: string;
-    allBlockScopes: Array<{
-        block_id: string;
-        write_paths: string[];
-    }>;
-}): WriteScopeDecision;
-/**
- * Build the map from a known obligation/node alias to the finding id that owns
- * it, for one block. A worker that mislabels its `finding_id` as an obligation
- * id it was assigned (or a CP-BLOCK-prefixed/unprefixed node alias) is remapped
- * to the owning node's finding rather than dropped as an orphan — the tolerant
- * seam (the host is a variable of any strength). The map only ever points at
- * findings that belong to THIS block, so a mislabel can never resolve to an
- * unrelated node.
- */
-export declare function buildBlockAliasMap(block: RemediationBlock, state: RemediationState): Map<string, string>;
-/**
- * Collapse a worker result's `item_results` to one entry per resolved finding
- * id, applying the block alias map first (obligation/node-alias → finding). When
- * several entries collapse onto the same finding, a single `blocked` entry wins
- * over `resolved` (a node is not complete if any reported facet failed), and the
- * union of evidence / first failure_reason is preserved. Entries whose id is
- * neither a known finding nor a known alias are returned in `unresolved` so the
- * caller can record them as orphans.
- */
-export declare function collapseItemResults(itemResults: ImplementWorkerResult["item_results"], aliasMap: Map<string, string>, knownFindingIds: Set<string>): {
-    collapsed: ImplementWorkerResult["item_results"];
-    unresolved: ImplementWorkerResult["item_results"];
-};
-export type NodeDispositionStatus = "verified_complete" | "blocked" | "skipped" | "missing_result";
-export interface NodeDisposition {
-    node_id: string;
-    block_id: string;
-    disposition: NodeDispositionStatus;
-    /** The state status the node's finding(s) ended in. */
-    finding_status: string;
-    /** Reconciliation expectations the node was responsible for honoring (INV-DS-12). */
-    reconciliation_expectations: string[];
-    /** Why the node landed in this disposition (failure_reason / skip reason). */
-    reason?: string;
-}
-/**
- * Build the per-node disposition for a block (INV-DS-15). A SKIP disposition
- * (user-skipped: `ignored` / `deemed_inappropriate`) is NEVER reported as
- * `verified_complete`. Each block maps 1:1 to a node, so the disposition keys on
- * the block's first finding (the node id).
- */
-export declare function buildNodeDisposition(block: RemediationBlock, state: RemediationState): NodeDisposition;
-/**
- * Attribute a post-merge sibling-block failure (INV-DS-14). Given the repo-
- * relative paths implicated by a red sibling and the merged blocks' declared
- * write scopes, return the exactly-one block whose scope contains an implicated
- * file (attributable → route THAT sibling to triage). When zero or more than one
- * merged block could own the failure, the red is unattributable and is deferred
- * to the rolling-scheduler's coarse backstop (return null).
- */
-export declare function attributeSiblingRed(implicatedFiles: string[], mergedBlockScopes: Array<{
-    block_id: string;
-    write_paths: string[];
-}>, root: string): string | null;
-/** A merged block's ACTUAL edited file set (resolved from its worktree branch diff). */
-export interface BlockEditedFiles {
-    block_id: string;
-    /** Repo-relative forward-slash paths the block's worker actually changed. */
-    files: Set<string>;
-    /**
-     * The block's ACTUAL edited hunks (new-side line ranges), when git could
-     * resolve them. When absent / unavailable, {@link detectOverlappingEdits} MUST
-     * fail closed and treat any same-file pairing as a potential collision — a
-     * missing hunk map is never disjointness evidence.
-     */
-    hunks?: GitBranchHunks;
-}
-/** One detected overlap: two merged blocks whose actual edits hit the same file. */
-export interface OverlappingEdit {
-    path: string;
-    block_ids: string[];
-}
-/**
- * Detect lost-update hazards across concurrently-merged blocks (ARC-f378135d-2 /
- * ARC-c1693139). When the rolling engine dispatches multiple nodes in flight and
- * each worker edits in its own worktree, two workers can both modify the SAME
- * file; cherry-picking both branches silently drops one worker's change to that
- * file (lost update). This pure function returns every repo-relative path that
- * appears in more than one merged block's ACTUAL edit set, with the owning block
- * ids. The caller routes the involved blocks to triage so the conflict is
- * reconciled rather than silently losing an edit. Result-file artifacts and the
- * agent-feedback file are sanctioned side outputs and are never counted as
- * overlaps.
- */
-export declare function detectOverlappingEdits(editedByBlock: BlockEditedFiles[]): OverlappingEdit[];
-export declare function mergeImplementResults(options: DispatchOptions, runId: string): Promise<RemediationState>;
-export declare function readExtractedPlanIfPresent(artifactsDir: string): Promise<unknown | undefined>;
-export declare function readDispatchPlan(artifactsDir: string, runId: string, phase: "implement"): Promise<RemediationDispatchPlan>;
+export type { DispatchOptions, GitEditedFiles, GitBranchHunk, GitBranchHunks, } from "./dispatch/common.js";
+export { gitTopLevel, worktreeBranchForBlock, gitEditedFilesForBranch, gitHunksForBranch, parseUnifiedDiffHunks, writeScopeViolations, detectRepoConventionsCache, } from "./dispatch/common.js";
+export type { DagNodeFields } from "./dispatch/dagNodeFields.js";
+export type { HostConcurrencyLimit } from "audit-tools/shared";
+export { resolveHostActiveSubagentLimit, detectHostConcurrencyFromEnv, normalizeSlotTokens, resolveHostConcurrencyLimit, scheduleWave, buildConfirmedPools, buildDispatchQuota, } from "./dispatch/waveScheduling.js";
+export type { ScheduleWaveInput, WaveScheduleResult, } from "./dispatch/waveScheduling.js";
+export type { WorktreeVerifyResult } from "./dispatch/worktreeLifecycle.js";
+export { createWorktree, seedUntrackedDeclaredPaths, removeWorktree, resetNodeWorktreeAndBranch, verifyNodeInWorktree, mergeWorktree, dirtyMainTreeCollisions, rebaseBranchOntoHead, worktreePath, remediationBranchName, baseBranchLockPath, quarantineRef, quarantineFailedNodeCommit, quarantineUncommittedWorktreeEdits, clearQuarantinedCommit, listQuarantinedCommits, remediationBaseBranchPath, readRemediationBaseBranch, ensureRemediationBranchCheckedOut, commitWorktree, ensureWorktreeNodeModules, } from "./dispatch/worktreeLifecycle.js";
+export type { NodeWorkerOutcome, AcceptNodeWorktreeParams, AcceptNodeWorktreeResult, WorktreeNodeWorker, NodeWorktreeExecution, } from "./dispatch/acceptNode.js";
+export { acceptNodeWorktree, nodeAcceptOutcomePath, recordNodeAcceptOutcome, loadNodeAcceptOutcome, executeNodeInWorktree, } from "./dispatch/acceptNode.js";
+export { isBuildFreeVerifyCommand, normalizeNodeTestCommand, isWholeSuiteTestCommand, pathTokensInCommand, selfContainedVerifyCommands, verifyCommandsForEdits, deriveVerifyCommandsFromBranch, targetedCommandsForBlock, } from "./dispatch/verifyCommands.js";
+export type { TestFileEntry } from "./dispatch/implementPrompt.js";
+export { buildImplementModelHint, implementResultPath, isInfraModifyingBlock, buildTestFileIndex, collectReferencingTests, } from "./dispatch/implementPrompt.js";
+export type { WriteScopeDecision, NodeDispositionStatus, NodeDisposition, BlockEditedFiles, OverlappingEdit, } from "./dispatch/writeScope.js";
+export { enforceWriteScope, blockScopesFromPlan, declaredPathsFromPlan, adjudicateWriteScope, enforceAcceptWriteScope, buildBlockAliasMap, collapseItemResults, buildNodeDisposition, attributeSiblingRed, detectOverlappingEdits, } from "./dispatch/writeScope.js";
+export { prepareImplementDispatch, mergeImplementResults, readExtractedPlanIfPresent, readDispatchPlan, } from "./dispatch/marshal.js";
 //# sourceMappingURL=dispatch.d.ts.map