@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/operator-mcp.ts

@@ -0,0 +1,420 @@
+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 type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { digest, ServiceError } from './protocol.js';
+
+/**
+ * Operator-declared MCP servers: the operator's own grant, read only from Salaam's
+ * configuration directory. Workspaces never declare servers; Pi keeps --no-mcp and every
+ * declared server is reached through the daemon over the worker bridge.
+ */
+export interface StdioDeclaration {
+  name: string;
+  transport: 'stdio';
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+}
+export interface HttpDeclaration {
+  name: string;
+  transport: 'http';
+  url: string;
+  headers?: Record<string, string>;
+}
+export type McpDeclaration = StdioDeclaration | HttpDeclaration;
+export interface OperatorMcpFile {
+  version: 1;
+  servers: McpDeclaration[];
+}
+/** Public provenance for one server a session got. Never carries resolved secrets. */
+export interface McpServerProvenance {
+  name: string;
+  source: 'operator' | 'agentpod';
+  transport: 'stdio' | 'http';
+  command?: string;
+  args?: string[];
+  url?: string;
+  endpoint_digest?: string;
+  declaration_digest: string;
+}
+
+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: NodeJS.ProcessEnv = process.env): string {
+  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: string): never {
+  throw new ServiceError('invalid_mcp_config', message, 400);
+}
+function keys(value: Record<string, unknown>, allowed: string[], where: string) {
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key)) fail(`${where}: unknown key "${key}"`);
+}
+function record(value: unknown, where: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    fail(`${where} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+/** A value must be built from ${VAR} references; inline secrets are refused. */
+export function assertReference(value: unknown, where: string): string[] {
+  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: unknown, where: string, key: RegExp): Record<string, string> {
+  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 as Record<string, string>;
+}
+
+/** Shape validation shared by the CLI and the service. Does not touch PATH or env. */
+export function validateDeclaration(input: unknown, index = 0): McpDeclaration {
+  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 as string[])] } : {}),
+      ...(s.cwd ? { cwd: s.cwd as string } : {}),
+      ...(s.env ? { env: { ...(s.env as Record<string, string>) } } : {}),
+    };
+  }
+  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 as Record<string, string>) } } : {}),
+    };
+  }
+  fail(`${at}: transport must be "stdio" or "http"`);
+}
+
+export function validateOperatorMcp(input: unknown): OperatorMcpFile {
+  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<string>();
+  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: string): OperatorMcpFile {
+  if (!existsSync(path)) return { version: 1, servers: [] };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    fail(`${path} is not valid JSON`);
+  }
+  return validateOperatorMcp(parsed);
+}
+export function writeOperatorMcpFile(path: string, file: OperatorMcpFile): void {
+  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: McpDeclaration): string => digest(d);
+
+export function resolveCommand(command: string, env: NodeJS.ProcessEnv): string {
+  const executable = (path: string) => {
+    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: Record<string, string> | undefined,
+  env: NodeJS.ProcessEnv,
+  where: string,
+): Record<string, string> | undefined {
+  if (!map) return undefined;
+  return Object.fromEntries(
+    Object.entries(map).map(([k, v]) => [
+      k,
+      v.replace(REF, (_m, name: string) => {
+        const value = env[name];
+        if (value === undefined) fail(`${where}.${k} references unset variable ${name}`);
+        return value;
+      }),
+    ]),
+  );
+}
+
+interface Resolved {
+  declaration: McpDeclaration;
+  provenance: McpServerProvenance;
+  command?: string;
+  env?: Record<string, string>;
+  headers?: Record<string, string>;
+}
+interface Connection {
+  client: Client;
+  transport: Transport;
+  ready: Promise<void>;
+}
+const CALL_TIMEOUT_MS = 120_000;
+const RESULT_LIMIT = 262_144;
+
+export class OperatorMcp {
+  readonly servers: Resolved[];
+  readonly digest: string;
+  private readonly sessions = new Map<string, Map<string, Connection>>();
+  private readonly secrets: string[];
+
+  /** Resolves commands and references now, so a bad declaration refuses service start. */
+  constructor(
+    readonly file: OperatorMcpFile,
+    env: NodeJS.ProcessEnv = process.env,
+  ) {
+    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: string, env: NodeJS.ProcessEnv = process.env): OperatorMcp {
+    return new OperatorMcp(readOperatorMcpFile(path), env);
+  }
+  provenance(): McpServerProvenance[] {
+    return this.servers.map((s) => structuredClone(s.provenance));
+  }
+  get empty(): boolean {
+    return this.servers.length === 0;
+  }
+  private server(name: unknown): Resolved {
+    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;
+  }
+  private connection(session: string, server: Resolved): Connection {
+    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: 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: Connection = {
+      client,
+      transport,
+      ready: client.connect(transport, { timeout: 30_000 }),
+    };
+    connection.ready.catch(() => owned!.delete(d.name));
+    owned.set(d.name, connection);
+    return connection;
+  }
+  private redact(text: string): string {
+    let out = text;
+    for (const secret of this.secrets) out = out.split(secret).join('[redacted]');
+    return out;
+  }
+  private failure(error: unknown): never {
+    if (error instanceof ServiceError) throw error;
+    throw new ServiceError(
+      'mcp_server_failed',
+      this.redact(`Declared MCP server failed: ${(error as Error)?.message ?? 'unknown'}`).slice(
+        0,
+        512,
+      ),
+      502,
+    );
+  }
+  async catalog(session: string, serverName?: unknown, tool?: unknown): Promise<unknown> {
+    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: string,
+    serverName: unknown,
+    tool: unknown,
+    args: unknown,
+    signal?: AbortSignal,
+  ): Promise<{ content: { type: 'text'; text: string }[]; is_error: boolean }> {
+    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 ?? {}) as Record<string, unknown> },
+        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' as const, 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: string): Promise<void> {
+    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(): Promise<void> {
+    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: readonly McpServerProvenance[],
+  agentpod: readonly McpServerProvenance[],
+): McpServerProvenance[] {
+  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/src/persona.ts

@@ -0,0 +1,37 @@
+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 interface Persona {
+  text: string;
+  digest: string;
+}
+export function loadPersona(path: string): Persona {
+  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: Persona): string {
+  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/src/pi.ts

@@ -1,3 +1,4 @@
+import { redactFailureText } from './acp-outcome.js';
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
@@ -12,10 +13,31 @@ export interface ToolObservation {
   input_digest?: string;
   input_truncated?: boolean;
   failed?: boolean;
+  output?: string;
+  output_truncated?: boolean;
 }
 
 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: unknown): Pick<ToolObservation, 'output' | 'output_truncated'> {
+  const content = (result as { content?: unknown } | null)?.content;
+  if (!Array.isArray(content)) return {};
+  const text = content
+    .filter((p) => p && p.type === 'text' && typeof p.text === 'string')
+    .map((p) => p.text as string)
+    .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 {
@@ -94,7 +116,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) }),
             } satisfies ToolObservation);
           }
           this.emit('record', record);

package/src/protocol.ts

@@ -45,6 +45,7 @@ export function workerCapabilities(
     ...(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(
@@ -57,6 +58,7 @@ export function workerTools(
   station = false,
   local = false,
   localCoding = false,
+  operatorMcp = false,
 ): string[] {
   return child
     ? [...(childTools ?? ['salaam_probe'])].sort()
@@ -68,7 +70,9 @@ export function workerTools(
         ...(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 interface ChildTask {
@@ -89,6 +93,7 @@ export interface ChildTask {
 }
 export type WorkerState = 'stopped' | 'starting' | 'ready' | 'unhealthy' | 'exited';
 export interface Session {
+  mcp_servers?: import('./operator-mcp.js').McpServerProvenance[];
   id: string;
   cwd: string;
   revision: number;

package/src/rate-limit-retries.ts

@@ -0,0 +1,69 @@
+import type { Store } from './store.js';
+
+/**
+ * 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';
+
+type Step = { id: string; state: string; attempt_id: string | null };
+export type RetryDecision =
+  | { action: 'none' }
+  | { action: 'wait' }
+  | { action: 'retry'; step: string; n: number }
+  | { action: 'stop'; reason: string };
+
+export class RateLimitRetries {
+  constructor(private readonly 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: string): boolean {
+    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: { id: string; steps: Step[] }, now = Date.now()): RetryDecision {
+    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) as { failures: number; retry_at: number } | undefined;
+    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/src/recurring-work.ts

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

package/src/repository-snapshots.ts

@@ -71,9 +71,12 @@ export class RepositorySnapshots {
     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,
     };