@naswerks/periscope 1.0.0

package/dist/host/claude-transcripts.js

@@ -0,0 +1,339 @@
+/**
+ * The discovery door: read-only enumeration and tail-probing of the agent CLI's own transcript
+ * directory, `~/.claude/projects`.
+ *
+ * The posture, stated once because it is the whole design. This host names `~/.claude` in one
+ * other place, `host/paths.ts`, to protect it from the sessions it runs. That protection is about
+ * the agent's hands; this module is the host's own eyes, a deliberate read-only capability over a
+ * directory every Claude session on the machine writes into (a VS Code session and a session this
+ * host started land side by side). The two postures do not touch: nothing here weakens the gate,
+ * and nothing here can write.
+ *
+ * Read-only is a property, not a promise. The module's filesystem surface is exactly
+ * `createReadStream`, `readdir` and `stat`; no write-capable API is imported, and
+ * `src/pins/transcript-readonly.test.ts` holds the import surface to that allowlist.
+ *
+ * The jail: three layers, all three always, for every caller-supplied name:
+ *   1. the strict name allowlist (`NAME_ALLOWLIST`);
+ *   2. an explicit `'.'` / `'..'` reject — dot-names PASS the regex, so this layer is load-bearing;
+ *   3. resolve-then-containment — the real resolver first, then `isContainedBy` against the root,
+ *      so a name the first two layers somehow admitted still cannot shape a path outside it.
+ * A violation refuses `transcript-path-escape`, naming the layer. An ABSENT transcript is a value,
+ * never a refusal: a missing projects directory is a fresh machine and lists as empty.
+ *
+ * The rewrite hazard: the CLI rewrites a transcript on compaction,
+ * so a byte-offset resume across a rewrite is invalid. Every answer that carries an offset also
+ * carries the file's current (size, mtime) pair; a caller that sees either move under it re-reads
+ * whole rather than resuming. A file SHORTER than the asked offset is treated as rewritten and
+ * scanned from 0.
+ *
+ * Project slugs are OPAQUE NAMES, never decoded: the CLI flattens every non-alphanumeric character
+ * of a directory path to `-` (on win32 `C:\src\x\.y` becomes `C--src-x--y`), so the
+ * mapping is not invertible and nothing here tries.
+ */
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { ok, refuse } from '../core/result.js';
+import { isContainedBy, normalizePath } from '../core/paths.js';
+import { TRANSCRIPT_PAGE_SIZE, TRANSCRIPT_WHAT_PREFIX } from '../control/frames.js';
+import { nodePathResolver } from './paths.js';
+/**
+ * The strict name allowlist — drive/path characters only. `'.'` and `'..'` PASS this regex, which
+ * is exactly why the dot-name reject below is its own layer rather than a tightening of this one.
+ */
+export const NAME_ALLOWLIST = /^[A-Za-z0-9._-]+$/;
+/**
+ * The agent's home when nothing configures one: the folder the agent CLI keeps its state in, under
+ * the user's home directory. Null when there is no home to derive it from — a refusable state,
+ * never a fallback: inventing one would turn "this machine has no home directory" into a silent
+ * empty listing that reads as a fresh machine.
+ */
+export function defaultAgentHome(env = process.env) {
+    const home = env['USERPROFILE'] ?? env['HOME'];
+    if (typeof home === 'string' && home.trim() !== '') {
+        return normalizePath(`${home.replace(/[\\/]+$/, '')}/.claude`);
+    }
+    return null;
+}
+/** Where the agent CLI keeps transcripts under its home: derived, never configured on its own. */
+export function transcriptsRootUnder(agentHome) {
+    return normalizePath(`${agentHome.replace(/[\\/]+$/, '')}/projects`);
+}
+/** The transcripts root under the default agent home, or null when there is no home. */
+export function claudeProjectsRoot(env = process.env) {
+    const home = defaultAgentHome(env);
+    return home === null ? null : transcriptsRootUnder(home);
+}
+/** How much of a transcript's head is read for its `cwd` — the first entries, never the file. */
+const CWD_HEAD_BYTES = 64 * 1024;
+/**
+ * The first `cwd` string on the file's first entries, or null. A summary line carries none; the first
+ * user or assistant entry does. Every failure is null — the listing describes files, it does not refuse
+ * over one of them.
+ */
+async function readTranscriptCwd(path) {
+    let head = '';
+    try {
+        for await (const chunk of createReadStream(path, {
+            start: 0,
+            end: CWD_HEAD_BYTES - 1,
+            encoding: 'utf8',
+        })) {
+            head += chunk;
+        }
+    }
+    catch {
+        return null;
+    }
+    for (const line of head.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const entry = JSON.parse(trimmed);
+            if (typeof entry === 'object' &&
+                entry !== null &&
+                typeof entry.cwd === 'string') {
+                const cwd = entry.cwd;
+                if (cwd.length > 0)
+                    return cwd;
+            }
+        }
+        catch {
+            // a partial last line inside the window, or a non-JSON line — keep looking
+        }
+    }
+    return null;
+}
+/**
+ * THE JAIL. Resolve `{root}/{projectSlug}/{sessionId}.jsonl` with all three layers applied to both
+ * caller-supplied names. The one path-shaping function in this module — list, tail and the bulk
+ * resolver all come through here, so there is no second door to keep honest.
+ */
+export function resolveTranscriptPath(root, projectSlug, sessionId) {
+    for (const [value, what] of [
+        [projectSlug, 'projectSlug'],
+        [sessionId, 'sessionId'],
+    ]) {
+        if (value === '.' || value === '..') {
+            return refuse('transcript-path-escape', `${what} is a dot-name — refused by the dot-name layer`);
+        }
+        if (!NAME_ALLOWLIST.test(value)) {
+            return refuse('transcript-path-escape', `${what} fails the name allowlist — refused by the allowlist layer`);
+        }
+    }
+    const resolvedRoot = normalizePath(nodePathResolver(root));
+    const candidate = normalizePath(nodePathResolver(`${resolvedRoot}/${projectSlug}/${sessionId}.jsonl`));
+    if (!isContainedBy(candidate, resolvedRoot)) {
+        return refuse('transcript-path-escape', `the resolved path leaves the projects root — refused by the containment layer`);
+    }
+    return ok(candidate);
+}
+/**
+ * Enumerate every session transcript: direct-child `*.jsonl` per slug directory (nested files are
+ * the CLI's subagent transcripts and are not part of this listing). Newest first by mtime, paged.
+ * A missing root is a fresh machine and answers an empty listing, never an error; a file deleted
+ * between readdir and stat is skipped for the same reason.
+ */
+export async function listTranscripts(root, page = {}) {
+    const fromIndex = Math.max(0, page.fromIndex ?? 0);
+    const pageSize = Math.max(1, page.pageSize ?? TRANSCRIPT_PAGE_SIZE);
+    const resolvedRoot = normalizePath(nodePathResolver(root));
+    let slugDirs;
+    try {
+        slugDirs = (await readdir(resolvedRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory() && NAME_ALLOWLIST.test(entry.name) && entry.name !== '.' && entry.name !== '..');
+    }
+    catch {
+        return { entries: [], totalCount: 0, nextIndex: null };
+    }
+    const all = [];
+    for (const slugDir of slugDirs) {
+        let files;
+        try {
+            files = await readdir(`${resolvedRoot}/${slugDir.name}`, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.isFile() || !file.name.endsWith('.jsonl'))
+                continue;
+            const sessionId = file.name.slice(0, -'.jsonl'.length);
+            if (sessionId === '.' || sessionId === '..' || !NAME_ALLOWLIST.test(sessionId))
+                continue;
+            try {
+                const stats = await stat(`${resolvedRoot}/${slugDir.name}/${file.name}`);
+                all.push({
+                    projectSlug: slugDir.name,
+                    sessionId,
+                    sizeBytes: stats.size,
+                    mtimeMs: Math.floor(stats.mtimeMs),
+                });
+            }
+            catch {
+                // Deleted between readdir and stat — the listing describes what exists, not what did.
+            }
+        }
+    }
+    all.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    // The cwd is read for the PAGE only — one head per listed row, never one per file on the machine.
+    const entries = await Promise.all(all.slice(fromIndex, fromIndex + pageSize).map(async (entry) => ({
+        ...entry,
+        cwd: await readTranscriptCwd(`${resolvedRoot}/${entry.projectSlug}/${entry.sessionId}.jsonl`),
+    })));
+    const nextIndex = fromIndex + entries.length;
+    return {
+        entries,
+        totalCount: all.length,
+        nextIndex: nextIndex < all.length ? nextIndex : null,
+    };
+}
+/**
+ * Probe one transcript from `fromOffset` for a user entry matching `needle` (null = any user-text
+ * entry). Jail violations refuse; an absent file answers `{absent: true}`; a read that FAILS is a
+ * refusal (`transcript-read-failed`), never a false negative — to the asker "no new entry" and
+ * "could not look" must not be the same answer.
+ */
+export async function tailTranscript(root, projectSlug, sessionId, probe = {}) {
+    const resolved = resolveTranscriptPath(root, projectSlug, sessionId);
+    if (!resolved.ok)
+        return resolved;
+    let stats;
+    try {
+        stats = await stat(resolved.value);
+    }
+    catch {
+        return ok({ absent: true, found: false, newOffset: 0, sizeBytes: null, mtimeMs: null });
+    }
+    if (!stats.isFile()) {
+        return ok({ absent: true, found: false, newOffset: 0, sizeBytes: null, mtimeMs: null });
+    }
+    const sizeBytes = stats.size;
+    const mtimeMs = Math.floor(stats.mtimeMs);
+    const asked = Math.max(0, probe.fromOffset ?? 0);
+    // A file shorter than the baseline was rewritten (compaction, or a fork replacing it): scan from
+    // the start and let the needle reject stale entries — resuming into a rewritten file would read
+    // from the middle of a line that no longer exists.
+    const start = sizeBytes < asked ? 0 : asked;
+    const needle = probe.needle ?? null;
+    if (start >= sizeBytes) {
+        return ok({ absent: false, found: false, newOffset: sizeBytes, sizeBytes, mtimeMs });
+    }
+    try {
+        const found = await scanForUserEntry(resolved.value, start, sizeBytes, needle);
+        return ok({ absent: false, found, newOffset: sizeBytes, sizeBytes, mtimeMs });
+    }
+    catch (error) {
+        return refuse('transcript-read-failed', `reading ${projectSlug}/${sessionId} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * The bulk-lane resolver for transcript reads: `claude-transcript:{slug}/{sessionId}` to a jailed
+ * absolute path. A locator outside the namespace is refused as an invalid bulk target so an
+ * embedder composing several resolvers can tell "not mine" from "mine and malformed".
+ */
+export function claudeTranscriptResolver(root) {
+    return (what) => {
+        if (!what.startsWith(TRANSCRIPT_WHAT_PREFIX)) {
+            return refuse('bulk-target-invalid', `this host resolves "${TRANSCRIPT_WHAT_PREFIX}{projectSlug}/{sessionId}" locators; got "${what}"`);
+        }
+        const rest = what.slice(TRANSCRIPT_WHAT_PREFIX.length);
+        const slash = rest.indexOf('/');
+        if (slash <= 0 || slash === rest.length - 1) {
+            return refuse('bulk-target-invalid', `a transcript locator is "${TRANSCRIPT_WHAT_PREFIX}{projectSlug}/{sessionId}"; got "${what}"`);
+        }
+        return resolveTranscriptPath(root, rest.slice(0, slash), rest.slice(slash + 1));
+    };
+}
+// ---------------------------------------------------------------------------
+// The user-entry predicate: the rule that decides whether a new user entry landed.
+// ---------------------------------------------------------------------------
+/** Collapse every whitespace run to one space and trim, so needle matching survives reflowing. */
+const normalizeForMatch = (text) => text.replace(/\s+/g, ' ').trim();
+/** A user entry's text: a flat string content, or its concatenated `text` blocks. */
+function userTextOf(message) {
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    let out = '';
+    for (const block of content) {
+        if (block !== null &&
+            typeof block === 'object' &&
+            block.type === 'text' &&
+            typeof block.text === 'string') {
+            out += block.text;
+        }
+    }
+    return out;
+}
+/**
+ * One line: does it count as a matching user entry? Unparseable or foreign lines are skipped,
+ * never thrown — a truncated LAST line is the normal state of a file being appended to. A
+ * tool-result-only user line has no text block and so never matches.
+ */
+export function isMatchingUserEntry(line, needle) {
+    let root;
+    try {
+        root = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    if (root === null || typeof root !== 'object' || Array.isArray(root))
+        return false;
+    if (root.type !== 'user')
+        return false;
+    const message = root.message;
+    if (message === null || typeof message !== 'object' || Array.isArray(message))
+        return false;
+    const role = message.role;
+    if (role !== undefined && role !== 'user')
+        return false;
+    const text = userTextOf(message);
+    if (text.trim().length === 0)
+        return false;
+    if (needle === null || needle === '')
+        return true;
+    return normalizeForMatch(text).includes(needle);
+}
+/**
+ * Read `[start, end)` in chunks with a line carry, so a large transcript never lands in one buffer
+ * and a partial final line is simply the last carry. The final carry is tested too — an
+ * unterminated tail is still a line.
+ */
+function scanForUserEntry(file, start, end, needle) {
+    return new Promise((resolve, reject) => {
+        const stream = createReadStream(file, { start, end: end - 1, encoding: 'utf8' });
+        let carry = '';
+        let found = false;
+        stream.on('data', (chunk) => {
+            if (found)
+                return;
+            const text = carry + String(chunk);
+            const lines = text.split('\n');
+            carry = lines.pop() ?? '';
+            for (const raw of lines) {
+                const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+                if (line.length === 0)
+                    continue;
+                if (isMatchingUserEntry(line, needle)) {
+                    found = true;
+                    stream.destroy();
+                    return;
+                }
+            }
+        });
+        stream.on('error', reject);
+        stream.on('close', () => {
+            if (!found && carry.length > 0) {
+                const line = carry.endsWith('\r') ? carry.slice(0, -1) : carry;
+                if (line.length > 0 && isMatchingUserEntry(line, needle))
+                    found = true;
+            }
+            resolve(found);
+        });
+    });
+}
+//# sourceMappingURL=claude-transcripts.js.map

package/dist/host/config-file.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Every key the config file may carry — the environment variables the composition root reads,
+ * minus `PERISCOPE_CONFIG_DIR` (the bootstrap exclusion above).
+ */
+export declare const CONFIG_KEYS: readonly ["PERISCOPE_CONTROLLER_URL", "PERISCOPE_DECISION_URL", "PERISCOPE_HOST_ID", "PERISCOPE_WORKSPACE_ROOT", "PERISCOPE_REPOSITORY_ROOT", "PERISCOPE_BRANCH_SCHEME", "PERISCOPE_WORKSPACE_KEY", "PERISCOPE_AGENT_HOME"];
+export type ConfigKey = (typeof CONFIG_KEYS)[number];
+/**
+ * The keys a controller may set over the wire (`host_configure`): where this machine's things are,
+ * and where its control plane is. The two URLs are written to the file and never applied to
+ * the live link: the host dials what it dialled until its next start, and names the keys as pending
+ * in its answer and in every hello until then. Never the host id (a paired credential outranks it
+ * anyway) or the default workspace key (a start-up posture, screened at boot).
+ */
+export declare const WIRE_CONFIGURABLE_KEYS: readonly ["PERISCOPE_WORKSPACE_ROOT", "PERISCOPE_REPOSITORY_ROOT", "PERISCOPE_BRANCH_SCHEME", "PERISCOPE_AGENT_HOME", "PERISCOPE_CONTROLLER_URL", "PERISCOPE_DECISION_URL"];
+export type WireConfigurableKey = (typeof WIRE_CONFIGURABLE_KEYS)[number];
+/** The wire-settable keys that take effect only at the next start: the control-plane addresses. */
+export declare const RESTART_KEYS: readonly ["PERISCOPE_CONTROLLER_URL", "PERISCOPE_DECISION_URL"];
+export declare function isWireConfigurableKey(value: string): value is WireConfigurableKey;
+export declare function isConfigKey(value: string): value is ConfigKey;
+/** Where the config file lives, or null when there is nowhere to keep one (no home, no override). */
+export declare function configFilePath(env?: NodeJS.ProcessEnv): string | null;
+/** What a read found: the values, or the named problem that makes them unusable. */
+export interface ConfigFileReading {
+    readonly values: Readonly<Record<string, string>>;
+    /** Null when the file is usable (a missing file is usable: it reads as empty). */
+    readonly problem: string | null;
+}
+/**
+ * Read the config file. A MISSING file is `{}` — the ordinary state of every machine that has
+ * never run `periscope config`. A file that exists and cannot be used is a PROBLEM, never a silent
+ * empty: falling back would make a corrupt file behave like a deliberate absence, which is the
+ * exact ambiguity the paired credential's fatal-on-corrupt posture exists to end.
+ */
+export declare function readConfigFile(env?: NodeJS.ProcessEnv): ConfigFileReading;
+/**
+ * Write one entry, creating the directory and file as needed. Returns null, or the named problem.
+ * Refuses an unknown key BEFORE touching the disk — see the closed-set rule in the header.
+ */
+export declare function writeConfigEntry(env: NodeJS.ProcessEnv, key: string, value: string): string | null;
+/** One entry of a multi-key write: a value to set, or null to remove the key. */
+export interface ConfigEntryWrite {
+    readonly key: string;
+    readonly value: string | null;
+}
+/**
+ * Write several entries as one read-modify-write, creating the directory and file as needed.
+ * Returns null, or the named problem. Every key is screened BEFORE the disk is touched, so a set
+ * with one bad key writes nothing; a null value removes its key. The same corrupt-file posture as
+ * the single-entry write: never merged over.
+ */
+export declare function writeConfigEntries(env: NodeJS.ProcessEnv, entries: readonly ConfigEntryWrite[]): string | null;
+/**
+ * The environment, with file values FILLING ABSENCES — the one implementation of "env wins".
+ *
+ * Returns a NEW plain object; the process environment is never mutated. Only the closed key set is
+ * consulted, so nothing outside it (identity configuration, the config dir itself) can arrive from
+ * a file. Empty-string env values count as absent, matching how the composition root reads them.
+ */
+export declare function withConfigFallback(env: NodeJS.ProcessEnv, values: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
+//# sourceMappingURL=config-file.d.ts.map

package/dist/host/config-file.js

@@ -0,0 +1,216 @@
+/**
+ * The config file: the CLI as a first-class writer, so a library user with no UI is not env-only.
+ *
+ * It lives beside the credential files on purpose. `periscopeCredentialDir(env)` is the single
+ * source both the token cache's location and the gate's protected set derive from, so a config file
+ * written under it is protected from the sessions this host runs by having been put there — not by
+ * somebody remembering to add a line. (Nothing in it is secret today; the property costs nothing
+ * and the alternative is a second directory with a second protection question.)
+ *
+ * The environment still wins, per key. The file is a fallback for an absence: a value here is
+ * consulted only when the same variable is unset or empty in the process environment, so a
+ * deployment that sets env vars is configured by them alone — and there is
+ * never a precedence question to look up, because a stated env var makes the file's value
+ * unreachable. `withConfigFallback` is the one place that rule is implemented.
+ *
+ * The key set is closed, on both the write and the read. An unknown key written is refused naming
+ * the legal set (a typo'd key that "worked" would configure nothing, silently). An unknown key
+ * read is a problem too, for the same reason from the other side: this host wrote none, so one in
+ * the file is a hand-edit that does nothing, the misconfiguration nobody finds. And
+ * `PERISCOPE_CONFIG_DIR` is deliberately not settable here: it is what says where this file is,
+ * and a file that could move itself is a bootstrap circle.
+ *
+ * Sync I/O throughout, deliberately: `serve()` stays synchronous (its own docblock says why), and a
+ * one-shot read at boot plus a one-shot write per `config` invocation need no event loop.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, periscopeCredentialDir } from './paths.js';
+/**
+ * Every key the config file may carry — the environment variables the composition root reads,
+ * minus `PERISCOPE_CONFIG_DIR` (the bootstrap exclusion above).
+ */
+export const CONFIG_KEYS = [
+    'PERISCOPE_CONTROLLER_URL',
+    'PERISCOPE_DECISION_URL',
+    'PERISCOPE_HOST_ID',
+    'PERISCOPE_WORKSPACE_ROOT',
+    'PERISCOPE_REPOSITORY_ROOT',
+    'PERISCOPE_BRANCH_SCHEME',
+    'PERISCOPE_WORKSPACE_KEY',
+    'PERISCOPE_AGENT_HOME',
+];
+/**
+ * The keys a controller may set over the wire (`host_configure`): where this machine's things are,
+ * and where its control plane is. The two URLs are written to the file and never applied to
+ * the live link: the host dials what it dialled until its next start, and names the keys as pending
+ * in its answer and in every hello until then. Never the host id (a paired credential outranks it
+ * anyway) or the default workspace key (a start-up posture, screened at boot).
+ */
+export const WIRE_CONFIGURABLE_KEYS = [
+    'PERISCOPE_WORKSPACE_ROOT',
+    'PERISCOPE_REPOSITORY_ROOT',
+    'PERISCOPE_BRANCH_SCHEME',
+    'PERISCOPE_AGENT_HOME',
+    'PERISCOPE_CONTROLLER_URL',
+    'PERISCOPE_DECISION_URL',
+];
+/** The wire-settable keys that take effect only at the next start: the control-plane addresses. */
+export const RESTART_KEYS = [
+    'PERISCOPE_CONTROLLER_URL',
+    'PERISCOPE_DECISION_URL',
+];
+export function isWireConfigurableKey(value) {
+    return WIRE_CONFIGURABLE_KEYS.includes(value);
+}
+export function isConfigKey(value) {
+    return CONFIG_KEYS.includes(value);
+}
+/** Where the config file lives, or null when there is nowhere to keep one (no home, no override). */
+export function configFilePath(env = process.env) {
+    const dir = periscopeCredentialDir(env);
+    return dir === null ? null : join(dir, 'config.json');
+}
+/**
+ * Read the config file. A MISSING file is `{}` — the ordinary state of every machine that has
+ * never run `periscope config`. A file that exists and cannot be used is a PROBLEM, never a silent
+ * empty: falling back would make a corrupt file behave like a deliberate absence, which is the
+ * exact ambiguity the paired credential's fatal-on-corrupt posture exists to end.
+ */
+export function readConfigFile(env = process.env) {
+    const path = configFilePath(env);
+    if (path === null)
+        return { values: {}, problem: null };
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { values: {}, problem: null };
+        return {
+            values: {},
+            problem: `the config file at ${path} exists and cannot be read: ${describe(error)}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            values: {},
+            problem: `the config file at ${path} is not JSON: ${describe(error)}`,
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            values: {},
+            problem: `the config file at ${path} must hold one JSON object of string values`,
+        };
+    }
+    const values = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!isConfigKey(key)) {
+            return {
+                values: {},
+                problem: `the config file at ${path} carries an unknown key '${key}' — this host reads only ` +
+                    `${CONFIG_KEYS.join(', ')}, so the entry would configure nothing`,
+            };
+        }
+        if (typeof value !== 'string') {
+            return {
+                values: {},
+                problem: `the config file at ${path} carries a non-string value for '${key}'`,
+            };
+        }
+        values[key] = value;
+    }
+    return { values, problem: null };
+}
+/**
+ * Write one entry, creating the directory and file as needed. Returns null, or the named problem.
+ * Refuses an unknown key BEFORE touching the disk — see the closed-set rule in the header.
+ */
+export function writeConfigEntry(env, key, value) {
+    if (!isConfigKey(key)) {
+        return `'${key}' is not a config key this host reads — the legal keys are ${CONFIG_KEYS.join(', ')}`;
+    }
+    const path = configFilePath(env);
+    if (path === null) {
+        return 'there is nowhere to keep a config file — no home directory and no PERISCOPE_CONFIG_DIR';
+    }
+    const existing = readConfigFile(env);
+    if (existing.problem !== null) {
+        // Never merged-over: writing "around" a corrupt file destroys whatever the operator hand-wrote.
+        return `${existing.problem} — fix or remove it before writing`;
+    }
+    try {
+        const dir = path.slice(0, path.lastIndexOf('/'));
+        mkdirSync(dir, { recursive: true });
+        const next = { ...existing.values, [key]: value };
+        writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        return null;
+    }
+    catch (error) {
+        return `the config file at ${path} could not be written: ${describe(error)}`;
+    }
+}
+/**
+ * Write several entries as one read-modify-write, creating the directory and file as needed.
+ * Returns null, or the named problem. Every key is screened BEFORE the disk is touched, so a set
+ * with one bad key writes nothing; a null value removes its key. The same corrupt-file posture as
+ * the single-entry write: never merged over.
+ */
+export function writeConfigEntries(env, entries) {
+    for (const entry of entries) {
+        if (!isConfigKey(entry.key)) {
+            return `'${entry.key}' is not a config key this host reads — the legal keys are ${CONFIG_KEYS.join(', ')}`;
+        }
+    }
+    const path = configFilePath(env);
+    if (path === null) {
+        return 'there is nowhere to keep a config file — no home directory and no PERISCOPE_CONFIG_DIR';
+    }
+    const existing = readConfigFile(env);
+    if (existing.problem !== null) {
+        return `${existing.problem} — fix or remove it before writing`;
+    }
+    try {
+        const dir = path.slice(0, path.lastIndexOf('/'));
+        mkdirSync(dir, { recursive: true });
+        const next = { ...existing.values };
+        for (const entry of entries) {
+            if (entry.value === null)
+                delete next[entry.key];
+            else
+                next[entry.key] = entry.value;
+        }
+        writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        return null;
+    }
+    catch (error) {
+        return `the config file at ${path} could not be written: ${describe(error)}`;
+    }
+}
+/**
+ * The environment, with file values FILLING ABSENCES — the one implementation of "env wins".
+ *
+ * Returns a NEW plain object; the process environment is never mutated. Only the closed key set is
+ * consulted, so nothing outside it (identity configuration, the config dir itself) can arrive from
+ * a file. Empty-string env values count as absent, matching how the composition root reads them.
+ */
+export function withConfigFallback(env, values) {
+    const merged = { ...env };
+    for (const key of CONFIG_KEYS) {
+        const fromEnv = env[key];
+        const fromFile = values[key];
+        if ((fromEnv === undefined || fromEnv === '') && fromFile !== undefined && fromFile !== '') {
+            merged[key] = fromFile;
+        }
+    }
+    return merged;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=config-file.js.map

package/dist/host/git-facts.d.ts

@@ -0,0 +1,7 @@
+import type { TransitionWhere } from '../state/model.js';
+/**
+ * The `where` for a directory. Never throws — the caller stamps this onto every transition, so a
+ * throw here would take out the state record along with the fact it was decorating.
+ */
+export declare function readWhere(cwd: string): TransitionWhere;
+//# sourceMappingURL=git-facts.d.ts.map