@quantiya/codevibe-core 2.0.92 → 2.0.93

package/dist/substrate/pasta-isolation-check.d.ts

@@ -0,0 +1,60 @@
+export interface ProbeTarget {
+    host: string;
+    port: number;
+    /** What the target is: a loopback address or a gateway, at a host listener's port. */
+    kind: 'loopback' | 'gateway';
+    /** The host listener the port belongs to. */
+    listener: string;
+}
+export interface ProbeOutcome extends ProbeTarget {
+    connected: boolean;
+}
+export interface IsolationEvidence {
+    probes: ProbeOutcome[];
+    /** Connections each host listener recorded, by listener name. */
+    listenerConnections: Record<string, number>;
+}
+export interface IsolationVerdict {
+    pass: boolean;
+    reasons: string[];
+}
+/** The exact §6.2 `-T none` rule, as a pure function of what the probe and the listeners observed. */
+export declare function evaluateIsolation(e: IsolationEvidence): IsolationVerdict;
+/**
+ * The host's IPv6 state, stable fields only (S1R15-N2): each `ip -6 route` entry's destination, gateway and device,
+ * each `inet6` address with its prefix length and scope — not lifetimes / expiry counters, not temporary addresses.
+ */
+export declare function ipv6StateDigest(routeText: string, addrText: string): string;
+export declare function isolationCacheKey(pastaSha256: string, ipv6Digest: string): string;
+/** The probe, run with Node inside the pasta namespace. argv[1] = JSON of the host listeners' ports to try. */
+export declare const ISOLATION_PROBE_SOURCE: string;
+export interface RunIsolationCheckOptions {
+    pastaPath?: string;
+    nodePath?: string;
+    desktopPid?: number;
+    timeoutMs?: number;
+    /** Evidence controls only (e.g. the design's run without `--no-map-gw`, which must fail): rewrites the pasta argv. */
+    mutatePastaArgv?: (argv: string[]) => string[];
+}
+/** Runs the check on this host (Linux, pasta installed) and returns the evidence and verdict. */
+/**
+ * F-PASTA-SELINUX-STDIO: a probe that exits 0 having printed nothing did not reach its verdict. On SELinux enforcing the
+ * passt policy closes a socket inherited across pasta's domain transition, and Node's child stdio is a socket, so the child
+ * runs with no stdin, stdout or stderr. The installer loads the one rule that allows it.
+ */
+export declare function parseIsolationProbeOutput(stdout: string): ProbeOutcome[];
+export declare function runIsolationCheck(opts?: RunIsolationCheckOptions): Promise<{
+    evidence: IsolationEvidence;
+    verdict: IsolationVerdict;
+}>;
+export interface IsolationCacheEntry {
+    key: string;
+    pastaSha256: string;
+    ipv6Digest: string;
+    pass: boolean;
+    reasons: string[];
+    checkedAt: string;
+}
+/** Cached results beside the §6.4 tier self-test results: `<dir>/pasta-isolation-<key>.json`. */
+export declare function readIsolationCache(dir: string, key: string): IsolationCacheEntry | null;
+export declare function writeIsolationCache(dir: string, entry: IsolationCacheEntry): void;

package/dist/substrate/pasta.d.ts

@@ -28,6 +28,14 @@ export declare function buildSetprivPrefix(desktopPid?: number): string[];
  * Closes all fds above 2, opens filter as fd 9, and execs bwrap with --seccomp 9.
  */
 export declare const IN_TIER_CLEANUP_PASTA = "for f in /proc/self/fd/*; do n=${f##*/}; case $n in 0|1|2) ;; *) eval \"exec $n>&-\" 2>/dev/null;; esac; done; exec 9<\"$0\" && exec bwrap --seccomp 9 \"$@\"";
+/**
+ * §6.2 broker tier — the in-tier command run by bubblewrap: start the relay on the inherited fd 3, wait (bounded) for
+ * its ready file, close fd 3, then exec the agent, so the agent holds exactly fds 0–2 whatever was inherited.
+ * argv after the script: <node> <relay script> <port> <ready file> <agent argv…>. Exit 98: the relay never got ready.
+ */
+export declare const IN_TIER_RELAY_STEP: string;
+/** Where the relay's ready file lives inside the tier (the spawn's private `/tmp`). */
+export declare const IN_TIER_RELAY_READY_FILE = "/tmp/.codevibe-relay-ready";
 /**
  * In-tier bash step for the isolated broker tier (no pasta):
  * Keeps fds 0-3 (fd 3 is the broker relay socketpair), closes fds above 3,

package/dist/substrate/relay-channel.d.ts

@@ -0,0 +1,80 @@
+import net from 'node:net';
+import type { Duplex } from 'node:stream';
+export declare const RELAY_MAX_FRAME_BYTES = 65536;
+export declare const RELAY_MAX_STREAM_ID: number;
+export declare const RELAY_MAX_OWNED_SOCKETS = 64;
+export declare const RELAY_MAX_OUTBOUND_BYTES: number;
+export declare const RELAY_MAX_STREAM_BUFFER_BYTES: number;
+export declare const RELAY_HALF_CLOSED_CAP = 256;
+export declare const RELAY_PARTIAL_FRAME_DEADLINE_MS = 5000;
+export declare const RELAY_LINGER_MS = 5000;
+export interface RelayChannelOptions {
+    /** Opens the desktop's OWN connection to its OWN broker — the only address this channel ever dials. */
+    connectBroker: () => net.Socket;
+    maxOutboundBytes?: number;
+    partialFrameDeadlineMs?: number;
+    lingerMs?: number;
+    onClose?: (reason: string | null) => void;
+}
+export interface RelayChannelStats {
+    streams: number;
+    ownedHighWater: number;
+    owned: number;
+    halfClosedFrames: number;
+    halfClosedSetSize: number;
+    relayClosesReceived: number;
+    droppedForRelayClosed: number;
+    pausedToBroker: number;
+    resumedOnClose: number;
+    protocolErrors: number;
+    outboundHighWater: number;
+    channelDrainListeners: number;
+    closeReason: string | null;
+}
+export declare class RelayChannel {
+    private readonly channel;
+    private readonly connectBroker;
+    private readonly maxOutbound;
+    private readonly partialDeadlineMs;
+    private readonly lingerMs;
+    private readonly onClose?;
+    private buffer;
+    private highestId;
+    private readonly streams;
+    /** Ids the desktop closed: late frames discarded; insertion-ordered for oldest-first eviction. */
+    private readonly halfClosed;
+    /**
+     * Recently relay-closed ids, for the refusal's reason only: every id at or below the highest that is neither live nor
+     * half-closed is refused anyway (ids strictly increase), so this stays bounded (oldest-first, 256).
+     */
+    private readonly relayClosedIds;
+    /** Every broker socket the desktop owns, from connect() until it actually closes. */
+    private readonly owned;
+    /** Broker sockets paused because the channel's outbound side is full; resumed by the one channel drain listener. */
+    private readonly pausedForChannel;
+    /** The stream whose broker write filled up: the channel is paused until it drains or closes. */
+    private pauseOwner;
+    private partialTimer;
+    private closed;
+    private readonly stats;
+    constructor(channel: Duplex, opts: RelayChannelOptions);
+    snapshot(): RelayChannelStats;
+    /** Close the channel and every broker socket it owns (teardown, or a protocol error with its reason). */
+    close(reason: string | null): void;
+    private onChannelData;
+    private rememberRelayClosed;
+    private parse;
+    private onFrame;
+    private openStream;
+    private toBroker;
+    private onBrokerDrain;
+    private releasePause;
+    private relayClose;
+    private fromBroker;
+    private sendFrame;
+    private onChannelDrain;
+    private brokerEnded;
+    private brokerClosed;
+    private armPartialDeadline;
+    private clearPartialDeadline;
+}

package/dist/substrate/review-mask.d.ts

@@ -0,0 +1,20 @@
+/**
+ * P63 Slice 2 — §8.2 the macOS masked original (W5).
+ *
+ * A macOS reviewer seat may read the user's folder for context, read-only, with these kinds made unreadable by
+ * trailing Seatbelt denies (last match wins, as for `<workdir>/.git` and `~/.codevibe` in `sandbox-exec.ts`):
+ * secrets (`.env`, `.env.*`, `id_*`, `.aws/credentials`, `*.pem`, `*.key`, `*.crt`, `*.pfx`, `*.p12`, `*.keystore`),
+ * credential configs (`.npmrc`, `.pypirc`, `.netrc`, `.yarnrc.yml`), CodeVibe-internal names (`.codevibe*`,
+ * `.agent-worktrees`, `.review-worktrees`, `.hard-gate`, `*-home`), audio and video by extension, and `<original>/.git`.
+ * They are PATTERNS anchored at the regex-escaped original — so they match at any depth and also cover files created
+ * after the profile was written — with every letter written per character (`[mM][pP]4`) for case-insensitive volumes.
+ * Every changed file whose bytes the bundle withholds gets a per-file `literal` deny; more than
+ * {@link MAX_WITHHELD_LITERALS} of them means no masked original at all — the seat gets the bundle only, as on Linux.
+ */
+/** §8.2 / SP-A4j: 1,000 literals added ~0.4 s to profile start; 5,000 ~8.8 s; 20,000 never started. */
+export declare const MAX_WITHHELD_LITERALS = 1000;
+/**
+ * The trailing deny lines masking `originalDir` for a reviewer, or null when `changedWithheld` (paths relative to the
+ * original) exceeds {@link MAX_WITHHELD_LITERALS} — the caller then grants the bundle only.
+ */
+export declare function reviewMaskDenyLines(originalDir: string, changedWithheld: readonly string[]): string[] | null;

package/dist/substrate/sandbox-exec.d.ts

@@ -1,4 +1,5 @@
 import type { CommandRunner, Substrate, SubstrateHandle, SubstrateSpec } from './types';
+import { type SeatbeltOwnFolder } from './seatbelt-grants';
 /** Injectable deps — default-wired to the real runtime; stubbed in unit tests. */
 export interface SandboxExecDeps {
     /** Process layer (default: `node:child_process`). */
@@ -66,6 +67,33 @@ export interface SandboxExecDeps {
  * @param execPath  the Node interpreter to grant read on (default
  *                  `process.execPath`); injectable for deterministic tests.
  */
+/** P63 §6.1 — what a Seatbelt profile needs for the grant rule, the credential block and the hide block. */
+export interface SeatbeltProfileWorkspace {
+    project: string;
+    copyRoots: string[];
+    ownFolders: SeatbeltOwnFolder[];
+    toolchainGrants: string[];
+    nodeGrants: string[];
+}
+/**
+ * The shipped trailing denies, re-emitted after every hide block (in the profile and in the exec-time append): the
+ * workdir's `.git`, `~/.codevibe`, the reviewer's bundle/original write denies and masks, the plan-mode write deny and
+ * the audit dir.
+ */
+export declare function seatbeltTrailingDenyLines(opts: {
+    workdir: string;
+    homedir: string;
+    reviewGrants: {
+        bundleDir: string;
+        maskedOriginal?: {
+            dir: string;
+            changedWithheld: readonly string[];
+        };
+    } | null;
+    maskLines: string[] | null;
+    writableWorkdir: boolean;
+    auditDir: string | null;
+}): string[];
 export declare function buildSeatbeltProfile(workdir: string, execPath?: string, 
 /**
  * CP-7 PART D — extra READ-ONLY dirs to grant (the apiKeyHelper bootstrap dir
@@ -116,7 +144,24 @@ networkPosture?: 'loopback' | 'open',
  * When false, denies writes to the worktree, establishing a hard read-only boundary (R5-F1).
  * Default true (writes permitted to workdir).
  */
-writableWorkdir?: boolean): string;
+writableWorkdir?: boolean, 
+/**
+ * P63 Slice 2 (§8.2) — a reviewer seat's read-only grants: the review bundle, and (macOS) the user's original folder
+ * masked by {@link reviewMaskDenyLines}. The seat's `workdir` is its private scratch. When the mask cannot be built
+ * (more than 1,000 changed withheld files) the original is not granted at all — bundle only, as on Linux.
+ */
+reviewGrants?: {
+    bundleDir: string;
+    maskedOriginal?: {
+        dir: string;
+        changedWithheld: readonly string[];
+    };
+} | null, 
+/**
+ * P63 §6.1 — the read-grant rule, credential block and hide block. Absent → the pre-Slice-2 profile (unit stubs).
+ * `toolchainGrants` are already through the grant rule (`seatbeltToolchainGrants`).
+ */
+workspace?: SeatbeltProfileWorkspace | null): string;
 /**
  * A5 macOS `sandbox-exec` substrate (`egressFidelity: 'coarse'`). See file
  * header. NOT the default — the LE selects it as the macOS Docker-fallback.
@@ -127,4 +172,6 @@ export declare class SandboxExecSubstrate implements Substrate {
     private readonly platform;
     constructor(deps?: SandboxExecDeps);
     launch(spec: SubstrateSpec): Promise<SubstrateHandle>;
+    /** P63 §6.1 — the seat's own folders, the toolchain and interpreter grants (through the rule), and the PATH. */
+    private seatbeltWorkspace;
 }

package/dist/substrate/seatbelt-grants.d.ts

@@ -0,0 +1,46 @@
+import { type GrantRuleInput } from './grant-rule';
+/** Regex-escapes a literal path for a Seatbelt `(regex #"…")` (POSIX ERE metacharacters). */
+export declare function seatbeltRegexEscape(literal: string): string;
+/** A literal name as a case-independent pattern: letters become `[xX]`, regex metacharacters are escaped. */
+export declare function caseFree(literal: string): string;
+/** §6.1 — the credential names hidden inside granted roots, as case-free pattern fragments for one path component. */
+export declare function credentialNamePatterns(): {
+    anyDepth: string[];
+    rootOnly: string[];
+    pemAllow: string[];
+};
+/**
+ * The credential block for these roots: denies of every credential name at any depth (and `.docker/config.json`
+ * anywhere, `config.json` at the root), then the CA-bundle re-allows (read only).
+ */
+export declare function credentialBlockLines(roots: readonly string[]): string[];
+export interface SeatbeltOwnFolder {
+    dir: string;
+    mode: 'read' | 'read-write';
+}
+/** The hide block: deny the project and every copy root, re-allow this seat's own folders, metadata re-allows. */
+export declare function hideBlockLines(opts: {
+    project: string;
+    copyRoots: readonly string[];
+    ownFolders: readonly SeatbeltOwnFolder[];
+}): string[];
+/**
+ * §6.1 (S1R8-N3) — true when some component of `p` has a sibling whose name differs only in letter case (possible only
+ * on a case-sensitive volume, where a Seatbelt grant of one would also cover the other).
+ */
+export declare function hasCaseVariantSibling(p: string, readdir?: (dir: string) => string[]): boolean;
+/**
+ * §6.1 "Letter case" for CodeVibe's own folders and a reviewer's original (S2-C2, Stage 2 R1): the reason to refuse a
+ * grant, or null. Unlike a toolchain entry, which can simply be left out, these folders cannot be dropped, so a path
+ * whose case cannot be checked (a parent that cannot be listed) is refused as well.
+ */
+export declare function ownFolderCaseRefusal(p: string, readdir?: (dir: string) => string[]): string | null;
+/** The macOS toolchain grants: the shared rule, then the case-variant refusal. */
+export declare function seatbeltToolchainGrants(input: Omit<GrantRuleInput, 'platform'>, caseCheck?: (p: string) => boolean): {
+    grants: string[];
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+    sandboxPath: string[];
+};

package/dist/substrate/spawn-records.d.ts

@@ -0,0 +1,95 @@
+import { type ProcessIdentity } from '../local-executor/process-identity';
+import { type SpawnSweepRecord, type SpawnSweepResult } from '../local-executor/spawn-sweep';
+export declare const SPAWN_RECORD_FILE_RE: RegExp;
+export type SpawnFolderKind = 'spawn' | 'agy-home' | 'advisory';
+export interface SpawnStartRecord {
+    version: 1;
+    spawnId: string;
+    /** null for an advisory turn. */
+    taskId: string | null;
+    kind: SpawnFolderKind;
+    /** The spawn's folder, by exact path. */
+    folder: string;
+    /** The copy location the folder lies under (one of the §5.1 copy roots). */
+    copyRoot: string;
+    platform: NodeJS.Platform;
+    /** Linux only — `/proc/sys/kernel/random/boot_id`. */
+    bootId?: string;
+    /** Linux only — the exact `bwrap …` vector the chain execs. */
+    sandboxArgv?: string[];
+    owner: ProcessIdentity;
+    /** Added once `spawn()` returned (the chain is detached, so pid = pgid = sid). */
+    pgid?: number;
+    pid?: number;
+    sid?: number;
+    leaderStarttime?: string;
+}
+/** The record's own path: the task's state directory, or `advisory/` for an advisory turn. */
+export declare function spawnRecordPath(stateRoot: string, taskId: string | null, spawnId: string): string;
+/** The §5.1 folder for a spawn — the only two forms (three with macOS agy-home) the sweep accepts (S1R13-L1). */
+export declare function spawnFolderPath(copyRoot: string, taskId: string | null, spawnId: string, kind: SpawnFolderKind): string;
+/** The filter beside the record (Linux): `filter-<spawn>.bpf` in the same state directory. */
+export declare function spawnFilterPath(stateRoot: string, taskId: string | null, spawnId: string): string;
+/**
+ * The spawn's durable start record, before the spawn: exclusive, mode 0600, synced with its directory. The folder
+ * must be one of the exact §5.1 forms for this record's task and spawn.
+ */
+export declare function writeSpawnStartRecord(stateRoot: string, input: Omit<SpawnStartRecord, 'version' | 'owner' | 'platform'> & {
+    owner?: ProcessIdentity;
+    platform?: NodeJS.Platform;
+}): Promise<string>;
+/**
+ * A tier that adopts a caller-seeded folder (`SubstrateSpec.spawnFolder`) completes the caller's start record with the
+ * exact sandbox argv and boot id, before its spawn, instead of writing a second record for the same spawn. The record
+ * must already name this spawn, task, kind and folder.
+ */
+export declare function completeAdoptedSpawnRecord(stateRoot: string, base: Pick<SpawnStartRecord, 'spawnId' | 'taskId' | 'kind' | 'folder' | 'copyRoot'>, fields: {
+    sandboxArgv: string[];
+    bootId: string;
+    platform: NodeJS.Platform;
+}): Promise<string>;
+export declare function readSpawnRecord(file: string): Promise<SpawnStartRecord | null>;
+export interface SpawnProcStat {
+    pgrp: number;
+    session: number;
+    starttime: string;
+}
+/** Linux `/proc/<pid>/stat`: fields 5 (pgrp), 6 (session) and 22 (starttime), or null. */
+export declare function readSpawnProcStat(pid: number): SpawnProcStat | null;
+/**
+ * As soon as `spawn()` returned (§6.2, S1R20-F3): the chain is started detached, so it should be its own session and
+ * group. The record-time invariant (S1R39-F8): only when the spawn's pgid AND sid both equal its own pid is the group
+ * recorded (with the leader's starttime); otherwise the record carries NO group and the sweep resolves the spawn by
+ * its sandbox argv alone. A mis-read is fail-safe — a group holding no argv witness never opens.
+ */
+export declare function recordSpawnGroup(file: string, pid: number, stat: SpawnProcStat | null): Promise<boolean>;
+/**
+ * The helper's stdin record (§6.2). The folder needle is the exact §5.1 form WITH its trailing separator
+ * (`…/<task>/spawn/<spawn>/`, `…/advisory-<spawn>/`): the helper refuses any other form, and the separator is what keeps
+ * spawn `abc`'s needle from matching a command line that names spawn `abcd`.
+ */
+export declare function sweepRecordOf(record: SpawnStartRecord): SpawnSweepRecord;
+export interface SpawnRemovalDeps {
+    runSweep?: (record: SpawnSweepRecord, platform: NodeJS.Platform) => Promise<SpawnSweepResult>;
+}
+/**
+ * Ends one recorded spawn's folders: on Linux the spawn sweep first (when `sweep` is set — the spawn did not end by
+ * the agent's own exit, or the record is an orphan), then the folder, the filter and the record, by exact path.
+ * Returns false (and removes nothing) when the sweep reports anything still owned or a blocker.
+ */
+export declare function removeRecordedSpawn(stateRoot: string, record: SpawnStartRecord, opts: {
+    sweep: boolean;
+} & SpawnRemovalDeps): Promise<boolean>;
+export interface OrphanSpawnSweepResult {
+    removed: string[];
+    /** Tasks whose spawn could not be cleared — the caller keeps their state (the next start retries). */
+    blockedTaskIds: Set<string>;
+    retained: string[];
+}
+/**
+ * Desktop start: every record whose owning desktop no longer runs is an orphan — swept (Linux) and removed by exact
+ * path. A record of a live desktop (another CodeVibe session) is left alone, and so is its task.
+ */
+export declare function sweepOrphanSpawnRecords(stateRoot: string, deps?: SpawnRemovalDeps & {
+    isOwnerAlive?: (owner: ProcessIdentity) => Promise<boolean>;
+}): Promise<OrphanSpawnSweepResult>;

package/dist/substrate/tier-relay-main.d.ts

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

package/dist/substrate/tier-relay.d.ts

@@ -0,0 +1,7 @@
+import net from 'node:net';
+export declare function runTierRelay(opts: {
+    channelFd: number;
+    port: number;
+    readyFile: string;
+    host?: string;
+}): net.Server;

package/dist/substrate/tier-relay.js

@@ -0,0 +1,3 @@
+"use strict";var R=Object.create;var E=Object.defineProperty;var U=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var M=Object.getPrototypeOf,_=Object.prototype.hasOwnProperty;var N=(n,r,s,c)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of A(r))!_.call(n,t)&&t!==s&&E(n,t,{get:()=>r[t],enumerable:!(c=U(r,t))||c.enumerable});return n};var I=(n,r,s)=>(s=n!=null?R(M(n)):{},N(r||!n||!n.__esModule?E(s,"default",{value:n,enumerable:!0}):s,n));var k=I(require("node:fs")),b=I(require("node:net")),B=65536,f=8;function x(n){let r=new b.default.Socket({fd:n.channelFd,readable:!0,writable:!0}),s=new Map,c=1,t=Buffer.alloc(0),a=null,y=new Set,v=(e,o,i)=>{let l=Buffer.alloc(f);l.writeUInt32BE(o.length,0),l.writeUInt32BE(e,4),!r.write(o.length>0?Buffer.concat([l,o]):l)&&i&&!i.destroyed&&(i.pause(),y.add(i))};r.on("drain",()=>{for(let e of y)e.destroyed||e.resume();y.clear()});let F=()=>{for(;t.length>=f;){let e=t.readUInt32BE(0),o=t.readUInt32BE(4);if(e>B)return d();if(t.length<f+e)return;let i=t.subarray(f,f+e);t=t.subarray(f+e);let l=s.get(o);if(l){if(e===0){s.delete(o),l.end(),a===l&&h();continue}!l.write(i)&&a===null&&(a=l,r.pause())}}},h=()=>{a=null,r.resume(),F()};r.on("data",e=>{t=t.length===0?e:Buffer.concat([t,e]),F()});let p=b.default.createServer(e=>{let o=0,i=()=>(o===0&&(o=c++,s.set(o,e)),o);e.on("data",m=>{let S=i();if(s.has(S))for(let u=0;u<m.length;u+=B)v(S,m.subarray(u,u+B),e)}),e.on("drain",()=>{a===e&&h()});let l=()=>{o!==0&&(s.get(o)===e&&(s.delete(o),v(o,Buffer.alloc(0),null)),a===e&&h())};e.on("end",l),e.on("close",l),e.on("error",()=>e.destroy())}),d=()=>{for(let e of s.values())e.destroy();s.clear(),p.close(),r.destroy()};return r.on("end",d),r.on("close",d),r.on("error",d),p.listen(n.port,n.host??"127.0.0.1",()=>{k.writeFileSync(n.readyFile,`${process.pid}
+`,{mode:384,flag:"wx"})}),p}var g=Number(process.argv[2]),w=process.argv[3];(!Number.isInteger(g)||g<=0||g>65535||typeof w!="string"||w.length===0)&&(process.stderr.write(`tier-relay: usage: tier-relay <port> <ready file>
+`),process.exit(2));x({channelFd:3,port:g,readyFile:w});

package/dist/substrate/types.d.ts

@@ -32,6 +32,19 @@ export interface SubstrateSpec {
     workdir: string;
     /** Exact host workdir incarnation for task-scoped mutable launches. */
     workdirAuthority?: WorkspaceRootAuthority;
+    /**
+     * P63 Slice 2 (§8.2) — a reviewer seat's read-only grants; `workdir` is then the seat's PRIVATE scratch. The review
+     * bundle is granted read-only on every backend; `maskedOriginal` (the user's folder for context, with the §8.2
+     * secret / credential / internal / audio-video kinds and the changed withheld files denied) on macOS only — Linux
+     * and Docker seats get the bundle only (a live read-only bind cannot hide secrets created later).
+     */
+    reviewGrants?: {
+        bundleDir: string;
+        maskedOriginal?: {
+            dir: string;
+            changedWithheld: readonly string[];
+        };
+    };
     /**
      * Where the broker actually listens on the HOST (e.g.
      * `127.0.0.1:<ephemeral>`).
@@ -60,6 +73,15 @@ export interface SubstrateSpec {
      * further.
      */
     sanitizedEnv: Readonly<Record<string, string>>;
+    /**
+     * P63 §5.1 (Linux) — a spawn folder the caller already created by exact path (`<copy location>/<task>/spawn/<spawn>/`
+     * or `<copy location>/advisory-<spawn>/`) and seeded (agy's token copies in `home/`). The bubblewrap tier adopts it:
+     * adds `tmp/`, records it (§6.2) and removes the whole folder at teardown. Absent → the tier creates its own.
+     */
+    spawnFolder?: {
+        dir: string;
+        spawnId: string;
+    };
     /**
      * CP-7 PART D (§3.3 agy-R3 bootstrap) — OPTIONAL, additive. The host
      * directory holding the agent's `apiKeyHelper` script + the broker-token
@@ -139,6 +161,23 @@ export interface SubstrateSpec {
      * Default true (writes permitted to workdir).
      */
     writableWorkdir?: boolean;
+    /**
+     * P63 Slice 2 (§8.2) — the spawn's capture directory (`<task folder>/capture/<spawn>/`): granted READ-WRITE beside a
+     * read-only view so a plan-mode Codex run can still write its `--output-last-message` file. Seatbelt: an extra write
+     * dir; bubblewrap: `--bind` at the same path; Docker: mounted at `/codevibe-capture`. Task-owned, so it outlives the
+     * substrate teardown until the plan is read.
+     */
+    captureDir?: string;
+    /**
+     * WORKSPACE-HARDENING-DESIGN §6.1 / §6.2 — the user's real project root and CodeVibe's copy-location roots. The
+     * Linux tier grants toolchains by the §6.1 rule (never covering these), lays a `--tmpfs` hide over each one that lies
+     * inside a bound folder (a project under `/opt`), and binds this task's own folders again after the hides. Absent →
+     * no toolchain grants and no hides (the legacy launch).
+     */
+    workspaceRoots?: {
+        project: string;
+        copyRoots: readonly string[];
+    };
 }
 /**
  * A structural `ChildProcess` subset. The LE widens its internal child
@@ -240,7 +279,13 @@ export interface CommandResult {
  * `sandbox-exec <argv>` — structurally a {@link SubstrateProc} (so the LE's
  * `wireLifecycle` consumes it) plus nothing more.
  */
-export type RunnerProc = SubstrateProc;
+export type RunnerProc = SubstrateProc & {
+    /**
+     * §6.2 broker tier — the desktop's end of the connected AF_UNIX stream socketpair the child holds as fd 3 (Node's
+     * `stdio: 'pipe'` on Unix; never an IPC channel). Present only when `spawnLong` was asked for `relayChannel`.
+     */
+    relayChannel?: import('node:stream').Duplex;
+};
 /**
  * The injected process layer for the A1/A5 impls (§3.1). `run` is the
  * await-to-completion form (network create/rm, container run/kill — the impl
@@ -288,5 +333,7 @@ export interface CommandRunner {
         launchPathAuthorities?: readonly WorkspaceRootAuthority[];
         /** P46b ID-31 — the descendant sweep the process host runs if the desktop dies first. */
         descendantReap?: HostDescendantReap;
+        /** §6.2 broker tier — give the child a fourth stdio entry: the relay channel socketpair as its fd 3. */
+        relayChannel?: boolean;
     }): RunnerProc;
 }

package/dist/substrate-launch/engage-substrate.d.ts

@@ -3,7 +3,7 @@ import type { BrokerDeps } from "../credential-broker/broker";
 import type { ModelGatewayBroker, UpstreamClient, VendorProvider } from "../credential-broker/types";
 import type { ProcessRole } from "../local-executor/types";
 import type { WorkspaceRootAuthority } from "../local-executor/workspace-authority";
-import type { SubstrateHandle } from "../substrate/types";
+import type { SubstrateHandle, SubstrateSpec } from "../substrate/types";
 import { type FallbackLadderDeps } from "./fallback-ladder";
 /** Map the implementor agent to the broker provider (Claude+Codex only, §6 Q4). */
 export declare function providerForAgent(agentKind: "CLAUDE" | "GEMINI" | "CODEX" | "ANTIGRAVITY"): VendorProvider | null;
@@ -24,6 +24,13 @@ export interface EngageSubstrateInput {
     workdir: string;
     /** Exact workdir incarnation for task-scoped mutable dispatch. */
     workdirAuthority?: WorkspaceRootAuthority;
+    /**
+     * P63 Slice 2 (§8.2) — a reviewer seat's read-only grants (the review bundle; macOS: the masked original). `workdir`
+     * is then the seat's private scratch. Passed through unchanged to every backend's {@link SubstrateSpec}.
+     */
+    reviewGrants?: SubstrateSpec['reviewGrants'];
+    /** P63 Slice 2 (§8.2) — the spawn's task-owned capture dir, granted read-write beside a read-only view. */
+    captureDir?: string;
     /** The implementor role marker value (always 'implementor' here). */
     role: ProcessRole;
     /**
@@ -48,6 +55,13 @@ export interface EngageSubstrateInput {
     writableWorkdir?: boolean;
     /** Optional spawn identifier for per-spawn private homes / filters. */
     spawnId?: string;
+    /** §5.1 / §6.2 — where the spawn's start record goes (default `~/.codevibe/shadow-state-v2`); tests isolate it. */
+    spawnStateRoot?: string;
+    /**
+     * P63 §6.1 / §6.2 — the user's real project folder the spawn's copy (or review bundle) was made from. Required to
+     * engage the Linux bubblewrap tier: the grant rule hides it and never grants a root that contains it.
+     */
+    projectRoot?: string;
     /** Optional home dir override (injectable for tests). */
     homedir?: string;
     /** F-P46a-4 — the implementor spawn's process-tree id (descendant reaping marker). */
@@ -102,7 +116,7 @@ export interface EngageSubstrateInput {
  */
 export interface SubstrateEngaged {
     mode: "substrate";
-    tier: "docker" | "sandbox_exec";
+    tier: "docker" | "sandbox_exec" | "bubblewrap";
     /** Reduced-trust badge for the A5 coarse tier (false for A1 strict). */
     reducedTrust: boolean;
     reducedTrustReason?: string;