strom-research 1.0.0

package/dist/core/roles.js

@@ -0,0 +1,30 @@
+// The roles people have in a record, whatever language they are written in:
+// "kmotr", "Pate", "svědek", "Hebamme", "oddávající" — and RELA of other programs.
+import { foldText } from "./text.js";
+import { PARTICIPANT_ROLES } from "./model.js";
+/** The role a word names, in any of the languages records and programs use; undefined if none. */
+export function roleWord(word) {
+    const r = foldText(word ?? "");
+    if (!r)
+        return undefined;
+    if (PARTICIPANT_ROLES.includes(r))
+        return r;
+    // Latin registers: patrinus/patrina, levans (who lifts the child), susceptor; paranymphus (at a wedding) is a witness
+    if (/godparent|godfather|godmother|sponsor|kmotr|pate|patin|patrin|levan|suscept|compater|commater|chrzest|parrain|marraine|padrino|madrina/.test(r))
+        return "godparent";
+    if (/witness|svedek|svedk|zeuge|swiadek|swiadk|temoin|testigo|testis|testes|paranymph|druzba|druzic/.test(r))
+        return "witness";
+    if (/officiant|clergy|priest|minister|pastor|knez|farar|kaplan|pfarrer|ksiadz|cure|sacerdo|parochus|capellan|cooperator|vicari|baptizans|copulans|copulavi|oddavajici|krtici/.test(r))
+        return "officiant";
+    if (/informant|oznamovatel|anzeig|declarant/.test(r))
+        return "informant";
+    if (/midwife|porodni|baba|hebamme|polozna|sage-femme|obstetrix/.test(r))
+        return "midwife";
+    if (/participant|ucastnik|teilnehmer|uczestnik/.test(r))
+        return "other";
+    return undefined;
+}
+/** RELA as other programs write it → our role. */
+export function roleOf(rela, fallback = "other") {
+    return roleWord(rela) ?? fallback;
+}

package/dist/core/schema.js

@@ -0,0 +1,261 @@
+// Declarative field rules for record types. Used for write-time validation
+// and by `strom check` (including references between records).
+import { ACCESS, AUTOMATION, INPUT_KINDS, JURISDICTIONS, LESSON_MAX, LESSON_SCOPES, SEARCH_METHODS, SEARCH_RESULTS, SOURCE_KINDS, TASK_LEVELS, TASK_STATES, } from "./model.js";
+import { normalizeDate } from "./gdate.js";
+const S = (extra = {}) => ({ t: "string", ...extra });
+const R = (to, req = false) => ({ t: "ref", to, req });
+const RS = (to, min = 0) => ({ t: "refs", to, req: true, min });
+/** A fraction of an image (0–1). */
+const F = { t: "number", req: true, min: 0, max: 1 };
+const ANY_SUBJECT = ["person", "family", "place", "recordset", "repository", "source", "research", "input"];
+/** A task can also be about a conflict or a hypothesis: the work that decides it. */
+const TASK_SUBJECT = [...ANY_SUBJECT, "conflict", "hypothesis"];
+export const SCHEMAS = {
+    source: {
+        kind: S({ req: true, enum: SOURCE_KINDS }),
+        title: S({ req: true, max: 300 }),
+        recordset: R("recordset"),
+        repository: R("repository"),
+        input: R("input"),
+        locator: S({ max: 300 }),
+        date: S({ date: true }),
+        transcript: S(),
+        translation: S(),
+        language: S(),
+        information: S({ req: true, enum: ["primary", "secondary", "unknown"] }),
+        form: S({ req: true, enum: ["original", "derivative", "authored"] }),
+        url: S(),
+        accessed: S(),
+        media: { t: "refs", to: "media" },
+    },
+    repository: {
+        name: S({ req: true, max: 200 }),
+        country: S(),
+        region: S(),
+        url: S(),
+        terms: S({ max: 1000 }),
+        automation: S({ req: true, enum: AUTOMATION }),
+    },
+    recordset: {
+        title: S({ req: true, max: 300 }),
+        repository: R("repository"),
+        callNumber: S(),
+        kinds: { t: "strings", req: true },
+        places: { t: "strings", req: true },
+        years: S(),
+        access: S({ req: true, enum: ACCESS }),
+        url: S(),
+        images: { t: "number", int: true, min: 1 },
+        calibration: { t: "array", req: true, of: { image: { t: "number", req: true, int: true, min: 1 }, page: S({ req: true }) } },
+        layout: S({ max: 1000 }),
+    },
+    place: {
+        names: { t: "array", req: true, min: 1, of: { name: S({ req: true }), lang: S(), from: { t: "number", int: true }, to: { t: "number", int: true } } },
+        kind: S(),
+        coords: { t: "object", of: { lat: { t: "number", req: true, min: -90, max: 90 }, lon: { t: "number", req: true, min: -180, max: 180 } } },
+        parent: R("place"),
+        jurisdictions: {
+            t: "array",
+            req: true,
+            of: {
+                kind: S({ req: true, enum: JURISDICTIONS }),
+                name: S({ req: true }),
+                from: { t: "number", int: true },
+                to: { t: "number", int: true },
+                repository: R("repository"),
+                recordsets: RS("recordset"),
+            },
+        },
+    },
+    search: {
+        question: S({ req: true, max: 300 }),
+        recordsets: RS("recordset"),
+        scope: { t: "object", req: true, of: { years: S(), surnames: { t: "strings" }, places: { t: "strings" }, pages: S() } },
+        method: S({ req: true, enum: SEARCH_METHODS }),
+        result: S({ req: true, enum: SEARCH_RESULTS }),
+        findings: RS("source"),
+        task: R("task"),
+        by: S({ req: true, enum: ["main", "reader", "user"] }),
+    },
+    task: {
+        level: S({ req: true, enum: TASK_LEVELS }),
+        priority: { t: "number", req: true, int: true, min: 1, max: 5 },
+        what: S({ req: true, max: 200 }),
+        where: { t: "strings", req: true, min: 1 },
+        why: S({ req: true, max: 1000 }),
+        doneWhen: S({ req: true, max: 500 }),
+        subject: RS(TASK_SUBJECT),
+        research: R("research"),
+        state: S({ req: true, enum: TASK_STATES }),
+        parkedUntil: S(),
+        waitingOn: S(),
+        awaits: { t: "object", of: { recordset: R("recordset", true), images: S({ req: true, max: 200 }), folder: S({ req: true, max: 200 }) } },
+        result: S({ max: 1000 }),
+        produced: { t: "strings" },
+        origin: S({ req: true }),
+    },
+    conflict: {
+        title: S({ req: true, max: 200 }),
+        subject: RS(ANY_SUBJECT, 1),
+        claims: { t: "array", req: true, min: 2, of: { source: R("source"), value: S({ req: true, max: 500 }), note: S({ max: 500 }) } },
+        state: S({ req: true, enum: ["open", "resolved"] }),
+        resolution: S({ max: 500 }),
+        reasoning: S({ max: 2000 }),
+    },
+    hypothesis: {
+        question: S({ req: true, max: 300 }),
+        subject: RS(ANY_SUBJECT, 1),
+        variants: {
+            t: "array",
+            req: true,
+            min: 2,
+            of: { label: S({ req: true, max: 20 }), claim: S({ req: true, max: 500 }), support: { t: "strings", req: true }, against: { t: "strings", req: true } },
+        },
+        state: S({ req: true, enum: ["open", "decided", "abandoned"] }),
+        decision: S({ max: 1000 }),
+    },
+    lesson: {
+        scope: S({ req: true, enum: LESSON_SCOPES }),
+        target: R(["repository", "recordset", "place"]),
+        rule: S({ req: true, max: LESSON_MAX }),
+        detail: S({ max: 2000 }),
+    },
+    session: {
+        task: R("task"),
+        research: R("research"),
+        state: S({ req: true, enum: ["open", "closed", "interrupted"] }),
+        runner: S(),
+        worker: S(),
+        agent: S(),
+        endedBy: S({ enum: ["user", "run", "chat", "agent"] }),
+        started: S({ req: true }),
+        ended: S(),
+        summary: S({ max: 2000 }),
+        next: S({ max: 1000 }),
+        metrics: { t: "any" },
+    },
+    input: {
+        name: S({ req: true }),
+        file: S(),
+        text: S(),
+        sha: S(),
+        size: { t: "number", int: true, min: 0 },
+        mime: S(),
+        from: S(),
+        kind: S({ req: true, enum: INPUT_KINDS }),
+        state: S({ req: true, enum: ["new", "processed", "skipped"] }),
+        source: R("source"),
+        imported: { t: "any" },
+    },
+    media: {
+        sha: S({ req: true }),
+        file: S({ req: true }),
+        mime: S({ req: true }),
+        size: { t: "number", req: true, int: true, min: 0 },
+        width: { t: "number", int: true, min: 1 },
+        height: { t: "number", int: true, min: 1 },
+        recordset: R("recordset"),
+        image: { t: "number", int: true, min: 0 },
+        part: { t: "object", of: { x: F, y: F, w: F, h: F } },
+        page: S({ max: 100 }),
+        url: S(),
+        from: S(),
+        fetched: { t: "object", of: { connector: S({ req: true, max: 100 }), book: S({ req: true, max: 300 }), via: S({ enum: ["browser"] }) } },
+        accessed: S(),
+    },
+};
+function prefixOk(id, to, prefixes) {
+    return to.some((t) => id.startsWith(prefixes[t]) && /^[A-Z]\d{4,}$/.test(id));
+}
+/** Validate fields against a spec; collect references for `check`. */
+export function checkFields(value, spec, prefixes, path, out, refs) {
+    for (const [key, rule] of Object.entries(spec)) {
+        const v = value[key];
+        const p = path ? `${path}.${key}` : key;
+        if (v === undefined || v === null) {
+            if ("req" in rule && rule.req)
+                out.push({ path: p, message: "is required" });
+            continue;
+        }
+        switch (rule.t) {
+            case "any":
+                break;
+            case "string":
+                if (typeof v !== "string")
+                    out.push({ path: p, message: "must be text" });
+                else {
+                    if (rule.req && v.trim() === "")
+                        out.push({ path: p, message: "must not be empty" });
+                    if (rule.enum && !rule.enum.includes(v))
+                        out.push({ path: p, message: `must be one of ${rule.enum.join(", ")}` });
+                    if (rule.max && [...v].length > rule.max)
+                        out.push({ path: p, message: `is longer than ${rule.max} characters` });
+                    if (rule.date && normalizeDate(v) !== v)
+                        out.push({ path: p, message: `"${v}" is not a normalized GEDCOM date` });
+                }
+                break;
+            case "number":
+                if (typeof v !== "number" || Number.isNaN(v))
+                    out.push({ path: p, message: "must be a number" });
+                else {
+                    if (rule.int && !Number.isInteger(v))
+                        out.push({ path: p, message: "must be a whole number" });
+                    if (rule.min !== undefined && v < rule.min)
+                        out.push({ path: p, message: `must be at least ${rule.min}` });
+                    if (rule.max !== undefined && v > rule.max)
+                        out.push({ path: p, message: `must be at most ${rule.max}` });
+                }
+                break;
+            case "ref": {
+                const to = Array.isArray(rule.to) ? rule.to : [rule.to];
+                if (typeof v !== "string" || !prefixOk(v, to, prefixes))
+                    out.push({ path: p, message: `must be a ${to.join("/")} ID` });
+                else
+                    refs.push({ path: p, id: v, to });
+                break;
+            }
+            case "refs": {
+                const to = Array.isArray(rule.to) ? rule.to : [rule.to];
+                if (!Array.isArray(v))
+                    out.push({ path: p, message: "must be a list of IDs" });
+                else {
+                    if (rule.min && v.length < rule.min)
+                        out.push({ path: p, message: `needs at least ${rule.min}` });
+                    v.forEach((id, i) => {
+                        if (typeof id !== "string" || !prefixOk(id, to, prefixes))
+                            out.push({ path: `${p}[${i}]`, message: `must be a ${to.join("/")} ID` });
+                        else
+                            refs.push({ path: `${p}[${i}]`, id, to });
+                    });
+                }
+                break;
+            }
+            case "strings":
+                if (!Array.isArray(v) || v.some((x) => typeof x !== "string"))
+                    out.push({ path: p, message: "must be a list of texts" });
+                else if (rule.min && v.length < rule.min)
+                    out.push({ path: p, message: `needs at least ${rule.min}` });
+                break;
+            case "array":
+                if (!Array.isArray(v))
+                    out.push({ path: p, message: "must be a list" });
+                else {
+                    if (rule.min && v.length < rule.min)
+                        out.push({ path: p, message: `needs at least ${rule.min}` });
+                    v.forEach((item, i) => {
+                        if (item === null || typeof item !== "object")
+                            out.push({ path: `${p}[${i}]`, message: "must be an object" });
+                        else
+                            checkFields(item, rule.of, prefixes, `${p}[${i}]`, out, refs);
+                    });
+                }
+                break;
+            case "object":
+                if (typeof v !== "object" || Array.isArray(v))
+                    out.push({ path: p, message: "must be an object" });
+                else
+                    checkFields(v, rule.of, prefixes, p, out, refs);
+                break;
+        }
+    }
+}

package/dist/core/seal.js

@@ -0,0 +1,77 @@
+// Tamper evidence.
+//
+// - Every operation strom writes records the SHA-256 of each file it wrote,
+//   links to the previous operation (hash chain) and is signed with an HMAC
+//   key that lives OUTSIDE the tree: <config>/keys/<tree id>.key (agents are
+//   not permitted to read it).
+// - Every commit strom makes carries a trailer `Strom-Seal: <HMAC of the git
+//   tree hash>`, so a commit made outside strom is detected by looking at
+//   HEAD alone — cheap enough to run before every command.
+//
+// Agents bypass tools out of convenience, not malice; this catches every
+// convenience bypass, and deliberate forgery needs a secret the agent was
+// told not to read.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { configDir } from "./paths.js";
+import { canonicalize } from "./json.js";
+export function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+export function fileSha(file) {
+    try {
+        return sha256(fs.readFileSync(file));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function keyFile(env, treeId) {
+    return path.join(configDir(env), "keys", `${treeId}.key`);
+}
+export function loadKey(env, treeId) {
+    try {
+        return Buffer.from(fs.readFileSync(keyFile(env, treeId), "utf8").trim(), "hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Create the key for a tree on this computer (0600). Fails if it exists. */
+export function createKey(env, treeId) {
+    const file = keyFile(env, treeId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const key = crypto.randomBytes(32);
+    fs.writeFileSync(file, key.toString("hex") + "\n", { mode: 0o600, flag: "wx" });
+    return key;
+}
+/** Short public fingerprint of a key, stored on each operation. */
+export function fingerprint(key) {
+    return sha256(key).slice(0, 12);
+}
+function hmac(key, text) {
+    return crypto.createHmac("sha256", key).update(text).digest("hex").slice(0, 32);
+}
+/** Signature over the operation without its own `sig` field. */
+export function signOp(op, key) {
+    const { sig: _omit, ...rest } = op;
+    return hmac(key, JSON.stringify(canonicalize(rest)));
+}
+function safeEqual(a, b) {
+    return a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+export function verifyOp(op, key) {
+    return typeof op.sig === "string" && safeEqual(op.sig, signOp(op, key));
+}
+export const SEAL_TRAILER = "Strom-Seal";
+export function commitSeal(key, treeHash) {
+    return `${SEAL_TRAILER}: ${hmac(key, `tree ${treeHash}`)}`;
+}
+export function readCommitSeal(message) {
+    return new RegExp(`^${SEAL_TRAILER}: ([0-9a-f]{32})\\s*$`, "m").exec(message)?.[1];
+}
+export function verifyCommitSeal(key, treeHash, message) {
+    const seal = readCommitSeal(message);
+    return seal !== undefined && safeEqual(seal, hmac(key, `tree ${treeHash}`));
+}

package/dist/core/self.js

@@ -0,0 +1,40 @@
+// This very installation of strom: how it was installed and how to start it
+// again — for the agent's `strom` on PATH, the shortcut on the desktop, a
+// process strom starts itself.
+//
+// strom is JavaScript on Node, installed one of three ways:
+//   installed  by strom's installer: a folder with the official Node from
+//              nodejs.org (node/) and strom's code (app/), install.json beside
+//              them naming the command(s) on PATH that start it
+//   npm        npm install -g strom-research, on the Node of the computer
+//   source     run from the repository (node src/cli.ts)
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const here = fileURLToPath(import.meta.url);
+/** How this strom was installed (read once). */
+let cached;
+export function installation() {
+    if (cached)
+        return cached;
+    if (here.endsWith(".ts"))
+        return (cached = { kind: "source" });
+    // …/app/dist/core/self.js
+    const app = path.resolve(path.dirname(here), "..", "..");
+    const root = path.dirname(app);
+    try {
+        if (path.basename(app) === "app") {
+            const info = JSON.parse(fs.readFileSync(path.join(root, "install.json"), "utf8"));
+            return (cached = { kind: "installed", root, launchers: info.launchers ?? [], ...(info.node ? { node: info.node } : {}) });
+        }
+    }
+    catch {
+        // not the installer's folder
+    }
+    return (cached = { kind: "npm" });
+}
+/** The program and arguments that run strom: this Node and its entry script (cli.ts from sources, cli.js built). */
+export function stromLauncher() {
+    const cli = path.resolve(path.dirname(here), "..", here.endsWith(".ts") ? "cli.ts" : "cli.js");
+    return { command: process.execPath, args: [cli] };
+}

package/dist/core/session.js

@@ -0,0 +1,155 @@
+// Sessions: one agent working on one task. While a session is open, every
+// operation is logged under its ID (data/ops/N0001.jsonl) and the tree knows
+// who wrote what. Several agents may work side by side, each in a session of
+// its own on a task of its own: the current session of an agent strom started
+// lives in .strom/session-<worker>.json (STROM_WORKER, set by strom chat), of
+// any other in .strom/session.json (local state, not evidence), or in
+// STROM_SESSION (set by `strom run`).
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "./errors.js";
+import { now } from "./tree.js";
+import { makeNote } from "./actions.js";
+import { detectAgent } from "./which.js";
+import { isLiveWorker, isWorkerId } from "./workers.js";
+function currentFile(tree, env = tree.env) {
+    const w = env.STROM_WORKER;
+    return path.join(tree.root, ".strom", isWorkerId(w) ? `session-${w}.json` : "session.json");
+}
+/** Who holds a session, for keeping agents apart: its worker, a run, or anyone else. */
+function holder(s) {
+    return s.worker ?? (s.runner ? "run" : "");
+}
+/** Who this process works for. */
+function holderOf(env, runner) {
+    return isWorkerId(env.STROM_WORKER) ? env.STROM_WORKER : runner ? "run" : "";
+}
+/** Open sessions of other agents, and the tasks they hold. */
+export function othersAtWork(tree, env = tree.env, runner) {
+    const me = holderOf(env, runner);
+    const sessions = openSessions(tree).filter((s) => holder(s) !== me);
+    return { sessions, tasks: new Set(sessions.flatMap((s) => (s.task ? [s.task] : []))) };
+}
+/**
+ * Sessions whose agent is gone: strom chat ended (or the computer went down)
+ * with the session still open. The tree knows it from the worker's presence.
+ */
+export function abandonedSessions(tree) {
+    return openSessions(tree).filter((s) => s.worker && !isLiveWorker(tree.root, s.worker));
+}
+/** The open session of this tree, if any. */
+export function currentSession(tree, env) {
+    let id = env.STROM_SESSION;
+    if (!id) {
+        try {
+            id = JSON.parse(fs.readFileSync(currentFile(tree, env), "utf8")).id;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const s = id ? tree.get(id) : undefined;
+    return s?.state === "open" ? s : undefined;
+}
+export function setCurrent(tree, id) {
+    if (tree.dryRun)
+        return;
+    const file = currentFile(tree);
+    if (id === undefined)
+        fs.rmSync(file, { force: true });
+    else {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ id, at: now() }) + "\n");
+    }
+}
+export function openSessions(tree) {
+    return tree.list("session").filter((s) => s.state === "open");
+}
+/** Start a session on a task (the task goes to "doing"). One open session per agent; one agent per task. */
+export function startSession(tree, opts) {
+    return tree.withTreeLock(() => {
+        const me = holderOf(tree.env, opts.runner);
+        const busy = openSessions(tree).filter((s) => holder(s) === me && (!opts.research || !s.research || s.research === opts.research));
+        if (busy.length)
+            throw new UsageError(`session ${busy[0].id} is still open${busy[0].task ? ` on ${busy[0].task}` : ""}`, {
+                hint: `finish it: strom session close --summary "…" --next "…"   (or, if it died: strom session close ${busy[0].id} --interrupted)`,
+            });
+        const taken = opts.task ? othersAtWork(tree, tree.env, opts.runner).sessions.find((s) => s.task === opts.task.id) : undefined;
+        if (taken)
+            throw new UsageError(`${opts.task.id} is being worked on in session ${taken.id}${taken.agent ? ` (${taken.agent})` : ""}`, {
+                hint: "take another task: strom session start (the next free one)",
+            });
+        const task = opts.task ? (tree.get(opts.task.id) ?? opts.task) : undefined;
+        const agent = detectAgent(tree.env) ?? (opts.runner && opts.runner !== "script" ? opts.runner : undefined);
+        const t = now();
+        const s = {
+            id: tree.allocate("N"),
+            type: "session",
+            state: "open",
+            started: t,
+            notes: [],
+            created: t,
+            updated: t,
+            ...(opts.task ? { task: opts.task.id } : {}),
+            ...(opts.research ?? opts.task?.research ? { research: (opts.research ?? opts.task?.research) } : {}),
+            ...(opts.runner ? { runner: opts.runner } : {}),
+            ...(isWorkerId(tree.env.STROM_WORKER) ? { worker: tree.env.STROM_WORKER } : {}),
+            ...(agent ? { agent } : {}),
+        };
+        tree.put(s, { op: "session.start", targets: [s.id, ...(task ? [task.id] : [])], summary: `${s.id} session started${task ? ` on ${task.id}` : ""}` });
+        tree.actor = s.id;
+        if (task && task.state !== "doing") {
+            const doing = { ...task, state: "doing", updated: now() };
+            tree.put(doing, { op: "task.start", targets: [doing.id, s.id], summary: `${doing.id} start` });
+        }
+        setCurrent(tree, s.id);
+        return s;
+    });
+}
+export function sessionNote(tree, s, text) {
+    return tree.withTreeLock(() => {
+        const next = { ...s, notes: [...s.notes, makeNote(tree, text)], updated: now() };
+        tree.put(next, { op: "session.note", targets: [s.id], summary: `${s.id} note: ${text.slice(0, 60)}` });
+        return next;
+    });
+}
+/** Close a session. The task must not be left "doing" — done, parked, waiting, or explicitly continued. */
+export function closeSession(tree, s, input) {
+    if (!input.interrupted && (!input.summary.trim() || !input.next.trim()))
+        throw new UsageError("closing needs --summary and --next", { hint: 'e.g. --summary "found the baptism, parents Josef and Marie" --next "marriage of Josef ~1898 in B0002"' });
+    return tree.withTreeLock(() => {
+        s = tree.get(s.id) ?? s;
+        const task = s.task ? tree.get(s.task) : undefined;
+        if (task && task.state === "doing") {
+            if (!input.continueTask && !input.interrupted)
+                throw new UsageError(`task ${task.id} is still in progress`, {
+                    hint: `close it first: strom task done ${task.id} --result "…" | task park | task wait — or keep it for the next session: --continue`,
+                });
+            const back = { ...task, state: "open", notes: [...task.notes, makeNote(tree, `${input.interrupted ? "interrupted" : "continued"} in ${s.id}: ${input.next || "(no handover)"}`.slice(0, 500))], updated: now() };
+            tree.put(back, { op: "task.continue", targets: [task.id, s.id], summary: `${task.id} back to the queue` });
+        }
+        const closed = {
+            ...s,
+            state: input.interrupted ? "interrupted" : "closed",
+            ended: now(),
+            updated: now(),
+            ...(input.summary.trim() ? { summary: input.summary.trim() } : {}),
+            ...(input.next.trim() ? { next: input.next.trim() } : {}),
+            ...(input.metrics ? { metrics: input.metrics } : {}),
+            ...(input.endedBy ? { endedBy: input.endedBy } : {}),
+        };
+        tree.put(closed, { op: "session.close", targets: [s.id], summary: `${s.id} ${closed.state}: ${(input.summary || "no summary").slice(0, 80)}` });
+        // Only the session this agent calls its current one is forgotten — not another agent's.
+        if (currentSession(tree, tree.env)?.id === s.id)
+            setCurrent(tree, undefined);
+        return closed;
+    });
+}
+/** The last closed sessions (newest first), optionally of one research. */
+export function recentSessions(tree, research, n = 2) {
+    return tree
+        .list("session")
+        .filter((s) => s.state !== "open" && (!research || !s.research || s.research === research))
+        .sort((a, b) => (b.ended ?? b.updated).localeCompare(a.ended ?? a.updated))
+        .slice(0, n);
+}

package/dist/core/shortcut.js

@@ -0,0 +1,90 @@
+// A "Strom research" shortcut on the desktop: a double-click opens a terminal
+// window with strom's menu — for users who never type a command.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { desktopDir, userHome } from "./paths.js";
+import { stromLauncher } from "./self.js";
+/** Make (or refresh) the shortcut; returns the files written. */
+export function createShortcut(name, env, platform = process.platform) {
+    const { command, args } = stromLauncher();
+    const run = [command, ...args].map((a) => `"${a}"`).join(" ");
+    const desktop = desktopDir(env, platform);
+    fs.mkdirSync(desktop, { recursive: true });
+    if (platform === "darwin") {
+        // A .command file opens in Terminal on a double-click.
+        const file = path.join(desktop, `${name}.command`);
+        fs.writeFileSync(file, `#!/bin/sh\ncd "$HOME"\nexec ${run}\n`, { mode: 0o755 });
+        fs.chmodSync(file, 0o755);
+        return [file];
+    }
+    if (platform === "win32") {
+        // chcp 65001: the console shows diacritics; the window stays when strom ends with an error.
+        const file = path.join(desktop, `${name}.cmd`);
+        fs.writeFileSync(file, `@echo off\r\nchcp 65001 >nul\r\ncd /d "%USERPROFILE%"\r\n${run}\r\nif errorlevel 1 pause\r\n`);
+        return [file];
+    }
+    // Linux: an entry in the applications menu, and the same on the desktop.
+    const entry = [
+        "[Desktop Entry]",
+        "Type=Application",
+        `Name=${name}`,
+        `Exec=${run}`,
+        "Terminal=true",
+        "Categories=Office;",
+        "",
+    ].join("\n");
+    const apps = path.join(env.XDG_DATA_HOME ?? path.join(userHome(env), ".local", "share"), "applications");
+    fs.mkdirSync(apps, { recursive: true });
+    const files = [path.join(apps, "strom-research.desktop"), path.join(desktop, "strom-research.desktop")];
+    for (const f of files)
+        fs.writeFileSync(f, entry, { mode: 0o755 });
+    return files;
+}
+/**
+ * Run strom with these arguments in a new terminal window, in this folder — an
+ * agent hands the research over to its own conversation (strom chat) without
+ * starting one inside itself. strom's own settings from the environment go
+ * along (another config folder, language, …), an agent's marks do not.
+ * False when this computer cannot open a window (or a test asks not to).
+ */
+export function openInNewTerminal(argv, cwd, env, platform = process.platform) {
+    if (env.STROM_NO_OPEN === "1")
+        return false;
+    const { command, args } = stromLauncher();
+    const skip = new Set(["STROM_WORKER", "STROM_SESSION", "STROM_NONINTERACTIVE"]);
+    const own = Object.entries(env).filter(([k, v]) => k.startsWith("STROM_") && !skip.has(k) && v !== undefined);
+    const dir = path.join(cwd, ".strom", "open");
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = Date.now().toString(36);
+    if (platform === "win32") {
+        const q = (a) => `"${a.replace(/"/g, '""')}"`;
+        const file = path.join(dir, `strom-${stamp}.cmd`);
+        const lines = ["@echo off", "chcp 65001 >nul", ...own.map(([k, v]) => `set "${k}=${v}"`), `cd /d ${q(cwd)}`, [command, ...args, ...argv].map(q).join(" "), "if errorlevel 1 pause", ""];
+        fs.writeFileSync(file, lines.join("\r\n"));
+        const r = spawn(env.ComSpec ?? "cmd.exe", ["/d", "/c", "start", '""', file], { detached: true, stdio: "ignore", windowsHide: true });
+        r.on("error", () => undefined);
+        r.unref();
+        return true;
+    }
+    const q = (a) => `'${a.replace(/'/g, `'\\''`)}'`;
+    const file = path.join(dir, `strom-${stamp}.command`);
+    const body = ["#!/bin/sh", ...own.map(([k, v]) => `export ${k}=${q(v)}`), `cd ${q(cwd)}`, `exec ${[command, ...args, ...argv].map(q).join(" ")}`, ""];
+    fs.writeFileSync(file, body.join("\n"), { mode: 0o755 });
+    fs.chmodSync(file, 0o755);
+    // macOS: a .command file opens in Terminal. Linux: the desktop's terminal, when there is one.
+    const how = platform === "darwin"
+        ? [["open", [file]]]
+        : env.DISPLAY || env.WAYLAND_DISPLAY
+            ? [["x-terminal-emulator", ["-e", file]], ["gnome-terminal", ["--", file]], ["konsole", ["-e", file]], ["xterm", ["-e", file]]]
+            : [];
+    for (const [cmd, a] of how) {
+        if (platform !== "darwin" && spawnSync("sh", ["-c", `command -v ${cmd}`], { stdio: "ignore" }).status !== 0)
+            continue;
+        const r = spawn(cmd, a, { detached: true, stdio: "ignore", env: env });
+        r.on("error", () => undefined);
+        r.unref();
+        return true;
+    }
+    return false;
+}