@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/cli/stop-diagnostics.mjs

@@ -0,0 +1,114 @@
+// Bounded streaming failure excerpts for the Stop recipe relay.
+import { StringDecoder } from "node:string_decoder";
+
+export const STOP_DIAGNOSTIC_BYTES = 4096;
+export const STOP_RECIPE_BYTES = 6144;
+const LINE_BYTES = 1024;
+const SUCCESS = /^(?:PASS(?:\b|[-_])|GREEN\b|ok\b|[✔✓▶﹣]|TAP version \d+\b|\d+\.\.\d+(?:\s|$))|^#\s*Subtest:|^(?:#|ℹ)\s*(?:(?:pass|tests|suites|duration_ms|skipped|todo)\b|(?:fail|cancelled)\s+0\b)/i;
+const FAILURE = /^(?:#\s*)?(?:FAIL(?:ED|URE|URES)?(?:\b|[-_])|RED\b|ERROR\b|ERR_[A-Z_]+\b|(?:Assertion|Type|Syntax|Range|Reference|Eval)?Error\b|not ok\b|[✗✖×])|^(?:#|ℹ)\s*(?:fail|cancelled)\s+[1-9]\d*\b|(?:^|\s)(?:error:|command not found\b|permission denied\b|No such file or directory\b)|^(?:verify|tests):.*(?:failed|failing|could not|cannot|refused|missing)/i;
+
+export function clipDiagnostic(value, limit) {
+    const text = String(value);
+    if (Buffer.byteLength(text) <= limit) return text;
+    const notice = " [clipped]";
+    const decoder = new StringDecoder("utf8");
+    return decoder.write(Buffer.from(text).subarray(0, limit - Buffer.byteLength(notice))) + notice;
+}
+
+function lines() {
+    const kept = [];
+    let bytes = 0, omitted = 0;
+    return {
+        add(line) {
+            const size = Buffer.byteLength(line) + 1;
+            if (bytes + size <= 2800) { kept.push(line); bytes += size; }
+            else omitted++;
+        },
+        get present() { return kept.length > 0; },
+        text: () => kept.join("\n") + (omitted ? `\n[${omitted} diagnostic lines omitted]` : ""),
+    };
+}
+
+export function stopDiagnostics() {
+    const failures = lines(), fallback = lines();
+    const streams = new Map();
+    let observed = false;
+    function flush(state) {
+        const decoder = new StringDecoder("utf8");
+        const text = decoder.write(Buffer.concat(state.chunks)) + (state.clipped ? " [line clipped]" : decoder.end());
+        const line = text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+        const trimmed = line.trim();
+        state.chunks = []; state.bytes = 0; state.clipped = false;
+        if (!trimmed) return;
+        const indent = line.length - line.trimStart().length;
+        if (state.todoIndent !== null) {
+            if (indent === state.todoIndent + 2 && trimmed === state.todoEnd) { state.todoIndent = null; return; }
+            if (indent > state.todoIndent) return;
+            state.todoIndent = null;
+        }
+        const tapExpected = /^(?:ok|not ok)\s+\d+\b.*(?<!\\)#\s*(?:TODO|SKIP)\b/i.test(trimmed);
+        const specAnnotated = /^[⚠✖✗].*\(\d+(?:\.\d+)?ms\)\s+#\s*\S/.test(trimmed);
+        const specExpected = /^⚠.*#\s*TODO\b/i.test(trimmed)
+            || (specAnnotated && (trimmed.startsWith("⚠") || !/\(\d+(?:\.\d+)?ms\)$/.test(trimmed)));
+        if (tapExpected || specExpected) {
+            state.todoIndent = indent; state.todoEnd = tapExpected ? "..." : "}"; state.context = 0; state.location = null;
+            return;
+        }
+        if (/^(?:---|\.\.\.)$|^duration_ms:\s*\d+(?:\.\d+)?$|^type:\s*['"](?:test|suite)['"]$/.test(trimmed)) return;
+        if (trimmed === "✖ failing tests:") { state.context = 0; state.location = null; return; }
+        if (/^test at .+:\d+(?::\d+)?$/.test(trimmed)) { state.location = line; return; }
+        if (SUCCESS.test(trimmed)) { state.context = 0; state.location = null; return; }
+        if (FAILURE.test(trimmed)) {
+            if (state.location) failures.add(state.location);
+            state.location = null;
+            failures.add(line); state.context = 8;
+        }
+        else if (state.context && /^\s|^#\s/.test(line)) { failures.add(line); state.context--; }
+        else {
+            if (state.location) fallback.add(state.location);
+            state.location = null;
+            fallback.add(line); state.context = 0;
+        }
+    }
+    function add(name, chunk) {
+        observed = true;
+        name = name === "stderr" ? "stderr" : "stdout";
+        if (!streams.has(name)) streams.set(name, { chunks: [], bytes: 0, clipped: false, context: 0, todoIndent: null, location: null });
+        const state = streams.get(name);
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        let start = 0;
+        while (start < buffer.length) {
+            const newline = buffer.indexOf(10, start);
+            const end = newline < 0 ? buffer.length : newline;
+            const size = Math.min(LINE_BYTES - state.bytes, end - start);
+            if (size) { state.chunks.push(Buffer.from(buffer.subarray(start, start + size))); state.bytes += size; }
+            if (end - start > size) state.clipped = true;
+            if (newline < 0) break;
+            flush(state);
+            start = newline + 1;
+        }
+    }
+    return {
+        add,
+        finish(result) {
+            const raw = Array.isArray(result.diagnostics) ? result.diagnostics : [];
+            if (!observed && result.output) {
+                const suffix = raw.length ? `\n${raw.join("\n")}` : "";
+                const output = suffix && result.output.endsWith(suffix) ? result.output.slice(0, -suffix.length) : result.output;
+                if (output) add("stdout", output);
+            }
+            for (const state of streams.values()) if (state.bytes || state.clipped) flush(state);
+            for (const state of streams.values()) if (state.location) fallback.add(state.location);
+            const structured = [
+                ...(result.interrupted ? [`interrupted by ${clipDiagnostic(result.interrupted, 64)}`] : []),
+                ...(result.timedOut ? ["recipe time limit reached"] : []),
+            ];
+            const reasons = [...structured, ...raw.filter(reason => !structured.includes(reason))];
+            const runner = reasons.length
+                ? `executor: ${reasons.slice(0, 3).map(reason => clipDiagnostic(reason, 192)).join("; ")}${reasons.length > 3 ? ` [${reasons.length - 3} executor reasons omitted]` : ""}\n` : "";
+            const body = failures.present ? failures.text() : fallback.present
+                ? `unrecognized output (no failure marker identified):\n${fallback.text()}` : "no failure diagnostic identified";
+            return clipDiagnostic(`${runner}${body}\nRun verification explicitly for complete output.`, STOP_DIAGNOSTIC_BYTES);
+        },
+    };
+}

package/cli/stop-gate.mjs

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
-// The Stop-gate runner — "done" is not a thing an agent may simply declare.
-//
-// A crashed hook fails open (Claude Code 2.1.220), so every failure path here returns a verdict instead of throwing.
+// Stop-gate: bounded recipe and work checks. Hook failures need a verdict, since a crashed hook fails open.
 
 import fs from "node:fs";
 import os from "node:os";
@@ -11,6 +9,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { isInside } from "./inside.mjs";
 import { recipeSet } from "./recipe-set.mjs";
+import { runRecipe } from "./recipe-runner.mjs";
+import { readStopPolicy } from "./stop-policy.mjs";
+import { stopDiagnostics, clipDiagnostic, STOP_RECIPE_BYTES } from "./stop-diagnostics.mjs";
 
 const PROJECT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const WORKSPACE = path.resolve(PROJECT, process.env.PORTULAN_WORKSPACE || ".portulan");
@@ -87,9 +88,6 @@ export const MAX_TOTAL_BLOCKS = 9;
 // restarting both caps. Set above MAX_TOTAL_BLOCKS, so a session whose id holds meets the other bounds first.
 export const MAX_CHAIN_BLOCKS = 12;
 
-// Well inside the host's 600 s hook timeout, so a hung recipe meets a verdict here first.
-const RECIPE_TIMEOUT_MS = 90_000;
-
 function counterFile(sessionId, dir, root = REPO) {
     const digest = (v) => {
         let h = 0;
@@ -189,11 +187,6 @@ function allow() {
     process.exit(0);
 }
 
-function block(reason) {
-    process.stdout.write(`${JSON.stringify({ decision: "block", reason })}\n`);
-    process.exit(0);
-}
-
 function defaultRecipe() {
     try {
         const manifest = JSON.parse(fs.readFileSync(path.join(WORKSPACE, "workspace.json"), "utf8"));
@@ -201,9 +194,28 @@ function defaultRecipe() {
         const set = recipeSet(manifest, { packs: [] });
         if (!set.ok) return null;
         const recipe = set.recipes.find((r) => r.id === set.default);
-        return recipe ? { id: recipe.id, run: recipe.run } : null;
-    } catch {
-        return null;
+        return recipe ? { id: recipe.id, run: recipe.run, timeout: readStopPolicy(manifest).seconds } : null;
+    } catch (error) {
+        return { error: error.message };
+    }
+}
+
+function handoffPolicy(tree) {
+    const file = path.join(tree.workspace, "workspace.json");
+    try {
+        const manifest = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new Error("the manifest must be an object");
+        const slots = manifest.slots;
+        if (slots === undefined) return { directory: null };
+        if (!slots || typeof slots !== "object" || Array.isArray(slots)) throw new Error("slots must be an object");
+        if (!Object.hasOwn(slots, "handoffs")) return { directory: null };
+        if (typeof slots.handoffs !== "string" || !/^[^#?:/][^#?:]*\/$/.test(slots.handoffs)) {
+            throw new Error("slots.handoffs must be a directory path ending in /, without a fragment, query or colon");
+        }
+        return { directory: path.resolve(tree.workspace, slots.handoffs) };
+    } catch (error) {
+        const why = error instanceof SyntaxError ? "the manifest is not valid JSON" : error.code ?? error.message;
+        return { directory: null, error: `could not read the record policy from ${file}: ${why}. Fix the manifest before ending this work.` };
     }
 }
 
@@ -213,8 +225,8 @@ function didWork(root = REPO) {
     try {
         if (git(["status", "--porcelain"]).trim() !== "") return true;
     } catch {
-        process.stderr.write("portulan stop-gate: cannot read git status — the handoff check is not running.\n");
-        return false;
+        process.stderr.write("portulan stop-gate: cannot read git status — the work check is not running.\n");
+        return null;
     }
 
     try {
@@ -249,7 +261,7 @@ function didWork(root = REPO) {
         const degraded = (why, check) => {
             process.stderr.write(
                 `portulan stop-gate: could not compare by patch-id (${why}), so commits on no remote are ` +
-                    "being read as work. If this branch was rebase-merged the handoff demand may be spurious — " +
+                    "being read as work. If this branch was rebase-merged the work demand may be spurious — " +
                     `${check} and say so rather than working around the gate.\n`,
             );
             return true;
@@ -272,25 +284,27 @@ function didWork(root = REPO) {
         }
         return cherry.split("\n").some((line) => line.startsWith("+"));
     } catch {
-        process.stderr.write("portulan stop-gate: cannot determine whether this session did work — the handoff check is not running.\n");
-        return false;
+        process.stderr.write("portulan stop-gate: cannot determine whether this session did work — the work check is not running.\n");
+        return null;
     }
 }
 
-/** Today's handoffs as `{ own, recorded }`, `recorded` being clean and held by a remote at that path. */
-function handoffToday(stamp, tree = { root: REPO, workspace: WORKSPACE }) {
+/** Today's handoffs as `{ own, recorded }`, with remote content checked since two UTC days before their date. */
+function handoffToday(stamp, tree, handoffsDir) {
     let dated;
     try {
-        dated = fs.readdirSync(path.join(tree.workspace, "handoffs")).filter((f) => f.startsWith(stamp) && f.endsWith(".md"));
-    } catch {
+        dated = fs.readdirSync(handoffsDir).filter((f) => f.startsWith(stamp) && f.endsWith(".md"));
+    } catch (error) {
+        if (error.code !== "ENOENT") process.stderr.write(`portulan stop-gate: could not read the declared handoff series (${error.code ?? "read failed"}); no handoff was found.\n`);
         return { own: [], recorded: [] };
     }
-    const handoffsDir = path.join(tree.workspace, "handoffs");
     const dir = path.relative(tree.root, handoffsDir).split(path.sep).join("/");
     if (dir === "" || !isInside(tree.root, handoffsDir)) return { own: dated, recorded: [] };
     const git = (args) => execFileSync("git", args, { cwd: tree.root, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
     const own = [];
     const recorded = [];
+    const cutoff = new Date(`${stamp}T00:00:00Z`);
+    cutoff.setUTCDate(cutoff.getUTCDate() - 2);
     for (const name of dated) {
         const file = `:(literal)${dir}/${name}`;
         let unrecorded;
@@ -300,7 +314,7 @@ function handoffToday(stamp, tree = { root: REPO, workspace: WORKSPACE }) {
                 // By content, not commit: a rebase or squash merge pushes a handoff in a commit of its own.
                 // `--root`, or `log.showRoot=false` skips a root commit.
                 const blob = git(["rev-parse", `HEAD:./${dir}/${name}`]).trim();
-                unrecorded = git(["log", "-1", "--root", "--format=%h", "--remotes", `--find-object=${blob}`, "--", file]).trim() === "";
+                unrecorded = git(["log", "-1", "--root", "--format=%h", "--remotes", `--since=${cutoff.toISOString()}`, `--find-object=${blob}`, "--", file]).trim() === "";
             }
         } catch {
             process.stderr.write(`portulan stop-gate: could not tell whether ${name} is committed and pushed, so it counts as this tree's own.\n`);
@@ -325,14 +339,14 @@ function treeIdentity(root = REPO) {
 }
 
 // Refs on disk only: a fetch would put a round trip, or an offline host's timeout, inside every Stop.
-function handoffInHistory(stamp, tree = { root: REPO, workspace: WORKSPACE }, held = []) {
+function handoffInHistory(stamp, tree, handoffsDir, held = []) {
     try {
-        const handoffsDir = path.join(tree.workspace, "handoffs");
         const dir = path.relative(tree.root, handoffsDir).split(path.sep).join("/");
         if (dir === "" || !isInside(tree.root, handoffsDir)) return null;
+        const prefix = dir.replace(/[\\*?[\]]/g, "\\$&");
         const git = (args) => execFileSync("git", args, { cwd: tree.root, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
         // `:(glob)`, since git reads a bare `*` literally under `GIT_NOGLOB_PATHSPECS=1` (git 2.50.1).
-        const commit = git(["log", "-1", "--format=%H", "--all", "--not", "HEAD", "--", `:(glob)${dir}/${stamp}*`,
+        const commit = git(["log", "-1", "--format=%H", "--all", "--not", "HEAD", "--", `:(glob)${prefix}/${stamp}*`,
             ...held.map((name) => `:(exclude,literal)${dir}/${name}`)]).trim();
         if (!commit) return null;
         const refs = git(["branch", "--all", "--contains", commit, "--format=%(refname:short)"])
@@ -343,47 +357,45 @@ function handoffInHistory(stamp, tree = { root: REPO, workspace: WORKSPACE }, he
     }
 }
 
-function collectProblems(tree = { root: REPO, workspace: WORKSPACE, origin: "told", note: null }) {
+export function workNotice({ stamp, directory, identity, answeredElsewhere = "", recorded = [], found = "" }) {
+    if (directory === null) return `${identity} holds work that is not committed and pushed. Commit and push it, its why in the commit message.`;
+    const notCounted = recorded.length
+        ? `${recorded.map((f) => `\`${f}\``).join(", ")} ${recorded.length === 1 ? "is" : "are"} committed and pushed already, ` +
+          `so ${recorded.length === 1 ? "it records" : "they record"} work already recorded. `
+        : "";
+    return `no handoff dated ${stamp}${recorded.length ? " of this tree's own" : ""} in ${directory}, read from ` +
+        `${identity}${answeredElsewhere}. ${notCounted}` +
+        "This tree holds work that is not committed and pushed. Commit and push it, its why in the commit " +
+        "message, or end with a dated handoff naming what is open: where things stand, the open questions " +
+        `and the next action. Five lines is enough; absent is not.${found}`;
+}
+
+function workProblems(tree) {
     const problems = [];
-    let recipeGreen = false;
 
-    // Only the told workspace's recipe, run in the told root: one read from a tree the payload names would run what stdin chose.
-    const recipe = defaultRecipe();
-    if (!recipe) {
-        problems.push({
-            reason: "recipe",
-            text:
-                "could not read the workspace's default verify recipe from .portulan/workspace.json, so nothing " +
-                "verified this work. That is 'could not run', which blocks exactly as red does.",
-        });
-    } else {
-        try {
-            execFileSync("bash", ["-c", recipe.run], {
-                cwd: REPO,
-                encoding: "utf8",
-                timeout: RECIPE_TIMEOUT_MS,
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-            recipeGreen = true;
-        } catch (error) {
-            const code = error.status;
-            const output = `${error.stdout ?? ""}${error.stderr ?? ""}`.trim().split("\n").slice(-25).join("\n");
-            const CANNOT_RUN = new Set([2, 126, 127]);
-            const outcome = CANNOT_RUN.has(code) || code === undefined || code === null
-                ? `could not run (exit ${code ?? "no status"}) — the gate could not judge`
-                : `RED (exit ${code})`;
+    const policy = handoffPolicy(tree);
+    const handoffEnabled = policy.directory !== null;
+    if (policy.error) {
+        problems.push({ reason: "handoff", text: policy.error });
+        return { problems, handoffEnabled, handoffCleared: false };
+    }
+    if (!handoffEnabled) {
+        const work = didWork(tree.root);
+        if (work === true) {
             problems.push({
-                reason: "recipe",
-                text: `verify recipe \`${recipe.id}\` in ${REPO} — ${outcome}\n${output}`,
+                reason: "handoff",
+                text: workNotice({ identity: treeIdentity(tree.root), directory: null }),
             });
         }
+        return { problems, handoffEnabled, handoffCleared: work === false };
     }
 
     const stamp = today();
-    const handoffs = handoffToday(stamp, tree);
+    const handoffs = handoffToday(stamp, tree, policy.directory);
     const handoffPresent = handoffs.own.length > 0;
     // `handoffPresent` first: `didWork()` runs git several times and may warn about a handoff that is not owed.
-    if (!handoffPresent && didWork(tree.root)) {
+    const work = handoffPresent ? null : didWork(tree.root);
+    if (work === true) {
         const real = (dir) => {
             try {
                 return fs.realpathSync(dir);
@@ -395,39 +407,63 @@ function collectProblems(tree = { root: REPO, workspace: WORKSPACE, origin: "tol
             ? ` — the tree this session worked in, not the one this hook was told (${REPO})`
             : "";
         const { recorded } = handoffs;
-        const elsewhere = handoffInHistory(stamp, tree, recorded);
+        const elsewhere = handoffInHistory(stamp, tree, policy.directory, recorded);
         const found = elsewhere
             ? ` One dated ${stamp} does exist elsewhere in this repository's refs, at ` +
               `${elsewhere.commit}${elsewhere.ref ? ` on \`${elsewhere.ref}\`` : ""} — so this working tree may not be ` +
               "the tree that did the work. Check before writing a second one."
             : "";
-        const notCounted = recorded.length
-            ? `${recorded.map((f) => `\`${f}\``).join(", ")} ${recorded.length === 1 ? "is" : "are"} committed and pushed already, ` +
-              `so ${recorded.length === 1 ? "it records" : "they record"} work already recorded. `
-            : "";
         problems.push({
             reason: "handoff",
-            text:
-                `no handoff dated ${stamp}${recorded.length ? " of this tree's own" : ""} in ${path.join(tree.workspace, "handoffs")}, read from ` +
-                `${treeIdentity(tree.root)}${answeredElsewhere}. ${notCounted}` +
-                "This tree holds work that is not committed and pushed. Commit and push it, its why in the commit " +
-                "message, or end with a dated handoff naming what is open: where things stand, the open questions " +
-                `and the next action. Five lines is enough; absent is not.${found}`,
+            text: workNotice({ stamp, directory: policy.directory, identity: treeIdentity(tree.root), answeredElsewhere, recorded, found }),
         });
     }
 
-    return { problems, recipeGreen };
+    return { problems, handoffEnabled, handoffCleared: handoffPresent || work === false };
+}
+
+export async function runStopRecipe(recipe, execute = runRecipe) {
+    const problem = text => ({ reason: "recipe", text: clipDiagnostic(text, STOP_RECIPE_BYTES) });
+    if (!recipe || recipe.error) return {
+        reason: "recipe",
+        text: clipDiagnostic(`could not read the workspace's default verify recipe from ${clipDiagnostic(path.join(WORKSPACE, "workspace.json"), 512)}: ${clipDiagnostic(recipe?.error ?? "no runnable default", 4096)}. Nothing verified this work.`, STOP_RECIPE_BYTES),
+    };
+    const label = clipDiagnostic(`verify recipe \`${clipDiagnostic(recipe.id, 512)}\` in ${clipDiagnostic(REPO, 512)}`, 1100);
+    try {
+        const diagnostics = stopDiagnostics();
+        const result = await execute(recipe, { root: REPO, env: process.env, timeout: recipe.timeout * 1000, mergeOutput: false, onOutput: diagnostics.add });
+        if (result.outcome === "green") return null;
+        const outcome = result.timedOut
+            ? `could not run: timed out after ${clipDiagnostic(recipe.timeout, 64)} s — the gate could not judge`
+            : result.outcome === "red" ? `RED (exit ${clipDiagnostic(result.code, 64)})` : `could not run (exit ${clipDiagnostic(result.code ?? "no status", 64)}) — the gate could not judge`;
+        return problem(`${label} — ${outcome}\n${diagnostics.finish(result)}`);
+    } catch (error) {
+        return problem(`${label} could not run — ${clipDiagnostic(error?.message ?? error, 4096)}; the gate could not judge. Run verification explicitly.`);
+    }
+}
+
+async function collectProblems(tree, state, chain) {
+    const work = workProblems(tree);
+    const recipeCapped = (state.counts.recipe ?? 0) >= MAX_BLOCKS;
+    const handoffCapped = work.problems.some(p => p.reason === "handoff") && (state.counts.handoff ?? 0) >= MAX_BLOCKS;
+    const skip = recipeCapped || handoffCapped || state.total >= MAX_TOTAL_BLOCKS || chain > MAX_CHAIN_BLOCKS;
+    const recipeProblem = skip ? {
+        reason: "recipe", charge: false, capped: recipeCapped,
+        text: "verify recipe not rerun: this Stop is released at a refusal bound. No result was measured on this Stop; existing obligations remain unresolved. Run verification explicitly before claiming done.",
+    } : await runStopRecipe(defaultRecipe());
+    return { ...work, problems: [...(recipeProblem ? [recipeProblem] : []), ...work.problems], recipeGreen: !skip && recipeProblem === null };
 }
 
-export function verdict({ problems, counts = {}, total = 0, chain = 0, max = MAX_BLOCKS, maxTotal = MAX_TOTAL_BLOCKS, maxChain = MAX_CHAIN_BLOCKS }) {
+export function verdict({ problems, counts = {}, total = 0, chain = 0, max = MAX_BLOCKS, maxTotal = MAX_TOTAL_BLOCKS, maxChain = MAX_CHAIN_BLOCKS, handoffEnabled = true }) {
     if (problems.length === 0) return { action: "allow" };
 
     const text = problems.map((p) => p.text).join("\n\n");
-    const spent = problems.map((p) => p.reason).filter((reason) => (counts[reason] ?? 0) > max);
+    const spent = problems.filter((p) => p.capped || (counts[p.reason] ?? 0) > max).map((p) => p.reason);
+    const label = (reason) => !handoffEnabled && reason === "handoff" ? "work" : reason;
 
     if (spent.length || total > maxTotal || chain > maxChain) {
         const bound = spent.length
-            ? `the cap of ${max} consecutive refusals for \`${spent.join("`, `")}\` was reached`
+            ? `the cap of ${max} consecutive refusals for \`${spent.map(label).join("`, `")}\` was reached`
             : total > maxTotal
               ? `the absolute ceiling of ${maxTotal} refusals was reached (no single reason had reached its cap of ${max})`
               : `${chain} consecutive hook-provoked stops were seen in this tree, past the chain bound of ${maxChain} — ` +
@@ -437,13 +473,13 @@ export function verdict({ problems, counts = {}, total = 0, chain = 0, max = MAX
             action: "release",
             message:
                 `PORTULAN STOP-GATE — ${bound}. This session is ending **RED**, not done.\n` +
-                `Nothing below was fixed, and the session ending does not fix it. Say so in the handoff and in any\n` +
+                `Nothing below was fixed, and the session ending does not fix it. Say so in ${handoffEnabled ? "the handoff and in any" : "any"}\n` +
                 `report of this work; a task that ends at the cap is an unfinished task with a stop attached.\n\n` +
                 `${text}\n`,
         };
     }
 
-    const tally = problems.map((p) => `${p.reason} ${counts[p.reason] ?? 0}/${max}`).join(", ");
+    const tally = problems.map((p) => `${label(p.reason)} ${counts[p.reason] ?? 0}/${max}`).join(", ");
     return {
         action: "block",
         message:
@@ -453,7 +489,14 @@ export function verdict({ problems, counts = {}, total = 0, chain = 0, max = MAX
     };
 }
 
-function main() {
+export function stopOutput(result) {
+    return {
+        stdout: result.action === "block" ? JSON.stringify({ decision: "block", reason: result.message }) : "",
+        stderr: result.action === "release" ? result.message : "",
+    };
+}
+
+async function main() {
     let payload = {};
     try {
         payload = JSON.parse(fs.readFileSync(0, "utf8"));
@@ -466,26 +509,26 @@ function main() {
     const tree = resolveSessionTree(payload.cwd);
     if (tree.note) process.stderr.write(`portulan stop-gate: ${tree.note}; answering about ${REPO} instead.\n`);
 
-    const { problems, recipeGreen } = collectProblems(tree);
+    const prior = readCount(counterFile(sessionId, os.tmpdir()));
+    const chain = bumpChain(payload.stop_hook_active === true, os.tmpdir(), tree.root);
+    const { problems, recipeGreen, handoffEnabled, handoffCleared } = await collectProblems(tree, prior, chain);
 
     // The session's counts stay on the told root, so a `cwd` that moves mid-session cannot restart them.
     if (recipeGreen) clearReason(sessionId, "recipe");
-    if (!problems.some((p) => p.reason === "handoff")) clearReason(sessionId, "handoff");
+    if (handoffCleared) clearReason(sessionId, "handoff");
 
     const state = problems.length === 0
         ? { counts: {}, total: 0 }
-        : bumpCount(sessionId, [...new Set(problems.map((p) => p.reason))]);
-    const chain = bumpChain(problems.length > 0 && payload.stop_hook_active === true, os.tmpdir(), tree.root);
-    const result = verdict({ problems, counts: state.counts, total: state.total, chain });
-
-    if (result.action === "allow") allow();
-    if (result.action === "release") {
-        process.stderr.write(result.message);
-        allow();
-    }
-    block(result.message);
+        : bumpCount(sessionId, [...new Set(problems.filter(p => p.charge !== false).map((p) => p.reason))]);
+    if (problems.length === 0) bumpChain(false, os.tmpdir(), tree.root);
+    const result = verdict({ problems, counts: state.counts, total: state.total, chain, handoffEnabled });
+
+    const output = stopOutput(result);
+    if (output.stderr) process.stderr.write(output.stderr);
+    if (output.stdout) process.stdout.write(`${output.stdout}\n`);
+    allow();
 }
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
-    main();
+    await main();
 }

package/cli/stop-policy.mjs

@@ -0,0 +1,14 @@
+// Stop recipe deadline policy.
+export const DEFAULT_STOP_TIMEOUT = 90;
+export const STOP_HOOK_MARGIN = 60;
+export const MAX_STOP_TIMEOUT = Math.floor((2 ** 31 - 1) / 1000) - STOP_HOOK_MARGIN;
+
+export function readStopPolicy(manifest) {
+    const seconds = manifest?.verify?.stopTimeout;
+    if (seconds === undefined) return { seconds: DEFAULT_STOP_TIMEOUT, declared: false };
+    const spec = manifest?.portulan?.spec;
+    const version = typeof spec === "string" ? /^(\d+)\.(\d+)$/.exec(spec) : null;
+    if (!version || Number(version[1]) !== 2 || Number(version[2]) < 14) throw new Error("verify.stopTimeout requires portulan.spec 2.14 or a later minor on major 2");
+    if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > MAX_STOP_TIMEOUT) throw new Error(`verify.stopTimeout must be an integer from 1 to ${MAX_STOP_TIMEOUT} seconds`);
+    return { seconds, declared: true };
+}

package/cli/symbols.mjs

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
+import { HTML_ENTITIES } from "./html-entities.mjs";
 
 const USAGE = "usage: node cli/symbols.mjs <file>... | <file.md>#<heading>... | --find <name>...";
 
@@ -764,7 +765,14 @@ function order(entries) {
 // 5. Markdown: headings, and the section under each
 // ===========================================================================================
 
-// Headings as CommonMark reads them, outside fences, HTML comments and frontmatter; a setext heading in a list item is missed.
+// Top-level headings; list-container headings and full CommonMark block parsing are outside this reader.
+
+function characterReference(reference) {
+    if (!reference.startsWith("#")) return Object.hasOwn(HTML_ENTITIES, reference) ? HTML_ENTITIES[reference] : `&${reference};`;
+    const hex = /^#x/i.test(reference);
+    const point = Number.parseInt(reference.slice(hex ? 2 : 1), hex ? 16 : 10);
+    return String.fromCodePoint(point === 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff) ? 0xfffd : point);
+}
 
 /** A heading's text as it reads rendered: a code span's content kept, links and images their text, and emphasis, tags and escapes gone. */
 function plainText(title) {
@@ -772,9 +780,8 @@ function plainText(title) {
         text
             .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
             .replace(/!?\[([^\]]*)\]\[[^\]]*\]/g, "$1")
-            .replace(/<[^>]*>/g, "")
-            .replace(/\\([!-/:-@[-`{-~])/g, "$1")
-            .replace(/(^|[^\p{L}\p{N}*_])[*_]+|[*_]+(?=[^\p{L}\p{N}*_]|$)/gu, "$1");
+            .replace(/\\([!-/:-@[-`{-~])|<([A-Za-z][A-Za-z0-9+.-]{1,31}:[^<>\x00-\x20]*|[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?)>|<[^>]*>|&(#\d{1,7}|#[xX][\da-fA-F]{1,6}|[A-Za-z][A-Za-z0-9]*);|(^|[^\p{L}\p{N}*_])[*_]+|[*_]+(?=[^\p{L}\p{N}*_]|$)/gu,
+                (match, escaped, autolink, reference, lead) => escaped ?? autolink ?? (reference ? characterReference(reference) : lead ?? ""));
     let out = "";
     let at = 0;
     for (const span of title.matchAll(/(`+)(.+?)\1(?!`)/g)) {
@@ -794,6 +801,15 @@ const loose = (text) => plainText(text).replace(/\s+/g, " ").trim().toLowerCase(
 // A line that opens a block other than a paragraph, so no `=` or `-` line under it makes it a heading.
 const NOT_PARAGRAPH = /^(?: {4}|\t| {0,3}(?:>|[-*+](?:[ \t]|$)|\d{1,9}[.)](?:[ \t]|$)|<[A-Za-z/!?]|\|))/;
 const RULE = /^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})$/;
+const HEADING_OR_FENCE = /^(?:#{1,6}(?:[ \t]|$)|`{3,}|~{3,})/;
+
+const startsListParagraph = (text) => text.trim() !== "" && !NOT_PARAGRAPH.test(text) && !RULE.test(text) && !HEADING_OR_FENCE.test(text);
+
+function columns(text, start = 0) {
+    let col = start;
+    for (const char of text) col += char === "\t" ? 4 - col % 4 : 1;
+    return col;
+}
 
 /** The outline of a Markdown file: `{lines, bytes, entries}`, an entry per heading, nested by level. */
 export function outlineMd(src) {
@@ -811,8 +827,10 @@ export function outlineMd(src) {
     }
     let fence = null;
     let comment = false;
-    let para = null; // the line a paragraph opened at, at the margin, while it is open
+    let para = null; // the line the current paragraph opened at
     let above = "start"; // what the line above was: start, blank, heading, rule, para or other
+    const listIndents = [];
+    let listParagraph = false;
     for (; i < lines; i++) {
         const line = at(i);
         if (fence) {
@@ -829,6 +847,36 @@ export function outlineMd(src) {
             }
             continue;
         }
+        const indent = columns(/^[ \t]*/.exec(line)[0]);
+        const marker = !RULE.test(line) && /^([ \t]*)([-*+]|\d{1,9}[.)])([ \t]+|$)/.exec(line);
+        if (marker && (indent <= 3 || (listIndents.length && indent < listIndents.at(-1) + 4))) {
+            const end = indent + marker[2].length;
+            const padding = columns(marker[3], end) - end;
+            while (listIndents.length && listIndents.at(-1) > indent) listIndents.pop();
+            listIndents.push(end + (padding >= 1 && padding <= 4 ? padding : 1));
+            listParagraph = padding <= 4 && startsListParagraph(line.slice(marker[0].length));
+            para = null;
+            above = "other";
+            continue;
+        }
+        if (listIndents.length) {
+            if (line.trim() === "") {
+                listParagraph = false;
+            } else if (indent >= listIndents[0] || (listParagraph && !RULE.test(line) && !/^ {0,3}(?:#{1,6}(?:[ \t]|$)|>|`{3,}|~{3,}|<)/.test(line))) {
+                if (indent >= listIndents[0]) {
+                    while (listIndents.at(-1) > indent) listIndents.pop();
+                    listParagraph = (listParagraph || indent < listIndents.at(-1) + 4) && startsListParagraph(line.trimStart());
+                }
+                para = null;
+                above = "other";
+                continue;
+            } else {
+                listIndents.length = 0;
+                listParagraph = false;
+                para = null;
+                above = "blank";
+            }
+        }
         const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
         if (open && !(open[1][0] === "`" && open[2].includes("`"))) {
             fence = new RegExp(`^ {0,3}${open[1][0]}{${open[1].length},}[ \\t]*$`);
@@ -843,7 +891,7 @@ export function outlineMd(src) {
         }
         const atx = /^ {0,3}(#{1,6})(?:[ \t]+|$)(.*)$/.exec(line);
         if (atx) {
-            found.push({ start: i + 1, level: atx[1].length, title: atx[2].replace(/(?:^|[ \t]+)#+[ \t]*$/, "").trim() });
+            found.push({ start: i + 1, level: atx[1].length, title: atx[2].replace(/(?:^|[ \t]+)#+[ \t]*$/, "").replace(/^[ \t]+|[ \t]+$/g, "") });
             para = null;
             above = "heading";
             continue;
@@ -866,8 +914,7 @@ export function outlineMd(src) {
             para = null;
             above = "other";
         } else if (above !== "para" && above !== "other") {
-            // A paragraph a setext line may underline opens at the margin; one indented may sit in a list.
-            para = /^\S/.test(line) ? i + 1 : null;
+            para = i + 1;
             above = para === null ? "other" : "para";
         }
     }