@dokebi/cli 0.2.3 → 0.2.5

package/dist/server.js

@@ -1,26 +1,36 @@
 // Server commands (D-0044): dev, start, stop, status and logs for the project's one process
-// (`src/main.ts`). The background process is tracked by `.dokebi/run/app.pid`; its stdout and
-// stderr go to `.dokebi/run/app.log`. A pid is only acted on when `ps` (/proc on Linux) shows it runs this
-// project's entry and started when the pid file says, so a reused pid is never signalled.
+// (`src/main.ts`). The background process is tracked by `.dokebi/run/app.pid`. Its stdout and
+// stderr are pipes into a detached log writer (`log-writer.ts`, D-0053) that writes
+// `.dokebi/run/app.log` and rotates it by size (`app.log.1` … `app.log.<files>`). A pid is only
+// acted on when `ps` (/proc on Linux) shows it runs this project's entry and started when the pid
+// file says, so a reused pid is never signalled.
 import { execFile, spawn } from 'node:child_process';
 import { existsSync, readFileSync, watch } from 'node:fs';
-import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { debug, debugEnabled, isMissing, reportError } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { ProjectInspector } from './project-inspector.js';
+import { logFiles } from './rotating-log.js';
 const exec = promisify(execFile);
 const ENTRY = 'src/main.ts';
 const RUN = '.dokebi/run';
 /** Written by the generated `src/main.ts` once `app.start()` resolved. */
 const STARTED = 'Dokebi application started';
-const LOG_WARN_BYTES = 100 * 1024 * 1024;
+/** Rotation defaults and limits (D-0053): `--log-max-mb`, `--log-files`. */
+export const LOG_LIMITS = {
+    maxMb: { default: 50, min: 1, max: 10_240 },
+    files: { default: 5, min: 1, max: 100 },
+};
+const MB = 1024 * 1024;
 const paths = (root) => ({
     run: join(root, RUN),
     pid: join(root, RUN, 'app.pid'),
     log: join(root, RUN, 'app.log'),
+    writerLog: join(root, RUN, 'log-writer.log'),
     lock: join(root, RUN, 'start.lock'),
     entry: join(root, ENTRY),
 });
@@ -33,15 +43,21 @@ async function readRecord(root) {
     try {
         text = await readFile(paths(root).pid, 'utf8');
     }
-    catch {
+    catch (error) {
+        // No pid file means not started; anything else is reported and treated the same way.
+        if (!isMissing(error))
+            reportError('PID_FILE_READ_FAILED', 'Unable to read the pid file', error);
         return undefined;
     }
     try {
         const value = JSON.parse(text);
         if (Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.entry === 'string')
             return value;
+        debug('Pid file ignored: unexpected content', { file: `${RUN}/app.pid` });
+    }
+    catch (error) {
+        reportError('PID_FILE_INVALID', 'Pid file is not valid JSON; treating the app as stopped', error);
     }
-    catch { }
     return undefined;
 }
 /**
@@ -68,8 +84,11 @@ async function procInfo(pid) {
             command: cmdline.split('\0').join(' ').trim(),
         };
     }
-    catch {
-        return undefined; // no such process
+    catch (error) {
+        // ENOENT: no such process. Anything else (permissions, a changed /proc) is reported.
+        if (!isMissing(error))
+            reportError('PROCESS_INFO_FAILED', 'Unable to read process information from /proc', error);
+        return undefined;
     }
 }
 async function processInfo(pid) {
@@ -87,29 +106,69 @@ async function processInfo(pid) {
             return undefined;
         return { startedAt, rssKb: Number(rss), command: command.join(' ') };
     }
-    catch {
-        return undefined; // ps exits 1 when the pid does not exist
+    catch (error) {
+        // ps exits 1 when the pid does not exist; anything else (no ps, killed) is reported.
+        if (error.code !== 1)
+            reportError('PROCESS_INFO_FAILED', 'Unable to read process information with ps', error);
+        return undefined;
     }
 }
 /** The recorded process, when it is still alive and still this project's process. */
 async function live(record) {
     const info = await processInfo(record.pid);
-    if (!info?.command.includes(record.entry))
+    if (!info?.command.includes(record.entry)) {
+        if (info)
+            debug('Recorded pid runs another command; treating it as stale', { pid: record.pid });
         return undefined;
+    }
     // lstart has one-second resolution; the pid file is written right after spawn.
-    if (Math.abs(info.startedAt - Date.parse(record.startedAt)) > 5000)
+    if (Math.abs(info.startedAt - Date.parse(record.startedAt)) > 5000) {
+        debug('Recorded pid was reused by a later process; treating it as stale', { pid: record.pid });
         return undefined;
+    }
     return info;
 }
+/** Whether the record's log writer still runs (its command names the writer and the entry). */
+async function writerAlive(record) {
+    if (record.logWriter === undefined)
+        return false;
+    const info = await processInfo(record.logWriter);
+    return Boolean(info?.command.includes('log-writer') && info.command.includes(record.entry));
+}
+async function logInfo(root) {
+    const { log, writerLog } = paths(root);
+    const sizes = async (file) => stat(file).then((stats) => stats.size, (error) => {
+        // Rotated away between listing and stat: it is simply no longer there.
+        if (!isMissing(error))
+            reportError('LOG_READ_FAILED', 'Unable to read a log file size', error);
+        return undefined;
+    });
+    const files = [];
+    for (const file of logFiles(log)) {
+        const bytes = await sizes(file);
+        if (bytes !== undefined)
+            files.push({ file, bytes });
+    }
+    const writerBytes = await sizes(writerLog);
+    return { logFiles: files, ...(writerBytes ? { logWriterLog: writerLog } : {}) };
+}
 export async function status(root) {
     const { pid, log } = paths(root);
     const record = await readRecord(root);
+    const logs = await logInfo(root);
     if (!record)
-        return { running: false, log };
+        return { running: false, log, ...logs };
     const info = await live(record);
     if (!info) {
         await rm(pid, { force: true });
-        return { running: false, stale: true, pid: record.pid, startedAt: record.startedAt, log };
+        return {
+            running: false,
+            stale: true,
+            pid: record.pid,
+            startedAt: record.startedAt,
+            log,
+            ...logs,
+        };
     }
     return {
         running: true,
@@ -118,6 +177,10 @@ export async function status(root) {
         uptimeSec: Math.round((Date.now() - Date.parse(record.startedAt)) / 1000),
         rssMb: Math.round(info.rssKb / 1024),
         log,
+        ...logs,
+        ...(record.logWriter !== undefined
+            ? { logWriter: { pid: record.logWriter, running: await writerAlive(record) } }
+            : {}),
     };
 }
 async function checkProject(root) {
@@ -137,30 +200,70 @@ const environment = (mode) => ({
     ...process.env,
     NODE_ENV: process.env.NODE_ENV ?? mode,
 });
-async function tail(file, lines, maxBytes = 1024 * 1024) {
+/**
+ * The last `lines` lines of one file (reading at most its last `maxBytes`). An open handle is
+ * read up to `end` (the size it had when opened) and left open.
+ */
+async function lastLines(source, lines, maxBytes = MB) {
+    if (lines <= 0)
+        return [];
     let handle;
     try {
-        handle = await open(file, 'r');
-        const { size } = await handle.stat();
+        const opened = typeof source === 'string' ? await open(source, 'r') : source.handle;
+        if (typeof source === 'string')
+            handle = opened;
+        const size = typeof source === 'string' ? (await opened.stat()).size : source.end;
         const length = Math.min(size, maxBytes);
         const buffer = Buffer.alloc(length);
-        await handle.read(buffer, 0, length, size - length);
+        await opened.read(buffer, 0, length, size - length);
         const text = buffer.toString('utf8').split('\n');
         if (text.at(-1) === '')
             text.pop();
-        return text.slice(-lines).join('\n') + (text.length ? '\n' : '');
+        return text.slice(-lines);
     }
-    catch {
-        return '';
+    catch (error) {
+        // Rotated away while reading: the next older file has those lines.
+        if (!isMissing(error))
+            reportError('LOG_READ_FAILED', 'Unable to read the app log', error);
+        return [];
     }
     finally {
         await handle?.close();
     }
 }
-export async function start(root, waitMs = 10_000, 
+/**
+ * The last `lines` lines across app.log and its rotated files (D-0053). With `current` (app.log
+ * opened by the follower), app.log is read through it up to where following starts.
+ */
+async function tail(file, lines, current) {
+    let result = [];
+    const files = logFiles(file);
+    if (current && files[0] !== file)
+        files.unshift(file);
+    for (const each of files) {
+        const source = current && each === file ? current : each;
+        result = [...(await lastLines(source, lines - result.length)), ...result];
+        if (result.length >= lines)
+            break;
+    }
+    return result.length ? `${result.join('\n')}\n` : '';
+}
+/** Rejects rotation settings outside LOG_LIMITS; bytes below 1 MB are allowed for tests. */
+function logSettings(options) {
+    const maxBytes = options.logMaxBytes ?? LOG_LIMITS.maxMb.default * MB;
+    const files = options.logFiles ?? LOG_LIMITS.files.default;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1024 || maxBytes > LOG_LIMITS.maxMb.max * MB)
+        throw new CliError('USAGE', `--log-max-mb must be an integer from ${LOG_LIMITS.maxMb.min} to ${LOG_LIMITS.maxMb.max}`);
+    if (!Number.isSafeInteger(files) || files < LOG_LIMITS.files.min || files > LOG_LIMITS.files.max)
+        throw new CliError('USAGE', `--log-files must be an integer from ${LOG_LIMITS.files.min} to ${LOG_LIMITS.files.max}`);
+    return { maxBytes, files };
+}
+export async function start(root, options = {}, 
 /** Tests replace the project inspection; the CLI always inspects. */
 check = checkProject) {
     daemonOnly();
+    const { maxBytes, files: keep } = logSettings(options);
+    const waitMs = options.waitMs ?? 10_000;
     const files = paths(root);
     const began = performance.now();
     const current = await status(root);
@@ -175,69 +278,126 @@ check = checkProject) {
     try {
         await writeFile(files.lock, String(process.pid), { flag: 'wx' });
     }
-    catch {
-        const age = Date.now() - (await stat(files.lock).catch(() => ({ mtimeMs: 0 }))).mtimeMs;
+    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));
     }
     const warnings = [];
+    let writer;
     try {
-        const before = await stat(files.log).catch(() => undefined);
-        if (before && before.size > LOG_WARN_BYTES)
-            warnings.push(`${RUN}/app.log is ${Math.round(before.size / 1048576)} MB; it is not rotated`);
-        const offset = before?.size ?? 0;
-        const log = await open(files.log, 'a');
-        let child;
+        // The writer's own diagnostics (it has no app logger) go to log-writer.log.
+        const writerLog = await open(files.writerLog, 'a');
         try {
-            await log.write(`\n--- dokebi start ${new Date().toISOString()} ---\n`);
-            child = spawn(process.execPath, [entry], {
+            writer = spawn(process.execPath, [
+                fileURLToPath(new URL('./log-writer.js', import.meta.url)),
+                files.log,
+                String(maxBytes),
+                String(keep),
+                entry,
+            ], {
                 cwd: root,
                 detached: true,
-                stdio: ['ignore', log.fd, log.fd],
+                stdio: ['ignore', 'ignore', writerLog.fd, 'ipc'],
                 env: environment('production'),
             });
         }
         finally {
-            await log.close();
+            await writerLog.close();
         }
-        const pid = child.pid;
-        if (pid === undefined)
-            throw new CliError('START_FAILED', 'The process could not be spawned');
-        let exited;
-        child.once('exit', (code, signal) => {
-            exited = code ?? (signal ? 128 : 1);
+        const writerPid = writer.pid;
+        if (writerPid === undefined)
+            throw new CliError('START_FAILED', 'The log writer process could not be spawned');
+        const state = {};
+        writer.on('message', (message) => {
+            if (typeof message?.spawned === 'number')
+                state.pid = message.spawned;
+            if (message?.ready)
+                state.ready = true;
+            if (message && 'exited' in message)
+                state.exited = message.signal ? `signal ${message.signal}` : `code ${message.exited}`;
+            if (typeof message?.failed === 'string')
+                state.failed = message.failed;
         });
-        child.unref();
-        const record = {
-            pid,
-            startedAt: new Date().toISOString(),
-            entry,
-            node: process.version,
+        writer.once('exit', (code, signal) => {
+            // The writer ends with 0 only after the app ended (its message may still be on the way).
+            if (code === 0)
+                state.exited ??= 'an unknown code (see the log)';
+            else
+                state.failed ??= `the log writer exited (${signal ?? code})`;
+        });
+        debug('Log writer spawned; waiting for the app', { writer: writerPid, waitMs, maxBytes, keep });
+        const failure = async (message) => {
+            await rm(files.pid, { force: true });
+            return new CliError('START_FAILED', message, {
+                details: {
+                    log: files.log,
+                    tail: await tail(files.log, 30),
+                    logWriterLog: (await lastLines(files.writerLog, 30)).join('\n'),
+                },
+            });
         };
-        await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`);
-        await rename(`${files.pid}.tmp`, files.pid);
         const deadline = performance.now() + waitMs;
-        let ready = false;
+        let recorded;
         while (performance.now() < deadline) {
-            await delay(100);
-            if (exited !== undefined) {
-                await rm(files.pid, { force: true });
-                throw new CliError('START_FAILED', `The application exited with code ${exited}`, {
-                    details: { log: files.log, tail: await tail(files.log, 30) },
-                });
+            await delay(50);
+            if (state.pid !== undefined && recorded === undefined) {
+                recorded = state.pid;
+                const record = {
+                    pid: state.pid,
+                    startedAt: new Date().toISOString(),
+                    entry,
+                    node: process.version,
+                    logWriter: writerPid,
+                    logMaxBytes: maxBytes,
+                    logFiles: keep,
+                };
+                await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`);
+                await rename(`${files.pid}.tmp`, files.pid);
+                debug('App process spawned; waiting for the start line', { pid: state.pid });
             }
-            const text = await readFile(files.log).catch(() => Buffer.alloc(0));
-            if (text.subarray(offset).includes(STARTED)) {
-                ready = true;
+            if (state.exited !== undefined)
+                throw await failure(`The application exited with ${state.exited}`);
+            if (state.failed !== undefined)
+                throw await failure(`The application could not be started: ${state.failed}`);
+            if (state.ready && recorded !== undefined)
                 break;
-            }
         }
+        if (recorded === undefined) {
+            // The writer never started the app: do not leave it (or a late app) behind. The writer
+            // leads its own process group (detached), so the group signal reaches both.
+            process.kill(-writerPid, 'SIGKILL');
+            throw await failure(`The log writer did not start the application within ${waitMs} ms`);
+        }
+        const ready = state.ready === true;
         if (!ready)
             warnings.push(`"${STARTED}" was not logged within ${waitMs} ms; the process is running but may not be ready`);
-        return { pid, log: files.log, ready, ms: Math.round(performance.now() - began), warnings };
+        return {
+            pid: recorded,
+            log: files.log,
+            logWriter: writerPid,
+            logMaxBytes: maxBytes,
+            logFiles: keep,
+            ready,
+            ms: Math.round(performance.now() - began),
+            warnings,
+        };
     }
     finally {
+        // The writer and the app outlive this command.
+        if (writer?.connected)
+            writer.disconnect();
+        writer?.unref();
         await rm(files.lock, { force: true });
     }
 }
@@ -252,57 +412,243 @@ export async function stop(root, timeoutMs = 30_000, force = false) {
         return { stopped: false, pid: record.pid, stale: true };
     }
     const began = performance.now();
-    const gone = async (limit) => {
+    const gone = async (alive, limit) => {
         const until = performance.now() + limit;
         while (performance.now() < until) {
-            if (!(await live(record)))
+            if (!(await alive()))
                 return true;
             await delay(100);
         }
         return false;
     };
+    const app = async () => Boolean(await live(record));
+    // SIGTERM goes to the app (core drain); the log writer exits once the app's output ends.
+    debug('Sending SIGTERM', { pid: record.pid, timeoutMs });
     process.kill(record.pid, 'SIGTERM');
     let forced = false;
-    if (!(await gone(timeoutMs))) {
+    if (!(await gone(app, timeoutMs))) {
         if (!force)
             throw new CliError('STOP_TIMEOUT', `pid ${record.pid} did not stop within ${timeoutMs} ms; it is still draining or stuck (use --force)`);
+        debug('Stop timed out; sending SIGKILL', { pid: record.pid });
         process.kill(record.pid, 'SIGKILL');
         forced = true;
-        if (!(await gone(5000)))
+        if (!(await gone(app, 5000)))
             throw new CliError('STOP_TIMEOUT', `pid ${record.pid} survived SIGKILL`);
     }
     await rm(files.pid, { force: true });
-    return { stopped: true, pid: record.pid, ms: Math.round(performance.now() - began), forced };
+    const warnings = [];
+    if (record.logWriter !== undefined && !(await gone(() => writerAlive(record), 5000))) {
+        debug('Log writer still running after the app stopped', { writer: record.logWriter });
+        warnings.push(`the log writer (pid ${record.logWriter}) was still running 5 s after the app stopped; a process the app started may hold its output`);
+    }
+    return {
+        stopped: true,
+        pid: record.pid,
+        ms: Math.round(performance.now() - began),
+        forced,
+        ...(warnings.length ? { warnings } : {}),
+    };
 }
-/** Prints the last `lines` lines; with `follow`, keeps printing what is appended until SIGINT. */
-export async function logs(root, lines = 100, follow = false, write = (text) => process.stdout.write(text)) {
+/**
+ * Prints the last `lines` lines (across app.log and its rotated files); with `follow`, keeps
+ * printing what is appended until SIGINT (or `signal`), following app.log across rotations.
+ * The follower remembers the inode of the file it reads. When app.log has become another file,
+ * it finishes its file, then reads each rotated file newer than it (found by inode, oldest
+ * first) before following the new app.log, so several rotations between two polls skip no line.
+ */
+export async function logs(root, lines = 100, follow = false, write = (text) => process.stdout.write(text), signal) {
     const file = paths(root).log;
-    if (!follow && !existsSync(file))
-        throw new CliError('NO_LOG', `${RUN}/app.log does not exist; the app was never started`);
-    write(await tail(file, lines));
-    if (!follow)
+    if (!follow) {
+        if (!existsSync(file))
+            throw new CliError('NO_LOG', `${RUN}/app.log does not exist; the app was never started`);
+        write(await tail(file, lines));
         return;
-    let position = (await stat(file).catch(() => ({ size: 0 }))).size;
+    }
     const stopped = new AbortController();
-    process.once('SIGINT', () => stopped.abort());
-    while (!stopped.signal.aborted) {
-        await delay(250);
-        const size = (await stat(file).catch(() => ({ size: 0 }))).size;
-        if (size < position)
-            position = 0; // removed or truncated: follow the new file
-        if (size === position)
-            continue;
-        const handle = await open(file, 'r');
+    const onInt = () => stopped.abort();
+    process.once('SIGINT', onInt);
+    signal?.addEventListener('abort', onInt, { once: true });
+    const follower = new LogFollower(file, write, stopped.signal);
+    try {
+        // app.log is opened first and the tail ends where following starts: no line falls between.
+        write(await tail(file, lines, await follower.open()));
+        await follower.run();
+    }
+    finally {
+        process.off('SIGINT', onInt);
+        await follower.close();
+    }
+}
+/** `logs -f` (D-0053): reads app.log as it grows and follows it across rotations by inode. */
+class LogFollower {
+    file;
+    write;
+    signal;
+    #handle;
+    /** The inode of the file being read. */
+    #reading;
+    #position = 0;
+    constructor(file, write, signal) {
+        this.file = file;
+        this.write = write;
+        this.signal = signal;
+    }
+    /** Opens app.log at its end; the handle and that end, when it exists. */
+    async open() {
+        const opened = await this.#open(this.file);
+        await this.#use(opened, 'end');
+        return opened && { handle: opened.handle, end: opened.size };
+    }
+    async close() {
+        const handle = this.#handle;
+        this.#handle = undefined;
+        await handle?.close();
+    }
+    /** Prints what is appended until the signal aborts. */
+    async run() {
+        while (!this.signal.aborted) {
+            await delay(250);
+            if (!this.#handle) {
+                // Before the first start: follow app.log from its beginning once it exists.
+                await this.#use(await this.#open(this.file), 'start');
+                await this.#drain();
+                continue;
+            }
+            // Rotated once or more: finish this file (it is complete), then each newer one in turn.
+            let current = await this.#inode(this.file);
+            while (current !== undefined && current !== this.#reading && !this.signal.aborted) {
+                await this.#drain();
+                if (!(await this.#advance()))
+                    break; // a rotation is under way: next poll
+                current = await this.#inode(this.file);
+            }
+            await this.#drain();
+        }
+    }
+    /** Prints what the open file has beyond the position; the handle reads a renamed file too. */
+    async #drain() {
+        const handle = this.#handle;
+        if (!handle)
+            return;
+        const { size } = await handle.stat();
+        if (size < this.#position)
+            this.#position = 0; // truncated: read it again from the start
+        while (this.#position < size) {
+            const buffer = Buffer.alloc(Math.min(size - this.#position, MB));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, this.#position);
+            if (!bytesRead)
+                break;
+            this.write(buffer.subarray(0, bytesRead).toString('utf8'));
+            this.#position += bytesRead;
+        }
+    }
+    /**
+     * Moves to the file written after the one being read; false when it cannot be told yet.
+     * The writer renames the oldest first (`.k` → `.k+1` before `.k-1` → `.k`), so `.k-1`
+     * opened while `.k` holds our inode both before and after the open is the next file;
+     * otherwise a rotation ran meanwhile and the place is looked up again. A gap that stays
+     * (a rotated file removed by hand) is stepped over to the next newer file there is.
+     */
+    async #advance() {
+        const attempts = 20;
+        for (let attempt = 0; attempt < attempts && !this.signal.aborted; attempt++) {
+            if (attempt)
+                await delay(5);
+            const rotated = await this.#rotated();
+            const index = await this.#indexOf(rotated, this.#reading);
+            if (index === undefined) {
+                if (await this.#removed())
+                    return this.#skipToOldest(rotated);
+                continue; // moved up while we looked: look again
+            }
+            // A gap at `.k-1` lasts microseconds during a rotation; one seen for ~100 ms is a hole.
+            const target = attempt < attempts - 1 ? index - 1 : (rotated.filter((each) => each < index).at(-1) ?? 0);
+            const next = await this.#open(this.#named(target));
+            if (!next)
+                continue; // `.k-1` is between its rename and the next one
+            if ((await this.#inode(this.#named(index))) === this.#reading) {
+                if (debugEnabled())
+                    debug('App log rotated; following the next file', { file: this.#named(target) });
+                await this.#use(next, 'start');
+                return true;
+            }
+            await next.handle.close();
+        }
+        return false;
+    }
+    /** The followed file was removed beyond --log-files: lines between are gone from disk too. */
+    async #skipToOldest(rotated) {
+        const oldest = rotated.at(-1) ?? 0;
+        const opened = await this.#open(this.#named(oldest));
+        if (!opened)
+            return false;
+        debug('Followed log file was removed by rotation; continuing with the oldest kept file', {
+            file: this.#named(oldest),
+        });
+        this.write('--- dokebi: logs -f fell behind; rotated lines removed before they were read ---\n');
+        await this.#use(opened, 'start');
+        return true;
+    }
+    /** The index of the rotated file with `inode` (`app.log.<index>`), when one has it. */
+    async #indexOf(rotated, inode) {
+        for (const index of rotated)
+            if ((await this.#inode(this.#named(index))) === inode)
+                return index;
+        return undefined;
+    }
+    /** Indexes of the rotated files there are, ascending (newest first). */
+    async #rotated() {
+        const name = basename(this.file);
+        const names = await readdir(dirname(this.file)).catch((error) => {
+            if (!isMissing(error))
+                reportError('LOG_READ_FAILED', 'Unable to list the rotated app logs', error, 5000);
+            return [];
+        });
+        return names
+            .filter((each) => each.startsWith(`${name}.`) && /^\d+$/.test(each.slice(name.length + 1)))
+            .map((each) => Number(each.slice(name.length + 1)))
+            .sort((a, b) => a - b);
+    }
+    /** True when the open file has no name left (removed beyond --log-files). */
+    async #removed() {
+        return (await this.#handle?.stat())?.nlink === 0;
+    }
+    /** `app.log.<index>` (`app.log` for 0). */
+    #named(index) {
+        return index ? `${this.file}.${index}` : this.file;
+    }
+    /** The inode at `name`, or undefined while it does not exist. */
+    async #inode(name) {
+        return stat(name).then((stats) => stats.ino, (error) => {
+            // Between the rename and the new file (rotation) or before the first start: absent.
+            if (!isMissing(error))
+                reportError('LOG_READ_FAILED', 'Unable to read the app log', error, 5000);
+            return undefined;
+        });
+    }
+    async #open(name) {
+        let handle;
         try {
-            const buffer = Buffer.alloc(size - position);
-            await handle.read(buffer, 0, buffer.length, position);
-            write(buffer.toString('utf8'));
-            position = size;
+            handle = await open(name, 'r');
+            const { ino, size } = await handle.stat();
+            return { handle, ino, size };
         }
-        finally {
-            await handle.close();
+        catch (error) {
+            await handle?.close();
+            if (!isMissing(error))
+                reportError('LOG_READ_FAILED', 'Unable to open the app log', error, 5000);
+            return undefined;
         }
     }
+    /** Reads `opened` from its start or end from now on, closing the file read so far. */
+    async #use(opened, from) {
+        if (!opened)
+            return;
+        await this.#handle?.close();
+        this.#handle = opened.handle;
+        this.#reading = opened.ino;
+        this.#position = from === 'end' ? opened.size : 0;
+    }
 }
 /** Runs the app in the foreground and forwards SIGINT/SIGTERM; resolves with its exit code. */
 export async function foreground(root) {
@@ -333,7 +679,11 @@ function installedVersion(root, name) {
             const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
             return parts ? [Number(parts[1]), Number(parts[2]), Number(parts[3])] : undefined;
         }
-        catch { }
+        catch (error) {
+            // Not installed here: keep walking up like Node's resolution does.
+            if (!isMissing(error))
+                reportError('PACKAGE_READ_FAILED', `Unable to read the installed ${name} package.json`, error);
+        }
         if (dirname(directory) === directory)
             return undefined;
     }
@@ -367,7 +717,12 @@ export async function dev(root, say) {
     const child = (args) => spawn(process.execPath, ['--import', guard, ...args], {
         cwd: root,
         stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
-        env: { ...environment('development'), ...(hot ? { DOKEBI_VITE_DEV: '1' } : {}) },
+        // DOKEBI_DEV: a cluster app runs one worker (@dokebi/cluster, DOKEBI_DEV_WORKERS for more).
+        env: {
+            ...environment('development'),
+            DOKEBI_DEV: '1',
+            ...(hot ? { DOKEBI_VITE_DEV: '1' } : {}),
+        },
     });
     const run = () => {
         app = child([entry]);
@@ -446,7 +801,8 @@ export async function dev(root, say) {
             return;
         clearTimeout(timer);
         timer = setTimeout(() => {
-            restarting = restarting.then(async () => {
+            restarting = restarting
+                .then(async () => {
                 if (exiting)
                     return;
                 say(`${what} changed; restarting`);
@@ -455,6 +811,10 @@ export async function dev(root, say) {
                 await halt(previous);
                 if (!exiting)
                     run();
+            })
+                .catch((error) => {
+                // Keep the loop alive: the next change tries again.
+                reportError('DEV_RESTART_FAILED', 'Restarting the app failed', error);
             });
         }, 300);
     };