@turri-dev/cli 0.2.0 → 0.2.1-next.bc56a0d

package/dist/regenerate/testing.js

@@ -212,6 +212,20 @@ export const NOT_CODE = new Set([
     RECORD_FILE,
     BASE_RECORD_FILE,
 ]);
+/** Whether a codebase holds a file of its own - as `listFiles` counts them - stopping at the first. */
+export function hasFiles(root) {
+    const look = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            if (NOT_CODE.has(entry))
+                continue;
+            const full = join(dir, entry);
+            if (!statSync(full).isDirectory() || look(full))
+                return true;
+        }
+        return false;
+    };
+    return existsSync(root) && look(root);
+}
 export function listFiles(root) {
     const found = [];
     const walk = (dir) => {

package/dist/release-agent.d.ts

@@ -1,4 +1,16 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type DeployState } from "./release-tools.ts";
+/**
+ * The agent that releases a module on its own - `turri release`'s, and a pulse's last stage under
+ * `release-after-pulse: true`, which is the word to release: the guidance it finds as the chat does - what it was told,
+ * the project's AGENTS.md, its skills - says only how. It passes it to `release`, and does what it says, asking no one.
+ */
+type AnyTool = ToolDefinition<any, any, any>;
+/**
+ * The person's own shell, in the deployed folder: it installs what the release needs into the project, and runs it. It
+ * changes nothing of the machine's - no toolchain installed, no system setting changed: a command that would is refused.
+ */
+export declare function releaseShell(dir: string): AnyTool;
 /**
  * What the project says of itself, for the agent to find release guidance in: its AGENTS.md and its skills
  * (`.agents/skills`, `.pi/skills`, `.claude/skills`), where turri runs and in the host codebase - once each, whole.
@@ -20,7 +32,12 @@ export interface ReleaseAgentInput {
         moduleName: string;
         subject: string;
     };
+    /** Released for the sentinel to check functional specs of the module in: asked for, so released; the guidance says how. */
+    forCheck?: {
+        moduleName: string;
+    };
     onDelta?: (delta: string) => void;
 }
 /** Run the release agent to its end; its last reply. */
 export declare function runReleaseAgent(input: ReleaseAgentInput): Promise<string>;
+export {};

package/dist/release-agent.js

@@ -3,14 +3,24 @@ import { join, relative, resolve, sep } from "node:path";
 import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "@earendil-works/pi-coding-agent";
 import { createDeployTools, DEPLOY_TOOLS } from "./release-tools.js";
 import { hostDirOf, shortPath } from "./regenerate/release.js";
+import { machineChange, machineChangeReason } from "./regenerate/command-check.js";
 import { projectDirOf } from "./regenerate/paths.js";
 import { ask, BEGIN, createExecutor } from "./pi.js";
-/** The person's own shell, in the deployed folder: it installs and runs what the release needs. */
-function hostBash(dir) {
+/**
+ * The person's own shell, in the deployed folder: it installs what the release needs into the project, and runs it. It
+ * changes nothing of the machine's - no toolchain installed, no system setting changed: a command that would is refused.
+ */
+export function releaseShell(dir) {
     const bash = createBashToolDefinition(dir);
     return {
         ...bash,
-        description: `${bash.description}\n\nIt runs on the person's own machine, in ${shortPath(dir)}. Never start a server here: activate does.`,
+        description: `${bash.description}\n\nIt runs on the person's own machine, in ${shortPath(dir)}. Never start a server here: activate does. It installs nothing on the machine and changes none of its settings: what the machine lacks, the person installs.`,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const changes = machineChange(String(params.command ?? ""));
+            if (changes !== undefined)
+                throw new Error(machineChangeReason(changes));
+            return bash.execute(toolCallId, params, signal, onUpdate, ctx);
+        },
     };
 }
 /** A file tool that writes, refused inside plain_modules: the built code is the spec's to change, never a release's. */
@@ -78,7 +88,7 @@ export async function runReleaseAgent(input) {
     const executor = await createExecutor({
         // Its sessions are kept in the project, not in the folder it deploys.
         cwd: projectDirOf(plainFile),
-        customTools: [...fileTools, hostBash(dir), ...tools],
+        customTools: [...fileTools, releaseShell(dir), ...tools],
         tools: [...fileTools.map((tool) => tool.name), "bash", ...DEPLOY_TOOLS],
         ...(input.model !== undefined ? { model: input.model } : {}),
         role: "release",
@@ -89,16 +99,18 @@ export async function runReleaseAgent(input) {
         task: [
             input.afterPulse !== undefined
                 ? `A pulse of module ${input.afterPulse.moduleName} just landed: ${input.afterPulse.subject}. Release it now, before the module's next pulse starts: the project releases after every pulse.`
-                : `Release ${shortPath(plainFile)} for the person to try, with the release tool, then do what it says.`,
+                : input.forCheck !== undefined
+                    ? `The person asked turri's sentinel to check functional specs of module ${input.forCheck.moduleName} in its release, and what runs of it is not its last commit. Release its last commit now, for the sentinel to test.`
+                    : `Release ${shortPath(plainFile)} for the person to try, with the release tool, then do what it says.`,
             "",
             "First ask yourself: is there guidance for how this project releases it - what the person said below, the project's",
             "notes and skills below, or anything else you find? If there is, call release with it as guidance, in full: the code is",
             "put in dist/<module>, and the guidance takes it on from there. If there is none, call release without guidance: the",
             "code is put in dist/<module> and started from there, as best it can be.",
-            ...(input.afterPulse !== undefined
+            ...(input.afterPulse !== undefined || input.forCheck !== undefined
                 ? [
                     "",
-                    "Release it whether or not the guidance speaks of releasing after a build - the project's setting has said to. What",
+                    `Release it whether or not the guidance speaks of releasing ${input.afterPulse !== undefined ? "after a build - the project's setting has said to" : "for a check - the person asked for it"}. What`,
                     "the guidance says is how. When release says it is already released, leave it at that.",
                 ]
                 : []),

package/dist/release-tools.d.ts

@@ -17,6 +17,12 @@ export interface DeployState {
     guidance: Map<string, string>;
 }
 export declare function createDeployState(): DeployState;
+/**
+ * A module's release as it stands, when it is current: its own codebase's last commit is what the last release shipped,
+ * and nothing that release started has ended. Undefined when it is behind, was never made, or what it started died -
+ * then it is released again.
+ */
+export declare function currentRelease(state: DeployState, plainFile: string, moduleName: string): Deployment | undefined;
 /** What the agent is to do once the code is in dist - in the deploy tool's answer, and the CLI agent's prompt. */
 export declare function deployGuide(dir: string): string;
 /**

package/dist/release-tools.js

@@ -2,20 +2,39 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { refuseTestPlainFile } from "./test-plain-files.js";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { deployLogDir, deployTarget, describeDeployment, exportModule, hostDirOf, shortPath, startDeployed, stopDeployed, } from "./regenerate/release.js";
+import { deployLogDir, deployTarget, describeDeployment, exportModule, hostDirOf, listDeployed, shortPath, startDeployed, stopDeployed, } from "./regenerate/release.js";
 import { projectDirOf } from "./regenerate/paths.js";
 import { haltTool } from "./loop-tools.js";
 export function createDeployState() {
     return { released: new Map(), guidance: new Map() };
 }
+/**
+ * A module's release as it stands, when it is current: its own codebase's last commit is what the last release shipped,
+ * and nothing that release started has ended. Undefined when it is behind, was never made, or what it started died -
+ * then it is released again.
+ */
+export function currentRelease(state, plainFile, moduleName) {
+    let target;
+    try {
+        target = deployTarget(plainFile, moduleName);
+    }
+    catch {
+        return undefined;
+    }
+    const last = state.released.get(moduleName);
+    if (target.entry.moduleName !== moduleName || last === undefined || !target.commit.startsWith(last.commit))
+        return undefined;
+    const started = listDeployed().filter((item) => item.moduleName === moduleName && (last.at === undefined || item.startedAt >= last.at));
+    return started.some((item) => item.exited !== undefined) ? undefined : last;
+}
 /** What the agent is to do once the code is in dist - in the deploy tool's answer, and the CLI agent's prompt. */
 export function deployGuide(dir) {
     const where = shortPath(dir);
     return [
         `What to do now, to have the person try it - it runs on this machine, outside the sandbox, from ${where}:`,
         `1. Find out how it runs: its README, its manifests (package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle, docker-compose.yml) and entry points, in ${where}.`,
-        "2. Check the toolchains it needs are on this machine (`command -v node`, `python3 --version`, `go version`, ...). One missing: install it with this machine's package manager (brew on macOS, apt or dnf on Linux), then go on.",
-        "3. Install what it needs yourself, in your shell - dependencies into a virtual environment or node_modules, a build that fetches packages, an image pull. Do not ask the person: do it, and fix what fails.",
+        "2. Check the toolchains it needs are on this machine (`command -v node`, `python3 --version`, `go version`, ...) - under another name too: python where python3 is not, of the version it needs. One missing: you install nothing on the machine and change none of its settings - stop, and tell the person exactly what to install, the command they run themselves (`brew install node`), and that releasing again picks it up.",
+        "3. Install what it needs into the project yourself, in your shell - dependencies into a virtual environment or node_modules, a build that fetches packages, an image pull. Do not ask the person: do it, and fix what fails - within the project: never a global install, never a system setting.",
         "4. Start anything that keeps running - a backend, a frontend's dev server - with activate, with the URL it serves at: never in the shell with & or nohup. An app with a backend and a frontend: start both, the backend first.",
         "5. Then tell the person, briefly. Something that serves: only where to open it - the frontend's URL, and the API's in one line when there is one. A CLI or a library: a few commands to paste, run from the folder, with what they print. A port that is taken: say which and by what, and do not move the app to another.",
         `Do not change the code in ${where} - it is a copy of what was built, and a fix belongs in the spec. A config file it needs made from its example (a .env from .env.example) is fine.`,
@@ -37,7 +56,7 @@ export function guidedGuide(deployment, guidance) {
         `What to do now - on this machine, outside the sandbox, from ${host}:`,
         `1. The code to release is in ${dist}: the last commit that landed whole. Take it from there, never from ${built}, where a pulse may be writing. Where the guidance's own tooling reads ${built}, point it at ${dist} if it can take another source; if it cannot, do by hand, from ${dist}, what it does.`,
         `2. Read what the guidance leaves open - the scripts, files and commands it names, in ${host} - then do what it says, in its order. Where it says to change the host - a registration, an import, a config entry - change it. Never change ${built} or ${dist}: a fix to the code belongs in the spec.`,
-        "3. Run the project's scripts and install what it needs yourself, in your shell. Do not ask the person: do it, and fix what fails.",
+        "3. Run the project's scripts and install what it needs into the project yourself, in your shell. Do not ask the person: do it, and fix what fails. A toolchain or system tool the machine lacks you never install, nor change a setting of the machine's: tell the person the command they run themselves.",
         "4. Start what keeps running - a start script, a dev server - with activate, with the URL it serves at - never in the shell with & or nohup.",
         `5. Then tell the person briefly: what was done, what you changed in ${host} if anything, and where to open it or how to try it. Where the guidance does not fit what you find, say so, and do not guess past it.`,
     ].join("\n");
@@ -105,7 +124,7 @@ export function createDeployTools(options) {
             const exported = exportModule(plainFile, params.in_module);
             const deployment = guidance === undefined ? exported : { ...exported, way: "guided", hostDir: hostDirOf(plainFile, options.cwd) };
             state.current = deployment;
-            state.released.set(deployment.moduleName, deployment);
+            state.released.set(deployment.moduleName, { ...deployment, at: Date.now() });
             if (guidance !== undefined)
                 state.guidance.set(deployment.moduleName, guidance);
             return text([

package/dist/sentinel-chat.d.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-w
 import type { ChatLink, TurriCore } from "./chats.ts";
 import { type Conclusion, type Notice } from "./sentinel.ts";
 /** The sentinel's tools and model, built into its chat. */
-export declare function registerSentinel(pi: ExtensionAPI, session: TurriCore, cwd: string, hostTools: ToolDefinition[], allowed: Set<string>): void;
+export declare function registerSentinel(pi: ExtensionAPI, session: TurriCore, cwd: string, hostTools: ToolDefinition[], allowed: Set<string>, resume: (plainFile: string) => Promise<string>): void;
 /**
  * The terminal's question whether to start the sentinel: the sentence, and how to switch to it - it opens last in the
  * strip, after the `open` chats there are. A host has its own way to it, and is given the sentence alone.

package/dist/sentinel-chat.js

@@ -1,6 +1,6 @@
 import { Box, Text } from "@earendil-works/pi-tui";
 import { projectModels, readProjectConfig, roleModel } from "./config.js";
-import { concludedNote, concludeTool, keepGuidanceTool, notifyTool, sentinelFileTools } from "./sentinel.js";
+import { concludedNote, concludeTool, keepGuidanceTool, notifyTool, resumeTool, sentinelFileTools } from "./sentinel.js";
 /**
  * The sentinel in a chat: its tools in place of the chat's - the project to read, its shell behind the walls, notices,
  * its guidance, a host's own - its model, and, in every chat, the notices it puts to the person: a card in the chat and,
@@ -16,7 +16,7 @@ const IGNORE = "Ignore - leave it as the build has it";
 const STEER = "Say what to do instead…";
 const DISMISS = "Dismiss";
 /** The sentinel's tools and model, built into its chat. */
-export function registerSentinel(pi, session, cwd, hostTools, allowed) {
+export function registerSentinel(pi, session, cwd, hostTools, allowed, resume) {
     // pi's own file tools and shell, replaced by fenced ones of the same names: the whole project to read, nothing to write.
     for (const tool of sentinelFileTools(cwd))
         pi.registerTool(tool);
@@ -27,6 +27,7 @@ export function registerSentinel(pi, session, cwd, hostTools, allowed) {
     }));
     pi.registerTool(concludeTool((conclusion) => session.concluded(conclusion)));
     pi.registerTool(keepGuidanceTool(cwd));
+    pi.registerTool(resumeTool(resume));
     for (const tool of hostTools)
         pi.registerTool(tool);
     // Only its tools are offered to its model; what it calls besides is refused (extension.ts, tool_call).
@@ -90,10 +91,15 @@ export function noticeDialogs(pi, session, link, context) {
         const data = entry.data;
         if (data === undefined)
             return undefined;
-        const about = data.module !== undefined ? `${data.module}${data.pulse !== undefined ? ` · pulse ${data.pulse}` : ""}` : data.job;
-        const mark = data.verdict === "holds" ? theme.fg("success", "✓") : theme.fg("error", "✗");
+        const about = data.check !== undefined
+            ? `${data.module !== undefined ? `${data.module} · ` : ""}check ${data.check}`
+            : data.module !== undefined
+                ? `${data.module}${data.pulse !== undefined ? ` · pulse ${data.pulse}` : ""}`
+                : (data.job ?? "");
+        const mark = data.verdict === "holds" ? theme.fg("success", "✓") : data.verdict === "unchecked" ? theme.fg("muted", "·") : theme.fg("error", "✗");
+        const said = data.verdict === "holds" ? "checked, it holds" : data.verdict === "unchecked" ? "not checked" : "found something wrong";
         const box = new Box(1, 0);
-        box.addChild(new Text(`${mark} ${theme.fg("muted", `sentinel · ${about} · ${data.verdict === "holds" ? "checked, it holds" : "found something wrong"}`)}\n  ${theme.fg("text", data.summary)}`, 0, 0));
+        box.addChild(new Text(`${mark} ${theme.fg("muted", `sentinel · ${about} · ${said}`)}\n  ${theme.fg("text", data.summary)}`, 0, 0));
         return box;
     });
     pi.registerEntryRenderer(NOTICE_OVER_ENTRY, (entry, _options, theme) => {
@@ -176,8 +182,8 @@ export function noticeDialogs(pi, session, link, context) {
             catch {
                 /* the host still hears of it */
             }
-            // A host answers it itself: its card, its buttons.
-            if (session.host.onNotice !== undefined)
+            // A host answers it itself: its card, its buttons. A note of a fix the sentinel made asks nothing: its card alone.
+            if (session.host.onNotice !== undefined || notice.kind === "fixed")
                 return;
             waiting.push(notice);
             void ask();
@@ -189,7 +195,14 @@ export function noticeDialogs(pi, session, link, context) {
             catch {
                 /* the agent is still told */
             }
-            void pi.sendMessage({ customType: "turri_sentinel_concluded", content: concludedNote(conclusion), display: false, details: { jobId: conclusion.job, verdict: conclusion.verdict } }, { triggerTurn: true, deliverAs: "followUp" });
+            // A host that shows the person the conclusion itself: the chat knows of it - in order, with no turn of its own.
+            const shown = session.host.pulseEndsShown === true;
+            void pi.sendMessage({
+                customType: "turri_sentinel_concluded",
+                content: concludedNote(conclusion, { shown }),
+                display: false,
+                details: { ...(conclusion.job !== undefined ? { jobId: conclusion.job } : {}), ...(conclusion.check !== undefined ? { checkId: conclusion.check } : {}), verdict: conclusion.verdict },
+            }, shown ? { triggerTurn: false } : { triggerTurn: true, deliverAs: "followUp" });
         },
         over(notice) {
             asking.get(notice.id)?.abort();

package/dist/sentinel-check.d.ts

@@ -0,0 +1,36 @@
+import type { SentinelCheck } from "./notice.ts";
+/**
+ * A check a host asks the sentinel for (docs/sentinel.md): functional specs of one module, tested in the module's release -
+ * its own codebase's last commit, which holds the code of every module its requires chain builds on. Refused before it is
+ * queued when there is nothing to test: a module that is not there or does not parse, a func-id it does not have, one
+ * not built in its codebase as its ***plain has it now.
+ */
+export interface CheckRequest {
+    /** The module, by name: its .plain file's, in the project's folder. */
+    module: string;
+    /**
+     * The functional specs to test, each `module:func-id` - of the module, or of any module its requires chain builds on,
+     * whose code its release holds. A bare func-id is the module's own.
+     */
+    funcIds: string[];
+}
+/** A host's check, found good to queue - or why not, saying which. */
+export declare function prepareCheck(project: string, request: CheckRequest): SentinelCheck | {
+    refused: string;
+};
+/** A functional spec of a check, as turri reads it now: what it says, and its scenarios. */
+export interface CheckedSpec {
+    /** As the check names it: `module:func-id`. */
+    funcId: string;
+    text: string;
+    conformance: Array<{
+        id: string;
+        text: string;
+    }>;
+    acceptance: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+/** The check's functional specs as the module's ***plain has them now, with their scenarios - in the brief. */
+export declare function checkedSpecs(check: SentinelCheck): CheckedSpec[];

package/dist/sentinel-check.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { PLAIN_SOURCE_FILE_EXTENSION, withParseCache } from "./plain/parser.js";
+import { ACCEPTANCE_TESTS, CONFORMANCE_TESTS, FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS } from "./plain/spec.js";
+import { chainSpec, codebaseCompletion } from "./regenerate/loop.js";
+import { builtTips, isImportModule, projectPlainFiles, resolveRequiresChain } from "./regenerate/requires.js";
+/** A host's check, found good to queue - or why not, saying which. */
+export function prepareCheck(project, request) {
+    return withParseCache(() => {
+        const name = (request.module ?? "").trim();
+        const file = projectPlainFiles(project).find((path) => basename(path, PLAIN_SOURCE_FILE_EXTENSION) === name);
+        if (name === "" || file === undefined)
+            return { refused: `There is no module ${name === "" ? "named" : name} in the project: no .plain file of its folder is ${name || "<module>"}.plain.` };
+        if (isImportModule(file))
+            return { refused: `${name} is an import module: it has no codebase of its own to release. Check a module that imports it.` };
+        let chain;
+        try {
+            chain = resolveRequiresChain(file, [], undefined, { allowNoFunctionalities: true });
+        }
+        catch (error) {
+            return { refused: `${name} does not parse: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        const tip = chain.at(-1);
+        const asked = [...new Set((request.funcIds ?? []).map((funcId) => funcId.trim()).filter((funcId) => funcId !== ""))];
+        if (asked.length === 0)
+            return { refused: `Name at least one of ${whose(name)} functional specs to check, by func-id.` };
+        // Each as the module and func-id it is - `module:func-id`, a bare func-id the module's own.
+        const named = asked.map((funcId) => {
+            const colon = funcId.indexOf(":");
+            const module = colon === -1 ? name : funcId.slice(0, colon).trim();
+            const id = colon === -1 ? funcId : funcId.slice(colon + 1).trim();
+            return { module, id, label: `${module}:${id}` };
+        });
+        // Only what its release holds: the module and the modules its requires chain builds on.
+        const inChain = new Map(chain.map((entry) => [entry.moduleName, entry]));
+        const outside = named.filter(({ module }) => !inChain.has(module));
+        if (outside.length > 0) {
+            const below = chain.slice(0, -1).map((entry) => entry.moduleName);
+            return {
+                refused: `Not in ${whose(name)} release: ${outside.map((spec) => spec.label).join(", ")} - ${[...new Set(outside.map((spec) => spec.module))].join(", ")} ${new Set(outside.map((spec) => spec.module)).size === 1 ? "is" : "are"} not ${name} or a module its requires chain builds on` +
+                    `${below.length > 0 ? ` (${below.join(", ")})` : ` - it builds on none`}.`,
+            };
+        }
+        const unknown = named.filter(({ module, id }) => !inChain.get(module).funcIds.includes(id));
+        if (unknown.length > 0)
+            return { refused: `No such functional spec: ${unknown.map((spec) => `${spec.module} has no ${spec.id}`).join("; ")}.` };
+        // Built in its own codebase, as its ***plain has it now: its record, as last committed, holds it.
+        const completion = codebaseCompletion(chain);
+        const incomplete = new Set(completion.codebase === tip.buildDir ? completion.modules.flatMap((module) => module.incomplete.map((id) => `${module.module}\0${id}`)) : named.map(({ module, id }) => `${module}\0${id}`));
+        const notBuilt = named.filter(({ module, id }) => incomplete.has(`${module}\0${id}`));
+        if (notBuilt.length > 0) {
+            const above = builtTips(file).map((built) => built.at(-1).moduleName).filter((module) => module !== name);
+            return {
+                refused: `Not built in ${whose(name)} codebase as its ***plain has ${notBuilt.length === 1 ? "it" : "them"} now: ${notBuilt.map((spec) => spec.label).join(", ")}.` +
+                    (above.length > 0 ? ` ${whose(name)} code is built on in ${above.join(" and ")}'s codebase: check ${above.length === 1 ? above[0] : "one of them"}, naming ${notBuilt.length === 1 ? "it" : "them"} as ${name}:<func-id>.` : ""),
+            };
+        }
+        return { id: randomUUID().slice(0, 8), module: name, plainFile: file, funcIds: named.map((spec) => spec.label), at: new Date().toISOString() };
+    });
+}
+/** A module's, in words: predators', app's. */
+const whose = (name) => (name.endsWith("s") ? `${name}'` : `${name}'s`);
+/** The check's functional specs as the module's ***plain has them now, with their scenarios - in the brief. */
+export function checkedSpecs(check) {
+    const tree = chainSpec(resolveRequiresChain(check.plainFile, [], undefined, { allowNoFunctionalities: true })).tree;
+    const own = tree[FUNCTIONAL_REQUIREMENTS] ?? [];
+    const inherited = tree[REQUIRED_FUNCTIONAL_SPECS] ?? [];
+    const scenarios = (list) => (list ?? []).map((scenario) => ({ id: String(scenario.id ?? ""), text: String(scenario.text ?? "").trim() }));
+    return check.funcIds.flatMap((funcId) => {
+        const colon = funcId.indexOf(":");
+        const module = colon === -1 ? check.module : funcId.slice(0, colon);
+        const id = colon === -1 ? funcId : funcId.slice(colon + 1);
+        const item = module === check.module ? own.find((each) => each.id === id) : inherited.find((each) => each.module === module && each.id === id);
+        if (item === undefined)
+            return [];
+        return [{ funcId, text: String(item.markdown ?? "").trim(), conformance: scenarios(item[CONFORMANCE_TESTS]), acceptance: scenarios(item[ACCEPTANCE_TESTS]) }];
+    });
+}

package/dist/sentinel.d.ts

@@ -2,7 +2,8 @@ import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type SentinelSetting } from "./config.ts";
 import { type Job } from "./regenerate/jobs.ts";
 import type { DeployedProcess } from "./regenerate/release.ts";
-import { type Conclusion, type Notice, type NoticeInput } from "./notice.ts";
+import { type Conclusion, type Notice, type NoticeInput, type SentinelCheck } from "./notice.ts";
+import type { CheckedSpec } from "./sentinel-check.ts";
 export * from "./notice.ts";
 /**
  * The sentinel: a chat of the session's own that every finished pulse goes to (docs/sentinel.md). It checks how each
@@ -15,9 +16,10 @@ export * from "./notice.ts";
 export declare function sentinelSetting(cwd: string): SentinelSetting;
 /**
  * What the person is asked before the sentinel first opens in a session, under `sentinel: ask`, in one sentence: the pulse
- * that would open it and what it does - so a tab that starts working on its own is not a surprise - and whether to start it.
+ * - or the host's check - that would open it and what it does - so a tab that starts working on its own is not a surprise
+ * - and whether to start it.
  */
-export declare function sentinelStartNotice(job: Job, cwd: string): NoticeInput;
+export declare function sentinelStartNotice(about: Job | SentinelCheck, cwd: string): NoticeInput;
 /** A pulse that stopped on ***plain that contradicts itself: put to the person by turri itself, the way out the chat's to work out. */
 export declare function specConflictNotice(job: Job, task: string): NoticeInput;
 export declare function guidanceFile(cwd: string): string;
@@ -32,7 +34,9 @@ export declare function pulseEndsBlock(sentinel: boolean): string;
  * What the chat the person is in is told of a pulse that landed, with the sentinel on: that it landed, what the sentinel
  * does with it - and to tell the person so, and do nothing else about it.
  */
-export declare function landedNote(job: Job, released: DeployedProcess[]): string;
+export declare function landedNote(job: Job, released: DeployedProcess[], options?: {
+    shown?: boolean;
+}): string;
 /**
  * Its identity and its task, in its system prompt in place of the conversation's. A host's `surface` - where the person
  * watches it, in the host's words - stands in place of their not watching, and has it try a release with the host's tools.
@@ -50,16 +54,43 @@ export declare function sentinelBrief(job: Job, context: {
     releaseAfterPulse: boolean;
     reaction: string;
 }): string;
-/** The tools the sentinel's agent may call: what reads, its notices and its guidance - and what a host gives it. */
+/**
+ * What the sentinel is told of a host's check: the module and its release - what runs, and where - and the functional
+ * specs to test, with what each says and its scenarios, as turri reads them now.
+ */
+export declare function sentinelCheckBrief(check: SentinelCheck, context: {
+    specs: CheckedSpec[];
+    released: DeployedProcess[];
+    commit?: string;
+    releasedNow: boolean;
+    focused?: string;
+}): string;
+/**
+ * The tools the sentinel's agent may call: what reads, write and edit for the project's tooling alone, resume, its
+ * notices and its guidance - and what a host gives it.
+ */
 export declare const SENTINEL_TOOLS: string[];
+/** The keys of config.turri.yaml the sentinel may change: where the testing scripts are, and the toolchains' folders. */
+export declare const SENTINEL_CONFIG_KEYS: string[];
 /**
- * Its file tools and shell: the whole project to read and nothing to write - the shell behind the command check, the OS
- * sandbox where one is up, and the audit, with the network open. Its home and temporary folder are its own, in the
- * modules' scratch.
+ * The project's tooling, which the sentinel fixes itself: its testing scripts - `test_scripts/`, a `run_*.sh` or
+ * `prepare_environment*.sh` at its root, and each script its config names - and its `config.turri*.yaml` files. In the
+ * project, and in a project one folder down (***plain kept in plain/). Never a .plain file: the ***plain is the person's.
+ */
+export declare function sentinelTooling(cwd: string): string[];
+/**
+ * Its file tools and shell: the whole project to read, and to write only its tooling (`sentinelTooling`) - in a config
+ * file, only the keys of SENTINEL_CONFIG_KEYS. Its shell runs behind the command check, the OS sandbox where one is up,
+ * and the audit, with the project read only and the network open - and changes nothing of the machine's. Its home and
+ * temporary folder are its own, in the modules' scratch.
  */
 export declare function sentinelFileTools(cwd: string): ToolDefinition[];
 export declare function notifyTool(notify: (input: NoticeInput) => Notice | undefined): ToolDefinition;
 export declare function concludeTool(conclude: (conclusion: Conclusion) => string | undefined): ToolDefinition;
 /** What the chat the person is in is told when the sentinel is done with a pulse: to say so, and do nothing more. */
-export declare function concludedNote(conclusion: Conclusion): string;
+export declare function concludedNote(conclusion: Conclusion, options?: {
+    shown?: boolean;
+}): string;
+/** Bring a module up again once the sentinel fixed what stopped its pulse: what is left there is regenerated, its scripts run. */
+export declare function resumeTool(resume: (plainFile: string) => Promise<string>): ToolDefinition;
 export declare function keepGuidanceTool(cwd: string): ToolDefinition;