agenticloops 0.1.1 → 0.2.0

package/bin/cli.mjs

@@ -2,12 +2,13 @@
 // agenticloops — install and run agentic loops (recurring AI agents in one
 // LOOP.md). One file defines it; any harness can run it. https://agenticloops.dev
 import { install } from "../src/install.mjs";
+import { runLoop } from "../src/runcmd.mjs";
 import { loadRegistry, search } from "../src/registry.mjs";
 import { listRecords, parseSchedule } from "../src/schedule.mjs";
 import { fetchInstalls } from "../src/telemetry.mjs";
 import { c, sym, fail, info, CliError } from "../src/util.mjs";
 
-const VERSION = "0.1.1";
+const VERSION = "0.1.2";
 
 function parseArgs(argv) {
   const flags = {};
@@ -25,6 +26,7 @@ const HELP = `${c.bold("agenticloops")} — install and run agentic loops ${c.di
 
 ${c.bold("Usage")}
   npx agenticloops install <owner/loop> [--harness=<id>] [--no-telemetry] [--yes] [--dry-run]
+  npx agenticloops run <owner/loop|path> [--harness=<id>] [--backend=portable|5dive]
   npx agenticloops find <query>
   npx agenticloops list
   npx agenticloops update [<slug>]
@@ -32,6 +34,8 @@ ${c.bold("Usage")}
 ${c.bold("Commands")}
   install   Fetch + validate a LOOP.md, install its skills, pre-flight its
             requirements, and register the recurring job on your harness.
+  run       Execute a loop's chain once now (what a schedule fires). Multi-agent
+            loops run each role in order, threading {{previous_output}} forward.
   find      Search the public directory (agenticloops.dev) for loops.
   list      Show loops installed on this machine + their install counts.
   update    Re-fetch + re-install a loop (all, or one slug).
@@ -57,9 +61,32 @@ async function cmdInstall(positional, flags) {
     noTelemetry: !!flags["no-telemetry"],
     yes: !!flags.yes,
     dryRun: !!flags["dry-run"],
+    run: !!flags.run, // --run: execute the chain once right after install
   });
 }
 
+async function cmdRun(positional, flags) {
+  const ref = positional[0];
+  if (!ref) throw new CliError("usage: agenticloops run <owner/loop|path>", 2);
+  // --agents=role:agent,role:agent maps chain roles to 5dive agents (5dive backend).
+  let roleAgents;
+  if (typeof flags.agents === "string") {
+    roleAgents = {};
+    for (const pair of flags.agents.split(",")) {
+      const [role, agent] = pair.split(":");
+      if (role && agent) roleAgents[role.trim()] = agent.trim();
+    }
+  }
+  const res = await runLoop(ref, {
+    harness: typeof flags.harness === "string" ? flags.harness : undefined,
+    backend: typeof flags.backend === "string" ? flags.backend : undefined,
+    roleAgents,
+    agent: typeof flags.agent === "string" ? flags.agent : undefined,
+  });
+  if (flags.json) process.stdout.write(JSON.stringify(res.signed || res.receipt, null, 2) + "\n");
+  process.exitCode = res.ok ? 0 : 1;
+}
+
 async function cmdFind(positional) {
   const query = positional.join(" ");
   const { loops, url } = await loadRegistry();
@@ -94,8 +121,12 @@ async function cmdList() {
   for (const r of recs) {
     const n = installs[r.slug];
     const sched = r.cron ? r.cron : r.trigger?.value || "?";
+    const kind = r.multiAgent
+      ? c.cyan(`multi-agent: ${(r.roles || []).join(" → ")}`)
+      : c.dim("single-agent");
     process.stdout.write(
       `${c.bold(r.slug)}  ${c.dim("on " + r.harness)}${typeof n === "number" ? c.dim("  " + n + "↓ globally") : ""}\n` +
+        `  ${kind}\n` +
         `  ${c.cyan(sched)} — ${(r.description || "").split("\n")[0]}\n` +
         `  ${c.dim(r.source || r.ref)}\n\n`,
     );
@@ -138,6 +169,8 @@ async function main() {
     case "install":
     case "add":
       return cmdInstall(positional, flags);
+    case "run":
+      return cmdRun(positional, flags);
     case "find":
     case "search":
       return cmdFind(positional, flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticloops",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Install and run agentic loops — recurring AI agents defined in a single LOOP.md file. One file defines it; any harness can run it.",
   "type": "module",
   "bin": {
@@ -35,6 +35,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@5dive/openagent": "^0.35.0",
     "yaml": "^2.4.5"
   }
 }

package/src/backends/fivedive.mjs

@@ -0,0 +1,91 @@
+// 5dive-native backend — the host-optimized path. Each role is a linked 5dive
+// task assigned to a role agent; the agent is woken via HEARTBEAT (deterministic
+// — not tmux/agent-send keystroke injection, which is racy to a busy agent and
+// needs sudo), does the work, and finishes with `task done --result=…`. The
+// driver polls task STATUS (cold-safe) and the engine threads the structured
+// result into the next role's {{previous_output}}.
+//
+// Role→agent: opts.roleAgents maps role id -> agent name; falls back to
+// opts.agent (one agent runs the roles in sequence). v0.2 provisions a distinct
+// keyed agent per role so each handoff becomes a co-signed edge.
+import { spawnSync } from "node:child_process";
+
+const sh = (args) => spawnSync("5dive", args, { encoding: "utf8" });
+
+function taskAdd({ title, body, assignee }) {
+  // NOTE: 5dive flags are =form — `--body=x`, not `--body x` (caught in spike).
+  const r = sh(["task", "add", title, `--body=${body}`, `--assignee=${assignee}`, "--priority=high", "--json"]);
+  if (r.status !== 0) throw new Error(`task add failed: ${(r.stderr || r.stdout || "").trim()}`);
+  const m = (r.stdout || "").match(/([A-Z]+-\d+)/);
+  if (!m) throw new Error(`could not parse task id from: ${r.stdout}`);
+  return m[1];
+}
+
+function ensureHeartbeat(agent) {
+  // Idempotent: enroll the role agent so a queued task wakes it. Best-effort —
+  // if heartbeat enroll fails we still created the task (an operator/other tick
+  // can pick it up); we just won't auto-drive.
+  sh(["heartbeat", "on", agent]);
+}
+
+function nudgeTick() {
+  // Wake due agents NOW instead of waiting for the heartbeat cron, so a
+  // run-now chain doesn't stall up to the tick interval. Best-effort; needs root.
+  spawnSync("sudo", ["5dive", "heartbeat", "tick"], { encoding: "utf8" });
+}
+
+// The handoff instruction the heartbeat-woken agent needs: it sees ONLY the task
+// body (no agent-send), so the body must tell it to finish by completing the
+// task with its full output as --result (that result IS the next role's input).
+function withHandoffInstruction(prompt) {
+  return (
+    `${prompt}\n\n` +
+    `--- how to finish (required) ---\n` +
+    `Complete THIS task with your full, self-contained output as the result:\n` +
+    `  5dive task done <this-task-id> --result="<your output>"\n` +
+    `Your result is the ONLY thing passed to the next role — make it complete.`
+  );
+}
+
+function pollTask(taskId) {
+  const r = sh(["task", "show", taskId, "--json"]);
+  if (r.status !== 0) return { status: "unknown" };
+  try {
+    const j = JSON.parse(r.stdout);
+    const d = j.data?.task || j.data || j; // task show nests under data.task
+    return { status: d.status, result: d.result };
+  } catch {
+    return { status: "unknown" };
+  }
+}
+
+export function fivediveBackend(opts = {}) {
+  const roleAgents = opts.roleAgents || {};
+  const fallback = opts.agent || null;
+  const pollEveryMs = opts.pollEveryMs || 10000;
+  const timeoutMs = opts.timeoutMs || 30 * 60 * 1000;
+
+  return {
+    label: "5dive (linked tasks · heartbeat wake · structured result)",
+    async runRole({ role, prompt, onLog }) {
+      const agent = roleAgents[role] || fallback;
+      if (!agent) {
+        return { status: "error", output: "", error: `no agent mapped for role "${role}" (set roleAgents or --agent)` };
+      }
+      const taskId = taskAdd({ title: `${opts.loop || "loop"}:${role}`, body: withHandoffInstruction(prompt), assignee: agent });
+      ensureHeartbeat(agent);
+      if (opts.nudge !== false) nudgeTick();
+      onLog?.(`task ${taskId} → ${agent} (heartbeat wake)`);
+
+      const deadline = Date.now() + timeoutMs;
+      // NOTE: Date.now() is fine — live runtime path, not a resumable workflow.
+      for (;;) {
+        const p = pollTask(taskId);
+        if (p.status === "done") return { status: "done", output: p.result || "", ref: taskId };
+        if (p.status === "cancelled") return { status: "cancelled", output: p.result || "", ref: taskId };
+        if (Date.now() > deadline) return { status: "timeout", output: "", ref: taskId };
+        spawnSync("sleep", [String(Math.ceil(pollEveryMs / 1000))]);
+      }
+    },
+  };
+}

package/src/backends/portable.mjs

@@ -0,0 +1,45 @@
+// Portable backend — the harness-agnostic reference path (a JS port of the
+// reference run-loop.py). Runs each role as ONE headless invocation of the
+// harness's own model command (`claude -p`, `codex exec`, …) and threads the
+// structured output forward. Nothing host-specific beyond `headlessCmd`; the
+// loop file is identical across harnesses. Used for every non-5dive harness.
+import { spawn } from "node:child_process";
+
+function runOnce(cmd, prompt, { timeout = 180000 } = {}) {
+  return new Promise((resolve) => {
+    const [bin, ...args] = cmd;
+    const child = spawn(bin, [...args, prompt], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeout);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolve({ ok: false, output: "", error: `${bin} not runnable: ${e.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ ok: true, output: out.trim() });
+      else resolve({ ok: false, output: out.trim(), error: err.trim() || `exit ${code}` });
+    });
+  });
+}
+
+// backend factory. headlessCmd e.g. ["claude","-p"].
+export function portableBackend(headlessCmd, opts = {}) {
+  if (!Array.isArray(headlessCmd) || !headlessCmd.length)
+    throw new Error("portable backend needs a headlessCmd, e.g. [\"claude\",\"-p\"]");
+  return {
+    label: `portable (${headlessCmd.join(" ")})`,
+    async runRole({ prompt }) {
+      const r = await runOnce(headlessCmd, prompt, opts);
+      return {
+        status: r.ok ? "done" : "error",
+        output: r.output,
+        ref: headlessCmd[0],
+        error: r.error,
+      };
+    },
+  };
+}

package/src/chain.mjs

@@ -0,0 +1,72 @@
+// The harness-agnostic run engine. A multi-agent loop is ONE run executed as an
+// ordered chain of role-prompts; each role's structured output is threaded into
+// the next via {{previous_output}}. HOW a role is run (a local headless process,
+// a linked 5dive task, …) is the BACKEND's business — the engine only sequences
+// and threads. Backend contract:
+//   async runRole({ role, persona, prompt, index, total, onLog }) -> { output, ref, status }
+//   status === "done" continues; anything else stops the chain.
+
+// Thread the prior role's structured output into a role's prompt: substitute the
+// {{previous_output}} token if present, else prepend a context block. Role 1
+// (no prior output) just strips a dangling token.
+export function resolvePrompt(prompt, previous) {
+  const TOKEN = /\{\{\s*previous_output\s*\}\}/g;
+  if (!previous) return prompt.replace(TOKEN, "").trimEnd();
+  if (TOKEN.test(prompt)) return prompt.replace(TOKEN, previous);
+  return `--- context from the previous role ---\n${previous}\n--- end context ---\n\n${prompt}`;
+}
+
+export async function runChain(loopName, roles, backend, opts = {}) {
+  const onStep = opts.onStep || (() => {});
+  const steps = [];
+  let previous = opts.initialContext || null;
+
+  for (let i = 0; i < roles.length; i++) {
+    const role = roles[i];
+    const prompt = resolvePrompt(role.prompt, previous);
+    onStep({ phase: "start", role: role.role, index: i + 1, total: roles.length, handoffChars: previous?.length || 0 });
+
+    let res;
+    try {
+      res = await backend.runRole({
+        role: role.role,
+        persona: role.persona,
+        prompt,
+        index: i + 1,
+        total: roles.length,
+        onLog: (m) => onStep({ phase: "log", role: role.role, message: m }),
+      });
+    } catch (e) {
+      res = { status: "error", output: "", ref: null, error: e.message };
+    }
+
+    const status = res.status || "done";
+    steps.push({ role: role.role, persona: role.persona, ref: res.ref || null, status, output: res.output || "" });
+    onStep({ phase: "done", role: role.role, index: i + 1, status, ref: res.ref, error: res.error });
+
+    if (status !== "done") {
+      return { ok: false, loop: loopName, failedAt: role.role, steps, receipt: receiptBody(loopName, steps, false) };
+    }
+    previous = res.output || "";
+  }
+
+  return { ok: true, loop: loopName, steps, receipt: receiptBody(loopName, steps, true) };
+}
+
+// The unsigned receipt body. The signer (openagent did:key) wraps this.
+export function receiptBody(loopName, steps, ok) {
+  return {
+    loop: loopName,
+    ok,
+    ranAt: null, // stamped by the caller (engine stays time-pure for testability)
+    roles: steps.map((s) => ({
+      role: s.role,
+      persona: s.persona,
+      ref: s.ref,
+      status: s.status,
+      outputChars: (s.output || "").length,
+    })),
+    finalRole: steps.length ? steps[steps.length - 1].role : null,
+    outputs: Object.fromEntries(steps.map((s) => [s.role, s.output || null])),
+  };
+}

package/src/config.mjs

@@ -15,4 +15,4 @@ export const SKILLS_REGISTRY_URL = "https://skills.sh/index.json";
 export const SPEC_VERSION = "0.1";
 
 // User-Agent so server logs can attribute pings to the CLI (still anonymous).
-export const UA = `agenticloops-cli/0.1.1 (+${SITE})`;
+export const UA = `agenticloops-cli/0.1.2 (+${SITE})`;

package/src/harness.mjs

@@ -2,8 +2,9 @@
 // loop's skills, honor its trigger, and run the prompt. Crucially, a loop needs
 // SCHEDULING — a harness that can only run interactively (an IDE) can run the
 // agent but cannot honor a recurring trigger; we warn when targeting one.
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 
 function has(bin) {
@@ -15,36 +16,50 @@ function has(bin) {
   }
 }
 
-// Each harness: id, label, canSchedule, and a detect() that inspects cwd/env.
+// Each harness: id, label, canSchedule, headlessCmd (how it runs ONE prompt
+// non-interactively — the portable multi-agent backend shells this), and a
+// detect() that inspects cwd/env.
 export const HARNESSES = [
   {
     id: "5dive",
     label: "5dive runtime",
     canSchedule: true,
+    headlessCmd: ["claude", "-p"],
     detect: () => has("5dive") || existsSync("/var/lib/5dive"),
   },
   {
     id: "github-actions",
     label: "GitHub Actions",
     canSchedule: true,
+    headlessCmd: ["claude", "-p"],
     detect: (cwd) => existsSync(join(cwd, ".github", "workflows")) || !!process.env.GITHUB_ACTIONS,
   },
   {
     id: "claude-code",
     label: "Claude Code",
     canSchedule: false,
+    headlessCmd: ["claude", "-p"],
     detect: (cwd) => existsSync(join(cwd, ".claude")) || has("claude"),
   },
+  {
+    id: "codex",
+    label: "Codex CLI",
+    canSchedule: false,
+    headlessCmd: ["codex", "exec"],
+    detect: (cwd) => existsSync(join(cwd, ".codex")) || has("codex"),
+  },
   {
     id: "cursor",
     label: "Cursor",
     canSchedule: false,
+    headlessCmd: ["claude", "-p"], // no native headless; use claude if present
     detect: (cwd) => existsSync(join(cwd, ".cursor")),
   },
   {
     id: "cron",
     label: "system cron",
     canSchedule: true,
+    headlessCmd: ["claude", "-p"],
     detect: () => has("crontab"),
   },
 ];
@@ -53,6 +68,32 @@ export function getHarness(id) {
   return HARNESSES.find((h) => h.id === id);
 }
 
+// Where each harness keeps installed skills (a dir of <skill>/SKILL.md). Used
+// to mark a skill "host-satisfied" only when it's VERIFIABLY present, so the
+// skip is honest — never an asserted-but-unchecked built-in.
+const SKILL_DIRS = {
+  "claude-code": [join(homedir(), ".claude", "skills")],
+  cursor: [join(homedir(), ".cursor", "skills")],
+  "5dive": [join(homedir(), ".claude", "skills")],
+};
+
+export function hostSkillsFor(harnessId) {
+  const dirs = SKILL_DIRS[harnessId] || [];
+  const found = new Set();
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    try {
+      for (const name of readdirSync(dir)) {
+        const p = join(dir, name);
+        if (statSync(p).isDirectory() && existsSync(join(p, "SKILL.md"))) found.add(name);
+      }
+    } catch {
+      /* unreadable dir — skip */
+    }
+  }
+  return [...found];
+}
+
 // Auto-detect: prefer a schedulable harness when several are present, since a
 // loop's whole point is the recurring trigger. Returns { harness, all }.
 export function detectHarness(cwd = process.cwd()) {

package/src/install.mjs

@@ -1,8 +1,8 @@
 // The install flow (SPEC §3): fetch+validate LOOP.md -> install skills ->
 // pre-flight `requires` (prompt-or-refuse, never auto-install) -> register the
 // scheduled job -> (on success) anonymous telemetry ping.
-import { fetchLoopMd, parseLoopMd, validateManifest, triggerOf } from "./loop.mjs";
-import { detectHarness, getHarness } from "./harness.mjs";
+import { fetchLoopMd, parseLoopMd, validateManifest, triggerOf, isMultiAgent, rolesOf, allSkills } from "./loop.mjs";
+import { detectHarness, getHarness, hostSkillsFor } from "./harness.mjs";
 import { planSkills, installSkill } from "./skills.mjs";
 import { preflight } from "./preflight.mjs";
 import { parseSchedule, registerTrigger, saveRecord } from "./schedule.mjs";
@@ -39,8 +39,10 @@ export async function install(ref, opts = {}) {
   }
   const slug = manifest.name;
   const trig = triggerOf(manifest);
+  const multi = isMultiAgent(manifest);
   ok(`${c.bold(manifest.name)} — ${manifest.description?.split("\n")[0] ?? ""}`);
   info(`trigger: ${trig.kind === "event" ? `on ${trig.value}` : trig.value}`);
+  if (multi) info(`multi-agent: ${rolesOf(manifest).map((r) => r.role).join(" → ")} ${c.dim("(sequential chain)")}`);
 
   // 2. Pick the harness (auto-detect unless --harness given) + warn if it can't schedule.
   step("Target harness");
@@ -71,7 +73,10 @@ export async function install(ref, opts = {}) {
   }
 
   // 3. Install skills (§3.1) — host-satisfied skipped, paths fetched, bare resolved.
-  const skillPlan = await planSkills(manifest.skills || [], opts.hostSkills || []);
+  // Host-satisfied = verifiably present in the harness's skills dir (not asserted).
+  const hostSkills = [...new Set([...(opts.hostSkills || []), ...hostSkillsFor(harness.id)])];
+  // Multi-agent: install the union of shared + per-role skills.
+  const skillPlan = await planSkills(multi ? allSkills(manifest) : manifest.skills || [], hostSkills);
   if (skillPlan.length) {
     step("Skills");
     for (const s of skillPlan) {
@@ -138,13 +143,18 @@ export async function install(ref, opts = {}) {
     trigger: trig,
     cron: sched.cron || null,
     description: manifest.description,
+    multiAgent: multi,
+    roles: multi ? rolesOf(manifest).map((r) => r.role) : null,
     installedAt: new Date().toISOString(),
   };
   if (!dryRun) saveRecord(slug, record, fetched.raw);
+  // A multi-agent loop's scheduled body runs the whole chain via the CLI; a
+  // single-prompt loop's body is the prompt itself.
+  const body = multi ? `npx agenticloops run ${loopRef} --harness=${harness.id}` : prompt;
   const reg = registerTrigger(harness.id, {
     slug,
     name: manifest.name,
-    prompt,
+    prompt: body,
     cron: sched.cron || manifest.schedule || "",
     dryRun,
   });
@@ -162,5 +172,12 @@ export async function install(ref, opts = {}) {
   step(`${sym.ok} Installed ${c.bold(slug)} on ${harness.label}${dryRun ? c.dim(" (dry-run)") : ""}`);
   if (reg.scheduled === false && trig.needsScheduler)
     info(`it won't fire until you wire a scheduler — see ${c.cyan("agenticloops list")}`);
+
+  // --run executes the chain once now (the install-and-it-runs demo moment).
+  if (opts.run && !dryRun) {
+    const { runLoop } = await import("./runcmd.mjs");
+    const res = await runLoop(loopRef, { harness: harness.id });
+    return { ...record, firstRun: res.receipt, signed: res.signed };
+  }
   return record;
 }

package/src/loop.mjs

@@ -99,9 +99,52 @@ export function validateManifest(manifest) {
   if (m.skills && !Array.isArray(m.skills)) errs.push("`skills` must be a list");
   if (m.requires && typeof m.requires !== "object") errs.push("`requires` must be a mapping");
 
+  // Multi-agent (§ agents:) — an ordered chain of role-prompts. Additive: a loop
+  // with no `agents:` is the single-prompt body, unchanged.
+  if (m.agents !== undefined) {
+    if (!Array.isArray(m.agents) || m.agents.length === 0) {
+      errs.push("`agents` must be a non-empty list of roles");
+    } else {
+      const seen = new Set();
+      m.agents.forEach((a, i) => {
+        if (!a || typeof a !== "object") return errs.push(`agents[${i}] must be a mapping`);
+        if (!a.role || !/^[a-z0-9][a-z0-9-]*$/.test(a.role))
+          errs.push(`agents[${i}].role must be a kebab-case id`);
+        else if (seen.has(a.role)) errs.push(`duplicate role "${a.role}"`);
+        else seen.add(a.role);
+        if (!a.prompt || typeof a.prompt !== "string")
+          errs.push(`agents[${i}] (${a.role || i}) is missing a prompt`);
+        if (a.skills && !Array.isArray(a.skills))
+          errs.push(`agents[${i}].skills must be a list`);
+      });
+    }
+  }
+
   return errs;
 }
 
+// A loop is multi-agent when it carries a non-empty ordered `agents:` chain.
+export function isMultiAgent(manifest) {
+  return Array.isArray(manifest?.agents) && manifest.agents.length > 0;
+}
+
+// Normalised roles for the run engine. Role 1 gets no prior output.
+export function rolesOf(manifest) {
+  return (manifest.agents || []).map((a) => ({
+    role: a.role,
+    persona: a.persona || null,
+    skills: Array.isArray(a.skills) ? a.skills : [],
+    prompt: a.prompt,
+  }));
+}
+
+// Every skill the loop touches: top-level (shared) ∪ per-role (additive).
+export function allSkills(manifest) {
+  const top = Array.isArray(manifest.skills) ? manifest.skills : [];
+  const perRole = (manifest.agents || []).flatMap((a) => (Array.isArray(a.skills) ? a.skills : []));
+  return [...new Set([...top, ...perRole])];
+}
+
 // A trigger that a harness must be able to honor. `schedule` accepts human
 // grammar or raw cron; we don't expand it here — adapters do — but we surface a
 // label and whether scheduling (vs event) is needed.

package/src/receipt.mjs

@@ -0,0 +1,84 @@
+// Run receipts — REUSE the canonical openagent receipt scheme so the bytes match
+// card provenance, A2A handshakes, and zerohuman edges (one verifier ranks the
+// whole directory: "proof, not popularity"). We import lib/receipts.js directly
+// from the published @5dive/openagent and reimplement only the tiny keystore
+// loader on lib/provenance.js (keystore.js isn't published) — SAME
+// ~/.openagent/agent.key path + SAME keygen, so the did:key is byte-identical.
+//
+// v0.1 = SINGLE-SIGNER run receipt: the loop owner's did signs one body over the
+// whole run (hashed outputs, never the raw text). An honest attestation that the
+// run happened with these outputs. v0.2 = per-handoff co-signed EDGES on the
+// 5dive backend where each role is a distinct keyed agent (receipts.cosign()).
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+// Both come straight from the published @5dive/openagent package (>=0.35.0 ships
+// lib/receipts.js), so signatures are byte-identical to card provenance /
+// zerohuman edges — no vendored copy to drift from the canonical scheme.
+const receipts = require("@5dive/openagent/lib/receipts.js");
+const provenance = require("@5dive/openagent/lib/provenance.js");
+
+function agentHome() {
+  const env = process.env.OPENAGENT_HOME;
+  if (env && env.trim()) {
+    const e = env.trim();
+    return e.startsWith("~") ? path.join(os.homedir(), e.slice(1)) : path.resolve(e);
+  }
+  return path.join(os.homedir(), ".openagent");
+}
+
+// Load the agent's keystore key (~/.openagent/agent.key), minting one on first
+// use — identical layout + keygen to openagent/lib/keystore.js so the identity
+// is the same one the agent's card/handshakes use.
+export function loadOrCreateKey() {
+  const home = agentHome();
+  const keyPath = path.join(home, "agent.key");
+  let privateKey;
+  try {
+    privateKey = fs.readFileSync(keyPath, "utf8").trim();
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    const kp = provenance.generateKeypair();
+    fs.mkdirSync(home, { recursive: true });
+    fs.writeFileSync(keyPath, kp.privateKey + "\n", { mode: 0o600 });
+    try {
+      fs.writeFileSync(path.join(home, "agent.pub"), kp.publicKey + "\n", { mode: 0o644 });
+    } catch {
+      /* pub is a convenience */
+    }
+    privateKey = kp.privateKey;
+  }
+  const publicKey = provenance.publicPemFromPrivate(privateKey);
+  return { privateKey, publicKey, did: provenance.didKeyFromPublicKey(publicKey) };
+}
+
+// Sign a single-signer run receipt over the chain. `steps` = [{role, persona,
+// output}]. Outputs are sha256-hashed (size/privacy) — never embedded.
+export function signRunReceipt({ loop, spec = "0.1", steps, at }) {
+  const key = loadOrCreateKey();
+  const body = {
+    v: 1,
+    loop,
+    spec,
+    roles: steps.map((s) => ({
+      role: s.role,
+      persona: s.persona || null,
+      output_hash: receipts.hash(s.output || ""),
+    })),
+    final: steps.length ? receipts.hash(steps[steps.length - 1].output || "") : null,
+    at,
+  };
+  return { receipt: body, sigs: [receipts.sign(body, key.privateKey)], signer: key.did };
+}
+
+// Verify a single-signer run receipt: the signature verifies over the body and
+// its `by` did matches its embedded key. (requireBoth=false — this is an
+// attestation, not a two-party edge.)
+export function verifyRunReceipt(signed) {
+  return receipts.verify(signed, { requireBoth: false });
+}
+
+export { receipts };

package/src/runcmd.mjs

@@ -0,0 +1,74 @@
+// `agenticloops run <ref>` — execute a loop's chain ONCE, now. This is what a
+// schedule fires (a recurring 5dive task / GH Actions job calls it), and it's
+// how you test a loop locally. Routes to a backend by harness: 5dive uses the
+// native linked-task chain; everything else uses the portable headless runner.
+import { fetchLoopMd, parseLoopMd, validateManifest, isMultiAgent, rolesOf } from "./loop.mjs";
+import { detectHarness, getHarness } from "./harness.mjs";
+import { portableBackend } from "./backends/portable.mjs";
+import { fivediveBackend } from "./backends/fivedive.mjs";
+import { runChain } from "./chain.mjs";
+import { signRunReceipt } from "./receipt.mjs";
+import { c, info, ok, warn, fail, step, CliError } from "./util.mjs";
+
+function pickBackend(harness, opts) {
+  // harness=5dive -> host-optimized linked-task chain (distinct agents, task
+  // receipts). Everything else -> portable headless runner. --backend overrides.
+  const choice = opts.backend || (harness.id === "5dive" ? "5dive" : "portable");
+  if (choice === "5dive") return fivediveBackend(opts);
+  if (!harness.headlessCmd)
+    throw new CliError(`harness ${harness.id} has no headless run command for the portable backend`, 2);
+  return portableBackend(harness.headlessCmd, opts);
+}
+
+export async function runLoop(ref, opts = {}) {
+  const fetched = await fetchLoopMd(ref);
+  const { manifest, prompt } = parseLoopMd(fetched.raw);
+  const errs = validateManifest(manifest);
+  if (errs.length) {
+    errs.forEach((e) => fail(e));
+    throw new CliError("LOOP.md failed validation", 3);
+  }
+
+  // Single-prompt loops run as a one-role chain so one engine handles both.
+  const roles = isMultiAgent(manifest)
+    ? rolesOf(manifest)
+    : [{ role: "main", persona: manifest.persona || null, skills: manifest.skills || [], prompt }];
+
+  const harness = opts.harness
+    ? getHarness(opts.harness) || (() => { throw new CliError(`unknown harness "${opts.harness}"`, 2); })()
+    : detectHarness().harness;
+  if (!harness) throw new CliError("no harness detected — pass --harness=<id>", 4);
+
+  const backend = pickBackend(harness, { ...opts, loop: manifest.name });
+  step(`Running ${c.bold(manifest.name)} — ${roles.length} role${roles.length > 1 ? "s" : ""} · ${backend.label}`);
+
+  const result = await runChain(manifest.name, roles, backend, {
+    onStep: (s) => {
+      if (s.phase === "start")
+        info(`role ${s.index}/${s.total}: ${c.bold(s.role)}${s.handoffChars ? c.dim(` ← ${s.handoffChars} chars`) : ""}`);
+      else if (s.phase === "done")
+        s.status === "done"
+          ? ok(`${s.role} ${c.dim(s.ref ? "(" + s.ref + ")" : "")}`)
+          : fail(`${s.role} → ${s.status}${s.error ? ": " + s.error : ""}`);
+      else if (s.phase === "log") info(c.dim(`  ${s.message}`));
+    },
+  });
+
+  const at = new Date().toISOString();
+  result.receipt.ranAt = at;
+
+  // Sign a single-signer run receipt with the owner's openagent did:key — same
+  // scheme as card provenance / zerohuman edges, so one verifier ranks them all.
+  if (opts.sign !== false) {
+    try {
+      result.signed = signRunReceipt({ loop: manifest.name, steps: result.steps, at });
+      info(c.dim(`receipt signed by ${result.signed.signer}`));
+    } catch (e) {
+      warn(`receipt signing skipped: ${e.message}`);
+    }
+  }
+
+  if (result.ok) step(`${c.green("✓")} chain complete — final output by ${c.bold(result.receipt.finalRole)}`);
+  else warn(`chain stopped at ${result.failedAt}`);
+  return result;
+}

package/src/schedule.mjs

@@ -70,8 +70,9 @@ export function removeRecord(slug) {
 // --- harness adapters: register the recurring trigger -----------------------
 
 function registerOn5dive({ name, prompt, cron, dryRun }) {
-  const args = ["task", "add", name, "--body", prompt, "--recurring", cron];
-  if (dryRun) return { ok: true, detail: `5dive ${args.join(" ")}`, skipped: "dry-run" };
+  // 5dive flags are =form (`--body=x`, not `--body x`) — caught in the spike.
+  const args = ["task", "add", name, `--body=${prompt}`, `--recurring=${cron}`];
+  if (dryRun) return { ok: true, detail: `5dive task add ${name} --recurring=${cron}`, skipped: "dry-run" };
   const res = spawnSync("5dive", args, { stdio: "inherit" });
   return { ok: res.status === 0, detail: `5dive ${args.join(" ")}`, status: res.status };
 }