@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/cli/persona-routing.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// Regrade the acquired core-persona records and check their shipped routing without a model.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { CORPUS, grade, price } from "../evals/ab/personas/grader.mjs";
+
+export const CAPTURE = "evals/ab/personas/acquisition.json";
+export const CAPTURE_SHA256 = "ff3688658bc20af6b78e834a5149ea6bd52bc88027b0340ec98cb52430c6d641";
+export const ROLES = ["implementer", "reviewer", "librarian"];
+export const ROUTING = { model: "inherit", effort: null, omitClaudeMd: false, cacheLifetime: "5m" };
+const CLASSES = ["uncached", "written5m", "written1h", "writtenUnknown", "read", "output"];
+const BAD_DESCRIPTION = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+const sha = bytes => createHash("sha256").update(bytes).digest("hex");
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const hash = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const demand = (ok, why) => { if (!ok) throw new Finding(why); };
+export class Finding extends Error {}
+
+export function bindingContract(text) {
+    demand(typeof text === "string" && text.startsWith("---\n") && !text.includes("\uFFFD"), "binding frontmatter is unusable");
+    const close = text.indexOf("\n---\n", 4);
+    demand(close !== -1, "binding frontmatter is unclosed");
+    const lines = text.slice(4, close).split("\n");
+    const descriptions = lines.filter(line => /^\s*description\s*:/.test(line));
+    demand(descriptions.length === 1 && /^description: \S/.test(descriptions[0]), "binding needs one nonempty single-line description");
+    for (const line of lines.slice(lines.indexOf(descriptions[0]) + 1)) {
+        if (/^[A-Za-z_][\w-]*\s*:/.test(line)) break;
+        demand(!line.trim() || /^\s*#/.test(line), "binding description has a multiline continuation");
+    }
+    const raw = descriptions[0].slice("description: ".length);
+    demand(!BAD_DESCRIPTION.test(raw), "binding description contains a control or line separator");
+    let value;
+    if (raw.startsWith('"')) {
+        try { value = JSON.parse(raw); } catch {}
+    } else if (raw.startsWith("'")) {
+        if (/^'(?:[^']|'')*'$/.test(raw)) value = raw.slice(1, -1).replaceAll("''", "'");
+    } else if (/^[\p{L}_][^:#{}\[\]\r\n]*$/u.test(raw) && !/^(true|false|null)$/i.test(raw.trim())) value = raw;
+    demand(typeof value === "string" && value.trim() && !BAD_DESCRIPTION.test(value), "binding description is not a usable single-line scalar");
+    return text.slice(0, 4) + lines.map(line => line === descriptions[0] ? "description: <description>" : line).join("\n") + text.slice(close);
+}
+
+export function costOf(call) {
+    const parent = price(call.usage.parent), child = price(call.usage.child);
+    return { parent, child, observed: parent.observed + child.observed, normalized: parent.normalized + child.normalized };
+}
+
+export function summarize(record) {
+    const arms = Object.fromEntries(["a", "b"].map(arm => {
+        const turns = record.turns.filter(turn => turn.arm === arm);
+        const costs = turns.map(costOf);
+        return [arm, { passed: turns.filter(turn => grade(CORPUS.cases.find(task => task.id === turn.task), turn.answer).ok).length,
+            cases: turns.length, observed: costs.reduce((sum, value) => sum + value.observed, 0), normalized: costs.reduce((sum, value) => sum + value.normalized, 0) }];
+    }));
+    return { arms, mediumWinsObservedCorpus: arms.b.passed === 3 && arms.b.normalized < arms.a.normalized,
+        shipped: ROUTING, scope: "retained policy; one observed model and three cases; no global medium default earned" };
+}
+
+export function register(record) {
+    const result = summarize(record);
+    const lines = [`# ${record.role} — acquired routing comparison`, "", `Host: ${record.host}. Concrete model: ${record.model}.`, "",
+        "A uses the shipped inherited model and undeclared child effort (observed high). B requests medium through the native child tool. Each case has one attempt per arm.", "",
+        "| Arm | Semantic passes | Observed cost index | Cold-normalized cost index |", "|---|---:|---:|---:|"];
+    for (const arm of ["a", "b"]) {
+        const value = result.arms[arm];
+        lines.push(`| ${arm.toUpperCase()} | ${value.passed}/${value.cases} | ${value.observed.toFixed(2)} | ${value.normalized.toFixed(2)} |`);
+    }
+    lines.push("", `Medium wins this observed corpus: **${result.mediumWinsObservedCorpus ? "yes" : "no"}**. The shipped policy remains inherited model, undeclared effort, instruction floor retained and five-minute cache lifetime.`, "",
+        "These are three observations, not a reliability estimate. A result on this concrete model does not establish medium effort for other inherited models. Cost indexes use the frozen declared vector, include parent and child requests, and are not subscription bills. First-request input is normalized separately in each fresh parent and child context.", "",
+        "| Case | A | B |", "|---|---|---|");
+    for (const task of CORPUS.cases.filter(task => task.role === record.role)) {
+        const verdict = arm => grade(task, record.turns.find(turn => turn.task === task.id && turn.arm === arm).answer).ok ? "PASS" : "FAIL";
+        lines.push(`| ${task.id} | ${verdict("a")} | ${verdict("b")} |`);
+    }
+    lines.push("", "The common acquisition record accounts for both mechanism probes and discloses the one retained-answer decoder repair after the first outcome. The original failed decode score and the repaired score are both retained; that child was never rerun.", "");
+    return lines.join("\n");
+}
+
+function checkCall(call, model, ids, contexts, quality = false) {
+    demand(call && ["complete", "invalid"].includes(call.state), "call completion state missing");
+    demand(typeof call.context === "string" && !contexts.has(call.context), "a parent context was reused");
+    contexts.add(call.context);
+    demand(typeof call.childContext === "string" && !contexts.has(call.childContext), "a child context was reused");
+    contexts.add(call.childContext);
+    demand(hash(call.raw?.parent) && hash(call.raw?.result), "raw parent/result digest missing");
+    demand(Date.parse(call.started) <= Date.parse(call.ended), "call timing is invalid");
+    for (const side of ["parent", "child"]) {
+        const requests = call.usage?.[side];
+        demand(Array.isArray(requests) && requests.length > 0, `${side} usage missing`);
+        for (const [index, request] of requests.entries()) {
+            demand(typeof request.id === "string" && !ids.has(request.id), "duplicate request identity");
+            ids.add(request.id);
+            demand(request.model === model, "concrete model changed");
+            demand(request.effort === (side === "parent" ? "high" : call.effort ?? "high"), "effective effort differs from frozen arm");
+            demand(Number.isFinite(request.at) && request.at >= Date.parse(call.started) && request.at <= Date.parse(call.ended), "request outside its call");
+            demand(index === 0 || request.at >= requests[index - 1].at, "usage requests are out of chronological order");
+            for (const key of CLASSES) demand(Number.isSafeInteger(request[key]) && request[key] >= 0, `invalid ${key} count`);
+        }
+    }
+    costOf(call);
+    if (!quality) return;
+    demand(call.state === "complete" && call.exit === 0 && call.timedOut === false, "quality call did not complete");
+    demand(hash(call.raw.child) && hash(call.invocation?.promptSha256), "raw child/prompt digest missing");
+    demand(call.invocation.type === `portulan:${call.role}` && call.invocation.effort === call.effort && call.invocation.model === null && call.invocation.background === false, "native child selection changed");
+    demand(call.model === model && call.requestedModel === model, "quality model changed");
+    demand(call.parentEffort === "high" && call.fresh === true, "quality parent was not fresh/high");
+    demand(hash(call.answerRawSha256) && sha(call.answer) === call.answerPresentationSha256 && typeof call.answerNormalized === "boolean", "answer presentation provenance missing");
+    demand(call.answerNormalized === (call.answerRawSha256 !== call.answerPresentationSha256), "answer normalization flag differs");
+    demand(!/\/Users\/|\/private\/var\/folders\//.test(call.answer), "an original local path remains in a public answer");
+}
+
+export function verifyData(capture, records) {
+    demand(capture.version === 1 && capture.phase === "complete", "acquisition is incomplete");
+    demand(capture.model === "claude-sonnet-5-5" && same(capture.prices, CORPUS.prices), "frozen model or price vector changed");
+    demand(capture.seed === CORPUS.seed && /^[a-f0-9]{40}$/.test(capture.sourceCommit), "corpus seed or source commit missing");
+    demand(same(Object.keys(capture.taskSha256 ?? {}).sort(), CORPUS.cases.map(task => task.id).sort()), "frozen task roster changed");
+    for (const task of CORPUS.cases) demand(sha(JSON.stringify({ role: task.role, task: task.task }, null, 2) + "\n") === capture.taskSha256[task.id], "frozen task bytes differ from the public corpus");
+    demand(same(capture.routing, ROUTING), "routing differs from retained policy");
+    demand(capture.preflights?.length === 2 && capture.preflights[0].state === "invalid" && capture.preflights[1].state === "complete", "both mechanism probes must be accounted");
+    demand(capture.preflights[0].reason === "error_max_budget_usd" && capture.preflights[0].argvProvenance === "reconstructed-after-execution", "failed first probe provenance missing");
+    demand(capture.preflights[1].markerSeen === true, "native medium mechanism was not demonstrated");
+    demand(capture.preflights[0].instrumentSha256 === capture.instruments.firstProbe.sha256 && capture.preflights[1].instrumentSha256 === capture.instruments.secondProbe.sha256, "probe instrument attribution differs");
+    const repair = capture.decodeRepair;
+    demand(repair?.observedOutcomes === 1 && repair.retainedKey === "implementer-lower-bound-a" && repair.reruns === 0 && repair.approval === "PASS", "one-answer repair disclosure missing");
+    for (const key of ["previousGrader", "grader", "abortedJournalSha256", "approvalSha256", "semanticSuffixSha256"]) demand(hash(repair[key]), `repair ${key} missing`);
+    const ids = new Set(), contexts = new Set();
+    checkCall(capture.preflights[0], "claude-fable-5-2", ids, contexts);
+    checkCall(capture.preflights[1], capture.model, ids, contexts, true);
+    demand(capture.preflights[1].effort === "medium" && capture.preflights[1].answer === "MECHANISM_OK", "medium probe answer/effort differs");
+    const all = [];
+    for (const role of ROLES) {
+        const record = records[role];
+        demand(record?.version === 1 && record.role === role && record.model === capture.model && record.host === capture.host, "role record identity changed");
+        demand(record.turns?.length === 6, "role has other than six acquired turns");
+        const expected = CORPUS.cases.filter(task => task.role === role).flatMap(task => ["a", "b"].map(arm => `${task.id}-${arm}`));
+        demand(same(record.turns.map(turn => turn.key).sort(), expected.sort()), "role case/arm coverage differs");
+        for (const turn of record.turns) {
+            const task = CORPUS.cases.find(task => task.id === turn.task);
+            demand(turn.role === role && task.role === role && turn.key === `${turn.task}-${turn.arm}` && turn.effort === (turn.arm === "a" ? null : "medium"), "role/arm changed");
+            checkCall(turn, capture.model, ids, contexts, true);
+            demand(turn.instrumentSha256 === capture.instruments[turn.key === repair.retainedKey ? "firstOutcome" : "continuation"].sha256, "quality instrument attribution differs");
+            const actual = grade(task, turn.answer);
+            demand(same(actual, turn.regraded ?? turn.grade), "stored semantic grade differs");
+            if (turn.key === repair.retainedKey) demand(turn.grade.ok === false && turn.regraded?.ok === true, "original failed decode score was overwritten");
+            else demand(!Object.hasOwn(turn, "regraded"), "an unapproved outcome was regraded");
+            if (turn.arm === "a") demand(actual.ok, "a failed control earns no routing");
+            all.push(turn);
+        }
+        demand(same(record.summary, summarize(record)), "stored role summary differs");
+    }
+    const expectedOrder = CORPUS.cases.flatMap((task, index) => (index % 2 === 0 ? ["a", "b"] : ["b", "a"]).map(arm => `${task.id}-${arm}`));
+    demand(same(capture.order, expectedOrder), "frozen acquisition order changed");
+    const chronological = all.sort((a, b) => Date.parse(a.started) - Date.parse(b.started));
+    demand(same(capture.publication?.normalizedAnswers, chronological.filter(turn => turn.answerNormalized).map(turn => turn.key)), "normalized answer disclosure differs");
+    demand(same(chronological.map(turn => turn.key), expectedOrder), "turns did not run in frozen order");
+    demand(Date.parse(capture.qualityFrozenAt) <= Date.parse(chronological[0].started) && Date.parse(capture.continuationFrozenAt) >= Date.parse(chronological[0].ended) && Date.parse(capture.continuationFrozenAt) <= Date.parse(chronological[1].started), "freeze/repair timing differs from the disclosed sequence");
+    const calls = [...capture.preflights, ...chronological];
+    demand(calls.every((call, index) => index === 0 || Date.parse(call.started) >= Date.parse(calls[index - 1].ended)), "fresh calls overlap or probes were reordered");
+    const requests = capture.preflights.flatMap(call => [...call.usage.parent, ...call.usage.child]).length + all.flatMap(call => [...call.usage.parent, ...call.usage.child]).length;
+    demand(capture.accounting.requests === requests && capture.accounting.calls === 20 && capture.accounting.qualityChildren === 18 && capture.accounting.parentContexts === 20, "usage accounting is incomplete");
+    return { roles: ROLES.length, qualityChildren: all.length, requests, overhead: capture.preflights.map(costOf) };
+}
+
+export function verifyCapture(root, expectedDigest = CAPTURE_SHA256) {
+    const bytes = fs.readFileSync(path.join(root, CAPTURE));
+    demand(sha(bytes) === expectedDigest, "acquisition digest changed");
+    const capture = JSON.parse(bytes), directory = path.dirname(path.join(root, CAPTURE));
+    const records = {};
+    for (const role of ROLES) {
+        const file = `${role}.json`, data = fs.readFileSync(path.join(directory, file));
+        demand(sha(data) === capture.files[file], `${role} record digest changed`);
+        records[role] = JSON.parse(data);
+        demand(fs.readFileSync(path.join(directory, `${role}.md`), "utf8") === register(records[role]), `${role} register differs`);
+    }
+    const sources = ["evals/ab/personas/corpus.json", "evals/ab/personas/grader.mjs", ...ROLES.map(role => `core/personas/${role}.md`)];
+    demand(same(Object.keys(capture.sources ?? {}).sort(), sources.sort()), "required source roster differs");
+    for (const [file, expected] of Object.entries(capture.sources)) demand(sha(fs.readFileSync(path.join(root, file))) === expected, `source differs: ${file}`);
+    const old = fs.readFileSync(path.join(directory, "repairs/grader-before-decode-repair.mjs.txt"), "utf8");
+    const current = fs.readFileSync(path.join(directory, "grader.mjs"), "utf8");
+    demand(sha(old) === capture.decodeRepair.previousGrader && sha(current) === capture.decodeRepair.grader, "decoder versions differ");
+    const suffix = text => text.slice(text.indexOf("function codeCases"));
+    demand(suffix(old) === suffix(current) && sha(suffix(current)) === capture.decodeRepair.semanticSuffixSha256, "repair changed semantic predicates or pricing");
+    const first = records.implementer.turns.find(turn => turn.key === capture.decodeRepair.retainedKey);
+    demand(fs.readFileSync(path.join(directory, "repairs/first-control-answer.txt"), "utf8") === first.answer + "\n", "retained first answer differs");
+    for (const [key, name] of Object.entries({ firstProbe: "first-probe", secondProbe: "second-probe", firstOutcome: "first-outcome", continuation: "continuation", publisher: "publisher" })) {
+        demand(sha(fs.readFileSync(path.join(directory, `protocol/${name}.mjs.txt`))) === capture.instruments[key].sha256, "instrument snapshot differs");
+    }
+    for (const role of ROLES) {
+        const source = fs.readFileSync(path.join(root, `core/personas/${role}.md`), "utf8");
+        const header = source.split("---")[1];
+        demand(/^model: inherit$/m.test(header) && !/^effort:/m.test(header) && /^omitClaudeMd: false$/m.test(header) && /^cacheLifetime: 5m$/m.test(header), "shipped source routing differs");
+        const binding = fs.readFileSync(path.join(directory, `bindings/${role}.txt`));
+        demand(sha(binding) === capture.bindings[role], "captured binding differs");
+        const installed = path.join(root, `agents/${role}.md`);
+        if (fs.existsSync(installed)) demand(bindingContract(fs.readFileSync(installed, "utf8")) === bindingContract(binding.toString("utf8")), "shipped plugin binding differs outside its description");
+    }
+    return verifyData(capture, records);
+}
+
+export function run(argv = process.argv.slice(2)) {
+    try {
+        if (argv.length && !(argv.length === 2 && argv[0] === "--repo-root")) throw Error("usage: node cli/persona-routing.mjs [--repo-root <dir>]");
+        const result = verifyCapture(path.resolve(argv[1] ?? "."));
+        console.log(`persona-routing: ${result.roles} acquired role records, ${result.qualityChildren} quality children and ${result.requests} accounted requests; shipped policy matches`);
+        return 0;
+    } catch (error) { console.error(`persona-routing: ${error.message}`); return error instanceof Finding ? 1 : 2; }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) process.exitCode = run();

package/cli/plugin-lint.mjs

@@ -11,6 +11,9 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { HOST_SKILL_DEPTH, skillsSet, canonical } from "./skills-set.mjs";
+import { parseFrontmatter } from "./frontmatter.mjs";
+export { parseFrontmatter };
+import { packContributions, personaDeclarations } from "./compile.mjs";
 
 /** Raised when `plugin-lint` cannot run at all. Always exit 2, never 1. */
 export class PluginLintError extends Error {
@@ -25,7 +28,6 @@ const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 // Kept by hand with docs/plan.md's repo topology: visibility is a GitHub setting no file can read.
 const PRIVATE_FEEDS = ["sleepy-panda-srl/portulan-internal"];
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-const BLOCK_SCALAR = /^[|>][+-]?$/;
 
 const PATH_FIELDS = [
     "skills",
@@ -44,46 +46,6 @@ const SKIP_DIRS = new Set([".git", "node_modules", ".claude-plugin"]);
 export const AGENT_DIR = "agents";
 const MAX_WALK_DEPTH = 6;
 
-// ===========================================================================================
-// Frontmatter
-// ===========================================================================================
-
-/** A flat-YAML reader: `fields` is null without a usable block, and `error` is set when that is a defect. */
-export function parseFrontmatter(text) {
-    const lines = text.split(/\r?\n/);
-    if (lines[0]?.trim() !== "---") return { fields: null };
-
-    const close = lines.indexOf("---", 1);
-    if (close === -1) {
-        return { fields: null, error: "the frontmatter block is never closed" };
-    }
-
-    const fields = {};
-    const body = lines.slice(1, close);
-    for (let i = 0; i < body.length; i += 1) {
-        const match = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(body[i]);
-        if (!match) continue;
-        const key = match[1];
-        let value = match[2].trim();
-
-        if (BLOCK_SCALAR.test(value)) {
-            const collected = [];
-            while (i + 1 < body.length && (body[i + 1].trim() === "" || /^\s+/.test(body[i + 1]))) {
-                i += 1;
-                collected.push(body[i].trim());
-            }
-            value = collected.join(" ").trim();
-        } else if (
-            (value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
-            (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
-        ) {
-            value = value.slice(1, -1);
-        }
-        fields[key] = value;
-    }
-    return { fields };
-}
-
 // ===========================================================================================
 // Inspection
 // ===========================================================================================
@@ -91,7 +53,7 @@ export function parseFrontmatter(text) {
 /** Lexical: a symlink inside `root` can still lead out of it. */
 function escapes(root, target) {
     const inside = path.relative(root, target);
-    return inside.startsWith("..") || path.isAbsolute(inside);
+    return inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside);
 }
 
 /** Throws PluginLintError only when the root is not a readable directory; `payload` excuses an absent marketplace.json. */
@@ -119,10 +81,21 @@ export function inspect(rawRoot, { payload = false } = {}) {
     const fail = (check, message) => findings.push({ severity: "fail", check, message });
     const note = (check, message) => findings.push({ severity: "note", check, message });
 
+    const ownedText = (file, scope = root) => {
+        const realScope = fs.realpathSync(scope), real = fs.realpathSync(file);
+        if (escapes(root, realScope) || escapes(realScope, real)) throw Error(`${file} resolves outside its bundled owner`);
+        if (!fs.statSync(real).isFile()) throw Error(`${file} is not a regular source file`);
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(real));
+    };
+    const ownedJson = (file, scope = root) => {
+        const value = JSON.parse(ownedText(file, scope));
+        if (value === null || typeof value !== "object" || Array.isArray(value)) throw Error(`${file} is not a JSON object`);
+        return value;
+    };
     /** Never throws: a failed read becomes a finding and returns null. */
     const read = (file, check, label) => {
         try {
-            return fs.readFileSync(file, "utf8");
+            return ownedText(file);
         } catch (error) {
             fail(check, `${label} could not be read — ${error.code ?? error.message}`);
             return null;
@@ -420,7 +393,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
     let composition;
     let composable = true;
     try {
-        composition = JSON.parse(fs.readFileSync(path.join(root, GOVERNING), "utf8"));
+        composition = JSON.parse(ownedText(path.join(root, GOVERNING), path.join(root, ".portulan")));
     } catch (error) {
         if (error.code === "ENOENT") composable = false;
         else {
@@ -550,7 +523,7 @@ export function inspect(rawRoot, { payload = false } = {}) {
         for (const { name, dir } of composed) {
             let text;
             try {
-                text = fs.readFileSync(path.join(dir, "pack.json"), "utf8");
+                text = ownedText(path.join(dir, "pack.json"), dir);
             } catch (error) {
                 if (error.code === "ENOENT") continue;
                 fail(
@@ -616,8 +589,8 @@ export function inspect(rawRoot, { payload = false } = {}) {
     for (const stranded of walkForStrandedAgents(root)) {
         note(
             "agents",
-            `${path.relative(root, stranded)} is not in ./${AGENT_DIR}/, the only directory the host ` +
-                "loads agents from — it will not load",
+            `${path.relative(root, stranded)} is not in ./${AGENT_DIR}/, this plugin's agent directory — ` +
+                "it will not load as a plugin binding",
         );
     }
 
@@ -703,28 +676,77 @@ export function inspect(rawRoot, { payload = false } = {}) {
     // Fails where doctor only reports: this bundle targets one host, and an unbound persona is inert there.
     const personaDir = path.join(root, "core", "personas");
     let personaFiles = null;
+    let corePresent = false;
     try {
+        fs.lstatSync(personaDir);
+        corePresent = true;
+        if (escapes(root, fs.realpathSync(personaDir))) throw Error("core/personas/ resolves outside the plugin");
         personaFiles = fs
             .readdirSync(personaDir)
             .filter((entry) => entry.endsWith(".md") && entry !== "README.md")
             .map((entry) => path.basename(entry, ".md"))
             .sort();
     } catch (error) {
-        if (error.code !== "ENOENT") fail("agents", `core/personas/ could not be read — ${error.code ?? error.message}, so the binding correspondence went unchecked`);
+        if (error.code !== "ENOENT" || corePresent) fail("agents", `core/personas/ could not be read — ${error.code ?? error.message}, so the binding correspondence went unchecked`);
+    }
+    const owners = new Map();
+    for (const name of personaFiles ?? []) {
+        const source = `core/personas/${name}.md`;
+        try { ownedText(path.join(root, source)); owners.set(name, source); }
+        catch (error) { fail("agents", `${source} could not be read — ${error.message}`); }
+    }
+    let composedDeclared = false;
+    const workspaceFile = path.join(root, ".portulan/workspace.json");
+    let workspacePresent = false;
+    try {
+        fs.lstatSync(workspaceFile);
+        workspacePresent = true;
+        const workspace = ownedJson(workspaceFile, path.dirname(workspaceFile));
+        if (workspace?.packs !== undefined && !Array.isArray(workspace.packs)) throw Error("workspace packs is not an array");
+        composedDeclared = (workspace?.packs?.length ?? 0) > 0;
+        if (composedDeclared) {
+            for (const ref of workspace.packs) {
+                if (typeof ref !== "string" || !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(ref)) throw Error("a composed pack reference is malformed");
+                const packsRoot = fs.realpathSync(path.join(root, "packs"));
+                const packDir = fs.realpathSync(path.join(root, "packs", ref));
+                if (escapes(root, packsRoot) || escapes(packsRoot, packDir)) throw Error(`${ref} resolves outside its bundled packs root`);
+                const pack = ownedJson(path.join(packDir, "pack.json"), packDir);
+                if (pack.contributes !== undefined && (pack.contributes === null || typeof pack.contributes !== "object" || Array.isArray(pack.contributes))) throw Error(`${ref} contributes is not a mapping`);
+            }
+            const composed = packContributions(root, ".portulan", { packRoots: [path.join(root, "packs")] });
+            if (composed.unresolved.length) throw Error(`unresolved persona owners: ${composed.unresolved.map(pack => pack.name).join(", ")}`);
+            for (const contribution of composed.contributions) {
+                for (const rel of contribution.personas) {
+                    if (typeof rel !== "string" || !rel.trim()) throw Error("a composed persona path is not a nonempty string");
+                    const file = path.resolve(contribution.dir, rel);
+                    if (escapes(contribution.dir, file)) throw Error(`${contribution.pack}'s ${rel} resolves outside its bundled pack`);
+                    const source = `${contribution.pack}'s ${rel}`;
+                    const parsed = personaDeclarations(ownedText(file, contribution.dir));
+                    if (parsed.problems.length) throw Error(`${source}: ${parsed.problems.join("; ")}`);
+                    const name = parsed.name ?? path.basename(rel, ".md");
+                    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) throw Error(`${source} has no usable binding name`);
+                    if (owners.has(name)) throw Error(`${name} has multiple persona owners: ${owners.get(name)} and ${source}`);
+                    owners.set(name, source);
+                }
+            }
+        }
+    } catch (error) {
+        if (error.code !== "ENOENT" || workspacePresent) fail("agents", `composed persona ownership could not be read — ${error.code ?? error.message}`);
     }
-    if (personaFiles && !agentsExamined) {
+    const correspondence = personaFiles !== null || composedDeclared;
+    if (correspondence && !agentsExamined) {
         note(
             "agents",
             `the persona↔binding correspondence went unchecked — ./${AGENT_DIR}/ could not be examined, so an empty binding set is a ` +
-                `question nobody answered rather than ${personaFiles.length} persona(s) with nothing bound to them`,
+                `question nobody answered rather than ${owners.size} persona(s) with nothing bound to them`,
         );
-    } else if (personaFiles) {
-        for (const persona of personaFiles) {
+    } else if (correspondence) {
+        for (const [persona, source] of owners) {
             const binding = bindings.get(persona);
             if (!binding) {
                 fail(
                     "agents",
-                    `core/personas/${persona}.md has no binding at ./${AGENT_DIR}/${persona}.md — a persona this plugin ships and does not bind ` +
+                    `${source} has no binding at ./${AGENT_DIR}/${persona}.md — a persona this plugin ships and does not bind ` +
                         `is doctrine the host never registers, which looks from the outside exactly like a role that is available`,
                 );
                 continue;
@@ -732,14 +754,13 @@ export function inspect(rawRoot, { payload = false } = {}) {
             if (binding.name !== undefined && binding.name !== persona) {
                 fail(
                     "agents",
-                    `${binding.rel} binds \`core/personas/${persona}.md\` by its filename while declaring \`name: ${binding.name}\` — the host keys ` +
+                    `${binding.rel} binds \`${source}\` by its filename while declaring \`name: ${binding.name}\` — the host keys ` +
                         `on the field, so the two disagree about which role this file registers`,
                 );
             }
         }
-        const personaNames = new Set(personaFiles);
         for (const [name, binding] of bindings) {
-            if (!personaNames.has(name)) {
+            if (!owners.has(name)) {
                 fail(
                     "agents",
                     `${binding.rel} binds no persona — there is no \`core/personas/${name}.md\`. A host file that outlived the doctrine it was ` +

package/cli/recipe-output.mjs

@@ -0,0 +1,91 @@
+// Agent output for any recipe: one green count, complete failure streams.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { execFileSync } from "node:child_process";
+import { runRecipe } from "./recipe-runner.mjs";
+
+function spools(tmpdir) {
+    const dir = fs.mkdtempSync(path.join(tmpdir, "portulan-recipe-output-"));
+    const descriptors = [];
+    try {
+        for (const name of ["stdout", "stderr"]) {
+            const file = path.join(dir, name);
+            descriptors.push(fs.openSync(file, "wx+", 0o600));
+            fs.unlinkSync(file);
+        }
+        fs.rmdirSync(dir);
+        return descriptors;
+    } catch (error) {
+        for (const fd of descriptors) { try { fs.closeSync(fd); } catch {} }
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+
+async function replay(fd, destination) {
+    function* chunks() {
+        const buffer = Buffer.alloc(64 * 1024);
+        let offset = 0;
+        for (;;) {
+            const bytes = fs.readSync(fd, buffer, 0, buffer.length, offset);
+            if (bytes === 0) break;
+            offset += bytes;
+            yield Buffer.from(buffer.subarray(0, bytes));
+        }
+    }
+    await pipeline(Readable.from(chunks()), destination, { end: false });
+}
+
+export async function execute(command, { root = process.cwd(), env = process.env, tmpdir = os.tmpdir(), stdout = process.stdout, stderr = process.stderr, timeout = 600_000 } = {}) {
+    let descriptors = [];
+    try {
+        if (typeof command !== "string" || !command.trim()) throw new Error("one nonempty recipe command is required");
+        descriptors = spools(tmpdir);
+        const inherited = env.PORTULAN_RECIPE_MANAGED === "1";
+        const groupId = Number(env.PORTULAN_RECIPE_GROUP);
+        if (inherited && process.platform !== "win32") {
+            const actual = Number(execFileSync("ps", ["-o", "pgid=", "-p", String(process.pid)], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "pipe"] }).trim());
+            if (!Number.isInteger(groupId) || groupId <= 1 || actual !== groupId) throw new Error("inherited recipe group does not own this executor");
+        }
+        const result = await runRecipe({ id: "recipe", run: command }, {
+            root, env, timeout: inherited ? 0 : timeout, mergeOutput: false, inheritGroup: inherited, groupId,
+            onOutput: (name, chunk) => {
+                const fd = descriptors[name === "stdout" ? 0 : 1];
+                let offset = 0;
+                while (offset < chunk.length) {
+                    let wrote;
+                    try { wrote = fs.writeSync(fd, chunk, offset, chunk.length - offset); }
+                    catch (error) { stderr.write(`recipe-output: could not run — ${error.message}\n`); throw error; }
+                    if (wrote <= 0) throw new Error("output spool made no write progress");
+                    offset += wrote;
+                }
+            },
+        });
+        if (result.outcome !== "green") {
+            await replay(descriptors[0], stdout);
+            await replay(descriptors[1], stderr);
+            if (result.diagnostics?.length) stderr.write(`recipe-output: could not run — ${result.diagnostics.join("; ")}\n`);
+        }
+        for (const fd of descriptors) fs.closeSync(fd);
+        descriptors = [];
+        if (result.outcome === "green") { await pipeline(Readable.from(["GREEN — 1 recipe passed\n"]), stdout, { end: false }); return 0; }
+        return result.code ?? 2;
+    } catch (error) {
+        stderr.write(`recipe-output: could not run — ${error.message}\n`);
+        return 2;
+    } finally {
+        for (const fd of descriptors) { try { fs.closeSync(fd); } catch {} }
+    }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    const args = process.argv.slice(2);
+    if (args.length !== 2 || args[0] !== "--") {
+        process.stderr.write("usage: node cli/recipe-output.mjs -- <recipe-command>\n");
+        process.exitCode = 2;
+    } else process.exitCode = await execute(args[1]);
+}

package/cli/recipe-runner.md

@@ -0,0 +1,68 @@
+# Recipe execution and cleanup
+
+`finish` and the Stop-gate share `recipe-runner.mjs`. Finish allows ten minutes.
+Stop allows ninety seconds unless its trusted workspace declares
+`verify.stopTimeout` in seconds at spec 2.14 or later. Recompile after declaring it:
+the compiled Stop hook allows that deadline plus sixty seconds for other checks
+and cleanup. An invalid declaration prevents execution. Output is drained as it arrives; only the last
+64 KiB and at most one incoming chunk are retained.
+
+Stop reads both command and deadline from the hook-told workspace and runs in the
+hook-told root. The payload's session worktree selects its record/work checks,
+and cannot choose executable policy. Verification of that other worktree remains
+the separate #311 trust question; a green here covers the told tree.
+
+After three actual recipe refusals in a session, further Stops skip that recipe
+and release explicitly unverified/RED. Repairing files then does not resume
+automatic verification in that session: run it explicitly before claiming done,
+or use a new session. A still-pending handoff at its cap, nine total refusals, or
+the thirteenth consecutive hook-provoked Stop also suppresses recipe execution.
+Skipped runs never charge a recipe failure or become green evidence. A handoff
+that clears before the other bounds allows execution again; ordinary Stops reset
+the chain, and a measured green before the recipe cap clears its streak.
+
+The deadline tests inject a long selection and exercise a short live timeout;
+they demonstrate configuration and cleanup, not a real five-minute recipe or a
+live host's outer-timeout enforcement. Counter-file failure/concurrent-write
+limits remain; this is not a cross-session scheduler or a cache of green trees.
+
+On POSIX, Bash starts in a detached process group. A timeout sends TERM to the group;
+SIGINT, SIGTERM and SIGHUP received by the active runner are forwarded to it. After
+250 ms the runner sends KILL to that group, even if Bash has already exited or closed
+its pipes. Repeated interruptions do not restart that grace period. Cleanup allows
+one further second for closure and reports failures as could-not-run. Finish retains
+an observed interruption, stops its recipe loop, rolls back its provisional commit
+and pushes nothing.
+
+On Windows, the runner checks an absolute system `taskkill.exe` path before starting
+Bash. Cleanup invokes `/PID <owned pid> /T /F` with a one-second command timeout;
+this is forced tree termination rather than POSIX signal forwarding. Missing tools
+and termination errors produce could-not-run diagnostics. Command construction and
+error paths have unit controls here; native Windows execution has not been tested.
+
+A normally exiting recipe keeps the existing behavior: inherited pipes are drained
+for at most one second, and background processes can continue. Descendants that
+intentionally escape the POSIX group are outside its cleanup. OS signal denial,
+runner SIGKILL and failures outside active recipe execution cannot promise cleanup
+or commit rollback. This runner does not impose a deadline on finish's other Git
+operations.
+
+`recipe-set --agent` wraps each command in `recipe-output.mjs`. That executor
+spools stdout and stderr separately to private descriptors, unlinks their names
+before starting the child, and replays all bytes on failure. Green is one counted
+line. The runner's ordinary tail remains bounded; the executor's failure stream
+is complete at its own boundary. Output capture, replay or setup failures return
+could-not-run, never green.
+
+The runner marks the environment of its owned child. A nested executor shares
+that process group and delegates its deadline to the outer runner. On POSIX it
+checks its actual group with `ps` before inheriting ownership, so the outer
+timeout or interruption reaches every descendant even if the executor is killed.
+An inner capture failure also terminates that owned group. Anonymous descriptors
+leave no named temporary logs behind on a hard kill. Standalone executors own
+their own recipe group and a ten-minute deadline. Native Windows execution of
+this output mode remains untested, as does its forced-termination filesystem
+behavior; inability to create anonymous spools refuses execution.
+
+The platform mechanisms follow [Node's detached-process documentation](https://nodejs.org/api/child_process.html#optionsdetached)
+and [Microsoft's taskkill reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill).