@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/dist/src/supervisor.js

@@ -1,12 +1,15 @@
+import { BoardReads } from './board-reads.js';
+import { HostBreaker, callThroughBreaker } from './host-breaker.js';
 import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { EventEmitter } from 'node:events';
-import { mkdirSync, existsSync, writeFileSync, readFileSync, readlinkSync } from 'node:fs';
+import { mkdirSync, existsSync, writeFileSync, readFileSync, readlinkSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { PROTOCOL_VERSION, canonical, object, ServiceError, textDigest, workerTools, workerCapabilities, string, } from './protocol.js';
 import { PI_CLI, HOUSE_EXTENSION, POLICY_DIGEST, bundleDigest, VERSION, PI_VERSION, } from './config.js';
 import { readinessFingerprint } from './readiness-fingerprint.js';
 import { PiProcess, PiCommandError } from './pi.js';
+import { mergeMcpProvenance } from './operator-mcp.js';
 import { OFFLINE_ROUTE, providerRoute, providerHasOutputCap, } from './provider-config.js';
 import { validateApiKey } from './credentials.js';
 import { resolveProviderAuth } from './provider-auth.js';
@@ -37,7 +40,18 @@ export function processIdentity(pid) {
                     throw Error('Invalid process start identity');
                 return { start: fields[19], group: fields[2], session: fields[3] };
             };
-            const before = stat(), boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(), executable = readlinkSync(path + '/exe'), argv = readFileSync(path + '/cmdline');
+            const before = stat(), boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(), 
+            // A tools-user launcher (sudo) is root-owned; its exe link is unreadable to the service.
+            executable = (() => {
+                try {
+                    return readlinkSync(path + '/exe');
+                }
+                catch (error) {
+                    if (error.code === 'EACCES')
+                        return 'unreadable';
+                    throw error;
+                }
+            })(), argv = readFileSync(path + '/cmdline');
             if (!/^[a-f0-9-]{36}$/.test(boot) ||
                 !argv.length ||
                 argv.length > 16384 ||
@@ -75,8 +89,12 @@ export class Supervisor extends EventEmitter {
     localCoding;
     tasks;
     compactionJobs = new Set();
+    fetchBreaker = new HostBreaker();
     managed;
     mcp;
+    operatorMcp;
+    /** Item 9: the host's pinned persona, given to every worker on this host. */
+    persona;
     toolkit;
     station;
     children;
@@ -118,7 +136,26 @@ export class Supervisor extends EventEmitter {
         const child = this.children?.owned(id);
         if (child)
             return JSON.parse(child.authority);
-        return workerTools(!!this.options.effectsEnabled, !!this.children?.owned(id), this.codingBinding(id), undefined, !!this.mcp, !!this.toolkit, !!this.station, this.store.localWorkspace(id), this.store.localCoding(id));
+        return workerTools(!!this.options.effectsEnabled, !!this.children?.owned(id), this.codingBinding(id), undefined, !!this.mcp, !!this.toolkit, !!this.station, this.store.localWorkspace(id), this.store.localCoding(id), this.declaredMcp(id));
+    }
+    /** Operator-declared MCP reaches root sessions only; children get no MCP authority. */
+    declaredMcp(id) {
+        return !!this.operatorMcp && !this.operatorMcp.empty && !this.children?.owned(id);
+    }
+    /** Every MCP server the session got, from both sources; persisted beside the worker. */
+    mcpServers(id) {
+        const live = this.workers.get(id)?.mcpServers;
+        if (live)
+            return structuredClone(live);
+        try {
+            const path = join(this.options.stateDir, 'workers', id, 'mcp-servers.json');
+            return existsSync(path)
+                ? JSON.parse(readFileSync(path, 'utf8'))
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
     childBoundary(id, epoch) {
         const child = this.children?.owned(id);
@@ -149,6 +186,10 @@ export class Supervisor extends EventEmitter {
     }
     bootId = randomUUID();
     workers = new Map();
+    boardReadsStore;
+    get boardReads() {
+        return (this.boardReadsStore ??= new BoardReads(this.store));
+    }
     monitor;
     bundle;
     constructor(store, options) {
@@ -276,6 +317,18 @@ export class Supervisor extends EventEmitter {
                 worker.mcp = await this.mcp.ready(id);
             if (this.toolkit && !child)
                 worker.toolkit = await this.toolkit.ready(id);
+            if (this.declaredMcp(id))
+                worker.operatorMcp = this.operatorMcp.provenance();
+            if (worker.operatorMcp || worker.mcp) {
+                // Collisions are refused at admission; nothing is silently shadowed.
+                worker.mcpServers = mergeMcpProvenance(worker.operatorMcp ?? [], (worker.mcp?.servers ?? []).map((server) => ({
+                    name: server.name,
+                    source: 'agentpod',
+                    transport: 'http',
+                    endpoint_digest: server.endpoint_digest,
+                    declaration_digest: digest(server),
+                })));
+            }
             if (this.station && !child)
                 worker.station = this.station.ready(id);
             this.store.execution.assert(id);
@@ -290,6 +343,11 @@ export class Supervisor extends EventEmitter {
             }), { mode: 0o600 });
             const sessionDir = join(workerDir, 'sessions');
             mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+            const provenancePath = join(workerDir, 'mcp-servers.json');
+            if (worker.mcpServers)
+                writeFileSync(provenancePath, JSON.stringify(worker.mcpServers, null, 2), { mode: 0o600 });
+            else
+                rmSync(provenancePath, { force: true });
             const config = {
                 socket: this.options.bridgeSocket,
                 token: worker.token,
@@ -306,8 +364,11 @@ export class Supervisor extends EventEmitter {
                 local: this.store.localWorkspace(id),
                 localCoding: this.store.localCoding(id),
                 ...(worker.mcp ? { mcp: worker.mcp } : {}),
+                ...(worker.operatorMcp ? { operator_mcp: worker.operatorMcp } : {}),
+                ...(worker.mcpServers ? { mcp_servers: worker.mcpServers } : {}),
                 ...(worker.toolkit ? { toolkit: worker.toolkit } : {}),
                 ...(worker.station ? { station: worker.station } : {}),
+                ...(this.persona ? { persona: this.persona } : {}),
             };
             const args = [
                 PI_CLI,
@@ -543,6 +604,36 @@ export class Supervisor extends EventEmitter {
         }
         return w;
     }
+    /** Is this attempt a task step that has acceptance checks to decide it? */
+    checkedStepAttempt(attempt) {
+        const row = this.store.db
+            .prepare('SELECT checks FROM task_steps WHERE attempt_id=?')
+            .get(attempt);
+        try {
+            const checks = row?.checks ? JSON.parse(String(row.checks)) : [];
+            return Array.isArray(checks) && checks.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A station call refused before it runs leaves no station_calls row, so record its
+     * method, requested action and refusal code: never its path, arguments or content. */
+    recordStationRefusal(id, method, body, error) {
+        const args = body.args && typeof body.args === 'object' ? body.args : {};
+        const ident = (v) => typeof v === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(v) ? v : null;
+        try {
+            this.store.transaction(() => this.store.event(id, 'station.call_refused', {
+                attempt_id: this.workers.get(id)?.attempt ?? null,
+                method: ident(method),
+                action: ident(args.action),
+                code: error instanceof ServiceError ? ident(error.code) : 'error',
+            }));
+        }
+        catch {
+            // Recording a refusal never changes the refusal itself.
+        }
+    }
     async bridge(id, method, token, body) {
         const w = this.authenticate(id, token, body);
         const route = w.route;
@@ -587,8 +678,14 @@ export class Supervisor extends EventEmitter {
                     context_digest: textDigest(w.frame),
                     ...(boundary ? { worker_binding: boundary } : {}),
                     ...(w.mcp ? { mcp: w.mcp } : {}),
+                    ...(w.operatorMcp ? { operator_mcp: w.operatorMcp } : {}),
+                    ...(w.mcpServers
+                        ? { mcp_servers: w.mcpServers, mcp_servers_digest: digest(w.mcpServers) }
+                        : {}),
                     ...(w.toolkit ? { toolkit: w.toolkit } : {}),
                     ...(w.station ? { station: w.station } : {}),
+                    // Item 9: the worker proves it runs with the host's pinned persona.
+                    ...(this.persona ? { persona_digest: this.persona.digest } : {}),
                 };
                 for (const [key, value] of Object.entries(expected))
                     if (canonical(body[key]) !== canonical(value))
@@ -680,6 +777,45 @@ export class Supervisor extends EventEmitter {
                 w.secrets = [...new Set([...(w.secrets ?? []), ...credentialStrings(auth)])];
                 return auth;
             }
+            if (method.startsWith('operator_mcp.')) {
+                if (!this.declaredMcp(id) || !w.operatorMcp || !w.attempt)
+                    throw new ServiceError('mcp_disabled', 'Worker has no declared MCP servers', 403);
+                this.assertActive(id, w.epoch, w.attempt);
+                if (method === 'operator_mcp.catalog')
+                    return await this.operatorMcp.catalog(id, body.server, body.tool);
+                if (method !== 'operator_mcp.call')
+                    throw new ServiceError('invalid_field', 'Unknown declared MCP method', 400);
+                const attempt = w.attempt;
+                const args = body.arguments ?? {};
+                const server = String(body.server ?? ''), tool = String(body.tool ?? '');
+                // A host failing again and again is paused briefly (never called, so no operator MCP call
+                // is recorded); the agent gets a tool error and the run carries on.
+                return await callThroughBreaker(this.fetchBreaker, id, args, (paused) => this.store.transaction(() => this.store.event(id, 'fetch.host_paused', { attempt_id: attempt, ...paused })), async () => {
+                    try {
+                        const result = await this.operatorMcp.call(id, body.server, body.tool, args);
+                        this.store.transaction(() => this.store.event(id, 'operator_mcp.call', {
+                            attempt_id: attempt,
+                            server,
+                            tool,
+                            argument_digest: digest(args),
+                            outcome: result.is_error ? 'tool_error' : 'returned',
+                            result_digest: digest(result),
+                        }));
+                        return result;
+                    }
+                    catch (error) {
+                        this.store.transaction(() => this.store.event(id, 'operator_mcp.call', {
+                            attempt_id: attempt,
+                            server,
+                            tool,
+                            argument_digest: digest(args),
+                            outcome: 'failed',
+                            error: error.code ?? 'mcp_server_failed',
+                        }));
+                        throw error;
+                    }
+                });
+            }
             if (method.startsWith('toolkit.')) {
                 if (!this.toolkit || !w.toolkit || !w.attempt || this.children?.owned(id))
                     throw new ServiceError('toolkit_disabled', 'Worker has no native Toolkit authority', 403);
@@ -732,6 +868,15 @@ export class Supervisor extends EventEmitter {
                         : {}),
                 };
             }
+            if (method === 'board.read' || method === 'board.status') {
+                // Read-only board reads, served by the hub (operator ruling 2026-10-28, option iii).
+                if (!this.station || !w.station || !w.attempt || this.children?.owned(id))
+                    throw new ServiceError('station_disabled', 'Board reads need protected station work');
+                this.assertActive(id, w.epoch, w.attempt);
+                return method === 'board.read'
+                    ? this.boardReads.request(id, string(body.tool_call_id, 'tool_call_id', 512), object(body.args))
+                    : this.boardReads.get(id, string(body.read_id, 'read_id', 64));
+            }
             if (method.startsWith('station.')) {
                 if (!this.station || !w.station || !w.attempt || this.children?.owned(id))
                     throw new ServiceError('station_disabled', 'Station execution is unavailable');
@@ -948,6 +1093,8 @@ export class Supervisor extends EventEmitter {
         }
         catch (error) {
             this.store.taskBudgetDenied?.(id, error);
+            if (method.startsWith('station.'))
+                this.recordStationRefusal(id, method, body, error);
             if (method.startsWith('station.') &&
                 error instanceof ServiceError &&
                 [
@@ -960,6 +1107,16 @@ export class Supervisor extends EventEmitter {
                     'not_found',
                 ].includes(error.code))
                 throw error;
+            if (method.startsWith('operator_mcp.') &&
+                error instanceof ServiceError &&
+                [
+                    'invalid_field',
+                    'invalid_mcp_server',
+                    'invalid_mcp_tool',
+                    'invalid_mcp_arguments',
+                    'mcp_server_failed',
+                ].includes(error.code))
+                throw error;
             if ((method.startsWith('mcp.') || method.startsWith('toolkit.')) &&
                 error instanceof ServiceError &&
                 [
@@ -1064,6 +1221,7 @@ export class Supervisor extends EventEmitter {
                         ? null
                         : 'No provider-enforced output cap; tasks must explicitly disable token budgeting',
                 },
+            ...(this.mcpServers(id) ? { mcp_servers: this.mcpServers(id) } : {}),
         };
         const w = this.workers.get(id);
         if (w?.invalid)
@@ -1317,11 +1475,17 @@ export class Supervisor extends EventEmitter {
                         outcome = candidate;
                 }
             }
-            if (value.type === 'tool_execution_end' && value.isError === true)
+            // A checked task step is decided by its checks, not by a tool error the model went on
+            // to recover from (operator decision, 2026-10-23). The error stays in the journal
+            // (tool.finished failed=true). A delegated child turn, whose denied probes are its
+            // boundary proof, and any attempt outside a checked step still fail on it.
+            if (value.type === 'tool_execution_end' &&
+                value.isError === true &&
+                (this.children?.owned(id) || !this.checkedStepAttempt(work.attempt.id)))
                 outcome ??= {
                     version: 1,
                     stopReason: 'error',
-                    failure: acpFailure(new ServiceError('tool_failed', 'Tool execution failed')),
+                    failure: acpFailure(new ServiceError('tool_failed', toolFailureMessage(value.toolName))),
                 };
         };
         w.pi.on('record', record);
@@ -1386,6 +1550,7 @@ export class Supervisor extends EventEmitter {
         try {
             this.managed?.invalidateWorker(w.id, w.epoch);
             this.cancelMcpWorker(w);
+            void this.operatorMcp?.stopSession(w.id).catch(() => { });
             this.children?.workerLost(w.id, 'Worker stopped before child dispatch');
         }
         catch {
@@ -1414,3 +1579,10 @@ export class Supervisor extends EventEmitter {
             throw new AggregateError(errors, 'Worker shutdown could not persist all final states');
     }
 }
+/** Names the failing tool (never its arguments or output), so a failed step says which call
+ * failed it. Only a plain tool identifier is echoed. */
+export function toolFailureMessage(toolName) {
+    return typeof toolName === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(toolName)
+        ? `Tool execution failed (tool ${toolName})`
+        : 'Tool execution failed';
+}

package/dist/src/task-budget.js

@@ -6,6 +6,12 @@ export class TaskBudgetError extends ServiceError {
         this.session_id = session_id;
     }
 }
+/** Tools a critic review child may hold and still be left out of the verification busy check. */
+export const READ_ONLY_REVIEW_TOOLS = [
+    'salaam_findings',
+    'salaam_probe',
+    'salaam_repository',
+];
 export class TaskBudget {
     store;
     tasks;
@@ -23,6 +29,8 @@ export class TaskBudget {
         store.taskChildFinished = (attempt) => this.releaseChild(attempt);
         store.taskCommandAdmission = (session) => this.command(session);
         store.taskRemainingRuntime = (session) => this.remaining(session);
+        // Only the task's own session: a child's attempt keeps the budget its reservation set.
+        store.taskAttemptRequestLimit = (session) => this.tasks.forSession(session)?.limits.requests;
     }
     task(session) {
         const direct = this.tasks.forSession(session);
@@ -39,14 +47,42 @@ export class TaskBudget {
             .n);
         return { ...runtime, invocations_spent: n, external_model_usage: n ? 'unknown' : 'none' };
     }
-    active(task) {
+    /** The child attempt of each running critic review of this task revision whose recorded
+     * tools are all read-only (operator ruling 2026-10-30, option A). Only verification reads may
+     * leave these out of the busy count: the reviewer reads a digest-bound snapshot and cannot
+     * write the workspace, run a command or reach the station (staging card_019a647a169744ff). */
+    readOnlyReviews(task) {
+        if (!this.store.db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_critics'")
+            .get())
+            return [];
+        const rows = this.store.db
+            .prepare("SELECT c.child_attempt, c.authority FROM task_critics r JOIN child_tasks c ON c.id=r.child_id WHERE r.task_id=? AND r.plan_revision=? AND r.state='running' AND c.parent_session=?")
+            .all(task.id, task.plan_revision, task.session_id);
+        return rows
+            .filter((r) => {
+            try {
+                const tools = JSON.parse(r.authority);
+                return (Array.isArray(tools) &&
+                    tools.every((t) => READ_ONLY_REVIEW_TOOLS.includes(t)));
+            }
+            catch {
+                return false;
+            }
+        })
+            .map((r) => r.child_attempt);
+    }
+    /** Live work in the task's session tree. `verification` leaves out a running read-only review's
+     * child attempt, for verification reads only; admission and concurrency count everything. */
+    active(task, opts = {}) {
+        const excluded = JSON.stringify(opts.verification ? this.readOnlyReviews(task) : []);
         const row = this.store.db
             .prepare(`WITH tree(id) AS (SELECT ? UNION ALL SELECT child_session FROM child_tasks WHERE parent_session=?) SELECT
-      (SELECT count(*) FROM attempts WHERE session_id IN (SELECT id FROM tree) AND state IN ('accepted','dispatching','running')) +
+      (SELECT count(*) FROM attempts WHERE session_id IN (SELECT id FROM tree) AND state IN ('accepted','dispatching','running') AND id NOT IN (SELECT value FROM json_each(?))) +
       (SELECT count(*) FROM station_calls WHERE session_id IN (SELECT id FROM tree) AND kind='check' AND attempt_id IS NULL AND state IN ('prepared','dispatching')) +
       (SELECT count(*) FROM command_runs WHERE session_id IN (SELECT id FROM tree) AND state NOT IN ('succeeded','failed','cancelled','timed_out','output_limited','interrupted')) +
       (SELECT count(*) FROM external_runs e JOIN child_tasks c ON c.id=e.child_id JOIN attempts a ON a.id=c.child_attempt WHERE c.parent_session=? AND e.stopped=0 AND a.state NOT IN ('accepted','dispatching','running')) AS n`)
-            .get(task.session_id, task.session_id, task.session_id);
+            .get(task.session_id, task.session_id, excluded, task.session_id);
         return Number(row.n);
     }
     deny(session, message) {

package/dist/src/task-critic.js

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * The completion critic (item 8). When the admitted plan declares a critic, the built-in reviewer
+ * reads an immutable snapshot of the verified deliverables against the plan's rubric before the
+ * task may complete. Its verdict is bound to the exact verified evidence (checks and tree): any
+ * later change makes it stale. A critical or high finding means changes are needed; a reviewer
+ * that reports nothing at all is a failure, never a pass.
+ */
+export const CRITIC_BUDGET = 4;
+export const CRITIC_REOPENS = 2;
+export class TaskCritic {
+    store;
+    artifacts;
+    deps;
+    constructor(store, artifacts, deps) {
+        this.store = store;
+        this.artifacts = artifacts;
+        this.deps = deps;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS task_critics(
+      id TEXT PRIMARY KEY NOT NULL,
+      task_id TEXT NOT NULL,
+      plan_revision INTEGER NOT NULL,
+      evidence_digest TEXT NOT NULL,
+      round INTEGER NOT NULL,
+      child_id TEXT NOT NULL,
+      state TEXT NOT NULL,
+      findings TEXT,
+      reason TEXT,
+      UNIQUE(task_id, plan_revision, evidence_digest))`);
+    }
+    /** Whether this exact verified evidence has a passing critic verdict. */
+    passed(task, evidenceDigest) {
+        return (this.store.db
+            .prepare("SELECT 1 FROM task_critics WHERE task_id=? AND plan_revision=? AND evidence_digest=? AND state='pass'")
+            .get(task.id, task.plan_revision, evidenceDigest) !== undefined);
+    }
+    /** How many times the critic has sent this plan revision back for changes. */
+    reopens(task) {
+        return Number(this.store.db
+            .prepare("SELECT count(*) AS n FROM task_critics WHERE task_id=? AND plan_revision=? AND state='changes_needed'")
+            .get(task.id, task.plan_revision).n);
+    }
+    /** The verdict for this verified evidence, starting the reviewer the first time it is asked. */
+    async gate(task, evidenceDigest, deliverables) {
+        const critic = task.completion_gate?.critic;
+        if (!critic)
+            return { state: 'pass' };
+        const row = this.store.db
+            .prepare('SELECT * FROM task_critics WHERE task_id=? AND plan_revision=? AND evidence_digest=?')
+            .get(task.id, task.plan_revision, evidenceDigest);
+        if (row)
+            return this.settle(row);
+        const last = this.store.db
+            .prepare('SELECT b.attempt_id FROM task_step_attempts b JOIN task_steps s ON s.id=b.step_id WHERE s.task_id=? ORDER BY b.rowid DESC LIMIT 1')
+            .get(task.id);
+        if (!last)
+            return { state: 'failed', reason: 'No step attempt for the critic to follow' };
+        if (!deliverables.length)
+            return { state: 'failed', reason: 'No verified deliverables to review' };
+        const round = Number(this.store.db
+            .prepare('SELECT count(*) AS n FROM task_critics WHERE task_id=? AND plan_revision=?')
+            .get(task.id, task.plan_revision).n) + 1;
+        const snapshot = Object.fromEntries(deliverables.map((d) => [
+            d.path,
+            { content: Buffer.from(d.content, 'utf8').toString('base64'), executable: false },
+        ]));
+        const grant = await this.deps.admit(task, `critic:${task.id}:${task.plan_revision}`);
+        const child = this.deps.spawn(task, String(last.attempt_id), `critic-${task.plan_revision}-${round}`, [
+            'Judge the delivered work against this rubric before it is accepted:',
+            critic.rubric,
+            '',
+            'Objective: ' + task.objective,
+            'Deliverables (the snapshot): ' + deliverables.map((d) => d.path).join(', '),
+            '',
+            'Report findings with salaam_findings, citing the file and line. Use critical or high only',
+            'for what must change before the work is accepted; medium or low for suggestions. If the',
+            'work meets the rubric, report an empty list.',
+        ].join('\n'), CRITIC_BUDGET, grant, snapshot);
+        this.store.db
+            .prepare("INSERT INTO task_critics VALUES (?,?,?,?,?,?,'running',NULL,NULL)")
+            .run(randomUUID(), task.id, task.plan_revision, evidenceDigest, round, child.id);
+        return { state: 'pending' };
+    }
+    settle(row) {
+        if (row.state === 'pass')
+            return { state: 'pass' };
+        if (row.state === 'changes_needed')
+            return { state: 'changes_needed', findings: JSON.parse(String(row.findings)) };
+        if (row.state === 'failed')
+            return { state: 'failed', reason: String(row.reason) };
+        const child = this.store.db
+            .prepare('SELECT state FROM child_tasks WHERE id=?')
+            .get(String(row.child_id));
+        if (!child || child.state === 'accepted')
+            return { state: 'pending' };
+        const report = this.store.db
+            .prepare('SELECT artifact_id FROM specialist_reports WHERE worker_id=?')
+            .get(this.deps.workerId(String(row.child_id)));
+        const set = (state, findings, reason) => this.store.db
+            .prepare('UPDATE task_critics SET state=?,findings=?,reason=? WHERE id=?')
+            .run(state, findings ? JSON.stringify(findings) : null, reason, String(row.id));
+        if (!report) {
+            const reason = 'The critic returned no findings report';
+            set('failed', null, reason);
+            return { state: 'failed', reason };
+        }
+        const findings = JSON.parse(this.artifacts.read(String(report.artifact_id))).findings.map(({ path, line, severity, message }) => ({ path, line, severity, message }));
+        if (findings.some((f) => f.severity === 'critical' || f.severity === 'high')) {
+            set('changes_needed', findings, null);
+            return { state: 'changes_needed', findings };
+        }
+        set('pass', findings, null);
+        return { state: 'pass' };
+    }
+}

package/dist/src/task-driver.js

@@ -1,3 +1,6 @@
+import { CRITIC_REOPENS } from './task-critic.js';
+import { requiredChecks } from './task-policy.js';
+import { RATE_LIMIT_STOP, RateLimitRetries } from './rate-limit-retries.js';
 import { randomUUID } from 'node:crypto';
 import { commandTerminal } from './coding.js';
 import { canonical, ServiceError } from './protocol.js';
@@ -14,6 +17,7 @@ export class TaskDriver {
     awaitingAuthorityRenewal;
     active;
     stopped = true;
+    rateLimits;
     constructor(store, tasks, budget, verification, supervisor, children, coding) {
         this.store = store;
         this.tasks = tasks;
@@ -22,6 +26,7 @@ export class TaskDriver {
         this.supervisor = supervisor;
         this.children = children;
         this.coding = coding;
+        this.rateLimits = new RateLimitRetries(store);
         tasks.assertProgressionBinding = (task, binding) => {
             if (canonical(this.verification.binding(task)) !== binding)
                 throw new ServiceError('task_progression_stale', 'Workspace or execution environment changed since the bounded grant');
@@ -295,6 +300,22 @@ export class TaskDriver {
             return;
         }
         if (task.steps.some((s) => ['interrupted', 'failed', 'cancelled'].includes(s.state))) {
+            // A provider 429 is retried as a fresh attempt of the step after a backoff; past the limit,
+            // or with no progression step left, the task stops with a block recovery can settle.
+            const retry = this.rateLimits.decide(task);
+            if (retry.action === 'wait')
+                return;
+            if (retry.action === 'retry' && Number(r.remaining_steps) >= 1) {
+                if (!(await this.worker(task)) || this.stopped)
+                    return;
+                this.tasks.retryStep(task.id, retry.step, retry.n, Number(r.auto_epoch));
+                return;
+            }
+            if (retry.action !== 'none') {
+                this.budget.block(task.session_id, RATE_LIMIT_STOP);
+                this.stop(task, RATE_LIMIT_STOP);
+                return;
+            }
             this.stop(task, 'An interrupted or failed step requires explicit operator review');
             return;
         }
@@ -334,14 +355,37 @@ export class TaskDriver {
             // A passed receipt cannot be re-observed while another final check owns
             // the native workspace. Wait for the whole set before testing freshness;
             // finishAsync still performs the final transactional evidence validation.
-            if (task.acceptance.some((check) => {
+            if (requiredChecks(task).some((check) => {
                 const receipt = this.verification.latest(task, check.key, null);
                 return receipt?.state === 'accepted' || receipt?.state === 'running';
             }))
                 return;
-            for (const check of task.acceptance)
+            for (const check of requiredChecks(task))
                 if (!(await this.check(task, check.key, null)))
                     return;
+            // Item 8: a declared critic reviews the verified deliverables before completion.
+            if (task.completion_gate?.critic) {
+                const verdict = await this.verification.criticGateAsync(task);
+                if (verdict.state === 'pending')
+                    return;
+                if (verdict.state === 'failed') {
+                    this.stop(task, 'Critic review failed: ' + verdict.reason);
+                    return;
+                }
+                if (verdict.state === 'changes_needed') {
+                    const round = this.verification.critic.reopens(task);
+                    if (round > CRITIC_REOPENS || Number(r.remaining_steps) < 1) {
+                        this.stop(task, 'Critic requested changes');
+                        return;
+                    }
+                    if (!(await this.worker(task)) || this.stopped)
+                        return;
+                    this.tasks.reopenForCritic(task.id, task.steps.at(-1).id, round, Number(r.auto_epoch), verdict.findings
+                        .map((f) => `- ${f.path}:${f.line} (${f.severity}) ${f.message}`)
+                        .join('\n'));
+                    return;
+                }
+            }
             await this.verification.finishAsync(task.id, 'auto-finish:' + task.id + ':' + task.plan_revision, task.revision, null, () => {
                 if (!this.budget.state(task.id).auto_enabled)
                     throw new ServiceError('task_authority', 'Progression paused before completion');

package/dist/src/task-policy.js

@@ -1,5 +1,23 @@
 import { integer, object, ServiceError, string } from './protocol.js';
 import { filePath } from './workspaces.js';
+/** Every check completion requires: the acceptance checks, then each hook as hook-<key>. */
+export function requiredChecks(policy) {
+    return [
+        ...policy.acceptance,
+        ...(policy.completion_gate?.hooks ?? []).map((h) => ({ ...h, key: 'hook-' + h.key })),
+    ];
+}
+const check = (v, keys, what) => {
+    const c = object(v), key = string(c.key, what + ' key', 64);
+    if (!/^[a-zA-Z0-9_-]+$/.test(key) || keys.has(key))
+        throw new ServiceError('invalid_plan', what + ' keys must be unique identifiers', 400);
+    keys.add(key);
+    return {
+        key,
+        command: string(c.command, what + ' command', 4096),
+        cwd: c.cwd === undefined || c.cwd === '.' ? '.' : filePath(c.cwd),
+    };
+};
 export const DEFAULT_TASK_LIMITS = {
     requests: 64,
     runtime_ms: 900000,
@@ -14,17 +32,7 @@ export function taskPolicy(value) {
     if (!Array.isArray(raw) || raw.length > 8)
         throw new ServiceError('invalid_plan', 'Supply at most eight acceptance checks', 400);
     const keys = new Set();
-    const acceptance = raw.map((v) => {
-        const c = object(v), key = string(c.key, 'check key', 64);
-        if (!/^[a-zA-Z0-9_-]+$/.test(key) || keys.has(key))
-            throw new ServiceError('invalid_plan', 'Acceptance keys must be unique identifiers', 400);
-        keys.add(key);
-        return {
-            key,
-            command: string(c.command, 'check command', 4096),
-            cwd: c.cwd === undefined || c.cwd === '.' ? '.' : filePath(c.cwd),
-        };
-    });
+    const acceptance = raw.map((v) => check(v, keys, 'Acceptance'));
     const paths = value.deliverables ?? [];
     if (!Array.isArray(paths) || paths.length > 32)
         throw new ServiceError('invalid_plan', 'Supply at most 32 deliverable paths', 400);
@@ -66,5 +74,29 @@ export function taskPolicy(value) {
             throw new ServiceError('invalid_budget', 'Invocation limit must be 1–64', 400);
         limits.invocations = n;
     }
-    return { acceptance, deliverables, limits };
+    let completion_gate;
+    if (value.completion_gate !== undefined) {
+        const g = object(value.completion_gate);
+        const hooks = g.hooks;
+        const c = g.critic;
+        const critic = c === null
+            ? null
+            : (() => {
+                const v = object(c);
+                if (Object.keys(v).join(',') !== 'rubric')
+                    throw new ServiceError('invalid_plan', 'A critic names only its rubric', 400);
+                return { rubric: string(v.rubric, 'critic rubric', 4096) };
+            })();
+        if (Object.keys(g).sort().join(',') !== 'critic,hooks' ||
+            !Array.isArray(hooks) ||
+            hooks.length > 8 ||
+            (!critic && hooks.length < 1))
+            throw new ServiceError('invalid_plan', 'A completion gate has a critic or 1–8 hooks, and at most 8 hooks', 400);
+        const hookKeys = new Set();
+        completion_gate = { critic, hooks: hooks.map((v) => check(v, hookKeys, 'Hook')) };
+        if (requiredChecks({ acceptance, completion_gate }).length !==
+            new Set(requiredChecks({ acceptance, completion_gate }).map((c) => c.key)).size)
+            throw new ServiceError('invalid_plan', 'A hook collides with an acceptance check', 400);
+    }
+    return { acceptance, deliverables, limits, ...(completion_gate ? { completion_gate } : {}) };
 }