@volter/supercode-orchestrator 0.4.130 → 0.4.132

package/board/ci.mjs

@@ -0,0 +1,107 @@
+// Deployment evidence is observed before a board mutation. No network or Git
+// process runs inside the optimistic transaction that decides completion.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const observations = new Map();
+const key = (board, id) => `${board.root}\0${board.slug}\0${id}`;
+const run = (program, args, cwd) => {
+  const result = spawnSync(program, args, { cwd, encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`${program}: ${(result.stderr || result.error?.message || 'command failed').trim().slice(-500)}`);
+  return result.stdout.trim();
+};
+const codePath = path => path && !/^(?:docs\/|\.volter\/tracker\/)/.test(path) && (!/\.(?:md|txt|png|jpg|svg)$/i.test(path) || /(?:^|\/)prompts\//.test(path));
+
+export function completionEvidence(board, id) {
+  return observations.get(key(board, id)) ?? { required: true, ready: false, reason: 'Deployment evidence has not been observed; request review or done through the board CLI with --commit and --ci-run.' };
+}
+
+export function observeCompletionEvidence(board, id, entry, payload = {}) {
+  const state = { required: true, ready: false, reason: null };
+  observations.set(key(board, id), state);
+  if (!entry.params.completion_ci) { Object.assign(state, { required: false, ready: true }); return state; }
+  try {
+    const task = board.db.prepare('SELECT t.*,c.subtask_of,c.workspace_anchor FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
+    const parent = task?.subtask_of && board.db.prepare('SELECT workspace_path FROM tasks WHERE id=?').get(task.subtask_of);
+    const path = task?.workspace_path ?? parent?.workspace_path;
+    const old = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind IN ('review_requested','state_requested','review_pass') ORDER BY id DESC LIMIT 20").all(id)
+      .map(row => { try { return JSON.parse(row.payload)?.ci; } catch { return null; } }).find(ci => ci?.commit);
+    const supplied = payload.commit ?? payload.metadata?.commit ?? old?.commit;
+    if (!path) {
+      if (supplied) throw new Error('The named commit needs a resolved repository workspace.');
+      Object.assign(state, { required: false, ready: true }); return state;
+    }
+    const history = run('git', ['log', '--all', '--format=%H%x00', '--name-only', '--fixed-strings', `--grep=${id}`], path);
+    const records = [...history.matchAll(/([a-f0-9]{40})\0([^\0]*?)(?=[a-f0-9]{40}\0|$)/gs)];
+    const latest = records.find(([, , names]) => names.split('\n').some(codePath))?.[1];
+    if (!latest && !supplied) { Object.assign(state, { required: false, ready: true }); return state; }
+    const commit = run('git', ['rev-parse', '--verify', `${supplied ?? latest}^{commit}`], path);
+    if (latest) run('git', ['merge-base', '--is-ancestor', latest, commit], path);
+    const remote = run('git', ['remote', 'get-url', 'origin'], path);
+    const repo = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(remote)?.[1];
+    if (!repo) throw new Error('Deployment evidence requires this workspace\'s GitHub origin.');
+    Object.assign(state, { commit, repository: repo });
+    if (entry.params.completion_ci.keeper_repositories?.includes(repo)) {
+      const receiptPath = join(board.root, 'runtime-deployment.json');
+      const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+      if (receipt.repository !== repo || receipt.completed_at < Number(run('git', ['show', '-s', '--format=%ct', commit], path)) * 1000) throw new Error('No keeper tick after this runtime commit.');
+      run('git', ['merge-base', '--is-ancestor', commit, receipt.head], receipt.checkout);
+      const current = workflowRevision(board.root);
+      if (!current || current.head !== receipt.head || current.workflow_hash !== receipt.workflow_hash) throw new Error('The retained keeper tick does not describe the live checkout and loaded workflow revision.');
+      Object.assign(state, { ready: true, workflow: 'launchd keeper', run_id: `${receipt.pid}@${receipt.completed_at}`, status: 'completed', conclusion: 'success', deployed_sha: receipt.head, url: receiptPath });
+      return state;
+    }
+    const configured = entry.params.completion_ci.workflows?.[repo] ?? entry.params.completion_ci.workflows?.['*'];
+    if (!Array.isArray(configured) || !configured.length) throw new Error(`No deployment workflow is declared for ${repo} in completion_ci.workflows.`);
+    const matchedRules = (entry.params.completion_ci.path_workflows?.[repo] ?? []).filter(rule =>
+      records.some(([, , names]) => names.split('\n').some(path => rule.paths.some(prefix => path.startsWith(prefix)))));
+    const deploymentWorkflows = matchedRules.length ? configured.filter(name => matchedRules.every(rule => rule.workflows.includes(name))) : configured;
+    const requestedRun = payload.ci_run ?? payload['ci-run'] ?? payload.metadata?.ci_run ?? (old?.commit === commit ? old?.run_id : null);
+    let receipt;
+    if (requestedRun) {
+      receipt = JSON.parse(run('gh', ['run', 'view', String(requestedRun), '--repo', repo, '--json', 'databaseId,workflowName,headSha,status,conclusion,url'], path));
+    } else {
+      const runs = JSON.parse(run('gh', ['run', 'list', '--repo', repo, '--commit', commit, '--limit', '100', '--json', 'databaseId,workflowName,headSha,status,conclusion,url'], path));
+      receipt = runs.find(row => deploymentWorkflows.includes(row.workflowName));
+    }
+    if (!receipt) throw new Error(`No deployment CI run exists for ${repo}@${commit}.`);
+    Object.assign(state, { run_id: receipt.databaseId, workflow: receipt.workflowName, status: receipt.status, conclusion: receipt.conclusion, url: receipt.url });
+    if (receipt.headSha !== commit) throw new Error(`CI run ${receipt.databaseId} is for ${receipt.headSha}, not ${commit}.`);
+    if (!deploymentWorkflows.includes(receipt.workflowName)) throw new Error(`${receipt.workflowName} is not a declared deployment workflow for ${repo}.`);
+    if (receipt.status !== 'completed' || receipt.conclusion !== 'success') throw new Error(`Deployment CI ${receipt.databaseId} is ${receipt.status}/${receipt.conclusion || 'pending'}.`);
+    state.deployed_sha = commit;
+    state.ready = true;
+    state.reason = null;
+  } catch (error) { state.reason = error.message; }
+  return state;
+}
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+/** Read the tracked workflow revision the next serve tick will load. */
+export function workflowRevision(root) {
+  try {
+    const workflow = realpathSync(join(root, 'workflow.yaml'));
+    const checkout = run('git', ['rev-parse', '--show-toplevel'], dirname(workflow));
+    const head = run('git', ['rev-parse', 'HEAD'], checkout);
+    const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], checkout))?.[1];
+    const name = relative(checkout, workflow).replaceAll('\\', '/');
+    const source = readFileSync(workflow, 'utf8').trimEnd();
+    if (run('git', ['show', `${head}:${name}`], checkout) !== source) return null;
+    // Prompts are loaded with the workflow and must belong to the same revision.
+    run('git', ['diff', '--quiet', 'HEAD', '--', name, join(dirname(name), 'prompts')], checkout);
+    return { checkout, repository, head, workflow_hash: digest(source), started_at: Date.now(), pid: process.pid };
+  } catch { return null; }
+}
+
+/** Only the retained serve loop calls this after a successful tick. */
+export function retainWorkflowTick(root, before) {
+  if (!before) return null;
+  const after = workflowRevision(root);
+  if (!after || after.head !== before.head || after.workflow_hash !== before.workflow_hash) return null;
+  const receipt = { ...before, completed_at: Date.now() };
+  const path = join(root, 'runtime-deployment.json'), temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(receipt) + '\n', { mode: 0o600 }); renameSync(temporary, path);
+  return receipt;
+}

package/board/cli.mjs

@@ -537,7 +537,7 @@ export async function runWorkflow(argv) {
     case 'complete': {
       need(1, 'a card id');
       const metadata = metadataOf(args.metadata);
-      for (const t of rest) await withBoardAsync((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: metadata ?? null }));
+      for (const t of rest) await withBoardAsync((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: metadata ?? null, commit: args.commit ?? null, ci_run: args['ci-run'] ?? null }));
       say(args, rest.map((t) => `Completed ${t}`).join('\n'), { ok: true, completed: rest }); return 0;
     }
     case 'edit': {
@@ -567,7 +567,7 @@ export async function runWorkflow(argv) {
       if (args.reason) for (const [t] of results) await withBoardAsync((b) => engine.comment(b, t, callerName(), `UNBLOCK: ${args.reason}`));
       say(args, results.map(([t, s]) => `Unblocked ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
     }
-    case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
+    case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, commit: args.commit ?? null, ci_run: args['ci-run'] ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
     case 'request-changes': need(2, 'a card id and the reason'); await withBoardAsync((b) => engine.requestChanges(b, id, { reason: rest.slice(1).join(' '), reviewer: args.reviewer ?? null })); say(args, `${id} sent back for changes`, { ok: true }); return 0;
     case 'reopen': {
       // a done card back to work; the cards that built on it are invalidated with it (Hermes's reopen)
@@ -856,7 +856,7 @@ export async function runWorkflow(argv) {
       if (!declared) throw new Error(`no workflow verb ${verb}; \`supercode workflow help\` lists them`);
       need(1, 'a card id');
       const { _: _words, root: _r, board: _b, json: _j, at: _a, ids: _i, ...fields } = args;
-      const payload = { ...fields, waiting_on: args['waiting-on'] ?? fields.waiting_on, reason: args.reason ?? (rest.slice(1).join(' ') || null) };
+      const payload = { ...fields, ci_run: args['ci-run'] ?? fields.ci_run, deployed_sha: args['deployed-sha'] ?? fields.deployed_sha, waiting_on: args['waiting-on'] ?? fields.waiting_on, reason: args.reason ?? (rest.slice(1).join(' ') || null) };
       const results = [];
       for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.act(b, t, name, { payload }))).to]);
       say(args, results.map(([t, s]) => name === 'request_state' ? `${t}: ${payload.state} requested; state remains ${s}. Mail delivery is recorded on the card.` : `${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
@@ -1199,14 +1199,16 @@ async function serve(root, args = {}) {
         const state = await laneState(root);
         const settings = { ...state.settings, ...override };
         interval = settings.interval;
-        for (const r of await tick({ root, lanes: state.lanes, settings, params })) {
+        for (const r of await tick({ root, lanes: state.lanes, settings, params, deploymentReceipt: true })) {
           const said = summary(r);
+          if (r.deployment) log(`runtime deployed ${r.deployment.repository}@${r.deployment.head}; workflow ${r.deployment.workflow_hash}; tick ${r.deployment.completed_at}`);
           if (!said.endsWith('nothing to do') || args.verbose) log(said);
           if (args.verbose && r.ms) log(`  took ${Object.entries(r.ms).map(([k, v]) => `${k} ${(v / 1000).toFixed(1)}s`).join(', ')}`);
           if (r.paused && !pausedSaid) { log(`new starts paused by ${r.paused} (\`supercode workflow resume\` lifts it)`); pausedSaid = true; }
           // Event bursts do not shorten the six-sweep stuck warning.
           stuck[r.board] = r.ready_waiting && !r.started.length && !r.paused ? (stuck[r.board] || Date.now()) : 0;
           if (stuck[r.board] && Date.now() - stuck[r.board] >= interval * 6000 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log(`board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${Math.floor((Date.now() - stuck[r.board]) / 1000)}s; \`supercode workflow diagnostics\``); warned[r.board] = Date.now(); }
+          for (const [t, why] of r.queued) log(`  ${t} waits: ${why}`);
           for (const [t, why] of r.failed) log(`  ${t} did not start: ${why}`);
           for (const [t, why] of r.unsettled ?? []) log(`  ${t} could not be read: ${why}`);
           for (const [t, s, m] of r.started) log(`  ${t} started ${s} (${m})`);

package/board/dispatch.mjs

@@ -15,6 +15,7 @@
 // Every side effect follows a committed transition: a card is claimed before its session is launched, and a
 // subscriber's cursor moves only after its notice was delivered, so two dispatchers over one board never both
 // launch and a crash between the two steps is answered by the next tick.
+import { workflowRevision, retainWorkflowTick } from './ci.mjs';
 import { createRequire } from 'node:module';
 import { spawn as spawnChild, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -780,7 +781,7 @@ export async function sessionNotice(board, e) {
   let error = null, receipt = null;
   try {
     if (!e.address) throw new Error('lifecycle notice awaits the owned launch session identity');
-    receipt = await send(boardAddress(board.label), board.label, e.address, e.text, `board-run-notice-${e.id}-${e.durableId}`);
+    receipt = await send(boardAddress(board.label), board.label, e.address, e.text, e.messageKey ?? `board-run-notice-${e.id}-${e.durableId}`);
     if (!receipt.delivered) error = receipt.reason ?? 'notice queued; native transcript confirmation pending'; }
   catch (failure) { error = String(failure.message).slice(-500); }
   tx(board, (db) => {
@@ -1091,7 +1092,7 @@ function launchPane(board, task, runId, lane, fleet, { input = null, slot = 'wor
         try { deliverNow(board, addressOf(prev), input, `board-run-${task.id}-r${runId}`); }
         catch (error) {
           tx(board, (db) => {
-            const effect = { kind: 'session_notice', id: task.id, runId, address: addressOf(prev), text: input, verb: 'start' };
+            const effect = { kind: 'session_notice', id: task.id, runId, address: addressOf(prev), text: input, verb: 'start', messageKey: `board-run-${task.id}-r${runId}` };
             const saved = db.prepare('INSERT INTO supercode_effects(effect) VALUES(?)').run(JSON.stringify(effect));
             setRunSession(db, runId, { lifecycle_notice_pending: Number(saved.lastInsertRowid), lifecycle_notice_error: error.message });
             event(db, task.id, 'session_notice_failed', { verb: 'start', error: error.message, retry: true }, runId);
@@ -1303,6 +1304,7 @@ function deliverNow(board, to, body, key) {
   const r = sc(['message', 'remote-deliver'], { input: JSON.stringify(request), timeout: 120_000 });
   const answer = lastJson(r.stdout);
   if (answer?.code !== 0) throw new Error((answer?.text || r.stderr || `no delivery answer (exit ${r.code})`).trim().slice(-300));
+  if (!answer.receipt?.delivered) throw new Error(answer.receipt?.reason ?? 'native delivery confirmation pending');
 }
 
 async function send(from, label, to, body, key, { queue = false, ask = false } = {}) {
@@ -1331,8 +1333,9 @@ export async function sendBoardMessages(board, report, taskId = null) {
     if (taskId && row.task_id !== taskId) continue;
     const m = json(row.payload, {}) ?? {};
     try {
-      await send(boardAddress(board.label), board.label, m.to, m.text, m.message_id ?? `board-message-${row.id}`, { ask: Boolean(m.message_id) });
-      tx(board, (db) => event(db, row.task_id, 'board_message_sent', { event: row.id, to: m.to, ...(m.message_id ? { message_id: m.message_id } : {}) }));
+      const receipt = await send(boardAddress(board.label), board.label, m.to, m.text, m.message_id ?? `board-message-${row.id}`, { ask: Boolean(m.message_id) });
+      if (!receipt.delivered) throw new Error(receipt.reason ?? 'queued; native transcript confirmation pending');
+      tx(board, (db) => event(db, row.task_id, 'board_message_sent', { event: row.id, to: m.to, receipt, ...(m.message_id ? { message_id: m.message_id } : {}) }));
     } catch (error) {
       const reason = String(error.message).slice(-200);
       report.undelivered.push([row.task_id, m.to, reason]);
@@ -1404,7 +1407,7 @@ async function notify(board, fleet, report, entry) {
     // the card as the workflow names it (its status the workflow's: triaging, reviewing, stopped; `stored_as` kanban.db's)
     const task = view(board, (db) => { const t = getTask(db, sub.task_id); return t ? { ...t, status: statusOf(db, t), stored_as: t.status } : t; });
     let cursor = Number(sub.last_event_id);
-    let failed = null;
+    let failed = null, pending = false;
     try {
       for (const ev of events) {
         const p = json(ev.payload, {}) ?? {};
@@ -1417,23 +1420,28 @@ async function notify(board, fleet, report, entry) {
           text = c ? noticeOf(entry, role, ev.kind, task, p, c) : null;
         } else text = noticeOf(entry, role, ev.kind, task, p);
         if (text) {
-          // Hermes's delivery modes: `notify` is passive (read at the session's next turn), `wake`/`notify+wake` start its turn
-          await send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { queue: sub.delivery_mode === 'notify' });
-          tx(board, (db) => event(db, sub.task_id, 'notice_delivered', { source_event: ev.id, kind: ev.kind, address: sub.chat_id }));
+          const receipt = await send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { queue: !entry.workflow.run && sub.delivery_mode === 'notify' });
+          if (!receipt.delivered) { pending = Boolean(receipt.queued); throw new Error(receipt.reason ?? 'native delivery confirmation pending'); }
+          tx(board, (db) => event(db, sub.task_id, 'notice_delivered', { source_event: ev.id, kind: ev.kind, address: sub.chat_id, receipt }));
           report.notified.push([sub.task_id, ev.kind, sub.chat_id]);
         }
         cursor = ev.id;
       }
     } catch (error) {
       failed = String(error.message).slice(-200);
-      tx(board, (db) => event(db, sub.task_id, 'notice_failed', { after_event: cursor, address: sub.chat_id, error: failed, retry: true }));
+      tx(board, (db) => {
+        const kind = pending ? 'notice_queued' : 'notice_failed';
+        const previous = db.prepare('SELECT payload FROM task_events WHERE task_id=? AND kind=? ORDER BY id DESC LIMIT 1').get(sub.task_id, kind);
+        const payload = { after_event: cursor, address: sub.chat_id, error: failed, retry: true };
+        if (JSON.stringify(json(previous?.payload, {})) !== JSON.stringify(payload)) event(db, sub.task_id, kind, payload);
+      });
       report.undelivered.push([sub.task_id, sub.chat_id, failed]);
     }
     // the cursor moves past what was delivered (a failed delivery is retried next tick; the mail id dedupes)
     tx(board, (db) => {
       const where = "WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?";
       db.prepare(`UPDATE kanban_notify_subs SET last_event_id = ? ${where} AND last_event_id < ?`).run(cursor, sub.task_id, sub.chat_id, cursor);
-      const failures = failed ? Number(sub.delivery_metadata?.failures ?? 0) + 1 : 0;
+      const failures = failed && !pending ? Number(sub.delivery_metadata?.failures ?? 0) + 1 : 0;
       if (failures >= MAX_SEND_FAILURES) { db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(sub.task_id, sub.chat_id); return; }
       if (failures !== Number(sub.delivery_metadata?.failures ?? 0)) db.prepare(`UPDATE kanban_notify_subs SET delivery_metadata = ? ${where}`).run(JSON.stringify({ ...sub.delivery_metadata, failures }), sub.task_id, sub.chat_id);
       if (task?.status === 'archived' && cursor >= events.at(-1).id) db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(sub.task_id, sub.chat_id);
@@ -1676,8 +1684,9 @@ export async function plan({ root, lanes, settings, slugs = null, params = {} })
  * `only` limits starting to one card (a create that answers whether its card started). Each board is ticked under its
  * version-checked card claims; no dispatcher file lock. Answers one report per board.
  */
-export async function tick({ root, lanes, settings, only = null, slugs = null, dispatch = true, params = {} }) {
+export async function tick({ root, lanes, settings, only = null, slugs = null, dispatch = true, params = {}, deploymentReceipt = false }) {
   // a verb's flags (dispatch --max, --failure-limit) are params of this tick, read by the workflow as its own
+  const deployment = deploymentReceipt ? workflowRevision(root) : null;
   const loaded = await loadWorkflow(root, { fresh: true });
   const entry = { ...loaded, params: { ...loaded.params, ...params } };
   const needFleet = Object.values(lanes).some((l) => l.surface === 'pane');
@@ -1742,5 +1751,9 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
     }
     out.push(report);
   }
+  if (deployment && out.every(report => !report.error)) {
+    const receipt = retainWorkflowTick(root, deployment);
+    if (receipt && out[0]) out[0].deployment = receipt;
+  }
   return out;
 }

package/board/engine.mjs

@@ -13,6 +13,7 @@ import { join, resolve } from 'node:path';
 import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace, isWorkspacePath } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { view, actorOf, claimer, event, json, newTaskId, now, tx } from './store.mjs';
+import { observeCompletionEvidence } from './ci.mjs';
 import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
@@ -347,6 +348,7 @@ export function setCaller(fn) { callerRoles = fn; }
 export async function act(board, id, name, { roles = null, payload = {}, extra = {} } = {}) {
   const entry = await loadWorkflow(board.root);
   refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
+  if (['complete', 'request_review', 'request_state'].includes(name)) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload) };
   const result = tx(board, (db) => {
     roles ??= callerRoles(db, id);
     const r = fire(db, board, entry, id, name, { roles, payload, extra });
@@ -364,6 +366,7 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
 export async function goto(board, id, status, { roles = null, payload = {} } = {}) {
   const entry = await loadWorkflow(board.root);
   refreshCardInputs(board, id, { commits: true });
+  observeCompletionEvidence(board, id, entry, payload);
   const { name, refusal, from } = (() => {
     const db=board.db;
     roles ??= callerRoles(db, id);
@@ -454,14 +457,14 @@ function invalidateDescendants(db, board, id) {
 
 // each of Hermes's verbs is an event of the workflow; the words it takes are the event's payload
 
-export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null } = {}) =>
-  act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId } });
+export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null, commit = null, ci_run = null } = {}) =>
+  act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, ci_run } });
 // a block names the one thing that ends it: a card it waits on (`on`), or the message whose answer it waits for (`waiting_on`)
 export const block = (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
   act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
 export const unblock = (board, id, { reason = null, on = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason, on } });
-export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles } = {}) =>
-  act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId } });
+export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, ci_run = null } = {}) =>
+  act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, ci_run } });
 export const requestChanges = (board, id, { reason = null, reviewer = null, roles } = {}) => act(board, id, 'request_changes', { roles, payload: { reason, reviewer } });
 export const reopen = (board, id, { author = 'user', reason = null, roles } = {}) => act(board, id, 'reopen', { roles, payload: { author, reason } });
 export const reopenReview = (board, id, { roles } = {}) => act(board, id, 'reopen_review', { roles });

package/board/tools.mjs

@@ -105,7 +105,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
           }
         }
         if (env.HERMES_SESSION_ID && own === tid) metadata = { ...(metadata ?? {}), worker_session_id: env.HERMES_SESSION_ID };
-        await engine.complete(board, tid, { summary, result, metadata });
+        await engine.complete(board, tid, { summary, result, metadata, commit: args.commit ?? null, ci_run: args.ci_run ?? null });
         return ok({ task_id: tid, status: 'done' });
       }
       case 'kanban_block': {
@@ -115,12 +115,12 @@ export async function boardTool(root, name, args = {}, env = {}) {
       }
       case 'kanban_request_state': {
         const stale = ownRun(); if (stale) return error(stale);
-        await engine.act(board, tid, 'request_state', { payload: { state: args.state, reason: args.reason, on: args.on ?? null, waiting_on: args.waiting_on ?? null, evidence: args.evidence ?? null } });
+        await engine.act(board, tid, 'request_state', { payload: { state: args.state, reason: args.reason, on: args.on ?? null, waiting_on: args.waiting_on ?? null, evidence: args.evidence ?? null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, deployed_sha: args.deployed_sha ?? null } });
         return ok({ task_id: tid, requested: args.state, changed: false });
       }
       case 'kanban_request_review': {
         const stale = ownRun(); if (stale) return error(stale);
-        await engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, reviewer: args.reviewer ?? null, expectedRunId: own === tid && runId ? runId : null });
+        await engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, reviewer: args.reviewer ?? null, expectedRunId: own === tid && runId ? runId : null });
         return ok({ task_id: tid, status: 'review' });
       }
       case 'kanban_request_changes': {

package/board/workflow.mjs

@@ -11,6 +11,7 @@ import { resolve, relative, isAbsolute } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { actorOf, appendRunObservation, event as record, json, now } from './store.mjs';
 import { evaluate, holds, render } from './expr.mjs';
+import { completionEvidence } from './ci.mjs';
 
 const loaded = new Map();
 
@@ -222,6 +223,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
   const card = {
     ...task,
     creator_address: creatorOf(db, task.id),
+    ci: completionEvidence(board, task.id),
     dispatch_hold: one(db, "SELECT kind FROM task_events WHERE task_id=? AND kind IN ('dispatch_held','dispatch_released','session_adopted') ORDER BY id DESC LIMIT 1", task.id)?.kind === 'dispatch_held',
     status,
     blocked_by: blocks,
@@ -369,7 +371,7 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
     none.noTransition = true; throw none;
   }
   for (const v of taken.validate ?? []) {
-    if (!holds(v.expr, scope)) { const refusal = new Error(v.message); refusal.refusal = v.message; throw refusal; }
+    if (!holds(v.expr, scope)) { const reason = render(v.message, scope); const refusal = new Error(reason); refusal.refusal = reason; throw refusal; }
   }
   const effects = [];
   const to = take(db, board, entry, task, from, taken, scope, effects);
@@ -515,12 +517,12 @@ const firstLine = (text) => String(text ?? '').trim().split('\n')[0].slice(0, 40
 const FORMAT = {
   completed: ({ e }) => {
     const artifacts = Array.isArray(e.metadata?.artifacts) ? e.metadata.artifacts.filter((a) => typeof a === 'string' && a.trim()) : [];
-    return { result_len: e.result ? String(e.result).length : 0, summary: firstLine(e.summary ?? e.result), ...(artifacts.length ? { artifacts } : {}) };
+    return { ci: e.ci ?? null, result_len: e.result ? String(e.result).length : 0, summary: firstLine(e.summary ?? e.result), ...(artifacts.length ? { artifacts } : {}) };
   },
   blocked: ({ e, after, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, waiting_on: e.waiting_on ?? null, recurrences: Number(after.block_recurrences || 0), source_status: source }),
   block_loop_detected: ({ e, after, source, params }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), limit: params.block_recurrence_limit, source_status: source }),
   dependency_wait: ({ e, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, source_status: source }),
-  review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), implementer: before.assignee, reviewer: after.assignee !== before.assignee ? after.assignee : (e.reviewer ?? null) }),
+  review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), ci: e.ci ?? null, implementer: before.assignee, reviewer: after.assignee !== before.assignee ? after.assignee : (e.reviewer ?? null) }),
   // the reviewer is the lane that reviewed (the card's assignee while in review), unless the verdict names one
   changes_requested: ({ e, before, after }) => ({ reason: e.reason ?? null, reviewer: e.reviewer ?? before.assignee ?? null, implementer: after.assignee }),
   review_reopened: ({ after, to }) => ({ status: to, implementer: after.assignee }),
@@ -567,7 +569,14 @@ const ACTIONS = {
     }
     if (remove) {
       if (!String(reason ?? '').trim()) throw new Error('unblock must say what arrived');
-      blocks = blocks.filter((b) => remove === 'messages' ? b.kind !== 'message' : remove !== '*' && b.id !== remove);
+      let resolved = remove;
+      if (remove !== '*' && remove !== 'messages') {
+        const matches = blocks.filter(b => b.id === remove || (b.kind === 'message' && String(remove).startsWith('m-') &&
+          (String(remove).startsWith(b.id) || b.id.startsWith(String(remove)))));
+        if (matches.length !== 1) throw new Error(matches.length ? `ambiguous dependency ${remove}; name one of ${matches.map(b => b.id).join(', ')}` : `no dependency ${remove}; current blockers: ${blocks.map(b => b.id).join(', ') || 'none'}`);
+        resolved = matches[0].id;
+      }
+      blocks = blocks.filter((b) => resolved === 'messages' ? b.kind !== 'message' : resolved !== '*' && b.id !== resolved);
     }
     cardField(ctx, 'blocked_by', JSON.stringify(blocks));
     // task_links is the Hermes projection of the canonical card relations, including within this transaction.
@@ -891,7 +900,7 @@ export function fireRun(db, board, entry, id, name, { roles = [], payload = {},
   const candidates = [...(machine.states[from]?.on?.[name] ?? []), ...(machine.on?.[name] ?? [])];
   const t = candidates.find((t) => (!t.from?.length || t.from.includes(from)) && (!t.by?.length || t.by.some((r) => roles.includes(r))) && holds(t.guard ?? null, scope));
   if (!t) { const error = new Error(`${id}: run event ${name} does not apply`); error.noTransition = true; throw error; }
-  for (const v of t.validate ?? []) if (!holds(v.expr, scope)) throw new Error(v.message);
+  for (const v of t.validate ?? []) if (!holds(v.expr, scope)) throw new Error(render(v.message, scope));
   const to = t.target ? String(templateValue(t.target, scope)) : from;
   if (!machine.states[to]) throw new Error(`unknown run state ${to}`);
   const effects = [];

package/mcp/hermes-kanban-tools.json

@@ -1,7 +1,7 @@
 [
   {
     "name": "kanban_show",
-    "description": "Read a task's full state — title, body, assignee, parent task handoffs, your prior attempts on this task if any, comments, and recent events. Use this to (re)orient yourself before starting work, especially on retries. The response includes a pre-formatted ``worker_context`` string suitable for inclusion verbatim in your reasoning.",
+    "description": "Read a task's full state \u2014 title, body, assignee, parent task handoffs, your prior attempts on this task if any, comments, and recent events. Use this to (re)orient yourself before starting work, especially on retries. The response includes a pre-formatted ``worker_context`` string suitable for inclusion verbatim in your reasoning.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -11,7 +11,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": []
@@ -19,7 +19,7 @@
   },
   {
     "name": "kanban_list",
-    "description": "List Kanban task summaries so an orchestrator profile can discover work to route. Supports the same core filters as the CLI: assignee, status, tenant, include_archived, and limit. Returns compact rows with ids, title, status, assignee, priority, parent/child ids, and counts. Bounded to 50 rows by default, 200 max, with truncation metadata. Also recomputes ready tasks before listing, matching the CLI. Orchestrator-only — dispatcher-spawned task workers never see this tool.",
+    "description": "List Kanban task summaries so an orchestrator profile can discover work to route. Supports the same core filters as the CLI: assignee, status, tenant, include_archived, and limit. Returns compact rows with ids, title, status, assignee, priority, parent/child ids, and counts. Bounded to 50 rows by default, 200 max, with truncation metadata. Also recomputes ready tasks before listing, matching the CLI. Orchestrator-only \u2014 dispatcher-spawned task workers never see this tool.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -54,7 +54,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": []
@@ -62,7 +62,7 @@
   },
   {
     "name": "kanban_complete",
-    "description": "Complete through the home's declared workflow permissions with a structured handoff. Homes may reserve terminal closure to the recorded creator or manager; use kanban_request_state when you need their decision. Prefer ``summary`` for a human-readable 1-3 sentence description of what you did; put machine-readable facts in ``metadata`` (changed_files, tests_run, decisions, findings, etc). At least one of ``summary`` or ``result`` is required. If you created new tasks via ``kanban_create`` during this run, list their ids in ``created_cards`` — the kernel verifies them so phantom references are caught before they leak into downstream automation. If you produced deliverable files (charts, PDFs, spreadsheets, generated images), list their absolute paths in ``artifacts`` — the gateway notifier will upload them as native attachments to the human who subscribed to the task, so the deliverable lands in their chat alongside the summary instead of being a path they have to fetch by hand.",
+    "description": "Complete through the home's declared workflow permissions with a structured handoff. Homes may reserve terminal closure to the recorded creator or manager; use kanban_request_state when you need their decision. Prefer ``summary`` for a human-readable 1-3 sentence description of what you did; put machine-readable facts in ``metadata`` (changed_files, tests_run, decisions, findings, etc). At least one of ``summary`` or ``result`` is required. If you created new tasks via ``kanban_create`` during this run, list their ids in ``created_cards`` \u2014 the kernel verifies them so phantom references are caught before they leak into downstream automation. If you produced deliverable files (charts, PDFs, spreadsheets, generated images), list their absolute paths in ``artifacts`` \u2014 the gateway notifier will upload them as native attachments to the human who subscribed to the task, so the deliverable lands in their chat alongside the summary instead of being a path they have to fetch by hand.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -76,7 +76,7 @@
         },
         "metadata": {
           "type": "object",
-          "description": "Free-form dict of structured facts about this attempt — {\"changed_files\": [...], \"tests_run\": 12, \"findings\": [...]}. Surfaced to downstream workers alongside ``summary``."
+          "description": "Free-form dict of structured facts about this attempt \u2014 {\"changed_files\": [...], \"tests_run\": 12, \"findings\": [...]}. Surfaced to downstream workers alongside ``summary``."
         },
         "result": {
           "type": "string",
@@ -87,18 +87,26 @@
           "items": {
             "type": "string"
           },
-          "description": "Optional structured manifest of task ids you created via ``kanban_create`` during this run. The kernel verifies each id exists and was created by this worker's profile; any phantom id blocks the completion with an error listing what went wrong (auditable in the task's events). Only list ids you got back from a successful ``kanban_create`` call — do not invent or remember ids from prose. Omit the field if you did not create any cards."
+          "description": "Optional structured manifest of task ids you created via ``kanban_create`` during this run. The kernel verifies each id exists and was created by this worker's profile; any phantom id blocks the completion with an error listing what went wrong (auditable in the task's events). Only list ids you got back from a successful ``kanban_create`` call \u2014 do not invent or remember ids from prose. Omit the field if you did not create any cards."
         },
         "artifacts": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Optional list of absolute paths to deliverable files you produced during this run — generated charts, PDFs, spreadsheets, images, archives. Examples: [\"/tmp/q3-revenue.png\", \"/tmp/report.pdf\"]. The gateway notifier uploads each path as a native attachment to the subscribed chat (images embed inline, everything else uploads as a file) so the deliverable lands with the completion notification. Skip intermediate scratch files and references that are not the deliverable. The path must exist on disk at completion. Files inside a managed scratch workspace are copied to durable task attachments before cleanup; a missing declared scratch artifact keeps the task in-flight so you can fix the path and retry."
+          "description": "Optional list of absolute paths to deliverable files you produced during this run \u2014 generated charts, PDFs, spreadsheets, images, archives. Examples: [\"/tmp/q3-revenue.png\", \"/tmp/report.pdf\"]. The gateway notifier uploads each path as a native attachment to the subscribed chat (images embed inline, everything else uploads as a file) so the deliverable lands with the completion notification. Skip intermediate scratch files and references that are not the deliverable. The path must exist on disk at completion. Files inside a managed scratch workspace are copied to durable task attachments before cleanup; a missing declared scratch artifact keeps the task in-flight so you can fix the path and retry."
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        },
+        "commit": {
+          "type": "string",
+          "description": "Exact commit deployed by the CI run."
+        },
+        "ci_run": {
+          "type": "integer",
+          "description": "GitHub Actions deployment run id for that exact commit."
         }
       },
       "required": []
@@ -124,11 +132,11 @@
         },
         "waiting_on": {
           "type": "string",
-          "description": "The id of the message (m-… or a-…) whose answer this waits for."
+          "description": "The id of the message (m-\u2026 or a-\u2026) whose answer this waits for."
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -138,7 +146,7 @@
   },
   {
     "name": "kanban_request_review",
-    "description": "Hand the task off for review: implementation, self-review, and verification are complete and you want a human (or reviewer) to look before it is marked done. Moves the task to the 'review' column and notifies the subscriber. Unlike ``kanban_block`` this is NOT a blocker — it never counts toward unblock-loop detection, so a task can cycle through review across follow-ups without ever being falsely escalated to triage. Use this instead of blocking with a free-form 'review-required:' reason.",
+    "description": "Hand the task off for review: implementation, self-review, and verification are complete and you want a human (or reviewer) to look before it is marked done. Moves the task to the 'review' column and notifies the subscriber. Unlike ``kanban_block`` this is NOT a blocker \u2014 it never counts toward unblock-loop detection, so a task can cycle through review across follow-ups without ever being falsely escalated to triage. Use this instead of blocking with a free-form 'review-required:' reason.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -148,7 +156,7 @@
         },
         "summary": {
           "type": "string",
-          "description": "What was implemented and how it was verified, in one or two sentences — shown to the reviewer. Don't paste the whole diff; the reviewer has the board and the PR."
+          "description": "What was implemented and how it was verified, in one or two sentences \u2014 shown to the reviewer. Don't paste the whole diff; the reviewer has the board and the PR."
         },
         "reviewer": {
           "type": "string",
@@ -161,7 +169,15 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        },
+        "commit": {
+          "type": "string",
+          "description": "Exact commit deployed by the CI run."
+        },
+        "ci_run": {
+          "type": "integer",
+          "description": "GitHub Actions deployment run id for that exact commit."
         }
       },
       "required": [
@@ -185,7 +201,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -195,7 +211,7 @@
   },
   {
     "name": "kanban_heartbeat",
-    "description": "Signal that you're still alive during a long operation (training, encoding, large crawls). Call every few minutes so humans see liveness separately from PID checks. Pure side effect — no work changes.",
+    "description": "Signal that you're still alive during a long operation (training, encoding, large crawls). Call every few minutes so humans see liveness separately from PID checks. Pure side effect \u2014 no work changes.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -209,7 +225,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": []
@@ -217,13 +233,13 @@
   },
   {
     "name": "kanban_comment",
-    "description": "Append a comment to a task's thread. Use for durable notes that should outlive this run (questions for the next worker, partial findings, rationale). Ephemeral reasoning doesn't belong here — use your normal response instead.",
+    "description": "Append a comment to a task's thread. Use for durable notes that should outlive this run (questions for the next worker, partial findings, rationale). Ephemeral reasoning doesn't belong here \u2014 use your normal response instead.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "task_id": {
           "type": "string",
-          "description": "Task id. Required (may be your own task or another's — comment threads are per-task)."
+          "description": "Task id. Required (may be your own task or another's \u2014 comment threads are per-task)."
         },
         "body": {
           "type": "string",
@@ -231,7 +247,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -242,7 +258,7 @@
   },
   {
     "name": "kanban_attach",
-    "description": "Attach a file to a task by passing its bytes inline (base64). Use for genuine file artifacts the next worker or a human should be able to download — generated reports, images, exports. The file is stored as a real attachment (not a comment link) under the task's attachments dir, capped at 25 MB. Prefer kanban_attach_url when you only have a URL.",
+    "description": "Attach a file to a task by passing its bytes inline (base64). Use for genuine file artifacts the next worker or a human should be able to download \u2014 generated reports, images, exports. The file is stored as a real attachment (not a comment link) under the task's attachments dir, capped at 25 MB. Prefer kanban_attach_url when you only have a URL.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -264,7 +280,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -275,7 +291,7 @@
   },
   {
     "name": "kanban_attach_url",
-    "description": "Attach a file to a task by URL — Hermes downloads it server-side and stores it as a real attachment (capped at 25 MB). Use when you have a link rather than the bytes. Only http/https URLs are accepted.",
+    "description": "Attach a file to a task by URL \u2014 Hermes downloads it server-side and stores it as a real attachment (capped at 25 MB). Use when you have a link rather than the bytes. Only http/https URLs are accepted.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -297,7 +313,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -317,7 +333,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": []
@@ -325,7 +341,7 @@
   },
   {
     "name": "kanban_create",
-    "description": "Create a new kanban task, optionally as a child of the current one (pass the current task id in ``parents``). Used by orchestrator workers to fan out — decompose work into child tasks with specific assignees, link them into a pipeline, then complete your own task. The dispatcher picks up the new tasks on its next tick and spawns the assigned profiles.",
+    "description": "Create a new kanban task, optionally as a child of the current one (pass the current task id in ``parents``). Used by orchestrator workers to fan out \u2014 decompose work into child tasks with specific assignees, link them into a pipeline, then complete your own task. The dispatcher picks up the new tasks on its next tick and spawns the assigned profiles.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -335,7 +351,7 @@
         },
         "assignee": {
           "type": "string",
-          "description": "Profile name that should execute this task (e.g. 'researcher-a', 'reviewer', 'writer'). Required — tasks without an assignee are never dispatched."
+          "description": "Profile name that should execute this task (e.g. 'researcher-a', 'reviewer', 'writer'). Required \u2014 tasks without an assignee are never dispatched."
         },
         "body": {
           "type": "string",
@@ -375,7 +391,7 @@
         },
         "triage": {
           "type": "boolean",
-          "description": "If true, task lands in 'triage' instead of 'todo' — a specifier profile is expected to flesh out the body before work starts."
+          "description": "If true, task lands in 'triage' instead of 'todo' \u2014 a specifier profile is expected to flesh out the body before work starts."
         },
         "idempotency_key": {
           "type": "string",
@@ -398,7 +414,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Skill names to force-load into the dispatched worker. The kanban lifecycle is already injected automatically; use this to pin a task to a specialist context — e.g. ['translation'] for a translation task, ['github-code-review'] for a reviewer task. The names must match skills installed on the assignee's profile."
+          "description": "Skill names to force-load into the dispatched worker. The kanban lifecycle is already injected automatically; use this to pin a task to a specialist context \u2014 e.g. ['translation'] for a translation task, ['github-code-review'] for a reviewer task. The names must match skills installed on the assignee's profile."
         },
         "goal_mode": {
           "type": "boolean",
@@ -414,11 +430,11 @@
         },
         "provider": {
           "type": "string",
-          "description": "Provider the 'model' belongs to (e.g. 'openrouter', 'anthropic', 'nous'). Set this whenever the model is not from the assignee profile's configured provider — a model name alone is resolved against the profile's provider and will fail if it belongs to a different one. Requires 'model'."
+          "description": "Provider the 'model' belongs to (e.g. 'openrouter', 'anthropic', 'nous'). Set this whenever the model is not from the assignee profile's configured provider \u2014 a model name alone is resolved against the profile's provider and will fail if it belongs to a different one. Requires 'model'."
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -429,7 +445,7 @@
   },
   {
     "name": "kanban_unblock",
-    "description": "Unblock a Kanban task. It moves to ready when all parents are done, or todo while any parent remains open. Orchestrator-only — only profiles with the kanban toolset can unblock routed work; dispatcher-spawned task workers never see this tool.",
+    "description": "Unblock a Kanban task. It moves to ready when all parents are done, or todo while any parent remains open. Orchestrator-only \u2014 only profiles with the kanban toolset can unblock routed work; dispatcher-spawned task workers never see this tool.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -439,7 +455,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -449,7 +465,7 @@
   },
   {
     "name": "kanban_link",
-    "description": "Add a parent→child dependency edge after both tasks already exist. The child won't promote to 'ready' until all parents are 'done'. Cycles and self-links are rejected.",
+    "description": "Add a parent\u2192child dependency edge after both tasks already exist. The child won't promote to 'ready' until all parents are 'done'. Cycles and self-links are rejected.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -463,7 +479,7 @@
         },
         "board": {
           "type": "string",
-          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
         }
       },
       "required": [
@@ -501,6 +517,18 @@
         },
         "evidence": {
           "type": "string"
+        },
+        "commit": {
+          "type": "string",
+          "description": "Exact commit deployed by the CI run."
+        },
+        "ci_run": {
+          "type": "integer",
+          "description": "GitHub Actions deployment run id for that exact commit."
+        },
+        "deployed_sha": {
+          "type": "string",
+          "description": "The deployed commit the independent reviewer actually inspected."
         }
       },
       "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.130",
+  "version": "0.4.132",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {