audit-tools 0.32.19 → 0.32.22

package/dist/remediate/steps/dispatch/waveScheduling.js

@@ -0,0 +1,352 @@
+import { computeDispatchAdmission, createReservationLedger, tierRank } from "audit-tools/shared";
+import { deriveCostRank, lookupConfirmedPosition } from "audit-tools/shared";
+import { scheduleWave as computePoolWaveSchedule } from "audit-tools/shared";
+import { buildQuotaSource, HostSessionQuotaSource, compareTier, buildSourcePools, buildHostModelPools, resolveHostProviderName, isDemotableInProcessProvider, } from "audit-tools/shared";
+import { REMEDIATION_DISPATCH_QUOTA_CONTRACT_VERSION, } from "../types.js";
+import { computeDispatchCapacity, resolveHostActiveSubagentLimit, readQuotaState, buildProviderModelKey, computeBackoffCooldownMs, computeBackoffFailureWeight, summarizeDispatchCapacityPools, } from "../../quota/index.js";
+export { resolveHostActiveSubagentLimit };
+export { detectHostActiveSubagentLimit as detectHostConcurrencyFromEnv, } from "../../quota/hostLimits.js";
+const DEFAULT_WAVE_SIZE = 5;
+export function normalizeSlotTokens(tokens, count) {
+    if (!tokens || tokens.length === 0)
+        return new Array(count).fill(0);
+    if (tokens.length > count)
+        return tokens.slice(0, count);
+    if (tokens.length < count)
+        return [...tokens, ...new Array(count - tokens.length).fill(0)];
+    return tokens;
+}
+export function resolveHostConcurrencyLimit(options) {
+    return resolveHostActiveSubagentLimit({
+        explicitLimit: options.hostMaxConcurrent,
+        sessionConfig: options.sessionConfig ?? {},
+        env: options.env,
+    });
+}
+function _capacityPoolSummary(poolId, slots, schedule) {
+    return {
+        pool_id: poolId,
+        slots,
+        model: schedule.model,
+        confidence: schedule.confidence,
+        source: schedule.source,
+        resolved_limits: schedule.resolved_limits,
+        host_concurrency_limit: schedule.host_concurrency_limit,
+        cooldown_until: schedule.cooldown_until,
+        estimated_wave_tokens: schedule.estimated_wave_tokens,
+        binding_cap: schedule.binding_cap ?? "none",
+        quota_source_snapshot: schedule.quota_source_snapshot ?? null,
+    };
+}
+/**
+ * Most-capable rank first, so the largest pending items land on the rank with
+ * the largest window. Ordering comes from the single shared tier-rank authority
+ * (`compareTier`, negated for descending) — no local {small,standard,deep} copy.
+ */
+function sortRosterMostCapableFirst(roster) {
+    return [...roster].sort((a, b) => compareTier(b.rank, a.rank));
+}
+async function buildHostPoolPreamble(input) {
+    const sessionConfig = input.sessionConfig ?? {};
+    const providerName = input.providerName ??
+        sessionConfig.provider ??
+        "claude-code";
+    const hostModel = input.hostModel ??
+        sessionConfig.block_quota
+            ?.host_model ??
+        null;
+    // Quota-key identity: resolved model name, else the host's opaque id, else
+    // null → `provider/*`. Per-roster-rank `model_id` overrides per pool below.
+    const quotaModelKeySegment = hostModel ?? input.hostModelId ?? null;
+    const roster = input.hostModels?.length
+        ? sortRosterMostCapableFirst(input.hostModels)
+        : null;
+    const hostLimit = resolveHostConcurrencyLimit({
+        hostMaxConcurrent: input.hostMaxConcurrent,
+        sessionConfig,
+        env: input.env,
+    });
+    // The capability handshake: the host reported its dispatch model's real
+    // context/output window this session (the roster's most capable entry under
+    // the multi-rank handshake). Carried into the pool's discoveredLimits so the
+    // shared discovered_capability rung sizes the budget to the real window
+    // instead of the conservative 32k floor. RPM/TPM stay null and fill from the
+    // learned quota state.
+    const hostContextTokens = input.hostContextTokens ?? roster?.[0]?.context_tokens ?? null;
+    const hostOutputTokens = input.hostOutputTokens ?? roster?.[0]?.output_tokens ?? null;
+    const hostCapabilityLimits = hostContextTokens != null || hostOutputTokens != null
+        ? { context_tokens: hostContextTokens, output_tokens: hostOutputTokens }
+        : null;
+    let quotaEntries = {};
+    try {
+        const state = await readQuotaState();
+        quotaEntries = state.entries;
+    }
+    catch (err) {
+        process.stderr.write(`[waveScheduler] readQuotaState failed; degrading to no learned quota entry. ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    // The proactive quota snapshot (Claude OAuth source, then learned) so the
+    // scheduler can throttle/cooldown from live remaining quota — mirrors
+    // audit-code's buildDispatchPool. PREPEND the host-session source keyed on
+    // this host pool's own (provider, model) key — first-class PRE-WALL source
+    // (graduated remaining_pct → LOW/CRITICAL throttle before a 429), gating on the
+    // exact key so it never masks the proactive/learned sources.
+    const quotaSource = buildQuotaSource({
+        halfLifeHours: sessionConfig.quota
+            ?.empirical_half_life_hours,
+        hostSession: input.hostSession ??
+            new HostSessionQuotaSource({
+                providerModelKey: buildProviderModelKey(providerName, quotaModelKeySegment),
+            }),
+    });
+    // One capacity pool per reported roster rank (most capable first), each with
+    // its own discovered window and quota key; a single pool for the scalar/absent
+    // handshake. Built via the shared host-pool-from-roster core so the pool shape
+    // + account-keyed pool ids can't drift across the two consumers.
+    const primaryPools = await buildHostModelPools({
+        providerName,
+        hostModel,
+        hostConcurrencyLimit: hostLimit,
+        quotaSource,
+        quotaEntries,
+        roster,
+        resolve: (entry) => ({
+            poolKey: buildProviderModelKey(providerName, entry?.model_id ?? quotaModelKeySegment),
+            discoveredLimits: entry
+                ? { context_tokens: entry.context_tokens, output_tokens: entry.output_tokens }
+                : hostCapabilityLimits,
+        }),
+    });
+    return {
+        sessionConfig,
+        providerName,
+        hostModel,
+        quotaModelKeySegment,
+        roster,
+        hostLimit,
+        hostContextTokens,
+        hostOutputTokens,
+        hostCapabilityLimits,
+        quotaEntries,
+        quotaSource,
+        primaryPools,
+    };
+}
+export async function scheduleWave(input) {
+    const sessionConfig = input.sessionConfig ?? {};
+    const providerName = input.providerName ?? sessionConfig.provider ?? "claude-code";
+    const hostModel = input.hostModel ?? sessionConfig.block_quota?.host_model ?? null;
+    // Quota-key identity: resolved model name, else the host's opaque id, else
+    // null → `provider/*`. Per-roster-rank `model_id` overrides per pool below.
+    const quotaModelKeySegment = hostModel ?? input.hostModelId ?? null;
+    const roster = input.hostModels?.length
+        ? sortRosterMostCapableFirst(input.hostModels)
+        : null;
+    const hostLimit = resolveHostConcurrencyLimit({
+        hostMaxConcurrent: input.hostMaxConcurrent,
+        sessionConfig,
+        env: input.env,
+    });
+    // The capability handshake: the host reported its dispatch model's real
+    // context/output window this session (the roster's most capable entry under
+    // the multi-rank handshake). Carried into the pool's discoveredLimits so the
+    // shared discovered_capability rung sizes the budget to the real window
+    // instead of the conservative 32k floor. RPM/TPM stay null and fill from the
+    // learned quota state.
+    const hostContextTokens = input.hostContextTokens ?? roster?.[0]?.context_tokens ?? null;
+    const hostOutputTokens = input.hostOutputTokens ?? roster?.[0]?.output_tokens ?? null;
+    const quota = sessionConfig.quota;
+    if (!quota || quota.enabled === false) {
+        const cap = hostLimit?.active_subagents ?? DEFAULT_WAVE_SIZE;
+        const waveSize = Math.max(1, Math.min(cap, input.itemCount));
+        // Single-source the quota-off schedule math (wave-token formula + confidence +
+        // source) through the shared scheduler so the two orchestrators can't drift —
+        // remediate previously re-implemented it with a flat average + confidence:"low",
+        // disagreeing with shared's sumTopN + "high". The wave is already capped to
+        // `waveSize`, so shared (`requestedConcurrency: waveSize`, no quota) returns it
+        // verbatim. Only the roster-honoring window and the DEFAULT_WAVE_SIZE-aware
+        // binding_cap are remediate-specific and layered back on top.
+        const base = computePoolWaveSchedule({
+            providerName,
+            sessionConfig,
+            hostModel,
+            requestedConcurrency: waveSize,
+            estimatedSlotTokens: input.estimatedSlotTokens,
+            hostConcurrencyLimit: hostLimit,
+        });
+        const schedule = {
+            ...base,
+            resolved_limits: {
+                // Honor a host-reported window even with quota disabled; fall back to the
+                // shared scheduler's default only when nothing was discovered.
+                context_tokens: hostContextTokens ?? base.resolved_limits.context_tokens,
+                output_tokens: hostOutputTokens ?? base.resolved_limits.output_tokens,
+                requests_per_minute: null,
+                input_tokens_per_minute: null,
+                output_tokens_per_minute: null,
+            },
+            host_concurrency_limit: hostLimit,
+            // hostLimit-gated: a DEFAULT_WAVE_SIZE cap below itemCount is NOT a host
+            // concurrency bind (there is no host limit), so it stays "none".
+            binding_cap: hostLimit && waveSize < input.itemCount ? "host_concurrency" : "none",
+        };
+        return {
+            ...schedule,
+            capacity_pools: [_capacityPoolSummary(buildProviderModelKey(providerName, quotaModelKeySegment), waveSize, schedule)],
+        };
+    }
+    const preamble = await buildHostPoolPreamble({
+        sessionConfig: input.sessionConfig,
+        providerName: input.providerName,
+        hostModel: input.hostModel,
+        hostMaxConcurrent: input.hostMaxConcurrent,
+        hostContextTokens: input.hostContextTokens,
+        hostOutputTokens: input.hostOutputTokens,
+        hostModels: input.hostModels,
+        hostModelId: input.hostModelId,
+        env: input.env,
+    });
+    const capacity = computeDispatchCapacity({
+        pools: preamble.primaryPools,
+        sessionConfig,
+        pendingItemTokens: normalizeSlotTokens(input.estimatedSlotTokens, input.itemCount),
+    });
+    return {
+        ...capacity.primary.schedule,
+        capacity_pools: summarizeDispatchCapacityPools(capacity),
+    };
+}
+/**
+ * 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 async function buildConfirmedPools(input) {
+    // Defect-1: the ACTUAL configured backend (used to build the demoted source pool) vs
+    // the HOST-pool identity. When an attended host demotes a headless backend to a source
+    // (codex/opencode/openai-compatible), the host pool must key to the CONVERSATION HOST
+    // (claude-code), not the backend — otherwise the host fan-out is charged against the
+    // backend's meter AND collides with the demoted source pool ([[capability-is-per-auditor-not-per-audit]]).
+    const actualProviderName = resolveHostProviderName(input.sessionConfig);
+    const demoteHostIdentity = input.demotePrimaryInProcess === true && isDemotableInProcessProvider(actualProviderName);
+    const hostProviderName = demoteHostIdentity
+        ? "claude-code"
+        : actualProviderName;
+    // Resolve identity/limits and build the per-rank host-model pools via the
+    // SAME preamble `scheduleWave` uses — the two no longer keep parallel copies.
+    const { sessionConfig, quotaSource, quotaEntries, primaryPools } = await buildHostPoolPreamble({
+        sessionConfig: input.sessionConfig,
+        providerName: hostProviderName,
+        hostMaxConcurrent: input.hostMaxConcurrent,
+        hostContextTokens: input.hostContextTokens,
+        hostOutputTokens: input.hostOutputTokens,
+        hostModels: input.hostModels,
+        hostModelId: input.hostModelId,
+        env: input.env,
+        hostSession: input.hostSession,
+    });
+    // Every configured dispatchable backend source (any non-IDE source: NIM/vLLM API,
+    // a CLI pool, …) becomes a CapacityPool alongside the primary, so the scheduler's
+    // proactive cross-pool spill (INV-QD-14) and the A-8 coordinator can route work to
+    // them. Single-sourced in shared (`buildSourcePools`) so audit and remediate surface
+    // the IDENTICAL pool shapes — the spill topology can't drift. `primaryProviderName`
+    // is the ACTUAL configured backend (not the demoted host identity) so the demoted
+    // source is built for the real provider.
+    const sourcePools = await buildSourcePools({
+        sessionConfig,
+        primaryProviderName: actualProviderName,
+        quotaSource,
+        quotaEntries,
+        demotePrimaryInProcess: input.demotePrimaryInProcess,
+    });
+    primaryPools.push(...sourcePools);
+    return primaryPools;
+}
+/**
+ * Build the `AdmissionPool[]` the admission loop admits against from a schedule's
+ * per-pool capacity summaries — the remediate analog of audit's `finalizeDispatchQuota`
+ * pool mapping (both feed the single-sourced `computeDispatchAdmission`, so the two
+ * orchestrators can't drift). Budget = the pool's live remaining token budget
+ * (null ⇒ optimistic +Inf); declared cap = its host in-flight cap passed VERBATIM
+ * (null ⇒ none — the only place an explicit agent-count exists); cost/capability rank
+ * from its tier; capacity = its context window (a packet's input+output envelope must fit).
+ */
+function admissionPoolsFromSchedule(schedule, confirmedCostPositions) {
+    return (schedule.capacity_pools ?? []).map((pool) => {
+        // costRank is a REAL cost axis (blended $/Mtok via the shared cost-first
+        // engine), decoupled from capabilityRank (still the tier ordinal). See
+        // spec/cost-first-routing.md. Rung 1 (operator-confirmed) via the model-keyed
+        // map; absent ⇒ price (rung 2) ⇒ tier (rung 3).
+        return {
+            poolId: pool.pool_id,
+            resourceKey: pool.pool_id,
+            budget: pool.remaining_token_budget ?? Number.POSITIVE_INFINITY,
+            declaredCap: pool.host_concurrency_limit?.active_subagents ?? null,
+            costRank: deriveCostRank({
+                model: pool.model,
+                tier: pool.rank,
+                confirmedPosition: lookupConfirmedPosition(confirmedCostPositions, pool.model),
+            }),
+            capabilityRank: tierRank(pool.rank),
+            capacityTokens: pool.resolved_limits.context_tokens,
+        };
+    });
+}
+export async function buildDispatchQuota(runId, phase, schedule, admissionPackets, 
+/**
+ * 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, quotaStateEntry, 
+/**
+ * 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) {
+    let backoffState = null;
+    const count = quotaStateEntry?.consecutive_429_count ?? 0;
+    if (count > 0) {
+        backoffState = {
+            consecutive_429_count: count,
+            current_cooldown_ms: computeBackoffCooldownMs(count),
+            current_failure_weight: computeBackoffFailureWeight(count),
+        };
+    }
+    // Admission control: instead of a computed `max_concurrent_agents`, GRANT the
+    // affordable admitted set (cost-first-capable, ledger-leased). Per-packet reservation
+    // = input estimate + output envelope (declared output cap; the learned ratio refines
+    // it once a provider reports usage — dormant on the always-on claude-code host).
+    const admission = await computeDispatchAdmission({
+        packets: admissionPackets,
+        pools: admissionPoolsFromSchedule(schedule, confirmedCostPositions),
+        outputCap: schedule.resolved_limits.output_tokens,
+        grantLeases,
+        ledger: createReservationLedger(),
+    });
+    return {
+        contract_version: REMEDIATION_DISPATCH_QUOTA_CONTRACT_VERSION,
+        run_id: runId,
+        phase,
+        host_concurrency_limit: schedule.host_concurrency_limit,
+        admission,
+        estimated_wave_tokens: schedule.estimated_wave_tokens,
+        model: schedule.model,
+        confidence: schedule.confidence,
+        source: schedule.source,
+        resolved_limits: schedule.resolved_limits,
+        cooldown_until: schedule.cooldown_until,
+        binding_cap: schedule.binding_cap ?? "none",
+        capacity_pools: schedule.capacity_pools,
+        quota_source_snapshot: schedule.quota_source_snapshot ?? null,
+        backoff_state: backoffState,
+    };
+}
+//# sourceMappingURL=waveScheduling.js.map

package/dist/remediate/steps/dispatch/waveScheduling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waveScheduling.js","sourceRoot":"","sources":["../../../../src/remediate/steps/dispatch/waveScheduling.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,189 @@
+export interface WorktreeVerifyResult {
+    passed: boolean;
+    output: string;
+}
+/**
+ * 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;
+//# sourceMappingURL=worktreeLifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktreeLifecycle.d.ts","sourceRoot":"","sources":["../../../../src/remediate/steps/dispatch/worktreeLifecycle.ts"],"names":[],"mappings":"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"}