cool-workflow 0.1.87 → 0.1.88

package/dist/doctor.js

@@ -91,7 +91,15 @@ function runDoctor(args = {}, env = process.env, cwd = process.cwd()) {
         : { name: "node", status: "fail", detail: `Node ${process.version} is below the required v18.`, fix: "Install Node.js 18+ (e.g. `brew install node`, or https://nodejs.org)." });
     // 2. Agent backend — CW delegates execution; without one, real runs park.
     const cfg = (0, agent_config_1.resolveAgentConfig)(args, env);
-    if (cfg.source === "none") {
+    if (cfg.source === "auto") {
+        const vendor = (cfg.model && cfg.model.startsWith("builtin:")) ? cfg.model.slice("builtin:".length) : "auto";
+        checks.push({
+            name: "agent",
+            status: "ok",
+            detail: `Agent auto-detected: ${vendor}. Set CW_AGENT_COMMAND or --agent-command to override.`
+        });
+    }
+    else if (cfg.source === "none") {
         checks.push({
             name: "agent",
             status: "warn",
@@ -161,6 +169,11 @@ function formatDoctorReport(report) {
     const summaryGlyph = report.ok ? (0, term_1.green)("✓") : (0, term_1.red)("✗");
     lines.push(`${summaryGlyph} ${report.summary}`);
     if (report.onramp) {
+        lines.push("");
+        lines.push("Quick start (3 steps):");
+        lines.push("  1. cw demo tamper        — prove trust checks work (30s)");
+        lines.push("  2. cw demo bundle         — prove portable bundles (30s)");
+        lines.push('  3. cw -q "what risks?"     — your first real report (needs an agent)');
         lines.push("");
         lines.push("Onramp");
         lines.push(`  ${report.onramp.summary}`);

package/dist/drive.js

@@ -25,7 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DRIVE_SCHEMA_VERSION = void 0;
+exports.MAX_SUB_WORKFLOW_DEPTH = exports.DRIVE_SCHEMA_VERSION = void 0;
 exports.driveStep = driveStep;
 exports.driveConcurrentRound = driveConcurrentRound;
 exports.drive = drive;
@@ -38,9 +38,14 @@ const worker_isolation_1 = require("./worker-isolation");
 const agent_config_1 = require("./agent-config");
 const scheduling_1 = require("./scheduling");
 const observability_1 = require("./observability");
+const loop_expansion_1 = require("./loop-expansion");
+const telemetry_attestation_1 = require("./telemetry-attestation");
 const state_1 = require("./state");
+const trust_audit_1 = require("./trust-audit");
 const compare_1 = require("./compare");
 exports.DRIVE_SCHEMA_VERSION = 1;
+/** Hard cap on inline sub-workflow nesting depth (fail-closed bound on recursion). */
+exports.MAX_SUB_WORKFLOW_DEPTH = 4;
 /** The task the next drive step would advance: a RUNNING (already-dispatched,
  *  awaiting fulfillment / retry) task first, else the next PENDING task in the
  *  first runnable phase. Deterministic; honors the existing phase gate. */
@@ -71,10 +76,12 @@ function exitCodeFromEvidence(evidence) {
 function agentConfigured(config) {
     return Boolean(config.command || config.endpoint);
 }
-/** Opt-in progress to STDERR (stdout stays clean JSON), gated on CW_DRIVE_PROGRESS,
- *  so a live multi-minute drive is observable. */
+/** Progress to STDERR (stdout stays clean JSON). On by default when stderr is a
+ *  TTY; silent in CI/pipes. CW_DRIVE_PROGRESS=0 forces off, =1 forces on. */
 function emitProgress(message) {
-    if (process.env.CW_DRIVE_PROGRESS)
+    const forcedOff = process.env.CW_DRIVE_PROGRESS === "0";
+    const forcedOn = process.env.CW_DRIVE_PROGRESS === "1";
+    if ((Boolean(process.stderr.isTTY) && !forcedOff) || forcedOn)
         process.stderr.write(`[drive] ${message}\n`);
 }
 /** Advance exactly ONE deterministic step. Pure-ish: all mutation is through the
@@ -202,7 +209,7 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
     // immediate activity instead of a long silence on the first worker. task.label
     // is the human-facing display name; the id stays the stable reference.
     const promptDigest = node_fs_1.default.existsSync(manifest.inputPath) ? (0, execution_backend_1.sha256)(node_fs_1.default.readFileSync(manifest.inputPath, "utf8")) : (0, execution_backend_1.sha256)(manifest.prompt || "");
-    const cachePath = resultCachePath(run, selected, (0, execution_backend_1.sha256)(selected.prompt));
+    const cachePath = resultCachePath(run, selected, (0, execution_backend_1.sha256)(selected.prompt), ctx.incremental, ctx.incremental ? incrementalDelegationDigest(selected, manifest, ctx.config) : "");
     if (cachePath && node_fs_1.default.existsSync(cachePath)) {
         emitProgress(`↺ ${selected.label || selected.id} (${selected.phase}) — accepting cached result`);
         try {
@@ -220,6 +227,12 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
             reason: "result cache hit"
         });
     }
+    // Sub-workflow fulfillment (alternative to the agent backend): plan + drive a
+    // CHILD run and bind its report back as this task's result. Leaf work is still
+    // external-agent delegation at every level; CW imports no model SDK here.
+    if (selected.subWorkflow) {
+        return runSubWorkflow(ctx, run, selected, workerId, manifest);
+    }
     emitProgress(`→ ${selected.label || selected.id} (${selected.phase}) — ${dispatched ? "dispatched, " : ""}spawning agent, may take minutes…`);
     const envelope = (0, execution_backend_1.runBackend)(buildAgentRequest(ctx, run, selected, manifest, preparedOutcome));
     const handle = envelope.provenance.handle;
@@ -269,7 +282,63 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
         reportedModel
     });
 }
-function resultCachePath(run, task, promptDigest) {
+function cacheFilePath(run, task, digest) {
+    return node_path_1.default.join(run.cwd, ".cw", "cache", "worker-results", (0, state_1.safeFileName)(run.workflow.id), `${(0, state_1.safeFileName)(task.id)}-${digest.replace(/^sha256:/, "").slice(0, 32)}.md`);
+}
+/** Digest of the per-task DELEGATION config that determines a result but is NOT
+ *  carried by the prompt or run.inputs: the resolved model (task override OR the
+ *  global agent-config model), the agent IDENTITY (which binary/endpoint actually
+ *  produces the bytes — `command`/`args`/`endpoint`), the backend driver, and the
+ *  resolved sandbox PROFILE ID. All of these are operator flags/env (`--agent-model`,
+ *  `--agent-command`, `--agent-endpoint`, ...) stripped from run.inputs by
+ *  DRIVE_RUNTIME_KEYS, so they must be folded here or swapping the model/agent/
+ *  endpoint would serve a stale result (and attest the wrong producer). The sandbox
+ *  PROFILE ID (not the full resolved policy) is used because the policy's read/write
+ *  paths embed the per-run worker dir, so the full policy is NOT stable across runs
+ *  (it would defeat all reuse); the id is stable and changes on a profile swap. Args
+ *  are secret-stripped (no credential lands in the digest input). `config.args` is
+ *  the un-substituted template (e.g. `{{result}}`), so it is stable across runs.
+ *  Deterministic: stableStringify, no clock/random. */
+function incrementalDelegationDigest(task, manifest, config) {
+    return (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)({
+        model: task.model || config.model || "",
+        agentType: task.agentType || "agent",
+        sandboxProfileId: manifest.sandboxPolicy?.id || task.sandboxProfileId || "",
+        command: config.command || "",
+        args: config.args ? (0, execution_backend_1.stripSecretArgs)(config.args) : [],
+        endpoint: config.endpoint || ""
+    }));
+}
+function resultCachePath(run, task, promptDigest, incremental, delegationDigest) {
+    // Incremental resume (opt-in, run-level): EVERY task is keyed by content so a
+    // re-run reuses the longest unchanged prefix. The key folds the rendered prompt,
+    // the full run.inputs, the per-task DELEGATION config (model/backend/sandbox —
+    // result-determining but NOT carried by prompt/inputs, so editing the model must
+    // invalidate), and the UPSTREAM RESULT digests (not just prompts: a CW prompt is
+    // rendered from run.inputs and does NOT carry an upstream task's result bytes, so
+    // a changed/nondeterministic upstream result must invalidate downstream — which
+    // keying on upstream result bytes does). A changed prompt/input/model perturbs
+    // that task's key, and its changed result perturbs every downstream key, so the
+    // "first changed task and everything after" re-run falls out for free. The phase
+    // barrier guarantees every upstream task is `completed` before this task runs, so
+    // its result bytes are available to digest. schemaVersion:2 never collides with
+    // the opt-in schemaVersion:1 cache below.
+    if (incremental) {
+        const upstreamResultsDigest = previousPhaseResultsDigest(run, task);
+        if (upstreamResultsDigest === undefined)
+            return undefined;
+        const digest = (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)({
+            schemaVersion: 2,
+            workflowId: run.workflow.id,
+            taskId: task.id,
+            promptDigest,
+            runInputsDigest: (0, execution_backend_1.sha256)((0, telemetry_attestation_1.stableStringify)(run.inputs || {})),
+            delegationDigest,
+            upstreamResultsDigest
+        }));
+        return cacheFilePath(run, task, digest);
+    }
+    // Default: the per-task OPT-IN cache (unchanged — POLA).
     const policy = task.resultCache;
     if (!policy || policy.mode !== "read-write")
         return undefined;
@@ -288,12 +357,13 @@ function resultCachePath(run, task, promptDigest) {
         keyValue,
         promptDigest,
         completedResultsDigest
-    })).replace(/^sha256:/, "");
-    return node_path_1.default.join(run.cwd, ".cw", "cache", "worker-results", (0, state_1.safeFileName)(run.workflow.id), `${(0, state_1.safeFileName)(task.id)}-${digest.slice(0, 32)}.md`);
+    }));
+    return cacheFilePath(run, task, digest);
 }
-function completedResultsCacheDigest(run, task) {
-    if (task.resultCache?.includeCompletedResults !== "previous-phases")
-        return "";
+/** Digest of the result bytes of every task in strictly-earlier phases (deterministic
+ *  id order). `undefined` when any such task is not yet completed/readable — so a
+ *  caller never keys on partial upstream state. */
+function previousPhaseResultsDigest(run, task) {
     const phaseIndex = run.phases.findIndex((phase) => phase.name === task.phase || phase.id === task.phase);
     if (phaseIndex < 0)
         return undefined;
@@ -310,6 +380,11 @@ function completedResultsCacheDigest(run, task) {
         return undefined;
     return (0, execution_backend_1.sha256)(JSON.stringify(records));
 }
+function completedResultsCacheDigest(run, task) {
+    if (task.resultCache?.includeCompletedResults !== "previous-phases")
+        return "";
+    return previousPhaseResultsDigest(run, task);
+}
 function writeResultCache(file, content) {
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
     const tmp = `${file}.${process.pid}.tmp`;
@@ -393,7 +468,7 @@ function prepareConcurrentOutcomes(ctx, batch) {
             continue;
         }
         const manifest = runner.showWorkerManifest(runId, workerId);
-        const cachePath = resultCachePath(run, task, (0, execution_backend_1.sha256)(task.prompt));
+        const cachePath = resultCachePath(run, task, (0, execution_backend_1.sha256)(task.prompt), ctx.incremental, ctx.incremental ? incrementalDelegationDigest(task, manifest, ctx.config) : "");
         if (cachePath && node_fs_1.default.existsSync(cachePath))
             continue;
         const job = (0, execution_backend_1.prepareAgentSpawn)(buildAgentRequest(ctx, run, task, manifest));
@@ -458,19 +533,150 @@ function handleHop(ctx, task, workerId, reason) {
 function step(action, status, fields) {
     return { schemaVersion: 1, action, status, ...fields };
 }
+function errMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Render a sub-workflow's input templates against the PARENT run's inputs, so the
+ *  child inputs are a pure function of recorded parent inputs (deterministic). */
+function renderSubInputs(spec, parentInputs) {
+    const out = {};
+    for (const [key, template] of Object.entries(spec.inputs || {})) {
+        out[key] = String(template).replace(/\{\{(\w+)\}\}/g, (_, name) => String(parentInputs[name] ?? ""));
+    }
+    return out;
+}
+/** Fulfill a sub-workflow task: plan + drive a CHILD run, then bind its report (or
+ *  verdict result) back as the parent task's result through the SAME accept path, so
+ *  the parent's verifier/schema/evidence gate and downstream tasks treat it like any
+ *  other result. Fail-closed: bounded recursion + cycle detection BEFORE any child
+ *  state is minted; a child that does not complete parks the parent hop. The child's
+ *  own telemetry/audit live in the child run; the parent records ONE honest
+ *  `worker.sub-workflow` cross-link (child run id + report digest + child audit
+ *  verdict) — nothing is summed or fabricated. */
+function runSubWorkflow(ctx, run, selected, workerId, manifest) {
+    const spec = selected.subWorkflow;
+    const parentApp = run.workflow.id;
+    // Fail-closed BEFORE planning a child (no child state minted when refused).
+    if (ctx.depth + 1 > exports.MAX_SUB_WORKFLOW_DEPTH) {
+        return handleHop(ctx, selected, workerId, `sub-workflow depth limit exceeded (> ${exports.MAX_SUB_WORKFLOW_DEPTH})`);
+    }
+    // Include the CURRENT app on the path, so a direct self-cycle (A→A) is caught at
+    // depth 0 — before any child run dir is minted.
+    if ([...ctx.visitedAppIds, parentApp].includes(spec.appId)) {
+        return handleHop(ctx, selected, workerId, `sub-workflow cycle detected: ${[...ctx.visitedAppIds, parentApp, spec.appId].join(" -> ")}`);
+    }
+    // Deterministic child run id derived from the parent run + task (no clock/random).
+    const childRunId = `sub-${run.id}-${(0, state_1.safeFileName)(selected.id)}`;
+    const childInputs = {
+        repo: run.inputs.repo ?? run.cwd,
+        cwd: run.cwd,
+        question: run.inputs.question ?? "",
+        ...renderSubInputs(spec, run.inputs),
+        runId: childRunId
+    };
+    emitProgress(`⧉ ${selected.label || selected.id} (${selected.phase}) — sub-workflow ${spec.appId}…`);
+    let childRun;
+    try {
+        childRun = ctx.runner.plan(spec.appId, childInputs);
+    }
+    catch (error) {
+        return handleHop(ctx, selected, workerId, `sub-workflow plan failed (${spec.appId}): ${errMessage(error)}`);
+    }
+    const childResult = drive(ctx.runner, childRun.id, {
+        now: ctx.now,
+        agentConfig: ctx.config,
+        policy: ctx.policy,
+        incremental: ctx.incremental,
+        depth: ctx.depth + 1,
+        visitedAppIds: [...ctx.visitedAppIds, parentApp]
+    });
+    if (childResult.status !== "complete") {
+        return handleHop(ctx, selected, workerId, `sub-workflow ${spec.appId} did not complete (status: ${childResult.status})`);
+    }
+    // Bind the child's bytes: the rendered report (default) or the verdict result.
+    const finalChild = ctx.runner.loadRun(childRun.id);
+    let childBytes;
+    if (spec.bindResult === "verdict-result") {
+        const verdict = finalChild.tasks.find((t) => /^verdict[:/]|^synthesis[:/]/i.test(t.id) && t.status === "completed");
+        childBytes = verdict?.resultPath && node_fs_1.default.existsSync(verdict.resultPath) ? node_fs_1.default.readFileSync(verdict.resultPath, "utf8") : undefined;
+    }
+    else {
+        childBytes = node_fs_1.default.existsSync(finalChild.paths.report) ? node_fs_1.default.readFileSync(finalChild.paths.report, "utf8") : undefined;
+    }
+    if (childBytes === undefined) {
+        return handleHop(ctx, selected, workerId, `sub-workflow ${spec.appId} produced no ${spec.bindResult || "report"}`);
+    }
+    // Accept through the SAME path as any other result (verifier/schema/evidence gate).
+    try {
+        node_fs_1.default.writeFileSync(manifest.resultPath, childBytes, "utf8");
+        ctx.runner.recordWorkerOutput(run.id, workerId, manifest.resultPath, {});
+    }
+    catch (error) {
+        return handleHop(ctx, selected, workerId, `sub-workflow result rejected by parent gate: ${errMessage(error)}`);
+    }
+    // Honest cross-link (provenance only — never fails the accepted hop): one
+    // worker.sub-workflow audit event on the parent pins the child run + report digest
+    // + the child's own audit-chain verdict, and the task points at the child run dir.
+    try {
+        const afterAccept = ctx.runner.loadRun(run.id);
+        const task = afterAccept.tasks.find((t) => t.id === selected.id);
+        const childAudit = (0, trust_audit_1.verifyTrustAudit)(finalChild);
+        (0, trust_audit_1.recordTrustAuditEvent)(afterAccept, {
+            kind: "worker.sub-workflow",
+            decision: "recorded",
+            source: "runtime-derived",
+            workerId,
+            taskId: selected.id,
+            nodeId: task?.resultNodeId,
+            metadata: {
+                subWorkflowAppId: spec.appId,
+                subRunId: childRun.id,
+                childReportDigest: (0, execution_backend_1.sha256)(childBytes),
+                childAuditVerified: childAudit.verified,
+                bindResult: spec.bindResult || "report"
+            }
+        });
+        if (task) {
+            task.subRunId = childRun.id;
+            task.subRunDir = finalChild.paths.runDir;
+        }
+        (0, state_1.saveCheckpoint)(afterAccept);
+    }
+    catch {
+        /* the cross-link is provenance; a failure here must not undo an accepted hop */
+    }
+    return step("accept", "ok", {
+        runId: run.id,
+        taskId: selected.id,
+        phase: selected.phase,
+        handleKind: "sub-workflow",
+        reason: `sub-workflow ${spec.appId} → ${childRun.id}`
+    });
+}
 /** Drive a run: `--once` advances exactly one step; otherwise run to completion,
  *  park, or a blocked stop. Composes the existing verbs + the agent backend only. */
 function drive(runner, runId, options = {}) {
     const now = options.now || new Date().toISOString();
     const policy = (0, scheduling_1.normalizeSchedulingPolicy)(options.policy || scheduling_1.DEFAULT_SCHEDULING_POLICY);
     const config = options.agentConfig || (0, agent_config_1.resolveAgentConfig)(options.args || {});
-    const ctx = { runner, runId, now, policy, config, attempts: new Map() };
+    const ctx = {
+        runner, runId, now, policy, config, attempts: new Map(),
+        incremental: Boolean(options.incremental),
+        depth: Math.max(0, Math.floor(options.depth || 0)),
+        visitedAppIds: options.visitedAppIds || []
+    };
     const steps = [];
     const run0 = runner.loadRun(runId);
     const plannedWorkers = run0.tasks.length;
-    // Safety bound: every worker, every retry, plus the terminal commit + slack.
-    // Each concurrent round retires >=1 worker, so this bounds rounds too.
-    const maxIterations = plannedWorkers * (policy.maxAttempts + 1) + 5;
+    // Safety bound: every worker, every retry, plus the terminal commit + slack. Each
+    // concurrent round retires >=1 worker, so this bounds rounds too. A bounded dynamic
+    // loop can append up to (maxRounds-1)×templateTasks MORE tasks at runtime, so the
+    // iteration bound (NOT plannedWorkers, which stays the initial count for status) adds
+    // the worst-case expansion derived STATICALLY from the declaration — a pure function
+    // of the workflow, never of runtime results — so the bound is replay-stable and the
+    // drive is provably terminating; it reduces to the original value when there are no
+    // loop phases.
+    const maxIterations = (plannedWorkers + (0, loop_expansion_1.maxLoopExpansion)(run0)) * (policy.maxAttempts + 1) + 5;
     const concurrency = Math.max(1, Math.floor(options.concurrency || 1));
     // The parallel() on-ramp: a phase authored with mode "parallel" is fulfilled
     // concurrently through EVERY shipping surface (run --drive, quickstart) — no

package/dist/execution-backend.js

@@ -678,10 +678,10 @@ function runAgentProcess(descriptor, policy, request, label, handle, attestation
             outcome = request.preparedAgentOutcome;
         }
         else {
-            // Live output is opt-in (POLA): stdout is always captured as data, while
-            // stderr is forwarded only when the operator explicitly asks for a stream
-            // and this process is attached to a terminal. CI/pipes stay silent.
-            const streamStderr = process.env.CW_AGENT_STREAM === "1" && Boolean(process.stderr.isTTY) && process.env.CW_NO_STREAM !== "1";
+            // Live output on by default when stderr is a TTY. stdout is always
+            // captured as data. CI/pipes stay silent. CW_AGENT_STREAM=0 or
+            // CW_NO_STREAM=1 forces off; CW_AGENT_STREAM=1 forces on.
+            const streamStderr = process.env.CW_AGENT_STREAM !== "0" && Boolean(process.stderr.isTTY) && process.env.CW_NO_STREAM !== "1";
             const child = (0, node_child_process_1.spawnSync)(resolved.binary, realArgs, {
                 cwd: request.cwd,
                 env: { ...process.env },

package/dist/loop-expansion.js

@@ -0,0 +1,60 @@
+"use strict";
+// Bounded dynamic control flow (#2) — a declarative LOOP phase whose tasks are a
+// per-round TEMPLATE: after each round completes, a registered PURE predicate decides
+// whether to run another round (a fresh phase appended after this one, with the same
+// tasks under round-suffixed ids) or stop. Hard-capped at `maxRounds`.
+//
+// REPLAY-DETERMINISM: the predicate is a pure function of RECORDED round results +
+// recorded usage — no IO/clock/random in its context by construction. The engine
+// RECORDS each decision as a `loop-control` state node, so a replay walks the recorded
+// round sequence; re-running the predicate is a verification cross-check, not the
+// source of truth. Predicates are NAMED (registry refs), never inline closures —
+// closures cannot be serialized into state or re-evaluated byte-identically on replay.
+//
+// The materialization (cloning tasks, appending phases, recording the loop-control
+// node) lives in the orchestrator (maybeExpandLoop), which owns writeTaskFiles + the
+// plan pipeline; THIS module is just the pure registry + the STATIC expansion bound.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLoopPredicate = registerLoopPredicate;
+exports.getLoopPredicate = getLoopPredicate;
+exports.hasLoopPredicate = hasLoopPredicate;
+exports.maxLoopExpansion = maxLoopExpansion;
+const REGISTRY = new Map();
+/** Register a named pure loop predicate (apps register theirs at load; CW ships a few
+ *  built-ins below). Re-registering a name overwrites it. */
+function registerLoopPredicate(name, fn) {
+    REGISTRY.set(name, fn);
+}
+function getLoopPredicate(name) {
+    return REGISTRY.get(name);
+}
+function hasLoopPredicate(name) {
+    return REGISTRY.has(name);
+}
+// ---- Built-in predicates ---------------------------------------------------------
+/** Stop once a round produced no findings (a convergence loop: keep going while the
+ *  agent still reports findings; stop when a round comes back empty). */
+registerLoopPredicate("no-new-findings", (ctx) => {
+    const empty = ctx.roundResults.every((r) => !r || !Array.isArray(r.findings) || r.findings.length === 0);
+    return empty
+        ? { done: true, reason: "no-new-findings: the latest round produced no findings" }
+        : { done: false, reason: "no-new-findings: the latest round still has findings" };
+});
+/** Always stop after the first round (a degenerate loop ≈ a normal phase; useful as a
+ *  default / for tests). */
+registerLoopPredicate("single-round", () => ({ done: true, reason: "single-round: stop after one round" }));
+/** Static worst-case number of EXTRA tasks a fully-expanded run could mint, derived
+ *  purely from the workflow DECLARATION (every loop origin phase contributes
+ *  (maxRounds-1) × its round-1 task count). Used to keep the drive's iteration bound
+ *  safe as tasks grow, WITHOUT reading any runtime result — so the bound is itself
+ *  replay-stable and the loop is provably bounded. Zero when there are no loop phases. */
+function maxLoopExpansion(run) {
+    let extra = 0;
+    for (const phase of run.phases) {
+        if (phase.loop && typeof phase.loop.maxRounds === "number" && phase.loop.maxRounds > 1) {
+            const templateTaskCount = phase.taskIds.length;
+            extra += (phase.loop.maxRounds - 1) * templateTaskCount;
+        }
+    }
+    return extra;
+}

package/dist/onramp.js

@@ -131,6 +131,12 @@ function buildDoctorOnramp(options = {}) {
                         command: "cw demo tamper",
                         reason: "Shows the core trust check without an agent or a repo."
                     },
+                    {
+                        id: "demo-bundle",
+                        title: "Prove portable checks",
+                        command: "cw demo bundle",
+                        reason: "Shows the bundle proof in one step — create, check, forge, detect. No agent needed."
+                    },
                     {
                         id: "setup",
                         title: "Check setup",
@@ -163,6 +169,25 @@ function buildDoctorOnramp(options = {}) {
                     }
                 ]
             },
+            {
+                id: "no-agent",
+                title: "No Agent?",
+                summary: "The demo steps above need no agent. A real report needs one. Pick and install one agent before the next step.",
+                actions: [
+                    {
+                        id: "agent-claude",
+                        title: "Claude Code (npm)",
+                        command: "npm install -g @anthropic-ai/claude-code",
+                        reason: "First-party Claude Code tool; CW works with Claude Code, Codex, Gemini CLI, and OpenCode."
+                    },
+                    {
+                        id: "agent-check",
+                        title: "Check agent setup",
+                        command: "cw doctor",
+                        reason: "Doctor names missing agent or setup trouble and tells you what to fix."
+                    }
+                ]
+            },
             {
                 id: "change-loop",
                 title: "Change Loop",

package/dist/orchestrator/lifecycle-operations.js

@@ -27,6 +27,8 @@ const harness_1 = require("../harness");
 const workflow_app_framework_1 = require("../workflow-app-framework");
 const workflow_api_1 = require("../workflow-api");
 const observability_1 = require("../observability");
+const compare_1 = require("../compare");
+const loop_expansion_1 = require("../loop-expansion");
 const dispatch_1 = require("../dispatch");
 const verifier_1 = require("../verifier");
 const trust_audit_1 = require("../trust-audit");
@@ -53,7 +55,13 @@ function plan(appRecord, options) {
             inputs[declared.name] = declared.default ?? "";
     }
     const cwd = node_path_1.default.resolve(String(inputs.cwd || inputs.repo || process.cwd()));
-    const runId = createRunId(workflow.id);
+    // A caller (e.g. an inline sub-workflow task) may inject a DETERMINISTIC run id so
+    // the child run id is reproducible across re-runs; otherwise mint one. `runId` is
+    // never a declared workflow input, so strip it from inputs to keep run.inputs (and
+    // the digests derived from it) clean — POLA for every normal plan.
+    const injectedRunId = typeof options.runId === "string" && options.runId.trim() ? options.runId.trim() : undefined;
+    delete inputs.runId;
+    const runId = injectedRunId || createRunId(workflow.id);
     const runDir = node_path_1.default.join(cwd, ".cw", "runs", runId);
     const paths = (0, state_1.createRunPaths)(runDir);
     (0, state_1.ensureRunDirs)(paths);
@@ -79,7 +87,10 @@ function plan(appRecord, options) {
             status: "pending",
             taskIds: phase.tasks.map((task) => task.id),
             // parallel() DSL: the drive loop reads this to size its concurrent round.
-            ...(phase.mode ? { mode: phase.mode } : {})
+            ...(phase.mode ? { mode: phase.mode } : {}),
+            // loop() DSL: the ORIGIN phase carries the loop spec + round 1; the expander
+            // appends round-2+ phases after each round (loop-expansion / maybeExpandLoop).
+            ...(phase.loop ? { loop: phase.loop, loopRound: 1 } : {})
         })),
         tasks,
         dispatches: [],
@@ -323,6 +334,9 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         }
         run.loopStage = "observe";
         (0, dispatch_1.updatePhaseStatuses)(run);
+        // Bounded dynamic loops: after a round's tasks complete, evaluate the predicate
+        // and either append the next round or mark the loop done (no-op for non-loop runs).
+        maybeExpandLoop(run);
         (0, verifier_1.validateRunGates)(run);
         (0, commit_1.commitState)(run, `worker:${workerId}:result`);
         (0, report_1.writeReport)(run);
@@ -410,6 +424,120 @@ function validateInputs(workflow, inputs) {
         }
     }
 }
+/** Bounded dynamic loop expansion. After a worker result is recorded: if the just-
+ *  completed phase is the LATEST round of a loop whose origin is not yet done, evaluate
+ *  the registered predicate over the round's recorded results and either append the
+ *  next round (clone the round-1 template tasks into a fresh phase, materialized like
+ *  plan() does) or mark the loop done. One deterministic `loop-control` node is recorded
+ *  per round boundary — the replay source of truth. No-op when the run has no loop
+ *  phases (POLA). Expands at most ONE loop boundary per call; the next accept handles
+ *  the next. Bounded: a loop never exceeds `maxRounds` (fail-closed); an unregistered
+ *  predicate stops the loop rather than spinning. */
+function maybeExpandLoop(run) {
+    for (const phase of [...run.phases]) {
+        const originId = phase.loop ? phase.id : phase.loopOrigin;
+        if (!originId)
+            continue;
+        const origin = run.phases.find((p) => p.id === originId);
+        if (!origin || !origin.loop || origin.loopDone)
+            continue;
+        // Act only from the LATEST round phase of this loop.
+        const loopPhases = run.phases.filter((p) => p.id === originId || p.loopOrigin === originId);
+        const latest = loopPhases.reduce((a, b) => ((b.loopRound || 1) >= (a.loopRound || 1) ? b : a));
+        if (phase.id !== latest.id)
+            continue;
+        const roundTasks = run.tasks.filter((t) => latest.taskIds.includes(t.id));
+        if (roundTasks.length === 0 || !roundTasks.every((t) => t.status === "completed"))
+            continue;
+        const round = latest.loopRound || 1;
+        const ordered = (tasks) => tasks.slice().sort((a, b) => (0, compare_1.compareBytes)(a.id, b.id)).map((t) => t.result);
+        const roundResults = ordered(roundTasks);
+        const allLoopTasks = run.tasks.filter((t) => t.status === "completed" && loopPhases.some((p) => p.taskIds.includes(t.id)));
+        const allResults = ordered(allLoopTasks);
+        const ctx = { round, roundResults, allResults, usageTotals: (0, observability_1.deriveUsageTotals)(run).totals, inputs: run.inputs };
+        const until = origin.loop.until;
+        let decision;
+        if (until.kind === "budget-target") {
+            // Budget-aware scaling: keep spawning rounds while RECORDED (attested-only) usage
+            // stays under the target. Composes with the fail-closed cap (limits.tokenBudget),
+            // which the drive enforces before each spawn and which remains the absolute
+            // backstop — whichever fires first wins, and the cap can never be overshot.
+            const spent = ctx.usageTotals.totalTokens;
+            decision = { done: spent >= until.target, reason: `budget-target: ${spent}/${until.target} recorded tokens` };
+        }
+        else {
+            const predicate = (0, loop_expansion_1.getLoopPredicate)(until.ref);
+            decision = predicate
+                ? predicate(ctx)
+                : { done: true, reason: `loop predicate "${until.ref}" not registered — stopping fail-closed` };
+        }
+        const atCap = round >= origin.loop.maxRounds;
+        const done = decision.done || atCap;
+        // Record the decision under a deterministic id (the replay source of truth).
+        (0, state_node_1.appendRunNode)(run, (0, state_node_1.createStateNode)({
+            id: `${run.id}:loop-control:${originId}:r${round}`,
+            kind: "loop-control",
+            status: "completed",
+            loopStage: "adjust",
+            outputs: { round, done, atCap, reason: decision.reason },
+            metadata: { originPhaseId: originId, until: until.kind === "predicate" ? until.ref : `budget-target:${until.target}`, round, done, atCap, reason: decision.reason }
+        }));
+        if (done) {
+            origin.loopDone = true;
+            return;
+        }
+        // Expand: clone the ROUND-1 template tasks into a fresh phase appended right after.
+        const nextRound = round + 1;
+        const nextPhaseName = `${origin.name} (round ${nextRound})`;
+        const templateTasks = run.tasks.filter((t) => origin.taskIds.includes(t.id));
+        const newTasks = templateTasks.map((t) => ({
+            id: `${t.id.replace(/@r\d+$/, "")}@r${nextRound}`,
+            kind: t.kind,
+            phase: nextPhaseName,
+            status: "pending",
+            requiresEvidence: t.requiresEvidence,
+            prompt: t.prompt,
+            taskPath: "",
+            resultPath: "",
+            loopStage: "interpret",
+            loopRound: nextRound,
+            ...(t.sandboxProfileId ? { sandboxProfileId: t.sandboxProfileId } : {}),
+            ...(t.label ? { label: t.label } : {}),
+            ...(t.model ? { model: t.model } : {}),
+            ...(t.agentType ? { agentType: t.agentType } : {}),
+            ...(t.schema ? { schema: t.schema } : {})
+        }));
+        const nextPhase = {
+            id: `${originId}@r${nextRound}`,
+            name: nextPhaseName,
+            status: "pending",
+            taskIds: newTasks.map((t) => t.id),
+            loopOrigin: originId,
+            loopRound: nextRound,
+            ...(origin.mode ? { mode: origin.mode } : {})
+        };
+        const insertAt = run.phases.findIndex((p) => p.id === latest.id);
+        run.phases.splice(insertAt + 1, 0, nextPhase);
+        run.tasks.push(...newTasks);
+        // Materialize: task files + a plan-stage contract node per new task (mirrors plan()).
+        (0, harness_1.writeTaskFiles)(run);
+        const contractId = run.contracts && run.contracts[0] ? run.contracts[0].id : undefined;
+        const inputNodeId = `${run.id}:input`;
+        const pipeline = (0, pipeline_runner_1.createPipelineRunner)({ contractId, persist: false });
+        for (const t of newTasks) {
+            const result = pipeline.runPipelineStage(run, "plan", inputNodeId, {
+                outputNodeId: `${run.id}:task:${t.id}`,
+                outputStatus: "pending",
+                loopStage: "interpret",
+                artifacts: [{ id: "task", kind: "markdown", path: t.taskPath }],
+                metadata: { workflowId: run.workflow.id, taskId: t.id, phase: t.phase, taskKind: t.kind, requiresEvidence: t.requiresEvidence, sandboxProfileId: t.sandboxProfileId }
+            });
+            t.stateNodeId = result.outputNodeId;
+        }
+        (0, dispatch_1.updatePhaseStatuses)(run);
+        return;
+    }
+}
 function flattenTasks(workflow, inputs) {
     const seen = new Set();
     const tasks = [];
@@ -437,7 +565,10 @@ function flattenTasks(workflow, inputs) {
                 ...(task.label ? { label: task.label } : {}),
                 ...(task.model ? { model: task.model } : {}),
                 ...(task.agentType ? { agentType: task.agentType } : {}),
-                ...(task.resultCache ? { resultCache: task.resultCache } : {})
+                ...(task.resultCache ? { resultCache: task.resultCache } : {}),
+                ...(task.subWorkflow ? { subWorkflow: task.subWorkflow } : {}),
+                // A loop phase's tasks are round 1 of the loop; the expander clones them.
+                ...(phase.loop ? { loopRound: 1 } : {})
             });
         }
     }