@turri-dev/cli 0.1.25-next.fb3566e → 0.1.26-next.2fc445f

package/README.md

@@ -159,6 +159,7 @@ In a new project **turri** starts it itself, without asking how: it chooses the
 - **`/halt`** halts a pulse, **`/lineage`** shows every generation of a module, and the **`drift`** tool says what is left to regenerate;
 - **`/btw <question>`** asks turri something on the side - answered at once, even while a question waits for you (typed as the answer, under "Something else…"), and left out of the conversation;
 - **`/turri-config`** changes any setting of the project's `config.turri.yaml` - the models, review, conformance tests, how many pulses at once - and says when it takes effect: now, at your next message, or at the next pulse. No restart: `/turri-config review false`, or `/turri-config` alone to pick from the list;
+- **`/sentinel`** says whether the sentinel checks every pulse that finishes: `ask` (you are asked before it first opens), `on` or `off`;
 - **`/stack`** chooses the stack to build with, in a project whose backend and frontend each have their own testing scripts in `config.turri.<stack>.yaml` - `/stack backend`, `/stack none` - for the session (`--stack <name>` on the command line). The chat's model builds each part with its own stack by itself, pinned to that module's pulses.
 
 Other things to ask for:

package/dist/chats.d.ts

@@ -2,6 +2,7 @@ import type { AgentSession, ExtensionAPI, ExtensionContext, ExtensionFactory, Ex
 import { type ChatScope } from "./chat-scope.ts";
 import { type RunRecord } from "./chat-records.ts";
 import { type ChatUi } from "./chat-ui.ts";
+import { type SentinelSetting } from "./config.ts";
 import type { AskUserIO } from "./ask.ts";
 import type { Job, JobRegistry } from "./regenerate/jobs.ts";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
@@ -23,7 +24,9 @@ import { type ChatRole, type Conclusion, type Notice, type NoticeAnswer, type No
  *
  * With the project's sentinel on (sentinel.ts), every finished pulse goes to the sentinel - a chat of the session's own,
  * opened in the background with the first, and again after it is closed - and the chat the person looks at shows only
- * that it landed. What the sentinel finds wrong it puts to the person as a notice, in the chat they look at.
+ * that it landed. What the sentinel finds wrong it puts to the person as a notice, in the chat they look at. Under
+ * `sentinel: ask`, the person is asked first - a notice of turri's own, before it first opens in the session - the pulses
+ * that end meanwhile held until they answer.
  */
 /** The most chats a session has open at once. */
 export declare const MAX_CHATS = 9;
@@ -63,7 +66,7 @@ export interface TurriHost {
     onConcluded?(conclusion: Conclusion & {
         chat: string;
     }): void;
-    /** What the sentinel puts to the person: the host draws it in the chat it names, and answers it with `answer`. */
+    /** What the sentinel puts to the person - and, `kind: "sentinel-start"`, whether to start it: the host draws it in the chat it names, and answers it with `answer`. */
     onNotice?(notice: Notice): void;
     /** A notice is over - answered, dismissed, or superseded by a newer one about its module: the host takes its card down. */
     onNoticeOver?(notice: Notice): void;
@@ -229,8 +232,12 @@ export interface CoreOptions {
     persist?: boolean;
     /** The host's dialogs, a chat's own. */
     dialogs?: (chat: string) => AskUserIO | undefined;
-    /** Whether the project wants a sentinel - read as each pulse finishes. Unset: none. */
-    sentinel?: () => boolean;
+    /** Whether the project wants a sentinel - read as each pulse finishes: on, off, or ask the person first. Unset: none. */
+    sentinel?: () => SentinelSetting;
+    /** Under `sentinel: ask`: what the person is asked before the sentinel first opens, about the pulse that would open it. */
+    sentinelStart?: (job: Job) => NoticeInput;
+    /** The person chose for the project, asked whether to start the sentinel: `sentinel:` written. */
+    setSentinel?: (on: boolean) => void;
 }
 /** A chat's session, as stopping what it does reaches it. */
 export type Stoppable = Pick<AgentSession, "isStreaming" | "isCompacting" | "isRetrying" | "isBashRunning" | "abort" | "abortBash">;

package/dist/chats.js

@@ -5,7 +5,7 @@ import { adoptRun, forgetChat, recordRun } from "./chat-records.js";
 import { createChatUi } from "./chat-ui.js";
 import { debugMode } from "./config.js";
 import { record } from "./regenerate/ledger.js";
-import { newNotice, noticeTask, SENTINEL, wentWrong } from "./notice.js";
+import { newNotice, noticeTask, SENTINEL, sentinelStartChoice, wentWrong } from "./notice.js";
 /**
  * The chats of a turri session.
  *
@@ -23,7 +23,9 @@ import { newNotice, noticeTask, SENTINEL, wentWrong } from "./notice.js";
  *
  * With the project's sentinel on (sentinel.ts), every finished pulse goes to the sentinel - a chat of the session's own,
  * opened in the background with the first, and again after it is closed - and the chat the person looks at shows only
- * that it landed. What the sentinel finds wrong it puts to the person as a notice, in the chat they look at.
+ * that it landed. What the sentinel finds wrong it puts to the person as a notice, in the chat they look at. Under
+ * `sentinel: ask`, the person is asked first - a notice of turri's own, before it first opens in the session - the pulses
+ * that end meanwhile held until they answer.
  */
 /** The most chats a session has open at once. */
 export const MAX_CHATS = 9;
@@ -90,6 +92,13 @@ export function createChats(options) {
     const open = [];
     /** The pulse the sentinel is on now, while its agent works: a newer one of the same module replaces a check of one that went well. */
     let sentinelOnJob;
+    /**
+     * Under `sentinel: ask`, whether the person said to start the sentinel this session: asked - the notice `asking` open,
+     * the pulses that ended meanwhile `held` - started, or not this session.
+     */
+    let consent = "unasked";
+    let asking;
+    const held = [];
     const run = { run: randomUUID().slice(0, 8), pid: process.pid, started: new Date().toISOString(), chats: [] };
     const changed = () => {
         for (const listener of listeners) {
@@ -106,14 +115,19 @@ export function createChats(options) {
     const sentinelChat = () => chats.find((chat) => chat.role === SENTINEL);
     /** The person's chats: all but the sentinel. */
     const people = () => chats.filter((chat) => chat.role !== SENTINEL);
-    const wantsSentinel = () => {
+    const setting = () => {
         try {
-            return options.sentinel?.() === true;
+            return options.sentinel?.() ?? false;
         }
         catch {
             return false;
         }
     };
+    /** On, or asked for - and not declined this session. */
+    const wantsSentinel = () => {
+        const now = setting();
+        return now === true || (now === "ask" && consent !== "declined");
+    };
     /** The chat the person looks at, for what is put to them - never the sentinel: when it is shown, `fallback`, else their first. */
     const personFacing = (fallback) => {
         const shown = chats.find((chat) => chat.id === shownId);
@@ -250,6 +264,9 @@ export function createChats(options) {
             }
             const recorded = run.chats.find((kept) => kept.id === id);
             chats.splice(chats.indexOf(chat), 1);
+            // The question whether to start the sentinel was in it: put again in the chat the person looks at now.
+            if (asking?.chat === id)
+                askAgain();
             chat.unsubscribe?.();
             chat.ui?.close();
             inChat(chat.scope, () => record({ kind: "chat.closed" }, { project: cwd }));
@@ -343,26 +360,19 @@ export function createChats(options) {
         },
         sentinelOn: () => driver !== undefined && wantsSentinel(),
         jobFinished(job) {
+            // The question was settled in config.turri.yaml while it was open: what it held goes as the file now says.
+            if (consent === "asking" && setting() !== "ask")
+                settleStart(setting() === true ? "given" : "declined", "superseded");
             if (core.sentinelOn()) {
+                if (consent === "asking" || (setting() === "ask" && consent === "unasked" && sentinelChat() === undefined && askToStart(job))) {
+                    held.push(job);
+                    changed();
+                    return;
+                }
                 sentinelFinished(job);
                 return;
             }
-            const asked = chats.find((chat) => chat.id === job.chat);
-            const chat = asked?.instance !== undefined ? asked : (core.shownChat() ?? chats[0]);
-            if (chat === undefined)
-                return;
-            if (chat.id !== shownId)
-                chat.unread = true;
-            try {
-                chat.instance?.announce(job);
-            }
-            catch {
-                // A chat let go as the pulse ended: the one shown is told instead.
-                const shown = core.shownChat();
-                if (shown !== undefined && shown !== chat)
-                    shown.instance?.announce(job);
-            }
-            changed();
+            toAsker(job);
         },
         jobsChanged() {
             for (const chat of chats) {
@@ -437,6 +447,8 @@ export function createChats(options) {
                 return "missing";
             if (notice.state !== "open")
                 return "over";
+            if (notice.kind === "sentinel-start")
+                return answerStart(notice, answer);
             const task = noticeTask(notice, answer);
             over(notice, "dismiss" in answer ? "dismissed" : "steer" in answer ? "steered" : "accepted");
             if (task === undefined)
@@ -491,6 +503,89 @@ export function createChats(options) {
         if (chat !== undefined)
             inChat(chat.scope, () => record({ kind: "notice.over", notice: notice.id, state }, { project: cwd }));
     }
+    /** A pulse ended, told to the chat that asked for it - as without a sentinel - or the chat shown, when that one is closed. */
+    function toAsker(job) {
+        const asked = chats.find((chat) => chat.id === job.chat);
+        const chat = asked?.instance !== undefined ? asked : (core.shownChat() ?? chats[0]);
+        if (chat === undefined)
+            return;
+        if (chat.id !== shownId)
+            chat.unread = true;
+        try {
+            chat.instance?.announce(job);
+        }
+        catch {
+            // A chat let go as the pulse ended: the one shown is told instead.
+            const shown = core.shownChat();
+            if (shown !== undefined && shown !== chat)
+                shown.instance?.announce(job);
+        }
+        changed();
+    }
+    /**
+     * Under `sentinel: ask`, the first pulse that would open the sentinel this session: the person asked whether to start it,
+     * in the chat they look at. False when there is nothing to ask with, or no chat to ask in: the sentinel opens as asked.
+     */
+    function askToStart(job) {
+        let input;
+        try {
+            input = options.sentinelStart?.(job);
+        }
+        catch {
+            input = undefined;
+        }
+        if (input === undefined)
+            return false;
+        consent = "asking";
+        asking = core.notice({ ...input, kind: "sentinel-start" });
+        if (asking === undefined)
+            consent = "unasked";
+        return asking !== undefined;
+    }
+    /** The chat the question was put in is gone: it is put in the chat the person looks at - none left, the pulses go as without one. */
+    function askAgain() {
+        const question = asking;
+        over(question, "superseded");
+        asking = undefined;
+        consent = "unasked";
+        if (!askToStart(held[0]))
+            settleStart("declined", "superseded");
+    }
+    /** The person answered whether to start the sentinel: written to the project, when they chose for it, and what was held let go. */
+    function answerStart(notice, answer) {
+        const choice = sentinelStartChoice(notice, answer);
+        try {
+            if (choice === "always" || choice === "never")
+                options.setSentinel?.(choice === "always");
+        }
+        catch (error) {
+            core.notify(`config.turri.yaml could not be written: ${error instanceof Error ? error.message : String(error)}`, "warning");
+        }
+        settleStart(choice === "start" || choice === "always" ? "given" : "declined", "dismiss" in answer ? "dismissed" : "steer" in answer ? "steered" : "accepted");
+        // Their own words are the chat's to act on: the sentinel is not started.
+        if ("steer" in answer) {
+            const task = noticeTask(notice, answer);
+            const chat = chats.find((candidate) => candidate.id === notice.chat) ?? personFacing();
+            if (task !== undefined)
+                chat?.instance?.act(task);
+        }
+        return "dismiss" in answer ? "dismissed" : "done";
+    }
+    /** Whether to start the sentinel is settled: its question closed, and the pulses held go to it - or, declined, to their chats. */
+    function settleStart(now, state) {
+        consent = now;
+        const question = asking;
+        asking = undefined;
+        if (question !== undefined && question.state === "open")
+            over(question, state);
+        for (const job of held.splice(0)) {
+            if (core.sentinelOn())
+                sentinelFinished(job);
+            else
+                toAsker(job);
+        }
+        changed();
+    }
     /**
      * A pulse ended, with the sentinel on: the chat the person looks at says so - its agent told of one that landed, to
      * tell the person it landed and what the sentinel does with it, and nothing more; of one that went wrong, not, the

package/dist/config-command.js

@@ -139,6 +139,36 @@ export function registerTurriConfig(pi, options) {
         }
         return top.find((setting) => chosen.startsWith(`${setting.key}:`));
     };
+    // /sentinel: its one setting by its own name - asked before it first opens in a session, on without asking, or off.
+    const sentinelChoices = [
+        ["ask", "ask", "you are asked, with what it does, before it first opens in a session"],
+        ["on", "true", "it opens with the first pulse that finishes, without asking"],
+        ["off", "false", "no sentinel: each pulse is told to the chat that asked for it"],
+    ];
+    pi.registerCommand("sentinel", {
+        description: "Whether the sentinel checks every finished pulse: ask first, on, or off",
+        getArgumentCompletions: (prefix) => {
+            const items = sentinelChoices.filter(([word]) => word.startsWith(prefix.trim().toLowerCase()));
+            return items.length === 0 ? null : items.map(([word, , about]) => ({ value: word, label: word, description: about }));
+        },
+        handler: async (args, ctx) => {
+            const setting = settingOf("sentinel");
+            const typed = args.trim().toLowerCase();
+            let word = typed;
+            if (word === "") {
+                if (!ctx.hasUI)
+                    return;
+                const now = currentValue(readConfigText(cwd), setting.key);
+                const lines = sentinelChoices.map(([choice, , about]) => `${choice} - ${about}`);
+                const chosen = await ctx.ui.select(`/sentinel - now: ${now === undefined ? `unset - ${setting.unset}` : shownValue(now)}`, lines);
+                if (chosen === undefined)
+                    return;
+                word = chosen.slice(0, chosen.indexOf(" "));
+            }
+            const value = sentinelChoices.find(([choice]) => choice === word)?.[1] ?? word;
+            await apply(setting, value, ctx);
+        },
+    });
     pi.registerCommand("turri-config", {
         description: `Change a setting of the project's ${CONFIG_FILE}`,
         getArgumentCompletions: (prefix) => {

package/dist/config-edit.js

@@ -66,7 +66,7 @@ export function settings(rules = []) {
         { key: "mutation-testing", about: "whether the coding agent and the reviewer can put a bug in the code for one test run (can_it_fail)", kind: "boolean", unset: "true", effect: "next-pulse" },
         { key: "allow-to-stop-jobs", about: "whether turri stops a running pulse the ***plain has moved on from", kind: "boolean", unset: "true", effect: "now" },
         { key: "release-after-pulse", about: "whether every pulse that lands code releases it", kind: "boolean", unset: "false", effect: "next-landing" },
-        { key: "sentinel", about: "whether a chat of its own checks every finished pulse, tests the release, and tells you what is wrong", kind: "boolean", unset: "true", effect: "next-landing" },
+        { key: "sentinel", about: "whether a chat of its own checks every finished pulse, tests the release, and tells you what is wrong - ask: you are asked before it first opens", kind: "choice", options: ["ask", "true", "false"], unset: "ask", effect: "next-landing" },
         { key: "unittests-script", about: "the unit testing script, by path from the project root", kind: "path", unset: "the one run_unittests*.sh found", effect: "next-test-run" },
         { key: "conformance-tests-script", about: "the conformance testing script, by path from the project root", kind: "path", unset: "the one run_conformance_tests*.sh found", effect: "next-test-run" },
         { key: "prepare-environment-script", about: "run on the build before every conformance testing script run, by path from the project root - optional", kind: "path", unset: "the one prepare_environment*.sh found, else none", effect: "next-test-run" },
@@ -119,7 +119,7 @@ export function parseValue(setting, typed, known) {
         case "choice": {
             const word = text.toLowerCase();
             if (setting.options?.includes(word))
-                return { value: setting.key === "conformance-tests" && word === "false" ? false : word };
+                return { value: word === "false" ? false : word === "true" ? true : word };
             return { error: `${setting.key} is one of ${setting.options?.join(", ")}.` };
         }
         case "number": {

package/dist/config.d.ts

@@ -19,7 +19,7 @@
  * mutation-testing: false                                   # give the coding agent and the reviewer can_it_fail (default: true)
  * allow-to-stop-jobs: false                                 # stop a running job the spec moved on from (default: true)
  * release-after-pulse: true                                 # release what each pulse lands, as its last stage, before the next pulse (default: false)
- * sentinel: false                                           # a chat of its own every finished pulse goes to, which tests the release and tells you what is wrong (default: true)
+ * sentinel: true                                            # a chat of its own every finished pulse goes to, which tests the release and tells you what is wrong: true, false, or ask - the person asked before it first opens in a session (default: ask)
  * rules-off: [integrations]                                 # ***plain rules to leave out of the prompts, by name (default: none)
  * unittests-script: test_scripts/run_unittests.sh           # the testing scripts - see test-scripts.ts
  * conformance-tests-script: test_scripts/run_conformance_tests.sh
@@ -174,6 +174,8 @@ export declare function projectModels(config: Pick<ProjectConfig, "harnessModel"
 export declare function roleModel(config: Pick<ProjectConfig, "harnessModel" | "judgeModel" | "models">, role: AgentRole): ModelChoice | undefined;
 /** How long each turn of a role's agents may take, in milliseconds: its own, `default`'s, `turn-limit:`'s - or undefined, the harness's default. */
 export declare function roleTurnLimitMs(config: Pick<ProjectConfig, "models" | "turnLimit">, role: AgentRole | undefined): number | undefined;
+/** `sentinel:` - on, off, or `ask`: on once the person says so, asked before it first opens in a session. */
+export type SentinelSetting = boolean | "ask";
 export interface ProjectConfig {
     /** The .plain file the module command builds when it is given none. */
     module?: string;
@@ -228,9 +230,10 @@ export interface ProjectConfig {
     releaseAfterPulse?: boolean;
     /**
      * Whether the session has a sentinel: a chat of its own that every finished pulse goes to - checked, a release tested,
-     * and what is wrong put to the person - instead of the chat that asked for it (docs/sentinel.md). Unset: true.
+     * and what is wrong put to the person - instead of the chat that asked for it (docs/sentinel.md). `ask`: the person is
+     * asked, before it first opens in a session, whether to start it. Unset: ask.
      */
-    sentinel?: boolean;
+    sentinel?: SentinelSetting;
     /** Path from the root to the unit testing script. */
     unittestsScript?: string;
     /** Path from the root to the conformance testing script. */

package/dist/config.js

@@ -25,7 +25,7 @@ import { projectDirOf } from "./regenerate/paths.js";
  * mutation-testing: false                                   # give the coding agent and the reviewer can_it_fail (default: true)
  * allow-to-stop-jobs: false                                 # stop a running job the spec moved on from (default: true)
  * release-after-pulse: true                                 # release what each pulse lands, as its last stage, before the next pulse (default: false)
- * sentinel: false                                           # a chat of its own every finished pulse goes to, which tests the release and tells you what is wrong (default: true)
+ * sentinel: true                                            # a chat of its own every finished pulse goes to, which tests the release and tells you what is wrong: true, false, or ask - the person asked before it first opens in a session (default: ask)
  * rules-off: [integrations]                                 # ***plain rules to leave out of the prompts, by name (default: none)
  * unittests-script: test_scripts/run_unittests.sh           # the testing scripts - see test-scripts.ts
  * conformance-tests-script: test_scripts/run_conformance_tests.sh
@@ -561,7 +561,7 @@ function readConfigFile(path) {
         mutationTesting: typeof raw[CONFIG_KEYS.mutationTesting] === "boolean" ? raw[CONFIG_KEYS.mutationTesting] : undefined,
         allowToStopJobs: typeof raw[CONFIG_KEYS.allowToStopJobs] === "boolean" ? raw[CONFIG_KEYS.allowToStopJobs] : undefined,
         releaseAfterPulse: typeof raw[CONFIG_KEYS.releaseAfterPulse] === "boolean" ? raw[CONFIG_KEYS.releaseAfterPulse] : undefined,
-        sentinel: typeof raw[CONFIG_KEYS.sentinel] === "boolean" ? raw[CONFIG_KEYS.sentinel] : undefined,
+        sentinel: typeof raw[CONFIG_KEYS.sentinel] === "boolean" || raw[CONFIG_KEYS.sentinel] === "ask" ? raw[CONFIG_KEYS.sentinel] : undefined,
         unittestsScript: text(raw[CONFIG_KEYS.unittestsScript]),
         conformanceTestsScript: text(raw[CONFIG_KEYS.conformanceTestsScript]),
         prepareEnvironmentScript: text(raw[CONFIG_KEYS.prepareEnvironmentScript]),

package/dist/extension.js

@@ -55,6 +55,7 @@ import { inheritProviders, inheritThinkingLevel } from "./pi.js";
 import { beginCapture, captureConsole, describeCaptured, dropNoise } from "./quiet.js";
 import { loadRules, renderRulesBlock } from "./rules.js";
 import { registerTurriConfig } from "./config-command.js";
+import { writeSetting } from "./config-edit.js";
 import { describeStdlib } from "./stdlib.js";
 import { DECLINED, peekKeyListener, runAsk } from "./ask.js";
 import { QuestionDialog } from "./question-dialog.js";
@@ -64,7 +65,7 @@ import { supersededByTurri } from "./chat-skills.js";
 import { conversationIdentity } from "./identity.js";
 import { setSurface, surfaceOf } from "./surface.js";
 import { createChats, scopedToChat } from "./chats.js";
-import { landedNote, pulseEndsBlock, SENTINEL, SENTINEL_TOOLS, sentinelBrief, sentinelOn, sentinelPrompt, specConflictNotice } from "./sentinel.js";
+import { landedNote, pulseEndsBlock, SENTINEL, SENTINEL_TOOLS, sentinelBrief, sentinelPrompt, sentinelSetting, sentinelStartNotice, specConflictNotice } from "./sentinel.js";
 import { noticeDialogs, registerSentinel } from "./sentinel-chat.js";
 import { currentChat } from "./chat-scope.js";
 import { registerChats } from "./chat-commands.js";
@@ -321,8 +322,11 @@ export function createTurriCore(host = {}, options = {}) {
         host,
         jobs,
         extension: (pi, link) => turriExtension(pi, core, link),
-        // A finished pulse goes to the sentinel when the project wants one - read as each pulse finishes.
-        sentinel: () => sentinelOn(cwd),
+        // A finished pulse goes to the sentinel when the project wants one - read as each pulse finishes - the person asked
+        // first under `sentinel: ask`, and what they choose for the project written.
+        sentinel: () => sentinelSetting(cwd),
+        sentinelStart: (job) => sentinelStartNotice(job, cwd),
+        setSentinel: (on) => void writeSetting(cwd, "sentinel", on),
         ...(options.persist !== undefined ? { persist: options.persist } : {}),
         ...(options.dialogs !== undefined ? { dialogs: options.dialogs } : {}),
     });

package/dist/host.d.ts

@@ -6,7 +6,7 @@
  */
 export { createTurri, type Turri, type TurriOptions } from "./host-session.ts";
 export { MAX_CHATS, type ChatInfo, type ChatStatus, type TurriHost } from "./chats.ts";
-export { SENTINEL, type Conclusion, type Notice, type NoticeAction, type NoticeAnswer, type NoticeSeverity, type NoticeState } from "./notice.ts";
+export { SENTINEL, SENTINEL_START, type Conclusion, type Notice, type NoticeAction, type NoticeAnswer, type NoticeSeverity, type NoticeState } from "./notice.ts";
 export type { AskUserIO } from "./ask.ts";
 /** pi itself, as turri is built against it: a host's own extensions and UI are made with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";

package/dist/host.js

@@ -8,7 +8,7 @@
 export { createTurri } from "./host-session.js";
 export { MAX_CHATS } from "./chats.js";
 // The sentinel's notices: what it puts to the person, and how they answer.
-export { SENTINEL } from "./notice.js";
+export { SENTINEL, SENTINEL_START } from "./notice.js";
 /** pi itself, as turri is built against it: a host's own extensions and UI are made with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
 // The project and its settings.

package/dist/init-config.d.ts

@@ -113,7 +113,7 @@ export declare const DEFAULTS: {
     readonly mutationTesting: true;
     readonly allowToStopJobs: true;
     readonly releaseAfterPulse: true;
-    readonly sentinel: true;
+    readonly sentinel: "ask";
     readonly testingScriptsRunOn: "in-place";
     readonly turnLimit: 120;
     readonly compactAt: 100000;

package/dist/init-config.js

@@ -220,7 +220,7 @@ export const DEFAULTS = {
     mutationTesting: true,
     allowToStopJobs: true,
     releaseAfterPulse: true,
-    sentinel: true,
+    sentinel: "ask",
     testingScriptsRunOn: "in-place",
     turnLimit: 120,
     compactAt: 100000,
@@ -266,7 +266,8 @@ export function quickStartConfig(vendor = "other", bedrock, models) {
         `release-after-pulse: ${DEFAULTS.releaseAfterPulse}`,
         "",
         "# Whether a chat of its own, the sentinel, checks every pulse that finishes - and, with release-after-pulse, tests what",
-        "# was released - and tells you in the chat you are in when something needs you.",
+        "# was released - and tells you in the chat you are in when something needs you. ask: you are asked, with what it does,",
+        "# before it first opens in a session; true: it opens without asking; false: none.",
         `sentinel: ${DEFAULTS.sentinel}`,
         "",
         "# What the testing scripts run on: in-place - the code itself; copy - a fresh copy of it.",

package/dist/notice.d.ts

@@ -13,6 +13,11 @@ export interface NoticeAction {
     task: string;
 }
 export interface NoticeInput {
+    /**
+     * `sentinel-start`: not something wrong but a question turri puts before the sentinel first opens in a session - its
+     * actions start it, or not, and are turri's to carry out, not the chat's agent's (SENTINEL_START). None: the sentinel's.
+     */
+    kind?: "sentinel-start";
     severity: NoticeSeverity;
     /** What is wrong, in a line. */
     summary: string;
@@ -33,6 +38,14 @@ export interface Notice extends NoticeInput {
     state: NoticeState;
     at: string;
 }
+/** The answers to the question put before the sentinel first opens: the actions of a `sentinel-start` notice, in order. */
+export declare const SENTINEL_START: {
+    readonly start: "Start the sentinel";
+    readonly always: "Start it, and don't ask again";
+    readonly notNow: "Not this session";
+    readonly never: "Turn it off for this project";
+};
+export type SentinelStartChoice = keyof typeof SENTINEL_START;
 /** How the person answered a notice: one of its actions (by index or label), their own words, or not at all. */
 export type NoticeAnswer = {
     action: number | string;
@@ -42,6 +55,8 @@ export type NoticeAnswer = {
     dismiss: true;
 };
 export declare function newNotice(input: NoticeInput, chat: string): Notice;
+/** The choice an answer to a `sentinel-start` notice makes: dismissed, or answered in the person's own words, it is not now. */
+export declare function sentinelStartChoice(notice: Notice, answer: NoticeAnswer): SentinelStartChoice;
 /** What the focused chat's agent is asked to do once the person answered a notice - undefined when they dismissed it. */
 export declare function noticeTask(notice: Notice, answer: NoticeAnswer): string | undefined;
 /** A notice in words: its summary, its evidence and what can be done - for the agent, the log and a chat without a card. */

package/dist/notice.js

@@ -5,9 +5,23 @@ import { randomUUID } from "node:crypto";
  */
 /** Its name in the strip, the host's chat list, and the ledger. */
 export const SENTINEL = "sentinel";
+/** The answers to the question put before the sentinel first opens: the actions of a `sentinel-start` notice, in order. */
+export const SENTINEL_START = {
+    start: "Start the sentinel",
+    always: "Start it, and don't ask again",
+    notNow: "Not this session",
+    never: "Turn it off for this project",
+};
 export function newNotice(input, chat) {
     return { ...input, id: randomUUID().slice(0, 8), chat, state: "open", at: new Date().toISOString() };
 }
+/** The choice an answer to a `sentinel-start` notice makes: dismissed, or answered in the person's own words, it is not now. */
+export function sentinelStartChoice(notice, answer) {
+    if (!("action" in answer))
+        return "notNow";
+    const label = typeof answer.action === "number" ? notice.actions[answer.action]?.label : answer.action;
+    return Object.keys(SENTINEL_START).find((choice) => SENTINEL_START[choice] === label) ?? "notNow";
+}
 /** What the focused chat's agent is asked to do once the person answered a notice - undefined when they dismissed it. */
 export function noticeTask(notice, answer) {
     if ("dismiss" in answer)

package/dist/sentinel-chat.d.ts

@@ -3,6 +3,11 @@ 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;
+/**
+ * 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.
+ */
+export declare function startTitle(notice: Notice, open: number): string;
 /**
  * A chat's notices: each drawn as a card, and - with no host to answer it - put to the person as a dialog once the chat
  * is idle, one at a time: an action accepted, their own words, or dismissed. A notice that is over closes its dialog.

package/dist/sentinel-chat.js

@@ -54,6 +54,13 @@ export function registerSentinel(pi, session, cwd, hostTools, allowed) {
             pi.setThinkingLevel(choice.thinking);
     });
 }
+/**
+ * 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.
+ */
+export function startTitle(notice, open) {
+    return `${notice.summary}\nUse "/chat ${open + 1}" to open the sentinel.`;
+}
 /**
  * A chat's notices: each drawn as a card, and - with no host to answer it - put to the person as a dialog once the chat
  * is idle, one at a time: an action accepted, their own words, or dismissed. A notice that is over closes its dialog.
@@ -114,8 +121,10 @@ export function noticeDialogs(pi, session, link, context) {
         const controller = new AbortController();
         asking.set(notice.id, controller);
         try {
-            const options = [...notice.actions.map((action, index) => `${index + 1}. ${action.label}`), STEER, DISMISS];
-            const picked = await ctx.ui.select(`sentinel: ${notice.summary}`, options, { signal: controller.signal });
+            // Whether to start the sentinel is turri's question, its answers its own: no words of the person's to act on.
+            const starting = notice.kind === "sentinel-start";
+            const options = [...notice.actions.map((action, index) => `${index + 1}. ${action.label}`), ...(starting ? [] : [STEER]), DISMISS];
+            const picked = await ctx.ui.select(starting ? startTitle(notice, session.chats().length) : `sentinel: ${notice.summary}`, options, { signal: controller.signal });
             if (controller.signal.aborted || notice.state !== "open")
                 return;
             if (picked === STEER) {

package/dist/sentinel.d.ts

@@ -1,4 +1,5 @@
 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";
@@ -10,8 +11,13 @@ export * from "./notice.ts";
  * file tools only read, its shell runs with the project read only, and it has none of the tools that change ***plain or
  * start work. The chat the person talks to is never interrupted for a pulse that went well.
  */
-/** Whether the project wants a sentinel: `sentinel:` in config.turri.yaml, true unset. */
-export declare function sentinelOn(cwd: string): boolean;
+/** Whether the project wants a sentinel: `sentinel:` in config.turri.yaml - true, false, or ask, as it is unset. */
+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.
+ */
+export declare function sentinelStartNotice(job: Job, 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;

package/dist/sentinel.js

@@ -10,7 +10,7 @@ import { formatDuration, pulseName } from "./regenerate/jobs.js";
 import { readLedger } from "./regenerate/ledger.js";
 import { describePulseView, pulseView } from "./regenerate/ledger-view.js";
 import { MODULES_DIR, ensureInScratch } from "./regenerate/paths.js";
-import { SENTINEL, wentWrong } from "./notice.js";
+import { SENTINEL, SENTINEL_START, wentWrong } from "./notice.js";
 export * from "./notice.js";
 /**
  * The sentinel: a chat of the session's own that every finished pulse goes to (docs/sentinel.md). It checks how each
@@ -19,15 +19,42 @@ export * from "./notice.js";
  * file tools only read, its shell runs with the project read only, and it has none of the tools that change ***plain or
  * start work. The chat the person talks to is never interrupted for a pulse that went well.
  */
-/** Whether the project wants a sentinel: `sentinel:` in config.turri.yaml, true unset. */
-export function sentinelOn(cwd) {
+/** Whether the project wants a sentinel: `sentinel:` in config.turri.yaml - true, false, or ask, as it is unset. */
+export function sentinelSetting(cwd) {
     try {
-        return readProjectConfig(cwd).sentinel !== false;
+        return readProjectConfig(cwd).sentinel ?? "ask";
     }
     catch {
-        return true;
+        return "ask";
     }
 }
+/**
+ * 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.
+ */
+export function sentinelStartNotice(job, cwd) {
+    let released = false;
+    try {
+        released = readProjectConfig(cwd).releaseAfterPulse === true;
+    }
+    catch {
+        /* a config that cannot be read releases nothing */
+    }
+    return {
+        kind: "sentinel-start",
+        severity: "info",
+        summary: `${pulseName(job)} finished - start the sentinel, a background tab that reviews each finished pulse${released ? " and tries to use what was released" : ""}?`,
+        evidence: [],
+        actions: [
+            { label: SENTINEL_START.start, task: "The sentinel is started for this session: this pulse and each after it go to it." },
+            { label: SENTINEL_START.always, task: "The sentinel is started, and sentinel: true written to config.turri.yaml: it opens without asking from now on." },
+            { label: SENTINEL_START.notNow, task: "No sentinel this session: each pulse is told to the chat that asked for it. turri asks again next time." },
+            { label: SENTINEL_START.never, task: "sentinel: false written to config.turri.yaml: no sentinel, and no asking." },
+        ],
+        job: job.id,
+        ...(job.pulse !== undefined ? { pulse: job.pulse } : {}),
+    };
+}
 /** 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 function specConflictNotice(job, task) {
     return {

package/docs/chats.md

@@ -21,7 +21,7 @@ The session's, shared by every chat:
 - **what `activate` started** - it runs until turri ends or `/halt activated <name>`, whatever chats are opened or closed;
 - **the ledger** - one run, each event with the id of the chat its work was asked for in (`chat`), and `chat.opened` and `chat.closed` as they happen.
 
-A pulse's end goes to the [sentinel](sentinel.md) - a chat of turri's own, opened in the background with the first pulse that finishes - which checks it, tests what was released, and puts what needs you as a notice in the chat you are in. That chat shows the pulse's end; its agent is told of a pulse that landed, to tell you so and what the sentinel is doing with it - and when the sentinel is done with any pulse, what it found - and nothing more - and not of one that went wrong: the sentinel's notice is what it hears of that. With `sentinel: false`, a pulse's end is told to the chat that asked for it instead, shown or not - its agent reacts to it there; the chat's mark in the strip says it has something new. When that chat has been closed, the chat shown is told. Closing a chat stops its turn, never its pulses.
+A pulse's end goes to the [sentinel](sentinel.md) - a chat of turri's own, opened in the background with the first pulse that finishes, once you said to start it under `sentinel: ask` - which checks it, tests what was released, and puts what needs you as a notice in the chat you are in. That chat shows the pulse's end; its agent is told of a pulse that landed, to tell you so and what the sentinel is doing with it - and when the sentinel is done with any pulse, what it found - and nothing more - and not of one that went wrong: the sentinel's notice is what it hears of that. With `sentinel: false`, a pulse's end is told to the chat that asked for it instead, shown or not - its agent reacts to it there; the chat's mark in the strip says it has something new. When that chat has been closed, the chat shown is told. Closing a chat stops its turn, never its pulses.
 
 ## In the terminal
 

package/docs/config.md

@@ -90,7 +90,7 @@ models:                              # each agent role's model, thinking and tur
 | `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every \*\*\*plain-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any \*\*\*plain is written. `turri init-config` writes it with `integration-embedded`, `integration-embedded-testing` and `integration-standalone` - take them out when the project writes an integration against a REST API. The project's alone | none |
 | `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job \*\*\*plain has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates \*\*\*plain as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |
 | `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model releases it, following the project's release guidance as the chat finds it (what was passed to `release` this conversation, AGENTS.md, the project's skills) for how, or to `dist/<module>` without any - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays. `turri init-config` writes `true` | `false` |
-| `sentinel` | `true` or `false`: whether a chat of turri's own, the sentinel, gets every pulse that finishes - checks it, tests what was released under `release-after-pulse`, and puts what needs you as a notice in the chat you are in - instead of the chat that asked for it. See [the sentinel](sentinel.md). `turri init-config` writes `true` | `true` |
+| `sentinel` | `ask`, `true` or `false`: whether a chat of turri's own, the sentinel, gets every pulse that finishes - checks it, tests what was released under `release-after-pulse`, and puts what needs you as a notice in the chat you are in - instead of the chat that asked for it. `ask`: you are asked, with what it does, before it first opens in a session - see [starting it](sentinel.md#starting-it); `true`: it opens without asking. `/sentinel` sets it from the chat. `turri init-config` writes `ask` | `ask` |
 | `unittests-script` | the unit testing script, by path from the project root - it runs the code's static checks too, exiting 80 when only they fail (see [the static checks](regenerating.md#the-static-checks)) | looked for - see below |
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
 | `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |

package/docs/hosting.md

@@ -123,6 +123,7 @@ await turri.dispose();                 // every chat let go, what activate start
 The [sentinel](sentinel.md) is one of the host's chats: turri opens it with the first pulse that finishes, through the host's own `create` like any chat - `onChats` hears of it, `role: "sentinel"` - and never moves `focus` to it. It closes like any chat, and the next pulse that finishes opens it again; with it on, `openChat` opens up to eight.
 
 - **Notices.** What it finds wrong comes as `onNotice(notice)`: `{ id, chat, severity: "error" | "warning" | "info", summary, evidence: string[], actions: [{ label, task }], module?, pulse?, job?, state: "open" }`. Draw it in the chat `chat` names - the one `focus` last named, or, while that is the sentinel, the chat that asked for the pulse. It is drawn there as a card in the transcript too. A host given `onNotice` answers it itself - the terminal's dialog is not opened - with `answer(id, …)`: `{ action: index | label }` starts that chat's agent on the action's task, `{ steer: text }` on the person's words, `{ dismiss: true }` on nothing. `onNoticeOver(notice)` comes as it is answered - and when a newer notice about its module supersedes it (`state: "superseded"`) - for the host to take the card down. `notices()` lists the open ones.
+- **Starting it.** Under `sentinel: ask` - as it is unset - the person is asked before it first opens in the session: a notice with `kind: "sentinel-start"`, `severity: "info"`, in the chat `chat` names, its `summary` the question in one sentence, no `evidence`, and its actions the answers - `Start the sentinel`, `Start it, and don't ask again`, `Not this session`, `Turn it off for this project`. Draw it as a question rather than as something wrong. `answer(id, { action })` answers it, by index or label - `"done"` - and `{ dismiss: true }` is not this session; turri writes `sentinel:` itself for the two that choose for the project. Until it is answered, the pulses that finish are held: neither the sentinel nor the chat hears of them. A host that offers the setting too writes it as `/turri-config` does - `ask`, `true` or `false` (see `configSettings`).
 - **Conclusions.** As the sentinel is done with each pulse - all well or not - `onConcluded({ job, verdict: "holds" | "wrong", summary, module, pulse, chat })` comes, and the chat `chat` names - the one `focus` last named, as for a notice - shows it and its agent says so in a line.
 - **Its model.** The `sentinel` role in `models:`, else the chat's model - `models.chat`, else `harness-model` - with its thinking, set as its chat opens: not pi's default model, which may not be one the project's provider has. What the person then picks in its chat stands. See [its model](sentinel.md#its-model).
 - **Its tools.** `sentinel: { tools }` are [pi](https://pi.dev) tool definitions registered in the sentinel's chat alone and told to it in its prompt - the host's browser, say, for it to test a release with. The rest of the host's `extensions` are built into its chat too, but their tools are refused it: only its own read, and these.

package/docs/sentinel.md

@@ -2,12 +2,25 @@
 
 The sentinel is a chat of turri's own, beside the chats you talk to. Every pulse that finishes goes to it: it checks how the pulse went - and, with `release-after-pulse` on, tests what was released - and when something needs you, it says so in the chat you are in, with what can be done about it. You go on talking about the software, and building it, while it watches what lands.
 
-It is on unless `config.turri.yaml` says `sentinel: false`. It is there in the terminal and in a host such as turri-desktop - wherever turri holds [chats](chats.md) - and not in pi's print, json or rpc modes, nor on the command line (`turri regenerate`, `turri change-plain`), which have no chat to tell: there a pulse is told as it is without it.
+`sentinel:` in `config.turri.yaml` says whether there is one: `ask`, as it is unset - you are asked before it first opens in a session (below); `true` - it opens without asking; `false` - none. It is there in the terminal and in a host such as turri-desktop - wherever turri holds [chats](chats.md) - and not in pi's print, json or rpc modes, nor on the command line (`turri regenerate`, `turri change-plain`), which have no chat to tell: there a pulse is told as it is without it.
+
+## Starting it
+
+Under `sentinel: ask`, a tab that starts working on its own is not sprung on you. When the first pulse of a session finishes, turri asks first - a notice of its own in the chat you are in, before the sentinel opens, in one sentence: `app · regenerate pulse 3 finished - start the sentinel, a background tab that reviews each finished pulse and tries to use what was released?` - the release left out with `release-after-pulse` off. In the terminal it is a dialog once that chat is not mid-turn, with how to switch to the sentinel once it is open - `Use "/chat 2" to open the sentinel.`, the number the one it will have in the strip; in a host, a notice with `kind: "sentinel-start"` (see [in a host](#in-a-host)). You answer:
+
+- **Start the sentinel** - it opens, and checks this pulse and each after it this session;
+- **Start it, and don't ask again** - the same, and `sentinel: true` is written to `config.turri.yaml`;
+- **Not this session**, or `esc` - no sentinel until turri starts again: each pulse is told to the chat that asked for it, as without one;
+- **Turn it off for this project** - `sentinel: false` is written.
+
+Nothing goes to the sentinel, or to your chat, until you answer: the pulses that finish meanwhile are held, and go to it - or to their chats - as you say. You are asked once a session: a sentinel closed and opened again by the next pulse is not asked for again, nor one `turri --continue` reopened. Close the chat it was asked in, and it is asked again in the one you look at.
+
+`/sentinel` sets it from the chat - `/sentinel ask`, `/sentinel on`, `/sentinel off`, or `/sentinel` alone to pick - written to `config.turri.yaml` as `/turri-config sentinel` does.
 
 ## What you see
 
 - **In the chat you are in**, a pulse that finishes shows as it always has - `✓ app · regenerate pulse 3 finished after 4m 10s`, and for one that went wrong, where to see why. A pulse that landed is told to the chat's agent, which tells you in a line or two what landed and what the sentinel is doing with it - and again, in a line, when the sentinel is done with it - checking it, testing what was released - and does nothing else about it: it does not test, release or open it, nor do what the project's guidance says to do once a pulse finishes. The pulse is the sentinel's. A pulse that went wrong is not told to it: the sentinel looks into it, and you hear of it as a notice.
-- **The sentinel** opens with the first pulse that finishes - in the background: it never takes the screen, and you stay in your chat. It is a tab in the strip like any other chat - `sentinel` - marked while it works and when it has something new. Switch to it to read what it checked.
+- **The sentinel** opens with the first pulse that finishes - once you said to start it, under `sentinel: ask` - in the background: it never takes the screen, and you stay in your chat. It is a tab in the strip like any other chat - `sentinel` - marked while it works and when it has something new. Switch to it to read what it checked.
 - **A notice**, when something needs you: a card in the chat you are in - what is wrong, what shows it, and what can be done, numbered - and, in the terminal, once that chat is not mid-turn, a dialog on it:
   - `enter` on an action accepts it: the chat's agent is started on it - a change to the \*\*\*plain, a pulse regenerated again, a credential to provide, a setting to change;
   - **Say what to do instead…** - your own words, and the agent does that;
@@ -37,7 +50,7 @@ Switch to its chat and say how to check your software - *test the sign-up flow a
 
 ## Closing it
 
-It closes like any chat (`/chat close`, `alt+w`, a host's `closeChat`), and that does not turn it off: the next pulse that finishes opens it again, with a fresh conversation - and your guidance. `turri --continue` reopens it with the other chats, as it was. `sentinel: false` - in `config.turri.yaml`, or with `/turri-config` - turns it off: from the next pulse that finishes, a pulse is told to the chat that asked for it, whose agent reacts to it, as without one.
+It closes like any chat (`/chat close`, `alt+w`, a host's `closeChat`), and that does not turn it off: the next pulse that finishes opens it again, with a fresh conversation - and your guidance. `turri --continue` reopens it with the other chats, as it was. `sentinel: false` - in `config.turri.yaml`, or with `/sentinel off` or `/turri-config` - turns it off: from the next pulse that finishes, a pulse is told to the chat that asked for it, whose agent reacts to it, as without one.
 
 It has a slot of its own: with it on, you open up to eight chats, and the ninth is the sentinel's, open or not.
 
@@ -47,8 +60,8 @@ The `sentinel` role in `models:` - else the chat's model, `models.chat` else `ha
 
 ## In a host
 
-A host sees the sentinel as one of its chats - `role: "sentinel"` in `chats()` and `onChats` - and never has focus moved to it. Each notice comes as `onNotice(notice)` - `{ id, chat, module, pulse, job, severity, summary, evidence, actions, state }`, `chat` the one to draw it in - and `onNoticeOver(notice)` when it is answered or superseded; `notices()` lists those open. `answer(id, { action } | { steer } | { dismiss: true })` answers one, as the terminal's dialog does. `onConcluded({ job, verdict: "holds" | "wrong", summary, module, pulse, chat })` comes as it is done with a pulse, all well or not - told to the chat `chat` too. The sentinel's own tools - a browser - are given with `createTurri({ sentinel: { tools } })`, and it is told it has them. `sentinel: { surface }` says, in the host's words, where the person watches it use them: then it tries a release with them, where the person can watch, and keeps its shell for what they cannot show - logs, exit codes, files. Without it, the person does not watch the sentinel, and the host's tools are only to test with as well. See [running turri in a host](hosting.md#the-sentinel).
+A host sees the sentinel as one of its chats - `role: "sentinel"` in `chats()` and `onChats` - and never has focus moved to it. Under `sentinel: ask`, the question before it first opens comes as a notice like the others, with `kind: "sentinel-start"`, its actions the four answers: `answer(id, { action })` answers it - by index or label - and `{ dismiss: true }` is not this session. Each notice comes as `onNotice(notice)` - `{ id, chat, module, pulse, job, severity, summary, evidence, actions, state }`, `chat` the one to draw it in - and `onNoticeOver(notice)` when it is answered or superseded; `notices()` lists those open. `answer(id, { action } | { steer } | { dismiss: true })` answers one, as the terminal's dialog does. `onConcluded({ job, verdict: "holds" | "wrong", summary, module, pulse, chat })` comes as it is done with a pulse, all well or not - told to the chat `chat` too. The sentinel's own tools - a browser - are given with `createTurri({ sentinel: { tools } })`, and it is told it has them. `sentinel: { surface }` says, in the host's words, where the person watches it use them: then it tries a release with them, where the person can watch, and keeps its shell for what they cannot show - logs, exit codes, files. Without it, the person does not watch the sentinel, and the host's tools are only to test with as well. See [running turri in a host](hosting.md#the-sentinel).
 
 ## In the ledger
 
-`chat.opened` carries `role: "sentinel"` for its chat; `notice.put` and `notice.over` record each notice - its severity and module, and how it ended: `accepted`, `steered`, `dismissed`, `superseded` - and `sentinel.concluded` each pulse it is done with, `holds` or `wrong`.
+`chat.opened` carries `role: "sentinel"` for its chat; `notice.put` and `notice.over` record each notice - the question before it opens among them - - its severity and module, and how it ended: `accepted`, `steered`, `dismissed`, `superseded` - and `sentinel.concluded` each pulse it is done with, `holds` or `wrong`.

package/docs/using.md

@@ -81,6 +81,7 @@ A regeneration takes minutes, so in the TUI every tool that regenerates starts t
   `ctrl+h` again, or `esc`, closes it and goes back to the chat. Beside the chat, one side has the keys and the other is drawn faint: `ctrl+h` switches sides - from the chat to the panel, from the panel to the chat, the panel staying and following the pulses - `esc` gives the chat the keys too, and a click gives them to the side clicked. `ctrl+c` closes the panel; so do `s`, over the whole screen, then `esc`. ([pi](https://pi.dev)'s regular screen, `--tui-mode regular`, reads no mouse: there it is the keys alone.) While the panel has the keys, every key is the panel's, whatever else happens: a question the chat model asks in the background (`ask_user`) waits in the chat, unanswered - an `enter` in the panel never answers it - and the panel's top line says "the chat is waiting for your answer". Back in the chat, the question is there, with the keys.
 - `turri` runs [pi](https://pi.dev) in fullscreen mode, so the conversation stays where you scroll it while the pulses redraw (PgUp/PgDn, the wheel); `--tui-mode regular` goes back to the terminal's own scrollback.
 - **`/turri-config`** changes a setting of the project's `config.turri.yaml` - the models, review, conformance tests, any key - and says when it takes effect: now, at your next message, or at the next pulse; never only after a restart. See [changing it from the chat](config.md#changing-it-from-the-chat).
+- **`/sentinel`** says whether the [sentinel](sentinel.md) checks every pulse that finishes: `ask` - you are asked before it first opens in a session - `on`, or `off`; written to `config.turri.yaml`.
 - **`/stack`** chooses the stack everything is built with from then on, in a project whose parts are on different stacks: a list of the project's stacks, or `/stack backend`, `/stack none`. The stack's `config.turri.<stack>.yaml` is laid over `config.turri.yaml` - its testing scripts, toolchains, models - for the session; a module already asked for keeps the stack it was asked for with. The chat model switches it too when you ask - and, to build one part, passes that part's stack to `regenerate` instead, leaving the session's as it is. See [stacks](config.md#stacks).
 - **`/regenerate [module | file.plain] [functionality ...] [from scratch [whole chain]] [how to cut the work]`** regenerates a module from its \*\*\*plain as it is now, as the `regenerate` tool does: what is left to regenerate is planned into pulses - one functional spec at a time, a few together or the whole module in one, as the planner judges - and the first starts. Words after the module are guidance for that plan (`/regenerate app models first`). A module's name typed with spaces for its underscores is that module - `/regenerate d365_function executor` is `d365_function_executor`. With no module named: the one `module:` in `config.turri.yaml` names, else the folder's top modules, to pick from. Asked for from scratch - `from scratch`, `start over`, `delete the module` - it starts at once, with nothing to confirm: it deletes the module's code and conformance tests in every codebase where they live, committed so `/lineage` keeps them, and regenerates the whole module from its \*\*\*plain, built though nothing in it changed: `/regenerate shorty from scratch`. The modules below it keep their code, and the module starts again from a copy of the code below it. Asked for its chain too - `/regenerate shorty from scratch, the whole chain` - the code of every module of its requires chain is deleted, the base's included, and the whole chain is regenerated from the bottom: what to do after modules were split, merged or moved, when the code below was laid out for modules that are no more. The chat's `regenerate` does the same with `from_scratch: "module"` or `"chain"`, when you ask for it; `turri regenerate --from-scratch` or `--from-scratch-chain` on the command line, not with `--dry-run`. Functionalities named after the module - `/regenerate shorty 3 5` - are regenerated though their \*\*\*plain did not change, on the model chosen for functionalities: as `turri regenerate shorty.plain 3 5` does, and the chat's `regenerate` with `functionalities`.
 - **`/halt <id>`** halts a pulse - a queued one never starts - **`/halt <module>`** (or a planned row's id) halts a module's planned pulses until you ask for it again, a \*\*\*plain change not starting it, and **`/halt activated <name>`** halts a server `activate` started; it lists all three when no id is given.

package/genome/rules/turri-regeneration.md

@@ -43,7 +43,7 @@ The other rules say what a spec means. This one says what turri does with a chan
 - In order of cost: change the spec where it is wrong or silent; regenerate the functional specs whose code went bad again, by name; regenerate the module from scratch, or its whole chain - only when the person asks for it or agrees to it
 - Pulses regenerate in the background: the spec can be changed while they run, and need not wait for them. A change inside what a running pulse regenerates steers it; the rest is planned again around it
 - A pulse that does not land is rolled back whole - code, tests and record together - and its module waits until the spec changes or the module is asked for again. Running it again unchanged usually ends the same way: look at why it did not land first
-- A finished pulse goes to the sentinel, a chat of turri's own - unless `sentinel: false`: it checks the pulse, tests what was released, and puts what is wrong to the person as a notice with what can be done. A pulse that landed is told to the chat the person is in too, only to say it landed and what the sentinel does with it, and when the sentinel is done with a pulse, what it found - the chat does nothing else about either; a pulse that went wrong is not told to it - the chat's agent is given a notice's task once the person accepts it, and does that
+- A finished pulse goes to the sentinel, a chat of turri's own - unless `sentinel: false`; under `sentinel: ask`, the default, only once the person said to start it, asked by turri before it first opens in a session (declined, a pulse goes to the chat that asked for it, as with `false`): it checks the pulse, tests what was released, and puts what is wrong to the person as a notice with what can be done. A pulse that landed is told to the chat the person is in too, only to say it landed and what the sentinel does with it, and when the sentinel is done with a pulse, what it found - the chat does nothing else about either; a pulse that went wrong is not told to it - the chat's agent is given a notice's task once the person accepts it, and does that
 
 ## Where the cost is
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.25-next.fb3566e",
+  "version": "0.1.26-next.2fc445f",
   "license": "MIT",
   "type": "module",
   "repository": {