@dokebi/cli 0.4.0 → 0.4.2

package/dist/server.js

@@ -27,7 +27,7 @@
 import { execFile, spawn } from 'node:child_process';
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync, watch } from 'node:fs';
-import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { mkdir, open, readdir, readFile, rename, rm, stat, utimes, writeFile, } from 'node:fs/promises';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { basename, dirname, join } from 'node:path';
@@ -70,6 +70,145 @@ function daemonOnly() {
     if (process.platform === 'win32')
         throw new CliError('UNSUPPORTED_PLATFORM', 'Background start and stop need POSIX signals; on Windows use dokebi dev or dokebi start --foreground');
 }
+/** A start lock not refreshed for this long belongs to a start that died. */
+const LOCK_STALE_MS = 60_000;
+/** A start in progress refreshes its lock this often, however long it waits. */
+const LOCK_REFRESH_MS = 10_000;
+/** Breaking a stale lock takes milliseconds; a guard this old belongs to a process that died. */
+const BREAK_STALE_MS = 10_000;
+/**
+ * The start lock `.dokebi/run/start.lock` (R3). One start at a time holds it from before it
+ * reads the running state until its pid file is written, and `status`/`stop` take it to remove a
+ * stale pid file, so a pid file is only ever replaced or removed by the lock holder. It is
+ * created with `wx`; the holder refreshes it while it waits, so a lock older than LOCK_STALE_MS
+ * belongs to a start that died and is broken (see breakStale) before trying again.
+ */
+class StartLock {
+    file;
+    timer;
+    constructor(file) {
+        this.file = file;
+        this.timer = setInterval(() => {
+            const now = new Date();
+            utimes(file, now, now).catch((error) => {
+                reportError('START_LOCK_REFRESH_FAILED', 'Unable to refresh the start lock', error);
+            });
+        }, LOCK_REFRESH_MS);
+        this.timer.unref();
+    }
+    /** The lock, or undefined while another start holds it. */
+    static async acquire(file) {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            try {
+                await writeFile(file, String(process.pid), { flag: 'wx' });
+                debug('Start lock acquired', { file: basename(file) });
+                return new StartLock(file);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            let held;
+            try {
+                held = await stat(file);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+                debug('Start lock released meanwhile; trying again', { attempt });
+                continue;
+            }
+            if (Date.now() - held.mtimeMs < LOCK_STALE_MS)
+                return undefined;
+            if (!(await StartLock.breakStale(file, held)))
+                return undefined;
+        }
+        debug('Start lock still contended after several attempts');
+        return undefined;
+    }
+    /**
+     * Removes the stale lock `held` under the guard `<lock>.break` (created with `wx`), so only one
+     * process breaks it and never a lock another start created after `held` was read (same inode
+     * and time, checked under the guard). False when another process is breaking it right now.
+     * A guard older than BREAK_STALE_MS is left by a process that died within these few steps.
+     */
+    static async breakStale(file, held) {
+        const guard = `${file}.break`;
+        try {
+            await writeFile(guard, String(process.pid), { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let since;
+            try {
+                since = Date.now() - (await stat(guard)).mtimeMs;
+            }
+            catch (cause) {
+                if (!isMissing(cause))
+                    throw cause;
+                debug('The stale start lock was broken meanwhile; trying again');
+                return true;
+            }
+            if (since < BREAK_STALE_MS)
+                return false;
+            debug('Removing the guard of a lock break that died', { ageMs: Math.round(since) });
+            await rm(guard, { force: true });
+            return true;
+        }
+        try {
+            let now;
+            try {
+                now = await stat(file);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+                return true;
+            }
+            if (now.ino === held.ino && now.mtimeMs === held.mtimeMs) {
+                await rm(file, { force: true });
+                debug('Removed a stale start lock', { ageMs: Math.round(Date.now() - now.mtimeMs) });
+            }
+            return true;
+        }
+        finally {
+            await rm(guard, { force: true });
+        }
+    }
+    async release() {
+        clearInterval(this.timer);
+        await rm(this.file, { force: true });
+        debug('Start lock released', { file: basename(this.file) });
+    }
+}
+/**
+ * Removes the pid file when it still holds `record` (R3): under the start lock, so a start that
+ * wrote a newer record meanwhile keeps it. While a start holds the lock it is left to that start,
+ * which replaces the file anyway. `locked` is true when the caller holds the lock already.
+ */
+async function removeRecord(root, record, locked = false) {
+    const files = paths(root);
+    const lock = locked ? undefined : await StartLock.acquire(files.lock);
+    if (!locked && !lock) {
+        debug('A start holds the lock; leaving the pid file to it', { pid: record.pid });
+        return;
+    }
+    try {
+        const current = await readRecord(root);
+        if (current &&
+            (current.pid !== record.pid ||
+                current.startedAt !== record.startedAt ||
+                current.token !== record.token)) {
+            debug('The pid file names a newer start; keeping it', { pid: record.pid, now: current.pid });
+            return;
+        }
+        await rm(files.pid, { force: true });
+    }
+    finally {
+        await lock?.release();
+    }
+}
 async function readRecord(root) {
     let text;
     try {
@@ -118,6 +257,9 @@ async function procInfo(pid) {
         ]);
         // Fields after the parenthesised command name: state is field 3, starttime field 22.
         const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        // A zombie has exited and only waits for its parent to reap it: gone for every caller here.
+        if (fields[0] === 'Z')
+            return undefined;
         const ticks = Number(fields[19]);
         const boot = Number(/^btime (\d+)$/m.exec(uptime)?.[1]);
         if (!Number.isFinite(ticks) || !Number.isFinite(boot))
@@ -129,14 +271,22 @@ async function procInfo(pid) {
         };
     }
     catch (error) {
-        // ENOENT: no such process. Anything else (permissions, a changed /proc) is a failure.
         if (error instanceof CliError)
             throw error;
-        if (isMissing(error))
+        if (procGone(error))
             return undefined;
         throw processInfoFailed(pid, '/proc', error);
     }
 }
+/**
+ * Whether a /proc read failed because the process is gone: ENOENT (no /proc/<pid>), or ESRCH,
+ * which Linux returns when the process exits while one of its files is open. Anything else
+ * (permissions, a changed /proc) is a failure. ESRCH was found by the v0.4.1 tag pipeline: an
+ * app that stopped during `stop`'s check ended as PROCESS_INFO_FAILED.
+ */
+export function procGone(error) {
+    return isMissing(error) || error?.code === 'ESRCH';
+}
 const readProcess = async (pid) => {
     if (process.platform === 'linux')
         return procInfo(pid);
@@ -210,7 +360,11 @@ export async function status(root,
 read = readProcess, 
 /** Tests replace how a process is signalled; the CLI uses process.kill. */
 kill = signalProcess) {
-    const { pid, log } = paths(root);
+    return statusOf(root, read, kill, false);
+}
+/** `status`; `locked` when the caller (start) holds the start lock. */
+async function statusOf(root, read, kill, locked) {
+    const { log } = paths(root);
     const record = await readRecord(root);
     const logs = await logInfo(root);
     if (!record)
@@ -228,7 +382,7 @@ kill = signalProcess) {
             proof = found;
     }
     if (!info && proof === 'process') {
-        await rm(pid, { force: true });
+        await removeRecord(root, record, locked);
         return {
             running: false,
             stale: true,
@@ -528,48 +682,34 @@ check = checkProject) {
     const waitMs = options.waitMs ?? 10_000;
     const files = paths(root);
     const began = performance.now();
-    const current = await status(root);
-    if (current.running)
-        throw new CliError('ALREADY_RUNNING', `Already running (pid ${current.pid})`, {
-            details: current,
-        });
-    const entry = await check(root);
-    // The project's .env under the CLI's environment (D-0073); a malformed file stops here.
-    const token = randomBytes(24).toString('base64url');
-    const env = appEnvironment(root, 'production', {
-        ...options.env,
-        [INSTANCE_TOKEN_ENV]: token,
-    });
     await mkdir(files.run, { recursive: true });
     await writeFile(join(files.run, '.gitignore'), '*\n');
-    // Lines this start writes begin here (the web listening line is parsed from them).
-    const logOffset = await stat(files.log).then((info) => info.size, (error) => {
-        if (!isMissing(error))
-            throw error;
-        return 0;
-    });
-    // One start at a time; a lock left by a start that died more than a minute ago is stale.
-    try {
-        await writeFile(files.lock, String(process.pid), { flag: 'wx' });
-    }
-    catch (error) {
-        if (error.code !== 'EEXIST')
-            throw error;
-        const age = Date.now() -
-            (await stat(files.lock).catch((cause) => {
-                // The other start removed its lock meanwhile: the lock counts as stale.
-                if (!isMissing(cause))
-                    throw cause;
-                return { mtimeMs: 0 };
-            })).mtimeMs;
-        if (age < 60_000)
-            throw new CliError('START_IN_PROGRESS', 'Another dokebi start is running for this project');
-        debug('Replacing a stale start lock', { ageMs: age });
-        await writeFile(files.lock, String(process.pid));
-    }
+    // One start at a time (R3): the lock is taken before the running state is read, so a start
+    // that waited (in its checks) while another start finished sees that start's app.
+    const lock = await StartLock.acquire(files.lock);
+    if (!lock)
+        throw new CliError('START_IN_PROGRESS', 'Another dokebi start is running for this project');
     const warnings = [];
     let writer;
     try {
+        const current = await statusOf(root, readProcess, signalProcess, true);
+        if (current.running)
+            throw new CliError('ALREADY_RUNNING', `Already running (pid ${current.pid})`, {
+                details: current,
+            });
+        const entry = await check(root);
+        // The project's .env under the CLI's environment (D-0073); a malformed file stops here.
+        const token = randomBytes(24).toString('base64url');
+        const env = appEnvironment(root, 'production', {
+            ...options.env,
+            [INSTANCE_TOKEN_ENV]: token,
+        });
+        // Lines this start writes begin here (the web listening line is parsed from them).
+        const logOffset = await stat(files.log).then((info) => info.size, (error) => {
+            if (!isMissing(error))
+                throw error;
+            return 0;
+        });
         // The writer's own diagnostics (it has no app logger) go to log-writer.log.
         const writerLog = await open(files.writerLog, 'a');
         try {
@@ -690,7 +830,7 @@ check = checkProject) {
         if (writer?.connected)
             writer.disconnect();
         writer?.unref();
-        await rm(files.lock, { force: true });
+        await lock.release();
     }
 }
 /**
@@ -763,7 +903,6 @@ read = readProcess,
 /** Tests replace how a process is signalled; the CLI uses process.kill. */
 kill = signalProcess) {
     daemonOnly();
-    const files = paths(root);
     const record = await readRecord(root);
     if (!record)
         return { stopped: false };
@@ -785,7 +924,7 @@ kill = signalProcess) {
     }
     if (!found) {
         debug('Removing a stale pid file', { pid: record.pid });
-        await rm(files.pid, { force: true });
+        await removeRecord(root, record);
         return { stopped: false, pid: record.pid, stale: true };
     }
     if (proof === 'log-writer')
@@ -829,7 +968,7 @@ kill = signalProcess) {
         if (!(await gone(app, 5000)))
             throw new CliError('STOP_TIMEOUT', `pid ${record.pid} survived SIGKILL`);
     }
-    await rm(files.pid, { force: true });
+    await removeRecord(root, record);
     const warnings = [];
     // The app is stopped and its pid file removed: a failure to read the writer is a warning.
     const writerGone = await gone(writer, 5000).catch((error) => {
@@ -857,7 +996,6 @@ kill = signalProcess) {
  * the connection). An unreachable or unproven writer leaves everything as it was.
  */
 async function stopThroughWriter(root, record, timeoutMs, force, proof, refused) {
-    const files = paths(root);
     const began = performance.now();
     const asked = await askWriter(record, { op: 'stop', timeoutMs, force });
     if (!asked.reached)
@@ -877,7 +1015,7 @@ async function stopThroughWriter(root, record, timeoutMs, force, proof, refused)
             ? reply.message
             : `The log writer could not stop pid ${record.pid} (${String(reply.code)})`);
     }
-    await rm(files.pid, { force: true });
+    await removeRecord(root, record);
     if (reply.stopped !== true) {
         debug('The log writer reports that the app had already exited', { pid: record.pid });
         await asked.closed(0);
@@ -923,11 +1061,11 @@ function pidExists(pid, kill = signalProcess) {
  */
 export async function stopStarted(root, started, timeoutMs = 30_000, force = false) {
     daemonOnly();
-    const files = paths(root);
     const forget = async () => {
         // Only the pid file of this start: another start may have replaced it meanwhile.
-        if ((await readRecord(root))?.pid === started.pid)
-            await rm(files.pid, { force: true });
+        const current = await readRecord(root);
+        if (current?.pid === started.pid)
+            await removeRecord(root, current);
     };
     const gone = async (pid, limit) => {
         const until = performance.now() + limit;

package/dist/transaction.d.ts

@@ -1,3 +1,17 @@
+/**
+ * A path the rollback left as it found it, because it is no longer what this commit put there
+ * (ISSUE-0006 A06): `modified` (other content), `replaced` (a directory or special file now),
+ * `symlink`, `created` (something appeared where the original goes back), `not-empty` (a folder
+ * this commit created now holds files), `unsafe-path` / `path-conflict` (a parent folder became a
+ * symlink or a file). `backup` is the original, kept in the transaction folder; `kept` is where a
+ * file changed during the rollback itself was left.
+ */
+export interface RollbackConflict {
+    readonly path: string;
+    readonly reason: 'modified' | 'replaced' | 'symlink' | 'created' | 'not-empty' | 'unsafe-path' | 'path-conflict';
+    readonly backup?: string;
+    readonly kept?: string;
+}
 export declare class Transaction {
     #private;
     readonly root: string;
@@ -8,11 +22,17 @@ export declare class Transaction {
     ensureDirectory(path: string): Promise<void>;
     read(path: string): Promise<string>;
     write(path: string, content: string | Uint8Array): Promise<void>;
+    /** Puts `source` (a file or folder) at `path` on commit; without `source`, removes `path`. */
     replace(path: string, source?: string): Promise<void>;
     get paths(): string[];
     /**
      * Applies every change; `afterApply` runs once they are all in place, and when it fails the
      * changes are rolled back like a failed apply (D-0035: the workspace npm install).
+     *
+     * The rollback only undoes what is still this commit's own (ISSUE-0006 A06): `afterApply` can
+     * run for minutes while the user edits files. A path that is no longer what this commit put
+     * there (or, for a removed path, where something appeared) is left as it is, its original stays
+     * in the transaction folder, and the commit ends with RECOVERY_REQUIRED naming those paths.
      */
     commit(beforeApply?: (index: number) => void, afterApply?: () => Promise<void>): Promise<void>;
     close(): Promise<void>;

package/dist/transaction.js

@@ -1,8 +1,39 @@
-import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { link, lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join, relative } from 'node:path';
+import { hash as hashing } from '@dokebi/core/libraries';
 import { debug, debugEnabled, describeError, reportError } from './diagnostics.js';
 import { CliError } from './errors.js';
-import { exists, fingerprint, json, securePath } from './filesystem.js';
+import { exists, fingerprint, hash, json, securePath } from './filesystem.js';
+/**
+ * What is at `path` now, without following a symlink: null when nothing is there, `file:<sha256>`
+ * for a file, `directory:<dev>:<ino>` for a folder (its identity: a folder's content is not
+ * hashed), `symlink` or `other`.
+ */
+async function observe(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink())
+        return 'symlink';
+    if (stat.isDirectory())
+        return `directory:${stat.dev}:${stat.ino}`;
+    if (!stat.isFile())
+        return 'other';
+    return `file:${await hashing.sha256File(path)}`;
+}
+const LINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EMLINK', 'EXDEV']);
+/** Why `now` is not the `installed` fingerprint (both as `observe` writes them). */
+function differs(installed, now) {
+    if (now === 'symlink')
+        return 'symlink';
+    return installed?.startsWith('file:') && now.startsWith('file:') ? 'modified' : 'replaced';
+}
 export class Transaction {
     root;
     directory;
@@ -70,13 +101,17 @@ export class Transaction {
     async write(path, content) {
         const source = join(this.directory, `new-${this.#changes.length}`);
         await writeFile(source, content, { mode: 0o600 });
-        await this.replace(path, source);
+        await this.#add(path, source, `file:${hash(content)}`);
     }
+    /** Puts `source` (a file or folder) at `path` on commit; without `source`, removes `path`. */
     async replace(path, source) {
+        await this.#add(path, source);
+    }
+    async #add(path, source, installs) {
         if (this.#changes.some((change) => change.path === path))
             throw new CliError('DUPLICATE_CHANGE', path);
         await this.capture(path);
-        this.#changes.push(source === undefined ? { path } : { path, source });
+        this.#changes.push(source === undefined ? { path } : installs ? { path, source, installs } : { path, source });
     }
     get paths() {
         return this.#changes.map((change) => change.path);
@@ -84,6 +119,11 @@ export class Transaction {
     /**
      * Applies every change; `afterApply` runs once they are all in place, and when it fails the
      * changes are rolled back like a failed apply (D-0035: the workspace npm install).
+     *
+     * The rollback only undoes what is still this commit's own (ISSUE-0006 A06): `afterApply` can
+     * run for minutes while the user edits files. A path that is no longer what this commit put
+     * there (or, for a removed path, where something appeared) is left as it is, its original stays
+     * in the transaction folder, and the commit ends with RECOVERY_REQUIRED naming those paths.
      */
     async commit(beforeApply, afterApply) {
         for (const [path, expected] of this.#snapshots) {
@@ -91,13 +131,20 @@ export class Transaction {
                 throw new CliError('CONCURRENT_CHANGE', `File changed while planning: ${path}`);
             }
         }
-        const journal = this.#changes.map((change, index) => ({
-            ...change,
-            backup: join(this.directory, `old-${index}`),
-            existed: this.#snapshots.get(change.path) !== null,
-            backedUp: false,
-            installed: false,
-        }));
+        const journal = [];
+        for (const [index, change] of this.#changes.entries()) {
+            // What this change installs, to recognise it again in a rollback: a written file's hash, a
+            // staged file's hash or a staged folder's identity (node_modules).
+            const installs = change.installs ?? (change.source ? await observe(change.source) : null) ?? undefined;
+            journal.push({
+                ...change,
+                ...(installs ? { installs } : {}),
+                backup: join(this.directory, `old-${index}`),
+                existed: this.#snapshots.get(change.path) !== null,
+                backedUp: false,
+                installed: false,
+            });
+        }
         await writeFile(join(this.directory, 'journal.json'), json(journal));
         try {
             for (const [index, change] of journal.entries()) {
@@ -134,39 +181,140 @@ export class Transaction {
                     changes: journal.length,
                     error: describeError(cause),
                 });
-            const failures = [];
-            for (const change of [...journal].reverse()) {
+            await this.#rollback(journal, cause);
+        }
+    }
+    async #rollback(journal, cause) {
+        const failures = [];
+        const conflicts = [];
+        for (const [index, change] of [...journal.entries()].reverse()) {
+            try {
+                const conflict = await this.#undo(change, index);
+                if (conflict) {
+                    debug('Rollback kept a path changed during the commit', { ...conflict });
+                    conflicts.push(conflict);
+                }
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length || conflicts.length) {
+            this.#keep = true;
+            const directory = relative(this.root, this.directory);
+            const kept = conflicts.length
+                ? `kept ${conflicts.length} path(s) changed during the operation: ${conflicts
+                    .map((item) => `${item.path} (${item.reason})`)
+                    .join(', ')}; `
+                : '';
+            const failed = failures.length ? `${failures.length} step(s) failed; ` : '';
+            throw new CliError('RECOVERY_REQUIRED', `Rollback ${kept}${failed}preserve ${directory} and .dokebi/lock`, {
+                cause: failures.length ? new AggregateError([cause, ...failures]) : cause,
+                phase: 'commit',
+                details: { conflicts, transaction: directory },
+            });
+        }
+        throw new CliError('COMMIT_FAILED', 'Changes were rolled back', { cause });
+    }
+    /**
+     * Undoes one change unless the path is no longer this commit's own: then leaves it and says
+     * why. The look and the removal cannot be one atomic step; the window is kept to a rename
+     * (see `#undo`'s move-aside) and documented in docs/cli/README.md.
+     */
+    async #undo(change, index) {
+        const backup = change.backedUp ? { backup: relative(this.root, change.backup) } : {};
+        let target;
+        try {
+            // The parent folders, never following a symlink; the path itself is looked at below.
+            const parent = dirname(change.path);
+            const folder = parent === '.' ? this.root : await securePath(this.root, parent);
+            target = join(folder, basename(change.path));
+        }
+        catch (error) {
+            const code = error instanceof CliError ? error.code : undefined;
+            if (code !== 'UNSAFE_PATH' && code !== 'PATH_CONFLICT')
+                throw error;
+            return {
+                path: change.path,
+                reason: code === 'UNSAFE_PATH' ? 'unsafe-path' : 'path-conflict',
+                ...backup,
+            };
+        }
+        if (change.kind === 'directory') {
+            if (!change.installed)
+                return undefined;
+            try {
+                // rmdir removes only an empty folder and never follows a symlink.
+                await rmdir(target);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ENOENT')
+                    return undefined;
+                if (code === 'ENOTEMPTY' || code === 'EEXIST')
+                    return { path: change.path, reason: 'not-empty' };
+                if (code === 'ENOTDIR')
+                    return { path: change.path, reason: 'replaced' };
+                throw error;
+            }
+            return undefined;
+        }
+        if (change.installed) {
+            const now = await observe(target);
+            if (now !== null) {
+                if (now !== change.installs)
+                    return { path: change.path, reason: differs(change.installs, now), ...backup };
+                // Move it aside (atomic), then look again: an edit between the look and the move is
+                // found here and put back, never deleted.
+                const aside = join(this.directory, `rollback-${index}`);
                 try {
-                    const target = await securePath(this.root, change.path);
-                    if (change.kind === 'directory') {
-                        if (change.installed) {
-                            try {
-                                await rmdir(target);
-                            }
-                            catch (error) {
-                                if (error.code !== 'ENOENT')
-                                    throw error;
-                            }
-                        }
-                        continue;
-                    }
-                    if (change.installed)
-                        await rm(target, { recursive: true, force: true });
-                    if (change.backedUp)
-                        await rename(change.backup, target);
+                    await rename(target, aside);
                 }
                 catch (error) {
-                    failures.push(error);
+                    if (error.code !== 'ENOENT')
+                        throw error;
                 }
+                const moved = await observe(aside);
+                if (moved !== null && moved !== change.installs) {
+                    const restored = await this.#place(aside, target);
+                    return {
+                        path: change.path,
+                        reason: differs(change.installs, moved),
+                        ...backup,
+                        ...(restored ? {} : { kept: relative(this.root, aside) }),
+                    };
+                }
+                if (moved !== null)
+                    await rm(aside, { recursive: true, force: true });
             }
-            if (failures.length) {
-                this.#keep = true;
-                throw new CliError('RECOVERY_REQUIRED', `Rollback failed; preserve ${this.directory} and .dokebi/lock`, {
-                    cause: new AggregateError([cause, ...failures]),
-                });
-            }
-            throw new CliError('COMMIT_FAILED', 'Changes were rolled back', { cause });
         }
+        if (change.backedUp && !(await this.#place(change.backup, target)))
+            return { path: change.path, reason: 'created', ...backup };
+        return undefined;
+    }
+    /**
+     * Moves `from` to `to` without replacing anything at `to`: false when something is there. A
+     * file goes by link + unlink (link fails on an existing name); a folder (or a file system
+     * without hard links) by rename after checking `to` is free, which leaves a tiny window.
+     */
+    async #place(from, to) {
+        try {
+            await link(from, to);
+            await unlink(from);
+            return true;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (code === 'EEXIST')
+                return false;
+            if (!LINK_UNSUPPORTED.has(code))
+                throw error;
+            debug('Rollback restores by rename (no hard link)', { path: to, code });
+        }
+        if ((await observe(to)) !== null)
+            return false;
+        await rename(from, to);
+        return true;
     }
     async close() {
         if (this.#keep)

package/dist/verify.d.ts

@@ -46,17 +46,26 @@ export interface HttpProbe {
     readonly ok: boolean;
     /** `other`: an answer without this run's token header — another server on the port. */
     readonly instance?: 'ours' | 'other';
+    /**
+     * The identity probe (no readiness route and no app domain): `GET /` passes with any status
+     * below 500 that carries this run's header.
+     */
+    readonly identity?: true;
     readonly error?: string;
 }
 /**
  * The HTTP check of verify: GET the readiness path, then `/` of each app domain, at `base`. An
  * answer counts only when it carries `token` in the x-dokebi-verify header (the instance verify
  * started); anything else is retried like a failed request and then reported FOREIGN_SERVER.
+ * With neither a readiness path (`healthRoutes: false`) nor an app domain, one identity probe
+ * runs instead (ISSUE-0006 A08: no request at all used to pass): `GET /`, which passes with any
+ * status below 500 that carries the token, a 404 included (the app may have no route at `/`).
+ * Each request must complete within `timeoutMs` (ISSUE-0006 A09).
  */
 export declare function httpChecks(base: string, paths: {
     ready: string | null;
     domains: readonly string[];
-}, token: string, delayMs?: number): Promise<Omit<VerifyCheck, 'name' | 'ms'>>;
+}, token: string, delayMs?: number, timeoutMs?: number): Promise<Omit<VerifyCheck, 'name' | 'ms'>>;
 export declare function verify(root: string, options?: {
     waitMs?: number;
 }): Promise<VerifyResult>;