@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/fs/config-store.js

@@ -0,0 +1,101 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { GezelConfigSchema, KeyedLock } from '@bendyline/gezel';
+import { gezelPaths } from '@bendyline/gezel/paths';
+import { writeFileAtomic } from './atomic.js';
+export class ConfigCorruptionError extends Error {
+    code = 'CONFIG_CORRUPT';
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigCorruptionError';
+    }
+}
+// All configuration writers in one owning daemon share this queue.
+const configWriteLocks = new KeyedLock();
+/** Configuration persistence only: safe to construct in an engine-only home. */
+export class ConfigStore {
+    home;
+    constructor(home) {
+        this.home = home;
+    }
+    get homePath() {
+        return this.home;
+    }
+    async readConfig() {
+        const p = gezelPaths(this.home);
+        let raw;
+        try {
+            raw = await readFile(p.config, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return {};
+            throw new ConfigCorruptionError(`Unable to read ${p.config}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new ConfigCorruptionError(`config.json is not valid JSON. Gezel left it untouched: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const result = GezelConfigSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new ConfigCorruptionError(`config.json failed schema validation. Gezel left it untouched: ${result.error.message}`);
+        }
+        return result.data;
+    }
+    async writeConfig(config) {
+        return configWriteLocks.run(resolve(gezelPaths(this.home).config), () => this.writeConfigPatch(config));
+    }
+    async writeConfigPatch(config) {
+        const p = gezelPaths(this.home);
+        const existing = await this.readConfig();
+        // Explicit `null` on any patched field means "reset to default" —
+        // drop it from the merged shape instead of persisting the null.
+        // The transport strips `undefined`, so the UI uses null to clear a field.
+        // Internal undefined patches retain their omission-on-JSON behavior.
+        const merged = { ...existing, ...config };
+        for (const [k, v] of Object.entries(config)) {
+            if (v === null)
+                delete merged[k];
+        }
+        // externalFolders is a nested object; per-scope `null` clears that
+        // scope's external path. If all three scopes end up absent the
+        // parent object goes away entirely so the on-disk config stays
+        // narrow.
+        if ('externalFolders' in config && config.externalFolders !== null) {
+            const incoming = config.externalFolders;
+            if (incoming && typeof incoming === 'object' && !Array.isArray(incoming)) {
+                const existingExternal = existing.externalFolders ?? {};
+                const mergedExternal = { ...existingExternal, ...incoming };
+                for (const [k, v] of Object.entries(incoming)) {
+                    if (v === null)
+                        delete mergedExternal[k];
+                }
+                if (Object.keys(mergedExternal).length === 0) {
+                    delete merged.externalFolders;
+                }
+                else {
+                    merged.externalFolders = mergedExternal;
+                }
+            }
+        }
+        // ambientDashboard combines user-authored preferences with the Electron
+        // shell's last-known primary-display target. A settings toggle commonly
+        // patches only `{ enabled }`; merge this object so that action cannot erase
+        // the screen geometry needed by scheduled renders after the app closes.
+        if ('ambientDashboard' in config && config.ambientDashboard !== null) {
+            const incoming = config.ambientDashboard;
+            if (incoming && typeof incoming === 'object' && !Array.isArray(incoming)) {
+                merged.ambientDashboard = {
+                    ...(existing.ambientDashboard ?? {}),
+                    ...incoming,
+                };
+            }
+        }
+        const validated = GezelConfigSchema.parse(merged);
+        await writeFileAtomic(p.config, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
+        return validated;
+    }
+}

package/dist/fs/home-permissions.d.ts

@@ -0,0 +1,18 @@
+interface PrivateHomeDependencies {
+    platform?: NodeJS.Platform;
+    mkdir?: (path: string, options: {
+        recursive: true;
+        mode: number;
+    }) => Promise<unknown>;
+    chmod?: (path: string, mode: number) => Promise<unknown>;
+}
+/**
+ * Create or repair a per-user Gezel home so other local Unix accounts cannot
+ * traverse it. Files beneath the home may retain ordinary modes (for example
+ * 0644); the non-traversable 0700 root remains the security boundary.
+ *
+ * Windows is intentionally excluded: POSIX mode bits are not its access
+ * control boundary, and the installer/user profile ACLs are handled elsewhere.
+ */
+export declare function ensurePrivateUserHome(home: string, dependencies?: PrivateHomeDependencies): Promise<void>;
+export {};

package/dist/fs/home-permissions.js

@@ -0,0 +1,27 @@
+import { chmod, mkdir } from 'node:fs/promises';
+/**
+ * Create or repair a per-user Gezel home so other local Unix accounts cannot
+ * traverse it. Files beneath the home may retain ordinary modes (for example
+ * 0644); the non-traversable 0700 root remains the security boundary.
+ *
+ * Windows is intentionally excluded: POSIX mode bits are not its access
+ * control boundary, and the installer/user profile ACLs are handled elsewhere.
+ */
+export async function ensurePrivateUserHome(home, dependencies = {}) {
+    if ((dependencies.platform ?? process.platform) === 'win32')
+        return;
+    const makeDirectory = dependencies.mkdir ?? mkdir;
+    const setMode = dependencies.chmod ?? chmod;
+    try {
+        // `mode` protects a newly-created home even under a permissive umask.
+        await makeDirectory(home, { recursive: true, mode: 0o700 });
+        // mkdir does not repair an existing directory, so chmod is required for
+        // upgrades from releases that inherited 0755 from the caller's umask.
+        await setMode(home, 0o700);
+    }
+    catch (error) {
+        throw new Error(`Unable to secure the private Gezel home at ${home} with mode 0700`, {
+            cause: error,
+        });
+    }
+}

package/dist/fs/safe-paths.d.ts

@@ -0,0 +1,107 @@
+import { isReservedWindowsName, unresolvedTemplatePlaceholders } from '@bendyline/gezel';
+export { isReservedWindowsName, unresolvedTemplatePlaceholders };
+/**
+ * Belt-and-suspenders for the model that echoes an absolute path back
+ * into a workspace tool. The standing prompt conceals the workspace's
+ * host path, but absolute paths still leak in from git output, error
+ * strings, or a user paste — and `safeJoin` refuses every one of them
+ * ({@link safeJoin} rejects `isAbsolute`), which historically surfaced as
+ * an indistinguishable "missing" and led a security-review gezel to
+ * conclude its checkout was gone and confabulate over files it could not
+ * see.
+ *
+ * This normalizes at the workspace boundary, BEFORE the safe primitives:
+ *   - a relative path passes through untouched (the common case);
+ *   - an absolute path *inside* `base` is rebased to workspace-relative
+ *     (equal-to-base collapses to `''`), so the model's naive call just
+ *     works — containment is unchanged because the rebased path still
+ *     flows through `safeJoin` + `realpathContained` downstream;
+ *   - an absolute path *outside* `base` throws an actionable
+ *     `PathSafetyError` instead of a silent miss, so the model is told to
+ *     use a workspace-relative path and can self-correct.
+ *
+ * The comparison is lexical (normalized, platform-case-aware) — it never
+ * widens access, since the real security enforcement is the downstream
+ * realpath containment check. `safeJoin`'s reject-absolute invariant is
+ * left intact for defense in depth.
+ */
+export declare function intoWorkspaceRelative(base: string, p: string): string;
+/**
+ * Resolve `relPath` against `base` and return the resulting absolute
+ * path ONLY if it stays inside `base`. Returns `null` on any attempt to
+ * escape (`..`, absolute paths, Windows drive swaps, etc.).
+ *
+ * Both the base and the candidate are normalized before comparison, and
+ * the containment check requires a trailing separator OR exact match so
+ * `/home/foo` does not pass for `/home/foobar`. Case comparison follows
+ * the platform FS convention.
+ */
+export declare function safeJoin(base: string, relPath: string): string | null;
+/**
+ * After `safeJoin` returns a logically-contained path, still verify
+ * with `realpath` that any symlinks along the way don't escape. The
+ * target file itself might not exist yet (writes), so we realpath the
+ * nearest existing ancestor.
+ *
+ * Returns true if the real path is inside the real base, false
+ * otherwise. The caller should treat false as "refuse the op."
+ */
+export declare function realpathContained(base: string, fullPath: string, opts?: {
+    allowMissingBase?: boolean;
+}): Promise<boolean>;
+/** Mutation roots can be created lazily, but their existing ancestors must still contain the write. */
+export declare function resolveMutationPath(base: string, relPath: string): Promise<string>;
+/**
+ * Is `target` the same directory as `root`, or somewhere beneath it?
+ *
+ * The purely lexical companion to {@link realpathContained}, for callers
+ * that have already resolved symlinks or are only classifying a path rather
+ * than guarding a write. Both arguments are resolved first, and the compare
+ * respects the platform's case rules — on macOS and Windows, `~/.gezel` and
+ * `~/.Gezel` are one directory, and treating them as different silently
+ * misfiles content as living outside the home folder.
+ *
+ * A path that merely shares a string prefix (`<home>-backup`) is not inside.
+ */
+export declare function isPathInside(target: string, root: string): boolean;
+/**
+ * `realpath` the given path if it exists, else walk up to the nearest
+ * existing ancestor and realpath that + append the un-realpath'd tail.
+ * This gives us a meaningful symlink-resolved path even for files that
+ * don't exist yet (common during `write_file`).
+ */
+export declare function realpathNearest(p: string): Promise<string | null>;
+export type PathSafetyCode = 'path-traversal' | 'symlink-escape' | 'reserved-name' | 'empty-path' | 'template-placeholder';
+/**
+ * Refuse a write whose path still carries an unresolved `{{param}}` token.
+ *
+ * `step-gate.ts` already refuses to EVALUATE a gate holding one, because a
+ * literal `{{…}}` handed to a path resolver can never match. Nothing refused
+ * the mirror-image act: writing a file AT that literal path. On task gezel/7
+ * a security gezel read its own paused gate, correctly diagnosed that
+ * `workPath` had never resolved, and then "worked around" it by writing the
+ * deliverable a second time to `{{task.dir}}/security/review-scope.md` — a
+ * real directory named `{{task.dir}}` that the drawer now owned forever. It
+ * could not have helped: the gate rejects on configuration before any check
+ * runs, so no file placement satisfies it.
+ *
+ * The token was always meant to be substituted, so refusing costs a caller
+ * nothing real — the exception is a gezel deliberately authoring a template
+ * tree (cookiecutter/copier scaffolding uses `{{…}}` directory names), which
+ * is why the workspace applies this only to model-initiated writes and the
+ * user's own hand stays unrestricted.
+ */
+export declare function assertNoTemplatePlaceholderPath(p: string): void;
+export declare class PathSafetyError extends Error {
+    readonly code: PathSafetyCode;
+    constructor(message: string, code: PathSafetyCode);
+}
+/**
+ * End-to-end safe resolution: normalize, verify containment, realpath
+ * to catch symlink escape, reject reserved Windows basenames. Throws
+ * `PathSafetyError` on any violation so callers get a single catch
+ * for the whole class of "this path isn't allowed" errors.
+ */
+export declare function resolveInside(base: string, relPath: string, opts?: {
+    allowRoot?: boolean;
+}): Promise<string>;

package/dist/fs/safe-paths.js

@@ -0,0 +1,264 @@
+import { realpath } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, normalize, resolve, sep } from 'node:path';
+import { DESKTOP_SEGMENT_RULES, findPathRuleViolation, isReservedWindowsName, unresolvedTemplatePlaceholders, } from '@bendyline/gezel';
+export { isReservedWindowsName, unresolvedTemplatePlaceholders };
+/**
+ * Shared path-safety primitives. Every write or execution inside a
+ * user-supplied path (project workspace, artifacts, documents, etc.)
+ * funnels through these helpers so the containment rules stay uniform.
+ *
+ * Three latent bugs that the raw `normalize(join(base, p)).startsWith(base)`
+ * pattern we used before had:
+ *
+ *   1. `/home/foo` matches `/home/foobar` (no separator terminator).
+ *   2. Case-sensitive on Windows / macOS default FS, letting
+ *      `C:\USERS\FOO\..` slip past.
+ *   3. Doesn't resolve symlinks — a model can create a symlink inside
+ *      the workspace pointing at `/etc/hosts`, then write through it.
+ *
+ * `safeJoin` fixes (1) + (2). `realpathContained` fixes (3).
+ */
+/**
+ * Case-insensitive path compare on Windows + macOS (which default to
+ * case-preserving-but-case-insensitive filesystems). On Linux, an exact
+ * match is required — it's a case-sensitive FS, and being lenient there
+ * would weaken the check.
+ */
+function pathEq(a, b) {
+    if (process.platform === 'win32' || process.platform === 'darwin') {
+        return a.toLowerCase() === b.toLowerCase();
+    }
+    return a === b;
+}
+function pathStartsWithDir(candidate, base) {
+    const prefix = directoryPrefix(base);
+    if (process.platform === 'win32' || process.platform === 'darwin') {
+        return candidate.toLowerCase().startsWith(prefix.toLowerCase());
+    }
+    return candidate.startsWith(prefix);
+}
+function directoryPrefix(base) {
+    return base.endsWith(sep) ? base : base + sep;
+}
+/**
+ * Belt-and-suspenders for the model that echoes an absolute path back
+ * into a workspace tool. The standing prompt conceals the workspace's
+ * host path, but absolute paths still leak in from git output, error
+ * strings, or a user paste — and `safeJoin` refuses every one of them
+ * ({@link safeJoin} rejects `isAbsolute`), which historically surfaced as
+ * an indistinguishable "missing" and led a security-review gezel to
+ * conclude its checkout was gone and confabulate over files it could not
+ * see.
+ *
+ * This normalizes at the workspace boundary, BEFORE the safe primitives:
+ *   - a relative path passes through untouched (the common case);
+ *   - an absolute path *inside* `base` is rebased to workspace-relative
+ *     (equal-to-base collapses to `''`), so the model's naive call just
+ *     works — containment is unchanged because the rebased path still
+ *     flows through `safeJoin` + `realpathContained` downstream;
+ *   - an absolute path *outside* `base` throws an actionable
+ *     `PathSafetyError` instead of a silent miss, so the model is told to
+ *     use a workspace-relative path and can self-correct.
+ *
+ * The comparison is lexical (normalized, platform-case-aware) — it never
+ * widens access, since the real security enforcement is the downstream
+ * realpath containment check. `safeJoin`'s reject-absolute invariant is
+ * left intact for defense in depth.
+ */
+export function intoWorkspaceRelative(base, p) {
+    if (typeof p !== 'string' || !isAbsolute(p))
+        return p;
+    const normalizedBase = normalize(base);
+    const normalizedPath = normalize(p);
+    if (pathEq(normalizedPath, normalizedBase))
+        return '';
+    if (pathStartsWithDir(normalizedPath, normalizedBase)) {
+        // Slice by prefix length rather than `path.relative`: containment is
+        // already proven (case-insensitively on macOS/Windows), and `relative`
+        // is case-SENSITIVE on posix, so a differently-cased-but-contained
+        // path would wrongly yield a `../` escape. Slicing keeps the tail's
+        // real casing.
+        return normalizedPath.slice(directoryPrefix(normalizedBase).length);
+    }
+    throw new PathSafetyError(`absolute path outside the workspace: ${p} — pass a path relative to the workspace root`, 'path-traversal');
+}
+/**
+ * Resolve `relPath` against `base` and return the resulting absolute
+ * path ONLY if it stays inside `base`. Returns `null` on any attempt to
+ * escape (`..`, absolute paths, Windows drive swaps, etc.).
+ *
+ * Both the base and the candidate are normalized before comparison, and
+ * the containment check requires a trailing separator OR exact match so
+ * `/home/foo` does not pass for `/home/foobar`. Case comparison follows
+ * the platform FS convention.
+ */
+export function safeJoin(base, relPath) {
+    if (typeof relPath !== 'string')
+        return null;
+    // Apply Windows' dangerous-name rules on every platform. Workspaces and
+    // archives are routinely moved between OSes; allowing ADS syntax, device
+    // names, or normalization-ambiguous trailing dots elsewhere creates files
+    // that become unsafe as soon as the project reaches Windows.
+    if (hasUnsafePortableSegment(relPath))
+        return null;
+    if (isAbsolute(relPath))
+        return null;
+    const normalizedBase = normalize(base);
+    const candidate = normalize(join(normalizedBase, relPath));
+    if (pathEq(candidate, normalizedBase))
+        return candidate;
+    if (pathStartsWithDir(candidate, normalizedBase))
+        return candidate;
+    return null;
+}
+/**
+ * After `safeJoin` returns a logically-contained path, still verify
+ * with `realpath` that any symlinks along the way don't escape. The
+ * target file itself might not exist yet (writes), so we realpath the
+ * nearest existing ancestor.
+ *
+ * Returns true if the real path is inside the real base, false
+ * otherwise. The caller should treat false as "refuse the op."
+ */
+export async function realpathContained(base, fullPath, opts) {
+    const realBase = opts?.allowMissingBase ? await realpathNearest(base) : await realpathSafe(base);
+    if (!realBase)
+        return false;
+    const realTarget = await realpathNearest(fullPath);
+    if (!realTarget)
+        return false;
+    if (pathEq(realTarget, realBase))
+        return true;
+    return pathStartsWithDir(realTarget, realBase);
+}
+/** Mutation roots can be created lazily, but their existing ancestors must still contain the write. */
+export async function resolveMutationPath(base, relPath) {
+    const full = safeJoin(base, relPath);
+    if (!full)
+        throw new PathSafetyError('path traversal blocked', 'path-traversal');
+    if (pathEq(full, normalize(base))) {
+        throw new PathSafetyError('the root folder cannot be mutated', 'empty-path');
+    }
+    if (!(await realpathContained(base, full, { allowMissingBase: true }))) {
+        throw new PathSafetyError(`symlink escape detected for ${relPath}`, 'symlink-escape');
+    }
+    return full;
+}
+/**
+ * Is `target` the same directory as `root`, or somewhere beneath it?
+ *
+ * The purely lexical companion to {@link realpathContained}, for callers
+ * that have already resolved symlinks or are only classifying a path rather
+ * than guarding a write. Both arguments are resolved first, and the compare
+ * respects the platform's case rules — on macOS and Windows, `~/.gezel` and
+ * `~/.Gezel` are one directory, and treating them as different silently
+ * misfiles content as living outside the home folder.
+ *
+ * A path that merely shares a string prefix (`<home>-backup`) is not inside.
+ */
+export function isPathInside(target, root) {
+    const resolvedTarget = resolve(target);
+    const resolvedRoot = resolve(root);
+    if (pathEq(resolvedTarget, resolvedRoot))
+        return true;
+    return pathStartsWithDir(resolvedTarget, resolvedRoot);
+}
+async function realpathSafe(p) {
+    try {
+        return normalize(await realpath(p));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `realpath` the given path if it exists, else walk up to the nearest
+ * existing ancestor and realpath that + append the un-realpath'd tail.
+ * This gives us a meaningful symlink-resolved path even for files that
+ * don't exist yet (common during `write_file`).
+ */
+export async function realpathNearest(p) {
+    const direct = await realpathSafe(p);
+    if (direct)
+        return direct;
+    const parent = dirname(p);
+    if (parent === p)
+        return null; // reached root
+    const realParent = await realpathNearest(parent);
+    if (!realParent)
+        return null;
+    return normalize(join(realParent, basename(p)));
+}
+/** The desktop's per-segment screen; containment is `safeJoin`'s job. */
+function hasUnsafePortableSegment(relPath) {
+    return findPathRuleViolation(relPath, DESKTOP_SEGMENT_RULES) !== null;
+}
+/**
+ * Refuse a write whose path still carries an unresolved `{{param}}` token.
+ *
+ * `step-gate.ts` already refuses to EVALUATE a gate holding one, because a
+ * literal `{{…}}` handed to a path resolver can never match. Nothing refused
+ * the mirror-image act: writing a file AT that literal path. On task gezel/7
+ * a security gezel read its own paused gate, correctly diagnosed that
+ * `workPath` had never resolved, and then "worked around" it by writing the
+ * deliverable a second time to `{{task.dir}}/security/review-scope.md` — a
+ * real directory named `{{task.dir}}` that the drawer now owned forever. It
+ * could not have helped: the gate rejects on configuration before any check
+ * runs, so no file placement satisfies it.
+ *
+ * The token was always meant to be substituted, so refusing costs a caller
+ * nothing real — the exception is a gezel deliberately authoring a template
+ * tree (cookiecutter/copier scaffolding uses `{{…}}` directory names), which
+ * is why the workspace applies this only to model-initiated writes and the
+ * user's own hand stays unrestricted.
+ */
+export function assertNoTemplatePlaceholderPath(p) {
+    const hits = unresolvedTemplatePlaceholders(p);
+    if (hits.length === 0)
+        return;
+    throw new PathSafetyError(`unresolved template placeholder in path: ${hits.join(' ')} — writing "${p}" would create a folder literally named that. The launch parameter behind the token was never substituted; use the real path it stands for (a task's working folder is tasks/<task number>). If a gate is asking for this path, the gate is misconfigured and no file can satisfy it.`, 'template-placeholder');
+}
+export class PathSafetyError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'PathSafetyError';
+        this.code = code;
+    }
+}
+/**
+ * End-to-end safe resolution: normalize, verify containment, realpath
+ * to catch symlink escape, reject reserved Windows basenames. Throws
+ * `PathSafetyError` on any violation so callers get a single catch
+ * for the whole class of "this path isn't allowed" errors.
+ */
+export async function resolveInside(base, relPath, opts) {
+    // Rebase an absolute-under-base path to workspace-relative (or throw on
+    // absolute-outside) before the containment checks; a relative path is
+    // returned unchanged, so existing callers are unaffected.
+    const rebasedPath = intoWorkspaceRelative(base, relPath);
+    if (!rebasedPath || rebasedPath.trim() === '') {
+        throw new PathSafetyError('empty path', 'empty-path');
+    }
+    const reservedSegment = rebasedPath.split(/[\\/]+/).find(isReservedWindowsName);
+    if (reservedSegment) {
+        throw new PathSafetyError(`reserved Windows name: ${reservedSegment}`, 'reserved-name');
+    }
+    const joined = safeJoin(base, rebasedPath);
+    if (joined === null) {
+        throw new PathSafetyError(`path escapes the base dir: ${rebasedPath}`, 'path-traversal');
+    }
+    // Read/list callers may name the root. Mutators must reject equivalent
+    // spellings such as '.' and 'notes/..' before reaching the filesystem.
+    if (opts?.allowRoot === false && pathEq(joined, normalize(base))) {
+        throw new PathSafetyError('the root folder cannot be mutated', 'empty-path');
+    }
+    if (isReservedWindowsName(basename(joined))) {
+        throw new PathSafetyError(`reserved Windows name: ${basename(joined)}`, 'reserved-name');
+    }
+    const contained = await realpathContained(base, joined);
+    if (!contained) {
+        throw new PathSafetyError(`symlink escape detected for ${rebasedPath}`, 'symlink-escape');
+    }
+    return joined;
+}

package/dist/fs/security-json.d.ts

@@ -0,0 +1,13 @@
+export declare class SecurityStateCorruptionError extends Error {
+    readonly label: string;
+    readonly filePath: string;
+    constructor(label: string, filePath: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Read a security-sensitive JSON document. A valid sibling `.bak` is used to
+ * repair a missing/corrupt primary, but ambiguous state is never normalized to
+ * an empty collection. Callers provide the strict decoder for their schema.
+ */
+export declare function readSecurityJson<T>(filePath: string, label: string, decode: (raw: string) => T): Promise<T | null>;
+/** Stage the new valid snapshot as a backup, then atomically commit primary. */
+export declare function writeSecurityJson(filePath: string, content: string): Promise<void>;

package/dist/fs/security-json.js

@@ -0,0 +1,67 @@
+import { readFile } from 'node:fs/promises';
+import { writeFileAtomic } from './atomic.js';
+export class SecurityStateCorruptionError extends Error {
+    label;
+    filePath;
+    constructor(label, filePath, message, options) {
+        super(`${label} state at ${filePath} is unusable: ${message}`, options);
+        this.label = label;
+        this.filePath = filePath;
+        this.name = 'SecurityStateCorruptionError';
+    }
+}
+/**
+ * Read a security-sensitive JSON document. A valid sibling `.bak` is used to
+ * repair a missing/corrupt primary, but ambiguous state is never normalized to
+ * an empty collection. Callers provide the strict decoder for their schema.
+ */
+export async function readSecurityJson(filePath, label, decode) {
+    const primary = await readOptional(filePath, label);
+    if (primary !== null) {
+        try {
+            return decode(primary);
+        }
+        catch (primaryError) {
+            const backup = await readOptional(`${filePath}.bak`, `${label} backup`);
+            if (backup !== null) {
+                try {
+                    const recovered = decode(backup);
+                    await writeFileAtomic(filePath, backup, { mode: 0o600, durable: true });
+                    return recovered;
+                }
+                catch (backupError) {
+                    throw new SecurityStateCorruptionError(label, filePath, 'both the primary and backup failed validation; neither file was overwritten', { cause: backupError });
+                }
+            }
+            throw new SecurityStateCorruptionError(label, filePath, 'the primary failed validation and no valid backup exists; the file was not overwritten', { cause: primaryError });
+        }
+    }
+    const backup = await readOptional(`${filePath}.bak`, `${label} backup`);
+    if (backup === null)
+        return null;
+    try {
+        const recovered = decode(backup);
+        await writeFileAtomic(filePath, backup, { mode: 0o600, durable: true });
+        return recovered;
+    }
+    catch (error) {
+        throw new SecurityStateCorruptionError(label, filePath, 'the primary is missing and the backup failed validation', { cause: error });
+    }
+}
+/** Stage the new valid snapshot as a backup, then atomically commit primary. */
+export async function writeSecurityJson(filePath, content) {
+    await writeFileAtomic(`${filePath}.bak`, content, { mode: 0o600, durable: true });
+    await writeFileAtomic(filePath, content, { mode: 0o600, durable: true });
+}
+async function readOptional(filePath, label) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new SecurityStateCorruptionError(label, filePath, 'the file could not be read', {
+            cause: error,
+        });
+    }
+}

package/dist/http/auth-context.d.ts

@@ -0,0 +1,23 @@
+import 'hono';
+declare module 'hono' {
+    interface ContextVariableMap {
+        /**
+         * Set by {@link bearerAuth} once the request's bearer token is
+         * resolved to a known {@link import('./token-store.js').TokenRecord}.
+         * Route handlers (and the {@link requireScope} middleware) read this
+         * to audit per-app calls and gate scope-sensitive endpoints. Absent
+         * on the unauthenticated `/api/health` path.
+         */
+        auth: {
+            appId: string;
+            /** Human-readable connected-app name, used for audit and queue labels. */
+            appName?: string;
+            scopes: readonly string[];
+            /** Present on session-scoped tokens (a gezel's MCP subprocess); the
+             *  scope-guard confines them to this project unless `team`. */
+            projectId?: string;
+            gezelId?: string;
+            team?: boolean;
+        };
+    }
+}

package/dist/http/auth-context.js

@@ -0,0 +1 @@
+import 'hono';

package/dist/http/engine-runtime-context.d.ts

@@ -0,0 +1,30 @@
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import type { EngineBinaryRegistry } from '../engines/registry.js';
+import type { ConfigStore } from '../fs/config-store.js';
+import type { LlamaCppModelManager } from '../providers/llama-cpp/models.js';
+import type { MlxModelManager } from '../providers/mlx/models.js';
+import type { NativeInference } from '../providers/native/inference.js';
+export interface EngineRuntimeContext {
+    home: string;
+    store: Pick<ConfigStore, 'readConfig' | 'writeConfig' | 'homePath'>;
+    catalog: CatalogService;
+    chat: NativeInference;
+    engineBinaries: EngineBinaryRegistry;
+    llamaCppModels: LlamaCppModelManager;
+    ds4Models: LlamaCppModelManager;
+    mlxModels: MlxModelManager;
+    machineEngine?: {
+        isConnected(): boolean;
+        isRequired(): boolean;
+        proxy(request: Request, from: string, to: string): Promise<Response>;
+    };
+    recognition?: {
+        reset(): Promise<void>;
+    };
+    imageProvider?: {
+        reset(): Promise<void>;
+    };
+    stt?: {
+        reset(): Promise<void>;
+    };
+}

package/dist/http/engine-runtime-context.js

@@ -0,0 +1 @@
+export {};