@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/orchestrator/orchestrator.service.js

@@ -11,7 +11,13 @@
  *
  * Classic mode:
  *   - child_process.fork() with manual exit handling (legacy compat)
- *   - Real CPU/memory metrics via pidusage
+ *
+ * Metrics for both modes come from one `ps -o pid=,rss=,%cpu=` call covering
+ * every managed pid — supervisor children and pool workers alike. This line
+ * used to say "real CPU/memory metrics via pidusage"; `pidusage` is not a
+ * dependency of this package and appears nowhere else in the source. The
+ * sentence outlived the code it described, in the one area where a stale
+ * claim is hardest to catch: metrics that are wrong still look like metrics.
  *
  * Architecture:
  *   pm.supervisor({ children: [{ process: bootstrap-process.js, ... }] })
@@ -21,18 +27,59 @@
  *     → Two Netron instances: PM management plane + app HTTP data plane
  */
 import fs from 'node:fs';
+import { readDeclaredConfig, withDeclaredConfig } from '../project/declared-config.js';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { PoolStrategy, SupervisionStrategy, } from '@omnitron-dev/titan-pm';
+import { PoolStrategy, SupervisionStrategy, ProcessLifecycleQueue, LifecyclePreempted, computeBackoff, isAlive, discoverManagedProcesses, } from '@omnitron-dev/titan-pm';
 import { EventEmitter } from '@omnitron-dev/eventemitter';
 import { AppHandle } from './app-handle.js';
+import { parsePsLine, parsePsBatch } from './ps-metrics.js';
 import { launchClassic } from './classic-launcher.js';
 import { resolveStartupOrder, resolveShutdownOrder } from './dependency-resolver.js';
 import { buildRestartPolicy } from '../supervisor/restart-policy.js';
+/**
+ * How long to wait for a pool worker to finish exposing its `@Service`
+ * classes before giving up on `topology.expose`. A worker reports ready
+ * before its Application starts, and exposure happens during start, so the
+ * gap is a real one — measured at ~7s for a worker that opens database
+ * connections first. The consumer that needs the service starts right after
+ * this returns, so the wait is paid once at boot and buys a feature that
+ * otherwise stays off until the next restart.
+ */
+/**
+ * `childName` is sometimes bare ('http') and sometimes already carries the app
+ * ('acme/dev/pricing/http'), depending on which supervisor path raised the
+ * event. Prefixing unconditionally produced
+ * `acme/dev/pricing/acme/dev/pricing/http` in the log file.
+ */
+function qualifyChildName(appName, childName) {
+    return childName.startsWith(`${appName}/`) || childName === appName
+        ? childName
+        : `${appName}/${childName}`;
+}
+const TOPOLOGY_EXPOSE_TIMEOUT_MS = 30_000;
+const TOPOLOGY_EXPOSE_POLL_MS = 250;
 import { ServiceRouter } from './service-router.js';
 import { loadBootstrapConfig, clearCacheFor } from './bootstrap-loader.js';
+/** Levels a pino logger accepts. A child is spawned with nothing else. */
+const PINO_LEVELS = new Set(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent']);
+/**
+ * Process-manager states in which a record no longer describes a live process.
+ *
+ * Read by `managerOwnedPids`, where the distinction decides whether a pid is
+ * protected from the janitor. Written as strings rather than imported from
+ * `ProcessStatus` because that export is a const object whose values are
+ * these same literals; the set has to hold values, not keys, and a typo here
+ * would silently protect a dead pid — so it is pinned by a test.
+ */
+const TERMINAL_PROCESS_STATUSES = new Set(['stopped', 'failed', 'crashed']);
 import { BuildService } from './build-service.js';
+import { execFile } from 'node:child_process';
 import { ProcessJanitor } from './process-janitor.js';
+import { addressInUse, holderCommand, parseHolders, explainConflict } from './port-conflict.js';
+import { collectOwnedPids } from './owned-pids.js';
+import { combineProcessHealth, notRunningHealth, poolHealth } from './app-health.js';
+import { combineProcessTraffic } from './app-traffic.js';
 import { CLI_VERSION } from '../config/defaults.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve bootstrap-process path — .ts in dev (tsx), .js when compiled
@@ -63,15 +110,77 @@ function mapStrategy(strategy) {
  * stack mode + bare-name RPC paths can be deduplicated.
  *
  * Examples:
- *   effectiveAppName('omni/dev/paysys') === 'paysys'
- *   effectiveAppName('paysys')           === 'paysys'
- *   effectiveAppName('a/b/c/paysys')     === 'paysys'  (last segment)
+ *   effectiveAppName('omni/dev/payments') === 'payments'
+ *   effectiveAppName('payments')           === 'payments'
+ *   effectiveAppName('a/b/c/payments')     === 'payments'  (last segment)
  */
-function effectiveAppName(key) {
+export function effectiveAppName(key) {
     const idx = key.lastIndexOf('/');
     return idx >= 0 ? key.slice(idx + 1) : key;
 }
+/**
+ * Auto-promote a bare `entry.name` to canonical `${project}/${stack}/${name}`
+ * form when the env carries OMNITRON_PROJECT + OMNITRON_STACK. The stack-mode
+ * boot path (ProjectService.startStack) already prefixes the name explicitly;
+ * this helper closes every other entry point that could otherwise register a
+ * bare-name handle which then becomes invisible to the stack-prefix-based
+ * UI lookup (ProjectService.toStackInfo filters on `${project}/${stack}/`).
+ *
+ * Idempotent: if the entry already looks namespaced (or env lacks the keys),
+ * the input is returned unchanged. An entry qualified under a DIFFERENT
+ * project/stack is preserved too — that's operator intent (cross-project
+ * administrative run), not a bug.
+ */
+export function ensureNamespacedEntry(entry) {
+    const project = entry.env?.['OMNITRON_PROJECT'];
+    const stack = entry.env?.['OMNITRON_STACK'];
+    if (!project || !stack)
+        return entry;
+    const canonicalPrefix = `${project}/${stack}/`;
+    if (entry.name.startsWith(canonicalPrefix))
+        return entry;
+    if (entry.name.includes('/'))
+        return entry;
+    return { ...entry, name: `${canonicalPrefix}${entry.name}` };
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Startup budget for a child process that declares none of its own.
+ *
+ * There were TWO of these and they disagreed — `?? 60_000` on the pooled path
+ * and `?? 30_000` on the single-process path — and, worse, the pooled one did
+ * not consult `entry.startupTimeout` at all. So an operator who set
+ * `startupTimeout: 120_000` on an app had it honoured for the app and
+ * SILENTLY IGNORED for its child processes, which kept 60 seconds and could
+ * not be given more by any setting.
+ *
+ * Measured on this host: an app whose own successful boot takes 120.6 seconds
+ * carried a 120 s budget, and its `deposit-worker` child — a deposit scanner
+ * — stayed `stopped` while the app itself came up. Two copies of one decision,
+ * one of which discarded the only knob an operator has.
+ *
+ * 60 s rather than 30 s, for the reason the project's own config already
+ * writes down: an over-long ceiling costs a slower failure report, a short one
+ * costs the whole stack.
+ */
+const DEFAULT_CHILD_STARTUP_TIMEOUT = 60_000;
+/**
+ * Deadline for an RPC the daemon makes to a child it supervises.
+ *
+ * A call across this connection is WORK — aggregate five minutes of candles,
+ * answer a health probe that touches a pool, hand back metrics — not a wire
+ * request, and netron's default (5000 ms) is sized for the latter. The pool
+ * path stated this number and the single-child path stated nothing, so a
+ * client built for a single child fell back to that default: measured, 94
+ * timeouts «after 5000ms» in the daemon log, every one on
+ * `callExposedService`, which lives on exactly those single children.
+ *
+ * It belongs here rather than in titan-pm because the orchestrator is what
+ * knows the nature of the work; the library's own fallback is 30 s
+ * (`process-pool.ts:212`) and applies when a caller states nothing — which,
+ * after this, no caller here does.
+ */
+const CHILD_REQUEST_TIMEOUT = 120_000;
 export class OrchestratorService extends EventEmitter {
     logger;
     pm;
@@ -88,6 +197,30 @@ export class OrchestratorService extends EventEmitter {
      * for the same name isn't permanently locked out.
      */
     startingApps = new Map();
+    /**
+     * Per-app async serial-execution queue covering start / stop / restart
+     * / crash-restart-timer (P0-E + P0-I + P2-B in the audit). Pre-this-
+     * queue each path had its own coalescer:
+     *   - startingApps: same-name start coalescing only — `stopApp` did
+     *     NOT consult it, so stop racing in-flight start left an orphan
+     *     supervisor when stop arrived before start wrote childProcess.
+     *   - restartCoalescer: same-name restart coalescing; independent of
+     *     stop+start.
+     *   - handleClassicCrash setTimeout: a raw timer that could fire
+     *     during the `await stopChild(...)` window and spawn a zombie
+     *     against an app the operator just stopped.
+     * The queue collapses all four into one primitive ordered by
+     * priority (stop > restart > start > crash-restart). The same-key
+     * mutex means stop ALWAYS observes a completed start, and an
+     * explicit stop ALWAYS preempts a pending crash-restart timer.
+     */
+    lifecycleQueue = new ProcessLifecycleQueue();
+    /**
+     * Pending post-escalation cool-down timers, keyed by app name.
+     * Held here rather than inside a lifecycle-queue slot so that a
+     * crashed app still answers operator commands while it waits.
+     */
+    coolDownTimers = new Map();
     config = null;
     cwd;
     metricsTimer = null;
@@ -96,6 +229,56 @@ export class OrchestratorService extends EventEmitter {
     devMode = false;
     /** esbuild bundling pipeline — pre-bundles TS entry points for child processes */
     buildService = null;
+    watchDisabled = false;
+    watchSelection = null;
+    bootstrapSources = new Map();
+    allowsWatch(entry) {
+        return this.devMode && !this.watchDisabled && entry.watch !== false &&
+            (!this.watchSelection || this.watchSelection.has(entry.name));
+    }
+    /** One policy for both fs.watch and esbuild; disabling does not stop apps. */
+    async setWatchMode(enabled, apps) {
+        this.watchDisabled = !enabled;
+        this.watchSelection = apps ? new Set(apps.map((name) => this.resolveAppName(name) ?? name)) : null;
+        for (const [name, state] of this.restartCoalescer) {
+            if (!enabled || !this.handles.get(name) || !this.allowsWatch(this.handles.get(name).entry))
+                state.watchSerial = 0;
+        }
+        await Promise.all([...this.bootstrapSources.keys()].map((name) => this.syncBootstrapWatch(name)));
+    }
+    getBuildWatchedApps() {
+        return [...this.bootstrapSources].filter(([name]) => this.buildService?.isWatching(name))
+            .map(([name, source]) => ({ name, directory: path.dirname(source.path) }));
+    }
+    async syncBootstrapWatch(name) {
+        const source = this.bootstrapSources.get(name);
+        const entry = this.handles.get(name)?.entry;
+        if (!this.buildService || !source)
+            return;
+        if (!entry || !this.allowsWatch(entry) || !entry.bootstrap ||
+            path.resolve(entry.cwd ?? this.cwd, entry.bootstrap) !== source.path) {
+            const state = this.restartCoalescer.get(name);
+            if (state)
+                state.watchSerial = 0;
+            await this.buildService.unwatchApp(name);
+            return;
+        }
+        if (this.buildService.isWatching(name))
+            return;
+        await this.buildService.watchApp(name, source.path, source.definition, () => {
+            void this.restartAfterChange(name).catch((error) => {
+                this.logger.error({ app: name, error: error.message }, 'Restart after source change failed');
+            });
+        });
+    }
+    /** Automatic triggers remain revocable while queued; manual restart is independent. */
+    async restartAfterChange(name) {
+        const canonical = this.resolveAppName(name) ?? name;
+        const handle = this.handles.get(canonical);
+        if (!handle || !this.allowsWatch(handle.entry))
+            return handle;
+        return this.restartAppCoalesced(canonical, true, 'watch');
+    }
     /** Cached build results per app name */
     buildResults = new Map();
     /**
@@ -129,10 +312,23 @@ export class OrchestratorService extends EventEmitter {
      */
     static POST_ONLINE_COOLDOWN_MS = 3_000;
     /**
-     * Orphan-process reaper. Lazily created on first `startAll` so unit
-     * tests that hit `startApp` directly don't get a periodic timer.
+     * Orphan-process reaper. Lazily created on first reconcile so unit
+     * tests that hit `startApp` directly don't get a periodic timer
+     * until the first real reconcile runs (which they bypass by
+     * stubbing `bootReconciled = true`).
      */
     janitor = null;
+    /**
+     * One-shot guard for cold-start reconciliation. T#63 — every code
+     * path that lands an app on this orchestrator goes through
+     * `ensureBootReconciled()`, regardless of whether the entry-point
+     * is `startAll` (daemon-config) or `startApp` (project/stack
+     * mode). Pre-T#63 the cold-start sweep only fired inside
+     * `startAll`, so project-mode boots silently inherited orphans
+     * from the previous daemon generation.
+     */
+    bootReconciled = false;
+    bootReconcilePromise = null;
     /** Daemon's Netron instance for native service routing */
     daemonNetron = null;
     /** Daemon Unix socket path for child-to-daemon Netron connections */
@@ -220,13 +416,117 @@ export class OrchestratorService extends EventEmitter {
     // ============================================================================
     // Lifecycle
     // ============================================================================
+    /**
+     * Refresh the orchestrator's view of the ecosystem config. Called
+     * from `daemon.reloadConfig` so a subsequent `restartApp` reads the
+     * new entry definition (mode, env, dependsOn, restart policy)
+     * instead of the stale copy captured at first `startAll`. Pre-fix
+     * the two refs diverged silently after every reload — operators
+     * editing ecosystem.config.ts and running `omnitron reload`
+     * believed the daemon picked up the changes; in fact only daemon's
+     * own RPC service did, and individual app restarts kept running
+     * against the pre-reload definition until the daemon itself
+     * restarted. P0-G in the audit.
+     */
+    setConfig(config) {
+        this.config = config;
+        // Metrics polling is armed here rather than in `startAll` alone.
+        //
+        // It used to run only from `startAll`, which is the `omnitron start`
+        // path. Apps brought up any other way — `stack start`, a single
+        // `omnitron start <app>`, or the daemon resuming a stack at boot — were
+        // never sampled, so `omnitron list`, `status` and the console's app
+        // cards reported cpu 0 / memory 0 for processes that were serving
+        // traffic. Observed live: six apps online, every one showing 0 while
+        // `ps` reported ~105 MB RSS apiece.
+        //
+        // `setConfig` is the one point every path passes through, and the call
+        // is idempotent — an existing timer is cleared first.
+        this.ensureMetricsPolling();
+    }
+    /**
+     * Start metrics sampling if it is not already running.
+     *
+     * Called from every path that can produce a managed process, so no app can
+     * end up unsampled because of how it was started.
+     */
+    ensureMetricsPolling() {
+        if (this.metricsTimer)
+            return;
+        this.startMetricsPolling(this.config?.monitoring?.metrics?.interval ?? 5_000);
+    }
+    /**
+     * One-shot cold-start reconciliation: discover pre-existing managed
+     * processes, reap fork-workers left over from a previous daemon
+     * generation, and arm the periodic janitor sweep. Idempotent —
+     * concurrent callers join the in-flight promise; subsequent calls
+     * after success are no-ops.
+     *
+     * Called from BOTH `startAll` (top-level daemon-config boot) and
+     * `startApp` (project/stack mode boot), so every code path that
+     * lands an app on this orchestrator runs the cleanup. Pre-T#63 the
+     * cold-start sweep was gated on `startAll` and never ran in
+     * project mode, so an orphan from a previous daemon survived
+     * silently and held the listen port hostage from its successor.
+     */
+    async ensureBootReconciled(config) {
+        if (this.bootReconciled)
+            return;
+        if (this.bootReconcilePromise) {
+            await this.bootReconcilePromise;
+            return;
+        }
+        this.bootReconcilePromise = (async () => {
+            // Discovery: surface OMNITRON_MANAGED-tagged processes that match
+            // a configured app so the operator can see what's about to be
+            // reaped (or — once the ChildContract handshake lands — adopted).
+            // P2-A in the audit.
+            try {
+                const discovered = discoverManagedProcesses();
+                const adopted = [];
+                const knownApps = new Set(config?.apps.map((a) => a.name) ?? []);
+                for (const proc of discovered) {
+                    if (proc.ppid === process.pid)
+                        continue; // our own freshly-spawned child
+                    const fqn = proc.fullyQualifiedName;
+                    const bare = proc.appName;
+                    if (knownApps.has(fqn) || knownApps.has(bare)) {
+                        adopted.push(`${fqn}#${proc.pid}`);
+                    }
+                }
+                if (adopted.length > 0) {
+                    this.logger.warn({ discovered: adopted.length, apps: adopted }, 'Found pre-existing managed processes — they will be reaped by the janitor in 60s unless adopted');
+                }
+            }
+            catch (err) {
+                this.logger.debug({ err: err.message }, 'Process discovery failed — proceeding without reconcile');
+            }
+            // Reap any fork-workers left over from a previous daemon BEFORE
+            // launching apps. Without this, a hard-killed daemon's children
+            // are still alive (now reparented to init); they hold DB
+            // connections and listen ports that the new apps will fight
+            // for. The reap is bounded by `gracefulMs` (default 3s).
+            await this.ensureJanitor().coldStartSweep();
+            // Arm the periodic sweep so runtime leaks from partially-failed
+            // restart cycles (esbuild-rebuild → spawn-fail → orphan) get
+            // collected on every interval.
+            this.ensureJanitor().start();
+        })();
+        try {
+            await this.bootReconcilePromise;
+            this.bootReconciled = true;
+        }
+        finally {
+            this.bootReconcilePromise = null;
+        }
+    }
     async startAll(config) {
         this.config = config;
-        // Reap any fork-workers left over from a previous daemon BEFORE
-        // launching apps. Without this, a hard-killed daemon's children
-        // are still alive (now adopted by init); they hold DB connections
-        // and sockets that the new apps will fight for.
-        await this.ensureJanitor().coldStartSweep();
+        // Cold-start orphan reap + periodic janitor arming. Idempotent —
+        // safe to call on every boot path. Project-mode flows that call
+        // `startApp` directly trigger the same one-shot reconcile, so
+        // every boot path lands in the same post-condition. (T#63)
+        await this.ensureBootReconciled(config);
         // Dependency-aware skip: if app A fails to start, every app that
         // declares A in `dependsOn` (transitively) is skipped instead of
         // attempted. Without this, a downstream app would launch, fail to
@@ -255,10 +555,8 @@ export class OrchestratorService extends EventEmitter {
         if (failed.size > 0 || blocked.size > 0) {
             this.logger.warn({ failed: [...failed], blocked: [...blocked] }, 'Startup completed with failures — some apps did not launch');
         }
-        // Periodic sweep handles runtime leaks from partially-failed
-        // restart cycles (esbuild-rebuild → spawn-fail → orphan).
-        this.ensureJanitor().start();
-        this.startMetricsPolling(config.monitoring.metrics.interval);
+        // Periodic sweep was armed by `ensureBootReconciled` above, and metrics
+        // polling by `setConfig` — no second call needed for either.
         this.persistState();
     }
     /**
@@ -276,44 +574,143 @@ export class OrchestratorService extends EventEmitter {
         return this.janitor;
     }
     /**
-     * Walk every live handle's supervisor children and collect the OS
-     * pids the orchestrator currently considers ours. Cheap — called
-     * every janitor sweep.
+     * Every OS pid the orchestrator currently considers ours. Cheap — called
+     * on every janitor sweep, and the janitor kills whatever this set omits.
+     *
+     * The rule itself lives in `owned-pids.ts`, where it can be tested: the
+     * janitor's own tests supply this set as a fixture, so they could never
+     * catch it being incomplete — and it was, by a whole class of process.
      */
+    /**
+     * Who is holding the port an app could not bind, in one sentence.
+     *
+     * Called where a start or restart failed, because that is the moment the
+     * answer is worth having and the moment nobody has it: the error names the
+     * address and never the holder. Measured on this daemon — four
+     * `EADDRINUSE` failures on 3005 in thirty-one seconds, `omnitron list`
+     * reporting the app crashed with no pid, and the port held the whole time
+     * by a child of this very daemon that nothing in its records claimed.
+     *
+     * Returns null when the failure was not a port clash, and says so out loud
+     * when it could not read the machine — a reading that failed and a port
+     * nobody holds are different findings.
+     */
+    async explainPortConflict(message) {
+        const address = addressInUse(message);
+        if (!address)
+            return null;
+        const { file, args } = holderCommand(address.port, process.platform);
+        let output;
+        try {
+            output = await new Promise((resolve, reject) => {
+                execFile(file, args, { encoding: 'utf8', timeout: 5_000 }, (err, stdout) => {
+                    // `ss` and `lsof` both exit non-zero when nothing matches, which is
+                    // an answer rather than a failure; the empty stdout carries it.
+                    if (err && !stdout)
+                        reject(err);
+                    else
+                        resolve(stdout);
+                });
+            });
+        }
+        catch (err) {
+            return `could not read who holds port ${address.port}: ${file} ${err.message}`;
+        }
+        const holders = parseHolders(output, process.platform);
+        // One `ps` for the parents, before deciding: the decision is pure and
+        // takes the answers, so that it can be tested without a machine.
+        const parents = new Map();
+        for (const holder of holders) {
+            const ppid = await this.parentOf(holder.pid);
+            if (ppid !== undefined)
+                parents.set(holder.pid, ppid);
+        }
+        const verdict = explainConflict({
+            port: address.port,
+            holders,
+            parentOf: (pid) => parents.get(pid),
+            daemonPid: process.pid,
+            owned: this.collectOwnedPids(),
+        });
+        return verdict.because;
+    }
+    /** The parent of one process, or undefined when it cannot be read. */
+    async parentOf(pid) {
+        try {
+            const out = await new Promise((resolve, reject) => {
+                execFile('ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf8', timeout: 5_000 }, (err, stdout) => {
+                    if (err && !stdout)
+                        reject(err);
+                    else
+                        resolve(stdout);
+                });
+            });
+            const parsed = Number(out.trim());
+            return Number.isInteger(parsed) ? parsed : undefined;
+        }
+        catch {
+            // A process that exited between the two readings has no parent to
+            // report, and that is not an error worth a line of its own — the
+            // verdict already says the holder was gone.
+            return undefined;
+        }
+    }
     collectOwnedPids() {
-        const owned = new Set();
-        for (const handle of this.handles.values()) {
-            const supervisor = handle.supervisor;
-            if (!supervisor)
+        return collectOwnedPids(this.handles.values(), (workerId) => this.pm.getWorkerHandle(workerId)?.pid, this.managerOwnedPids());
+    }
+    /**
+     * Every pid the process manager currently vouches for.
+     *
+     * Two windows, and a process is only safe if both are asked. `getForkedPids`
+     * holds a claim from `fork()` until `spawn()` resolves and releases it —
+     * after that its own docstring says "the WorkerHandle registry is the
+     * authority". `listProcesses()` IS that registry, and it is the only source
+     * that answers for a process the orchestrator did not start: the daemon's
+     * system workers go through this same manager but belong to no app handle,
+     * so walking `this.handles` can never see them.
+     *
+     * Terminal records are excluded deliberately. They keep the pid they had,
+     * the OS reuses pids, and a stale one here would vouch for exactly the
+     * leaked worker the janitor exists to reap.
+     */
+    managerOwnedPids() {
+        const pids = [...(this.pm.getForkedPids?.() ?? [])];
+        for (const info of this.pm.listProcesses?.() ?? []) {
+            if (typeof info.pid !== 'number')
                 continue;
-            for (const childName of supervisor.getChildNames()) {
-                const processId = supervisor.getChildProcessId(childName);
-                if (!processId)
-                    continue;
-                const workerHandle = this.pm.getWorkerHandle(processId);
-                const pid = workerHandle?.pid;
-                if (typeof pid === 'number')
-                    owned.add(pid);
-            }
+            if (TERMINAL_PROCESS_STATUSES.has(info.status))
+                continue;
+            pids.push(info.pid);
         }
-        return owned;
+        return pids;
     }
     async startApp(entry, config) {
-        // T#57: coalesce concurrent calls for the same app name. Without
-        // this, two near-simultaneous `startApp({ name: 'main' })` calls
-        // both see `this.handles.get('main')` as undefined-or-not-online
-        // (the first one's handle is in status='starting'), both fall
-        // through to `launchBootstrapMode`, and we spawn two parallel
-        // worker pools competing for the same port. Promise coalescing
-        // — return the in-flight promise to the second caller — gives
-        // both callers the same handle and ensures only one launch
-        // actually runs.
+        // T#63: run the one-shot cold-start reconcile (orphan reap +
+        // janitor arming) before ANY app spawns. Project-mode boots flow
+        // through `projectService.startStack → orchestrator.startApp`
+        // and historically bypassed the reap entirely — a previous
+        // daemon's children (now reparented to init) kept their HTTP
+        // listen ports and the fresh child failed to bind silently.
+        // No-op after first call thanks to `bootReconciled`.
+        await this.ensureBootReconciled(config);
+        // Defensive auto-namespacing — promotes a bare entry.name to the
+        // canonical `${project}/${stack}/${name}` form when the env carries
+        // OMNITRON_PROJECT + OMNITRON_STACK. Catches every code path that
+        // bypasses ProjectService.startStack:
+        //   - direct CLI `omnitron start <name>` (no stack context)
+        //   - legacy ecosystem configs without per-app namespace
+        //   - daemon startAll() flows over a not-yet-namespaced config
+        entry = ensureNamespacedEntry(entry);
         const inflight = this.startingApps.get(entry.name);
         if (inflight) {
             this.logger.debug({ app: entry.name }, 'Coalescing concurrent startApp into in-flight launch (T#57)');
             return inflight;
         }
-        const promise = this.startAppInternal(entry, config).finally(() => {
+        // Serialise against stop/restart for the same app via the
+        // lifecycle queue. A stopApp arriving while this start is queued
+        // (or in-flight) now waits its turn instead of racing through
+        // and leaving an orphan supervisor.
+        const promise = this.lifecycleQueue.enqueue(entry.name, 'start', () => this.startAppInternal(entry, config)).finally(() => {
             this.startingApps.delete(entry.name);
         });
         this.startingApps.set(entry.name, promise);
@@ -339,17 +736,44 @@ export class OrchestratorService extends EventEmitter {
         //   - exact key already exists, online   → return it (idempotent)
         //   - exact key already exists, not online → fall through and re-launch
         //     under the same key
-        //   - DIFFERENT key with the same effective short name → reject:
-        //     operator should restart by canonical name, not register an
-        //     alias.
+        //   - different fully qualified keys are distinct apps and coexist
+        //   - bare/qualified keys with the same effective short name:
+        //       - new is MORE specific (namespaced) and existing is bare → stop
+        //         the bare one and re-launch under the namespaced key. Without
+        //         this, a boot-race where bare-name auto-start beats the
+        //         project/stack flow strands the app under the wrong key and
+        //         webapp/CLI lookups by namespaced key see it as stopped.
+        //       - new is LESS-or-equally specific → refuse: operator should
+        //         restart by canonical name, not register an alias.
         const effective = effectiveAppName(entry.name);
+        const newIsNamespaced = entry.name.includes('/');
+        if (!newIsNamespaced && [...this.handles.keys()].filter(key => key.includes('/') && effectiveAppName(key) === effective).length > 1) {
+            throw new Error(`Ambiguous app name '${entry.name}'; use its full project/stack/app identity`);
+        }
         for (const [key, h] of this.handles) {
             if (key === entry.name)
                 continue;
             if (effectiveAppName(key) !== effective)
                 continue;
-            // Same effective app under a different key.
+            const existingIsNamespaced = key.includes('/');
+            // Qualified identities are separate deployments, even when their basename matches.
+            if (newIsNamespaced && existingIsNamespaced)
+                continue;
+            // A bare alias may still refer to the one qualified deployment.
             if (h.status === 'online') {
+                if (newIsNamespaced && !existingIsNamespaced) {
+                    this.logger.info({ stale: key, replacing_with: entry.name, effective }, 'Stopping bare-name handle to re-register under namespaced key');
+                    try {
+                        await this.stopApp(key);
+                    }
+                    catch (err) {
+                        this.logger.warn({ stale: key, error: err.message }, 'stopApp during dedup failed — clearing handle anyway');
+                    }
+                    this.handles.delete(key);
+                    if (key !== entry.name)
+                        this.metricsBridge?.evictApp(key);
+                    continue;
+                }
                 this.logger.warn({ existing: key, attempted: entry.name, effective }, 'App already running under a canonical name — refusing duplicate registration');
                 return h;
             }
@@ -357,6 +781,12 @@ export class OrchestratorService extends EventEmitter {
             // failed previous launch doesn't permanently block the canonical
             // form.
             this.logger.info({ stale: key, replacing_with: entry.name, effective }, 'Replacing stale duplicate handle');
+            // The handle is errored or stopped, so `stopApp` never ran for it and
+            // its services are still registered on the daemon's Netron. Dropping the
+            // handle here is the last moment anything knows they exist — or that its
+            // processes still run: an errored app's other children and its pools.
+            await this.releaseExposedServices(h);
+            await this.tearDownProcesses(h);
             this.handles.delete(key);
             // Drop any metrics that were collected under the stale alias so it
             // doesn't haunt future snapshots as a ghost offline app.
@@ -368,9 +798,40 @@ export class OrchestratorService extends EventEmitter {
             this.logger.warn({ app: entry.name }, 'App already running');
             return existing;
         }
+        // A handle that is not online may still run processes. A crash restart and
+        // a cool-down recovery only flip its status before coming here; one child
+        // crashing leaves its siblings — the server among them — up; and its pools
+        // were never any supervisor's to stop. Stopped before the new handle
+        // starts, or the new one finds its own predecessor on its port: on
+        // sample/test (2026-09-25) payments's crash restarts failed five times on
+        // `EADDRINUSE :3004`, «held by … a child this daemon still accounts for».
+        if (existing) {
+            await this.releaseExposedServices(existing);
+            await this.tearDownProcesses(existing);
+        }
         const mode = entry.bootstrap ? 'bootstrap' : 'classic';
         const handle = new AppHandle(entry, mode);
+        // The restart budget belongs to the APP, not to this handle instance.
+        // Every start replaces the handle, so a counter that starts at zero here
+        // can never reach `maxRestarts` — which made the budget, the escalation
+        // and the cool-down unreachable even once the restart itself worked. The
+        // window is enforced by the policy, not by forgetting.
+        if (existing)
+            handle.restarts = existing.restarts;
         this.handles.set(entry.name, handle);
+        // Arm metrics sampling here — the one place an app enters the registry.
+        //
+        // It used to be armed only from `startAll` (the `omnitron start` path).
+        // Anything else — `stack start`, a single `omnitron start <app>`, the
+        // daemon resuming a stack at boot — was never sampled, so `list`,
+        // `status` and the console's app cards reported cpu 0 / memory 0 for
+        // processes serving traffic. Observed: six apps online, every one at
+        // zero, while `ps` showed ~105 MB RSS apiece.
+        //
+        // `setConfig` looked like the right seam but is only called on config
+        // RELOAD, so it never fired on a normal start. This is the seam that
+        // actually covers every path. Idempotent: re-arming replaces the timer.
+        this.ensureMetricsPolling();
         this.logger.info({ app: entry.name, mode }, 'Starting app');
         try {
             if (mode === 'classic') {
@@ -379,47 +840,115 @@ export class OrchestratorService extends EventEmitter {
             else {
                 await this.launchBootstrapMode(entry, handle, cfg);
             }
-            this.logger.info({ app: entry.name, pid: handle.pid, mode }, 'App started');
+            // «App started» only for an app that is. It was logged in the same
+            // millisecond as a child's «Process failed to start», for an app whose
+            // processes never all came up.
+            if (handle.status === 'online') {
+                this.logger.info({ app: entry.name, pid: handle.pid, mode }, 'App started');
+            }
+            else {
+                this.logger.error({ app: entry.name, status: handle.status, mode }, 'App did not come up — not every declared process started');
+            }
             this.persistState();
             return handle;
         }
         catch (err) {
+            // `errored` rather than `crashed` is the right REPORT — the app never
+            // ran. It was also, until now, the end of the story: `'errored'` is read
+            // by no code in this repository outside formatters, `status` and a
+            // metrics label, so a start that failed was never attempted again. One
+            // try, then errored until a human noticed.
+            //
+            // That asymmetry is backwards. A failure to start is MORE likely to be
+            // transient than a crash after a successful boot — a dependency still
+            // coming up, a disk still cold, a machine briefly loaded. Six bootstrap
+            // apps here timed out at `config:loading` under a load average of 149
+            // and stayed down after the load passed, because nothing asked again.
+            //
+            // The counter is bumped by hand because `markErrored()` deliberately
+            // does not (an app that never ran has not "restarted"), and without it
+            // the budget below can never trip and the retry would be unbounded.
             handle.markErrored();
+            handle.restarts++;
             this.persistState();
+            this.scheduleRecovery(entry, handle, cfg);
             throw err;
         }
     }
-    async stopApp(name, force = false, timeout = 10_000) {
-        const canonical = this.resolveAppName(name) ?? name;
-        const handle = this.handles.get(canonical);
-        if (!handle || handle.status === 'stopped')
-            return;
-        handle.markStopping();
-        // Unexpose topology services from daemon Netron before stopping processes
-        if (handle.serviceRouter) {
-            try {
-                for (const svcName of handle.serviceRouter.getServiceNames()) {
-                    await handle.serviceRouter.unexposeService(svcName);
-                }
+    /**
+     * Everything a handle still runs, stopped: its supervisor's children (or its
+     * classic child process) AND its topology pools.
+     *
+     * The pools were missed. A pool's workers are not the supervisor's children
+     * — they are the daemon's, siblings of the server, recorded only in
+     * `topologyPools` — so `supervisor.stop()` never reached them, and nothing
+     * in the orchestrator destroyed a pool: only the daemon's own shutdown did.
+     * Every restart of an app with `instances > 1` left the previous workers
+     * running. On sample/test (2026-09-25): quotes's `ohlcv-aggregator` and
+     * storage's `transform` in three generations at once.
+     *
+     * The pools go even when the supervisor's stop throws: a stop that failed
+     * half-way must not also leave the half nobody asked about.
+     */
+    async tearDownProcesses(handle, force = false, timeout = 10_000) {
+        try {
+            if (handle.mode === 'bootstrap' && handle.supervisor) {
+                await handle.supervisor.stop();
             }
-            catch {
-                // Best-effort cleanup
+            else if (handle.childProcess) {
+                await this.stopChildProcess(handle, force, timeout);
+            }
+        }
+        finally {
+            for (const [name, pool] of handle.topologyPools) {
+                try {
+                    await pool.destroy();
+                }
+                catch (err) {
+                    this.logger.warn({ app: handle.name, pool: name, error: err.message }, 'Destroying a topology pool failed — its workers may still run');
+                }
             }
-            handle.serviceRouter = null;
+            handle.topologyPools.clear();
         }
-        if (handle.mode === 'bootstrap' && handle.supervisor) {
-            await handle.supervisor.stop();
+    }
+    /**
+     * Give back every service an app exposed on the daemon's Netron.
+     *
+     * A registration outlives the process behind it: the daemon keeps answering
+     * `queryInterface` with the full method list and every call through the name
+     * fails at the socket. `takeOverExisting` rescues a name the next launch
+     * re-exposes; one it does not stays advertised for the life of the daemon.
+     */
+    async releaseExposedServices(handle) {
+        if (!handle.serviceRouter)
+            return;
+        try {
+            await handle.serviceRouter.releaseAll();
         }
-        else if (handle.childProcess) {
-            await this.stopChildProcess(handle, force, timeout);
+        catch (err) {
+            this.logger.warn({ app: handle.name, error: err.message }, 'Releasing exposed services failed — the daemon may still advertise them');
         }
-        handle.markStopped();
-        this.persistState();
-        this.logger.info({ app: name }, 'App stopped');
+        handle.serviceRouter = null;
+    }
+    async stopApp(name, force = false, timeout = 10_000) {
+        const canonical = this.resolveAppName(name) ?? name;
+        // Outside the queue on purpose: the operator's intent lands the
+        // moment the command arrives, not whenever the queue drains.
+        this.clearCoolDown(canonical);
+        return this.lifecycleQueue.enqueue(canonical, 'stop', async () => {
+            const handle = this.handles.get(canonical);
+            if (!handle || handle.status === 'stopped')
+                return;
+            handle.markStopping();
+            // Unexpose topology services from daemon Netron before stopping processes
+            await this.releaseExposedServices(handle);
+            await this.tearDownProcesses(handle, force, timeout);
+            handle.markStopped();
+            this.persistState();
+            this.logger.info({ app: name }, 'App stopped');
+        });
     }
     async stopAll(force = false) {
-        if (!this.config)
-            return 0;
         if (this.metricsTimer) {
             clearInterval(this.metricsTimer);
             this.metricsTimer = null;
@@ -432,7 +961,34 @@ export class OrchestratorService extends EventEmitter {
         let count = 0;
         // When force=true (daemon shutdown), use short timeout per app (3s SIGTERM, then SIGKILL)
         const perAppTimeout = force ? 3_000 : 10_000;
-        for (const batch of resolveShutdownOrder(this.config.apps)) {
+        // Registered projects need not belong to the daemon's root ecosystem.
+        // Ownership is defined by handles, not by whichever config booted first.
+        // Drain admitted starts before taking the shutdown graph snapshot.
+        await Promise.allSettled([...this.startingApps.values()]);
+        const entries = [...this.handles.values()].map((handle) => handle.entry);
+        const names = new Set(entries.map((entry) => entry.name));
+        const graph = entries.map((entry) => {
+            const scope = entry.name.slice(0, entry.name.lastIndexOf('/') + 1);
+            return {
+                ...entry,
+                dependsOn: (entry.dependsOn ?? []).flatMap((dependency) => {
+                    const name = !dependency.includes('/') && names.has(scope + dependency)
+                        ? scope + dependency : dependency;
+                    // A dependency never started here has no owned process to stop.
+                    return names.has(name) ? [name] : [];
+                }),
+            };
+        });
+        let batches;
+        try {
+            batches = resolveShutdownOrder(graph);
+        }
+        catch (error) {
+            // Invalid reconfiguration must not turn shutdown into leaked children.
+            this.logger.error({ error: error.message }, 'Invalid shutdown graph; stopping every owned app');
+            batches = [entries];
+        }
+        for (const batch of batches) {
             await Promise.all(batch.map(async (entry) => {
                 try {
                     await this.stopApp(entry.name, force, perAppTimeout);
@@ -458,8 +1014,28 @@ export class OrchestratorService extends EventEmitter {
             this.buildService = null;
         }
         this.buildResults.clear();
+        this.bootstrapSources.clear();
         return count;
     }
+    /**
+     * Give a supervised app the definition its next start will use — its
+     * environment, its command. The running process is not touched; the next
+     * `restartApp` starts from this. `false` when nothing by that name runs
+     * here. See `AppHandle.redefine`.
+     */
+    async redefineApp(name, entry) {
+        const handle = this.handles.get(this.resolveAppName(name) ?? name);
+        if (!handle)
+            return false;
+        handle.redefine(entry);
+        if (!this.allowsWatch(entry)) {
+            const state = this.restartCoalescer.get(handle.name);
+            if (state)
+                state.watchSerial = 0;
+        }
+        await this.syncBootstrapWatch(handle.name);
+        return true;
+    }
     /**
      * Restart an app, coalescing concurrent triggers.
      *
@@ -493,16 +1069,76 @@ export class OrchestratorService extends EventEmitter {
      * triggers, just continuations — they must not bump or the trailing
      * coalesced restart would re-fire forever.
      */
-    async restartAppCoalesced(name, fromExternal) {
+    async restartAppCoalesced(name, fromExternal, cause = 'manual') {
         const canonical = this.resolveAppName(name) ?? name;
         const handle = this.handles.get(canonical);
-        if (!handle)
+        if (!handle) {
+            // A PROJECT-QUALIFIED name with no live handle is not this daemon's to
+            // start, and matching it against the daemon's own config starts the
+            // WRONG APP.
+            //
+            // The names collide in practice. omnitron's own `omnitron.config.ts`
+            // declares `main`, `payments`, `messaging`, `storage`, `pricing` — the
+            // same five a downstream stack uses. On 2026-09-10, after payments died,
+            // `omnitron restart acme/dev/payments` matched omnitron's sample entry by
+            // its last path segment and launched `apps/payments/src/main.ts` relative
+            // to the DAEMON's cwd. It died with ERR_MODULE_NOT_FOUND on a path that
+            // exists in neither repository, and the backend stayed down while the
+            // command reported that it had restarted it.
+            //
+            // Starting the wrong app is worse than refusing: the operator is told
+            // their service is coming back, and the log that says otherwise is the
+            // one they are not reading yet. `startApp` on the daemon already refuses
+            // this exact shape and names the command that works; this is the same
+            // refusal on the same reasoning, at the point where "no live handle" is
+            // already known.
+            const qualified = name.includes('/');
+            const ownProject = this.config?.project;
+            if (qualified && !ownProject) {
+                const [project, stack] = name.split('/');
+                throw new Error(`'${name}' belongs to a registered project, which this daemon restarts through its ` +
+                    `stack. Use \`omnitron stack start ${project} ${stack}\`, or restart the app by its ` +
+                    `bare name if you mean the daemon's own config.`);
+            }
+            // P1-F — fall through to startApp when there's no live handle but
+            // the ecosystem config declares the app. Operators expect
+            // `omnitron restart foo` to work even when `foo` was never started
+            // (or was stopped, or crashed and was reaped). Previously this
+            // threw "Unknown app", forcing the operator to first run start
+            // explicitly.
+            const effective = effectiveAppName(name);
+            const entry = this.config?.apps.find((a) => a.name === name || a.name === effective || effectiveAppName(a.name) === effective);
+            if (entry) {
+                this.logger.info({ app: name }, 'restartApp: no live handle — falling through to startApp');
+                // Restart under the name the OPERATOR asked for. The match above
+                // accepts a bare entry for a qualified request, and handing it to
+                // `startApp` unchanged re-registers the app bare —
+                // `ensureNamespacedEntry` leaves an entry with no OMNITRON_PROJECT /
+                // OMNITRON_STACK env alone by design. The app then silently leaves its
+                // stack, because `ProjectService.toStackInfo` filters handles on the
+                // `${project}/${stack}/` prefix.
+                const requested = name.includes('/') && !entry.name.includes('/')
+                    ? { ...entry, name }
+                    : entry;
+                return this.startApp(requested);
+            }
             throw new Error(`Unknown app: ${name}`);
+        }
         name = canonical;
         const state = this.getCoalescerState(name);
-        if (fromExternal)
+        if (fromExternal) {
             state.triggerSerial += 1;
-        const observedSerial = state.triggerSerial;
+            if (cause === 'watch')
+                state.watchSerial = state.triggerSerial;
+            else
+                state.manualSerial = state.triggerSerial;
+        }
+        if (!this.allowsWatch(handle.entry) || ['errored', 'crashed', 'stopped', 'stopping'].includes(handle.status)) {
+            state.watchSerial = 0;
+        }
+        const observedSerial = Math.max(state.manualSerial, state.watchSerial);
+        if (observedSerial <= state.firedSerial)
+            return handle;
         // Cooldown: the app reported online recently. Wait it out, then
         // proceed as a non-external continuation (we already counted this
         // trigger when we first arrived).
@@ -531,7 +1167,7 @@ export class OrchestratorService extends EventEmitter {
         }
         // Take the slot. Capture which serial this run is consuming —
         // anything bumped after this is the next run's problem.
-        const consumedSerial = state.triggerSerial;
+        const consumedSerial = observedSerial;
         const promise = this.restartAppNow(name);
         state.inFlight = promise;
         try {
@@ -547,7 +1183,7 @@ export class OrchestratorService extends EventEmitter {
             // trigger arrived between when we claimed the slot and now.
             // Two coalescer arms colliding can no longer cause this branch
             // to fire because they don't bump triggerSerial.
-            if (state.triggerSerial > consumedSerial) {
+            if (Math.max(state.manualSerial, state.watchSerial) > consumedSerial) {
                 this.restartAppCoalesced(name, /* fromExternal */ false).catch((err) => {
                     this.logger.error({ app: name, error: err.message }, 'Trailing coalesced restart failed');
                 });
@@ -569,6 +1205,26 @@ export class OrchestratorService extends EventEmitter {
      * bootstrap-config cache is cleared because changes to `bootstrap.ts`
      * (topology definition) need to take effect on the next start.
      */
+    /**
+     * Start an app this daemon already supervises, using the entry its handle
+     * carries.
+     *
+     * `startApp(entry)` needs an ecosystem entry, which the daemon's own config
+     * is only one source of — a project stack registers handles this daemon
+     * never declared. `restartAppNow` has always taken the entry off the handle
+     * for exactly that reason; this is the same move for a start, so the name
+     * `list` prints is a name `start` accepts.
+     *
+     * Returns `undefined` when the app is unknown, leaving the caller to decide
+     * what to say about a name that names nothing.
+     */
+    async startKnownApp(name) {
+        const canonical = this.resolveAppName(name) ?? name;
+        const handle = this.handles.get(canonical);
+        if (!handle)
+            return undefined;
+        return this.startApp(handle.entry);
+    }
     async restartAppNow(name) {
         const handle = this.handles.get(name);
         if (!handle)
@@ -583,7 +1239,7 @@ export class OrchestratorService extends EventEmitter {
     getCoalescerState(name) {
         let state = this.restartCoalescer.get(name);
         if (!state) {
-            state = { inFlight: null, triggerSerial: 0, firedSerial: 0, cooldownUntil: 0 };
+            state = { inFlight: null, triggerSerial: 0, firedSerial: 0, manualSerial: 0, watchSerial: 0, cooldownUntil: 0 };
             this.restartCoalescer.set(name, state);
         }
         return state;
@@ -602,10 +1258,14 @@ export class OrchestratorService extends EventEmitter {
      * Resolve a user-supplied name to a canonical handle key.
      *
      * Inputs accepted:
-     *   - exact canonical key (`omni/dev/paysys`) → returned as-is
-     *   - bare short name (`paysys`) → returns the canonical key whose
+     *   - exact canonical key (`omni/dev/payments`) → returned as-is
+     *   - bare short name (`payments`) → returns the canonical key whose
      *     last `/`-segment matches, IF AND ONLY IF the match is unique.
      *
+     * A qualified name that matches no handle exactly resolves to nothing: it
+     * names a deployment this daemon does not have, and the nearest app with
+     * the same last segment is a different one.
+     *
      * Returns `undefined` for no match. Throws on ambiguity (multiple
      * stacks expose the same short name) so the caller can surface a
      * clear error to the operator instead of operating on the wrong
@@ -614,6 +1274,18 @@ export class OrchestratorService extends EventEmitter {
     resolveAppName(rawName) {
         if (this.handles.has(rawName))
             return rawName;
+        // A qualified name is an ADDRESS, and the only handle that satisfies it
+        // is the one with that address. Falling through to the short-name match
+        // answered a question about one deployment with another's data:
+        //
+        //     omnitron logs sample/deployed/main   →  sample/dev/main
+        //
+        // — the node's app asked for, this laptop's app printed, with nothing
+        // said. `startApp` already refuses this for the same reason ("a
+        // PROJECT-QUALIFIED name with no live handle is not this daemon's to
+        // start"); the resolver every other caller goes through did not.
+        if (rawName.includes('/'))
+            return undefined;
         const effective = effectiveAppName(rawName);
         const matches = [];
         for (const key of this.handles.keys()) {
@@ -667,8 +1339,11 @@ export class OrchestratorService extends EventEmitter {
                 this.logger.info({ app: name, child: childName }, 'Child reloaded successfully');
             }
             catch (err) {
-                this.logger.error({ app: name, child: childName, error: err.message }, 'Failed to reload child — aborting zero-downtime reload');
-                throw new Error(`Zero-downtime reload failed for '${name}' at child '${childName}': ${err.message}`);
+                // `error: err`, not `error: err.message`: the logger aliases `error`
+                // onto pino's error serializer, so the object arrives with its stack
+                // and a string arrives as a string with nothing behind it.
+                this.logger.error({ app: name, child: childName, error: err }, 'Failed to reload child — aborting zero-downtime reload');
+                throw new Error(`Zero-downtime reload failed for '${name}' at child '${childName}': ${err.message}`, { cause: err });
             }
         }
         this.logger.info({ app: name }, 'Zero-downtime reload complete');
@@ -761,6 +1436,14 @@ export class OrchestratorService extends EventEmitter {
     getWorkerHandle(processId) {
         return this.pm.getWorkerHandle(processId);
     }
+    /**
+     * Surface the underlying IProcessInfo for a titan-pm processId
+     * so callers (e.g. the daemon's `inspect` RPC) can read uptime
+     * + status without reaching into the process-manager directly.
+     */
+    getChildProcessInfo(processId) {
+        return this.pm.getProcess(processId);
+    }
     // ============================================================================
     // Monitoring — async, delegates to PM supervisor for bootstrap mode
     // ============================================================================
@@ -793,38 +1476,23 @@ export class OrchestratorService extends EventEmitter {
         }
         return null;
     }
+    /**
+     * `name` is resolved like every other per-app question (`main` finds
+     * `sample/dev/main`); it was compared verbatim, so `omnitron metrics main`
+     * printed «(no data)». An unknown name answers `{}`, and the caller says so.
+     */
     async getMetrics(name) {
+        const wanted = name === undefined ? undefined : this.resolveAppName(name);
+        if (name !== undefined && wanted === undefined)
+            return {};
         const result = {};
         for (const [appName, handle] of this.handles) {
-            if (name && appName !== name)
+            if (wanted && appName !== wanted)
                 continue;
             if (handle.mode === 'bootstrap' && handle.supervisor) {
-                const childNames = handle.supervisor.getChildNames();
-                let cpu = 0, memory = 0, requests = 0, errors = 0;
-                for (const childName of childNames) {
-                    // Try PM-level RPC metrics first
-                    const m = await handle.supervisor.getChildMetrics(childName);
-                    if (m && (m.cpu > 0 || m.memory > 0)) {
-                        cpu += m.cpu;
-                        memory += m.memory;
-                        requests += m.requests ?? 0;
-                        errors += m.errors ?? 0;
-                    }
-                    else {
-                        // Fallback: OS-level metrics via ps for the child PID
-                        const processId = handle.supervisor.getChildProcessId(childName);
-                        if (processId) {
-                            const workerHandle = this.pm.getWorkerHandle(processId);
-                            const childPid = workerHandle?.pid;
-                            if (childPid) {
-                                const osMetrics = await this.sampleProcessMetrics(childPid);
-                                cpu += osMetrics.cpu;
-                                memory += osMetrics.memory;
-                            }
-                        }
-                    }
-                }
-                const aggregated = { cpu, memory, requests, errors };
+                // Same sampler the poller uses, so `omnitron metrics` and `omnitron
+                // list` cannot report different numbers for the same app.
+                const aggregated = await this.sampleAppMetrics(handle);
                 handle.lastMetrics = aggregated;
                 result[appName] = aggregated;
             }
@@ -835,21 +1503,36 @@ export class OrchestratorService extends EventEmitter {
         }
         return result;
     }
+    /**
+     * Each app's health, asked of every process it runs — its supervisor
+     * children and its worker pools — and combined (`app-health.ts`).
+     *
+     * `name` is resolved like every other per-app question: `main` finds
+     * `sample/dev/main`. It was compared verbatim, so `omnitron health main`
+     * matched nothing and the answer was empty. An unknown name answers `{}`,
+     * and the caller says so.
+     */
     async getHealth(name) {
+        const wanted = name === undefined ? undefined : this.resolveAppName(name);
+        if (name !== undefined && wanted === undefined)
+            return {};
         const result = {};
         for (const [appName, handle] of this.handles) {
-            if (name && appName !== name)
+            if (wanted && appName !== wanted)
+                continue;
+            if (handle.status !== 'online') {
+                result[appName] = notRunningHealth(handle.status);
                 continue;
+            }
             if (handle.mode === 'bootstrap' && handle.supervisor) {
-                const childNames = handle.supervisor.getChildNames();
-                if (childNames.length > 0) {
-                    const health = await handle.supervisor.getChildHealth(childNames[0]);
-                    handle.lastHealth = health;
-                    result[appName] = health;
-                }
-                else {
-                    result[appName] = handle.lastHealth;
+                const supervisor = handle.supervisor;
+                const answers = await Promise.all(supervisor.getChildNames().map(async (child) => [child, await supervisor.getChildHealth(child)]));
+                for (const [pool, instance] of handle.topologyPools) {
+                    answers.push([pool, poolHealth(instance.metrics)]);
                 }
+                const health = answers.length > 0 ? combineProcessHealth(answers) : handle.lastHealth;
+                handle.lastHealth = health;
+                result[appName] = health;
             }
             else {
                 result[appName] = handle.lastHealth;
@@ -952,7 +1635,7 @@ export class OrchestratorService extends EventEmitter {
             else {
                 this.logger.error({ app: entry.name, code, signal }, 'App exited unexpectedly');
                 handle.markCrashed();
-                this.handleClassicCrash(entry, handle, config);
+                this.scheduleRecovery(entry, handle, config);
             }
             this.persistState();
         });
@@ -967,29 +1650,56 @@ export class OrchestratorService extends EventEmitter {
     async launchBootstrapMode(entry, handle, config) {
         handle.markStarting();
         const bootstrapAbsPath = path.resolve(entry.cwd ?? this.cwd, entry.bootstrap);
-        // Load bootstrap definition to check for process topology and requirements
+        // Load bootstrap definition to check for process topology and requirements.
+        //
+        // In dev, in a process of its own (`freshModuleGraph`): imported here, a
+        // package the definition uses would be the one this daemon first saw, for
+        // as long as it runs (bootstrap-loader.ts has the measurement). What comes
+        // back is data, which is all the daemon reads of it — here, in the build
+        // service and in the stack resolver; the app's own processes load the
+        // definition themselves, functions and all.
         let topology;
         let definition;
         try {
-            definition = await loadBootstrapConfig(bootstrapAbsPath, { devMode: this.devMode });
+            definition = await loadBootstrapConfig(bootstrapAbsPath, { devMode: this.devMode, freshModuleGraph: true });
             topology = definition.processes;
         }
         catch (err) {
-            this.logger.warn({ app: entry.name, error: err.message }, 'Could not load bootstrap config for topology — using single-process mode');
+            // Refused, with the reason. This fell back to «single-process mode» at
+            // warn — but every definition declares its topology (IAppDefinition:
+            // `processes` is required), so the fallback started the app in a shape
+            // it was never written for. Measured 2026-09-23 on the master: payments
+            // and messaging, whose definitions failed to load («Parameter
+            // decorators only work when experimental decorators are enabled»), were
+            // started that way and died on «Dependency 'AuthModule:JWTService' not
+            // found» and a module path that single mode could not resolve — the
+            // operator saw those, and the cause sat one line up at warn.
+            throw new Error(`Could not load ${entry.name}'s definition from ${bootstrapAbsPath}: ${err.message}`, { cause: err });
         }
-        // Populate omnitronConfig from app's config/default.json if not set by bootstrap
-        if (definition && !definition.omnitronConfig) {
-            try {
-                const srcDir = path.dirname(bootstrapAbsPath);
-                const appRoot = path.resolve(srcDir, '..');
-                const configPath = path.join(appRoot, 'config', 'default.json');
-                const content = fs.readFileSync(configPath, 'utf-8');
-                const json = JSON.parse(content);
-                if (json.omnitron) {
-                    definition.omnitronConfig = json.omnitron;
+        // The app's `config/default.json`, read on every start and put on a COPY
+        // of the definition. This wrote the section onto the loader's cached
+        // definition «if not set», so the first start's reading was every later
+        // start's — and the logger level beside it, read in the same block, was
+        // never read again at all (`project/declared-config.ts`).
+        if (definition) {
+            const declared = readDeclaredConfig(bootstrapAbsPath);
+            if (declared.malformed) {
+                this.logger.error({ app: entry.name, configPath: declared.configPath, error: declared.malformed }, 'config/default.json does not parse — its `omnitron` section is being ignored');
+            }
+            definition = withDeclaredConfig(definition, declared);
+            // The only place the parent can learn the level the app chose; children
+            // are spawned with it below. Validated rather than trusted: this is a
+            // hand-edited JSON file, and a level pino does not know ("verbose", a
+            // typo) would be handed straight to a child's logger constructor.
+            const level = declared.loggerLevel;
+            if (typeof level === 'string') {
+                if (PINO_LEVELS.has(level)) {
+                    handle.appLogLevel = level;
+                }
+                else {
+                    this.logger.warn({ app: entry.name, configPath: declared.configPath, level }, 'config/default.json declares a logger level this runtime does not know — children keep the default');
                 }
             }
-            catch { /* config file missing — skip */ }
         }
         // Resolve infrastructure config and inject as env vars.
         // Skip if already injected by project.service.ts (stack flow sets OMNITRON_STACK).
@@ -1020,93 +1730,8 @@ export class OrchestratorService extends EventEmitter {
         }
         // Build all entry points via esbuild (dev mode bundles from source .ts)
         //
-        // On a *restart* (as opposed to a first start), buildResults already
-        // has a fresh entry — esbuild's watcher just produced the bundle
-        // that triggered us. Reusing it skips a redundant cold rebuild
-        // (which was costing ~500ms per restart and racing against the
-        // watcher's own incremental output). The watch context is also
-        // preserved (we never unwatched), so we don't re-arm it either.
-        if (definition && this.devMode) {
-            try {
-                if (!this.buildService) {
-                    this.buildService = new BuildService(/* isDev */ true, {
-                        onEsbuildReset: (info) => this.metricsBridge?.recordResilientHandleReset(info),
-                        onBuildResult: ({ app, kind, durationMs, ok }) => this.metricsBridge?.recordEsbuildBuild(app, kind, durationMs, ok),
-                    });
-                }
-                const existing = this.buildResults.get(entry.name);
-                const existingWatch = this.buildService.isWatching?.(entry.name);
-                // Bundle on-disk presence check. A restart can race against
-                // the user (or a script) removing `.omnitron-build/` between
-                // builds — without this stat the orchestrator hands the
-                // worker a path that no longer exists and the child dies
-                // with `ERR_MODULE_NOT_FOUND` before the supervisor can
-                // recover. Cheap stat, big DX win.
-                const bundlePresent = existing
-                    ? fs.existsSync(existing.bootstrapPath)
-                    : false;
-                if (existing && existingWatch && bundlePresent) {
-                    // Restart path — keep the already-built bundle and live watch.
-                    this.logger.debug({ app: entry.name, modules: existing.modulePaths.size }, 'Reusing existing esbuild bundle + watch (restart path)');
-                }
-                else {
-                    if (existing && existingWatch && !bundlePresent) {
-                        // Bundle was deleted out from under us. Clear the watch
-                        // and the cached BuildResult so the next call rebuilds
-                        // from cold and re-arms the watcher cleanly.
-                        this.logger.warn({ app: entry.name, bootstrapPath: existing.bootstrapPath }, 'Cached bundle missing on disk — forcing rebuild');
-                        try {
-                            await this.buildService.unwatchApp?.(entry.name);
-                        }
-                        catch (err) {
-                            this.logger.debug({ err, app: entry.name }, 'unwatchApp failed (non-fatal)');
-                        }
-                        this.buildResults.delete(entry.name);
-                    }
-                    // First-start path — build everything from cold and arm the watcher.
-                    const buildResult = await this.buildService.buildApp(entry.name, bootstrapAbsPath, definition);
-                    this.buildResults.set(entry.name, buildResult);
-                    this.logger.info({ app: entry.name, modules: buildResult.modulePaths.size }, 'Built entry points via esbuild');
-                    // Start esbuild watch for incremental rebuilds on source changes.
-                    // On rebuild → fire a restart trigger; the coalescer takes it
-                    // from there.
-                    await this.buildService.watchApp(entry.name, bootstrapAbsPath, definition, () => {
-                        // Gate: skip if the app is in a non-running state — repeated
-                        // restarts of an escalated/errored process just churn forever
-                        // without forward progress (Fix #248).
-                        // Skip restart when the app is in a terminal non-running
-                        // state. Includes 'crashed' (supervisor escalated after
-                        // exceeding its restart budget) and 'errored' (start
-                        // failed). 'stopped' means operator explicitly stopped it.
-                        // In all three cases, restarting just churns a known-broken
-                        // process; the operator must fix the underlying issue and
-                        // call `omnitron start <app>` to clear the state.
-                        const status = this.getAppStatus(entry.name);
-                        if (status === 'errored' || status === 'crashed' || status === 'stopped') {
-                            this.logger.warn({ app: entry.name, status }, 'esbuild rebuild detected but app is not running — skipping restart');
-                            return;
-                        }
-                        this.logger.info({ app: entry.name }, 'esbuild rebuild detected — restarting');
-                        this.metricsBridge?.recordEsbuildBuild(entry.name, 'rebuild', 0, true);
-                        this.restartApp(entry.name).catch((err) => {
-                            this.logger.error({ app: entry.name, error: err.message }, 'Restart after esbuild rebuild failed');
-                        });
-                    });
-                }
-            }
-            catch (err) {
-                // The "fall back to tsx" wording was misleading — the orchestrator
-                // does not inject a tsx loader into spawned children, so without
-                // a build the bootstrap-process will try to `import` the source
-                // .ts file (referenced as `./app.module.js` in the topology) and
-                // fail with a cryptic "Cannot find module" downstream. Surface
-                // the build error directly so the operator sees the actual
-                // problem on `omnitron start/restart`.
-                this.logger.error({ app: entry.name, error: err.message }, 'esbuild build failed — app cannot start without bundled output');
-                throw new Error(`Cannot launch '${entry.name}' in dev mode: esbuild build failed (${err.message}). ` +
-                    `Fix the build error and retry, or run with bundled output present in apps/${entry.name}/.omnitron-build/.`);
-            }
-        }
+        if (definition)
+            await this.prepareBootstrapBuild(entry, bootstrapAbsPath, definition);
         const buildResult = this.buildResults.get(entry.name);
         // Use bundled bootstrap path for topology import when available
         const effectiveBootstrapPath = buildResult?.bootstrapPath ?? bootstrapAbsPath;
@@ -1117,6 +1742,36 @@ export class OrchestratorService extends EventEmitter {
             await this.launchSingleProcess(entry, handle, config, effectiveBootstrapPath, buildResult);
         }
     }
+    async prepareBootstrapBuild(entry, bootstrapAbsPath, definition) {
+        const sourceTopology = /\.(?:[cm]?ts|tsx)$/.test(bootstrapAbsPath) ||
+            definition.processes.some((process) => /\.(?:[cm]?ts|tsx)$/.test(process.module));
+        if (!this.devMode && !sourceTopology)
+            return;
+        try {
+            this.buildService ??= new BuildService(this.devMode, {
+                onEsbuildReset: (info) => this.metricsBridge?.recordResilientHandleReset(info),
+                onBuildResult: ({ app, kind, durationMs, ok }) => this.metricsBridge?.recordEsbuildBuild(app, kind, durationMs, ok),
+            });
+            const existing = this.buildResults.get(entry.name);
+            const current = this.handles.get(entry.name)?.entry ?? entry;
+            const reusable = existing && this.allowsWatch(current) && this.buildService.isWatching(entry.name) &&
+                this.buildService.canReuseBuild(existing, bootstrapAbsPath, definition);
+            if (!reusable) {
+                // A manual restart with watch:false deliberately compiles the current
+                // sources. It must not reuse an artifact that stopped being maintained.
+                await this.buildService.unwatchApp(entry.name);
+                this.buildResults.delete(entry.name);
+                this.buildResults.set(entry.name, await this.buildService.buildApp(entry.name, bootstrapAbsPath, definition));
+                this.logger.info({ app: entry.name }, 'Built entry points via esbuild');
+            }
+            this.bootstrapSources.set(entry.name, { path: bootstrapAbsPath, definition });
+            await this.syncBootstrapWatch(entry.name);
+        }
+        catch (error) {
+            this.logger.error({ app: entry.name, error }, 'esbuild build failed — app cannot start without bundled output');
+            throw new Error(`Cannot launch '${entry.name}': esbuild build failed (${error.message}). Fix the build error and retry.`, { cause: error });
+        }
+    }
     /**
      * Launch app with process topology — multiple children managed by Omnitron.
      *
@@ -1157,14 +1812,20 @@ export class OrchestratorService extends EventEmitter {
                 size: instances,
                 strategy: PoolStrategy.POWER_OF_TWO,
                 metrics: true,
-                replaceUnhealthy: true,
-                requestTimeout: 120_000,
+                // `replaceUnhealthy` is deliberately not set: titan-pm declares it
+                // and reads it nowhere. An unhealthy worker is replaced by the
+                // health path regardless, so `true` was a no-op that happened to
+                // match the behaviour — and `false` would have been a no-op that did
+                // not, leaving an operator believing they had turned replacement off.
+                // What actually governs it is `healthCheck.unhealthyThreshold`.
+                requestTimeout: CHILD_REQUEST_TIMEOUT,
                 maxQueueSize: 200,
                 spawnOptions: {
                     name: `${entry.name}/${procEntry.name}`,
                     version: '1.0.0',
                     allMethodsPublic: true,
-                    startupTimeout: procEntry.startupTimeout ?? 60_000,
+                    ...(handle.appLogLevel && { logLevel: handle.appLogLevel }),
+                    startupTimeout: procEntry.startupTimeout ?? entry.startupTimeout ?? DEFAULT_CHILD_STARTUP_TIMEOUT,
                     ...(entry.env && { env: entry.env }),
                     ...(entry.cwd && { cwd: entry.cwd }),
                     dependencies: {
@@ -1187,25 +1848,31 @@ export class OrchestratorService extends EventEmitter {
                     enabled: procEntry.health?.enabled !== false,
                     interval: procEntry.health?.interval ?? config.monitoring.healthCheck.interval,
                 },
+                // `scaling.strategy` is what opts a pool into autoscaling; anything
+                // else — including the default of not declaring it — means the pool
+                // stays at the declared `instances`, which is what 'fixed' says on
+                // the tin.
+                //
+                // Both arms of this ternary used to set `enabled: true`, differing
+                // only in where the numbers came from. The setting existed, the
+                // mechanism existed, and nothing connected them: every pool in the
+                // platform was autoscaled whether or not it asked to be. Live effect
+                // on two pools declared `instances: 2` — grown to their cap of eight
+                // and held there, sixteen processes where four were configured.
+                //
+                // `min` follows the declared instance count rather than 1: a pool
+                // asked for two workers should not be scaled below two.
                 autoScale: procEntry.scaling?.strategy === 'auto'
                     ? {
                         enabled: true,
-                        min: 1,
+                        min: instances,
                         max: procEntry.scaling?.maxInstances ?? instances * 4,
                         targetCPU: procEntry.scaling?.targetCPU ?? 70,
                         targetMemory: procEntry.scaling?.targetMemory ?? 80,
                         queueThreshold: procEntry.scaling?.queueThreshold ?? 10,
                         cooldownPeriod: procEntry.scaling?.cooldownPeriod ?? 30_000,
                     }
-                    : {
-                        enabled: true,
-                        min: 1,
-                        max: instances * 4,
-                        targetCPU: 70,
-                        targetMemory: 80,
-                        queueThreshold: 10,
-                        cooldownPeriod: 30_000,
-                    },
+                    : { enabled: false, min: instances, max: instances },
             };
             this.logger.info({ app: entry.name, process: procEntry.name, instances }, 'Creating topology process pool');
             // pm.pool() returns a Proxy wrapping ProcessPool — execute() dispatches to pool workers
@@ -1217,24 +1884,50 @@ export class OrchestratorService extends EventEmitter {
             // which returns null for pool workers (they aren't supervisor
             // children) and the entry is mis-reported as `status: 'stopped'`.
             handle.topologyPools.set(procEntry.name, pool);
+            this.attachPoolLogCapture(entry.name, procEntry.name, handle, pool);
             // Auto-discover @Service metadata from pool workers and expose via ServiceRouter.
             // No manual `exports` needed — @Service decorator IS the source of truth.
             // Requires explicit `topology: { expose: true }` — opt-in for security.
             if (procEntry.topology?.expose === true) {
                 try {
+                    // A pool worker reports ready before its Application has started, and
+                    // `@Service` classes are exposed to Netron during start — so asking
+                    // once, or once more 500ms later, asks a worker that is still booting.
+                    // What it answers then is an empty list, or a service whose method
+                    // list has not been filled in yet, and both used to end the same way:
+                    // nothing registered on the daemon, the consumer process starting
+                    // seconds later, querying, and being told the service does not exist.
+                    // The consumer resolves its topology proxy exactly once, so that
+                    // answer disabled the feature for the life of the process — in the
+                    // case that surfaced this, every OHLCV candle aggregation.
+                    //
+                    // Poll instead, and treat "a service with no methods" as not ready
+                    // rather than as a service, because an empty method list produces a
+                    // proxy that can do nothing.
+                    const usable = (list) => Array.isArray(list) && list.length > 0 && list.some((svc) => svc.methods?.length > 0);
                     let services = await pool.execute('getExposedServices');
-                    // Defensive: if services list is empty, the worker's Application may still
-                    // be registering services. Retry once after a short delay.
-                    if (!services || services.length === 0) {
-                        await new Promise((r) => setTimeout(r, 500));
+                    const deadline = Date.now() + TOPOLOGY_EXPOSE_TIMEOUT_MS;
+                    while (!usable(services) && Date.now() < deadline) {
+                        await new Promise((r) => setTimeout(r, TOPOLOGY_EXPOSE_POLL_MS));
                         services = await pool.execute('getExposedServices');
                     }
-                    if (!services || services.length === 0) {
-                        this.logger.warn({ app: entry.name, process: procEntry.name }, 'No @Service found on pool worker — topology.expose has no effect');
+                    if (!usable(services)) {
+                        this.logger.warn({
+                            app: entry.name,
+                            process: procEntry.name,
+                            waitedMs: TOPOLOGY_EXPOSE_TIMEOUT_MS,
+                            reported: services?.map((svc) => `${svc.name}(${svc.methods?.length ?? 0})`) ?? [],
+                        }, 'No usable @Service found on pool worker — topology.expose has no effect, and any ' +
+                            'process declaring topology.access on it will start without a proxy');
                     }
-                    for (const svc of services) {
-                        if (svc.methods.length === 0)
+                    for (const svc of services ?? []) {
+                        if (svc.methods.length === 0) {
+                            // Silently skipped before. A consumer then failed to find a
+                            // service its own declaration named, with nothing anywhere
+                            // connecting the two facts.
+                            this.logger.warn({ app: entry.name, process: procEntry.name, service: svc.name }, 'Pool service exposes no methods — not registered on the daemon');
                             continue;
+                        }
                         await serviceRouter.exposePoolService(procEntry.name, svc.name, svc.version ?? '1.0.0', pool, svc.methods);
                         this.logger.info({ app: entry.name, process: procEntry.name, service: svc.name, methods: svc.methods.length }, 'Auto-discovered and exposed pool service on daemon Netron');
                     }
@@ -1253,7 +1946,10 @@ export class OrchestratorService extends EventEmitter {
                 name: `${entry.name}/${procEntry.name}`,
                 version: '1.0.0',
                 allMethodsPublic: true,
-                startupTimeout: procEntry.startupTimeout ?? entry.startupTimeout ?? 30_000,
+                // Without this the child's client takes netron's 5000 ms; the pool
+                // path beside it has always stated one. See CHILD_REQUEST_TIMEOUT.
+                requestTimeout: CHILD_REQUEST_TIMEOUT,
+                startupTimeout: procEntry.startupTimeout ?? entry.startupTimeout ?? DEFAULT_CHILD_STARTUP_TIMEOUT,
                 ...(entry.env && { env: entry.env }),
                 ...(entry.cwd && { cwd: entry.cwd }),
                 dependencies: {
@@ -1271,6 +1967,7 @@ export class OrchestratorService extends EventEmitter {
                     timeout: procEntry.health?.timeout ?? config.monitoring.healthCheck.timeout,
                 },
                 observability: { metrics: true },
+                ...(handle.appLogLevel && { logLevel: handle.appLogLevel }),
             };
             children.push({
                 name: `${entry.name}/${procEntry.name}`,
@@ -1295,18 +1992,11 @@ export class OrchestratorService extends EventEmitter {
         };
         // Create supervisor WITHOUT starting — wire events first to avoid race condition
         const supervisor = this.pm.createSupervisor(supervisorConfig);
-        supervisor.on('child:started', (childName) => {
-            const processId = supervisor.getChildProcessId(childName);
-            if (processId) {
-                const workerHandle = this.pm.getWorkerHandle(processId);
-                const info = this.pm.getProcess(processId);
-                const childPid = workerHandle?.pid ?? info?.pid;
-                handle.markOnline(childPid ?? process.pid);
-            }
-            this.persistState();
-            this.startPostOnlineCooldown(entry.name);
-            this.emit('app:online', entry.name);
-        });
+        // The app's pid is its server's: the single process with a transport, the
+        // one `handle.port` names. A topology with none has no pid to give.
+        const server = singleEntries.find((p) => p.transports?.http) ?? singleEntries.find((p) => p.transports) ?? null;
+        handle.declareChildren(children.map((child) => child.name), server ? `${entry.name}/${server.name}` : null);
+        this.onChildStarted(entry, handle, supervisor);
         // Set supervisor on handle BEFORE start so attachLogCapture can access it
         handle.supervisor = supervisor;
         handle.serviceRouter = serviceRouter;
@@ -1315,6 +2005,73 @@ export class OrchestratorService extends EventEmitter {
         this.wireSupervisorEvents(entry, handle, supervisor);
         // Now start — events will be captured correctly
         await supervisor.start();
+        // Step 4: register the single processes that declare `topology.expose`.
+        //
+        // This was a pool-only feature, ignored in silence everywhere else: a
+        // process declaring `expose: true` got no registration and no warning,
+        // and every consumer naming it in `topology.access` started without a
+        // proxy. Measured on quotes, whose `collector` is a single process
+        // holding the only objects that know whether the exchange WebSockets are
+        // up — the server process could not ask, and answered `ready: down —
+        // exchanges unavailable` while three were connected.
+        //
+        // After `supervisor.start()` because there is no child to ask before it.
+        // A consumer among these children may therefore start before the service
+        // is registered; consumers re-resolve their proxy on use for exactly that
+        // reason (see quotes's `OhlcvSchedulerService`).
+        await this.exposeChildTopologyServices(entry, supervisor, serviceRouter, singleEntries);
+    }
+    /**
+     * Register each single process's `@Service` classes on the daemon.
+     *
+     * Mirrors the pool path above, including its poll: a child reports ready
+     * before its Application has started, and `@Service` classes are exposed to
+     * Netron during start, so asking once asks a process that is still booting
+     * and gets an empty list back.
+     */
+    async exposeChildTopologyServices(entry, supervisor, serviceRouter, singleEntries) {
+        for (const procEntry of singleEntries) {
+            if (procEntry.topology?.expose !== true)
+                continue;
+            const childName = `${entry.name}/${procEntry.name}`;
+            const getProxy = () => supervisor.getChildProxy(childName);
+            try {
+                const usable = (list) => Array.isArray(list) && list.length > 0 && list.some((svc) => svc.methods?.length > 0);
+                const ask = async () => {
+                    const child = getProxy();
+                    if (!child?.getExposedServices)
+                        return undefined;
+                    return (await child.getExposedServices());
+                };
+                let services = await ask();
+                const deadline = Date.now() + TOPOLOGY_EXPOSE_TIMEOUT_MS;
+                while (!usable(services) && Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, TOPOLOGY_EXPOSE_POLL_MS));
+                    services = await ask();
+                }
+                if (!usable(services)) {
+                    this.logger.warn({
+                        app: entry.name,
+                        process: procEntry.name,
+                        waitedMs: TOPOLOGY_EXPOSE_TIMEOUT_MS,
+                        reported: services?.map((svc) => `${svc.name}(${svc.methods?.length ?? 0})`) ?? [],
+                    }, 'No usable @Service found on this process — topology.expose has no effect, and any ' +
+                        'process declaring topology.access on it will start without a proxy');
+                    continue;
+                }
+                for (const svc of services ?? []) {
+                    if (svc.methods.length === 0) {
+                        this.logger.warn({ app: entry.name, process: procEntry.name, service: svc.name }, 'Process service exposes no methods — not registered on the daemon');
+                        continue;
+                    }
+                    await serviceRouter.exposeChildService(procEntry.name, svc.name, svc.version ?? '1.0.0', getProxy, svc.methods);
+                    this.logger.info({ app: entry.name, process: procEntry.name, service: svc.name, methods: svc.methods.length }, 'Auto-discovered and exposed process service on daemon Netron');
+                }
+            }
+            catch (err) {
+                this.logger.error({ app: entry.name, process: procEntry.name, error: err.message }, "Failed to auto-discover/expose this process's services");
+            }
+        }
     }
     /**
      * Launch single-process bootstrap app (no topology — original behavior).
@@ -1330,11 +2087,22 @@ export class OrchestratorService extends EventEmitter {
         const spawnOpts = {
             name: entry.name,
             version: '1.0.0',
+            // As above: a single child's client otherwise runs on netron's default.
+            requestTimeout: CHILD_REQUEST_TIMEOUT,
             ...(entry.env && { env: entry.env }),
             dependencies: {
                 bootstrapPath: bootstrapAbsPath,
                 ...(bundledModulePath && { bundledModulePath }),
             },
+            // Omitted when unset, which delegates the budget to titan-pm —
+            // `process-spawner.ts`: `options.startupTimeout ?? resources?.timeout ??
+            // 30_000`. Worth naming, because it is otherwise invisible from here:
+            // an APP that declares nothing gets 30s while its CHILD processes get
+            // `DEFAULT_CHILD_STARTUP_TIMEOUT`, 60s. Backwards if anything, since the
+            // app usually does the heavier work — and the downstream project's own
+            // config carries a note about a 30s default that kept a whole stack from
+            // starting. Left as delegation rather than changed here: raising it is a
+            // decision about titan-pm's contract, not about this call site.
             ...(entry.startupTimeout != null && { startupTimeout: entry.startupTimeout }),
             health: {
                 enabled: true,
@@ -1342,6 +2110,7 @@ export class OrchestratorService extends EventEmitter {
                 timeout: config.monitoring.healthCheck.timeout,
             },
             observability: { metrics: true },
+            ...(handle.appLogLevel && { logLevel: handle.appLogLevel }),
         };
         const childConfig = {
             name: entry.name,
@@ -1354,7 +2123,8 @@ export class OrchestratorService extends EventEmitter {
                 size: instances,
                 strategy: PoolStrategy.ROUND_ROBIN,
                 metrics: true,
-                replaceUnhealthy: true,
+                // See the note on the other pool: `replaceUnhealthy` is declared by
+                // titan-pm and read by nothing.
                 healthCheck: {
                     enabled: true,
                     interval: config.monitoring.healthCheck.interval,
@@ -1392,20 +2162,10 @@ export class OrchestratorService extends EventEmitter {
         };
         // Create supervisor WITHOUT starting — wire events first to avoid race condition
         const supervisor = this.pm.createSupervisor(supervisorConfig);
-        // Wire supervisor events BEFORE start so we catch the initial child:started
-        supervisor.on('child:started', (childName) => {
-            const processId = supervisor.getChildProcessId(childName);
-            if (processId) {
-                // Prefer WorkerHandle.pid (actual child OS PID), fallback to IProcessInfo.pid
-                const workerHandle = this.pm.getWorkerHandle(processId);
-                const info = this.pm.getProcess(processId);
-                const childPid = workerHandle?.pid ?? info?.pid;
-                handle.markOnline(childPid ?? process.pid);
-            }
-            this.persistState();
-            this.startPostOnlineCooldown(entry.name);
-            this.emit('app:online', entry.name);
-        });
+        // Wire supervisor events BEFORE start so we catch the initial child:started.
+        // One child, and it is the whole app — so it is the server too.
+        handle.declareChildren([childConfig.name], childConfig.name);
+        this.onChildStarted(entry, handle, supervisor);
         // Set supervisor on handle BEFORE start so attachLogCapture can access it
         handle.supervisor = supervisor;
         handle.instanceCount = instances;
@@ -1413,14 +2173,50 @@ export class OrchestratorService extends EventEmitter {
         // Now start — events will be captured correctly
         await supervisor.start();
     }
+    /**
+     * A child's start, for both launch paths: the app is online when the start
+     * completes it, and not before (`AppHandle.childStarted`).
+     *
+     * Each path had its own copy of this handler, and both marked the app
+     * online — with that child's pid — on every child's start. `app:online`
+     * went out once per child with it: three STARTED events for one boot of a
+     * three-process app, the first two about an app still coming up.
+     */
+    onChildStarted(entry, handle, supervisor) {
+        supervisor.on('child:started', (childName) => {
+            // A pool child's proxy answers every property with a function —
+            // `__processId` included — so only a string is a process id. The old
+            // handler took that function for one, found no worker behind it, and
+            // gave such an app the DAEMON's pid.
+            const processId = supervisor.getChildProcessId(childName);
+            const pid = typeof processId === 'string'
+                ? (this.pm.getWorkerHandle(processId)?.pid ?? this.pm.getProcess(processId)?.pid ?? null)
+                : null;
+            const whole = handle.childStarted(childName, pid);
+            this.persistState();
+            if (!whole)
+                return;
+            this.startPostOnlineCooldown(entry.name);
+            this.emit('app:online', entry.name);
+        });
+    }
     /**
      * Wire common supervisor events (crash, restart, escalate) and log capture.
      */
     wireSupervisorEvents(entry, handle, supervisor) {
         supervisor.on('child:started', (childName) => {
             this.attachLogCapture(entry.name, childName, handle);
+            this.attachExitCapture(entry.name, childName, handle);
+            // The app re-entered a live state — drop the previous crash
+            // context so a future `omnitron inspect` shows the *next*
+            // crash, not the last one.
+            handle.clearLastExit();
         });
+        // A child that is down leaves the app partial until it is back — a
+        // sibling's restart must not bring the app `online` around it.
+        supervisor.on('child:stopped', (childName) => handle.childGone(childName));
         supervisor.on('child:crash', (childName, error) => {
+            handle.childGone(childName);
             // If app never reached 'online', mark as errored (not crashed — it never ran)
             if (handle.status === 'starting') {
                 handle.markErrored();
@@ -1428,10 +2224,94 @@ export class OrchestratorService extends EventEmitter {
             else {
                 handle.markCrashed();
             }
+            // Stash the supervisor-provided error message onto whatever
+            // exit context the workerHandle.onExit hook already wrote. If
+            // the exit event hasn't fired yet (race) we still need to
+            // persist *something* — record a synthetic entry that the
+            // exit hook below will overwrite when it does fire.
+            if (handle.lastExit) {
+                handle.lastExit.message = error.message;
+            }
+            else {
+                handle.recordExit({ code: null, signal: null, expected: false, message: error.message });
+            }
             this.logger.error({ app: entry.name, child: childName, error: error.message }, 'Process crashed');
             this.persistState();
             this.emit('app:crash', entry.name, error);
         });
+        // T#60 — startup failures (child throws/rejects in waitForReady
+        // before ever reporting ready) come through this event, NOT
+        // child:crash. Without a handler the orchestrator just sees
+        // status='errored' with no clue what went wrong. titan-pm
+        // already stuffs the captured stderr into `error.details.stderr`
+        // so we surface it on `lastExit.stderrTail`.
+        supervisor.on('child:start-failed', (childName, error) => {
+            const details = error.details;
+            const stderrTail = typeof details?.stderr === 'string'
+                ? details.stderr.split('\n').filter((l) => l.length > 0).slice(-80)
+                : [];
+            for (const line of stderrTail)
+                handle.appendStderr(line);
+            // A child that never came up because WE stopped the app is not a
+            // failure, and reporting it as one is worse than saying nothing: the
+            // message titan-pm builds for an aborted start says the process "did not
+            // choose to exit, so its own logs will not explain this" — true, and it
+            // sends the reader hunting a fault in an application that was doing
+            // nothing wrong. Every `stack stop` issued while anything was still
+            // booting wrote one of these per child, at error level, into the app's
+            // own log.
+            //
+            // `'stopping'` only — NOT `'stopped'`, which is also an AppHandle's
+            // initial value, so accepting it would swallow the first genuine failure
+            // of any app whose handle had not yet been marked starting.
+            const expected = handle.status === 'stopping' ||
+                error.stoppedDuringStartup === true;
+            if (expected) {
+                handle.recordExit({
+                    code: null,
+                    signal: null,
+                    expected: true,
+                    message: error.message,
+                });
+                this.logger.info({ app: entry.name, child: childName, err: error.message }, 'Process stopped before it finished starting');
+                this.persistState();
+                return;
+            }
+            // Put what the child printed into the app's LOG FILE, not only into the
+            // in-memory ring `omnitron inspect` reads.
+            //
+            // A child that dies during startup never produces a WorkerHandle at all
+            // — titan-pm registers one only after `waitForReady` resolves — so there
+            // is no `onLog` to subscribe to here and nothing to replay. What does
+            // exist is the output `waitForReady` captured while waiting, which it
+            // attaches to the error. Feeding that to the log handlers is the only
+            // way a failed boot reaches disk, and a failed boot is the case where
+            // reading it matters most: an application that dies before its logger
+            // exists has said everything it is ever going to say on these streams.
+            // The failure itself first. A child can fail without printing a word —
+            // it reports the error over the IPC channel and exits, which is what a
+            // module that throws on import does — so the streams below are often
+            // empty and the only account of what happened is on the error.
+            this.persistChildFailure(entry.name, childName, error);
+            this.persistChildOutput(entry.name, childName, details?.stdout, 'stdout');
+            this.persistChildOutput(entry.name, childName, details?.stderr, 'stderr');
+            handle.recordExit({
+                code: null,
+                signal: null,
+                expected: false,
+                message: error.message,
+            });
+            // The supervisor gives up on a non-critical child whose start failed (a
+            // critical one throws, and `startApp` says so). That went unseen while
+            // the first child's start made the app `online`; now the app would wait
+            // for a child that is not coming, in `starting` — which `omnitron start`
+            // takes for a start in progress and leaves alone. A declared process
+            // that did not start is an app that did not start.
+            if (handle.status === 'starting')
+                handle.markErrored();
+            this.logger.error({ app: entry.name, child: childName, err: error.message }, 'Process failed to start');
+            this.persistState();
+        });
         supervisor.on('child:restart', (childName, attempt) => {
             handle.restarts = attempt;
             this.logger.info({ app: entry.name, child: childName, attempt }, 'Process restarting');
@@ -1458,9 +2338,45 @@ export class OrchestratorService extends EventEmitter {
         const workerHandle = this.pm.getWorkerHandle(processId);
         if (!workerHandle?.onLog)
             return;
-        workerHandle.onLog((line, _stream) => {
+        workerHandle.onLog(this.childLogForwarder(appName, handle));
+    }
+    /**
+     * Attach log capture to the workers of a topology POOL.
+     *
+     * `attachLogCapture` above is driven by `child:started`, which only
+     * supervisor children emit — a pool worker is not one, so nothing ever
+     * subscribed to its output. Everything those workers print went nowhere:
+     * the OHLCV aggregator and the image transformer have been mute since they
+     * were written, and since titan-pm started holding pre-capture output it was
+     * also a megabyte per worker retained for a reader that never arrived.
+     *
+     * Attached once, at pool creation. A worker replaced later by autoscaling or
+     * a health restart is not covered; these pools are fixed-size, and the
+     * alternative is an event this package does not expose yet.
+     */
+    attachPoolLogCapture(appName, processName, handle, pool) {
+        const forward = this.childLogForwarder(appName, handle);
+        let attached = 0;
+        for (const workerId of pool.getWorkerIds()) {
+            const workerHandle = pool.getWorkerHandle(workerId);
+            if (!workerHandle?.onLog)
+                continue;
+            workerHandle.onLog(forward);
+            attached++;
+        }
+        this.logger.debug({ app: appName, process: processName, workers: attached }, 'Pool log capture attached');
+    }
+    /** The one place a child's line becomes an app's line. */
+    childLogForwarder(appName, handle) {
+        return (line, stream) => {
             // In-memory ring buffer (for live CLI tailing)
             handle.appendLog(line);
+            // Separate stderr ring — feeds `lastExit.stderrTail` on death.
+            // Without this, the operator running `omnitron inspect` after
+            // a crash sees no hint at WHY (the in-flight pipe is gone).
+            if (stream === 'stderr') {
+                handle.appendStderr(line);
+            }
             // Persist to disk via registered log handlers (LogManager)
             for (const handler of this.appLogHandlers) {
                 try {
@@ -1470,6 +2386,108 @@ export class OrchestratorService extends EventEmitter {
                     // Log handler failure must not break the app
                 }
             }
+        };
+    }
+    /**
+     * Write the failure a child reported before it could start to the app's log
+     * handlers, as one structured line.
+     *
+     * `error.childStack` is the stack from inside the child when it managed to
+     * send one — for a module that throws on import that is the entire
+     * diagnosis, and it exists nowhere else once the process is gone.
+     */
+    persistChildFailure(appName, childName, error) {
+        const childStack = error.childStack;
+        const entry = JSON.stringify({
+            level: 50,
+            time: new Date().toISOString(),
+            processName: qualifyChildName(appName, childName),
+            event: 'process.start_failed',
+            err: { message: error.message, ...(childStack ? { stack: childStack } : {}) },
+            msg: `Process failed to start: ${error.message}`,
+        });
+        for (const handler of this.appLogHandlers) {
+            try {
+                handler(appName, entry);
+            }
+            catch {
+                // A log handler must not break failure reporting.
+            }
+        }
+    }
+    /**
+     * Write a dead child's captured output to the app's log handlers.
+     *
+     * Emitted as pino-shaped JSON so it lands in the same file, at the same
+     * level, as everything else that app ever logged — a reader tailing
+     * `app.log` after a failed start finds the reason there rather than having
+     * to know that this particular failure hides in a different place.
+     */
+    persistChildOutput(appName, childName, output, stream) {
+        if (!output)
+            return;
+        const time = new Date().toISOString();
+        for (const line of output.split('\n')) {
+            if (!line.trim())
+                continue;
+            // Already-structured lines pass through untouched; the child may well
+            // have got far enough to produce them.
+            const entry = line.trimStart().startsWith('{')
+                ? line
+                : JSON.stringify({
+                    // stderr is not error. A boot script's own progress markers go
+                    // there, and a failing start emits a run of them — classifying
+                    // every one at 50 filled the log with errors that are nothing of
+                    // the sort, next to the single line that IS the failure. The
+                    // failure is reported at 50 by `persistChildFailure`; this is the
+                    // context around it, and `stream` keeps it greppable.
+                    level: stream === 'stderr' ? 40 : 30,
+                    time,
+                    processName: qualifyChildName(appName, childName),
+                    stream,
+                    msg: line,
+                });
+            for (const handler of this.appLogHandlers) {
+                try {
+                    handler(appName, entry);
+                }
+                catch {
+                    // A log handler must not break failure reporting.
+                }
+            }
+        }
+    }
+    /**
+     * Subscribe to the WorkerHandle's `exit` event so the orchestrator
+     * keeps the exit code / signal / "expected" flag past the
+     * WorkerHandle's GC. Pre-fix the supervisor's `child:crash` event
+     * fired with an Error but never surfaced the underlying
+     * code/signal — operators had no way to tell SIGKILL from a
+     * thrown TypeError. The captured info lands on
+     * `handle.lastExit` and is surfaced by `omnitron inspect`.
+     */
+    attachExitCapture(appName, childName, handle) {
+        const supervisor = handle.supervisor;
+        if (!supervisor)
+            return;
+        const processId = supervisor.getChildProcessId(childName);
+        if (!processId)
+            return;
+        const workerHandle = this.pm.getWorkerHandle(processId);
+        if (!workerHandle?.onExit)
+            return;
+        workerHandle.onExit((info) => {
+            // Preserve the supervisor's error message if `child:crash`
+            // already fired before us. recordExit overwrites the synthetic
+            // entry with the authoritative code/signal.
+            const message = handle.lastExit?.message;
+            handle.recordExit({
+                code: info.code,
+                signal: info.signal,
+                expected: info.expected,
+                ...(message !== undefined && { message }),
+            });
+            this.logger.debug({ app: appName, child: childName, code: info.code, signal: info.signal, expected: info.expected }, 'Captured worker exit context');
         });
     }
     // ============================================================================
@@ -1479,30 +2497,58 @@ export class OrchestratorService extends EventEmitter {
         const child = handle.childProcess;
         if (!child || !child.pid)
             return;
+        const pid = child.pid;
+        // P0-D — Signal the whole process group, not just the direct
+        // child. classic-launcher spawns with `detached: true` so the
+        // child becomes group leader (pgid === pid). `process.kill(-pid)`
+        // delivers the signal to every process in the group, reaping
+        // grandchildren (ffmpeg, docker, worker pools …) that ignore the
+        // direct-child kill. Falls back to `child.kill` when the negative-
+        // pid call fails (test environments, restricted permissions, the
+        // child wasn't started detached — bootstrap-mode currently isn't).
+        const sendSignal = (sig) => {
+            try {
+                process.kill(-pid, sig);
+                return;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== 'ESRCH' && code !== 'EPERM') {
+                    // ESRCH/EPERM = group already gone or not a group leader.
+                    // Anything else (EINVAL etc.) → log via best-effort.
+                    this.logger.debug({ app: handle.name, pid, sig, code }, 'process.kill(-pid) fallback');
+                }
+            }
+            try {
+                child.kill(sig);
+            }
+            catch { /* best-effort */ }
+        };
         await new Promise((resolve) => {
             const timer = setTimeout(() => {
-                try {
-                    child.kill('SIGKILL');
-                }
-                catch {
-                    // SIGKILL send is best-effort
-                }
+                sendSignal('SIGKILL');
                 resolve();
             }, timeout);
             child.once('exit', () => {
                 clearTimeout(timer);
                 resolve();
             });
-            try {
-                child.kill(force ? 'SIGKILL' : 'SIGTERM');
-            }
-            catch {
-                clearTimeout(timer);
-                resolve();
-            }
+            sendSignal(force ? 'SIGKILL' : 'SIGTERM');
         });
     }
-    async handleClassicCrash(entry, handle, config) {
+    /**
+     * Cancel a pending crash cool-down for `name`, if one is armed.
+     * An explicit stop means "this app is going down now, stay down",
+     * which the cool-down must not undo ten minutes later.
+     */
+    clearCoolDown(name) {
+        const timer = this.coolDownTimers.get(name);
+        if (timer) {
+            clearTimeout(timer);
+            this.coolDownTimers.delete(name);
+        }
+    }
+    async scheduleRecovery(entry, handle, config) {
         const policy = buildRestartPolicy(entry, config);
         if (!policy.enabled)
             return;
@@ -1510,87 +2556,416 @@ export class OrchestratorService extends EventEmitter {
             handle.status = 'crashed';
             this.logger.error({ app: entry.name }, 'Max restarts exceeded');
             this.emit('app:escalated', entry.name);
+            // P1-I — auto-recovery after a cool-down. pm2 has this as
+            // `restart_delay` + a fresh attempt window; pre-fix omnitron
+            // left the app permanently 'crashed' until human intervention.
+            // We reset the counter + schedule one fresh attempt 10 minutes
+            // out. If THAT attempt also crashes through maxRestarts we
+            // land back here and pause another 10 minutes — bounded
+            // self-healing without thrashing.
+            //
+            // The wait happens OUTSIDE the lifecycle queue, and that is the
+            // whole point. It used to be a queued `crash-restart` whose
+            // `run()` slept for the entire cool-down — but `enqueue` will
+            // not preempt a RUNNING head, and with an empty queue the
+            // sleeper always became the head immediately. So the `onPreempt`
+            // hook meant to cancel it could never fire, and an operator's
+            // `stop` or `restart` simply queued behind ten minutes of sleep:
+            // the CLI's RPC timed out after 60s while the op stayed queued,
+            // to fire whenever the cool-down finally elapsed. An app that
+            // exhausted its restart budget was unreachable by every command
+            // the CLI offers — `restart` hung, `stop` hung, `stack start`
+            // skipped it — and the only recovery was restarting the daemon.
+            const COOL_DOWN_MS = 10 * 60_000;
+            this.clearCoolDown(entry.name);
+            const timer = setTimeout(() => {
+                this.coolDownTimers.delete(entry.name);
+                // Re-read the handle: every start replaces it (see
+                // `startAppInternal`), so the one captured above is stale the
+                // moment anything restarts this app. Only a still-crashed app
+                // wants this attempt — an operator who started it meanwhile
+                // has already settled the question.
+                const current = this.handles.get(entry.name);
+                if (!current || current.status !== 'crashed')
+                    return;
+                this.logger.info({ app: entry.name }, 'Cool-down elapsed — attempting fresh recovery');
+                current.restarts = 0; // fresh attempt window
+                current.status = 'stopped';
+                void this.lifecycleQueue
+                    .enqueue(entry.name, 'crash-restart', () => this.startAppInternal(entry, config))
+                    .catch((err) => {
+                    if (err instanceof LifecyclePreempted)
+                        return;
+                    this.logger.error({ app: entry.name, err: err.message }, 'Cool-down recovery failed');
+                });
+            }, COOL_DOWN_MS);
+            timer.unref?.();
+            this.coolDownTimers.set(entry.name, timer);
             return;
         }
         const backoff = policy.backoff ?? config.supervision.backoff;
         const delay = this.calculateBackoff(handle.restarts, backoff);
         this.logger.info({ app: entry.name, delay, attempt: handle.restarts + 1 }, 'Scheduling restart');
-        const timer = setTimeout(async () => {
-            // Guard: don't restart if orchestrator was stopped during backoff
-            if (handle.status === 'stopping' || handle.status === 'stopped')
-                return;
-            try {
-                handle.status = 'stopped';
-                await this.startApp(entry, config);
-            }
-            catch (err) {
-                this.logger.error({ app: entry.name, error: err.message }, 'Restart failed');
+        // P0-I — schedule the crash-restart through the lifecycle queue
+        // so an explicit stop preempts the pending restart before it
+        // fires. The setTimeout is still the timing source, but the
+        // queue.enqueue with `onPreempt` guarantees the timer is cleared
+        // (and the promise rejected with LifecyclePreempted) the moment a
+        // higher-priority op for the same app arrives. Pre-fix the timer
+        // could fire during stopApp's `await stopChild(...)` window and
+        // spawn a zombie under the same handle.
+        let timer = null;
+        const restartPromise = this.lifecycleQueue.enqueue(entry.name, 'crash-restart', () => new Promise((resolve, reject) => {
+            timer = setTimeout(async () => {
+                timer = null;
+                // Guard: don't restart if orchestrator was stopped during backoff
+                if (handle.status === 'stopping' || handle.status === 'stopped') {
+                    resolve();
+                    return;
+                }
+                try {
+                    handle.status = 'stopped';
+                    // `startAppInternal`, not `startApp`.
+                    //
+                    // This task holds the lifecycle-queue slot for `entry.name`.
+                    // `startApp` enqueues 'start' on that same key, and the queue
+                    // cannot run it until this task returns — so the await never
+                    // settles and the restart silently never happens. Measured:
+                    // `startApp:enter` with no matching exit, and the app left in
+                    // whatever state the crash put it in.
+                    //
+                    // This is why the whole policy below — bounded attempts,
+                    // exponential backoff, the ten-minute cool-down described in its
+                    // own comment as "bounded self-healing" — had never restarted
+                    // anything. The queue was introduced (P0-I) to stop a restart
+                    // timer racing a stop; it also made the restart unreachable, and
+                    // nothing failed loudly enough to say so.
+                    await this.startAppInternal(entry, config);
+                    resolve();
+                }
+                catch (err) {
+                    const message = err.message;
+                    this.logger.error({ app: entry.name, error: message }, 'Restart failed');
+                    // Said separately and after, because reading the process table
+                    // takes a moment and the failure itself must not wait for it.
+                    void this.explainPortConflict(message).then((held) => {
+                        if (held)
+                            this.logger.error({ app: entry.name }, `Restart failed — ${held}`);
+                    });
+                    reject(err);
+                }
+            }, delay);
+        }), () => {
+            // onPreempt — explicit stop / restart arrived. Cancel the
+            // pending timer so the restart never fires.
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
             }
-        }, delay);
-        // Allow cleanup on explicit stop
+        });
+        // Swallow LifecyclePreempted — that's the explicit-stop happy
+        // path, not an error. Anything else gets logged.
+        restartPromise.catch((err) => {
+            if (err instanceof LifecyclePreempted)
+                return;
+            this.logger.warn({ app: entry.name, err: err.message }, 'Crash restart task rejected');
+        });
+        // Legacy field — callers still poke handle.crashRestartTimer to
+        // check "is a restart pending"; keep it in sync with the queued
+        // timer so existing inspect / status code paths don't break.
         handle.crashRestartTimer = timer;
     }
     calculateBackoff(attempt, backoff) {
-        const initial = backoff.initial ?? 1000;
-        const max = backoff.max ?? 30_000;
-        const factor = backoff.factor ?? 2;
-        if (backoff.type === 'exponential')
-            return Math.min(initial * Math.pow(factor, attempt), max);
-        if (backoff.type === 'linear')
-            return Math.min(initial * (attempt + 1), max);
-        return initial;
-    }
-    /** Sample CPU/memory for a single OS process via `ps` (async — does not block event loop) */
+        // Delegate to the shared backoff library in titan-pm. Pre-fix the
+        // inline impl here defaulted `initial=1000` while supervisor's
+        // copy defaulted to 300 — same config produced 3.3× longer
+        // delays in classic-mode than bootstrap-mode. Now both routes
+        // run the same math.
+        return computeBackoff(attempt + 1, backoff);
+    }
+    /**
+     * The live OS processes behind one topology entry.
+     *
+     * Single-instance entries run as supervisor children; entries with
+     * `instances > 1` run in a pool the supervisor knows nothing about. Both
+     * shapes are resolved here, in one place, because metrics sampling and
+     * status reporting each used to resolve them separately — and disagreed.
+     * The pool branch asserted `online` from `pool.size > 0` before looking at
+     * a pid at all, so a worker whose process had exited still read as online
+     * (observed live: two pool workers reporting `online` on pids that `kill
+     * -0` said were gone).
+     */
+    resolveTopologyPids(handle, topo) {
+        return this.resolveTopologyMembers(handle, topo).members.map((m) => m.pid);
+    }
+    /**
+     * The live processes behind one topology entry, keyed by the PM process id
+     * as well as the OS pid.
+     *
+     * The pid alone answers "is it alive"; the process id is what any question
+     * ABOUT that process has to be asked with — `pm.getProcess(id)` carries the
+     * spawn time, and the supervisor's restart counter is keyed by child name.
+     * `resolveTopologyPids` used to discard both on the way out, which is why
+     * the `omnitron list` DTO had nothing to report but the parent's numbers.
+     */
+    resolveTopologyMembers(handle, topo) {
+        const isPoolEntry = (topo.instances ?? 1) > 1;
+        if (isPoolEntry) {
+            const pool = handle.topologyPools.get(topo.name);
+            if (!pool || pool.size === 0)
+                return { members: [], childName: null };
+            const members = pool
+                .getWorkerIds()
+                .map((processId) => ({ processId, pid: this.pm.getWorkerHandle(processId)?.pid }))
+                .filter((m) => typeof m.pid === 'number');
+            return { members, childName: null };
+        }
+        const childNames = handle.supervisor?.getChildNames() ?? [];
+        const childName = childNames.find((cn) => cn.includes(topo.name)) ?? topo.name;
+        const processId = handle.supervisor?.getChildProcessId(childName);
+        if (!processId)
+            return { members: [], childName };
+        const pid = this.pm.getWorkerHandle(processId)?.pid;
+        return { members: typeof pid === 'number' ? [{ processId, pid }] : [], childName };
+    }
+    /**
+     * Sample every process an app owns, and record the per-entry readings on
+     * the handle on the way through.
+     *
+     * A bootstrap app is several OS processes, so "the memory this app uses"
+     * is their sum. The periodic poller used to sample the single pid stored
+     * on the handle — which for a multi-process app is whichever child was
+     * registered last — and overwrite `lastMetrics` with it every five
+     * seconds, while `getMetrics()` right beside it aggregated correctly and
+     * wrote to the same field. The poller won on frequency, so the aggregate
+     * was never what anyone saw: `acme/dev/main` reported 122 MB against 437 MB
+     * actually resident across its three processes.
+     *
+     * ## Why `ps` and not the child's own report
+     *
+     * The aggregating path preferred the PM-level metrics a child reports over
+     * its RPC channel, falling back to `ps`. Those two are not the same
+     * quantities:
+     *
+     *   - `cpu` from the child is `(cpuUsage().user + .system) / 1e6` — CPU
+     *     SECONDS CONSUMED SINCE START, a monotonically growing counter. `ps`
+     *     `%cpu` is a percentage. The dashboard column is labelled `CPU %`,
+     *     so an app running for a day would have read `86400`. Observed
+     *     climbing live: 12.845 to 13.297 across twelve seconds of idling.
+     *   - `memory` from the child is `memoryUsage().heapUsed` — the V8 heap.
+     *     `ps` reports RSS, which is what "memory this app uses" means to
+     *     whoever is sizing a host. Observed: 66 MB heap against 149 MB
+     *     resident for the same process.
+     *
+     * Mixing them per-child, depending on which source answered first, gave a
+     * column that was neither quantity. `ps` is asked for both figures here so
+     * that every number under one label means one thing.
+     */
+    async sampleAppMetrics(handle) {
+        const topology = handle.topologyProcesses ?? [];
+        const childNames = handle.supervisor?.getChildNames() ?? [];
+        // Which pids belong to which topology entry. Everything is sampled in a
+        // single `ps` call: sampling one child at a time would fork a process per
+        // child per polling interval, and a monitor that costs more than what it
+        // monitors is its own kind of defect.
+        const pidsByEntry = new Map();
+        for (const topo of topology) {
+            pidsByEntry.set(topo.name, this.resolveTopologyPids(handle, topo));
+        }
+        if (topology.length === 0) {
+            // No declared topology: fall back to the supervisor's children, and
+            // failing that to the handle's own pid.
+            for (const childName of childNames) {
+                const processId = handle.supervisor?.getChildProcessId(childName);
+                const pid = processId ? this.pm.getWorkerHandle(processId)?.pid : undefined;
+                if (typeof pid === 'number')
+                    pidsByEntry.set(childName, [pid]);
+            }
+            if (pidsByEntry.size === 0 && handle.pid) {
+                pidsByEntry.set(handle.name, [handle.pid]);
+            }
+        }
+        const batch = await this.sampleProcessMetricsBatch([...pidsByEntry.values()].flat());
+        let cpu = 0;
+        let memory = 0;
+        const sampled = new Map();
+        for (const [name, pids] of pidsByEntry) {
+            const sample = { cpu: 0, memory: 0 };
+            for (const pid of pids) {
+                const os = batch.get(pid);
+                if (!os)
+                    continue;
+                sample.cpu += os.cpu;
+                sample.memory += os.memory;
+            }
+            sampled.set(name, sample);
+            cpu += sample.cpu;
+            memory += sample.memory;
+        }
+        // Traffic can only come from inside the child; `ps` knows nothing about
+        // it. Its CPU and memory figures are deliberately NOT used — see the note
+        // on this method. Only what a child reports as TRAFFIC is summed: the
+        // `requests`/`errors` a child on an older runtime reports are the call
+        // counters of its wrapper — the supervisor's own health and metrics
+        // calls — and adding them up counted this daemon's questions as the
+        // app's requests (`combineProcessTraffic`).
+        const reports = [];
+        for (const childName of childNames) {
+            const reported = await handle.supervisor?.getChildMetrics(childName);
+            reports.push(reported?.traffic);
+        }
+        const traffic = combineProcessTraffic(reports);
+        // A sample that produced nothing for an app that HAS live processes is a
+        // failed sample, not a measurement of zero — `ps` can time out under load,
+        // and it did: an app was observed reporting 0 MB one second and 143 MB the
+        // next. Overwriting the last known reading with zeros would put the exact
+        // placeholder this method exists to remove back on the dashboard, so the
+        // previous reading is kept instead.
+        const sampledNothing = batch.size === 0 && [...pidsByEntry.values()].some((pids) => pids.length > 0);
+        if (sampledNothing && handle.lastMetrics) {
+            return handle.lastMetrics;
+        }
+        handle.childMetrics = sampled;
+        return traffic
+            ? {
+                cpu,
+                memory,
+                requests: traffic.requests,
+                errors: traffic.serverErrors,
+                traffic,
+                ...(traffic.latency
+                    ? {
+                        latency: {
+                            p50: traffic.latency.p50,
+                            p75: traffic.latency.p75,
+                            p90: traffic.latency.p90,
+                            p95: traffic.latency.p95,
+                            p99: traffic.latency.p99,
+                            mean: traffic.latency.mean,
+                        },
+                    }
+                    : {}),
+            }
+            : { cpu, memory };
+    }
+    /**
+     * Sample several processes in one `ps` call.
+     *
+     * Pids the OS no longer knows are simply absent from the result — an
+     * omission the caller can see, unlike a zeroed reading it cannot tell
+     * apart from an idle process.
+     */
+    async sampleProcessMetricsBatch(pids) {
+        const out = new Map();
+        const unique = [...new Set(pids)];
+        if (unique.length === 0)
+            return out;
+        try {
+            const psOutput = await new Promise((resolve, reject) => {
+                execFile('ps', ['-p', unique.join(','), '-o', 'pid=,rss=,%cpu='], { timeout: 5000 }, (err, stdout) => {
+                    // `ps` exits non-zero when NONE of the pids exist, but still
+                    // prints the ones that do — so stdout is worth reading either way.
+                    if (err && !stdout)
+                        reject(err);
+                    else
+                        resolve(stdout.trim());
+                });
+            });
+            for (const [pid, sample] of parsePsBatch(psOutput))
+                out.set(pid, sample);
+        }
+        catch {
+            // Leave the map empty: no reading is honest, a zero reading is not.
+        }
+        return out;
+    }
+    /**
+     * Sample CPU/memory for a single OS process via `ps`.
+     *
+     * `null` when it could not be read. This used to return
+     * `{ cpu: 0, memory: 0 }` on any failure, and the caller wrote that
+     * straight over `handle.lastMetrics` — so a `ps` that timed out under load
+     * made a running classic-mode app read as idle, indistinguishable from one
+     * that genuinely was. The batch path above already treated absence as
+     * absence; these two now agree.
+     */
     async sampleProcessMetrics(pid) {
         try {
-            const { execFile } = await import('node:child_process');
             const psOutput = await new Promise((resolve, reject) => {
-                execFile('ps', ['-p', String(pid), '-o', 'rss=,%cpu='], { timeout: 5000 }, (err, stdout) => {
-                    if (err)
+                execFile('ps', ['-p', String(pid), '-o', 'pid=,rss=,%cpu='], { timeout: 5000 }, (err, stdout) => {
+                    if (err && !stdout)
                         reject(err);
                     else
                         resolve(stdout.trim());
                 });
             });
-            const [rssKb, cpuPercent] = psOutput.split(/\s+/);
-            return {
-                cpu: parseFloat(cpuPercent ?? '0'),
-                memory: parseInt(rssKb ?? '0', 10) * 1024,
-            };
+            return parsePsLine(psOutput)?.sample ?? null;
         }
         catch {
-            return { cpu: 0, memory: 0 };
+            return null;
         }
     }
-    /** Periodic metrics polling for classic mode processes */
+    /**
+     * Periodic CPU/memory sampling for every managed process.
+     *
+     * Idempotent: re-arming replaces the previous timer rather than stacking a
+     * second one, so `setConfig` can call it on every config reload.
+     */
     startMetricsPolling(interval) {
+        if (this.metricsTimer) {
+            clearInterval(this.metricsTimer);
+            this.metricsTimer = null;
+        }
         this.metricsTimer = setInterval(async () => {
             for (const handle of this.handles.values()) {
                 if (handle.status !== 'online')
                     continue;
                 if (handle.mode === 'classic' && handle.childProcess?.pid) {
                     const m = await this.sampleProcessMetrics(handle.childProcess.pid);
-                    handle.lastMetrics = { ...m, requests: 0, errors: 0 };
+                    // A failed read keeps the previous numbers rather than replacing
+                    // them with zeros — the same rule the bootstrap path below uses.
+                    if (m) {
+                        handle.lastMetrics = {
+                            ...m,
+                            requests: handle.lastMetrics?.requests ?? 0,
+                            errors: handle.lastMetrics?.errors ?? 0,
+                        };
+                    }
                 }
-                else if (handle.mode === 'bootstrap' && handle.pid) {
-                    const m = await this.sampleProcessMetrics(handle.pid);
-                    handle.lastMetrics = {
-                        ...m,
-                        requests: handle.lastMetrics?.requests ?? 0,
-                        errors: handle.lastMetrics?.errors ?? 0,
-                    };
+                else if (handle.mode === 'bootstrap') {
+                    // Every process the app owns, not just the one on the handle.
+                    // As sampled. The counts used to fall back to the previous reading
+                    // whenever a sample said 0 — which kept a stale figure alive
+                    // across a process restart (traffic counts restart from zero with
+                    // the process) and, while `requests` was the wrapper's call count,
+                    // mixed the two meanings in one field.
+                    handle.lastMetrics = await this.sampleAppMetrics(handle);
                 }
             }
         }, interval);
+        this.metricsTimer.unref();
     }
     // ============================================================================
     // Private — Utilities
     // ============================================================================
     toProcessInfo(handle) {
+        // Ghost-online guard. The in-memory `handle.status` reflects the
+        // last event the supervisor observed. If a child died between
+        // the last sweep and now (kill -9 by an operator, OOM kill,
+        // container restart) the handle still claims 'online' until the
+        // next event lands. A cheap signal-0 verification at DTO-mapping
+        // time keeps `omnitron list` honest: when the OS reports the pid
+        // is gone, surface 'crashed' instead of lying to the operator.
+        // `isAlive` covers EPERM as alive (correct — process exists, we
+        // just can't signal it).
+        let status = handle.status;
+        if (status === 'online' && handle.pid != null && !isAlive(handle.pid)) {
+            status = 'crashed';
+        }
         const info = {
             name: handle.name,
             pid: handle.pid,
-            status: handle.status,
+            status,
             cpu: handle.cpu,
             memory: handle.memory,
             uptime: handle.uptime,
@@ -1605,49 +2980,48 @@ export class OrchestratorService extends EventEmitter {
             info.processes = [];
             for (const topo of handle.topologyProcesses) {
                 const isPoolEntry = (topo.instances ?? 1) > 1;
-                let childPid = null;
-                let childStatus = 'stopped';
-                if (isPoolEntry) {
-                    // Pool-managed topology — the supervisor doesn't know about
-                    // these (workers are owned by ProcessPool). Read directly
-                    // from the pool ref we stashed at creation time.
-                    const pool = handle.topologyPools.get(topo.name);
-                    if (pool && pool.size > 0) {
-                        childStatus = 'online';
-                        // Surface the first worker's PID. Pool workers are
-                        // interchangeable so any one is representative; the CLI
-                        // prints "PID" as a quick liveness signal, not a unique
-                        // identifier.
-                        const workerIds = pool.getWorkerIds();
-                        if (workerIds.length > 0) {
-                            const firstId = workerIds[0];
-                            const wh = this.pm.getWorkerHandle(firstId);
-                            childPid = wh?.pid ?? null;
-                        }
-                    }
-                }
-                else {
-                    // Single-instance topology — supervisor manages the child directly.
-                    const childNames = handle.supervisor.getChildNames();
-                    const childName = childNames.find((cn) => cn.includes(topo.name)) ?? topo.name;
-                    const processId = handle.supervisor.getChildProcessId(childName);
-                    if (processId) {
-                        const wh = this.pm.getWorkerHandle(processId);
-                        childPid = wh?.pid ?? null;
-                        childStatus = childPid ? 'online' : 'stopped';
-                    }
-                }
+                // The same ghost-online guard the parent gets a few lines above.
+                // Without it the pool branch reported `online` from the pool's own
+                // bookkeeping, never checking whether the pid it printed alongside
+                // still existed.
+                const { members, childName } = this.resolveTopologyMembers(handle, topo);
+                const alive = members.filter((m) => isAlive(m.pid));
+                const declaredInstances = topo.instances ?? 1;
+                const liveInstances = isPoolEntry
+                    ? (handle.topologyPools.get(topo.name)?.size ?? 0)
+                    : alive.length;
+                const chosen = alive[0] ?? members[0];
+                const childPid = chosen?.pid ?? null;
+                const childStatus = alive.length > 0 ? 'online' : members.length > 0 ? 'crashed' : 'stopped';
+                // The row prints one pid, so the row's clock is that pid's clock.
+                // `startTime` is written when the process id is registered and a
+                // restart registers a new one, so it moves when the process does.
+                // (`IProcessInfo.restartCount` does NOT: it is assigned 0 there and
+                // incremented nowhere. The supervisor keeps the real count, by child
+                // name — reading the field instead would have replaced a wrong
+                // constant with a wrong lookup.)
+                const chosenInfo = chosen ? this.pm.getProcess(chosen.processId) : undefined;
+                const childUptime = typeof chosenInfo?.startTime === 'number' && chosenInfo.startTime > 0
+                    ? Math.max(0, Date.now() - chosenInfo.startTime)
+                    : 0;
+                // A pool is not a supervisor child and nothing counts its restarts.
+                // `null` says so; `0` would be absence written as a value from the
+                // domain, leaving "never restarted" and "not tracked" identical.
+                const childRestarts = isPoolEntry || !childName ? null : (handle.supervisor?.getRestartCount(childName) ?? null);
                 // Derive process type from declarations for backward-compatible DTO
                 const derivedType = topo.transports ? 'server' : isPoolEntry ? 'worker' : 'custom';
+                const sample = handle.childMetrics.get(topo.name);
                 info.processes.push({
                     name: topo.name,
                     type: derivedType,
                     pid: childPid,
                     status: childStatus,
-                    cpu: 0,
-                    memory: 0,
-                    uptime: handle.uptime,
-                    restarts: 0,
+                    cpu: sample?.cpu ?? 0,
+                    memory: sample?.memory ?? 0,
+                    uptime: childUptime,
+                    restarts: childRestarts,
+                    instances: liveInstances,
+                    declaredInstances,
                 });
             }
         }