@quantiya/codevibe-core 1.0.23 → 2.0.1

package/dist/local-executor/__tests__/authority-symlink-fixture.d.ts

@@ -0,0 +1,15 @@
+import type { AuthorityScope } from '../authority';
+export interface SymlinkBypassFixture {
+    tmpRoot: string;
+    insideScope: string;
+    outsideScope: string;
+    outsideTarget: string;
+    attemptViaSymlink: string;
+    scope: AuthorityScope;
+}
+export interface CreateSymlinkBypassFixtureOptions {
+    parentMissing?: boolean;
+}
+export declare function createSymlinkBypassFixture(options?: CreateSymlinkBypassFixtureOptions): Promise<SymlinkBypassFixture>;
+export declare function cleanupFixture(fixture: SymlinkBypassFixture): Promise<void>;
+export declare function makeEmptyExpiredScope(): AuthorityScope;

package/dist/local-executor/__tests__/authority.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/class-a-emit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/class-b-consumer.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/class-b-consumer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/hook-bridge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/local-executor.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/spawn.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/__tests__/verification-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-executor/authority.d.ts

@@ -0,0 +1,29 @@
+import { promises as fs } from 'node:fs';
+export interface AuthorityScope {
+    writeScopes: string[];
+    readScopes: string[];
+    networkAllowed: boolean;
+    commandAllowlist: string[];
+    expiresAt: string;
+}
+export type AuthorityRefusalCategory = 'authority_scope_conflict' | 'signature_invalid' | 'ulid_replay' | 'policy_rejection';
+export interface AuthorityRefusal {
+    category: AuthorityRefusalCategory;
+    detail: string;
+}
+export declare class AuthorityError extends Error {
+    readonly refusal: AuthorityRefusal;
+    constructor(refusal: AuthorityRefusal);
+}
+export declare class FileNotFound extends Error {
+    readonly canonicalPath: string;
+    constructor(canonicalPath: string, cause?: unknown);
+}
+export declare function enforceWrite(scope: AuthorityScope, p: string): Promise<string>;
+export declare function safeWriteFile(scope: AuthorityScope, p: string, data: Buffer | string, options?: Parameters<typeof fs.writeFile>[2]): Promise<void>;
+export declare function enforceRead(scope: AuthorityScope, p: string): Promise<string>;
+export declare function safeReadFile(scope: AuthorityScope, p: string, options?: {
+    encoding?: BufferEncoding;
+}): Promise<string | Buffer>;
+export declare function enforceNetwork(scope: AuthorityScope): void;
+export declare function enforceCommand(scope: AuthorityScope, argv: string[]): void;

package/dist/local-executor/class-a-emit.d.ts

@@ -0,0 +1,138 @@
+import type { AdapterProgressEnvelope } from '../adapter/progress';
+import { AuthorityRefusal, AuthorityRefusalCategory } from './authority';
+import { AgentKind, FailureClass, ProcessRole } from './types';
+export type ExecutionEventKind = 'PROCESS_SPAWNED' | 'TOOL_USE' | 'FILE_CHANGE' | 'VERIFICATION_RUN' | 'PROCESS_EXITED';
+export type ClassAMessageType = 'EXECUTION_EVENT' | 'EXECUTOR_REFUSAL' | 'VERIFICATION_RESULT' | 'ADAPTER_PROGRESS';
+export interface ClassAEnvelope {
+    messageVersion: 1;
+    messageType: ClassAMessageType;
+    messageId: string;
+    taskId: string;
+    sessionId: string;
+    userId: string;
+    tenantId: string;
+    deviceId: string;
+    occurredAt: string;
+    payload: unknown;
+    signature?: string;
+}
+export interface ProcessSpawnedPayload {
+    kind: 'PROCESS_SPAWNED';
+    processRole: ProcessRole;
+    pid: number;
+    adapter: AgentKind;
+}
+export interface ToolUsePayload {
+    kind: 'TOOL_USE';
+    toolName: string;
+    bounded: boolean;
+    toolInputDigest: string;
+}
+export interface FileChangePayload {
+    kind: 'FILE_CHANGE';
+    repoPath: string;
+    changeSummary: {
+        added: number;
+        modified: number;
+        deleted: number;
+    };
+    diffDigest: string;
+}
+export interface VerificationRunPayload {
+    kind: 'VERIFICATION_RUN';
+    check: string;
+    passed: boolean;
+    runtimeMs: number;
+}
+export interface ProcessExitedPayload {
+    kind: 'PROCESS_EXITED';
+    pid: number;
+    exitCode: number;
+    failureClass: FailureClass;
+}
+export interface ExecutorRefusalPayload {
+    refusedMessageId: string;
+    refusalCategory: AuthorityRefusalCategory;
+    refusalDetail: string;
+    recommendedRecovery: 'reauthorize_locally' | 'abort_task' | 'ask_user' | 'retry_after_resync';
+}
+export type VerificationGateKind = 'build' | 'tests' | 'lint' | 'typecheck' | 'hostile_grep' | 'source_traceability' | 'diff_sanity' | 'deploy_preflight';
+export interface VerificationResultPayload {
+    gate_kind: VerificationGateKind;
+    status: 'PASS' | 'FAIL';
+    exit_code: number;
+    stdout_summary_truncated: string;
+    stderr_summary_truncated: string;
+    duration_ms: number;
+}
+export interface ClassASink {
+    emit(envelope: ClassAEnvelope): Promise<void>;
+}
+export declare class LocalStubSink implements ClassASink {
+    private readonly logPath;
+    constructor(logPath: string);
+    emit(envelope: ClassAEnvelope): Promise<void>;
+}
+export interface ClassAEmitterContext {
+    taskId: string;
+    sessionId: string;
+    userId: string;
+    tenantId: string;
+    deviceId: string;
+}
+export declare const DEFAULT_DEDUPE_CAP = 10000;
+export declare function isValidUlid(s: string): boolean;
+export interface EmitterLogger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare class ClassAEmitter {
+    private readonly sink;
+    private readonly cap;
+    private readonly logger?;
+    private readonly seenUlids;
+    private readonly messageIdFactory;
+    constructor(sink: ClassASink, seenUlids?: Set<string>, cap?: number, logger?: EmitterLogger | undefined, messageIdFactory?: () => string);
+    emitProcessSpawned(ctx: ClassAEmitterContext, args: {
+        pid: number;
+        processRole: ProcessRole;
+        adapter: AgentKind;
+        occurredAt?: string;
+    }): Promise<void>;
+    emitToolUse(ctx: ClassAEmitterContext, args: {
+        toolName: string;
+        toolInputDigest: string;
+        bounded?: boolean;
+        occurredAt?: string;
+    }): Promise<void>;
+    emitFileChange(ctx: ClassAEmitterContext, args: {
+        repoPath: string;
+        changeSummary: FileChangePayload['changeSummary'];
+        diffDigest: string;
+        occurredAt?: string;
+    }): Promise<void>;
+    emitVerificationRun(ctx: ClassAEmitterContext, args: {
+        check: string;
+        passed: boolean;
+        runtimeMs: number;
+        occurredAt?: string;
+    }): Promise<void>;
+    emitProcessExited(ctx: ClassAEmitterContext, args: {
+        pid: number;
+        exitCode: number;
+        failureClass: FailureClass;
+        occurredAt?: string;
+    }): Promise<void>;
+    emitExecutorRefusal(ctx: ClassAEmitterContext, args: {
+        refusal: AuthorityRefusal;
+        refusedMessageId: string;
+        recommendedRecovery?: ExecutorRefusalPayload['recommendedRecovery'];
+        occurredAt?: string;
+    }): Promise<void>;
+    submitVerificationResultClassAEvent(ctx: ClassAEmitterContext, payload: VerificationResultPayload, occurredAt?: string): Promise<void>;
+    submitAdapterProgressClassAEvent(ctx: ClassAEmitterContext, envelope: AdapterProgressEnvelope, occurredAt?: string): Promise<void>;
+    private emitExecutionEvent;
+    private buildEnvelope;
+    private dispatchWithDedupe;
+    /** @internal */
+    get seenUlidsForTests(): ReadonlySet<string>;
+}

package/dist/local-executor/class-b-consumer.d.ts

@@ -0,0 +1,121 @@
+import type { AuthorityScope } from './authority';
+import { ClassAEmitter, ClassAEmitterContext } from './class-a-emit';
+import { EmitShellEventFn } from './hook-bridge';
+import { ClassBInbound } from './types';
+export type ClassBVerificationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'malformed_envelope' | 'algorithm_unsupported';
+};
+/**
+ * CP-1.e signature-verification STUB per design §4.1.
+ *
+ * Returns `{ ok: false }` on:
+ *   - missing/empty `signedEnvelope` or `signatureB64`
+ *   - unsupported `algorithm` (only `ed25519` / `p384-ecdsa` per CP-0 §2.3 enum)
+ *   - missing/empty `publicKeyId`
+ *   - missing/malformed `nonceUlid` (must be 26-char ULID)
+ *
+ * Returns `{ ok: true }` for every structurally-well-formed envelope. CP-2
+ * Stage A replaces the implementation with real signature verification but
+ * preserves this exact return-type contract (LOCK #E1-1 stability).
+ */
+export declare function verifyClassBSignature(envelope: ClassBInbound): ClassBVerificationResult;
+export declare const INBOUND_REPLAY_CAP = 10000;
+export declare const INBOUND_REPLAY_TTL_MS: number;
+/**
+ * INBOUND ULID-replay registry per design §5.1 + CP-0 §2.5 invariant #5.
+ *
+ * SCOPE DISAMBIGUATION (LOCK inherited from CP-1.c §6.2):
+ *   - OUTBOUND emitter dedupe = `ClassAEmitter.seenUlids` (CP-1.c scope).
+ *   - INBOUND consumer replay refusal = this class (CP-1.e scope).
+ *
+ * Bounded memory: 10K LRU entries × 24h TTL. Sweep is O(n) worst case but
+ * amortizes O(1) per insert because JS Map iterates in insertion order — a
+ * single non-expired entry means all subsequent ones are non-expired.
+ */
+export declare class UlidReplayRegistry {
+    private readonly cap;
+    private readonly ttlMs;
+    private readonly nowMs;
+    private readonly seenAt;
+    constructor(cap?: number, ttlMs?: number, nowMs?: () => number);
+    /**
+     * Returns `true` if the ULID is a replay (already seen within the active
+     * window). On `false`, the ULID is inserted and the registry is swept for
+     * expired entries + cap overflow.
+     */
+    checkAndInsert(ulid: string): boolean;
+    private sweepExpired;
+    /** Test-only — exposes seen-set size. */
+    get sizeForTests(): number;
+}
+export interface ClassBConsumerState {
+    /** Last received PlannerDecisionApproved per taskId; CP-2 reads. */
+    plannerDecisionByTask: Map<string, Extract<ClassBInbound, {
+        kind: 'PlannerDecisionApproved';
+    }>>;
+    /** Last received GateDispatch per gateRunId; CP-2 reads. */
+    gateDispatchByRun: Map<string, Extract<ClassBInbound, {
+        kind: 'GateDispatch';
+    }>>;
+    /** Last received ContinuationOffer per handoffId; CP-2 reads. */
+    continuationOfferByHandoff: Map<string, Extract<ClassBInbound, {
+        kind: 'ContinuationOffer';
+    }>>;
+}
+export interface ClassBConsumerDeps {
+    emitter: ClassAEmitter;
+    emitShellEvent: EmitShellEventFn;
+    getContext: () => ClassAEmitterContext;
+    /** Called on TaskAuthorized to mutate the LocalExecutorImpl's authority scope (CP-0 §2.5 invariant #6). */
+    advanceAuthorityScope: (newScope: AuthorityScope, taskId: string) => void;
+    /** Called on PolicyRejection to surface the rejection to the user (LOCK C4-3 user-visible channel). */
+    notifyPolicyRejection?: (detail: string, category: string, recommendedRecovery: string) => void;
+    /** Test seam for deterministic UlidReplayRegistry behavior. */
+    replayRegistry?: UlidReplayRegistry;
+}
+/**
+ * Class B inbound consumer per design §6.1.
+ *
+ * Single-entrypoint `consume(packet)` enforces LOCK #E3-1 ordering:
+ *   1. verify (LOCK #E1-1 — refuses signature_invalid via Class A audit)
+ *   2. replay-check (LOCK #E2-1 — refuses ulid_replay via Class A audit)
+ *   3. per-kind dispatch (5 locked variants per CP-0 §2.F.9-§2.F.13)
+ *
+ * Reverse ordering would let a tampered-but-replayed envelope advance state —
+ * explicitly forbidden by LOCK #E3-1.
+ */
+export declare class ClassBConsumer {
+    private readonly deps;
+    private readonly state;
+    private readonly replayRegistry;
+    constructor(deps: ClassBConsumerDeps);
+    consume(packet: ClassBInbound): Promise<void>;
+    private handlePlannerDecisionApproved;
+    private handleGateDispatch;
+    private handleContinuationOffer;
+    private handleTaskAuthorized;
+    private handlePolicyRejection;
+    /**
+     * Constructs an AuthorityRefusal with one of the LOCK #E4-1 widened category
+     * literals and emits an EXECUTOR_REFUSAL via the CP-1.c emitter. Audit-only:
+     * the user-visible NOTIFICATION channel is reserved for PolicyRejection (the
+     * only Class B variant that surfaces hosted policy decisions to the user).
+     *
+     * `recommendedRecovery` is derived per-category to match CP-0 §2.F.14 fixture
+     * row literals verbatim on the wire (was Codex Stage-2 r1 H-1 — emitter
+     * default `'reauthorize_locally'` is correct for `authority_scope_conflict`
+     * (CP-1.c authority paths) but wrong for the CP-1.e Class-B variants):
+     *   - signature_invalid     → 'retry_after_resync' (CP-0 fixture line 458)
+     *   - ulid_replay           → 'abort_task'         (CP-0 fixture line 486)
+     *   - policy_rejection      → 'ask_user'           (consumer of policy reject)
+     *   - authority_scope_conflict → 'reauthorize_locally' (inherited CP-1.c default)
+     */
+    private refuseWithCategory;
+    /** Test-only — exposes cached-decision registry for §6.4 assertions. */
+    get stateForTests(): Readonly<ClassBConsumerState>;
+    /** Test-only — exposes replay registry for §5.3 / §6.4 introspection. */
+    get replayRegistryForTests(): UlidReplayRegistry;
+}

package/dist/local-executor/hook-bridge.d.ts

@@ -0,0 +1,36 @@
+import { AuthorityError, AuthorityScope } from './authority';
+import { ClassAEmitter, ClassAEmitterContext } from './class-a-emit';
+import { AgentKind, HookEvent } from './types';
+export type EmitShellEventFn = (args: {
+    sessionId: string;
+    type: 'USER_PROMPT' | 'ASSISTANT_RESPONSE' | 'INTERACTIVE_PROMPT' | 'LOCAL_AUTHORITY_REFUSAL' | 'NOTIFICATION';
+    content?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+}) => Promise<void>;
+export interface HookBridgeDeps {
+    emitter: ClassAEmitter;
+    emitShellEvent: EmitShellEventFn;
+    getAuthorityScope: () => AuthorityScope;
+    getCurrentTaskId: () => string | null;
+    getContextWithoutTask: () => Omit<ClassAEmitterContext, 'taskId'>;
+    adapter: AgentKind;
+}
+export declare class HookBridge {
+    private readonly deps;
+    constructor(deps: HookBridgeDeps);
+    ingest(event: HookEvent): Promise<void>;
+    private translateToolUse;
+    private translateFileChange;
+    private translateProcessExited;
+    private translateUserPrompt;
+    private translateAssistantText;
+    bridgeAuthorityRefusal(err: AuthorityError, args: {
+        refusedMessageId: string;
+        shellContent: string;
+        shellMetadata?: Record<string, unknown>;
+    }): Promise<void>;
+    private contextOrNull;
+    /** @internal */
+    get adapterForTests(): AgentKind;
+}

package/dist/local-executor/index.d.ts

@@ -0,0 +1,8 @@
+export { AuthorityError, AuthorityRefusal, AuthorityRefusalCategory, AuthorityScope, FileNotFound, enforceCommand, enforceNetwork, enforceRead, enforceWrite, safeReadFile, safeWriteFile, } from './authority';
+export { spawnHealthProbe, spawnImplementor, spawnReviewer } from './spawn';
+export { AgentKind, AuthorityAction, ClassBInbound, ExecutorError, FailureClass, FileChangeKind, HookEvent, ImplementorHandle, LocalExecutor, ProbeHandle, ProcessExitedInfo, ProcessRole, ProcessSpawnedInfo, ReviewerHandle, SignedEnvelope, SpawnArgs, SpawnArgsInvalid, SpawnHandleBase, } from './types';
+export { EmitShellEventFn, HookBridge, HookBridgeDeps, } from './hook-bridge';
+export { LocalExecutorImpl, LocalExecutorImplDeps, makeEmptyScope, } from './local-executor-impl';
+export { ClassAEmitter, ClassAEmitterContext, ClassAEnvelope, ClassAMessageType, ClassASink, DEFAULT_DEDUPE_CAP, EmitterLogger, ExecutionEventKind, ExecutorRefusalPayload, FileChangePayload, LocalStubSink, ProcessExitedPayload, ProcessSpawnedPayload, ToolUsePayload, VerificationGateKind, VerificationResultPayload, VerificationRunPayload, isValidUlid, } from './class-a-emit';
+export { DEFAULT_GATE_TIMEOUT_MS, GateRunResult, SUMMARY_CAP_BYTES, TIMEOUT_EXIT_CODE, VerificationGateRequest, VerificationRunnerDeps, runVerificationGates, truncateUtf8Safe, } from './verification-runner';
+export { ClassBConsumer, ClassBConsumerDeps, ClassBConsumerState, ClassBVerificationResult, INBOUND_REPLAY_CAP, INBOUND_REPLAY_TTL_MS, UlidReplayRegistry, verifyClassBSignature, } from './class-b-consumer';

package/dist/local-executor/local-executor-impl.d.ts

@@ -0,0 +1,83 @@
+import { AuthorityScope } from './authority';
+import { ClassAEmitter, ClassAEmitterContext, ClassASink } from './class-a-emit';
+import { EmitShellEventFn } from './hook-bridge';
+import { AgentKind, AuthorityAction, ClassBInbound, HookEvent, ImplementorHandle, LocalExecutor, ProbeHandle, ReviewerHandle, SpawnArgs } from './types';
+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;
+    };
+}
+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;
+    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>;
+    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).
+     */
+    consumeClassB(packet: ClassBInbound): Promise<void>;
+    /** 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;
+    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;

package/dist/local-executor/spawn.d.ts

@@ -0,0 +1,6 @@
+import { AuthorityScope } from './authority';
+import { ImplementorHandle, ProbeHandle, ReviewerHandle, SpawnArgs, SpawnHandleBase } from './types';
+export declare function spawnImplementor(scope: AuthorityScope, args: SpawnArgs): Promise<ImplementorHandle>;
+export declare function spawnReviewer(scope: AuthorityScope, args: SpawnArgs): Promise<ReviewerHandle>;
+export declare function spawnHealthProbe(scope: AuthorityScope, args: SpawnArgs): Promise<ProbeHandle>;
+export declare function spawnSubprocess(scope: AuthorityScope, args: SpawnArgs): Promise<SpawnHandleBase>;

package/dist/local-executor/types.d.ts

@@ -0,0 +1,183 @@
+import type { ChildProcess } from 'node:child_process';
+import type { AuthorityRefusal, AuthorityScope } from './authority';
+export type ProcessRole = 'implementor' | 'reviewer' | 'health_probe' | 'auth_probe' | 'model_probe';
+export type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX';
+export type FailureClass = null | 'quota_exhausted' | 'auth_failed' | 'timeout' | 'unavailable' | 'user_aborted';
+export interface SpawnArgs {
+    argv: string[];
+    workingDir: string;
+    role: ProcessRole;
+    agentKind?: AgentKind;
+    timeoutMs: number | null;
+    envOverrides?: Record<string, string>;
+    stdinTty?: boolean;
+    stdinPayload?: string;
+    signal?: AbortSignal;
+    onProcessSpawned?: ProcessSpawnedHook;
+    onProcessExited?: ProcessExitedHook;
+}
+export interface ProcessSpawnedInfo {
+    pid: number;
+    role: ProcessRole;
+    agentKind: AgentKind | undefined;
+    spawnedAt: string;
+}
+export interface ProcessExitedInfo {
+    pid: number;
+    exitCode: number;
+    failureClass: FailureClass;
+    exitedAt: string;
+    runtimeMs: number;
+}
+export type ProcessSpawnedHook = (info: ProcessSpawnedInfo) => void;
+export type ProcessExitedHook = (info: ProcessExitedInfo) => void;
+export interface SpawnHandleBase {
+    pid: number;
+    role: ProcessRole;
+    agentKind: AgentKind | undefined;
+    spawnedAt: string;
+    /** Resolves when the child exits, regardless of cause. */
+    done: Promise<ProcessExitedInfo>;
+    /** Forcibly terminate (SIGKILL + cleanup). Idempotent. */
+    abort(): Promise<void>;
+    /** Captured stdout/stderr — local-only, never crosses the wire. */
+    stdout(): string;
+    stderr(): string;
+}
+export interface ImplementorHandle extends SpawnHandleBase {
+    kind: 'implementor';
+}
+export interface ReviewerHandle extends SpawnHandleBase {
+    kind: 'reviewer';
+}
+export interface ProbeHandle extends SpawnHandleBase {
+    kind: 'probe';
+}
+export declare class SpawnArgsInvalid extends Error {
+    readonly reason: string;
+    readonly offendingKey?: string | undefined;
+    constructor(reason: string, offendingKey?: string | undefined);
+}
+export declare const MARKER_ENV_KEYS: {
+    readonly CHILD: "CODEVIBE_CHILD_PROCESS";
+    readonly ROLE: "CODEVIBE_PROCESS_ROLE";
+    readonly QUORUM: "QUORUM_REVIEWER_SUBPROCESS";
+};
+export declare const MARKER_KEY_SET: ReadonlySet<string>;
+export type AuthorityAction = {
+    kind: 'Write';
+    path: string;
+} | {
+    kind: 'Read';
+    path: string;
+} | {
+    kind: 'Network';
+    urlOrHost: string;
+} | {
+    kind: 'Command';
+    command: string;
+    argv: string[];
+};
+export interface SignedEnvelope {
+    algorithm: 'ed25519' | 'p384-ecdsa';
+    publicKeyId: string;
+    signatureB64: string;
+    issuedAt: string;
+    nonceUlid: string;
+}
+export type ClassBInbound = {
+    kind: 'PlannerDecisionApproved';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'GateDispatch';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'ContinuationOffer';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'TaskAuthorized';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'PolicyRejection';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+};
+export type ExecutorError = {
+    kind: 'AuthorityRefusal';
+    refusal: AuthorityRefusal;
+} | {
+    kind: 'SpawnFailed';
+    detail: string;
+} | {
+    kind: 'SubprocessIo';
+    detail: string;
+} | {
+    kind: 'SignatureVerification';
+    detail: string;
+} | {
+    kind: 'MalformedClassB';
+    detail: string;
+} | {
+    kind: 'PolicyMismatch';
+    detail: string;
+};
+export type FileChangeKind = 'Created' | 'Modified' | 'Deleted';
+export type HookEvent = {
+    kind: 'ToolUse';
+    sessionId: string;
+    toolName: string;
+    toolInput: unknown;
+    timestamp: string;
+} | {
+    kind: 'FileChange';
+    sessionId: string;
+    path: string;
+    change: FileChangeKind;
+    timestamp: string;
+} | {
+    kind: 'ProcessExited';
+    sessionId: string;
+    pid: number;
+    exitCode: number;
+    timestamp: string;
+    failureClass?: FailureClass | undefined;
+    failureSignal?: NodeJS.Signals | undefined;
+} | {
+    kind: 'UserPrompt';
+    sessionId: string;
+    contentB64: string;
+    timestamp: string;
+} | {
+    kind: 'AssistantText';
+    sessionId: string;
+    contentB64: string;
+    timestamp: string;
+};
+export interface LocalExecutor {
+    spawnImplementor(args: SpawnArgs): Promise<ImplementorHandle>;
+    spawnReviewer(args: SpawnArgs): Promise<ReviewerHandle>;
+    spawnHealthProbe(args: SpawnArgs): Promise<ProbeHandle>;
+    /**
+     * Single-entrypoint authority gate. Dispatches to `enforceWrite` /
+     * `enforceRead` / `enforceNetwork` / `enforceCommand` based on `action.kind`.
+     * Throws `AuthorityError` on refusal (master §9:1284).
+     */
+    enforceAuthority(action: AuthorityAction): Promise<void>;
+    ingestHookEvent(event: HookEvent): Promise<void>;
+    /** Read-only view of the current TASK_AUTHORIZED.authorityScope. */
+    authorityScope(): Readonly<AuthorityScope>;
+    /** CP-1.c STUB; CP-1.e wires real AppSync subscription + signature verification. */
+    consumeClassB(packet: ClassBInbound): Promise<void>;
+}
+export interface SpawnedProcess {
+    child: ChildProcess;
+    pid: number;
+    role: ProcessRole;
+    agentKind: AgentKind | undefined;
+    spawnedAt: string;
+    spawnedAtMs: number;
+}

package/dist/local-executor/verification-gates/build.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface BuildGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runBuildGate(args: BuildGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/deploy-preflight.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface DeployPreflightGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runDeployPreflightGate(args: DeployPreflightGateArgs): Promise<GateRunResult>;

package/dist/local-executor/verification-gates/diff-sanity.d.ts

@@ -0,0 +1,6 @@
+import type { GateRunResult } from '../verification-runner';
+export interface DiffSanityGateArgs {
+    cwd: string;
+    timeoutMs: number;
+}
+export declare function runDiffSanityGate(args: DiffSanityGateArgs): Promise<GateRunResult>;