@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/approval-rules.js

@@ -0,0 +1,287 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { object, ServiceError } from './protocol.js';
+const SHELL_SPECIAL = /[;&|<>`$(){}\\\n\r*?[\]~!#]/;
+const PRIVATE_PART = /^(\.|credentials$|secrets$)/;
+/** The command's words, or null when a shell would read it as more than plain words. */
+export function commandArgv(command) {
+    const words = [];
+    let word = '', inWord = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (ch === "'") {
+            const end = command.indexOf("'", i + 1);
+            if (end < 0)
+                return null;
+            word += command.slice(i + 1, end);
+            inWord = true;
+            i = end;
+        }
+        else if (ch === '"') {
+            const end = command.indexOf('"', i + 1);
+            if (end < 0)
+                return null;
+            const inner = command.slice(i + 1, end);
+            if (/[$`\\]/.test(inner))
+                return null;
+            word += inner;
+            inWord = true;
+            i = end;
+        }
+        else if (ch === ' ' || ch === '\t') {
+            if (inWord)
+                words.push(word);
+            word = '';
+            inWord = false;
+        }
+        else if (SHELL_SPECIAL.test(ch))
+            return null;
+        else {
+            word += ch;
+            inWord = true;
+        }
+    }
+    if (inWord)
+        words.push(word);
+    // A leading NAME=value is an environment assignment, not a command word.
+    if (!words.length || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]))
+        return null;
+    return words;
+}
+function patternWords(pattern) {
+    const words = pattern.trim().split(/\s+/);
+    if (!pattern.trim() || words.some((w) => /[;&|<>`$(){}\\'"!#~?[\]]/.test(w)))
+        throw new ServiceError('invalid_rule', 'A command rule is plain words; a word may use *, and a final * takes any further words');
+    return words;
+}
+const wordRe = (w) => new RegExp('^' +
+    w
+        .split('*')
+        .map((p) => p.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('.*') +
+    '$');
+function commandMatches(pattern, argv) {
+    const words = patternWords(pattern);
+    const rest = words[words.length - 1] === '*';
+    const fixed = rest ? words.slice(0, -1) : words;
+    if (rest ? argv.length < fixed.length : argv.length !== fixed.length)
+        return false;
+    return fixed.every((w, i) => wordRe(w).test(argv[i]));
+}
+/** A project-relative glob as a regex: `**` spans segments, `*` stays within one. */
+function globRe(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        if (glob.startsWith('**/', i)) {
+            re += '(?:.*/)?';
+            i += 2;
+        }
+        else if (glob.startsWith('/**', i) && i + 3 === glob.length) {
+            re += '(?:/.*)?';
+            i += 2;
+        }
+        else if (glob.startsWith('**', i)) {
+            re += '.*';
+            i += 1;
+        }
+        else if (glob[i] === '*')
+            re += '[^/]*';
+        else
+            re += glob[i].replace(/[.+^${}()|[\]\\?]/g, '\\$&');
+    }
+    return new RegExp('^' + re + '$');
+}
+const pathMatches = (globs, path) => globs.some((g) => globRe(g).test(path));
+export function validateRule(value) {
+    const input = object(value);
+    if (Object.keys(input).some((k) => !['effect', 'tool', 'command', 'paths'].includes(k)))
+        throw new ServiceError('invalid_rule', 'A rule has effect, tool, and command or paths only');
+    if (!['allow', 'ask', 'deny'].includes(String(input.effect)))
+        throw new ServiceError('invalid_rule', 'A rule effect is allow, ask or deny');
+    if (!['command', 'edit', 'any'].includes(String(input.tool)))
+        throw new ServiceError('invalid_rule', 'A rule tool is command, edit or any');
+    const rule = { effect: input.effect, tool: input.tool };
+    if (input.command !== undefined) {
+        if (typeof input.command !== 'string' || input.command.length > 512 || input.tool === 'edit')
+            throw new ServiceError('invalid_rule', 'Only command rules take a command pattern');
+        patternWords(input.command);
+        rule.command = input.command.trim().split(/\s+/).join(' ');
+    }
+    if (input.paths !== undefined) {
+        const paths = input.paths;
+        if (input.tool === 'command' ||
+            !Array.isArray(paths) ||
+            !paths.length ||
+            paths.length > 32 ||
+            paths.some((p) => typeof p !== 'string' ||
+                p.length > 512 ||
+                p.startsWith('/') ||
+                /[\x00-\x1f\x7f\\]/.test(p) ||
+                p.split('/').some((part) => !part || part === '..' || PRIVATE_PART.test(part))))
+            throw new ServiceError('invalid_rule', 'Edit rules take up to 32 project-relative globs; no absolute paths, traversal or private paths');
+        rule.paths = [...paths];
+    }
+    if (rule.tool === 'edit' && !rule.paths)
+        throw new ServiceError('invalid_rule', 'An edit rule names the paths it covers');
+    return rule;
+}
+/** The deciding rule for a request: deny beats ask beats allow; no match asks. */
+export function evaluateRules(rules, request) {
+    const matching = rules.filter((r) => {
+        if (r.tool !== 'any' && r.tool !== request.tool)
+            return false;
+        if (request.tool === 'command') {
+            if (r.paths)
+                return false;
+            if (!r.command)
+                return r.effect === 'deny' || request.argv !== null;
+            return request.argv !== null && commandMatches(r.command, request.argv);
+        }
+        if (!r.paths)
+            return r.tool === 'any' && !r.command;
+        return r.effect === 'allow'
+            ? request.paths.length > 0 && request.paths.every((p) => pathMatches(r.paths, p))
+            : request.paths.some((p) => pathMatches(r.paths, p));
+    });
+    for (const effect of ['deny', 'ask', 'allow']) {
+        const rule = matching.find((r) => r.effect === effect);
+        if (rule)
+            return { effect, rule };
+    }
+    return { effect: 'ask' };
+}
+export function defaultUserRulesFile(env = process.env) {
+    return (env.SALAAM_PERMISSIONS_FILE ||
+        join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'salaam', 'permissions.json'));
+}
+export class ApprovalRules {
+    store;
+    userFile;
+    constructor(store, userFile = defaultUserRulesFile()) {
+        this.store = store;
+        this.userFile = userFile;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS approval_rules(
+      id TEXT PRIMARY KEY NOT NULL,
+      scope TEXT NOT NULL CHECK(scope IN ('session','repo')),
+      session_id TEXT,
+      root TEXT NOT NULL,
+      rule TEXT NOT NULL,
+      created_at INTEGER NOT NULL)`);
+    }
+    /** Whether rules apply: only desk sessions, never host-managed (AgentPod) or child work. */
+    applies(session) {
+        if (!this.store.localCoding(session))
+            return false;
+        const has = (sql) => {
+            try {
+                return !!this.store.db.prepare(sql).get(session);
+            }
+            catch {
+                return false;
+            }
+        };
+        return (!has('SELECT 1 FROM agentpod_admissions WHERE session_id=?') &&
+            !has('SELECT 1 FROM child_tasks WHERE child_session=?'));
+    }
+    userRules() {
+        let text;
+        try {
+            text = readFileSync(this.userFile, 'utf8');
+        }
+        catch {
+            return { rules: [] };
+        }
+        try {
+            const doc = object(JSON.parse(text));
+            if (doc.version !== 1 || !Array.isArray(doc.rules))
+                throw new Error('expected {"version": 1, "rules": [...]}');
+            return {
+                rules: doc.rules.map((r, i) => ({
+                    ...validateRule(r),
+                    id: 'user:' + i,
+                    source: 'user',
+                })),
+            };
+        }
+        catch (error) {
+            return {
+                rules: [],
+                problem: `${this.userFile} is ignored: ${error instanceof Error ? error.message : 'unreadable'}`,
+            };
+        }
+    }
+    list(session) {
+        const root = this.store.session(session).cwd;
+        const stored = this.store.db
+            .prepare("SELECT id,scope,rule FROM approval_rules WHERE (scope='session' AND session_id=?) OR (scope='repo' AND root=?) ORDER BY created_at,rowid")
+            .all(session, root);
+        return [
+            ...stored.map((r) => ({
+                ...JSON.parse(r.rule),
+                id: r.id,
+                source: r.scope,
+            })),
+            ...this.userRules().rules,
+        ];
+    }
+    problems(session) {
+        void session;
+        const problem = this.userRules().problem;
+        return problem ? [problem] : [];
+    }
+    add(session, scope, value, request) {
+        const rule = validateRule(value);
+        if (!this.applies(session))
+            throw new ServiceError('rules_unavailable', 'Approval rules apply only to desk coding sessions');
+        return this.store.request('local-operator', request, { kind: 'approval-rule', session, scope, rule }, () => {
+            const id = randomUUID();
+            this.store.db
+                .prepare('INSERT INTO approval_rules(id,scope,session_id,root,rule,created_at) VALUES(?,?,?,?,?,?)')
+                .run(id, scope, scope === 'session' ? session : null, this.store.session(session).cwd, JSON.stringify(rule), Date.now());
+            this.store.event(session, 'approval_rule.added', { id, scope, rule });
+            return { ...rule, id, source: scope };
+        });
+    }
+    remove(session, id) {
+        const root = this.store.session(session).cwd;
+        const done = this.store.db
+            .prepare("DELETE FROM approval_rules WHERE id=? AND ((scope='session' AND session_id=?) OR (scope='repo' AND root=?))")
+            .run(id, session, root);
+        if (!done.changes)
+            throw new ServiceError('rule_not_found', 'No such rule for this session or repository');
+        this.store.event(session, 'approval_rule.removed', { id });
+    }
+    /** The rule an approved operation stands for: the exact command words, or the exact edited paths. */
+    ruleFor(args) {
+        if (args.action === 'command') {
+            const argv = commandArgv(args.command ?? '');
+            if (!argv)
+                throw new ServiceError('invalid_rule', 'This command uses shell features a rule cannot match safely; approve it once instead');
+            const quote = (w) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(w) && !w.includes('*') ? w : null;
+            if (argv.some((w) => quote(w) === null))
+                throw new ServiceError('invalid_rule', 'This command has words a rule cannot spell exactly; approve it once instead');
+            return validateRule({ effect: 'allow', tool: 'command', command: argv.join(' ') });
+        }
+        if (args.action === 'edit' && args.edits?.length)
+            return validateRule({ effect: 'allow', tool: 'edit', paths: args.edits.map((e) => e.path) });
+        throw new ServiceError('invalid_rule', 'Only local commands and edits can become rules');
+    }
+    addFromOperation(session, operation, scope, request) {
+        const row = this.store.db
+            .prepare('SELECT args,session_id FROM local_calls WHERE operation_id=?')
+            .get(operation);
+        if (!row || row.session_id !== session)
+            throw new ServiceError('rule_not_found', 'That request is not a local command or edit in this session');
+        return this.add(session, scope, this.ruleFor(JSON.parse(row.args)), request);
+    }
+}
+/** Why a reviewed request can only be approved once: a command with shell features (pipes,
+ * redirects, substitutions) can never become an approval rule. Undefined when a rule is possible. */
+export function onceOnlyReason(value) {
+    const command = /\nCommand:\n([\s\S]*)$/.exec(value)?.[1];
+    return command !== undefined && commandArgv(command) === null
+        ? 'This command uses shell features (pipes, redirects, substitutions), so it cannot become a rule. Approve it once or deny it.'
+        : undefined;
+}

package/dist/src/attach.js

@@ -41,7 +41,7 @@ export class Outbox {
         renameSync(temporary, path);
         syncDirectory(this.dir);
     }
-    enqueue(text, revision, continues) {
+    enqueue(text, revision, continues, confirmSensitive = false) {
         if (!text.trim() || text.length > 256 * 1024 || text.trimStart().startsWith('/'))
             throw new Error('Enter a plain instruction of at most 256 Ki characters');
         const created = this.records().reduce((latest, record) => Math.max(latest, record.created_at + 1), Date.now());
@@ -51,6 +51,7 @@ export class Outbox {
             expected_revision: revision,
             text,
             ...(continues ? { continues_attempt_id: continues } : {}),
+            ...(confirmSensitive ? { confirm_sensitive: true } : {}),
         };
         this.save(record);
         return record;
@@ -174,6 +175,7 @@ export class Outbox {
                             'approval_mismatch',
                             'binding_changed',
                             'attempt_settled',
+                            'sensitive_attachment',
                         ].includes(error.code) ||
                             (record.command && error.code === 'not_found') ||
                             (['task', 'job'].includes(record.command?.kind ?? '') &&

package/dist/src/autonomy.js

@@ -1,5 +1,20 @@
 import { realpathSync } from 'node:fs';
 import { canonical, digest, object, ServiceError } from './protocol.js';
+const MODES = [
+    'inspect',
+    'review',
+    'scoped-edit',
+    'accept-edits',
+    'auto',
+];
+/** Modes in which the service performs no local mutation, however it was approved. */
+const READ_ONLY_MODES = ['inspect'];
+/** Shift+Tab: review → accept edits → auto → review. Full access and YOLO are never in the cycle. */
+const CYCLE = ['review', 'accept-edits', 'auto'];
+export function nextMode(mode) {
+    const at = CYCLE.indexOf(mode);
+    return at < 0 ? 'review' : CYCLE[(at + 1) % CYCLE.length];
+}
 export function permissionPolicy(store, session) {
     const root = store.session(session).cwd;
     const row = store.db
@@ -17,9 +32,14 @@ export function permissionPolicy(store, session) {
         if (!Number.isSafeInteger(saved.revision) ||
             Number(saved.revision) < 1 ||
             saved.root !== root ||
-            Object.keys(saved).some((key) => !['revision', 'root', 'mode', 'paths'].includes(key)))
+            Object.keys(saved).some((key) => !['revision', 'root', 'mode', 'paths', 'access'].includes(key)))
             throw new Error('Invalid saved policy');
-        const policy = validatePermissions({ mode: saved.mode, paths: saved.paths });
+        const policy = validatePermissions({
+            // Plan mode was removed (operator ruling 2026-10-31): a session saved in it reads as review.
+            mode: saved.mode === 'plan' ? 'review' : saved.mode,
+            paths: saved.paths,
+            ...(saved.access === undefined ? {} : { access: saved.access }),
+        });
         return { ...policy, revision: Number(saved.revision), root };
     }
     catch {
@@ -28,9 +48,10 @@ export function permissionPolicy(store, session) {
 }
 export function validatePermissions(value) {
     const input = object(value);
-    if (Object.keys(input).some((k) => !['mode', 'paths'].includes(k)) ||
-        !['inspect', 'review', 'scoped-edit'].includes(String(input.mode)))
-        throw new ServiceError('invalid_permissions', 'Choose inspect, review or scoped-edit; unknown policy fields are rejected');
+    if (Object.keys(input).some((k) => !['mode', 'paths', 'access'].includes(k)) ||
+        !MODES.includes(String(input.mode)) ||
+        (input.access !== undefined && input.access !== 'full' && input.access !== 'yolo'))
+        throw new ServiceError('invalid_permissions', 'Choose inspect, review, scoped-edit, accept-edits or auto, and access "full", "yolo" or none; unknown policy fields are rejected');
     const paths = input.paths ?? [];
     if (!Array.isArray(paths) ||
         paths.length > 32 ||
@@ -48,16 +69,31 @@ export function validatePermissions(value) {
         throw new ServiceError('invalid_permissions', 'Use up to 32 distinct project-relative files or directories ending in /; no wildcards, traversal or private paths');
     if ((input.mode === 'scoped-edit') !== paths.length > 0)
         throw new ServiceError('invalid_permissions', 'Only scoped-edit takes paths, and requires at least one');
-    return { mode: input.mode, paths: [...paths].sort() };
+    return {
+        mode: input.mode,
+        paths: [...paths].sort(),
+        ...(input.access === 'full' || input.access === 'yolo'
+            ? { access: input.access }
+            : {}),
+    };
 }
-export function configurePermissions(store, session, request, expected, value, actor) {
+export function configurePermissions(store, session, request, expected, value, actor, 
+/** The operator's settings: may an interactive session choose full access or YOLO, and is this a
+ * desk session (YOLO is never for host-managed, board or child work)? */
+opts = {}) {
     const policy = validatePermissions(value);
+    if (policy.access === 'full' && opts.allowFullAccess === false)
+        throw new ServiceError('full_access_denied', 'The operator does not allow full access on this host; commands stay in the OS sandbox');
+    if (policy.access === 'yolo' && (opts.allowYolo === false || opts.deskSession !== true))
+        throw new ServiceError('yolo_denied', opts.deskSession !== true
+            ? 'YOLO is only for your own desk sessions, never host-managed, board or child work'
+            : 'The operator does not allow YOLO on this host; commands keep their approvals');
     return store.request('local-operator', request, { kind: 'configure-permissions', session, expected, policy }, () => {
         store.authorizeControl(session, actor);
         store.execution.assert(session);
         if (!store.localWorkspace(session))
             throw new ServiceError('permissions_unavailable', 'This policy applies only to local workspace sessions, not managed stations or child workers');
-        if (policy.mode !== 'inspect' && !store.localCoding(session))
+        if (!READ_ONLY_MODES.includes(policy.mode) && !store.localCoding(session))
             throw new ServiceError('local_denied', 'Create a coding session first; policy cannot grant missing coding capability');
         const current = permissionPolicy(store, session);
         if (current.revision !== expected)
@@ -80,7 +116,7 @@ export function matchesEditScope(policy, paths) {
 }
 export function assertPermissionBinding(store, session, operation, root) {
     const policy = permissionPolicy(store, session);
-    if (policy.root !== root || policy.mode === 'inspect')
+    if (policy.root !== root || READ_ONLY_MODES.includes(policy.mode))
         throw new ServiceError('permission_denied', 'Current policy does not permit local mutations');
     const binding = store.db
         .prepare("SELECT payload FROM events WHERE session_id=? AND kind='permission.auto-approved' AND json_extract(payload,'$.operation_id')=? ORDER BY seq DESC LIMIT 1")
@@ -88,4 +124,39 @@ export function assertPermissionBinding(store, session, operation, root) {
     if (binding && JSON.parse(binding.payload).policy_digest !== digest(policy))
         throw new ServiceError('permission_changed', 'Auto-approval belongs to an older policy; prepare and review a fresh operation');
 }
+/** A project-relative path the session's modes may edit without review: not private or hidden. */
+function ordinaryProjectPath(path) {
+    return (path.length > 0 &&
+        !path.startsWith('/') &&
+        path
+            .split('/')
+            .every((part) => part !== '' &&
+            part !== '..' &&
+            !part.startsWith('.') &&
+            !['credentials', 'secrets', 'node_modules', 'vendor'].includes(part)));
+}
+/** Whether this policy approves these edits by itself: scoped edits, accept-edits, auto and full
+ * access approve ordinary project edits; YOLO approves every edit. */
+export function autoApprovesEdits(policy, paths) {
+    if (policy.access === 'yolo')
+        return paths.length > 0;
+    if (policy.mode === 'scoped-edit' && !policy.access)
+        return matchesEditScope(policy, paths);
+    return ((policy.mode === 'accept-edits' || policy.mode === 'auto' || policy.access === 'full') &&
+        paths.length > 0 &&
+        paths.every(ordinaryProjectPath));
+}
+/** Whether this policy approves a command by itself: auto inside the OS sandbox; full access unless
+ * the danger check calls the command dangerous; YOLO always. */
+export function autoApprovesCommands(policy, sandboxed, dangerous, 
+/** Pushes or opens a pull request: asks in every mode but YOLO (operator ruling 2026-10-31). */
+publishes = false) {
+    if (policy.access === 'yolo')
+        return true;
+    if (publishes)
+        return false;
+    if (policy.access === 'full')
+        return !dangerous;
+    return policy.mode === 'auto' && sandboxed;
+}
 export const permissionDigest = (policy) => digest(JSON.parse(canonical(policy)));

package/dist/src/board-reads.js

@@ -0,0 +1,106 @@
+import { randomUUID } from 'node:crypto';
+import { ServiceError } from './protocol.js';
+const ITEM = /^itm_[0-9a-f]{16}$/;
+/** The most a hub answer may carry back to the agent. */
+export const BOARD_READ_MAX_BYTES = 256 * 1024;
+const bad = (message) => new ServiceError('invalid_board_read', message, 400);
+/** Closed arguments per action; anything else is refused. */
+export function boardReadArgs(input) {
+    const { action, ...rest } = input;
+    const keys = Object.keys(rest).filter((k) => rest[k] !== undefined);
+    if (action === 'card' || action === 'attempts') {
+        if (keys.length)
+            throw bad(`${action} takes no arguments: it is always this run's own card`);
+        return { action, args: {} };
+    }
+    if (action === 'library_search') {
+        const q = rest.query;
+        if (keys.join() !== 'query' || typeof q !== 'string' || !q.trim() || q.length > 500)
+            throw bad('library_search takes one query of 1 to 500 characters');
+        return { action, args: { query: q.trim() } };
+    }
+    if (action === 'library_get') {
+        const id = rest.item_id;
+        if (keys.join() !== 'item_id' || typeof id !== 'string' || !ITEM.test(id))
+            throw bad('library_get takes one item_id (itm_ and 16 hex characters)');
+        return { action, args: { item_id: id } };
+    }
+    throw bad('Board reads are card, attempts, library_search or library_get');
+}
+export class BoardReads {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS board_reads(
+      id TEXT PRIMARY KEY, session_id TEXT NOT NULL, tool_call_id TEXT NOT NULL, action TEXT NOT NULL,
+      args TEXT NOT NULL, state TEXT NOT NULL, ok INTEGER, text TEXT, error TEXT,
+      created_at TEXT NOT NULL, answered_at TEXT, UNIQUE(session_id, tool_call_id))`);
+    }
+    view(row) {
+        return {
+            id: String(row.id),
+            action: String(row.action),
+            args: JSON.parse(String(row.args)),
+            state: String(row.state),
+            ...(row.state === 'answered'
+                ? {
+                    ok: row.ok === 1,
+                    ...(row.text !== null ? { text: String(row.text) } : {}),
+                    ...(row.error !== null ? { error: String(row.error) } : {}),
+                }
+                : {}),
+        };
+    }
+    /** Record a read for this session, once per tool call. */
+    request(session, toolCallId, input) {
+        const { action, args } = boardReadArgs(input);
+        const existing = this.store.db
+            .prepare('SELECT * FROM board_reads WHERE session_id=? AND tool_call_id=?')
+            .get(session, toolCallId);
+        if (existing)
+            return this.view(existing);
+        const id = randomUUID();
+        this.store.db
+            .prepare("INSERT INTO board_reads(id,session_id,tool_call_id,action,args,state,created_at) VALUES (?,?,?,?,?,'pending',?)")
+            .run(id, session, toolCallId, action, JSON.stringify(args), new Date().toISOString());
+        return this.get(session, id);
+    }
+    get(session, id) {
+        const row = this.store.db
+            .prepare('SELECT * FROM board_reads WHERE id=? AND session_id=?')
+            .get(id, session);
+        if (!row)
+            throw new ServiceError('board_read_not_found', 'No such board read', 404);
+        return this.view(row);
+    }
+    /** What the hub should serve for this session, oldest first. */
+    pending(session) {
+        return this.store.db
+            .prepare("SELECT * FROM board_reads WHERE session_id=? AND state='pending' ORDER BY rowid LIMIT 8")
+            .all(session)
+            .map((r) => {
+            const v = this.view(r);
+            return { id: v.id, action: v.action, args: v.args };
+        });
+    }
+    /** The hub's answer: once, for a read of this session, bounded. */
+    answer(session, value) {
+        const a = (value ?? {});
+        const keys = Object.keys(a).sort().join();
+        const ok = a.ok === true;
+        if (typeof a.read_id !== 'string' ||
+            (ok
+                ? keys !== 'ok,read_id,text' || typeof a.text !== 'string'
+                : keys !== 'error,ok,read_id' || a.ok !== false || typeof a.error !== 'string'))
+            throw bad('Closed board read answer required');
+        const body = ok ? a.text : a.error;
+        if (Buffer.byteLength(body) > (ok ? BOARD_READ_MAX_BYTES : 2048))
+            throw bad('Board read answer too large');
+        const done = this.store.db
+            .prepare("UPDATE board_reads SET state='answered',ok=?,text=?,error=?,answered_at=? WHERE id=? AND session_id=? AND state='pending'")
+            .run(ok ? 1 : 0, ok ? body : null, ok ? null : body, new Date().toISOString(), a.read_id, session);
+        if (done.changes !== 1)
+            throw new ServiceError('board_read_settled', 'That board read is not pending for this run', 409);
+        return this.get(session, a.read_id);
+    }
+}

package/dist/src/children.js

@@ -169,6 +169,89 @@ export class ChildWork {
             this.start(child);
         return child;
     }
+    /**
+     * The task critic (item 8): a reviewer child over an immutable snapshot of the verified
+     * deliverables. No parent attempt is active at completion, so it is linked to the task's last
+     * step attempt and charged to its own bounded budget, never to an attempt's reservation. The
+     * grant must be the built-in reviewer; the child can read the snapshot and report findings only.
+     */
+    spawnCritic(parent, parentAttempt, step, prompt, budget, grant, snapshot) {
+        if (!Number.isSafeInteger(budget) || budget < 1 || budget > 8)
+            throw new ServiceError('invalid_budget', 'Critic request budget must be 1–8');
+        if (grant.profile.id !== 'salaam/reviewer' || grant.owner_session !== parent)
+            throw new ServiceError('authority_denied', 'The critic must be the built-in reviewer');
+        if (!Object.keys(snapshot).length)
+            throw new ServiceError('invalid_child', 'A critic needs a snapshot of the verified deliverables');
+        if (!prompt.trim() || prompt.length > 32768)
+            throw new ServiceError('invalid_child', 'Invalid critic prompt');
+        const authority = [...grant.profile.tools].sort();
+        const input = digest({
+            prompt,
+            budget,
+            critic: grant.profile_digest,
+            snapshot: digest(snapshot),
+        });
+        const prepare = () => {
+            const old = this.store.db
+                .prepare('SELECT * FROM child_tasks WHERE parent_session=? AND step_key=?')
+                .get(parent, step);
+            if (old) {
+                if (old.input_digest !== input)
+                    throw new ServiceError('spawn_conflict', 'Critic step already binds a different review');
+                return { child: old, fresh: false };
+            }
+            if (this.paused)
+                throw new ServiceError('stopping', 'Child dispatch is stopping');
+            this.store.execution.assert(parent);
+            if (this.activeCount() >= 8)
+                throw new ServiceError('child_limit', 'Daemon worker admission limit reached');
+            const effectivePrompt = `${grant.profile.prompt}\n\nGoal:\n${prompt}`;
+            const id = randomUUID(), session = randomUUID(), submission = randomUUID(), childAttempt = randomUUID();
+            this.store.db
+                .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
+                .run(session, this.store.session(parent).cwd, session);
+            this.store.db
+                .prepare('INSERT INTO submissions(id,session_id,text,attempt_id) VALUES (?,?,?,?)')
+                .run(submission, session, effectivePrompt, childAttempt);
+            this.store.db
+                .prepare("INSERT INTO attempts(id,session_id,submission_id,state) VALUES (?,?,?,'accepted')")
+                .run(childAttempt, session, submission);
+            this.store.db
+                .prepare("INSERT INTO child_tasks(id,parent_session,parent_attempt,step_key,input_digest,child_session,child_attempt,authority,budget,state) VALUES (?,?,?,?,?,?,?,?,?,'accepted')")
+                .run(id, parent, parentAttempt, step, input, session, childAttempt, JSON.stringify(authority), budget);
+            this.store.taskChildReserve?.(parent, childAttempt, budget);
+            this.store.usage.budget(childAttempt, budget);
+            const artifact = this.artifacts.prepare(session, effectivePrompt);
+            artifact.commit();
+            // The reviewed snapshot is the verified bytes; its base is empty, so its diff is all of it.
+            const current = this.artifacts.prepare(session, JSON.stringify(snapshot)), base = this.artifacts.prepare(session, JSON.stringify({}));
+            current.commit();
+            base.commit();
+            this.store.workerBoundary.freeze(this.owned(session), artifact.id, false, grant, {
+                artifact_id: current.id,
+                base_artifact: base.id,
+                digest: digest(snapshot),
+            });
+            this.store.event(session, 'session.created', { parent_session: parent, child_id: id });
+            this.store.event(session, 'submission.accepted', {
+                attempt_id: childAttempt,
+                submission_id: submission,
+            });
+            this.store.event(parent, 'child.spawned', {
+                child_id: id,
+                child_session: session,
+                step_key: step,
+                budget,
+                authority,
+                critic: true,
+            });
+            return { child: this.inspect(parent, id), fresh: true };
+        };
+        const { child, fresh } = this.store.transaction(prepare);
+        if (fresh)
+            this.start(child);
+        return child;
+    }
     activeCount(parent) {
         return Number(this.store.db
             .prepare(`SELECT count(*) AS n FROM child_tasks c WHERE (? IS NULL OR c.parent_session=?) AND (c.state='accepted' OR EXISTS(SELECT 1 FROM workers w WHERE w.session_id=c.child_session AND w.state!='exited') OR EXISTS(SELECT 1 FROM external_runs e WHERE e.child_id=c.id AND e.stopped=0))`)