strom-research 1.1.0 → 1.2.0

package/dist/commands/session.js

@@ -9,7 +9,7 @@ import path from "node:path";
 import { register } from "../cli/registry.js";
 import { ui } from "../cli/ui.js";
 import { lines, table, truncate } from "../cli/format.js";
-import { UsageError, StromError } from "../core/errors.js";
+import { NeedsConsentError, UsageError, StromError } from "../core/errors.js";
 import { closeSession, currentSession, openSessions, othersAtWork, sessionNote, startSession } from "../core/session.js";
 import { buildBrief } from "../brief/brief.js";
 import { DEFAULT_BUDGET, DEFAULT_RUN_MINUTES, Settings } from "../core/config.js";
@@ -25,8 +25,10 @@ import { syncAgentFiles } from "../agents/files.js";
 import { setTreeSetting } from "./setup.js";
 import { RUNNERS } from "../runners/index.js";
 import { PROFILES } from "../agents/profiles.js";
-import { AGENTS, detectAgent, which } from "../core/which.js";
+import { AGENTS, detectAgent, isAgent, which } from "../core/which.js";
+import { askGate, ensureGatesDir, loadGate } from "../core/gate.js";
 import { keepAwake } from "../core/awake.js";
+import { deadlineOf, WRAP_UP_MS } from "../core/clock.js";
 import { stromLauncher } from "../core/self.js";
 import { phrase } from "../core/phrases.js";
 import { enterWorker, runAlive, runsAtWork } from "../core/workers.js";
@@ -161,7 +163,7 @@ register({
     tree: true,
     run(ctx) {
         const all = ctx.tree().list("session").slice().reverse();
-        const cost = (s) => (s.metrics?.costUsd !== undefined ? `$${s.metrics.costUsd.toFixed(2)}` : "");
+        const cost = (s) => costText(s.metrics);
         return {
             text: all.length ? table(all.map((s) => [s.id, s.state, s.task ?? "", s.started.slice(0, 16).replace("T", " "), cost(s), truncate(s.summary ?? "", 70)])) : "no sessions yet → strom session start",
             data: { sessions: all },
@@ -186,7 +188,7 @@ register({
                     m.inputTokens && `${m.inputTokens} in`,
                     m.outputTokens && `${m.outputTokens} out`,
                     m.cacheReadTokens && `${m.cacheReadTokens} cache read`,
-                    m.costUsd !== undefined && `$${m.costUsd.toFixed(2)}`,
+                    costText(m),
                     s.ended && `${Math.max(1, Math.round((Date.parse(s.ended) - Date.parse(s.started)) / 60000))} min`,
                     m.denied && `${m.denied} refused by permissions`,
                 ]
@@ -210,7 +212,7 @@ register({
         const tree = ctx.tree();
         const s = currentSession(tree, ctx.env);
         const task = args[0] ? requireRecord(tree, args[0], "task") : s?.task ? tree.get(s.task) : taskQueue(tree, { strategy: ctx.settings.strategy(tree.config) })[0];
-        const b = buildBrief(tree, { ...(task ? { task } : {}), ...(s ? { session: s } : {}), budget: ctx.settings.number("brief.budget", tree.config, DEFAULT_BUDGET), shared: ctx.settings.shared()?.value });
+        const b = buildBrief(tree, { ...(task ? { task } : {}), ...(s ? { session: s, deadline: deadlineOf(ctx.env) } : {}), budget: ctx.settings.number("brief.budget", tree.config, DEFAULT_BUDGET), shared: ctx.settings.shared()?.value });
         if (opts.stats)
             return {
                 text: lines(table(b.sections.map((x) => [x.name, `${x.tokens}`, x.cut ? "cut" : ""])), `total ~${b.total} tokens of ${b.budget}`),
@@ -381,20 +383,30 @@ register({
     description: "One session by default; with --until, session after session until that time. The agent works headless with\n" +
         "the tree's permissions (anything else is denied), or with the terminal (--interactive). Stops at the\n" +
         "subscription limit, when the queue is empty, or at --until (a session already running finishes, within\n" +
-        "--minutes). A session longer than --minutes is stopped (its task goes back to the queue); a task that comes\n" +
-        "back twice in a row with nothing recorded is parked. --task picks the tasks (one session each, in that order;\n" +
-        "one done or held by another agent meanwhile is left out). Arguments after -- go to the agent CLI unchanged.",
+        "--minutes). The agent knows when its session is stopped (the brief; strom's output counts down its last\n" +
+        "10 minutes, a short session its last quarter); at --minutes it is stopped, and Claude Code, Codex and OpenCode\n" +
+        "get 5 minutes more to write down what they found and close (an unfinished task goes back to the queue); a task\n" +
+        "that comes back twice in a row with nothing recorded is parked. --task picks the tasks (one session each, in that order;\n" +
+        "one done or held by another agent meanwhile is left out). --loop: session after session for as long as there\n" +
+        "is work. A gate (setting run.gate, or --gate; plugins/gates/<name>) is asked before each session of --loop and\n" +
+        "--until: go on, wait (the run waits and asks again) or stop — the user's condition, e.g. the subscription's room\n" +
+        "(strom gate list). Tasks started otherwise (one, --max, --task) are the user's choice: the gate is asked once,\n" +
+        "and when it would not start, the user is asked whether to start anyway (an agent: a window of the system).\n" +
+        "Arguments after -- go to the agent CLI unchanged.",
     options: [
         { name: "task", type: "string", multiple: true, value: "<T…>", description: "work on these tasks, in this order (repeatable or T0003,T0007; default: the next one of the queue)" },
         { name: "research", type: "string", value: "<G…>", description: "only tasks of this research" },
         { name: "max", type: "string", value: "<n>", description: "at most n sessions (default 1; with --until, no limit)" },
         { name: "until", type: "string", value: "<HH:MM>", description: "start no session after this time" },
+        { name: "loop", type: "boolean", description: "session after session for as long as there is work (and the gate lets it)" },
+        { name: "gate", type: "string", value: "<name [n]>", description: 'ask this gate before each session, with what it is given, e.g. "claude-usage 20" (default: run.gate)' },
+        { name: "no-gate", type: "boolean", description: "ask no gate this time (only you: an agent cannot)" },
         { name: "minutes", type: "string", value: "<n>", description: `time limit of one session (default: run.minutes, ${DEFAULT_RUN_MINUTES})` },
         { name: "budget", type: "string", value: "<tokens>", description: `brief size (default: brief.budget, ${DEFAULT_BUDGET})` },
         { name: "model", type: "string", value: "<model>", description: "model of the main agent (default: model.lead)" },
         { name: "interactive", type: "boolean", description: "give the agent the terminal (you can talk to it)" },
     ],
-    examples: ["strom run", "strom run --max 3 --until 23:00", "strom run --task T0003,T0007", "strom run --interactive", "strom run --agent codex", "strom run --minutes 30 -- --add-dir ~/Scans"],
+    examples: ["strom run", "strom run --max 3 --until 23:00", "strom run --loop", "strom run --task T0003,T0007", "strom run --interactive", "strom run --agent codex", "strom run --minutes 30 -- --add-dir ~/Scans"],
     run: async (ctx, { opts, extra }) => {
         const root = ctx.tree().root;
         const treeCfg = ctx.tree().config;
@@ -408,10 +420,11 @@ register({
         const until = parseUntil(opts.until);
         // Tasks the user picked: one session each, in their order (then the queue, when --max asks for more).
         const picked = csvOpt(opts.task).map((id) => requireRecord(Tree.open(root, ctx.env), id, "task").id);
-        const max = opts.max === undefined ? (picked.length ? picked.length : until ? Infinity : 1) : Number(opts.max);
+        const max = opts.max === undefined ? (picked.length ? picked.length : until || opts.loop ? Infinity : 1) : Number(opts.max);
         if (max !== Infinity && (!Number.isInteger(max) || max < 1))
             throw new UsageError("--max must be a positive number");
         const minutes = ctx.settings.number("run.minutes", treeCfg, DEFAULT_RUN_MINUTES);
+        const gate = runGate(ctx, opts);
         const budget = ctx.settings.number("brief.budget", treeCfg, DEFAULT_BUDGET);
         // Each run has a name of its own (as a conversation does): several work side by side, never on one task.
         const worker = `run-${process.pid}-${Date.now().toString(36)}`;
@@ -419,10 +432,12 @@ register({
         // Present in the tree for the others at work (conversations with agents): strom shows who works.
         const beside = runsAtWork(root);
         const leave = enterWorker(root, worker, `${PROFILES[runnerId]?.name ?? runnerId} on its own`);
-        const stopAwake = keepAwake(ctx.env);
+        let stopAwake = keepAwake(ctx.env);
         // Progress goes to stderr when stdout carries JSON.
         const out = (s) => (ctx.json ? ctx.io.stderr : ctx.io.stdout)(s + "\n");
         const report = [];
+        // What the gate answered, for the record of the run.
+        const gates = [];
         // Why the run stopped: a code for the exit status and for data, words for the user (their language).
         const lang = Tree.open(root, runEnv).lang;
         let stopCode = "done";
@@ -466,6 +481,12 @@ register({
                 out(ui(lang, "ui.run.browser.model", { model: models.lead }));
             if (permissions === "full")
                 out(ui(lang, "ui.run.full"));
+            // The gate holds a run that goes on by itself (--loop, --until). Tasks the user starts themselves (one, --max n,
+            // --task) are their choice: the gate is asked once, and when it would not start, the user decides.
+            const gateHolds = Boolean(opts.loop || until);
+            let gateAnswered = false;
+            if (gate)
+                out(ui(lang, gateHolds ? "ui.run.gate" : "ui.run.gate.once", { name: gate.manifest.title ?? gate.name }));
             for (let i = 0; i < max; i++) {
                 if (stop.signal.aborted) {
                     stopCode = "user";
@@ -500,9 +521,49 @@ register({
                     stopCode = "empty";
                     break;
                 }
+                // The user's condition, between sessions only: go on, wait and ask again, or stop — in a run that goes on by
+                // itself. Tasks the user started themselves: asked once, and the user decides when it would not start.
+                if (gate && !gateAnswered) {
+                    const said = askGate(gate, runEnv, { tree: root, lang, agent: runnerId, model: models.lead, sessions: report.length, costUsd: report.reduce((a, r) => a + (r.costUsd ?? 0), 0), nextTask: task.id });
+                    const answer = { at: new Date().toISOString(), verdict: said.verdict, ...(said.reason ? { reason: said.reason } : {}) };
+                    gates.push(answer);
+                    const name = gate.manifest.title ?? gate.name;
+                    if (!gateHolds) {
+                        gateAnswered = true;
+                        if (said.verdict !== "go") {
+                            if (!(await startAnyway(ctx, name, gateReason(said, lang), lang))) {
+                                stopCode = "gate.declined";
+                                stopValues = { name, reason: gateReason(said, lang) };
+                                break;
+                            }
+                            answer.anyway = true;
+                        }
+                    }
+                    else if (said.verdict === "stop" || said.verdict === "error") {
+                        stopCode = said.verdict === "stop" ? "gate" : "gate.error";
+                        stopValues = { name, reason: said.reason ?? "" };
+                        break;
+                    }
+                    else if (said.verdict === "wait") {
+                        const at = Date.now() + said.waitMs;
+                        if (until && at > until) {
+                            stopCode = "time";
+                            break;
+                        }
+                        out(ui(lang, "ui.run.gate.wait", { at: new Date(at).toLocaleString(lang, { weekday: "short", hour: "2-digit", minute: "2-digit" }), reason: said.reason ?? "" }));
+                        // nothing to do meanwhile: the computer may sleep
+                        stopAwake();
+                        await pause(at - Date.now(), stop.signal);
+                        stopAwake = keepAwake(ctx.env);
+                        i--; // this was no session: ask again, with the queue as it is then
+                        continue;
+                    }
+                }
                 const session = startSession(tree, { task, ...(research ? { research: research.id } : {}), runner: runnerId, ...(models.lead ? { model: models.lead } : {}) });
                 commitNow(tree, `${session.id} session started on ${task.id}`);
-                const brief = buildBrief(tree, { task, session, budget, shared: ctx.settings.shared()?.value });
+                // When the agent is stopped: it knows (the brief, strom's reminders near the end), and gets a few minutes more to write down what it found.
+                const deadline = Date.now() + minutes * 60_000;
+                const brief = buildBrief(tree, { task, session, budget, shared: ctx.settings.shared()?.value, deadline });
                 const briefFile = path.join(root, ".strom", "briefs", `${session.id}.md`);
                 fs.mkdirSync(path.dirname(briefFile), { recursive: true });
                 fs.writeFileSync(briefFile, brief.text);
@@ -514,6 +575,8 @@ register({
                 const env = {
                     ...prependPath(runEnv, bin),
                     STROM_SESSION: session.id,
+                    STROM_DEADLINE: new Date(deadline).toISOString(),
+                    STROM_MINUTES: String(minutes),
                     ...(opts.interactive ? {} : { STROM_NONINTERACTIVE: "1" }),
                 };
                 const result = await runner.run({
@@ -525,6 +588,12 @@ register({
                     name: ["Strom", tree.config.name, tree.get(task.research ?? research?.id ?? "")?.name, `${truncate(task.what, 50)} (${task.id})`].filter(Boolean).join(" · "),
                     logFile: path.join(root, ".strom", "runs", `${session.id}.log`),
                     timeoutMs: minutes * 60_000,
+                    wrapUp: {
+                        ms: WRAP_UP_MS,
+                        prompt: `Time is up: strom stopped you at the session's limit (${minutes} min). You have ${WRAP_UP_MS / 60_000} minutes, no more. Do not open anything new: ` +
+                            "record in strom what you found and have not recorded yet (facts, sources, the images searched, in vain too), " +
+                            `then \`strom session close --continue --summary "…" --next "exactly where you stopped"\` (or finish the task, if it is done).`,
+                    },
                     settingsFile: path.join(root, ".claude", "settings.json"),
                     shared: ctx.settings.shared()?.value,
                     ...(models.lead ? { model: models.lead } : {}),
@@ -567,7 +636,7 @@ register({
                 const geds = writeGedcoms(ctx, after);
                 const committed = commitNow(after, `${s.id} ${s.state}: ${truncate(s.summary ?? "", 60)} · ${geds.map((g) => after.relative(g.file)).join(", ")}`);
                 report.push({ session: s.id, task: task.id, outcome: result.outcome, ...(s.summary ? { summary: s.summary } : {}), ...(result.metrics.costUsd !== undefined ? { costUsd: result.metrics.costUsd } : {}) });
-                out(`■ ${s.id} ${s.state} · ${result.outcome}${result.metrics.costUsd !== undefined ? ` · $${result.metrics.costUsd.toFixed(2)}` : ""}${s.summary ? ` · ${truncate(s.summary, 80)}` : ""}`);
+                out(`■ ${s.id} ${s.state} · ${result.outcome}${costText(result.metrics) ? ` · ${costText(result.metrics)}` : ""}${s.summary ? ` · ${truncate(s.summary, 80)}` : ""}`);
                 if (result.denied?.length)
                     out(ui(lang, "ui.run.denied", { n: result.denied.length, what: result.denied.slice(0, 3).join(" · ") }));
                 if (!committed) {
@@ -611,11 +680,79 @@ register({
         const reason = ui(lang, `ui.run.stop.${stopCode}`, stopValues);
         return {
             text: lines(ui(lang, "ui.run.summary", { n: report.length, reason }), waiting ? `\n${waiting}` : undefined),
-            data: { sessions: report, stopped: reason, stop: stopCode },
-            exitCode: ["failed", "problems", "auth", "denied"].includes(stopCode) ? 1 : 0,
+            data: { sessions: report, stopped: reason, stop: stopCode, ...(gate ? { gate: { name: gate.name, answers: gates } } : {}) },
+            exitCode: ["failed", "problems", "auth", "denied", "gate.error"].includes(stopCode) ? 1 : 0,
         };
     },
 });
+/**
+ * The gate this run asks (run.gate, or --gate), or none (--no-gate). Going round the user's gate is the user's
+ * decision: an agent asks them (a window of the system).
+ */
+function runGate(ctx, opts) {
+    const set = ctx.settings.runGate();
+    const asked = typeof opts.gate === "string" ? opts.gate : undefined;
+    if (opts["no-gate"]) {
+        if (set && isAgent(ctx.env))
+            ctx.requireHuman(`Let the agent work on its own without the gate "${set}"?`, "strom run --no-gate", "run.gate", ui(ctx.uiLang(), "ui.consent.gate.skip", { name: set }));
+        return undefined;
+    }
+    const name = asked ?? set;
+    if (!name)
+        return undefined;
+    if (asked && set && asked !== set && isAgent(ctx.env))
+        ctx.requireHuman(`Ask the gate "${asked}" instead of "${set}"?`, `strom run --gate ${asked}`, "run.gate", ui(ctx.uiLang(), "ui.consent.gate.set", { name: asked }));
+    const shared = ctx.settings.shared()?.value;
+    if (!shared)
+        throw new StromError("no shared folder, so no gates", { hint: "strom setup" });
+    ensureGatesDir(shared);
+    return loadGate(shared, name);
+}
+/** Why the gate would not start, for the user: its own words, else what it answered. */
+function gateReason(said, lang) {
+    return said.reason ?? ui(lang, said.verdict === "error" ? "ui.run.gate.noanswer" : said.verdict === "wait" ? "ui.run.gate.later" : "ui.run.gate.no");
+}
+/**
+ * Tasks the user started themselves while the gate would not start: the user decides — on a terminal, a question;
+ * asked by an agent, a window of the system (going round the user's condition is never the agent's decision). A run
+ * nobody can ask keeps to the gate.
+ */
+async function startAnyway(ctx, name, reason, lang) {
+    const question = ui(lang, "ui.run.gate.anyway", { name, reason });
+    if (ctx.interactive && !isAgent(ctx.env))
+        return ctx.confirm(question, false);
+    if (!isAgent(ctx.env))
+        return false;
+    try {
+        ctx.requireHuman(`Start the tasks although the condition "${name}" would not (${reason})?`, "strom run --no-gate", "run.gate", question);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof NeedsConsentError)
+            throw err; // nobody to ask: the user runs it themselves
+        return false; // the user said no in the window
+    }
+}
+/** Wait, until the time or until the user stops the run. */
+function pause(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted || ms <= 0)
+            return resolve();
+        const t = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(t);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}
+/** What a session cost: "$1.20"; "$0.30+" or "cost unknown" when the agent was stopped before it said. */
+function costText(m) {
+    if (m?.costPartial)
+        return m.costUsd ? `$${m.costUsd.toFixed(2)}+` : "cost unknown";
+    return m?.costUsd !== undefined ? `$${m.costUsd.toFixed(2)}` : "";
+}
 /** How the user clears the agent's context, in the agent's own words. */
 const CLEAR = { claude: "/clear", codex: "/new", opencode: "/new" };
 /** The hint after a session in a conversation: the next task in a fresh context (images stay in a context and are paid on every turn). */

package/dist/commands/setup.js

@@ -30,12 +30,14 @@ import { NeedsInputError, StromError, UsageError } from "../core/errors.js";
 import { check } from "../core/check.js";
 import { assertIntact, verifyFull } from "../core/integrity.js";
 import { ensurePluginsDir } from "../core/connector.js";
+import { ensureGatesDir, loadGate } from "../core/gate.js";
 import { downloadsDir } from "../core/browser.js";
 export const SHARED_DIRS = ["media", "catalog", "tools", "cache", "inbox"];
 export function ensureShared(dir) {
     for (const d of SHARED_DIRS)
         fs.mkdirSync(path.join(dir, d), { recursive: true });
     ensurePluginsDir(dir);
+    ensureGatesDir(dir);
 }
 register({
     path: ["setup"],
@@ -397,6 +399,15 @@ function setUserSetting(ctx, key, value) {
     // Asking before a connector runs is the user's safeguard: only they take it away.
     if (key === "connectors.consent" && value !== "on" && s.connectorsConsent())
         ctx.requireHuman("Let connectors run without asking you first?", `strom config set connectors.consent ${value ?? "off"}`, "connectors.consent", ui(ctx.uiLang(), "ui.consent.connectors.off"));
+    // The gate decides what working alone spends: set and taken away by the user alone.
+    if (key === "run.gate" && value !== s.runGate())
+        ctx.requireHuman(value ? `Let the gate "${value}" decide when the agent working alone goes on?` : `Remove the gate "${s.runGate()}" — the agent working alone no longer asks it?`, value ? `strom config set run.gate ${value}` : "strom config unset run.gate", "run.gate", ui(ctx.uiLang(), value ? "ui.consent.gate.set" : "ui.consent.gate.unset", { name: String(value ?? s.runGate()) }));
+    // a gate that is not there (or not a gate) is said now, not at the next run
+    const sh = s.shared()?.value;
+    if (key === "run.gate" && typeof value === "string" && sh) {
+        ensureGatesDir(sh);
+        loadGate(sh, value);
+    }
     writeStored(s.config, key, s.agent(ctx.hasTree() ? ctx.tree().config : undefined).value, value);
     s.save();
     if (key === "shared" && typeof value === "string")

package/dist/commands/sources.js

@@ -245,6 +245,23 @@ register({
     },
 });
 // ── repositories ───────────────────────────────────────────────────────────
+/** The website's host without "www.", lowercase: https://www.FamilySearch.org/search → familysearch.org. */
+function siteOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`).hostname.toLowerCase().replace(/^www\./, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An archive already here under this name or on this website. */
+export function sameRepository(all, name, url) {
+    const folded = foldText(name);
+    const site = siteOf(url);
+    return all.find((r) => foldText(r.name) === folded || (site !== undefined && siteOf(r.url) === site));
+}
 register({
     path: ["repo", "add"],
     summary: "Add an archive, library or portal that holds records",
@@ -260,10 +277,17 @@ register({
         { name: "terms", type: "string", value: "<text>", description: "terms of use in one sentence (+ link)" },
         { name: "automation", type: "string", value: "<a>", description: "allowed, manual (browser only), forbidden, unknown (default)" },
         { name: "note", type: "string", value: "<text>", description: "short note" },
+        { name: "another", type: "boolean", description: "a different archive, though one here has its name or website" },
     ],
     examples: ['strom repo add "State Archive, online reading room" --country CZ --url https://archive.example.org --automation manual'],
     run(ctx, { args, opts }) {
         const tree = ctx.tree();
+        // One archive, one record: a second "FamilySearch" splits its books, terms and lessons in two (found in a live run).
+        const twin = opts.another ? undefined : sameRepository(tree.list("repository"), args[0], str(opts.url));
+        if (twin)
+            throw new UsageError(`${twin.id} "${twin.name}" is this archive already${twin.url ? ` (${twin.url})` : ""}`, {
+                hint: `use it: --repo ${twin.id} (strom repo show ${twin.id}) — a different archive after all: add --another`,
+            });
         const r = create(tree, "repository", {
             name: args[0].trim(),
             country: str(opts.country)?.toUpperCase(),

package/dist/core/clock.js

@@ -0,0 +1,55 @@
+// The session's time. `strom run` stops an agent at its time limit (run.minutes),
+// and what the agent had only in its context is lost then (found in a live run:
+// 25 minutes of reading a census film, nothing written down, all gone). So the
+// agent is told when its session is stopped (STROM_DEADLINE, set by the run; the
+// brief says it), near the end every strom command it runs reminds it, and at
+// the limit an agent that can be resumed gets a few minutes more to write down
+// what it found and close the session (runners: wrapUp).
+/** From how long before the end strom's output reminds the agent (a short session: its last quarter). */
+export const REMIND_MS = 10 * 60_000;
+/** From how long before the end the reminder says to write down and close (a short session: its last eighth). */
+export const CLOSE_MS = 3 * 60_000;
+/** The time an agent stopped at its limit gets to write down what it found. */
+export const WRAP_UP_MS = 5 * 60_000;
+/** When this session is stopped (ms since the epoch), if a run set a limit. */
+export function deadlineOf(env) {
+    const t = Date.parse(env.STROM_DEADLINE ?? "");
+    return Number.isNaN(t) ? undefined : t;
+}
+/** The session's whole time limit (STROM_MINUTES), if the run said it. */
+function limitOf(env) {
+    const m = Number(env.STROM_MINUTES);
+    return m > 0 ? m * 60_000 : undefined;
+}
+/** A time of day as the agent reads it in its brief and in the reminders. */
+export function clockTime(t) {
+    return new Date(t).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });
+}
+/**
+ * The line strom adds to a command's output near the end of the session (none before): first that the time is
+ * getting short (go on, writing down), in the last minutes to write down and close, then that it is up. A short
+ * session is reminded in proportion — a reminder from its first minute would only make the agent give up.
+ */
+export function clockLine(env, now = Date.now()) {
+    const end = deadlineOf(env);
+    if (end === undefined)
+        return undefined;
+    const limit = limitOf(env);
+    const remind = limit ? Math.min(REMIND_MS, limit / 4) : REMIND_MS;
+    const close = limit ? Math.min(CLOSE_MS, limit / 8) : CLOSE_MS;
+    const left = end - now;
+    if (left > remind)
+        return undefined;
+    const min = Math.max(1, Math.ceil(left / 60_000));
+    if (left <= 0)
+        return '⏳ this session\'s time is up: record what you found and close it now: strom session close --continue --summary "…" --next "exactly where you stopped"';
+    if (left <= close)
+        return `⏳ ${min} min left: this session is stopped at ${clockTime(end)}. Record what you have found now (facts, sources, the images searched), then close: strom session close --summary "…" --next "…"`;
+    return `⏳ ${min} min left: this session is stopped at ${clockTime(end)}. Go on, but write each find down as you have it and start nothing you cannot finish by then.`;
+}
+/** What the brief says of the session's time: when, and not to hurry — strom says when it is getting short. */
+export function briefClock(end, now = Date.now()) {
+    return (`Time: this session is stopped at ${clockTime(end)} (it is ${clockTime(now)} now). Do not hurry and do not stop early: strom's output tells you ` +
+        "when the time is getting short; until then work on the task as usual. Write each find and each stretch of images searched into strom the " +
+        "moment you have it: what is only in your context is lost when the session ends.");
+}

package/dist/core/config.js

@@ -39,6 +39,8 @@ export const SETTINGS = [
     })),
     { key: "brief.budget", env: "STROM_BRIEF_BUDGET", tree: true, kind: "number", description: `size of the brief in tokens (default ${DEFAULT_BUDGET})` },
     { key: "run.minutes", env: "STROM_RUN_MINUTES", tree: true, kind: "number", description: `time limit of one \`strom run\` session (default ${DEFAULT_RUN_MINUTES})` },
+    // Read from the config file only, changed by the user alone: the gate decides what working alone spends.
+    { key: "run.gate", env: "", tree: false, kind: "plugin", description: "a condition on the agent working alone: the gate (plugins/gates/<name>) strom asks before each session of strom run — go on, wait or stop; its name, then what it is given (strom gate list; e.g. claude-usage 10: the Claude subscription's daily ration, 10 points in hand) — only you set it" },
     { key: "queue.strategy", env: "STROM_QUEUE_STRATEGY", tree: true, kind: "choice", choices: STRATEGIES, description: "order of the task queue: balanced (default — nearest ancestors first, spread over the lines, nothing taken forever), depth (stay on one line), priority (strict priority)" },
     { key: "gedcom.for", env: "STROM_GEDCOM_FOR", tree: true, kind: "choice", choices: ["both", "standard", "strom"], description: "GEDCOM files written: both (default), standard (any program), strom (the Strom app)" },
     { key: "stories", env: "STROM_STORIES", tree: true, kind: "choice", choices: ["yes", "no"], description: "stories of the ancestors for the family, written from the facts: yes (default — strom proposes one once a person's life is told by records), no — the user is told when the research starts and may say no" },
@@ -73,6 +75,7 @@ const FIELDS = {
     "excerpts.quality": "excerptsQuality",
     "excerpts.for": "excerptsFor",
     "excerpts.mb": "excerptsMb",
+    "run.gate": "runGate",
 };
 /** Environment variables that are not settings but steer strom. */
 export const OTHER_ENV = [
@@ -128,6 +131,11 @@ export function checkValue(def, raw, resolvePath) {
                 throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: def.choices?.join(", ") });
             return c;
         }
+        case "plugin":
+            // its name, then what it is given: "claude-usage 10"
+            if (!/^[a-z0-9][a-z0-9-]*(\s+\S+)*$/.test(v))
+                throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: 'a plugin\'s name (lowercase letters, digits and dashes), then what it is given, e.g. "claude-usage 10"' });
+            return v.split(/\s+/).join(" ");
         case "person":
             if (!/^[Pp]\d{4,}$/.test(v))
                 throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: "a person's ID, e.g. P0009 (strom find <name>)" });
@@ -332,6 +340,10 @@ export class Settings {
         return r ? String(r.value) : undefined;
     }
     /** What the agent may do without asking — from the config file alone, which only the user raises. */
+    /** The gate of working alone, if the user set one (the config file only). */
+    runGate() {
+        return this.config.runGate || undefined;
+    }
     agentPermissions() {
         const v = this.config.agentPermissions ?? "auto";
         return PERMISSION_ALIASES[v] ?? (PERMISSION_LEVELS.includes(v) ? v : "auto");

package/dist/core/gate.js

@@ -0,0 +1,175 @@
+// Gates: a condition the user sets on working alone. Before each session of
+// `strom run` (--loop runs on for as long as there is work) strom asks the
+// gate the user chose (setting run.gate) whether to go on, wait or stop — the
+// subscription's capacity, a budget, the night's tariff: whatever the gate's
+// program decides, strom holds only the interface.
+//
+// A gate is a folder in the plugins folder, <shared>/plugins/gates/<name>/,
+// with gate.json ({"interface": 1, "command": [...]}) and its program; the
+// user may give it arguments after its name (run.gate "claude-usage 10"). The
+// interface (assets/plugins/gates/README.md, copied next to the gates): the
+// program's exit status says it — 0 go on, 1 wait, 2 stop — and one line of
+// JSON on stdout may add why ("reason") and how long to wait ("wait" seconds
+// or "until" a time). Anything else (a crash, no answer in time) stops the
+// run: working alone never spends blind.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { StromError, UsageError } from "./errors.js";
+import { NAME_RE, pluginsDir } from "./connector.js";
+import { readAsset } from "./assets.js";
+export const GATE_INTERFACE = 1;
+const MANIFEST = "gate.json";
+/** How long a gate may think (it may ask a service). */
+const DEFAULT_TIMEOUT_S = 120;
+/** A gate that says wait without saying how long is asked again after this. */
+export const DEFAULT_WAIT_MS = 15 * 60_000;
+/** Never ask again sooner than this (a gate answering "wait 0" must not spin). */
+const MIN_WAIT_MS = 60_000;
+export function gatesDir(shared) {
+    return path.join(pluginsDir(shared), "gates");
+}
+/** The gates folder with strom's own files: the interface and the gates strom ships (refreshed). */
+export function ensureGatesDir(shared) {
+    const dir = gatesDir(shared);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const own = [[path.join(dir, "README.md"), readAsset("plugins", "gates", "README.md")]];
+        for (const name of SHIPPED)
+            for (const f of ["gate.json", "gate.ts"])
+                own.push([path.join(dir, name, f), readAsset("plugins", "gates", name, f)]);
+        for (const [file, text] of own) {
+            if (text === undefined)
+                continue;
+            let old;
+            try {
+                old = fs.readFileSync(file, "utf8");
+            }
+            catch {
+                old = undefined;
+            }
+            if (old === text)
+                continue;
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, text);
+        }
+    }
+    catch (err) {
+        // a folder strom may not write here (an agent's sandbox): the gates there still run
+        if (!["EACCES", "EPERM", "EROFS"].includes(err?.code ?? ""))
+            throw err;
+    }
+    return dir;
+}
+/** Gates strom ships: ready in the gates folder, used only when the user sets run.gate. */
+export const SHIPPED = ["claude-usage"];
+export function listGates(shared) {
+    const dir = gatesDir(shared);
+    let names = [];
+    try {
+        names = fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && NAME_RE.test(d.name)).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.sort()) {
+        try {
+            out.push(loadGate(shared, name));
+        }
+        catch {
+            // not a gate (yet): no gate.json, or one strom cannot read — `strom gate test <name>` says why
+        }
+    }
+    return out;
+}
+/** A gate as the user names it: its name, then what it is given ("claude-usage 10"). */
+export function loadGate(shared, spec) {
+    const [name = "", ...args] = spec.trim().split(/\s+/);
+    if (!NAME_RE.test(name))
+        throw new UsageError(`invalid gate name "${name}"`, { hint: "lowercase letters, digits and dashes, e.g. claude-usage" });
+    const dir = path.join(gatesDir(shared), name);
+    const file = path.join(dir, MANIFEST);
+    if (!fs.existsSync(file))
+        throw new StromError(`no gate "${name}" (no ${file})`, { hint: `the gates here: strom gate list — a gate is a folder in ${gatesDir(shared)} with ${MANIFEST}` });
+    let m;
+    try {
+        m = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new StromError(`gate "${name}": ${MANIFEST} is not valid JSON (${err.message})`);
+    }
+    if (m.interface !== GATE_INTERFACE)
+        throw new StromError(`gate "${name}" is for interface ${m.interface}, this strom knows ${GATE_INTERFACE}`, { hint: m.interface > GATE_INTERFACE ? "update strom: strom update" : `see ${path.join(gatesDir(shared), "README.md")}` });
+    if (!Array.isArray(m.command) || !m.command.length || !m.command.every((c) => typeof c === "string" && c))
+        throw new StromError(`gate "${name}": "command" must be a list of strings, e.g. ["node", "gate.ts"]`);
+    return { name, dir, manifest: m, args };
+}
+/** Ask the gate once. Never throws: a gate that fails answers "error". */
+export function askGate(gate, env, facts) {
+    const [cmd, ...args] = gate.manifest.command;
+    const program = cmd === "node" ? process.execPath : cmd;
+    const timeout = (gate.manifest.timeout ?? DEFAULT_TIMEOUT_S) * 1000;
+    const r = spawnSync(program, [...args, ...gate.args], {
+        cwd: gate.dir,
+        encoding: "utf8",
+        timeout,
+        windowsHide: true,
+        env: {
+            ...env,
+            STROM_GATE: gate.name,
+            STROM_TREE: facts.tree,
+            STROM_LANG: facts.lang,
+            STROM_AGENT: facts.agent,
+            STROM_MODEL: facts.model ?? "",
+            STROM_SESSIONS: String(facts.sessions),
+            STROM_COST_USD: facts.costUsd.toFixed(2),
+            STROM_NEXT_TASK: facts.nextTask ?? "",
+        },
+    });
+    if (r.error) {
+        const timedOut = r.error.code === "ETIMEDOUT";
+        return { verdict: "error", reason: timedOut ? `no answer within ${timeout / 1000} s` : r.error.message };
+    }
+    const said = parseSaid(r.stdout ?? "");
+    const reason = said.reason ?? (r.status !== 0 && r.status !== 1 && r.status !== 2 ? lastLine(r.stderr ?? "") : undefined);
+    switch (r.status) {
+        case 0:
+            return { verdict: "go", ...(reason ? { reason } : {}) };
+        case 1:
+            return { verdict: "wait", ...(reason ? { reason } : {}), waitMs: Math.max(MIN_WAIT_MS, said.waitMs ?? DEFAULT_WAIT_MS) };
+        case 2:
+            return { verdict: "stop", ...(reason ? { reason } : {}) };
+        default:
+            return { verdict: "error", reason: reason ?? (r.signal ? `ended by ${r.signal}` : `exit status ${r.status}`) };
+    }
+}
+/** The last line of JSON the gate printed: {"reason", "wait" (seconds) | "until" (a time)}; plain text is the reason. */
+function parseSaid(stdout) {
+    const line = lastLine(stdout);
+    if (!line)
+        return {};
+    if (!line.startsWith("{"))
+        return { reason: line.slice(0, 300) };
+    try {
+        const j = JSON.parse(line);
+        const out = {};
+        if (typeof j.reason === "string" && j.reason.trim())
+            out.reason = j.reason.trim().slice(0, 300);
+        if (typeof j.wait === "number" && Number.isFinite(j.wait) && j.wait >= 0)
+            out.waitMs = j.wait * 1000;
+        else if (typeof j.until === "string" && !Number.isNaN(Date.parse(j.until)))
+            out.waitMs = Date.parse(j.until) - Date.now();
+        return out;
+    }
+    catch {
+        return { reason: line.slice(0, 300) };
+    }
+}
+function lastLine(s) {
+    return s
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .pop();
+}

package/dist/core/overview.js

@@ -72,6 +72,8 @@ export function treeStats(tree, from) {
         if (!stats.sessions.last || at > stats.sessions.last)
             stats.sessions.last = at;
         cost += s.metrics?.costUsd ?? 0;
+        if (s.metrics?.costPartial)
+            stats.sessions.costPartial = (stats.sessions.costPartial ?? 0) + 1;
     }
     if (cost > 0)
         stats.sessions.costUsd = Math.round(cost * 100) / 100;