strom-research 1.7.0 → 1.9.0

package/dist/commands/session.js

@@ -5,20 +5,24 @@
 // closes what the agent left open, exports the GEDCOM and commits. Between
 // sessions not a single token is spent.
 import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 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 { NeedsConsentError, UsageError, StromError } from "../core/errors.js";
 import { closeSession, currentSession, openSessions, othersAtWork, sessionNote, startSession } from "../core/session.js";
+import { reviveLive } from "../core/live.js";
 import { buildBrief } from "../brief/brief.js";
 import { DEFAULT_BUDGET, DEFAULT_RUN_MINUTES, Settings } from "../core/config.js";
 import { prependPath } from "../runners/runner.js";
 import { frontier } from "../core/frontier.js";
+import { treeEdges } from "../core/edge.js";
+import { label, parentsOf, resolvePerson } from "../core/people.js";
 import { storyProposals } from "../core/stories.js";
 import { OFF_MAP_HOW, offMapLine, placesOffMap } from "../core/places.js";
 import { create, csvOpt, requireRecord, update } from "../core/records.js";
-import { taskQueue, waitingLines } from "./tasks.js";
+import { offTreeLine, taskQueue, waitingLines } from "./tasks.js";
 import { resolveResearch } from "./research.js";
 import { writeGedcoms } from "./output.js";
 import { syncAgentFiles } from "../agents/files.js";
@@ -28,15 +32,16 @@ import { PROFILES } from "../agents/profiles.js";
 import { AGENTS, detectAgent, isAgent, which, withoutAgentMarks } 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 { askFinish, deadlineOf, finishAsked, WRAP_UP_MS } from "../core/clock.js";
+import { OWN_GROUP } from "../runners/runner.js";
 import { stromLauncher } from "../core/self.js";
 import { phrase } from "../core/phrases.js";
-import { enterWorker, runAlive, runsAtWork } from "../core/workers.js";
+import { enterWorker, markPaused, runAlive, runsAtWork } from "../core/workers.js";
 import { assertIntact, snapshot, verifyFast } from "../core/integrity.js";
 import { guard } from "../core/guard.js";
 import { hasErrors } from "../core/check.js";
 import { Tree } from "../core/tree.js";
-import { treeBrowserConnectors } from "../core/connector.js";
+import { agentBrowser, treeBrowserConnectors } from "../core/connector.js";
 import { browserNote } from "./connectors.js";
 import { reviewProposals } from "../core/review.js";
 function written(tree) {
@@ -70,6 +75,9 @@ export function researchProposals(tree, research) {
 }
 /** Create the tasks strom proposes for a research; returns their IDs. */
 export function applyFrontier(tree, research) {
+    // a direction paused or ended proposes nothing (resumed: what it would, at once)
+    if (research.state !== "active")
+        return [];
     return researchProposals(tree, research).map(({ proposal, kind }) => create(tree, "task", { ...proposal, state: "open" }, (id) => `+${id} task "${truncate(proposal.what, 60)}" (${kind})`).id);
 }
 /** Commit behind the same gate as every write. */
@@ -102,8 +110,11 @@ register({
         if (task && !["open", "doing", "parked"].includes(task.state))
             throw new UsageError(`${task.id} is ${task.state}`);
         const s = startSession(tree, { ...(task ? { task } : {}), ...(research ? { research: research.id } : {}) });
+        reviveLive(tree.root, ctx.env);
         const brief = buildBrief(tree, { ...(task ? { task } : {}), session: s, budget: ctx.settings.number("brief.budget", tree.config, DEFAULT_BUDGET), shared: ctx.settings.shared()?.value });
-        return { text: lines(written(tree), "", brief.text), data: { session: s, brief: brief.text, sections: brief.sections } };
+        // a task the queue holds back, started by its ID: the agent hears why before it begins
+        const off = task && args[0] ? offTreeLine(tree, task, true) : undefined;
+        return { text: lines(written(tree), off, "", brief.text), data: { session: s, brief: brief.text, sections: brief.sections, ...(off ? { offTree: true } : {}) } };
     },
 }, {
     path: ["session", "note"],
@@ -120,6 +131,30 @@ register({
         sessionNote(tree, s, args[0]);
         return { text: written(tree) };
     },
+}, {
+    path: ["session", "finish"],
+    summary: "Ask a session at work to finish now: its agent writes down what it found and closes it",
+    group: "research",
+    tree: true,
+    description: "For the user: a session of strom run (or a conversation) is told, from the next strom command its agent runs, to\n" +
+        "start nothing new, record what it has and close the session (the task back to the queue when unfinished).\n" +
+        "Nothing is stopped by force; the run it belongs to stops after it (as at the first Ctrl-C in its terminal).",
+    args: [{ name: "session", description: "session ID (default: the one open session)" }],
+    examples: ["strom session finish", "strom session finish N0001"],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const lang = tree.lang;
+        const open = openSessions(tree);
+        const s = args[0] ? requireRecord(tree, args[0], "session") : open.length === 1 ? open[0] : undefined;
+        if (!s && !open.length)
+            throw new UsageError(ui(lang, "ui.session.finish.none"), { hint: "strom session list" });
+        if (!s)
+            throw new UsageError(ui(lang, "ui.session.finish.which", { sessions: open.map((x) => x.id).join(", ") }), { hint: `strom session finish ${open[0].id}` });
+        if (s.state !== "open")
+            throw new UsageError(ui(lang, "ui.session.finish.closed", { session: s.id }), { hint: "strom session list" });
+        askFinish(tree.root, s.id, ctx.env.STROM_WORKER ?? "user");
+        return { text: ui(lang, "ui.session.finish.done", { session: s.id, task: s.task ?? "–" }), data: { session: s.id, task: s.task ?? null, asked: true } };
+    },
 }, {
     path: ["session", "close"],
     summary: "Finish the session: summary, next step; exports the GEDCOM and fills the task queue",
@@ -261,7 +296,132 @@ register({
             data: { frontier: items.map((i) => ({ person: i.person.id, generation: i.generation, reason: i.reason, coveredBy: i.coveredBy, proposal: i.proposal, exhausted: i.exhausted })), stories },
         };
     },
+}, {
+    path: ["edge"],
+    summary: "Where the tree ends: above whom it does not go on, why (what the records say so far) and what comes next — what the Strom app shows on those cards",
+    group: "tasks",
+    tree: true,
+    args: [{ name: "person", description: "whose edge in full: ID (P0001) or name (default: every edge the research reaches)", variadic: true }],
+    options: [{ name: "all", type: "boolean", description: "also the edges no direction reaches: family outside the directions, people off the tree" }],
+    examples: ["strom edge", "strom edge P0001", "strom edge --all --json"],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const { edges, islands } = treeEdges(tree);
+        const who = (id) => {
+            const p = tree.get(id);
+            return p ? label(p) : id;
+        };
+        if (args.length) {
+            const people = args.map((a) => resolvePerson(tree, a));
+            const out = [];
+            for (const p of people) {
+                const e = edges.get(p.id);
+                const isle = islands.get(p.id);
+                if (out.length)
+                    out.push("");
+                if (!e)
+                    out.push(`${label(p)} — ${parentsOf(tree, p.id).length === 2 ? "the tree goes on above: a record proves the parents" : "nothing the research knows of the edge above yet (no direction reaches them, no work on it)"}`);
+                else
+                    out.push(...edgeLines(tree, e, who));
+                if (isle)
+                    out.push(islandLine(isle, who));
+            }
+            const data = people.map((p) => ({ person: p.id, edge: edges.get(p.id) ?? null, island: islands.get(p.id) ? { ...islands.get(p.id), people: islands.get(p.id).people.length } : null }));
+            return { text: lines(...out), data: { edges: data } };
+        }
+        const reached = new Set(["in", "limit", "paused", "done"]);
+        const shown = [...edges.values()].filter((e) => opts.all || reached.has(e.scope)).sort((a, b) => (a.generation ?? 99) - (b.generation ?? 99) || a.person.localeCompare(b.person));
+        const count = (k) => [...shown.reduce((m, e) => m.set(e[k], (m.get(e[k]) ?? 0) + 1), new Map())].map(([v, n]) => `${v} ${n}`).join(", ");
+        const hidden = edges.size - shown.length;
+        return {
+            text: shown.length
+                ? lines(table(shown.map((e) => [
+                    e.person,
+                    e.generation !== undefined ? `G${e.generation}` : "",
+                    e.missing,
+                    e.scope === "in" ? "" : e.scope,
+                    e.end,
+                    e.next,
+                    truncate(edgeNext(e), 70),
+                ])), "", `ends: ${count("end")}`, `next: ${count("next")}`, hidden ? `${hidden} more no direction reaches (strom edge --all)` : undefined, "one in full: strom edge P…")
+                : "no edge the research reaches — every person in its directions has parents a record proves",
+            data: { edges: shown, islands: [...new Set(islands.values())].map((i) => ({ ...i, people: i.people.length, first: i.people[0] })) },
+        };
+    },
 });
+/** What comes next at an edge, in a few words: the first task and where it stands, else what the user decides. */
+function edgeNext(e) {
+    const t = e.tasks[0];
+    const hyp = e.hypotheses.find((h) => h.joins.length);
+    const join = hyp ? ` · ${hyp.id} ${hyp.island ? `joins ${hyp.joins.join(" ")} (${hyp.island.people} people off the tree)` : `would join through ${hyp.joins.join(" ")}`}` : "";
+    if (t)
+        return `${t.id}${t.position ? ` #${t.position}` : ""}${t.held ? ` (${t.held})` : ""}${e.tasks.length > 1 ? ` +${e.tasks.length - 1}` : ""}${join}`;
+    if (e.next === "decide")
+        return `tried ${e.tried.join(" ")} — ask the user${join}`;
+    return join.replace(/^ · /, "");
+}
+const MISSING_WORDS = {
+    parents: "both parents unknown",
+    father: "the father unknown",
+    mother: "the mother unknown",
+    proof: "no record proves the parents recorded",
+};
+const SCOPE_WORDS = {
+    in: "reached by",
+    limit: "at the limit of",
+    paused: "in a paused direction,",
+    done: "in an ended direction,",
+    living: "most likely alive — not researched",
+    outside: "family of the tree no direction goes through",
+    "off-tree": "of a family nothing links to the tree yet",
+};
+const END_WORDS = {
+    unnamed: "the baptism names no father (born out of wedlock)",
+    lost: "the records of those years are lost",
+    "before-records": "born before the known birth records of the place begin",
+    gap: "the known records have a gap in those years",
+    "not-found": "searched in vain everywhere strom knew to look",
+    offline: "the books left are only in the archive",
+    partly: "searched in part",
+    unsearched: "not searched yet",
+    "no-books": "no book of the birthplace known",
+    "no-place": "the birthplace unknown",
+    "no-clue": "nothing to go on: no year, no place of birth",
+};
+const NEXT_WORDS = {
+    working: "an agent works on it now",
+    waiting: "waits for the user",
+    queued: "in the queue",
+    held: "waits out of the queue",
+    proposed: "strom proposes it with the next session",
+    decide: "everything strom could propose was tried — the user decides",
+    none: "nothing planned",
+};
+/** One edge in full, for the agent. */
+function edgeLines(tree, e, who) {
+    const y = (r) => (r.from === r.to ? `${r.from}` : `${r.from}–${r.to}`);
+    const est = e.estimate;
+    const basis = est?.basis ? ` (estimated from ${est.basis.kind === "MARR" ? "the marriage" : "the eldest child"} ${est.basis.year})` : "";
+    return [
+        `${who(e.person)} — the tree ends above: ${MISSING_WORDS[e.missing]}`,
+        `  ${SCOPE_WORDS[e.scope]}${e.research ? ` ${e.research}, generation ${e.generation}` : ""}`,
+        `  the records: ${END_WORDS[e.end]}${e.recordsFrom ? ` (from ${e.recordsFrom})` : ""}`,
+        e.window ? `  baptism sought ${y(e.window)}${est?.place ? ` in ${est.place}` : ""}${basis}` : est?.place ? `  born in ${est.place}, year unknown` : undefined,
+        e.books.length ? `  books: ${e.books.map((b) => `${b.id}${b.years ? ` (${b.years})` : ""}${b.access.startsWith("online") ? "" : ` ${b.access}`}`).join(", ")}` : undefined,
+        e.covered.length ? `  searched in vain: ${e.covered.map(y).join(", ")}` : undefined,
+        e.noRecords.length ? `  no records known: ${e.noRecords.map(y).join(", ")}` : undefined,
+        `  next: ${NEXT_WORDS[e.next]}`,
+        ...e.tasks.map((t) => `    ${t.id} ${t.level} ${t.state}${t.position ? ` #${t.position}` : ""}${t.held ? ` (waits: ${t.held}${t.until ? ` until ${t.until}` : ""})` : ""}${t.on ? ` — ${truncate(t.on, 60)}` : ""}: ${truncate(t.what, 90)}`),
+        e.tried.length ? `  tried: ${e.tried.join(" ")}` : undefined,
+        ...e.hypotheses.map((h) => `  ${h.id} ${truncate(h.question, 90)}${!h.joins.length ? "" : h.island ? ` — would join ${h.joins.map(who).join(", ")} of a family off the tree (${h.island.people} people, ${h.island.held} tasks wait for it)` : ` — would join them to the tree through ${h.joins.map(who).join(", ")}`}${h.tests.length ? `; tested by ${h.tests.join(" ")}` : "; no task tests it"}`),
+        e.conflicts.length ? `  open conflicts: ${e.conflicts.join(" ")}` : undefined,
+        e.searches || e.sessions ? `  work so far: ${e.searches} search${e.searches === 1 ? "" : "es"}, ${e.sessions} session${e.sessions === 1 ? "" : "s"}${e.cost !== undefined ? `, $${e.cost.toFixed(2)}${e.costPartial ? "+" : ""}` : ""}${e.last ? `; last ${e.last}` : ""}` : undefined,
+    ].filter((x) => x !== undefined);
+}
+function islandLine(i, who) {
+    const joins = i.hypotheses.map((h) => `${h.id} (to ${h.joins.map(who).join(", ")})`);
+    return `  of a family nothing links to the tree: ${i.people.length} people, ${i.held} tasks wait for it${joins.length ? `; would join it: ${joins.join(", ")}` : "; no hypothesis would join it yet"}`;
+}
 // ── agents ─────────────────────────────────────────────────────────────────
 register({
     path: ["agents", "sync"],
@@ -402,6 +562,7 @@ register({
         { 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: "follow", type: "boolean", description: "open the Strom app to follow the work live when the first session starts (after the gate)" },
         { 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)" },
@@ -439,15 +600,27 @@ register({
         const report = [];
         // What the gate answered, for the record of the run.
         const gates = [];
+        // The Strom app opened to follow the run (--follow): once, when its first session starts.
+        let followed = false;
         // 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";
         let stopValues = {};
-        // Ctrl-C, a closed terminal, a shutdown: stop the agent, close its session, give the task back.
+        // The first Ctrl-C while a session works: it is asked to finish (the agent writes down what it found and closes
+        // it), then the run stops — no next session. Ctrl-C again, a closed terminal, a shutdown: stop the agent now,
+        // close its session, give the task back. (Windows: the console stops the agent itself — now.)
         const stop = new AbortController();
+        let atWorkOn;
+        let finishing = false;
         const onSignal = (sig) => {
             if (stop.signal.aborted)
-                process.exit(130); // a second Ctrl-C: now
+                process.exit(130); // a third Ctrl-C: at once
+            if (sig === "SIGINT" && atWorkOn && !finishing && OWN_GROUP && !opts.interactive) {
+                finishing = true;
+                askFinish(root, atWorkOn, "user");
+                out(`\n${ui(lang, "ui.run.finishing", { session: atWorkOn })}`);
+                return;
+            }
             out(`\n${ui(lang, "ui.run.stopping")} (${sig})`);
             stop.abort();
         };
@@ -478,6 +651,10 @@ register({
             const permissions = ctx.settings.agentPermissions();
             for (const c of browser)
                 out(ui(lang, "ui.run.browser", { name: c.manifest.title ?? c.name, hosts: c.manifest.hosts.join(", ") }));
+            // agent.browser always (the user's choice): the browser in every session, for the research's archives
+            const web = runnerId === "claude" ? agentBrowser(Tree.open(root, runEnv), ctx.settings.shared()?.value) : undefined;
+            if (web?.always)
+                out(ui(lang, "ui.run.browser.always", { hosts: web.hosts.length ? web.hosts.join(", ") : "–" }));
             if (browser.length && /haiku/i.test(models.lead ?? ""))
                 out(ui(lang, "ui.run.browser.model", { model: models.lead }));
             // Archives through the browser with an agent that has no browser tools, or without the extension: said before it starts.
@@ -493,7 +670,7 @@ register({
             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) {
+                if (stop.signal.aborted || finishing) {
                     stopCode = "user";
                     break;
                 }
@@ -558,7 +735,14 @@ register({
                         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);
+                        // the Strom app shows the run paused until then, not at work
+                        markPaused(root, worker, { until: new Date(at).toISOString(), ...(said.reason ? { reason: said.reason } : {}) });
+                        try {
+                            await pause(at - Date.now(), stop.signal);
+                        }
+                        finally {
+                            markPaused(root, worker, undefined);
+                        }
                         stopAwake = keepAwake(ctx.env);
                         i--; // this was no session: ask again, with the queue as it is then
                         continue;
@@ -566,6 +750,17 @@ register({
                 }
                 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}`);
+                // the Strom app followed the research and its bridge ended without a word: on its address again
+                reviveLive(root, ctx.env);
+                // The Strom app follows it from the first session on — not while the run still waits for its gate.
+                if (opts.follow && !followed) {
+                    followed = true;
+                    const { command, args: self } = stromLauncher();
+                    const app = spawnSync(command, [...self, "app", "--live"], { cwd: root, env: ctx.env, encoding: "utf8", windowsHide: true, timeout: 60_000 });
+                    const said = `${app.stdout ?? ""}${app.stderr ?? ""}`.trim();
+                    if (said)
+                        out(said);
+                }
                 // 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 });
@@ -584,6 +779,7 @@ register({
                     STROM_MINUTES: String(minutes),
                     ...(opts.interactive ? {} : { STROM_NONINTERACTIVE: "1" }),
                 };
+                atWorkOn = session.id;
                 const result = await runner.run({
                     cwd: root,
                     prompt,
@@ -605,16 +801,19 @@ register({
                     ...(opts.interactive ? { interactive: true } : {}),
                     // the level for every agent (each maps it to its own switches); the browser and Remote Control are Claude Code's
                     permissions,
-                    ...(runnerId === "claude" ? { chrome: browser.length > 0, remote: ctx.settings.agentRemote() } : {}),
+                    ...(runnerId === "claude" ? { chrome: Boolean(web?.on), remote: ctx.settings.agentRemote() } : {}),
                     ...(extra?.length ? { extraArgs: extra } : {}),
                     onProgress: (l) => out(`  · ${l}`),
                     signal: stop.signal,
                 });
+                atWorkOn = undefined;
                 // Close what the agent left open, record the metrics, export, commit.
                 const after = Tree.open(root, runEnv);
                 let s = after.get(session.id);
                 // strom worked for the agent when it closed the session itself or recorded something
                 const ranStrom = s.state !== "open" || sessionWrites(after, s.id) > 0;
+                // the user asked it to finish (strom session finish, the Strom app's "finish and stop"): no next session
+                const askedToFinish = finishAsked(root, s.id) || s.endedBy === "user";
                 if (s.state === "open")
                     s = closeSession(after, s, {
                         summary: result.outcome === "stopped" ? phrase(after.lang, "session.user") : phrase(after.lang, "session.agent", { outcome: result.outcome }),
@@ -653,7 +852,7 @@ register({
                     stopCode = "problems";
                     break;
                 }
-                if (stop.signal.aborted) {
+                if (stop.signal.aborted || finishing || askedToFinish) {
                     stopCode = "user";
                     break;
                 }

package/dist/commands/setup.js

@@ -453,6 +453,9 @@ function setUserSetting(ctx, key, value) {
     // Loosening the agent's permissions is the user's decision alone.
     if (key === "agent.permissions" && raises(s.agentPermissions(), value))
         ctx.requireHuman(`Let the agent ${value === "full" ? "do everything but what the tree's permissions deny" : "work on its own, asking only about risky steps"}, without asking?`, `strom config set agent.permissions ${value}`, "agent.permissions", ui(ctx.uiLang(), value === "full" ? "ui.consent.level.full" : "ui.consent.level.auto"));
+    // The browser in every session: the user's decision alone.
+    if (key === "agent.browser" && value === "always" && s.resolve("agent.browser", ctx.hasTree() ? ctx.tree().config : undefined)?.value !== "always")
+        ctx.requireHuman("Give the agent browser tools (Claude in Chrome) in every research session?", "strom config set agent.browser always", "agent.browser", ui(ctx.uiLang(), "ui.consent.browser"));
     // Sessions steered from elsewhere (Remote Control): the user's decision alone.
     if (key === "agent.remote" && value === "on" && !s.agentRemote())
         ctx.requireHuman("Start the Claude Code sessions with Remote Control (followed and steered from claude.ai or your phone)?", "strom config set agent.remote on", "agent.remote", ui(ctx.uiLang(), "ui.consent.remote"));

package/dist/commands/start.js

@@ -16,7 +16,7 @@ import { syncAgentFiles } from "../agents/files.js";
 import { AGENTS, findAgent, isAgent, withoutAgentMarks } from "../core/which.js";
 import { DESKTOP_APPS, agentsHere, whereToTalk } from "../core/apps.js";
 import { assertIntact } from "../core/integrity.js";
-import { treeBrowserConnectors } from "../core/connector.js";
+import { agentBrowser } from "../core/connector.js";
 import { browserNote } from "./connectors.js";
 import { offerLinks } from "../cli/wizard.js";
 import { appOpensLinks, appOpensResearch, importAppUrl, installedStromApp, liveAppUrl, noticeStromApp, STROM_APP_URL, stromAppUrl } from "../core/stromapp.js";
@@ -134,7 +134,7 @@ register({
             // its research when there is one, the day.
             name: ["Strom", tree.config.name, researches.length === 1 ? researches[0].name : undefined, new Date().toLocaleDateString(lang, { day: "numeric", month: "numeric" })].filter(Boolean).join(" · "),
             shared,
-            ...(agent === "claude" ? { chrome: treeBrowserConnectors(tree, shared).length > 0, remote: ctx.settings.agentRemote() } : {}),
+            ...(agent === "claude" ? { chrome: agentBrowser(tree, shared).on, remote: ctx.settings.agentRemote() } : {}),
         };
         const args = conversationArgs(agent, base);
         if (opts.print)
@@ -263,7 +263,10 @@ register({
     tree: true,
     description: "A small web server on this computer only (127.0.0.1, a secret address), that only reads: the Strom app, opened with\n" +
         "strom app --live, takes the tree from it and hears what changes — who is at work on what, what was recorded, what\n" +
-        "waits for the user. It ends by itself when nobody asks it anything for two hours, or with strom live stop.",
+        "waits for the user. It ends by itself when nobody asks it anything for two hours, or with strom live stop.\n" +
+        "One error does not end it (a read that fails is tried again); what it did and what went wrong is in .strom/live.log.\n" +
+        "Started again it takes the address it had (its port while free), so the app following it goes on by itself;\n" +
+        "one that ended without a word is started again when a session starts.",
     examples: ["strom live", "strom live start", "strom live stop"],
     run(ctx) {
         const tree = ctx.tree();

package/dist/commands/story.js

@@ -8,6 +8,42 @@ import { approveStory, setStory, findEventOwner } from "../core/actions.js";
 import { UsageError } from "../core/errors.js";
 import { csvOpt, normId, textOpt } from "../core/records.js";
 import { resolvePerson } from "../core/people.js";
+import { foldText } from "../core/text.js";
+/**
+ * The one heading a story has is its title (--title). A first line "# …" is taken as the title when none is given,
+ * and dropped when it only repeats it; any other "# …" line stays (the Strom app shows it as a subheading).
+ */
+function titleOf(text, title) {
+    const [first = "", ...rest] = text.replace(/\r\n?/g, "\n").trimStart().split("\n");
+    const heading = /^#[ \t]+(.+?)[ \t#]*$/.exec(first)?.[1]?.trim();
+    if (!heading)
+        return { text, ...(title ? { title } : {}) };
+    if (!title?.trim())
+        return { text: rest.join("\n"), title: heading };
+    return foldText(heading) === foldText(title) ? { text: rest.join("\n"), title } : { text, title };
+}
+/**
+ * What the Strom app shows as plain text (its set: paragraphs, "## " subheadings, "- " bullets, **bold**,
+ * *italic*): said, never refused. Numbered lists count only as two such lines in a row — a date may start a line.
+ */
+function outsideSet(text) {
+    const found = [];
+    const lns = text.split("\n");
+    if (/\[[^\]\n]+\]\([^)\n]+\)/.test(text))
+        found.push("links");
+    if (lns.filter((l) => /^\s*\|.*\|\s*$/.test(l)).length >= 2)
+        found.push("tables");
+    if (lns.some((l) => /^\s*>/.test(l)))
+        found.push("quotes (> )");
+    if (/`[^`\n]+`/.test(text))
+        found.push("code");
+    if (lns.some((l, i) => /^\s*\d+[.)]\s/.test(l) && /^\s*\d+[.)]\s/.test(lns[i + 1] ?? "")))
+        found.push("numbered lists");
+    // "* 1831" is the sign of a birth, no bullet
+    if (lns.some((l) => /^\s*[*+]\s+(?!\d)/.test(l)))
+        found.push('bullets other than "- "');
+    return found;
+}
 function owner(tree, ref) {
     return /^F\d+$/i.test(ref.trim()) ? normId(ref, "family") : resolvePerson(tree, ref).id;
 }
@@ -17,8 +53,10 @@ register({
     group: "people",
     tree: true,
     writes: true,
-    description: "Every statement rests on a recorded fact: list them with --fact. Paragraphs are separated by a blank line;\n" +
-        "**bold** is kept. Writing it again replaces it (the history keeps the old one).",
+    description: "Every statement rests on a recorded fact: list them with --fact. Paragraphs are separated by a blank line.\n" +
+        "Kept: \"## subheading\" lines, \"- \" bullet lines, **bold**, *italic*; anything else shows as plain text in the\n" +
+        "Strom app. The title goes in --title (a first line \"# …\" is taken as it). Writing it again replaces it (the\n" +
+        "history keeps the old one).",
     args: [{ name: "who", description: "person (ID or name) or family (F…)", required: true }],
     options: [
         { name: "text", type: "string", value: "<text|@file>", description: "the story, in the research language" },
@@ -30,18 +68,21 @@ register({
     examples: ['strom story set P0001 --text @notes/story-P0001.md --title "The miller of Týnec" --fact E0001 --fact E0002 --note "The house is inferred from the census."'],
     run(ctx, { args, opts }) {
         const tree = ctx.tree();
-        const text = textOpt(opts.text, (p) => fs.readFileSync(ctx.resolvePath(p), "utf8"));
-        if (!text?.trim())
+        const given = textOpt(opts.text, (p) => fs.readFileSync(ctx.resolvePath(p), "utf8"));
+        if (!given?.trim())
             throw new UsageError("--text is required", { hint: "--text @notes/story.md (a file) or the text itself" });
+        const { text, title } = titleOf(given, opts.title);
         const rec = setStory(tree, owner(tree, args[0]), {
             text,
-            title: opts.title,
+            title,
             facts: csvOpt(opts.fact).map((f) => normId(f)),
             note: opts.note,
             final: Boolean(opts.final),
         });
         const missing = rec.story.facts.length === 0 ? "note: no --fact given — say which facts the story rests on" : undefined;
-        return { text: lines(...tree.written.map((o) => o.summary), tree.dryRun ? "(dry run — nothing written)" : undefined, missing), data: { story: rec.story } };
+        const outside = outsideSet(rec.story.text);
+        const plain = outside.length ? `note: the Strom app shows ${outside.join(", ")} as plain text — keep to paragraphs, "## " subheadings, "- " bullets, **bold**, *italic*` : undefined;
+        return { text: lines(...tree.written.map((o) => o.summary), tree.dryRun ? "(dry run — nothing written)" : undefined, missing, plain), data: { story: rec.story } };
     },
 }, {
     path: ["story", "approve"],