strom-research 1.8.0 → 1.10.0

package/dist/commands/session.js

@@ -17,10 +17,12 @@ 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";
@@ -68,7 +70,7 @@ export function researchProposals(tree, research) {
         out.push({ proposal, kind: "review" });
     if (new Settings(tree.env, {}).stories(tree.config).on)
         for (const proposal of storyProposals(tree, research))
-            out.push({ proposal: { ...proposal, origin: "frontier" }, kind: "story" });
+            out.push({ proposal: { ...proposal, origin: proposal.origin ?? "frontier" }, kind: "story" });
     return out;
 }
 /** Create the tasks strom proposes for a research; returns their IDs. */
@@ -110,7 +112,9 @@ register({
         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"],
@@ -292,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"],

package/dist/commands/story.js

@@ -4,7 +4,7 @@
 import fs from "node:fs";
 import { register } from "../cli/registry.js";
 import { lines } from "../cli/format.js";
-import { approveStory, setStory, findEventOwner } from "../core/actions.js";
+import { approveStory, discardStoryDraft, 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";
@@ -56,12 +56,14 @@ register({
     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).",
+        "history keeps the old one). A story the user approved is locked: written again, the new version waits beside it\n" +
+        "for their approval (strom story approve), or goes (strom story discard) — the approved one stays until then.",
     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" },
         { name: "title", type: "string", value: "<text>", description: "a heading" },
         { name: "fact", type: "string", multiple: true, value: "<E…>", description: "a fact it leans on (repeatable)" },
+        { name: "source", type: "string", multiple: true, value: "<S…>", description: "a source of the background of place and time it tells — not a fact of the person (repeatable)" },
         { name: "note", type: "string", value: "<text>", description: "your caveat: what is inferred, what is unknown" },
         { name: "final", type: "boolean", description: "the user approved it" },
     ],
@@ -76,29 +78,49 @@ register({
             text,
             title,
             facts: csvOpt(opts.fact).map((f) => normId(f)),
+            sources: csvOpt(opts.source).map((s) => normId(s)),
             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;
-        const outside = outsideSet(rec.story.text);
+        const written = rec.story.draft ?? rec.story;
+        const missing = written.facts.length === 0 ? "note: no --fact given — say which facts the story rests on" : undefined;
+        const outside = outsideSet(written.text);
+        const locked = rec.story.draft
+            ? `the user approved the story before: it stays as it is, the new version waits for them — tell them, they approve it (strom story approve ${rec.id}) or keep the old one (strom story discard ${rec.id})`
+            : undefined;
         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 } };
+        return { text: lines(...tree.written.map((o) => o.summary), tree.dryRun ? "(dry run — nothing written)" : undefined, locked, missing, plain), data: { story: rec.story } };
     },
 }, {
     path: ["story", "approve"],
-    summary: "The user approved the story as it is: no longer a draft",
+    summary: "The user approved the story as it is: no longer a draft, locked — or the new version waiting beside it takes its place",
     group: "people",
     tree: true,
     writes: true,
-    description: "Only on the user's word (they read it and said it is right): the text stays, the draft becomes the story of the family book.",
+    description: "Only on the user's word (they read it and said it is right): the text stays, the draft becomes the story of the family book —\n" +
+        "locked: written again, the new version waits beside it for the user. With a new version waiting, that one is approved in its place.",
     args: [{ name: "who", description: "person (ID or name) or family (F…)", required: true }],
     examples: ["strom story approve P0001"],
     run(ctx, { args }) {
         const tree = ctx.tree();
         const id = owner(tree, args[0]);
-        const was = tree.get(id)?.story?.status;
+        const was = tree.get(id)?.story;
         const rec = approveStory(tree, id);
-        return { text: was === "final" ? `${id} story was approved already` : lines(...tree.written.map((o) => o.summary)), data: { story: rec.story } };
+        return { text: was?.status === "final" && !was.draft ? `${id} story was approved already` : lines(...tree.written.map((o) => o.summary)), data: { story: rec.story } };
+    },
+}, {
+    path: ["story", "discard"],
+    summary: "The new version of an approved story is not wanted: the approved one stays",
+    group: "people",
+    tree: true,
+    writes: true,
+    description: "Only on the user's word: the new version written beside the story they approved goes (the history keeps it).",
+    args: [{ name: "who", description: "person (ID or name) or family (F…)", required: true }],
+    examples: ["strom story discard P0001"],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const rec = discardStoryDraft(tree, owner(tree, args[0]));
+        return { text: lines(...tree.written.map((o) => o.summary)), data: { story: rec.story } };
     },
 }, {
     path: ["story", "show"],
@@ -125,7 +147,16 @@ register({
             }
         });
         return {
-            text: lines(`${id} story · ${st.status} · ${st.at.slice(0, 10)}${st.title ? ` · ${st.title}` : ""}`, "", st.text, "", st.facts.length ? "rests on" : "rests on no recorded fact", ...facts, st.note ? `\nnote: ${st.note}` : undefined),
+            text: lines(`${id} story · ${st.status} · ${st.at.slice(0, 10)}${st.title ? ` · ${st.title}` : ""}`, "", st.text, "", st.facts.length ? "rests on" : "rests on no recorded fact", ...facts, ...(st.sources?.length ? ["the background of place and time from", ...st.sources.map((s) => `  ${s} ${tree.get(s)?.title ?? "(no longer exists)"}`)] : []), st.note ? `\nnote: ${st.note}` : undefined, ...(st.draft
+                ? [
+                    "",
+                    `── a new version (${st.draft.at.slice(0, 10)}) waits for the user: strom story approve ${id} (it takes the place of the one above) · strom story discard ${id} (the one above stays)`,
+                    st.draft.title ? `“${st.draft.title}”` : undefined,
+                    "",
+                    st.draft.text,
+                    st.draft.note ? `\nnote: ${st.draft.note}` : undefined,
+                ]
+                : [])),
             data: { story: st },
         };
     },

package/dist/commands/sync.js

@@ -11,6 +11,7 @@ import { EXIT, StromError, UsageError } from "../core/errors.js";
 import { fileSha256, MAX_IN_TREE, mimeOf } from "../core/media.js";
 import { create, update } from "../core/records.js";
 import { safeFolderName } from "../core/text.js";
+import { humanAge } from "../core/age.js";
 import { now } from "../core/tree.js";
 import { applySync, nothingSince, planSync, readTreeFile, receivedSince, undoSync } from "../core/sync.js";
 import { startLive } from "../core/live.js";
@@ -19,7 +20,13 @@ import { chromiumBrowser, openInBrowser, openWebApp } from "../core/chromium.js"
 function factText(f, lang) {
     if (!f)
         return "—";
-    return [f.value, humanDate(f.date, lang), humanPlace(f.place, undefined, lang)].filter(Boolean).join(", ") || "—";
+    return [f.value, humanDate(f.date, lang), humanPlace(f.place, undefined, lang), detailText(f, lang)].filter(Boolean).join(", ") || "—";
+}
+/** What a fact says besides: its house, age and cause. */
+function detailText(f, lang) {
+    if (!f)
+        return "";
+    return [f.house && ui(lang, "ui.sync.house", { x: f.house }), f.age && humanAge(f.age, lang), f.cause && ui(lang, "ui.sync.cause", { x: f.cause })].filter(Boolean).join(", ");
 }
 /** A position on the map as a map shows it: degrees, six decimals at most. */
 const point = (p) => `${+p.lat.toFixed(6)}, ${+p.lon.toFixed(6)}`;
@@ -41,8 +48,9 @@ function changeLine(tree, c, incoming, lang) {
         name: name(c.person),
         kind: kind(c.fact ?? c.was),
         fact: `${kind(c.fact ?? c.was)} ${factText(c.fact ?? c.was, lang)}`,
-        was: factText(c.was, lang),
-        now: factText(c.fact, lang),
+        was: c.kind === "fact.detail" ? detailText(c.was, lang) || "—" : factText(c.was, lang),
+        now: c.kind === "fact.detail" ? detailText(c.fact, lang) : factText(c.fact, lang),
+        when: [humanDate(c.fact?.date, lang), humanPlace(c.fact?.place, undefined, lang)].filter(Boolean).join(", "),
         text: truncate(c.text ?? "", 120),
         child: name(c.child),
         kids: c.kind === "family.new" && c.text ? ` + ${c.text.split(" ").filter(Boolean).map(name).join(", ")}` : "",
@@ -51,7 +59,8 @@ function changeLine(tree, c, incoming, lang) {
         from: c.place?.was ? point(c.place.was) : "",
     };
     const key = c.kind === "place.coords" && !c.place?.was ? "ui.sync.place.located" : `ui.sync.${c.kind}`;
-    return `${ui(lang, key, v)} → ${ui(lang, `ui.sync.do.${c.action}`)}`;
+    const does = c.kind === "fact.detail" && c.action === "add" ? "ui.sync.do.detail" : `ui.sync.do.${c.action}`;
+    return `${ui(lang, key, v)} → ${ui(lang, does)}`;
 }
 function planText(tree, plan, incoming, file, lang, edits) {
     const shown = file.includes(" ") ? `"${file}"` : file;

package/dist/commands/tasks.js

@@ -20,6 +20,9 @@ import { makeNote } from "../core/actions.js";
 import { phrase } from "../core/phrases.js";
 import { readJsonLines } from "../core/json.js";
 import { lacksImages, rankTasks } from "../core/queue.js";
+import { joiningHypotheses, offTree } from "../core/kin.js";
+import { aboutPeople } from "../core/directions.js";
+import { storiesToApprove } from "../core/stories.js";
 import { clipNote, inboxFolderFor, parseImageList, transcriptNote } from "../core/media.js";
 function written(tree) {
     return lines(...tree.written.map((o) => o.summary), tree.dryRun ? "(dry run — nothing written)" : undefined);
@@ -61,8 +64,11 @@ export function waitingForUser(tree) {
  */
 export function waitingLines(tree, where = {}, max = 5) {
     const w = tree.list("task").filter((t) => t.state === "waiting");
+    // the new versions of stories the user approved: they decide (the lock)
+    const stories = storiesToApprove(tree).map((s) => s.id);
+    const storyLine = stories.length ? `  ${ui(tree.lang, "ui.wait.stories", { ids: stories.join(" ") })}` : undefined;
     if (!w.length)
-        return undefined;
+        return stories.length ? lines(ui(tree.lang, "ui.wait.title", { n: stories.length }), storyLine) : undefined;
     const show = where.display ?? ((p) => p);
     const lang = tree.lang;
     const images = (t) => {
@@ -75,7 +81,7 @@ export function waitingLines(tree, where = {}, max = 5) {
             `         ${ui(lang, "ui.wait.save", { dir: `${dir}${path.sep}` })}`,
         ];
     };
-    return lines(ui(lang, "ui.wait.title", { n: w.length }), ...w.slice(0, max).flatMap((t) => [`  ${t.id}  ${truncate(t.waitingOn || t.what, 150)}`, ...images(t)]), w.length > max ? `  … strom task list --state waiting` : undefined, `  ${ui(lang, "ui.wait.how1")}`, `  ${ui(lang, "ui.wait.how2")}`);
+    return lines(ui(lang, "ui.wait.title", { n: w.length + stories.length }), ...w.slice(0, max).flatMap((t) => [`  ${t.id}  ${truncate(t.waitingOn || t.what, 150)}`, ...images(t)]), w.length > max ? `  … strom task list --state waiting` : undefined, storyLine, `  ${ui(lang, "ui.wait.how1")}`, `  ${ui(lang, "ui.wait.how2")}`);
 }
 /** The open tasks of the queue in the order to work on them (see core/queue.ts). */
 export function taskQueue(tree, filter = {}) {
@@ -89,6 +95,22 @@ export function rankedQueue(tree, filter = {}) {
         .filter((t) => !filter.level || t.level === filter.level);
     return rankTasks(tree, tasks, filter.strategy, { storyTurn: filter.storyTurn });
 }
+/**
+ * What an agent is told of a task about people nothing links to the tree (core/kin.ts offTree): it waits out of the
+ * queue until the user asks for it or the hypothesis that would join them is decided; the task that tests that
+ * hypothesis names it. Undefined for a task of the tree.
+ */
+export function offTreeLine(tree, t, starting = false) {
+    if (!offTree(tree)(t))
+        return undefined;
+    const joins = joiningHypotheses(tree, aboutPeople(tree, t.subject));
+    const first = joins.length
+        ? `test first what would join them: ${joins.map((h) => `${h.id} "${truncate(h.question, 70)}"`).join("; ")} — a task that tests it names it (--about ${joins[0].id})`
+        : "first a link to a person of the tree: a hypothesis (strom hypothesis add … --about P… of the tree) and a task that tests it, naming it (--about H…)";
+    return starting
+        ? `⚠ ${t.id} is about people nothing links to the tree yet: go on only if the user asked for this work. Else close the session (strom session close --continue …) and ${first}`
+        : `· ${t.id} is about people nothing links to the tree yet: it waits out of the queue until the user asks for it or a hypothesis joins them — ${first}`;
+}
 function taskLine(t) {
     return [t.id, `p${t.priority}`, t.level, t.state === "open" ? "" : `[${t.state}]`, truncate(t.what, 70)];
 }
@@ -231,7 +253,7 @@ register({
         // it is known — not in a session spent finding out that there is nothing to read.
         const noImages = lacksImages(tree, t);
         return {
-            text: lines(written(tree), ...similar.map((x) => `⚠ similar ${x.state} task ${x.id} "${truncate(x.what, 60)}" — if it is the same, keep one: strom task drop ${t.id} --reason "duplicate of ${x.id}" and strom task edit ${x.id} --where … --note "…"`), noImages ? `· no images for it here yet — if the user has to download them, say which now: strom task wait ${t.id} --images B…:<numbers> --on "<the book, its link, which images>"` : undefined),
+            text: lines(written(tree), ...similar.map((x) => `⚠ similar ${x.state} task ${x.id} "${truncate(x.what, 60)}" — if it is the same, keep one: strom task drop ${t.id} --reason "duplicate of ${x.id}" and strom task edit ${x.id} --where … --note "…"`), offTreeLine(tree, t), noImages ? `· no images for it here yet — if the user has to download them, say which now: strom task wait ${t.id} --images B…:<numbers> --on "<the book, its link, which images>"` : undefined),
             data: { task: t, similar: similar.map((x) => x.id), needsImages: noImages },
         };
     },
@@ -250,8 +272,13 @@ register({
         const strategy = ctx.settings.strategy(tree.config);
         const queue = rankedQueue(tree, { ...(research ? { research } : {}), ...(opts.level ? { level: String(opts.level) } : {}), strategy });
         const first = queue[0];
-        if (!first)
-            return { text: 'no open tasks → strom research show <G…> to see what is missing, then strom task add', data: { task: null } };
+        if (!first) {
+            const held = tree.list("task").filter(offTree(tree)).filter((t) => t.state === "open").length;
+            const text = held
+                ? `no open task of the tree — ${held} wait about people nothing links to it yet (strom task list --off-tree): test the hypothesis that would join them, or ask the user`
+                : "no open tasks → strom research show <G…> to see what is missing, then strom task add";
+            return { text, data: { task: null, offTree: held } };
+        }
         const t = first.task;
         return {
             text: lines(taskDetail(tree, t), "", `first because: ${first.why} (queue: ${strategy})`, `start it: strom task start ${t.id}`),
@@ -271,6 +298,7 @@ register({
         { name: "research", type: "string", value: "<G…>", description: "only this research" },
         { name: "level", type: "string", value: "<level>", description: "only this level" },
         { name: "about", type: "string", value: "<who>", description: "only tasks about this person/record (also X…, H…)" },
+        { name: "off-tree", type: "boolean", description: "the open tasks that wait out of the queue: about people nothing links to the tree yet" },
         { name: "full", type: "boolean", description: "--json: whole records instead of one row each" },
     ],
     run(ctx, { opts }) {
@@ -278,7 +306,10 @@ register({
         const research = typeof opts.research === "string" ? resolveResearch(tree, opts.research).id : undefined;
         let all;
         const why = new Map();
-        if (!opts.state) {
+        const off = offTree(tree);
+        if (opts["off-tree"])
+            all = tree.list("task").filter((t) => t.state === "open" && off(t) && (!opts.level || t.level === opts.level));
+        else if (!opts.state) {
             const ranked = rankedQueue(tree, { ...(research ? { research } : {}), ...(opts.level ? { level: String(opts.level) } : {}), strategy: ctx.settings.strategy(tree.config) });
             for (const r of ranked)
                 why.set(r.task.id, r.why);
@@ -297,8 +328,10 @@ register({
             all = all.filter((t) => t.subject.includes(id));
         }
         const page = paginate(all, ctx.limit, ctx.page);
+        // the queue says what waits out of it for a link to the tree
+        const held = !opts.state && !opts["off-tree"] && !opts.about ? tree.list("task").filter((t) => t.state === "open" && off(t)).length : 0;
         return {
-            text: all.length ? lines(table(page.items.map(taskLine)), moreLine(page, "strom task list")) : "no tasks",
+            text: lines(all.length ? lines(table(page.items.map(taskLine)), moreLine(page, "strom task list")) : "no tasks", held ? `${held} more wait out of the queue: about people nothing links to the tree yet (strom task list --off-tree)` : undefined),
             data: { total: page.total, tasks: opts.full ? page.items : page.items.map((t) => ({ id: t.id, priority: t.priority, level: t.level, state: t.state, what: t.what, subject: t.subject, ...(why.has(t.id) ? { why: why.get(t.id) } : {}) })) },
         };
     },
@@ -360,7 +393,7 @@ register({
             summary: `${id} ${fields.map((f) => (f === "doneWhen" ? "done-when" : f === "subject" ? "about" : f)).join(", ")}${change.where ? ` → ${truncate(change.where.join("; "), 50)}` : ""}`,
             reason: opts.reason,
         });
-        return { text: written(tree), data: { task: t } };
+        return { text: lines(written(tree), change.subject ? offTreeLine(tree, t) : undefined), data: { task: t } };
     },
 }, {
     path: ["task", "start"],

package/dist/core/actions.js

@@ -589,7 +589,8 @@ export function editPerson(tree, id, edit, reason) {
  */
 export function editEvent(tree, eventId, edit, reason) {
     const date = edit.date === undefined ? undefined : parseDate(edit.date);
-    const age = edit.age === undefined ? undefined : parseAge(edit.age);
+    // an empty age takes it away
+    const age = edit.age === undefined ? undefined : edit.age.trim() ? parseAge(edit.age) : "";
     const ages = edit.ages ? Object.fromEntries(Object.entries(edit.ages).map(([who, a]) => [who, parseAge(a, who)])) : undefined;
     return replaceEvent(tree, eventId, (e) => {
         const changed = [];
@@ -821,7 +822,11 @@ export function mergeFamilies(tree, keepId, otherId, reason) {
         return { family: merged, repointed };
     });
 }
-/** Write (or rewrite) the story of a person or a couple. The facts it leans on must exist. */
+/**
+ * Write (or rewrite) the story of a person or a couple. The facts it leans on must exist. A story the user approved is
+ * locked: written again, the new version waits beside it for their approval (story.draft) — unless they approve it now
+ * (final).
+ */
 export function setStory(tree, id, input) {
     const text = input.text.replace(/\r\n?/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
     if (!text)
@@ -829,28 +834,55 @@ export function setStory(tree, id, input) {
     const facts = [...new Set((input.facts ?? []).map((f) => f.trim().toUpperCase()))];
     for (const f of facts)
         findEventOwner(tree, f);
+    const sources = [...new Set((input.sources ?? []).map((s) => s.trim().toUpperCase()))];
+    for (const s of sources)
+        if (tree.get(s)?.type !== "source")
+            throw new UsageError(`no source ${s}`, { hint: "the background of place and time is recorded first: strom source add … --kind book|newspaper|web" });
     return tree.withTreeLock(() => {
         const rec = tree.get(id);
         if (!rec || (rec.type !== "person" && rec.type !== "family"))
             throw new UsageError(`no person or family ${id}`);
         if (rec.mergedInto)
             throw new UsageError(`${id} was merged into ${rec.mergedInto}`);
-        const story = {
+        const version = {
             ...(input.title?.trim() ? { title: input.title.trim() } : {}),
-            status: input.final ? "final" : "draft",
             text,
             facts,
+            ...(sources.length ? { sources } : {}),
             ...(input.note?.trim() ? { note: input.note.trim() } : {}),
             at: now(),
             by: tree.actor,
         };
-        const updated = { ...rec, story, updated: now() };
         const words = text.split(/\s+/).length;
+        if (rec.story?.status === "final" && !input.final) {
+            const updated = { ...rec, story: { ...rec.story, draft: version }, updated: now() };
+            tree.put(updated, { op: "story.set", targets: [id], summary: `${id} story: a new version (${words} words) waits for the user's approval; the approved one stays` });
+            return updated;
+        }
+        const story = { ...version, status: input.final ? "final" : "draft" };
+        const updated = { ...rec, story, updated: now() };
         tree.put(updated, { op: "story.set", targets: [id], summary: `${id} story${rec.story ? " rewritten" : ""}: ${words} words, ${story.status}` });
         return updated;
     });
 }
-/** The user approved the story as it is: no longer a draft (the text stays). */
+/** The new version of an approved story is not wanted: it goes, the approved story stays (the history keeps it). */
+export function discardStoryDraft(tree, id) {
+    return tree.withTreeLock(() => {
+        const rec = tree.get(id);
+        if (!rec || (rec.type !== "person" && rec.type !== "family"))
+            throw new UsageError(`no person or family ${id}`);
+        if (!rec.story?.draft)
+            throw new UsageError(`${id} has no new version of its story waiting`, { hint: `strom story show ${id}` });
+        const { draft: _gone, ...story } = rec.story;
+        const updated = { ...rec, story, updated: now() };
+        tree.put(updated, { op: "story.discard", targets: [id], summary: `${id} story: the new version discarded, the approved one stays` });
+        return updated;
+    });
+}
+/**
+ * The user approved the story as it is: no longer a draft (the text stays), locked — or, when a new version waits
+ * beside an approved one, that new version takes its place, approved.
+ */
 export function approveStory(tree, id) {
     return tree.withTreeLock(() => {
         const rec = tree.get(id);
@@ -858,6 +890,11 @@ export function approveStory(tree, id) {
             throw new UsageError(`no person or family ${id}`);
         if (!rec.story)
             throw new UsageError(`${id} has no story yet`, { hint: `strom story set ${id} --text @file --fact E…` });
+        if (rec.story.draft) {
+            const updated = { ...rec, story: { ...rec.story.draft, status: "final" }, updated: now() };
+            tree.put(updated, { op: "story.approve", targets: [id], summary: `${id} story: the new version approved, in place of the old one` });
+            return updated;
+        }
         if (rec.story.status === "final")
             return rec;
         const updated = { ...rec, story: { ...rec.story, status: "final" }, updated: now() };

package/dist/core/changelog.js

@@ -48,6 +48,7 @@ const SAID = {
     "repository.edit": "log.repository.edit",
     "story.set": "log.story.set",
     "story.approve": "log.story.approve",
+    "story.discard": "log.story.discard",
     "note.add": "log.note.add",
     "input.add": "log.input.add",
     "input.sync": "log.input.sync",

package/dist/core/config.js

@@ -44,6 +44,7 @@ export const SETTINGS = [
     { 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" },
+    { key: "stories.sources", env: "STROM_STORIES_SOURCES", tree: true, kind: "choice", choices: ["yes", "no"], description: "before a story is written, a search beyond the registers — newspapers, directories, military, land and court records, graves, the history of the place — so the story can tell more, every word still on a record: yes (default, while stories are on), no (the story from what the research found)" },
     { key: "sync.edits", env: "STROM_SYNC_EDITS", tree: true, kind: "choice", choices: ["conflict", "user"], description: "your edits in the Strom app (or another program's file) to a fact a record proves, taken by strom sync: conflict (default — the research keeps the record's, a conflict for you to decide) or user (your edit wins, the record's fact is withdrawn with the reason)" },
     { key: "main.person", env: "STROM_MAIN_PERSON", tree: true, kind: "person", description: "the main person of the tree (P…): first in the GEDCOM files — the Strom app opens on them (default: the nearest person descended from every research's focus, else the first research's focus)" },
     { key: "excerpts.quality", env: "STROM_EXCERPTS_QUALITY", tree: true, kind: "choice", choices: EXCERPT_QUALITIES, description: "the entries cut out of their scans in the file for the Strom app (output/tree-strom.ged): small (1000 px, grey — half the size), normal (default, 1200 px), sharp (1600 px)" },
@@ -362,6 +363,10 @@ export class Settings {
         const v = this.resolve("stories", tree)?.value;
         return { on: v !== "no", said: v === "yes" || v === "no" };
     }
+    /** Before a story, the sources beyond the registers (core/stories.ts): on unless the user said no. */
+    storySources(tree) {
+        return this.resolve("stories.sources", tree)?.value !== "no";
+    }
     /** strom sync: whether the user's edit to a fact a record proves wins, or becomes a conflict. */
     syncEdits(tree) {
         return this.resolve("sync.edits", tree)?.value === "user" ? "user" : "conflict";