@cleocode/core 2026.6.12 → 2026.6.13

package/dist/llm/pi/pi-execution-env.js

@@ -0,0 +1,406 @@
+/**
+ * Guarded Pi `ExecutionEnv` (T11761 · S1 · T11897).
+ *
+ * Pi's agent loop performs ALL filesystem + shell work through a single
+ * pluggable seam: `ExecutionEnv extends FileSystem, Shell`. This module supplies
+ * Cleo's implementation of that seam — {@link GuardedExecutionEnv} — which routes
+ * every operation through the deny-first {@link ToolGuard} chokepoint and an
+ * injected **workspace boundary**, so Pi can touch nothing outside the
+ * allowlisted roots and runs no command on the denylist.
+ *
+ * Two layers of confinement (deny-first):
+ * 1. **Workspace boundary** — every fs path is canonicalized with SYMLINK
+ *    RESOLUTION (`fs.realpath` on the nearest existing ancestor) and the REAL
+ *    target MUST fall under the injected `workspaceRoot`; a `../` escape, an
+ *    out-of-root absolute path, OR a symlink (file or parent dir) whose real
+ *    target leaves the root is rejected as a Pi `Result.err(FileError)` BEFORE
+ *    the guard is consulted. A purely lexical check is symlink-blind, so the
+ *    boundary resolves symlinks first. (The guard's own `allowedRoots` is a
+ *    second, ALSO-symlink-resolving net.)
+ * 2. **ToolGuard** — the allowed operations delegate to the `ToolGuard` surface
+ *    (`readFileText`/`writeFileAtomic`/`pathExists`/`executeShell`/`runGit`),
+ *    which applies the project's symlink-resolved path allowlist + shell
+ *    denylist + subprocess-env scrub. A `GuardDeniedError` from enforce-mode is
+ *    CAUGHT and converted to a Pi `Result.err` — Pi's `FileSystem`/`Shell` ops
+ *    must NEVER throw. The guard MUST be constructed in `enforce` mode (the
+ *    factory asserts it) — in `warn` mode its allowlist/denylist are advisory
+ *    and confinement would collapse to the workspace boundary alone.
+ *
+ * Every other capability (binary reads, raw temp/dir mutation, listing, …) for
+ * which there is no atomic primitive in v0 is DENIED with a typed error rather
+ * than reaching the real filesystem. The structural Pi interfaces are declared
+ * locally here (the `@earendil-works/pi-agent-core` package is not yet a
+ * dependency); S2 replaces these with the real type-only imports — the shapes
+ * match `@earendil-works/pi-agent-core@0.78.1` `harness/types.ts:268-332`.
+ *
+ * Scope discipline (S1): NO `pi-ai`/`pi-agent-core` imports, NO DB access, NO
+ * LLM calls. Import-time side-effect free.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11897
+ */
+import { isAbsolute, relative, resolve as resolvePath } from 'node:path';
+import { scrubSubprocessEnv } from '../../tools/env-scrub.js';
+import { canonicalizePath } from '../../tools/fs.js';
+import { GuardDeniedError } from '../../tools/guard.js';
+// ---------------------------------------------------------------------------
+// Result constructors
+// ---------------------------------------------------------------------------
+/** Build a successful {@link PiResult}. */
+function ok(value) {
+    return { ok: true, value };
+}
+/** Build a failed {@link PiResult} with a {@link PiFileError}. */
+function fsErr(code, message, path) {
+    return { ok: false, error: { code, message, ...(path !== undefined ? { path } : {}) } };
+}
+/** Build a failed {@link PiResult} with a {@link PiExecutionError}. */
+function execErr(code, message) {
+    return { ok: false, error: { code, message } };
+}
+/**
+ * Whether `err` is a "file does not exist" failure (`ENOENT`). Used by
+ * {@link GuardedExecutionEnv.appendFile} to treat append-to-missing as
+ * append-creates (empty prefix) while still propagating every OTHER failure
+ * (guard denial, permission, …).
+ */
+function isMissingFileError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+/**
+ * Deny-first {@link PiExecutionEnv} backed by the Cleo {@link ToolGuard} surface
+ * and a workspace boundary.
+ *
+ * - File reads/writes/existence checks route through the guard's atomic
+ *   primitives, confined to `workspaceRoot`.
+ * - `exec` routes through the guard's `executeShell` (shell denylist applies).
+ * - Capabilities with no atomic primitive in v0 (binary read, `listDir`,
+ *   `createDir`, `remove`, temp dir/file) are DENIED with a typed
+ *   `Result.err` — they never reach the real filesystem.
+ * - Pure path arithmetic (`cwd`/`absolutePath`/`joinPath`) is computed locally
+ *   (no fs access), anchored to `workspaceRoot`.
+ *
+ * Every method honours the Pi contract: it returns a {@link PiResult} and never
+ * throws — a {@link GuardDeniedError} from the guard is caught and converted.
+ */
+export class GuardedExecutionEnv {
+    #guard;
+    #root;
+    /**
+     * @param deps - The guard surface + the workspace root to confine to.
+     */
+    constructor(deps) {
+        this.#guard = deps.guard;
+        this.#root = resolvePath(deps.workspaceRoot);
+    }
+    /**
+     * Lexically resolve a (possibly relative) path against the workspace root and
+     * assert it does not climb out. This is the fast FIRST gate only — it is
+     * symlink-blind, so {@link #confine} additionally re-checks the REAL target.
+     *
+     * @returns the lexically-resolved absolute path, or `null` on a `../`/absolute
+     *   escape.
+     */
+    #lexicalConfine(path) {
+        const abs = isAbsolute(path) ? resolvePath(path) : resolvePath(this.#root, path);
+        const rel = relative(this.#root, abs);
+        if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)))
+            return abs;
+        return null;
+    }
+    /**
+     * Resolve a (possibly relative) path against the workspace root and assert its
+     * REAL filesystem target stays inside the boundary. Two gates:
+     * 1. lexical (`#lexicalConfine`) — rejects `../` / out-of-root absolute paths;
+     * 2. SYMLINK resolution (`canonicalizePath`) — follows every symlink component
+     *    (incl. a symlinked parent of a fresh write target) and re-checks
+     *    containment against the REAL path, defeating the classic symlink/TOCTOU
+     *    escape that a purely lexical check is blind to.
+     *
+     * @returns the symlink-resolved absolute path, or `null` when it escapes.
+     */
+    async #confine(path) {
+        const lexical = this.#lexicalConfine(path);
+        if (lexical === null)
+            return null;
+        const real = await canonicalizePath(lexical);
+        // Compare against the REAL root too, so a workspace whose own path traverses
+        // a symlink does not spuriously reject its own contained files.
+        const realRoot = await canonicalizePath(this.#root);
+        const rel = relative(realRoot, real);
+        // The REAL target must not climb out of the (also-real) root.
+        if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)))
+            return real;
+        return null;
+    }
+    // --- pure path arithmetic (no fs access) ---------------------------------
+    /** The workspace root (the in-process Pi run's working directory). */
+    cwd() {
+        return this.#root;
+    }
+    /** Resolve `path` to an absolute path anchored at the workspace root. */
+    absolutePath(path) {
+        return isAbsolute(path) ? resolvePath(path) : resolvePath(this.#root, path);
+    }
+    /** Join path segments (pure). */
+    joinPath(...segments) {
+        return resolvePath(this.#root, ...segments);
+    }
+    // --- file reads ----------------------------------------------------------
+    /** Read a file's text, confined to the workspace + guarded. */
+    async readTextFile(path) {
+        const abs = await this.#confine(path);
+        if (abs === null)
+            return fsErr('E_PI_FS_DENIED', 'path escapes workspace boundary', path);
+        try {
+            const res = await this.#guard.readFileText({ path: abs });
+            return ok(res.content);
+        }
+        catch (err) {
+            return this.#toFsErr(err, abs);
+        }
+    }
+    /** Read a file's text as an array of lines. */
+    async readTextLines(path) {
+        const res = await this.readTextFile(path);
+        return res.ok ? ok(res.value.split(/\r?\n/)) : res;
+    }
+    /**
+     * Binary read — DENIED in v0. The atomic `readFileText` primitive is
+     * text-only (`ReadFileInput.encoding` has no binary variant); a binary
+     * primitive must be added under `core/src/tools` (Gate 11) before this is
+     * supported. Deny-first: never reaches the filesystem.
+     */
+    async readBinaryFile(path) {
+        return fsErr('E_PI_FS_UNSUPPORTED', 'binary read is not supported in v0', path);
+    }
+    // --- file writes ---------------------------------------------------------
+    /** Atomically write a file, confined to the workspace + guarded. */
+    async writeFile(path, content) {
+        const abs = await this.#confine(path);
+        if (abs === null)
+            return fsErr('E_PI_FS_DENIED', 'path escapes workspace boundary', path);
+        try {
+            await this.#guard.writeFileAtomic({ path: abs, content });
+            return ok(undefined);
+        }
+        catch (err) {
+            return this.#toFsErr(err, abs);
+        }
+    }
+    /**
+     * Append to a file. The atomic surface offers only whole-file atomic writes,
+     * so this reads-then-writes the concatenation (still confined + guarded). A
+     * missing file is treated as empty.
+     *
+     * Confinement happens EXACTLY ONCE here, then the read + write delegate
+     * straight to the guard with the already-resolved `abs`. Re-entering the
+     * public `readTextFile`/`writeFile` would re-`#confine` the value `#confine`
+     * just returned — and because `#confine` yields the SYMLINK-RESOLVED real path
+     * (e.g. macOS `/tmp`→`/private/tmp`, or a symlinked workspace root), that real
+     * path is `../`-outside the lexical `workspaceRoot`, so the second lexical
+     * gate would spuriously reject it (`E_PI_FS_DENIED`). Reading once through the
+     * guard — whose own allowlist canonicalizes both sides — avoids the
+     * double-confine while keeping the symlink-escape denial intact.
+     */
+    async appendFile(path, content) {
+        const abs = await this.#confine(path);
+        if (abs === null)
+            return fsErr('E_PI_FS_DENIED', 'path escapes workspace boundary', path);
+        // Read existing content directly via the guard (a missing file → ENOENT,
+        // treated as empty). Do NOT route through readTextFile: that would re-confine
+        // the resolved real path against the lexical root and falsely reject it.
+        let prefix = '';
+        try {
+            const res = await this.#guard.readFileText({ path: abs });
+            prefix = res.content;
+        }
+        catch (err) {
+            // A missing file is the only non-fatal case (append-creates). Any other
+            // failure (guard denial, permission, …) propagates as the Pi error.
+            if (!isMissingFileError(err))
+                return this.#toFsErr(err, abs);
+        }
+        try {
+            await this.#guard.writeFileAtomic({ path: abs, content: prefix + content });
+            return ok(undefined);
+        }
+        catch (err) {
+            return this.#toFsErr(err, abs);
+        }
+    }
+    // --- metadata ------------------------------------------------------------
+    /** Report whether a path is a file or directory, confined + guarded. */
+    async fileInfo(path) {
+        const abs = await this.#confine(path);
+        if (abs === null)
+            return fsErr('E_PI_FS_DENIED', 'path escapes workspace boundary', path);
+        try {
+            const res = await this.#guard.pathExists({ path: abs });
+            if (!res.exists)
+                return fsErr('E_PI_FS_NOT_FOUND', 'path does not exist', abs);
+            return ok({ isFile: res.kind === 'file', isDirectory: res.kind === 'directory' });
+        }
+        catch (err) {
+            return this.#toFsErr(err, abs);
+        }
+    }
+    /** Whether a path exists, confined + guarded. */
+    async exists(path) {
+        const abs = await this.#confine(path);
+        if (abs === null)
+            return fsErr('E_PI_FS_DENIED', 'path escapes workspace boundary', path);
+        try {
+            const res = await this.#guard.pathExists({ path: abs });
+            return ok(res.exists);
+        }
+        catch (err) {
+            return this.#toFsErr(err, abs);
+        }
+    }
+    /**
+     * Canonicalize a path inside the workspace. SYMLINK-RESOLVING: `#confine`
+     * follows every symlink component via `fs.realpath`, so the returned value is
+     * the REAL on-disk location (matching Pi's `NodeExecutionEnv.canonicalPath`
+     * contract), and a path whose real target escapes the workspace is denied.
+     */
+    async canonicalPath(path) {
+        const abs = await this.#confine(path);
+        if (abs === null)
+            return fsErr('E_PI_FS_DENIED', 'path escapes workspace boundary', path);
+        return ok(abs);
+    }
+    // --- denied fs-mutating / listing ops (no atomic primitive in v0) --------
+    /** DENIED in v0 — no `listDir` atomic primitive. */
+    async listDir(path) {
+        return fsErr('E_PI_FS_UNSUPPORTED', 'directory listing is not supported in v0', path);
+    }
+    /** DENIED in v0 — no `createDir` atomic primitive. */
+    async createDir(path) {
+        return fsErr('E_PI_FS_UNSUPPORTED', 'directory creation is not supported in v0', path);
+    }
+    /** DENIED in v0 — no `remove` atomic primitive. */
+    async remove(path) {
+        return fsErr('E_PI_FS_UNSUPPORTED', 'remove is not supported in v0', path);
+    }
+    /** DENIED in v0 — no temp-dir atomic primitive. */
+    async createTempDir() {
+        return fsErr('E_PI_FS_UNSUPPORTED', 'temp dir creation is not supported in v0');
+    }
+    /** DENIED in v0 — no temp-file atomic primitive. */
+    async createTempFile() {
+        return fsErr('E_PI_FS_UNSUPPORTED', 'temp file creation is not supported in v0');
+    }
+    // --- shell ---------------------------------------------------------------
+    /**
+     * Execute a command through the guard's shell surface (denylist applies). The
+     * Pi `command` string is a bare executable name (args are passed by Pi via the
+     * loop, but the v0 seam takes only `command`); we forward it as the guard's
+     * `command` with empty args. `cwd` is symlink-confined to the workspace.
+     *
+     * ## Env is SCRUBBED before it leaves this seam (T11897 · security)
+     *
+     * Pi's `options.env` is UNTRUSTED model-driven input. Forwarding it verbatim
+     * would let Pi set `LD_PRELOAD`/`NODE_OPTIONS`/`GIT_SSH_COMMAND` (arbitrary
+     * native code execution outside any allowlist) or hijack `PATH` to make a
+     * workspace-resident impostor satisfy an allowed command basename. So the env
+     * is run through {@link scrubSubprocessEnv} HERE — forbidden keys (loader
+     * hooks, `PATH`, secrets) are dropped and `PATH` is pinned to a trusted value
+     * — before it reaches the guard (which scrubs again as a redundant net, as
+     * does `defaultShellExecutor`). This also prevents the daemon's own secrets
+     * from leaking into the child (the scrubbed env never inherits `process.env`).
+     */
+    async exec(command, options) {
+        const cwd = options?.cwd ? await this.#confine(options.cwd) : this.#root;
+        if (cwd === null) {
+            return execErr('E_PI_EXEC_DENIED', 'cwd escapes workspace boundary');
+        }
+        // Scrub Pi-supplied env to a minimal allowlist at the seam (defense in depth
+        // — the guard + executor scrub again). Pi can NOT inject a loader hook,
+        // hijack PATH, or read inherited daemon secrets through this channel.
+        const env = scrubSubprocessEnv({ extra: options?.env });
+        try {
+            const res = await this.#guard.executeShell({
+                command,
+                cwd,
+                env,
+                ...(options?.timeout !== undefined ? { timeoutMs: options.timeout } : {}),
+            });
+            return ok({ stdout: res.stdout, stderr: res.stderr, exitCode: res.code });
+        }
+        catch (err) {
+            if (err instanceof GuardDeniedError) {
+                return execErr('E_PI_EXEC_DENIED', err.message);
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return execErr('E_PI_EXEC_FAILED', message);
+        }
+    }
+    // --- cleanup (best-effort, must not throw) -------------------------------
+    /** Best-effort cleanup; the guarded surface owns no resources, so a no-op. */
+    async cleanup() {
+        // no-op — required on both FileSystem + Shell; owns nothing to release.
+    }
+    // --- error mapping -------------------------------------------------------
+    /** Convert a thrown error from the guarded surface into a Pi `Result.err`. */
+    #toFsErr(err, path) {
+        if (err instanceof GuardDeniedError) {
+            return fsErr('E_PI_FS_DENIED', err.message, path);
+        }
+        const code = typeof err === 'object' && err !== null && 'code' in err
+            ? String(err.code)
+            : 'E_PI_FS_FAILED';
+        const message = err instanceof Error ? err.message : String(err);
+        return fsErr(code, message, path);
+    }
+}
+/**
+ * Thrown by {@link createGuardedExecutionEnv} when the injected guard is NOT in
+ * `enforce` mode. In `warn` mode the guard's path allowlist + command denylist
+ * are advisory (log-and-proceed), so the second confinement net does not exist
+ * and the boundary would collapse to the workspace check alone. The Pi adapter
+ * therefore REFUSES a non-enforce guard rather than running untrusted Pi work
+ * behind an advisory boundary.
+ */
+export class PiGuardModeError extends Error {
+    /** Machine-readable code. */
+    code = 'E_PI_GUARD_NOT_ENFORCING';
+    /**
+     * @param mode - The (non-enforce) mode the guard was constructed with.
+     */
+    constructor(mode) {
+        super(`Pi ExecutionEnv requires an enforce-mode ToolGuard; got "${mode}". ` +
+            'In warn mode the path allowlist + command denylist are advisory and provide no boundary.');
+        this.name = 'PiGuardModeError';
+    }
+}
+/**
+ * Construct a deny-first {@link GuardedExecutionEnv}.
+ *
+ * REQUIRES an `enforce`-mode guard: a `warn`-mode guard's allowlist/denylist are
+ * advisory, so handing untrusted Pi work behind one would leave confinement to
+ * the workspace boundary alone. The factory ASSERTS the mode and throws
+ * {@link PiGuardModeError} otherwise — the Pi adapter never silently degrades to
+ * an advisory boundary.
+ *
+ * @param deps - The guard surface + the workspace root to confine to.
+ * @returns A {@link PiExecutionEnv} safe to hand to Pi's agent loop.
+ * @throws {PiGuardModeError} When `deps.guard.mode !== 'enforce'`.
+ *
+ * @example
+ * ```ts
+ * const guard = createToolGuard({ allowedRoots: [projectRoot], mode: 'enforce' });
+ * const env = createGuardedExecutionEnv({ guard, workspaceRoot: projectRoot });
+ * ```
+ */
+export function createGuardedExecutionEnv(deps) {
+    if (deps.guard.mode !== 'enforce') {
+        throw new PiGuardModeError(deps.guard.mode);
+    }
+    return new GuardedExecutionEnv(deps);
+}
+//# sourceMappingURL=pi-execution-env.js.map

package/dist/llm/pi/pi-execution-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-execution-env.js","sourceRoot":"","sources":["../../../src/llm/pi/pi-execution-env.ts"],"names":[],"mappings":"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"}

package/dist/llm/pi/pi-gondolin-env.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Gondolin micro-VM Pi `ExecutionEnv` — the SECOND backend of the
+ * {@link PiExecutionEnv} seam (T11909 · T11888-B · P5 Gondolin · epic T11599).
+ *
+ * Where the in-process {@link import('./pi-execution-env.js').GuardedExecutionEnv}
+ * (S1 · T11761 · T11897) confines Pi with a deny-first `ToolGuard` + workspace
+ * boundary INSIDE the host process, this backend's confinement is the
+ * **micro-VM boundary itself**. Guest code runs with:
+ *
+ * - **ZERO host authority** — no `cleo.db` handle, no writer-lease IPC socket, no
+ *   host `process.env` secrets, no host filesystem outside the single RW
+ *   `/workspace` mount. The guest is a different kernel; it cannot reach the
+ *   daemon, the lease arbiter, or BRAIN even if Pi-driven code tries.
+ * - **Egress only via the credential-injection proxy** — `createHttpHooks` is
+ *   constructed with `allowedHosts: []` (present-and-empty = DENY ALL per the
+ *   gondolin docs; OMITTING it = allow-all — the egress footgun this guards) and
+ *   host-side secret PLACEHOLDERS, so the guest only ever sees the `placeholder`
+ *   bytes, never the real token. The loop appends specific hosts per run.
+ * - **Live DBs NEVER mounted** — `.cleo/tasks.db` / `.cleo/brain.db` are NOT in
+ *   the VFS mount set. A replay operates on a DISPOSABLE seeded copy
+ *   (`VACUUM INTO` snapshot), so the T5158 data-loss vector (git overwrites the
+ *   live WAL-backed DB) is structurally impossible: there is no live handle
+ *   inside the VM to corrupt.
+ *
+ * This is strictly stronger than S1's env-scrub: S1 protects against an in-process
+ * Pi escape via the guard allowlist; Gondolin protects via kernel + VFS + network
+ * namespace separation. A thin in-guest deny layer (lexical `/workspace`
+ * confinement + a command denylist for real egress verbs) is kept as DEFENSE IN
+ * DEPTH — the boundary is the VM, but a Pi escape that runs a binary still cannot
+ * do damage that survives the run.
+ *
+ * Optional-dep discipline (D11142): `@earendil-works/gondolin` is loaded ONLY via
+ * the {@link import('./gondolin-loader.js').loadGondolin} dynamic import — it is
+ * in NEITHER `dependencies` NOR `optionalDependencies`, and this module declares
+ * NO `import type` from the package (the consumed structural shapes come from the
+ * loader's LOCAL types). `core` builds + all non-gondolin tests pass with gondolin
+ * ABSENT, and this module is import-time side-effect-free (no top-level VM boot).
+ *
+ * Never-throw discipline: every `vm.fs.*` / `vm.exec` call is wrapped exactly as
+ * S1's `#toFsErr` / `execErr` — a thrown gondolin/guest error becomes a
+ * {@link PiResult} `err` with `E_PI_FS_*` / `E_PI_EXEC_*` codes. The
+ * `PiResult<T, E>` contract is byte-for-byte identical to S1, so the Pi loop
+ * cannot tell the two backends apart.
+ *
+ * @epic T11599
+ * @task T11909
+ * @see ./pi-execution-env.js — the S1 `GuardedExecutionEnv` this mirrors over a VM
+ * @see ./gondolin-loader.js — the optional-dep loader supplying the structural types
+ */
+import { type GondolinModule, type SecretDefinition, type VM } from './gondolin-loader.js';
+import type { PiExecOptions, PiExecResult, PiExecutionEnv, PiExecutionError, PiFileError, PiFileInfo, PiResult } from './pi-execution-env.js';
+/** The single RW mount point inside the guest — the ONLY writable location. */
+export declare const GONDOLIN_WORKSPACE_ROOT: "/workspace";
+/**
+ * The injectable factory the {@link createGondolinExecutionEnv} uses to obtain
+ * the gondolin module. Defaults to the real lazy {@link loadGondolin}; unit
+ * tests inject a fake that returns a MOCK module so NO real QEMU VM is launched.
+ */
+export type GondolinLoader = () => Promise<GondolinModule | null>;
+/** Construction options for {@link createGondolinExecutionEnv}. */
+export interface CreateGondolinExecutionEnvOptions {
+    /**
+     * The host directory mounted RW at `/workspace` inside the guest. This MUST be
+     * a DISPOSABLE seeded copy (e.g. a `VACUUM INTO` snapshot dir) — NEVER a path
+     * containing the live `.cleo/tasks.db` / `.cleo/brain.db`. The factory mounts
+     * ONLY this directory; live DBs are structurally absent from the guest VFS.
+     */
+    readonly seededCopyDir: string;
+    /**
+     * Outbound host allowlist. Defaults to `[]` (DENY ALL) when omitted — the
+     * egress footgun guard. The loop appends ONLY the specific hosts it needs
+     * (e.g. the model endpoint via the Vault proxy) per run.
+     */
+    readonly allowedHosts?: readonly string[];
+    /**
+     * Host-side secret injections. The guest only ever sees each entry's
+     * `placeholder`; the real `value` bytes never enter the VM.
+     */
+    readonly vaultSecrets?: Readonly<Record<string, SecretDefinition>>;
+    /** Guest memory bound (e.g. `"1G"`). Defaults to {@link DEFAULT_GUEST_MEMORY}. */
+    readonly memory?: string;
+    /**
+     * Guest environment — the ONLY env the guest sees (host `process.env` is NEVER
+     * inherited; that isolation is structural). Defaults to an empty map.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Optional loader override (tests inject a fake → a MOCK VM, no QEMU). Defaults
+     * to the real {@link loadGondolin}.
+     */
+    readonly load?: GondolinLoader;
+}
+/**
+ * A {@link PiExecutionEnv} whose confinement is a gondolin micro-VM. Owns exactly
+ * ONE {@link VM} and releases it in {@link cleanup} via `vm.close()`.
+ *
+ * Every fs op maps to `vm.fs.*`; `exec` maps to `vm.exec`. Each call is wrapped
+ * try/catch → {@link PiResult} `err`, so no method ever throws. A thin in-guest
+ * deny layer (lexical `/workspace` confinement + the {@link DENIED_EXEC_PREFIXES}
+ * command denylist) is the defense-in-depth net BEHIND the VM boundary.
+ *
+ * Unlike the stateless {@link import('./pi-execution-env.js').GuardedExecutionEnv}
+ * (whose `cleanup()` is a no-op), this env OWNS the VM and MUST release it.
+ * `cleanup()` is idempotent (guarded by a `#closed` flag).
+ */
+export declare class GondolinExecutionEnv implements PiExecutionEnv {
+    #private;
+    /**
+     * @param vm - The booted gondolin VM this env owns. Construct via
+     *   {@link createGondolinExecutionEnv}, not directly — the factory wires the
+     *   deny-by-default egress hooks + seeded-copy-only mount set.
+     */
+    constructor(vm: VM);
+    /** The guest workspace root — the in-VM Pi run's working directory. */
+    cwd(): string;
+    /** Resolve `path` to a guest-absolute path anchored at `/workspace`. */
+    absolutePath(path: string): string;
+    /** Join path segments (pure POSIX) anchored at the guest workspace root. */
+    joinPath(...segments: string[]): string;
+    /** Read a file's text from the guest workspace. */
+    readTextFile(path: string): Promise<PiResult<string, PiFileError>>;
+    /** Read a file's text as an array of lines. */
+    readTextLines(path: string): Promise<PiResult<string[], PiFileError>>;
+    /**
+     * Binary read — FILLS S1's v0 denial. The guest VFS supports binary reads
+     * directly via `vm.fs.readFile(p)` (returns a `Uint8Array`).
+     */
+    readBinaryFile(path: string): Promise<PiResult<Uint8Array, PiFileError>>;
+    /** Write a file to the guest workspace. */
+    writeFile(path: string, content: string): Promise<PiResult<void, PiFileError>>;
+    /**
+     * Append to a file. The guest fs surface offers only whole-file writes, so this
+     * reads-then-writes the concatenation (still confined). A missing file is
+     * treated as empty (append-creates).
+     */
+    appendFile(path: string, content: string): Promise<PiResult<void, PiFileError>>;
+    /** Report whether a guest path is a file or directory. */
+    fileInfo(path: string): Promise<PiResult<PiFileInfo, PiFileError>>;
+    /** Whether a guest path exists. */
+    exists(path: string): Promise<PiResult<boolean, PiFileError>>;
+    /**
+     * Canonicalize a guest path via `realpath` inside the guest. Runs the binary in
+     * ARRAY form (no `$PATH` / shell expansion) so the path argument cannot be
+     * reinterpreted as shell.
+     */
+    canonicalPath(path: string): Promise<PiResult<string, PiFileError>>;
+    /** List a guest directory — FILLS S1's v0 denial. */
+    listDir(path: string): Promise<PiResult<string[], PiFileError>>;
+    /** Create a guest directory (recursive) — FILLS S1's v0 denial. */
+    createDir(path: string): Promise<PiResult<void, PiFileError>>;
+    /** Remove a guest path (recursive, force) — FILLS S1's v0 denial. */
+    remove(path: string): Promise<PiResult<void, PiFileError>>;
+    /**
+     * Create a temp directory under `/workspace/.tmp` — FILLS S1's v0 denial. Runs
+     * `mktemp -d` in ARRAY form (no `$PATH` / shell expansion).
+     */
+    createTempDir(prefix?: string): Promise<PiResult<string, PiFileError>>;
+    /**
+     * Create a temp file under `/workspace/.tmp` — FILLS S1's v0 denial. Runs
+     * `mktemp` in ARRAY form (no `$PATH` / shell expansion).
+     */
+    createTempFile(prefix?: string): Promise<PiResult<string, PiFileError>>;
+    /**
+     * Execute a command in the guest via `vm.exec`. Deny-first: a real-egress verb
+     * ({@link DENIED_EXEC_PREFIXES} — `gh` / `git push` / `npm publish` / `cleo` /
+     * `git remote`) is rejected BEFORE reaching the VM, even though the VM itself
+     * has no egress (the network namespace is deny-by-default). `cwd` is confined
+     * to the workspace; the host `AbortSignal` is forwarded only when supplied.
+     *
+     * ## exitCode mapping
+     *
+     * gondolin's `ExecResult.exitCode` is `number` (NON-nullable) with a SEPARATE
+     * optional `signal` field; Pi's `PiExecResult.exitCode` is `number | null`
+     * ("null when killed by signal"). So a signal-kill is mapped to `null`, NOT
+     * the raw `exitCode`.
+     */
+    exec(command: string, options?: PiExecOptions): Promise<PiResult<PiExecResult, PiExecutionError>>;
+    /**
+     * Tear down the owned VM (`vm.close()`). Idempotent: a second call is a no-op.
+     * Best-effort and never throws (a close failure is logged, not propagated) so
+     * the Pi contract — `cleanup()` must not throw — holds.
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Thrown by {@link createGondolinExecutionEnv} when the optional
+ * `@earendil-works/gondolin` package (or its QEMU/KVM host infra) is not
+ * available, so a VM cannot be booted. Callers that want graceful degradation
+ * should check `isGondolinAvailable()` first (the selector
+ * {@link import('./resolve-execution-env.js')} does this) and fall back to the
+ * in-process {@link import('./pi-execution-env.js').GuardedExecutionEnv}.
+ */
+export declare class GondolinUnavailableError extends Error {
+    /** Machine-readable code. */
+    readonly code = "E_GONDOLIN_UNAVAILABLE";
+    constructor(message: string);
+}
+/**
+ * Boot a gondolin micro-VM and wrap it in a {@link GondolinExecutionEnv}.
+ *
+ * The VM is configured for ZERO host authority:
+ * - **mount set** = ONLY `{ '/workspace': new RealFSProvider(seededCopyDir) }`.
+ *   The disposable seeded copy is the single RW mount; live `tasks.db`/`brain.db`
+ *   are structurally absent from the guest VFS (T5158 impossible in-VM).
+ * - **egress** = `createHttpHooks({ allowedHosts, secrets })` with `allowedHosts`
+ *   defaulting to `[]` (DENY ALL — the footgun guard) and host-side secret
+ *   PLACEHOLDERS (the guest never sees real token bytes).
+ * - **env** = ONLY `opts.env` (host `process.env` is NEVER inherited).
+ * - **memory** = `opts.memory` (default `"1G"`), set EXPLICITLY.
+ *
+ * Import-time side-effect-free: the gondolin module is loaded lazily HERE (not at
+ * module top-level) via the injectable {@link GondolinLoader} (tests pass a fake
+ * → a MOCK VM, so NO real QEMU boots).
+ *
+ * @param opts - The seeded-copy mount dir + egress allowlist/secrets + guest env.
+ * @returns A {@link PiExecutionEnv} backed by the booted VM.
+ * @throws {GondolinUnavailableError} When the optional package cannot be loaded.
+ *
+ * @example
+ * ```ts
+ * const env = await createGondolinExecutionEnv({ seededCopyDir: snapshotDir });
+ * // ... drive Pi's loop over `env` ...
+ * await env.cleanup(); // releases the VM
+ * ```
+ */
+export declare function createGondolinExecutionEnv(opts: CreateGondolinExecutionEnvOptions): Promise<PiExecutionEnv>;
+//# sourceMappingURL=pi-gondolin-env.d.ts.map

package/dist/llm/pi/pi-gondolin-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-gondolin-env.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-gondolin-env.ts"],"names":[],"mappings":"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"}