@hearsay-tools/squawk 0.0.0-stage → 0.17.0-pr3058.5683

package/dist/workspace/agent-profiles.js

@@ -0,0 +1,190 @@
+import { realpathSync } from 'node:fs';
+import { readdir, realpath } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { isOmpProfileName, ompProfileName, profileEnv, looksLikeProfileDir } from '../core/agent-profiles.js';
+import { agentHomePaths, expandTilde, ompProfilesDir } from '../paths.js';
+import { DEFAULT_AGENT_ACCOUNT_ID, loadAgentAccounts, selectionFor, } from './agent-accounts.js';
+/**
+ * The implicit account for a provider: whatever `agentHomePaths()` discovers, which already
+ * honours the vendors' own `CLAUDE_CONFIG_DIR` / `CODEX_HOME` / `XDG_CONFIG_HOME`. Setting one of
+ * those on the cezar process therefore moves the DEFAULT account rather than being ignored.
+ */
+export function defaultAgentProfile(provider, env = process.env) {
+    const home = agentHomePaths(env);
+    const path = { claude: home.claude, codex: home.codex, opencode: home.opencodeConfig, pi: home.pi, cursor: home.cursor, omp: home.omp }[provider];
+    return {
+        id: DEFAULT_AGENT_ACCOUNT_ID,
+        provider,
+        label: 'Default',
+        configDir: path,
+        path,
+        isDefault: true,
+    };
+}
+/** Expand a stored account into its resolved form. Pure; the caller supplies the row. */
+export function resolveStoredProfile(account) {
+    return {
+        id: account.id,
+        provider: account.provider,
+        label: account.label || account.id,
+        configDir: account.configDir,
+        path: expandTilde(account.configDir),
+        isDefault: false,
+    };
+}
+/** Every account for `provider`, discovered default first, then the stored extras in file order. */
+export function profilesForProvider(store, provider, env = process.env) {
+    return [
+        defaultAgentProfile(provider, env),
+        ...store.accounts.filter((a) => a.provider === provider).map(resolveStoredProfile),
+    ];
+}
+/** Every account across every provider — the listing route's source. */
+export function listAgentProfiles(store, providers, env = process.env) {
+    return providers.flatMap((provider) => profilesForProvider(store, provider, env));
+}
+/**
+ * Resolve explicit choice, then project selection, then discovered default. Unknown selections
+ * fall back here; a known unavailable named account must fail later availability checks.
+ */
+export function selectProfile(store, options) {
+    const { provider, repoRoot, profileId } = options;
+    const env = options.env ?? process.env;
+    const chosen = profileId ?? selectionFor(store, repoRoot, provider);
+    if (chosen === undefined || chosen === DEFAULT_AGENT_ACCOUNT_ID)
+        return defaultAgentProfile(provider, env);
+    const stored = store.accounts.find((a) => a.id === chosen && a.provider === provider);
+    return stored ? resolveStoredProfile(stored) : defaultAgentProfile(provider, env);
+}
+/**
+ * The env a spawned `provider` process needs for the account selected by `repoRoot`/`profileId`.
+ *
+ * `{}` for the default account, which is the whole point: the zero-config path adds nothing to the
+ * child environment. Reads the store per call (see the module note). An unreadable home degrades to
+ * the default account, which is the behaviour cezar had before accounts existed. The one throw is
+ * `AgentAccountUnavailableError`, for a named account that would open another folder than its own
+ * (`namedAccountUnavailable`); spawning bare instead would bill the default while the UI names the
+ * stored account.
+ */
+export async function resolveProfileEnvForRoot(repoRoot, provider, profileId, env = process.env, home) {
+    let store;
+    try {
+        store = await loadAgentAccounts(home);
+    }
+    catch {
+        return { profile: defaultAgentProfile(provider, env), env: {} };
+    }
+    const profile = selectProfile(store, { provider, repoRoot, profileId, env });
+    // The default account contributes nothing: `agentHomePaths()` already reflects whatever the host
+    // env says, so re-exporting it would be a no-op at best and a surprise at worst.
+    if (profile.isDefault)
+        return { profile, env: {} };
+    const unavailable = namedAccountUnavailable(provider, profile.path, env);
+    if (unavailable !== null)
+        throw new AgentAccountUnavailableError(unavailable);
+    return { profile, env: profileEnv(provider, profile.path) };
+}
+/** Whether an account's directory exists and looks like the agent wrote it. Never throws. */
+export async function profileDirState(provider, path) {
+    let entries;
+    try {
+        entries = await readdir(path);
+    }
+    catch {
+        return { exists: false, looksValid: false };
+    }
+    return { exists: true, looksValid: looksLikeProfileDir(provider, entries) };
+}
+export async function resolveRuntimeAuthVerificationTarget(provider, profileId, home) {
+    if (profileId === undefined || profileId === DEFAULT_AGENT_ACCOUNT_ID)
+        return { kind: 'default' };
+    let store;
+    try {
+        store = await loadAgentAccounts(home);
+    }
+    catch {
+        return null;
+    }
+    const account = store.accounts.find((a) => a.id === profileId && a.provider === provider);
+    return account
+        ? { kind: 'profile', id: account.id, configDir: resolveStoredProfile(account).path }
+        : null;
+}
+/**
+ * Why `path` cannot be a named omp account, or `null` when it can. `path` is already expanded.
+ *
+ * An omp account is an omp profile, selected by NAME (`OMP_PROFILE`), and omp resolves that name
+ * under its own root: `~/<PI_CONFIG_DIR or .omp>/profiles/<name>`. A folder anywhere else would
+ * make omp open a different folder than the one Settings names, so it is refused here rather than
+ * discovered at run time. The parent is compared through `realpath`, so the real spelling of a
+ * profiles dir behind a symlinked home is the same place; the profile entry itself may be a symlink
+ * to a folder elsewhere, which omp follows. Synchronous, because an owned worker's launch
+ * (`boundWorkerAccountEnv`) repeats the check through `namedAccountUnavailable`.
+ */
+export function ompProfileDirError(path, env = process.env) {
+    const profilesDir = ompProfilesDir(env);
+    const name = ompProfileName(path);
+    const segments = path.split(/[\\/]+/).filter((segment) => segment !== '');
+    const last = segments[segments.length - 1] ?? '';
+    if (name === null && segments[segments.length - 2] === 'profiles' && !isOmpProfileName(last)) {
+        return `"${last}" is not an omp profile name: use lowercase letters, digits, ".", "_" or "-" (not "default")`;
+    }
+    const parent = dirname(resolve(path));
+    if (name === null || !sameDirSync(parent, profilesDir)) {
+        return `an omp account is an omp profile: the folder must be ${profilesDir}/<name>`;
+    }
+    return null;
+}
+/**
+ * A named account cezar refuses to spawn as it stands. The caller fails the step or answers with
+ * the message. It never falls back to the default account, which would bill an account the UI
+ * does not name.
+ */
+export class AgentAccountUnavailableError extends Error {
+    name = 'AgentAccountUnavailableError';
+}
+/**
+ * Why a named account would open another folder than its own if spawned now, or `null`.
+ *
+ * Only omp can. Its account is a profile NAME, and omp resolves the name under the root it computes
+ * at spawn from `HOME` and `PI_CONFIG_DIR`. The route checked the folder against the root of the
+ * day it was added. After either variable changes, `OMP_PROFILE=<name>` opens
+ * `<new root>/profiles/<name>`, another profile or a fresh empty one, while Settings still shows the
+ * stored folder. Every other provider is handed the folder itself. `env` is the env the child takes
+ * `HOME` and `PI_CONFIG_DIR` from.
+ */
+export function namedAccountUnavailable(provider, path, env = process.env) {
+    if (provider !== 'omp' || ompProfileDirError(path, env) === null)
+        return null;
+    return `omp would not open this account's folder ${path}: omp now reads profiles from ${ompProfilesDir(env)}, `
+        + 'because HOME or PI_CONFIG_DIR changed after the account was added. Point the account at a profile there, '
+        + 'or restore the old value.';
+}
+function sameDirSync(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is `path` the same directory as an existing account's (or the default's)?
+ *
+ * Compared through `realpath` so two spellings of one dir — a symlink, a trailing slash — cannot
+ * become two accounts that silently share a session store. A path that does not exist yet cannot
+ * collide with anything, which is correct: the CLI has not created it, so it is nobody's home.
+ */
+export async function sameProfileDir(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return (await realpath(a)) === (await realpath(b));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=agent-profiles.js.map

package/dist/workspace/agent-profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-profiles.js","sourceRoot":"","sources":["../../src/workspace/agent-profiles.ts"],"names":[],"mappings":"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"}

package/dist/workspace/backup-cli.d.ts

@@ -0,0 +1,9 @@
+import type { Home } from '../home/home.ts';
+import { type BackupFile } from './backups.ts';
+export declare function restoreBackup(file: BackupFile, at: string | undefined, home: Home): Promise<string>;
+/** Cockpit recovery never falls back to a rotation when another cockpit already resolved it. */
+export declare function restorePinnedRecovery(file: BackupFile, home: Home, detectedAt?: string): string | undefined;
+/** `contained` marks a legacy home listed before migration: the list reads nothing outside it. */
+export declare function runBackupCommand(argv: string[], _env: NodeJS.ProcessEnv, home: Home, legacyCanary?: boolean, { contained }?: {
+    contained?: boolean | undefined;
+}): Promise<number>;

package/dist/workspace/backup-cli.js

@@ -0,0 +1,147 @@
+import { logPrefix } from '../home/display.js';
+import { commandText } from '../home/command.js';
+import { readFileSync } from 'node:fs';
+import { homeFileLocation } from '../home/file-location.js';
+import { HomeStore } from '../home/store.js';
+import { isBackupFile, listBackups, parseBackupArgs, restoreLimit, restoreRequest } from './backups.js';
+import { storeSchema } from './agent-accounts.js';
+import { workspaceConfigSchema } from './config.js';
+import { resolveLegacyRecovery } from '../home/legacy-recovery.js';
+import { REBRAND_SWITCH } from '../home/switch.js';
+const HELP = commandText(`usage:
+  cez backup list [<file>]
+  cez backup restore <file> [--at <time>]
+
+Restore the newest backup, or the newest at or before an ISO UTC time.
+Use a home-relative file, such as config.json or remote-settings/4321.json.
+Account config directories are not restored.`);
+function backupHelp(legacyCanary) {
+    return HELP + (legacyCanary ? commandText(`\n\nLegacy home changes:
+  cez backup import <file>   merge changes from the old home
+  cez backup ignore <file>   keep the live file and clear the old-home incident
+Import requires a successful backup. Deleted legacy files can only be ignored.`) : '');
+}
+/** Host CLI actions share the recovery writer; grant files remain blocked in HTTP. */
+function resolveLegacyCommand(command, file, validArgs, home, enabled) {
+    if (command !== 'import' && command !== 'ignore')
+        return false;
+    if (!enabled)
+        throw new Error('Legacy home import and ignore are not enabled.');
+    if (!file || !validArgs)
+        throw new Error(backupHelp(enabled));
+    resolveLegacyRecovery(home, file, undefined, command, enabled);
+    console.log(`Resolved legacy home change for ${file} with ${command}.`);
+    return true;
+}
+export async function restoreBackup(file, at, home) {
+    if (!isBackupFile(file))
+        throw new Error(`Unsupported backup file: ${file}`);
+    const limit = restoreLimit(at);
+    if (Number.isNaN(limit))
+        throw new Error('Invalid --at time; use an ISO UTC time');
+    const store = new HomeStore(home);
+    if (at === undefined) {
+        const recovered = restorePinnedRecovery(file, home);
+        if (recovered)
+            return recovered;
+    }
+    const entry = listBackups(file, home).find((item) => Date.parse(item.time) <= limit);
+    if (!entry)
+        throw new Error(`No backup for ${file}${at ? ` at or before ${at}` : ''}`);
+    const bytes = readFileSync(entry.path);
+    const restored = restoreBytes(file, bytes);
+    store.restoreFile(homeFileLocation(home, file).path, restored);
+    if (file === 'config.json')
+        refreshSnapshot(store, home);
+    return entry.time;
+}
+/** Cockpit recovery never falls back to a rotation when another cockpit already resolved it. */
+export function restorePinnedRecovery(file, home, detectedAt) {
+    if (!isBackupFile(file))
+        throw new Error(`Unsupported backup file: ${file}`);
+    const store = new HomeStore(home);
+    const recovered = store.restoreRecovery(homeFileLocation(home, file).path, detectedAt);
+    if (recovered && file === 'config.json')
+        refreshSnapshot(store, home);
+    return recovered;
+}
+const warnedSnapshots = new Set();
+/** A failed auxiliary snapshot never changes the result of the committed primary restore. */
+function refreshSnapshot(store, home) {
+    try {
+        let bytes;
+        try {
+            bytes = readFileSync(home.workspaceConfig);
+        }
+        catch (error) {
+            // Restoring an absent pinned HEAD must not recreate it from a stale snapshot.
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        store.replace(`${home.workspaceConfig}.bak`, bytes);
+    }
+    catch (error) {
+        if (warnedSnapshots.has(home.workspaceConfig))
+            return;
+        warnedSnapshots.add(home.workspaceConfig);
+        console.warn(`${logPrefix()} workspace backup unavailable after restore (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+function restoreBytes(file, bytes) {
+    if (file !== 'config.json' && file !== 'agent-accounts.json')
+        return bytes;
+    const raw = JSON.parse(bytes.toString('utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('Backup must contain a JSON object');
+    let restored;
+    if (file === 'config.json') {
+        const config = workspaceConfigSchema.parse(raw);
+        warnDroppedEntries(raw, 'projects', config.projects.length);
+        restored = config;
+    }
+    else {
+        const accounts = storeSchema.parse(raw);
+        warnDroppedEntries(raw, 'accounts', accounts.accounts.length);
+        restored = accounts;
+    }
+    return Buffer.from(`${JSON.stringify(restored, null, 2)}\n`);
+}
+function warnDroppedEntries(raw, key, kept) {
+    const original = raw[key];
+    if (Array.isArray(original) && original.length > kept) {
+        console.warn(`${logPrefix()} restore dropped ${original.length - kept} invalid ${key} entries from the snapshot`);
+    }
+}
+/** `contained` marks a legacy home listed before migration: the list reads nothing outside it. */
+export async function runBackupCommand(argv, _env, home, legacyCanary = REBRAND_SWITCH, { contained = false } = {}) {
+    try {
+        const args = parseBackupArgs(argv);
+        const { values, positionals } = args;
+        if (values.help) {
+            console.log(backupHelp(legacyCanary));
+            return 0;
+        }
+        const [command, file] = positionals;
+        if (file !== undefined && !isBackupFile(file))
+            throw new Error('File must be a supported home-relative HomeStore file');
+        if (resolveLegacyCommand(command, file, positionals.length === 2 && values.at === undefined, home, legacyCanary))
+            return 0;
+        if (command === 'list' && positionals.length <= 2 && values.at === undefined) {
+            console.log(JSON.stringify(listBackups(file, home, { contained }), null, 2));
+            return 0;
+        }
+        const restore = restoreRequest(args);
+        if (restore) {
+            const time = await restoreBackup(restore.file, restore.at, home);
+            console.log(`Restored ${restore.file} from ${time}. Only the home file was restored.`);
+            return 0;
+        }
+        throw new Error(backupHelp(legacyCanary));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+//# sourceMappingURL=backup-cli.js.map

package/dist/workspace/backup-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-cli.js","sourceRoot":"","sources":["../../src/workspace/backup-cli.ts"],"names":[],"mappings":"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"}

package/dist/workspace/backups.d.ts

@@ -0,0 +1,36 @@
+import type { Home } from '../home/home.ts';
+export declare const BACKUP_FILES: readonly ['config.json', 'config.json.bak', 'agent-accounts.json', 'ui-state.json', 'server.json', 'server.install.lock'];
+export type BackupFile = string;
+export interface BackupEntry {
+    file: BackupFile;
+    time: string;
+    path: string;
+}
+export declare function isBackupFile(value: string): value is BackupFile;
+/** The newest allowed backup time for `--at`; NaN when the value is not an ISO UTC time. */
+export declare function restoreLimit(at: string | undefined): number;
+/** The one parser for `backup` arguments: the command and its home entry read the same options. */
+export declare function parseBackupArgs(argv: readonly string[]): {
+    values: {
+        at?: string;
+        help?: boolean;
+    };
+    positionals: string[];
+};
+/** `restore <file> [--at <time>]` with one supported file and no help; anything else is not a restore. */
+export declare function restoreRequest({ values, positionals }: ReturnType<typeof parseBackupArgs>): {
+    file: BackupFile;
+    at: string | undefined;
+} | undefined;
+/** A restore that will run: its arguments parse and its time is valid. Anything else is help or a usage error. */
+export declare function isValidRestore(argv: readonly string[]): boolean;
+/** `contained` lists a home this command does not own: every read must stay inside its root. */
+export declare function listBackups(file: BackupFile | undefined, home: string | Home, { contained }?: {
+    contained?: boolean | undefined;
+}): BackupEntry[];
+/** Best effort before replacement or removal. Older raw lock snapshots stay listed and byte-for-byte restorable. */
+export declare function backupBeforeWrite(path: string, next: unknown, options?: {
+    home?: Home | string;
+    unavailable?: unknown;
+    required?: boolean | undefined;
+}): void;

package/dist/workspace/backups.js

@@ -0,0 +1,249 @@
+import { logPrefix } from '../home/display.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { assertCezarHomeWriteIsSandboxed } from '../paths.js';
+import { assertHomePaths } from '../home/boundary.js';
+import { homeFileSchema } from '../contract/index.js';
+import { homeFileLocation, homePathLocation } from '../home/file-location.js';
+export const BACKUP_FILES = ['config.json', 'config.json.bak', 'agent-accounts.json', 'ui-state.json', 'server.json', 'server.install.lock'];
+export function isBackupFile(value) {
+    return homeFileSchema.safeParse(value).success;
+}
+/** The newest allowed backup time for `--at`; NaN when the value is not an ISO UTC time. */
+export function restoreLimit(at) {
+    if (at === undefined)
+        return Infinity;
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(at) ? Date.parse(at) : NaN;
+}
+/** The one parser for `backup` arguments: the command and its home entry read the same options. */
+export function parseBackupArgs(argv) {
+    return parseArgs({ args: [...argv], allowPositionals: true, options: {
+            at: { type: 'string' }, help: { type: 'boolean', short: 'h' },
+        } });
+}
+/** `restore <file> [--at <time>]` with one supported file and no help; anything else is not a restore. */
+export function restoreRequest({ values, positionals }) {
+    const [command, file] = positionals;
+    if (values.help || command !== 'restore' || positionals.length !== 2 || file === undefined || !isBackupFile(file))
+        return undefined;
+    return { file, at: values.at };
+}
+/** A restore that will run: its arguments parse and its time is valid. Anything else is help or a usage error. */
+export function isValidRestore(argv) {
+    try {
+        const request = restoreRequest(parseBackupArgs(argv));
+        return request !== undefined && !Number.isNaN(restoreLimit(request.at));
+    }
+    catch {
+        return false;
+    }
+}
+function backupRoot(home) {
+    return typeof home === 'string' ? join(home, 'backups') : home.backups;
+}
+const readAny = () => true;
+function readInside(root) {
+    return path => { try {
+        assertHomePaths(root, [path]);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+}
+/** Names are sortable UTC times, with colons replaced for Windows. */
+function entries(home, file, directory = join(backupRoot(home), file), readable = readAny) {
+    const dir = directory;
+    if (!readable(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.flatMap((name) => {
+        const match = /^(\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d\.\d{3}Z)-([a-f0-9]{8})\.json$/.exec(name);
+        if (!match)
+            return [];
+        const path = join(dir, name);
+        if (!readable(path))
+            return [];
+        try {
+            if (createHash('sha256').update(readFileSync(path)).digest('hex').slice(0, 8) !== match[2])
+                return [];
+        }
+        catch {
+            return [];
+        }
+        const time = match[1].replace(/T(\d\d)-(\d\d)-(\d\d)/, 'T$1:$2:$3');
+        return [{ file, time, path }];
+    }).sort((a, b) => b.time.localeCompare(a.time) || b.path.localeCompare(a.path));
+}
+/** Discover backup keys even after the live file was removed. Never recurse into snapshots. */
+function backupFiles(home, readable) {
+    const files = [...BACKUP_FILES];
+    for (const family of ['remote-settings', 'server-instances']) {
+        const familyRoot = typeof home === 'string' ? home : homeFileLocation(home, `${family}/config.json`).root;
+        const directories = [join(backupRoot(home), family)];
+        if (typeof home === 'string' || home.layout === 'legacy')
+            directories.push(join(familyRoot, family, 'backups'));
+        for (const dir of directories) {
+            if (!readable(dir))
+                continue;
+            try {
+                for (const name of readdirSync(dir)) {
+                    const key = `${family}/${name}`;
+                    if (isBackupFile(key) && !files.includes(key))
+                        files.push(key);
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    return files;
+}
+function listedEntries(home, file, readable) {
+    const found = entries(home, file, undefined, readable);
+    const root = typeof home === 'string' ? home : home.root;
+    // P0/P1b used the basename under a named instance's own directory.
+    if ((typeof home === 'string' || home.layout === 'legacy') && file.includes('/') && ['config.json', 'agent-accounts.json'].includes(basename(file))) {
+        found.push(...entries(home, file, join(root, dirname(file), 'backups', basename(file)), readable));
+    }
+    found.sort((a, b) => b.time.localeCompare(a.time) || b.path.localeCompare(a.path));
+    if (file === 'config.json') {
+        const path = join(root, 'config.json.bak');
+        if (readable(path))
+            try {
+                const value = JSON.parse(readFileSync(path, 'utf8'));
+                if (value && typeof value === 'object' && !Array.isArray(value)) {
+                    // .bak is the newest recovery entry, including on coarse filesystem clocks.
+                    const time = new Date(Math.max(statSync(path).mtimeMs, found[0] ? Date.parse(found[0].time) + 1 : 0)).toISOString();
+                    found.unshift({ file, path, time });
+                }
+            }
+            catch { /* The loader also ignores an unreadable or corrupt recovery snapshot. */ }
+    }
+    return found;
+}
+/** `contained` lists a home this command does not own: every read must stay inside its root. */
+export function listBackups(file, home, { contained = false } = {}) {
+    if (file !== undefined && !isBackupFile(file))
+        throw new Error(`Unsupported backup file: ${file}`);
+    const readable = contained ? readInside(typeof home === 'string' ? home : home.root) : readAny;
+    return (file ? [file] : backupFiles(home, readable)).flatMap((name) => listedEntries(home, name, readable));
+}
+function prune(home, file, now) {
+    const days = new Set();
+    const cutoff = now.getTime() - 30 * 86_400_000;
+    for (const [index, entry] of entries(home, file).entries()) {
+        const day = entry.time.slice(0, 10);
+        const daily = Date.parse(entry.time) >= cutoff && !days.has(day);
+        days.add(day);
+        if (index < 20 || daily)
+            continue;
+        assertCezarHomeWriteIsSandboxed(entry.path);
+        unlinkSync(entry.path);
+    }
+}
+/** An install lock holds only the pid of a running installer: no data to recover, so no new snapshot. */
+const isInstallLock = (file) => file.endsWith('.install.lock');
+const warned = new Set();
+/** Best effort before replacement or removal. Older raw lock snapshots stay listed and byte-for-byte restorable. */
+export function backupBeforeWrite(path, next, options = {}) {
+    // The optional fallback preserves the exported P0 helper for root-file callers.
+    const home = options.home ?? dirname(path);
+    const root = typeof home === 'string' ? home : home.state;
+    const file = homePathLocation(home, path).file;
+    if (!isBackupFile(file))
+        throw new Error(`Unsupported backup file: ${file}`);
+    if (isInstallLock(file))
+        return;
+    let raw;
+    try {
+        raw = readFileSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        backupUnavailable(path, error, options.required);
+        return;
+    }
+    const bytes = next === null || Buffer.isBuffer(next) ? next : Buffer.from(`${JSON.stringify(next, null, 2)}\n`);
+    if (bytes !== null && raw.equals(bytes))
+        return;
+    if (options.unavailable !== undefined) {
+        backupUnavailable(path, options.unavailable, options.required);
+        return;
+    }
+    try {
+        const backups = backupRoot(home);
+        const dir = join(backups, file);
+        assertHomePaths(root, [dir]);
+        const now = new Date();
+        const latest = entries(home, file)[0];
+        const timestamp = new Date(Math.max(now.getTime(), latest ? Date.parse(latest.time) + 1 : 0));
+        const sha = createHash('sha256').update(raw).digest('hex').slice(0, 8);
+        for (const directory of [backups, dir]) {
+            assertCezarHomeWriteIsSandboxed(directory);
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+        }
+        writeSnapshot(dir, timestamp, sha, raw);
+        prune(home, file, now);
+    }
+    catch (error) {
+        backupUnavailable(path, error, options.required);
+    }
+}
+function backupUnavailable(path, error, required = false) {
+    if (required)
+        throw new Error(`Import refused: backup of ${path} is unavailable. Ignore this change or repair backups before importing.`, { cause: error });
+    warn(path, error);
+}
+/** Keep serialized writes ordered even with a coarse or adjusted clock. */
+function writeSnapshot(dir, timestamp, sha, raw) {
+    const stage = join(dir, `${randomUUID()}.tmp`);
+    assertCezarHomeWriteIsSandboxed(stage);
+    try {
+        writeFileSync(stage, raw, { mode: 0o600, flag: 'wx' });
+        for (;;) {
+            const target = join(dir, `${timestamp.toISOString().replaceAll(':', '-')}-${sha}.json`);
+            assertCezarHomeWriteIsSandboxed(target);
+            try {
+                // A hard link publishes complete bytes atomically and refuses an existing target.
+                linkSync(stage, target);
+                return;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                timestamp.setTime(timestamp.getTime() + 1);
+            }
+        }
+    }
+    finally {
+        assertCezarHomeWriteIsSandboxed(stage);
+        try {
+            unlinkSync(stage);
+        }
+        catch {
+            // Cleanup is best effort; a leftover staging name is never listed or restored.
+        }
+    }
+}
+function warn(path, error) {
+    if (warned.has(path))
+        return;
+    warned.add(path);
+    const code = error.code ?? (error instanceof Error ? error.message : 'unavailable');
+    console.warn(`${logPrefix()} backups for ${path} are unavailable (${code}); continuing the write`);
+}
+//# sourceMappingURL=backups.js.map