bullswarm 0.13.1 → 0.13.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # bullswarm changelog
 
+## 0.13.2 — user text is never a template
+
+- `workflow goal` failed before anything ran when the goal text quoted
+  something shaped like a template ref (`{{outputs.x.data.field}}` in a goal
+  *about* templates): the goal was spliced into the scout prompt and the
+  workflow validator rejected the ref as unresolvable — "autonomous workflow
+  invalid (nothing ran)". The goal is now a declared input (`inputs.goal`)
+  inserted at render time, so nothing in user text is ever parsed.
+- A grammar-valid ref with nothing behind it no longer kills the action at
+  render time. It is left literally in the prompt and reported as
+  `template.unresolved_ref { actionId, ref }`; planner-authored prompts may
+  quote refs as text, and a worker can usually still act on the literal.
+  `renderTemplate(str, scope, { strict: true })` keeps the old hard failure.
+
 ## 0.13.1 — a repaired verify counts as verification of its repair
 
 - `completionEvidenceGaps` accepted a verify as evidence for the latest worker

package/docs/claude-dynamic-workflow-mechanics.md

@@ -216,7 +216,15 @@ from `docs/experiments/2026-08-29-ultracode-vs-bullswarm.md`, never projected.
   policy and race on the barrel file." The policy it cites was a caution line
   in the planner prompt; a concurrency cap of 8 was available and unused.
   Discovery alone then ran 458 s. (Final numbers: experiment report.)
-- (comparison fixture final results: pending)
+- Final comparison on the 6-module fixture (experiment report for the full
+  tables). Goal 2 (known items): Claude 58 min, 24 agents, 0 orchestrator
+  turns during execution, parallelism 3.1 · bullswarm 0.11.1 41 min, 3 planner
+  turns (27 %), max 6 concurrent, parallelism 2.74 · bullswarm 0.12.1 48 min of
+  execution after a 3 h quota wait it survived, 4 planner turns (two caused by
+  the bug fixed in 0.13.1), max 7 concurrent, one live repair round. Goal 3
+  (discovered items) on 0.13.1: 28 min 42 s, **one planner turn**, the runtime
+  recorded `complete` itself, exactly the three unguarded modules fixed,
+  75/75 tests.
 
 ## 3. bullswarm today, mechanic by mechanic
 
@@ -316,7 +324,7 @@ author and the `Workflow` runtime.
    sees `outputs.scout.ok=false` with the reason, and a run where only the
    scout succeeded is `blocked`, never "delivered".
 
-8. **Program-level completion** (0.13.0, unreleased at the time of writing) —
+8. **Program-level completion** (0.13.0) —
    `completion: { when: "all-actions-ok", reason }` on a program. Claude's
    script simply returns when its code is done; bullswarm still spent a final
    planner turn (110–250 s measured) to say `complete` after a clean run. Now
@@ -324,10 +332,24 @@ author and the `Workflow` runtime.
    never below the completion policy) and consults the planner only when
    something failed. With 0.12.0's repair-in-program this makes a clean run
    **one planner turn**: compile, execute, done — Claude's "0 orchestrator turns
-   during execution" for the passing case.
+   during execution" for the passing case. **[OBSERVED]** goal-3 run
+   `wf-mtdkvx0k` (0.13.1): the planner attached the predicate on its own, the
+   runtime emitted `decision.auto_completed` (`source: program-completion`),
+   one planner process for the whole 28 min run.
 9. **Rate limits are waited for** (0.12.1): a burst-gated provider parks the
    dispatch in `waiting_for_quota` until the window resets instead of failing
    the run in 4 s, which is what the first 0.12.0 comparison launch did.
+   **[OBSERVED]** goal-2 run `wf-mtdcghw0`: parked at 95 % for 3 h 2 min,
+   dispatched 17 s after the provider reset.
+10. **A repair is verified by its verify's re-run** (0.13.1). The executor's
+   repair loop creates `<verify>-repair-N` *depending on* the verify, then runs
+   the verify again; the completion-evidence check only followed
+   `verify.dependsOn` and so never saw a repair as verified. **[OBSERVED]** on
+   `wf-mtdcghw0`: a clean `complete` rejected, three more planner turns
+   (~11 min) to re-prove a passed re-verify. In Claude's model this bug cannot
+   exist — the script's `while (!ok)` loop *is* the evidence — which is the
+   general lesson: every piece of control flow bullswarm moves from planner
+   into runtime needs its evidence rule moved with it.
 
 **Honest limitation.** `itemsFrom` removes the planner *turn*, not the stage
 *barrier*: a verify depending on a data-driven fan-out waits for all items,

package/docs/experiments/2026-08-29-ultracode-vs-bullswarm.md

@@ -325,7 +325,7 @@ together with its instructions. (2) The remediation round spent two of its
 three fixes on "non-blocking" nits from verifiers that had returned
 `ok:true`; 0.12.0's doctrine tells the planner those are informational.
 
-### bullswarm 0.12.0 (installed binary) — same goal, fresh copy `g2-bs-v3`
+### bullswarm 0.12.0 → 0.12.1 (installed binary) — same goal, fresh copy `g2-bs-v3`
 
 **First launch, 19:09:48 Z, installed 0.12.0 — failed in 4 s.** Both the
 scout and the orchestrator were `failed_terminal` with `no eligible pool`
@@ -393,27 +393,73 @@ Take the bug and the dependency slip out and this run is ~29 min of execution wi
 The originally planned 0.10.9 goal-2 run was dropped at the user's request
 (2026-08-29): the installed latest is the only baseline that matters.
 
+### bullswarm 0.13.1 (installed binary) — goal 3, discovery-shaped, fresh copy `g3-bs-v3`
+
+Goal 3 was written to exercise what goal 2 cannot: an **unknown item list**.
+"Some — not all — of the exported functions accept a wrong-typed argument and
+misbehave. Find out which modules actually have this problem (probe every
+export; keep only the misbehaving modules), then for EACH affected module only:
+add top-of-function argument validation (TypeError naming function, parameter,
+expected type; behaviour for valid input unchanged) and `tests/<module>.guards.test.js`
+(node:test, one test per guard). Do not modify existing tests or touch modules
+that already validate. Finish with `npm test` passing and report exactly which
+modules you changed and which you left alone, with evidence." Same fixture
+family, same single pool (`claude-opus-5`), 0.13.1 installed after the goal-2
+run ended so the binary each run used is unambiguous. Run `wf-mtdkvx0k-c40480`,
+23:23:56 → 23:52:41 Z.
+
+| when (Z) | what |
+|---|---|
+| 23:23:59 → 23:28:05 | scout (246 s): probed all six modules; found exactly three misbehaving (csv, slugify, semver) with per-function evidence |
+| 23:28:05 → 23:32:59 | planner turn 1 (294 s): **one 9-action program with `completion: {when: "all-actions-ok"}`** — `fix-{csv,slugify,semver}` + `audit-remaining` (independently re-probe duration/intervals/lru/index) in parallel, each with its own `verify-*` carrying `repair {maxRounds: 2}`, then `verify-suite` |
+| 23:32:59 | 4 workers started in the same second |
+| 23:37:04 → 23:39:31 | each `verify-<m>` started as its own fix finished (pipeline, no barrier) |
+| 23:42:44 → 23:52:41 | `verify-suite` (597 s) ok:true |
+| 23:52:41 | **runtime recorded `complete` itself** — `decision.auto_completed`, `source: program-completion`; no second planner process |
+
+| metric | value |
+|---|---|
+| wall | **28 min 42 s** (1 722 s), no quota wait |
+| planner turns / seconds | **1 / 294 s (17 %)** |
+| dispatches / max concurrent / parallelism | 11 / 4 / 1.82 (four items → four chains; width was item-bound, cap 8 unused) |
+| repairs | 0 needed (every verify ok:true first time) |
+| actions by source | planner 9; completion recorded by the runtime |
+| result (audit-fixture.sh + `npm test`) | `src/csv.js`, `src/semver.js`, `src/slugify.js` modified (24/9/9 non-comment lines); duration/intervals/lru/index untouched; 3 new `*.guards.test.js`; existing tests byte-identical; **75/75** (52 + 23) |
+| tokens (estimate) | 51 422 |
+
+Two notes. First, the planner did **not** use `fanout.itemsFrom` — it inlined
+the three modules the scout had already named and gave the "not yet confirmed"
+half of the repo to one `audit-remaining` worker. That is the right call (the
+scout had done the discovery), and it is exactly what Claude's author does when
+it discovers the list inline before writing the script; `itemsFrom` stays the
+tool for lists that only exist after a worker runs. Second, `verify-others` and
+`verify-suite` both flagged `lru` throwing `RangeError` rather than `TypeError`
+for a wrong-typed capacity and both correctly treated it as informational (the
+existing test pins `RangeError`): passing-with-nits produced no extra work,
+as the doctrine intends.
+
 ## Behaviour differences observed
 
 Same goal, same fixture, same model (Opus for every worker and for bullswarm's
 planner; the Claude session's author was Opus too). Read left to right: what
 Claude did, what bullswarm 0.11.1 did on the identical run, and what 0.12.x
-now does about it (built and unit-tested; the live re-run below is the
-confirmation).
+now does about it. Every 0.12.x/0.13.x cell is unit-tested; cells marked
+**observed** were also seen live in the `g2-bs-v3` (0.12.1) and `g3-bs-v3`
+(0.13.1) runs above.
 
-| Dimension | Claude Code `Workflow` (ultracode) — observed | bullswarm 0.11.1 — observed | bullswarm 0.12.0 / 0.12.1 — built |
+| Dimension | Claude Code `Workflow` (ultracode) — observed | bullswarm 0.11.1 — observed | bullswarm 0.12.1 / 0.13.1 |
 | --- | --- | --- | --- |
-| Who plans, and when | The session author read every file and ran the tests inline (4 min), then wrote **one script** (23 k chars, 5 `agent()` sites). **0 orchestrator turns during the 48 min 51 s of execution.** | The planner compiled the **whole 14-action graph in one decision** (253 s) — but blind: goal text + cwd only, no repo survey, no worker output text in its context. Consulted **3 times** (253 s, 304 s, 110 s) = **27 % of wall**. | Read-only `scout` action before the planner; `outputExcerpt` of every finished action in the planner context; prompt reframed as "compile the goal into a PROGRAM"; planner told it is consulted only at the program boundary. |
+| Who plans, and when | The session author read every file and ran the tests inline (4 min), then wrote **one script** (23 k chars, 5 `agent()` sites). **0 orchestrator turns during the 48 min 51 s of execution.** | The planner compiled the **whole 14-action graph in one decision** (253 s) — but blind: goal text + cwd only, no repo survey, no worker output text in its context. Consulted **3 times** (253 s, 304 s, 110 s) = **27 % of wall**. | Read-only `scout` action before the planner; `outputExcerpt` of every finished action in the planner context; prompt reframed as "compile the goal into a PROGRAM"; planner told it is consulted only at the program boundary. **Observed:** both runs compiled the whole program on turn 1 from the scout's survey; goal 3 ran on **one planner turn** (0.13.0 self-completion). |
 | Item discovery | `pipeline(MODULES, probe, author, verify, fix-loop)` over a known list; when a list is unknown Claude discovers it inline *before* writing the script. | Goal named the six modules → inlined them. Nothing to discover here. | `fanout.itemsFrom: "outputs.<discovery>.outFile"` resolved at run time (+ one bounded read-only extraction retry), so an unknown item count never costs a planner turn. |
 | Parallel width and overlap | **6 concurrent** (= six items, cap 8), mean parallelism 3.1. Per-item pipeline: author-B starts the second probe-B ends; no barriers. | **6 concurrent**, mean parallelism 2.74. Ready-set scheduler: each `verify-<m>` started the second its own `module-<m>` finished; `docs-index` waited for all six by design. | Unchanged for known items. Limitation stays: a verify on a *discovered* fan-out waits for all items (no per-item chain inside a fan-out yet). |
-| Verify → fix | Fix loops **pre-authored in code** (`while (!verdict.ok && rounds < N)`): slugify ×2, intervals ×1, all inside the script; 9 verifies, 3 fixes, 0 planner involvement. | A failed/blocked verify came back to the **planner** (turn 2, 304 s), which authored `slugify-recheck` + `verify-slugify-2`. Round trip ≈ 5 min before the fix even started. | `verify.repair { prompt, maxRounds 1–3 }` — the executor runs `<verify>-repair-<n>` with the concerns verbatim and re-runs the same verify; only still-failing verifies return to the planner. |
-| Passing verifies with nits | Schema-forced `{ok, issues}`; the script fixes only when `!ok`. Nits on passing modules were ignored. | Planner spent **2 of 3 remediation fixes** (`polish-semver`, `polish-lru`) on "non-blocking" notes from verifiers that had returned `ok:true` — an extra ~10 min program round. | Doctrine line: an `ok:true` verify is accepted; its concerns are informational. |
-| Robustness to content | Prompts are JS strings; the runtime substitutes nothing. A parse error in the *script* was caught by the harness and corrected inline in 94 s. | The template renderer parsed **any** `{{…}}` — in a planner prompt *and* in the review artifact it appended. `verify-slugify` died at render time with **0 attempts**, blocked `verify-suite`, cost a planner round, and the fix **rewrote fixture source** (JSDoc) to dodge the bug. | Only a known root + dotted identifiers is a template ref; other double braces are text. `verify` appends the reviewed artifact verbatim, never rendered. |
-| Provider rate limits | Agents retry on API errors; a terminal error resolves the agent to `null`, the script keeps going. The session waits. | Pool burst-gated (5h window 91 %) → the whole run **failed in 4 s** with `no eligible pool`, no reset time named (first 0.12.0 launch, 19:09 Z). | 0.12.1: `waiting_for_quota` stage, meter re-read every 60 s, continue when the window resets; fail only after reset + 10 min grace, naming pool / usage / reset time. |
+| Verify → fix | Fix loops **pre-authored in code** (`while (!verdict.ok && rounds < N)`): slugify ×2, intervals ×1, all inside the script; 9 verifies, 3 fixes, 0 planner involvement. | A failed/blocked verify came back to the **planner** (turn 2, 304 s), which authored `slugify-recheck` + `verify-slugify-2`. Round trip ≈ 5 min before the fix even started. | `verify.repair { prompt, maxRounds 1–3 }` — the executor runs `<verify>-repair-<n>` with the concerns verbatim and re-runs the same verify; only still-failing verifies return to the planner. **Observed** (goal 2): `verify-full-delivery` failed on a missing `docs/README.md`, the repair wrote it and the re-verify passed, ~9 min, no planner turn. Exposed the 0.13.1 bug (repair never counted as verified). |
+| Passing verifies with nits | Schema-forced `{ok, issues}`; the script fixes only when `!ok`. Nits on passing modules were ignored. | Planner spent **2 of 3 remediation fixes** (`polish-semver`, `polish-lru`) on "non-blocking" notes from verifiers that had returned `ok:true` — an extra ~10 min program round. | Doctrine line: an `ok:true` verify is accepted; its concerns are informational. **Observed:** 6 + 4 passing verifies with concerns in the two runs, zero polish actions. |
+| Robustness to content | Prompts are JS strings; the runtime substitutes nothing. A parse error in the *script* was caught by the harness and corrected inline in 94 s. | The template renderer parsed **any** `{{…}}` — in a planner prompt *and* in the review artifact it appended. `verify-slugify` died at render time with **0 attempts**, blocked `verify-suite`, cost a planner round, and the fix **rewrote fixture source** (JSDoc) to dodge the bug. | Only a known root + dotted identifiers is a template ref; other double braces are text. `verify` appends the reviewed artifact verbatim, never rendered. **Observed:** same pristine `slugify.js` with `{{maxLength?: number}}`, `verify-slugify` ran and passed. |
+| Provider rate limits | Agents retry on API errors; a terminal error resolves the agent to `null`, the script keeps going. The session waits. | Pool burst-gated (5h window 91 %) → the whole run **failed in 4 s** with `no eligible pool`, no reset time named (first 0.12.0 launch, 19:09 Z). | 0.12.1: `waiting_for_quota` stage, meter re-read every 60 s, continue when the window resets; fail only after reset + 10 min grace, naming pool / usage / reset time. **Observed:** waited 3 h 2 min at 95 %, resumed 17 s after the reset, no operator action. |
 | Structured worker output | `schema:` forces a `StructuredOutput` tool call; mismatches retry at the tool layer, so the script never parses prose. | Prose "content gate" (`looksLikeWork`); a bare JSON array answer was rejected as an "announcement"; the verify verdict is the only structured channel. | Content gate accepts JSON; `parseJsonArray` prefers the trailing array; one extraction action when discovery output has no array. A general `outputSchema` on run actions is still open. |
 | Failure semantics | In code: `parallel()` never rejects, a throwing stage drops its item to `null`, `.filter(Boolean)`. | Runtime `onError: continue` per step; failed dependencies block dependents; blocked graph → planner. | Same, plus: a failed scout is non-fatal; fan-out `ok` is a boolean so dependents can wait on a whole fan-out. |
-| Outcome quality (audits, read-only) | 168/168 tests (52 + 116 new); existing tests byte-identical; `src` comment-only; every deliverable present. | 130/130 tests (52 + 78 new); existing tests byte-identical; `src` comment-only; every deliverable present. | — (re-run below) |
-| Time and agents | 58 min end to end; 24 agents. | 41 min end to end; 22 dispatches. Faster because it wrote fewer tests per module (11–15 vs 16–24) and skipped Claude's probe stage — not because it orchestrated better. | — |
+| Outcome quality (audits, read-only) | 168/168 tests (52 + 116 new); existing tests byte-identical; `src` comment-only; every deliverable present. | 130/130 tests (52 + 78 new); existing tests byte-identical; `src` comment-only; every deliverable present. | Goal 2 on 0.12.1: 120/120 (52 + 68); existing tests byte-identical; `src` comment-only; every deliverable present. Goal 3 on 0.13.1: exactly the three unguarded modules changed, 75/75. |
+| Time and agents | 58 min end to end; 24 agents. | 41 min end to end; 22 dispatches. Faster because it wrote fewer tests per module (11–15 vs 16–24) and skipped Claude's probe stage — not because it orchestrated better. | Goal 2 on 0.12.1: 48 min of execution (+3 h quota wait), 22 dispatches, max 7 concurrent — ~11 min of it spent on the 0.13.1 bug and ~9 min on one repair round. Goal 3 on 0.13.1: 28 min 42 s, 11 dispatches, 1 planner turn. |
 
 The short version: after 0.11.x the *shape* already matched (one decision =
 whole graph, six in parallel, per-item verify overlap). What still separated
@@ -425,8 +471,9 @@ the runtime.
 
 ## What to change in bullswarm
 
-**Shipped in this cycle** (0.12.0 `c1b71a8`, 0.12.1 `beeed94`; all covered by
-unit tests, 295/295):
+**Shipped in this cycle** (0.12.0 `c1b71a8`, 0.12.1 `beeed94`, 0.13.0
+`6e5f620`, 0.13.1 `1bf0840` — all released to npm and installed; unit suite
+299/299):
 
 1. Orchestrator as **compiler**: prompt reframed; planner consulted only at the
    program boundary; `programFeatures: ['itemsFrom', 'repair']` advertised.
@@ -442,11 +489,18 @@ unit tests, 295/295):
 8. Template refs are grammar-checked; review artifacts are never rendered.
 9. Doctrine: `ok:true` verifies are accepted; concerns are informational.
 10. Burst-gated providers are waited for (`waiting_for_quota`), not failed.
-11. **Program-level completion predicate** (`0bcfd21`, 0.13.0 unreleased while
-    the 0.12.1 observation run is in flight): `completion: { when:
+11. **Program-level completion predicate** (0.13.0): `completion: { when:
     "all-actions-ok", reason }` lets a clean program record its own `complete`
-    decision — no final planner turn (110 s here) just to say so. Anything
-    failing still returns to the planner.
+    decision — no final planner turn just to say so. Anything failing still
+    returns to the planner. **Observed** on goal 3: the planner attached it
+    unprompted, the runtime recorded `complete` (`source: program-completion`)
+    at 23:52:41 Z, one planner turn for the whole run.
+12. **A repaired verify counts as verification of its repair** (0.13.1): the
+    completion-evidence check only followed `verify.dependsOn`; a repair action
+    depends on its verify (reverse edge), so after a clean repair round every
+    `complete` was rejected as "missing a successful verification of latest
+    worker <verify>-repair-1" — observed on goal 2 (three extra planner turns,
+    ~11 min) and it would have blocked item 11 in the same situation.
 
 **Still open, in priority order** (each is a measured gap, not a guess):
 
@@ -467,3 +521,14 @@ unit tests, 295/295):
    whatever the planner wrote. A default skeptic framing in the verify wrapper
    is cheap and would have caught nothing extra here — listed for parity, not
    urgency.
+5. **Dependency slips by the planner.** Goal 2's `write-docs-index` was
+   compiled with `dependsOn: []` although it reads the six `docs/<m>.md` files
+   the builders create; it ran first and found nothing. The verify + repair
+   loop recovered it (~9 min). Claude has the same failure class (a mis-ordered
+   `pipeline` stage) and the same recovery. A doctrine line — "an action that
+   reads another proposed action's deliverable must depend on it" — is free;
+   a deterministic check is not possible without declared outputs, which would
+   be a small schema addition (`produces: [paths]`).
+6. **Record `completion` on the decision.** The planner artifact carries the
+   predicate but `state.decisions[]` does not, so `watch`/metrics cannot show
+   that a program declared itself self-completing until it does. One field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/src/workflow/goal.js

@@ -122,7 +122,17 @@ export function buildGoalWorkflow({
         requireSuccessfulVerification: true,
       },
     },
-    inputs: {},
+    // The goal is user text. It is declared as an input and inserted into
+    // prompts at render time ({{inputs.goal}}), so anything in it that looks
+    // like a template ref — a goal about templates quoting
+    // `{{outputs.x.data.field}}`, say — is inserted verbatim, never resolved.
+    inputs: {
+      goal: {
+        description: 'The user goal, verbatim.',
+        required: true,
+        default: goal.trim(),
+      },
+    },
     settings: {
       concurrency,
       retryAttempts,
@@ -141,7 +151,7 @@ export function buildGoalWorkflow({
         type: 'run',
         lane: 'analyze',
         addDir: targetDir,
-        prompt: scoutPrompt(goal.trim(), targetDir),
+        prompt: scoutPrompt('{{inputs.goal}}', targetDir),
       }] : []), {
         id: 'orchestrator',
         type: 'decide',

package/src/workflow/runtime.js

@@ -878,6 +878,13 @@ export class WorkflowRuntime {
     }
   }
 
+  /** renderDeep options that turn an unresolved ref into a visible event. */
+  renderOpts(actionId) {
+    return {
+      onUnresolved: (ref) => this.emit('template.unresolved_ref', { actionId, ref }),
+    };
+  }
+
   async runSingle(step, scope, opts = {}) {
     this.enforceRequiredInputs(step.id);
     const rendered = renderDeep(
@@ -888,6 +895,7 @@ export class WorkflowRuntime {
         taskFile: step.taskFile,
       },
       scope,
+      this.renderOpts(step.id),
     );
     const taskText = rendered.prompt
       ?? readFileSync(rendered.taskFile, 'utf8');
@@ -965,7 +973,7 @@ export class WorkflowRuntime {
       lane: step.lane ?? 'analyze',
       addDir: step.addDir,
       prompt: reviewInstructions,
-    }, scope);
+    }, scope, this.renderOpts(step.id));
     // A custom prompt changes the review instructions, never the review
     // input. Always append the resolved artifact so the skeptic receives
     // the thing it is meant to judge.
@@ -1160,7 +1168,7 @@ export class WorkflowRuntime {
     const rendered = renderDeep({
       prompt: step.prompt ?? 'Judge whether the workflow has enough evidence to finish.',
       addDir: step.addDir,
-    }, scope);
+    }, scope, this.renderOpts(step.id));
     const taskText = [
       rendered.prompt,
       '',
@@ -1328,7 +1336,7 @@ export class WorkflowRuntime {
         const itemScope = { ...scope, item };
         let template;
         try {
-          template = renderDeep(step.stepTemplate, itemScope);
+          template = renderDeep(step.stepTemplate, itemScope, this.renderOpts(`${step.id}[${i}]`));
         } catch (err) {
           const itemAction = this.ensureAction(step, { ...opts, item, itemIndex: i });
           itemAction.status = 'failed_terminal';

package/src/workflow/template.js

@@ -32,25 +32,35 @@ export function isTemplateRef(ref) {
  * {{runId}}, {{wfDir}}. Non-string values are JSON-stringified. Double-brace
  * text that is not a ref (see isTemplateRef) is returned untouched.
  */
-export function renderTemplate(str, scope) {
+export function renderTemplate(str, scope, opts = {}) {
   if (typeof str !== 'string') return str;
   return str.replace(TEMPLATE_TOKEN_RE, (match, ref) => {
     if (!isTemplateRef(ref)) return match;
     const v = getPath(scope, ref.trim());
     if (v === undefined) {
-      throw new Error(`template ref "{{${ref.trim()}}}" unresolved at render time`);
+      // A grammar-valid ref with nothing behind it. Planner-authored prompts
+      // legitimately quote refs as text (a goal *about* templates does), and a
+      // worker can usually still act on the literal — so this is reported,
+      // never fatal. Callers that want the old hard failure pass strict:true.
+      // (Observed 2026-08-29: a goal quoting `{{outputs.x.data.field}}` failed
+      // the whole run at validation with "nothing ran".)
+      if (opts.strict === true) {
+        throw new Error(`template ref "{{${ref.trim()}}}" unresolved at render time`);
+      }
+      if (typeof opts.onUnresolved === 'function') opts.onUnresolved(ref.trim());
+      return match;
     }
     return typeof v === 'string' ? v : JSON.stringify(v);
   });
 }
 
 /** Deep-render every string in a step-like object. */
-export function renderDeep(obj, scope) {
-  if (typeof obj === 'string') return renderTemplate(obj, scope);
-  if (Array.isArray(obj)) return obj.map((v) => renderDeep(v, scope));
+export function renderDeep(obj, scope, opts = {}) {
+  if (typeof obj === 'string') return renderTemplate(obj, scope, opts);
+  if (Array.isArray(obj)) return obj.map((v) => renderDeep(v, scope, opts));
   if (obj && typeof obj === 'object') {
     const out = {};
-    for (const [k, v] of Object.entries(obj)) out[k] = renderDeep(v, scope);
+    for (const [k, v] of Object.entries(obj)) out[k] = renderDeep(v, scope, opts);
     return out;
   }
   return obj;