@geohar/un-bien 0.7.0

package/dist/daemon/registry.d.ts

@@ -0,0 +1,63 @@
+export interface DaemonEntry {
+    /** Absolute realpath of the cwd this daemon manages. */
+    cwd: string;
+    /**
+     * Display name (mesh `agent_name`). Persisted here because the supervisor
+     * now injects the daemon's config via `UNBIEN_DIRECT_CONFIG` at spawn
+     * instead of reading a per-cwd `.pi/un-bien/config.json`. Legacy entries
+     * (cwd only) fall back to `defaultAgentName(cwd)`.
+     */
+    name?: string;
+}
+export interface DaemonRegistry {
+    daemons: DaemonEntry[];
+}
+/**
+ * Normalizes a user-provided path: expands `~`/`~/...`, resolves relative
+ * components against `process.cwd()`, and runs `realpath` to canonicalize
+ * symlinks. Throws if the resulting path doesn't exist on disk.
+ *
+ * `/unbien create` always stores normalized paths so two registrations
+ * of the same logical folder via different aliases produce a single entry.
+ */
+export declare function normalizeCwd(input: string): string;
+/** Reads the registry, returning an empty one when the file is absent. */
+export declare function loadRegistry(): DaemonRegistry;
+export declare function saveRegistry(reg: DaemonRegistry): void;
+/**
+ * Adds a daemon entry. Refuses duplicates (same normalized cwd already
+ * present). Returns the derived id + normalized cwd so the caller can
+ * report it back to the user.
+ */
+export declare function addDaemon(rawCwd: string, name?: string): {
+    id: string;
+    cwd: string;
+    name: string;
+};
+/**
+ * Removes the daemon entry whose derived id matches `id`. Returns the
+ * removed cwd (if any). Does NOT touch the cwd's local config — `create`
+ * the same cwd later restores the registration idempotently.
+ */
+export declare function removeDaemon(id: string): {
+    removed: boolean;
+    cwd?: string;
+};
+/** Snapshot of all registered daemons with derived ids. Order matches the
+ *  file's insertion order — first-registered first. */
+export declare function listDaemons(): Array<{
+    id: string;
+    cwd: string;
+    name: string;
+}>;
+/**
+ * One-shot migration: backfill `name` (folder-derived) into legacy entries
+ * that predate the name field, persisting the change to `daemons.json`.
+ * Idempotent — writes only when something was missing. Returns how many
+ * entries were backfilled. The supervisor runs this on start.
+ */
+export declare function migrateRegistryNames(): number;
+/** Test/diag-only: returns the on-disk path. Exported so tests can poke
+ *  at it (e.g. tmpdir override is done via env, but for now the path is
+ *  hardcoded to ~/.pi/un-bien/daemons.json). */
+export declare function registryPath(): string;

package/dist/daemon/registry.js

@@ -0,0 +1,153 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
+import { daemonIdForCwd } from "./id.js";
+import { defaultAgentName } from "../session/local_config.js";
+import { unbienStateHome } from "../paths.js";
+/**
+ * The global daemon registry: which working directories are promoted to
+ * always-on daemons under the supervisor.
+ *
+ * Schema rationale (decision Q in plan/26): the registry stores **only**
+ * `cwd` per entry. Everything else (agent_name, auto_start_relay, etc.)
+ * is the cwd's local config at `<cwd>/.pi/un-bien/config.json` — single
+ * source of truth, no duplication. The daemon `id` is *derived* from cwd
+ * via `daemonIdForCwd`, never persisted.
+ *
+ * Cwds are always normalized to an **absolute realpath** before storage.
+ * A user typing `/unbien create ~/Movies` or `/unbien create .`
+ * results in the same entry as `/unbien create /Users/x/Movies` — no
+ * surprise duplicates, symlinks collapse correctly.
+ */
+/** Resolved at call time so tests can override via `UNBIEN_HOME`. The
+ *  prod path is always `~/.pi/un-bien/daemons.json`. */
+function registryPathInternal() {
+    return join(unbienStateHome(), "daemons.json");
+}
+/**
+ * Normalizes a user-provided path: expands `~`/`~/...`, resolves relative
+ * components against `process.cwd()`, and runs `realpath` to canonicalize
+ * symlinks. Throws if the resulting path doesn't exist on disk.
+ *
+ * `/unbien create` always stores normalized paths so two registrations
+ * of the same logical folder via different aliases produce a single entry.
+ */
+export function normalizeCwd(input) {
+    if (!input || !input.trim()) {
+        throw new Error("cwd is required");
+    }
+    let p = input.trim();
+    // Expand `~` / `~/relative`. Shell wouldn't expand inside slash command args.
+    if (p === "~")
+        p = homedir();
+    else if (p.startsWith("~/"))
+        p = join(homedir(), p.slice(2));
+    if (!isAbsolute(p))
+        p = resolvePath(process.cwd(), p);
+    // realpath canonicalizes symlinks + throws if path doesn't exist.
+    return realpathSync(p);
+}
+/** Reads the registry, returning an empty one when the file is absent. */
+export function loadRegistry() {
+    if (!existsSync(registryPathInternal()))
+        return { daemons: [] };
+    try {
+        const raw = readFileSync(registryPathInternal(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return { daemons: [] };
+        const arr = parsed.daemons;
+        if (!Array.isArray(arr))
+            return { daemons: [] };
+        const daemons = [];
+        for (const item of arr) {
+            if (!item || typeof item !== "object")
+                continue;
+            const cwd = item.cwd;
+            if (typeof cwd === "string" && cwd.length > 0) {
+                const rawName = item.name;
+                const entry = { cwd };
+                if (typeof rawName === "string" && rawName.length > 0)
+                    entry.name = rawName;
+                daemons.push(entry);
+            }
+        }
+        return { daemons };
+    }
+    catch {
+        return { daemons: [] };
+    }
+}
+export function saveRegistry(reg) {
+    mkdirSync(dirname(registryPathInternal()), { recursive: true });
+    writeFileSync(registryPathInternal(), JSON.stringify(reg, null, 2) + "\n");
+}
+/**
+ * Adds a daemon entry. Refuses duplicates (same normalized cwd already
+ * present). Returns the derived id + normalized cwd so the caller can
+ * report it back to the user.
+ */
+export function addDaemon(rawCwd, name) {
+    const cwd = normalizeCwd(rawCwd);
+    const reg = loadRegistry();
+    if (reg.daemons.some((d) => d.cwd === cwd)) {
+        throw new Error(`Daemon already registered for cwd: ${cwd}`);
+    }
+    // Always persist a name (the registry is the source of truth now that the
+    // supervisor injects config via env instead of a local config file).
+    const resolvedName = name?.trim() || defaultAgentName(cwd);
+    reg.daemons.push({ cwd, name: resolvedName });
+    saveRegistry(reg);
+    return { id: daemonIdForCwd(cwd), cwd, name: resolvedName };
+}
+/**
+ * Removes the daemon entry whose derived id matches `id`. Returns the
+ * removed cwd (if any). Does NOT touch the cwd's local config — `create`
+ * the same cwd later restores the registration idempotently.
+ */
+export function removeDaemon(id) {
+    const reg = loadRegistry();
+    const idx = reg.daemons.findIndex((d) => daemonIdForCwd(d.cwd) === id);
+    if (idx === -1)
+        return { removed: false };
+    const [removed] = reg.daemons.splice(idx, 1);
+    saveRegistry(reg);
+    return { removed: true, cwd: removed.cwd };
+}
+/** Snapshot of all registered daemons with derived ids. Order matches the
+ *  file's insertion order — first-registered first. */
+export function listDaemons() {
+    return loadRegistry().daemons.map((d) => ({
+        id: daemonIdForCwd(d.cwd),
+        cwd: d.cwd,
+        // Legacy entries (cwd only) fall back to the folder-derived name so a
+        // daemon is never nameless. New entries already carry an explicit name.
+        name: d.name ?? defaultAgentName(d.cwd),
+    }));
+}
+/**
+ * One-shot migration: backfill `name` (folder-derived) into legacy entries
+ * that predate the name field, persisting the change to `daemons.json`.
+ * Idempotent — writes only when something was missing. Returns how many
+ * entries were backfilled. The supervisor runs this on start.
+ */
+export function migrateRegistryNames() {
+    const reg = loadRegistry();
+    let changed = 0;
+    for (const d of reg.daemons) {
+        if (!d.name) {
+            d.name = defaultAgentName(d.cwd);
+            changed++;
+        }
+    }
+    if (changed > 0)
+        saveRegistry(reg);
+    return changed;
+}
+/** Test/diag-only: returns the on-disk path. Exported so tests can poke
+ *  at it (e.g. tmpdir override is done via env, but for now the path is
+ *  hardcoded to ~/.pi/un-bien/daemons.json). */
+export function registryPath() {
+    return registryPathInternal();
+}
+//# sourceMappingURL=registry.js.map

package/dist/daemon/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/daemon/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AAEH;wDACwD;AACxD,SAAS,oBAAoB;IAC3B,OAAO,IAAI,CAAC,eAAe,EAAE,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC;AAkBD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACrB,8EAA8E;IAC9E,IAAI,CAAC,KAAK,GAAG;QAAE,CAAC,GAAG,OAAO,EAAE,CAAC;SACxB,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IACtD,kEAAkE;IAClE,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,oBAAoB,EAAE,EAAE,MAAM,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAClE,MAAM,GAAG,GAAI,MAAgC,CAAC,OAAO,CAAC;QACtD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAChD,MAAM,OAAO,GAAkB,EAAE,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAChD,MAAM,GAAG,GAAI,IAA0B,CAAC,GAAG,CAAC;YAC5C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9C,MAAM,OAAO,GAAI,IAA2B,CAAC,IAAI,CAAC;gBAClD,MAAM,KAAK,GAAgB,EAAE,GAAG,EAAE,CAAC;gBACnC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;oBACnD,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC;gBACvB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAmB;IAC9C,SAAS,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,aAAa,CAAC,oBAAoB,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,IAAa;IAEb,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,0EAA0E;IAC1E,qEAAqE;IACrE,MAAM,YAAY,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC3D,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IAC9C,YAAY,CAAC,GAAG,CAAC,CAAC;IAClB,OAAO,EAAE,EAAE,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACvE,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC1C,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7C,YAAY,CAAC,GAAG,CAAC,CAAC;IAClB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAQ,CAAC,GAAG,EAAE,CAAC;AAC9C,CAAC;AAED;uDACuD;AACvD,MAAM,UAAU,WAAW;IAKzB,OAAO,YAAY,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC;QACzB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,sEAAsE;QACtE,wEAAwE;QACxE,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC;KACxC,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACZ,CAAC,CAAC,IAAI,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACjC,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,CAAC;QAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;gDAEgD;AAChD,MAAM,UAAU,YAAY;IAC1B,OAAO,oBAAoB,EAAE,CAAC;AAChC,CAAC"}

package/dist/daemon/rpc_child.d.ts

@@ -0,0 +1,194 @@
+import { EventEmitter } from "node:events";
+import type { DaemonState } from "./control_protocol.js";
+import { type LocalConfig } from "../session/local_config.js";
+/**
+ * Wrapper around a `pi --mode rpc -e <extension>` child process for the
+ * supervisor.
+ *
+ * Lifecycle:
+ *   - `spawn()` boots the child with the daemon's cwd + `UNBIEN_DAEMON=1`
+ *     env so the extension knows to skip the interactive wizard.
+ *   - `sendPrompt(text)` writes a Pi RPC `prompt` command to stdin.
+ *   - The child's stdout (Pi RPC events) is currently consumed line-by-line
+ *     and ignored — wave 2 only needs fire-and-forget. Later waves can
+ *     surface the events back through the supervisor's status op.
+ *   - Exit/crash fires `exit` event with `{code, signal, isCrash}` so the
+ *     supervisor can decide whether to auto-restart.
+ *
+ * Each `RpcChild` instance maps 1:1 to a registry entry (single cwd).
+ * The supervisor owns the map of these and addresses them by `id`.
+ */
+export interface RpcChildOptions {
+    /** Path to the `pi` binary. Defaults to "pi" (must be on PATH). */
+    piBin?: string;
+    /** Absolute path to the un-bien `dist/index.js` to load as -e. */
+    extensionPath: string;
+    /** Working directory for the spawned process. Determines which local
+     *  config the extension reads. */
+    cwd: string;
+    /** Additional env vars merged on top of `process.env` + the mandatory
+     *  `UNBIEN_DAEMON=1`. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Daemon config injected into the child via `UNBIEN_DIRECT_CONFIG`
+     * (JSON inline) instead of a per-cwd `.pi/un-bien/config.json` file. The
+     * supervisor builds this from the registry. When set, the child reads it
+     * env-first (see `loadLocalConfig`) and no config file is needed. Also the
+     * source of the `--name` for the session. Falls back to the on-disk config
+     * when omitted.
+     */
+    config?: LocalConfig;
+}
+export interface RpcChildExitEvent {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    /** True when exit was not clean (non-zero or signal). */
+    isCrash: boolean;
+}
+export declare const EXIT_DAEMON_FRESH_SESSION = 42;
+/**
+ * Resolve the `pi` executable for `spawn` (plan/40, decision C). On Windows a
+ * bare `pi` is actually `pi.cmd`/`pi.ps1`, and `spawn` won't find it without an
+ * extension → resolve the real path via `where` (rather than `shell:true`,
+ * which risks shell injection). An explicit path or an already-suffixed name is
+ * used as-is. POSIX returns the name unchanged. Best-effort: if `where` fails,
+ * fall back to the bare name (spawn will surface ENOENT honestly).
+ *
+ * `where` lists every match in PATH order, which on pi-node installs puts the
+ * extensionless `pi` (a shell script) BEFORE `pi.cmd`. Naively taking the first
+ * line spawns the unrunnable script → ENOENT → "crashed". So we prefer a result
+ * with a real Windows executable extension and only fall back to the first line.
+ */
+export declare function resolvePiBin(piBin: string, plat?: NodeJS.Platform): string;
+/** What to pass to `spawn`: the executable and any args to prepend before the
+ *  caller's args. On POSIX (and for `.exe`) `prefixArgs` is empty. */
+export interface PiSpawnTarget {
+    command: string;
+    prefixArgs: string[];
+}
+/**
+ * Resolve `pi` to a directly-spawnable target (plan/40). On Windows `pi` is an
+ * npm `.cmd` shim, which modern Node refuses to `spawn` without `shell:true`
+ * (EINVAL, post CVE-2024-27980). Wrapping it in `cmd.exe` would (a) add a layer
+ * that orphans the real `node` on kill and (b) complicate stdio — both fatal for
+ * a long-lived RPC daemon the supervisor must stop/restart cleanly. Instead we
+ * parse the shim to recover the underlying `node <cli.js>` and spawn that
+ * directly: one process, clean signals, clean stdio.
+ *
+ * Falls back to the bare resolved path when not a parseable shim (e.g. a real
+ * `pi.exe`, or POSIX) so `spawn` surfaces any real error honestly.
+ */
+export declare function resolvePiSpawn(piBin: string, plat?: NodeJS.Platform, nodeExe?: string): PiSpawnTarget;
+/**
+ * Extract the JS entry an npm `.cmd` shim launches. npm shims invoke
+ * `"%_prog%"  "%dp0%\<relative>\entry.js" %*`; we recover `<dir>\<relative>\entry.js`
+ * (dir = the shim's own folder, i.e. `%dp0%`). Returns null when the shim
+ * doesn't match the expected shape or the target is missing.
+ */
+export declare function _npmShimTarget(cmdPath: string): string | null;
+/**
+ * Maps an RPC stdout line to a busy-state transition: `message_start` → true
+ * (a message is streaming), `message_end` → false. Other lines → null (no
+ * change). Pure + exported for tests.
+ *
+ * NOTE (plan/39 detail 1): the Pi RPC stream has NO turn-level event — only
+ * per-message start/end (and `response{command:"prompt"}` is emitted at
+ * PREFLIGHT, i.e. turn START, not end). So this passive flag reflects
+ * "a message is being produced right now"; the authoritative turn-busy signal
+ * is `get_state.isStreaming` (see `RpcChild.refreshBusy`).
+ */
+export declare function busyTransition(line: string): boolean | null;
+/**
+ * CLI args for the daemon's `pi --mode rpc` child.
+ *
+ * `--continue` is the key bit: it resumes the **most recent** session for the
+ * cwd (`SessionManager.continueRecent`, non-interactive — unlike `--resume`
+ * which opens a picker). Without it every supervisor restart spun up a brand
+ * new session file, piling up thousands of JSONLs per folder. With it, a
+ * restart REUSES the one session; the app's `/new` (session_new) still rolls
+ * it over to a fresh one, which the next restart then continues. First boot
+ * (no prior session) just creates the first one.
+ *
+ * `--name <sessionName>`, when given, pins the session's display name to the
+ * daemon's identity (its `agent_name`) so every restart shows up under the
+ * same stable name in the picker/app instead of an auto-generated one. The
+ * daemon's name is set at registration (`unbien create <cwd> --name "…"`).
+ * Omitted when no name resolves, so the arg list stays minimal.
+ *
+ * `--approve` is mandatory for a daemon (pi ≥0.79 project trust): RPC mode is
+ * non-interactive, so without an override Pi resolves an untrusted project
+ * folder (any folder with `.pi/` or CLAUDE.md/AGENTS.md) to NOT trusted and
+ * silently skips its `.pi/settings.json` (model/provider/keys), instructions,
+ * resources and project extensions — the daemon then comes up with no model
+ * and fails on the first turn. The operator already authorized this folder by
+ * registering/launching a daemon in it, so `--approve` (trust-for-this-run) is
+ * the correct non-interactive stance. (Does NOT affect the separate "extension
+ * loaded twice" conflict, which comes from the extension being BOTH installed
+ * in ~/.pi/agent/extensions or cwd/.pi/extensions AND passed via `-e`.)
+ */
+export declare function rpcSpawnArgs(extensionPath: string, sessionName?: string, useContinue?: boolean): string[];
+export declare class RpcChild extends EventEmitter {
+    private readonly opts;
+    private child;
+    private _state;
+    private _startedAt;
+    private _restartCount;
+    /** True while a deliberate `stop()` is in flight. The process dies by
+     *  signal (SIGTERM/SIGKILL), which would otherwise look like a crash and
+     *  trip the supervisor's auto-restart — re-spawning a daemon the operator
+     *  just stopped/removed. Gating `isCrash` on this makes a deliberate stop a
+     *  clean exit (no restart). Reset on every `spawn()`. */
+    private _stopping;
+    /** Next spawn should create a fresh session instead of --continue. */
+    private forceFreshSessionOnNextSpawn;
+    /** Accumulates partial stdout lines while waiting for `\n`. */
+    private stdoutBuf;
+    /** Passive busy flag derived from the RPC stream (message_start/end). Hint
+     *  only; `refreshBusy` syncs it authoritatively via get_state.isStreaming. */
+    private _busy;
+    /** In-flight `get_state` requests, keyed by request id. */
+    private readonly _statePending;
+    constructor(opts: RpcChildOptions);
+    get state(): DaemonState;
+    /** Passive busy hint from the stream. Prefer `refreshBusy()` for an
+     *  authoritative check before acting on it (cron skip_if_busy). */
+    get isBusy(): boolean;
+    get pid(): number | undefined;
+    get restartCount(): number;
+    get uptimeMs(): number | undefined;
+    /**
+     * Spawn the child process. Idempotent for the same instance: a second
+     * call while already running is a no-op.
+     */
+    spawn(): void;
+    /**
+     * Sends a Pi RPC `prompt` command to the child's stdin. Fire-and-forget
+     * — we don't wait for the response (response would be the success ack;
+     * the actual agent output streams via the relay/UDS, not back through
+     * stdout).
+     *
+     * Returns false if the child isn't running (caller decides how to report).
+     */
+    sendPrompt(text: string, requestId?: string): boolean;
+    /**
+     * Asks the child to exit gracefully. Sends SIGTERM; if the child doesn't
+     * exit within `timeoutMs`, escalates to SIGKILL. Resolves when the
+     * `exit` event fires.
+     */
+    stop(timeoutMs?: number): Promise<void>;
+    private _onStdout;
+    private _handleStdoutLine;
+    /**
+     * Authoritative busy check: queries the child's `get_state` and syncs
+     * `_busy` to `isStreaming`. Resolves the passive flag on timeout (no
+     * response) or when the child isn't running. Used by the cron `skip_if_busy`
+     * gate, where a false "not busy" would pile a prompt onto a live turn.
+     */
+    refreshBusy(timeoutMs?: number): Promise<boolean>;
+    /** Test-only: feed a raw stdout line through the same handler. */
+    _ingestStdoutForTest(line: string): void;
+    private _onExit;
+    /** Bumps the restart counter — called by the supervisor when it
+     *  decides to re-spawn after a crash. Exposed so tests can drive it. */
+    noteRestart(): void;
+}