@coryrylan/cradle 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+## 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cory Rylan 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# cradle
+
+![CI Build](https://github.com/coryrylan/cradle/actions/workflows/pull-request.yml/badge.svg)
+
+A runtime for portable agents defined as folders. `cradle start <dir>` reads an agent folder — an `APPEND_SYSTEM.md` plus optional pi-native config, skills, extensions, and sandbox posture — and launches the [pi](https://github.com/earendil-works/pi-mono) coding agent configured from it. An agent declaring `sandbox/nono.json` runs inside the [nono](https://github.com/always-further/nono) filesystem sandbox. See [ARCHITECTURE.md](../../ARCHITECTURE.md) for the folder format and [`examples/hello`](../../examples/hello) for a minimal agent. Built with Bun and TypeScript; install the standalone binary via `install.sh` (primary) or the npm package [`@coryrylan/cradle`](https://www.npmjs.com/package/@coryrylan/cradle) (alternative).
+
+## Dependencies
+
+`cradle` drives external tools rather than bundling them. Run `cradle doctor` to check what's on your PATH.
+
+| Tool                                              | Status          | Why                                                                                                                                                                                                                                                  |
+| ------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`pi`](https://github.com/earendil-works/pi-mono) | **Required**    | The coding agent cradle launches. Every `cradle start` spawns it.                                                                                                                                                                                    |
+| [`nono`](https://github.com/always-further/nono)  | **Recommended** | The filesystem sandbox pi runs inside for a sandboxed run — a folder declaring `sandbox/nono.json`, or `--sandbox`/`--offline`/`--allow-host`; required for that run, not needed otherwise.                                                          |
+| [`mise`](https://mise.jdx.dev)                    | **Recommended** | The supported way to install and manage `pi` and `nono`. cradle doesn't invoke mise directly, but it falls back to mise's shims when resolving the tools, and the generated sandbox profile grants mise's trees so a sandboxed pi finds its runtime. |
+
+## Installation
+
+Install the standalone binary to `~/.local/bin/cradle` (macOS and Linux; no Bun required to run it):
+
+```bash
+curl -fsSL https://coryrylan.github.io/cradle/install.sh | bash
+```
+
+Or install the npm package — the installed command is still `cradle`, and [Bun](https://bun.sh) must be on your `PATH` to run it:
+
+```bash
+npm install -g @coryrylan/cradle
+```
+
+The install script and binaries are statically deployed with the [docs site](https://coryrylan.github.io/cradle/); from a clone, `bun run install:local` in `projects/cli/` builds and installs the same binary locally.
+
+## Development
+
+Clone the repo and install dependencies:
+
+```bash
+bun install
+```
+
+Run the CLI directly:
+
+```bash
+bun start
+```
+
+## Commands
+
+| Command                   | Description                                                     |
+| ------------------------- | --------------------------------------------------------------- |
+| `bun start`               | Run the CLI via Bun                                             |
+| `bun run build`           | Build ESM bundle, type declarations, and platform binaries      |
+| `bun run test`            | Run tests (no coverage)                                         |
+| `bun run test:coverage`   | Run tests with coverage; enforces thresholds from `bunfig.toml` |
+| `bun run lint`            | Lint this package with ESLint (typescript-eslint strict)        |
+| `bun run format`          | Check formatting with Prettier                                  |
+| `bun run format:fix`      | Auto-fix formatting                                             |
+| `bun run ci`              | Run lint + build + test:coverage (used in CI)                   |
+| `bun run install:local`   | Build and install binary to `~/.local/bin`                      |
+| `bun run uninstall:local` | Remove locally installed binary                                 |
+
+> Knip (unused files / deps / exports) is configured at the monorepo root and runs across all workspaces. From the repo root, run `bun run lint:knip`.
+
+## CLI Usage
+
+```bash
+cradle --version
+cradle doctor                         # check pi (required), nono/mise (recommended) on PATH, with versions
+cradle start ./my-agent               # run an agent folder with pi; sandboxed when sandbox/nono.json exists
+cradle start my-agent                 # run a name from ~/.cradle/settings.json instead of a path
+cradle start . --offline              # block all outbound network (exfil protection)
+cradle start . --allow-host api.z.ai  # restrict network to these hosts (repeatable)
+cradle start . --no-sandbox           # run pi directly (debug)
+cradle start . --dry-run -- --resume  # print the write plan + command; forward `--resume` to pi
+```
+
+The agent runs in _your_ working directory; the agent folder is a parameter (default `.`). Everything after `--` is forwarded verbatim to pi. `--dry-run` prints the generated-extension write plan and the composed command without spawning (and without requiring the bins to be installed). Per-agent state (generated extensions + session history) lives under `~/.cradle/agents/<name>-<hash>/`.
+
+### Global agent aliases (`~/.cradle/settings.json`)
+
+The `dir` positional accepts a bare name instead of a path — `cradle start my-agent` resolves against a global name → folder map, so agent folders you keep far from any project don't need a full path from every cwd:
+
+```json
+{
+  "agents": {
+    "my-agent": { "path": "~/dev/agents/my-agent/" }
+  }
+}
+```
+
+A bare name (no `/`, not `.`/`~`-led) checks the alias table first, falling back to the cwd-relative path (`./my-agent`) when no alias is defined — anything already path-shaped (`./x`, `../x`, `/abs/x`, `~/x`, `.`) is never looked up as an alias. See [ARCHITECTURE.md](../../ARCHITECTURE.md#global-agent-aliases) for the full resolution rules.
+
+Each sandboxed run generates its own nono profile at `~/.cradle/agents/<id>/nono-profile.json` — the built-in base merged with that agent's `sandbox/nono.json` grants — and points `nono run --profile` at it. There's no shared global profile and no separate setup step: an agent's whole sandbox posture lives in its own directory. To widen it (e.g. granting a tool's data dir), add a `sandbox/` folder to the agent with a `nono.json`:
+
+```json
+{
+  "filesystem": {
+    "allow": ["~/.some-tool"]
+  }
+}
+```
+
+### Network policy (`network`)
+
+Outbound network is **open by default within a sandboxed run**. A `network` block in `sandbox/nono.json` tightens it — the keys mirror nono's canonical [`network`](https://nono.sh/docs) profile fields, folded into the generated profile and enforced by nono (a local CONNECT/credential proxy that Seatbelt forces all egress through). Verified enforced on macOS Seatbelt:
+
+```json
+{
+  "network": {
+    "block": false,
+    "allow_domain": ["api.z.ai", "localhost"],
+    "open_port": [11434],
+    "listen_port": [8080]
+  }
+}
+```
+
+| Key               | Effect                                                                                          |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| `block`           | `true` denies **all** outbound (full offline).                                                  |
+| `allow_domain`    | Host allowlist. **Presence flips nono to default-deny** — unlisted hosts are refused (403).     |
+| `open_port`       | localhost TCP ports the agent may connect/bind (e.g. a local model or dev server).              |
+| `listen_port`     | TCP ports the agent may listen on.                                                              |
+| `network_profile` | Named nono network-policy profile (opaque pass-through; requires a host `network-policy.json`). |
+
+An `allow_domain` allowlist blocks localhost too, so a local-model agent must list `localhost`/`127.0.0.1` **and** open its port (see [`examples/hello`](../../examples/hello), locked to Ollama on `localhost:11434`). CLI flags override the folder: `--offline` (full block) and repeatable `--allow-host <host>` (allowlist). Precedence: `--offline` > `--allow-host` > `sandbox/nono.json` > open. Requesting a network policy only means something inside the sandbox, so `--offline`/`--allow-host` force the sandbox on (same as `--sandbox`) unless `--no-sandbox` is passed explicitly, in which case cradle warns `network policy has no effect without the sandbox — pi runs with no network isolation (--sandbox to enforce it)` and nothing is enforced. cradle doesn't echo the resolved posture itself — run with `--verbose` to drop nono's `--silent` flag and see its own capabilities banner (grants + network mode), or read the generated per-agent profile (`nono-profile.json` in the agent's state dir). nono **fails closed** — a malformed `network` key or a platform that can't enforce proxy filtering makes the run refuse to start rather than silently ship an unenforced allowlist.
+
+### macOS Seatbelt escape hatch (`unsafe_macos_seatbelt_rules`)
+
+Some tools need OS capabilities the conservative base profile denies. `sandbox/nono.json` can append raw macOS Seatbelt rules — s-expressions merged verbatim after the base's rules (nono validates the syntax at load). Each one widens the OS sandbox, so audit them where they live: the folder's `sandbox/nono.json` or the generated per-agent profile (`nono-profile.json` in the agent's state dir) — nono's own capabilities banner (shown with `--verbose`) never lists seatbelt rules. Ignored on Linux.
+
+**Browser automation is the motivating case.** [agent-browser](https://agent-browser.dev/) + Chrome for Testing runs sandboxed under nono with exactly two rules plus Chrome's own `--no-sandbox` flag:
+
+```json
+{
+  "filesystem": {
+    "allow": ["~/.agent-browser"]
+  },
+  "unsafe_macos_seatbelt_rules": ["(allow mach-register)", "(allow iokit-open)"]
+}
+```
+
+| Entry                    | Why it's needed                                                                                                                                               |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow ~/.agent-browser` | agent-browser's own state dir — daemon socket, downloaded Chrome, config. Without it the daemon can't create its socket (`Operation not permitted`).          |
+| `(allow mach-register)`  | Chrome's Crashpad handler registers a Mach service (`bootstrap_check_in org.chromium.crashpad.*`); the base profile denies it, so the browser process aborts. |
+| `(allow iokit-open)`     | Chrome opens IOKit user clients during startup even headless; without it the browser process crashes before serving CDP.                                      |
+
+The two rules are IPC/IOKit capabilities only — the filesystem and network boundaries stay intact, so the sandbox still denies an ungranted path (verified: a granted read succeeds, `~/some-secret` returns `Operation not permitted`). No grant for Chrome's own `~/Library/…/Chrome for Testing` dir is needed — its Crashpad-database `stat` failure under the sandbox is non-fatal noise.
+
+Chrome's **own** nested sandbox can't initialize inside nono's seatbelt (macOS forbids nesting), so its child processes need `--no-sandbox`. Deliver it through a pi extension rather than a shell env var — an extension travels with the agent folder and pi propagates it into every tool's env regardless of how the extension itself set it. The simplest is a one-line agent extension:
+
+```ts
+// extensions/browser-sandbox.ts — set the flag before agent-browser launches Chrome
+process.env.AGENT_BROWSER_ARGS ??= '--no-sandbox';
+```
+
+(Or pass `agent-browser --args --no-sandbox` on each call.) See [`examples/browser`](../../examples/browser) for the complete folder.
+
+An agent that still cannot run sandboxed can declare `{ "sandbox": false }` instead. cradle then runs pi bare, warns loudly on every run, and an explicit `--sandbox` flag always forces isolation back on.
+
+## Build Targets
+
+The build produces platform-specific standalone binaries in `dist/`:
+
+- `cradle-macos-arm64`
+- `cradle-macos-x64`
+- `cradle-linux-x64`
+- `cradle-linux-arm64`
+- `cradle-windows-x64.exe`
+
+## License
+
+MIT

package/dist/agent/aliases.d.ts

@@ -0,0 +1,19 @@
+export interface ResolveRefDeps {
+    readonly home: string;
+    readonly cwd: string;
+}
+/**
+ * Resolve a `cradle start` ref into a folder path `loadAgentFolder` can load.
+ * Path-shaped refs pass through untouched (`loadAgentFolder`'s own `resolve()`
+ * handles them, and they never consult `deps.cwd`); a bare name resolves
+ * against the global alias table into an ABSOLUTE, normalized path, falling
+ * back to the cwd-relative folder when no alias matches (so `cradle start
+ * hello` from `examples/` keeps working) — and throwing only when neither
+ * resolves. Every bare-name branch resolves against the injected `deps.cwd`,
+ * never `process.cwd()`, so the dep is the single source of truth for what the
+ * lookup tested.
+ */
+export declare function resolveAgentRef(ref: string, deps: ResolveRefDeps): Promise<{
+    dir: string;
+    warnings: readonly string[];
+}>;

package/dist/agent/extensions/providers.d.ts

@@ -0,0 +1 @@
+export declare function emitProvidersExtension(providersJson: string): string;

package/dist/agent/folder.d.ts

@@ -0,0 +1,76 @@
+import { type NpmPackageSpec } from './packages.js';
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+export interface AgentSettings {
+    readonly defaultProvider?: string;
+    readonly defaultModel?: string;
+    readonly defaultThinkingLevel?: ThinkingLevel;
+    /** Parsed `npm:` package sources from settings.json's `packages` key — see `./packages.js`. */
+    readonly packages?: readonly NpmPackageSpec[];
+    /**
+     * Installer argv from settings.json's `npmCommand`; `["npm"]` when absent.
+     * Always exactly one of `npm`/`pnpm`/`yarn`/`bun` — see `readNpmCommand`.
+     */
+    readonly npmCommand?: readonly string[];
+}
+export interface AgentSandboxGrants {
+    readonly read: readonly string[];
+    readonly write: readonly string[];
+    readonly allow: readonly string[];
+}
+/**
+ * The agent's declared network posture — a curated subset of nono's profile
+ * `network` block, using nono's CANONICAL key names (not the `proxy_allow` /
+ * `port_allow` legacy aliases). Folded verbatim into the generated per-agent
+ * profile by `nono/profiles.ts`, where nono is the enforcement authority:
+ * `allow_domain` presence flips nono to default-deny proxy filtering, and nono
+ * fails closed (refuses to run) on an unenforceable platform or a bad key —
+ * cradle never has to synthesize a fallback. Absent entirely ⇒ nono default
+ * (open network), preserving the old `net: "allow"` behavior.
+ */
+export interface AgentNetwork {
+    /** Deny all outbound (replaces the old `net: "block"`). */
+    readonly block?: boolean;
+    /** Named nono network-policy profile (host `network-policy.json`); opaque pass-through. */
+    readonly networkProfile?: string;
+    /** Outbound host allowlist — hostnames/IPs. Presence ⇒ nono default-denies unlisted hosts. */
+    readonly allowDomain?: readonly string[];
+    /** localhost TCP ports the child may connect+bind (local IPC / dev servers). */
+    readonly openPort?: readonly number[];
+    /** TCP ports the child may listen on. */
+    readonly listenPort?: readonly number[];
+}
+export type AgentSandboxPosture = 'unconfigured' | 'enabled' | 'disabled';
+export interface AgentSandbox {
+    /**
+     * The folder's declared sandbox posture. `'unconfigured'` when the folder has
+     * no `sandbox/nono.json`; otherwise mirrors the file's `sandbox` key
+     * (absent ⇒ `'enabled'`).
+     */
+    readonly posture: AgentSandboxPosture;
+    readonly network?: AgentNetwork;
+    readonly filesystem: AgentSandboxGrants;
+    /**
+     * Raw macOS Seatbelt s-expression rules from `sandbox/nono.json`'s
+     * `unsafe_macos_seatbelt_rules`, merged verbatim after the base profile's
+     * rules (see nono/profiles.ts). The escape hatch a browser agent uses to let
+     * Chrome register its crashpad Mach service and open IOKit — capabilities the
+     * default profile denies. Named "unsafe" because each rule widens the OS
+     * sandbox; nono's startup banner does not list seatbelt rules, so review a
+     * folder's `sandbox/nono.json` or the generated profile to audit them.
+     */
+    readonly unsafeMacosSeatbeltRules: readonly string[];
+}
+export interface AgentFolder {
+    readonly dir: string;
+    /** Abs path of APPEND_SYSTEM.md — appended to pi's system prompt via `--append-system-prompt`. */
+    readonly appendSystemFilePath: string;
+    readonly settings: AgentSettings;
+    /** Serialized `providers` object from models.json, `null` when absent. */
+    readonly providersJson: string | null;
+    readonly skillsDir: string | null;
+    /** pi-native extensions (top-level `extensions/*.ts` plus each subdir's `index.ts`), absolute paths. */
+    readonly extensionFiles: readonly string[];
+    readonly sandbox: AgentSandbox;
+    readonly warnings: readonly string[];
+}
+export declare function loadAgentFolder(dir: string): Promise<AgentFolder>;

package/dist/agent/launch.d.ts

@@ -0,0 +1,108 @@
+import type { AgentFolder } from './folder.js';
+export interface LaunchSpec {
+    readonly folder: AgentFolder;
+    readonly stateDir: string;
+    /**
+     * Where the generated providers extension is written (see
+     * `folder.providersJson`) and where `--session-dir` points, sourced from the
+     * plan's own `extensionsDir`/`sessionsDir` (`commands/start.ts` — the single
+     * derivation site; re-deriving from `stateDir` here risks silently
+     * disagreeing with a plan whose dirs were overridden after `planStart`).
+     */
+    readonly extensionsDir: string;
+    readonly sessionsDir: string;
+    /**
+     * Where sandboxed runs point `MISE_CACHE_DIR` (see `composeEnv`), sourced
+     * from the plan's `statePaths` derivation like `extensionsDir`/`sessionsDir`.
+     */
+    readonly miseCacheDir: string;
+    readonly sandbox: boolean;
+    readonly passthrough: readonly string[];
+    /** Resolved path, or bare `nono` for dry-run previews. */
+    readonly nonoBin: string;
+    /**
+     * Resolved path (mise-shim fallback included, see `util/which.ts`), or bare
+     * `pi` for dry-run previews. Used consistently whether or not the run is
+     * sandboxed — the generated profile already grants read on the mise install
+     * tree (see `nono/cradle-pi.json`), so the absolute path resolves inside the
+     * sandbox too; a bare `pi` only resolves on whatever PATH the spawning
+     * process happens to have, which is exactly the gap a fresh mise-only
+     * install falls into.
+     */
+    readonly piBin: string;
+    /** Abs path of the generated per-agent nono profile; used only when `sandbox` is true. */
+    readonly profilePath: string;
+    /**
+     * When true, nono runs without `--silent` so its capabilities banner
+     * (effective grants + network disclosure) prints; default is silent — the
+     * generated profile file and `--verbose` are the audit surfaces.
+     */
+    readonly verbose?: boolean;
+    /**
+     * Abs paths of the pi extension entry files resolved from settings.json's
+     * `packages` (see `./packages.js`), installed into `<stateDir>/npm` by
+     * `commands/start.ts`. Absent/empty on the argv-only preview used for
+     * `--dry-run` (packages resolve at install time, after the preview is
+     * printed) and on folders that declare no packages.
+     */
+    readonly packageEntries?: readonly string[];
+}
+/**
+ * Build the bare pi argv. `passthrough` lands last so user-passed flags win
+ * under pi's last-wins parsing. The `-e` order is load-bearing: the generated
+ * providers extension goes first, then the resolved package entries, then the
+ * agent's own `extensions/` files — which load with the agent's providers
+ * registered and any package-provided tools already available, since the
+ * agent's own extensions may depend on them.
+ */
+export declare function composePiArgv(spec: LaunchSpec): string[];
+/**
+ * Compose the spawn env for a sandboxed run: `{ MISE_CACHE_DIR: spec.miseCacheDir }`;
+ * `{}` when unsandboxed.
+ *
+ * The generated profile denies the shared `~/Library/Caches/mise` on purpose
+ * — a poisoned `bin_paths` cache would redirect which binaries the user's
+ * later UNSANDBOXED mise execs resolve to, invisibly and machine-globally.
+ * Without this override, every sandboxed `mise exec` spams `mise WARN failed
+ * to write cache file` because it can't write there. Pointing `MISE_CACHE_DIR`
+ * at a private cache inside the already-granted state dir instead lets mise
+ * cache writes succeed (no warnings, working cache) while the shared host
+ * cache stays untouched; mise creates the directory itself, cradle never
+ * pre-creates or wipes it. Unsandboxed runs return `{}` and keep the shared
+ * host cache — no override needed since there's no sandbox denial to work
+ * around.
+ *
+ * This deliberately overrides any user-set `MISE_CACHE_DIR` for sandboxed
+ * runs — the profile wouldn't grant a custom location either, so honoring one
+ * would just trade the warning spam for a silent cache-write failure. It is
+ * also cradle's single exception to argv-only composition (see the module
+ * header and `ARCHITECTURE.md`'s "Why argv" section): this configures mise,
+ * not pi, so it doesn't touch the argv-survives-sandboxing rationale that
+ * motivates keeping pi's own configuration on argv. The failure mode if this
+ * env var were ever stripped is benign — mise falls back to the shared cache
+ * and the warnings return, nothing breaks.
+ */
+export declare function composeEnv(spec: LaunchSpec): Record<string, string>;
+/**
+ * Build the argv for `nono run … -- pi …`, or the bare pi argv when
+ * sandboxing is disabled (`--no-sandbox`).
+ *
+ * All filesystem grants (cwd, agent dir, state dir, and the agent's own
+ * `sandbox/nono.json` entries) AND the network posture live inside the
+ * generated per-agent profile at `spec.profilePath` — see `nono/profiles.ts`.
+ * The wrapper is `nono run --silent --profile <file>` by default (silent mode
+ * suppresses nono's startup banner); `--verbose` omits `--silent` to show the
+ * capabilities banner, and cradle prints `🔒 Sandbox Active` on silent runs.
+ * No per-flag network posture — it all lives in the profile.
+ *
+ * Both `spec.nonoBin` and `spec.piBin` are resolved paths (mise-shim fallback
+ * included), never bare names: cradle spawns `nonoBin` directly, and a
+ * freshly mise-installed nono may not be on PATH yet; `piBin` is passed
+ * through to nono as plain argv (`-- <piBin> …`), and nono execs it *inside*
+ * the sandbox, where the resolved absolute path resolves fine against the
+ * mise install tree the base profile already grants read on (see
+ * `nono/cradle-pi.json`) — no PATH lookup needed either side of the sandbox
+ * boundary. nono guarantees child processes inherit the sandbox, so pi
+ * spawning its own subprocesses is covered too.
+ */
+export declare function composeArgv(spec: LaunchSpec): string[];

package/dist/agent/packages.d.ts

@@ -0,0 +1,28 @@
+import { type JsonValue } from '../setup/utils.js';
+/** A parsed `npm:<name>[@<version>]` package source from settings.json's `packages` key. */
+export interface NpmPackageSpec {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Parse a settings.json record's `packages` key into validated npm: package
+ * specs. Only `npm:` sources are supported — pi also accepts `git:`,
+ * `https://`, `ssh://`, and local paths, all warned and dropped here, since
+ * cradle installs the package itself rather than delegating to pi's loader.
+ */
+export declare function readPackageSpecs(record: {
+    readonly [key: string]: JsonValue;
+}, path: string, warnings: string[]): readonly NpmPackageSpec[];
+/** Deterministic npm manifest for a per-agent packages install, dependencies sorted by name. */
+export declare function emitPackagesManifest(specs: readonly NpmPackageSpec[]): string;
+/**
+ * Resolve each spec's installed package into pi extension entry files, ready
+ * to pass as explicit `-e` flags. Every failure (not installed, malformed
+ * manifest, an entry that escapes the package directory, a missing entry
+ * file, no declared extensions) is a warning + skip — packages are
+ * warn-don't-throw like every other agent-folder input.
+ */
+export declare function resolvePackageEntries(npmDir: string, specs: readonly NpmPackageSpec[]): Promise<{
+    entries: string[];
+    warnings: string[];
+}>;

package/dist/agent/state.d.ts

@@ -0,0 +1,10 @@
+export interface StatePaths {
+    readonly extensionsDir: string;
+    readonly sessionsDir: string;
+    readonly miseCacheDir: string;
+}
+/** Stable, readable id for an agent folder: sanitized basename + 8-hex path hash. */
+export declare function agentId(absDir: string): string;
+/** Where an agent's runtime state lives. Override the root via `CRADLE_STATE_DIR` (or the `stateRoot` param). */
+export declare function stateDirFor(absDir: string, home?: string, stateRoot?: string | undefined): string;
+export declare function statePaths(stateDir: string): StatePaths;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/commands/doctor.d.ts

@@ -0,0 +1,25 @@
+import { type WhichFn } from '../util/which.js';
+export interface DoctorCheck {
+    readonly name: string;
+    readonly bin: string;
+    readonly required: boolean;
+    readonly found: string | null;
+    readonly version: string | null;
+    readonly note?: string;
+}
+interface DoctorDeps {
+    readonly which?: WhichFn;
+    /** Read a bin's `--version` output; injected so in-process tests never spawn. */
+    readonly readVersion?: (binPath: string) => Promise<string | null>;
+}
+/**
+ * Probe the environment cradle depends on: `pi` (always required), `nono`
+ * (required for sandboxed runs — a folder declaring sandbox/nono.json, or
+ * --sandbox/--offline/--allow-host; not needed otherwise), and `mise`
+ * (recommended toolchain manager).
+ */
+export declare function runDoctor(deps?: DoctorDeps): Promise<DoctorCheck[]>;
+export declare function formatDoctorReport(checks: readonly DoctorCheck[]): string;
+/** Exit non-zero when any required dependency is missing. */
+export declare function doctorExitCode(checks: readonly DoctorCheck[]): number;
+export {};

package/dist/commands/start.d.ts

@@ -0,0 +1,94 @@
+import { type LaunchSpec } from '../agent/launch.js';
+import { type NpmPackageSpec } from '../agent/packages.js';
+import { type TreeFile } from '../setup/install.js';
+import { type WhichFn } from '../util/which.js';
+export interface StartFlags {
+    readonly dir: string;
+    /** `--offline` → full network block. Overrides the folder network posture and forces the sandbox on (unless --no-sandbox). */
+    readonly offline?: boolean;
+    /** `--allow-host` (repeatable) → network host allowlist. Overrides the folder allowlist and forces the sandbox on (unless --no-sandbox). */
+    readonly allowHost?: readonly string[];
+    /** Explicit CLI choice: `--no-sandbox` → true, `--sandbox` → false. Absent = defer to the folder. */
+    readonly noSandbox?: boolean;
+    readonly dryRun?: boolean;
+    readonly passthrough?: readonly string[];
+    /** `--verbose` → show nono's full sandbox capabilities banner instead of the one-line status. */
+    readonly verbose?: boolean;
+}
+interface StartDeps {
+    readonly cwd?: string;
+    readonly home?: string;
+    readonly which?: WhichFn;
+}
+/**
+ * The agent's settings.json `packages` resolved into a per-agent npm install
+ * plan. `npmDir` is a private npm project under the agent's state dir — never
+ * the folder itself, so the install stays out of the portable, committable
+ * agent folder.
+ */
+export interface PackagesPlan {
+    readonly npmDir: string;
+    /** `emitPackagesManifest` output — the package.json cradle writes into `npmDir`. */
+    readonly manifest: string;
+    readonly specs: readonly NpmPackageSpec[];
+    /**
+     * `[...(settings.npmCommand ?? ['npm']), 'install', '--ignore-scripts']`.
+     * This install runs on the host, unsandboxed, before the sandbox spawns —
+     * `--ignore-scripts` stops a folder-declared package's postinstall from
+     * running arbitrary host code (`npmCommand` is validated upstream to a
+     * single-element allowlist of `npm`/`pnpm`/`yarn`/`bun`, all of which accept
+     * this flag).
+     */
+    readonly installCommand: readonly string[];
+}
+export interface StartPlan {
+    /** Generated extensions, relative to `extensionsDir`. */
+    readonly files: readonly TreeFile[];
+    /**
+     * Authoritative — the single derivation site for where generated extensions
+     * and sessions live. `materializeStart` re-asserts these onto `launch`
+     * before composing the final argv, so overriding either here (as tests do)
+     * changes the composed argv accordingly instead of silently disagreeing
+     * with whatever `launch` had baked in at `planStart` time.
+     */
+    readonly extensionsDir: string;
+    readonly sessionsDir: string;
+    readonly warnings: readonly string[];
+    /** The generated per-agent nono profile to write before spawning; `null` on unsandboxed runs (no profile needed). */
+    readonly profile: {
+        readonly path: string;
+        readonly content: string;
+    } | null;
+    /** Settings.json `packages` resolved into an install plan; `null` when the folder declares none. */
+    readonly packages: PackagesPlan | null;
+    /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeStart` recomposes it with resolved package entries. */
+    readonly launch: LaunchSpec;
+    readonly dryRun: boolean;
+}
+/**
+ * Resolve the ref (bare alias name or path — see `../agent/aliases.js`), load
+ * the agent folder, and compose the launch. Returns a plan; the caller
+ * decides whether to print it (`--dry-run`) or materialize + spawn it.
+ *
+ * `--dry-run` only previews, so it deliberately skips the bin checks — you can
+ * compose a command before nono/pi are installed.
+ */
+export declare function planStart(flags: StartFlags, deps?: StartDeps): Promise<StartPlan>;
+export interface MaterializeDeps {
+    /** Runs a package install (e.g. `npm install`) in `cwd`; `cli.ts` always passes `runInstall` from `util/proc.js`. */
+    readonly install?: (command: readonly string[], cwd: string) => Promise<void>;
+}
+/**
+ * Write the generated extensions (replacing stale ones), ensure the sessions
+ * dir, and — on sandboxed runs — (re)write the generated per-agent nono profile
+ * that `nono run --profile` points at. When the folder declares `packages`,
+ * also (re)install the per-agent npm project and resolve each package's pi
+ * extension entries, returning the final argv with those entries appended as
+ * `-e` flags plus any resolution warnings; otherwise the plan's argv is
+ * already final.
+ */
+export declare function materializeStart(plan: StartPlan, deps?: MaterializeDeps): Promise<{
+    argv: string[];
+    warnings: string[];
+}>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import './cli.js';