attesso 0.4.1 → 0.6.0

package/src/fs-paths.mjs

@@ -0,0 +1,121 @@
+// Filesystem scope for file tools. This is deliberately separate from the
+// action policy: a tool can be allowed by the policy and still fail because the
+// path it names is outside the roots the user approved.
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+
+export const PATH_ACCESS = ['read', 'write'];
+const CASE_INSENSITIVE = process.platform === 'darwin' || process.platform === 'win32';
+export const FILE_TOOLS = new Set([
+  'read_file', 'write_file', 'patch', 'apply_patch', 'search_files', 'list_dir',
+  'create_file', 'delete_file', 'edit_file', 'str_replace_editor', 'notebook_edit',
+  'Read', 'Write', 'Edit', 'Glob', 'Grep', 'read_files', 'write_to_file', 'replace_in_file',
+]);
+
+export function validatePathsConfig(value) {
+  const fail = (message) => { throw new Error(`paths.json is invalid: ${message}`); };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('not an object');
+  if (value.version !== 1) fail('version must be 1');
+  if (!Array.isArray(value.allowed_roots)) fail('allowed_roots must be a list');
+  if (!Array.isArray(value.exclusions)) fail('exclusions must be a list');
+  if (value.allowed_roots.length > 128) fail('too many allowed roots');
+  if (value.exclusions.length > 128) fail('too many exclusions');
+  const roots = value.allowed_roots.map((entry) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) fail('every allowed root needs path and access');
+    if (typeof entry.path !== 'string' || entry.path.trim() === '') fail('allowed root path must not be empty');
+    if (entry.path.includes('..')) fail(`allowed root may not traverse: ${entry.path}`);
+    if (!Array.isArray(entry.access) || entry.access.length === 0) fail(`allowed root needs access: ${entry.path}`);
+    const access = [...new Set(entry.access)];
+    if (access.some((item) => !PATH_ACCESS.includes(item))) fail(`unknown access: ${entry.path}`);
+    return { path: entry.path.trim(), access };
+  });
+  const exclusions = value.exclusions.map((item) => {
+    if (typeof item !== 'string' || item.trim() === '') fail('exclusion must be a non-empty path');
+    if (item.includes('..')) fail(`exclusion may not traverse: ${item}`);
+    return item.trim();
+  });
+  const shellScope = value.shell_scope ?? 'unscoped';
+  if (!['unscoped', 'deny'].includes(shellScope)) fail('shell_scope must be unscoped or deny');
+  return { version: 1, allowed_roots: roots, exclusions, ...(value.shell_scope === undefined ? {} : { shell_scope: shellScope }) };
+}
+
+const expand = (value, home) => value.startsWith('~/') ? join(home, value.slice(2)) : value;
+const posix = (value) => value.split(sep).join('/');
+
+function absolutePath(value, { cwd, home }) {
+  const expanded = expand(value, home);
+  return isAbsolute(expanded) ? normalize(expanded) : resolve(cwd, expanded);
+}
+
+function realOrLexical(value) {
+  try {
+    return realpathSync(value);
+  } catch {
+    // A write target may not exist yet. Resolve its existing parent so a symlink
+    // in the parent cannot be used to escape the configured root.
+    try {
+      return join(realpathSync(dirname(value)), value.slice(dirname(value).length + 1));
+    } catch {
+      return value;
+    }
+  }
+}
+
+function under(root, target) {
+  const rel = relative(root, target);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function glob(pattern) {
+  const chars = [...posix(pattern)];
+  let expression = '';
+  for (let index = 0; index < chars.length; index += 1) {
+    const char = chars[index];
+    if (char === '*' && chars[index + 1] === '*') {
+      if (chars[index + 2] === '/') {
+        expression += '(?:.*/)?';
+        index += 2;
+      } else {
+        expression += '.*';
+        index += 1;
+      }
+    } else if (char === '*') {
+      expression += '[^/]*';
+    } else if (char === '?') {
+      expression += '[^/]';
+    } else {
+      expression += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${expression}$`, CASE_INSENSITIVE ? 'i' : '');
+}
+
+export function evaluatePathScope(config, proposal, { cwd = process.cwd(), home = homedir() } = {}) {
+  if (!config) return null;
+  if (config.shell_scope === 'deny' && proposal.capability === 'execute') {
+    return { decision: 'DENY', code: 'SHELL_SCOPE_DENIED', rule: 'shell-scope' };
+  }
+  if (typeof proposal.path !== 'string' || proposal.path === '') {
+    return FILE_TOOLS.has(proposal.subject) ? { decision: 'DENY', code: 'PATH_REQUIRED', rule: 'path-required' } : null;
+  }
+  const target = realOrLexical(absolutePath(proposal.path, { cwd, home }));
+  const targetPosix = posix(target);
+  const excluded = config.exclusions.some((pattern) => {
+    const expression = glob(pattern);
+    return expression.test(targetPosix) || expression.test(posix(proposal.path));
+  });
+  if (excluded) return { decision: 'DENY', code: 'PATH_SCOPE_DENIED', rule: 'path-exclusion' };
+  const capability = proposal.capability;
+  if (!PATH_ACCESS.includes(capability)) return null;
+  const roots = config.allowed_roots.map((entry) => ({
+    root: realOrLexical(absolutePath(entry.path.replace(/\/\*\*$/, ''), { cwd, home })),
+    access: entry.access,
+  }));
+  const match = roots.find((entry) => under(entry.root, target));
+  if (!match) return { decision: 'DENY', code: 'PATH_SCOPE_DENIED', rule: 'path-root' };
+  if (!match.access.includes(capability)) {
+    return { decision: 'DENY', code: 'PATH_SCOPE_DENIED', rule: 'path-access' };
+  }
+  return null;
+}

package/src/harness.mjs

@@ -0,0 +1,130 @@
+// Harness I/O belongs here, not in the decision path. Each product sends a
+// different event name and reads a different decision object; the payload
+// carries enough to detect them, so one hook command can serve them all.
+//
+// A refusal is rendered in the caller's own shape. Observe mode and an ALLOW
+// never answer "allow" on harnesses whose allow bypasses their native approval
+// prompt; they stay silent and let the product ask its own question.
+const CLAUDE = 'claude-code';
+const CURSOR = 'cursor';
+const CLINE = 'cline';
+const GEMINI = 'gemini';
+const HERMES = 'hermes';
+const GENERIC = 'generic';
+
+// One descriptor per caller. Detection reads `event`; installation reads the
+// same entry, so adding a caller cannot leave the two halves disagreeing.
+export const HARNESSES = {
+  [HERMES]: { event: 'pre_tool_call', kind: 'yaml' },
+  [CLAUDE]: { event: 'PreToolUse', kind: 'json' },
+  codex: { event: 'PreToolUse', kind: 'json' },
+  [CURSOR]: { event: 'preToolUse', kind: 'json' },
+  [GEMINI]: { event: 'BeforeTool', kind: 'json' },
+  [CLINE]: { event: 'preToolUse', kind: 'script', script: 'PreToolUse' },
+};
+
+export function normalizeHookPayload(payload = {}) {
+  if (payload.preToolUse && typeof payload.preToolUse === 'object') {
+    return {
+      harness: CLINE,
+      payload: {
+        tool_name: payload.preToolUse.tool,
+        tool_input: payload.preToolUse.parameters,
+        session_id: payload.taskId ?? 'unknown',
+      },
+    };
+  }
+
+  const harness = harnessOf(payload.hook_event_name);
+  return {
+    harness,
+    payload: {
+      tool_name: payload.tool_name,
+      tool_input: payload.tool_input,
+      session_id: payload.session_id ?? payload.conversation_id ?? 'unknown',
+      tool_definition_hash: payload.tool_definition_hash,
+    },
+  };
+}
+
+function harnessOf(event) {
+  if (event === HARNESSES[HERMES].event) return HERMES;
+  const match = Object.entries(HARNESSES).find(([, spec]) => spec.kind === 'json' && spec.event === event);
+  return match?.[0] ?? GENERIC;
+}
+
+export function renderHook({ harness, result }) {
+  const body = result.body;
+  const message = body.message ?? `Attesso refused ${body.code}.`;
+
+  if (!body.enforced) {
+    if (harness === HERMES) {
+      return { stdout: `${JSON.stringify({ decision: 'allow', code: body.code })}\n`, exitCode: 0 };
+    }
+    if (harness === CLINE) {
+      return { stdout: `${JSON.stringify({ cancel: false })}\n`, exitCode: 0 };
+    }
+    if (harness === GEMINI) {
+      return { stdout: '{}\n', exitCode: 0 };
+    }
+    return { stdout: '', exitCode: 0 };
+  }
+
+  if (harness === HERMES) {
+    return {
+      stdout: `${JSON.stringify({ decision: 'block', message, code: body.code })}\n`,
+      exitCode: 2,
+    };
+  }
+
+  if (harness === CLAUDE) {
+    return {
+      stdout: `${JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: message,
+        },
+      })}\n`,
+      exitCode: 0,
+    };
+  }
+
+  if (harness === CURSOR) {
+    return {
+      stdout: `${JSON.stringify({
+        permission: 'deny',
+        user_message: message,
+        agent_message: message,
+      })}\n`,
+      exitCode: 0,
+    };
+  }
+
+  if (harness === CLINE) {
+    return { stdout: `${JSON.stringify({ cancel: true, errorMessage: message })}\n`, exitCode: 0 };
+  }
+
+  if (harness === GEMINI) {
+    return {
+      stdout: `${JSON.stringify({ decision: 'deny', reason: message, systemMessage: message })}\n`,
+      exitCode: 0,
+    };
+  }
+
+  return {
+    stdout: `${JSON.stringify({
+      decision: 'block',
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: message,
+      },
+      permission: 'deny',
+      cancel: true,
+      errorMessage: message,
+      reason: message,
+    })}\n`,
+    exitCode: 2,
+  };
+}

package/src/hook.mjs

@@ -1,38 +1,12 @@
 import { createHash } from 'node:crypto';
 import { canonical } from './canonical.mjs';
+import { classifyTool, loadTools } from './classify.mjs';
+import { taskControl } from './control.mjs';
 
 // One decision for a harness hook. Reads the shell-hook payload on stdin
 // ({hook_event_name, tool_name, tool_input, session_id, ...}, the shape Claude
 // Code, Cursor and Hermes all use) and answers in the same contract: exit 2 with
 // a message refuses, exit 0 lets the call run.
-//
-// The mapping from a tool name to (action, capability, trust) is the only
-// harness-specific knowledge here, so every harness shares one policy engine.
-const EXECUTE = new Set(['terminal', 'execute_code', 'process_manage', 'shell', 'bash']);
-const WRITE = new Set(['write_file', 'patch', 'skill_manage', 'str_replace_editor', 'edit']);
-const UNTRUSTED_READ = new Set([
-  'browser_exec',
-  'web_search',
-  'web_extract',
-  'firecrawl',
-  'firecrawl_scrape',
-  'firecrawl_search',
-  'firecrawl_crawl',
-  'firecrawl_map',
-  'firecrawl_extract',
-  'firecrawl_deep_research',
-  'deepseek-search',
-  'ds',
-]);
-
-export function classifyTool(toolName) {
-  const name = String(toolName ?? '').trim();
-  if (UNTRUSTED_READ.has(name)) return { action: 'web.read', capability: 'read', trust: 'untrusted' };
-  if (EXECUTE.has(name)) return { action: 'shell.execute', capability: 'execute', trust: 'internal' };
-  if (WRITE.has(name)) return { action: 'file.write', capability: 'execute', trust: 'internal' };
-  if (/send|mail|post|publish/i.test(name)) return { action: 'message.send', capability: 'send', trust: 'internal' };
-  return { action: 'tool.call', capability: 'read', trust: 'internal' };
-}
 
 // A repeat is the same tool with the same arguments, so the fingerprint of the
 // arguments is what the rule compares. Storing the digest, never the payload: an
@@ -41,36 +15,86 @@ export function argsFingerprint(toolInput) {
   return createHash('sha256').update(canonical(toolInput ?? {})).digest('base64url').slice(0, 16);
 }
 
-export function requestFromPayload(payload) {
-  const { action, capability, trust } = classifyTool(payload.tool_name);
+const PATH_FIELDS = ['path', 'file_path', 'target_file', 'notebook_path', 'directory', 'cwd'];
+
+function pathFromPayload(payload) {
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object') return undefined;
+  for (const field of PATH_FIELDS) {
+    if (typeof input[field] === 'string' && input[field] !== '') return input[field];
+  }
+  return undefined;
+}
+
+export function requestFromPayload(payload, tools) {
+  const { action, capability, trust } = classifyTool(payload.tool_name, tools);
+  const toolHash =
+    typeof payload.tool_definition_hash === 'string' && payload.tool_definition_hash !== ''
+      ? payload.tool_definition_hash
+      : undefined;
   return {
     action,
     subject: payload.tool_name ?? null,
     task: payload.session_id ?? 'unknown',
     trust,
     capability,
-    meta: { args_hash: argsFingerprint(payload.tool_input) },
+    args_hash: argsFingerprint(payload.tool_input),
+    tool_hash: toolHash,
+    path: pathFromPayload(payload),
   };
 }
 
-export function decide({ append, dir, observe }) {
+export function createHookDecider({ append, dir, observe }) {
   return (payload) => {
-    const entry = append(dir, requestFromPayload(payload));
+    const proposal = requestFromPayload(payload, loadTools(dir));
+    let control;
+    try {
+      control = taskControl(dir, proposal.task);
+    } catch (error) {
+      return {
+        exitCode: observe ? 0 : 2,
+        body: {
+          decision: observe ? 'allow' : 'block',
+          code: 'CONTROL_UNAVAILABLE',
+          enforced: !observe,
+          message: `Attesso could not read the task control: ${error.message}`,
+        },
+      };
+    }
+    const entry = append(
+      dir,
+      proposal,
+      control ? { control: { mode: control.mode, at: control.at, reason: control.reason } } : undefined,
+    );
     const refused = entry.decision !== 'ALLOW';
+    const enforced = refused && (!observe || entry.control !== undefined);
     return {
-      exitCode: refused && !observe ? 2 : 0,
+      exitCode: enforced ? 2 : 0,
       body: {
         // The harness obeys `decision`, so observe mode must answer allow even
-        // when the verdict is DENY: the ledger keeps the verdict, work continues.
-        decision: refused && !observe ? 'block' : 'allow',
+        // when the verdict is DENY. An explicit pause or stop is the exception:
+        // it is the operator's steering act, not an observation.
+        decision: enforced ? 'block' : 'allow',
         verdict: entry.decision,
         code: entry.code,
-        enforced: refused && !observe,
+        enforced,
         seq: entry.seq,
-        message: entry.meta?.rule
-          ? `Attesso refused ${payload.tool_name}: ${entry.code} by ${entry.meta.rule} (step #${entry.meta.tainted_by} tainted this task). Entry #${entry.seq} in the signed ledger.`
-          : `Attesso refused ${payload.tool_name}: ${entry.code}. Entry #${entry.seq} in the signed ledger.`,
+        message: refusalMessage(entry, payload.tool_name),
       },
     };
   };
 }
+
+function refusalMessage(entry, toolName) {
+  if (entry.control) {
+    const verb = entry.control.mode === 'stop' ? 'stopped' : 'paused';
+    return `Attesso ${verb} task ${entry.task}: ${entry.code}. Run attesso resume ${entry.task} when ready.`;
+  }
+  if (entry.rule && entry.tainted_by !== undefined) {
+    return `Attesso refused ${toolName}: ${entry.code} by ${entry.rule} (step #${entry.tainted_by} tainted this task). Entry #${entry.seq} in the signed ledger.`;
+  }
+  if (entry.rule) {
+    return `Attesso refused ${toolName}: ${entry.code} by ${entry.rule}. Entry #${entry.seq} in the signed ledger.`;
+  }
+  return `Attesso refused ${toolName}: ${entry.code}. Entry #${entry.seq} in the signed ledger.`;
+}

package/src/install.mjs

@@ -0,0 +1,122 @@
+// Harness installation belongs here. setup decides what to install; this
+// module knows only how a hook is written, backed up and replaced.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { HARNESSES } from './harness.mjs';
+
+const shellQuote = (value) => `'${String(value).replaceAll("'", `'\\''`)}'`;
+
+const hookCommand = (cli, dir, enforce = false, modeFile = false) =>
+  `${shellQuote(cli)} --dir ${shellQuote(dir)} hook${modeFile ? '' : enforce ? '' : ' --observe'}`;
+
+const hermesConfig = () => join(homedir(), '.hermes', 'config.yaml');
+
+function readJsonConfig(path, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON: ${error.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} must hold an object`);
+  }
+  return parsed;
+}
+
+const containsAttesso = (group) => /attesso[^"]*hook/.test(JSON.stringify(group));
+
+function wireJsonHook(path, event, cli, dir, { dryRun = false, enforce = false, failureBlock = false, modeFile = false } = {}) {
+  if (!existsSync(path)) return { applied: false, reason: `no config at ${path}` };
+  const config = readJsonConfig(path, path);
+  const hooks = config.hooks;
+  if (hooks !== undefined && (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks))) {
+    return { applied: false, reason: 'hooks is not an object; merge by hand' };
+  }
+  const existing = hooks?.[event];
+  if (existing !== undefined && !Array.isArray(existing)) {
+    return { applied: false, reason: `${event} is not a list; merge by hand` };
+  }
+  const handler = { type: 'command', command: hookCommand(cli, dir, enforce, modeFile), timeout: 10 };
+  if (enforce && failureBlock) handler.onFailure = 'block';
+  const groups = existing ?? [];
+  const ourGroups = groups.filter(containsAttesso);
+  if (ourGroups.some((group) => group.hooks?.some((entry) => entry.command === handler.command))) {
+    return { applied: false, reason: 'already wired' };
+  }
+  const nextGroups = ourGroups.length
+    ? groups.map((group) =>
+        containsAttesso(group)
+          ? {
+              ...group,
+              hooks: (group.hooks ?? []).map((entry) =>
+                /attesso[^"]*hook/.test(entry.command ?? '') ? handler : entry,
+              ),
+            }
+          : group,
+      )
+    : [...groups, { matcher: '*', hooks: [handler] }];
+  const next = {
+    ...config,
+    hooks: { ...(hooks ?? {}), [event]: nextGroups },
+  };
+  if (dryRun) return { applied: false, dryRun: true, path, preview: next };
+  renameSync(path, `${path}.bak`);
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+  return { applied: true, path, changed: ourGroups.length > 0 };
+}
+
+export function wireClaude(cli, dir, { dryRun = false, enforce = false, modeFile = false, path = join(homedir(), '.claude', 'settings.json') } = {}) {
+  return wireJsonHook(path, HARNESSES['claude-code'].event, cli, dir, { dryRun, enforce, modeFile, failureBlock: true });
+}
+
+export function wireCodex(cli, dir, { dryRun = false, enforce = false, modeFile = false, path = join(homedir(), '.codex', 'hooks.json') } = {}) {
+  return wireJsonHook(path, HARNESSES.codex.event, cli, dir, { dryRun, enforce, modeFile });
+}
+
+export function wireGemini(cli, dir, { dryRun = false, enforce = false, modeFile = false, path = join(homedir(), '.gemini', 'settings.json') } = {}) {
+  return wireJsonHook(path, HARNESSES.gemini.event, cli, dir, { dryRun, enforce, modeFile });
+}
+
+export function wireCline(cli, dir, { dryRun = false, enforce = false, modeFile = false, path = join(homedir(), 'Documents', 'Cline', 'Hooks') } = {}) {
+  const file = join(path, HARNESSES.cline.script);
+  const script = `#!/bin/sh\nexec ${hookCommand(cli, dir, enforce, modeFile)}\n`;
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (current === script) return { applied: false, reason: 'already wired' };
+  if (dryRun) return { applied: false, dryRun: true, path: file, preview: script };
+  mkdirSync(path, { recursive: true });
+  if (existsSync(file)) renameSync(file, `${file}.bak`);
+  writeFileSync(file, script, { mode: 0o755 });
+  chmodSync(file, 0o755);
+  return { applied: true, path: file, changed: current.includes('attesso') };
+}
+
+export function wireHermes(cli, dir, { dryRun = false, enforce = false, modeFile = false, path = hermesConfig() } = {}) {
+  if (!existsSync(path)) return { applied: false, reason: 'no Hermes config at ~/.hermes/config.yaml' };
+  const text = readFileSync(path, 'utf8');
+  if (/attesso.*hook/.test(text)) return { applied: false, reason: 'already wired' };
+  const block = `hooks:\n  ${HARNESSES.hermes.event}:\n    - command: ${hookCommand(cli, dir, enforce, modeFile)}\n      timeout: 10\n`;
+  if (/^hooks:/m.test(text)) {
+    return { applied: false, reason: 'config already has a hooks: block, merge by hand', snippet: block };
+  }
+  const next = text.replace(/^approvals:/m, `${block}approvals:`);
+  if (next === text) return { applied: false, reason: 'no anchor to insert before; add the block by hand', snippet: block };
+  if (dryRun) return { applied: false, dryRun: true, path, snippet: block };
+  renameSync(path, `${path}.bak`);
+  writeFileSync(path, next);
+  return { applied: true, path, snippet: block };
+}
+
+const writers = {
+  hermes: wireHermes,
+  'claude-code': wireClaude,
+  codex: wireCodex,
+  gemini: wireGemini,
+  cline: wireCline,
+};
+
+export function wireHarness(key, cli, dir, options = {}) {
+  const writer = writers[key];
+  return writer ? writer(cli, dir, options) : { applied: false, reason: `no installer for ${key}` };
+}

package/src/jsonl.mjs

@@ -0,0 +1,16 @@
+// One reading of a JSONL line, shared by the array reader and the stream.
+export function parseLine(line, index) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    throw new Error(`ledger line ${index} is not JSON; the file was edited or truncated mid-line`);
+  }
+}
+
+export function parseTail(line, index) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+}

package/src/ledger.mjs

@@ -36,10 +36,39 @@ export function signEntry(entry, privatePem) {
 }
 
 export function verifyEntry(entry, publicPem) {
-  return verify(null, signingPayload(entry), publicPem, Buffer.from(entry.sig, 'base64url'));
+  if (!entry || typeof entry.sig !== 'string' || entry.sig === '') return false;
+  try {
+    return verify(null, signingPayload(entry), publicPem, Buffer.from(entry.sig, 'base64url'));
+  } catch {
+    return false;
+  }
 }
 
-export function buildEntry({ seq, prev, action, subject, amount, meta, task, trust, capability, decision, code, policyDigest, kid, at }) {
+export function buildEntry({
+  seq,
+  prev,
+  action,
+  subject,
+  amount,
+  meta,
+  task,
+  trust,
+  capability,
+  decision,
+  code,
+  rule,
+  taintedBy,
+  argsHash,
+  policyDigest,
+  rulesDigest,
+  toolsDigest,
+  toolHash,
+  toolPin,
+  mcpDigest,
+  control,
+  kid,
+  at,
+}) {
   const entry = {
     v: ENTRY_VERSION,
     seq,
@@ -56,32 +85,62 @@ export function buildEntry({ seq, prev, action, subject, amount, meta, task, tru
   if (task) entry.task = task;
   if (trust) entry.trust = trust;
   if (capability) entry.capability = capability;
+  if (rule) entry.rule = rule;
+  if (taintedBy !== undefined) entry.tainted_by = taintedBy;
+  if (argsHash) entry.args_hash = argsHash;
+  if (rulesDigest) entry.rules_digest = rulesDigest;
+  if (toolsDigest) entry.tools_digest = toolsDigest;
+  if (toolHash) entry.tool_hash = toolHash;
+  if (toolPin) entry.tool_pin = toolPin;
+  if (mcpDigest) entry.mcp_digest = mcpDigest;
+  if (control) entry.control = control;
   if (meta && Object.keys(meta).length > 0) entry.meta = meta;
   return entry;
 }
 
 // Returns the first defect rather than a boolean, so a reader learns which entry
 // to look at. `head` comes from config, which is what makes truncation visible.
-export function verifyChain(entries, publicPem, head) {
-  let previous = 'genesis';
-  for (const [index, entry] of entries.entries()) {
-    if (entry.seq !== index + 1) {
-      return { ok: false, reason: `entry ${index + 1} carries seq ${entry.seq}` };
-    }
-    if (entry.prev !== previous) {
-      return { ok: false, reason: `entry ${entry.seq} does not chain to the entry before it` };
-    }
-    if (!verifyEntry(entry, publicPem)) {
-      return { ok: false, reason: `entry ${entry.seq} signature does not verify` };
-    }
-    previous = entryHash(entry);
-  }
+export function verifyHead(count, hash, head) {
   if (!head) return { ok: false, reason: 'no recorded head, so the end of the log cannot be checked' };
-  if (head.count !== entries.length) {
-    return { ok: false, reason: `config records ${head.count} entries, the log holds ${entries.length}` };
+  if (head.count !== count) {
+    if (head.count < count) {
+      const extra = count - head.count;
+      const noun = extra === 1 ? 'entry' : 'entries';
+      return {
+        ok: false,
+        reason: `the log holds ${extra} more ${noun} than the recorded head; an interrupted append left them, and the next append repairs the head`,
+      };
+    }
+    return { ok: false, reason: `config records ${head.count} entries, the log holds ${count}` };
   }
-  if (head.hash !== previous) {
+  if (head.hash !== hash) {
     return { ok: false, reason: 'the last entry does not match the recorded head' };
   }
-  return { ok: true, reason: `chain of ${entries.length} entries verifies` };
+  return { ok: true, reason: `chain of ${count} entries verifies` };
+}
+
+export function verifyStep(entry, index, previous, publicPem) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { ok: false, reason: `entry ${index + 1} is not an object` };
+  }
+  if (entry.seq !== index + 1) {
+    return { ok: false, reason: `entry ${index + 1} carries seq ${entry.seq}` };
+  }
+  if (entry.prev !== previous) {
+    return { ok: false, reason: `entry ${entry.seq} does not chain to the entry before it` };
+  }
+  if (!verifyEntry(entry, publicPem)) {
+    return { ok: false, reason: `entry ${entry.seq} signature does not verify` };
+  }
+  return { ok: true, hash: entryHash(entry) };
+}
+
+export function verifyChain(entries, publicPem, head) {
+  let previous = 'genesis';
+  for (const [index, entry] of entries.entries()) {
+    const step = verifyStep(entry, index, previous, publicPem);
+    if (!step.ok) return step;
+    previous = step.hash;
+  }
+  return verifyHead(entries.length, previous, head);
 }