@nanobpm/nano-workforce 0.198.0 → 0.199.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.199.0](https://github.com/nanobpm/nano-workforce/compare/v0.198.1...v0.199.0) (2026-10-02)
+
+### Features
+
+* **review-round:** fix the bug class + self-review before push; heredoc result examples ([#843](https://github.com/nanobpm/nano-workforce/issues/843)) ([0b2f26f](https://github.com/nanobpm/nano-workforce/commit/0b2f26f817f15191ef530075d34f6131c99e43cb)), closes [#842](https://github.com/nanobpm/nano-workforce/issues/842)
+
+## [0.198.1](https://github.com/nanobpm/nano-workforce/compare/v0.198.0...v0.198.1) (2026-10-02)
+
+### Bug Fixes
+
+* **deps:** update dependency @nanobpm/agentic to ^0.15.0 ([#848](https://github.com/nanobpm/nano-workforce/issues/848)) ([26f731a](https://github.com/nanobpm/nano-workforce/commit/26f731a9d87a50a9a4852dc7dd5bc8b3e61c72c4))
+
 ## [0.198.0](https://github.com/nanobpm/nano-workforce/compare/v0.197.0...v0.198.0) (2026-10-02)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.198.0",
+  "version": "0.199.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -64,7 +64,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.14.0",
+    "@nanobpm/agentic": "^0.15.0",
     "@nanobpm/urban": "^0.95.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },

package/resources/prompts/fix-ci.md

@@ -120,14 +120,22 @@ machine-readable result one of two ways:
    harness sets for you). The object's keys become process variables. Examples:
 
    ```sh
-   # pushed a fix you believe turns the failing checks green:
-   printf '%s' '{"status":"fixed","pushed":true,"summary":"Fixed the flaky timeout in auth.test.ts and pushed"}' > "$AGENT_RESULT_FILE"
-   # nothing to fix — the failing checks are stale/transient (CANCELLED superseded on the same head SHA, head already green); just re-attempt the merge:
-   printf '%s' '{"status":"reattempt","pushed":false,"summary":"Failing checks are CANCELLED runs superseded by a green run on the same head SHA — nothing to fix, re-queue the merge"}' > "$AGENT_RESULT_FILE"
-   # ordering constraint — must wait for another PR to land first:
-   printf '%s' '{"status":"waiting-on-pr","pushed":false,"summary":"Blocked by the linked-issue gate","dependsOn":"owner/repo#123"}' > "$AGENT_RESULT_FILE"
-   # genuinely stuck — a human must decide:
-   printf '%s' '{"status":"blocked","pushed":false,"summary":"CI needs an NPM_TOKEN secret I cannot set","question":"Add the NPM_TOKEN repo secret, then answer to rerun."}' > "$AGENT_RESULT_FILE"
+# pushed a fix you believe turns the failing checks green:
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"fixed","pushed":true,"summary":"Fixed the flaky timeout in auth.test.ts and pushed"}
+EOF
+# nothing to fix — the failing checks are stale/transient (CANCELLED superseded on the same head SHA, head already green); just re-attempt the merge:
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"reattempt","pushed":false,"summary":"Failing checks are CANCELLED runs superseded by a green run on the same head SHA — nothing to fix, re-queue the merge"}
+EOF
+# ordering constraint — must wait for another PR to land first:
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"waiting-on-pr","pushed":false,"summary":"Blocked by the linked-issue gate","dependsOn":"owner/repo#123"}
+EOF
+# genuinely stuck — a human must decide:
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"blocked","pushed":false,"summary":"CI needs an NPM_TOKEN secret I cannot set","question":"Add the NPM_TOKEN repo secret, then answer to rerun."}
+EOF
    ```
 
    Write this file **once**, at the very end, with your final result. Keep it a flat

package/resources/prompts/rebase.md

@@ -113,12 +113,18 @@ machine-readable result one of two ways:
    harness sets for you). The object's keys become process variables. Examples:
 
    ```sh
-   # branch tip now contains the latest base (you pushed a resolved rebase, or it was already up to date):
-   printf '%s' '{"status":"rebased","summary":"Rebased onto main, resolved 2 conflicts in router.ts, pushed"}' > "$AGENT_RESULT_FILE"
-   # ordering constraint — must wait for another PR to land first:
-   printf '%s' '{"status":"waiting-on-pr","summary":"Stacked on the base PR that has not merged","dependsOn":"owner/repo#123"}' > "$AGENT_RESULT_FILE"
-   # genuine semantic conflict — a human must decide which behaviour wins:
-   printf '%s' '{"status":"blocked","summary":"main and this branch both rewrote retry() incompatibly","question":"Should retries stay capped at 3 (main) or become unbounded (this PR)?"}' > "$AGENT_RESULT_FILE"
+# branch tip now contains the latest base (you pushed a resolved rebase, or it was already up to date):
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"rebased","summary":"Rebased onto main, resolved 2 conflicts in router.ts, pushed"}
+EOF
+# ordering constraint — must wait for another PR to land first:
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"waiting-on-pr","summary":"Stacked on the base PR that has not merged","dependsOn":"owner/repo#123"}
+EOF
+# genuine semantic conflict — a human must decide which behaviour wins:
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"blocked","summary":"main and this branch both rewrote retry() incompatibly","question":"Should retries stay capped at 3 (main) or become unbounded (this PR)?"}
+EOF
    ```
 
    Write this file **once**, at the very end, with your final result. Keep it a flat

package/resources/prompts/review-round.md

@@ -90,13 +90,60 @@ Because several agents may run on the same host at once:
    *nitpick*); otherwise **decline it explicitly with a one-line rationale in your
    `summary`** (e.g. "declined suppressed advisory X — input already validated
    upstream at Y"). Never silently drop one.
-3. **Act.** Make the code changes for all fixes + nitpicks in your workspace (`cwd`)
-   in one coherent, signed-off commit (`git commit -s`). Run the repo's
-   build/test/lint locally before pushing. Push to the PR's head branch (the branch
-   you are already on) — do not open a new branch or PR. If the branch has drifted
+   Treat a **"Previously missed"** advisory as evidence that a whole *category* of issue
+   (e.g. unvalidated input, terminal-width overflow, an unhandled error path) went
+   unchecked in that area. Sweep **every file you touch** for that category this round,
+   rather than fixing only the cited line and waiting for the next review to cite the
+   neighbour.
+3. **Act — fix the class, not the instance.** Each review round costs a full GitHub
+   re-review cycle, so a fix that closes only the cited occurrence just buys another
+   round when the reviewer finds its sibling. For every *fix*:
+   - **Name the bug class** the finding is an instance of (e.g. "fail-open detector:
+     an unrecognised shape is allowed through", "unsanitised text reaches the
+     terminal", "unbounded growth").
+   - **Sweep for the class.** Search the changed code and its siblings (same file,
+     same pattern, same helper's other call sites) for every other occurrence, and fix
+     them in this same commit. Prefer a structural fix that removes the whole class
+     (e.g. fail closed by default, one validating constructor) over patching the cited
+     case.
+   - **Test the class.** Add a red-first regression test per variant you found, not
+     only the one cited.
+
+   Make the code changes for all fixes + nitpicks in your workspace (`cwd`)
+   in one coherent, signed-off commit (`git commit -s`). If the branch has drifted
    behind its base and you need to **rebase / resolve a merge conflict** to keep it
-   mergeable, that is allowed: do it in place on this branch and **force-push**
-   (`--force-with-lease`). Any push this round — including a rebase/force-push with
+   mergeable, do that rebase **now, before validating** — never after the self-review
+   pass below. Then run the repo's build/test/lint locally.
+
+   **Before you push, do one adversarial self-review pass over your own diff.**
+   Diff against the PR's **current base**, not `origin/<head-branch>`: after a
+   permitted rebase, `origin/<head-branch>` still names the pre-rebase remote
+   history, so the three-dot merge base can fall back to the old base and pull
+   unrelated upstream changes into the pass. Resolve and fetch the base fresh,
+   then diff it against `HEAD` — correct before and after any rebase:
+
+   ```sh
+   BASE=$(gh pr view --json baseRefName --jq .baseRefName)   # the PR's current base branch
+   git fetch origin "$BASE"
+   git diff FETCH_HEAD...HEAD                                # the diff the reviewer actually sees
+   ```
+
+   Read it as the reviewer will: what input,
+   edge case, error path, or bypass would a hostile reviewer cite next? Fix what you
+   find in the same commit. **If this pass edits the diff, re-run the repo's
+   build/test/lint before pushing** — otherwise the self-review fix ships unvalidated,
+   since the checks above ran against the pre-self-review code. **The same rule covers
+   any change after the pass:** if you rebase, resolve a conflict, or otherwise alter
+   the diff after this point, re-run build/test/lint *and* redo this self-review before
+   pushing — a late rebase must never ship unvalidated. Do only **one** self-review
+   pass per state of the diff: it exists to catch the obvious next finding, not to
+   block the round.
+
+   Push to the PR's head branch (the branch
+   you are already on) — do not open a new branch or PR. A rebase/force-push
+   (`--force-with-lease`) is allowed when it is needed to keep the branch mergeable,
+   but only **before** the validation + self-review above (or followed by re-running
+   both). Any push this round — including a rebase/force-push with
    no reviewer comments to act on — is an **`addressed`** round (see the return table).
 4. **Reply in-thread** to each comment you addressed or pushed back on, one reply
    per comment, so the trail lives on the PR.
@@ -142,24 +189,24 @@ Because several agents may run on the same host at once:
    leading row summary before it (e.g. `nano-ack: a.json :: Adds X; A is wrong`). Example:
 
    ```sh
-   # Post the ack thread (pick any changed line in the diff for path/line). Use the PR's real HEAD
-   # SHA as commit_id — `git rev-parse HEAD` can drift from the PR head; ask GitHub:
-   CID=$(gh api repos/OWNER/REPO/pulls/PR --jq .head.sha)
-   # Build the body via a QUOTED heredoc so the verbatim advisory prose is never re-interpreted by
-   # the shell — a single-quoted `-f body='...'` breaks the moment the prose contains a `'` (e.g.
-   # "doesn't handle ..."), and a double-quoted one breaks on `$`/backticks. `<<'EOF'` (quoted
-   # delimiter) disables ALL expansion, so any advisory text is safe:
-   BODY=$(cat <<'EOF'
-   Applied. nano-ack: <path> :: <verbatim advisory text>
-   EOF
-   )   # to DECLINE instead, build the body the same quoted-heredoc way (never a single-quoted
-       # `-f body='...'`, which breaks the moment the reason or advisory prose contains a `'`):
-       #   BODY=$(cat <<'EOF'
-       #   Declined, false positive — <reason>. nano-ack: <path> :: <verbatim advisory text>
-       #   EOF
-       #   )
-   gh api repos/OWNER/REPO/pulls/PR/comments -f commit_id="$CID" -f path="PATH" -F line=LINE -f side=RIGHT -f body="$BODY"
-   # Then resolve it exactly like any other thread (map its databaseId -> thread node id -> resolveReviewThread).
+# Post the ack thread (pick any changed line in the diff for path/line). Use the PR's real HEAD
+# SHA as commit_id — `git rev-parse HEAD` can drift from the PR head; ask GitHub:
+CID=$(gh api repos/OWNER/REPO/pulls/PR --jq .head.sha)
+# Build the body via a QUOTED heredoc so the verbatim advisory prose is never re-interpreted by
+# the shell — a single-quoted `-f body='...'` breaks the moment the prose contains a `'` (e.g.
+# "doesn't handle ..."), and a double-quoted one breaks on `$`/backticks. `<<'EOF'` (quoted
+# delimiter) disables ALL expansion, so any advisory text is safe:
+BODY=$(cat <<'EOF'
+Applied. nano-ack: <path> :: <verbatim advisory text>
+EOF
+)   # to DECLINE instead, build the body the same quoted-heredoc way (never a single-quoted
+    # `-f body='...'`, which breaks the moment the reason or advisory prose contains a `'`):
+    #   BODY=$(cat <<'EOF'
+    #   Declined, false positive — <reason>. nano-ack: <path> :: <verbatim advisory text>
+    #   EOF
+    #   )
+gh api repos/OWNER/REPO/pulls/PR/comments -f commit_id="$CID" -f path="PATH" -F line=LINE -f side=RIGHT -f body="$BODY"
+# Then resolve it exactly like any other thread (map its databaseId -> thread node id -> resolveReviewThread).
    ```
    Only the `nano-ack: <path> :: <text>` (prose-keyed) form is honoured. A bare
    `nano-ack: <path>:<line>` marker is **not** an acknowledgement: keyed only on
@@ -258,9 +305,15 @@ default, and you waste a round. So emit a machine-readable result one of two way
    round that needs a human decision:
 
    ```sh
-   printf '%s' '{"status":"needs_input","summary":"Resolved 3 nits; blocked on API shape","question":"Should getUser() throw or return null when the user is absent?"}' > "$AGENT_RESULT_FILE"
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"status":"needs_input","summary":"Resolved 3 nits; blocked on API shape","question":"Should getUser() throw or return null when the user is absent?"}
+EOF
    ```
 
+   Use the **quoted heredoc** shown above (`<<'EOF'`), never a single-quoted
+   `printf '…'` string: your `summary` is free text, and its first apostrophe
+   ("review 123's finding") ends a single-quoted string and breaks the command.
+
    Write this file **once**, at the very end, with your final result. Keep it a flat
    JSON object of exactly the variables in the table above.
 

package/resources/prompts/scope-classify.md

@@ -115,13 +115,17 @@ your output is **not** parsed. Emit a machine-readable result one of two ways:
    once, at the very end. Example (not blocked):
 
    ```sh
-   printf '%s' '{"scopeBlocked":false,"scopeBlockReason":""}' > "$AGENT_RESULT_FILE"
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"scopeBlocked":false,"scopeBlockReason":""}
+EOF
    ```
 
    Blocked example:
 
    ```sh
-   printf '%s' '{"scopeBlocked":true,"scopeBlockReason":"#412 requires both the read AND write projection (acceptance criteria 2 + 3); this PR ships only the read side and defers the write projection with no filed tracker. File a follow-up issue for the write projection, link it (Follow-up: #N), and downgrade Closes #412 -> Part of #412 (close #412 by hand only when the write side lands)."}' > "$AGENT_RESULT_FILE"
+cat > "$AGENT_RESULT_FILE" <<'EOF'
+{"scopeBlocked":true,"scopeBlockReason":"#412 requires both the read AND write projection (acceptance criteria 2 + 3); this PR ships only the read side and defers the write projection with no filed tracker. File a follow-up issue for the write projection, link it (Follow-up: #N), and downgrade Closes #412 -> Part of #412 (close #412 by hand only when the write side lands)."}
+EOF
    ```
 
 2. **Fallback** (only if you cannot write the file): print a single last line to

package/scripts/prompt-result-examples.test.ts

@@ -0,0 +1,421 @@
+// Guard for issue #842: agent-prompt result examples must not put free-text JSON in a
+// single-quoted shell string.
+//
+// Agents copy the prompt's `$AGENT_RESULT_FILE` example verbatim. With the old
+// `printf '%s' '{"summary":"…"}' > "$AGENT_RESULT_FILE"` shape, the first apostrophe in the
+// agent's own free-text summary (e.g. "review 123's finding") terminates the single-quoted
+// string. The command then breaks: the nano-coder sandbox rejected it as an "unterminated
+// quote" and the agent had to retry, in a live kimi-k3 review round. A quoted heredoc
+// (`<<'EOF'`) disables all expansion and quoting, so any prose is safe. This guards the
+// whole class across every deployed prompt, not just the one that bit.
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Urban deploys everything under resources/ RECURSIVELY (AGENTS.md "Deploy by convention"), so a
+// nested prompt (resources/**/foo.md) ships just like a top-level one. Scan the whole deployed
+// surface, not just the immediate children of resources/prompts, or a nested prompt could
+// reintroduce the unsafe example past this guard.
+const RESOURCES_DIR = join(import.meta.dirname, "..", "resources");
+
+function deployedMarkdownFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...deployedMarkdownFiles(full));
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+// The unsafe class is a single-quoted shell string that opens a JSON object (`'{"`) reaching the
+// result file — in ANY redirection form. The retired `printf '…' > "$FILE"` shape is only one
+// instance; `cat > "${AGENT_RESULT_FILE}" <<< '{"…"}'` (herestring, braced var) and
+// `printf '…' | tee "$AGENT_RESULT_FILE"` break identically the moment an apostrophe appears in the
+// free-text JSON. So match the two signals independently (order-free), not the printf layout:
+//   (a) a single-quoted JSON opener, and (b) a reference to AGENT_RESULT_FILE (with or without braces).
+// The opener's whitespace class is `\s`, not `[ \t]`: a multiline single-quoted value (`JSON='` on
+// one line, `{"summary":"x"}` on the next) is one shell string, and `unsafeResultBlocks` joins those
+// lines — a horizontal-only class can't cross the inserted newline, so the same apostrophe failure
+// would slip past the guard (review 5387000199). `\s` matches the joined newline too. But `\s` also
+// lets the CLOSING quote of a quoted-heredoc delimiter (`<<'EOF'`) pair with a JSON body line on the
+// next line — the safe shape — so the lookbehind `(?<![A-Za-z0-9_])` requires the `'` to be an
+// OPENING quote (not preceded by a word char), excluding a delimiter's closing quote. JSON also
+// allows whitespace AFTER the opening brace (`'{ "summary":…}'`), which breaks on an apostrophe
+// identically — so the brace is followed by `\s*` too, not `"` directly (review 5387091667).
+const SINGLE_QUOTED_JSON_OPENER = /(?<![A-Za-z0-9_])'\s*\{\s*"/;
+const RESULT_FILE_REF = /\$\{?AGENT_RESULT_FILE\}?/;
+const isUnsafeResultLine = (line: string): boolean =>
+  SINGLE_QUOTED_JSON_OPENER.test(line) && RESULT_FILE_REF.test(line);
+
+// A single unsafe command need not fit on one physical line: a shell command split with `\`
+// continuations, or a single-quoted JSON assignment on one line whose value is written to the
+// result file on another, has the two signals on different lines and slips past a per-line check.
+// And the assignment and write can be ARBITRARILY separated inside one shell example — three
+// comments between them push the write past any fixed line-distance window, yet the apostrophe
+// still breaks the assignment (review 5387175386). So scope the scan to the unit an agent actually
+// copies and runs — the whole fenced code block — not a fixed window: join continuation lines,
+// then test each fenced block as one unit so a split command / assignment-then-write is caught no
+// matter how far apart the two signals sit inside the block.
+function logicalLines(lines: string[]): string[] {
+  const joined: string[] = [];
+  let buf = "";
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, "");
+    buf = buf ? `${buf}\n${line}` : line;
+    if (!line.endsWith("\\")) {
+      joined.push(buf);
+      buf = "";
+    }
+  }
+  if (buf) joined.push(buf);
+  return joined;
+}
+// Extract the fenced ``` code blocks from a markdown example. Only a fenced block is a runnable
+// shell example an agent copies verbatim; prose between blocks never mixes into a command, so a
+// single-quoted JSON opener and a result-file write only form the unsafe shape when they share a
+// block. Scoping to the block (not the whole file) is what keeps a benign single-quoted JSON in
+// one block from pairing with an unrelated `$AGENT_RESULT_FILE` prose mention in another.
+function fencedBlocks(lines: string[]): string[][] {
+  const blocks: string[][] = [];
+  let cur: string[] | null = null;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) {
+      if (cur) {
+        blocks.push(cur);
+        cur = null;
+      } else {
+        cur = [];
+      }
+    } else if (cur) {
+      cur.push(line);
+    }
+  }
+  if (cur) blocks.push(cur);
+  return blocks;
+}
+function unsafeResultBlocks(lines: string[]): number[] {
+  const bad: number[] = [];
+  for (const block of fencedBlocks(lines)) {
+    const text = logicalLines(block).join("\n");
+    if (SINGLE_QUOTED_JSON_OPENER.test(text) && RESULT_FILE_REF.test(text)) bad.push(0);
+  }
+  return bad;
+}
+
+// A heredoc is only executable if its terminator is a bare delimiter at column 1. The defect fixed
+// in #843 was an INDENTED `EOF` (list-indented markdown) that the shell never recognises, so the
+// heredoc runs to EOF-of-file and the result file is garbage. Validate each deployed heredoc as a
+// complete block: every `<<'TAG'` opener must be closed by a line that is exactly `TAG` at column 1.
+// An opener is a real shell redirect, so ignore backtick-quoted inline-code mentions (`<<'EOF'`) and
+// prose references to the syntax — only a `<<'TAG'` that is NOT inside backticks opens a heredoc.
+// Capture whether the opener used `<<-` (strip-leading-tabs): shell `<<-` deliberately permits a
+// TAB-indented terminator, so the dash flag must be preserved per pending heredoc and the
+// terminator check strips leading tabs only for a `<<-` opener (review 5387476399, previously-missed).
+// The `<<` must NOT be preceded by another `<`: a here-STRING `cat <<<'EOF'` is not a heredoc at
+// all (it feeds the literal text `EOF` to the command's stdin), so without the `(?<!<)` lookbehind
+// the regex matches the here-string's final two `<` and reports an unterminated heredoc where none
+// exists (review 5387687539).
+const HEREDOC_OPENER = /(?<!<)<<(-?)\s*'([A-Za-z_][A-Za-z0-9_]*)'/;
+function heredocOpeners(line: string): { tag: string; dash: boolean }[] {
+  // Strip inline-code spans (`...`) so a prose mention of `<<'EOF'` is not mistaken for an opener.
+  const code = line.replace(/`[^`]*`/g, "");
+  if (code.trimStart().startsWith("#")) return []; // a commented-out example is not a real opener
+  const tags: { tag: string; dash: boolean }[] = [];
+  for (const m of code.matchAll(new RegExp(HEREDOC_OPENER.source, "g")))
+    tags.push({ tag: m[2], dash: m[1] === "-" });
+  return tags;
+}
+// Model the pending heredocs as an ordered QUEUE of expected terminators. One command line can
+// stack several openers (`cat <<'A' <<'B'`), and the shell reads each body in turn, so EVERY opener
+// needs its own later column-1 terminator. A single terminator line therefore closes only the FRONT
+// pending heredoc — it must NOT be credited to every same-line opener that happens to share the
+// delimiter: `cat <<'EOF' <<'EOF'` closed by a single `EOF` still leaves a second heredoc open, so
+// it is malformed (review 5387296036).
+//
+// While a heredoc is pending its body is LITERAL shell input, so a body line is never a new opener:
+// once `cat <<'OUTER'` opens, a body line containing the text `<<'INNER'` is data the command reads,
+// not a redirection, and must not enqueue an `INNER` terminator (review 5387415767). So when the
+// queue is non-empty we only test whether the line is the FRONT terminator; if it is, that heredoc
+// closes, and either way we skip opener discovery for the line. Only a line scanned while NO heredoc
+// is pending can contribute new openers. Every opener still pending at end-of-input is an
+// unterminated heredoc.
+//
+// Two refinements:
+//  - A `<<-` opener's terminator may be TAB-indented (shell strips leading tabs), so the terminator
+//    test strips leading tabs only when that pending opener used `<<-`; a plain `<<` still requires
+//    the bare delimiter at column 1.
+//  - A heredoc body does not begin until a backslash-CONTINUED command is complete: `cat <<'A' \`
+//    followed by `<<'B'` is one command stacking two heredocs, so the second line is more command,
+//    not body, and its opener must still be discovered (review 5387476399). Continuation state must
+//    be tracked ONLY across the command portion — as an explicit flag carried forward, NOT recomputed
+//    from the previous physical line each iteration (review 5387541694). Recomputing it per line had
+//    two symmetric defects: (a) a terminator was tested BEFORE continuation, so `cat <<'A' \` then a
+//    bare `A` credited that `A` as the terminator even though it is a command argument (real bash:
+//    `cat: A: No such file or directory`) and the heredoc is unterminated; and (b) a BODY line ending
+//    in a backslash wrongly re-entered command mode, letting the next literal body line (e.g. text
+//    `<<'INNER'`) be parsed as a new opener. With the flag, `continued` is updated only while in
+//    command mode: once the command completes (a command line not ending in `\`), the body is literal
+//    and a trailing backslash inside it can never reopen command mode.
+function malformedHeredocs(lines: string[]): string[] {
+  const pending: { tag: string; dash: boolean; line: number }[] = [];
+  const isTerminator = (line: string, open: { tag: string; dash: boolean }) =>
+    open.dash ? line.replace(/^\t+/, "") === open.tag : line === open.tag;
+  // `continued` === we are still inside the (possibly multi-line, backslash-continued) COMMAND that
+  // opened the pending heredocs — its body has not begun yet. While command mode is active we discover
+  // openers and never test terminators; once it ends, pending bodies are literal until their terminators.
+  let continued = false;
+  for (let i = 0; i < lines.length; i++) {
+    const inBody = pending.length > 0 && !continued;
+    if (inBody) {
+      // A pending body is literal input: the only thing that matters is whether this line closes the
+      // FRONT heredoc. It never opens a new one and never re-enters command mode.
+      if (isTerminator(lines[i], pending[0])) pending.shift();
+      continue;
+    }
+    for (const open of heredocOpeners(lines[i])) pending.push({ ...open, line: i });
+    continued = lines[i].replace(/\s+$/, "").endsWith("\\");
+  }
+  return pending.map(
+    (open) => `line ${open.line + 1}: heredoc <<'${open.tag}' has no column-1 '${open.tag}' terminator`,
+  );
+}
+// Validate a whole Markdown file one fenced block at a time. A runnable heredoc example lives inside
+// a single ``` fence; scanning the whole file at once lets an unterminated opener borrow a bare
+// delimiter from later prose or another fence (review 5387415767, previously-missed). `malformedHeredocs`
+// itself validates ONE runnable unit (its `lines` are the block), so the cross-fence isolation lives
+// here in the caller: feed each fenced block separately so a terminator can never cross a fence.
+function malformedHeredocsInFile(lines: string[]): string[] {
+  const bad: string[] = [];
+  for (const block of fencedBlocks(lines)) bad.push(...malformedHeredocs(block));
+  return bad;
+}
+
+test("no agent prompt writes $AGENT_RESULT_FILE from a single-quoted JSON string (#842)", () => {
+  const offenders: string[] = [];
+  for (const file of deployedMarkdownFiles(RESOURCES_DIR)) {
+    const rel = file.slice(RESOURCES_DIR.length + 1);
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (const i of unsafeResultBlocks(lines)) offenders.push(`${rel}:${i + 1}`);
+  }
+  assert(
+    offenders.length === 0,
+    `use a quoted heredoc (cat > "$AGENT_RESULT_FILE" <<'EOF') instead of a single-quoted JSON string: ${offenders.join(", ")}`,
+  );
+});
+
+test("every deployed heredoc is a complete, executable block with a column-1 terminator (#843)", () => {
+  const problems: string[] = [];
+  for (const file of deployedMarkdownFiles(RESOURCES_DIR)) {
+    const rel = file.slice(RESOURCES_DIR.length + 1);
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (const p of malformedHeredocsInFile(lines)) problems.push(`${rel}: ${p}`);
+  }
+  assert(
+    problems.length === 0,
+    `every heredoc terminator must be the bare delimiter at column 1 so the example runs verbatim:\n${problems.join("\n")}`,
+  );
+});
+
+test("the guard flags every unsafe result-file shape and accepts the heredoc shape", () => {
+  // The printf redirection that bit, plus the equivalents a `> "$AGENT_RESULT_FILE"`-only check missed:
+  assert(
+    isUnsafeResultLine(`printf '%s' '{"status":"addressed","summary":"x"}' > "$AGENT_RESULT_FILE"`),
+    "retired printf shape must be flagged",
+  );
+  assert(
+    isUnsafeResultLine(`printf '%s' ' {"summary":"x"}' > "$AGENT_RESULT_FILE"`),
+    "single-quoted JSON with leading whitespace before { must still be flagged",
+  );
+  assert(
+    isUnsafeResultLine(`printf '%s' '{ "summary":"review 123's finding"}' > "$AGENT_RESULT_FILE"`),
+    "single-quoted JSON with whitespace after { must still be flagged (review 5387091667)",
+  );
+  assert(
+    isUnsafeResultLine(`cat > "\${AGENT_RESULT_FILE}" <<< '{"summary":"x"}'`),
+    "herestring into a braced result var must be flagged",
+  );
+  assert(
+    isUnsafeResultLine(`printf '%s' '{"summary":"x"}' | tee "$AGENT_RESULT_FILE"`),
+    "tee pipe of single-quoted JSON must be flagged",
+  );
+  // The safe heredoc shape, and its dedented/body lines, must all pass:
+  assert(!isUnsafeResultLine(`cat > "$AGENT_RESULT_FILE" <<'EOF'`), "heredoc opener must pass");
+  assert(!isUnsafeResultLine(`{"status":"addressed","summary":"x"}`), "heredoc body line must pass");
+  assert(!isUnsafeResultLine(`EOF`), "heredoc terminator must pass");
+});
+
+test("the guard flags unsafe shapes split across lines (continuations and assignment-then-write)", () => {
+  // A single-quoted JSON and the result-file write on DIFFERENT physical lines must still be caught.
+  // Each fixture is a fenced ``` block — the unit an agent copies and runs.
+  const continuation = ["```sh", `printf '%s' \\`, `'{"summary":"x"}' \\`, `> "$AGENT_RESULT_FILE"`, "```"];
+  assert(unsafeResultBlocks(continuation).length > 0, "backslash-continued unsafe command must be flagged");
+  const assignThenWrite = ["```sh", `JSON='{"summary":"x"}'`, `printf '%s' "$JSON" > "$AGENT_RESULT_FILE"`, "```"];
+  assert(unsafeResultBlocks(assignThenWrite).length > 0, "single-quoted JSON assigned then written must be flagged");
+  // A MULTILINE single-quoted value — `JSON='` opens on one line and the JSON object starts on the
+  // next — is one shell string. The joined block inserts a newline between `'` and `{"`, which a
+  // horizontal-only whitespace class cannot cross (review 5387000199): this shape must be flagged.
+  const multilineSingleQuoted = ["```sh", `JSON='`, `{"summary":"x"}'`, `printf '%s' "$JSON" > "$AGENT_RESULT_FILE"`, "```"];
+  assert(
+    unsafeResultBlocks(multilineSingleQuoted).length > 0,
+    "multiline single-quoted JSON value reaching the result file must be flagged",
+  );
+  // The safe heredoc shape spans lines but has no single-quoted JSON opener, so it must pass.
+  const safeHeredoc = ["```sh", `cat > "$AGENT_RESULT_FILE" <<'EOF'`, `{"summary":"x"}`, `EOF`, "```"];
+  assert(unsafeResultBlocks(safeHeredoc).length === 0, "safe heredoc block must pass");
+  // A benign single-quoted JSON in one fenced block must NOT pair with a `$AGENT_RESULT_FILE` prose
+  // mention in a DIFFERENT block — scoping to the block (not the whole file) prevents that false
+  // positive.
+  const separateBlocks = [
+    "```sh",
+    `echo '{"status":"ok"}'`,
+    "```",
+    "Write the result to `$AGENT_RESULT_FILE` as shown above.",
+  ];
+  assert(
+    unsafeResultBlocks(separateBlocks).length === 0,
+    "a benign single-quoted JSON in one block and a result-file mention in another must not be flagged",
+  );
+  // An assignment and its write can be arbitrarily separated inside one shell example. Three
+  // comments between them push the write past a fixed four-line window, yet the apostrophe still
+  // breaks the assignment — so the scan is scoped to the whole fenced code block, not a fixed
+  // line distance (review 5387175386).
+  const beyondWindow = [
+    "```sh",
+    `JSON='{"summary":"review 123's finding"}'`,
+    `# comment one`,
+    `# comment two`,
+    `# comment three`,
+    `printf '%s' "$JSON" > "$AGENT_RESULT_FILE"`,
+    "```",
+  ];
+  assert(
+    unsafeResultBlocks(beyondWindow).length > 0,
+    "single-quoted JSON assigned then written beyond a fixed four-line window must be flagged",
+  );
+});
+
+test("the heredoc block validator flags an indented terminator and accepts a column-1 one", () => {
+  // The concrete defect fixed in #843: an indented `EOF` is not a terminator.
+  assert(
+    malformedHeredocs([`cat > "$F" <<'EOF'`, `{"a":1}`, `   EOF`]).length > 0,
+    "indented terminator must be flagged as an unterminated heredoc",
+  );
+  assert(
+    malformedHeredocs([`cat > "$F" <<'EOF'`, `{"a":1}`, `EOF`]).length === 0,
+    "column-1 terminator must pass",
+  );
+  // A commented-out example opener is not a real heredoc and must not be flagged.
+  assert(
+    malformedHeredocs([`    #   BODY=$(cat <<'EOF'`, `    #   EOF`]).length === 0,
+    "commented-out example must be ignored",
+  );
+  // A prose / inline-code mention of `<<'EOF'` is not an opener and must not be flagged.
+  assert(
+    malformedHeredocs(["   Use the **quoted heredoc** shown above (`<<'EOF'`), never a single-quoted"]).length === 0,
+    "inline-code mention of <<'EOF' in prose must not be treated as an opener",
+  );
+  // A heredoc whose terminator is INDENTED is not terminated at that line, so the shell keeps
+  // reading body until a column-1 delimiter. Under correct shell semantics (verified against bash),
+  // a later `cat <<'EOF'` line INSIDE that pending body is literal text, not a second opener — so
+  // `cat <<'EOF'` / `  EOF` / `cat <<'EOF'` / `body` / `EOF` is ONE well-formed heredoc closed by the
+  // final column-1 `EOF`. The "reused delimiter lends its terminator" hazard this fixture guarded in
+  // round 8 is real only when the two blocks are SEPARATE runnable units — i.e. in different fences —
+  // which is exactly the cross-fence case `malformedHeredocsInFile` now isolates (review 5387415767).
+  // Within one pending body there is no second opener to mis-credit, so this must PASS.
+  assert(
+    malformedHeredocs([`cat <<'EOF'`, `  EOF`, `cat <<'EOF'`, `body`, `EOF`]).length === 0,
+    "a later same-delimiter line inside a pending body is literal text, not a borrowed terminator",
+  );
+  // The cross-fence borrow IS malformed: an unterminated opener in one fence must not be closed by a
+  // bare delimiter in later prose or another fence. This is the per-fence isolation fix.
+  assert(
+    malformedHeredocsInFile(["```sh", `cat <<'EOF'`, "```", "trailing prose", "EOF"]).length > 0,
+    "an unterminated fence must not borrow a terminator from later prose (review 5387415767)",
+  );
+  // Two correctly-terminated blocks reusing the same delimiter must still pass.
+  assert(
+    malformedHeredocs([`cat <<'EOF'`, `a`, `EOF`, `cat <<'EOF'`, `b`, `EOF`]).length === 0,
+    "two well-formed blocks reusing one delimiter must pass",
+  );
+  // Several heredocs STACKED on one line (`cat <<'EOF' <<'EOF'`) each need their own terminator: the
+  // shell reads each body in turn, so one `EOF` closes only the first and leaves the second open.
+  // A single terminator must not be credited to every same-line opener sharing the delimiter
+  // (review 5387296036).
+  assert(
+    malformedHeredocs([`cat <<'EOF' <<'EOF'`, `body`, `EOF`]).length > 0,
+    "one terminator must not close two same-line heredocs sharing a delimiter",
+  );
+  // The same stacked pair with BOTH terminators present is well-formed and must pass.
+  assert(
+    malformedHeredocs([`cat <<'EOF' <<'EOF'`, `a`, `EOF`, `b`, `EOF`]).length === 0,
+    "two same-line heredocs each with their own column-1 terminator must pass",
+  );
+  // A pending heredoc's body is LITERAL shell input: a body line containing the text `<<'INNER'` is
+  // data the command reads, not a redirection, so it must NOT enqueue an `INNER` terminator. The
+  // block is one well-formed heredoc closed by `OUTER` (review 5387415767).
+  assert(
+    malformedHeredocs([`cat <<'OUTER'`, `this body mentions <<'INNER' as literal text`, `OUTER`]).length === 0,
+    "a body line containing a heredoc-opener-looking text must not be treated as a new opener",
+  );
+  // The same holds when heredocs are stacked: once `A` is pending, a body line with `<<'C'` is
+  // literal until `A` (then `B`) terminate in turn.
+  assert(
+    malformedHeredocs([`cat <<'A' <<'B'`, `a`, `A`, `body with <<'C' inside`, `B`]).length === 0,
+    "a stacked heredoc body containing opener-like text must still pass",
+  );
+  // A heredoc body does not begin until a backslash-CONTINUED command completes: `cat <<'A' \`
+  // followed by `<<'B'` is ONE command stacking two heredocs, so the second line is more command,
+  // not body, and its opener must be discovered. Omitting the `B` terminator is therefore malformed
+  // (review 5387476399).
+  assert(
+    malformedHeredocs([`cat <<'A' \\`, `<<'B'`, `body-A`, `A`]).length > 0,
+    "a backslash-continued second opener must be discovered, so its omitted terminator is flagged",
+  );
+  // The same split stacked-heredoc command with BOTH terminators present is well-formed and passes.
+  assert(
+    malformedHeredocs([`cat <<'A' \\`, `<<'B'`, `body-A`, `A`, `body-B`, `B`]).length === 0,
+    "a backslash-continued stacked command with both terminators must pass",
+  );
+  // A `<<-` opener's terminator may be TAB-indented (shell strips leading tabs), so a tab-indented
+  // `EOF` closes a `<<-'EOF'` heredoc (review 5387476399, previously-missed).
+  assert(
+    malformedHeredocs([`cat <<-'EOF'`, `\tbody`, `\tEOF`]).length === 0,
+    "a <<- heredoc must accept a tab-indented terminator",
+  );
+  // A plain `<<` opener still requires the bare delimiter at column 1: a tab-indented `EOF` does NOT
+  // terminate it, so the heredoc runs to end-of-input and is malformed.
+  assert(
+    malformedHeredocs([`cat <<'EOF'`, `\tbody`, `\tEOF`]).length > 0,
+    "a plain << heredoc must still reject a tab-indented terminator",
+  );
+  // Continuation state is tracked only across the COMMAND, not recomputed per line (review 5387541694).
+  // (F1) A terminator is never credited while the command is still being continued: `cat <<'A' \`
+  // followed by a bare `A` is `cat <<'A' A` — the `A` is a command ARGUMENT (real bash: `cat: A: No
+  // such file or directory`), not the terminator, so the heredoc is unterminated and must be flagged.
+  assert(
+    malformedHeredocs([`cat <<'A' \\`, `A`]).length > 0,
+    "a bare delimiter on a backslash-continued command line is an argument, not a terminator",
+  );
+  // (F2) A trailing backslash inside a heredoc BODY must NOT re-enter command mode: once `cat <<'OUTER'`
+  // opens, a body line ending in `\` is still literal data, so the following `<<'INNER'` is body text,
+  // not a new opener — the block is well-formed with just the one `OUTER` terminator.
+  assert(
+    malformedHeredocs([`cat <<'OUTER'`, `some text \\`, `<<'INNER'`, `OUTER`]).length === 0,
+    "a backslash at the end of a body line must not reopen command mode and parse the next body line as an opener",
+  );
+  // A here-STRING `cat <<<'EOF'` is NOT a heredoc: it feeds the literal text `EOF` to the command's
+  // stdin (real bash prints `EOF`, exit 0 — no terminator is ever expected). The opener regex must
+  // not match the here-string's final two `<`, so no `EOF` terminator is required (review 5387687539).
+  assert(
+    malformedHeredocs([`cat <<<'EOF'`]).length === 0,
+    "a here-string `<<<'EOF'` must not be reported as an unterminated heredoc",
+  );
+  // A real `<<` heredoc still matches even when it directly follows other text on the line, and a
+  // here-string's leading `<<<` must not swallow a genuine `<<` opener later on the same line.
+  assert(
+    malformedHeredocs([`cat <<<'X' && cat <<'EOF'`, `body`, `EOF`]).length === 0,
+    "a real heredoc later on a line that also contains a here-string must still be validated",
+  );
+});