@quantiya/codevibe-core 2.0.92 → 2.0.93

package/dist/orchestration-shell/review-bundle.d.ts

@@ -0,0 +1,77 @@
+import { type BlobStore } from '../local-executor/blob-store';
+import type { BlobRef } from '../local-executor/change-manifest';
+import { type ShadowChangeKind } from '../local-executor/shadow-protocol';
+export interface ReviewBundleFile {
+    path: string;
+    change_kind: ShadowChangeKind;
+    /** The new version (null for a deletion). */
+    after: {
+        store: BlobStore;
+        ref: BlobRef;
+    } | null;
+    /** The base version (null for a created file, and for a base the user changed since the task started). */
+    before: {
+        store: BlobStore;
+        ref: BlobRef;
+    } | null;
+    /** R1-F6: the permission bits before and after (null where the side does not exist or is unknown). */
+    modes?: {
+        before: number | null;
+        after: number | null;
+    };
+    /**
+     * R1-F6 / R1-F7: the recorded base's SHA-256 and size, and whether the user's folder no longer holds it (so `before`
+     * is null although the file existed at task start). The INDEX says so instead of diffing against nothing.
+     */
+    base?: {
+        sha256: string;
+        size: number | null;
+        changed: boolean;
+    };
+}
+/** §5.7 / §7.4 — what the INDEX lists besides the changed files (R1-F6). */
+export interface ReviewIndexContext {
+    /** Private folders in the task copy — written to, never applied — with their §5.7 group. */
+    privateFolders: ReadonlyArray<{
+        path: string;
+        group: 'hidden' | 'dependencies' | 'rebuild-output' | 'codevibe';
+    }>;
+    /** Links, sockets, FIFOs and devices in the task copy — never applied. */
+    notApplicable: readonly string[];
+    /** §7.4 — the user's own changes to their folder since the task started (absent when it could not be counted). */
+    folderChanges?: {
+        changed: number;
+        created: number;
+        deleted: number;
+    };
+}
+/** At most this many names per INDEX list; the counts are always complete. */
+export declare const REVIEW_INDEX_LIST_LIMIT = 200;
+export interface ReviewBundleRecord {
+    version: 1;
+    /** Every file in the bundle, by its bundle-relative name (forward slashes), sorted. */
+    files: Array<{
+        name: string;
+        sha256: string;
+        size: number;
+    }>;
+}
+/** Build the bundle. `bundleDir` must not exist; its parent must. Returns the hash record to re-check on return. */
+export declare function buildReviewBundle(input: {
+    bundleDir: string;
+    taskBrief: string;
+    files: readonly ReviewBundleFile[];
+    context?: ReviewIndexContext;
+}): Promise<ReviewBundleRecord>;
+/**
+ * Remove a task-owned review round folder (bundle + seat scratch) — the bundle is read-only, so write permission is
+ * restored first. Never follows a link: entries are lstat'ed and only directories are walked. Absent → no-op.
+ */
+export declare function removeReviewRound(roundDir: string): Promise<void>;
+/** §8.1 return check: every recorded file present with its hash, and nothing else in the bundle. */
+export declare function verifyReviewBundle(bundleDir: string, record: ReviewBundleRecord): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;

package/dist/orchestration-shell/review-receipts.d.ts

@@ -0,0 +1,100 @@
+import type { ShadowChangeKind } from '../local-executor/shadow-protocol';
+export declare const MAX_RECEIPTS_PER_SEAT = 12;
+/** A change larger than this is not fully visible in the engine's inline excerpt — drawn first (§8.6). */
+export declare const RECEIPT_PRIORITY_CHANGE_BYTES: number;
+/**
+ * R1-F4 — a line longer than this is never requested: no reviewer can copy a minified file's megabyte line, so such a
+ * change falls back to the INDEX request. Lines are scanned as byte ranges, so a line's length never costs memory.
+ */
+export declare const MAX_RECEIPT_LINE_BYTES = 512;
+/**
+ * §8.1 — above this a version's changed lines are also placed in `large/`, in parts of at most this size: agy's file
+ * reader refuses a file over 100 MB (measured, agy 1.4.12) and a confined seat has no command tool (D-11).
+ */
+export declare const LARGE_VIEW_FILE_BYTES: number;
+export interface ReceiptFile {
+    path: string;
+    change_kind: ShadowChangeKind;
+    /** Full SHA-256 of the new version (the base version's for a deletion) — the INDEX lists its 12-char prefix. */
+    sha256: string;
+    hasAfter: boolean;
+    hasBefore: boolean;
+}
+export interface ReceiptRequest {
+    id: string;
+    kind: 'line' | 'index';
+    /** Bundle-relative file the request names (`after/<p>`, `before/<p>` or `INDEX.md`). */
+    file: string;
+    /** 1-based line number (kind `line`). */
+    line?: number;
+    /** What the reply must equal (line: whitespace-normalised) or contain (index: the SHA-256 prefix). */
+    expected: string;
+    /** The request as the prompt states it. */
+    text: string;
+}
+/** Collapse runs of whitespace and trim — the comparison §8.4 calls "exact (whitespace-normalised)". */
+export declare function normaliseReceiptValue(v: string): string;
+/**
+ * The changed region of a text file: after-lines (P, aCount − S] and before-lines (P, bCount − S], where P is the
+ * common prefix and S the common suffix (S never overlaps P) — exactly the single hunk `excerptDiff` renders.
+ */
+export declare function changedRegion(beforeFile: string | null, afterFile: string | null): Promise<{
+    after: [number, number] | null;
+    before: [number, number] | null;
+    changedBytes: number;
+}>;
+/**
+ * §8.1 — writes lines `range` of `file` to `<destDir>/lines-<first>-<last>.txt`, cut at line ends, each at most
+ * `partBytes` (a single longer line gets its own part). Line numbers are the whole file's. Deterministic, so a rebuilt
+ * bundle is byte-identical. Memory stays one chunk.
+ */
+export declare function writeLargeViewParts(file: string, range: [number, number], destDir: string, partBytes?: number): Promise<void>;
+/**
+ * Draw one seat's receipt requests from the bundle. `rng(n)` returns an integer in [0, n) — cryptographic by default,
+ * so a seat cannot predict its requests; tests inject a deterministic one.
+ */
+export declare function drawReceiptRequests(input: {
+    bundleDir: string;
+    files: readonly ReceiptFile[];
+    max?: number;
+    rng?: (n: number) => number;
+}): Promise<ReceiptRequest[]>;
+/** Re-read one request's expected value from the bundle (used by tests and the return path). */
+export declare function readRequestedLine(bundleDir: string, req: ReceiptRequest): Promise<string | null>;
+/**
+ * Parse `RECEIPT <id>: <value>` lines from a seat's final reply (last answer per id wins). R1-F5: backticks are part of
+ * the value — a copied markdown line may start or end with them — except the run that closes a code span the receipt
+ * line itself opened (`` `RECEIPT r1: value` ``).
+ */
+export declare function parseReceipts(text: string): Map<string, string>;
+/** §8.5 check: the requests that are missing or wrong in the reply (empty → every receipt is valid). */
+export declare function failingReceipts(requests: readonly ReceiptRequest[], replyText: string): ReceiptRequest[];
+/**
+ * F-AGY-RECEIPT — a shape-only account of why a reply failed its receipts, for the failure log: never a value or any
+ * file content (the reply quotes the user's files). `receiptLines` counts lines naming RECEIPT at all, so "the reply
+ * carried no receipts" is told apart from "it answered the wrong thing"; for a mismatch, `near` says whether the
+ * answer would have matched once quotes, emphasis or case were ignored — evidence for or against a formatting cause.
+ */
+export declare function diagnoseReceiptReply(failing: readonly ReceiptRequest[], replyText: string): {
+    replyBytes: number;
+    receiptLines: number;
+    failing: Array<{
+        id: string;
+        kind: string;
+        state: string;
+        near?: string;
+    }>;
+};
+/**
+ * §8.3 — the fixed section the desktop appends to the engine-rendered reviewer prompt: where the review folder is
+ * (and, for a macOS seat that has one, the masked original), that the folder is authoritative over any truncated
+ * excerpt above, and the receipt requests. A re-dispatch lists the requests the previous reply failed.
+ */
+export declare function renderReviewSeatSection(input: {
+    bundleDir: string;
+    originalDir?: string;
+    requests: readonly ReceiptRequest[];
+    failedBefore?: readonly ReceiptRequest[];
+    /** A seat whose command attempts end its turn with no reply (a confined agy seat, D-11). */
+    fileToolsOnly?: boolean;
+}): string;

package/dist/orchestration-shell/reviewer-seat-self-test.d.ts

@@ -0,0 +1,43 @@
+import type { SelfTestTier, TierSelfTestKeyInput } from '../local-executor/tier-self-test';
+import type { ReviewerEvaluateOptions, ReviewerSpec } from '../reviewer/provider';
+import type { SubstrateHandle } from '../substrate/types';
+export interface ReviewerSeatSelfTestConfig {
+    cacheDir: string;
+    /** Where the throwaway view goes (the real copy location, so the test sees the same filesystem and grants). */
+    viewParent: () => Promise<string>;
+    /** Linux bubblewrap tier: the §6.4 key parts (`linuxTierSelfTestKeyParts`). `open` for an open-egress mode. */
+    linuxKeyParts?: (open: boolean) => Promise<Pick<TierSelfTestKeyInput, 'filterSha256' | 'bwrapVersion' | 'setprivPath' | 'bashPath' | 'pastaSha256'>>;
+    readAgentVersion?: (binary: string) => Promise<string>;
+}
+export interface EngagedSelfTestSeat {
+    handle: SubstrateHandle;
+    tier: SelfTestTier;
+    teardown: () => Promise<void>;
+}
+export interface ReviewerSeatSelfTestInput {
+    config: ReviewerSeatSelfTestConfig;
+    /** The real seat's spec (its agent, role, tools and model); the prompt and timeout are replaced. */
+    spec: ReviewerSpec;
+    tier: SelfTestTier;
+    /** Whether this seat is granted the masked original (macOS): part of its argv. */
+    withOriginal: string | undefined;
+    /** One self-test per key at a time; concurrent seats of the same key share it. */
+    inFlight: Map<string, Promise<ReviewerSeatSelfTestVerdict>>;
+    /** Engage a seat for the throwaway view; null when this host would not confine it (the test cannot run). */
+    engage: (args: {
+        taskId: string;
+        workdir: string;
+        bundleDir: string;
+    }) => Promise<EngagedSelfTestSeat | null>;
+    evaluate: (spec: ReviewerSpec, gateId: string, opts: ReviewerEvaluateOptions) => Promise<unknown>;
+    /** Removes the folders the engage made under the self-test's own task id. */
+    removeTaskFolder?: (taskId: string) => Promise<void>;
+}
+export interface ReviewerSeatSelfTestVerdict {
+    pass: boolean;
+    reason?: string;
+}
+/** The seat's argv for the fixed placeholder view, so one task's paths never force a new test. */
+export declare function reviewerArgvTemplate(spec: ReviewerSpec, withOriginal: boolean): string[];
+/** §6.4 — the seat's cached verdict in this tier, or a new run. Never throws for a failing agent. */
+export declare function ensureReviewerSeatSelfTest(input: ReviewerSeatSelfTestInput): Promise<ReviewerSeatSelfTestVerdict>;

package/dist/orchestration-shell/team-decompose.d.ts

@@ -145,6 +145,7 @@ export type DecomposerResult = {
  */
 export declare function readImplementorFinalMessage(plan: ReturnType<typeof buildImplementorArgv>, handle: {
     stdout: () => string;
+    lastMessageCapturePath?: string;
 }, agent: AgentKind, exitCode: number, workdir?: string): Promise<string>;
 /**
  * Build the decomposition prompt fed to the local decomposer on stdin (§3.B).

package/dist/orchestration-shell/types.d.ts

@@ -485,6 +485,27 @@ export interface TaskStartConfirmationState {
         singleFallbackBrief?: string;
     };
 }
+/**
+ * P63 §6.4 — a START refused because its implementor cannot be confined on this machine. The question offers to run
+ * it unconfined THIS ONCE; only an affirmative reply re-issues exactly these start arguments with `allowUnconfined`.
+ */
+export type ConfinementOptInState = {
+    kind?: 'single';
+    reason: string;
+    startArgs: Parameters<import('./quorum-loop').QuorumLoop['startTask']>[0];
+} | {
+    kind: 'team';
+    reason: string;
+    /** The refused launch, re-issued as is (same group key) with `allowUnconfined` on an affirmative reply. */
+    team: {
+        workItems: WorkItemInput[];
+        briefsByTrackIndex: Map<number, string>;
+        groupIdempotencyKey: string;
+        attachments?: ImageAttachment[];
+        attachmentPaths?: string[];
+        retryOf?: string;
+    };
+};
 export interface PendingClarification {
     originalPrompt: string;
     rounds: Array<{
@@ -514,6 +535,8 @@ export interface PendingClarification {
      * anything else cancels) without calling the planner classifier.
      */
     startConfirmation?: TaskStartConfirmationState;
+    /** P63 §6.4 — its own pending kind beside `startConfirmation`: the "run it unconfined this once?" question. */
+    confinementOptIn?: ConfinementOptInState;
 }
 /**
  * A1a #3/#4 — one numbered choice in a `PendingPlannerOffer`. Contract-ready
@@ -1023,6 +1046,7 @@ export type OrchestrationAction = {
     taskId?: string;
     brainstorm?: BrainstormContextMetadata;
     startConfirmation?: TaskStartConfirmationState;
+    confinementOptIn?: ConfinementOptInState;
 } | {
     type: 'EVENT_RECEIVED';
     event: EventStreamEntry;

package/dist/reviewer/provider.d.ts

@@ -51,6 +51,34 @@ export interface ReviewerEvaluateOptions {
      * substrate with) keeps the handle's surface minimal.
      */
     workdir?: string;
+    /**
+     * P63 Slice 2 (§8.2) — present when the gate has a review round: `workdir` is then the seat's private scratch
+     * folder and these are the folders the reviewer reads — the read-only review bundle and, when the seat has one,
+     * the original folder (on macOS masked by the seat's profile). Every provider runs in `workdir` and grants these:
+     * Claude and Antigravity with `--add-dir`; Codex reads them by path under its own read-only sandbox. ABSENT →
+     * each provider's pre-Slice-2 behaviour.
+     */
+    reviewDirs?: {
+        bundleDir: string;
+        originalDir?: string;
+    };
+    /**
+     * P63 Slice 2 (§8.2) — the boundary the reviewer ENGAGER reported for this seat (never inferred from the handle's
+     * presence): `seatbelt` / `docker` tier, and whether that profile gives the seat a read-only view of everything but
+     * its scratch (true for a seat with a review round). The Codex provider rewrites `--sandbox read-only` to
+     * `danger-full-access` ONLY for `{kind: 'seatbelt', readOnlyView: true}` — Codex's own read-only sandbox cannot
+     * start inside Seatbelt (SP-F1 (b)) and the profile is then the boundary; everywhere else `read-only` stays.
+     */
+    boundary?: {
+        kind: 'seatbelt' | 'docker';
+        readOnlyView: boolean;
+    };
+    /**
+     * P63 Slice 2 (§8.5) — called with the reviewer's raw final reply (Claude: the envelope's `.result`; Codex: the
+     * `--output-last-message` text; agy: stdout) once the CLI exited cleanly, before the verdict is classified. The loop
+     * checks the seat's read receipts in it. Never called for a failed run.
+     */
+    onFinalText?: (text: string) => void;
     /**
      * REVIEWER-VERDICT-GEMMA-CLASSIFIER-DESIGN.md (D1) — when present, the provider's
      * `buildVerdict` calls `await classifyVerdict(rawText, ctx)` (local-Gemma verdict

package/dist/reviewer/providers/antigravity.d.ts

@@ -37,7 +37,9 @@ export declare class AntigravityReviewerProvider implements ReviewerProvider {
  * No `--output-format json` exists in agy print mode — stdout is the raw
  * reply text and there is no usage/token envelope (D10: tokens_used null).
  */
-export declare function buildCommand(executable: string, spec: ReviewerSpec, workdir: string): BuiltCommand;
+export declare function buildCommand(executable: string, spec: ReviewerSpec, 
+/** The folders agy's tools may read (`--add-dir` each): the user's folder, or a review round's bundle (+ original). */
+addDirs: string | readonly string[]): BuiltCommand;
 /**
  * Map the raw subprocess outcome into a `ReviewerVerdict` or throw a
  * structured `ReviewerErrorClass`. Exit code first (a crashed CLI's stdout is
@@ -45,4 +47,4 @@ export declare function buildCommand(executable: string, spec: ReviewerSpec, wor
  * unwrap — agy print mode is plain text) fed to the injected classifier
  * (default) or the legacy regex parser (`CODEVIBE_REVIEWER_VERDICT_CLASSIFIER=regex`).
  */
-export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, classifyVerdict?: VerdictClassifier): Promise<ReviewerVerdict>;
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, classifyVerdict?: VerdictClassifier, onFinalText?: (text: string) => void): Promise<ReviewerVerdict>;

package/dist/reviewer/providers/claude.d.ts

@@ -64,11 +64,16 @@ export declare class ClaudeReviewerProvider implements ReviewerProvider {
  * not via this field. On the LEGACY path (`sandboxed === false`, the default)
  * the env is built exactly as before — byte-identical non-regression.
  */
-export declare function buildCommand(executable: string, spec: ReviewerSpec, sandboxed?: boolean): BuiltCommand;
+export declare function buildCommand(executable: string, spec: ReviewerSpec, sandboxed?: boolean, 
+/** P63 Slice 2 (§8.2) — the review round's bundle (+ original): granted with `--add-dir`. */
+reviewDirs?: {
+    bundleDir: string;
+    originalDir?: string;
+}): BuiltCommand;
 /**
  * Map the raw subprocess outcome into a `ReviewerVerdict` or throw a
  * structured `ReviewerErrorClass`. Exit code is checked first — a crashed
  * CLI that happened to print something valid on stdout should still be
  * treated as a spawn failure, not a silently-accepted verdict.
  */
-export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, classifyVerdict?: VerdictClassifier): Promise<ReviewerVerdict>;
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, classifyVerdict?: VerdictClassifier, onFinalText?: (text: string) => void): Promise<ReviewerVerdict>;

package/dist/reviewer/providers/codex.d.ts

@@ -56,7 +56,7 @@ export declare function buildCommand(executable: string, spec: ReviewerSpec, las
  * `claude.ts::buildVerdict` for the shared safety rule (non-zero exit
  * overrides any parseable stdout / file).
  */
-export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, lastMessage: string, classifyVerdict?: VerdictClassifier): Promise<ReviewerVerdict>;
+export declare function buildVerdict(spec: ReviewerSpec, gateId: string, outcome: SubprocessOutcome, lastMessage: string, classifyVerdict?: VerdictClassifier, onFinalText?: (text: string) => void): Promise<ReviewerVerdict>;
 /**
  * Sum `usage.input_tokens + usage.output_tokens` across every
  * `turn.completed` JSONL event in `stdout`. Returns `null` when usage is absent,

package/dist/session-resume/cli-resume.d.ts

@@ -9,6 +9,7 @@ import type { Session } from '../types/session';
 import { type ResumeStart } from './resume-entry';
 import type { ResumeEntryPoint } from './resume-target';
 export interface ResumeShellArgs {
+    predecessorSessionId: string;
     restoredItems: ResumeStart['restoredItems'];
     markerSeq: string;
     header: {

package/dist/substrate/bwrap.d.ts

@@ -1,3 +1,4 @@
+import { type SpawnStartRecord, type SpawnRemovalDeps, type SpawnProcStat } from './spawn-records';
 import { type WorkspaceRootAuthority } from '../local-executor/workspace-authority';
 import type { HostDescendantReap } from '../local-executor/descendant-reaper';
 import type { CommandRunner, EgressFidelity, Substrate, SubstrateHandle, SubstrateProc, SubstrateSpec } from './types';
@@ -33,6 +34,19 @@ export interface BubblewrapDeps {
     uid?: number;
     gid?: number;
     homedir?: string;
+    /**
+     * §6.2 broker tier — the bundled in-tier relay (`dist/substrate/tier-relay.js` of THIS installed package, resolved by
+     * absolute path, never PATH) and the Node binary that runs it inside the tier. Defaults: resolved beside this module;
+     * `process.execPath`.
+     */
+    tierRelayPath?: string;
+    nodePath?: string;
+    /** §6.2 — the boot id the spawn record carries; default `/proc/sys/kernel/random/boot_id`. */
+    readBootId?: () => string;
+    /** §6.2 — the spawn sweep run before a desktop-ended spawn's folder is removed (default: the shipped helper). */
+    runSweep?: SpawnRemovalDeps['runSweep'];
+    /** §6.2 — `/proc/<pid>/stat` reader for the record-time group check (tests inject it). */
+    readProcStat?: (pid: number) => SpawnProcStat | null;
     fsShim?: {
         lstatSync?: (p: string) => {
             isSymbolicLink: () => boolean;
@@ -42,6 +56,53 @@ export interface BubblewrapDeps {
         realpathSync?: (p: string) => string;
     };
 }
+/**
+ * §6.2 — the bundled in-tier relay of this installed package. Bundles live at `dist/index.js` and
+ * `dist/orchestration-shell/cli.js`, so the relay is `dist/substrate/tier-relay.js` from either (and beside this module
+ * when it runs unbundled from source). Never PATH; the first that exists as a regular file.
+ */
+export declare function defaultTierRelayPath(): string | null;
+/** §6.1 / §6.2 — what the handle needs to assemble the bubblewrap argv at exec. */
+export interface BubblewrapExecPlan {
+    /** The chain up to and including the filter path (setpriv … bash step … filter). */
+    chain: readonly string[];
+    /** bwrap arguments before the exec-time segment (system binds … read-only and writable grants). */
+    pre: readonly string[];
+    /** bwrap arguments from `--clearenv` on (env, chdir, `--`, the in-tier relay step if any). */
+    post: readonly string[];
+    /** Toolchain grants (read-only) and the credential files inside them to mask. */
+    grants: readonly string[];
+    grantMasks: readonly string[];
+    /** Folders whose contents are visible (system read-only binds and grants) — a hidden root lies inside one of them. */
+    boundRoots: readonly string[];
+    /** The roots to hide when they lie inside a bound folder: the project, the copy roots. */
+    hideRoots: readonly string[];
+    /** This task's own folders, bound again after the hides with their access mode. */
+    ownFolders: ReadonlyArray<{
+        host: string;
+        target: string;
+        mode: 'ro' | 'rw';
+    }>;
+    /** For the agent binary folder checks. */
+    project: string;
+    copyRoots: readonly string[];
+    hostPath: string;
+}
+/**
+ * Assemble the full argv at exec: the chain, the launch-time bwrap arguments, then — fixed when this spawn starts — the
+ * agent binary's folders (read-only; the run refused when §6.1 forbids them), the `/dev/null` masks over credential
+ * files in every grant and binary folder, the `--tmpfs` hides over the project and the copy roots that lie inside a
+ * bound folder, this task's own folders bound again after the hides, and the rest (env, chdir, the agent).
+ */
+export declare function buildExecArgv(plan: BubblewrapExecPlan, argv: readonly string[]): string[];
+export interface BubblewrapSpawnRecordPlan {
+    stateRoot: string;
+    base: Omit<SpawnStartRecord, 'version' | 'owner' | 'platform' | 'sandboxArgv' | 'pgid' | 'pid' | 'sid' | 'leaderStarttime'>;
+    runSweep?: SpawnRemovalDeps['runSweep'];
+    readProcStat?: (pid: number) => SpawnProcStat | null;
+    /** The folder was handed over (`spec.spawnFolder`): complete the caller's record instead of writing one. */
+    adopted?: boolean;
+}
 export declare class BubblewrapHandle implements SubstrateHandle {
     readonly id: string;
     readonly egressFidelity: EgressFidelity;
@@ -59,6 +120,14 @@ export declare class BubblewrapHandle implements SubstrateHandle {
     private executed;
     private inFlightExec;
     private teardownPromise;
+    /** §6.2 broker tier: the desktop's own broker address the relay channel dials, and the channel once exec'd. */
+    private readonly relayBroker?;
+    private relay;
+    private readonly execPlan?;
+    /** §6.2 — the spawn record: written before the spawn, the group added after, removed with the folder. */
+    private readonly spawnRecord?;
+    private recordFile;
+    private endedByDesktop;
     constructor(opts: {
         id: string;
         runner: CommandRunner;
@@ -68,6 +137,17 @@ export declare class BubblewrapHandle implements SubstrateHandle {
         workdir: string;
         workdirAuthority?: WorkspaceRootAuthority;
         scratchAuthority?: WorkspaceRootAuthority;
+        egressFidelity?: EgressFidelity;
+        relayBroker?: {
+            host: string;
+            port: number;
+        };
+        /**
+         * §6.1 / §6.2 — the exec-time segment: the bubblewrap argv is split around it (everything before `--clearenv`,
+         * and from `--clearenv` on), because the agent binary's folders are known only from argv[0].
+         */
+        execPlan?: BubblewrapExecPlan;
+        spawnRecord?: BubblewrapSpawnRecordPlan;
     });
     exec(argv: string[], opts: {
         stdinTty: boolean;
@@ -88,6 +168,11 @@ export declare class BubblewrapSubstrate implements Substrate {
     private readonly gid;
     private readonly homedir;
     private readonly fsShim?;
+    private readonly tierRelayPath?;
+    private readonly nodePath;
+    private readonly readBootId;
+    private readonly runSweep?;
+    private readonly readProcStat?;
     constructor(deps?: BubblewrapDeps);
     launch(spec: SubstrateSpec): Promise<SubstrateHandle>;
 }

package/dist/substrate/command-runner.d.ts

@@ -21,5 +21,6 @@ export declare class ChildProcessCommandRunner implements CommandRunner {
         cwdAuthority?: WorkspaceRootAuthority;
         launchPathAuthorities?: readonly WorkspaceRootAuthority[];
         descendantReap?: HostDescendantReap;
+        relayChannel?: boolean;
     }): RunnerProc;
 }

package/dist/substrate/docker.d.ts

@@ -1,8 +1,17 @@
 import { type ForwarderFactory } from './forwarder';
 import type { CommandRunner, EgressObservationHook, Substrate, SubstrateHandle, SubstrateSpec } from './types';
 import { type WorkspaceRootAuthority, type WorkspaceRootLease } from '../local-executor/workspace-authority';
+/**
+ * The base image the agent runs inside. **[ASM]** the exact image is an
+ * operational detail (any image carrying the agent CLI + Node); pinned here as a
+ * default so the argv is deterministic for the conformance test. Overridable
+ * via {@link DockerSubstrateDeps.image}.
+ */
+export declare const DEFAULT_IMAGE = "codevibe/substrate:rung1";
 /** Where, inside the container, the worktree is mounted (the agent's cwd/home). */
 export declare const CONTAINER_WORKDIR = "/workspace";
+/** P63 Slice 2 (§8.2) — where a spawn's capture dir is mounted read-write inside the container. */
+export declare const CONTAINER_CAPTURE_DIR = "/codevibe-capture";
 /** Injectable deps — default-wired to the real runtime; stubbed in unit tests. */
 export interface DockerSubstrateDeps {
     /** Process layer (default: `node:child_process`). Stub in unit tests. */
@@ -77,6 +86,18 @@ export declare function buildRunArgv(args: {
         hostDir: string;
         sandboxDir: string;
     };
+    /**
+     * P63 Slice 2 (§8.2) — a reviewer seat's review bundle, mounted READ-ONLY at the same absolute path it has on the
+     * host (so the prompt names one path on every backend). Bundle only — never the user's folder.
+     */
+    reviewBundleDir?: string;
+    /**
+     * P63 Slice 2 (§8.2) — `false` mounts the workdir READ-ONLY (`:ro`): the plan-mode / review read-only view, which
+     * Seatbelt enforces with its trailing write deny. Absent / `true` → the shipped read-write mount.
+     */
+    writableWorkdir?: boolean;
+    /** P63 Slice 2 (§8.2) — the spawn's capture dir, mounted read-write at {@link CONTAINER_CAPTURE_DIR}. */
+    captureDir?: string;
 }): string[];
 /**
  * `docker exec [-i] <name> env -i <sanitizedEnv> <argv...>` — run the agent

package/dist/substrate/grant-rule.d.ts

@@ -0,0 +1,71 @@
+/** argv[0] on the HOST PATH (the agent binary the tier will run), or null. */
+export declare function resolveOnHostPath(cmd: string, hostPath?: string): string | null;
+/** Linux: the XDG user folders, from `~/.config/user-dirs.dirs` (what `xdg-user-dir` reads). */
+export declare function xdgUserDirs(homedir: string): string[];
+export interface GrantRuleInput {
+    platform: 'darwin' | 'linux';
+    pathEntries: readonly string[];
+    homedir: string;
+    /** The user's real project folder. */
+    project: string;
+    /** CodeVibe copy-location roots (§5.1). */
+    copyRoots: readonly string[];
+    /** `~/.codevibe`. */
+    codevibeDir: string;
+    /** `$TMPDIR` (and its realpath is added by the rule). */
+    tmpdir?: string;
+    xdgRuntimeDir?: string;
+    /** Linux: the XDG user folders as `xdg-user-dir` reports them. */
+    xdgUserDirs?: readonly string[];
+    isWsl?: boolean;
+    /** Folders the tier already reads (system dirs): entries there need no grant but stay on the sandbox PATH. */
+    readableSystemDirs: readonly string[];
+    /** The shipped default PATH appended after the user's granted entries. */
+    defaultPath: readonly string[];
+    realpath: (p: string) => string | null;
+    isDirectory: (p: string) => boolean;
+}
+export interface GrantRuleResult {
+    /** Read-only grants (deduplicated, in first-use order). */
+    grants: string[];
+    /** Refused candidates with the reason, for the task log. */
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** The sandbox PATH entries, in the user's order, then the shipped default. */
+    sandboxPath: string[];
+}
+export declare function computeToolchainGrants(input: GrantRuleInput): GrantRuleResult;
+/**
+ * §6.1 — whether a file inside a granted root is credential-named (compared without regard to letter case). `relDir`
+ * is its directory relative to the grant root ('' at the root): `config.json` is hidden only at the root, and
+ * `.docker/config.json` anywhere.
+ */
+export declare function isCredentialName(name: string, relDir: string): boolean;
+export interface GrantScanResult {
+    /** Credential-named files to mask (`--ro-bind /dev/null <file>`). */
+    masks: string[];
+    /** A Unix socket found inside (refuses the grant / the run on Linux). */
+    socket: string | null;
+    /** The walk exceeded its bounds (200,000 entries or 10 s). */
+    exceeded: boolean;
+}
+/**
+ * §6.1 (Linux) — walk a granted root or an agent binary folder with the credential-name test, for every spawn when its
+ * argv is built: bounded (200,000 entries, 10 s), symlinks never followed, sockets reported.
+ */
+export declare function scanGrantRoot(root: string, bounds?: {
+    maxEntries: number;
+    maxMs: number;
+}, now?: () => number): GrantScanResult;
+/**
+ * §6.1 — the agent binary's folders (the directory of the resolved argv[0] and of its realpath): granted read-only,
+ * not by the toolchain rule; the RUN is refused when one lies inside the project or a copy root, or equals, contains or
+ * lies inside a temporary or runtime folder.
+ */
+export declare function agentBinaryFolders(resolvedArgv0: string, realArgv0: string, input: Pick<GrantRuleInput, 'project' | 'copyRoots' | 'tmpdir' | 'xdgRuntimeDir' | 'realpath' | 'homedir' | 'pathEntries' | 'platform' | 'codevibeDir' | 'readableSystemDirs' | 'defaultPath' | 'isDirectory'>): {
+    folders: string[];
+} | {
+    refusal: string;
+};