@quantiya/codevibe-claude-plugin 1.0.52 → 2.0.2

package/node_modules/@quantiya/codevibe-core/dist/local-executor/local-executor-impl.d.ts

@@ -0,0 +1,724 @@
+import type { SubstrateHandle } from '../substrate/types';
+import { AuthorityScope } from './authority';
+import { ClassAEmitter, ClassAEmitterContext, ClassASink, VerificationGateKind } from './class-a-emit';
+import { type DeviceSigningKey } from './class-a-sign';
+import { EmitShellEventFn } from './hook-bridge';
+import { MergeResult, SubmitMergeGateVerdictInput } from './task-group-types';
+import { TrackRegistry } from './track-registry';
+import { AgentKind, AuthorityAction, ClassBInbound, GateDispatchPayload, HookEvent, ImplementorHandle, LocalExecutor, MergeGateDispatchPayload, ProbeHandle, ProcessRole, ReviewerDispatchPayload, ReviseFeedbackPayload, ReviewerHandle, SpawnArgs, TrackAssignedPayload } from './types';
+import { type TeamExecution } from './team-execution-flag';
+import type { RenderedConflict, TrackIntentDiff } from './wb2-review-bundle';
+import type { ConflictModelCaller } from './class2-resolver';
+import type { ConflictResolverContext } from './merge-conflict-resolve';
+import { type ContentCipher } from './conflict-resolution-durable-store';
+import type { TrackTipsView } from './durable-store';
+/**
+ * CP-7 W2 Stage-2 HIGH (Finding 2) — STRICT delivery sink for the
+ * `tier:'none'` (moat-OFF) reduced-trust badge.
+ *
+ * The ordinary `emitShellEvent` chokepoint RESOLVES WITHOUT EMITTING when the
+ * cohort flag is off, the session is a `cp1a-local-*` stub, or no session key
+ * exists (see `emit-shell-event.ts`); the team store tap likewise ignores the
+ * `cp7_reduced_trust` notification. A `tier:'none'` badge routed through it can
+ * therefore "succeed" (await resolves) while the user sees NOTHING — and the
+ * legacy unsandboxed spawn would proceed on only a WARN.
+ *
+ * A `StrictBadgeSink` MUST instead CONFIRM that the user-facing NOTIFICATION was
+ * ACTUALLY delivered (e.g. `createEvent` was invoked) and THROW when it cannot
+ * deliver (cohort off / no session / stub / tap-ignored). For `tier:'none'` a
+ * throw → FAIL CLOSED (no legacy spawn). It is INTENTIONALLY separate from the
+ * audit emit: audit emission stays on the existing Class-A / shell-event path;
+ * this sink is ONLY the user-facing moat-OFF warning.
+ *
+ * Resolves on a confirmed delivery; REJECTS on a silent no-op / undeliverable.
+ */
+export type StrictBadgeSink = (badge: {
+    sessionId: string;
+    content: string;
+    metadata: Record<string, unknown>;
+}) => Promise<void>;
+/**
+ * CP-12 W2.b — the narrow AppSync surface the MergeGate runner consumes (W2.a
+ * `submitMergeGateVerdict`). Declared structurally (NOT importing the concrete
+ * `AppSyncClient`) so the LE module stays decoupled and the test surface can
+ * inject a mock without constructing the full GraphQL client.
+ */
+export interface MergeGateAppSyncClient {
+    submitMergeGateVerdict(input: SubmitMergeGateVerdictInput): Promise<{
+        outcome: string;
+    }>;
+}
+/**
+ * CP-12 W2.b — the narrow crypto surface for E2E-encrypting the
+ * `submitMergeGateVerdict.detail` payload under the ONE team session key (§0.2 /
+ * §6). Matches `cryptoService.encryptContent(content, sessionKeyBase64)` (the
+ * SAME path the LE already uses for gate content), but injected structurally so
+ * the runner has no hard dependency on the singleton.
+ */
+export interface MergeGateContentEncryptor {
+    encryptContent(content: string, sessionKeyBase64: string): string;
+}
+/**
+ * CP-7 PART F — the narrow result the LE consumes from `engageSubstrate`. Two
+ * variants: `substrate` (the moat is ON — the LE passes `substrateHandle` into
+ * `spawnImplementor` and calls `teardown()` on process exit) and
+ * `reduced_trust` (the moat is OFF — the LE takes the legacy `nodeSpawn` path +
+ * surfaces the prominent badge). Declared structurally (NOT importing the
+ * concrete `SubstrateLaunch.engageSubstrate`) so the LE module stays decoupled
+ * and tests inject a stub. Matches `SubstrateLaunch.EngageResult`.
+ */
+export type SubstrateEngageResult = {
+    mode: 'substrate';
+    tier: 'docker' | 'sandbox_exec';
+    reducedTrust: boolean;
+    reducedTrustReason?: string;
+    substrateHandle: SubstrateHandle;
+    refreshBrokerToken(): Promise<void>;
+    teardown(): Promise<void>;
+} | {
+    mode: 'reduced_trust';
+    reducedTrust: true;
+    reducedTrustReason: string;
+    teardown(): Promise<void>;
+};
+/**
+ * CP-7 PART F — the injected substrate engager. The orchestration shell wires
+ * this to `SubstrateLaunch.engageSubstrate` for orchestration-mode implementor
+ * sessions. ABSENT (the default) → the LE never engages the substrate (companion
+ * mode / tests / reviewer-probe-only sessions): the legacy path is byte-identical
+ * (§7 non-regression). GEMINI is reduced-trust (§6 Q4) — the engager handles it
+ * (returns `reduced_trust`); the LE never calls it for reviewer/probe roles.
+ */
+export type SubstrateEngager = (input: {
+    taskId: string;
+    agentKind: AgentKind;
+    workdir: string;
+    role: ProcessRole;
+}) => Promise<SubstrateEngageResult>;
+export interface LocalExecutorImplDeps {
+    sessionId: string;
+    initialScope?: AuthorityScope;
+    baseCtx: Omit<ClassAEmitterContext, 'taskId'>;
+    adapter: AgentKind;
+    sink?: ClassASink;
+    emitShellEvent: EmitShellEventFn;
+    logger?: {
+        warn: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    /**
+     * Spawns the per-track implementor process. Factored as a dep so tests can
+     * substitute a stub. Defaults to the module `spawnImplementor` bound to the
+     * track's authority scope. Returns the implementor handle.
+     */
+    spawnTrackImplementor?: (scope: AuthorityScope, args: SpawnArgs) => Promise<ImplementorHandle>;
+    /**
+     * Builds the `SpawnArgs.argv` for a track's implementor given the track
+     * payload + canonicalized state dir. The shell knows which agent binary
+     * (claude/gemini/codex) to invoke and the prompt wiring; the LE only
+     * orchestrates spawn + idempotency + state-dir isolation. When omitted, the
+     * MergeGate happy-path + idempotency tests still exercise the registry via a
+     * `spawnTrackImplementor` stub.
+     */
+    buildTrackArgv?: (payload: TrackAssignedPayload, stateDir: string) => string[];
+    /** AppSync surface for `submitMergeGateVerdict` (W2.a). Required for MergeGate. */
+    appsyncClient?: MergeGateAppSyncClient;
+    /** LE device P-256 key material — signs the MergeGate classification (#C12-8). */
+    deviceSigningKey?: DeviceSigningKey;
+    /** LE's registered Class A device id — bound into the classification signature. */
+    leDeviceId?: string;
+    /** ONE team session key (base64) — encrypts the MergeGate `detail` (§6 / 2f.4). */
+    teamSessionKeyB64?: string;
+    /** E2E content encryptor. Defaults to `cryptoService` if injected by the shell. */
+    contentEncryptor?: MergeGateContentEncryptor;
+    /**
+     * Repo root (canonicalized absolute) — the parent under which per-track state
+     * dirs `<repoRoot>/.codevibe/state/<group>/<track>/` live, and the cwd the
+     * MergeGate integration check runs in. Required for team sessions.
+     */
+    repoRoot?: string;
+    /**
+     * CP-12 W2.b (§3.C.1 / §3.C.3 / M5) — the brief→task_id bridge callback. On
+     * `TrackAssigned`, `launchTrack` calls this with the track's child `task_id`,
+     * `trackIndex`, `implementor_agent`, and declared write scope; the shell wires
+     * it to look up the parse-time `briefsByTrackIndex.get(track_index)` and
+     * register `{ brief, agent, trackIndex, write scope }` in the QuorumLoop's
+     * `activeBriefByTask` (which also drains any buffered team `GATE_DISPATCH` for
+     * the task). The per-track implementor run then happens in the QuorumLoop on
+     * the track's `GATE_DISPATCH` (NOT a bare spawn here). ABSENT (non-team LE /
+     * tests) → the track is registered in the registry but no brief bridge runs.
+     */
+    registerTeamTask?: (info: {
+        taskId: string;
+        taskGroupId: string;
+        trackIndex: number;
+        agent: AgentKind;
+        writePaths: string[];
+        autoModifiedFiles: string[];
+        /** #590 — the track's own-module test files; part of the declared write
+         *  scope (engine disjointness-validated) so a test write stays in-lane. */
+        testSurfaces: string[];
+    }) => Promise<void>;
+    /**
+     * CP-12 W4 (#593, Stage-2 r1 Codex MED) — corrupt-brief TOMBSTONE predicate
+     * (wired to `QuorumLoop.isTrackTombstoned`). `launchTrack` consults it at the
+     * VERY TOP — before any registry mutation / state-dir canonicalization / spawn
+     * / lease-renewing progress emit — so a track whose durable brief failed to
+     * decrypt is refused on the LIVE path as early as on the recovery path (never
+     * an empty-brief implementor; the engine sweeper times the un-launched track
+     * out, bounded). ABSENT (non-team LE / tests) → no tombstone gating.
+     *
+     * Keyed by `(taskGroupId, trackIndex)` (#593 Stage-2 r2) — B.2 recovery
+     * aggregates across groups, so a tombstone must be scoped to its group.
+     */
+    isTrackTombstoned?: (taskGroupId: string, trackIndex: number) => boolean;
+    /**
+     * #592 PROVENANCE GUARD (live path, wired to `QuorumLoop.isForeignTeamGroup`).
+     * `launchTrack` consults it right after the tombstone gate — BEFORE any registry
+     * mutation / state-dir canonicalization / spawn — and refuses a `TrackAssigned`
+     * for a team group this desktop did NOT originate. Class B team packets broadcast
+     * PER-USER, and TWO clients that share one `sessionId` (shared device-home →
+     * adopted ACTIVE session) each receive the other's `TrackAssigned`; without this
+     * the foreign track would pin ITS base on THIS workspace and submit an empty
+     * round-0 → born-halt the real originator's gate (dogfood 2026-06-26, proven).
+     * Returns true ONLY when this desktop owns ≥1 group AND the arg is not among them
+     * (empty owned-set / fresh process / post-crash → false, so own-group recovery is
+     * unaffected). ABSENT (non-team LE / tests) → no provenance gating.
+     */
+    isForeignTeamGroup?: (taskGroupId: string) => boolean;
+    /**
+     * The substrate engager (wired by the orchestration shell to
+     * `SubstrateLaunch.engageSubstrate`). When present, the LE engages the moat
+     * for orchestration-mode IMPLEMENTOR spawns: it runs the agent inside the
+     * wiped-env, default-deny-egress sandbox with a per-session broker holding the
+     * vendor key (the agent is creditless). ABSENT (default) → the legacy spawn
+     * path is byte-identical (§7 non-regression: companion mode / reviewer-probe /
+     * tests are unaffected). The engager itself handles the §6 Q2 fallback ladder
+     * + the GEMINI reduced-trust case.
+     */
+    substrateEngager?: SubstrateEngager;
+    /**
+     * CP-7 W2 Stage-2 HIGH (Finding 2) — STRICT delivery sink for the
+     * `tier:'none'` (moat-OFF) reduced-trust badge. When supplied (production
+     * wiring in cli.ts), the moat-OFF badge is delivered through THIS sink — which
+     * confirms the NOTIFICATION actually reached `createEvent` and THROWS on a
+     * silent no-op (cohort off / no session key / stub / tap-ignored) — instead of
+     * the cohort-gated `emitShellEvent` that can resolve without emitting. A throw
+     * here makes the `tier:'none'` path FAIL CLOSED (no unsandboxed spawn).
+     *
+     * ABSENT (default) → the legacy behavior: the badge goes through
+     * `emitShellEvent` and a reject still fails closed, but a SILENT no-op would
+     * NOT (the gap this fix closes). Production MUST wire this; tests that want the
+     * pre-fix behavior may omit it.
+     */
+    strictBadgeSink?: StrictBadgeSink;
+    /** §3.C.18 — real Ed25519 signature verifier (resolves+caches the engine key). */
+    classBSignatureVerifier?: (packet: ClassBInbound) => Promise<boolean>;
+    /**
+     * §3.C.20 (Wave 3 FIX) — drive the round-0 implementor spawn off GATE_DISPATCH.
+     * CP-12 W2.b (§3.C.2 / H1) — `envelopeTaskId` carries the OUTER Class-B
+     * envelope's `task_id` so the team loop routes the round-0 dispatch to the
+     * right per-track `task_id` (the payload has none). The engine stamps this on
+     * EVERY dispatch — for single-impl it equals the loop's active task, and the
+     * loop's `envelopeTaskId !== activeTaskId` discriminator keeps it single-impl
+     * (falls back to the single active task). Wired straight through to the
+     * consumer's `gateDispatch`.
+     */
+    gateDispatch?: (payload: GateDispatchPayload, envelopeTaskId?: string) => Promise<void>;
+    /** §3.C.21 — spawn all assigned reviewer seats for a REVIEWER_DISPATCH packet. */
+    spawnReviewers?: (payload: ReviewerDispatchPayload) => Promise<void>;
+    /** §3.C.23 — re-run the implementor for round N+1 on a REVISE_FEEDBACK packet. */
+    runReviseRound?: (payload: ReviseFeedbackPayload) => Promise<void>;
+    /**
+     * CP-1.f execute-first (D5 / #PR-1 / #PR-3) — promote the task's SHADOW onto
+     * the real tree on the `TaskAuthorized` Class-B edge. Wired straight through
+     * to the consumer's `promoteOnTaskAuthorized`. ABSENT → no promote (back-compat).
+     */
+    promoteOnTaskAuthorized?: (taskId: string) => Promise<void>;
+    /**
+     * CP-12 W2.b (§3.C.2b (d) / H3-4) — promote-quiescence BARRIER for a task.
+     * Backed by the `QuorumLoop`'s public `awaitTaskShadowQuiescent` (an empty
+     * critical section on the per-task shadow-ops mutex). `runMergeGate` awaits
+     * this for EVERY member `task_id` (via `trackRegistry.forGroup`) immediately
+     * before the integration check, so a `MergeGateDispatch` that races an
+     * in-flight `promoteShadow` never reads a tree missing a track's promote.
+     * Wired from the shell EXACTLY like `promoteOnTaskAuthorized`. ABSENT (non-team
+     * LE / tests) → the barrier is skipped (back-compat; single-impl has no
+     * MergeGate so it never calls this).
+     */
+    awaitTaskShadowQuiescent?: (taskId: string) => Promise<void>;
+    /**
+     * TEST SEAM — override the bounded await for member track tips in the
+     * `worktree_merge` gate (default {@link TRACK_TIP_AWAIT_MS}). The engine
+     * dispatches `MergeGateDispatch` as soon as the LAST track flips Passed, but
+     * the desktop commits each track's tip asynchronously on its OWN
+     * `TaskAuthorized` receipt — so the dispatch can arrive BEFORE the final
+     * track's commit has even STARTED (the shadow-ops mutex is not yet held, so
+     * the quiescence barrier passes straight through). Dogfood-pinned 2026-07-02:
+     * team-joint-conflict read a missing tip 0.1s before the commit landed →
+     * FAIL verdict stored → the real train's later PASS hit the #C12-1 replay →
+     * "Team halted — merge_integration_failure" AFTER a successful promote.
+     */
+    trackTipAwaitMs?: number;
+    /**
+     * CP-14 — the team execution model. Since the §10 retirement (2026-07-03)
+     * `worktree_merge` is the ONLY model: the merge gate always runs
+     * {@link runWorktreeMergeGate} (merge-train the committed track branches +
+     * promote the integration tip). Retained as a dep for wire/test stability.
+     */
+    teamExecution?: TeamExecution;
+    /**
+     * CP-14 Wave A — read the durable committed track tips (the merge-train inputs)
+     * for a group. Backed by `RevertManifestStore.readTrackTips`. REQUIRED when
+     * `teamExecution === 'worktree_merge'` (the gate fails closed without it).
+     */
+    readTrackTips?: (taskGroupId: string) => Promise<TrackTipsView>;
+    /**
+     * TEST SEAM (§10 retirement, 2026-07-03) — override the worktree merge gate
+     * body. Defaults to the real {@link runWorktreeMergeBranch} (merge-train +
+     * promote). Mirrors the `runVerificationGatesFn` precedent: unit tests of the
+     * classification/signing/submission flow AROUND the gate inject a fixed
+     * result instead of standing up a real git fixture with track branches (the
+     * merge-train itself has its own fixture-backed suites).
+     */
+    worktreeMergeGateFn?: (payload: MergeGateDispatchPayload, repoRootCanonical: string, gateKinds: VerificationGateKind[]) => Promise<MergeResult>;
+    /**
+     * Audited-path fix (Fix 1) — surface a hosted-side PolicyRejection to the
+     * DESKTOP. The LE already emits a mobile-bound NOTIFICATION via
+     * `notifyPolicyRejection`, but `handleSubscribedEvent` drops every non-gate
+     * shell event, so the desktop user saw NOTHING when a task was policy-rejected.
+     * When wired (cli.ts), this is called with the CLASSIFIED rejection fields (no
+     * raw plaintext) so the shell can (a) dispatch a `SHELL_ADVISORY` into the
+     * store and (b) discard the policy-rejected task's shadow (a policy-rejected
+     * task never authorizes, so its shadow must go the same way a signalled
+     * terminal does). ABSENT → desktop-surface is skipped (the mobile NOTIFICATION
+     * still fires). Best-effort: a throw here is swallowed (never breaks Class B
+     * consumption per LOCK #E3-1).
+     */
+    onPolicyRejection?: (info: {
+        detail: string;
+        category: string;
+        recommendedRecovery: string;
+        /**
+         * Audited-path fix (Fix B) — the rejected task's OWN taskId (from the Class
+         * B envelope; the PolicyRejection payload carries none). The cli.ts wiring
+         * discards EXACTLY this task's shadow instead of `quorumLoop.activeTask`,
+         * so a DELAYED rejection for an OLD task can never discard the CURRENT
+         * task's shadow. Undefined when the envelope lacked a taskId → no discard.
+         */
+        rejectedTaskId?: string;
+    }) => void;
+    /**
+     * CP-14 Wave B (§2.1) — build the CONFINED class-2 model caller for a merge
+     * gate, or `null` when no confinement holds (path C — a bare host with
+     * sandboxing off + not a trusted container). Wired (cli.ts) to the QuorumLoop,
+     * which owns the substrate-engage / trusted-container / spawn machinery. `null`
+     * → the worktree_merge gate runs WITHOUT a resolver (byte-identical
+     * halt-on-conflict — no unconfined LLM resolver ever runs). The caller carries
+     * the `ownerTaskId` audit scope; `teardown()` is called after the gate.
+     */
+    makeConflictModelCaller?: (args: {
+        ownerTaskId: string;
+    }) => Promise<{
+        caller: ConflictModelCaller;
+        teardown: () => Promise<void>;
+    } | null>;
+    /**
+     * CP-14 WB2 (§2.1/§2.2/§2.3) — build the AGENTIC class-2 resolver for a merge
+     * gate, or `null` on path C (no confinement). When wired (cli.ts → QuorumLoop)
+     * AND `isAgenticResolverEnabled()` AND confinement holds, a class-2 slot's
+     * conflicts are resolved by re-dispatching the INCOMING track's implementor
+     * (read+write) in a disposable repo, fd-safe selective-import. `null` → the
+     * `resolveAgentic` closure stays unset → the legacy bounded-prompt `caller`
+     * path / halt (byte-identical). The agentic resolver NEVER spawns unconfined
+     * (fail-closed at construction AND per-resolve dispatch). `teardown()` is called
+     * after the gate alongside the model-caller teardown.
+     */
+    makeAgenticResolver?: (args: {
+        ownerTaskId: string;
+    }) => Promise<{
+        resolveAgentic: NonNullable<ConflictResolverContext['resolveAgentic']>;
+        teardown: () => Promise<void>;
+    } | null>;
+    /**
+     * CP-14 Wave B (§2.3, LOCK #C14-FINAL-TIER2 / #C14-MOAT) — dispatch the
+     * mandatory final-tip Tier-2 reviewer over the integration diff (base → tip),
+     * CONFINED via the same §2.1 tri-state (it returns `confined: false` on path C
+     * so the gate fails closed). Wired (cli.ts) to the QuorumLoop's reviewer
+     * registry + substrate engage. ABSENT → the gate fails closed when the Tier-2
+     * trigger fires (an LLM byte never promotes without a scoped, confined Tier-2).
+     */
+    dispatchFinalTier2Review?: (args: {
+        ownerTaskId: string;
+        repoDir: string;
+        baseSha: string;
+        integrationTip: string;
+        /** CP-14 WB2 §2.4 — the agentic resolver set, for independent Tier-2 selection. */
+        resolverAgents?: ReadonlySet<string>;
+        /** CP-14 WB2 §2.6 (additive) — the rendered intent bundle folded into the prompt. */
+        conflictBundle?: readonly RenderedConflict[];
+        trackIntentDiffs?: readonly TrackIntentDiff[];
+    }) => Promise<{
+        verdict: 'pass' | 'reject';
+        confined: boolean;
+        reason?: string;
+    }>;
+    /**
+     * CP-14 Wave B (§2.4) — symmetric cipher for the durable ConflictResolution
+     * store's at-rest content encryption (the team session key, via cli.ts's
+     * cryptoService). ABSENT → the durable store persists content plaintext (the
+     * structural metadata + the moat are unaffected; encryption is defense-in-depth
+     * on the desktop-local store). The conflict_id/hashes/class stay plaintext.
+     */
+    conflictContentCipher?: ContentCipher;
+}
+export declare function makeEmptyScope(): AuthorityScope;
+export declare class LocalExecutorImpl implements LocalExecutor {
+    private scope;
+    private taskId;
+    private readonly emitter;
+    private readonly bridge;
+    private readonly classBConsumer;
+    private readonly emitShellEvent;
+    private readonly baseCtx;
+    private readonly adapter;
+    private readonly sessionId;
+    private readonly trackRegistry;
+    private readonly trackPayloads;
+    private readonly resolvedMergeOutcomes;
+    /**
+     * CP-14 concurrent-dispatch dedup — the ONE in-flight merge-gate run per
+     * `${merge_gate_id}:${dispatch_generation}` (see {@link runMergeGate}). Entries
+     * are removed when the run settles, so a post-completion re-drain still takes
+     * the #TC-7 replay path (re-submit → server replays the stored outcome).
+     */
+    private readonly inFlightMergeGates;
+    private _lastMergeGateEmitMs;
+    private readonly teamDeps;
+    private readonly logger;
+    private readonly teamModeEnabled;
+    private readonly substrateEngager?;
+    private readonly strictBadgeSink?;
+    constructor(deps: LocalExecutorImplDeps);
+    /**
+     * Single-entrypoint authority gate per master §9:1284. Dispatches to the
+     * underlying `authority.ts` primitive based on `action.kind`. Throws
+     * `AuthorityError` on refusal — caller (orchestration shell or hook bridge)
+     * is responsible for routing to `bridgeAuthorityErrorToShellRefusal` /
+     * `HookBridge.bridgeAuthorityRefusal` per LOCK #C4-3.
+     */
+    enforceAuthority(action: AuthorityAction): Promise<void>;
+    /**
+     * Read-only view of the current authority scope per master §9:1286.
+     * Returns a deep-frozen copy so callers cannot mutate the LE's state.
+     */
+    authorityScope(): Readonly<AuthorityScope>;
+    enforceCommand(argv: string[]): void;
+    enforceNetwork(): void;
+    enforceWrite(p: string): Promise<string>;
+    enforceRead(p: string): Promise<string>;
+    safeWriteFile(p: string, data: Buffer | string): Promise<void>;
+    safeReadFile(p: string, opts?: {
+        encoding?: BufferEncoding;
+    }): Promise<string | Buffer>;
+    spawnImplementor(args: SpawnArgs): Promise<ImplementorHandle>;
+    spawnReviewer(_args: SpawnArgs): Promise<ReviewerHandle>;
+    spawnHealthProbe(args: SpawnArgs): Promise<ProbeHandle>;
+    /**
+     * CP-7 PART F — engage the trusted-execution substrate for ONE implementor
+     * spawn. Returns the `SpawnArgs` to launch with (substrate-augmented on the
+     * `substrate` branch; unchanged on the legacy/reduced-trust branch) + an
+     * `onExit` callback the LE wires to the process-exit lifecycle so the broker
+     * is stopped (zeroized) + the bootstrap destroyed + the sandbox torn down.
+     *
+     * Fail-closed: if `engageSubstrate` THROWS (broker couldn't start, etc.) it
+     * propagates — we do NOT silently fall back to an unsandboxed run. The ONLY
+     * non-substrate outcome is the engager EXPLICITLY returning `reduced_trust`
+     * (no runtime available / GEMINI), which surfaces the prominent badge and
+     * takes the legacy path.
+     */
+    private engageSubstrateForSpawn;
+    /**
+     * CP-7 PART F — surface the PROMINENT reduced-trust badge (§6 Q2). The moat
+     * being OFF (or coarse) MUST be visible + auditable, never silent: a
+     * user-visible NOTIFICATION carrying a structured `reducedTrust: true` flag +
+     * a WARN log line.
+     *
+     * W2 Stage-2 HIGH — DELIVERY DISCIPLINE per tier:
+     *   - `tier: 'none'` (the moat is fully OFF — the agent runs unsandboxed with
+     *     ambient `process.env` reachable): the badge MUST be DELIVERED before the
+     *     agent runs. It is routed through the STRICT delivery sink
+     *     (`deps.strictBadgeSink`) which CONFIRMS the NOTIFICATION actually reached
+     *     `createEvent` and THROWS on a silent no-op (cohort off / no session key /
+     *     stub / tap-ignored) — the ordinary `emitShellEvent` would RESOLVE without
+     *     emitting in those cases (Finding 2). This method AWAITS that delivery with
+     *     a bounded timeout and RE-THROWS on a reject/timeout. The WARN log stays
+     *     but is NOT sufficient on its own — the caller turns a throw here into a
+     *     FAIL-CLOSED (no un-badged unsandboxed spawn). When no strict sink is wired
+     *     (legacy/tests), it falls back to `emitShellEvent` (a reject still fails
+     *     closed, but a silent no-op would not — production MUST wire the sink).
+     *   - `tier: 'sandbox_exec' | 'docker'` (the agent is still SANDBOXED, just
+     *     weakened/coarse egress): a failed badge is far less critical. We AWAIT
+     *     it (a bounded await is acceptable per §6 Q2) but SWALLOW a delivery
+     *     failure — the agent is still contained, so a missed coarse badge does
+     *     not warrant tearing the session down.
+     *
+     * Returns a promise the `tier:'none'` callers `await` (and fail-closed on
+     * reject); the coarse callers may `await` it too (it never rejects for them).
+     */
+    private surfaceReducedTrustBadge;
+    /**
+     * W2 Stage-2 HIGH — bound the `tier:'none'` badge delivery. Resolves only if
+     * the NOTIFICATION emit settles successfully within
+     * `REDUCED_TRUST_BADGE_DELIVERY_TIMEOUT_MS`; REJECTS if the emit rejects OR the
+     * timeout fires first. The caller fails closed on a reject (refuses the
+     * unsandboxed spawn) so no agent ever runs moat-OFF without the user having
+     * been warned.
+     */
+    private awaitBadgeDeliveryOrThrow;
+    private spawnWithLifecycle;
+    ingestHookEvent(event: HookEvent): Promise<void>;
+    /**
+     * Single-entrypoint inbound Class B dispatch per master §9:1287.
+     * Delegates to `ClassBConsumer.consume` which enforces LOCK #E3-1
+     * (verify → replay-check → dispatch) and per-kind handlers per CP-0
+     * §2.F.9-§2.F.13.
+     *
+     * TaskAuthorized advances authority scope + taskId atomically via the DI
+     * closure wired in the constructor (CP-0 §2.5 invariant #6).
+     *
+     * `envelopeTaskId` (Audited-path fix B) — the OUTER Class B envelope's taskId,
+     * forwarded to the consumer so a PolicyRejection (whose payload has no taskId)
+     * discards EXACTLY the rejected task's shadow. Optional for non-WS callers.
+     */
+    consumeClassB(packet: ClassBInbound, envelopeTaskId?: string): Promise<void>;
+    /**
+     * #C12-14 — launch the implementor for one track. IDEMPOTENT by
+     * `(task_group_id, track_index, dispatch_generation)`: a duplicate
+     * `TrackAssigned` for an already-launched generation spawns NOTHING
+     * (#C12-17). A strictly-newer generation (dispute re-dispatch, #C12-19)
+     * supersedes the stale entry.
+     *
+     * Steps: (1) idempotency check; (2) create + canonicalize the per-track
+     * `state_dir` via the existing spawn authority guard (NO bypass —
+     * `fs.realpath` exactly as `spawnSubprocess` requires); (3) advance the
+     * per-track authority scope to `ownership_scope`; (4) spawn the implementor
+     * in `state_dir` with the track's child `task_id`.
+     */
+    private launchTrack;
+    /**
+     * CP-12 W4 (#593) — the public team-dispatch recovery entrypoint. Exposes the
+     * EXACT private `launchTrack` body (register + brief bridge) so the QuorumLoop
+     * `recoverTeamTracks` PASS 2 can re-launch a track whose round-0 `TrackAssigned`
+     * was dropped by the emit-before-subscribe race. Returns the explicit result
+     * enum (`registered | duplicate | rejected`) the recovery loop discriminates:
+     *   - `registered` → the `registerTeamTask` brief bridge ran → drive the gate.
+     *   - `duplicate`  → returned BEFORE the bridge → recovery repairs the brief
+     *                    explicitly, then drives the gate.
+     *   - `rejected`   → the track did NOT launch (canonical state-dir confinement)
+     *                    → recovery skips it (no repair, no gate dispatch).
+     */
+    recoverLaunchTrack(payload: TrackAssignedPayload): Promise<'registered' | 'duplicate' | 'rejected'>;
+    /**
+     * FIX-4 — wrap a track's `SpawnArgs` with the Class A process-lifecycle
+     * audit hooks, mirroring the single-track `spawnWithLifecycle` path but bound
+     * to the TRACK's own `task_id` as the Class A context (so PROCESS_SPAWNED /
+     * PROCESS_EXITED envelopes attribute to the right track, not the team task).
+     */
+    private withTrackLifecycle;
+    /**
+     * #C12-7/#C12-8 — MergeGate runner. The `owner_track_index` track runs the
+     * shared integration check, derives a PASS/FAIL classification from the gate
+     * EXIT CODES (LE-cannot-lie), builds `changedFileSets` per track, signs the
+     * classification via W2.a `signMergeClassification`, and reports it through
+     * `submitMergeGateVerdict` (§2.1 shape).
+     *
+     * The LE reports ONLY the LE-reported failure classes (`IntegrationFailure`,
+     * `DirtyRepoState`); the server DERIVES the other 4 classes from the signed
+     * `changedFileSets` / cross-track data (#C12-8). The LE NEVER computes
+     * SharedFileConflict / ScopeViolation / ReviewerDisagreement / BudgetExhausted.
+     */
+    /**
+     * CP-14 Wave A — the `worktree_merge` merge-gate branch: build the merge-train
+     * inputs from the durable committed tips + the live member set, run
+     * {@link runWorktreeMergeGate} (merge-train → Tier-1 → promote the integration
+     * tip), and map the outcome to a `MergeResult` for the engine verdict. A
+     * `merged_promoted` ⇒ PASS; ANY halt ⇒ FAIL (the user tree is untouched by
+     * construction — #C14-AON — so there is no content to revert). FAILS CLOSED if
+     * `readTrackTips` is unwired (the gate cannot read its inputs).
+     */
+    private runWorktreeMergeBranch;
+    /**
+     * [P1b] GUARANTEED LOCAL freeze for the merge-gate timer. Wraps the inner gate
+     * so that ANY exit which STARTED the timer ('pending' emitted) but never
+     * converged — LEAK C (submit-exhaustion return), LEAK D (a thrown
+     * realpath/build/sign/encrypt), a pre-convergence halt — emits a local
+     * attempt-end that FREEZES the ticking clock. `runMergeGateInner` returns a
+     * DEDICATED `convergedOrBenign` boolean (NOT `resolvedMergeOutcomes.has(mgId)`,
+     * per the design's S2-iter3 Codex-L1: that map is set at submit-SUCCESS, before
+     * the convergence freeze — so a future refactor that lets `emitGroupConvergence`
+     * throw BEFORE its synchronous pass/fail freeze-tap would see `has()===true` and
+     * WRONGLY suppress the attempt-end → strand the timer forever). The boolean is
+     * `true` ONLY once the timer is actually frozen (convergence emitted) OR on the
+     * benign "another dispatch already converged + froze" return — so a throw (which
+     * leaves the `= await` assignment incomplete → `false`) always fires the freeze.
+     * The reducer no-ops the attempt-end when no live anchor exists (a pre-'pending'
+     * guard return / an already-frozen gate), so this is safe on every exit; a throw
+     * still propagates (the `finally` only emits — it never swallows).
+     */
+    private runMergeGate;
+    /** The single-flight merge-gate run body (P1b freeze wrapper). See {@link runMergeGate}. */
+    private runMergeGateExclusive;
+    /**
+     * Returns `convergedOrBenign`: `true` once the convergence pass/fail freeze-tap
+     * fired (timer frozen) OR on the benign already-resolved return; `false` on a
+     * strand exit (submit-exhaustion) so the wrapper's `finally` freezes the timer.
+     * A thrown exit never returns → the wrapper's boolean stays `false` → freeze.
+     */
+    private runMergeGateInner;
+    /**
+     * PHASE-589+469 W1 (§5.A / §5.C / #TC-2 / #TC-3) — drive the desktop CLI
+     * convergence from the AUTHORITATIVE engine `outcome`. Emits, via the SAME
+     * `emitShellEvent` tap chokepoint the per-track progress uses:
+     *   (a) the AUTHORITATIVE-sourced `merge_gate` status ('pass' on "complete",
+     *       'fail' on any failure-class outcome) — #TC-2;
+     *   (b) ONE `team_track_terminal` per member trackIndex (state 'Passed' on
+     *       "complete", else 'Failed') — flips InFlight→terminal (#TC-3);
+     *   (c) ONE `team_group_resolved` carrying the outcome — sets groupResolved.
+     *
+     * NO workspace mutation / promoteShadow here (#TC-1) — files already self-
+     * applied at each track's final_approval. Member trackIndices come from the
+     * local team registry (`trackPayloads`, the SAME source `buildChangedFileSets`
+     * uses). Team-only path — single-impl never reaches runMergeGate (#TC-8).
+     */
+    private emitGroupConvergence;
+    /**
+     * PHASE-589/469 W3.2 (D2) — drive the per-track render flip + group-resolved
+     * render for a USER GROUP DECISION (the 5-option escalation COMMIT), through
+     * the SAME `emitGroupConvergence` chokepoint the MergeGate convergence uses.
+     * This is the fix for the recurring "track stays InFlight after the user picks
+     * abort_task" gap: the group-decision path previously NEVER reached this
+     * chokepoint (only the MergeGate path did), so the per-track flip never fired.
+     *
+     * `outcome` is `'complete'` for an accept-family decision (tracks render
+     * `Passed`/kept) or a halted-reason label for a reject-family decision (tracks
+     * render `Failed`/reverted + the group resolves). Public so the orchestration
+     * shell can invoke it after the two-phase CLAIM→revert→COMMIT finishes.
+     */
+    driveGroupDecisionConvergence(taskGroupId: string, outcome: string): Promise<void>;
+    /**
+     * #C12-12 — surface a group halt to the UI (NOTIFICATION + escalation
+     * choices) and signal the in-flight track processes to stop. The deep
+     * choice-driven auto-resolution decision tree is server-side (#C12-3) — the
+     * LE only surfaces + stops. [DEFERRED — GA/CP-12 Wave 3+] for any LE-side
+     * choice-driven auto-action (retry/accept-partial/etc.); CP-8 #469 renders.
+     */
+    private haltTaskGroup;
+    /**
+     * FIX-2 — DERIVE + confinement-verify the per-track state dir (#C12-14).
+     *
+     * The state dir is the trust-boundary root for the per-track WRITE grant
+     * (scopeFromOwnership adds it to writeScopes). Trusting the payload's
+     * `state_dir` — OR the `task_group_id` / `track_index` we derive it from —
+     * verbatim would let a signed-but-malicious `TrackAssigned` point it OUTSIDE
+     * the sandbox and obtain a write grant there. So, defense-in-depth (the
+     * packet is Ed25519-signed but we still don't trust its fields as safe path
+     * segments):
+     *
+     *   0. VALIDATE `task_group_id` is a safe single path segment (non-empty, not
+     *      `.`/`..`, no `/`, `\`, or NUL, not absolute) and `track_index` is a
+     *      non-negative safe integer. Otherwise a `task_group_id` of
+     *      "../../../../tmp/x" makes the DERIVED path itself escape, and the
+     *      packet's matching `state_dir` then passes the exact-match check.
+     *   1. Compute the trusted state root `realpath(realpath(repoRoot)/.codevibe/
+     *      state)` (realpath resolves any symlinked component).
+     *   2. DERIVE `realpath(stateRoot)/<task_group_id>/<track_index>`, mkdir -p,
+     *      realpath it (canonical workingDir for the spawn guard).
+     *   3. CONTAINMENT CHECK — the realpath'd derived dir MUST stay strictly under
+     *      the realpath'd state root (catches both `..`-segment AND symlinked-
+     *      component escapes).
+     *   4. Verify the payload's supplied `state_dir` resolves to EXACTLY the
+     *      derived path. A mismatch / escape ⇒ REJECT (return null): no spawn, no
+     *      scope grant. Never feed an attacker-controlled path into the grant.
+     *
+     * Returns the canonical derived dir on success, or `null` on a confinement
+     * violation (logged here; the caller drops the packet).
+     */
+    private canonicalizeStateDir;
+    /**
+     * Map a track's snake_case `OwnershipScope` to the LE `AuthorityScope`. WRITE
+     * is limited to the declared `write_paths` + `auto_modified_files` + the
+     * track's own state dir; READ inherits the current scope's read prefixes (the
+     * shared workspace) plus the write set. Command/network inherit the current
+     * team scope's grants + expiry (the track runs the existing gate flow).
+     */
+    private scopeFromOwnership;
+    /**
+     * Build `changedFileSets` per track for the group (#C12-8). M2 derives each
+     * track's set from its declared `write_paths` (the LE enforced WRITE only
+     * there via the per-track authority scope) — the bounded trust attestation
+     * the design names (the signed manifest IS the trusted boundary for 2.0;
+     * server-stored signed diff manifests w/ base/head are a CP-7 follow-up,
+     * §12 deferred). Paths are relative-to-repo as declared.
+     *
+     * #590 NOTE — `test_surfaces` are DELIBERATELY NOT attested here. The signed
+     * manifest stays the strictly-disjoint `write_paths ∪ auto_modified_files`
+     * set so the MergeGate `SharedFileConflict` overlap check (which is unaware of
+     * the `isSharedTestOwner` exception) cannot false-positive on legitimately
+     * overlapping shared test surfaces. The desktop `filesOutsideWriteScope` guard
+     * DOES admit `test_surfaces` (an own-module test write is in-lane), and the
+     * server `derive_server_class` ScopeViolation allow-set is a SUPERSET that also
+     * admits `test_surfaces` — so a future actual-diff manifest carrying a declared
+     * test file stays accepted. Non-divergent because the manifest ⊆ that allow-set.
+     */
+    private buildChangedFileSets;
+    /**
+     * §2.3 — emit a per-track progress event carrying `track_index` + `task_id`
+     * in metadata so mobile/desktop CAN render per-track threads (CP-8 #469
+     * renders; W2.b adds the wire attribution only). Emitting a per-track
+     * progress event also renews that track's lease (#C12-18). This path is ONLY
+     * for group tracks — single-track events go through the hook bridge and OMIT
+     * the field (backward-compatible).
+     */
+    private emitTrackProgress;
+    /**
+     * CP-12 W3 Stage-2 r2 — emit the MergeGate lifecycle ('pending' | 'pass' |
+     * 'fail') to the status node via the SAME emitShellEvent tap chokepoint the
+     * per-track progress uses. `runMergeGate` calls this; the shell tap maps
+     * `source: 'merge_gate'` → `TEAM_MERGE_GATE`. Carries `task_group_id` so the
+     * tap's per-group isolation guard can drop a stale older-group event. Team-
+     * only path — single-track/Companion never reach runMergeGate.
+     */
+    /** [P1b] Strict-monotonic ISO stamp for the merge-gate `started_at` anchor. */
+    private nextMergeGateTs;
+    /**
+     * [P1b] Emit the merge-gate status to the shell + mobile. SYNCHRONOUS return —
+     * TAP-LOCAL-SYNC + FIRE-AND-FORGET the remote: `emitShellEvent` taps the desktop
+     * store synchronously (driving the merge-gate timer) then awaits the AppSync/
+     * mobile send, which we deliberately do NOT await, so a hung OR throwing remote
+     * emitter can never block `runMergeGate` before its `try/finally` freeze (S2 Codex-H
+     * "safeEmit is rejection-safe but not hang-safe"). Timestamps: `'pending'` (start)
+     * carries a strict-monotonic `started_at`; `attemptEnd`/pass/fail carry `ended_at`.
+     */
+    private emitMergeGateStatus;
+    /** Set the active taskId (production: CP-1.e on TASK_AUTHORIZED). */
+    setActiveTaskId(taskId: string | null): void;
+    /** Replace the active authority scope (production: CP-1.e on TASK_AUTHORIZED). */
+    setAuthorityScope(scope: AuthorityScope): void;
+    /** Expose emitter for §8.5 integration test introspection. */
+    get emitterForTests(): ClassAEmitter;
+    /** CP-12 W2.b — expose the per-track registry for idempotency introspection. */
+    get trackRegistryForTests(): TrackRegistry;
+    private contextOrNull;
+    /**
+     * Context resolver for ClassBConsumer emit paths (refusals + PolicyRejection).
+     * Class B inbound packets MAY arrive before a TaskAuthorized has set
+     * `this.taskId` (in fact, TaskAuthorized is the variant that SETS it). For
+     * the signature_invalid / ulid_replay / policy_rejection / malformed
+     * refusal-audit emit path we still need a valid envelope context, so we
+     * fall back to `pending` when no task is active. CP-2 may refine this; for
+     * CP-1.e the audit emit always succeeds with a deterministic placeholder.
+     */
+    private contextOrFallback;
+}
+/** @internal */
+export declare function __resetSessionRegistryForTests(): void;