@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/models/storage-roots.js

@@ -0,0 +1,865 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile, } from 'node:fs/promises';
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { createLogger } from '@bendyline/gezel';
+import { windowsHeadlessSpawnOptions } from '@bendyline/gezel/native';
+const execFileAsync = promisify(execFile);
+const log = createLogger('assets');
+// A first adoption can require hashing tens of gigabytes. Model inventory is
+// requested by several UI paths, so share that work instead of letting each
+// request start another full read of the same payload.
+const readOnlyVerificationInFlight = new Map();
+const verificationCacheWrites = new Map();
+/**
+ * Public machine assets are intentionally separate from the machine
+ * service's private GEZEL_HOME state. The installer/service host supplies
+ * this variable; standalone CLI launches supply the same canonical path as a
+ * read-only overlay.
+ */
+export const SHARED_ASSETS_ENV = 'GEZEL_SHARED_ASSETS_DIR';
+/**
+ * Additional gezel HOMES whose installed models this process may read but
+ * never write. Delimiter-separated absolute paths, lowest priority in the
+ * overlay.
+ *
+ * This exists for a daemon hosted by a third-party app through
+ * `@bendyline/gezel-app-sdk/host`: it owns a private home under
+ * `~/.gezel/apps/<appId>/`, so without this it would re-download weights the
+ * user's own Gezel install already has. Unlike {@link SHARED_ASSETS_ENV},
+ * which names a purpose-built public asset store, the entries here are
+ * ordinary homes, so the per-engine `engines/<engine>/models` suffix is
+ * applied for them. Read-only payloads still have to carry
+ * `manifest.fileSha256` to be adopted, so a home whose installs predate
+ * that field is simply skipped rather than trusted.
+ */
+export const READONLY_MODEL_HOMES_ENV = 'GEZEL_READONLY_MODEL_HOMES';
+const SHARED_MODEL_ENGINES = [
+    'llama-cpp',
+    'ds4',
+    'mlx',
+    'video',
+    'sd-cpp',
+    'whisper-cpp',
+    'recognition',
+];
+/**
+ * Resolve a model store without ever treating the machine service's private
+ * home as a fallback. Local assets shadow machine assets with the same id.
+ */
+export function modelStorageRoots(opts) {
+    const env = opts.env ?? process.env;
+    const localRoot = join(opts.home, 'engines', opts.engine, 'models');
+    const configured = env[SHARED_ASSETS_ENV]?.trim();
+    const sharedAssetsRoot = configured && isAbsolute(configured) ? resolve(configured) : undefined;
+    const sharedModelRoot = sharedAssetsRoot
+        ? join(sharedAssetsRoot, 'models', opts.engine)
+        : undefined;
+    if (env.GEZEL_SYSTEM_SCOPE === '1' && sharedModelRoot) {
+        return { writableRoot: sharedModelRoot, readOnlyRoots: [] };
+    }
+    const readOnlyRoots = [];
+    const seen = new Set([resolve(localRoot)]);
+    const addReadOnly = (root) => {
+        const resolved = resolve(root);
+        if (seen.has(resolved))
+            return;
+        seen.add(resolved);
+        readOnlyRoots.push(root);
+    };
+    if (sharedModelRoot)
+        addReadOnly(sharedModelRoot);
+    for (const home of readOnlyModelHomes(env)) {
+        addReadOnly(join(home, 'engines', opts.engine, 'models'));
+    }
+    return { writableRoot: localRoot, readOnlyRoots };
+}
+/**
+ * Parse {@link READONLY_MODEL_HOMES_ENV}. Relative entries are dropped rather
+ * than resolved against the daemon's cwd — a model root is a machine-level
+ * location, and guessing one from whichever directory happened to launch the
+ * process is how a host ends up reading someone else's files.
+ */
+export function readOnlyModelHomes(env = process.env) {
+    const raw = env[READONLY_MODEL_HOMES_ENV]?.trim();
+    if (!raw)
+        return [];
+    const homes = [];
+    const seen = new Set();
+    for (const entry of raw.split(delimiter)) {
+        const trimmed = entry.trim();
+        if (!trimmed || !isAbsolute(trimmed))
+            continue;
+        const resolved = resolve(trimmed);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        homes.push(resolved);
+    }
+    return homes;
+}
+/**
+ * Fail closed when an existing model-store component resolves through a
+ * symlink/junction or outside the configured root. On Windows, Node reports
+ * directory junctions as symbolic links and `realpath` resolves the final
+ * filesystem target, so this protects both recursive ACL work and ordinary
+ * publish/delete operations from descendant reparse redirection.
+ *
+ * Missing trailing components are allowed so callers can validate a publish
+ * target before creating it. Every existing ancestor, including `root`, is
+ * still checked.
+ */
+export async function assertModelStorePathSafe(root, target) {
+    const resolvedRoot = resolve(root);
+    const resolvedTarget = resolve(target);
+    const rel = relative(resolvedRoot, resolvedTarget);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`refusing a model-store path outside its root: ${resolvedTarget}`);
+    }
+    const components = rel ? rel.split(sep).filter(Boolean) : [];
+    let cursor = resolvedRoot;
+    let deepestExisting = resolvedRoot;
+    for (let index = -1; index < components.length; index += 1) {
+        if (index >= 0)
+            cursor = join(cursor, components[index]);
+        let info;
+        try {
+            info = await lstat(cursor);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                break;
+            throw error;
+        }
+        if (!info.isDirectory() || info.isSymbolicLink()) {
+            throw new Error(`refusing a linked or non-directory model-store path: ${cursor}`);
+        }
+        deepestExisting = cursor;
+    }
+    const [canonicalRoot, canonicalExisting] = await Promise.all([
+        realpath(resolvedRoot),
+        realpath(deepestExisting),
+    ]);
+    const canonicalRel = relative(canonicalRoot, canonicalExisting);
+    if (canonicalRel.startsWith('..') || isAbsolute(canonicalRel)) {
+        throw new Error(`refusing a model-store path whose final target escapes its root: ${resolvedTarget}`);
+    }
+}
+/**
+ * One-shot upgrade bridge for machine services that downloaded models into
+ * the formerly-private `<home>/engines/<engine>/models` tree. Both locations are on
+ * the same machine volume in supported installers, so directory renames are
+ * atomic and avoid copying multi-gigabyte weights.
+ */
+export async function migrateLegacySystemModels(home, env = process.env) {
+    if (env.GEZEL_SYSTEM_SCOPE !== '1' || !env[SHARED_ASSETS_ENV]?.trim())
+        return 0;
+    let moved = 0;
+    const publishFailures = [];
+    for (const engine of SHARED_MODEL_ENGINES) {
+        const roots = modelStorageRoots({ home, engine, env });
+        const legacyRoot = join(home, 'engines', engine, 'models');
+        if (resolve(legacyRoot) === resolve(roots.writableRoot))
+            continue;
+        const entries = await readdir(legacyRoot, { withFileTypes: true }).catch(() => null);
+        await mkdir(roots.writableRoot, { recursive: true });
+        await assertModelStorePathSafe(roots.writableRoot, roots.writableRoot);
+        if (entries) {
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.isSymbolicLink())
+                    continue;
+                const source = join(legacyRoot, entry.name);
+                const target = join(roots.writableRoot, entry.name);
+                await assertModelStorePathSafe(roots.writableRoot, target);
+                try {
+                    await lstat(target);
+                    continue;
+                }
+                catch {
+                    // Missing target is the only state we migrate.
+                }
+                await rename(source, target);
+                moved += 1;
+            }
+        }
+        // Releases before the public asset store did not record a complete
+        // per-file hash map. Backfill it while the bundle is still service-only,
+        // then widen read access. Also repairs bundles moved by an interrupted
+        // upgrade before this loop was introduced.
+        const sharedEntries = await readdir(roots.writableRoot, { withFileTypes: true }).catch(() => []);
+        for (const entry of sharedEntries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            const modelDir = join(roots.writableRoot, entry.name);
+            try {
+                await publishMigratedModel(modelDir, env);
+            }
+            catch (error) {
+                // Publishing widens read access on ONE bundle. It must never decide
+                // whether the daemon boots.
+                //
+                // This ran unguarded through v1.26219.44 and took the whole service
+                // down: the Windows installer had just made Administrators the owner
+                // of every pre-existing model while granting the service only Modify,
+                // so `icacls /reset` — which needs WRITE_DAC — failed with "Access is
+                // denied", the throw escaped startService, and gezeld crash-looped on
+                // SCM 1066. The installer grant is fixed (see nsis-hooks.nsh), but the
+                // structural bug was that a per-model permission repair was allowed to
+                // be fatal at all. Degrade the bundle, not the machine.
+                //
+                // Consequence of skipping: that bundle keeps its narrower ACL, so other
+                // accounts cannot read it until the next successful publish. The broker
+                // itself still uses it, so on-device inference is unaffected.
+                publishFailures.push(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    if (publishFailures.length > 0) {
+        log.warn(`${publishFailures.length} shared model bundle(s) could not be published for ` +
+            `cross-account read access and stay broker-only: ${publishFailures.join('; ')}`);
+    }
+    return moved;
+}
+async function publishMigratedModel(modelDir, env) {
+    const manifestPath = join(modelDir, 'manifest.json');
+    const info = await lstat(manifestPath).catch(() => null);
+    if (!info?.isFile() || info.isSymbolicLink())
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const existing = parsed.fileSha256;
+    const hasValidHashes = !!existing &&
+        typeof existing === 'object' &&
+        !Array.isArray(existing) &&
+        Object.keys(existing).length > 0 &&
+        Object.entries(existing).every(([path, sha]) => isSafeModelPath(path) && isSha256(String(sha)));
+    if (!hasValidHashes) {
+        const fileSha256 = await hashModelPayloadFiles(modelDir);
+        if (Object.keys(fileSha256).length === 0)
+            return;
+        await writeFile(manifestPath, `${JSON.stringify({ ...parsed, fileSha256 }, null, 2)}\n`, 'utf8');
+    }
+    await makeSharedModelReadable(modelDir, env);
+}
+/** Search order: user-owned/writable first, then machine-owned/read-only. */
+export function modelSearchRoots(roots) {
+    return [roots.writableRoot, ...roots.readOnlyRoots];
+}
+/**
+ * List ids across an overlay, de-duplicating in search order so a user-owned
+ * model intentionally shadows a machine model with the same catalog id.
+ */
+export async function listOverlayModelIds(roots) {
+    const seen = new Set();
+    const ids = [];
+    for (const root of modelSearchRoots(roots)) {
+        let entries;
+        try {
+            entries = await readdir(root);
+        }
+        catch {
+            continue;
+        }
+        for (const id of entries) {
+            // Dot-entries are never model ids: `publishStagedModel` parks the old
+            // install at `.<id>.gezmodel-backup-<uuid>` during a replace, and a
+            // crash mid-publish must not surface that backup as a duplicate model.
+            if (id.startsWith('.'))
+                continue;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            ids.push(id);
+        }
+    }
+    return ids;
+}
+/**
+ * Return the first overlay root containing a readable model manifest.
+ * Presence of an incomplete directory in a higher-priority root does not
+ * hide a complete machine model.
+ */
+export async function findModelRoot(roots, id) {
+    for (const root of modelSearchRoots(roots)) {
+        try {
+            const info = await lstat(join(root, id, 'manifest.json'));
+            if (info.isFile() && !info.isSymbolicLink())
+                return root;
+        }
+        catch {
+            // Try the next overlay root.
+        }
+    }
+    return null;
+}
+/**
+ * Resolve an id that a quant-suffix migration renamed away, by finding the
+ * install that records it as its {@link InstalledModelRenameRecord.renamedFrom}.
+ *
+ * Config pins, gezel frontmatter, eval caches, and session records all hold
+ * whatever id was current when they were written, and there is no way to
+ * find and rewrite every one of them. Keeping the former id resolvable is
+ * what makes the rename cosmetic rather than a breaking change.
+ *
+ * Only ever called on a miss, and only over directories whose name the
+ * former id prefixes — every rename target is the former id plus a suffix,
+ * so no other directory can be the answer.
+ */
+export async function findRenamedModelId(roots, formerId) {
+    if (!formerId)
+        return null;
+    for (const root of modelSearchRoots(roots)) {
+        let entries;
+        try {
+            entries = await readdir(root);
+        }
+        catch {
+            continue;
+        }
+        for (const id of entries) {
+            if (!id.startsWith(`${formerId}-`))
+                continue;
+            const parsed = await readFile(join(root, id, 'manifest.json'), 'utf8')
+                .then((raw) => JSON.parse(raw))
+                .catch(() => null);
+            if (parsed?.renamedFrom === formerId)
+                return id;
+        }
+    }
+    return null;
+}
+export async function modelExistsOnlyReadOnly(roots, id) {
+    const root = await findModelRoot(roots, id);
+    return root !== null && resolve(root) !== resolve(roots.writableRoot);
+}
+export const READ_ONLY_MODEL_CODE = 'read-only-model';
+/**
+ * Refusal to mutate a model that only exists in a read-only overlay root.
+ * Typed so HTTP routes can map it to a 4xx with the actionable message
+ * instead of letting it escape as an opaque 500.
+ */
+export class ReadOnlyModelError extends Error {
+    code = READ_ONLY_MODEL_CODE;
+    constructor(id) {
+        super(`model "${id}" is supplied by the read-only machine asset store; install a user-owned copy to replace it`);
+        this.name = 'ReadOnlyModelError';
+    }
+}
+export function readOnlyModelError(id) {
+    return new ReadOnlyModelError(id);
+}
+/**
+ * Remove a model directory, tolerating the file locks that make a naive
+ * `rm` flaky on Windows. Antivirus / Search-Indexer transient holds clear in
+ * a few hundred ms, so we retry with backoff. A *persistent* lock (a running
+ * llama-server has the GGUF open) never clears on its own — we surface an
+ * actionable message rather than the raw `EBUSY`/`EPERM` so the UI can tell
+ * the user to switch models first, instead of the delete looking like a no-op.
+ */
+export async function removeModelDir(itemDir, writableRoot = dirname(itemDir)) {
+    await assertModelStorePathSafe(writableRoot, itemDir);
+    const maxAttempts = 4;
+    for (let attempt = 1;; attempt++) {
+        try {
+            await rm(itemDir, { recursive: true, force: true });
+            return;
+        }
+        catch (err) {
+            const code = err?.code;
+            const locked = code === 'EBUSY' || code === 'EPERM' || code === 'EACCES' || code === 'ENOTEMPTY';
+            if (locked && attempt < maxAttempts) {
+                await new Promise((r) => setTimeout(r, 150 * attempt));
+                continue;
+            }
+            if (locked) {
+                throw new Error('Could not delete the model files — a file is still in use. If this model is loaded in a running chat, switch to another model (or wait a moment), then try deleting again.');
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * Hash every published payload file except the self-describing manifest.
+ *
+ * `precomputed` lets a caller that has *already* streamed a file through
+ * SHA-256 (the install path verifies every shard against the catalog hash
+ * before this runs) hand those digests in, keyed by the same '/'-joined
+ * relative path this returns. Matching files are taken from the cache
+ * instead of re-read — a multi-GB install would otherwise hash the whole
+ * payload from disk twice. Files on disk but absent from the cache (stale
+ * shards from a prior install, a dropped mmproj) are still enumerated and
+ * hashed, so the returned map always describes the real on-disk payload.
+ */
+export async function hashModelPayloadFiles(modelDir, precomputed) {
+    const result = {};
+    const root = resolve(modelDir);
+    for (const path of await listModelPayloadFiles(root)) {
+        result[path] = precomputed?.[path] ?? (await sha256File(join(root, ...path.split('/'))));
+    }
+    return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * Delete payload files in a model directory that the freshly-written install no
+ * longer references. When a model updates in place to a different quant/filename
+ * (e.g. gemma4-12b-q4 moving from `…-Q4_K_M.gguf` to `…-qat-UD-Q4_K_XL.gguf`),
+ * the rename publishes the new weights but the old file lingers — tens of GB of
+ * orphaned weights for one slot. `keep` is the set of '/'-joined relative paths
+ * the new manifest references (weights + shards + mmproj + draft). manifest.json
+ * and in-flight `.partial` files are never candidates (listModelPayloadFiles
+ * already excludes them). Returns the relative paths removed. Best-effort per
+ * file — a file we can't remove is left rather than aborting the install.
+ */
+export async function pruneModelPayloadFiles(modelDir, keep) {
+    const removed = [];
+    const root = resolve(modelDir);
+    for (const rel of await listModelPayloadFiles(root)) {
+        if (keep.has(rel))
+            continue;
+        try {
+            await rm(join(root, ...rel.split('/')), { force: true });
+            removed.push(rel);
+        }
+        catch {
+            // Leave a file we can't remove; the reclaim/prune runs again later.
+        }
+    }
+    return removed;
+}
+/**
+ * Revalidate a read-only machine model on first adoption. The user-owned
+ * cache records file identity + size + mtime; any change forces full SHA-256
+ * verification again. The cache itself never lives beside shared models.
+ */
+export async function verifyReadOnlyModelPayload(roots, modelRoot, id, expected, onReject) {
+    if (resolve(modelRoot) === resolve(roots.writableRoot)) {
+        try {
+            await assertModelStorePathSafe(roots.writableRoot, join(modelRoot, id));
+            return true;
+        }
+        catch (error) {
+            onReject?.(error instanceof Error ? error.message : String(error));
+            return false;
+        }
+    }
+    const key = readOnlyVerificationKey(roots, modelRoot, id, expected);
+    let verification = readOnlyVerificationInFlight.get(key);
+    if (!verification) {
+        verification = (async () => {
+            try {
+                return await verifyReadOnlyModelPayloadUnchecked(roots, modelRoot, id, expected);
+            }
+            catch (err) {
+                return err instanceof Error ? err.message : String(err);
+            }
+        })();
+        readOnlyVerificationInFlight.set(key, verification);
+        void verification.then(() => {
+            if (readOnlyVerificationInFlight.get(key) === verification) {
+                readOnlyVerificationInFlight.delete(key);
+            }
+        });
+    }
+    const reason = await verification;
+    if (reason !== null)
+        onReject?.(reason);
+    return reason === null;
+}
+function readOnlyVerificationKey(roots, modelRoot, id, expected) {
+    const expectedFingerprint = createHash('sha256')
+        .update(JSON.stringify(Object.entries(expected ?? {})
+        .map(([path, sha]) => [path, sha.toLowerCase()])
+        .sort(([left], [right]) => left.localeCompare(right))))
+        .digest('hex');
+    return `${resolve(roots.writableRoot)}\n${resolve(modelRoot)}\n${id}\n${expectedFingerprint}`;
+}
+/** Returns null when the payload verifies, else a human-readable rejection reason. */
+async function verifyReadOnlyModelPayloadUnchecked(roots, modelRoot, id, expected) {
+    if (resolve(modelRoot) === resolve(roots.writableRoot))
+        return null;
+    if (!expected || Object.keys(expected).length === 0) {
+        return 'shared manifest has no fileSha256 map (published before hash backfill?)';
+    }
+    if (Object.entries(expected).some(([path, sha]) => !isSafeModelPath(path) || !isSha256(sha))) {
+        return 'shared manifest fileSha256 map contains an unsafe path or malformed hash';
+    }
+    const modelDir = resolve(modelRoot, id);
+    const actualPaths = await listModelPayloadFiles(modelDir);
+    const expectedPaths = Object.keys(expected).sort();
+    if (actualPaths.length !== expectedPaths.length ||
+        actualPaths.some((path, index) => path !== expectedPaths[index])) {
+        const extra = actualPaths.filter((path) => !expectedPaths.includes(path));
+        const missing = expectedPaths.filter((path) => !actualPaths.includes(path));
+        return `shared payload files do not match the manifest (extra: [${extra.join(', ')}], missing: [${missing.join(', ')}])`;
+    }
+    const identities = {};
+    for (const path of expectedPaths) {
+        const absolute = join(modelDir, ...path.split('/'));
+        const info = await lstat(absolute);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            return `shared payload entry is not a regular file: ${path}`;
+        }
+        identities[path] = {
+            dev: info.dev,
+            ino: info.ino,
+            size: info.size,
+            mtimeMs: info.mtimeMs,
+            sha256: expected[path].toLowerCase(),
+        };
+    }
+    const cachePath = join(dirname(roots.writableRoot), 'shared-model-verification.json');
+    const cacheKey = `${resolve(modelRoot)}\n${id}`;
+    const cache = await readVerificationCache(cachePath);
+    if (JSON.stringify(cache[cacheKey]) === JSON.stringify(identities))
+        return null;
+    for (const path of expectedPaths) {
+        const actual = await sha256File(join(modelDir, ...path.split('/')));
+        if (actual !== expected[path].toLowerCase()) {
+            return `shared payload hash mismatch for ${path}`;
+        }
+    }
+    await updateVerificationCache(cachePath, cacheKey, identities);
+    return null;
+}
+/**
+ * Machine daemons use a restrictive umask for private state. After a model
+ * has been fully downloaded and hash-verified, make only that published
+ * bundle traversable/readable by ordinary users.
+ *
+ * Windows needs an explicit inheritance reset. A model imported through the
+ * private transaction area, or moved from the legacy private model store,
+ * keeps its old DACL when it is renamed within the ProgramData volume. Merely
+ * placing that directory below the public `assets` container therefore does
+ * not make it readable. Resetting the published tree makes it inherit the
+ * installer's read-only BUILTIN\Users ACE without granting users write access.
+ */
+export async function makeSharedModelReadable(modelDir, env = process.env) {
+    if (env.GEZEL_SYSTEM_SCOPE !== '1')
+        return;
+    const configured = env[SHARED_ASSETS_ENV]?.trim();
+    if (!configured || !isAbsolute(configured))
+        return;
+    const sharedModels = resolve(configured, 'models');
+    const target = resolve(modelDir);
+    const rel = relative(sharedModels, target);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`refusing to publish model outside the shared asset store: ${target}`);
+    }
+    // This must precede chmodTree and icacls /T: discovering a junction after a
+    // recursive permission rewrite is already too late.
+    await assertModelStorePathSafe(sharedModels, target);
+    await chmodTree(target);
+    if (process.platform === 'win32') {
+        await resetWindowsAclToInherited(target);
+    }
+    let ancestor = dirname(target);
+    while (ancestor === sharedModels || ancestor.startsWith(`${sharedModels}${sep}`)) {
+        const info = await lstat(ancestor);
+        if (!info.isDirectory() || info.isSymbolicLink()) {
+            throw new Error(`refusing a non-directory ancestor in the shared model store: ${ancestor}`);
+        }
+        try {
+            await chmod(ancestor, 0o755);
+        }
+        catch {
+            // Windows permissions are established by the installer DACL.
+        }
+        if (ancestor === sharedModels)
+            break;
+        ancestor = dirname(ancestor);
+    }
+}
+async function resetWindowsAclToInherited(target) {
+    try {
+        await execFileAsync('icacls.exe', [target, '/reset', '/T', '/L', '/Q'], {
+            maxBuffer: 256 * 1024,
+            ...windowsHeadlessSpawnOptions(),
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`could not publish shared model permissions for ${target}: ${detail}`);
+    }
+}
+async function chmodTree(path) {
+    const info = await lstat(path).catch(() => null);
+    if (!info)
+        return;
+    if (info.isSymbolicLink()) {
+        throw new Error(`refusing to publish a symlink in the shared model store: ${path}`);
+    }
+    if (!info.isDirectory()) {
+        try {
+            await chmod(path, 0o644);
+        }
+        catch {
+            // Windows permissions are established by the installer DACL.
+        }
+        return;
+    }
+    const entries = await readdir(path, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        await chmodTree(join(path, entry.name));
+    }
+    try {
+        await chmod(path, 0o755);
+    }
+    catch {
+        // Windows permissions are established by the installer DACL.
+    }
+}
+/** Grace period before an abandoned download is reclaimed. Within it the
+ *  `.partial` files still serve as resume credit for a retried install. */
+export const ABANDONED_DOWNLOAD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Delete abandoned model downloads from the writable root.
+ *
+ * A directory qualifies only when ALL of these hold — the gates are meant to
+ * make "we delete something the user wanted" impossible:
+ *   - no `manifest.json` (never completed an install, invisible to every
+ *     listing surface),
+ *   - contains at least one `.partial` file (the downloader's signature —
+ *     a hand-placed model directory without one is never touched),
+ *   - nothing in it was written for `ttlMs` (default 7 days — within that
+ *     window the `.partial` files are resume credit for a retried install),
+ *   - not currently being installed (`activeIds`).
+ *
+ * Only the writable root is swept — read-only machine roots belong to the
+ * machine service, which runs its own sweep. Callers run this once at boot;
+ * errors are contained per-directory so one unreadable entry can't stop the
+ * sweep.
+ */
+export async function reclaimAbandonedModelDownloads(opts) {
+    const ttlMs = opts.ttlMs ?? ABANDONED_DOWNLOAD_TTL_MS;
+    const now = opts.now ?? Date.now();
+    const reclaimed = [];
+    let entries;
+    try {
+        entries = await readdir(opts.writableRoot);
+    }
+    catch {
+        return reclaimed;
+    }
+    for (const id of entries) {
+        if (id.startsWith('.') || opts.activeIds?.has(id))
+            continue;
+        const dir = join(opts.writableRoot, id);
+        try {
+            const info = await lstat(dir);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                continue;
+            await assertModelStorePathSafe(opts.writableRoot, dir);
+            const scan = await scanAbandonedCandidate(dir);
+            if (!scan || !scan.hasPartial || now - scan.newestMtimeMs < ttlMs)
+                continue;
+            await rm(dir, { recursive: true, force: true });
+            reclaimed.push({ id, bytes: scan.totalBytes });
+        }
+        catch {
+            // Skip directories we can't read or remove; the next sweep retries.
+        }
+    }
+    return reclaimed;
+}
+export async function inspectModelDirectory(dir) {
+    try {
+        const rootInfo = await lstat(dir);
+        if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+            return null;
+        let bytes = 0;
+        let newestMtimeMs = rootInfo.mtimeMs;
+        let hasPartial = false;
+        let hasManifest = false;
+        const visit = async (current) => {
+            for (const entry of await readdir(current, { withFileTypes: true })) {
+                const absolute = join(current, entry.name);
+                if (entry.isSymbolicLink())
+                    continue;
+                if (entry.isDirectory()) {
+                    await visit(absolute);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                const info = await lstat(absolute);
+                newestMtimeMs = Math.max(newestMtimeMs, info.mtimeMs);
+                bytes += info.size;
+                if (entry.name.endsWith('.partial'))
+                    hasPartial = true;
+                if (entry.name === 'manifest.json')
+                    hasManifest = true;
+            }
+        };
+        await visit(dir);
+        return {
+            bytes,
+            updatedAt: new Date(newestMtimeMs).toISOString(),
+            hasPartial,
+            hasManifest,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List incomplete model downloads in the writable root — directories with no
+ * `manifest.json` (so they're invisible to `listInstalled` and every other
+ * listing surface) that nonetheless hold bytes. These are interrupted or
+ * unverified downloads: they can hold tens of GB yet the user has no way to
+ * see or manage them until the 7-day {@link reclaimAbandonedModelDownloads}
+ * sweep silently removes them. Surfacing them lets the UI offer resume/delete
+ * immediately. Currently-installing ids are excluded (they show as live
+ * progress elsewhere). Sorted largest-first — the most disk to reclaim.
+ */
+export async function listIncompleteModelDownloads(opts) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(opts.writableRoot);
+    }
+    catch {
+        return out;
+    }
+    for (const id of entries) {
+        if (id.startsWith('.') || opts.activeIds?.has(id))
+            continue;
+        const dir = join(opts.writableRoot, id);
+        try {
+            const info = await lstat(dir);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                continue;
+            const scan = await scanAbandonedCandidate(dir);
+            if (!scan || scan.totalBytes === 0)
+                continue;
+            out.push({
+                id,
+                bytes: scan.totalBytes,
+                updatedAt: new Date(scan.newestMtimeMs).toISOString(),
+                hasPartial: scan.hasPartial,
+            });
+        }
+        catch {
+            // Skip directories we can't read; they simply don't surface.
+        }
+    }
+    out.sort((a, b) => b.bytes - a.bytes);
+    return out;
+}
+/**
+ * Returns null when the directory holds a `manifest.json` (a real install —
+ * never a reclamation candidate), else its abandoned-download profile.
+ */
+async function scanAbandonedCandidate(dir) {
+    const profile = await inspectModelDirectory(dir);
+    if (!profile || profile.hasManifest)
+        return null;
+    return {
+        hasPartial: profile.hasPartial,
+        newestMtimeMs: new Date(profile.updatedAt).getTime(),
+        totalBytes: profile.bytes,
+    };
+}
+function isSafeModelPath(path) {
+    return (path.length > 0 &&
+        !path.startsWith('/') &&
+        !path.includes('\\') &&
+        path.split('/').every((segment) => segment.length > 0 && segment !== '.' && segment !== '..'));
+}
+async function listModelPayloadFiles(modelDir) {
+    const root = resolve(modelDir);
+    const result = [];
+    const visit = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const absolute = join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`refusing a symlink in a model bundle: ${absolute}`);
+            }
+            if (entry.isDirectory()) {
+                await visit(absolute);
+            }
+            else if (entry.isFile()) {
+                // `.partial` is an in-flight download (same rule as
+                // listBundleModelFiles); dot-files are OS droppings like .DS_Store.
+                // Neither is payload — an interrupted update or a Finder visit must
+                // not make an otherwise-complete shared model fail verification.
+                if (entry.name.endsWith('.partial') || entry.name.startsWith('.'))
+                    continue;
+                const path = relative(root, absolute).split(sep).join('/');
+                if (path !== 'manifest.json')
+                    result.push(path);
+            }
+        }
+    };
+    await visit(root);
+    return result.sort();
+}
+function isSha256(value) {
+    return /^[a-f0-9]{64}$/i.test(value);
+}
+/**
+ * Read buffer for hashing multi-GB model files off disk. The default
+ * `createReadStream` highWaterMark is 64 KB, which for a 7 GB file means
+ * ~110k `'data'` events — one event-loop turn each. Inside the daemon's busy
+ * event loop (chat, scheduler, index scans) those turns queue behind other
+ * work and the hash starves: a file that hashes in ~9s idle took 15+ minutes
+ * in the running service. A 16 MB buffer cuts it to ~400 turns, so a
+ * congested loop barely affects wall time (measured: a 6.3 GB file that
+ * hashed in ~9s idle did not finish in 2 min at 64 KB under a busy loop, but
+ * stayed ~10s at 16 MB). Hash correctness with this buffer is covered by the
+ * hashModelPayloadFiles tests in storage-roots.test.ts.
+ */
+export const MODEL_HASH_READ_BUFFER_BYTES = 16 * 1024 * 1024;
+function sha256File(path) {
+    return new Promise((resolveHash, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(path, { highWaterMark: MODEL_HASH_READ_BUFFER_BYTES });
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', () => resolveHash(hash.digest('hex')));
+    });
+}
+async function readVerificationCache(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function writeVerificationCache(path, cache) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+/** Merge cache entries serially so concurrent checks for different models do
+ * not overwrite each other's freshly verified identity records. */
+async function updateVerificationCache(path, key, identities) {
+    const previous = verificationCacheWrites.get(path) ?? Promise.resolve();
+    const write = previous
+        .catch(() => { })
+        .then(async () => {
+        const latest = await readVerificationCache(path);
+        latest[key] = identities;
+        await writeVerificationCache(path, latest);
+    });
+    verificationCacheWrites.set(path, write);
+    try {
+        await write;
+    }
+    finally {
+        if (verificationCacheWrites.get(path) === write)
+            verificationCacheWrites.delete(path);
+    }
+}