@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/dist/src/operator-mcp.js

@@ -0,0 +1,342 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { digest, ServiceError } from './protocol.js';
+const NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]{0,127})\}/g;
+// Literal text around references may only be a short scheme word such as "Bearer ".
+const LITERAL = /^(?:[A-Za-z][A-Za-z-]{0,15} ?)?$/;
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const HEADER = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$/;
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+export function operatorMcpPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME)
+        ? env.XDG_CONFIG_HOME
+        : join(env.HOME || homedir(), '.config');
+    return join(base, 'salaam', 'mcp.json');
+}
+function fail(message) {
+    throw new ServiceError('invalid_mcp_config', message, 400);
+}
+function keys(value, allowed, where) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            fail(`${where}: unknown key "${key}"`);
+}
+function record(value, where) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(`${where} must be an object`);
+    return value;
+}
+/** A value must be built from ${VAR} references; inline secrets are refused. */
+export function assertReference(value, where) {
+    if (typeof value !== 'string' || value.length > 1024)
+        fail(`${where} must be a string`);
+    const names = [...value.matchAll(REF)].map((m) => m[1]);
+    const literal = value.replace(REF, '');
+    if (!names.length || !LITERAL.test(literal))
+        fail(`${where} must reference an environment variable as \${VAR}; inline secrets are refused`);
+    return names;
+}
+function referenceMap(value, where, key) {
+    const map = record(value, where);
+    for (const [k, v] of Object.entries(map)) {
+        if (!key.test(k))
+            fail(`${where}: invalid name "${k}"`);
+        assertReference(v, `${where}.${k}`);
+    }
+    return map;
+}
+/** Shape validation shared by the CLI and the service. Does not touch PATH or env. */
+export function validateDeclaration(input, index = 0) {
+    const where = `servers[${index}]`;
+    const s = record(input, where);
+    if (typeof s.name !== 'string' || !NAME.test(s.name))
+        fail(`${where}.name must match ${NAME.source}`);
+    const at = `server "${s.name}"`;
+    if (s.transport === 'stdio') {
+        keys(s, ['name', 'transport', 'command', 'args', 'cwd', 'env'], at);
+        if (typeof s.command !== 'string' || !s.command || s.command.length > 4096)
+            fail(`${at}: command is required`);
+        if (!isAbsolute(s.command) && s.command.includes('/'))
+            fail(`${at}: command must be absolute or a bare name on PATH`);
+        if (s.args !== undefined &&
+            (!Array.isArray(s.args) ||
+                s.args.length > 256 ||
+                s.args.some((a) => typeof a !== 'string' || a.length > 4096)))
+            fail(`${at}: args must be a list of strings`);
+        if (s.cwd !== undefined && (typeof s.cwd !== 'string' || !isAbsolute(s.cwd)))
+            fail(`${at}: cwd must be absolute`);
+        if (s.env !== undefined)
+            referenceMap(s.env, `${at}: env`, ENV_KEY);
+        return {
+            name: s.name,
+            transport: 'stdio',
+            command: s.command,
+            ...(s.args ? { args: [...s.args] } : {}),
+            ...(s.cwd ? { cwd: s.cwd } : {}),
+            ...(s.env ? { env: { ...s.env } } : {}),
+        };
+    }
+    if (s.transport === 'http') {
+        keys(s, ['name', 'transport', 'url', 'headers'], at);
+        if (typeof s.url !== 'string' || !URL.canParse(s.url))
+            fail(`${at}: url is invalid`);
+        const url = new URL(s.url);
+        if (url.username || url.password)
+            fail(`${at}: url must not carry credentials`);
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname)))
+            fail(`${at}: url must be https (http only on loopback)`);
+        if (s.headers !== undefined)
+            referenceMap(s.headers, `${at}: headers`, HEADER);
+        return {
+            name: s.name,
+            transport: 'http',
+            url: s.url,
+            ...(s.headers ? { headers: { ...s.headers } } : {}),
+        };
+    }
+    fail(`${at}: transport must be "stdio" or "http"`);
+}
+export function validateOperatorMcp(input) {
+    const file = record(input, 'mcp.json');
+    keys(file, ['version', 'servers'], 'mcp.json');
+    if (file.version !== 1)
+        fail('mcp.json: version must be 1');
+    if (!Array.isArray(file.servers) || file.servers.length > 64)
+        fail('mcp.json: servers must be a list of at most 64');
+    const servers = file.servers.map((s, i) => validateDeclaration(s, i));
+    const seen = new Set();
+    for (const s of servers) {
+        if (seen.has(s.name))
+            fail(`mcp.json: duplicate server name "${s.name}"`);
+        seen.add(s.name);
+    }
+    return { version: 1, servers };
+}
+export function readOperatorMcpFile(path) {
+    if (!existsSync(path))
+        return { version: 1, servers: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        fail(`${path} is not valid JSON`);
+    }
+    return validateOperatorMcp(parsed);
+}
+export function writeOperatorMcpFile(path, file) {
+    const valid = validateOperatorMcp(file);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(valid, null, 2) + '\n', { mode: 0o600 });
+    renameSync(temp, path);
+}
+export const declarationDigest = (d) => digest(d);
+export function resolveCommand(command, env) {
+    const executable = (path) => {
+        try {
+            return statSync(path).isFile() && (statSync(path).mode & 0o111) !== 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (isAbsolute(command)) {
+        if (!executable(command))
+            fail(`command ${command} is not an executable file`);
+        return command;
+    }
+    for (const dir of (env.PATH ?? '').split(delimiter))
+        if (dir && isAbsolute(dir) && executable(join(dir, command)))
+            return join(dir, command);
+    fail(`command "${command}" is not on PATH`);
+}
+function resolveReferences(map, env, where) {
+    if (!map)
+        return undefined;
+    return Object.fromEntries(Object.entries(map).map(([k, v]) => [
+        k,
+        v.replace(REF, (_m, name) => {
+            const value = env[name];
+            if (value === undefined)
+                fail(`${where}.${k} references unset variable ${name}`);
+            return value;
+        }),
+    ]));
+}
+const CALL_TIMEOUT_MS = 120_000;
+const RESULT_LIMIT = 262_144;
+export class OperatorMcp {
+    file;
+    servers;
+    digest;
+    sessions = new Map();
+    secrets;
+    /** Resolves commands and references now, so a bad declaration refuses service start. */
+    constructor(file, env = process.env) {
+        this.file = file;
+        const valid = validateOperatorMcp(file);
+        this.servers = valid.servers.map((declaration) => {
+            const declaration_digest = declarationDigest(declaration);
+            if (declaration.transport === 'stdio') {
+                const command = resolveCommand(declaration.command, env);
+                return {
+                    declaration,
+                    command,
+                    env: resolveReferences(declaration.env, env, `server "${declaration.name}": env`),
+                    provenance: {
+                        name: declaration.name,
+                        source: 'operator',
+                        transport: 'stdio',
+                        command,
+                        args: declaration.args ?? [],
+                        declaration_digest,
+                    },
+                };
+            }
+            return {
+                declaration,
+                headers: resolveReferences(declaration.headers, env, `server "${declaration.name}": headers`),
+                provenance: {
+                    name: declaration.name,
+                    source: 'operator',
+                    transport: 'http',
+                    url: declaration.url,
+                    declaration_digest,
+                },
+            };
+        });
+        this.digest = digest(valid);
+        this.secrets = this.servers
+            .flatMap((s) => [...Object.values(s.env ?? {}), ...Object.values(s.headers ?? {})])
+            .filter((v) => v.length >= 8);
+    }
+    static load(path, env = process.env) {
+        return new OperatorMcp(readOperatorMcpFile(path), env);
+    }
+    provenance() {
+        return this.servers.map((s) => structuredClone(s.provenance));
+    }
+    get empty() {
+        return this.servers.length === 0;
+    }
+    server(name) {
+        const server = this.servers.find((s) => s.declaration.name === name);
+        if (!server)
+            throw new ServiceError('invalid_mcp_server', 'Unknown declared MCP server', 400);
+        return server;
+    }
+    connection(session, server) {
+        let owned = this.sessions.get(session);
+        if (!owned)
+            this.sessions.set(session, (owned = new Map()));
+        const existing = owned.get(server.declaration.name);
+        if (existing)
+            return existing;
+        const client = new Client({ name: 'salaam', version: '1' }, { capabilities: {} });
+        const d = server.declaration;
+        const transport = d.transport === 'stdio'
+            ? new StdioClientTransport({
+                command: server.command,
+                args: d.args ?? [],
+                ...(d.cwd ? { cwd: d.cwd } : {}),
+                ...(server.env ? { env: server.env } : {}),
+                stderr: 'ignore',
+            })
+            : new StreamableHTTPClientTransport(new URL(d.url), {
+                requestInit: { headers: server.headers ?? {}, redirect: 'error' },
+            });
+        const connection = {
+            client,
+            transport,
+            ready: client.connect(transport, { timeout: 30_000 }),
+        };
+        connection.ready.catch(() => owned.delete(d.name));
+        owned.set(d.name, connection);
+        return connection;
+    }
+    redact(text) {
+        let out = text;
+        for (const secret of this.secrets)
+            out = out.split(secret).join('[redacted]');
+        return out;
+    }
+    failure(error) {
+        if (error instanceof ServiceError)
+            throw error;
+        throw new ServiceError('mcp_server_failed', this.redact(`Declared MCP server failed: ${error?.message ?? 'unknown'}`).slice(0, 512), 502);
+    }
+    async catalog(session, serverName, tool) {
+        if (serverName === undefined || serverName === null || serverName === '')
+            return { servers: this.provenance().map(({ name, transport }) => ({ name, transport })) };
+        const server = this.server(serverName);
+        try {
+            const c = this.connection(session, server);
+            await c.ready;
+            const { tools } = await c.client.listTools(undefined, { timeout: 30_000 });
+            if (tool === undefined || tool === null || tool === '')
+                return {
+                    server: server.declaration.name,
+                    tools: tools.map((t) => ({ name: t.name, description: t.description ?? '' })),
+                };
+            const found = tools.find((t) => t.name === tool);
+            if (!found)
+                throw new ServiceError('invalid_mcp_tool', 'Unknown tool on that server', 400);
+            return { server: server.declaration.name, tool: found };
+        }
+        catch (error) {
+            this.failure(error);
+        }
+    }
+    async call(session, serverName, tool, args, signal) {
+        const server = this.server(serverName);
+        if (typeof tool !== 'string' || !tool || tool.length > 128)
+            throw new ServiceError('invalid_mcp_tool', 'A tool name is required', 400);
+        if (args !== undefined && (args === null || typeof args !== 'object' || Array.isArray(args)))
+            throw new ServiceError('invalid_mcp_arguments', 'Arguments must be an object', 400);
+        try {
+            const c = this.connection(session, server);
+            await c.ready;
+            const result = await c.client.callTool({ name: tool, arguments: (args ?? {}) }, undefined, { timeout: CALL_TIMEOUT_MS, ...(signal ? { signal } : {}) });
+            const parts = Array.isArray(result.content) ? result.content : [];
+            let budget = RESULT_LIMIT;
+            const content = parts.map((part) => {
+                const text = this.redact(part.type === 'text' ? String(part.text) : JSON.stringify(part)).slice(0, Math.max(0, budget));
+                budget -= text.length;
+                return { type: 'text', text };
+            });
+            if (result.structuredContent && !content.length)
+                content.push({
+                    type: 'text',
+                    text: this.redact(JSON.stringify(result.structuredContent)).slice(0, RESULT_LIMIT),
+                });
+            return { content, is_error: !!result.isError };
+        }
+        catch (error) {
+            this.failure(error);
+        }
+    }
+    async stopSession(session) {
+        const owned = this.sessions.get(session);
+        this.sessions.delete(session);
+        if (!owned)
+            return;
+        await Promise.allSettled([...owned.values()].map((c) => c.client.close()));
+    }
+    async close() {
+        await Promise.allSettled([...this.sessions.keys()].map((s) => this.stopSession(s)));
+    }
+}
+/** Both sources may serve one session; a shared name is refused rather than shadowed. */
+export function mergeMcpProvenance(operator, agentpod) {
+    const names = new Set(agentpod.map((s) => s.name));
+    const clash = operator.find((s) => names.has(s.name));
+    if (clash)
+        throw new ServiceError('mcp_name_collision', `Declared MCP server "${clash.name}" collides with an AgentPod-assigned server`, 409);
+    return [...operator, ...agentpod];
+}

package/dist/src/persona.js

@@ -0,0 +1,31 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { digest } from './protocol.js';
+/**
+ * Item 9: the operator's persona for this host's agent. A plain UTF-8 text file the operator
+ * reviews at `host plan`; the manifest pins its path and digest, `host start` refuses a changed
+ * file, and every worker on the host gets it as a final system-prompt section. It shapes voice and
+ * conduct only: it grants no tool, path or permission, and no workspace file can supply it.
+ */
+export const PERSONA_MAX_BYTES = 16 * 1024;
+export function loadPersona(path) {
+    if (!isAbsolute(path) || realpathSync(path) !== path)
+        throw Error('Use a canonical absolute persona path');
+    const st = statSync(path);
+    if (!st.isFile() || st.size > PERSONA_MAX_BYTES)
+        throw Error('A persona is a regular file of at most 16 KiB');
+    const raw = readFileSync(path);
+    const text = raw.toString('utf8');
+    if (Buffer.from(text, 'utf8').compare(raw) !== 0 || text.includes('\0'))
+        throw Error('A persona is UTF-8 text');
+    if (!text.trim())
+        throw Error('A persona must not be empty');
+    return { text, digest: digest({ persona: text }) };
+}
+/** The section appended to the system prompt. */
+export function personaSection(p) {
+    return ("\n\n## Persona (set by this host's operator)\n" +
+        'This shapes your voice and conduct only. It grants no tools, paths or permissions, and it never ' +
+        'overrides approvals, policy or the facts of a tool result.\n\n' +
+        p.text.trim());
+}

package/dist/src/pi.js

@@ -1,9 +1,30 @@
+import { redactFailureText } from './acp-outcome.js';
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import { ServiceError, object, textDigest } from './protocol.js';
 export class PiCommandError extends Error {
 }
+/**
+ * The text a finished tool returned, for the board's activity stream. A card showed every step
+ * with `result: null` because only the status crossed over. Images are left out, known secret
+ * shapes are redacted, and the text is clipped to 2 KiB.
+ */
+function toolOutput(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return {};
+    const text = content
+        .filter((p) => p && p.type === 'text' && typeof p.text === 'string')
+        .map((p) => p.text)
+        .join('\n');
+    if (!text)
+        return {};
+    const clean = redactFailureText(text);
+    return clean.length > 2048
+        ? { output: clean.slice(0, 2047) + '…', output_truncated: true }
+        : { output: clean };
+}
 // The upstream client does not expose process identity/group ownership or the
 // extension UI subprotocol. Keep this narrow transport behind the Pi adapter.
 export class PiProcess extends EventEmitter {
@@ -78,7 +99,7 @@ export class PiProcess extends EventEmitter {
                                     input_digest: textDigest(input),
                                     input_truncated: input.length > 8192,
                                 }
-                                : { failed: record.isError === true }),
+                                : { failed: record.isError === true, ...toolOutput(record.result) }),
                         });
                     }
                     this.emit('record', record);

package/dist/src/protocol.js

@@ -34,9 +34,10 @@ export function workerCapabilities(coding, childTools) {
         ...(childTools?.includes('salaam_station') ? ['protected-station-v1'] : []),
         ...(childTools?.includes('salaam_workspace') ? ['local-workspace-read'] : []),
         ...(childTools?.includes('salaam_local') ? ['local-coding-reviewed'] : []),
+        ...(childTools?.includes('salaam_operator_mcp') ? ['operator-mcp-v1'] : []),
     ];
 }
-export function workerTools(effects, child = false, coding, childTools, mcp = false, toolkit = false, station = false, local = false, localCoding = false) {
+export function workerTools(effects, child = false, coding, childTools, mcp = false, toolkit = false, station = false, local = false, localCoding = false, operatorMcp = false) {
     return child
         ? [...(childTools ?? ['salaam_probe'])].sort()
         : [
@@ -47,7 +48,9 @@ export function workerTools(effects, child = false, coding, childTools, mcp = fa
             ...(coding?.commands ? ['salaam_command'] : []),
             ...(mcp ? ['salaam_mcp'] : []),
             ...(toolkit ? ['salaam_toolkit'] : []),
-            ...(station ? ['salaam_station'] : []),
+            // salaam_board: read-only board reads, served by the hub (operator ruling 2026-10-28).
+            ...(station ? ['salaam_board', 'salaam_station'] : []),
+            ...(operatorMcp ? ['salaam_operator_mcp'] : []),
         ].sort();
 }
 export class ServiceError extends Error {

package/dist/src/rate-limit-retries.js

@@ -0,0 +1,62 @@
+/**
+ * A provider 429 on a step is retried as a fresh admitted attempt of that step, after a backoff,
+ * up to RATE_LIMIT_MAX_FAILURES rate-limited attempts in all. Each retry is a new attempt with its
+ * own admission and budget charge, never a replay of the refused request. After the last one the
+ * task stops with RATE_LIMIT_STOP, a block the stopped-run recovery can prove and settle.
+ */
+export const RATE_LIMIT_MAX_FAILURES = 3;
+export const RATE_LIMIT_BACKOFF_MS = [30_000, 60_000, 120_000];
+export const RATE_LIMIT_STOP = 'Provider rate limit reached';
+export class RateLimitRetries {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS task_rate_limits(
+      task_id TEXT NOT NULL,
+      step_id TEXT NOT NULL,
+      attempt_id TEXT NOT NULL UNIQUE,
+      failures INTEGER NOT NULL,
+      retry_at INTEGER NOT NULL,
+      PRIMARY KEY(task_id, step_id, failures))`);
+    }
+    /** Whether this attempt failed because the provider rate-limited it. */
+    rateLimited(attempt) {
+        const row = this.store.db.prepare('SELECT state,outcome FROM attempts WHERE id=?').get(attempt);
+        if (!row || row.state !== 'failed' || typeof row.outcome !== 'string')
+            return false;
+        try {
+            return JSON.parse(row.outcome)?.failure?.kind === 'rate_limit';
+        }
+        catch {
+            return false;
+        }
+    }
+    /** What the driver does with a task whose step failed. Records each rate-limited attempt once. */
+    decide(task, now = Date.now()) {
+        const failed = task.steps.filter((s) => ['failed', 'interrupted', 'cancelled'].includes(s.state));
+        const step = failed[0];
+        if (failed.length !== 1 || !step || step.state !== 'failed' || !step.attempt_id)
+            return { action: 'none' };
+        if (!this.rateLimited(step.attempt_id))
+            return { action: 'none' };
+        let row = this.store.db
+            .prepare('SELECT failures,retry_at FROM task_rate_limits WHERE attempt_id=?')
+            .get(step.attempt_id);
+        if (!row) {
+            const prior = Number(this.store.db
+                .prepare('SELECT count(*) AS n FROM task_rate_limits WHERE task_id=? AND step_id=?')
+                .get(task.id, step.id).n);
+            const failures = prior + 1;
+            const retry_at = now + (RATE_LIMIT_BACKOFF_MS[failures - 1] ?? RATE_LIMIT_BACKOFF_MS.at(-1));
+            this.store.db
+                .prepare('INSERT INTO task_rate_limits VALUES (?,?,?,?,?)')
+                .run(task.id, step.id, step.attempt_id, failures, retry_at);
+            row = { failures, retry_at };
+        }
+        if (row.failures >= RATE_LIMIT_MAX_FAILURES)
+            return { action: 'stop', reason: RATE_LIMIT_STOP };
+        if (now < row.retry_at)
+            return { action: 'wait' };
+        return { action: 'retry', step: step.id, n: row.failures };
+    }
+}

package/dist/src/recurring-work.js

@@ -110,6 +110,7 @@ export class RecurringWork {
                     checks,
                 })),
                 acceptance: task.acceptance,
+                ...(task.completion_gate ? { completion_gate: task.completion_gate } : {}),
                 deliverables: task.deliverables,
                 limits: task.limits,
             };

package/dist/src/repository-snapshots.js

@@ -54,9 +54,12 @@ export class RepositorySnapshots {
     }
     read(binding, args) {
         const tree = this.tree(binding), action = string(args.action, 'action', 32), offset = integer(args.offset ?? 0, 'offset');
+        // A snapshot-only reviewer (the critic) has no workspace; leave those fields out rather than
+        // undefined, since every read result is digested into the journal (card_5dcbd5d9be5c4183).
         const identity = {
-            workspace_id: binding.workspace?.id,
-            revision: binding.workspace?.revision,
+            ...(binding.workspace
+                ? { workspace_id: binding.workspace.id, revision: binding.workspace.revision }
+                : {}),
             digest: binding.repository.digest,
             artifact_id: binding.repository.artifact_id,
         };

package/dist/src/run-grants.js

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto';
+export const runGrantPrefix = (runId) => /^run_[A-Za-z0-9]{6,}$/.test(runId) ? `runs/${runId}/` : null;
+/** Whether a station patch's arguments are a write a grant for this prefix may answer. */
+export function runGrantCovers(prefix, args) {
+    if (args.action !== 'patch' || typeof args.content !== 'string')
+        return false;
+    const path = args.path;
+    if (typeof path !== 'string' || !path.startsWith(prefix) || path.length === prefix.length)
+        return false;
+    return path.split('/').every((s) => s !== '' && s !== '.' && s !== '..' && !s.startsWith('.'));
+}
+export class RunGrants {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS run_grants(
+      id TEXT PRIMARY KEY NOT NULL,
+      session_id TEXT NOT NULL,
+      task_id TEXT NOT NULL,
+      plan_revision INTEGER NOT NULL,
+      binding_digest TEXT NOT NULL,
+      path_prefix TEXT NOT NULL,
+      approval_id TEXT NOT NULL UNIQUE,
+      granted_by TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      revoked_at TEXT)`);
+    }
+    /** Within the caller's transaction, next to the decision that granted it. Idempotent per approval. */
+    createInTransaction(input) {
+        if (!this.store.db.isTransaction)
+            throw Error('A run grant is created with its decision');
+        const saved = this.store.db
+            .prepare('SELECT * FROM run_grants WHERE approval_id=?')
+            .get(input.approval_id);
+        if (saved)
+            return saved;
+        const grant = {
+            ...input,
+            id: randomUUID(),
+            created_at: new Date().toISOString(),
+            revoked_at: null,
+        };
+        this.store.db
+            .prepare('INSERT INTO run_grants VALUES (?,?,?,?,?,?,?,?,?,?)')
+            .run(grant.id, grant.session_id, grant.task_id, grant.plan_revision, grant.binding_digest, grant.path_prefix, grant.approval_id, grant.granted_by, grant.created_at, null);
+        this.store.event(grant.session_id, 'run_grant.created', {
+            grant_id: grant.id,
+            approval_id: grant.approval_id,
+            task_id: grant.task_id,
+            path_prefix: grant.path_prefix,
+        });
+        return grant;
+    }
+    /** The live grant for exactly this session, task, plan revision and binding, if any. */
+    active(scope) {
+        if (['cancelled', 'succeeded', 'succeeded_with_exception'].includes(scope.task_state))
+            return null;
+        return (this.store.db
+            .prepare('SELECT * FROM run_grants WHERE session_id=? AND task_id=? AND plan_revision=? AND binding_digest=? AND revoked_at IS NULL ORDER BY created_at DESC LIMIT 1')
+            .get(scope.session_id, scope.task_id, scope.plan_revision, scope.binding_digest) ?? null);
+    }
+}