@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/structural-summary/types.d.ts

@@ -0,0 +1,215 @@
+import type { Tier } from '../orchestration-shell/types';
+/**
+ * The 6 manifest kinds detected by the first slice (§4.4), plus `other`
+ * (parser found a candidate but parsing failed) and `none` (no manifest
+ * found at this rootPath).
+ *
+ * Matches the locked `RepoSummary.manifestType` enum at CP-0 §10.S.7 line 145.
+ */
+export type ManifestType = 'npm' | 'cargo' | 'pyproject' | 'go' | 'podfile' | 'gradle' | 'other' | 'none';
+export interface ParsedManifest {
+    type: ManifestType;
+    packageName?: string;
+    dependencies: string[];
+}
+/**
+ * One directory in the walked tree. Mirrors CP-0 §10.S.7:153-160; the
+ * Max-tier `body` + `bodyTruncated` fields are `[ADDITIVE WIDENING — CP-1.d]`
+ * per Hendry-locked round-1 Q1. `truncatedByDepth` is set when the walker
+ * hits `maxDepth = 12` on this node's subtree (§4.7).
+ */
+export interface DirectoryNode {
+    path: string;
+    fileCount: number;
+    bytes: number;
+    children: DirectoryNode[];
+    inferredLanguage?: string;
+    /** `[ADDITIVE WIDENING — CP-1.d]` Q1 LOCKED — Max-tier opt-in only. */
+    body?: string;
+    /** `[ADDITIVE WIDENING — CP-1.d]` Q1 LOCKED — true if `body` truncated or skipped due to per-file 512 KiB cap or shared 64 MiB body budget. */
+    bodyTruncated?: boolean;
+    /** True if walker stopped recursing here because `maxDepth = 12` was hit on a descendant. */
+    truncatedByDepth?: boolean;
+}
+/**
+ * One repo's portion of the assembled summary. The `rootPath` ECHOES the
+ * caller-supplied (possibly symlinked) path so the user-visible digest
+ * stays stable; the walker uses `realRootPath` for internal admission
+ * checks (§4.3 step 2 step 0).
+ */
+export interface RepoSummary {
+    rootPath: string;
+    manifestType: ManifestType;
+    packageName?: string;
+    dependencies: string[];
+    inferredLanguages: string[];
+    readmePreview: string;
+    directoryTree: DirectoryNode;
+}
+/**
+ * Privacy envelope counters + status flags. All but the first 3 fields are
+ * `[ADDITIVE WIDENING — CP-1.d]` extensions to the CP-0 §10.S.7:136-140
+ * 3-field sketch (per Stage 2 r1 Codex H-1 + Gemini H-1 + Hendry-locked Q2).
+ */
+export interface PrivacyEnvelope {
+    bodyInclusionPaths: string[];
+    excludedByGitignore: number;
+    excludedByIgnoreFile: number;
+    /** `[ADDITIVE WIDENING — CP-1.d]` Stage 2 r1 Codex H-1. */
+    excludedAsUntracked?: number;
+    /** `[ADDITIVE WIDENING — CP-1.d]` Q2 LOCKED — covers both file-count AND body-byte budgets. */
+    budgetExceeded?: boolean;
+    /** `[ADDITIVE WIDENING — CP-1.d]` Stage 2 r1 Gemini H-1 — disambiguates which budget tripped first. */
+    budgetReason?: 'fileCount' | 'bodyBytes';
+    /** `[ADDITIVE WIDENING — CP-1.d]` Stage 2 r1 Codex H-1 — graceful non-git fallback marker. */
+    notInGitRepo?: boolean;
+}
+/**
+ * The top-level structural summary returned by `generate()`. CP-1.b
+ * consumes `sha256` as an opaque cache key.
+ */
+export interface StructuralSummary {
+    generatedAt: string;
+    rootPaths: string[];
+    repos: RepoSummary[];
+    totalFileCount: number;
+    totalBytes: number;
+    privacyEnvelope: PrivacyEnvelope;
+    /**
+     * Hex-encoded SHA-256 over the canonical-JSON serialization of the
+     * summary EXCLUDING BOTH the `sha256` field AND the `generatedAt`
+     * field. `generatedAt` is excluded so identical repo content →
+     * identical sha256 across runs (the CP-1.b reproducibility contract);
+     * a wall-clock timestamp would defeat that.
+     *
+     * Canonical-JSON definition: `JSON.stringify(hashPayload, canonicalReplacer)`
+     * where `canonicalReplacer` sorts object keys lexicographically.
+     * Arrays preserve order, so any input array (e.g., `directoryTree.children`,
+     * `inferredLanguages`) must be sorted deterministically upstream — see
+     * `walker.ts` (children byte-wise sort) and `generator.ts:inferLanguages`
+     * (count + name byte-wise tie-break).
+     *
+     * See `generator.ts:~200-220` for the canonical hash-payload
+     * construction. The previous co-location in `assembler.ts` no longer
+     * applies (Stage 2 IMPL r2 — assembly inlined into `generator.ts`).
+     */
+    sha256: string;
+}
+/**
+ * Caller-supplied options. Mirrors PHASE-CP-1-DESIGN.md:1590-1596.
+ *
+ * `_test_caps` is a test-only escape hatch (note the underscore prefix
+ * + the `__INTERNAL__` doc tag). Production callers MUST NOT pass it;
+ * unit tests use it to trip the file-count + body-byte budget paths
+ * without authoring 50,000-file fixtures. Added by Stage 1 r1 M-3
+ * fix to support the design §5 line 1173 test row.
+ */
+export interface GenerateOpts {
+    rootPaths: string[];
+    ignoreFile?: string;
+    includeBodies?: string[];
+    userId: string;
+    tier: Tier;
+    /** __INTERNAL__ test-only seam — see JSDoc above. */
+    _test_caps?: {
+        fileCountCap?: number;
+        bodyByteCap?: number;
+    };
+}
+export interface StructuralSummaryGenerator {
+    generate(opts: GenerateOpts): Promise<StructuralSummary>;
+}
+/**
+ * Walker return value. Carries the assembled `directoryTree` + per-rootPath
+ * audit + the exclusion state + the two-set walker-accounting ledger.
+ *
+ * `countedExactPaths` + `countedPrunedPrefixes` (round-6 split per Codex r5 M-1)
+ * are the explicit ledger the manifest dispatcher + README reader consult via
+ * `isPathAccountedFor()` to avoid double-counting. See §4.3 step 6.
+ */
+export interface WalkResult {
+    directoryTree: DirectoryNode;
+    fileExtensions: Map<string, number>;
+    excludedByGitignore: number;
+    excludedByIgnoreFile: number;
+    excludedAsUntracked: number;
+    truncated: boolean;
+    bodyBudgetExceeded: boolean;
+    notInGitRepo: boolean;
+    exclusionState: ExclusionState;
+    /**
+     * Exact absolute paths the walker enumerated + already incremented an
+     * `excludedBy*` counter for (any of gitignore/userIgnore/untracked —
+     * NOT secret, which is silent).
+     */
+    countedExactPaths: Set<string>;
+    /**
+     * Absolute directory paths the walker pruned upfront without enumerating
+     * (Step 0.5 root admission OR Step 2 child-directory prune-during-descent).
+     * Counter was incremented once per prefix.
+     */
+    countedPrunedPrefixes: Set<string>;
+}
+/**
+ * Minimal gitignore-format matcher signature — the user-ignore file is
+ * matched against this. Kept as an interface so the implementation can swap
+ * between an in-process matcher and the `ignore` npm package later without
+ * surface churn.
+ */
+export interface UserIgnoreMatcher {
+    /**
+     * Returns true if the gitignore-style ruleset matches `relativePath`.
+     * `relativePath` is path.relative(realRootPath, absolutePath), with forward
+     * slashes on POSIX.
+     *
+     * Stage 2 r2 widening (M-2, Gemini M-1): `isDir` is consulted by rules
+     * with trailing `/` (e.g., `dist/`) — they MUST NOT match a regular
+     * file. Defaults to `false`; only the walker has cheap `Dirent.isDirectory()`
+     * info and threads it through. File-only callers (manifest dispatcher,
+     * README reader) get correct semantics with the default.
+     */
+    ignores(relativePath: string, isDir?: boolean): boolean;
+}
+/**
+ * Per-rootPath exclusion state, built ONCE at walker startup. See §4.3a.
+ *
+ * `ignoredExactPaths` + `ignoredDirPrefixes` (round-6 trailing-slash partition
+ * per Codex r5 H-1) replace round-5's conflated single `ignoredPrefixes` set.
+ * `realRootPath` (round-4 Codex H-1 + Gemini H-1) canonicalises the launch
+ * root through `fs.realpath()` so symlinked launch roots produce correct
+ * subtree-membership filters.
+ */
+export interface ExclusionState {
+    rootPath: string;
+    realRootPath: string;
+    notInGitRepo: boolean;
+    repoTopLevel: string;
+    untrackedSet: Set<string>;
+    ignoredExactPaths: Set<string>;
+    ignoredDirPrefixes: Set<string>;
+    userIgnoreMatcher: UserIgnoreMatcher;
+    secretDenyList: readonly string[];
+}
+/**
+ * On-disk schema for `~/.codevibe/structural-summary.opt-in.json`. Locked
+ * at §4.6.
+ */
+export interface OptInFile {
+    schemaVersion: 1;
+    bodyInclusionPaths: string[];
+    lastUpdatedAt: string;
+    tierAtOptIn: 'MAX';
+}
+export type StructuralSummaryErrorKind = 'tier_gate' | 'fs_unreadable' | 'budget_exceeded' | 'manifest_parse'
+/**
+ * `[ADDITIVE WIDENING — CP-1.d]` Stage 2 r2 Codex H-1.
+ * Thrown when a body-inclusion opt-in path is not absolute, or when
+ * realpath resolution fails (ENOENT etc.) — prevents PRIVACY REGRESSION
+ * where a relative opt-in could leak raw bodies from an unrelated
+ * repo's directory of the same name on a future `cd`.
+ */
+ | 'invalid_path';
+export declare class StructuralSummaryError extends Error {
+    readonly kind: StructuralSummaryErrorKind;
+    constructor(message: string, kind: StructuralSummaryErrorKind);
+}

package/dist/structural-summary/user-ignore-matcher.d.ts

@@ -0,0 +1,9 @@
+import type { UserIgnoreMatcher } from './types';
+/**
+ * Builds a matcher from a gitignore-format text blob.
+ */
+export declare function compileUserIgnore(text: string): UserIgnoreMatcher;
+/**
+ * Returns a no-op matcher (no rules — admits everything).
+ */
+export declare function emptyUserIgnoreMatcher(): UserIgnoreMatcher;

package/dist/structural-summary/walker.d.ts

@@ -0,0 +1,20 @@
+import type { WalkResult } from './types';
+export interface WalkOpts {
+    rootPath: string;
+    ignoreFile?: string;
+    includeBodies: string[];
+    maxDepth: number;
+    /** Shared file-count budget (mutated in-place across rootPaths). */
+    fileCountBudget: {
+        remaining: number;
+    };
+    /** Shared body-byte budget (mutated in-place across rootPaths). */
+    bodyBudget: {
+        remaining: number;
+    };
+}
+/**
+ * Walks `rootPath` and returns a `WalkResult`. Mutates the shared
+ * `fileCountBudget` + `bodyBudget` counters.
+ */
+export declare function walk(opts: WalkOpts): Promise<WalkResult>;

package/dist/substrate/__tests__/docker.test.d.ts

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

package/dist/substrate/__tests__/forwarder.test.d.ts

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

package/dist/substrate/__tests__/git-proxy.test.d.ts

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

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

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

package/dist/substrate/__tests__/substrate-e2e.integration.test.d.ts

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

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

@@ -0,0 +1,19 @@
+import type { CommandResult, CommandRunner, RunnerProc } from './types';
+/**
+ * The production `CommandRunner` — runs `docker` / `sandbox-exec` via
+ * `node:child_process`. No shell is used (argv is passed directly to
+ * `spawn`), so there is no shell-injection surface from the constructed
+ * arguments.
+ */
+export declare class ChildProcessCommandRunner implements CommandRunner {
+    run(argv: string[], opts?: {
+        timeoutMs?: number;
+        input?: string;
+    }): Promise<CommandResult>;
+    spawnLong(argv: string[], opts: {
+        stdinTty: boolean;
+        signal?: AbortSignal;
+        env?: Readonly<Record<string, string>>;
+        cwd?: string;
+    }): RunnerProc;
+}

package/dist/substrate/docker.d.ts

@@ -0,0 +1,134 @@
+import { type ForwarderFactory } from './forwarder';
+import type { CommandRunner, EgressObservationHook, Substrate, SubstrateHandle, SubstrateSpec } from './types';
+/** Where, inside the container, the worktree is mounted (the agent's cwd/home). */
+export declare const CONTAINER_WORKDIR = "/workspace";
+/** 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. */
+    runner?: CommandRunner;
+    /** Host-side UDS relay factory (default: real `node:net`). */
+    forwarderFactory?: ForwarderFactory;
+    /** §3.5 observation seam. **W3 wires the emit**; default no-op. */
+    onEgressDenied?: EgressObservationHook;
+    /** Override the container image (default {@link DEFAULT_IMAGE}). */
+    image?: string;
+    /**
+     * Override the host root for the per-session scratch dir (default:
+     * os.tmpdir()). The per-session dir holds ONLY the broker socket (in `uds/`),
+     * the relay script, and the scrubbed git-proxy (in `gitproxy/`) — no secrets.
+     * The git-proxy now lives UNDER this dir (MED fix), so the one
+     * teardown/rollback rm removes it.
+     */
+    sessionRoot?: string;
+}
+/** The deterministic per-session container name. */
+export declare function containerName(id: string): string;
+/**
+ * The shell-wrapped container entrypoint: start the in-container relay in the
+ * background, then hold the container alive for `docker exec`. We MUST wrap in
+ * `sh -c` because the relay has to run CONCURRENTLY with the hold (the relay is
+ * the broker channel; `exec sleep infinity` keeps the container up for exec).
+ * `exec` replaces the shell with sleep so signals (docker kill) propagate.
+ *
+ * MED fix (Stage-2): the whole `sh -c` runs under `env -i <sanitizedEnv>` so
+ * PID1 (and thus everything inheriting from it, including `docker exec`) has
+ * EXACTLY `sanitizedEnv` — the image's baked env is wiped. The relay needs
+ * Node on PATH; `sanitizedEnv` carries PATH (the allow-list includes it).
+ *
+ * Exposed for the conformance test (pins the `env -i … sh -c 'node relay.js
+ * <port> <sock> & exec sleep infinity'` shape).
+ */
+export declare function buildContainerEntrypoint(sanitizedEnv: Readonly<Record<string, string>>): string[];
+/**
+ * `docker run --network none -d` argv. Builds the FULL Option-A isolation
+ * surface the conformance test pins:
+ *   - `--network none`         → STRUCTURAL default-deny (only `lo`, no egress).
+ *   - `-v <workdir>:/workspace` → ONLY the worktree mounted (rw).
+ *   - `-v <gitProxy>:/workspace/.git:ro` → scrubbed `.git`, read-only (if any).
+ *   - `-v <relayScript>:/codevibe/relay.js:ro` → the in-container relay (ro).
+ *   - `-v <udsDir>:/codevibe/broker:rw`  → the bind-mounted broker UDS dir (rw,
+ *     so the container's `connect()` works; the dir holds only the socket).
+ *   - env via repeated `-e K=V` built EXACTLY from `spec.sanitizedEnv` (no host
+ *     env passthrough; `docker run` does NOT inherit the host env). MED fix:
+ *     the `-e` flags ADD to the image's baked env, so the AUTHORITATIVE wipe is
+ *     the `env -i <sanitizedEnv>` prefix on the entrypoint (PID1) + every exec.
+ *   - entrypoint: `env -i <sanitizedEnv> sh -c 'node relay.js <port> <sock> &
+ *     exec sleep infinity'` — PID1's env is EXACTLY sanitizedEnv (MED fix).
+ * NO `--add-host`, NO `--network <name>`, NO `--internal`, and NO `-v` for host
+ * keychain/home/dotfiles is ever added.
+ */
+export declare function buildRunArgv(args: {
+    id: string;
+    image: string;
+    workdir: string;
+    gitProxyPath: string | null;
+    relayScriptPath: string;
+    udsDir: string;
+    sanitizedEnv: Readonly<Record<string, string>>;
+    /** CP-7 PART D — apiKeyHelper bootstrap mount (`hostDir`→`sandboxDir:ro`). */
+    agentBootstrap?: {
+        hostDir: string;
+        sandboxDir: string;
+    };
+}): string[];
+/**
+ * `docker exec [-i] <name> env -i <sanitizedEnv> <argv...>` — run the agent
+ * inside the live sandbox. MED fix (Stage-2): the `env -i <sanitizedEnv>`
+ * prefix clears whatever env `docker exec` would inherit from PID1 / the image
+ * and sets EXACTLY `sanitizedEnv`, so the agent env is the SAME set as the A5
+ * path (no image `PATH`/baked-env leak). `--env-file`/`-e` on `docker exec`
+ * only ADD; `env -i` in the command position is the authoritative wipe.
+ */
+export declare function buildExecArgv(id: string, argv: string[], stdinTty: boolean, sanitizedEnv: Readonly<Record<string, string>>): string[];
+/** `docker kill <name>` — teardown step 1. */
+export declare function buildKillArgv(id: string): string[];
+/** `docker rm -f <name>` — teardown step 2 (idempotent via -f). */
+export declare function buildRmArgv(id: string): string[];
+/**
+ * A1 Docker substrate (`egressFidelity: 'strict'`, Option A). See file header
+ * for the full egress + fs + env contract.
+ */
+export declare class DockerSubstrate implements Substrate {
+    private readonly runner;
+    private readonly forwarderFactory;
+    private readonly onEgressDenied;
+    private readonly image;
+    private readonly sessionRoot;
+    constructor(deps?: DockerSubstrateDeps);
+    launch(spec: SubstrateSpec): Promise<SubstrateHandle>;
+    private rollback;
+    /**
+     * r5 HIGH-2 (Codex — NULL-vs-THROW gap). The proxy build produced no usable
+     * proxy (it returned `null` OR threw). Decide the safe outcome by whether the
+     * workdir actually HAS a `.git`:
+     *
+     *   - NO `<workdir>/.git`            → return `null` (a non-git workdir; the
+     *                                      `docker run` mounts only the worktree,
+     *                                      git reports "not a repository" — no
+     *                                      credential surface either way).
+     *   - `<workdir>/.git` EXISTS        → write an EMPTY SCRUBBED `.git` overlay
+     *                                      (a dir with ONLY a stripped synthetic
+     *                                      `config` — NO remotes/creds/hooks) and
+     *                                      return its path, so the `:ro` bind mount
+     *                                      SHADOWS the real `.git`. Degraded git
+     *                                      reads, but the credential surface is
+     *                                      fail-closed.
+     *   - overlay write ALSO fails       → roll back + throw (NEVER mount the
+     *                                      worktree with a live `.git`).
+     *
+     * Used for BOTH the null-return and the throw path so a workdir with a real
+     * but unresolvable `.git` can never reach the agent un-shadowed. `fsp.stat`
+     * (NOT `lstat`) follows a `.git` that is a symlink/dir/file alike — any of
+     * those "exists" cases must be shadowed.
+     */
+    private ensureGitOverlayOrFailClosed;
+    private assertDockerAvailable;
+}
+export declare const __testing: {
+    DEFAULT_IMAGE: string;
+    CONTAINER_WORKDIR: string;
+    CONTAINER_GIT: string;
+    CONTAINER_RELAY_PATH: string;
+    CONTAINER_BROKER_DIR: string;
+    RELAY_PORT: number;
+};

package/dist/substrate/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Thrown by {@link import('./docker').DockerSubstrate.launch} when the Docker
+ * CLI/daemon is absent or unusable, and by
+ * {@link import('./sandbox-exec').SandboxExecSubstrate.launch} when
+ * `sandbox-exec` is unavailable (non-macOS / missing binary).
+ *
+ * The LE catches this to drive the §6 Q2 fallback ladder. The carried
+ * `isolationTech` + `reason` let the LE log/branch precisely; the substrate
+ * itself NEVER falls back silently — refusing to run is the safe state.
+ */
+export declare class SubstrateUnavailableError extends Error {
+    /** Which backend was unavailable (`docker` / `sandbox_exec`). */
+    readonly isolationTech: string;
+    /** Human-readable cause (CLI missing, daemon down, non-macOS, …). */
+    readonly reason: string;
+    constructor(
+    /** Which backend was unavailable (`docker` / `sandbox_exec`). */
+    isolationTech: string, 
+    /** Human-readable cause (CLI missing, daemon down, non-macOS, …). */
+    reason: string, cause?: unknown);
+}
+/**
+ * Thrown when a substrate lifecycle step (network create, container run,
+ * `docker exec`, profile write) fails for a reason OTHER than the backend
+ * being absent — i.e. the backend is present but a command errored. Distinct
+ * from {@link SubstrateUnavailableError} so the LE does NOT mistake a transient
+ * command failure for "no runtime, fall back to A5."
+ */
+export declare class SubstrateLaunchError extends Error {
+    readonly isolationTech: string;
+    readonly reason: string;
+    constructor(isolationTech: string, reason: string, cause?: unknown);
+}

package/dist/substrate/forwarder.d.ts

@@ -0,0 +1,67 @@
+import type { EgressObservationHook } from './types';
+/**
+ * Construction spec for the host-side UDS relay. The substrate owns one per
+ * session.
+ */
+export interface ForwarderSpec {
+    /** Orchestration task_id — stamped on every `egress_denied` observation. */
+    taskId: string;
+    /**
+     * The FIXED upstream the relay ALWAYS dials (`spec.hostBrokerAddr`).
+     * Agent-supplied targets are ignored — this is the only destination.
+     */
+    hostBrokerAddr: string;
+    /**
+     * The host UDS path the relay LISTENS on (the container bind-mounts this rw
+     * and its in-relay dials it). Required for Option A — there is no TCP bind.
+     */
+    udsPath: string;
+    /** §3.5 observation seam. **W3 wires the emit**; default no-op. */
+    onEgressDenied?: EgressObservationHook;
+}
+/**
+ * The host-side UDS relay (§3.1, `strict` tier, Option A). Listens on a
+ * per-session host Unix-domain socket; every inbound connection is relayed to
+ * the single fixed `hostBrokerAddr`. It never reads an agent-supplied
+ * destination. A broker-upstream connect failure fires
+ * {@link EgressObservationHook} (W3 → `egress_denied`).
+ */
+export declare class HostEgressForwarder {
+    private readonly server;
+    private readonly upstream;
+    private readonly onEgressDenied;
+    private readonly taskId;
+    private readonly udsPath;
+    private listening;
+    constructor(spec: ForwarderSpec);
+    /**
+     * Start listening on the host UDS. Removes any stale socket file at the path
+     * first (a crashed prior run can leave one — listen() would EADDRINUSE).
+     * Resolves with the UDS path the container dials.
+     */
+    start(): Promise<{
+        udsPath: string;
+    }>;
+    /** The host UDS path the container dials (valid after {@link start}). */
+    boundAddr(): string;
+    /**
+     * Idempotent teardown — closes the listener (relayed sockets drop with it)
+     * and unlinks the host UDS file so the per-session dir can be removed.
+     */
+    stop(): Promise<void>;
+    private onConnection;
+    private observeDenial;
+    /**
+     * Directly record a blocked outbound attempt. Under Option A there is no
+     * network-observable denied attempt for A1 (the container has no NIC — see
+     * the docker.ts §3.5 footnote), so this is STRUCTURALLY UNFIRED for A1. It
+     * stays exposed so a future iptables/A5 tier that CAN observe a sandbox→
+     * non-broker attempt routes it through the same seam + id minting.
+     */
+    recordBlockedDestination(destination: string, denialReason: string): void;
+    private safeDestroy;
+}
+/** Factory the substrate uses (injectable so unit tests can stub the relay). */
+export type ForwarderFactory = (spec: ForwarderSpec) => HostEgressForwarder;
+/** Default factory — the real `node:net` UDS relay. */
+export declare const defaultForwarderFactory: ForwarderFactory;

package/dist/substrate/git-proxy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A minimal synthetic `config` written into the proxy. Repository-format
+ * version + bare=false ONLY — explicitly NO `[remote ...]`, NO `[credential]`,
+ * NO `core.hooksPath`, NO `[user]` (which could carry a signing key path). This
+ * is the credential-scrub: the real repo's config never enters the sandbox.
+ */
+export declare const SCRUBBED_CONFIG: string;
+/**
+ * Resolve the real parent `.git` directory for a worktree. In a worktree the
+ * `<workdir>/.git` is a FILE: `gitdir: /abs/path/to/parent/.git/worktrees/<n>`.
+ * The commit objects live in the parent repo's top-level `.git` (i.e. two
+ * levels up from `worktrees/<n>`). For a NON-worktree checkout `<workdir>/.git`
+ * is already the real dir. Returns the directory that holds `objects/` +
+ * `refs/`.
+ *
+ * @returns the resolved real git-common-dir, or `null` if `<workdir>/.git` is
+ *   absent/unreadable (the caller skips proxying — a non-git workdir is fine).
+ */
+export declare function resolveGitCommonDir(workdir: string): Promise<string | null>;
+/**
+ * Build a read-only, credential-scrubbed `.git` proxy at `destDir` from the
+ * resolved git-common-dir. **[W2-min]** — copies only {@link COPIED_GIT_ENTRIES}
+ * + a synthetic stripped {@link SCRUBBED_CONFIG}; NO remotes/creds/hooks/reflog.
+ *
+ * The substrate bind-mounts `destDir` READ-ONLY into the sandbox at
+ * `<workdir>/.git`. Returns the proxy path on success, or `null` if `workdir`
+ * is not a resolvable git checkout (the substrate then mounts only the worktree
+ * with no `.git`, and git read commands simply report "not a repository" — no
+ * ambient exposure either way).
+ */
+export declare function buildScrubbedGitProxy(workdir: string, destDir: string): Promise<string | null>;
+export declare const __testing: {
+    COPIED_GIT_ENTRIES: readonly ["HEAD", "refs", "packed-refs", "objects"];
+    SCRUBBED_CONFIG: string;
+};

package/dist/substrate/index.d.ts

@@ -0,0 +1,12 @@
+export type { IsolationTech, EgressFidelity, SubstrateSpec, SubstrateProc, SubstrateHandle, Substrate, EgressDenialDetail, EgressObservationHook, CommandResult, CommandRunner, RunnerProc, } from "./types";
+export { NOOP_EGRESS_HOOK } from "./types";
+export { DockerSubstrate } from "./docker";
+export type { DockerSubstrateDeps } from "./docker";
+export { SandboxExecSubstrate, buildSeatbeltProfile } from "./sandbox-exec";
+export type { SandboxExecDeps } from "./sandbox-exec";
+export { SubstrateUnavailableError, SubstrateLaunchError } from "./errors";
+export { ChildProcessCommandRunner } from "./command-runner";
+export { HostEgressForwarder, defaultForwarderFactory } from "./forwarder";
+export type { ForwarderSpec, ForwarderFactory } from "./forwarder";
+export { buildScrubbedGitProxy, resolveGitCommonDir } from "./git-proxy";
+export { IN_CONTAINER_RELAY_SOURCE, CONTAINER_RELAY_PATH, CONTAINER_BROKER_DIR, CONTAINER_BROKER_SOCK, BROKER_SOCK_NAME, RELAY_PORT, } from "./relay-script";

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

@@ -0,0 +1,27 @@
+/**
+ * The in-container relay source. argv: `node relay.js <port> <udsPath>`.
+ *   - `<port>`   : the loopback TCP port the agent dials (container namespace).
+ *   - `<udsPath>`: the bind-mounted host UDS the bytes are forwarded to.
+ *
+ * `net.createServer` on `127.0.0.1:<port>` → `net.connect(<udsPath>)` → pipe
+ * both ways. A per-connection UDS-connect failure drops only that connection
+ * (the agent retries); a listen failure exits non-zero so the wrapper's hold
+ * surfaces it. Bound to `127.0.0.1` explicitly so it never binds a routable
+ * interface (there is none under `--network none`, but this is belt-and-braces).
+ */
+export declare const IN_CONTAINER_RELAY_SOURCE = "'use strict';\n// CP-7 A1 in-container relay (loopback TCP -> bind-mounted host UDS).\nconst net = require('net');\nconst port = Number(process.argv[2]);\nconst udsPath = process.argv[3];\nif (!Number.isInteger(port) || port <= 0 || port > 65535 || !udsPath) {\n  console.error('relay: usage: node relay.js <port> <udsPath>');\n  process.exit(2);\n}\nconst server = net.createServer((client) => {\n  // Single hard-wired upstream: the bind-mounted host UDS. No agent-supplied\n  // destination is ever read \u2014 this relay forwards loopback bytes to the UDS only.\n  const up = net.connect(udsPath);\n  const drop = () => { try { client.destroy(); } catch (e) {} try { up.destroy(); } catch (e) {} };\n  up.on('connect', () => { client.pipe(up); up.pipe(client); });\n  up.on('error', drop);\n  client.on('error', drop);\n});\nserver.on('error', (err) => {\n  console.error('relay: listen failed: ' + (err && err.message));\n  process.exit(1);\n});\nserver.listen(port, '127.0.0.1', () => {\n  console.error('relay: listening on 127.0.0.1:' + port + ' -> ' + udsPath);\n});\n";
+/** The in-container path the relay script is bind-mounted (read-only) to. */
+export declare const CONTAINER_RELAY_PATH = "/codevibe/relay.js";
+/** The in-container directory the host UDS dir is bind-mounted (rw) to. */
+export declare const CONTAINER_BROKER_DIR = "/codevibe/broker";
+/** The UDS filename inside the broker dir (host + container agree on this). */
+export declare const BROKER_SOCK_NAME = "broker.sock";
+/** The in-container UDS path the relay forwards to. */
+export declare const CONTAINER_BROKER_SOCK = "/codevibe/broker/broker.sock";
+/**
+ * The FIXED loopback port the in-container relay listens on, and the port the
+ * agent dials via `sandboxBrokerUrl = http://127.0.0.1:<port>`. The container
+ * has its OWN net namespace under `--network none`, so a fixed port never
+ * collides with anything on the host. 8787 is arbitrary-but-stable.
+ */
+export declare const RELAY_PORT = 8787;