presubmit 0.1.0

package/dist/apps/server/src/hub.js

@@ -0,0 +1,159 @@
+import { streamAttachment } from './attach.js';
+import { createHash } from 'node:crypto';
+import { createConnection, createServer } from 'node:net';
+import { chmod, lstat, unlink } from 'node:fs/promises';
+import { acquireWorkspaceLock, WorkspaceAlreadyRunningError } from './workspace-lock.js';
+import { tailscaleOrigin } from './browser-access.js';
+export function hubAddress(home) {
+    return `/tmp/presubmit-hub-${process.getuid?.() ?? 'user'}-${createHash('sha256').update(home).digest('hex').slice(0, 20)}.sock`;
+}
+class HostStoppingError extends Error {
+}
+async function register(home, workspace, tailscale) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(hubAddress(home));
+        let bytes = '';
+        socket.setTimeout(30000, () => socket.destroy(new Error('Presubmit did not finish opening the project. Please retry.')));
+        socket.on('connect', () => socket.write(JSON.stringify({ workspace, tailscale }) + '\n'));
+        socket.on('data', (chunk) => {
+            bytes += chunk.toString();
+            if (bytes.length > 16384)
+                socket.destroy(new Error('Invalid Presubmit response.'));
+        });
+        socket.on('error', reject);
+        socket.on('end', () => {
+            try {
+                if (!bytes)
+                    throw Object.assign(new Error('Presubmit host disconnected.'), { code: 'ECONNRESET' });
+                const response = JSON.parse(bytes);
+                // Older hosts report the same transition without a structured code.
+                if (response.code === 'HOST_STOPPING' || response.error === 'Server is stopping.')
+                    throw new HostStoppingError('The previous Presubmit host is still shutting down. Please retry shortly.');
+                if (response.error)
+                    throw new Error(response.error);
+                const url = new URL(response.url);
+                if (url.username ||
+                    url.password ||
+                    (tailscale
+                        ? url.origin !== tailscale
+                        : url.protocol !== 'http:' || url.hostname !== '127.0.0.1'))
+                    throw new Error(tailscale
+                        ? 'The running host did not return the requested Tailscale URL. Restart it with this version and --tailscale <https-device-url>.'
+                        : 'Invalid Presubmit server URL.');
+                resolve(url.toString());
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+/** One CLI host per Presubmit home; private Unix IPC registers later repositories. */
+export async function acquireHub(home, workspace, tailscale) {
+    if (tailscale !== undefined)
+        tailscale = tailscaleOrigin(tailscale);
+    let lock;
+    const until = Date.now() + 15000;
+    while (!lock) {
+        try {
+            lock = await acquireWorkspaceLock(`presubmit-home:${home}`);
+        }
+        catch (error) {
+            if (!(error instanceof WorkspaceAlreadyRunningError))
+                throw error;
+            try {
+                return { existingUrl: await register(home, workspace, tailscale) };
+            }
+            catch (error) {
+                if ((!(error instanceof HostStoppingError) &&
+                    !['ENOENT', 'ECONNREFUSED', 'ECONNRESET'].includes(error.code ?? '')) ||
+                    Date.now() >= until)
+                    throw error;
+            }
+            // The old host keeps ownership until all workers and stores are closed.
+            // Re-acquire the lock after it leaves; never start a second host alongside it.
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    let control;
+    const peers = new Set();
+    let stopping = false;
+    return {
+        async listen(url, openProject, readEvents) {
+            const path = hubAddress(home);
+            try {
+                const info = await lstat(path);
+                if (!info.isSocket())
+                    throw new Error('Presubmit control path is not a socket.');
+                await unlink(path);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            control = createServer((socket) => {
+                peers.add(socket);
+                socket.once('close', () => peers.delete(socket));
+                let bytes = '';
+                let handled = false;
+                socket.on('error', () => { });
+                socket.setTimeout(30000, () => socket.destroy());
+                socket.on('data', (chunk) => {
+                    if (handled)
+                        return;
+                    bytes += chunk.toString();
+                    if (bytes.length > 8192) {
+                        socket.destroy();
+                        return;
+                    }
+                    if (!bytes.includes('\n'))
+                        return;
+                    handled = true;
+                    void (async () => {
+                        try {
+                            const input = JSON.parse(bytes);
+                            if (stopping) {
+                                socket.end(JSON.stringify({ code: 'HOST_STOPPING', error: 'Server is stopping.' }) + '\n');
+                                return;
+                            }
+                            if (input.type === 'attach') {
+                                if (!readEvents)
+                                    throw new Error('Host does not support attachment. Restart it with this version.');
+                                streamAttachment(socket, input, readEvents);
+                                return;
+                            }
+                            if (typeof input.workspace !== 'string')
+                                throw new Error('Invalid project path.');
+                            if (input.tailscale !== undefined && typeof input.tailscale !== 'string')
+                                throw new Error('Invalid Tailscale URL.');
+                            const remote = input.tailscale === undefined ? undefined : tailscaleOrigin(input.tailscale);
+                            socket.end(JSON.stringify({ url: await openProject(input.workspace, remote) }));
+                        }
+                        catch (error) {
+                            socket.end(JSON.stringify({
+                                error: error instanceof Error ? error.message : 'Could not open project.',
+                            }) + '\n');
+                        }
+                    })();
+                });
+            });
+            await new Promise((resolve, reject) => {
+                control.once('error', reject);
+                control.listen(path, resolve);
+            });
+            await chmod(path, 0o600);
+            lock.setUrl(url);
+        },
+        beginShutdown() {
+            stopping = true;
+        },
+        async close() {
+            stopping = true;
+            for (const peer of peers)
+                peer.destroy();
+            if (control?.listening)
+                await new Promise((resolve) => control.close(() => resolve()));
+            await lock.release();
+        },
+    };
+}

package/dist/apps/server/src/internal-transport.js

@@ -0,0 +1,38 @@
+import { request as httpRequest } from 'node:http';
+import { WebSocket } from 'ws';
+/** Child workspaces use private Unix sockets, never additional listening TCP ports. */
+export function requestWorkspace(origin, socketPath, path, options = {}) {
+    if (!socketPath)
+        return fetch(origin + path, options);
+    return new Promise((resolve, reject) => {
+        const req = httpRequest({
+            socketPath,
+            signal: options.signal,
+            path,
+            method: options.method ?? 'GET',
+            headers: { ...options.headers, Host: new URL(origin).host },
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+            response.on('error', reject);
+            response.on('end', () => {
+                const headers = new Headers();
+                for (let i = 0; i < response.rawHeaders.length; i += 2)
+                    headers.append(response.rawHeaders[i], response.rawHeaders[i + 1]);
+                const status = response.statusCode ?? 502;
+                resolve(new Response([204, 205, 304].includes(status) ? null : Buffer.concat(chunks), {
+                    status,
+                    headers,
+                }));
+            });
+        });
+        req.on('error', reject);
+        req.end(options.body);
+    });
+}
+export function connectWorkspace(origin, socketPath, path, options = {}) {
+    return new WebSocket(socketPath ? `ws+unix://${socketPath}:${path}` : origin.replace('http:', 'ws:') + path, {
+        ...options,
+        headers: { ...options.headers, Host: new URL(origin).host },
+    });
+}

package/dist/apps/server/src/local-embeddings.js

@@ -0,0 +1,70 @@
+/** Embeddings stay on loopback; redirecting requests to a remote provider is disallowed. */
+export function ollamaEmbeddings(model = 'nomic-embed-text', address = 'http://127.0.0.1:11434') {
+    const url = new URL(address);
+    if (url.protocol !== 'http:' ||
+        !['127.0.0.1', '[::1]'].includes(url.hostname) ||
+        url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash)
+        throw new Error('The embedding service must use a loopback HTTP address.');
+    if (!model.trim() || model.length > 200)
+        throw new Error('Invalid embedding model.');
+    async function request(path, signal, body) {
+        let response;
+        try {
+            response = await fetch(new URL(path, url), {
+                method: body ? 'POST' : 'GET',
+                headers: body ? { 'Content-Type': 'application/json' } : undefined,
+                body: body ? JSON.stringify(body) : undefined,
+                redirect: 'error',
+                signal: AbortSignal.any([signal, AbortSignal.timeout(30000)]),
+            });
+        }
+        catch {
+            if (signal.aborted)
+                throw new Error('Retrieval cancelled.');
+            throw new Error('Local embeddings are unavailable. Start Ollama and install the configured model.');
+        }
+        if (!response.ok)
+            throw new Error('Local embeddings are unavailable. Check the configured Ollama model.');
+        return response.json();
+    }
+    return {
+        model,
+        async identity(signal) {
+            const data = await request('/api/tags', signal);
+            const found = Array.isArray(data.models) &&
+                data.models.find((item) => item.name === model || item.name === `${model}:latest`);
+            if (!found || typeof found.digest !== 'string')
+                throw new Error('Install the configured embedding model in Ollama before using related search.');
+            // A changed model file gets a fresh table, even when its user-facing tag is unchanged.
+            return `${model}:${found.digest}`;
+        },
+        async embed(texts, kind, signal) {
+            const prefix = model.startsWith('nomic-embed-text')
+                ? kind === 'query'
+                    ? 'search_query: '
+                    : 'search_document: '
+                : '';
+            const data = await request('/api/embed', signal, {
+                model,
+                input: texts.map((text) => prefix + text),
+                truncate: false,
+                keep_alive: '5m',
+            });
+            const vectors = data.embeddings;
+            if (!Array.isArray(vectors) ||
+                vectors.length !== texts.length ||
+                vectors.some((v) => !Array.isArray(v) ||
+                    !v.length ||
+                    v.length > 8192 ||
+                    v.some((n) => typeof n !== 'number' || !Number.isFinite(n)) ||
+                    !v.some((n) => n !== 0)) ||
+                vectors.some((v) => v.length !== vectors[0].length))
+                throw new Error('The local model returned invalid embeddings.');
+            return vectors;
+        },
+    };
+}

package/dist/apps/server/src/ollama-setup.js

@@ -0,0 +1,56 @@
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { parseSearchSettings } from './search-settings.js';
+function executablePaths() {
+    const paths = (process.env.PATH ?? '')
+        .split(delimiter)
+        .filter(isAbsolute)
+        .map((directory) => join(directory, 'ollama'));
+    if (process.platform === 'darwin')
+        paths.push('/Applications/Ollama.app/Contents/Resources/ollama', '/opt/homebrew/bin/ollama', '/usr/local/bin/ollama');
+    else if (process.platform === 'linux')
+        paths.push('/usr/local/bin/ollama', '/usr/bin/ollama');
+    return [...new Set(paths)];
+}
+/** Inspect local installation and model metadata without executing or downloading anything. */
+export async function checkOllamaSetup(model, endpoint, options = {}) {
+    const settings = parseSearchSettings({ enabled: false, agentRetrieval: false, model, endpoint });
+    const signal = AbortSignal.any([options.signal, AbortSignal.timeout(2000)].filter((value) => value !== undefined));
+    const installed = (async () => {
+        for (const path of options.executablePaths ?? executablePaths()) {
+            if (signal.aborted)
+                break;
+            try {
+                await access(path, constants.X_OK);
+                if ((await stat(path)).isFile())
+                    return true;
+            }
+            catch {
+                // An absent executable is expected on a server that still needs setup.
+            }
+        }
+        return false;
+    })();
+    let running = false;
+    let modelAvailable = null;
+    try {
+        const response = await fetch(new URL('/api/tags', settings.endpoint), {
+            redirect: 'error',
+            signal,
+        });
+        if (!response.ok)
+            throw new Error('Model list unavailable.');
+        const data = await response.json();
+        if (!data || typeof data !== 'object' || !('models' in data) || !Array.isArray(data.models))
+            throw new Error('Invalid model list.');
+        if (!data.models.every((item) => item && typeof item.name === 'string' && typeof item.digest === 'string'))
+            throw new Error('Invalid model list.');
+        running = true;
+        modelAvailable = data.models.some((item) => item.name === settings.model || item.name === `${settings.model}:latest`);
+    }
+    catch {
+        // Unreachable services, redirects and non-Ollama responses do not complete these steps.
+    }
+    return { installed: (await installed) || running, running, modelAvailable };
+}

package/dist/apps/server/src/planning.js

@@ -0,0 +1,30 @@
+import { parsePlanningBoard } from '../../../packages/protocol/src/planning.js';
+/** Pure validation before either model proposals or human edits mutate durable state. */
+export function updatePlanningBoard(current, proposal, sourceRunIds) {
+    const next = parsePlanningBoard(proposal);
+    if (next.revision !== current.revision)
+        throw new Error('Planning board changed. Reload the latest board before saving.');
+    const sources = new Set(sourceRunIds);
+    for (const item of [...next.ideas, ...next.questions, ...next.tasks]) {
+        if (item.sourceRunIds?.some((id) => !sources.has(id)))
+            throw new Error('Unknown planning source message.');
+    }
+    for (const key of ['ideas', 'tasks', 'questions']) {
+        const ids = new Set(next[key].map((item) => item.id));
+        if (current[key].some((item) => !ids.has(item.id)))
+            throw new Error('Keep existing planning items. Defer or reject them instead of deleting their history.');
+    }
+    for (const key of ['ideas', 'questions', 'tasks']) {
+        for (const previous of current[key]) {
+            const item = next[key].find((item) => item.id === previous.id);
+            if (previous.sourceRunIds?.some((id) => !item.sourceRunIds?.includes(id)))
+                throw new Error('Preserve existing source message references.');
+        }
+    }
+    for (const previous of current.tasks) {
+        const task = next.tasks.find((task) => task.id === previous.id);
+        if (previous.sourceIdeaIds.some((id) => !task.sourceIdeaIds.includes(id)))
+            throw new Error('Preserve existing source idea references.');
+    }
+    return { ...next, revision: current.revision + 1 };
+}

package/dist/apps/server/src/project-agents.js

@@ -0,0 +1,276 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { agentId, agentText, parseAgentDefinition, parseAgentConnection, parseAgentInput, parseAgentInvocation, resolveAgentCapabilities, } from '../../../packages/protocol/src/agents.js';
+/** Owned by a project root Store, never a session Store. No launch, scheduling or external effects. */
+export class ProjectAgents {
+    store;
+    projectId;
+    constructor(store, projectId) {
+        this.store = store;
+        this.projectId = projectId;
+        agentId(projectId);
+        store.db
+            .exec(`CREATE TABLE IF NOT EXISTS agent_versions(kind TEXT NOT NULL, project TEXT NOT NULL, id TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL, PRIMARY KEY(kind,project,id,version));
+      CREATE TABLE IF NOT EXISTS agent_invocations(project TEXT NOT NULL, id TEXT NOT NULL, payload TEXT NOT NULL, PRIMARY KEY(project,id));`);
+    }
+    saveDefinition(input) {
+        const definition = parseAgentDefinition(input);
+        this.saveVersion('definition', definition);
+        return definition;
+    }
+    saveConnection(input) {
+        const connection = parseAgentConnection(input);
+        this.assertProject(connection.projectId);
+        const definition = this.definition(connection.agent.id, connection.agent.version);
+        resolveAgentCapabilities(definition, connection, definition.requestedCapabilities);
+        this.saveVersion('connection', connection);
+        return connection;
+    }
+    definition(id, version) {
+        return parseAgentDefinition(this.readVersion('definition', id, version));
+    }
+    connection(id, version) {
+        return parseAgentConnection(this.readVersion('connection', id, version));
+    }
+    /** Bounded discovery for a future builder. Returns latest versions, not mutable aliases. */
+    listDefinitions(limit = 50) {
+        return this.latest('definition', limit).map(parseAgentDefinition);
+    }
+    definitionVersions(id) {
+        agentId(id);
+        return this.store.db
+            .prepare('SELECT payload FROM agent_versions WHERE kind=? AND project=? AND id=? ORDER BY version DESC')
+            .all('definition', this.projectId, id).map((row) => parseAgentDefinition(JSON.parse(row.payload)));
+    }
+    listConnections(limit = 50) {
+        return this.latest('connection', limit).map(parseAgentConnection);
+    }
+    connectionVersions(id) {
+        agentId(id);
+        return this.store.db
+            .prepare('SELECT payload FROM agent_versions WHERE kind=? AND project=? AND id=? ORDER BY version DESC')
+            .all('connection', this.projectId, id).map((row) => parseAgentConnection(JSON.parse(row.payload)));
+    }
+    latest(kind, limit) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+            throw new Error('Invalid agent list limit.');
+        return this.store.db
+            .prepare(`SELECT payload FROM agent_versions AS v WHERE kind=? AND project=?
+      AND version=(SELECT MAX(version) FROM agent_versions WHERE kind=v.kind AND project=v.project AND id=v.id)
+      ORDER BY id LIMIT ?`)
+            .all(kind, this.projectId, limit).map((r) => JSON.parse(r.payload));
+    }
+    assertProject(projectId) {
+        if (projectId !== this.projectId)
+            throw new Error('Agent record belongs to another project.');
+    }
+    saveVersion(kind, value) {
+        this.assertProject(value.projectId);
+        this.store.transaction(() => {
+            const count = this.store.db
+                .prepare('SELECT COUNT(*) AS n FROM agent_versions WHERE project=?')
+                .get(this.projectId);
+            if (count.n >= 1000)
+                throw new Error('Project agent version limit reached (1000).');
+            const row = this.store.db
+                .prepare('SELECT MAX(version) AS v FROM agent_versions WHERE kind=? AND project=? AND id=?')
+                .get(kind, this.projectId, value.id);
+            if (value.version !== (row.v ?? 0) + 1)
+                throw new Error('Agent versions are immutable; save the next consecutive version.');
+            this.store.db
+                .prepare('INSERT INTO agent_versions VALUES(?,?,?,?,?)')
+                .run(kind, this.projectId, value.id, value.version, JSON.stringify(value));
+        });
+    }
+    readVersion(kind, id, version) {
+        agentId(id);
+        if (!Number.isSafeInteger(version) || version < 1)
+            throw new Error('Invalid agent version.');
+        const row = this.store.db
+            .prepare('SELECT payload FROM agent_versions WHERE kind=? AND project=? AND id=? AND version=?')
+            .get(kind, this.projectId, id, version);
+        if (!row)
+            throw new Error('Agent version not found in this project.');
+        return JSON.parse(row.payload);
+    }
+    /** Explicit caller action only. Captures inputs and both versions before any worker can start. */
+    prepare(connectionId, connectionVersion, input, host) {
+        const connection = this.connection(connectionId, connectionVersion);
+        const definition = this.definition(connection.agent.id, connection.agent.version);
+        return this.prepareFrozen(definition, connection, input, host);
+    }
+    /** Builder-only draft test: never publishes a definition or installs a connection. */
+    prepareTest(value, input, host) {
+        const definition = parseAgentDefinition(value);
+        this.assertProject(definition.projectId);
+        const snapshot = definition.contextRequirements.includes('snapshot');
+        const connection = parseAgentConnection({
+            schemaVersion: 1,
+            projectId: this.projectId,
+            id: `test-${randomUUID()}`,
+            version: 1,
+            agent: { id: definition.id, version: definition.version },
+            placement: snapshot ? 'snapshot-action' : 'conversation-action',
+            trigger: 'manual',
+            inputMapping: {
+                prompt: 'user-message',
+                ...(snapshot
+                    ? { snapshot: 'captured-snapshot' }
+                    : definition.contextRequirements.includes('workspace')
+                        ? { workspace: 'project-workspace' }
+                        : {}),
+            },
+            permissionCeiling: [...host],
+            resultDestination: definition.output,
+        });
+        return this.prepareFrozen(definition, connection, input, host);
+    }
+    prepareFrozen(definition, connection, input, host) {
+        const effectiveCapabilities = resolveAgentCapabilities(definition, connection, host);
+        const mappedInput = parseAgentInput(input, connection);
+        const now = new Date().toISOString();
+        const invocation = {
+            schemaVersion: 1,
+            projectId: this.projectId,
+            id: randomUUID(),
+            sessionId: randomUUID(),
+            runId: randomUUID(),
+            definition,
+            connection,
+            effectiveCapabilities,
+            input: mappedInput,
+            status: 'prepared',
+            revision: 1,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.transaction(() => {
+            const count = this.store.db
+                .prepare('SELECT COUNT(*) AS n FROM agent_invocations WHERE project=?')
+                .get(this.projectId);
+            if (count.n >= 1000)
+                throw new Error('Project invocation limit reached (1000).');
+            const active = this.store.db
+                .prepare(`SELECT COUNT(*) AS n FROM agent_invocations WHERE project=? AND json_extract(payload, '$.status') IN ('prepared','running','cancelling')`)
+                .get(this.projectId);
+            if (active.n >= 20)
+                throw new Error('Project active invocation limit reached (20).');
+            this.store.db
+                .prepare('INSERT INTO agent_invocations VALUES(?,?,?)')
+                .run(this.projectId, invocation.id, JSON.stringify(invocation));
+        });
+        return structuredClone(invocation);
+    }
+    read(id) {
+        agentId(id);
+        const row = this.store.db
+            .prepare('SELECT payload FROM agent_invocations WHERE project=? AND id=?')
+            .get(this.projectId, id);
+        if (!row)
+            throw new Error('Invocation not found in this project.');
+        const record = parseAgentInvocation(JSON.parse(row.payload));
+        this.assertProject(record.projectId);
+        if (record.id !== id)
+            throw new Error('Invocation identity does not match durable key.');
+        return record;
+    }
+    list(limit = 50) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error('Invalid invocation limit.');
+        return this.store.db
+            .prepare('SELECT payload FROM agent_invocations WHERE project=? ORDER BY rowid DESC LIMIT ?')
+            .all(this.projectId, limit).map((r) => {
+            const record = parseAgentInvocation(JSON.parse(r.payload));
+            this.assertProject(record.projectId);
+            return record;
+        });
+    }
+    update(id, revision, change) {
+        return this.store.transaction(() => {
+            const record = this.read(id);
+            if (record.revision !== revision)
+                throw new Error('Invocation changed; reload before acting.');
+            change(record);
+            record.revision++;
+            record.updatedAt = new Date().toISOString();
+            this.store.db
+                .prepare('UPDATE agent_invocations SET payload=? WHERE project=? AND id=?')
+                .run(JSON.stringify(record), this.projectId, id);
+            return record;
+        });
+    }
+    /** One-shot claim. A crash after claiming interrupts, never replays. Recheck current host ceiling. */
+    claim(id, revision, host) {
+        return this.update(id, revision, (record) => {
+            if (record.status !== 'prepared')
+                throw new Error('Invocation is not prepared; replay is prohibited.');
+            const effective = resolveAgentCapabilities(record.definition, record.connection, host);
+            record.effectiveCapabilities = record.effectiveCapabilities.filter((c) => effective.includes(c));
+            if (record.definition.output === 'review-findings' &&
+                !record.effectiveCapabilities.includes('findings.report'))
+                throw new Error('Host no longer permits required findings output.');
+            record.status = 'running';
+        });
+    }
+    cancel(id, revision) {
+        return this.update(id, revision, (record) => {
+            if (record.status === 'prepared')
+                record.status = 'cancelled';
+            else if (record.status === 'running')
+                record.status = 'cancelling';
+            else
+                throw new Error('Invocation cannot be cancelled in its current state.');
+        });
+    }
+    /** Call only after the existing harness has exited/disposed (including cancellation). */
+    finish(id, revision, runId, outcome, error) {
+        return this.update(id, revision, (record) => {
+            if (record.runId !== runId || !['running', 'cancelling'].includes(record.status))
+                throw new Error('Stale or inactive invocation completion.');
+            if (!['completed', 'failed', 'cancelled'].includes(outcome))
+                throw new Error('Invalid invocation outcome.');
+            record.status = record.status === 'cancelling' ? 'cancelled' : outcome;
+            if (error !== undefined)
+                record.error = agentText(error, 'invocation error', 4000);
+        });
+    }
+    /** Startup only, after old workers are gone. No constructor-triggered execution or automatic resume. */
+    recoverInterrupted() {
+        let count = 0;
+        const rows = this.store.db
+            .prepare(`SELECT payload FROM agent_invocations WHERE project=? AND json_extract(payload, '$.status') IN ('prepared','running','cancelling')`)
+            .all(this.projectId);
+        for (const row of rows) {
+            const record = parseAgentInvocation(JSON.parse(row.payload));
+            this.update(record.id, record.revision, (item) => {
+                item.status = 'interrupted';
+                item.error = 'Interrupted by restart; start a new invocation explicitly.';
+            });
+            count++;
+        }
+        return count;
+    }
+    /** Server-owned paths/auth, never values from instructions or input mappings. Uses the shared PiAgent. */
+    startOptions(id, host) {
+        const record = this.read(id);
+        if (record.status !== 'running')
+            throw new Error('Claim invocation before constructing start options.');
+        const snapshot = record.input.snapshot;
+        return {
+            runId: record.runId,
+            cwd: host.cwd,
+            dataDir: join(host.dataDir, 'agent-invocations', record.sessionId),
+            prompt: record.input.prompt,
+            mode: snapshot ? 'review' : 'research',
+            ...(snapshot ? { snapshotOnly: true, snapshot: structuredClone(snapshot) } : {}),
+            auth: host.auth,
+            reasoningLevel: host.reasoningLevel,
+            fastMode: host.fastMode,
+            projectAgent: {
+                invocationId: record.id,
+                instructions: record.definition.instructions,
+                capabilities: [...record.effectiveCapabilities],
+            },
+        };
+    }
+}