strom-research 1.0.0

package/dist/core/check.js

@@ -0,0 +1,112 @@
+// `strom check` — does the evidence hold together? Findings are either
+// errors (block the automatic commit) or warnings.
+import fs from "node:fs";
+import path from "node:path";
+import { RECORD_TYPES } from "./model.js";
+import { recordRefs, validateRecord } from "./validate.js";
+import { readJson, readJsonIfExists } from "./json.js";
+import { Tree, prefixOf } from "./tree.js";
+import { isBirthFamily } from "./people.js";
+export function check(tree) {
+    const out = [];
+    const seen = new Map();
+    // 1. every file parses, is valid, and its name matches its ID
+    for (const [type, def] of Object.entries(RECORD_TYPES)) {
+        const dir = path.join(tree.dataDir, def.dir);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of fs.readdirSync(dir).sort()) {
+            if (!f.endsWith(".json"))
+                continue;
+            const file = tree.relative(path.join(dir, f));
+            let rec;
+            try {
+                rec = readJson(path.join(dir, f));
+            }
+            catch (err) {
+                out.push({ level: "error", code: "json", file, message: err.message });
+                continue;
+            }
+            if (rec.id !== f.slice(0, -5))
+                out.push({ level: "error", code: "file-name", file, message: `file name does not match id ${rec.id}` });
+            if (rec.type !== type)
+                out.push({ level: "error", code: "wrong-dir", file, message: `record of type ${rec.type} in ${def.dir}/` });
+            for (const p of validateRecord(rec))
+                out.push({ level: "error", code: "schema", id: rec.id, file, message: `${p.path} ${p.message}` });
+            if (rec.id) {
+                if (seen.has(rec.id))
+                    out.push({ level: "error", code: "duplicate-id", id: rec.id, message: `also in ${seen.get(rec.id)}` });
+                seen.set(rec.id, file);
+            }
+        }
+    }
+    // 2. references point to existing records
+    const persons = tree.list("person");
+    const families = tree.list("family");
+    for (const type of Object.keys(RECORD_TYPES))
+        for (const rec of tree.list(type))
+            for (const ref of recordRefs(rec))
+                if (!tree.get(ref.id))
+                    out.push({ level: "error", code: "dangling", id: rec.id, message: `${ref.path} → ${ref.id} does not exist` });
+    // 3. a child belongs to at most one birth family
+    const birthFamily = new Map();
+    for (const f of families.filter((x) => !x.retracted))
+        for (const c of f.children) {
+            if (!isBirthFamily(f, c.person))
+                continue;
+            const prev = birthFamily.get(c.person);
+            if (prev)
+                out.push({ level: "error", code: "two-birth-families", id: c.person, message: `child of both ${prev} and ${f.id}` });
+            else
+                birthFamily.set(c.person, f.id);
+        }
+    // 4. event IDs are unique across the tree
+    const eventOwner = new Map();
+    for (const r of [...persons, ...families])
+        for (const e of r.events) {
+            const prev = eventOwner.get(e.id);
+            if (prev)
+                out.push({ level: "error", code: "duplicate-id", id: e.id, message: `event in both ${prev} and ${r.id}` });
+            eventOwner.set(e.id, r.id);
+        }
+    // 5. a proven fact beside an open conflict about the same person: the proof is not finished (GPS)
+    for (const x of tree.list("conflict").filter((c) => c.state === "open"))
+        for (const id of x.subject) {
+            const p = tree.get(id);
+            if (p?.type === "person" && p.events.some((e) => e.status === "proven" && !e.retracted))
+                out.push({ level: "warn", code: "open-conflict", id: x.id, message: `open while ${id} has proven facts — resolve it: strom conflict resolve ${x.id} --resolution … --reasoning …` });
+        }
+    // 5b. a house number written into the place: the place stops matching its books and its other facts
+    for (const owner of [...persons, ...families])
+        for (const e of owner.events) {
+            const m = e.place && !e.retracted ? houseIn(e.place) : undefined;
+            if (m)
+                out.push({
+                    level: "warn",
+                    code: "house-in-place",
+                    id: e.id,
+                    message: `place "${e.place}" holds a house number`,
+                    hint: `strom event edit ${e.id} --place "${m.place}" --house ${m.house} --reason "the house number out of the place"`,
+                });
+        }
+    // 6. counters are ahead of every ID on disk
+    const counters = readJsonIfExists(path.join(tree.dataDir, "_counters.json")) ?? {};
+    for (const id of [...seen.keys(), ...eventOwner.keys()]) {
+        const prefix = prefixOf(id);
+        if (!prefix)
+            continue;
+        if ((counters[prefix] ?? 0) < Number(id.slice(1)))
+            out.push({ level: "warn", code: "counter", id, message: `counter ${prefix} is behind existing IDs (it self-heals on next write)` });
+    }
+    return out;
+}
+export function hasErrors(findings) {
+    return findings.some((f) => f.level === "error");
+}
+/** "Vavřinec čp. 13", "Týnec, Haus-Nr. 5", "Oakham No. 12" → the settlement and the house. */
+export function houseIn(place) {
+    const m = /^(.*?)[\s,]+(?:č\.\s?p\.?|čp\.?|č\.\s?d\.?|c\.\s?p\.?|cp\.|Haus-?\s?N(?:r|ro)\.?|Nr\.|No\.|house\s+(?:No\.?)?|dům\s+(?:č\.)?)\s*(\d+[\w/-]*)\s*$/iu.exec(place.trim());
+    if (!m || !m[1].trim())
+        return undefined;
+    return { place: m[1].trim().replace(/,$/, ""), house: m[2] };
+}

package/dist/core/chromium.js

@@ -0,0 +1,88 @@
+// A browser that lets the Strom app reach strom on this computer. The app is a
+// web page (https://stromapp.info); it takes a research from strom's bridge on
+// 127.0.0.1. Chrome, Edge and the other Chromium browsers allow that; Safari
+// does not (and Firefox is not proven), so strom opens the research in a
+// Chromium browser when there is one — never in whatever is the default — and
+// otherwise shows the file to drag into the app's window.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { userHome } from "./paths.js";
+import { which } from "./which.js";
+const BROWSERS = [
+    { name: "Google Chrome", mac: "Google Chrome.app", win: ["Google\\Chrome\\Application\\chrome.exe"], linux: ["google-chrome", "google-chrome-stable"] },
+    { name: "Microsoft Edge", mac: "Microsoft Edge.app", win: ["Microsoft\\Edge\\Application\\msedge.exe"], linux: ["microsoft-edge", "microsoft-edge-stable"] },
+    { name: "Brave", mac: "Brave Browser.app", win: ["BraveSoftware\\Brave-Browser\\Application\\brave.exe"], linux: ["brave-browser", "brave"] },
+    { name: "Chromium", mac: "Chromium.app", win: ["Chromium\\Application\\chrome.exe"], linux: ["chromium", "chromium-browser"] },
+    { name: "Vivaldi", mac: "Vivaldi.app", win: ["Vivaldi\\Application\\vivaldi.exe"], linux: ["vivaldi", "vivaldi-stable"] },
+    { name: "Arc", mac: "Arc.app", win: [], linux: [] },
+];
+/** A Chromium browser on this computer, the most common first. STROM_APP_DIRS: folders to look in instead (tests). */
+export function chromiumBrowser(env, platform = process.platform) {
+    const own = env.STROM_APP_DIRS !== undefined ? env.STROM_APP_DIRS.split(path.delimiter).filter(Boolean) : undefined;
+    for (const b of BROWSERS) {
+        if (platform === "darwin") {
+            for (const d of own ?? ["/Applications", path.join(userHome(env), "Applications")])
+                if (fs.existsSync(path.join(d, b.mac)))
+                    return { name: b.name, path: path.join(d, b.mac) };
+        }
+        else if (platform === "win32") {
+            const roots = own ?? [env.LOCALAPPDATA, env.ProgramFiles, env["ProgramFiles(x86)"]].filter((r) => Boolean(r));
+            for (const root of roots)
+                for (const rel of b.win) {
+                    const exe = own ? path.join(root, path.win32.basename(rel)) : path.join(root, rel);
+                    if (fs.existsSync(exe))
+                        return { name: b.name, path: exe };
+                }
+        }
+        else {
+            for (const cmd of b.linux) {
+                const hit = own ? own.map((d) => path.join(d, cmd)).find((f) => fs.existsSync(f)) : which(cmd, env, platform);
+                if (hit)
+                    return { name: b.name, path: hit };
+            }
+        }
+    }
+    return undefined;
+}
+function launch(cmd, args, env) {
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true, env: env });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Open an address in that browser; false when this computer cannot (no desktop) or tests ask not to. */
+export function openInBrowser(browser, url, env, platform = process.platform) {
+    if (env.STROM_NO_OPEN === "1")
+        return false;
+    if (platform === "darwin")
+        return launch("open", ["-a", browser.path, url], env);
+    if (platform === "win32")
+        return launch(browser.path, [url], env);
+    if (!env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return false;
+    return launch(browser.path, [url], env);
+}
+/** Open a file with an app (the installed Strom app takes a .ged through its file handler) — macOS. */
+export function openFileWith(app, file, env, platform = process.platform) {
+    if (env.STROM_NO_OPEN === "1" || platform !== "darwin")
+        return false;
+    return launch("open", ["-a", app, file], env);
+}
+/** Show a file in Finder / Explorer / the file manager, selected where the system can. */
+export function revealFile(file, env, platform = process.platform) {
+    if (env.STROM_NO_OPEN === "1")
+        return false;
+    if (platform === "darwin")
+        return launch("open", ["-R", file], env);
+    if (platform === "win32")
+        return launch("explorer.exe", [`/select,${file}`], env);
+    if (!env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return false;
+    return launch("xdg-open", [path.dirname(file)], env);
+}

package/dist/core/config.js

@@ -0,0 +1,348 @@
+// User configuration and setting resolution.
+//
+// Every setting is resolved in one order: command flag > environment variable
+// > the tree (strom.json) > the user config > a derived default. Settings a
+// tree can carry are marked `tree`. If a required setting is still missing,
+// the caller asks the user (TTY) or fails with NeedsInputError (no TTY).
+import path from "node:path";
+import { configDir, defaultHome, expandHome } from "./paths.js";
+import { readJsonIfExists, writeJson } from "./json.js";
+import { detectLang, isValidLang } from "./lang.js";
+import { UsageError } from "./errors.js";
+import { DEFAULT_AGENT, PROFILES, TIERS } from "../agents/profiles.js";
+import { STRATEGIES } from "./model.js";
+import { downloadsDir } from "./browser.js";
+import { acquireLock } from "./lock.js";
+export const PERMISSION_LEVELS = ["ask", "auto", "full"];
+/** Earlier names of the levels, still understood. */
+const PERMISSION_ALIASES = { list: "auto", bypass: "full" };
+export const DEFAULT_BUDGET = 25_000;
+export const DEFAULT_RUN_MINUTES = 60;
+export const SETTINGS = [
+    { key: "home", env: "STROM_HOME", tree: false, kind: "path", description: "folder with the trees and shared data" },
+    { key: "shared", env: "STROM_SHARED", tree: false, kind: "path", description: "shared data: scans, catalog, tools (default <home>/shared)" },
+    { key: "trees", env: "STROM_TREES", tree: false, kind: "path", description: "folder holding the trees (default <home>)" },
+    { key: "lang", env: "STROM_LANG", tree: true, kind: "lang", description: "research language: the agent talks and writes in it" },
+    { key: "agent", env: "STROM_AGENT", tree: true, kind: "agent", description: "AI agent doing the research: claude, codex, antigravity, opencode" },
+    ...TIERS.map((t) => ({
+        key: `model.${t}`,
+        env: t === "lead" ? "STROM_MODEL" : `STROM_MODEL_${t.toUpperCase()}`,
+        tree: true,
+        kind: "model",
+        description: {
+            lead: "model of the main researcher (default: the agent's own)",
+            vision: "model for handwriting and scans — never weaker than lead",
+            text: "model for print, catalogues, web pages",
+            cheap: "model for mechanical work",
+        }[t],
+    })),
+    { key: "brief.budget", env: "STROM_BRIEF_BUDGET", tree: true, kind: "number", description: `size of the brief in tokens (default ${DEFAULT_BUDGET})` },
+    { key: "run.minutes", env: "STROM_RUN_MINUTES", tree: true, kind: "number", description: `time limit of one \`strom run\` session (default ${DEFAULT_RUN_MINUTES})` },
+    { 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: "strom.version", env: "STROM_APP_VERSION", tree: true, kind: "version", description: "version of the Strom app the Strom GEDCOM is for (set by the app)" },
+    { key: "connectors.consent", env: "STROM_CONNECTORS_CONSENT", tree: false, kind: "choice", choices: ["off", "on"], description: "off (default): connectors run without asking — paced by strom, only to their hosts; on: each needs the user's yes, in their terminal, to it and to each archive host" },
+    { key: "browser.downloads", env: "STROM_BROWSER_DOWNLOADS", tree: false, kind: "path", description: "the folder your browser saves downloads into (default: the system's Downloads folder) — strom takes a connector's images over from there" },
+    // Read from the config file only — no variable, no flag, no tree: nothing an agent can set.
+    { key: "agent.permissions", env: "", tree: false, kind: "choice", choices: PERMISSION_LEVELS, description: "what the agent may do without asking you: ask (what the tree allows; anything else it asks), auto (default: what the tree allows; anything else the agent's own review decides, asking only when risky), full (everything but what the tree denies) — only you raise it" },
+    { key: "agent.where", env: "STROM_AGENT_WHERE", tree: false, kind: "choice", choices: ["app", "terminal"], description: "where you talk with the agent: app (its desktop app — the easiest), terminal (its CLI) — unset: the app when it is installed" },
+    { key: "updates", env: "STROM_UPDATES", tree: false, kind: "choice", choices: ["check", "off"], description: "look for new versions of strom: check (default — at most once a day, one small file from the project's releases; strom says so, strom update installs it) or off" },
+    { key: "strom.app", env: "", tree: false, kind: "choice", choices: ["yes", "no"], description: "you use the Strom app: yes (strom says which file to import into it), no (strom never mentions it) — unset: strom notices it itself" },
+];
+/** Fields of the stored settings whose key is not the field name. */
+const FIELDS = {
+    "brief.budget": "briefBudget",
+    "run.minutes": "runMinutes",
+    "gedcom.for": "gedcomFor",
+    "strom.version": "stromVersion",
+    "queue.strategy": "queueStrategy",
+    "connectors.consent": "connectorsConsent",
+    "browser.downloads": "browserDownloads",
+    "agent.permissions": "agentPermissions",
+    "agent.where": "agentWhere",
+    "strom.app": "stromApp",
+};
+/** Environment variables that are not settings but steer strom. */
+export const OTHER_ENV = [
+    { env: "STROM_TREE", description: "the tree to work on (a folder or a tree name)" },
+    { env: "STROM_CONFIG_DIR", description: "where the user config and seal keys live" },
+    { env: "STROM_NONINTERACTIVE", description: "1 = never ask, fail with needs-input instead" },
+    { env: "STROM_DOCUMENTS", description: "the Documents folder, where strom suggests its home (default: the system's)" },
+    { env: "STROM_APP_URL", description: "another copy of the Strom app to open (its development: http://127.0.0.1:8080/)" },
+    { env: "STROM_APP", description: "set by the Strom app when it starts strom (or an agent for it): strom then knows the app is there" },
+];
+export function settingDef(key) {
+    const def = SETTINGS.find((s) => s.key === key);
+    if (!def)
+        throw new UsageError(`unknown setting "${key}"`, { hint: `settings: ${SETTINGS.map((s) => s.key).join(", ")}` });
+    return def;
+}
+export function configFile(env) {
+    return path.join(configDir(env), "config.json");
+}
+export function loadUserConfig(env) {
+    return readJsonIfExists(configFile(env)) ?? {};
+}
+export function saveUserConfig(env, cfg) {
+    writeJson(configFile(env), cfg);
+}
+function asPath(value, env) {
+    return path.resolve(expandHome(value, env));
+}
+/** Check and normalise a value for a setting; throws a UsageError with the allowed values. */
+export function checkValue(def, raw, resolvePath) {
+    const v = raw.trim();
+    switch (def.kind) {
+        case "path":
+            return resolvePath(v);
+        case "lang": {
+            const code = v.toLowerCase();
+            if (!isValidLang(code))
+                throw new UsageError(`invalid language code "${raw}"`, { hint: "use a code like cs, en, de" });
+            return code;
+        }
+        case "agent": {
+            const id = v.toLowerCase();
+            if (!PROFILES[id])
+                throw new UsageError(`unknown agent "${raw}"`, { hint: Object.keys(PROFILES).join(", ") });
+            return id;
+        }
+        case "model":
+            if (!v)
+                throw new UsageError("the model name is empty");
+            return v;
+        case "choice": {
+            const c = def.key === "agent.permissions" ? (PERMISSION_ALIASES[v.toLowerCase()] ?? v.toLowerCase()) : v.toLowerCase();
+            if (!def.choices?.includes(c))
+                throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: def.choices?.join(", ") });
+            return c;
+        }
+        case "version":
+            if (!/^\d+(\.\d+){0,2}$/.test(v))
+                throw new UsageError(`invalid ${def.key} "${raw}"`, { hint: "a version like 1.4.0" });
+            return v;
+        case "number": {
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0)
+                throw new UsageError(`${def.key} must be a positive number`);
+            return def.key === "brief.budget" ? Math.round(n) : n;
+        }
+    }
+}
+/** Where a setting is stored in the user config or in strom.json. */
+function readStored(store, key, agent) {
+    if (!store)
+        return undefined;
+    if (key.startsWith("model."))
+        return store.models?.[agent]?.[key.slice(6)];
+    const v = store[FIELDS[key] ?? key];
+    return typeof v === "string" || typeof v === "number" ? v : undefined;
+}
+/** Write (or with undefined, remove) a setting in a store. */
+export function writeStored(store, key, agent, value) {
+    const s = store;
+    if (key.startsWith("model.")) {
+        const tier = key.slice(6);
+        const models = (s.models ??= {});
+        const forAgent = (models[agent] ??= {});
+        if (value === undefined)
+            delete forAgent[tier];
+        else
+            forAgent[tier] = String(value);
+        if (Object.keys(forAgent).length === 0)
+            delete models[agent];
+        if (Object.keys(models).length === 0)
+            delete s.models;
+        return;
+    }
+    const field = FIELDS[key] ?? key;
+    if (value === undefined)
+        delete s[field];
+    else
+        s[field] = value;
+}
+export class Settings {
+    env;
+    flags;
+    config;
+    /** The config as it was read: save() writes only what changed since. */
+    baseline;
+    constructor(env, flags, config) {
+        this.env = env;
+        this.flags = flags;
+        this.config = config ?? loadUserConfig(env);
+        this.baseline = structuredClone(this.config);
+    }
+    /** Read the config file again (another strom process may have changed it). */
+    reload() {
+        this.replace(loadUserConfig(this.env));
+    }
+    /** Take these values in place: whoever holds `config` sees them. */
+    replace(next) {
+        const cur = this.config;
+        for (const k of Object.keys(cur))
+            delete cur[k];
+        Object.assign(cur, next);
+        this.baseline = structuredClone(this.config);
+    }
+    flagOf(key) {
+        if (key === "model.lead")
+            return this.flags.model;
+        if (key === "brief.budget")
+            return this.flags.budget;
+        if (key === "run.minutes")
+            return this.flags.minutes;
+        return this.flags[key];
+    }
+    /**
+     * Resolve any setting: flag > env > tree > user config. Undefined when none
+     * of them has it (the caller applies its default). Model keys resolve for
+     * `agent` (default: the resolved agent).
+     */
+    resolve(key, tree, agent) {
+        const def = settingDef(key);
+        if (key === "agent")
+            return this.agent(tree);
+        const who = agent ?? (def.kind === "model" ? this.agent(tree).value : "");
+        const check = (raw) => checkValue(def, raw, (p) => asPath(p, this.env));
+        const flag = this.flagOf(key);
+        if (flag)
+            return { value: check(flag), source: "flag" };
+        const env = def.env ? this.env[def.env] : undefined;
+        if (env)
+            return { value: check(env), source: "env" };
+        if (def.tree) {
+            const t = readStored(tree, key, who);
+            if (t !== undefined)
+                return { value: t, source: "tree" };
+        }
+        const u = readStored(this.config, key, who);
+        if (u !== undefined)
+            return { value: def.kind === "path" ? asPath(String(u), this.env) : u, source: "config" };
+        return undefined;
+    }
+    /** Home, or undefined when nothing is configured (the caller asks). */
+    home() {
+        return this.resolve("home");
+    }
+    suggestedHome() {
+        return defaultHome(this.env);
+    }
+    shared() {
+        const r = this.resolve("shared");
+        if (r)
+            return r;
+        const home = this.home();
+        return home ? { value: path.join(home.value, "shared"), source: "default" } : undefined;
+    }
+    trees() {
+        const r = this.resolve("trees");
+        if (r)
+            return r;
+        const home = this.home();
+        return home ? { value: home.value, source: "default" } : undefined;
+    }
+    /** Research language: flag > STROM_LANG > the tree > the user's default > detected from the system. */
+    lang(tree) {
+        return this.resolve("lang", tree) ?? { value: detectLang(this.env), source: "detected" };
+    }
+    /** Which agent does the research: flag > STROM_AGENT > tree > user > default. */
+    agent(tree) {
+        // Flags and env are not checked here: `strom run` says which agents it can
+        // drive (it also knows the test runner "script").
+        const r = this.agentAsSaid(tree);
+        // Gemini CLI ended for personal accounts (2026): Google's agent is Antigravity now.
+        return r.value === "gemini" ? { ...r, value: "antigravity" } : r;
+    }
+    agentAsSaid(tree) {
+        const f = this.flags.agent;
+        if (f)
+            return { value: f.toLowerCase(), source: "flag" };
+        const env = this.env.STROM_AGENT;
+        if (env)
+            return { value: env.toLowerCase(), source: "env" };
+        if (tree?.agent)
+            return { value: tree.agent, source: "tree" };
+        if (this.config.agent)
+            return { value: this.config.agent, source: "config" };
+        return { value: DEFAULT_AGENT, source: "default" };
+    }
+    /** Model per tier for an agent: profile defaults < user config < tree < env < flag. */
+    models(agent, tree) {
+        const out = { ...(PROFILES[agent]?.models ?? {}) };
+        for (const t of TIERS) {
+            const r = this.resolve(`model.${t}`, tree, agent);
+            if (r)
+                out[t] = String(r.value);
+        }
+        return out;
+    }
+    number(key, tree, fallback) {
+        const r = this.resolve(key, tree);
+        return r ? Number(r.value) : fallback;
+    }
+    /** How the task queue is ordered (core/queue.ts). */
+    strategy(tree) {
+        return String(this.resolve("queue.strategy", tree)?.value ?? "balanced");
+    }
+    /** The GEDCOM files to write: standard (any program), strom (the Strom app), or both. */
+    gedcomFor(tree) {
+        const v = String(this.resolve("gedcom.for", tree)?.value ?? "both");
+        return v === "both" ? ["standard", "strom"] : [v];
+    }
+    /** Does a connector need the user's consent before it runs? (Off unless they turned it on.) */
+    connectorsConsent() {
+        return this.resolve("connectors.consent")?.value === "on";
+    }
+    /** The folder the browser saves downloads into: the setting, else the system's Downloads folder. */
+    downloads() {
+        return String(this.resolve("browser.downloads")?.value ?? downloadsDir(this.env));
+    }
+    /** Where the user wants to talk with the agent, if they said (env, else the config); see whereToTalk. */
+    agentWhere() {
+        const r = this.resolve("agent.where");
+        return r ? String(r.value) : undefined;
+    }
+    /** What the agent may do without asking — from the config file alone, which only the user raises. */
+    agentPermissions() {
+        const v = this.config.agentPermissions ?? "auto";
+        return PERMISSION_ALIASES[v] ?? (PERMISSION_LEVELS.includes(v) ? v : "auto");
+    }
+    /** Stories of the ancestors: on unless the user said no; `said` — they chose (else they are to be told). */
+    stories(tree) {
+        const v = this.resolve("stories", tree)?.value;
+        return { on: v !== "no", said: v === "yes" || v === "no" };
+    }
+    stromVersion(tree) {
+        const r = this.resolve("strom.version", tree);
+        return r ? String(r.value) : undefined;
+    }
+    /**
+     * Write what this process changed — only that, onto the file as it is now:
+     * several strom processes run side by side (the menu, a conversation with an
+     * agent, a run) and none may wipe out what another saved meanwhile.
+     */
+    save() {
+        const file = configFile(this.env);
+        const release = acquireLock(`${file}.lock`, { owner: "strom config", waitMs: 10_000, staleMs: 60_000 });
+        try {
+            const fresh = loadUserConfig(this.env);
+            const mine = this.config;
+            const before = this.baseline;
+            for (const k of new Set([...Object.keys(before), ...Object.keys(mine)])) {
+                if (JSON.stringify(before[k]) === JSON.stringify(mine[k]))
+                    continue;
+                if (mine[k] === undefined)
+                    delete fresh[k];
+                else
+                    fresh[k] = mine[k];
+            }
+            saveUserConfig(this.env, fresh);
+            this.replace(fresh);
+        }
+        finally {
+            release();
+        }
+    }
+}