@dokebi/cli 0.2.5 → 0.4.1

package/dist/server.js

@@ -4,17 +4,46 @@
 // `.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.
+//
+// Two ways to stop (D-0065 §11):
+// - `stop` (the `dokebi stop` command) acts on a pid file that may be days old: its pid may have
+//   been reused by an unrelated process, so it signals only after `ps` (/proc) confirms the
+//   command and start time. Without process information (a sandbox that blocks `ps`, D-0073) it
+//   asks the app instead: `start` gives every app a random token (DOKEBI_INSTANCE_TOKEN, kept in
+//   the pid file) and @dokebi/web answers a request carrying a challenge in `x-dokebi-instance`
+//   with HMAC-SHA256(token, challenge). Only a correct answer at the recorded address proves the
+//   pid is ours; otherwise it refuses with PROCESS_INFO_FAILED and keeps the pid file. `status`
+//   reports which proof it used (`proof: process | http | log-writer`).
+//   An agent sandbox per command (Codex CLI, AI-M03) may refuse even the signal: the app was
+//   started in another sandbox instance. The log writer, the app's parent from that instance,
+//   listens on a loopback control port (log-writer-control.ts; `control` in the pid file); after
+//   both sides prove the instance token, it drain-stops the app (`via: 'log-writer'`). Without ps it is asked first
+//   (`proof: 'log-writer'`), then the HTTP proof; an unproven instance is never signalled or asked.
+// - `stopStarted` (used by `dokebi verify`) stops the process this same CLI run started seconds
+//   ago through the pids `start` returned: identity is known from the handle, so it needs no
+//   `ps` (liveness is `kill(pid, 0)`), and it works in agent sandboxes that block `ps`.
+//
+// Every app the CLI runs gets the project's `.env` under its own environment (D-0073).
 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 { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 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 { appUrls, readAppHosts } from './app-urls.js';
+import { CONFIG_FILE, parseProjectConfig } from './configuration.js';
+import { debug, debugEnabled, describeError, isMissing, reportError } from './diagnostics.js';
+import { appEnvironment, readEnvFile } from './env-file.js';
 import { CliError } from './errors.js';
+import { askLogWriter, CONTROL_HOST } from './log-writer-control.js';
+import { redactNpmOutput } from './npm-client.js';
 import { ProjectInspector } from './project-inspector.js';
 import { logFiles } from './rotating-log.js';
+import { ViteHostProcess, viteHostScript } from './vite-host-process.js';
 const exec = promisify(execFile);
 const ENTRY = 'src/main.ts';
 const RUN = '.dokebi/run';
@@ -26,6 +55,9 @@ export const LOG_LIMITS = {
     files: { default: 5, min: 1, max: 100 },
 };
 const MB = 1024 * 1024;
+const signalProcess = (pid, signal) => {
+    process.kill(pid, signal);
+};
 const paths = (root) => ({
     run: join(root, RUN),
     pid: join(root, RUN, 'app.pid'),
@@ -60,6 +92,18 @@ async function readRecord(root) {
     }
     return undefined;
 }
+function processInfoFailed(pid, source, cause) {
+    return new CliError('PROCESS_INFO_FAILED', `Unable to read process information of pid ${pid} with ${source}; the pid file is kept because the process may still run`, {
+        cause,
+        details: {
+            pid,
+            source,
+            // A sandbox that blocks ps (or /proc) is the usual cause: say how to go on (AI-M01).
+            hint: 'run this command outside the sandbox, or allow ps (macOS) or /proc (Linux) for it',
+            manualStop: `check the process yourself (ps -p ${pid} -o command=); if it runs this project's src/main.ts, stop it with kill -TERM ${pid} (drain), then remove .dokebi/run/app.pid`,
+        },
+    });
+}
 /**
  * Linux reads /proc: slim container images (node:*-slim) have no `ps`. Start time is the boot
  * time plus the process start in clock ticks (USER_HZ, 100 on Linux).
@@ -77,7 +121,7 @@ async function procInfo(pid) {
         const ticks = Number(fields[19]);
         const boot = Number(/^btime (\d+)$/m.exec(uptime)?.[1]);
         if (!Number.isFinite(ticks) || !Number.isFinite(boot))
-            return undefined;
+            throw processInfoFailed(pid, '/proc', new Error('Unexpected /proc stat content'));
         return {
             startedAt: (boot + ticks / 100) * 1000,
             rssKb: Number(/^VmRSS:\s+(\d+)/m.exec(status)?.[1] ?? 0),
@@ -85,37 +129,46 @@ async function procInfo(pid) {
         };
     }
     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;
+        // ENOENT: no such process. Anything else (permissions, a changed /proc) is a failure.
+        if (error instanceof CliError)
+            throw error;
+        if (isMissing(error))
+            return undefined;
+        throw processInfoFailed(pid, '/proc', error);
     }
 }
-async function processInfo(pid) {
+const readProcess = async (pid) => {
     if (process.platform === 'linux')
         return procInfo(pid);
+    let stdout;
     try {
-        const { stdout } = await exec('ps', ['-ww', '-o', 'lstart=,rss=,command=', '-p', String(pid)], {
+        ({ stdout } = await exec('ps', ['-ww', '-o', 'lstart=,rss=,command=', '-p', String(pid)], {
             env: { ...process.env, LC_ALL: 'C' },
-        });
-        // lstart is a fixed 24-character date: "Thu Oct 15 00:21:26 2026".
-        const line = stdout.trim();
-        const startedAt = Date.parse(line.slice(0, 24));
-        const [rss = '', ...command] = line.slice(24).trim().split(/\s+/);
-        if (!Number.isFinite(startedAt))
-            return undefined;
-        return { startedAt, rssKb: Number(rss), command: command.join(' ') };
+        }));
     }
     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;
+        // ps exits 1 with no output when the pid does not exist; anything else (no ps, a sandbox
+        // that refuses it, killed) means the process state is unknown.
+        const failed = error;
+        if (failed.code === 1 &&
+            !String(failed.stdout ?? '').trim() &&
+            !String(failed.stderr ?? '').trim())
+            return undefined;
+        throw processInfoFailed(pid, 'ps', error);
     }
-}
+    // lstart is a fixed 24-character date: "Thu Oct 15 00:21:26 2026".
+    const line = stdout.trim();
+    if (!line)
+        return undefined;
+    const startedAt = Date.parse(line.slice(0, 24));
+    const [rss = '', ...command] = line.slice(24).trim().split(/\s+/);
+    if (!Number.isFinite(startedAt))
+        throw processInfoFailed(pid, 'ps', new Error(`Unexpected ps output: ${line.slice(0, 200)}`));
+    return { startedAt, rssKb: Number(rss), command: command.join(' ') };
+};
 /** The recorded process, when it is still alive and still this project's process. */
-async function live(record) {
-    const info = await processInfo(record.pid);
+async function live(record, read) {
+    const info = await read(record.pid);
     if (!info?.command.includes(record.entry)) {
         if (info)
             debug('Recorded pid runs another command; treating it as stale', { pid: record.pid });
@@ -129,10 +182,10 @@ async function live(record) {
     return info;
 }
 /** Whether the record's log writer still runs (its command names the writer and the entry). */
-async function writerAlive(record) {
+async function writerAlive(record, read) {
     if (record.logWriter === undefined)
         return false;
-    const info = await processInfo(record.logWriter);
+    const info = await read(record.logWriter);
     return Boolean(info?.command.includes('log-writer') && info.command.includes(record.entry));
 }
 async function logInfo(root) {
@@ -152,14 +205,29 @@ async function logInfo(root) {
     const writerBytes = await sizes(writerLog);
     return { logFiles: files, ...(writerBytes ? { logWriterLog: writerLog } : {}) };
 }
-export async function status(root) {
+export async function status(root, 
+/** Tests replace how a process is read; the CLI uses ps (/proc on Linux). */
+read = readProcess, 
+/** Tests replace how a process is signalled; the CLI uses process.kill. */
+kill = signalProcess) {
     const { pid, log } = paths(root);
     const record = await readRecord(root);
     const logs = await logInfo(root);
     if (!record)
         return { running: false, log, ...logs };
-    const info = await live(record);
-    if (!info) {
+    let info;
+    let proof = 'process';
+    try {
+        info = await live(record, read);
+    }
+    catch (error) {
+        if (!processInfoFailure(error))
+            throw error;
+        const found = await withoutProcessInfo(root, record, error, kill);
+        if (found !== 'gone')
+            proof = found;
+    }
+    if (!info && proof === 'process') {
         await rm(pid, { force: true });
         return {
             running: false,
@@ -175,14 +243,212 @@ export async function status(root) {
         pid: record.pid,
         startedAt: record.startedAt,
         uptimeSec: Math.round((Date.now() - Date.parse(record.startedAt)) / 1000),
-        rssMb: Math.round(info.rssKb / 1024),
+        ...(info ? { rssMb: Math.round(info.rssKb / 1024) } : {}),
+        proof,
         log,
         ...logs,
         ...(record.logWriter !== undefined
-            ? { logWriter: { pid: record.logWriter, running: await writerAlive(record) } }
+            ? {
+                logWriter: {
+                    pid: record.logWriter,
+                    running: proof === 'process'
+                        ? await writerAlive(record, read)
+                        : proof === 'log-writer' || pidState(record.logWriter, kill) === 'alive',
+                },
+            }
             : {}),
     };
 }
+/** The variable `start` gives the app (D-0073); @dokebi/web answers the challenge with it. */
+export const INSTANCE_TOKEN_ENV = 'DOKEBI_INSTANCE_TOKEN';
+/** The challenge request header and the answer response header of @dokebi/web. */
+export const INSTANCE_HEADER = 'x-dokebi-instance';
+/** The answer to a challenge: base64url HMAC-SHA256 keyed with the instance token. */
+export function instanceAnswer(token, challenge) {
+    return createHmac('sha256', token).update(challenge).digest('base64url');
+}
+/** `kill(pid, 0)`: ESRCH is gone; EPERM (or a sandbox refusing signals) says nothing for sure. */
+function pidState(pid, kill) {
+    try {
+        kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return 'gone';
+        debug('kill(pid, 0) failed; the pid state is unknown', { pid, error: describeError(error) });
+        return 'unknown';
+    }
+}
+/** The web address dokebi.yaml configures, for pid files that recorded none. */
+async function configuredUrl(root) {
+    let source;
+    try {
+        source = await readFile(join(root, CONFIG_FILE), 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            reportError('CONFIG_READ_FAILED', `Unable to read ${CONFIG_FILE}`, error);
+        return undefined;
+    }
+    let web;
+    try {
+        web = (parseProjectConfig(source).options['dokebi-web'] ?? {});
+    }
+    catch (error) {
+        // doctor reports an invalid dokebi.yaml; here it only means there is no address to try.
+        debug('dokebi.yaml could not be parsed; no configured address', {
+            error: describeError(error),
+        });
+        return undefined;
+    }
+    if (typeof web.port !== 'number' || web.port <= 0)
+        return undefined;
+    const host = typeof web.host !== 'string' || ['0.0.0.0', '::', '[::]'].includes(web.host)
+        ? '127.0.0.1'
+        : web.host;
+    return `http://${host.includes(':') ? `[${host}]` : host}:${web.port}`;
+}
+/** One challenge request; resolves with the answer header (undefined when there is none). */
+function challenge(url, value, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        const https = target.protocol === 'https:';
+        const req = (https ? httpsRequest : httpRequest)({
+            host: target.hostname.replace(/^\[|\]$/g, ''),
+            port: target.port,
+            path: '/',
+            method: 'GET',
+            headers: { [INSTANCE_HEADER]: value },
+            timeout: timeoutMs,
+            // The HMAC answer is the proof; a development certificate need not be trusted for it.
+            ...(https ? { rejectUnauthorized: false } : {}),
+        }, (response) => {
+            response.once('error', reject);
+            response.once('end', () => {
+                const answer = response.headers[INSTANCE_HEADER];
+                resolve(typeof answer === 'string' ? answer : undefined);
+            });
+            response.resume();
+        });
+        req.once('timeout', () => req.destroy(new Error(`No answer within ${timeoutMs} ms`)));
+        req.once('error', reject);
+        req.end();
+    });
+}
+/**
+ * Whether the app at the recorded address knows the record's instance token (D-0073): a random
+ * challenge must come back as HMAC-SHA256(token, challenge). The token never goes on the wire.
+ */
+export async function proveInstance(root, record, timeoutMs = 2000) {
+    if (!record.token)
+        return {
+            proven: false,
+            tried: [],
+            reason: 'the pid file has no instance token (started by an older CLI)',
+        };
+    const recorded = record.urls ?? [];
+    const configured = recorded.length ? undefined : await configuredUrl(root);
+    const urls = [
+        ...recorded.filter((url) => url.includes('127.0.0.1')),
+        ...recorded.filter((url) => !url.includes('127.0.0.1')),
+        ...(configured ? [configured] : []),
+    ].slice(0, 4);
+    if (!urls.length)
+        return {
+            proven: false,
+            tried: [],
+            reason: 'no address to ask: the app logged no web listening line and dokebi.yaml has no dokebi-web.port',
+        };
+    const reasons = [];
+    for (const url of urls) {
+        const value = randomBytes(24).toString('base64url');
+        const expected = Buffer.from(instanceAnswer(record.token, value));
+        try {
+            const answer = await challenge(url, value, timeoutMs);
+            const given = Buffer.from(answer ?? '');
+            if (given.length === expected.length && timingSafeEqual(given, expected)) {
+                debug('The app proved its instance token', { url });
+                return { proven: true, url, tried: urls };
+            }
+            reasons.push(`${url}: ${answer === undefined ? `answered without ${INSTANCE_HEADER}` : 'wrong answer'}`);
+        }
+        catch (error) {
+            reasons.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    debug('No instance proof', { tried: urls, reasons });
+    return { proven: false, tried: urls, reason: reasons.join('; ') };
+}
+const processInfoFailure = (error) => error instanceof CliError && error.code === 'PROCESS_INFO_FAILED';
+/**
+ * Asks the record's log writer (its control socket) to do `request` once both sides proved the
+ * record's instance token, and checks that the writer's app is the recorded pid.
+ */
+async function askWriter(record, request) {
+    if (!record.token)
+        return {
+            reached: false,
+            reason: 'the pid file has no instance token (started by an older CLI)',
+        };
+    if (record.control === undefined)
+        return {
+            reached: false,
+            reason: 'the pid file names no control port (started by an older CLI, or the log writer could not listen: see .dokebi/run/log-writer.log)',
+        };
+    const asked = await askLogWriter(record.control, record.token, request);
+    if (!asked.reached)
+        return asked;
+    if (asked.app.pid !== record.pid) {
+        await asked.closed(0);
+        return {
+            reached: false,
+            reason: `the log writer runs pid ${asked.app.pid}, not the recorded pid ${record.pid}`,
+        };
+    }
+    return { reached: true, running: asked.app.running, reply: asked.reply, closed: asked.closed };
+}
+/**
+ * Without process information: `gone` (no such pid, or its log writer saw it exit),
+ * `log-writer` (the app's log writer proved the token on its control socket), `http` (the app
+ * proved the token over HTTP), or the original PROCESS_INFO_FAILED with what the proofs found,
+ * so an unproven pid is never used.
+ */
+async function withoutProcessInfo(root, record, failure, kill) {
+    const state = pidState(record.pid, kill);
+    if (state === 'gone') {
+        debug('No process information, but the recorded pid does not exist', { pid: record.pid });
+        return 'gone';
+    }
+    // The log writer first: it needs no web plugin, and it can stop the app when this shell may
+    // not signal it (an agent sandbox per command, AI-M03).
+    const writer = await askWriter(record, { op: 'status' });
+    if (writer.reached) {
+        debug('The log writer proved the instance token', { pid: record.pid, running: writer.running });
+        return writer.running ? 'log-writer' : 'gone';
+    }
+    const tried = record.control !== undefined ? [`tcp://${CONTROL_HOST}:${record.control}`] : [];
+    const reasons = [`log writer: ${writer.reason}`];
+    if (state === 'alive') {
+        const proof = await proveInstance(root, record);
+        if (proof.proven)
+            return 'http';
+        tried.push(...proof.tried);
+        if (proof.reason)
+            reasons.push(`http: ${proof.reason}`);
+    }
+    // kill(pid, 0) refused (EPERM): a sandbox or another user. The HTTP proof would not help:
+    // the stop signal itself would be refused too (AI-M03).
+    else
+        reasons.push(`pid ${record.pid} cannot be signalled from this shell (a sandbox or another user): stopping needs its log writer or a shell that may signal it`);
+    throw new CliError(failure.code, failure.message, {
+        cause: failure.cause ?? failure,
+        details: {
+            ...failure.details,
+            instanceProof: { tried, reason: reasons.join('; ') },
+        },
+    });
+}
 async function checkProject(root) {
     const { entry } = paths(root);
     if (!existsSync(entry))
@@ -196,10 +462,6 @@ async function checkProject(root) {
         });
     return entry;
 }
-const environment = (mode) => ({
-    ...process.env,
-    NODE_ENV: process.env.NODE_ENV ?? mode,
-});
 /**
  * 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.
@@ -272,8 +534,20 @@ check = checkProject) {
             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' });
@@ -309,7 +583,8 @@ check = checkProject) {
                 cwd: root,
                 detached: true,
                 stdio: ['ignore', 'ignore', writerLog.fd, 'ipc'],
-                env: environment('production'),
+                // The writer starts the app with its own environment.
+                env,
             });
         }
         finally {
@@ -320,6 +595,9 @@ check = checkProject) {
             throw new CliError('START_FAILED', 'The log writer process could not be spawned');
         const state = {};
         writer.on('message', (message) => {
+            // The writer sends its control port before it spawns the app (IPC keeps the order).
+            if (typeof message?.control === 'number')
+                state.control = message.control;
             if (typeof message?.spawned === 'number')
                 state.pid = message.spawned;
             if (message?.ready)
@@ -342,18 +620,24 @@ check = checkProject) {
             return new CliError('START_FAILED', message, {
                 details: {
                     log: files.log,
-                    tail: await tail(files.log, 30),
-                    logWriterLog: (await lastLines(files.writerLog, 30)).join('\n'),
+                    // App output in a result: credentials masked like npm output (logs prints it as is).
+                    tail: redactNpmOutput(await tail(files.log, 30)),
+                    logWriterLog: redactNpmOutput((await lastLines(files.writerLog, 30)).join('\n')),
                 },
             });
         };
+        // The pid file holds the instance token: only the owner reads it (0600).
+        const save = async (record) => {
+            await rm(`${files.pid}.tmp`, { force: true });
+            await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+            await rename(`${files.pid}.tmp`, files.pid);
+        };
         const deadline = performance.now() + waitMs;
         let recorded;
         while (performance.now() < deadline) {
             await delay(50);
             if (state.pid !== undefined && recorded === undefined) {
-                recorded = state.pid;
-                const record = {
+                recorded = {
                     pid: state.pid,
                     startedAt: new Date().toISOString(),
                     entry,
@@ -361,9 +645,10 @@ check = checkProject) {
                     logWriter: writerPid,
                     logMaxBytes: maxBytes,
                     logFiles: keep,
+                    token,
+                    ...(state.control !== undefined ? { control: state.control } : {}),
                 };
-                await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`);
-                await rename(`${files.pid}.tmp`, files.pid);
+                await save(recorded);
                 debug('App process spawned; waiting for the start line', { pid: state.pid });
             }
             if (state.exited !== undefined)
@@ -382,13 +667,20 @@ check = checkProject) {
         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`);
+        const listen = ready ? await startedUrls(files.log, logOffset) : [];
+        // Where stop and status ask for the instance proof when ps is unavailable (D-0073): the
+        // listening address (the proof does not depend on the Host header).
+        if (listen.length)
+            await save({ ...recorded, urls: listen });
         return {
-            pid: recorded,
+            pid: recorded.pid,
             log: files.log,
             logWriter: writerPid,
             logMaxBytes: maxBytes,
             logFiles: keep,
             ready,
+            urls: appUrls(listen, await appHostsOrNone(root)),
+            listen,
             ms: Math.round(performance.now() - began),
             warnings,
         };
@@ -401,16 +693,115 @@ check = checkProject) {
         await rm(files.lock, { force: true });
     }
 }
-export async function stop(root, timeoutMs = 30_000, force = false) {
+/**
+ * HTTP URLs from `Web server listening` log lines (D-0065): `address`, `addresses` or `urls`
+ * fields as strings (`http://…`) or `{ address, port }` objects. Unknown shapes are skipped.
+ */
+export function listeningUrls(text) {
+    const urls = new Set();
+    const add = (value) => {
+        if (typeof value === 'string' && /^https?:\/\//.test(value))
+            urls.add(value.replace(/\/$/, ''));
+        else if (value && typeof value === 'object') {
+            const { address, port } = value;
+            if (typeof address === 'string' && typeof port === 'number')
+                urls.add(`http://${address.includes(':') ? `[${address}]` : address}:${port}`);
+        }
+    };
+    for (const line of text.split('\n')) {
+        if (!/listening/i.test(line))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (error) {
+            // Plain output of the app, not a JSON log line: it carries no address.
+            debug('Skipped a non-JSON log line while looking for addresses', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        if (typeof record.message !== 'string' || !/web server listening/i.test(record.message))
+            continue;
+        for (const key of ['address', 'addresses', 'url', 'urls']) {
+            const value = record[key];
+            for (const item of Array.isArray(value) ? value : [value])
+                add(item);
+        }
+    }
+    return [...urls];
+}
+/**
+ * The app host settings for the shown URLs; when they cannot be read the listening addresses are
+ * shown instead (the app already runs: this is no reason to fail the command).
+ */
+export async function appHostsOrNone(root) {
+    try {
+        return await readAppHosts(root);
+    }
+    catch (error) {
+        reportError('APP_HOSTS_FAILED', 'Unable to read the app domains; the listening addresses are shown instead', error);
+        return { hosted: false, domains: [], answersUnknown: false };
+    }
+}
+async function startedUrls(log, offset) {
+    try {
+        const bytes = await readFile(log);
+        // A rotation since the start moved the lines: read the whole current file then.
+        return listeningUrls((bytes.length >= offset ? bytes.subarray(offset) : bytes).toString('utf8'));
+    }
+    catch (error) {
+        if (!isMissing(error))
+            reportError('LOG_READ_FAILED', 'Unable to read the app log', error);
+        return [];
+    }
+}
+export async function stop(root, timeoutMs = 30_000, force = false, 
+/** Tests replace how a process is read; the CLI uses ps (/proc on Linux). */
+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 };
-    if (!(await live(record))) {
+    // Without process information the app's log writer or the app itself must prove the instance
+    // token (D-0073); otherwise PROCESS_INFO_FAILED propagates and the pid file stays (a live
+    // server is not orphaned, an unproven pid is never signalled).
+    let proof = 'process';
+    let found;
+    try {
+        found = Boolean(await live(record, read));
+    }
+    catch (error) {
+        if (!processInfoFailure(error))
+            throw error;
+        const how = await withoutProcessInfo(root, record, error, kill);
+        found = how !== 'gone';
+        if (how !== 'gone')
+            proof = how;
+    }
+    if (!found) {
+        debug('Removing a stale pid file', { pid: record.pid });
         await rm(files.pid, { force: true });
         return { stopped: false, pid: record.pid, stale: true };
     }
+    if (proof === 'log-writer')
+        return stopThroughWriter(root, record, timeoutMs, force, proof);
+    // SIGTERM goes to the app (core drain); the log writer exits once the app's output ends.
+    debug('Sending SIGTERM', { pid: record.pid, timeoutMs, proof });
+    try {
+        kill(record.pid, 'SIGTERM');
+    }
+    catch (error) {
+        if (error.code !== 'EPERM')
+            throw error;
+        // The app runs in another sandbox instance (AI-M03): its log writer may signal it.
+        debug('SIGTERM refused; asking the log writer', { pid: record.pid, proof });
+        return stopThroughWriter(root, record, timeoutMs, force, proof, error);
+    }
     const began = performance.now();
     const gone = async (alive, limit) => {
         const until = performance.now() + limit;
@@ -421,30 +812,160 @@ export async function stop(root, timeoutMs = 30_000, force = false) {
         }
         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');
+    // Proven over HTTP: liveness is kill(pid, 0) from here on, as in stopStarted.
+    const app = proof === 'process'
+        ? async () => Boolean(await live(record, read))
+        : async () => pidExists(record.pid, kill);
+    const writer = proof === 'process'
+        ? () => writerAlive(record, read)
+        : async () => record.logWriter !== undefined && pidExists(record.logWriter, kill);
     let forced = false;
     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');
+        kill(record.pid, 'SIGKILL');
         forced = true;
         if (!(await gone(app, 5000)))
             throw new CliError('STOP_TIMEOUT', `pid ${record.pid} survived SIGKILL`);
     }
     await rm(files.pid, { force: true });
     const warnings = [];
-    if (record.logWriter !== undefined && !(await gone(() => writerAlive(record), 5000))) {
+    // 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) => {
+        reportError('PROCESS_INFO_FAILED', 'Unable to check the log writer after stop', error);
+        warnings.push(`could not check the log writer (pid ${record.logWriter}): ${error instanceof Error ? error.message : String(error)}`);
+        return true;
+    });
+    if (record.logWriter !== undefined && !writerGone) {
+        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,
+        proof,
+        via: 'signal',
+        ...(warnings.length ? { warnings } : {}),
+    };
+}
+/**
+ * The stop through the app's log writer (D-0073 addendum): it sends SIGTERM, waits `timeoutMs`
+ * and, with `force`, SIGKILL. Then the pid file goes and the writer's exit is awaited (it closes
+ * 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)
+        throw new CliError('STOP_FAILED', `Unable to stop pid ${record.pid}: this shell may not signal it (a sandbox or another user) and its log writer could not be asked (${asked.reason})`, {
+            cause: refused,
+            details: {
+                pid: record.pid,
+                logWriter: asked.reason,
+                hint: 'run dokebi stop from a shell that may signal the app (outside the sandbox)',
+                manualStop: `kill -TERM ${record.pid} from such a shell (drain), then remove .dokebi/run/app.pid`,
+            },
+        });
+    const { reply } = asked;
+    if (reply.ok !== true) {
+        await asked.closed(0);
+        throw new CliError(reply.code === 'STOP_TIMEOUT' ? 'STOP_TIMEOUT' : 'STOP_FAILED', typeof reply.message === 'string'
+            ? reply.message
+            : `The log writer could not stop pid ${record.pid} (${String(reply.code)})`);
+    }
+    await rm(files.pid, { force: true });
+    if (reply.stopped !== true) {
+        debug('The log writer reports that the app had already exited', { pid: record.pid });
+        await asked.closed(0);
+        return { stopped: false, pid: record.pid, stale: true };
+    }
+    const warnings = [];
+    // The writer closes the connection once it finished the log and exits.
+    if (!(await asked.closed(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`);
     }
+    debug('The log writer stopped the app', { pid: record.pid, forced: reply.forced });
     return {
         stopped: true,
         pid: record.pid,
         ms: Math.round(performance.now() - began),
+        forced: reply.forced === true,
+        proof,
+        via: 'log-writer',
+        ...(warnings.length ? { warnings } : {}),
+    };
+}
+/** Whether a pid exists, by `kill(pid, 0)` (no `ps`): ESRCH is gone, anything else throws. */
+function pidExists(pid, kill = signalProcess) {
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        throw new CliError('STOP_FAILED', `Unable to signal pid ${pid}`, {
+            cause: error,
+            details: { pid },
+        });
+    }
+}
+/**
+ * Stops the app this CLI run started (`start`'s result), without `ps` (see the file comment):
+ * SIGTERM, wait for the drain, SIGKILL after `timeoutMs` when `force`, then the pid file (when it
+ * still names this process) and a wait for the log writer. An app that already exited by itself
+ * is `{ stopped: false, stale: true }`.
+ */
+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 gone = async (pid, limit) => {
+        const until = performance.now() + limit;
+        while (performance.now() < until) {
+            if (!pidExists(pid))
+                return true;
+            await delay(100);
+        }
+        return !pidExists(pid);
+    };
+    if (!pidExists(started.pid)) {
+        debug('The started app had already exited', { pid: started.pid });
+        await forget();
+        return { stopped: false, pid: started.pid, stale: true };
+    }
+    const began = performance.now();
+    debug('Sending SIGTERM to the started app', { pid: started.pid, timeoutMs });
+    process.kill(started.pid, 'SIGTERM');
+    let forced = false;
+    if (!(await gone(started.pid, timeoutMs))) {
+        if (!force)
+            throw new CliError('STOP_TIMEOUT', `pid ${started.pid} did not stop within ${timeoutMs} ms; it is still draining or stuck`);
+        debug('Stop timed out; sending SIGKILL', { pid: started.pid });
+        process.kill(started.pid, 'SIGKILL');
+        forced = true;
+        if (!(await gone(started.pid, 5000)))
+            throw new CliError('STOP_TIMEOUT', `pid ${started.pid} survived SIGKILL`);
+    }
+    await forget();
+    const warnings = [];
+    if (!(await gone(started.logWriter, 5000))) {
+        debug('Log writer still running after the app stopped', { writer: started.logWriter });
+        warnings.push(`the log writer (pid ${started.logWriter}) was still running 5 s after the app stopped; a process the app started may hold its output`);
+    }
+    return {
+        stopped: true,
+        pid: started.pid,
+        ms: Math.round(performance.now() - began),
         forced,
         ...(warnings.length ? { warnings } : {}),
     };
@@ -656,7 +1177,8 @@ export async function foreground(root) {
     const child = spawn(process.execPath, [entry], {
         cwd: root,
         stdio: 'inherit',
-        env: environment('production'),
+        // The project's .env under the CLI's environment (D-0073).
+        env: appEnvironment(root, 'production'),
     });
     const forward = (signal) => () => child.kill(signal);
     const onInt = forward('SIGINT');
@@ -701,31 +1223,61 @@ const VIEW_FILE = /(^|[\\/])views[\\/].*\.(js|mjs|ts)$|\.(vue|css|scss|sass|less
 /**
  * Development loop: runs the app, restarts it (SIGTERM, drain, start) 300 ms after a change in
  * src/, dokebi.yaml or .env. With a Vite config, Inertia views come from the Vite dev server
- * inside the app (HMR, D-0045) when template-inertia supports it, otherwise from watch builds
- * that restart the app. The first Ctrl+C drains everything; a second one kills.
+ * (HMR, D-0045) when template-inertia supports it, otherwise from watch builds that restart the
+ * app. With template-inertia 0.4.0 that Vite is one host process beside the app, shared by every
+ * cluster worker and kept across app restarts (D-0045 addendum 3); older ones start it inside the app.
+ * The first Ctrl+C drains everything; a second one kills.
  */
 export async function dev(root, say) {
     const entry = await checkProject(root);
+    // The project's .env (D-0073), read again before every (re)start: a change restarts the app
+    // with the new values. A malformed file fails here and, later, fails that restart only.
+    let fileEnv = readEnvFile(root);
     let app;
     let exiting = false;
     const hasVite = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js'].some((name) => existsSync(join(root, name)));
     const hot = hasVite && inertiaDevServer(root);
     if (hot)
         say('Inertia views: Vite dev server with hot module replacement');
+    // Where to open the app (AI-M03): its domains, not the listening IP the app logs.
+    const configured = await configuredUrl(root);
+    if (configured) {
+        const urls = appUrls([configured], await appHostsOrNone(root));
+        say(urls.length
+            ? `the app answers at ${urls.join(' ')}`
+            : `listening on ${configured}; the app answers only the Host names of its domains (none is a loopback name such as localhost)`);
+    }
     const guard = new URL('./dev-guard.js', import.meta.url).href;
     // stdio fd 3 is the IPC channel the guard watches.
-    const child = (args) => spawn(process.execPath, ['--import', guard, ...args], {
+    const child = (args, extra = {}) => spawn(process.execPath, ['--import', guard, ...args], {
         cwd: root,
         stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
         // 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' } : {}),
-        },
+        env: appEnvironment(root, 'development', { DOKEBI_DEV: '1', ...(hot ? { DOKEBI_VITE_DEV: '1' } : {}), ...extra }, fileEnv),
     });
-    const run = () => {
-        app = child([entry]);
+    // One Vite for the session (D-0045 addendum 3) when template-inertia has the host script.
+    const hostScript = hot ? viteHostScript(root) : undefined;
+    const viteHost = hostScript ? new ViteHostProcess(() => child([hostScript]), say) : undefined;
+    debug('dev Vite mode', { hot, host: hostScript !== undefined });
+    const run = async () => {
+        try {
+            fileEnv = readEnvFile(root);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                say(`${error.message}; fix it and save again`);
+            // Reported by the caller (DEV_START_FAILED / DEV_RESTART_FAILED); the next change retries.
+            throw error;
+        }
+        let extra = {};
+        if (viteHost) {
+            const address = await viteHost.ensure();
+            // Said by the host process; the next change starts it again.
+            if (!address || exiting)
+                return;
+            extra = { DOKEBI_VITE_DEV_URL: address.url, DOKEBI_VITE_DEV_KEY: address.key };
+        }
+        app = child([entry], extra);
         const current = app;
         current.once('exit', (code, signal) => {
             if (app === current && !exiting)
@@ -793,9 +1345,11 @@ export async function dev(root, say) {
         await Promise.all(helpers.map((helper) => halt(helper, 5000)));
         throw error;
     }
-    run();
     let timer;
-    let restarting = Promise.resolve();
+    let restarting = run().catch((error) => {
+        // Keep the loop alive: the next change tries again.
+        reportError('DEV_START_FAILED', 'Starting the app failed', error);
+    });
     const changed = (what) => {
         if (exiting)
             return;
@@ -810,7 +1364,7 @@ export async function dev(root, say) {
                 app = undefined;
                 await halt(previous);
                 if (!exiting)
-                    run();
+                    await run();
             })
                 .catch((error) => {
                 // Keep the loop alive: the next change tries again.
@@ -831,6 +1385,9 @@ export async function dev(root, say) {
         watch(root, (_event, name) => {
             if (name === 'dokebi.yaml' || name === '.env')
                 changed(name);
+            // A running Vite reloads its own config; a host that failed to start tries again.
+            else if (viteHost && name && /^vite\.config\.[cm]?[jt]s$/.test(name) && !viteHost.running)
+                changed(name);
         }),
     ];
     return await new Promise((resolve) => {
@@ -839,6 +1396,7 @@ export async function dev(root, say) {
                 app?.kill('SIGKILL');
                 for (const helper of helpers)
                     helper.kill('SIGKILL');
+                await viteHost?.stop(0, true);
                 resolve(130);
                 return;
             }
@@ -849,6 +1407,8 @@ export async function dev(root, say) {
                 watcher.close();
             await restarting;
             await Promise.all([halt(app), ...helpers.map((helper) => halt(helper, 5000))]);
+            // After the app: its requests and server renders go to the host until it has drained.
+            await viteHost?.stop();
             resolve(0);
         };
         process.on('SIGINT', () => void finish());