@cmetech/otto 1.1.0 → 1.2.4

package/packages/coworker-scratchpad/dist/kernel-protocol.d.ts

@@ -0,0 +1,171 @@
+export type { SkippedKey } from './namespace-codec.js';
+import type { SkippedKey } from './namespace-codec.js';
+export interface RunRequest {
+    id: number;
+    type: 'run';
+    code: string;
+}
+export interface SnapshotRequest {
+    id: number;
+    type: 'snapshot';
+}
+export type KernelRequest = RunRequest | SnapshotRequest;
+export interface ResultOk {
+    id: number;
+    type: 'result';
+    ok: true;
+    value: unknown;
+    stdout: string;
+}
+export interface ResultErr {
+    id: number;
+    type: 'result';
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+export type ResultResponse = ResultOk | ResultErr;
+export interface SnapshotResultOk {
+    id: number;
+    type: 'snapshot_result';
+    ok: true;
+    skipped: SkippedKey[];
+    snapshotted_at: string;
+}
+export interface SnapshotResultErr {
+    id: number;
+    type: 'snapshot_result';
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+export type SnapshotResult = SnapshotResultOk | SnapshotResultErr;
+export type RecoveryNote = {
+    kind: 'namespace-absent';
+} | {
+    kind: 'namespace-corrupt';
+    message: string;
+} | {
+    kind: 'cells-since-snapshot';
+    n: number;
+} | {
+    kind: 'snapshot-failed';
+    message: string;
+};
+export interface DataLoadDrawer {
+    kind: 'data_load';
+    collector: string;
+    uri: string;
+    bytes: number | null;
+    rows_loaded: number | null;
+    loaded_at: string;
+    schema: null;
+}
+export interface ReadyEvent {
+    type: 'event';
+    event: 'ready';
+    recovery_notes?: RecoveryNote[];
+}
+export interface DataLoadEvent {
+    type: 'event';
+    event: 'data_load';
+    drawer: DataLoadDrawer;
+}
+export interface ProgressEvent {
+    type: 'event';
+    event: 'progress';
+    message?: string;
+}
+export interface StartupErrorEvent {
+    type: 'event';
+    event: 'startup_error';
+    kind: string;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+export interface ArtifactCreateDrawer {
+    kind: 'artifact';
+    slug: string;
+    artifact_kind: string;
+    uri: string;
+    primary_path: string;
+    created_at: string;
+}
+export interface ArtifactCreateRequest {
+    type: 'request';
+    request: 'artifact_create';
+    id: string;
+    kind: string;
+    name: string;
+}
+export interface ArtifactCreateResponseOk {
+    type: 'response';
+    request: 'artifact_create';
+    id: string;
+    ok: true;
+    slug: string;
+    uri: string;
+    primary_path: string;
+}
+export interface ArtifactCreateResponseErr {
+    type: 'response';
+    request: 'artifact_create';
+    id: string;
+    ok: false;
+    error: string;
+}
+export type ArtifactCreateResponse = ArtifactCreateResponseOk | ArtifactCreateResponseErr;
+export interface ArtifactUpdateRequest {
+    type: 'request';
+    request: 'artifact_update';
+    id: string;
+    slug: string;
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface ArtifactUpdateResponseOk {
+    type: 'response';
+    request: 'artifact_update';
+    id: string;
+    ok: true;
+    files_touched: string[];
+}
+export interface ArtifactUpdateResponseErr {
+    type: 'response';
+    request: 'artifact_update';
+    id: string;
+    ok: false;
+    error: string;
+}
+export type ArtifactUpdateResponse = ArtifactUpdateResponseOk | ArtifactUpdateResponseErr;
+export interface ArtifactCreateEvent {
+    type: 'event';
+    event: 'artifact_create';
+    drawer: ArtifactCreateDrawer;
+}
+export type KernelRpcRequest = ArtifactCreateRequest | ArtifactUpdateRequest;
+export type KernelRpcResponse = ArtifactCreateResponse | ArtifactUpdateResponse;
+export type KernelEvent = ReadyEvent | DataLoadEvent | ProgressEvent | StartupErrorEvent | ArtifactCreateEvent;
+export type KernelFrame = ResultResponse | KernelEvent | SnapshotResult | KernelRpcRequest;
+export declare function isDataLoadEvent(frame: KernelFrame): frame is DataLoadEvent;
+export declare function isProgressEvent(frame: KernelFrame): frame is ProgressEvent;
+export declare function isStartupErrorEvent(frame: KernelFrame): frame is StartupErrorEvent;
+export declare function isSnapshotResult(frame: KernelFrame): frame is SnapshotResult;
+export declare function isArtifactCreateEvent(frame: unknown): frame is ArtifactCreateEvent;
+export declare function isArtifactCreateRequest(frame: unknown): frame is ArtifactCreateRequest;
+export declare function isArtifactUpdateRequest(frame: unknown): frame is ArtifactUpdateRequest;
+export declare function isArtifactCreateResponse(frame: unknown): frame is ArtifactCreateResponse;
+export declare function isArtifactUpdateResponse(frame: unknown): frame is ArtifactUpdateResponse;
+/** True for any `{type:'response'}` frame addressed to the kernel. */
+export declare function isKernelRpcResponse(frame: unknown): frame is KernelRpcResponse;

package/packages/coworker-scratchpad/dist/kernel-protocol.js

@@ -0,0 +1,48 @@
+// NDJSON wire protocol between the scratchpad parent runtime and the kernel child.
+// One JSON object per line (\n terminated). See spec §2.4 + §6.3.
+export function isDataLoadEvent(frame) {
+    return frame.type === 'event' && frame.event === 'data_load';
+}
+export function isProgressEvent(frame) {
+    return frame.type === 'event' && frame.event === 'progress';
+}
+export function isStartupErrorEvent(frame) {
+    return frame.type === 'event' && frame.event === 'startup_error';
+}
+export function isSnapshotResult(frame) {
+    return frame.type === 'snapshot_result';
+}
+export function isArtifactCreateEvent(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return f.type === 'event' && f.event === 'artifact_create';
+}
+export function isArtifactCreateRequest(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return f.type === 'request' && f.request === 'artifact_create';
+}
+export function isArtifactUpdateRequest(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return f.type === 'request' && f.request === 'artifact_update';
+}
+export function isArtifactCreateResponse(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return f.type === 'response' && f.request === 'artifact_create';
+}
+export function isArtifactUpdateResponse(frame) {
+    if (typeof frame !== 'object' || frame === null)
+        return false;
+    const f = frame;
+    return f.type === 'response' && f.request === 'artifact_update';
+}
+/** True for any `{type:'response'}` frame addressed to the kernel. */
+export function isKernelRpcResponse(frame) {
+    return isArtifactCreateResponse(frame) || isArtifactUpdateResponse(frame);
+}

package/packages/coworker-scratchpad/dist/kernel-spawn.d.ts

@@ -0,0 +1,3 @@
+export declare function filterEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function kernelExecArgv(execArgv?: string[]): string[];
+export declare function resolveKernelEntry(): string;

package/packages/coworker-scratchpad/dist/kernel-spawn.js

@@ -0,0 +1,54 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const ENV_ALLOW = new Set([
+    'PATH', 'HOME', 'TERM', 'SHELL', 'TMPDIR', 'TMP', 'TEMP',
+    'LANG', 'LANGUAGE', 'PWD', 'USER', 'LOGNAME',
+]);
+const ENV_ALLOW_PREFIXES = ['LC_', 'XDG_', 'OTTO_', 'NODE_'];
+const ENV_DENY = new Set([
+    'LOOP24_GATEWAY_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY',
+    'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'GITHUB_TOKEN',
+]);
+export function filterEnv(source = process.env) {
+    const out = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (ENV_DENY.has(key))
+            continue; // denylist overrides any allow-rule
+        if (ENV_ALLOW.has(key) || ENV_ALLOW_PREFIXES.some((p) => key.startsWith(p))) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+const FORWARD_FLAGS_WITH_VALUE = new Set([
+    '--import', '--loader', '--experimental-loader', '--require', '-r', '--conditions',
+]);
+const FORWARD_FLAGS_BOOLEAN = new Set([
+    '--experimental-strip-types', '--experimental-transform-types', '--no-warnings',
+]);
+export function kernelExecArgv(execArgv = process.execArgv) {
+    const out = [];
+    for (let i = 0; i < execArgv.length; i++) {
+        const arg = execArgv[i];
+        const eq = arg.indexOf('=');
+        const flag = eq >= 0 ? arg.slice(0, eq) : arg;
+        if (FORWARD_FLAGS_WITH_VALUE.has(flag)) {
+            out.push(arg);
+            if (eq < 0 && i + 1 < execArgv.length)
+                out.push(execArgv[++i]);
+        }
+        else if (FORWARD_FLAGS_BOOLEAN.has(flag)) {
+            out.push(arg);
+        }
+        // Everything else (--test, --watch, --test-*, …) is dropped.
+    }
+    return out;
+}
+export function resolveKernelEntry() {
+    const js = fileURLToPath(new URL('./kernel-entry.js', import.meta.url));
+    if (existsSync(js))
+        return js;
+    return fileURLToPath(new URL('./kernel-entry.ts', import.meta.url));
+}

package/packages/coworker-scratchpad/dist/namespace-codec.d.ts

@@ -0,0 +1,22 @@
+export declare const NAMESPACE_SCHEMA_VERSION = 1;
+export interface SkippedKey {
+    key: string;
+    ctor: string | null;
+    reason: string;
+}
+export interface NamespaceEnvelope {
+    schema_version: number;
+    snapshot_b64: string;
+    skipped: SkippedKey[];
+    ts: string;
+}
+export interface EncodeResult {
+    envelope: NamespaceEnvelope;
+    skipped: SkippedKey[];
+}
+export interface DecodeResult {
+    values: Record<string, unknown>;
+    skipped: SkippedKey[];
+}
+export declare function encodeNamespace(values: Record<string, unknown>, now: () => number): EncodeResult;
+export declare function decodeNamespace(json: string): DecodeResult;

package/packages/coworker-scratchpad/dist/namespace-codec.js

@@ -0,0 +1,61 @@
+import { serialize, deserialize } from 'node:v8';
+export const NAMESPACE_SCHEMA_VERSION = 1;
+function ctorName(value) {
+    if (value === null || value === undefined)
+        return null;
+    const c = value.constructor;
+    return c?.name ?? null;
+}
+export function encodeNamespace(values, now) {
+    const survivors = {};
+    const skipped = [];
+    for (const key of Object.keys(values)) {
+        const value = values[key];
+        try {
+            // Probe by serializing a single-key wrapper. Cheaper than per-key buffers
+            // because the survivors map is re-serialized once below.
+            serialize({ [key]: value });
+            survivors[key] = value;
+        }
+        catch (err) {
+            skipped.push({
+                key,
+                ctor: ctorName(value),
+                reason: err.message,
+            });
+        }
+    }
+    let snapshot_b64;
+    try {
+        snapshot_b64 = serialize(survivors).toString('base64');
+    }
+    catch (err) {
+        // A value passed the per-key probe but threw on bulk serialize (e.g. a getter
+        // that throws on its second invocation). Demote every survivor to skipped so
+        // the caller still gets a usable envelope; the snapshot for this round is empty.
+        const reason = `bulk-serialize-failed: ${err.message}`;
+        for (const key of Object.keys(survivors)) {
+            skipped.push({ key, ctor: ctorName(survivors[key]), reason });
+        }
+        snapshot_b64 = serialize({}).toString('base64');
+    }
+    const envelope = {
+        schema_version: NAMESPACE_SCHEMA_VERSION,
+        snapshot_b64,
+        skipped,
+        ts: new Date(now()).toISOString(),
+    };
+    return { envelope, skipped };
+}
+export function decodeNamespace(json) {
+    const parsed = JSON.parse(json);
+    if (parsed.schema_version !== NAMESPACE_SCHEMA_VERSION) {
+        throw new Error(`namespace-codec: unsupported schema_version ${String(parsed.schema_version)} (expected ${NAMESPACE_SCHEMA_VERSION})`);
+    }
+    if (typeof parsed.snapshot_b64 !== 'string') {
+        throw new Error('namespace-codec: missing snapshot_b64');
+    }
+    const buf = Buffer.from(parsed.snapshot_b64, 'base64');
+    const values = deserialize(buf);
+    return { values, skipped: Array.isArray(parsed.skipped) ? parsed.skipped : [] };
+}

package/packages/coworker-scratchpad/dist/scratchpad-lock.d.ts

@@ -0,0 +1,24 @@
+export interface LockInfo {
+    pid: number;
+    host: string;
+    acquired_at: string;
+    takeover_from?: {
+        pid: number;
+        host: string;
+        reason: string;
+    };
+}
+export interface AcquireOptions {
+    forceTakeover?: boolean;
+    takeoverReason?: string;
+    now?: () => number;
+}
+export declare class ScratchpadBusyError extends Error {
+    readonly scratchpadName: string;
+    readonly holder: LockInfo;
+    constructor(scratchpadName: string, holder: LockInfo);
+}
+export declare function readLock(dir: string): LockInfo | null;
+export declare function isStaleLock(holder: LockInfo): boolean;
+export declare function acquireLock(dir: string, options?: AcquireOptions): LockInfo;
+export declare function releaseLock(dir: string): void;

package/packages/coworker-scratchpad/dist/scratchpad-lock.js

@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { hostname } from 'node:os';
+import process from 'node:process';
+export class ScratchpadBusyError extends Error {
+    scratchpadName;
+    holder;
+    constructor(scratchpadName, holder) {
+        super(`scratchpad ${scratchpadName} is busy in another session`);
+        this.name = 'ScratchpadBusyError';
+        this.scratchpadName = scratchpadName;
+        this.holder = holder;
+    }
+}
+function lockPath(dir) {
+    return join(dir, 'lock.json');
+}
+export function readLock(dir) {
+    const path = lockPath(dir);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null; // corrupt lock is treated as absent (clearable on acquire)
+    }
+}
+function holderIsAlive(holder) {
+    if (holder.host !== hostname())
+        return true; // can't verify a remote PID -> assume alive
+    try {
+        process.kill(holder.pid, 0);
+        return true; // exists and signalable
+    }
+    catch (err) {
+        return err.code !== 'ESRCH'; // ESRCH = no such process (dead); EPERM etc. = alive
+    }
+}
+export function isStaleLock(holder) {
+    return !holderIsAlive(holder);
+}
+export function acquireLock(dir, options = {}) {
+    const now = options.now ?? Date.now;
+    mkdirSync(dir, { recursive: true });
+    const path = lockPath(dir);
+    const self = { pid: process.pid, host: hostname(), acquired_at: new Date(now()).toISOString() };
+    try {
+        writeFileSync(path, JSON.stringify(self), { flag: 'wx' });
+        return self; // won the atomic create
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    const holder = readLock(dir);
+    if (holder === null || !holderIsAlive(holder)) {
+        // corrupt or stale -> clear and retake
+        unlinkSync(path);
+        writeFileSync(path, JSON.stringify(self), { flag: 'wx' });
+        return self;
+    }
+    if (options.forceTakeover) {
+        const taken = {
+            ...self,
+            takeover_from: { pid: holder.pid, host: holder.host, reason: options.takeoverReason ?? 'force-takeover' },
+        };
+        writeFileSync(path, JSON.stringify(taken)); // overwrite the live holder
+        return taken;
+    }
+    throw new ScratchpadBusyError(basename(dir), holder);
+}
+export function releaseLock(dir) {
+    const holder = readLock(dir);
+    if (holder === null)
+        return;
+    if (holder.pid === process.pid && holder.host === hostname()) {
+        try {
+            unlinkSync(lockPath(dir));
+        }
+        catch {
+            // already gone
+        }
+    }
+    // not ours (e.g. taken over) -> leave it
+}

package/packages/coworker-scratchpad/dist/scratchpad-manager.d.ts

@@ -0,0 +1,193 @@
+import type { CredentialInjector } from '@otto/coworker-vault';
+import type { AuditLog } from '@otto/coworker-utils';
+import type { ArtifactStore } from '@otto/coworker-artifacts';
+import { ChildProcessRuntime, type ChildProcessRuntimeOptions } from './child-process-runtime.js';
+import { type LockInfo } from './scratchpad-lock.js';
+import { CellArchive } from './cell-archive.js';
+import type { ArtifactCreateDrawer, DataLoadDrawer } from './kernel-protocol.js';
+export declare class ForkKernelHangError extends Error {
+    readonly srcName: string;
+    readonly pid: number;
+    constructor(srcName: string, pid: number);
+}
+export interface ScratchpadManagerOptions {
+    workspace: string;
+    root?: string;
+    maxLiveKernels?: number;
+    idleMs?: number;
+    sweepIntervalMs?: number;
+    now?: () => number;
+    runtimeOptions?: Omit<ChildProcessRuntimeOptions, 'workspace'>;
+    sessionId?: string;
+    forkExitTimeoutMs?: number;
+    /**
+     * Phase 2 Task 13: optional vault credential injector. When provided, each
+     * spawned ChildProcessRuntime receives the injector + the scratchpad's
+     * meta.bindings list. Absent => runtime spawns with no OTTO_DS_* env vars.
+     */
+    injector?: CredentialInjector;
+    /**
+     * Phase 2 Task 14: optional audit sink for SecretScanner redactions on
+     * cell-output journal writes. When provided, every cell run's stdout is
+     * scanned BEFORE archive.append and emits one `producer: 'secret-scanner'`
+     * record per hit. Absent => redaction is a no-op (backward compat).
+     *
+     * Wiring contract: the caller is expected to pass the SAME AuditLog instance
+     * held by the CredentialInjector so secret-scanner records appear alongside
+     * vault inject/inject-skipped records in a single audit stream.
+     */
+    audit?: AuditLog;
+    /**
+     * Phase 3 Task 19: cross-pillar hook for the memory pillar's MemoryRecorder.
+     * Invoked once per `otto.collectors.open(...).load()` call inside a cell,
+     * with the kernel's `DataLoadDrawer` and the scratchpad name that produced it.
+     * The manager fans this through every spawn of every scratchpad (the callback
+     * is closure-bound to the name at spawn time, so multi-scratchpad sessions
+     * route loads to the correct room). Absent => data_load events are dropped.
+     */
+    onDataLoad?: (drawer: DataLoadDrawer, scratchpadName: string) => void;
+    /**
+     * Phase 4 Task 10: cross-pillar hook for the memory pillar's MemoryRecorder.
+     * Invoked once per `otto.artifact.create(...)` call inside a cell, with the
+     * kernel's `ArtifactCreateDrawer` and the scratchpad name that produced it.
+     * Closure-bound to the name at spawn time (same pattern as onDataLoad), so
+     * multi-scratchpad sessions route artifact events to the correct room.
+     * Absent => artifact_create events are dropped (memory stays silent).
+     */
+    onArtifactCreate?: (drawer: ArtifactCreateDrawer, scratchpadName: string) => void;
+    /**
+     * Phase 4 Task 10: lazy accessor for the ArtifactStore. The manager calls
+     * this each time it services an artifact RPC so the resolution sees the
+     * current extension activation state (callers can flip the store on/off as
+     * the artifacts extension activates/deactivates). When this returns null the
+     * RPC fails fast with "artifacts unavailable" — the kernel surfaces the
+     * error to the cell. Absent => RPC always fails (no artifact store wired).
+     */
+    getArtifactStore?: () => ArtifactStore | null;
+}
+export interface AttachOptions {
+    forceTakeover?: boolean;
+    takeoverReason?: string;
+    /**
+     * Phase 2 Task 12: optional list of binding ids (e.g. ['jira:prod']) to record
+     * in meta.json on first create. Subsequent meta writes preserve whatever's on
+     * disk via prevExtras — once persisted, bindings survive every other meta-write
+     * path. Ignored on re-attach if meta.json already has a bindings field.
+     */
+    bindings?: string[];
+}
+export interface ScratchpadInfo {
+    name: string;
+    live: boolean;
+    lastUsedAt: number;
+    hasActiveCell: boolean;
+}
+interface Entry {
+    runtime: ChildProcessRuntime | null;
+    lock: LockInfo;
+    lastUsedAt: number;
+    archive: CellArchive;
+    kernelAtCellId: number | null;
+}
+export declare class ScratchpadManager {
+    protected readonly entries: Map<string, Entry>;
+    protected readonly workspace: string;
+    protected readonly root: string;
+    protected readonly maxLive: number;
+    protected readonly idleMs: number;
+    protected readonly sessionId: string | undefined;
+    protected readonly now: () => number;
+    protected readonly runtimeOptions: Omit<ChildProcessRuntimeOptions, 'workspace'>;
+    protected readonly forkExitTimeoutMs: number;
+    protected readonly injector: CredentialInjector | undefined;
+    protected readonly audit: AuditLog | undefined;
+    protected readonly onDataLoad: ((drawer: DataLoadDrawer, scratchpadName: string) => void) | undefined;
+    protected readonly onArtifactCreate: ((drawer: ArtifactCreateDrawer, scratchpadName: string) => void) | undefined;
+    protected readonly getArtifactStore: (() => ArtifactStore | null) | undefined;
+    protected disposed: boolean;
+    private sweepTimer;
+    constructor(options: ScratchpadManagerOptions);
+    protected dirFor(name: string): string;
+    private metaPath;
+    private existsOnDisk;
+    private payloadSize;
+    private writeMetaAtomic;
+    private writeMeta;
+    private appendRecoveryNotes;
+    private applySnapshotToMeta;
+    private snapshotThenDispose;
+    private ingestRecoveryNotesOnAttach;
+    private restoreLeafOnAttach;
+    private restoreKernelAtCellIdOnAttach;
+    private warmCount;
+    /**
+     * Phase 2 Task 13: read meta.bindings from disk so each fresh spawn picks up
+     * the current binding set (bindings can change between attaches via /sp use).
+     * Returns [] if meta.json doesn't exist or doesn't have a v4 bindings array.
+     *
+     * Phase 2 Task 16: also surfaced as a public read for /sp list rendering and
+     * staleness-banner emission. Stays a thin read; callers that need to mutate
+     * use addBinding / removeBinding (which atomically RMW meta.json).
+     */
+    readBindings(name: string): string[];
+    /**
+     * Phase 2 Task 16: append a binding ref (e.g. 'jira:prod') to meta.bindings.
+     * Idempotent — adding a ref already in the list is a no-op (the meta.json
+     * write still happens so callers can detect "added" vs "noop" only via the
+     * returned tuple). Atomically rewrites meta.json via writeMetaAtomic, so
+     * concurrent writers cannot interleave. Caller is responsible for validating
+     * `ref` (sp-command uses LocalDataVault.parseRef before invoking).
+     */
+    addBinding(name: string, ref: string): Promise<{
+        added: boolean;
+    }>;
+    /**
+     * Phase 2 Task 16: remove a binding ref from meta.bindings. Returns whether
+     * a removal happened so callers can emit "no such binding" if needed.
+     */
+    removeBinding(name: string, ref: string): Promise<{
+        removed: boolean;
+    }>;
+    private spawnRuntime;
+    private evictLruIfNeeded;
+    create(name: string, opts?: AttachOptions): Promise<ChildProcessRuntime>;
+    getOrAttach(name: string, opts?: AttachOptions): Promise<ChildProcessRuntime>;
+    runCell(name: string, code: string, opts?: AttachOptions): Promise<{
+        value: unknown;
+        stdout: string;
+    }>;
+    /**
+     * Phase 2 Task 14: redact known-secret patterns from a cell-output string
+     * before journaling. No-op (pass-through) when no AuditLog is configured —
+     * the manager was constructed in test/legacy mode without vault wiring.
+     */
+    private redactStdout;
+    /**
+     * Task D: Release a warm kernel's process+memory while preserving on-disk state
+     * (kernel.db, namespace.json, cells.jsonl, meta.json, lock.json). Cold-restart
+     * happens on the next attach.
+     *
+     * Without --force: refuses if a cell is mid-execution. With --force: cancels the
+     * active cell via runtime.cancel() (SIGINT → SIGTERM → SIGKILL escalation handled
+     * internally by ChildProcessRuntime). Post-cancel the kernel is dead, so we skip
+     * the snapshot — the next attach replays from cells.jsonl.
+     */
+    evict(name: string, opts?: {
+        force?: boolean;
+    }): Promise<{
+        interrupted: boolean;
+    }>;
+    setLeaf(name: string, id: number): Promise<void>;
+    fork(srcName: string, dstName: string): Promise<void>;
+    clearHistory(name: string): Promise<void>;
+    save(name: string): Promise<void>;
+    detach(name: string, sessionId: string): Promise<void>;
+    markRecoveryNotesSeen(name: string): Promise<void>;
+    private attachUnmanaged;
+    list(): ScratchpadInfo[];
+    remove(name: string): Promise<void>;
+    evictIdle(): Promise<void>;
+    disposeAll(): Promise<void>;
+    protected assertNotDisposed(): void;
+}
+export {};