@hraness/sponge 0.3.5 → 0.4.0

package/README.md

@@ -121,21 +121,30 @@ pruned generation needs a rebuild.
 A digest (Digest v2) is a short gist led by one sentence and 3–5 ideas, each a
 claim with detail and 0–2 verbatim quotes, with 1–6 quotes in all.
 A local model proposes it; Sponge checks every rule against the captured text
-and stores only a passing draft. Drafting is opt-in and needs a model server you
-start yourself, such as llama.cpp `llama-server`, LM Studio or Ollama:
+and stores only a passing draft. Drafting is opt-in. `sponge setup --digest`
+installs a pinned llama.cpp and model (Gemma 4 26B-A4B with 32 GB of memory or
+more, Qwen3.5 9B with 16 GB; about 17 or 6 GB of disk), and from then on the
+background worker digests each new capture:
 
 ```sh
-llama-server -m gemma-4-12b-it-Q4_K_M.gguf --port 8080
-sponge digest ITEM --endpoint http://127.0.0.1:8080 --model NAME
+sponge setup --digest            # or --model-file GGUF to reuse a download
+sponge digest ITEM --draft       # draft one item now
+sponge digest --auto off         # stop background digests (on to resume)
 sponge digest ITEM
 sponge review DIGEST --accept all --reject quote:1.0
 ```
 
+Sponge runs its model server sandboxed on loopback, only while drafting, and
+waits while another `llama-server` holds the GPU. To use a server you started
+yourself (llama.cpp `llama-server`, LM Studio or Ollama), pass its endpoint:
+
+```sh
+sponge digest ITEM --endpoint http://127.0.0.1:8080 --model NAME
+```
+
 `--model` must match an id the server lists at `/v1/models`. Endpoints must be
 literal loopback HTTP (`127.0.0.1` or `[::1]`); Sponge refuses anything else so
-captured text never leaves the machine, and never starts or downloads a model.
-Suggested models are Gemma 4 12B on 16 GB Macs and Gemma 4 E4B on 8 GB, with
-Qwen3.5 9B or 4B as alternatives. Rerunning with the same inputs returns the stored
+captured text never leaves the machine. Rerunning with the same inputs returns the stored
 draft. Review targets are `all`, `gist`, `idea:N` and `quote:N.M` (0-based); only
 accepted fields can be published. `--check-support` also requires each quote to
 support its claim by local embedding similarity. See [digest drafting](src/digest/README.md).

package/dist/migrations/011.d.ts

@@ -0,0 +1,3 @@
+/** Digest jobs: one per captured revision, drafted by the worker with the model from `sponge setup --digest`. Local to this device (never in the change log); the server's process custody is the worker's filesystem journal, so a job has no attempt rows or staging. `digest_settings` holds the auto-digest switch and the chosen model alias. Additive. */
+export declare const version = 11;
+export declare const sql = "\nCREATE TABLE digest_jobs(id TEXT PRIMARY KEY,item_id TEXT NOT NULL REFERENCES items(id),revision_id TEXT NOT NULL UNIQUE REFERENCES revisions(id),state TEXT NOT NULL CHECK(state IN ('queued','delayed','running','failed','cancelled','succeeded')),cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK(cancel_requested IN (0,1)),attempt_count INTEGER NOT NULL DEFAULT 0,reason TEXT,retryable INTEGER NOT NULL DEFAULT 0 CHECK(retryable IN (0,1)),not_before TEXT,owner_incarnation TEXT,fence INTEGER,derivation_id TEXT,created_at TEXT NOT NULL,finished_at TEXT) STRICT;\nCREATE INDEX digest_jobs_ready ON digest_jobs(state,not_before,created_at);\nCREATE INDEX digest_jobs_item ON digest_jobs(item_id);\nCREATE TABLE digest_settings(id INTEGER PRIMARY KEY CHECK(id=1),auto INTEGER NOT NULL DEFAULT 0 CHECK(auto IN (0,1)),model TEXT) STRICT;\nINSERT INTO digest_settings(id) VALUES(1);\n";

package/dist/migrations/011.js

@@ -0,0 +1,9 @@
+/** Digest jobs: one per captured revision, drafted by the worker with the model from `sponge setup --digest`. Local to this device (never in the change log); the server's process custody is the worker's filesystem journal, so a job has no attempt rows or staging. `digest_settings` holds the auto-digest switch and the chosen model alias. Additive. */
+export const version = 11;
+export const sql = `
+CREATE TABLE digest_jobs(id TEXT PRIMARY KEY,item_id TEXT NOT NULL REFERENCES items(id),revision_id TEXT NOT NULL UNIQUE REFERENCES revisions(id),state TEXT NOT NULL CHECK(state IN ('queued','delayed','running','failed','cancelled','succeeded')),cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK(cancel_requested IN (0,1)),attempt_count INTEGER NOT NULL DEFAULT 0,reason TEXT,retryable INTEGER NOT NULL DEFAULT 0 CHECK(retryable IN (0,1)),not_before TEXT,owner_incarnation TEXT,fence INTEGER,derivation_id TEXT,created_at TEXT NOT NULL,finished_at TEXT) STRICT;
+CREATE INDEX digest_jobs_ready ON digest_jobs(state,not_before,created_at);
+CREATE INDEX digest_jobs_item ON digest_jobs(item_id);
+CREATE TABLE digest_settings(id INTEGER PRIMARY KEY CHECK(id=1),auto INTEGER NOT NULL DEFAULT 0 CHECK(auto IN (0,1)),model TEXT) STRICT;
+INSERT INTO digest_settings(id) VALUES(1);
+`;

package/dist/migrations/index.js

@@ -10,6 +10,7 @@ import * as m7 from './007.js';
 import * as m8 from './008.js';
 import * as m9 from './009.js';
 import * as m10 from './010.js';
+import * as m11 from './011.js';
 import { syncReady } from '../src/store/sync-ready.js';
 import { incrementalIndex } from '../src/indexing/upgrade.js';
 /** Every migration, in order. Add a new numbered file and append it here; never edit or reorder a released entry. */
@@ -30,6 +31,7 @@ export const migrations = Object.freeze([
     m8,
     { ...m9, step: syncReady },
     { ...m10, step: incrementalIndex },
+    m11,
 ].map((m) => Object.freeze({ ...m })));
 migrations.forEach((m, i) => {
     if (m.version !== i + 1)

package/dist/src/cli/commands.js

@@ -9,6 +9,8 @@ import { portabilityAction } from './portability.js';
 import { restoreLibrary } from '../portability/backup.js';
 import { workerAction, serveWorker, hasDueAcquisition, workerDoctor } from './worker.js';
 import { nativeSetupPlan, provisionNative, inspectNative } from '../models/runtime.js';
+import { digestModel, digestSetupPlan, inspectDigest, provisionDigest } from '../models/digest.js';
+import { withDigestServer } from '../digest/server.js';
 import { nativeDownloadAuthGuidance } from '../models/download.js';
 import { drainIndexQueue } from '../indexing/runner.js';
 import { indexAction, overviewText } from './indexing.js';
@@ -123,12 +125,35 @@ export const commands = [
     {
         name: 'setup',
         summary: 'Download one pinned runtime',
-        usage: [['setup --capture|--asr|--embedding', 'Download one pinned runtime']],
+        usage: [
+            ['setup --capture|--asr|--embedding', 'Download one pinned runtime'],
+            [
+                'setup --digest [--digest-model ALIAS] [--model-file GGUF]',
+                'Install the local digest model; --model-file copies a GGUF you already have',
+            ],
+        ],
         positional: 0,
-        flags: { capture: 'boolean', asr: 'boolean', embedding: 'boolean' },
+        flags: {
+            capture: 'boolean',
+            asr: 'boolean',
+            embedding: 'boolean',
+            digest: 'boolean',
+            'digest-model': 'value',
+            'model-file': 'value',
+        },
         library: 'open',
-        check: (_, f) => [f.capture, f.asr, f.embedding].filter(Boolean).length === 1,
+        check: (_, f) => [f.capture, f.asr, f.embedding, f.digest].filter(Boolean).length === 1 &&
+            (!!f.digest || (f['digest-model'] === undefined && f['model-file'] === undefined)) &&
+            (f['model-file'] === undefined || abs(f['model-file'])),
         handler: async (c) => {
+            if (c.args.flags.digest) {
+                const flags = c.args.flags, pin = digestModel(typeof flags['digest-model'] === 'string' ? flags['digest-model'] : undefined), modelFile = typeof flags['model-file'] === 'string' ? flags['model-file'] : undefined;
+                process.stderr.write(JSON.stringify({ setup: 'digest', adopt: !!modelFile, ...digestSetupPlan(pin) }) + '\n');
+                await provisionDigest(c.nativeRoot, pin, { signal: c.signal, modelFile });
+                const gc = await setupRuntimeGc(c.store, c.version), settings = c.store.digests.configure({ auto: true, model: pin.alias });
+                c.emit({ digest: 'ready', model: pin.alias, auto: settings.auto, gc }, `Digest model ready: ${pin.alias}. New captures are digested in the background; turn that off with \`sponge digest --auto off\`.`);
+                return 0;
+            }
             if (!c.args.flags.capture) {
                 const kind = c.args.flags.asr ? 'asr' : 'embedding', plan = await nativeSetupPlan(kind, c.version);
                 process.stderr.write(JSON.stringify({ setup: kind, ...plan }) + '\n');
@@ -691,16 +716,36 @@ export const commands = [
                 'digest ITEM --endpoint http://127.0.0.1:PORT --model NAME [--check-support]',
                 'Draft a digest with a local model server you started',
             ],
+            ['digest ITEM --draft [--model ALIAS]', 'Draft a digest with the model from `sponge setup --digest`'],
             ['digest ITEM', 'Show the current digest and its review state'],
+            ['digest --auto on|off', 'Digest new captures in the background with the worker, or stop'],
         ],
-        positional: 1,
-        flags: { endpoint: 'value', model: 'value', 'check-support': 'boolean' },
+        positional: (p) => p.length <= 1,
+        flags: { endpoint: 'value', model: 'value', 'check-support': 'boolean', draft: 'boolean', auto: 'value' },
         library: 'open',
-        check: (_, f) => Boolean(f.endpoint) === Boolean(f.model) &&
+        check: (p, f) => (f.auto === undefined
+            ? p.length === 1
+            : p.length === 0 &&
+                ['on', 'off'].includes(String(f.auto)) &&
+                !f.draft &&
+                !f.endpoint &&
+                !f.model &&
+                !f['check-support']) &&
+            (f.draft ? !f.endpoint && !f['check-support'] : Boolean(f.endpoint) === Boolean(f.model)) &&
             !(f['check-support'] && !f.endpoint) &&
             (f.model === undefined || /^[\w.:/@+-]{1,256}$/.test(String(f.model))),
         handler: async (c) => {
             const { store, args, signal } = c;
+            if (args.flags.auto !== undefined) {
+                const settings = store.digests.configure({ auto: args.flags.auto === 'on' });
+                c.emit({ auto: settings.auto }, `Auto-digest ${settings.auto ? 'on' : 'off'}`);
+                return 0;
+            }
+            if (args.flags.draft) {
+                const runtime = await inspectDigest(c.nativeRoot, args.flags.model ?? store.digests.settings().model ?? undefined), result = await withDigestServer(store.root, runtime, (model) => createDigest(store, args.positional[0], model, { signal }), { signal });
+                c.emit({ digest: result.derivation, duplicate: result.duplicate, ...(result.trace ? { trace: result.trace } : {}) }, digestText(result.derivation));
+                return 0;
+            }
             if (!args.flags.endpoint) {
                 const digest = store.derivations.current('digest', args.positional[0]);
                 if (!digest)

package/dist/src/cli/runtimes.js

@@ -1,15 +1,19 @@
 import { defaultCapturePins } from '../acquisition/index.js';
 import { loadNativeCatalog, nativeModelPackage } from '../models/catalog.js';
 import { modelSetupPlan } from '../models/artifacts.js';
+import { digestFingerprints } from '../models/digest.js';
 import { collectRuntimes } from '../worker/runtime-gc.js';
 import { codeOf } from '../errors.js';
-/** References of this installed Sponge: its capture pin and its catalog's model packages. */
+/** References of this installed Sponge: its capture pin, its catalog's model packages and every digest pin. */
 async function installedReferences(version) {
     let models = null;
     try {
         const catalog = await loadNativeCatalog(version);
         models = {
-            fingerprints: ['asr', 'embedding'].map((kind) => modelSetupPlan(nativeModelPackage(catalog, kind)).fingerprint),
+            fingerprints: [
+                ...['asr', 'embedding'].map((kind) => modelSetupPlan(nativeModelPackage(catalog, kind)).fingerprint),
+                ...digestFingerprints(),
+            ],
         };
     }
     catch {

package/dist/src/cli/worker.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { inspectNative } from '../models/runtime.js';
 import { drainIndexQueue } from '../indexing/runner.js';
+import { drainDigestQueue } from '../digest/runner.js';
 import { drainLibrary } from '../worker/basic.js';
 import { recoverServiceLifetime } from '../service/lifetime.js';
 import { runWorkerService } from '../service/loop.js';
@@ -47,7 +48,7 @@ export function hasDueAcquisition(store) {
     const now = new Date().toISOString();
     return store.queue
         .list()
-        .some((job) => job.operation !== 'index' &&
+        .some((job) => !['index', 'digest'].includes(String(job.operation)) &&
         ['queued', 'delayed'].includes(String(job.state)) &&
         job.cancel_requested !== 1 &&
         (job.not_before === null || job.not_before === undefined || String(job.not_before) <= now));
@@ -83,6 +84,9 @@ export async function drainServiceQueues(store, options, version, signal) {
         const runtime = await inspectNative('embedding', join(store.root, 'runtime', 'models'), version);
         results.push(...(await drainIndexQueue(store, { runtime, signal })));
     }
+    // Last, under its own time budget: drafting holds the GPU and can take minutes per item.
+    if (!signal.aborted && store.queue.pendingCleanup() === 0 && store.digests.due())
+        results.push(...(await drainDigestQueue(store, { nativeRoot: join(store.root, 'runtime', 'models'), signal })));
     if (acquisitionError)
         throw acquisitionError;
     return results;

package/dist/src/digest/endpoint.d.ts

@@ -1,7 +1,8 @@
 import { type DigestModel } from './pipeline.js';
 /**
- * A user-started local OpenAI-compatible server (llama.cpp `llama-server`, LM Studio, Ollama). Captured text must not
- * leave the machine, so only literal loopback HTTP origins are accepted, redirects are refused, and Sponge never starts a server.
+ * A local OpenAI-compatible server: one the user started (llama.cpp `llama-server`, LM Studio, Ollama), or Sponge's own
+ * (src/digest/server.ts). Captured text must not leave the machine, so only literal loopback HTTP origins are accepted
+ * and redirects are refused.
  */
 export declare function loopbackEndpoint(value: string): URL;
 /** GGUF quantization from a model filename, e.g. `gemma-4-12b-it-Q4_K_M.gguf` → `Q4_K_M`. */

package/dist/src/digest/endpoint.js

@@ -1,7 +1,8 @@
 import { SpongeError } from '../errors.js';
 /**
- * A user-started local OpenAI-compatible server (llama.cpp `llama-server`, LM Studio, Ollama). Captured text must not
- * leave the machine, so only literal loopback HTTP origins are accepted, redirects are refused, and Sponge never starts a server.
+ * A local OpenAI-compatible server: one the user started (llama.cpp `llama-server`, LM Studio, Ollama), or Sponge's own
+ * (src/digest/server.ts). Captured text must not leave the machine, so only literal loopback HTTP origins are accepted
+ * and redirects are refused.
  */
 export function loopbackEndpoint(value) {
     let url;

package/dist/src/digest/runner.d.ts

@@ -0,0 +1,33 @@
+import type { LibraryStore } from '../store/index.js';
+import { inspectDigest } from '../models/digest.js';
+import { type DigestServerOptions } from './server.js';
+import { createDigest } from './pipeline.js';
+export type DigestRunResult = {
+    ok: true;
+    jobId: string;
+    digestId: string;
+    duplicate: boolean;
+} | {
+    ok: false;
+    jobId?: string;
+    code: string;
+    postponed?: number;
+};
+export interface DigestRunOptions {
+    /** `<library>/runtime/models`, where `sponge setup --digest` installed the runtime. */
+    nativeRoot: string;
+    signal?: AbortSignal;
+    /** No new job is claimed after this long; the one drafting finishes. Default 10 minutes. */
+    budgetMs?: number;
+    /** Test seams. */
+    inspect?: typeof inspectDigest;
+    create?: typeof createDigest;
+    server?: Partial<Omit<DigestServerOptions, 'runProcess' | 'scratchRoot' | 'signal'>>;
+}
+/**
+ * Draft queued digests with one Sponge-owned server per drain (`withDigestServer`), claiming jobs under the worker lease
+ * until the queue is empty, the budget is spent or the signal aborts. Never throws for a missing runtime, a busy GPU or
+ * a server that would not start: the ready jobs are postponed with that reason, so capture and indexing keep running.
+ * `cleanup-required` and `owner-busy` still throw, as the service loop expects.
+ */
+export declare function drainDigestQueue(store: LibraryStore, options: DigestRunOptions): Promise<DigestRunResult[]>;

package/dist/src/digest/runner.js

@@ -0,0 +1,82 @@
+import { inspectDigest } from '../models/digest.js';
+import { withDigestServer } from './server.js';
+import { createDigest } from './pipeline.js';
+import { codeOf } from '../errors.js';
+const minute = 60000;
+/** How long ready jobs wait when drafting cannot start, by cause. Nothing reached the model, so no attempt is counted. */
+const postponeMs = {
+    'model-busy': 5 * minute,
+    'model-unavailable': 30 * minute,
+    'runtime-missing': 60 * minute,
+    unsupported: 60 * minute,
+};
+const at = (ms) => new Date(Date.now() + ms).toISOString();
+/**
+ * Draft queued digests with one Sponge-owned server per drain (`withDigestServer`), claiming jobs under the worker lease
+ * until the queue is empty, the budget is spent or the signal aborts. Never throws for a missing runtime, a busy GPU or
+ * a server that would not start: the ready jobs are postponed with that reason, so capture and indexing keep running.
+ * `cleanup-required` and `owner-busy` still throw, as the service loop expects.
+ */
+export async function drainDigestQueue(store, options) {
+    if (options.signal?.aborted || !store.digests.due())
+        return [];
+    const settings = store.digests.settings(), results = [], deadline = Date.now() + (options.budgetMs ?? 10 * minute), create = options.create ?? createDigest;
+    const postpone = (code) => [
+        { ok: false, code, postponed: store.digests.postpone(code, at(postponeMs[code] ?? 6 * 60 * minute)) },
+    ];
+    let runtime;
+    try {
+        runtime = await (options.inspect ?? inspectDigest)(options.nativeRoot, settings.model ?? undefined);
+    }
+    catch (error) {
+        return postpone(codeOf(error));
+    }
+    try {
+        await withDigestServer(store.root, runtime, async (model, { incarnation }) => {
+            const owner = store.queue.acquireOwner(incarnation);
+            try {
+                while (!options.signal?.aborted && Date.now() < deadline) {
+                    const claim = store.digests.claim(owner);
+                    if (!claim)
+                        break;
+                    try {
+                        const { derivation, duplicate } = await create(store, claim.itemId, model, { signal: options.signal });
+                        store.digests.finish(claim, { derivationId: derivation.id });
+                        results.push({ ok: true, jobId: claim.jobId, digestId: derivation.id, duplicate });
+                    }
+                    catch (error) {
+                        const code = codeOf(error);
+                        if (code === 'cleanup-required')
+                            throw error;
+                        // A cancelled draft goes back to the queue as it was; a server that stopped answering ends the drain.
+                        if (options.signal?.aborted)
+                            store.digests.finish(claim, {
+                                reason: 'cancelled',
+                                retryable: true,
+                                countAttempt: false,
+                                notBefore: at(0),
+                            });
+                        else
+                            store.digests.finish(claim, { reason: code, retryable: code === 'model-unavailable' });
+                        results.push({ ok: false, jobId: claim.jobId, code });
+                        if (options.signal?.aborted || code === 'model-unavailable')
+                            break;
+                    }
+                }
+            }
+            finally {
+                store.queue.releaseOwner(owner);
+            }
+        }, { ...options.server, signal: options.signal });
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code === 'cleanup-required' || code === 'owner-busy')
+            throw error;
+        // Before any claim, the server would not start or verify. After one, every job is settled already.
+        if (!results.length)
+            return postpone(code);
+        results.push({ ok: false, code });
+    }
+    return results;
+}

package/dist/src/digest/server.d.ts

@@ -0,0 +1,40 @@
+import type { ProcessRunner } from '../worker/supervisor.js';
+import { type DigestRuntime } from '../models/digest.js';
+import type { DigestModel } from './pipeline.js';
+/**
+ * The Sponge-owned digest server: the verified llama.cpp archive is unpacked into the attempt's scratch root and
+ * `llama-server` runs under `sandbox-exec` with outbound connections other than loopback denied, bound to 127.0.0.1
+ * on a free port, through the caller's process runner (the worker supervisor), so the server's process group is
+ * collected and proved like any helper even if this process dies. Captured text never leaves the machine.
+ */
+export declare const sandboxProfile = "(version 1) (allow default) (deny network-outbound (remote ip \"*:*\")) (allow network-outbound (remote ip \"localhost:*\"))";
+/** Other `llama-server` processes in `ps -axo pid=,command=` output, with the model each loaded when it names one. */
+export declare function otherServers(ps: string, self?: number): {
+    pid: number;
+    model?: string;
+}[];
+/** An ephemeral loopback port; the kernel picks one that is free now. */
+export declare function freePort(): Promise<number>;
+export interface DigestServerOptions {
+    runProcess: ProcessRunner;
+    /** A private directory owned by the caller's attempt; removed by the caller after `stop`. */
+    scratchRoot: string;
+    signal?: AbortSignal;
+    ctx?: number;
+    readyTimeoutMs?: number;
+    /** Longest a server may run before the runner stops it. */
+    lifetimeMs?: number;
+    processes?: () => Promise<string>;
+    /** The executable inside the archive's directory; tests substitute a fake. */
+    executable?: string;
+    sandbox?: boolean;
+}
+/**
+ * Run `fn` against a Sponge-owned server for `runtime`, held as a `digest-server` attempt under worker custody: the
+ * server is stopped and its process group proved collected before custody is released.
+ */
+export declare function withDigestServer<T>(libraryRoot: string, runtime: DigestRuntime, fn: (model: DigestModel, custody: {
+    incarnation: string;
+}) => Promise<T>, options?: {
+    signal?: AbortSignal;
+} & Partial<Omit<DigestServerOptions, 'runProcess' | 'scratchRoot'>>): Promise<T>;

package/dist/src/digest/server.js

@@ -0,0 +1,166 @@
+import { execFile } from 'node:child_process';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { directory } from '../worker/journal.js';
+import { llamaRuntimePin } from '../models/digest.js';
+import { withTransientAttempt } from '../worker/transient.js';
+import { connectEndpoint } from './endpoint.js';
+import { SpongeError } from '../errors.js';
+/**
+ * The Sponge-owned digest server: the verified llama.cpp archive is unpacked into the attempt's scratch root and
+ * `llama-server` runs under `sandbox-exec` with outbound connections other than loopback denied, bound to 127.0.0.1
+ * on a free port, through the caller's process runner (the worker supervisor), so the server's process group is
+ * collected and proved like any helper even if this process dies. Captured text never leaves the machine.
+ */
+export const sandboxProfile = '(version 1) (allow default) (deny network-outbound (remote ip "*:*")) (allow network-outbound (remote ip "localhost:*"))';
+/** Other `llama-server` processes in `ps -axo pid=,command=` output, with the model each loaded when it names one. */
+export function otherServers(ps, self = process.pid) {
+    return ps.split('\n').flatMap((line) => {
+        const m = /^\s*(\d+)\s+(\S*llama-server)(\s.*)?$/.exec(line);
+        if (!m || Number(m[1]) === self)
+            return [];
+        const model = /\s(?:-m|--model)\s+(\S+)/.exec(m[3] ?? '')?.[1];
+        return [{ pid: Number(m[1]), ...(model ? { model: model.split('/').pop() } : {}) }];
+    });
+}
+const listProcesses = () => new Promise((ok, fail) => execFile('/bin/ps', ['-axo', 'pid=,command='], { maxBuffer: 16 * 1024 ** 2 }, (e, out) => (e ? fail(e) : ok(out))));
+/** An ephemeral loopback port; the kernel picks one that is free now. */
+export function freePort() {
+    return new Promise((ok, fail) => {
+        const s = createServer();
+        s.once('error', fail);
+        s.listen(0, '127.0.0.1', () => {
+            const port = s.address().port;
+            s.close(() => ok(port));
+        });
+    });
+}
+/** Every unpacked entry is a file, directory or a symlink resolving inside `root`. */
+async function confined(root, dir = root) {
+    for (const name of await readdir(dir)) {
+        const path = join(dir, name), s = await lstat(path);
+        if (s.isDirectory())
+            await confined(root, path);
+        else if (s.isSymbolicLink()) {
+            if (!(await realpath(path)).startsWith(root + '/'))
+                throw new SpongeError('integrity');
+        }
+        else if (!s.isFile())
+            throw new SpongeError('integrity');
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function startDigestServer(runtime, o) {
+    const [other] = otherServers(await (o.processes ?? listProcesses)());
+    // Two loaded models exhaust GPU memory and every request fails; wait for the other server instead.
+    if (other)
+        throw new SpongeError('model-busy', { detail: { pid: other.pid } });
+    const unpacked = await directory(join(o.scratchRoot, 'llama')), env = { PATH: '/usr/bin:/bin', HOME: o.scratchRoot, TMPDIR: o.scratchRoot, LANG: 'en_US.UTF-8' };
+    const tar = await o.runProcess('/usr/bin/tar', ['-xzf', runtime.archive, '-C', unpacked, '--no-same-owner'], {
+        env,
+        signal: o.signal,
+        deadlineMs: 120000,
+        maxOutputBytes: 65536,
+    });
+    if (tar.stopped === 'cancelled')
+        throw new SpongeError('cancelled');
+    if (tar.cleanup !== 'settled')
+        throw new SpongeError('cleanup-required');
+    if (tar.code !== 0 || tar.stopped)
+        throw new SpongeError('integrity');
+    await confined(await realpath(unpacked));
+    const server = join(unpacked, llamaRuntimePin.directory, o.executable ?? 'llama-server'), s = await lstat(server).catch(() => undefined);
+    if (!s?.isFile() || !(s.mode & 0o100))
+        throw new SpongeError('integrity');
+    const port = await freePort(), args = [
+        '-m',
+        runtime.model,
+        '--alias',
+        runtime.pin.alias,
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '-c',
+        String(o.ctx ?? 16384),
+        '-np',
+        '1',
+        '--jinja',
+        '--reasoning',
+        'off',
+        '--offline',
+        '--no-webui',
+        '--log-disable',
+    ];
+    const own = new AbortController(), signal = o.signal ? AbortSignal.any([o.signal, own.signal]) : own.signal, sandbox = o.sandbox ?? true;
+    let result;
+    const run = o
+        .runProcess(sandbox ? '/usr/bin/sandbox-exec' : server, sandbox ? ['-p', sandboxProfile, server, ...args] : args, {
+        env,
+        signal,
+        deadlineMs: o.lifetimeMs ?? 6 * 3600 * 1000,
+        maxOutputBytes: 4 * 1024 ** 2,
+        graceMs: 5000,
+    })
+        .then((r) => (result = r));
+    let stopping;
+    const endpoint = `http://127.0.0.1:${port}`, handle = {
+        endpoint,
+        model: runtime.pin.alias,
+        stop: () => (stopping ??= (async () => {
+            own.abort();
+            return (await run).cleanup;
+        })()),
+    };
+    const deadline = Date.now() + (o.readyTimeoutMs ?? 180000);
+    try {
+        while (Date.now() < deadline) {
+            if (o.signal?.aborted)
+                throw new SpongeError('cancelled');
+            if (result)
+                throw new SpongeError('model-unavailable', { detail: { exited: result.code } });
+            // `/health` can answer before the model is listed; ready means both.
+            const models = await fetch(`${endpoint}/health`, { redirect: 'error', signal: AbortSignal.timeout(2000) })
+                .then(async (r) => {
+                await r.body?.cancel().catch(() => undefined);
+                if (!r.ok)
+                    return undefined;
+                const m = await fetch(`${endpoint}/v1/models`, { redirect: 'error', signal: AbortSignal.timeout(2000) });
+                return m.ok ? (await m.json()) : undefined;
+            })
+                .catch(() => undefined);
+            if (models?.data?.some((m) => m?.id === runtime.pin.alias))
+                return handle;
+            await sleep(200);
+        }
+        throw new SpongeError('model-unavailable', { detail: { ready: false } });
+    }
+    catch (error) {
+        if ((await handle.stop()) === 'pending')
+            throw new SpongeError('cleanup-required', { cause: error });
+        throw error;
+    }
+}
+/**
+ * Run `fn` against a Sponge-owned server for `runtime`, held as a `digest-server` attempt under worker custody: the
+ * server is stopped and its process group proved collected before custody is released.
+ */
+export function withDigestServer(libraryRoot, runtime, fn, options = {}) {
+    return withTransientAttempt(libraryRoot, 'digest-server', async ({ scratchRoot, runProcess, incarnation }) => {
+        const server = await startDigestServer(runtime, { ...options, runProcess, scratchRoot });
+        let result;
+        try {
+            const model = await connectEndpoint({ endpoint: server.endpoint, model: server.model, signal: options.signal });
+            // The identity must be the pinned build, so a digest's input hash names what drafted it.
+            if (!model.identity.runtime.includes(String(llamaRuntimePin.build)))
+                throw new SpongeError('integrity');
+            result = await fn(model, { incarnation });
+        }
+        finally {
+            if ((await server.stop()) === 'pending')
+                throw new SpongeError('cleanup-required');
+        }
+        return result;
+    });
+}

package/dist/src/errors.d.ts

@@ -18,6 +18,7 @@ declare const parents: {
     readonly 'no-capture': "invalid-input";
     readonly 'draft-rejected': "unavailable";
     readonly 'model-unavailable': "unavailable";
+    readonly 'model-busy': "unavailable";
     readonly 'parent-missing': "invalid-input";
     readonly 'target-exists': "invalid-input";
 };

package/dist/src/errors.js

@@ -32,6 +32,7 @@ const parents = {
     'no-capture': 'invalid-input',
     'draft-rejected': 'unavailable',
     'model-unavailable': 'unavailable',
+    'model-busy': 'unavailable',
     'parent-missing': 'invalid-input',
     'target-exists': 'invalid-input',
 };
@@ -83,6 +84,7 @@ export const hints = {
 export const detailHints = {
     'draft-rejected': 'The model draft failed the digest checks listed above, even after one repair. Drafting is deterministic, so the same capture and model fail again; refresh the item or use another model.',
     'model-unavailable': 'The model server did not answer or returned an error. Check that it is still running and has free GPU memory (another loaded model can exhaust it), then retry.',
+    'model-busy': 'Another llama-server is running, and two loaded models can exhaust GPU memory. Wait for it to exit, then retry.',
 };
 /** The one error type. `message` is the code, so bare `String(error)` never carries detail, paths or causes. */
 export class SpongeError extends Error {

package/dist/src/importers/custody.d.ts

@@ -1,6 +1,3 @@
-import { supervisedRunner } from '../worker/supervisor.js';
+import { type TransientAttempt } from '../worker/transient.js';
 /** Read-only verification still owns subprocesses, including during an import preview. */
-export declare function withImportVerification<T>(libraryRoot: string, verify: (context: {
-    scratchRoot: string;
-    runProcess: ReturnType<typeof supervisedRunner>;
-}) => Promise<T>): Promise<T>;
+export declare function withImportVerification<T>(libraryRoot: string, verify: (context: Pick<TransientAttempt, 'scratchRoot' | 'runProcess'>) => Promise<T>): Promise<T>;