@gentbajko/slopify 0.1.0

package/dist/slices/reruns/index.js

@@ -0,0 +1,269 @@
+import { rmSync } from "node:fs";
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { allPiecesOf, deletePiece, deletePieces, setPiece, } from "../../kernel/runner/piece-repo.js";
+import { projectById, resetStage, stagesOf } from "../admission/repo.js";
+import { storeArticleText } from "../article/store.js";
+import { outputPath } from "../storage/layout.js";
+import { pieceFile } from "../storage/reconcile.js";
+import { deleteOutput, outputsOf } from "../storage/repo.js";
+import { storeText } from "../storage/staging.js";
+import { redoPlan } from "./cascade.js";
+// Only the one field this module changes is named; the rest of a piece's payload belongs
+// to the stage that wrote it and travels through untouched.
+const anyObject = z.record(z.string(), z.unknown());
+// What an article edit replaces (step 1). `instructions` is not among them: §Q57 keeps
+// the record of what was actually sent to the model, and an edit did not send anything.
+const articleRoles = ["article_md", "article_txt", "sources", "glossary"];
+// `logic/13` step 5 and `logic/01` §Q5: Retry is offered on a stage that stopped short,
+// and a canceled stage resumes exactly as a failed one does.
+export function retryStage(deps, projectId, kind) {
+    const loaded = load(deps, projectId);
+    if (!loaded.ok) {
+        return loaded;
+    }
+    const stage = stageOf(loaded.stages, kind);
+    if (stage === undefined || (stage.state !== "failed" && stage.state !== "canceled")) {
+        return { ok: false, reason: "not-retryable" };
+    }
+    // The pieces and the outputs stay where they are: the per-stage resume rules keep what
+    // finished (`logic/06` §Q54, `logic/08` §Q66, `logic/09` §Q73), and `logic/13` step 2
+    // keeps them through a cancel too. That is the whole of "a canceled stage is resumable".
+    transact(deps.db, () => {
+        resetStage(deps.db, stage.id);
+    });
+    return { ok: true, redone: [kind] };
+}
+// Steps 2, 3 and 8: Re-run audio with another voice, Re-run images, Re-render. The stage
+// starts over from the project's stored configuration rather than resuming.
+export function rerunStage(deps, projectId, kind) {
+    const loaded = load(deps, projectId);
+    if (!loaded.ok) {
+        return loaded;
+    }
+    const stage = stageOf(loaded.stages, kind);
+    if (stage === undefined || !rerunnable(stage.state)) {
+        return { ok: false, reason: "not-rerunnable" };
+    }
+    return apply(deps, projectId, { kind: "rerun", stage: kind }, loaded);
+}
+// Step 1: "the inline editor replaces the stored markdown; the plain-text narration source
+// and the sources and glossary files are rebuilt; then audio, LLM-mode intro/outro text,
+// LLM-written thumbnail, and video re-run; prompt-based images are untouched".
+//
+// ceiling: the LLM-mode intro and outro texts are *not* rewritten from the edited article.
+// Only the article stage writes them (`logic/07` step 5), and §Q60 makes any run of that
+// stage regenerate the whole article - which would throw away the edit that triggered it.
+// The audio does re-narrate the kept entry text, so the video is whole; the upgrade is a
+// mode on the article stage that keeps the stored article and rewrites the entries alone.
+export function editArticle(deps, projectId, markdown) {
+    const loaded = load(deps, projectId);
+    if (!loaded.ok) {
+        return loaded;
+    }
+    const article = stageOf(loaded.stages, "article");
+    if (article === undefined || (article.state !== "done" && article.state !== "provided")) {
+        return { ok: false, reason: "no-article" };
+    }
+    const text = markdown.trim();
+    if (text === "") {
+        // §Q106 leaves a project with one output per stage; an empty article would leave the
+        // audio stage with nothing to narrate and no way back except another edit.
+        return { ok: false, reason: "empty-article" };
+    }
+    return apply(deps, projectId, { kind: "article-edit" }, loaded, () => {
+        const replaced = loaded.outputs.filter((output) => articleRoles.includes(output.role));
+        for (const output of replaced) {
+            deleteOutput(deps.db, output.id);
+        }
+        // The four files are written back under the names they already had, so the write is
+        // the replacement §Q106 asks for rather than a second version beside the first.
+        storeText(deps, { projectId, stageKind: "article", role: "article_md", text });
+        storeArticleText(deps, { projectId, markdown: text });
+        return replaced.map((output) => output.path);
+    });
+}
+// Step 5 with `logic/09` §Q75: one image is "removed from the set; at least one image must
+// remain; video re-renders".
+export function deleteImage(deps, projectId, outputId) {
+    const loaded = load(deps, projectId);
+    if (!loaded.ok) {
+        return loaded;
+    }
+    const image = imageOf(loaded.outputs, outputId);
+    if (image === undefined) {
+        return { ok: false, reason: "unknown-image" };
+    }
+    if (loaded.outputs.filter((output) => output.role === "image").length <= 1) {
+        // §Q103's invariant: "at least one image always remains". `logic/11` step 2 has no
+        // slideshow to compute without one.
+        return { ok: false, reason: "last-image" };
+    }
+    return apply(deps, projectId, { kind: "image-deleted" }, loaded, () => {
+        // `slices/images/run.ts` counts an image as landed only when its row and its file both
+        // survive, so a delete removes both - and the piece that planned it, or the next run
+        // of the stage would read the plan and make the image again.
+        deleteOutput(deps.db, image.id);
+        dropImagePiece(deps, loaded.stages, image.path);
+        return [image.path];
+    });
+}
+// Step 4: "one new call with that image's stored prompt text, replacing it in place at the
+// same index (§Q103)". The piece carries that prompt and that index, so it is left alone
+// and the images stage sees one image of its plan missing.
+export function regenerateImage(deps, projectId, outputId) {
+    const loaded = load(deps, projectId);
+    if (!loaded.ok) {
+        return loaded;
+    }
+    const image = imageOf(loaded.outputs, outputId);
+    if (image === undefined) {
+        return { ok: false, reason: "unknown-image" };
+    }
+    return apply(deps, projectId, { kind: "image-regenerated" }, loaded, () => {
+        deleteOutput(deps.db, image.id);
+        forgetImageFile(deps, loaded.stages, image.path);
+        return [image.path];
+    });
+}
+function load(deps, projectId) {
+    const project = projectById(deps.db, projectId);
+    if (project === undefined) {
+        return { ok: false, reason: "no-project" };
+    }
+    const stages = stagesOf(deps.db, projectId);
+    // The precondition every action of `logic/12` shares: "no stage of the project is
+    // `running` (§Q106)". The page disables the controls; this is the other half, because
+    // clearing an output from under a stage that is writing it would lose both.
+    if (stages.some((stage) => stage.state === "running")) {
+        return { ok: false, reason: "running" };
+    }
+    return {
+        ok: true,
+        stages,
+        outputs: outputsOf(deps.db, projectId),
+        thumbnailSource: project.config.sources.thumbnail,
+    };
+}
+// One transaction for every row the action touches, then the filesystem. S4's lesson:
+// an unlink cannot be rolled back, so it waits for the commit - and a file with no row is
+// what the boot reconcile collects, where a row with no file is a broken download.
+function apply(deps, projectId, action, loaded, own) {
+    const plan = redoPlan({ action, stages: loaded.stages, thumbnailSource: loaded.thumbnailSource });
+    // `own` is the action's own change - the new article, the image that goes - and it runs
+    // first and inside the same transaction, so it lands or rolls back with the cascade it
+    // triggers. The files it writes take the names they already had, which is the
+    // replacement §Q106 asks for rather than work a rollback would have to undo.
+    const orphaned = transact(deps.db, () => {
+        const files = own === undefined ? [] : [...own()];
+        for (const redo of plan) {
+            const stage = stageOf(loaded.stages, redo.stage);
+            if (stage === undefined) {
+                continue;
+            }
+            if (redo.clears === "all") {
+                files.push(...clearStage(deps, stage, loaded.outputs));
+            }
+            resetStage(deps.db, stage.id);
+        }
+        return files;
+    });
+    removeFiles(deps, projectId, orphaned);
+    return { ok: true, redone: plan.map((redo) => redo.stage) };
+}
+// Everything the stage produced: its outputs, and the resumable pieces whose payloads name
+// files of their own - the audio chunks of `logic/08` §Q65, which are not outputs.
+function clearStage(deps, stage, outputs) {
+    const files = [];
+    for (const output of outputs) {
+        if (output.stageKind !== stage.kind) {
+            continue;
+        }
+        files.push(output.path);
+        deleteOutput(deps.db, output.id);
+    }
+    for (const piece of allPiecesOf(deps.db, stage.id)) {
+        const file = pieceFile(piece.payload);
+        if (file !== undefined) {
+            files.push(file);
+        }
+    }
+    deletePieces(deps.db, stage.id);
+    return files;
+}
+// §Q103 replaces the image "in place at the same index", so the piece keeps the prompt
+// and the index it was planned with and only stops naming a file: `slices/images/run.ts`
+// then sees one image of its plan still to make, and the file it named can be removed.
+function forgetImageFile(deps, stages, path) {
+    for (const piece of imagePieces(deps, stages, path)) {
+        if (piece.payload === null) {
+            continue;
+        }
+        const parsed = anyObject.safeParse(JSON.parse(piece.payload));
+        if (!parsed.success) {
+            continue;
+        }
+        const kept = Object.entries(parsed.data).filter(([name]) => name !== "file");
+        setPiece(deps.db, piece.id, "pending", JSON.stringify(Object.fromEntries(kept)));
+    }
+}
+function dropImagePiece(deps, stages, path) {
+    for (const piece of imagePieces(deps, stages, path)) {
+        deletePiece(deps.db, piece.id);
+    }
+}
+// The pieces of the images stage that name this file. There is one, unless a run before
+// this one wrote two pieces onto the same path, which the reconcile would have to sort
+// out anyway; taking all of them keeps the row set and the disk agreeing either way.
+function imagePieces(deps, stages, path) {
+    const stage = stageOf(stages, "images");
+    if (stage === undefined) {
+        return [];
+    }
+    return allPiecesOf(deps.db, stage.id).filter((piece) => pieceFile(piece.payload) === path);
+}
+// Read back rather than reasoned about: an edit rewrites `article.md` under the same name
+// it just deleted the row for, so what is still referenced after the commit is the only
+// safe answer to what may be unlinked.
+function removeFiles(deps, projectId, orphaned) {
+    const kept = new Set(outputsOf(deps.db, projectId).map((output) => output.path));
+    for (const stage of stagesOf(deps.db, projectId)) {
+        for (const piece of allPiecesOf(deps.db, stage.id)) {
+            const file = pieceFile(piece.payload);
+            if (file !== undefined) {
+                kept.add(file);
+            }
+        }
+    }
+    for (const path of new Set(orphaned)) {
+        if (kept.has(path)) {
+            continue;
+        }
+        try {
+            rmSync(outputPath(deps.paths, projectId, path), { force: true });
+        }
+        catch (error) {
+            // The row is already gone, so the next boot's reconcile removes the file. Failing
+            // the action here would leave the user with a stage that cannot be re-run.
+            deps.log.write("warn", "reruns.file", {
+                projectId,
+                detail: `${path}: ${messageOf(error)}`,
+            });
+        }
+    }
+}
+// `logic/01`: `done` → `running` is scenario 12's own transition, and a stage that failed
+// or was canceled may be started over rather than resumed. `provided` and `skipped` never
+// run, and `pending` has nothing to redo.
+function rerunnable(state) {
+    return state === "done" || state === "failed" || state === "canceled";
+}
+function stageOf(stages, kind) {
+    return stages.find((stage) => stage.kind === kind);
+}
+function imageOf(outputs, outputId) {
+    return outputs.find((output) => output.id === outputId && output.role === "image");
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/slices/research/planner.js

@@ -0,0 +1,81 @@
+export function plannerMessages(brief) {
+    return [
+        {
+            role: "user",
+            content: [
+                "You are planning the web research for an article.",
+                "",
+                briefText(brief),
+                "",
+                // §Q53: the prompt's section guide decides the chapters when it has one, and the
+                // planner proposes them when it does not. There is no cap on the count.
+                "List the chapters to research. If the prompt sets out a section guide, take the",
+                "chapters from it, in the order it gives them. If it does not, propose the chapters",
+                "this article needs.",
+                "",
+                "Answer with one chapter title per line and nothing else: no numbering, no",
+                "commentary, no blank lines, no heading.",
+            ].join("\n"),
+        },
+    ];
+}
+// The answer is a list, however the model chose to punctuate it. Numbering and bullets
+// are stripped because the instruction above asks for neither and models add them
+// anyway; a repeated title is dropped because `logic/06`'s invariant is that no chapter
+// is researched twice.
+export function chaptersFrom(text) {
+    const seen = new Set();
+    const chapters = [];
+    for (const line of text.split("\n")) {
+        const title = line
+            .trim()
+            .replace(/^(?:[-*•]|\d+[.)])\s+/, "")
+            .trim();
+        const key = title.toLowerCase();
+        if (title === "" || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        chapters.push(title);
+    }
+    return chapters;
+}
+// §Q52, §Q53: one sub-agent per chapter, web-grounded, answering that chapter's notes
+// and its sources. The whole outline travels with it so it covers its own chapter and
+// leaves the neighbouring ones to the sub-agents researching them.
+export function subAgentMessages(brief, chapter, outline) {
+    return [
+        {
+            role: "user",
+            content: [
+                "You are researching one chapter of an article on the web.",
+                "",
+                briefText(brief),
+                "",
+                "The article's chapters:",
+                "",
+                outline.map((title) => `- ${title}`).join("\n"),
+                "",
+                `Research this chapter and no other: ${chapter}`,
+                "",
+                "Search the web and answer with plain-text notes on what you found: no markdown",
+                "and no commentary on your own process. End with a line reading exactly",
+                '"Sources", then the URL of every page you used, one per line.',
+            ].join("\n"),
+        },
+    ];
+}
+// The half of every instruction that is the same for all three calls (§Q46): the
+// rendered prompt the article will be written from, and the run's keyword values.
+export function briefText(brief) {
+    const values = Object.entries(brief.values);
+    return [
+        "The article will be written from this prompt:",
+        "",
+        brief.articlePrompt,
+        "",
+        "Keyword values for this run:",
+        "",
+        values.length === 0 ? "(none)" : values.map(([name, value]) => `${name}: ${value}`).join("\n"),
+    ].join("\n");
+}

package/dist/slices/research/run.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { isProviderError } from "../../kernel/ports/model.js";
+import { insertPiece, piecesOf, setPiece } from "../../kernel/runner/piece-repo.js";
+import { projectById, setStageProgress } from "../admission/repo.js";
+import { storeText } from "../storage/staging.js";
+import { noTokens, plusUsage } from "../telemetry/model.js";
+import { chaptersFrom, plannerMessages, subAgentMessages } from "./planner.js";
+import { sourcedAnswer, synthesisMessages } from "./synthesis.js";
+// §Q47, verbatim: "the stage fails immediately with 'web research unsupported by this
+// model'; no fallback to model knowledge".
+export const webResearchUnsupported = "web research unsupported by this model";
+// What a chapter piece carries between runs: its title, and its notes once a sub-agent
+// has answered. That is the whole of the resume of §Q54.
+const chapterPayload = z.object({ title: z.string(), notes: z.string().optional() });
+export async function runResearch(deps, context, providers) {
+    const { projectId } = context.stage;
+    const project = projectById(deps.db, projectId);
+    if (project === undefined) {
+        throw new Error(`project ${projectId} has no row`);
+    }
+    const choice = project.config.llm;
+    const articlePrompt = project.config.rendered.article;
+    if (choice === undefined || articlePrompt === undefined) {
+        // Admission refuses a run whose research is Generate without both (`logic/04`), so
+        // reaching here is a bug in admission rather than something the user did.
+        throw new Error("the run has no LLM provider or no rendered article prompt");
+    }
+    const brief = { articlePrompt, values: project.config.values };
+    try {
+        await research(deps, context, providers, choice, brief);
+    }
+    catch (error) {
+        // The adapter says the model cannot ground on the web and the wrapper has already
+        // made that terminal; this is where it becomes the sentence the user reads (§Q47).
+        if (isProviderError(error) && error.fault.kind === "unsupported") {
+            throw new Error(webResearchUnsupported);
+        }
+        throw error;
+    }
+}
+async function research(deps, context, providers, choice, brief) {
+    // logic/16 step 3 counts tokens per stage, so the planner, every sub-agent and the
+    // synthesis add into one total. A call that was aborted or that failed never answers,
+    // so it adds nothing (§Q112); a provider that reports no usage adds zero, never an
+    // estimate (§Q131).
+    let tokens = noTokens;
+    const add = (usage) => {
+        tokens = plusUsage(tokens, usage);
+    };
+    const chapters = await plan(deps, context, providers, choice, brief, add);
+    const findings = await researchChapters(deps, context, providers, choice, brief, chapters, add);
+    const answer = await providers.llm({
+        provider: choice.provider,
+        model: choice.model,
+        messages: synthesisMessages(brief, findings),
+        check: (given) => sourcedAnswer("the synthesis", given.text),
+    });
+    add(answer.usage);
+    const { projectId } = context.stage;
+    // Step 4: the notes and every instruction sent are stored on the project. Each
+    // sub-agent's own output stays on its chapter row, which is where the resume reads it.
+    storeText(deps, { projectId, stageKind: "research", role: "notes", text: answer.text.trim() });
+    storeText(deps, {
+        projectId,
+        stageKind: "research",
+        role: "instructions",
+        text: instructionsText(brief, findings),
+    });
+    deps.count("stage.completed", {
+        stage: "research",
+        provider: choice.provider,
+        model: choice.model,
+        ...tokens,
+    });
+    deps.log.write("info", "research.done", {
+        projectId,
+        stage: "research",
+        detail: `${String(findings.length)} chapters researched`,
+    });
+}
+// The chapter list, planned once and kept. A retry after a failure finds the rows the
+// first run wrote and does not ask again (§Q54).
+async function plan(deps, context, providers, choice, brief, add) {
+    const existing = piecesOf(deps.db, context.stage.id, "chapter");
+    if (existing.length > 0) {
+        return existing;
+    }
+    const answer = await providers.llm({
+        provider: choice.provider,
+        model: choice.model,
+        messages: plannerMessages(brief),
+        // §Q50: an empty answer, or one with no chapter in it, is a failed attempt.
+        check: (given) => chaptersFrom(given.text).length === 0 ? "the planner named no chapters" : undefined,
+    });
+    add(answer.usage);
+    // §Q53: no cap on the count. The list is the prompt's own section guide as often as
+    // not, and capping it would silently drop a section the article asks for.
+    const planned = chaptersFrom(answer.text).map((title, index) => ({
+        id: deps.ids.next(),
+        stageId: context.stage.id,
+        kind: "chapter",
+        idx: index + 1,
+        state: "pending",
+        payload: JSON.stringify({ title }),
+    }));
+    transact(deps.db, () => {
+        for (const piece of planned) {
+            insertPiece(deps.db, piece);
+        }
+    });
+    return planned;
+}
+// §Q53: "one per chapter, all in parallel". §Q54: a chapter a previous run finished is
+// not researched again, and one that fails fails the whole stage while its siblings
+// finish and keep their output for the next resume.
+async function researchChapters(deps, context, providers, choice, brief, chapters, add) {
+    const outline = chapters.map((piece) => payloadOf(piece).title);
+    const total = chapters.length;
+    let done = chapters.filter((piece) => payloadOf(piece).notes !== undefined).length;
+    report(deps, context, done, total);
+    const outcomes = await Promise.all(chapters.map(async (piece) => {
+        const kept = payloadOf(piece);
+        if (kept.notes !== undefined) {
+            return { ok: true, finding: { title: kept.title, notes: kept.notes } };
+        }
+        setPiece(deps.db, piece.id, "running", piece.payload);
+        try {
+            const answer = await providers.forPiece(piece.id).llm({
+                provider: choice.provider,
+                model: choice.model,
+                messages: subAgentMessages(brief, kept.title, outline),
+                // §Q47: grounding is asked for explicitly, so a model without it says so
+                // instead of answering from what it already knows.
+                webSearch: true,
+                check: (given) => sourcedAnswer(`the researcher on "${kept.title}"`, given.text),
+            });
+            add(answer.usage);
+            const notes = answer.text.trim();
+            setPiece(deps.db, piece.id, "done", JSON.stringify({ title: kept.title, notes }));
+            done += 1;
+            report(deps, context, done, total);
+            return { ok: true, finding: { title: kept.title, notes } };
+        }
+        catch (error) {
+            // A cancel is not this chapter failing: `logic/13` §Q112 counts an aborted call
+            // as nothing, and the resume runs a `pending` chapter exactly as a failed one.
+            setPiece(deps.db, piece.id, context.signal.aborted ? "pending" : "failed", piece.payload);
+            return { ok: false, error };
+        }
+    }));
+    const findings = [];
+    for (const outcome of outcomes) {
+        if (!outcome.ok) {
+            throw outcome.error;
+        }
+        findings.push(outcome.finding);
+    }
+    return findings;
+}
+// Step 5: "k of N chapters researched". Written as well as emitted, so a page opened
+// mid-stage reads the count off the row rather than waiting for the next chapter.
+function report(deps, context, done, total) {
+    setStageProgress(deps.db, context.stage.id, done, total);
+    context.emit({
+        type: "stage.progress",
+        projectId: context.stage.projectId,
+        stage: "research",
+        current: done,
+        total,
+    });
+}
+// §Q51: every instruction sent is stored on the project. All three are pure functions of
+// the brief and the findings, so a resumed run reproduces the ones it did not send.
+function instructionsText(brief, findings) {
+    const outline = findings.map((finding) => finding.title);
+    const parts = [section("Planner", plannerMessages(brief))];
+    for (const title of outline) {
+        parts.push(section(`Sub-agent: ${title}`, subAgentMessages(brief, title, outline)));
+    }
+    parts.push(section("Synthesis", synthesisMessages(brief, findings)));
+    return `${parts.join("\n\n")}\n`;
+}
+function section(label, messages) {
+    return `=== ${label} ===\n\n${messages.map((message) => message.content).join("\n\n")}`;
+}
+function payloadOf(piece) {
+    if (piece.payload === null) {
+        throw new Error(`chapter ${piece.id} has no payload`);
+    }
+    return chapterPayload.parse(JSON.parse(piece.payload));
+}

package/dist/slices/research/synthesis.js

@@ -0,0 +1,48 @@
+import { briefText } from "./planner.js";
+// §Q52: "an editorial pass over every sub-agent's output that selects and organizes the
+// findings; it does not concatenate". The sub-agents' notes are the material, not the
+// answer, and the synthesising model is told so.
+export function synthesisMessages(brief, findings) {
+    return [
+        {
+            role: "user",
+            content: [
+                "You are the editor of the research behind an article.",
+                "",
+                briefText(brief),
+                "",
+                "One researcher covered each chapter. Their findings follow.",
+                "",
+                findings.map(block).join("\n\n"),
+                "",
+                "Write the research notes the article will be written from. Select what the",
+                "article needs, organise it, and resolve what the researchers disagree on. Do not",
+                "concatenate their reports and do not add anything they did not find.",
+                "",
+                "Answer with plain-text notes: no markdown and no commentary on your own process.",
+                'End with a line reading exactly "Sources", then the URL of every source you kept,',
+                "one per line, with no duplicates.",
+            ].join("\n"),
+        },
+    ];
+}
+// §Q48 and §Q55: the stored notes always end with a Sources list, and an answer without
+// one "counts as a failed attempt". A heading with nothing under it is not a list, so
+// the line has to be followed by something.
+const heading = /^\s*(?:#{1,6}\s*)?(?:\*\*)?\s*sources(?:\s+(?:list|consulted))?\s*(?:\*\*)?\s*:?\s*$/i;
+export function endsWithSources(text) {
+    const lines = text.split("\n");
+    const at = lines.findLastIndex((line) => heading.test(line));
+    return at !== -1 && lines.slice(at + 1).some((line) => line.trim() !== "");
+}
+// The one shape a stage hands `StageProviders.llm` as its `check`: an answer that arrived
+// but cannot be used is a failed attempt, so the wrapper retries it (§Q50, §Q55).
+export function sourcedAnswer(who, text) {
+    if (text.trim() === "") {
+        return `${who} answered with nothing`;
+    }
+    return endsWithSources(text) ? undefined : `${who} answered with no Sources list`;
+}
+function block(finding) {
+    return `--- ${finding.title} ---\n${finding.notes}`;
+}

package/dist/slices/settings/cli-status.js

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+// ceiling: `logic/02` §Q135 computes readiness at request time, so nothing is cached and
+// a hung CLI costs the settings page this long. Both probes run in parallel, so the page
+// waits 2 s in the worst case. Caching the answer for a few seconds is the upgrade if a
+// slow machine makes the status line flap.
+export const cliProbeTimeoutMs = 2000;
+const probeOutputMax = 64 * 1024;
+// The real probe: an argument array, never a shell string, so nothing in a binary name
+// or an argument can be interpreted as a command. It resolves for every outcome; a
+// missing CLI is an answer, not a failure.
+// ceiling: POSIX only. A Windows install puts `claude` on PATH as a `.cmd` shim, which
+// execFile cannot run without a shell; a shim-aware lookup is the upgrade when Windows
+// is supported.
+export function nodeCliProbe(binary, args, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile(binary, [...args], { timeout: timeoutMs, maxBuffer: probeOutputMax, windowsHide: true }, (error, stdout) => {
+            resolve(error === null ? { ran: true, stdout } : { ran: false, stdout: "" });
+        });
+    });
+}
+export async function cliReadiness(probe, provider) {
+    const result = await probe(provider.binary, provider.versionArgs, cliProbeTimeoutMs);
+    if (!result.ran) {
+        return { kind: "cli", installed: false };
+    }
+    const version = versionFrom(result.stdout);
+    return version === undefined
+        ? { kind: "cli", installed: true }
+        : { kind: "cli", installed: true, version };
+}
+// `claude --version` answers "2.1.258 (Claude Code)" and `codex --version` answers
+// "codex-cli 0.149.1", so the version is the first dotted number on the output rather
+// than the whole line either of them prints.
+export function versionFrom(stdout) {
+    const match = /\d+\.\d+(?:\.[0-9A-Za-z.+-]+)?/.exec(stdout);
+    return match?.[0];
+}