@dokebi/cli 0.4.1 → 0.4.26

package/dist/install-module.js

@@ -1,27 +1,143 @@
 import { spawn } from 'node:child_process';
-import { realpath } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, dirname, join, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { debug, debugEnabled, describeError } from './diagnostics.js';
+import { debug, debugEnabled, describeError, isMissing } from './diagnostics.js';
+import { redactNpmOutput } from './npm-client.js';
 export class InstallPlanningError extends Error {
     code;
-    constructor(code) {
-        super('Plugin installation planning failed (' + code + ').');
+    /**
+     * What the module said: the message of the error it threw, or the end of its stderr when the
+     * process failed (at most DETAIL_CHARS, `user:password@` and tokens masked). Without it a
+     * failing planInstall was only INSTALL_MODULE_FAILED, and its author could not see why.
+     */
+    detail;
+    constructor(code, options) {
+        super(`Plugin installation planning failed (${code}).`, options);
         this.code = code;
         this.name = 'InstallPlanningError';
+        // Masked before it is cut (R4CB-7): a cut inside a password left its first part without the
+        // `@` the mask looks for.
+        const detail = options?.detail ? redactNpmOutput(options.detail).trim() : undefined;
+        this.detail = detail ? detail.slice(0, DETAIL_CHARS) : undefined;
     }
 }
+const DETAIL_CHARS = 2000;
+/** The end of stderr kept for the detail: more than it shows, so the mask sees whole values. */
+const STDERR_CHARS = DETAIL_CHARS * 2;
 /** Returned when the module does not export the requested phase. */
 export const PHASE_MISSING = Symbol('dokebi.install.phase-missing');
 const MAX_BYTES = 1024 * 1024;
 const TIMEOUT_MS = 5000;
-const RUNNER = "\nconst finish = (value) => process.stdout.write(JSON.stringify(value), () => process.exit(0));\ntry {\n let input = '';\n for await (const chunk of process.stdin) input += chunk;\n const freeze = (value) => {\n  if (value && typeof value === 'object') {for (const child of Object.values(value)) freeze(child);Object.freeze(value);}\n  return value;\n };\n const phase = process.argv[2];\n const context = freeze({ ...JSON.parse(input), phase });\n const module = await import(process.argv[1]);\n if (typeof module[phase] !== 'function') finish({ok:true,missing:true});\n else {\n  const plan = await module[phase](context);\n  if(plan === undefined)finish({ok:false,code:'INSTALL_PLAN_INVALID'});\n  else finish({ok:true,plan});\n }\n} catch(error) {\n const code = error && error.code === 'ERR_ACCESS_DENIED' ? 'INSTALL_PERMISSION_DENIED' : error && typeof error.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : 'INSTALL_MODULE_FAILED';\n finish({ok:false,code});\n}\n";
+const RUNNER = "\nconst finish = (value) => process.stdout.write(JSON.stringify(value), () => process.exit(0));\ntry {\n let input = '';\n for await (const chunk of process.stdin) input += chunk;\n const freeze = (value) => {\n  if (value && typeof value === 'object') {for (const child of Object.values(value)) freeze(child);Object.freeze(value);}\n  return value;\n };\n const phase = process.argv[2];\n const context = freeze({ ...JSON.parse(input), phase });\n const failure = (error) => ({ok:false,code:error && error.code === 'ERR_ACCESS_DENIED' ? 'INSTALL_PERMISSION_DENIED' : error && typeof error.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : 'INSTALL_MODULE_FAILED',message:String(error && error.stack || error).slice(0, 4000)});\n // D-0162: one child checks the options of every listed plugin (context.entries: {url, options}) with\n // the main entry's createPlugin.checkOptions; each plugin's result or failure is its own.\n if (phase === 'checkOptions') {\n  const results = [];\n  for (const entry of context.entries) {\n   try {\n    const factory = (await import(entry.url)).createPlugin;\n    results.push(typeof factory?.checkOptions === 'function' ? {ok:true,result:factory.checkOptions(entry.options)} : {ok:true,missing:true});\n   } catch (error) { results.push(failure(error)); }\n  }\n  finish({ok:true,plan:results});\n } else {\n const module = await import(process.argv[1]);\n if (typeof module[phase] !== 'function') finish({ok:true,missing:true});\n else {\n  const plan = await module[phase](context);\n  if(plan === undefined)finish({ok:false,code:'INSTALL_PLAN_INVALID'});\n  else finish({ok:true,plan});\n }\n }\n} catch(error) {\n const code = error && error.code === 'ERR_ACCESS_DENIED' ? 'INSTALL_PERMISSION_DENIED' : error && typeof error.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : 'INSTALL_MODULE_FAILED';\n finish({ok:false,code,message:String(error && error.stack || error).slice(0, 4000)});\n}\n";
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i;
+/** Packages an install module may read (its own and its dependencies, transitively). */
+const MAX_READ_PACKAGES = 512;
+async function dependencyNames(directory) {
+    let text;
+    try {
+        text = await readFile(join(directory, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        // A folder without package.json (a bare install module) declares no dependencies.
+        if (!isMissing(error))
+            throw error;
+        debug('Install module package has no package.json', { directory });
+        return [];
+    }
+    const pkg = JSON.parse(text);
+    const names = new Set();
+    for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+        const value = pkg[field];
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            for (const name of Object.keys(value))
+                if (PACKAGE_NAME.test(name))
+                    names.add(name);
+    }
+    return [...names];
+}
+/** Where Node finds `name` from `directory`: `node_modules/<name>` in it or a parent folder. */
+async function findPackage(directory, name) {
+    for (let current = directory;; current = dirname(current)) {
+        if (basename(current) !== 'node_modules') {
+            const candidate = join(current, 'node_modules', name);
+            try {
+                await stat(candidate);
+                return candidate;
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        if (dirname(current) === current)
+            return undefined;
+    }
+}
+/**
+ * The folders an install module may read (R9): its own package and the packages it depends on
+ * (`dependencies`, `optionalDependencies`, `peerDependencies`, transitively), each found the way
+ * Node resolves it from the importer's real folder, and allowed both where Node finds it (a
+ * `node_modules/<name>` link) and at its real path. Never the project, the workspace root or
+ * the rest of `node_modules`, so `.env` files and other projects' files stay unreadable.
+ */
+export async function installReadRoots(packageDirectory) {
+    const own = await realpath(packageDirectory);
+    const roots = new Set([own]);
+    const visited = new Set([own]);
+    const queue = [own];
+    for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+        for (const name of await dependencyNames(next)) {
+            const found = await findPackage(next, name);
+            if (!found) {
+                // Optional and peer dependencies may be absent; an import of them fails on its own.
+                debug('Install module dependency not found', { package: next, dependency: name });
+                continue;
+            }
+            const real = await realpath(found);
+            roots.add(found);
+            roots.add(real);
+            if (visited.has(real))
+                continue;
+            visited.add(real);
+            if (visited.size > MAX_READ_PACKAGES)
+                throw new InstallPlanningError('INSTALL_DEPENDENCIES_LIMIT');
+            queue.push(real);
+        }
+    }
+    // A folder inside another allowed folder adds nothing; the own package stays first (cwd).
+    const sorted = [...roots].sort();
+    const result = [own];
+    for (const root of sorted)
+        if (root !== own &&
+            !sorted.some((other) => other !== root && root.startsWith(other + sep)) &&
+            !root.startsWith(own + sep))
+            result.push(root);
+    debug('Install module read roots', { package: own, roots: result });
+    return result;
+}
 /**
  * Runs one lifecycle phase of a plugin installation module in a child process.
  * The child uses the Node permission model: it may read only `readRoots`
- * (real paths), cannot write files or spawn processes, and receives no
+ * (at their real and link paths), cannot write files or spawn processes, and receives no
  * parent environment variables. Node 24 does not restrict network access.
  */
+/**
+ * The `--allow-fs-read` flags of the restricted child. Node 24.15's permission model denies a
+ * granted folder when a sibling folder whose name starts with it is granted too (with
+ * `node_modules/@dokebi/web` and `node_modules/@dokebi/websocket`, `realpath` of the first is
+ * ERR_ACCESS_DENIED, so `import('@dokebi/web')` fails: seen with D-0162's options check of
+ * dokebi-websocket). Such a folder is granted as `<folder>*`, which Node handles; it adds only
+ * the siblings that start with the same name.
+ */
+export function readPermissions(roots) {
+    return roots.map((root) => {
+        const parent = dirname(root);
+        const name = basename(root);
+        const shadowed = roots.some((other) => other !== root && dirname(other) === parent && basename(other).startsWith(name));
+        return `--allow-fs-read=${root}${shadowed ? '*' : ''}`;
+    });
+}
 export async function runInstallModule(modulePath, phase, context, readRoots = [dirname(modulePath)]) {
     const input = JSON.stringify(context);
     if (Buffer.byteLength(input) > MAX_BYTES)
@@ -29,16 +145,22 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
     let roots;
     let moduleUrl;
     try {
-        roots = await Promise.all(readRoots.map((root) => realpath(root)));
+        // Each root at its real path and, when it is a link (a package in node_modules), also at the
+        // link: Node checks the path it resolves through (node_modules/<name>/package.json) as well.
+        const resolved = await Promise.all(readRoots.map(async (root) => [
+            await realpath(root),
+            join(await realpath(dirname(root)), basename(root)),
+        ]));
+        roots = [...new Set(resolved.flat())];
         moduleUrl = pathToFileURL(await realpath(modulePath)).href;
     }
-    catch {
-        throw new InstallPlanningError('INSTALL_MODULE_MISSING');
+    catch (cause) {
+        throw new InstallPlanningError('INSTALL_MODULE_MISSING', { cause });
     }
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [
             '--permission',
-            ...roots.map((root) => `--allow-fs-read=${root}`),
+            ...readPermissions(roots),
             '--input-type=module',
             '--eval',
             RUNNER,
@@ -46,6 +168,7 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
             phase,
         ], { stdio: ['pipe', 'pipe', 'pipe'], env: {}, cwd: roots[0] });
         const chunks = [];
+        let stderr = '';
         let size = 0;
         let failure;
         const stop = (code) => {
@@ -64,6 +187,8 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
             size += chunk.length;
             if (size > MAX_BYTES)
                 stop('INSTALL_OUTPUT_LIMIT');
+            else
+                stderr = (stderr + chunk.toString('utf8')).slice(-STDERR_CHARS);
         });
         // Both become the typed InstallPlanningError the caller receives; debug keeps the cause.
         child.on('error', (error) => {
@@ -84,7 +209,9 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
                 return;
             }
             if (code !== 0) {
-                reject(new InstallPlanningError('INSTALL_PROCESS_FAILED'));
+                // The end of stderr, masked while whole (R4CB-7).
+                const tail = redactNpmOutput(stderr).trim().slice(-DETAIL_CHARS);
+                reject(new InstallPlanningError('INSTALL_PROCESS_FAILED', { detail: tail }));
                 return;
             }
             try {
@@ -103,7 +230,9 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
                 if (envelope.ok === false &&
                     typeof envelope.code === 'string' &&
                     /^[A-Z][A-Z0-9_]{0,63}$/.test(envelope.code)) {
-                    reject(new InstallPlanningError(envelope.code));
+                    reject(new InstallPlanningError(envelope.code, {
+                        detail: typeof envelope.message === 'string' ? envelope.message : undefined,
+                    }));
                     return;
                 }
             }

package/dist/install-plan.js

@@ -1,7 +1,7 @@
 import { path as paths } from '@dokebi/core/libraries';
+import { validateDefaults } from './config-values.js';
 import { CliError } from './errors.js';
 import { object, relativePath, templateTarget } from './filesystem.js';
-import { validateDefaults } from './merge-install-defaults.js';
 /**
  * Who edits a written file (D-0065 §11): `user` — a scaffold written once for the developer to
  * change (layouts, views, examples); doctor never reports an edit, upgrade keeps an edited copy.
@@ -71,8 +71,10 @@ export function readInstallPlan(value, legacy, extended = true) {
             try {
                 validateDefaults(plan.configDefaults);
             }
-            catch {
-                throw new CliError('INVALID_MANIFEST', 'Invalid install configuration defaults');
+            catch (cause) {
+                throw new CliError('INVALID_MANIFEST', 'Invalid install configuration defaults', {
+                    cause,
+                });
             }
             configDefaults = plan.configDefaults;
         }

package/dist/layout.d.ts

@@ -1,7 +1,9 @@
 import type { InstallPlan } from './install-plan.js';
 /**
  * Project layout (D-0031, D-0032). Plugins write only into
- * - `src/shared/<area>/…` — shared business code: models, modules (D-0032), views
+ * - `src/shared/<area>/…` — shared business code: models, services, modules (D-0032), views,
+ *   mail templates and locales (the consumer-facing rule is "Files and folders" in
+ *   capability-guide.ts, D-0092 §3)
  * - `src/infra/<name>/…` — code that wires a plugin up (connections, types, shared props …)
  * Files sit inside such a folder; plugins may also create the folder itself.
  * The plugin that hosts apps (manifest `dokebi.hosts: ["apps"]`, D-0070) also prepares `src/apps/`
@@ -16,3 +18,12 @@ export declare function assertLayout(plan: Pick<InstallPlan, 'files' | 'director
 }, pluginId: string, hosts?: readonly string[]): void;
 /** Installed entry paths from before D-0031 keep working; doctor reports them once. */
 export declare function legacyLayout(path: string, hosts?: readonly string[]): boolean;
+/**
+ * Source files older recipes wrote outside the "Files and folders" rule (the src root holds only
+ * main.ts and dokebi.generated.ts), mapped to where the current recipe writes them. Such a file
+ * keeps working where it is: doctor reports it as a LEGACY_LAYOUT warning that names the new
+ * place, and a re-run of the recipe keeps using the old file instead of writing a second copy.
+ * Moving it stays the developer's step because the file is user code (its relative imports and
+ * the import in src/main.ts change with it).
+ */
+export declare const MOVED_RECIPE_FILES: Readonly<Record<string, string>>;

package/dist/layout.js

@@ -2,7 +2,9 @@ import { path as paths } from '@dokebi/core/libraries';
 import { CliError } from './errors.js';
 /**
  * Project layout (D-0031, D-0032). Plugins write only into
- * - `src/shared/<area>/…` — shared business code: models, modules (D-0032), views
+ * - `src/shared/<area>/…` — shared business code: models, services, modules (D-0032), views,
+ *   mail templates and locales (the consumer-facing rule is "Files and folders" in
+ *   capability-guide.ts, D-0092 §3)
  * - `src/infra/<name>/…` — code that wires a plugin up (connections, types, shared props …)
  * Files sit inside such a folder; plugins may also create the folder itself.
  * The plugin that hosts apps (manifest `dokebi.hosts: ["apps"]`, D-0070) also prepares `src/apps/`
@@ -10,11 +12,11 @@ import { CliError } from './errors.js';
  */
 export function layoutAllowed(path, hosts = [], kind = 'file') {
     const key = paths.portablePathKey(path);
-    // Files live inside a named folder: src/shared/<area>/… (models, modules, views — D-0032) or
-    // src/infra/<name>/…
+    // Files live inside a named folder: src/shared/<area>/… (models, services, modules, views, mail,
+    // locales — D-0032, D-0092) or src/infra/<name>/…
     const area = kind === 'file'
-        ? /^src\/(shared\/(models|modules|views)|infra\/[^/]+)\/.+$/
-        : /^src\/(shared\/(models|modules|views)|infra\/[^/]+)(\/.+)?$/;
+        ? /^src\/(shared\/(models|services|modules|views|mail|locales)|infra\/[^/]+)\/.+$/
+        : /^src\/(shared\/(models|services|modules|views|mail|locales)|infra\/[^/]+)(\/.+)?$/;
     if (area.test(key))
         return true;
     return hosts.includes('apps') && (key === 'src/apps' || key.startsWith('src/apps/'));
@@ -28,9 +30,20 @@ export function assertLayout(plan, pluginId, hosts = []) {
     ];
     for (const [target, kind] of targets)
         if (!layoutAllowed(target, hosts, kind))
-            throw new CliError('INVALID_MANIFEST', `Plugin ${pluginId} writes outside src/shared/{models,modules,views}/ and src/infra/<name>/: ${target}`);
+            throw new CliError('INVALID_MANIFEST', `Plugin ${pluginId} writes outside src/shared/{models,services,modules,views,mail,locales}/ and src/infra/<name>/: ${target}`);
 }
 /** Installed entry paths from before D-0031 keep working; doctor reports them once. */
 export function legacyLayout(path, hosts = []) {
     return !layoutAllowed(path, hosts);
 }
+/**
+ * Source files older recipes wrote outside the "Files and folders" rule (the src root holds only
+ * main.ts and dokebi.generated.ts), mapped to where the current recipe writes them. Such a file
+ * keeps working where it is: doctor reports it as a LEGACY_LAYOUT warning that names the new
+ * place, and a re-run of the recipe keeps using the old file instead of writing a second copy.
+ * Moving it stays the developer's step because the file is user code (its relative imports and
+ * the import in src/main.ts change with it).
+ */
+export const MOVED_RECIPE_FILES = Object.freeze({
+    'src/site-worker.ts': 'src/infra/runtime/site-worker.ts',
+});

package/dist/log-writer-control.d.ts

@@ -28,6 +28,8 @@ export type ControlRequest = {
     op: 'stop';
     timeoutMs: number;
     force: boolean;
+} | {
+    op: 'reload';
 };
 /** The writer answered: its proven identity and its reply to the request. */
 export interface ControlReached {

package/dist/log-writer-control.js

@@ -13,10 +13,12 @@
 //   client → { challenge: C, answer: HMAC(token, 'dokebi-log-writer:client:' + W) }
 //   writer → { ok: false, code: 'UNAUTHORIZED' } and closes, or
 //            { ok: true, answer: HMAC(token, 'dokebi-log-writer:writer:' + C), writer, app }
-//   client → { op: 'status' } | { op: 'stop', timeoutMs, force }   (only after checking answer)
+//   client → { op: 'status' } | { op: 'stop', timeoutMs, force } | { op: 'reload' }
+//            (only after checking answer)
 //   writer → status: { ok: true, app: { pid, running } }
 //            stop:   { ok: true, stopped, forced, ms } | { ok: false, code: 'STOP_TIMEOUT', message }
-// Only `status` and `stop` exist. The writer closes the connection when it exits, so a client
+//            reload: { ok: true, signalled } (D-0154: SIGHUP to the app; it reads dokebi.yaml again)
+// Only `status`, `stop` and `reload` exist. The writer closes the connection when it exits, so a client
 // that asked for a stop knows the writer finished (its log closed) when the connection ends.
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { createConnection, createServer } from 'node:net';
@@ -26,8 +28,13 @@ import { debug, describeError, reportError } from './diagnostics.js';
 export const CONTROL_HOST = '127.0.0.1';
 const HELLO = 'dokebi-log-writer';
 const VERSION = 1;
-/** A longer line is not this protocol. */
+/** A longer line (in bytes, without its newline) is not this protocol. */
 const MAX_LINE = 4096;
+/** Messages (and their bytes) received but not yet read; the protocol needs one at a time. */
+const MAX_QUEUED = 2;
+const MAX_QUEUED_BYTES = MAX_QUEUED * MAX_LINE;
+const NEWLINE = 0x0a;
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
 /** An unauthenticated connection is closed after this long. */
 const HANDSHAKE_MS = 5000;
 /** The longest stop a client may ask for (one day). */
@@ -43,17 +50,30 @@ function matches(given, expected) {
     const b = Buffer.from(expected);
     return a.length === b.length && timingSafeEqual(a, b);
 }
-/** Newline-delimited JSON over a socket: read one message at a time, write messages. */
+/**
+ * Newline-delimited JSON over a socket: read one message at a time, write messages.
+ *
+ * ISSUE-0006 A05: the limits hold whatever the TCP chunking. Bytes are split on `\n` as they
+ * come; every line (complete or still open) is held to MAX_LINE bytes before it is decoded or
+ * parsed, and a line is taken only while the peer may send one: `expected` messages at first,
+ * then the `replies` each `send` asks for. Anything more is a protocol violation: the queue is
+ * dropped (nothing queued is acted on), next() rejects and the connection is destroyed.
+ */
 class LineSocket {
     socket;
-    #buffer = '';
+    /** The bytes of the line still open (no newline yet). */
+    #pending = [];
+    #pendingBytes = 0;
     #queue = [];
+    #queuedBytes = 0;
+    /** How many more messages the peer may send at this step of the protocol. */
+    #allowance;
     #waiting;
     #failure;
     closed;
-    constructor(socket) {
+    constructor(socket, expected) {
         this.socket = socket;
-        socket.setEncoding('utf8');
+        this.#allowance = expected;
         socket.on('data', (chunk) => this.#data(chunk));
         // Reported to whoever reads next (next() rejects); the socket closes after an error.
         socket.on('error', (error) => this.#fail(error));
@@ -61,28 +81,64 @@ class LineSocket {
         void this.closed.then(() => this.#fail(new Error('connection closed')));
     }
     #data(chunk) {
-        this.#buffer += chunk;
-        for (let end = this.#buffer.indexOf('\n'); end >= 0; end = this.#buffer.indexOf('\n')) {
-            const line = this.#buffer.slice(0, end);
-            this.#buffer = this.#buffer.slice(end + 1);
+        if (this.#failure)
+            return;
+        let start = 0;
+        for (let end = chunk.indexOf(NEWLINE); end >= 0; end = chunk.indexOf(NEWLINE, start)) {
+            const piece = chunk.subarray(start, end);
+            start = end + 1;
+            const bytes = this.#pendingBytes + piece.length;
+            if (!this.#acceptable(bytes))
+                return;
+            const line = this.#pendingBytes ? Buffer.concat([...this.#pending, piece]) : piece;
+            this.#pending = [];
+            this.#pendingBytes = 0;
+            if (this.#queue.length >= MAX_QUEUED || this.#queuedBytes + bytes > MAX_QUEUED_BYTES) {
+                this.#violation('too many messages waiting');
+                return;
+            }
             let message;
             try {
-                message = JSON.parse(line);
+                message = JSON.parse(UTF8.decode(line));
             }
             catch (error) {
-                this.#fail(new Error(`not a protocol message: ${describeError(error).split('\n')[0]}`));
-                this.socket.destroy();
+                this.#violation(`not a protocol message: ${describeError(error).split('\n')[0]}`);
                 return;
             }
-            this.#queue.push(message);
+            this.#allowance--;
+            this.#queue.push({ message, bytes });
+            this.#queuedBytes += bytes;
         }
-        if (this.#buffer.length > MAX_LINE) {
-            this.#fail(new Error(`a line longer than ${MAX_LINE} characters`));
-            this.socket.destroy();
-            return;
+        const rest = chunk.subarray(start);
+        if (rest.length) {
+            if (!this.#acceptable(this.#pendingBytes + rest.length))
+                return;
+            this.#pending.push(rest);
+            this.#pendingBytes += rest.length;
         }
         this.#deliver();
     }
+    /** A line of `bytes` so far may go on: a message is expected and the line is short enough. */
+    #acceptable(bytes) {
+        if (this.#allowance <= 0) {
+            this.#violation('a message the protocol does not expect at this step');
+            return false;
+        }
+        if (bytes > MAX_LINE) {
+            this.#violation(`a line longer than ${MAX_LINE} bytes`);
+            return false;
+        }
+        return true;
+    }
+    #violation(reason) {
+        debug('Control connection broke the protocol', { reason });
+        this.#queue = [];
+        this.#queuedBytes = 0;
+        this.#pending = [];
+        this.#pendingBytes = 0;
+        this.#fail(new Error(reason));
+        this.socket.destroy();
+    }
     #fail(error) {
         this.#failure ??= error;
         this.#deliver();
@@ -92,7 +148,13 @@ class LineSocket {
         if (!waiting || (!this.#queue.length && !this.#failure))
             return;
         this.#waiting = undefined;
-        waiting(this.#queue.length ? this.#queue.shift() : this.#failure);
+        const next = this.#queue.shift();
+        if (next) {
+            this.#queuedBytes -= next.bytes;
+            waiting(next.message);
+        }
+        else
+            waiting(this.#failure);
     }
     /** The next message; rejects when the connection fails or closes first, or after `ms`. */
     next(ms) {
@@ -113,7 +175,9 @@ class LineSocket {
             this.#deliver();
         });
     }
-    send(message) {
+    /** Sends `message`; the peer may then send `replies` messages (the protocol's next step). */
+    send(message, replies = 0) {
+        this.#allowance += replies;
         if (!this.socket.destroyed)
             this.socket.write(`${JSON.stringify(message)}\n`);
     }
@@ -178,7 +242,8 @@ export class ControlServer {
     #connection(socket) {
         this.#sockets.add(socket);
         socket.once('close', () => this.#sockets.delete(socket));
-        const lines = new LineSocket(socket);
+        // The client speaks only after the hello (which allows its proof).
+        const lines = new LineSocket(socket, 0);
         void this.#serve(lines).catch((error) => {
             // A client that broke the protocol or went silent: nothing was done for it.
             reportError('CONTROL_REQUEST_FAILED', 'A control request failed', error, 5000);
@@ -187,7 +252,7 @@ export class ControlServer {
     }
     async #serve(lines) {
         const challenge = randomBytes(24).toString('base64url');
-        lines.send({ hello: HELLO, version: VERSION, challenge });
+        lines.send({ hello: HELLO, version: VERSION, challenge }, 1);
         const hello = await lines.next(HANDSHAKE_MS);
         if (!matches(hello.answer, controlAnswer(this.token, 'client', challenge))) {
             debug('Control client refused: wrong instance proof');
@@ -208,13 +273,26 @@ export class ControlServer {
             answer: controlAnswer(this.token, 'writer', hello.challenge),
             writer: process.pid,
             app: { pid: app.pid, running: app.running() },
-        });
+        }, 1);
         const request = await lines.next(HANDSHAKE_MS);
         if (request.op === 'status') {
             lines.send({ ok: true, app: { pid: app.pid, running: app.running() } });
             lines.socket.end();
             return;
         }
+        if (request.op === 'reload') {
+            // D-0154: the CLI checked that the app reads dokebi.yaml again on SIGHUP before asking.
+            const running = app.running();
+            if (running)
+                app.signal('SIGHUP');
+            debug('Signalled the app to reload its configuration on a control request', {
+                pid: app.pid,
+                running,
+            });
+            lines.send({ ok: true, signalled: running });
+            lines.socket.end();
+            return;
+        }
         const timeoutMs = request.timeoutMs;
         if (request.op !== 'stop' ||
             !Number.isSafeInteger(timeoutMs) ||
@@ -266,7 +344,8 @@ export async function askLogWriter(port, token, request,
 stepMs = 3000) {
     const path = `${CONTROL_HOST}:${port}`;
     const socket = createConnection({ host: CONTROL_HOST, port });
-    const lines = new LineSocket(socket);
+    // The writer greets first: one message expected.
+    const lines = new LineSocket(socket, 1);
     const unreached = (reason) => {
         socket.destroy();
         debug('Log writer not reached', { path, reason });
@@ -291,7 +370,7 @@ stepMs = 3000) {
         if (hello.hello !== HELLO || typeof hello.challenge !== 'string')
             return unreached(`${path} is not a dokebi log writer`);
         const challenge = randomBytes(24).toString('base64url');
-        lines.send({ challenge, answer: controlAnswer(token, 'client', hello.challenge) });
+        lines.send({ challenge, answer: controlAnswer(token, 'client', hello.challenge) }, 1);
         const proof = await lines.next(stepMs);
         if (proof.code === 'NOT_READY')
             return unreached('the log writer has not started the app yet');
@@ -303,7 +382,7 @@ stepMs = 3000) {
         if (typeof app?.pid !== 'number' || typeof proof.writer !== 'number')
             return unreached('the log writer sent an unexpected answer');
         debug('Log writer proved the instance token', { path, writer: proof.writer, op: request.op });
-        lines.send(request);
+        lines.send(request, 1);
         const replyMs = request.op === 'stop' ? request.timeoutMs + (request.force ? 5000 : 0) + stepMs : stepMs;
         const reply = await lines.next(replyMs);
         return {