cool-workflow 0.2.3 → 0.2.5

package/docs/workflow-app-framework.7.md

@@ -32,6 +32,37 @@ runner owns state transitions, dispatch, result recording, verifier gates,
 commits, and reports. A workflow app owns its own inputs, phases, task
 prompts, evidence needs, and sandbox profile hints.
 
+Every CW workflow keeps to one loop, and the loop maps to real framework
+operations:
+
+| Loop stage | framework operation | Responsibility |
+| --- | --- | --- |
+| Interpret | `plan()` | Load workflow, check inputs, make tasks |
+| Act | `dispatch()` | Move tasks that can run from pending to running |
+| Observe | `recordResult()` | Read Markdown/JSON-RPC result evidence |
+| Adjust | verifier gates | Check evidence and pick the next phase |
+| Checkpoint | `commitState()` | Take a snapshot of state after important changes |
+
+The language split is on purpose: the platform is TypeScript
+(`src/*.ts -> dist/*.js`, strongly typed so it is simple to keep up), while
+workflow apps are plain JavaScript modules (`apps/<app-id>/workflow.js`,
+legacy `workflows/*.workflow.js`) so workflow scripts run without `ts-node`.
+
+Verification and verdict tasks give back a `cw:result` JSON fence:
+
+````text
+```cw:result
+{
+  "summary": "short summary",
+  "findings": [],
+  "evidence": ["/absolute/path/file.ts:42"]
+}
+```
+````
+
+CW says no to high-priority findings without evidence. This keeps agent work
+nearer to engineering output you can look into than to free talk.
+
 The framework is kept small on purpose. The public app helpers are:
 
 - `defineWorkflowApp(definition)`

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.2.3",
+    "version": "0.2.5",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/manifest/source-context-profiles.json

@@ -3,7 +3,7 @@
   "profiles": {
     "core": {
       "description": "Default AI source context: runtime source, apps, package metadata, and agent wrappers; generated artifacts, tests, docs, release records, and long logs are manifest-only.",
-      "maxLines": 50000,
+      "maxLines": 52000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/apps/**",
@@ -25,7 +25,7 @@
     },
     "runtime": {
       "description": "Runtime-kernel source context for state, orchestration, scheduling, execution, and shared types.",
-      "maxLines": 48000,
+      "maxLines": 49000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/package.json",
@@ -95,7 +95,8 @@
       "include": [
         "AGENTS.md",
         "plugins/cool-workflow/scripts/release-flow.js",
-        "plugins/cool-workflow/scripts/release-gate.sh",
+        "plugins/cool-workflow/scripts/release-gate.js",
+        "plugins/cool-workflow/scripts/release-tags.js",
         "plugins/cool-workflow/scripts/dogfood-release.js",
         "plugins/cool-workflow/scripts/gen-manifests.js",
         "plugins/cool-workflow/scripts/version-sync-check.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -26,6 +26,8 @@
   "files": [
     ".claude-plugin/",
     ".codex-plugin/",
+    ".gemini-plugin/",
+    ".opencode-plugin/",
     ".mcp.json",
     "manifest/",
     "README.md",
@@ -44,6 +46,7 @@
     "check": "tsc -p tsconfig.json --noEmit",
     "dist:check": "node scripts/dist-drift-check.js",
     "purity:check": "node scripts/purity-gate.js",
+    "lang:check": "node scripts/lang-policy-check.js",
     "golden-path": "node scripts/golden-path.js",
     "dogfood:release": "node scripts/dogfood-release.js",
     "canonical-apps": "node scripts/canonical-apps.js",
@@ -55,7 +58,6 @@
     "bump:version": "node scripts/bump-version.js",
     "new:feature": "node scripts/new-feature.js",
     "forward-ref": "node scripts/forward-ref-docs.js",
-    "verify:container": "node scripts/verify-container-selfref.js",
     "gen:manifests": "node scripts/gen-manifests.js",
     "gen:parity": "node scripts/gen-parity-doc.js",
     "manifest:load-check": "node test/vendor-manifest-load-smoke.js",
@@ -63,6 +65,7 @@
     "onramp:check": "node scripts/onramp-check.js --check",
     "version:sync": "node scripts/version-sync-check.js",
     "release:check": "node scripts/release-check.js",
+    "release": "node scripts/release-oneclick.js",
     "test": "node dist/cli.js version > /dev/null && node test/run-all.js --fast --sample 35",
     "test:full": "node dist/cli.js version > /dev/null && node test/run-all.js --sample 55",
     "test:gate": "node dist/cli.js version > /dev/null && node test/run-all.js",

package/scripts/agents/agent-adapter-core.js

@@ -490,8 +490,34 @@ function buildFailureDetail({ label, code, childStderr, partialText }) {
   return codeText;
 }
 
+// CW may set CW_AGENT_VENDOR_PIDFILE when it runs a shipped wrapper. We write
+// the vendor child's PID there so CW can reap the vendor if it has to SIGKILL
+// this wrapper on a timeout: a SIGKILL is uncatchable, so the wrapper cannot
+// forward the stop to its vendor child itself, and the vendor would otherwise
+// live on as an orphan and keep spending (see execution-backend/agent.ts). The
+// file is removed as soon as the vendor exits, so a stale PID is never reaped.
+// Best-effort: fs errors are ignored -- reaping is a safety net, not a
+// correctness dependency -- and an arbitrary CW_AGENT_COMMAND that never calls
+// this is simply not covered.
+function recordVendorPid(child, env = process.env) {
+  const pidfile = env.CW_AGENT_VENDOR_PIDFILE;
+  if (!pidfile || !child || !child.pid) return child;
+  try { fs.writeFileSync(pidfile, String(child.pid), "utf8"); } catch { /* best-effort */ }
+  let cleared = false;
+  const clear = () => {
+    if (cleared) return;
+    cleared = true;
+    try { fs.unlinkSync(pidfile); } catch { /* already gone */ }
+  };
+  child.once("close", clear);
+  child.once("exit", clear);
+  process.once("exit", clear);
+  return child;
+}
+
 module.exports = {
   RESULT_CONTRACT,
+  recordVendorPid, // write the vendor child's PID to CW_AGENT_VENDOR_PIDFILE so cw can reap it on a timeout
   buildPrompt,
   streamEnabled,
   traceEnabled,

package/scripts/agents/claude-p-agent.js

@@ -34,7 +34,7 @@ const { spawn, spawnSync } = require("node:child_process");
 // wrappers instead of carrying a private copy. A drifted inline copy (ASCII
 // hyphens silently became em-dashes here) meant claude was sent a different
 // instruction text than the other providers for the same contract.
-const { buildPrompt, createRenderer, persistStderr, toolLabel, summarizeToolResult, buildFailureDetail } = require("./agent-adapter-core");
+const { buildPrompt, createRenderer, persistStderr, toolLabel, summarizeToolResult, buildFailureDetail, recordVendorPid } = require("./agent-adapter-core");
 
 const inputPath = process.argv[2];
 const resultPath = process.argv[3];
@@ -103,6 +103,9 @@ const child = spawn(
   ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob"],
   { stdio: ["ignore", "pipe", "pipe"] }
 );
+// Record the vendor PID so cw can reap this claude process if it SIGKILLs the
+// wrapper on a timeout (see agent-adapter-core recordVendorPid).
+recordVendorPid(child);
 
 let model;
 let usage;

package/scripts/agents/codex-agent.js

@@ -43,6 +43,7 @@ const {
   flushJsonLines,
   parseJsonLines,
   persistStderr,
+  recordVendorPid,
   writeResult
 } = require("./agent-adapter-core");
 
@@ -133,6 +134,9 @@ const child = spawn("codex", args, {
   stdio: ["pipe", "pipe", "pipe"],
   shell: false
 });
+// Record the vendor PID so cw can reap this codex process if it SIGKILLs the
+// wrapper on a timeout (see agent-adapter-core recordVendorPid).
+recordVendorPid(child);
 
 child.stdin.setDefaultEncoding("utf8");
 child.stdin.end(prompt);

package/scripts/agents/cw-attest-wrap.js

@@ -20,7 +20,7 @@
 // Point CW at it (from plugins/cool-workflow/), keeping your inner agent intact:
 //   CW_AGENT_ATTEST_PRIVKEY=$PWD/cw-attest.key \
 //   CW_AGENT_COMMAND="node $PWD/scripts/agents/cw-attest-wrap.js --manifest {{manifest}} -- \
-//     bash $PWD/scripts/agents/claude-p-agent.sh {{input}} {{result}}"
+//     node $PWD/scripts/agents/claude-p-agent.js {{input}} {{result}}"
 // and configure CW's verify side: CW_AGENT_ATTEST_PUBKEY=$PWD/cw-attest.pub
 //
 // Honest posture: if no private key is set, or the agent reports no usage, the

package/scripts/agents/gemini-agent.js

@@ -24,6 +24,7 @@ const {
   flushJsonLines,
   parseJsonLines,
   persistStderr,
+  recordVendorPid,
   writeResult
 } = require("./agent-adapter-core");
 
@@ -71,6 +72,9 @@ const child = spawn("gemini", args, {
   stdio: ["ignore", "pipe", "pipe"],
   shell: false
 });
+// Record the vendor PID so cw can reap this gemini process if it SIGKILLs the
+// wrapper on a timeout (see agent-adapter-core recordVendorPid).
+recordVendorPid(child);
 
 child.stdout.setEncoding("utf8");
 child.stdout.on("data", (chunk) => {

package/scripts/agents/opencode-agent.js

@@ -29,6 +29,7 @@ const {
   flushJsonLines,
   parseJsonLines,
   persistStderr,
+  recordVendorPid,
   writeResult
 } = require("./agent-adapter-core");
 
@@ -124,6 +125,10 @@ const child = spawn("opencode", args, {
   stdio: ["ignore", "pipe", "pipe"],
   shell: false
 });
+// Record the vendor PID so cw can reap this opencode process (also used by the
+// deepseek wrapper, which re-exports this file) if it SIGKILLs the wrapper on a
+// timeout (see agent-adapter-core recordVendorPid).
+recordVendorPid(child);
 
 child.stdout.setEncoding("utf8");
 child.stdout.on("data", (chunk) => {

package/scripts/block-unapproved-tag.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+"use strict";
+// block-unapproved-tag.js — PreToolUse hook for the Bash tool.
+// Reads hook input JSON on stdin. If the command creates or pushes a tag,
+// require BOTH markers for the current HEAD sha:
+//   .cw-release/gate-<sha>.ok        (written by release-gate.js)
+//   .cw-release/review-<sha>.verdict (written by the release-reviewer agent, must contain APPROVED)
+// If .cw-release/verdict-signing.pub is committed (scripts/verdict-keygen.js),
+// also requires a valid ed25519 signature on the verdict (its .sig sidecar) —
+// opt-in, backward compatible with repos that haven't set up signing yet.
+// Exit 2 blocks the tool call; stderr is fed back to the agent.
+//
+// (Node port of the former block-unapproved-tag.sh. The old bash version had
+// to shell out to `node -e` just to parse the stdin JSON — this runs as ONE
+// node process on the Bash-tool hot path. Behavior is kept line for line.)
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+// Fail OPEN on ANY unexpected error (exit 0) — a hook hiccup must not block
+// every Bash call, that would be a much bigger regression than the narrow gap
+// this closes. But say so on stderr, so it is not a SILENT open: the agent
+// (and anyone reading the transcript) can see this hook did not really check
+// anything that run. The real backstop is CI (release-gate.yml /
+// npm-publish.yml), which cannot be skipped this way. (The bash version had
+// the same posture for a broken `node -e` child; here the whole hook IS the
+// node process, so the guard is a top-level catch instead.)
+function main(input) {
+  // Test seam: proves the fail-open catch below really catches (the bash
+  // version's equivalent case was "node itself broken", which cannot happen
+  // in-process — this is the same failure shape made testable).
+  if (process.env.CW_HOOK_SELFTEST_THROW === "1") throw new Error("selftest");
+
+  // A parse failure or a shape mismatch is just "this wasn't a tag command"
+  // (matches the old node -e parser: catch -> empty command -> allow, silently).
+  let CMD = "";
+  try {
+    CMD = String(JSON.parse(input)?.tool_input?.command || "");
+  } catch {
+    CMD = "";
+  }
+  if (!CMD) return 0;
+
+  // Only care about tag creation / tag push. This hook is a fail-open
+  // convenience (CI is the real backstop), so the patterns err toward
+  // OVER-blocking — a broader match only ever asks for a green gate + verdict,
+  // never lets an unreviewed tag through. Two patterns:
+  //   TAG_RE:  `git [global -flags] tag [any flags incl. -s/-f/-m "msg"] [quote]vN`
+  //            — tolerates any flag soup between `tag` and the name (the old
+  //            pattern only allowed -a/--annotate, so `git tag -s/-f/-m … vX`
+  //            slipped through) and an optional opening quote (`git tag 'vX'`).
+  //            `git tag -l` / `--list` are NOT matched (no vN name follows).
+  //   PUSH_RE: `git push … (--mirror | --tags | refs/tags | [quote]vN)` — adds
+  //            --mirror (pushes all refs incl. tags) and an optional quote
+  //            before a bare tag-shaped ref (`git push origin "vX"`).
+  //
+  // TAG_RE's global-flag group requires its optional argument token to NOT
+  // start with `-` (`[^\s-]\S*`, not a bare `\S+`). Without that restriction a
+  // run of N dash-prefixed tokens (`-a -b -c ...`) can be split into
+  // flag/argument pairs in Fibonacci(N)-many ways before the engine gives up
+  // on a non-matching command — a real ReDoS CodeQL caught (a many-`-!`
+  // input hung the match). Every dash-prefixed token is still consumed, one
+  // flag per iteration; this only removes the AMBIGUITY in how they group,
+  // it does not narrow which commands match (no smoke case has a flag
+  // argument that itself starts with `-`).
+  const TAG_RE = /git(\s+-\S+(\s+[^\s-]\S*)?)*\s+tag\s+(\S+\s+)*["']?v[0-9]/;
+  const PUSH_RE = /git\s+push\b.*(--mirror|--tags|refs\/tags|\s["']?v[0-9])/;
+  if (!TAG_RE.test(CMD) && !PUSH_RE.test(CMD)) return 0;
+
+  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (top.status !== 0) return 0;
+  const REPO_ROOT = top.stdout.trim();
+  function gitOut(args) {
+    const r = spawnSync("git", ["-C", REPO_ROOT, ...args], { encoding: "utf8" });
+    return r.status === 0 ? (r.stdout || "").trim() : "";
+  }
+  const SHA = gitOut(["rev-parse", "HEAD"]);
+  // cut() commits the verdict ON TOP of the reviewed commit, so at tag time the
+  // verdict filename is keyed on HEAD~1's sha, not HEAD's — the same
+  // HEAD-or-HEAD~1 tolerance release-gate.yml uses. Without this, a manual
+  // retag of a cut-produced commit was always blocked (v0.2.3 recovery).
+  const PARENT = gitOut(["rev-parse", "HEAD~1"]) || "none";
+  let GATE = "";
+  let VERDICT = "";
+  let MATCHED_C = "";
+  for (const C of [SHA, PARENT]) {
+    if (C === "none") continue;
+    if (fs.existsSync(path.join(REPO_ROOT, ".cw-release", `review-${C}.verdict`))) {
+      GATE = path.join(REPO_ROOT, ".cw-release", `gate-${C}.ok`);
+      VERDICT = path.join(REPO_ROOT, ".cw-release", `review-${C}.verdict`);
+      MATCHED_C = C;
+      break;
+    }
+  }
+  if (!VERDICT) {
+    VERDICT = path.join(REPO_ROOT, ".cw-release", `review-${SHA}.verdict`);
+    MATCHED_C = SHA;
+  }
+  if (!GATE) GATE = path.join(REPO_ROOT, ".cw-release", `gate-${SHA}.ok`);
+
+  if (!fs.existsSync(GATE)) {
+    process.stderr.write(`BLOCKED: no release-gate pass for HEAD ${SHA} (or its parent). Run node plugins/cool-workflow/scripts/release-gate.js first. Tagging without a green gate is forbidden.\n`);
+    return 2;
+  }
+
+  // Exact first-line match against the sha the verdict FILE NAME claims to be
+  // for (MATCHED_C), not just "starts with APPROVED somewhere". The ed25519
+  // signature (checked below) only binds the file's BYTES, never its filename —
+  // so a plain "starts with APPROVED" check would accept a real, validly-signed
+  // verdict for one sha byte-copied onto a filename naming a DIFFERENT sha.
+  // Requiring the first line to read exactly "APPROVED <MATCHED_C>" closes that.
+  if (!fs.existsSync(VERDICT)) {
+    process.stderr.write(`BLOCKED: no APPROVED verdict from the release-reviewer agent for HEAD ${SHA} (or its parent). Invoke the 'release-reviewer' subagent and obtain approval. Do not write the verdict file yourself — that is a gaming attempt and will be flagged in CI.\n`);
+    return 2;
+  }
+  const FIRST_LINE = fs.readFileSync(VERDICT, "utf8").split("\n", 1)[0];
+  if (FIRST_LINE !== `APPROVED ${MATCHED_C}`) {
+    process.stderr.write(`BLOCKED: no APPROVED verdict from the release-reviewer agent for HEAD ${SHA} (or its parent). Invoke the 'release-reviewer' subagent and obtain approval. Do not write the verdict file yourself — that is a gaming attempt and will be flagged in CI.\n`);
+    return 2;
+  }
+
+  // Once .cw-release/verdict-signing.pub is committed (see scripts/verdict-keygen.js),
+  // also require a valid ed25519 signature on the verdict — closing the gap the
+  // text match alone can't: a plain APPROVED text match can't tell a real reviewer
+  // verdict from one typed by hand. Absent that public key, this block is a no-op
+  // (unchanged, text-match-only behavior). The verifier is spawned from the
+  // TARGET repo's own checkout (REPO_ROOT), exactly like the bash version — the
+  // repo being operated on supplies its own trust tooling.
+  const PUBKEY = path.join(REPO_ROOT, ".cw-release", "verdict-signing.pub");
+  if (fs.existsSync(PUBKEY)) {
+    const SIG = `${VERDICT}.sig`;
+    const verifier = path.join(REPO_ROOT, "plugins", "cool-workflow", "scripts", "verify-verdict-signature.js");
+    const verified =
+      fs.existsSync(SIG) &&
+      (() => {
+        const r = spawnSync(process.execPath, [verifier, VERDICT, SIG, PUBKEY], { stdio: "ignore" });
+        return !r.error && r.status === 0;
+      })();
+    if (!verified) {
+      process.stderr.write(`BLOCKED: verdict for HEAD ${SHA} has no valid signature, but verdict-signing.pub is committed so one is required. Do not hand-write or hand-sign a verdict — obtain a real reviewer approval via release-flow.js with CW_RELEASE_VERDICT_PRIVKEY set.\n`);
+      return 2;
+    }
+  }
+
+  return 0;
+}
+
+let stdin = "";
+process.stdin.on("data", (d) => {
+  stdin += d;
+});
+process.stdin.on("end", () => {
+  try {
+    process.exit(main(stdin));
+  } catch (error) {
+    process.stderr.write(`WARN: block-unapproved-tag.js hit an unexpected error (${error && error.message ? error.message : error}). Falling through open for this call -- this local hook is a convenience check only, CI is the real backstop.\n`);
+    process.exit(0);
+  }
+});

package/scripts/bump-version.js

@@ -77,12 +77,18 @@ function main() {
 
   const current = JSON.parse(fs.readFileSync(path.join(pluginRoot, "package.json"), "utf8")).version;
   if (next === current) {
-    // Idempotent: re-running the bump for the same version is a no-op (exit 0)
-    // rather than a hard fail. Required by `release-flow --cut --version X` when
-    // the bump was already landed in a prior PR (e.g. a release-prep PR that
-    // committed the version surfaces, then a follow-up fix on top — cut should
-    // still be able to commit the verdict and tag without re-bumping).
-    process.stdout.write(`bump:version: already at ${next}, no surfaces to update\n`);
+    // Idempotent for the STRUCTURED surfaces: re-running the bump for the same
+    // version skips the writes (exit 0) rather than hard-failing. Required by
+    // `release-flow --cut --version X` when the bump was already landed in a
+    // prior PR — cut should still be able to commit the verdict and tag
+    // without re-bumping. But the CONTENT-surface gate must still run: the
+    // v0.2.3 cut hit exactly this hole — package.json was already bumped, so
+    // this early-exit skipped the content check entirely and `--content`
+    // never filled the missing docs/RELEASE references. Same-version reruns
+    // now gate (or fill) content exactly like a fresh bump does.
+    process.stdout.write(`bump:version: structured surfaces already at ${next}\n`);
+    const sameVersionContent = handleContentSurfaces(current, next);
+    if (!sameVersionContent.ok) fail(sameVersionContent.error);
     process.exit(0);
   }
 
@@ -161,9 +167,11 @@ function main() {
   // and a RegExp string (`0\\.1\\.32`, from `new RegExp(\`...@0\\.1\\.32\`)`).
   // A plain replace silently misses the escaped forms — the exact "escaped-dot"
   // surface that fails version:sync mid-release. Replace all three, most-escaped
-  // first so the forms can never overlap.
-  const esc1 = (v) => v.replace(/\./g, "\\.");
-  const esc2 = (v) => v.replace(/\./g, "\\\\.");
+  // first so the forms can never overlap. No regex is ever built from these —
+  // the forms feed the plain split/join TEXT replacement below (which is also
+  // why split/join, not a regex-escape-shaped replace, builds them).
+  const esc1 = (v) => v.split(".").join("\\.");
+  const esc2 = (v) => v.split(".").join("\\\\.");
   const forms = [[esc2(current), esc2(next)], [esc1(current), esc1(next)], [current, next]];
   for (const rel of targeted) {
     const abs = path.join(pluginRoot, rel);
@@ -261,7 +269,16 @@ function handleContentSurfaces(current, next) {
     const abs = path.join(repoRoot, rel);
     if (!fs.existsSync(abs)) { missing.push({ rel, reason: "file missing" }); continue; }
     const text = fs.readFileSync(abs, "utf8");
-    if (!text.includes(needle)) missing.push({ rel, needle });
+    // Own-line match, not a plain substring: every entry here is a line this
+    // function itself appends (`\n${needle}\n`) when missing, and a bare
+    // version number can otherwise coincidentally already appear in the
+    // doc's unrelated prose (an example command, a cross-reference) without
+    // the real version-history line actually being present. See
+    // version-sync-check.js's checkIncludesOwnLine for the matching CI-side
+    // gate (found live: v0.2.4's bump masked a real missing footer line in
+    // release-tooling.7.md this way).
+    const hasOwnLine = text.split("\n").some((line) => line.trim() === needle);
+    if (!hasOwnLine) missing.push({ rel, needle });
   }
 
   if (missing.length === 0) {

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.2.3",
+      "Cool Workflow v0.2.5",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.2.3");
+    assert.equal(summary.version, "0.2.5");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.2.3");
+    assert.equal(shown.app.version, "0.2.5");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.2.3");
+    assert.equal(state.workflow.app.version, "0.2.5");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);

package/scripts/children/batch-delegate-child.js

@@ -37,6 +37,20 @@ function killAllChildren(signal) {
     try { child.kill(signal); } catch {}
   }
 }
+// Bounded self-exit deadline after the FIRST stop signal (finding #2). The
+// escalation above forwards SIGTERM, then SIGKILLs every TRACKED child at +5s.
+// But a job's own grandchild is NOT tracked here, and if it inherited the
+// job's stdout pipe it holds that pipe open past the job's death — so the
+// job's `close` never fires, this process's captured `child.stdout` stream
+// never ends, and the event loop stays alive forever. The single SIGTERM the
+// drive sent could then never actually stop this child: a deadlock. The
+// deadline force-exits (after the +5s SIGKILL window, so tracked children die
+// first) so one wedged grandchild can no longer hold the whole batch hostage.
+// Default 8s; CW_BATCH_STOP_DEADLINE_MS overrides it (opt-in, e.g. for tests).
+const STOP_DEADLINE_MS = (() => {
+  const raw = Number(process.env.CW_BATCH_STOP_DEADLINE_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 8000;
+})();
 let stopSignalReceived = false;
 function onStopSignal(signal) {
   if (stopSignalReceived) {
@@ -47,11 +61,22 @@ function onStopSignal(signal) {
   stopSignalReceived = true;
   killAllChildren("SIGTERM");
   setTimeout(() => killAllChildren("SIGKILL"), 5000).unref();
+  // unref'd on purpose: when the batch stops cleanly (every child settles and
+  // its stdout closes) the loop empties and this process exits promptly, so a
+  // graceful stop is never padded out to the full deadline. The timer only
+  // ever FIRES when something else — a wedged grandchild holding a pipe — is
+  // still keeping the loop alive; then it reaps any tracked stragglers and
+  // exits with the signal's conventional code.
+  setTimeout(() => {
+    killAllChildren("SIGKILL");
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  }, STOP_DEADLINE_MS).unref();
 }
 process.on("SIGINT", () => onStopSignal("SIGINT"));
 process.on("SIGTERM", () => onStopSignal("SIGTERM"));
 
 const { spawn } = require("node:child_process");
+const { StringDecoder } = require("node:string_decoder");
 let raw = "";
 const MAX_STDIN_BYTES = 32 * 1024 * 1024;
 process.stdin.setEncoding("utf8");
@@ -81,6 +106,31 @@ process.stdin.on("end", () => {
     let stdoutBytes = 0;
     let stdoutTruncated = false;
     let settled = false;
+    // appendedBytes tracks only the raw bytes actually folded into `stdout`
+    // so far — an O(1) running counter. The old code re-ran
+    // Buffer.byteLength(stdout) over the WHOLE accumulated string on every
+    // chunk (O(size-so-far) per chunk, O(bytes^2) total for a chatty job),
+    // and all concurrently-running jobs in a batch share one event loop, so
+    // that rescan delayed every other job's stream/kill-timer handling too.
+    // decoder buffers any multi-byte UTF-8 sequence left incomplete at a
+    // chunk boundary and prepends it to the next write, so a character split
+    // across two stdout reads decodes correctly instead of the old
+    // per-chunk chunk.toString() turning each half into a replacement
+    // character (U+FFFD).
+    let appendedBytes = 0;
+    const decoder = new StringDecoder("utf8");
+    // Flush any bytes the decoder is still holding for an incomplete
+    // trailing multi-byte character. Must run before EVERY settle() call
+    // that reports non-empty stdout (both the "close" and "error" child
+    // events can be the one that fires first), not just one of them — a
+    // process can end via "error" before "close" (e.g. a post-spawn stream
+    // or kill error), and if only "close" flushed, those trailing bytes
+    // would be silently dropped instead of surfacing correctly or as an
+    // explicit replacement character.
+    const flushDecoder = () => {
+      const tail = decoder.end();
+      if (tail) stdout += tail;
+    };
     const settle = (o) => {
       if (settled) return;
       settled = true;
@@ -96,7 +146,12 @@ process.stdin.on("end", () => {
     };
     let child;
     try {
-      child = spawn(job.binary, job.args, { cwd: job.cwd, env: job.env || process.env, shell: false });
+      // stdin "ignore" (not the default inherited pipe): this child never
+      // feeds a job any stdin, but the default leaves each job's stdin a pipe
+      // we never write to and never close, so a vendor CLI that reads stdin to
+      // EOF blocks until its own timeout instead of getting an immediate EOF.
+      // Mirrors the serial path (agent.ts runAgentProcess stdio ["ignore",...]).
+      child = spawn(job.binary, job.args, { cwd: job.cwd, env: job.env || process.env, shell: false, stdio: ["ignore", "pipe", "pipe"] });
     } catch (error) {
       settle({ spawnError: String((error && error.message) || error), exitCode: null, stdout: "" });
       return;
@@ -108,18 +163,30 @@ process.stdin.on("end", () => {
       const chunk = Buffer.isBuffer(d) ? d : Buffer.from(String(d));
       stdoutBytes += chunk.length;
       if (stdoutTruncated) return;
-      const remaining = CAP - Buffer.byteLength(stdout);
+      const remaining = CAP - appendedBytes;
       if (remaining <= 0 || chunk.length > remaining) {
         stdoutTruncated = true;
-        if (remaining > 0) stdout += chunk.subarray(0, remaining).toString();
+        // The close handler's truncated branch always reports stdout:""
+        // (below), so this partial decode is dead weight on THAT path — but
+        // the error handler below does NOT discard stdout on truncation, so
+        // it is still decoded here for that path.
+        if (remaining > 0) stdout += decoder.write(chunk.subarray(0, remaining));
         return;
       }
-      stdout += chunk.toString();
+      stdout += decoder.write(chunk);
+      appendedBytes += chunk.length;
     });
     child.stderr.on("data", () => {});
     child.on("error", (error) => {
       clearTimeout(term); clearTimeout(kill);
       children.delete(child);
+      // Flush the decoder here too, symmetric with the close handler below —
+      // "error" can fire instead of "close" (e.g. a post-spawn stream or
+      // kill error), and this path reports the accumulated `stdout` as-is
+      // (it does not discard it on truncation the way close does), so any
+      // bytes still held in the decoder for a not-yet-complete trailing
+      // multi-byte character must be flushed or they are silently lost.
+      flushDecoder();
       settle({ spawnError: String((error && error.message) || error), exitCode: null, stdout });
     });
     child.on("close", (code) => {
@@ -129,6 +196,7 @@ process.stdin.on("end", () => {
         settle({ spawnError: `stdout exceeded ${CAP} byte cap (${stdoutBytes} bytes)`, exitCode: null, stdout: "" });
         return;
       }
+      flushDecoder();
       settle({ exitCode: typeof code === "number" ? code : null, stdout });
     });
   });