@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.11

package/src/commands/receipts.js

@@ -0,0 +1,140 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  pruneLocalWorkspaces,
+  validateReceiptEnvelope,
+} from "../receipts/index.js";
+
+function intFlag(args, flag, fallback) {
+  const index = args.indexOf(flag);
+  const value = index >= 0 ? Number.parseInt(args[index + 1], 10) : NaN;
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function numberFlag(args, flag, fallback) {
+  const index = args.indexOf(flag);
+  const value = index >= 0 ? Number(args[index + 1]) : NaN;
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function stringFlag(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 && args[index + 1] ? args[index + 1] : null;
+}
+
+async function readLocalReceipts(directory) {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  const receipts = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    try {
+      const value = JSON.parse(
+        await readFile(path.join(directory, entry.name), "utf8"),
+      );
+      if (validateReceiptEnvelope(value).ok) receipts.push(value);
+    } catch {}
+  }
+  receipts.sort(
+    (a, b) =>
+      Number(b.metrics?.created_at_unix || 0) -
+      Number(a.metrics?.created_at_unix || 0),
+  );
+  return receipts;
+}
+
+function writeSummary(receipt) {
+  const date = new Date(
+    Number(receipt.metrics?.created_at_unix || 0) * 1000,
+  ).toISOString();
+  process.stdout.write(
+    [
+      receipt.receipt_id,
+      receipt.status,
+      receipt.kind,
+      date,
+      receipt.identity?.repository_id || "-",
+    ].join("\t") + "\n",
+  );
+}
+
+export async function runReceipts(args = [], options = {}) {
+  const [command = "list", ...rest] = args;
+  const localDir =
+    options.localDir ||
+    stringFlag(rest, "--dir") ||
+    path.join(process.cwd(), ".agentsam", "receipts");
+
+  if (command === "prune") {
+    const result = await pruneLocalWorkspaces({
+      maxTmpGb: numberFlag(rest, "--max-tmp-gb", 1),
+      dryRun: rest.includes("--dry-run"),
+    });
+    if (rest.includes("--json")) {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else {
+      process.stdout.write(
+        "Scanned " +
+          result.scannedCount +
+          " AgentSam workdirs; purged " +
+          result.purgedCount +
+          "; " +
+          result.remainingBytes +
+          " bytes remain.\n",
+      );
+    }
+    return result;
+  }
+
+  const receipts = options.catalog
+    ? await options.catalog.list({
+        limit: intFlag(rest, "--limit", 20),
+        repositoryId: stringFlag(rest, "--repo"),
+        status: command === "failures" ? "failed" : undefined,
+      })
+    : await readLocalReceipts(localDir);
+
+  if (command === "show") {
+    const id = rest.find((arg) => !arg.startsWith("--"));
+    if (!id) throw new Error("agentsam receipts show requires a receipt id");
+    const receipt = options.catalog
+      ? await options.catalog.get(id)
+      : receipts.find((item) => item.receipt_id === id);
+    if (!receipt) {
+      const error = new Error("Receipt not found: " + id);
+      error.code = "AGENTSAM_RECEIPT_NOT_FOUND";
+      throw error;
+    }
+    process.stdout.write(JSON.stringify(receipt, null, 2) + "\n");
+    return receipt;
+  }
+
+  if (!["list", "failures"].includes(command)) {
+    throw new Error(
+      "Usage: agentsam receipts list [--limit 20] [--repo <id>]\n" +
+        "       agentsam receipts show <receipt-id>\n" +
+        "       agentsam receipts failures [--repo <id>]\n" +
+        "       agentsam receipts prune [--max-tmp-gb 1.0] [--dry-run]",
+    );
+  }
+
+  const repo = stringFlag(rest, "--repo");
+  const limit = intFlag(rest, "--limit", 20);
+  const filtered = receipts
+    .filter((receipt) => !repo || receipt.identity?.repository_id === repo)
+    .filter((receipt) => command !== "failures" || receipt.status === "failed")
+    .slice(0, limit);
+
+  if (rest.includes("--json")) {
+    process.stdout.write(JSON.stringify(filtered, null, 2) + "\n");
+  } else {
+    if (!options.catalog) {
+      process.stderr.write(
+        "  source: local receipt cache (" +
+          localDir +
+          "); durable D1 catalog requires a host catalog adapter\n",
+      );
+    }
+    for (const receipt of filtered) writeSummary(receipt);
+  }
+  return filtered;
+}

package/src/commands/run.js

@@ -0,0 +1,253 @@
+import { createAgentControlClient } from '../acp/client.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function number(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+function parse(argv = []) {
+  const out = {
+    command: clean(argv[0]) || 'help',
+    id: null,
+    json: false,
+    local: false,
+    url: '',
+    once: false,
+    after: -1,
+    limit: 200,
+    intervalMs: 1000,
+    objective: '',
+    role: '',
+    workItemId: '',
+    stepId: '',
+    modelKey: '',
+    runtimeRequirements: {},
+  };
+  let i = 1;
+  if (!['help', 'start'].includes(out.command) && argv[i] && !String(argv[i]).startsWith('-')) out.id = String(argv[i++]);
+  for (; i < argv.length; i += 1) {
+    const arg = String(argv[i]);
+    if (arg === '--json') out.json = true;
+    else if (arg === '--local') out.local = true;
+    else if (arg === '--once') out.once = true;
+    else if (arg === '--url') out.url = String(argv[++i] || '');
+    else if (arg.startsWith('--url=')) out.url = arg.slice(6);
+    else if (arg === '--after') out.after = number(argv[++i], -1);
+    else if (arg.startsWith('--after=')) out.after = number(arg.slice(8), -1);
+    else if (arg === '--limit') out.limit = number(argv[++i], 200);
+    else if (arg.startsWith('--limit=')) out.limit = number(arg.slice(8), 200);
+    else if (arg === '--interval-ms') out.intervalMs = number(argv[++i], 1000);
+    else if (arg.startsWith('--interval-ms=')) out.intervalMs = number(arg.slice(14), 1000);
+    else if (arg === '--objective') out.objective = String(argv[++i] || '');
+    else if (arg.startsWith('--objective=')) out.objective = arg.slice(12);
+    else if (arg === '--role') out.role = String(argv[++i] || '');
+    else if (arg.startsWith('--role=')) out.role = arg.slice(7);
+    else if (arg === '--work-item') out.workItemId = String(argv[++i] || '');
+    else if (arg.startsWith('--work-item=')) out.workItemId = arg.slice(12);
+    else if (arg === '--step') out.stepId = String(argv[++i] || '');
+    else if (arg.startsWith('--step=')) out.stepId = arg.slice(7);
+    else if (arg === '--model') out.modelKey = String(argv[++i] || '');
+    else if (arg.startsWith('--model=')) out.modelKey = arg.slice(8);
+    else if (arg === '--runtime-json') out.runtimeRequirements = JSON.parse(String(argv[++i] || '{}'));
+    else if (arg.startsWith('--runtime-json=')) out.runtimeRequirements = JSON.parse(arg.slice(15) || '{}');
+    else throw new Error(`unknown_run_option:${arg}`);
+  }
+  return out;
+}
+
+function help() {
+  return [
+    'Agent Sam · run',
+    'Provider-neutral Agent Control Plane inspection and control.',
+    '',
+    'Usage:',
+    '  agentsam run start --objective <text> [--role <slug>] [--model <key>] [--runtime-json <json>] [--json]',
+    '  agentsam run get <run_id> [--json] [--local | --url <base-url>]',
+    '  agentsam run tree <run_id> [--json]',
+    '  agentsam run events <run_id> [--after <seq>] [--limit <n>] [--json]',
+    '  agentsam run watch <run_id> [--after <seq>] [--interval-ms <ms>] [--once] [--json]',
+    '  agentsam run spawn <parent_run_id> --objective <text> [--role <slug>] [--runtime-json <json>] [--json]',
+    '  agentsam run cancel <run_id> [--json]',
+    '  agentsam run receipt <run_id> [--json]',
+    '',
+    'Host selection:',
+    '  local SQLite is the default.',
+    '  AGENTSAM_CONTROL_PLANE_URL or --url selects any HTTP ACP host.',
+    '  AGENTSAM_CONTROL_PLANE_TOKEN supplies hosted bearer auth without putting secrets in shell history.',
+    '  --local forces the project-local SQLite control plane.',
+  ].join('\n');
+}
+
+function formatRun(run, clientKind) {
+  if (!run) return 'run not found';
+  return [
+    'Agent Sam · run',
+    `source   ${clientKind}`,
+    `id       ${run.id}`,
+    `status   ${run.status}${run.cancelRequested ? ' · cancel requested' : ''}`,
+    `mode     ${run.mode || 'unknown'}`,
+    `parent   ${run.parentRunId || '—'}`,
+    `model    ${run.modelKey || '—'}`,
+    `calls    model ${run.modelCallCount || 0} · tool ${run.toolCallCount || 0}`,
+    `cost     $${Number(run.costUsd || 0).toFixed(6)}`,
+    run.suspension ? `wait     ${run.suspension.state} · ${run.suspension.reason}` : null,
+  ].filter(Boolean).join('\n');
+}
+
+function treeLines(node, depth = 0, rows = []) {
+  if (!node) return rows;
+  const indent = '  '.repeat(depth);
+  rows.push(`${indent}${depth ? '└─ ' : ''}${node.id} · ${node.status} · ${node.mode || 'agent'}`);
+  for (const child of node.children || []) treeLines(child, depth + 1, rows);
+  return rows;
+}
+
+function eventLine(event) {
+  const at = event.createdAt ? new Date(event.createdAt).toISOString() : '';
+  return `#${event.seq} ${event.eventType}${event.phase ? ` · ${event.phase}` : ''}${event.label ? ` · ${event.label}` : ''}${at ? ` · ${at}` : ''}`;
+}
+
+function requireId(args) {
+  if (!clean(args.id)) {
+    const error = new Error(`run_id_required:${args.command}`);
+    error.hint = `Usage: agentsam run ${args.command} <run_id>`;
+    throw error;
+  }
+}
+
+export async function runRun(argv = [], options = {}) {
+  const args = parse(argv);
+  const write = options.write || ((value) => process.stdout.write(String(value)));
+  if (args.command === 'help' || args.command === '--help' || args.command === '-h') {
+    write(help() + '\n');
+    return { ok: true, command: 'help' };
+  }
+  if (!['start', 'get', 'tree', 'events', 'watch', 'spawn', 'cancel', 'receipt'].includes(args.command)) {
+    throw new Error(`unknown_run_command:${args.command}`);
+  }
+  if (args.command !== 'start') requireId(args);
+
+  const client = options.client || createAgentControlClient({
+    cwd: options.cwd || process.cwd(),
+    url: args.url || options.url,
+    token: options.token,
+    local: args.local,
+    fetchImpl: options.fetchImpl,
+  });
+
+  if (args.command === 'start') {
+    if (!clean(args.objective)) {
+      const error = new Error('run_objective_required');
+      error.hint = 'Usage: agentsam run start --objective <text>';
+      throw error;
+    }
+    const started = await client.start({
+      objective: args.objective,
+      role: clean(args.role) || 'lead',
+      model_key: clean(args.modelKey) || null,
+      runtime_requirements: args.runtimeRequirements,
+    });
+    if (args.json) write(JSON.stringify(started, null, 2) + '\n');
+    else {
+      write([
+        'Agent Sam · run started',
+        `run      ${started.run_id}`,
+        `queue    ${started.queue || 'host-managed'}`,
+        `status   ${started.status || 'queued'}`,
+      ].join('\n') + '\n');
+    }
+    return started;
+  }
+
+  if (args.command === 'get') {
+    const run = await client.getRun(args.id);
+    if (!run) throw new Error(`run_not_found:${args.id}`);
+    write(args.json ? JSON.stringify(run, null, 2) + '\n' : formatRun(run, client.kind) + '\n');
+    return run;
+  }
+
+  if (args.command === 'tree') {
+    const tree = await client.tree(args.id);
+    if (!tree) throw new Error(`run_not_found:${args.id}`);
+    write(args.json ? JSON.stringify(tree, null, 2) + '\n' : treeLines(tree).join('\n') + '\n');
+    return tree;
+  }
+
+  if (args.command === 'events') {
+    const events = await client.events(args.id, { after: args.after, limit: args.limit });
+    write(args.json ? JSON.stringify(events, null, 2) + '\n' : (events.map(eventLine).join('\n') || 'no events') + '\n');
+    return events;
+  }
+
+  if (args.command === 'spawn') {
+    if (!clean(args.objective)) {
+      const error = new Error('child_run_objective_required');
+      error.hint = 'Usage: agentsam run spawn <parent_run_id> --objective <text>';
+      throw error;
+    }
+    const spawned = await client.spawn(args.id, {
+      objective: args.objective,
+      role: clean(args.role) || null,
+      work_item_id: clean(args.workItemId) || null,
+      step_id: clean(args.stepId) || null,
+      model_key: clean(args.modelKey) || null,
+      runtime_requirements: args.runtimeRequirements,
+    });
+    if (args.json) write(JSON.stringify(spawned, null, 2) + '\n');
+    else {
+      write([
+        'Agent Sam · child run',
+        `parent   ${spawned.parent_run_id || args.id}`,
+        `child    ${spawned.child_run_id || '—'}`,
+        `queue    ${spawned.queue || 'host-managed'}`,
+        `status   ${spawned.dependency_status || 'pending'}`,
+      ].join('\n') + '\n');
+    }
+    return spawned;
+  }
+
+  if (args.command === 'cancel') {
+    const run = await client.cancel(args.id);
+    if (!run) throw new Error(`run_not_found:${args.id}`);
+    write(args.json ? JSON.stringify(run, null, 2) + '\n' : formatRun(run, client.kind) + '\n');
+    return run;
+  }
+
+  if (args.command === 'receipt') {
+    const receipt = await client.receipt(args.id);
+    if (!receipt) throw new Error(`run_not_found:${args.id}`);
+    if (args.json) write(JSON.stringify(receipt, null, 2) + '\n');
+    else {
+      write([
+        'Agent Sam · run receipt',
+        `id       ${receipt.runId}`,
+        `status   ${receipt.status}`,
+        `terminal ${receipt.terminal ? 'yes' : 'no'}`,
+        `events   ${receipt.eventCount}`,
+        `children ${receipt.childRunCount}`,
+        `cost     $${Number(receipt.usage?.costUsd || 0).toFixed(6)}`,
+      ].join('\n') + '\n');
+    }
+    return receipt;
+  }
+
+  let after = args.after;
+  const seen = [];
+  const wait = options.sleep || sleep;
+  do {
+    const events = await client.events(args.id, { after, limit: args.limit });
+    for (const event of events) {
+      seen.push(event);
+      after = Math.max(after, Number(event.seq));
+      write(args.json ? JSON.stringify(event) + '\n' : eventLine(event) + '\n');
+    }
+    const run = await client.getRun(args.id);
+    if (!run) throw new Error(`run_not_found:${args.id}`);
+    if (args.once || ['completed', 'failed', 'cancelled', 'timed_out'].includes(run.status)) {
+      return { run, events: seen, after };
+    }
+    await wait(Math.max(100, args.intervalMs));
+  } while (true);
+}

package/src/go/container.js

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { probeGoDeploymentWithRetry } from './cloudflare.js';
+import { probeGoDeploymentWithRetry } from './probe.js';
 
 function runDocker(args, { productRoot, spawn = spawnSync } = {}) {
   const res = spawn('docker', args, {

package/src/go/contract.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { DEFAULT_PRODUCT } from './discover.js';
 
 const PACKAGE_TEMPLATE = {
@@ -90,12 +91,16 @@ function rel(root, file) {
   return path.relative(root, file).split(path.sep).join('/');
 }
 
-export function preflightToolchain({ requireDocker = false, productRoot = null } = {}) {
+export function preflightToolchain({
+  requireDocker = false,
+  productRoot = null,
+  spawn = spawnSync,
+} = {}) {
   const checks = [];
   const push = (id, ok, detail = '') => checks.push({ id, ok, detail });
 
   try {
-    const v = spawnSync('go', ['version'], { encoding: 'utf8' });
+    const v = spawn('go', ['version'], { encoding: 'utf8' });
     push('go', v.status === 0, (v.stdout || v.stderr || '').trim());
   } catch (e) {
     push('go', false, e.message);
@@ -103,7 +108,7 @@ export function preflightToolchain({ requireDocker = false, productRoot = null }
 
   const wranglerBin = resolveWranglerBin(productRoot);
   try {
-    const v = spawnSync(wranglerBin.command, wranglerBin.args.concat(['--version']), {
+    const v = spawn(wranglerBin.command, wranglerBin.args.concat(['--version']), {
       encoding: 'utf8',
       cwd: productRoot || process.cwd(),
     });
@@ -112,33 +117,71 @@ export function preflightToolchain({ requireDocker = false, productRoot = null }
     push('wrangler', false, e.message);
   }
 
-  try {
-    const v = spawnSync('docker', ['info'], { encoding: 'utf8' });
-    push('docker', v.status === 0, v.status === 0 ? 'available' : (v.stderr || 'unavailable').trim().slice(0, 200));
-  } catch (e) {
-    push('docker', false, e.message);
+  // Docker is capability-gated.
+  //
+  // A caller that does not require a container must not execute
+  // `docker info` merely to discover that Docker is optional.
+  //
+  // Besides wasting work, Docker Desktop may be installed while its
+  // daemon is stopped/unhealthy, and `docker info` can block for a
+  // significant period.
+  if (requireDocker) {
+    try {
+      const v = spawn('docker', ['info'], {
+        encoding: 'utf8',
+        timeout: 8000,
+      });
+      push(
+        'docker',
+        v.status === 0,
+        v.status === 0
+          ? 'available'
+          : (v.stderr || 'unavailable').trim().slice(0, 200),
+      );
+    } catch (e) {
+      push('docker', false, e.message);
+    }
+  } else {
+    push('docker', true, 'skipped:not-required');
   }
 
-  const failed = checks.filter((c) => {
-    if (c.ok) return false;
-    if (c.id === 'docker' && !requireDocker) return false;
-    return true;
-  });
+  const failed = checks.filter((c) => !c.ok);
   return { ok: failed.length === 0, checks, failed, wrangler: wranglerBin };
 }
 
-function resolveWranglerBin(productRoot) {
+export function resolveWranglerBin(productRoot) {
+  if (productRoot) {
+    try {
+      const req = createRequire(path.join(productRoot, 'package.json'));
+      const resolved = req.resolve('wrangler');
+      if (resolved) {
+        return { command: process.execPath, args: [resolved], source: 'package_dependency' };
+      }
+    } catch {
+      // Fall through to explicit paths / pinned npx fallback.
+    }
+  }
+
   const candidates = [];
   if (productRoot) {
-    candidates.push(path.join(productRoot, 'node_modules', 'wrangler', 'bin', 'wrangler.js'));
     candidates.push(path.join(productRoot, 'node_modules', '.bin', 'wrangler'));
   }
   candidates.push(path.join(process.cwd(), 'node_modules', '.bin', 'wrangler'));
   for (const candidate of candidates) {
     if (fs.existsSync(candidate)) {
-      if (candidate.endsWith('.js')) return { command: process.execPath, args: [candidate] };
-      return { command: candidate, args: [] };
+      return { command: candidate, args: [], source: 'local_bin' };
+    }
+  }
+
+  let requested = 'wrangler';
+  if (productRoot) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(productRoot, 'package.json'), 'utf8'));
+      const version = pkg.dependencies?.wrangler || pkg.devDependencies?.wrangler || '';
+      if (version) requested = 'wrangler@' + version;
+    } catch {
+      // Keep generic fallback only when package metadata is unavailable.
     }
   }
-  return { command: 'npx', args: ['--yes', 'wrangler'] };
+  return { command: 'npx', args: ['--yes', requested], source: 'npx_fallback' };
 }

package/src/go/discover.js

@@ -180,10 +180,6 @@ export function probeGoToolchain() {
 }
 
 export function resolveGoStateRoot(discovery, cwd = process.cwd()) {
-  const origin = discovery?.runtime?.origin || null;
-  if (origin === 'repository' || origin === 'sdk_development_tree') {
-    return discovery.runtime.productRoot;
-  }
   return repositoryRoot(cwd);
 }
 

package/src/go/index.js

@@ -1,7 +1,19 @@
 export { discoverGoRuntime, resolveProductRoot, resolveGoStateRoot, probeGoToolchain, DEFAULT_PRODUCT, SDK_ROOT } from './discover.js';
 export { ensureProductContract, readProductManifest, preflightToolchain } from './contract.js';
 export { buildGoProduct, runGoBuild, runGoTests, runGoVet } from './build.js';
-export { deployGoCloudflare, resolveWranglerIdentity, probeGoDeployment, probeGoDeploymentWithRetry, readLatestWranglerDeployment } from './cloudflare.js';
+export {
+  deployGoCloudflare,
+  resolveConfiguredDeploymentUrl,
+  resolveWranglerIdentity,
+  readLatestWranglerDeployment,
+  extractWorkersDevUrl,
+  guessWorkersDevUrl,
+} from './providers/cloudflare.js';
+
+export {
+  probeGoDeployment,
+  probeGoDeploymentWithRetry,
+} from './probe.js';
 export { verifyGoContainer } from './container.js';
 export { verifyGoProduct } from './verify.js';
 export {

package/src/go/probe.js

@@ -0,0 +1,109 @@
+const EXPECTED_HASH = '2e60bba13dc2bc37d75dd2ce5deb25466f19cb2994e20889388948879875eae9';
+
+export async function probeGoDeployment(origin, {
+  fetchImpl = globalThis.fetch,
+  expectedSource = null,
+  expectedSourceCommit = null,
+  expectedTarget = null,
+  edge = true,
+} = {}) {
+  const base = String(origin).replace(/\/+$/, '');
+  const results = {};
+  const checks = {};
+  const probedAt = new Date().toISOString();
+
+  async function request(key, pathname, init = {}) {
+    try {
+      const res = await fetchImpl(base + pathname, init);
+      let body = null;
+      try { body = await res.json(); } catch {}
+      results[key] = {
+        path: pathname,
+        status: res.status,
+        ok: res.status >= 200 && res.status < 300,
+        body,
+      };
+      return results[key];
+    } catch (error) {
+      results[key] = { path: pathname, status: 0, ok: false, error: error.message };
+      return results[key];
+    }
+  }
+
+  if (edge) {
+    await request('edge_root', '/', { headers: { Accept: 'application/json' } });
+    await request('edge_health', '/edge/health', { headers: { Accept: 'application/json' } });
+  }
+  await request('health', '/health', { headers: { Accept: 'application/json' } });
+  await request('runtime', '/v1/runtime', { headers: { Accept: 'application/json' } });
+  await request('capabilities', '/v1/capabilities', { headers: { Accept: 'application/json' } });
+  await request('hash', '/v1/hash', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({ input: 'agentsam', algorithm: 'sha256' }),
+  });
+  await request('inspect', '/v1/inspect', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({ files: [{ path: 'demo.css', content: '.button { color: #2563eb; }' }] }),
+  });
+  await request('malformed', '/v1/inspect', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({ not_files: true }),
+  });
+
+  const health = results.health?.body;
+  const runtime = results.runtime?.body;
+  const caps = results.capabilities?.body;
+  const malformed = results.malformed?.body;
+
+  if (edge) {
+    checks.edge_root = results.edge_root?.status === 200 && results.edge_root?.body?.edge === 'worker';
+    checks.edge_health = results.edge_health?.status === 200 && results.edge_health?.body?.edge === 'worker';
+    checks.edge_source = expectedSource
+      ? results.edge_root?.body?.source === expectedSource
+      : true;
+  }
+  checks.health = results.health?.status === 200
+    && health?.ok === true
+    && health?.runtime === 'go'
+    && (!expectedTarget || health?.target === expectedTarget);
+  checks.source_identity = expectedSource ? health?.build?.source === expectedSource : true;
+  checks.source_commit = expectedSourceCommit ? health?.build?.commit === expectedSourceCommit : true;
+  checks.runtime = results.runtime?.status === 200
+    && runtime?.schema === 'agentsam.go-runtime.v1'
+    && runtime?.os === 'linux';
+  checks.capabilities = results.capabilities?.status === 200
+    && caps?.schema === 'agentsam.go-capabilities.v1'
+    && ['hash', 'inspect', 'runtime', 'capabilities'].every((name) => caps?.capabilities?.includes(name));
+  checks.hash = results.hash?.status === 200 && results.hash?.body?.hash === EXPECTED_HASH;
+  checks.inspect = results.inspect?.status === 200
+    && results.inspect?.body?.findings?.some((finding) => finding.kind === 'hardcoded_color' && finding.value === '#2563eb');
+  checks.error_envelope = results.malformed?.status === 400
+    && malformed?.ok === false
+    && malformed?.schema_version === 1
+    && malformed?.reason === 'input_invalid'
+    && malformed?.code === 'INVALID_ARGUMENT';
+
+  results.deterministic_hash = { ok: checks.hash };
+  results.deterministic_inspect = { ok: checks.inspect };
+  results.malformed_rejected = { ok: checks.error_envelope };
+  const ok = Object.values(checks).every(Boolean);
+  return { origin: base, ok, checks, results, probed_at: probedAt };
+}
+
+export async function probeGoDeploymentWithRetry(origin, {
+  attempts = 12,
+  delayMs = 2500,
+  ...options
+} = {}) {
+  let latest = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    latest = await probeGoDeployment(origin, options);
+    latest.attempt = attempt;
+    if (latest.ok) return latest;
+    if (attempt < attempts) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return latest || { origin, ok: false, checks: {}, results: {}, probed_at: new Date().toISOString() };
+}