@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/evals/ab/personas/librarian.md

@@ -0,0 +1,22 @@
+# librarian — acquired routing comparison
+
+Host: 2.1.321 (Claude Code). Concrete model: claude-sonnet-5-5.
+
+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 |
+|---|---:|---:|---:|
+| A | 3/3 | 189830.90 | 454310.90 |
+| B | 3/3 | 175537.25 | 451854.20 |
+
+Medium wins this observed corpus: **yes**. 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 |
+|---|---|---|
+| librarian-duplicate | PASS | PASS |
+| librarian-conflict | PASS | PASS |
+| librarian-sealed | PASS | PASS |
+
+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.

package/evals/ab/personas/protocol/continuation.mjs.txt

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+// Acquire the frozen persona comparisons through native children; never run by a recipe.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { spawnSync, execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { cloneTree, childEnv, transcriptOf } from "./warm.mjs";
+import { readTranscript } from "./ledger.mjs";
+import { CORPUS, grade } from "../evals/ab/personas/grader.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PARENT_MODEL = "claude-sonnet-5-5";
+const ROLES = ["implementer", "reviewer", "librarian"];
+const FROZEN = ["evals/ab/personas/corpus.json", "evals/ab/personas/grader.mjs", "cli/persona-routing.test.mjs"];
+const digest = bytes => createHash("sha256").update(bytes).digest("hex");
+const sha = file => digest(fs.readFileSync(file));
+const json = file => JSON.parse(fs.readFileSync(file, "utf8"));
+const save = (file, value) => fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+const git = (...args) => execFileSync("git", args, { cwd: ROOT, encoding: "utf8" }).trim();
+const records = file => fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line));
+
+export function parentPrompt(role, taskFile, effort) {
+    const input = {
+        subagent_type: `portulan:${role}`, description: "Frozen persona artifact probe",
+        prompt: `Read ${taskFile} and follow its task exactly. This is an artifact proposal, not a completed repository change.`,
+        run_in_background: false,
+        ...(effort === null ? {} : { effort }),
+    };
+    return "This is a frozen evaluation. Invoke the Agent tool exactly once with these input values: " + JSON.stringify(input) +
+        ". Do not supply a child model or change the effort. Wait for that foreground child to finish. Do not answer its task yourself or invoke another child. After completion reply only DONE.";
+}
+
+function response(file) {
+    const raw = fs.readFileSync(file, "utf8").trim();
+    let value;
+    try { value = JSON.parse(raw); } catch { throw Error("the CLI returned no single JSON result"); }
+    if (value.type !== "result" || value.is_error || value.subtype !== "success" || typeof value.session_id !== "string") throw Error("the CLI did not complete successfully");
+    return value;
+}
+
+function answerOf(rows) {
+    const messages = rows.filter(r => r.type === "assistant" && r.message?.model !== "<synthetic>" && Array.isArray(r.message?.content));
+    const last = messages.at(-1)?.message.id;
+    if (!last) throw Error("child has no final assistant message");
+    const blocks = messages.filter(r => r.message.id === last).flatMap(r => r.message.content).filter(b => b.type === "text");
+    return [...new Set(blocks.map(b => b.text))].join("\n").trim();
+}
+
+export function nativeInvocation(rows, role, effort) {
+    const calls = rows.filter(r => r.type === "assistant").flatMap(r => r.message?.content ?? []).filter(b => b.type === "tool_use" && ["Agent", "Task"].includes(b.name));
+    const unique = [...new Map(calls.map(call => [call.id, call])).values()];
+    if (unique.length !== 1) throw Error("a parent must invoke exactly one native child");
+    const input = unique[0].input;
+    if (input?.subagent_type !== `portulan:${role}` || Object.hasOwn(input, "model") || (input.effort ?? null) !== effort) throw Error("the parent did not select the frozen role/inherited model/effort");
+    if (input.run_in_background === true) throw Error("a background child is not a completed foreground comparison");
+    return { type: input.subagent_type, effort: input.effort ?? null, prompt: input.prompt };
+}
+
+function collectCall(entry, dir, tree, env) {
+    if (entry.exit !== 0 || entry.timedOut) throw Error("a parent invocation failed or timed out");
+    const result = response(path.join(dir, entry.stdout));
+    if (result.session_id !== entry.sessionId) throw Error("the result belongs to a different parent session");
+    const transcript = transcriptOf(result.session_id, tree, env);
+    if (transcript === null) throw Error("the completed parent transcript is unavailable");
+    const rows = records(transcript);
+    const invocation = nativeInvocation(rows, entry.role, entry.effort);
+    if (invocation.prompt !== entry.childPrompt) throw Error("the child did not receive the frozen prompt verbatim");
+    const agentDir = path.join(path.dirname(transcript), result.session_id, "subagents");
+    const children = fs.readdirSync(agentDir).filter(name => /^agent-.*\.jsonl$/.test(name));
+    if (children.length !== 1) throw Error("the parent has other than one child transcript");
+    const child = path.join(agentDir, children[0]);
+    const childRows = records(child);
+    const parentUsage = readTranscript(transcript), childUsage = readTranscript(child);
+    if (parentUsage.malformed || childUsage.malformed) throw Error("a transcript has malformed records");
+    const parent = parentUsage.requests.filter(r => !r.synthetic && !r.sidechain);
+    const requests = childUsage.requests.filter(r => !r.synthetic);
+    if (!parent.length || !requests.length) throw Error("parent or child usage is missing");
+    const models = [...new Set([...parent, ...requests].map(r => r.model))];
+    if (models.length !== 1 || !models[0]) throw Error("inherited parent/child concrete models disagree or are unknown");
+    const efforts = [...new Set(requests.map(r => r.effort))];
+    if (entry.effort !== null && (efforts.length !== 1 || efforts[0] !== entry.effort)) throw Error("host usage does not establish the requested child effort");
+    const target = path.join(dir, "originals", entry.key);
+    fs.mkdirSync(target, { recursive: true });
+    fs.copyFileSync(transcript, path.join(target, "parent.jsonl"));
+    fs.copyFileSync(child, path.join(target, "child.jsonl"));
+    return {
+        invocation: { type: invocation.type, effort: invocation.effort, promptSha256: digest(invocation.prompt) },
+        model: models[0], efforts, parentEfforts: [...new Set(parent.map(r => r.effort))],
+        answer: answerOf(childRows), usage: { parent, child: requests },
+        raw: { result: sha(path.join(dir, entry.stdout)), parent: sha(path.join(target, "parent.jsonl")), child: sha(path.join(target, "child.jsonl")) },
+        transcriptDuplicates: { parent: parentUsage.duplicates, child: childUsage.duplicates },
+    };
+}
+
+function partialUsage(entry, dir, tree, env) {
+    const transcript = transcriptOf(entry.sessionId, tree, env);
+    if (transcript === null) return { parent: [], children: [], unavailable: true };
+    const target = path.join(dir, "originals", entry.key);
+    fs.mkdirSync(target, { recursive: true });
+    fs.copyFileSync(transcript, path.join(target, "parent.jsonl"));
+    const agentDir = path.join(path.dirname(transcript), entry.sessionId, "subagents");
+    const children = fs.existsSync(agentDir) ? fs.readdirSync(agentDir).filter(name => /^agent-.*\.jsonl$/.test(name)).map(name => {
+        const file = path.join(agentDir, name);
+        fs.copyFileSync(file, path.join(target, name));
+        return { usage: readTranscript(file).requests, sha256: sha(file) };
+    }) : [];
+    return { parent: readTranscript(transcript).requests, parentSha256: sha(transcript), children, unavailable: false };
+}
+
+function initialize(dir) {
+    if (fs.existsSync(dir)) throw Error("acquisition directory already exists; no automatic retry or resampling");
+    fs.mkdirSync(dir, { recursive: true });
+    const frozen = Object.fromEntries(FROZEN.map(rel => [rel, sha(path.join(ROOT, rel))]));
+    const tree = cloneTree(ROOT, path.join(dir, "tree"));
+    const version = execFileSync("claude", ["--version"], { encoding: "utf8" }).trim();
+    const journal = { version: 1, phase: "frozen", started: new Date().toISOString(), source: git("rev-parse", "HEAD"), host: version, frozen,
+        parentPolicy: { model: PARENT_MODEL, effort: "high", configuredEstimateCeilingUsd: 1, tools: "Agent,Read" }, instrumentSha256: sha(fileURLToPath(import.meta.url)), calls: [] };
+    fs.mkdirSync(path.join(dir, "frozen"));
+    for (const rel of FROZEN) fs.copyFileSync(path.join(ROOT, rel), path.join(dir, "frozen", path.basename(rel)));
+    fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "frozen", "acquire.mjs"));
+    fs.mkdirSync(path.join(dir, "tasks"));
+    for (const task of CORPUS.cases) save(path.join(dir, "tasks", task.id + ".json"), { role: task.role, task: task.task });
+    save(path.join(dir, "journal.json"), journal);
+    return { journal, tree };
+}
+
+function checkFrozen(journal, dir, tree) {
+    if (!journal.qualityFrozen) throw Error("quality inputs were not frozen");
+    for (const [rel, expected] of Object.entries(journal.qualityFrozen.semantic)) if (sha(path.join(ROOT, rel)) !== expected) throw Error("frozen semantic source changed");
+    for (const [id, expected] of Object.entries(journal.qualityFrozen.tasks)) if (sha(path.join(dir, "tasks", id + ".json")) !== expected) throw Error("frozen task bytes changed");
+    if (sha(fileURLToPath(import.meta.url)) !== journal.qualityFrozen.instrument) throw Error("frozen acquisition instrument changed");
+    if (journal.decodeRepair) {
+        const archive = path.join(dir, "aborted-before-decode-repair.json");
+        if (sha(archive) !== journal.decodeRepair.abortedJournalSha256) throw Error("the archived stop changed");
+        const retained = JSON.parse(JSON.stringify(journal.calls.slice(0, 2)));
+        delete retained[1]?.regraded;
+        if (JSON.stringify(retained) !== JSON.stringify(json(archive).calls)) throw Error("the retained original call prefix changed");
+    }
+    if (execFileSync("git", ["rev-parse", "HEAD"], { cwd: tree, encoding: "utf8" }).trim() !== journal.source || execFileSync("git", ["status", "--porcelain"], { cwd: tree, encoding: "utf8" }).trim()) throw Error("frozen plugin checkout changed");
+}
+
+export function pendingQuality(journal) {
+    const order = journal.qualityFrozen?.order;
+    const expected = CORPUS.cases.flatMap((task, i) => (i % 2 === 0 ? ["a", "b"] : ["b", "a"]).map(arm => `${task.id}-${arm}`));
+    if (JSON.stringify(order) !== JSON.stringify(expected)) throw Error("quality order is not the frozen matrix");
+    const probe = journal.calls?.[0];
+    if (probe?.key !== "mechanism-medium" || probe.task !== "mechanism" || probe.state !== "complete" || probe.effort !== "medium") throw Error("the original completed mechanism is not first");
+    const quality = journal.calls.filter(entry => entry.task !== "mechanism");
+    if (journal.phase === "quality-frozen" && quality.length === 0 && journal.calls.length === 1) return order;
+    const first = journal.calls[1];
+    if (journal.phase === "quality-frozen-repaired" && quality.length === 1 && journal.calls.length === 2 &&
+        journal.decodeRepair?.retainedKey === order[0] && first.key === order[0] && first.state === "complete" &&
+        first.task === CORPUS.cases[0].id && first.role === CORPUS.cases[0].role && first.effort === null &&
+        first.model === journal.parentPolicy?.model && first.collected?.model === journal.model &&
+        first.collected?.invocation?.type === `portulan:${CORPUS.cases[0].role}` && first.collected.invocation.effort === null &&
+        first.grade?.ok === false && first.regraded?.ok === true && journal.decodeRepair.approvedBy) return order.slice(1);
+    throw Error("no untouched matrix or approved one-answer decoding repair; refusing retry or resampling");
+}
+
+function decodingRepair(journal, dir) {
+    if (journal.phase !== "aborted" || journal.calls.length !== 2 || journal.decodeRepair) throw Error("decoding repair requires exactly one retained outcome");
+    const previous = journal.qualityFrozen;
+    const first = journal.calls[1];
+    if (first.key !== previous.order[0] || first.state !== "complete" || first.grade?.ok !== false) throw Error("the retained outcome is not the stopped first control");
+    const approval = json(path.join(dir, "decode-repair-approval.json"));
+    if (approval.verdict !== "PASS" || !approval.by || approval.previousGrader !== previous.semantic["evals/ab/personas/grader.mjs"] ||
+        approval.grader !== sha(path.join(ROOT, "evals/ab/personas/grader.mjs")) || approval.instrument !== sha(fileURLToPath(import.meta.url))) throw Error("decoding repair approval does not cover these exact sources");
+    if (sha(path.join(ROOT, "evals/ab/personas/corpus.json")) !== previous.semantic["evals/ab/personas/corpus.json"]) throw Error("decoding repair changed the task corpus");
+    for (const [id, expected] of Object.entries(previous.tasks)) if (sha(path.join(dir, "tasks", id + ".json")) !== expected) throw Error("decoding repair changed a task");
+    const before = fs.readFileSync(path.join(dir, "frozen-quality", "grader.mjs"), "utf8");
+    const after = fs.readFileSync(path.join(ROOT, "evals/ab/personas/grader.mjs"), "utf8");
+    if (before.slice(before.indexOf("function codeCases")) !== after.slice(after.indexOf("function codeCases"))) throw Error("decoding repair changed semantic predicates or pricing");
+    const original = json(path.join(dir, "aborted-before-decode-repair.json"));
+    if (JSON.stringify(original.calls) !== JSON.stringify(journal.calls)) throw Error("the retained calls changed after the stop");
+    const repaired = grade(CORPUS.cases[0], first.collected.answer);
+    if (!repaired.ok) throw Error("the original retained answer does not pass the repaired decoder");
+    fs.mkdirSync(path.join(dir, "frozen-quality-repair"));
+    for (const rel of FROZEN) fs.copyFileSync(path.join(ROOT, rel), path.join(dir, "frozen-quality-repair", path.basename(rel)));
+    fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "frozen-quality-repair", "acquire.mjs"));
+    journal.priorQualityFrozen = previous;
+    journal.qualityFrozen = { ...previous, revision: 2, at: new Date().toISOString(),
+        semantic: Object.fromEntries(FROZEN.map(rel => [rel, sha(path.join(ROOT, rel))])), instrument: sha(fileURLToPath(import.meta.url)) };
+    journal.decodeRepair = { retainedKey: first.key, approvedBy: approval.by, approvalSha256: sha(path.join(dir, "decode-repair-approval.json")),
+        abortedJournalSha256: sha(path.join(dir, "aborted-before-decode-repair.json")), previousGrader: approval.previousGrader, grader: approval.grader, observedOutcomes: 1 };
+    first.regraded = repaired;
+    journal.phase = "quality-frozen-repaired";
+    save(path.join(dir, "journal.json"), journal);
+}
+
+function call(journal, dir, tree, { key, role, effort, task, model = PARENT_MODEL }) {
+    if (task !== "mechanism") checkFrozen(journal, dir, tree);
+    const taskFile = path.join(dir, "tasks", task + ".json");
+    const env = childEnv(process.env, { cache_lifetime: "5m" }, { local: true });
+    const childPrompt = `Read ${taskFile} and follow its task exactly. This is an artifact proposal, not a completed repository change.`;
+    const sessionId = randomUUID();
+    const args = ["-p", parentPrompt(role, taskFile, effort), "--output-format", "json", "--session-id", sessionId, "--effort", "high", "--plugin-dir", tree,
+        "--tools", "Agent,Read", "--allowedTools", `Agent(portulan:${role}),Read`, "--add-dir", path.join(dir, "tasks"), "--max-budget-usd", "1", ...(model ? ["--model", model] : [])];
+    const entry = { key, role, effort, task, childPrompt, model, sessionId, argv: args, instrumentSha256: sha(fileURLToPath(import.meta.url)), started: new Date().toISOString(), state: "started", stdout: key + ".stdout.json", stderr: key + ".stderr.txt" };
+    journal.calls.push(entry);
+    save(path.join(dir, "journal.json"), journal);
+    const started = Date.now();
+    const run = spawnSync("claude", args, { cwd: tree, env, encoding: "utf8", timeout: 180000, maxBuffer: 4 * 1024 * 1024 });
+    fs.writeFileSync(path.join(dir, entry.stdout), run.stdout ?? "");
+    fs.writeFileSync(path.join(dir, entry.stderr), run.stderr ?? "");
+    Object.assign(entry, { exit: run.status, timedOut: run.error?.code === "ETIMEDOUT", durationMs: Date.now() - started, ended: new Date().toISOString() });
+    try {
+        entry.collected = collectCall(entry, dir, tree, env);
+        entry.state = "complete";
+        if (task !== "mechanism") entry.grade = grade(CORPUS.cases.find(c => c.id === task), entry.collected.answer);
+    } catch (error) {
+        entry.state = "invalid";
+        entry.fault = error.message;
+        try { entry.partial = partialUsage(entry, dir, tree, env); } catch { entry.partial = { unavailable: true }; }
+        journal.phase = "aborted";
+    }
+    save(path.join(dir, "journal.json"), journal);
+    process.stdout.write(`${key}: ${entry.state}${entry.grade ? `, semantic ${entry.grade.ok ? "PASS" : "FAIL"}` : ""}\n`);
+    if (entry.state !== "complete") throw Error(entry.fault);
+    return entry;
+}
+
+export function run(argv = process.argv.slice(2)) {
+    const [mode, named] = argv;
+    if (!["probe", "freeze", "repair", "run"].includes(mode) || !named || argv.length !== 2) throw Error("usage: node cli/acquire-personas.mjs probe|freeze|repair|run <private-directory>");
+    const dir = path.resolve(named);
+    if (mode === "probe") {
+        const { journal, tree } = initialize(dir);
+        save(path.join(dir, "tasks", "mechanism.json"), { role: "implementer", task: "Read your role charter, then reply exactly MECHANISM_OK. This tests native effort selection only; do not edit files or call other tools." });
+        const entry = call(journal, dir, tree, { key: "mechanism-medium", role: "implementer", effort: "medium", task: "mechanism" });
+        if (entry.collected.answer !== "MECHANISM_OK") throw Error("mechanism child did not finish its fixed task");
+        journal.model = entry.collected.model;
+        journal.phase = "mechanism-demonstrated";
+        save(path.join(dir, "journal.json"), journal);
+        return 0;
+    }
+    const journal = json(path.join(dir, "journal.json"));
+    const tree = path.join(dir, "tree");
+    if (mode === "repair") { decodingRepair(journal, dir); checkFrozen(journal, dir, tree); return 0; }
+    if (mode === "freeze") {
+        if (journal.phase !== "mechanism-demonstrated" || journal.calls.length !== 1 || journal.qualityFrozen) throw Error("quality freeze requires one valid probe and no outcomes or prior freeze");
+        fs.mkdirSync(path.join(dir, "frozen-quality"));
+        for (const rel of FROZEN) fs.copyFileSync(path.join(ROOT, rel), path.join(dir, "frozen-quality", path.basename(rel)));
+        fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "frozen-quality", "acquire.mjs"));
+        for (const task of CORPUS.cases) save(path.join(dir, "tasks", task.id + ".json"), { role: task.role, task: task.task });
+        journal.qualityFrozen = {
+            at: new Date().toISOString(), semantic: Object.fromEntries(FROZEN.map(rel => [rel, sha(path.join(ROOT, rel))])),
+            instrument: sha(fileURLToPath(import.meta.url)), tasks: Object.fromEntries(CORPUS.cases.map(task => [task.id, sha(path.join(dir, "tasks", task.id + ".json"))])),
+            parentPolicy: journal.parentPolicy,
+            order: CORPUS.cases.flatMap((task, i) => (i % 2 === 0 ? ["a", "b"] : ["b", "a"]).map(arm => `${task.id}-${arm}`)),
+            roles: Object.fromEntries(ROLES.map(role => [role, { persona: sha(path.join(tree, "core/personas", role + ".md")), binding: sha(path.join(tree, "agents", role + ".md")) }])),
+        };
+        journal.phase = "quality-frozen";
+        save(path.join(dir, "journal.json"), journal);
+        checkFrozen(journal, dir, tree);
+        return 0;
+    }
+    const pending = new Set(pendingQuality(journal));
+    checkFrozen(journal, dir, tree);
+    journal.instrument = sha(fileURLToPath(import.meta.url));
+    journal.phase = "acquiring";
+    save(path.join(dir, "journal.json"), journal);
+    try {
+    for (const [i, task] of CORPUS.cases.entries()) {
+        for (const arm of i % 2 === 0 ? ["a", "b"] : ["b", "a"]) {
+            if (!pending.has(`${task.id}-${arm}`)) continue;
+            const entry = call(journal, dir, tree, { key: `${task.id}-${arm}`, role: task.role, effort: arm === "a" ? null : "medium", task: task.id });
+            if (entry.collected.model !== journal.model) throw Error("the frozen concrete model changed");
+            if (arm === "a" && !entry.grade.ok) { journal.phase = "aborted"; save(path.join(dir, "journal.json"), journal); throw Error("a control failed: no routing is earned and no resampling is allowed"); }
+        }
+    }
+    } catch (error) {
+        journal.phase = "aborted";
+        journal.fault = error.message;
+        save(path.join(dir, "journal.json"), journal);
+        throw error;
+    }
+    journal.phase = "complete";
+    save(path.join(dir, "journal.json"), journal);
+    return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try { process.exitCode = run(); } catch (error) { process.stderr.write(`persona acquisition: ${error.message}\n`); process.exitCode = 2; }
+}

package/evals/ab/personas/protocol/first-outcome.mjs.txt

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// Acquire the frozen persona comparisons through native children; never run by a recipe.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { spawnSync, execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { cloneTree, childEnv, transcriptOf } from "./warm.mjs";
+import { readTranscript } from "./ledger.mjs";
+import { CORPUS, grade } from "../evals/ab/personas/grader.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PARENT_MODEL = "claude-sonnet-5-5";
+const ROLES = ["implementer", "reviewer", "librarian"];
+const FROZEN = ["evals/ab/personas/corpus.json", "evals/ab/personas/grader.mjs", "cli/persona-routing.test.mjs"];
+const digest = bytes => createHash("sha256").update(bytes).digest("hex");
+const sha = file => digest(fs.readFileSync(file));
+const json = file => JSON.parse(fs.readFileSync(file, "utf8"));
+const save = (file, value) => fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+const git = (...args) => execFileSync("git", args, { cwd: ROOT, encoding: "utf8" }).trim();
+const records = file => fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line));
+
+export function parentPrompt(role, taskFile, effort) {
+    const input = {
+        subagent_type: `portulan:${role}`, description: "Frozen persona artifact probe",
+        prompt: `Read ${taskFile} and follow its task exactly. This is an artifact proposal, not a completed repository change.`,
+        run_in_background: false,
+        ...(effort === null ? {} : { effort }),
+    };
+    return "This is a frozen evaluation. Invoke the Agent tool exactly once with these input values: " + JSON.stringify(input) +
+        ". Do not supply a child model or change the effort. Wait for that foreground child to finish. Do not answer its task yourself or invoke another child. After completion reply only DONE.";
+}
+
+function response(file) {
+    const raw = fs.readFileSync(file, "utf8").trim();
+    let value;
+    try { value = JSON.parse(raw); } catch { throw Error("the CLI returned no single JSON result"); }
+    if (value.type !== "result" || value.is_error || value.subtype !== "success" || typeof value.session_id !== "string") throw Error("the CLI did not complete successfully");
+    return value;
+}
+
+function answerOf(rows) {
+    const messages = rows.filter(r => r.type === "assistant" && r.message?.model !== "<synthetic>" && Array.isArray(r.message?.content));
+    const last = messages.at(-1)?.message.id;
+    if (!last) throw Error("child has no final assistant message");
+    const blocks = messages.filter(r => r.message.id === last).flatMap(r => r.message.content).filter(b => b.type === "text");
+    return [...new Set(blocks.map(b => b.text))].join("\n").trim();
+}
+
+export function nativeInvocation(rows, role, effort) {
+    const calls = rows.filter(r => r.type === "assistant").flatMap(r => r.message?.content ?? []).filter(b => b.type === "tool_use" && ["Agent", "Task"].includes(b.name));
+    const unique = [...new Map(calls.map(call => [call.id, call])).values()];
+    if (unique.length !== 1) throw Error("a parent must invoke exactly one native child");
+    const input = unique[0].input;
+    if (input?.subagent_type !== `portulan:${role}` || Object.hasOwn(input, "model") || (input.effort ?? null) !== effort) throw Error("the parent did not select the frozen role/inherited model/effort");
+    if (input.run_in_background === true) throw Error("a background child is not a completed foreground comparison");
+    return { type: input.subagent_type, effort: input.effort ?? null, prompt: input.prompt };
+}
+
+function collectCall(entry, dir, tree, env) {
+    if (entry.exit !== 0 || entry.timedOut) throw Error("a parent invocation failed or timed out");
+    const result = response(path.join(dir, entry.stdout));
+    if (result.session_id !== entry.sessionId) throw Error("the result belongs to a different parent session");
+    const transcript = transcriptOf(result.session_id, tree, env);
+    if (transcript === null) throw Error("the completed parent transcript is unavailable");
+    const rows = records(transcript);
+    const invocation = nativeInvocation(rows, entry.role, entry.effort);
+    if (invocation.prompt !== entry.childPrompt) throw Error("the child did not receive the frozen prompt verbatim");
+    const agentDir = path.join(path.dirname(transcript), result.session_id, "subagents");
+    const children = fs.readdirSync(agentDir).filter(name => /^agent-.*\.jsonl$/.test(name));
+    if (children.length !== 1) throw Error("the parent has other than one child transcript");
+    const child = path.join(agentDir, children[0]);
+    const childRows = records(child);
+    const parentUsage = readTranscript(transcript), childUsage = readTranscript(child);
+    if (parentUsage.malformed || childUsage.malformed) throw Error("a transcript has malformed records");
+    const parent = parentUsage.requests.filter(r => !r.synthetic && !r.sidechain);
+    const requests = childUsage.requests.filter(r => !r.synthetic);
+    if (!parent.length || !requests.length) throw Error("parent or child usage is missing");
+    const models = [...new Set([...parent, ...requests].map(r => r.model))];
+    if (models.length !== 1 || !models[0]) throw Error("inherited parent/child concrete models disagree or are unknown");
+    const efforts = [...new Set(requests.map(r => r.effort))];
+    if (entry.effort !== null && (efforts.length !== 1 || efforts[0] !== entry.effort)) throw Error("host usage does not establish the requested child effort");
+    const target = path.join(dir, "originals", entry.key);
+    fs.mkdirSync(target, { recursive: true });
+    fs.copyFileSync(transcript, path.join(target, "parent.jsonl"));
+    fs.copyFileSync(child, path.join(target, "child.jsonl"));
+    return {
+        invocation: { type: invocation.type, effort: invocation.effort, promptSha256: digest(invocation.prompt) },
+        model: models[0], efforts, parentEfforts: [...new Set(parent.map(r => r.effort))],
+        answer: answerOf(childRows), usage: { parent, child: requests },
+        raw: { result: sha(path.join(dir, entry.stdout)), parent: sha(path.join(target, "parent.jsonl")), child: sha(path.join(target, "child.jsonl")) },
+        transcriptDuplicates: { parent: parentUsage.duplicates, child: childUsage.duplicates },
+    };
+}
+
+function partialUsage(entry, dir, tree, env) {
+    const transcript = transcriptOf(entry.sessionId, tree, env);
+    if (transcript === null) return { parent: [], children: [], unavailable: true };
+    const target = path.join(dir, "originals", entry.key);
+    fs.mkdirSync(target, { recursive: true });
+    fs.copyFileSync(transcript, path.join(target, "parent.jsonl"));
+    const agentDir = path.join(path.dirname(transcript), entry.sessionId, "subagents");
+    const children = fs.existsSync(agentDir) ? fs.readdirSync(agentDir).filter(name => /^agent-.*\.jsonl$/.test(name)).map(name => {
+        const file = path.join(agentDir, name);
+        fs.copyFileSync(file, path.join(target, name));
+        return { usage: readTranscript(file).requests, sha256: sha(file) };
+    }) : [];
+    return { parent: readTranscript(transcript).requests, parentSha256: sha(transcript), children, unavailable: false };
+}
+
+function initialize(dir) {
+    if (fs.existsSync(dir)) throw Error("acquisition directory already exists; no automatic retry or resampling");
+    fs.mkdirSync(dir, { recursive: true });
+    const frozen = Object.fromEntries(FROZEN.map(rel => [rel, sha(path.join(ROOT, rel))]));
+    const tree = cloneTree(ROOT, path.join(dir, "tree"));
+    const version = execFileSync("claude", ["--version"], { encoding: "utf8" }).trim();
+    const journal = { version: 1, phase: "frozen", started: new Date().toISOString(), source: git("rev-parse", "HEAD"), host: version, frozen,
+        parentPolicy: { model: PARENT_MODEL, effort: "high", configuredEstimateCeilingUsd: 1, tools: "Agent,Read" }, instrumentSha256: sha(fileURLToPath(import.meta.url)), calls: [] };
+    fs.mkdirSync(path.join(dir, "frozen"));
+    for (const rel of FROZEN) fs.copyFileSync(path.join(ROOT, rel), path.join(dir, "frozen", path.basename(rel)));
+    fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "frozen", "acquire.mjs"));
+    fs.mkdirSync(path.join(dir, "tasks"));
+    for (const task of CORPUS.cases) save(path.join(dir, "tasks", task.id + ".json"), { role: task.role, task: task.task });
+    save(path.join(dir, "journal.json"), journal);
+    return { journal, tree };
+}
+
+function checkFrozen(journal, dir, tree) {
+    if (!journal.qualityFrozen) throw Error("quality inputs were not frozen");
+    for (const [rel, expected] of Object.entries(journal.qualityFrozen.semantic)) if (sha(path.join(ROOT, rel)) !== expected) throw Error("frozen semantic source changed");
+    for (const [id, expected] of Object.entries(journal.qualityFrozen.tasks)) if (sha(path.join(dir, "tasks", id + ".json")) !== expected) throw Error("frozen task bytes changed");
+    if (sha(fileURLToPath(import.meta.url)) !== journal.qualityFrozen.instrument) throw Error("frozen acquisition instrument changed");
+    if (execFileSync("git", ["rev-parse", "HEAD"], { cwd: tree, encoding: "utf8" }).trim() !== journal.source || execFileSync("git", ["status", "--porcelain"], { cwd: tree, encoding: "utf8" }).trim()) throw Error("frozen plugin checkout changed");
+}
+
+function call(journal, dir, tree, { key, role, effort, task, model = PARENT_MODEL }) {
+    if (task !== "mechanism") checkFrozen(journal, dir, tree);
+    const taskFile = path.join(dir, "tasks", task + ".json");
+    const env = childEnv(process.env, { cache_lifetime: "5m" }, { local: true });
+    const childPrompt = `Read ${taskFile} and follow its task exactly. This is an artifact proposal, not a completed repository change.`;
+    const sessionId = randomUUID();
+    const args = ["-p", parentPrompt(role, taskFile, effort), "--output-format", "json", "--session-id", sessionId, "--effort", "high", "--plugin-dir", tree,
+        "--tools", "Agent,Read", "--allowedTools", `Agent(portulan:${role}),Read`, "--add-dir", path.join(dir, "tasks"), "--max-budget-usd", "1", ...(model ? ["--model", model] : [])];
+    const entry = { key, role, effort, task, childPrompt, model, sessionId, argv: args, instrumentSha256: sha(fileURLToPath(import.meta.url)), started: new Date().toISOString(), state: "started", stdout: key + ".stdout.json", stderr: key + ".stderr.txt" };
+    journal.calls.push(entry);
+    save(path.join(dir, "journal.json"), journal);
+    const started = Date.now();
+    const run = spawnSync("claude", args, { cwd: tree, env, encoding: "utf8", timeout: 180000, maxBuffer: 4 * 1024 * 1024 });
+    fs.writeFileSync(path.join(dir, entry.stdout), run.stdout ?? "");
+    fs.writeFileSync(path.join(dir, entry.stderr), run.stderr ?? "");
+    Object.assign(entry, { exit: run.status, timedOut: run.error?.code === "ETIMEDOUT", durationMs: Date.now() - started, ended: new Date().toISOString() });
+    try {
+        entry.collected = collectCall(entry, dir, tree, env);
+        entry.state = "complete";
+        if (task !== "mechanism") entry.grade = grade(CORPUS.cases.find(c => c.id === task), entry.collected.answer);
+    } catch (error) {
+        entry.state = "invalid";
+        entry.fault = error.message;
+        try { entry.partial = partialUsage(entry, dir, tree, env); } catch { entry.partial = { unavailable: true }; }
+        journal.phase = "aborted";
+    }
+    save(path.join(dir, "journal.json"), journal);
+    process.stdout.write(`${key}: ${entry.state}${entry.grade ? `, semantic ${entry.grade.ok ? "PASS" : "FAIL"}` : ""}\n`);
+    if (entry.state !== "complete") throw Error(entry.fault);
+    return entry;
+}
+
+export function run(argv = process.argv.slice(2)) {
+    const [mode, named] = argv;
+    if (!["probe", "freeze", "run"].includes(mode) || !named || argv.length !== 2) throw Error("usage: node cli/acquire-personas.mjs probe|freeze|run <private-directory>");
+    const dir = path.resolve(named);
+    if (mode === "probe") {
+        const { journal, tree } = initialize(dir);
+        save(path.join(dir, "tasks", "mechanism.json"), { role: "implementer", task: "Read your role charter, then reply exactly MECHANISM_OK. This tests native effort selection only; do not edit files or call other tools." });
+        const entry = call(journal, dir, tree, { key: "mechanism-medium", role: "implementer", effort: "medium", task: "mechanism" });
+        if (entry.collected.answer !== "MECHANISM_OK") throw Error("mechanism child did not finish its fixed task");
+        journal.model = entry.collected.model;
+        journal.phase = "mechanism-demonstrated";
+        save(path.join(dir, "journal.json"), journal);
+        return 0;
+    }
+    const journal = json(path.join(dir, "journal.json"));
+    const tree = path.join(dir, "tree");
+    if (mode === "freeze") {
+        if (journal.phase !== "mechanism-demonstrated" || journal.calls.length !== 1 || journal.qualityFrozen) throw Error("quality freeze requires one valid probe and no outcomes or prior freeze");
+        fs.mkdirSync(path.join(dir, "frozen-quality"));
+        for (const rel of FROZEN) fs.copyFileSync(path.join(ROOT, rel), path.join(dir, "frozen-quality", path.basename(rel)));
+        fs.copyFileSync(fileURLToPath(import.meta.url), path.join(dir, "frozen-quality", "acquire.mjs"));
+        for (const task of CORPUS.cases) save(path.join(dir, "tasks", task.id + ".json"), { role: task.role, task: task.task });
+        journal.qualityFrozen = {
+            at: new Date().toISOString(), semantic: Object.fromEntries(FROZEN.map(rel => [rel, sha(path.join(ROOT, rel))])),
+            instrument: sha(fileURLToPath(import.meta.url)), tasks: Object.fromEntries(CORPUS.cases.map(task => [task.id, sha(path.join(dir, "tasks", task.id + ".json"))])),
+            parentPolicy: journal.parentPolicy,
+            order: CORPUS.cases.flatMap((task, i) => (i % 2 === 0 ? ["a", "b"] : ["b", "a"]).map(arm => `${task.id}-${arm}`)),
+            roles: Object.fromEntries(ROLES.map(role => [role, { persona: sha(path.join(tree, "core/personas", role + ".md")), binding: sha(path.join(tree, "agents", role + ".md")) }])),
+        };
+        journal.phase = "quality-frozen";
+        save(path.join(dir, "journal.json"), journal);
+        checkFrozen(journal, dir, tree);
+        return 0;
+    }
+    if (journal.phase !== "quality-frozen" || journal.calls.length !== 1) throw Error("no untouched quality freeze; refusing retry or resampling");
+    checkFrozen(journal, dir, tree);
+    journal.instrument = sha(fileURLToPath(import.meta.url));
+    journal.phase = "acquiring";
+    save(path.join(dir, "journal.json"), journal);
+    try {
+    for (const [i, task] of CORPUS.cases.entries()) {
+        for (const arm of i % 2 === 0 ? ["a", "b"] : ["b", "a"]) {
+            const entry = call(journal, dir, tree, { key: `${task.id}-${arm}`, role: task.role, effort: arm === "a" ? null : "medium", task: task.id });
+            if (entry.collected.model !== journal.model) throw Error("the frozen concrete model changed");
+            if (arm === "a" && !entry.grade.ok) { journal.phase = "aborted"; save(path.join(dir, "journal.json"), journal); throw Error("a control failed: no routing is earned and no resampling is allowed"); }
+        }
+    }
+    } catch (error) {
+        journal.phase = "aborted";
+        journal.fault = error.message;
+        save(path.join(dir, "journal.json"), journal);
+        throw error;
+    }
+    journal.phase = "complete";
+    save(path.join(dir, "journal.json"), journal);
+    return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try { process.exitCode = run(); } catch (error) { process.stderr.write(`persona acquisition: ${error.message}\n`); process.exitCode = 2; }
+}