@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/local-executor/durable-store.d.ts

@@ -0,0 +1,334 @@
+import type { ShadowChangeKind, ShadowDiffFile } from './workspace-shadow';
+import type { ImageAttachment } from '../orchestration-shell/types';
+/** The current manifest schema version (append-only; bump on a breaking shape change). */
+export declare const REVERT_MANIFEST_VERSION: 1;
+/** Marker stored in `preImageRef` for a file that did NOT exist pre-promote (a created file). */
+export declare const ABSENT_PREIMAGE: "ABSENT";
+/** Default TTL for a true-orphan manifest GC fallback (~48h, LOCK #589-I). */
+export declare const ORPHAN_TTL_MS: number;
+/**
+ * The lifecycle of a group's revert record — the GC-predicate key (LOCK #589-I).
+ * A group is GC-eligible ONLY in a terminal lifecycle (`accepted` /
+ * `reject_revert_complete`) OR past the orphan TTL. `in_flight` and
+ * `reject_revert_in_progress` ALWAYS survive a restart.
+ */
+export type RevertLifecycle = 'in_flight' | 'accepted' | 'reject_revert_in_progress' | 'reject_revert_complete';
+/** One applied-file entry in the durable revert manifest. */
+export interface RevertManifestEntry {
+    /** The track that applied this path. */
+    trackIndex: number;
+    /** Monotonic apply order ACROSS the whole group (reverse order drives reverse-apply). */
+    promoteOrder: number;
+    /** Path RELATIVE to the workspace root. */
+    path: string;
+    /** How the promote changed the file. */
+    changeKind: ShadowChangeKind;
+    /**
+     * Where the pre-image CONTENT lives — a `preimages/<sha>.blob` relative ref, OR
+     * the {@link ABSENT_PREIMAGE} marker for a `created` file (nothing to restore).
+     */
+    preImageRef: string;
+    /** SHA-256 of the pre-image content; `null` for an absent (created) file. */
+    preImageHash: string | null;
+    /** SHA-256 of the applied content; `null` for a `deleted` file. */
+    postPromoteHash: string | null;
+}
+/** The revert-manifest record-type-1 slot. */
+export interface RevertManifestSlot {
+    promotes: RevertManifestEntry[];
+}
+/**
+ * Record-type-4 slot (PHASE-589/469 W3.2, HIGH-1 / LOCK #589-J) — the durable
+ * "a group decision was CLAIMED but not yet COMMITted" marker. Persisted at CLAIM
+ * time (in `submitGroupDecision`, right after the CLAIM phase mints `claimToken`)
+ * so a desktop crash BETWEEN the CLAIM and the COMMIT can resume the side-effect
+ * AND drive the COMMIT on the next startup reconcile. Cleared after the terminal
+ * COMMIT lands (so it is never re-driven). Content-bounded:
+ *   - `decision` — the closed 5-option label (e.g. `REJECT_WITH_NOTES`);
+ *   - `claimToken` — the opaque race-arbiter token the COMMIT must echo (NOT a
+ *     secret — a discriminator, not an auth credential);
+ *   - `notes` — the user's OWN `*_WITH_NOTES` plaintext, re-sent E2E-encrypted by
+ *     the resumed COMMIT. It is at-rest under the SAME `0600`/atomic/no-symlink
+ *     guards as every other slot (LOCK #589-G), and NEVER logged (#589-G "no file
+ *     content in any log" — `notes` is the user's text).
+ */
+export interface PendingGroupDecision {
+    decision: string;
+    claimToken: string;
+    notes?: string;
+}
+/**
+ * Record-type-3 slot (PHASE-589/469 W3.2 RESIDUAL 1) — the retained `/team`
+ * launch input a `REJECT_RESTART` re-dispatches from. `workItems` is the wire
+ * `WorkItemInput[]` (ownership scopes / agents / isSharedTestOwner — NO brief on
+ * the wire); `briefs` is the per-track plaintext brief as `[trackIndex, brief]`
+ * pairs (the durable round-trip of the in-memory `Map<number,string>`). Typed
+ * `unknown[]` here so the store stays decoupled from the team wire types (it only
+ * JSON-round-trips the spec); `launchTeamFromWorkItems` casts back at reissue.
+ */
+export interface RetainedTeamLaunchSpec {
+    workItems: unknown[];
+    briefs: [number, string][];
+    /**
+     * IMAGE-ATTACHMENT-DESIGN.md §5 — retained image-attachment refs (paths +
+     * metadata, NEVER bytes) so a `REJECT_RESTART` reissue re-copies from
+     * `sourcePath` (fail-soft if a source moved). Append-only field — a pre-image
+     * record without it decodes via the `?? undefined` read.
+     */
+    attachments?: ImageAttachment[];
+    /**
+     * §13 Option-2 — the ordered-with-DUPLICATES resolved carried-path list aligned with
+     * the `[Image #N]` chip numbers in `briefs`, so a `REJECT_RESTART` reissue re-runs the
+     * same number-based chip rewrite. Append-only; a pre-image record decodes as undefined.
+     */
+    attachmentPaths?: string[];
+}
+/** The unified durable record under `<taskGroupId>/manifest.json` (#589-G). */
+export interface RevertRecordV1 {
+    version: typeof REVERT_MANIFEST_VERSION;
+    taskGroupId: string;
+    /** The GC-predicate key (LOCK #589-I). */
+    lifecycle: RevertLifecycle;
+    createdAtMs: number;
+    updatedAtMs: number;
+    /** Record type 1 — the revert manifest (outlives apply until group terminal). */
+    revertManifest: RevertManifestSlot;
+    /** Record type 2 — the optional #598 reviewed snapshot (cleared at promote). */
+    reviewedSnapshot: ShadowDiffFile[] | null;
+    /**
+     * Record type 3 — the optional retained `/team` launch spec (RESIDUAL 1). `null`
+     * until a team launch persists it; read by `REJECT_RESTART` reissue. Append-only
+     * field — a pre-W3.2-RESIDUAL record without it decodes via the `?? null` reads.
+     */
+    teamLaunchSpec?: RetainedTeamLaunchSpec | null;
+    /**
+     * Record type 4 — the optional CLAIMED-but-not-COMMITted group decision (HIGH-1
+     * / LOCK #589-J). Persisted at CLAIM time, cleared after the terminal COMMIT.
+     * A non-null value on startup means a CLAIM-crash → the reconcile resumes the
+     * revert (reject family) + drives the COMMIT with the persisted `claimToken`.
+     * Append-only field — a pre-HIGH-1 record decodes via the `?? null` reads.
+     */
+    pendingDecision?: PendingGroupDecision | null;
+}
+/**
+ * Stable cursor key for ONE manifest entry (W3-H1). The crash-resume cursor MUST
+ * key on the entry IDENTITY `(promoteOrder, path)`, NOT the path alone: a single
+ * path promoted MORE THAN ONCE (track/round promoted `shared.ts` C→B, then B→A)
+ * has TWO manifest entries with the SAME path but different `promoteOrder`. A
+ * path-only cursor records `shared.ts` after the newest step, so a crash before
+ * the older step makes resume SKIP the older entry (same path) → the tree is left
+ * dirty (stuck at B instead of the oldest baseline). The separator is a single
+ * space; `promoteOrder` is a non-negative integer (no spaces), so the leading
+ * maximal digit-run before the first space uniquely decomposes `(promoteOrder,
+ * path)` — the key is collision-free. Keys are only string-compared (Set
+ * membership), never parsed back. (Exported so the revert-runner reads/writes the
+ * SAME key.)
+ */
+export declare function revertEntryKey(promoteOrder: number, relPath: string): string;
+/** The write-ahead revert journal — crash-resume cursor (LOCK #589-I). */
+export interface RevertJournalV1 {
+    version: 1;
+    taskGroupId: string;
+    state: 'reverting' | 'complete';
+    startedAtMs: number;
+    /**
+     * Paths already reverted in THIS pass. RETAINED for backward-compat (a pre-W3-H1
+     * in-flight journal carries only this) + human-readable diagnostics; the resume
+     * cursor is now keyed on {@link revertedEntryKeys}, NOT this path-only list.
+     */
+    revertedPaths: string[];
+    /**
+     * W3-H1 — the PER-ENTRY resume cursor: `revertEntryKey(promoteOrder, path)` for
+     * each manifest entry reverted in THIS pass. Resume skips by ENTRY identity (not
+     * path), so a same-path multi-promote reverts EVERY remaining step in reverse
+     * order after a mid-revert crash. Append-only field — a pre-W3-H1 journal decodes
+     * via the `?? []` reads (its in-flight steps re-run, which is idempotent: the
+     * 3-hash check in revertOne no-ops an already-reverted entry).
+     */
+    revertedEntryKeys?: string[];
+}
+/** Manifest entries a promote contributes, BEFORE the content is spilled to blobs. */
+export interface PromoteManifestInput {
+    trackIndex: number;
+    promoteOrder: number;
+    path: string;
+    changeKind: ShadowChangeKind;
+    /** The pre-image content (the file currently on disk); `null` = absent (created). */
+    preImageContent: string | null;
+    /** SHA-256 of `preImageContent`; `null` when absent. */
+    preImageHash: string | null;
+    /** SHA-256 of the applied content; `null` for a deleted file. */
+    postPromoteHash: string | null;
+}
+/**
+ * CP-14 Wave A — one committed track tip (a merge-train input). Written at the
+ * per-track `promoteShadowLocked` seam under `team.execution=worktree_merge`;
+ * read by the merge gate to build the `MergeTrainTrack[]`. Durable so a desktop
+ * crash between a track commit and the merge gate doesn't lose the tip (a lost
+ * tip = a dropped track = data loss → the gate FAILS CLOSED on any absent tip).
+ */
+export interface TrackTipRecord {
+    trackIndex: number;
+    /** The persistent track branch, `codevibe/track/<group>/<idx>`. */
+    trackBranch: string;
+    /** The committed tip SHA the merge-train merges. */
+    trackTip: string;
+}
+/** The durable track-tip record the merge gate reads to build its merge-train. */
+export interface TrackTipsView {
+    /** The pinned group base, or null if no tips were ever recorded. */
+    baseSha: string | null;
+    tips: TrackTipRecord[];
+}
+/**
+ * The pure durable-store. ONE instance per desktop; all paths derive from
+ * {@link rootDir} (overridable for deterministic tests).
+ */
+export declare class RevertManifestStore {
+    private readonly rootDir;
+    /**
+     * CP-14 Wave A (Codex r2 MED) — per-group serialization for the track-tips
+     * read-modify-write. Two tracks of the SAME group authorize concurrently (the
+     * shadow mutex is per-TASK, not per-group), so two `appendTrackTip` calls could
+     * both read the old record and the later writer would clobber the earlier tip
+     * (a lost durable tip = an approved track's work vanishes from the merge gate's
+     * only source of truth). A per-group promise chain serializes the RMW.
+     */
+    private readonly trackTipChains;
+    constructor(opts?: {
+        rootDir?: string;
+    });
+    /** Serialize `fn` against other track-tip RMW for the same group (Codex r2 MED). */
+    private withTrackTipLock;
+    /** The per-group directory `<root>/<taskGroupId>/`. */
+    private groupDir;
+    /**
+     * Validate `taskGroupId` is a safe SINGLE path segment so a malicious id can't
+     * escape `<root>/` (defense-in-depth; ids are ULIDs server-side, but never
+     * trust a field as a path segment, #589-G).
+     */
+    private safeSegment;
+    /**
+     * Make a directory tree with `0700` on every created component.
+     * `recursive: true` honors `mode` for the components it creates.
+     */
+    private mkdirSecure;
+    /**
+     * Refuse to operate under a path whose any in-`rootDir` component is a symlink
+     * (LOCK #589-G "no symlink following"). lstat each component from `rootDir`
+     * down; a symlinked component throws. Missing components are fine (not yet
+     * created). The `rootDir` itself is lstat-checked too.
+     */
+    private assertNoSymlinkComponents;
+    /**
+     * Atomic write: write `<final>.tmp.<pid>.<rand>` (`0600`) → fsync → rename →
+     * fsync(dir). Refuses symlinked components first. NEVER logs CONTENT.
+     */
+    private atomicWrite;
+    private readJson;
+    /**
+     * Append a track's promote entries to the group manifest, BEFORE the tree
+     * mutates (LOCK #589-I). Spills pre-image content to `preimages/<sha>.blob`.
+     * Creates the record (`in_flight`) on first call. Idempotent on
+     * `(promoteOrder, path)` — a re-promote of the SAME entry overwrites it (a
+     * crash-redelivered promote does not double-append).
+     *
+     * NEVER logs file content.
+     */
+    appendPromote(taskGroupId: string, _trackIndex: number, entries: PromoteManifestInput[]): Promise<void>;
+    private writeRecord;
+    /** Read the full unified record, or `null` if none exists. */
+    readRecord(taskGroupId: string): Promise<RevertRecordV1 | null>;
+    /** Read just the manifest entries (empty when no record). */
+    readManifest(taskGroupId: string): Promise<RevertManifestEntry[]>;
+    /**
+     * Record a track's committed tip (the merge-train input) at the per-track
+     * `promoteShadowLocked` seam, BEFORE the merge gate runs. Idempotent on
+     * `trackIndex` — a re-committed track (crash-redelivered TaskAuthorized)
+     * overwrites its prior tip rather than duplicating. Atomic + symlink-guarded
+     * (same primitive as the revert manifest). NEVER logs content (only SHAs).
+     */
+    appendTrackTip(taskGroupId: string, baseSha: string, tip: TrackTipRecord): Promise<void>;
+    /**
+     * Read the pinned group base + all committed track tips (base `null` + empty
+     * when none). The merge gate builds its `MergeTrainTrack[]` from this DURABLE
+     * copy (the single source of truth) and FAILS CLOSED if an expected member's
+     * tip is missing.
+     */
+    readTrackTips(taskGroupId: string): Promise<TrackTipsView>;
+    /** Read a pre-image blob's content by its manifest `preImageRef`. */
+    readPreImage(taskGroupId: string, preImageRef: string): Promise<string>;
+    private setLifecycle;
+    /** Group accepted/kept → terminal lifecycle `accepted` (GC-eligible). */
+    markAccepted(taskGroupId: string): Promise<void>;
+    /** A reject revert has STARTED → `reject_revert_in_progress` (never GC'd). */
+    markRevertInProgress(taskGroupId: string): Promise<void>;
+    /** A reject revert COMPLETED → terminal lifecycle `reject_revert_complete` (GC-eligible). */
+    markRevertComplete(taskGroupId: string): Promise<void>;
+    /** Is this group's LOCAL revert lifecycle terminal (the GC-eligible predicate)? */
+    isLifecycleTerminal(lifecycle: RevertLifecycle): boolean;
+    /** Store the reviewed snapshot for a track promote (cleared at promote via {@link clearReviewedSnapshot}). */
+    setReviewedSnapshot(taskGroupId: string, snapshot: ShadowDiffFile[]): Promise<void>;
+    /** Read the reviewed snapshot, or `null`. */
+    getReviewedSnapshot(taskGroupId: string): Promise<ShadowDiffFile[] | null>;
+    /** Clear the reviewed snapshot at promote (its lifecycle ends here; the manifest survives). */
+    clearReviewedSnapshot(taskGroupId: string): Promise<void>;
+    /**
+     * Persist the ORIGINAL `/team` launch spec for a group (RESIDUAL 1), so a
+     * `REJECT_RESTART` can re-dispatch the WHOLE team from it after a restart. Creates
+     * the record (`in_flight`) on first call (a team launch persists this BEFORE any
+     * promote, so the record may not exist yet). Idempotent overwrite. NEVER logs the
+     * brief CONTENT (only counts — #589-G).
+     */
+    setTeamLaunchSpec(taskGroupId: string, spec: RetainedTeamLaunchSpec): Promise<void>;
+    /** Read the retained `/team` launch spec, or `null` (no record / never set). */
+    getTeamLaunchSpec(taskGroupId: string): Promise<RetainedTeamLaunchSpec | null>;
+    /**
+     * Persist the CLAIMED-but-not-COMMITted group decision (HIGH-1 / LOCK #589-J),
+     * written at CLAIM time so a crash before COMMIT resumes on the next startup.
+     * Creates the record (`in_flight`) on first call (a decision is claimed only on
+     * a live in-flight group, so the manifest already exists, but the `?? default`
+     * keeps this total). Idempotent overwrite. NEVER logs the `notes` CONTENT — only
+     * the closed `decision` label (#589-G).
+     */
+    setPendingDecision(taskGroupId: string, pending: PendingGroupDecision): Promise<void>;
+    /** Read the pending (claimed-not-committed) decision, or `null`. */
+    getPendingDecision(taskGroupId: string): Promise<PendingGroupDecision | null>;
+    /**
+     * Clear the pending decision after the terminal COMMIT lands (so the reconcile
+     * never re-drives it). No-op when there is no record / nothing pending.
+     */
+    clearPendingDecision(taskGroupId: string): Promise<void>;
+    /**
+     * Begin a revert journal (or read the existing one to RESUME). If a
+     * `reverting` journal already exists, return it (the caller resumes,
+     * skipping `revertedPaths`); otherwise start a fresh one.
+     */
+    beginRevert(taskGroupId: string): Promise<RevertJournalV1>;
+    /** Read the current journal (or `null`). */
+    readJournal(taskGroupId: string): Promise<RevertJournalV1 | null>;
+    private writeJournal;
+    /**
+     * Record ONE reverted manifest ENTRY (append-only resume cursor). W3-H1: the
+     * cursor is keyed on the entry IDENTITY `(promoteOrder, path)` — NOT path alone —
+     * so a same-path multi-promote records EACH step independently and a crash-resume
+     * reverts every remaining step. The path is ALSO appended (legacy/diagnostics
+     * compat). Idempotent on the entry key (a redelivered record is a no-op);
+     * atomic + append-only per LOCK #589-G.
+     */
+    recordReverted(taskGroupId: string, relPath: string, promoteOrder: number): Promise<void>;
+    /** Mark the journal complete (the revert finished this pass). */
+    endRevert(taskGroupId: string): Promise<void>;
+    /** List every group id with a durable record under `<root>/`. */
+    listManifests(): Promise<string[]>;
+    /**
+     * GC predicate (LOCK #589-I): delete a group's `<taskGroupId>/` ONLY when its
+     * LOCAL lifecycle is terminal (`accepted` / `reject_revert_complete`) OR it is
+     * past the orphan TTL. NEVER GC `in_flight` / `reject_revert_in_progress` —
+     * "engine terminal alone" is INSUFFICIENT (the caller reconciles BEFORE GC).
+     * Returns the ids it removed.
+     */
+    gc(now?: number, ttlMs?: number): Promise<string[]>;
+}
+/** SHA-256 hex of UTF-8 content (exported for the promote-site manifest capture). */
+export declare function hashManifestContent(content: string): string;

package/dist/local-executor/git-lock-retry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Is `msg` a TRANSIENT git lock-contention error (retryable), vs a genuine
+ * failure? A real `.lock`-file collision ALWAYS carries "unable to create
+ * '.../<name>.lock': File exists" (for a loose ref, `index.lock`, or
+ * `packed-refs.lock`); we also match the top-level "another git process" hint.
+ *
+ * DELIBERATELY narrow — it does NOT match the bare "cannot lock ref '<ref>':
+ * …" prefix, because git uses that SAME prefix for two NON-transient outcomes:
+ *   - "cannot lock ref '<ref>': reference already exists" — the create-only
+ *     (`update-ref <ref> <sha> ''`) refusal, which the caller inspects +
+ *     handles idempotently. Retrying it would loop forever against a
+ *     legitimately-existing branch (the bug this narrowing fixes).
+ *   - "cannot lock ref '<ref>': is at X but expected Y" — a real CAS
+ *     expected-old mismatch (the ref genuinely moved), which must surface.
+ * The transient variant ("cannot lock ref …: Unable to create '….lock': File
+ * exists") is still caught via the "unable to create" clause.
+ */
+export declare function isGitLockContention(msg: string): boolean;
+export interface GitLockRetryOpts {
+    /** Injected for tests (zero wall-clock). Defaults to a real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Override the attempt cap (default 5). */
+    maxAttempts?: number;
+    /** Override the exponential base delay (default 100ms). */
+    baseDelayMs?: number;
+}
+/**
+ * Run a single git op with (a) serialization onto the shared process-global
+ * chain and (b) retry-with-exponential-backoff on transient lock contention.
+ *
+ * `op` MUST be a single leaf git invocation (one `execFile`/`git()` call), NEVER
+ * a compound helper that awaits ANOTHER `withGitLockRetry` op inside it — a
+ * nested chained op would deadlock (the inner await can never acquire the chain
+ * the outer op holds). Sequential chained ops are fine (that is the point).
+ *
+ * A non-lock error (or the final attempt) propagates unchanged, so a caller's
+ * typed errors (e.g. a real CAS mismatch) surface intact — only lock
+ * contention is absorbed.
+ */
+export declare function withGitLockRetry<T>(op: () => Promise<T>, opts?: GitLockRetryOpts): Promise<T>;

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

@@ -3,7 +3,7 @@ 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';
+    type: 'USER_PROMPT' | 'ASSISTANT_RESPONSE' | 'INTERACTIVE_PROMPT' | 'LOCAL_AUTHORITY_REFUSAL' | 'NOTIFICATION' | 'CONTINUATION_PACKET_FAILED';
     content?: string;
     metadata?: Record<string, unknown>;
     timestamp?: string;

package/dist/local-executor/implementor-argv.d.ts

@@ -0,0 +1,183 @@
+import type { AuthorityScope } from './authority';
+import type { AgentKind } from './types';
+/** Read-only "plan" vs write "execute" authority for the implementor. */
+export type ImplementorMode = 'plan' | 'execute';
+/** Where to read the implementor's final proposal text from after exit. */
+export type ImplementorCaptureSurface = {
+    kind: 'stdout';
+} | {
+    kind: 'file';
+    path: string;
+};
+export interface ImplementorArgvPlan {
+    /** Argv WITHOUT the leading executable (the LE/spawn supplies the binary). */
+    argv: string[];
+    /** Where the final proposal text is captured from after `await handle.done`. */
+    capture: ImplementorCaptureSurface;
+}
+/**
+ * D9 — the ONE shared `CODEVIBE_AGY_MODEL` resolver used by BOTH
+ * `buildImplementorArgv` (the spawned argv) and `agyImplementorAllowlistEntries`
+ * (the authority templates) so the two can never drift. Absent/empty → `null`
+ * (omit `--model`, agy default). Invalid → THROW fail-closed with a clear
+ * operator error (surfaces at scope construction / spawn, never a silent
+ * mangled spawn).
+ *
+ * LIFETIME: the env is resolved ONCE into the authority scope at
+ * `LocalExecutor` construction (`makeImplementorCommandScope`) — mutating
+ * `CODEVIBE_AGY_MODEL` mid-session drifts the spawn argv from the cached
+ * template → a false-positive AuthorityError. Fixed-per-executor-lifecycle;
+ * tests that mutate the env MUST rebuild the scope/executor.
+ */
+export declare function resolveAgyModel(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * agy's INTERNAL print-mode ceiling for implementor runs. Deliberately
+ * generous (implementor spawns have no fixed external timeout on the round
+ * path) and FIXED — it is part of the pinned allowlist template prefix, so it
+ * cannot vary per spawn.
+ */
+export declare const AGY_IMPLEMENTOR_PRINT_TIMEOUT = "3600s";
+/**
+ * D3 (agy-R2-iter4 MED fix) — the COMPUTED per-mode agy allowlist entries.
+ * Kept OUT of the static `IMPLEMENTOR_COMMAND_ALLOWLIST` const because
+ * `--model <value>` is resolved from `CODEVIBE_AGY_MODEL` at RUNTIME — a
+ * static template can neither pin the value nor omit it when set. Two
+ * FULLY-PINNED templates (plan `--sandbox` vs execute
+ * `--dangerously-skip-permissions` — the N-3 defense-in-depth split), with
+ * `<workdir>` as the SOLE trailing wildcard. Appended by
+ * `makeImplementorCommandScope` at scope construction.
+ */
+export declare function agyImplementorAllowlistEntries(): string[];
+/**
+ * D3 — the abs-path brief preamble for an agy implementor/decomposer/resolver
+ * spawn. agy is WORKSPACE-CENTRIC: it ignores the process cwd, so the brief
+ * MUST name the working directory by ABSOLUTE path (the cwd-phrased default
+ * contract would silently no-op into agy's own scratch dir — the
+ * empty-shadow-diff hazard). Prepended to the standard contract by the spawn
+ * sites (quorum-loop `composeImplementorStdin`, team decomposer, agentic
+ * resolver).
+ */
+export declare function agyWorkdirBriefPreamble(workdir: string): string;
+/**
+ * Build the implementor invocation argv for `agent` in `mode`. The leading
+ * executable name (`claude` / `codex` / `gemini` / `agy`) is the argv[0] so
+ * callers can pass the whole array to `spawnImplementor` (which resolves the
+ * binary from PATH). The brief is fed on stdin by the caller (`stdinPayload`).
+ *
+ * `workdir` (AGY-2.0 D3) is REQUIRED for ANTIGRAVITY (agy is
+ * workspace-centric — `--add-dir <workdir>` is its only view of the tree; the
+ * agy case throws FAIL-CLOSED without it so a missed call site errors loudly
+ * instead of silently no-oping into agy's scratch). The cwd-based agents
+ * ignore it.
+ */
+export declare function buildImplementorArgv(agent: AgentKind, mode: ImplementorMode, workdir?: string): ImplementorArgvPlan;
+/**
+ * Positive runtime evidence that this process is ACTUALLY inside a container —
+ * the confinement boundary that `CODEVIBE_TRUSTED_CONTAINER` asserts. Docker
+ * drops `/.dockerenv`; Podman drops `/run/.containerenv`; containerd / cri-o /
+ * Kubernetes / LXC surface in PID 1's cgroup. Best-effort + FAIL-CLOSED: any fs
+ * error, or a non-Linux host with no markers, returns `false`. Bare macOS /
+ * Windows desktops (no container) return `false`. Pure read; no side effects.
+ */
+export declare function isInsideContainer(): boolean;
+/**
+ * `CODEVIBE_TRUSTED_CONTAINER` — a desktop-set signal that the LE is ALREADY
+ * running inside a container that confines it (e.g. the dogfood image, or any
+ * externally-sandboxed CI runner), even when the CP-7 substrate itself did not
+ * engage (no NESTED runtime available). When honored, the implementor's own
+ * inner sandbox is redundant AND, for Codex, actively broken (bwrap can't create
+ * a namespace in a nested/unprivileged container), so the outer container is
+ * treated as the confinement boundary.
+ *
+ * Stage-2 r1 Codex HIGH — DEFENSE IN DEPTH: an ambient env var ALONE is too weak
+ * a boundary signal. A stray `CODEVIBE_TRUSTED_CONTAINER` in a developer's
+ * persistent shell, or a misconfigured CI runner, would otherwise run Codex
+ * `--sandbox danger-full-access` on a BARE HOST with ambient credentials
+ * reachable. So the env flag is honored ONLY when `isInsideContainer()` returns
+ * POSITIVE runtime evidence that a confining boundary actually exists: the env
+ * says "a boundary confines me", the runtime check PROVES one is present. A bare
+ * host with a stray env var → `false` → Codex keeps its own `workspace-write`
+ * sandbox. The dogfood image (a real Docker container) passes both. The
+ * container check is injectable for tests.
+ */
+export declare function isTrustedContainerBoundary(env?: NodeJS.ProcessEnv, inContainer?: () => boolean): boolean;
+/**
+ * CP-7 substrate-aware Codex sandbox selection. When an OUTER confinement
+ * boundary already isolates the implementor — the CP-7 substrate engaged (Docker
+ * `--network none` / sandbox-exec), OR a marked trusted container
+ * (`CODEVIBE_TRUSTED_CONTAINER`) — rewrite the Codex EXECUTE argv's
+ * `--sandbox workspace-write` → `--sandbox danger-full-access`.
+ *
+ * Rationale: Codex's `workspace-write` builds its OWN inner sandbox with
+ * bubblewrap, which cannot create a user namespace inside a nested/unprivileged
+ * container and aborts before any file operation ("bwrap: No permissions to
+ * create a new namespace"). When an outer boundary already confines the agent
+ * (the CP-7 design intent — the substrate IS the sandbox), Codex's inner sandbox
+ * is both redundant and a hard blocker, so we drop it. On a BARE host (no outer
+ * boundary), `workspace-write` is KEPT — there bwrap works (Linux user
+ * namespaces / macOS Seatbelt) and is the only filesystem confinement.
+ *
+ * NARROW BY DESIGN:
+ *   - Only CODEX is affected (Claude/Gemini have no bwrap inner sandbox).
+ *   - Only `workspace-write` (the EXECUTE variant) is rewritten. `read-only`
+ *     (PLAN mode) is left untouched — it is a DELIBERATE write restriction, and
+ *     `danger-full-access` would let a plan-mode agent write, violating the plan
+ *     contract.
+ *   - No-op when `outerBoundaryConfines` is false.
+ * Pure; returns a NEW array when it rewrites, the same array otherwise.
+ */
+export declare function applyOuterBoundarySandbox(argv: readonly string[], agent: AgentKind, outerBoundaryConfines: boolean): string[];
+/**
+ * Authority `commandAllowlist` entries covering EVERY (agent, mode) argv
+ * `buildImplementorArgv` can produce. The single-impl + team LEs seed this
+ * into their authority scope at construction (cli.ts) so `enforceCommand`
+ * (authority.ts) permits the implementor spawn.
+ *
+ * CP-1.f Hybrid authority split (2026-06-05): the DESKTOP is the authority on
+ * WHICH agent binaries may run (this fixed allowlist); the engine authorizes
+ * per-task PATH scopes (writeScopes/readScopes) via the TaskAuthorized Class-B
+ * packet. Seeding commands desktop-side is the smaller, safer attack surface —
+ * an engine-supplied command allowlist would let a compromised backend
+ * authorize arbitrary command strings.
+ *
+ * Matching (authority.ts `enforceCommand`): an entry is a LITERAL full
+ * `argv.join(' ')` match, OR a ` *`-suffix TEMPLATE (prefix match).
+ *   - Claude / Gemini argvs are fixed → literal entries. (Gemini's `-p ''`
+ *     empty arg yields a DOUBLE space in the join — preserved verbatim here.)
+ *   - Codex carries a per-spawn temp path in `--output-last-message <tmp>` →
+ *     a ` *` template: the literal prefix up to `--output-last-message`, then
+ *     the wildcard absorbs the varying path + trailing `-`.
+ *
+ * DRIFT GUARD: `__tests__/implementor-argv.test.ts` asserts every
+ * `buildImplementorArgv(agent, mode)` output passes `enforceCommand` against
+ * this list — an argv-builder change not mirrored here fails the test.
+ */
+export declare const IMPLEMENTOR_COMMAND_ALLOWLIST: readonly string[];
+/**
+ * Build the LE authority scope seeding ONLY the implementor command allowlist —
+ * no write/read/network grants. `writeScopes`/`readScopes` stay empty (the
+ * engine authorizes paths via TaskAuthorized; the CP-7 substrate, not this
+ * scope, confines filesystem writes). `implementor` is NOT a network-gated
+ * spawn role (`ROLES_REQUIRING_NETWORK` in spawn.ts excludes it), so
+ * `networkAllowed: false` does not block the implementor spawn.
+ */
+export declare function makeImplementorCommandScope(): AuthorityScope;
+/**
+ * The Codex EXECUTE-under-confinement command (`danger-full-access`) authority
+ * entry — kept OUT of the ambient `IMPLEMENTOR_COMMAND_ALLOWLIST` and granted
+ * ONLY per-spawn via `withBoundaryConfinedCommandAuthority` (Stage-2 r2 Codex
+ * HIGH). Same ` *` template shape as the other Codex entries (the per-spawn temp
+ * path after `--output-last-message` is absorbed by the wildcard).
+ */
+export declare const CODEX_DANGER_FULL_ACCESS_COMMAND = "codex exec --sandbox danger-full-access --skip-git-repo-check --color never --json --ephemeral --output-last-message *";
+/**
+ * Return a scope that ADDS the boundary-confined Codex `danger-full-access`
+ * command authority (`CODEX_DANGER_FULL_ACCESS_COMMAND`) to `scope`'s
+ * `commandAllowlist`. The spawn path calls this ONLY when `outerBoundaryConfines`
+ * is proven (CP-7 substrate engaged OR a verified trusted container) — so the
+ * dangerous command is authorized for exactly the spawn that an outer boundary
+ * isolates, and NEVER ambiently. On an unconfined spawn the base scope (without
+ * this entry) makes `enforceCommand` fail-closed on any danger argv. Idempotent;
+ * returns `scope` unchanged if already present.
+ */
+export declare function withBoundaryConfinedCommandAuthority(scope: AuthorityScope): AuthorityScope;

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

@@ -1,8 +1,49 @@
 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 { AgentKind, AuthorityAction, ClassBInbound, ExecutorError, FailureClass, FileChangeKind, GateDispatchPayload, GateDispatchReviewerSeat, HookEvent, ImplementorHandle, LocalExecutor, MergeGateDispatchPayload, ProbeHandle, ProcessExitedInfo, ProcessRole, ProcessSpawnedInfo, ReviewerHandle, ReviewerDispatchPayload, ReviseFeedbackPayload, ReviseSeatFinding, SignedEnvelope, SpawnArgs, SpawnArgsInvalid, SpawnHandleBase, TaskGroupHaltedPayload, TrackAssignedPayload, TrackConflictContext, } from './types';
+export { agyImplementorAllowlistEntries, agyWorkdirBriefPreamble, AGY_IMPLEMENTOR_PRINT_TIMEOUT, buildImplementorArgv, IMPLEMENTOR_COMMAND_ALLOWLIST, makeImplementorCommandScope, resolveAgyModel, type ImplementorArgvPlan, type ImplementorCaptureSurface, type ImplementorMode, } from './implementor-argv';
+export { verifyClassBEd25519, classBCanonicalForSigning, ed25519PublicKeyFromRaw, type ClassBCryptoVerifyResult, } from './class-b-verify';
+export { TrackRegistry, TrackProcess, trackKey } from './track-registry';
 export { EmitShellEventFn, HookBridge, HookBridgeDeps, } from './hook-bridge';
-export { LocalExecutorImpl, LocalExecutorImplDeps, makeEmptyScope, } from './local-executor-impl';
+export { LocalExecutorImpl, LocalExecutorImplDeps, MergeGateAppSyncClient, MergeGateContentEncryptor, makeEmptyScope, } from './local-executor-impl';
+export type { SubstrateEngager, SubstrateEngageResult, StrictBadgeSink, } from './local-executor-impl';
+export { Cp7AuditWriter, CP7_CANONICAL_FORM_VERSION, GENESIS_PREV_HASH, canonicalJson, canonicalEntryBytes, computeEntryHash, verifyChain, } from './cp7-audit-writer';
+export type { Cp7AuditEntry } from './cp7-audit-writer';
 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';
+export { ClassBConsumer, ClassBConsumerDeps, ClassBConsumerState, ClassBVerificationResult, INBOUND_REPLAY_CAP, INBOUND_REPLAY_TTL_MS, UlidReplayRegistry, verifyClassBSignature, normalizeTrackAssignedWire, isValidTrackAssignedPayload, } from './class-b-consumer';
+export { DeviceSigningKey, canonicalJsonForSigning, signClassAEnvelope, signMergeClassification, } from './class-a-sign';
+export { ContractRefInput, CreateTaskGroupInput, CreateTaskGroupResult, DisjointnessRejection, DisjointnessViolation, EncryptedPayloadInput, FailingCondition, MergeClassificationInput, MergeFailureClass, MergeResult, MergeRetryTarget, MergeRetryTargetKind, OwnershipScopeInput, RecommendedOption, SubmitMergeGateVerdictInput, SubmitMergeGateVerdictResult, SubmitTrackVerificationOutcomeInput, SubmitTrackVerificationOutcomeResult, TeamTrackFailureReason, TrackChangedFiles, UserCeilingsInput, WorkItemInput, ClaimGroupDecisionInput, ClaimGroupDecisionResult, GroupDecisionLabel, GroupDecisionPhase, } from './task-group-types';
+export { RevertManifestStore, REVERT_MANIFEST_VERSION, ABSENT_PREIMAGE, ORPHAN_TTL_MS, hashManifestContent, } from './durable-store';
+export type { RevertLifecycle, RevertManifestEntry, RevertManifestSlot, RevertRecordV1, RevertJournalV1, PromoteManifestInput, RetainedTeamLaunchSpec, PendingGroupDecision, TrackTipRecord, TrackTipsView, } from './durable-store';
+export { revertGroup } from './revert-runner';
+export type { RevertResult } from './revert-runner';
+export { reconcileRevertManifestsThenGc } from './revert-reconcile';
+export type { EngineGroupState, ReconcileDeps, ReconcileResult, ReconcileCommitClient, } from './revert-reconcile';
+export { DEFAULT_TEAM_EXECUTION, TEAM_EXECUTION_ENV_VAR, isTeamExecution, resolveTeamExecution, isWorktreeMergeEnabled, } from './team-execution-flag';
+export type { TeamExecution } from './team-execution-flag';
+export { PromoteWalStore, PROMOTE_WAL_VERSION, computePromoteKey, } from './promote-wal-store';
+export type { PromoteMode, PromoteWalRecord, PromoteStartedInput, } from './promote-wal-store';
+export { MERGE_IMPL_ID, resolveMergeImplId, BranchStateMismatchError, trackBranchName, integrationBranchName, stashBranchName, rescueRefName, rescueLiveRefName, promotedTipRefName, createIntegrationBranch, createTrackBranch, promoteIntegration, revertToPrePromote, recoverPromote, recoverAllPromotes, gcDanglingPromptly, cleanupGroupRepo, mergeTreeOffBranch, commitTreeOffBranch, treeOf, pinnedGit, } from './worktree-merge';
+export type { BranchFoundation, PromoteOutcome, RevertToPrePromoteOutcome, PromoteRecoveryOutcome, WorktreeMergeRaceHooks, MergeTreeResult, } from './worktree-merge';
+export { MergeJournalStore, MERGE_JOURNAL_VERSION, computeMergeKey, } from './merge-journal-store';
+export type { MergeJournalRecord, MergeJournalTrack, MergeStepRecord, MergeGroupInput, MergeGroupWriteResult, MergeStepInput, } from './merge-journal-store';
+export { MergeOrderError, RefCasMismatchError, MERGE_KEY_TRAILER, MERGE_COMMIT_DATE, MERGE_COMMIT_IDENTITY, computeMergeOrder, runMergeTrain, deriveMergeGateId, recoverMergeTrain, runTier1OnIntegrationWorktree, runWorktreeMergeGate, } from './merge-train';
+export type { MergeTrainTrack, MergeOrder, MergeTrainOutcome, MergeTrainRecoveryOutcome, MergeTrainRecoveryHooks, Tier1Outcome, Tier1GateConfig, MergeGateResult, WorktreeMergeGateArgs, } from './merge-train';
+export { RESOLUTION_SET_TRAILER, buildMergeCommitMessage } from './merge-train';
+export { detectSharedContract, isHardSharedContract, globToRegExp, pathMatchesGlob, } from './shared-contract-detector';
+export type { SharedContractCategory, SharedContractMatch, SharedContractDetectorOptions, } from './shared-contract-detector';
+export { classifyConflict } from './conflict-classifier';
+export type { ConflictKind, GitObjectType, ConflictSide, ConflictFileMeta, ConflictClass, ConflictClassification, ConflictHunk, } from './conflict-types';
+export { attemptClass1, reconcileLockfile, lockfileCanonicalEntries } from './class1-reconcilers';
+export type { Class1ReconcileResult } from './class1-reconcilers';
+export { computeConflictId, hashResolvedBytes, snapshotSides, verifyResolvedBytes, InMemoryConflictResolutionStore, } from './conflict-resolution-store';
+export type { ConflictIdInput, ConflictSidesSnapshot, ConflictResolutionRecord, ConflictResolutionStore, } from './conflict-resolution-store';
+export { resolveClass2, assembleResolverPrompt, promptByteSize } from './class2-resolver';
+export type { ResolverPrompt, ResolverModelResult, ConflictModelCaller, ResolveClass2Input, ResolveClass2Deps, ResolveClass2Result, } from './class2-resolver';
+export { parseDiff3Conflicts, hunksFromSegments, composeResolvedFile, hasConflictMarkers, } from './merge-conflict-extract';
+export type { ConflictSegment } from './merge-conflict-extract';
+export { resolveSlotConflicts } from './merge-conflict-resolve';
+export type { ConflictResolverContext, HumanGatedConflict, SlotResolveResult, } from './merge-conflict-resolve';
+export { mergeBaseOf, lsTreeEntry, diff3MergeBlobs, extractThreeWayConflict, assembleResolvedTree, } from './worktree-merge';
+export type { TreeEntry } from './worktree-merge';