cohorte 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -7,6 +7,39 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.0.1 — 2026-08-03
+
+Three fixes, one failure: an autonomous `/cohorte-loop` run that built 1 surface of 3, stamped
+itself green, and then hung asking a human to approve its own pre-flight. All in `loop.sh` — no
+repo files change, so `npx cohorte@latest update --global` (or `update`) is the whole migration.
+
+- **Child sessions now run in `bypassPermissions`, not `acceptEdits`.** `acceptEdits` auto-approves
+  Write/Edit and *nothing else*, so the first `Bash` call no `allow` prefix in `settings.json`
+  covers raises a permission prompt — and a `claude -p` child has nobody to answer it. It stalls,
+  prints prose asking you to approve, and **exits 0**, which the driver scores as a clean phase.
+  That is the whole content of one observed run: the review child blocked on invoking
+  `preflight.sh` and the loop logged `▶ /cohorte-review … ok`. It is also backwards from what the
+  gate is built for — `hooks/gate.py` escalates every `ask` match to a hard **deny** under
+  `bypassPermissions` precisely because an unattended run cannot confirm. So the dangerous commands
+  from PIPELINE.md `gate` stay blocked deterministically, while typecheck/lint/tests/`git diff` stop
+  needing a human. `CLAUDE_FLAGS` still overrides it for a watched run.
+
+- **A build phase that reported nothing is no longer treated as a build that found nothing.** The
+  driver checked `dead[]` in `specs/reports/<id>.build.json` but accepted the file being **absent** —
+  and a phase cut short never reaches the step that writes it, so there was no file to grep and no
+  surface to name while the child still exited 0. A 3-surface build that lost 2 of them mid-write
+  stamped `<id>.built` and sent reviewers at the result. A missing `build.json` after a build now
+  aborts as **exit 2**, naming the cause, and leaves no stamp so a re-run rebuilds.
+
+- **`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` is exported for every child.** Print mode otherwise
+  *terminates* still-running background tasks at its ceiling ("Background tasks still running after
+  600s; terminating") — which is 25–40 min short of a real implementer batch, and killed the two
+  surfaces above mid-write. The phase is bounded by its own completion (and by the `caffeinate`
+  assertion the driver already holds), not by a stopwatch that fires inside the longest phase.
+
+`test-loop.mjs` pins all three, including the fixture bug that hid the second one: its `ready`
+build wrote no `build.json` either.
+
 ## 2.0.0 — 2026-08-03
 
 > **Breaking: every command is renamed.** `/build` → `/cohorte-build`, `/review` →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/scripts/loop.sh

@@ -99,7 +99,7 @@ usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild] [--resume]
                (loop_pass), instead of starting over at pass 1
 
   env CLAUDE_FLAGS   flags for every child session
-                     (default: --permission-mode acceptEdits)
+                     (default: --permission-mode bypassPermissions)
 EOF
   exit 64
 }
@@ -194,7 +194,32 @@ fm_set() {                        # fm_set <key> <value>  (replace, else append)
     mv "$spec.loop.tmp" "$spec" 2>/dev/null || rm -f "$spec.loop.tmp"
 }
 
-: "${CLAUDE_FLAGS:=--permission-mode acceptEdits}"
+# --- child session flags -----------------------------------------------------
+# bypassPermissions, NOT acceptEdits. acceptEdits auto-approves Write/Edit and
+# NOTHING else, so every Bash call in a child falls back to the settings.json
+# rules — and the first one no `allow` prefix covers raises a permission prompt.
+# In `claude -p` there is nobody to answer it: the child stalls, eventually
+# prints prose asking the human to approve, and EXITS 0. The driver then reads
+# that as a clean phase. Observed on a real run: the review child hung on its own
+# preflight.sh call ("could you approve the pending tool-call prompt") and the
+# loop scored the phase `ok`.
+#
+# This is also what the gate hook is built for: hooks/gate.py escalates every
+# `ask` match to a hard DENY under bypassPermissions, precisely because an
+# unattended run has nobody to confirm. The dangerous commands stay blocked — by
+# the gate, deterministically, from PIPELINE.md `gate` — while the mechanical
+# ones (typecheck, lint, tests, git diff) stop needing a human. Driving the loop
+# in acceptEdits gets this backwards: nothing is auto-denied and everything is
+# auto-hung. Override with CLAUDE_FLAGS to run in a stricter mode interactively.
+: "${CLAUDE_FLAGS:=--permission-mode bypassPermissions}"
+
+# A `/cohorte-build` implementer batch runs 25–40 min as background tasks. In print
+# mode the harness waits a bounded time for background work and then TERMINATES it
+# ("Background tasks still running after 600s; terminating"), which cuts implementers
+# off mid-write and still exits the child 0. 0 = wait indefinitely; the caffeinate
+# assertion above and the phase's own completion are what bound a phase, not a
+# stopwatch that fires in the middle of the longest one.
+export CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0
 
 : >"$log"
 {
@@ -309,6 +334,14 @@ spawned no agent; see $readiness, then /cohorte-spec $id"
     finish 2 "✗ an implementer died — the surface(s) in \"dead\" were never built; see $buildjson and $log"
   fi
   [ "$build_ok" -eq 1 ] || finish 2 "✗ /cohorte-build failed — see $log"
+  # An ABSENT build.json is the same class of lie as a dead implementer, and the `dead`
+  # check above cannot see it: a phase cut short (harness background-task ceiling, a
+  # Claude Code teardown, a crash) never reaches §3's report, so there is no file to
+  # grep and no surface to name — while the child still exits 0. Treating "no report"
+  # as "nothing to report" is what let a build of 3 surfaces stamp itself green with 2
+  # of them never written, and sent reviewers at the result.
+  [ -f "$buildjson" ] || finish 2 "✗ /cohorte-build wrote no $buildjson — the phase was cut short \
+(background-task ceiling, teardown or crash) and the surfaces it never reported are unbuilt; see $log"
   date -u +%Y-%m-%dT%H:%M:%SZ >"$stamp"
 fi
 

package/scripts/test-loop.mjs

@@ -59,6 +59,9 @@ case "$cmd" in
   *) echo "fake claude: expected a /cohorte-* command, got '$cmd'" >&2; exit 9 ;;
 esac
 cmd="\${cmd#/cohorte-}"          # scenarios are keyed on the PHASE, which stays unprefixed
+# Echoed so the tests can assert what the driver hands its children: an unattended child
+# that cannot answer a permission prompt, and a background ceiling that must not fire.
+echo "fake claude: bgceil=\${CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS:-unset}"
 n=0; [ -f "$SCEN_DIR/count" ] && n=$(cat "$SCEN_DIR/count")
 n=$((n + 1)); echo "$n" >"$SCEN_DIR/count"
 step=$(sed -n "\${n}p" "$SCEN_DIR/phases")
@@ -72,6 +75,13 @@ case "$do_what" in
       >specs/reports/feat-x.readiness.json ;;
   ready)
     printf '{"id":"feat-x","phase":"readiness","ts":"t","verdict":"READY","gaps":[],"surfaces":["backend"]}' \\
+      >specs/reports/feat-x.readiness.json
+    printf '{"id":"feat-x","phase":"build","ts":"t","surfaces":{"backend":"ok"},"dead":[]}' \\
+      >specs/reports/feat-x.build.json ;;
+  # READY, dispatched, and then cut short before §3's report — the harness terminating
+  # background implementers, a teardown, a crash. No build.json, and exit 0 anyway.
+  cutshort)
+    printf '{"id":"feat-x","phase":"readiness","ts":"t","verdict":"READY","gaps":[],"surfaces":["backend","frontend"]}' \\
       >specs/reports/feat-x.readiness.json ;;
   clean)
     printf '{"id":"feat-x","phase":"review","ts":"t","verdict":"SHIP","findings":2,"blocking":0,"deferred":2,"unreviewed":[],"fingerprint":""}' \\
@@ -114,24 +124,26 @@ function scenario(phases, { frontmatter = FM } = {}) {
 }
 
 function runLoop({ dir, bin }, args) {
-  const r = spawnSync("bash", [LOOP, ...args], {
-    cwd: dir,
-    encoding: "utf8",
-    env: {
-      ...process.env,
-      PATH: `${bin}:${process.env.PATH}`,
-      SCEN_DIR: dir,
-      CLAUDE_FLAGS: "--permission-mode acceptEdits",
-      GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t.t",
-      GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t.t",
-    },
-  });
+  const env = {
+    ...process.env,
+    PATH: `${bin}:${process.env.PATH}`,
+    SCEN_DIR: dir,
+    GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t.t",
+    GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t.t",
+  };
+  // Never inherit these from whoever runs the suite: the default child flags and the
+  // background ceiling are exactly what the assertions below are about.
+  delete env.CLAUDE_FLAGS;
+  delete env.CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS;
+  const r = spawnSync("bash", [LOOP, ...args], { cwd: dir, encoding: "utf8", env });
   const spec = readFileSync(join(dir, "specs/feat-x.md"), "utf8");
   const fm = k => {
     const m = spec.match(new RegExp(`^${k}:\\s*([^#\\n]*)`, "m"));
     return m ? m[1].trim() : null;
   };
-  return { code: r.status, out: `${r.stdout}${r.stderr}`, spec, fm };
+  const logPath = join(dir, "specs/reports/feat-x.loop.log");
+  const log = existsSync(logPath) ? readFileSync(logPath, "utf8") : "";
+  return { code: r.status, out: `${r.stdout}${r.stderr}`, spec, fm, log };
 }
 
 console.log("loop.sh — readiness gate");
@@ -189,6 +201,55 @@ console.log("loop.sh — a dead subagent is never a clean result");
   check("dead reviewer ⇒ spec is NOT left in-review", r.fm("status") === "blocked", r.fm("status"));
 }
 
+console.log("loop.sh — a build that never reported is never a built build");
+{
+  // The absent-file twin of the dead implementer, and the one the `dead[]` grep cannot
+  // see: a phase cut short never reaches the step that writes build.json, so there is no
+  // file to read and no surface to name — while the child still exits 0. Scoring that as
+  // a clean build stamps `.built` over a half-written tree and sends reviewers at it.
+  const s = scenario(["build:cutshort"]);
+  const r = runLoop(s, ["feat-x"]);
+  check("no build.json ⇒ exit 2, not a review pass", r.code === 2, `got ${r.code}: ${r.out}`);
+  check("no build.json ⇒ no reviewer was spawned", !/phase=review/.test(r.out));
+  check("no build.json ⇒ names the cut-short phase", /wrote no .*build\.json/.test(r.out),
+    r.out.trim().split("\n").pop());
+  check("no build.json ⇒ the build stamp is NOT written (a re-run must rebuild)",
+    !existsSync(join(s.dir, "specs/reports/feat-x.built")));
+  check("no build.json ⇒ spec left blocked", r.fm("status") === "blocked", r.fm("status"));
+}
+
+console.log("loop.sh — what the children are handed");
+{
+  // acceptEdits auto-approves Write/Edit and NOTHING else, so the first child Bash call no
+  // `allow` rule covers raises a prompt no `claude -p` can answer: the child stalls, asks
+  // the human in prose, and exits 0 — which the driver scores `ok`. Seen on a real run,
+  // where the review child hung on its own preflight.sh call. gate.py is built for the
+  // other mode: it escalates `ask` to a hard deny under bypassPermissions.
+  const s = scenario(["build:ready", "review:clean"]);
+  const r = runLoop(s, ["feat-x"]);
+  check("default child flags are bypassPermissions, not acceptEdits",
+    /# flags: --permission-mode bypassPermissions/.test(r.log) && !/acceptEdits/.test(r.log),
+    r.log.split("\n")[1]);
+  // Print mode TERMINATES still-running background tasks at its ceiling ("Background tasks
+  // still running after 600s"), which cuts a 25–40 min implementer batch off mid-write.
+  check("children inherit an unbounded background-task ceiling",
+    /fake claude: bgceil=0/.test(r.log), (r.log.match(/bgceil=\S*/) || ["absent"])[0]);
+}
+{
+  // The override is the escape hatch for a watched run — it must not have been hard-coded away.
+  const s = scenario(["review:clean"]);
+  const r = spawnSync("bash", [LOOP, "feat-x", "--no-build"], {
+    cwd: s.dir, encoding: "utf8",
+    env: { ...process.env, PATH: `${s.bin}:${process.env.PATH}`, SCEN_DIR: s.dir,
+      CLAUDE_FLAGS: "--permission-mode acceptEdits",
+      GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t.t",
+      GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t.t" },
+  });
+  const log = readFileSync(join(s.dir, "specs/reports/feat-x.loop.log"), "utf8");
+  check("CLAUDE_FLAGS overrides the default", /# flags: --permission-mode acceptEdits/.test(log),
+    `${r.status}: ${log.split("\n")[1]}`);
+}
+
 console.log("loop.sh — non-convergent + resume");
 {
   const s = scenario(["build:ready", "review:blocking", "fix:noop", "review:blocking"]);