@companion-ai/feynman 0.3.4 → 0.3.5

package/RELEASES.md

@@ -4,6 +4,19 @@ This file is the public release history for Feynman. Keep entries user-facing: w
 
 GitHub release notes are generated from the matching `## vX.Y.Z` section in this file.
 
+## v0.3.5 - 2026-06-28
+
+### Pi Runtime
+
+- Refreshed the bundled Pi runtime from `0.79.10` to `0.80.2` across all four packages (`pi-coding-agent`, `pi-agent-core`, `pi-ai`, `pi-tui`). This restores the `@earendil-works/pi-ai/compat` entrypoint and loader aliases used by optional packages such as `pi-web-access`, fixing the extension-load failure reported in #183.
+- Feynman's package installer now derives legacy `@mariozechner/*` alias versions from the current canonical `@earendil-works/*` runtime packages first, so stale legacy package roots cannot seed old Pi peer versions during `feynman update`.
+- Updated the Pi TUI patcher for the current upstream overflow-check layout so overwide rendered lines are clipped instead of crashing the session renderer.
+
+### Validation
+
+- Added regression coverage for the current Pi TUI overflow block, the `@earendil-works/pi-ai/compat` release-note boundary, and legacy Pi alias derivation from current runtime metadata.
+- Rebuilt and inspected the vendored runtime workspace so the packaged archive includes Pi `0.80.2`, `@earendil-works/pi-ai/dist/compat.js`, and the current/legacy `/compat` extension-loader aliases.
+
 ## v0.3.4 - 2026-06-12
 
 ### Research

package/dist/model/catalog.js

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { getEnvApiKey } from "@earendil-works/pi-ai";
+import { getEnvApiKey } from "@earendil-works/pi-ai/compat";
 import { createModelRegistry } from "./registry.js";
 const PRO_CLASS_MODEL_PATTERN = /(?:^|[-_.:/])pro(?:$|[-_.:/])/i;
 const PROVIDER_LABELS = {

package/dist/pi/package-ops.js

@@ -17,7 +17,7 @@ const FILTERED_INSTALL_OUTPUT_PATTERNS = [
     /^run `npm fund` for details$/i,
 ];
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const PI_RUNTIME_FALLBACK_VERSION = "0.79.10";
+const PI_RUNTIME_FALLBACK_VERSION = "0.80.2";
 const LEGACY_PI_RUNTIME_PACKAGE_ALIASES = {
     "@mariozechner/pi-agent-core": "@earendil-works/pi-agent-core",
     "@mariozechner/pi-ai": "@earendil-works/pi-ai",
@@ -114,6 +114,12 @@ function isPiRuntimePackageName(packageName) {
     return packageName.startsWith("pi-") || packageName.includes("/pi-");
 }
 function resolveRuntimePeerSpec(packageName) {
+    const aliasTarget = LEGACY_PI_RUNTIME_PACKAGE_ALIASES[packageName];
+    if (aliasTarget) {
+        const targetSpec = resolveRuntimePeerSpec(aliasTarget);
+        const targetVersion = targetSpec?.match(/@(\d+\.\d+\.\d+)$/)?.[1] ?? PI_RUNTIME_FALLBACK_VERSION;
+        return `${packageName}@npm:${aliasTarget}@${targetVersion}`;
+    }
     for (const packageRoot of [
         resolve(APP_ROOT, "node_modules", packageName),
         resolve(APP_ROOT, ".feynman", "npm", "node_modules", packageName),
@@ -133,12 +139,6 @@ function resolveRuntimePeerSpec(packageName) {
             continue;
         }
     }
-    const aliasTarget = LEGACY_PI_RUNTIME_PACKAGE_ALIASES[packageName];
-    if (aliasTarget) {
-        const targetSpec = resolveRuntimePeerSpec(aliasTarget);
-        const targetVersion = targetSpec?.match(/@(\d+\.\d+\.\d+)$/)?.[1] ?? PI_RUNTIME_FALLBACK_VERSION;
-        return `${packageName}@npm:${aliasTarget}@${targetVersion}`;
-    }
     return FALLBACK_RUNTIME_PEER_SPECS[packageName];
 }
 function withRuntimePeerSpecs(specs) {

package/dist/rank/paper-rank.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { XMLParser } from "fast-xml-parser";
+import { buildResearchRunId, createResearchArtifact, validateResearchRun } from "../research/contracts.js";
 export const DEFAULT_RANK_LIMIT = 25;
 export const MAX_RANK_LIMIT = 100;
 export const DEFAULT_FULL_TEXT_TOP = 0;
@@ -3685,6 +3686,7 @@ function renderPaperAccessReport(input) {
 }
 function writePaperRankArtifacts(input) {
     mkdirSync(input.outputDir, { recursive: true });
+    const researchRunPath = resolve(input.outputDir, `${input.slug}-research-run.json`);
     const reportPath = resolve(input.outputDir, `${input.slug}-paper-rank.md`);
     const papersPath = resolve(input.outputDir, `${input.slug}-papers.jsonl`);
     const scoresPath = resolve(input.outputDir, `${input.slug}-scores.jsonl`);
@@ -3704,6 +3706,33 @@ function writePaperRankArtifacts(input) {
     const critiquePath = input.critiques.length > 0 ? resolve(input.outputDir, `${input.slug}-critique.md`) : undefined;
     const modelSynthesisPath = input.synthesis.status === "generated" && input.synthesis.text ? resolve(input.outputDir, `${input.slug}-model-synthesis.md`) : undefined;
     const provenancePath = resolve(input.outputDir, `${input.slug}-rank.provenance.md`);
+    const artifacts = {
+        researchRunPath,
+        reportPath,
+        papersPath,
+        scoresPath,
+        scoreAuditPath,
+        sensitivityPath,
+        graphPath,
+        graphExplorerPath,
+        fieldMapPath,
+        provenancePath,
+        ...(calibrationPath ? { calibrationPath } : {}),
+        ...(calibrationTemplatePath ? { calibrationTemplatePath } : {}),
+        ...(calibrationGuidePath ? { calibrationGuidePath } : {}),
+        ...(reproductionLedgerPath ? { reproductionLedgerPath } : {}),
+        ...(reproductionTemplatePath ? { reproductionTemplatePath } : {}),
+        ...(replicationPlanPath ? { replicationPlanPath } : {}),
+        ...(synthesisPacketPath ? { synthesisPacketPath } : {}),
+        ...(synthesisPromptPath ? { synthesisPromptPath } : {}),
+        ...(critiquePath ? { critiquePath } : {}),
+        ...(modelSynthesisPath ? { modelSynthesisPath } : {}),
+    };
+    const researchRun = buildPaperRankResearchRun(input, artifacts);
+    const researchRunValidation = validateResearchRun(researchRun);
+    if (!researchRunValidation.valid) {
+        throw new Error(`Invalid PaperRank ResearchRun manifest: ${researchRunValidation.errors.join("; ")}`);
+    }
     writeFileSync(reportPath, renderRankReport(input), "utf8");
     writeFileSync(papersPath, input.papers.map((paper) => JSON.stringify(serializePaperRecord(paper))).join("\n") + "\n", "utf8");
     writeFileSync(scoresPath, input.scores.map((score) => JSON.stringify(score)).join("\n") + "\n", "utf8");
@@ -3733,26 +3762,159 @@ function writePaperRankArtifacts(input) {
     if (modelSynthesisPath && input.synthesis.text)
         writeFileSync(modelSynthesisPath, renderModelSynthesisReport(input), "utf8");
     writeFileSync(provenancePath, renderRankProvenance(input), "utf8");
+    writeFileSync(researchRunPath, JSON.stringify(researchRun, null, 2) + "\n", "utf8");
+    return artifacts;
+}
+function definedArtifact(artifact) {
+    return artifact !== undefined;
+}
+function buildPaperRankResearchRun(input, artifacts) {
+    const papersById = new Map(input.papers.map((paper) => [paper.paperId, paper]));
+    const rolesByPaper = new Map(input.fieldMap.paperRoles.map((role) => [role.paperId, role.roles]));
+    const reproductionByPaper = new Map(input.reproduction.papers.map((paper) => [paper.paperId, paper]));
+    const researchArtifacts = [
+        createResearchArtifact({ kind: "manifest", path: artifacts.researchRunPath, label: "ResearchRun manifest", role: "research_run_manifest", format: "application/json" }),
+        createResearchArtifact({ kind: "report", path: artifacts.reportPath, label: "PaperRank ranked brief", role: "primary_ranked_brief", primary: true, format: "text/markdown" }),
+        createResearchArtifact({ kind: "jsonl", path: artifacts.papersPath, label: "normalized papers", role: "paper_records", format: "application/jsonl" }),
+        createResearchArtifact({ kind: "jsonl", path: artifacts.scoresPath, label: "component scores", role: "score_records", format: "application/jsonl" }),
+        createResearchArtifact({ kind: "audit", path: artifacts.scoreAuditPath, label: "score audit", role: "score_explanation", format: "text/markdown" }),
+        createResearchArtifact({ kind: "json", path: artifacts.sensitivityPath, label: "rank sensitivity", role: "weight_sensitivity", format: "application/json" }),
+        createResearchArtifact({ kind: "graph", path: artifacts.graphPath, label: "citation graph", role: "citation_graph", format: "application/json" }),
+        createResearchArtifact({ kind: "html", path: artifacts.graphExplorerPath, label: "graph explorer", role: "graph_visualizer", format: "text/html" }),
+        createResearchArtifact({ kind: "json", path: artifacts.fieldMapPath, label: "field map", role: "field_structure", format: "application/json" }),
+        createResearchArtifact({ kind: "provenance", path: artifacts.provenancePath, label: "rank provenance", role: "source_accounting", format: "text/markdown" }),
+        createResearchArtifact({ kind: "json", path: artifacts.calibrationPath, label: "score calibration", role: "read_order_calibration", format: "application/json" }),
+        createResearchArtifact({ kind: "template", path: artifacts.calibrationTemplatePath, label: "calibration template", role: "read_order_preference_template", format: "application/json" }),
+        createResearchArtifact({ kind: "report", path: artifacts.calibrationGuidePath, label: "calibration guide", role: "read_order_calibration_instructions", format: "text/markdown" }),
+        createResearchArtifact({ kind: "ledger", path: artifacts.reproductionLedgerPath, label: "reproduction ledger", role: "completed_reproduction_evidence", format: "application/json" }),
+        createResearchArtifact({ kind: "template", path: artifacts.reproductionTemplatePath, label: "reproduction notes template", role: "reproduction_evidence_template", format: "application/json" }),
+        createResearchArtifact({ kind: "plan", path: artifacts.replicationPlanPath, label: "replication plan", role: "reproduction_plan", format: "text/markdown" }),
+        createResearchArtifact({ kind: "json", path: artifacts.synthesisPacketPath, label: "model synthesis packet", role: "bounded_model_handoff", format: "application/json" }),
+        createResearchArtifact({ kind: "prompt", path: artifacts.synthesisPromptPath, label: "model synthesis prompt", role: "bounded_model_prompt", format: "text/markdown" }),
+        createResearchArtifact({ kind: "report", path: artifacts.critiquePath, label: "research critique", role: "deterministic_research_critique", format: "text/markdown" }),
+        createResearchArtifact({ kind: "model_output", path: artifacts.modelSynthesisPath, label: "model synthesis", role: "generated_synthesis", format: "text/markdown" }),
+    ].filter(definedArtifact);
+    const fullTextAvailable = input.papers.filter((paper) => paper.fullTextStatus === "available").length;
+    const fullTextAttempted = input.papers.filter((paper) => Boolean(paper.fullTextStatus)).length;
+    const tools = [
+        {
+            id: input.source === "fixture" ? "fixture.openalex" : "openalex.works",
+            kind: "source_adapter",
+            label: input.source === "fixture" ? "OpenAlex fixture source" : "OpenAlex works search",
+            status: "completed",
+            outputArtifacts: [artifacts.papersPath],
+            caveats: input.source === "fixture" ? ["Fixture source is deterministic test data, not live provider evidence."] : [],
+        },
+        {
+            id: "feynman.paper_rank.scoring",
+            kind: "rank_scorer",
+            label: "PaperRank deterministic scoring",
+            status: "completed",
+            outputArtifacts: [artifacts.scoresPath, artifacts.scoreAuditPath],
+            caveats: ["Methodology and reproducibility are screening signals; they are not completed claim validation."],
+        },
+        {
+            id: "feynman.paper_rank.field_map",
+            kind: "artifact_exporter",
+            label: "Field map and citation graph artifacts",
+            status: "completed",
+            outputArtifacts: [artifacts.fieldMapPath, artifacts.graphPath, artifacts.graphExplorerPath],
+        },
+        {
+            id: "feynman.paper_rank.full_text",
+            kind: "access_resolver",
+            label: "source-specific full-text enrichment",
+            status: input.fullTextTop > 0 ? (fullTextAttempted > 0 ? "completed" : "partial") : "not_run",
+            outputArtifacts: [artifacts.papersPath, artifacts.scoresPath],
+            caveats: ["Raw full-text bodies are not written to PaperRank artifacts."],
+        },
+        ...(input.synthesis.requested ? [{
+                id: "feynman.paper_rank.model_synthesis",
+                kind: "model",
+                label: "bounded PaperRank model synthesis",
+                status: input.synthesis.status === "generated" ? "completed" : input.synthesis.status === "failed" ? "failed" : "partial",
+                outputArtifacts: [artifacts.synthesisPacketPath, artifacts.synthesisPromptPath, artifacts.modelSynthesisPath].filter((path) => Boolean(path)),
+                caveats: ["Deterministic artifacts remain the audit trail; generated synthesis is a narrative handoff."],
+            }] : []),
+    ];
     return {
-        reportPath,
-        papersPath,
-        scoresPath,
-        scoreAuditPath,
-        sensitivityPath,
-        graphPath,
-        graphExplorerPath,
-        fieldMapPath,
-        provenancePath,
-        ...(calibrationPath ? { calibrationPath } : {}),
-        ...(calibrationTemplatePath ? { calibrationTemplatePath } : {}),
-        ...(calibrationGuidePath ? { calibrationGuidePath } : {}),
-        ...(reproductionLedgerPath ? { reproductionLedgerPath } : {}),
-        ...(reproductionTemplatePath ? { reproductionTemplatePath } : {}),
-        ...(replicationPlanPath ? { replicationPlanPath } : {}),
-        ...(synthesisPacketPath ? { synthesisPacketPath } : {}),
-        ...(synthesisPromptPath ? { synthesisPromptPath } : {}),
-        ...(critiquePath ? { critiquePath } : {}),
-        ...(modelSynthesisPath ? { modelSynthesisPath } : {}),
+        schemaVersion: "feynman.researchRun.v1",
+        runId: buildResearchRunId({ workflow: "paper_rank", slug: input.slug, generatedAt: input.generatedAt }),
+        workflow: "paper_rank",
+        slug: input.slug,
+        topic: input.topic,
+        generatedAt: input.generatedAt,
+        status: "completed",
+        researchJobs: [
+            "discovering_prior_art",
+            "reading_paper_content",
+            "ranking_evidence",
+            "verifying_claims",
+            "planning_reproduction",
+            "synthesizing_artifacts",
+            "visualizing_research_structure",
+            "improving_research_loop",
+        ],
+        sources: [
+            {
+                id: input.source,
+                kind: input.source === "fixture" ? "fixture" : "paper_index",
+                url: input.sourceUrl,
+                fields: ["works", "metadata", "citations", "open_access", "abstracts"],
+            },
+            ...(input.fullTextTop > 0 ? [{
+                    id: "source-specific-full-text",
+                    kind: "full_text",
+                    fields: ["fullTextStatus", "fullTextLength", "fullTextSections", "rubric"],
+                }] : []),
+        ],
+        papers: input.scores.map((score) => {
+            const paper = papersById.get(score.paperId);
+            const reproduction = reproductionByPaper.get(score.paperId);
+            return {
+                id: score.paperId,
+                title: score.title,
+                rank: score.rank,
+                score: score.readFirstScore,
+                ...(score.year ? { year: score.year } : {}),
+                ...(paper?.doi ? { doi: paper.doi } : {}),
+                ...(paper?.arxivId ? { arxivId: paper.arxivId } : {}),
+                ...(paper?.pmid ? { pmid: paper.pmid } : {}),
+                ...(paper?.pmcid ? { pmcid: paper.pmcid } : {}),
+                ...(paper?.openAlexId ? { openAlexId: paper.openAlexId } : {}),
+                ...(paper?.urls[0]?.url ? { url: paper.urls[0].url } : {}),
+                ...(rolesByPaper.has(score.paperId) ? { roles: rolesByPaper.get(score.paperId) } : {}),
+                verification: {
+                    state: reproduction?.status && reproduction.status !== "not_started" ? "partial" : "not_checked",
+                    summary: reproduction?.status && reproduction.status !== "not_started"
+                        ? `External reproduction note recorded: ${reproduction.status}.`
+                        : "No completed reproduction note supplied for this run.",
+                },
+            };
+        }),
+        entities: [],
+        tools,
+        artifacts: researchArtifacts,
+        nextActions: input.nextResearchActions.nextActions.slice(0, 20).map((action) => ({
+            id: action.id,
+            title: action.title,
+            priority: action.priority,
+            artifactPointers: action.artifactPointers,
+        })),
+        verification: {
+            state: "partial",
+            summary: `PaperRank ranked ${input.scores.length} seed papers, expanded ${input.citationExpansion.expandedPaperCount} citation-neighborhood papers, fetched full text for ${fullTextAvailable}/${input.fullTextTop} requested papers, and generated ${input.nextResearchActions.summary.actionCount} next research actions.`,
+            caveats: [
+                "PaperRank is read-order triage, not a completed scientific validation.",
+                "Missing evidence means Feynman did not see it in fetched sources; it is not proof the paper lacks it.",
+                "Raw full-text bodies are not stored in the ResearchRun manifest.",
+            ],
+        },
+        constraints: {
+            rawFullTextStored: false,
+            promptsStored: Boolean(artifacts.synthesisPromptPath),
+            modelOutputsStored: Boolean(artifacts.modelSynthesisPath),
+        },
     };
 }
 function renderScoreAuditReport(input) {

package/dist/research/contracts.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+export const researchJobValues = [
+    "discovering_prior_art",
+    "reading_paper_content",
+    "extracting_research_entities",
+    "ranking_evidence",
+    "verifying_claims",
+    "planning_reproduction",
+    "running_research_experiments",
+    "synthesizing_artifacts",
+    "visualizing_research_structure",
+    "improving_research_loop",
+];
+export const researchRunStatusValues = ["planned", "running", "completed", "partial", "blocked", "failed"];
+export const verificationStateValues = ["not_checked", "inferred", "partial", "verified", "blocked", "failed"];
+export const researchArtifactKindValues = [
+    "report",
+    "json",
+    "jsonl",
+    "graph",
+    "html",
+    "audit",
+    "provenance",
+    "template",
+    "prompt",
+    "model_output",
+    "ledger",
+    "plan",
+    "manifest",
+];
+export function buildResearchRunId(input) {
+    const digest = createHash("sha256")
+        .update(`${input.workflow}\0${input.slug}\0${input.generatedAt}`)
+        .digest("hex")
+        .slice(0, 16);
+    return `${input.workflow}:${input.slug}:${digest}`;
+}
+export function createResearchArtifact(input) {
+    if (!input.path)
+        return undefined;
+    return {
+        kind: input.kind,
+        path: input.path,
+        label: input.label,
+        role: input.role,
+        ...(input.primary === undefined ? {} : { primary: input.primary }),
+        ...(input.format ? { format: input.format } : {}),
+    };
+}
+export function validateResearchRun(run) {
+    const errors = [];
+    if (run.schemaVersion !== "feynman.researchRun.v1")
+        errors.push("schemaVersion must be feynman.researchRun.v1");
+    if (!run.runId.trim())
+        errors.push("runId is required");
+    if (!run.workflow.trim())
+        errors.push("workflow is required");
+    if (!run.slug.trim())
+        errors.push("slug is required");
+    if (!run.topic.trim())
+        errors.push("topic is required");
+    if (!Date.parse(run.generatedAt))
+        errors.push("generatedAt must be an ISO timestamp");
+    if (!researchRunStatusValues.includes(run.status))
+        errors.push(`status is unsupported: ${run.status}`);
+    if (run.researchJobs.length === 0)
+        errors.push("researchJobs must be non-empty");
+    for (const job of run.researchJobs) {
+        if (!researchJobValues.includes(job))
+            errors.push(`researchJobs contains unsupported value: ${job}`);
+    }
+    if (run.artifacts.length === 0)
+        errors.push("artifacts must be non-empty");
+    if (!run.artifacts.some((artifact) => artifact.primary))
+        errors.push("at least one artifact must be primary");
+    for (const artifact of run.artifacts) {
+        if (!researchArtifactKindValues.includes(artifact.kind))
+            errors.push(`artifact kind is unsupported: ${artifact.kind}`);
+        if (!artifact.path.trim())
+            errors.push(`artifact path is required for ${artifact.label}`);
+        if (!artifact.role.trim())
+            errors.push(`artifact role is required for ${artifact.label}`);
+    }
+    if (!verificationStateValues.includes(run.verification.state))
+        errors.push(`verification state is unsupported: ${run.verification.state}`);
+    if (run.constraints.rawFullTextStored)
+        errors.push("ResearchRun manifests must not mark rawFullTextStored true");
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/research/plugin-manifest.js

@@ -0,0 +1,131 @@
+import { isAbsolute, normalize } from "node:path";
+import { researchJobValues } from "./contracts.js";
+export const feynmanPluginSlotValues = [
+    "source_adapters",
+    "access_resolvers",
+    "entity_extractors",
+    "rank_scorers",
+    "experiment_runners",
+    "artifact_exporters",
+    "visualizers",
+    "subagents",
+    "mcp_servers",
+];
+const knownTopLevelKeys = new Set(["manifest_version", "name", "version", "description", "research_jobs", "slots", "pi", "requires_env"]);
+const piResourceKeys = new Set(["extensions", "skills", "prompts", "themes"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSafePackageName(name) {
+    return /^[a-z0-9][a-z0-9._-]*$/i.test(name) && !name.includes("..") && !name.includes("/") && !name.includes("\\");
+}
+function isSafeRelativePath(path) {
+    if (!path.trim())
+        return false;
+    if (isAbsolute(path))
+        return false;
+    const normalized = normalize(path).replaceAll("\\", "/");
+    return normalized !== ".." && !normalized.startsWith("../") && !normalized.includes("/../");
+}
+function validatePathList(input) {
+    if (!Array.isArray(input.value)) {
+        input.errors.push(`${input.owner} must be an array of relative paths`);
+        return false;
+    }
+    for (const [index, path] of input.value.entries()) {
+        if (typeof path !== "string") {
+            input.errors.push(`${input.owner}[${index}] must be a string path`);
+            continue;
+        }
+        if (!isSafeRelativePath(path)) {
+            input.errors.push(`${input.owner}[${index}] must stay inside the plugin root`);
+        }
+    }
+    return true;
+}
+export function validateFeynmanPluginManifest(value) {
+    const errors = [];
+    const warnings = [];
+    if (!isRecord(value)) {
+        return { valid: false, errors: ["manifest must be an object"], warnings };
+    }
+    for (const key of Object.keys(value)) {
+        if (!knownTopLevelKeys.has(key))
+            warnings.push(`unknown top-level key ignored by v1: ${key}`);
+    }
+    if (value.manifest_version !== 1)
+        errors.push("manifest_version must be 1");
+    if (typeof value.name !== "string" || !isSafePackageName(value.name))
+        errors.push("name must be a package-safe identifier without path separators");
+    const researchJobs = value.research_jobs;
+    if (!Array.isArray(researchJobs) || researchJobs.length === 0) {
+        errors.push("research_jobs must be a non-empty array");
+    }
+    else {
+        for (const [index, job] of researchJobs.entries()) {
+            if (typeof job !== "string" || !researchJobValues.includes(job)) {
+                errors.push(`research_jobs[${index}] is not a supported Feynman research job`);
+            }
+        }
+    }
+    let declaredResource = false;
+    if (value.slots !== undefined) {
+        if (!isRecord(value.slots)) {
+            errors.push("slots must be an object");
+        }
+        else {
+            for (const [slot, paths] of Object.entries(value.slots)) {
+                if (!feynmanPluginSlotValues.includes(slot)) {
+                    errors.push(`unknown plugin slot: ${slot}`);
+                    continue;
+                }
+                if (validatePathList({ owner: `slots.${slot}`, value: paths, errors }) && Array.isArray(paths) && paths.length > 0) {
+                    declaredResource = true;
+                }
+            }
+        }
+    }
+    if (value.pi !== undefined) {
+        if (!isRecord(value.pi)) {
+            errors.push("pi must be an object");
+        }
+        else {
+            for (const [key, paths] of Object.entries(value.pi)) {
+                if (!piResourceKeys.has(key)) {
+                    errors.push(`unknown pi resource: ${key}`);
+                    continue;
+                }
+                if (validatePathList({ owner: `pi.${key}`, value: paths, errors }) && Array.isArray(paths) && paths.length > 0) {
+                    declaredResource = true;
+                }
+            }
+        }
+    }
+    if (!declaredResource)
+        errors.push("at least one slots or pi resource must be declared");
+    if (value.requires_env !== undefined) {
+        if (!Array.isArray(value.requires_env)) {
+            errors.push("requires_env must be an array");
+        }
+        else {
+            for (const [index, entry] of value.requires_env.entries()) {
+                if (typeof entry === "string") {
+                    if (!/^[A-Z][A-Z0-9_]*$/.test(entry))
+                        errors.push(`requires_env[${index}] must be an environment variable name`);
+                }
+                else if (isRecord(entry)) {
+                    if (typeof entry.name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(entry.name))
+                        errors.push(`requires_env[${index}].name must be an environment variable name`);
+                }
+                else {
+                    errors.push(`requires_env[${index}] must be a string or object`);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",
@@ -73,10 +73,10 @@
   "dependencies": {
     "@clack/prompts": "^1.5.1",
     "@companion-ai/alpha-hub": "^0.1.3",
-    "@earendil-works/pi-agent-core": "0.79.10",
-    "@earendil-works/pi-ai": "0.79.10",
-    "@earendil-works/pi-coding-agent": "0.79.10",
-    "@earendil-works/pi-tui": "0.79.10",
+    "@earendil-works/pi-agent-core": "0.80.2",
+    "@earendil-works/pi-ai": "0.80.2",
+    "@earendil-works/pi-coding-agent": "0.80.2",
+    "@earendil-works/pi-tui": "0.80.2",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.219.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.219.0",

package/scripts/lib/pi-tui-patch.mjs

@@ -35,6 +35,81 @@ const OVERFLOW_TRUNCATE_BLOCK = `            let line = newLines[i];
             }
             buffer += line;`;
 
+const OVERFLOW_THROW_BLOCK_AFTER_CLEAR = `            const line = newLines[i];
+            const isImage = isImageLine(line);
+            const imageReservedRows = isImage ? this.getKittyImageReservedRows(newLines, i, renderEnd) : 1;
+            if (imageReservedRows > 1) {
+                const imageStartScreenRow = i - viewportTop;
+                if (imageStartScreenRow < 0 || imageStartScreenRow + imageReservedRows > height) {
+                    logRedraw(\`kitty image pre-clear would scroll (\${imageStartScreenRow} + \${imageReservedRows} > \${height})\`);
+                    fullRender(true);
+                    return;
+                }
+                buffer += "\\x1b[2K";
+                for (let row = 1; row < imageReservedRows; row++) {
+                    buffer += "\\r\\n\\x1b[2K";
+                }
+                buffer += \`\\x1b[\${imageReservedRows - 1}A\`;
+                buffer += line;
+                buffer += \`\\x1b[\${imageReservedRows - 1}B\`;
+                i += imageReservedRows - 1;
+                continue;
+            }
+            buffer += "\\x1b[2K"; // Clear current line
+            if (!isImage && visibleWidth(line) > width) {
+                // Log all lines to crash file for debugging
+                const crashLogPath = path.join(os.homedir(), ".pi", "agent", "pi-crash.log");
+                const crashData = [
+                    \`Crash at \${new Date().toISOString()}\`,
+                    \`Terminal width: \${width}\`,
+                    \`Line \${i} visible width: \${visibleWidth(line)}\`,
+                    "",
+                    "=== All rendered lines ===",
+                    ...newLines.map((l, idx) => \`[\${idx}] (w=\${visibleWidth(l)}) \${l}\`),
+                    "",
+                ].join("\\n");
+                fs.mkdirSync(path.dirname(crashLogPath), { recursive: true });
+                fs.writeFileSync(crashLogPath, crashData);
+                // Clean up terminal state before throwing
+                this.stop();
+                const errorMsg = [
+                    \`Rendered line \${i} exceeds terminal width (\${visibleWidth(line)} > \${width}).\`,
+                    "",
+                    "This is likely caused by a custom TUI component not truncating its output.",
+                    "Use visibleWidth() to measure and truncateToWidth() to truncate lines.",
+                    "",
+                    \`Debug log written to: \${crashLogPath}\`,
+                ].join("\\n");
+                throw new Error(errorMsg);
+            }
+            buffer += line;`;
+
+const OVERFLOW_TRUNCATE_BLOCK_AFTER_CLEAR = `            let line = newLines[i];
+            const isImage = isImageLine(line);
+            const imageReservedRows = isImage ? this.getKittyImageReservedRows(newLines, i, renderEnd) : 1;
+            if (imageReservedRows > 1) {
+                const imageStartScreenRow = i - viewportTop;
+                if (imageStartScreenRow < 0 || imageStartScreenRow + imageReservedRows > height) {
+                    logRedraw(\`kitty image pre-clear would scroll (\${imageStartScreenRow} + \${imageReservedRows} > \${height})\`);
+                    fullRender(true);
+                    return;
+                }
+                buffer += "\\x1b[2K";
+                for (let row = 1; row < imageReservedRows; row++) {
+                    buffer += "\\r\\n\\x1b[2K";
+                }
+                buffer += \`\\x1b[\${imageReservedRows - 1}A\`;
+                buffer += line;
+                buffer += \`\\x1b[\${imageReservedRows - 1}B\`;
+                i += imageReservedRows - 1;
+                continue;
+            }
+            buffer += "\\x1b[2K"; // Clear current line
+            if (!isImage && visibleWidth(line) > width) {
+                line = sliceByColumn(line, 0, width, true);
+            }
+            buffer += line;`;
+
 // Two known upstream layouts: pi-tui <=0.75 and the 0.76+ Unicode
 // word-navigation rework. Both need applyBackgroundToLine added for the
 // background-fill render below.
@@ -200,10 +275,13 @@ export function patchPiTuiSource(source) {
 	if (source.includes("line = sliceByColumn(line, 0, width, true);")) {
 		return source;
 	}
-	if (!source.includes(OVERFLOW_THROW_BLOCK)) {
-		return source;
+	if (source.includes(OVERFLOW_THROW_BLOCK)) {
+		return source.replace(OVERFLOW_THROW_BLOCK, OVERFLOW_TRUNCATE_BLOCK);
+	}
+	if (source.includes(OVERFLOW_THROW_BLOCK_AFTER_CLEAR)) {
+		return source.replace(OVERFLOW_THROW_BLOCK_AFTER_CLEAR, OVERFLOW_TRUNCATE_BLOCK_AFTER_CLEAR);
 	}
-	return source.replace(OVERFLOW_THROW_BLOCK, OVERFLOW_TRUNCATE_BLOCK);
+	return source;
 }
 
 export function patchPiEditorSource(source) {

package/scripts/prepare-runtime-workspace.mjs

@@ -24,7 +24,7 @@ const workspacePackageJsonPath = resolve(workspaceDir, "package.json");
 const workspaceNpmConfigPath = resolve(workspaceDir, ".npmrc");
 const workspaceArchivePath = resolve(feynmanDir, "runtime-workspace.tgz");
 const PRUNE_VERSION = 8;
-const PI_RUNTIME_FALLBACK_VERSION = "0.79.10";
+const PI_RUNTIME_FALLBACK_VERSION = "0.80.2";
 const RUNTIME_PACKAGE_OVERRIDES = {
 	"@mozilla/readability": "0.6.0",
 	"@opentelemetry/core": "2.8.0",