@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/spend-offer.md

@@ -0,0 +1,53 @@
+# Init's spend offer
+
+`init` offers `spend.multipliers` and `spend.horizon.requests` independently. Each is
+declared only after accepting its interview answer or providing `--multipliers
+'<JSON>'` / `--horizon <positive integer>`. The answers file takes the same keys as
+strings; flags win. A declined offer leaves the key absent. A pointer has no spend
+policy and refuses these options. Either declaration requires spec 2.12.
+
+For Claude Code, the helper reads model IDs, timestamps, repository paths and usage
+presence from local assistant records. It selects the latest main-context record
+for this repository, ignoring synthetic records, sidechains, separate subagents
+and foreign paths. Conflicting latest models, missing models or unreadable records
+give a general offer with a reason. Malformed lines are counted and disclosed.
+Conversation content is not inspected. A configured model does not replace a
+recorded one. The last recorded model need not be the next session's model.
+
+The offer tries these sources in order:
+
+1. A matching `modelPricing.overrides` row in the system managed settings file:
+   `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS,
+   `/etc/claude-code/managed-settings.json` on Linux, or
+   `C:\Program Files\ClaudeCode\managed-settings.json` on Windows. Exact model IDs
+   precede supported canonical IDs with an eight-digit snapshot suffix removed.
+   All four rates must be finite numbers in 0–10000. `input` and `cacheRead` must
+   also be positive, the read/input ratio at most one, and write/input at least
+   one, for `spend` to represent them. One `cacheWrite` rate supplies both
+   lifetimes; a global multiplier cancels in ratios. Unusable rows fall through
+   with a reason. User/project/local `modelPricing` settings are ignored, as the
+   host ignores them. See the [host contract](https://code.claude.com/docs/en/settings-reference#modelpricing).
+2. The table embedded in `spend-offer.mjs`, checked **2026-11-09** against the
+   [vendor's price page](https://platform.claude.com/docs/en/about-claude/pricing).
+   The explicit Claude API model IDs use cache reads at 0.025 for Fable/Mythos
+   5.1/5.2, 0.05 for Opus/Sonnet 5.5, and 0.1 for the other listed IDs; writes are
+   1.25 at five minutes and 2 at one hour. This is a dated offer, updated with the
+   product, without a runtime fetch. Unknown IDs and provider-specific aliases
+   are not guessed. Only known canonical IDs and their eight-digit snapshots
+   normalize; custom gateway overrides require an exact match.
+3. General figures: read 0.1, writes 1.25/2. The horizon offered is 20 requests
+   still to go, which the task or workspace should replace with its own estimate.
+
+The file is **not an effective-settings resolver**. A nonempty JSON drop-in set
+at `managed-settings.d` makes the file source unavailable rather than pretending
+to merge it. Remote managed settings, MDM/plist/registry, policy helpers and
+embedding-host sources are not inspected; they can supersede the file. The offer
+names that condition. Native Windows discovery is not demonstrated here. See
+[managed source precedence](https://code.claude.com/docs/en/managed-settings).
+Other hosts and unsupported models get the general offer. A declaration is the
+workspace's value, not a verified billing rate.
+
+`spend-offer.test.mjs` uses injected local transcript and managed-file paths. All
+verification is offline; no recipe reads the operator's usage records or managed
+pricing. Accepted drafts are validated by `doctor`, and `compile` carries their
+figures onto advisory commands.

package/cli/spend-offer.mjs

@@ -0,0 +1,93 @@
+// Local evidence for init's optional spend declaration.
+import fs from "node:fs";
+import path from "node:path";
+import { GENERAL_READ, WRITE_BY_LIFETIME, HORIZON, hostPaths, transcriptFiles, readSpend } from "./ledger.mjs";
+import { isInside } from "./inside.mjs";
+
+export const PRICE_DATE = "2026-11-09";
+export const PRICE_SOURCE = "https://platform.claude.com/docs/en/about-claude/pricing";
+export const PRICE_READS = {
+    "claude-fable-5-2": 0.025, "claude-mythos-5-2": 0.025,
+    "claude-fable-5-1": 0.025, "claude-mythos-5-1": 0.025,
+    "claude-opus-5-5": 0.05, "claude-sonnet-5-5": 0.05,
+    "claude-haiku-5-5": 0.1, "claude-fable-5": 0.1, "claude-mythos-5": 0.1,
+    "claude-opus-5": 0.1, "claude-sonnet-5": 0.1,
+    "claude-opus-4-8": 0.1, "claude-opus-4-7": 0.1, "claude-opus-4-6": 0.1,
+    "claude-opus-4-5": 0.1, "claude-opus-4-1": 0.1, "claude-opus-4": 0.1,
+    "claude-sonnet-4-6": 0.1, "claude-sonnet-4-5": 0.1, "claude-sonnet-4": 0.1,
+    "claude-haiku-4-5": 0.1,
+};
+
+export function recordedModel(target, projects) {
+    let latest = -Infinity;
+    const models = new Set();
+    let malformed = 0;
+    try {
+        for (const { file, agent } of transcriptFiles(projects, [target])) {
+            if (agent !== null) continue;
+            for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+                if (!line.trim()) continue;
+                let r;
+                try { r = JSON.parse(line); } catch { malformed++; continue; }
+                if (r?.type !== "assistant" || r.isSidechain || r.agentId || !r.message?.usage || typeof r.message.usage !== "object" || Array.isArray(r.message.usage) || r.message.model === "<synthetic>" || typeof r.timestamp !== "string" || typeof r.cwd !== "string" || !path.isAbsolute(r.cwd) || !isInside(target, r.cwd)) continue;
+                const at = Date.parse(r.timestamp);
+                if (!Number.isFinite(at) || at < latest) continue;
+                if (at > latest) { latest = at; models.clear(); }
+                models.add(typeof r.message.model === "string" && r.message.model ? r.message.model : null);
+            }
+        }
+    } catch (error) {
+        return { model: null, reason: `recorded model could not be read (${error.code ?? "unreadable"})` };
+    }
+    const model = models.size === 1 ? [...models][0] : null;
+    const reason = model === null ? (models.size > 1 ? "conflicting latest recorded models" : "no recorded model") : `last recorded model ${JSON.stringify(model)}`;
+    return { model, reason: reason + (malformed ? `; ignored ${malformed} malformed record(s)` : "") };
+}
+
+export function managedPricingFile(platform = process.platform) {
+    if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
+    if (platform === "win32") return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
+    return "/etc/claude-code/managed-settings.json";
+}
+
+function hostMultipliers(model, canonical, file) {
+    if (file === null) return { reason: "file-based managed pricing not supplied" };
+    try {
+        const dropins = path.join(path.dirname(file), "managed-settings.d");
+        if (fs.existsSync(dropins) && fs.readdirSync(dropins).some(name => name.endsWith(".json"))) return { reason: "managed-settings.d may supersede file pricing; drop-ins are not resolved" };
+        if (!fs.statSync(file).isFile()) return { reason: "managed pricing is not a regular file" };
+        const pricing = JSON.parse(fs.readFileSync(file, "utf8"))?.modelPricing;
+        const overrides = pricing?.overrides;
+        if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) return { reason: "no file-based modelPricing override" };
+        const row = Object.hasOwn(overrides, model) ? overrides[model] : canonical !== null && Object.hasOwn(overrides, canonical) ? overrides[canonical] : null;
+        if (row === null) return { reason: "no matching file-based modelPricing override" };
+        if (!row || ["input", "output", "cacheRead", "cacheWrite"].some(key => typeof row[key] !== "number" || !Number.isFinite(row[key]) || row[key] < 0 || row[key] > 10000)) return { reason: "invalid file-based modelPricing override" };
+        try {
+            const multipliers = { read: row.cacheRead / row.input, write: { "5m": row.cacheWrite / row.input, "1h": row.cacheWrite / row.input } };
+            readSpend({ multipliers }, "host offer");
+            return { multipliers };
+        } catch { return { reason: "file-based modelPricing override is unrepresentable by spend" }; }
+    } catch (error) {
+        return { reason: error.code === "ENOENT" ? "no file-based managed pricing" : `file-based managed pricing unreadable (${error.code ?? "invalid JSON"})` };
+    }
+}
+
+export function spendOffer(target, options = {}) {
+    const paths = hostPaths(options.env, options.home);
+    const recorded = options.projects !== undefined ? recordedModel(target, options.projects) : paths.why ? { model: null, reason: "host record path is not absolute" } : recordedModel(target, paths.projects);
+    const { model } = recorded;
+    const normalized = model?.replace(/-\d{8}$/, "");
+    const canonical = normalized && Object.hasOwn(PRICE_READS, normalized) ? normalized : null;
+    const host = model === null ? { reason: "host pricing needs a recorded model" } : hostMultipliers(model, canonical, options.managedFile === undefined ? managedPricingFile(options.platform) : options.managedFile);
+    const source = host.multipliers ? "file-based managed modelPricing (conditional on this file being active)" : canonical !== null ? `Claude Code table ${PRICE_DATE}, ${PRICE_SOURCE}` : "general multipliers";
+    const multipliers = host.multipliers ?? { read: canonical === null ? GENERAL_READ : PRICE_READS[canonical], write: { ...WRITE_BY_LIFETIME } };
+    return { multipliers, horizon: HORIZON, source, reason: `${recorded.reason}; ${host.reason ?? "one cacheWrite rate supplies both lifetimes; a global multiplier cancels"}` };
+}
+
+export function spendOfferLines(offer) {
+    return [
+        `spend.multipliers offer ${JSON.stringify(offer.multipliers)} — ${offer.source}; ${offer.reason}`,
+        `spend.horizon offer {"requests":${offer.horizon}} — requests still to go, not requests already used; choose a task's expected remainder`,
+        "Only accepted answers or explicit --multipliers '<JSON>' / --horizon <requests> declare these at spec 2.12. Remote, MDM/registry, helper and embedding-host pricing are not inspected; other providers and unsupported model IDs use general figures. Confirm against your rates and next model.",
+    ];
+}

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();
 }