@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/config/types.d.ts

@@ -4,6 +4,30 @@
  * Declarative configuration for Titan application supervision.
  */
 import type { IRestartPolicy, IBackoffOptions } from '@omnitron-dev/titan-pm';
+import type { CorsOptions } from '@omnitron-dev/titan/netron';
+/**
+ * What an app says about its own health, through the daemon's channel to it.
+ *
+ * `checks` names what was measured, so a verdict other than `healthy` says
+ * WHAT is wrong; the process manager carries them through unchanged
+ * (`classifyWorkerHealth`), and `omnitron health <app>` prints them.
+ */
+export interface AppHealthAnswer {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    checks?: Array<{
+        name: string;
+        status: 'pass' | 'warn' | 'fail';
+        message?: string;
+    }>;
+}
+/**
+ * The app's readiness hook. It is handed the running Application, so it can
+ * ask the app's own health indicators (database, redis, the services it
+ * cannot serve without) — it was called with no arguments, which left a
+ * hook nothing to ask, and every sample app answered a literal
+ * `{ status: 'healthy' }`.
+ */
+export type AppHealthHook = (app: any) => Promise<AppHealthAnswer>;
 export interface IAppDefinition {
     name: string;
     version: string;
@@ -55,32 +79,12 @@ export interface IAppDefinition {
         afterStart?: (app: any) => Promise<void>;
         beforeStop?: (app: any) => Promise<void>;
         afterStop?: () => Promise<void>;
-        onHealthCheck?: () => Promise<{
-            status: 'healthy' | 'degraded' | 'unhealthy';
-        }>;
+        onHealthCheck?: AppHealthHook;
     };
     /** Infrastructure config read from app's config/default.json omnitron section */
     omnitronConfig?: OmnitronAppConfig;
     env?: Record<string, string>;
     cwd?: string;
-    /**
-     * Development mode overrides — applied when running via `omnitron dev`.
-     * Allows apps to customize their behavior in dev mode without
-     * affecting production configuration.
-     *
-     * Note: file watching is configured at the ecosystem level (omnitron.config.ts)
-     * via `IEcosystemAppEntry.watch`, not here — watching is an orchestrator concern.
-     */
-    dev?: {
-        /** Override HTTP port in dev mode */
-        port?: number;
-        /** Override log level in dev mode (default: 'debug') */
-        logLevel?: string;
-        /** Enable source maps (default: true in dev) */
-        sourceMaps?: boolean;
-        /** Additional env vars for dev mode */
-        env?: Record<string, string>;
-    };
     observability?: {
         metrics?: boolean | {
             export?: 'prometheus' | 'statsd';
@@ -115,6 +119,11 @@ export interface OmnitronAppConfig {
             max?: number;
         };
         extensions?: string[];
+        /**
+         * NOT READ. Every app shares one PostgreSQL container with a database
+         * per app; nothing provisions a dedicated instance. Same for `redis`
+         * below.
+         */
         dedicated?: boolean;
     };
     /** Redis. true = shared instance with auto-assigned DB index. */
@@ -131,8 +140,8 @@ export interface OmnitronAppConfig {
     services?: {
         discovery?: boolean;
         notifications?: boolean;
-        /** Cross-app: read priceverse price data from its Redis DB */
-        priceverse?: boolean;
+        /** Cross-app: read pricing price data from its Redis DB */
+        pricing?: boolean;
     };
     /**
      * Custom infrastructure services this app requires.
@@ -219,10 +228,6 @@ export interface IResolvedAppConfig {
         bucket: string;
         forcePathStyle: boolean;
     } | undefined;
-    auth?: {
-        jwtSecret: string;
-        algorithm: string;
-    } | undefined;
     [key: string]: unknown;
 }
 export type StackName = 'dev' | 'test' | 'staging' | 'prod' | string;
@@ -241,7 +246,7 @@ export type StackName = 'dev' | 'test' | 'staging' | 'prod' | string;
 export interface IStackConfig {
     /** Stack deployment type */
     type: 'local' | 'remote' | 'cluster';
-    /** Enable file watching (default: true for dev stacks, false for others) */
+    /** Enable file watching (default: true for every managed app) */
     watch?: boolean;
     /** Nodes for remote/cluster stacks */
     nodes?: IStackNode[];
@@ -266,11 +271,18 @@ export interface IStackConfig {
      * serviceOverrides: {
      *   // All apps using 'bitcoin' connect to this bare-metal node:
      *   bitcoin: { external: { host: '10.0.1.5', ports: { rpc: 8332 } } },
-     *   // Only paysys's monero uses a custom image:
-     *   'paysys/monero-daemon': { docker: { image: 'custom-monerod:latest' } },
+     *   // Only payments's monero uses a custom image:
+     *   'payments/monero-daemon': { docker: { image: 'custom-monerod:latest' } },
      * }
      */
     serviceOverrides?: Record<string, import('../infrastructure/types.js').IServiceOverride>;
+    /**
+     * What this stack demands of what reaches it. `mode: 'required'` — the
+     * stack takes releases only (`omnitron release build`, then `stack start
+     * --release <id>`); absent — it deploys the working tree, as a development
+     * stack does. See `StackReleaseRequirements`.
+     */
+    release?: import('../release/manifest.js').StackReleaseRequirements;
 }
 /**
  * Stack node — a machine participating in a remote or cluster stack.
@@ -301,15 +313,45 @@ export interface ISSHConfig {
     /** SSH port (default: 22) */
     port?: number;
 }
+/**
+ * A stack-given environment value: written, or the name of a key in the
+ * daemon's vault, resolved when the stack starts.
+ */
+export type StackEnvValue = string | {
+    readonly secret: string;
+};
 export interface IStackSettings {
     /** Redis DB offset for this stack (stacks get non-overlapping DB ranges) */
     redisDbOffset?: number;
     /** Docker container name prefix (default: `${project}-${stack}`) */
     containerPrefix?: string;
-    /** Custom environment variables injected into all apps in this stack */
-    env?: Record<string, string>;
+    /**
+     * Environment variables every app in this stack is given, local or remote.
+     * A value is written, or names a key in the daemon's vault. See
+     * `project/stack-env.ts`.
+     */
+    env?: Record<string, StackEnvValue>;
+    /**
+     * Environment variables ONE app is given, by its name — a secret only that
+     * app should hold (a KMS master key) goes here, not in `env`. Wins over
+     * `env`. Naming an app the stack does not run refuses the start.
+     */
+    appEnv?: Record<string, Record<string, StackEnvValue>>;
     /** Override log level for all apps in this stack */
     logLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+    /**
+     * The maintenance lock a remote deployment holds at the stack's gateway
+     * (`services/maintenance-lock.ts`): open pages are warned `noticeSeconds`
+     * ahead (default 60), then everyone is held until the deployed platform
+     * answers through the gateway; `etaSeconds` (default 180) is what callers
+     * are told to wait. `disabled` deploys unheld — for an emergency, where a
+     * minute of warning costs more than a restart under the users.
+     */
+    maintenance?: {
+        noticeSeconds?: number;
+        etaSeconds?: number;
+        disabled?: boolean;
+    };
     /** Override infrastructure ports for this stack (avoids port conflicts between stacks) */
     portOffsets?: {
         /** Offset added to postgres port (default: 0 for first stack) */
@@ -454,9 +496,10 @@ export interface IProcessEntry {
     restartPolicy?: IRestartPolicy;
     /** Environment variables specific to this process */
     env?: Record<string, string>;
-    /** Custom HTTP routes (only relevant if transports.http is set) */
+    /** Custom HTTP routes after reserved Netron endpoints (only with transports.http). */
     customRoutes?: Array<{
-        method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE';
+        /** Literal pathname with optional * wildcards; query strings are excluded. */
         pattern: string;
         handler: (req: Request) => Promise<Response | null>;
     }>;
@@ -468,9 +511,7 @@ export interface IProcessEntry {
         afterStart?: (app: any) => Promise<void>;
         beforeStop?: (app: any) => Promise<void>;
         afterStop?: () => Promise<void>;
-        onHealthCheck?: () => Promise<{
-            status: 'healthy' | 'degraded' | 'unhealthy';
-        }>;
+        onHealthCheck?: AppHealthHook;
     };
     /** Observability config for this process */
     observability?: {
@@ -531,7 +572,13 @@ export interface IProcessTopologyEntry {
 export interface IHttpTransportConfig {
     port: number;
     host?: string;
-    cors?: boolean;
+    /**
+     * `true` reflects whatever `Origin` arrived; an object restricts it. Widened
+     * from `boolean` so a deployment can pass the allow-list it already has —
+     * the transport has taken `boolean | CorsOptions` since 46af7aba, and this
+     * type was the narrower of the two saying different things about one field.
+     */
+    cors?: boolean | CorsOptions;
     requestTimeout?: number;
     keepAliveTimeout?: number;
     headersTimeout?: number;
@@ -582,7 +629,14 @@ export interface IEcosystemAppEntry {
     /** Startup timeout in ms (overrides global resources.timeout). Useful for apps with slow init (e.g. blockchain wallet connections) */
     startupTimeout?: number;
     /**
-     * Watch configuration for dev mode (`omnitron dev`).
+     * Watch configuration. Watching is on for every managed app by default —
+     * there is no stack-based gating; `omnitron up --no-watch` (or
+     * `OMNITRON_NO_WATCH=1`) turns it off daemon-wide, `watch: false` per app.
+     *
+     * Bootstrap-mode apps are watched through esbuild's import graph instead of
+     * `fs.watch`. `false` disables both engines; directory/ignore/debounce
+     * settings configure only fs.watch. Disabling cancels pending automatic
+     * restarts and waits for watchers to stop; manual restarts still work.
      *
      * - `string`: directory to watch (relative to cwd or absolute)
      * - `IWatchConfig`: full watch configuration
@@ -598,7 +652,15 @@ export interface IWatchConfig {
     directory: string;
     /** Additional directories to watch */
     include?: string[];
-    /** Glob patterns to ignore (added to defaults: node_modules, dist, .git, etc.) */
+    /**
+     * Path SEGMENTS to ignore, added to the defaults (node_modules, dist, .git,
+     * test, __tests__ and the rest — see `IGNORE_PATTERNS` in `file-watcher.ts`).
+     *
+     * Whole segments, compared for equality — NOT globs. `['test']` works;
+     * `['test/**']` matches nothing. This said "glob patterns" while the
+     * implementation compared segments, so the one form an operator would
+     * reach for first was the one that silently did nothing.
+     */
     ignore?: string[];
     /** Debounce interval in ms (default: 300) */
     debounce?: number;
@@ -608,8 +670,22 @@ export interface IDaemonConfig {
     socketPath: string;
     /** TCP port for remote omnitron ↔ omnitron fleet RPC */
     port: number;
-    /** TCP host for remote fleet RPC (use '0.0.0.0' for remote access) */
+    /**
+     * Bind address for the daemon's TCP (fleet), HTTP and WebSocket servers.
+     * Default `127.0.0.1`. Set `'0.0.0.0'` — or a specific interface — to
+     * accept connections from other hosts; the value is used literally.
+     */
     host: string;
+    /**
+     * The address slaves should dial to reach this master.
+     *
+     * Only consulted when provisioning a slave, and only needed when `host`
+     * cannot answer the question — which is whenever it is `0.0.0.0`, and
+     * always when the master is behind NAT or a load balancer. Nothing else
+     * can know that address: the daemon sees its own bind, not the path back
+     * to it.
+     */
+    advertiseHost?: string;
     /** HTTP port for webapp portal ↔ daemon Netron RPC */
     httpPort: number;
     pidFile: string;
@@ -635,7 +711,21 @@ export interface IDaemonConfig {
      */
     cluster?: {
         enabled: boolean;
-        discovery: 'redis' | 'static';
+        /**
+         * NOT READ. Peers come from the fleet registry in Postgres —
+         * `FleetService.listNodes()` — regardless of what this says, and no
+         * code path consults either this field or `peers`.
+         *
+         * Kept because removing them from a published type breaks every config
+         * that sets them, and because they state a real intent: a static peer
+         * list would let a cluster form without Postgres, which is the one
+         * dependency the fleet registry cannot do without. Until that exists,
+         * an operator choosing between 'redis' and 'static' is making a
+         * decision with no effect — so say so here rather than let them find
+         * out from behaviour that does not change.
+         */
+        discovery?: 'redis' | 'static';
+        /** NOT READ — see `discovery`. */
         peers?: string[];
         electionTimeout?: {
             min: number;
@@ -656,6 +746,51 @@ export interface IDaemonConfig {
     auth?: {
         jwtSecret?: string;
     };
+    /**
+     * Transport-level rate limiting for the daemon's HTTP RPC surface.
+     *
+     * Complements the per-account lockout in AuthService: the lockout stops
+     * password guessing against one account, this caps overall request volume
+     * so the control plane cannot be flooded.
+     *
+     * Note on deployment: the daemon binds loopback and nginx fronts it, so
+     * every request arrives from 127.0.0.1 unless `trustProxy` is enabled —
+     * meaning `maxRequests` behaves as a shared budget in that topology.
+     * `trustProxy` is off by default because the forwarded header is
+     * client-controlled unless the proxy is known to overwrite it.
+     */
+    /**
+     * Largest WebSocket frame the daemon will accept, in bytes. Default: 8 MB.
+     *
+     * The WebSocket transport takes no rate limit — this is the only bound it
+     * offers — and unset it inherits `ws`'s 100 MB default.
+     */
+    wsMaxPayload?: number;
+    /**
+     * Interface the console's nginx publishes on. Default: '127.0.0.1'.
+     *
+     * The daemon binds its own HTTP transport to loopback, but the console
+     * container published on every interface and proxies `/netron/` straight
+     * to it — so the RPC surface was reachable from the network, and the
+     * `allowAnonymous` methods on it were reachable without credentials.
+     *
+     * Set to '0.0.0.0' only where something else authenticates the traffic.
+     */
+    consoleBindHost?: string;
+    httpRateLimit?: {
+        /** Default: true. */
+        enabled?: boolean;
+        /** Window length in ms. Default: 60_000. */
+        windowMs?: number;
+        /** Requests per client key per window. Default: 3_000. */
+        maxRequests?: number;
+        /** Requests across all clients per window. Default: 6_000. */
+        globalMaxRequests?: number;
+        /** Trust X-Forwarded-For / X-Real-IP for the client key. Default: false. */
+        trustProxy?: boolean;
+        /** Client keys exempt from limiting. */
+        whitelist?: string[];
+    };
     /** Health monitor worker configuration */
     healthMonitor?: {
         /** Check interval in ms (default: 30_000) */
@@ -676,8 +811,33 @@ export interface IDaemonConfig {
         retentionDays?: number;
         /** Uptime bar bucket interval in ms (default: 86_400_000 = 24h) */
         uptimeIntervalMs?: number;
+        /**
+         * How long the worker gets to boot before the daemon gives up, ms
+         * (default: 120_000).
+         *
+         * The unit of work is a whole Titan application: a DI container, a module
+         * graph and a PG pool. Managed applications are given two to five minutes
+         * for the same thing; this was 30 seconds, and on a loaded host it expired
+         * on every attempt — so the fleet ran on the daemon's fallback checks
+         * indefinitely while the worker was restarted and killed, over and over.
+         */
+        startupTimeoutMs?: number;
     };
 }
+/** A platform's receiver of omnitron's critical alerts — see `IEcosystemConfig.monitoring.alertSink`. */
+export interface IAlertSink {
+    /** The app, by its name within a stack: `main` for `sample/dev/main`. */
+    app: string;
+    service: string;
+    method: string;
+    /**
+     * How the alert names where it came from — `<project>/<stack>`. Absent, the
+     * daemon says the stack it runs the sink in. A node runs its apps in a stack
+     * of its own (`deployed`), so its deployment writes the master's name for
+     * it: the bell says `sample/test`, not `sample/deployed`.
+     */
+    host?: string;
+}
 export interface IEcosystemConfig {
     /** Project display name (shown in webapp, CLI) */
     project?: string;
@@ -718,12 +878,35 @@ export interface IEcosystemConfig {
             interval: number;
             retention: number;
         };
+        /**
+         * Where this project's platform takes omnitron's critical alerts: a
+         * service method in one of its apps, which each daemon calls — through
+         * the same path as `omnitron exec`, its own socket into the app's
+         * process — on the stacks of this project it runs, and repeats until the
+         * call lands. Only an app in bootstrap mode: the HTTP branch of `exec`
+         * is never used for this.
+         *
+         *   alertSink: { app: 'main', service: 'OpsAlerts', method: 'raise' }
+         */
+        alertSink?: IAlertSink;
     };
     logging: {
         level: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+        /** Rotated log FILES on disk. Says nothing about the database table. */
         maxSize: string;
+        /** Rotated log FILES on disk. Says nothing about the database table. */
         maxFiles: number;
         compress: boolean;
+        /**
+         * Days of log history kept in the `logs` table. 0 disables pruning.
+         *
+         * Distinct from `maxSize`/`maxFiles`, which govern the rotated files and
+         * read like retention without being it. The table had none: 22.5 million
+         * rows and 13 GB on the development host, growing at whatever rate the
+         * platform logs, on a machine that has already lost its database and its
+         * containers to a full disk once.
+         */
+        databaseRetentionDays: number;
     };
 }
 export type AppStatus = 'stopped' | 'starting' | 'online' | 'stopping' | 'errored' | 'crashed';
@@ -753,30 +936,89 @@ export interface SubProcessInfoDto {
     status: AppStatus;
     cpu: number;
     memory: number;
+    /** Uptime of the process whose pid this row prints — not the app's. */
     uptime: number;
-    restarts: number;
+    /**
+     * Restarts of this child, or `null` when nothing counts them.
+     *
+     * The supervisor maintains a count per child name. A pool is not a
+     * supervisor child, so for a pool row the honest answer is "unknown" —
+     * reporting `0` would leave "never restarted" indistinguishable from "not
+     * tracked", which is the shape of defect this field used to have for every
+     * child: it was the literal `0`.
+     */
+    restarts: number | null;
+    /**
+     * Live worker count. 1 for a supervisor-managed child; the pool's actual
+     * size for an entry declaring `instances > 1`.
+     */
+    instances: number;
+    /**
+     * What the topology asked for. Reported alongside `instances` so a pool
+     * that has drifted from its declaration is visible without going and
+     * reading the bootstrap file — a pool grown past its configuration still
+     * reports itself as healthy, since it does have workers.
+     */
+    declaredInstances: number;
 }
 export interface DaemonStatusDto {
     version: string;
+    /**
+     * What this daemon's `dist` was compiled from (`dist/BUILD.json`); `null`
+     * when it runs from source or from a build nobody stamped. Absent from
+     * daemons on older builds. `version` is the package's and names no commit.
+     */
+    build?: {
+        commit: string;
+        dirty: boolean;
+        builtAt: string;
+    } | null;
     pid: number;
     uptime: number;
     apps: ProcessInfoDto[];
     totalCpu: number;
+    /** Apps and daemon together — `appsMemory + daemonMemory`. */
     totalMemory: number;
+    /** The daemon process's own RSS, bytes. Absent from daemons on older builds. */
+    daemonMemory?: number;
+    /** Every managed app's memory, summed, bytes. Absent from daemons on older builds. */
+    appsMemory?: number;
 }
 export interface AggregatedMetricsDto {
     timestamp: number;
     apps: Record<string, {
         cpu: number;
         memory: number;
+        /**
+         * Whether the app's processes reported what their transports answered.
+         * `not-reported` — no server process, or a runtime that does not say —
+         * is not zero traffic, and the fields below are then absent.
+         */
+        traffic: 'measured' | 'not-reported';
+        /** Requests answered since the process started, monitor probes excluded. */
         requests?: number;
+        /** Of those, 5xx. */
         errors?: number;
+        /** Of those, 4xx — the caller's. */
+        clientErrors?: number;
+        /** `/health` and `/metrics` polls. */
+        probes?: number;
+        /**
+         * Of `requests`, those to a method that holds its caller (a long poll):
+         * their duration is a wait, and is not in `latency`. Absent when the
+         * app's runtime does not count them.
+         */
+        held?: number;
+        /** Over the last `windowMs`, held requests excluded; `null` when nothing finished in it. */
         latency?: {
             p50: number;
             p95: number;
             p99: number;
             mean: number;
-        };
+            max: number;
+            count: number;
+            windowMs: number;
+        } | null;
     }>;
     totals: {
         cpu: number;
@@ -785,7 +1027,25 @@ export interface AggregatedMetricsDto {
 }
 export interface AggregatedHealthDto {
     timestamp: number;
+    /** The worst of the daemon's own verdict and every app's. */
     overall: 'healthy' | 'degraded' | 'unhealthy';
+    /**
+     * The daemon's own indicators — memory, docker, apps, event-loop stalls.
+     *
+     * These were returned AS `apps`, one «app» per indicator, and the apps
+     * themselves were never asked: `omnitron health` printed «Apps: 5 healthy»
+     * beside six apps, and `omnitron health main` printed the daemon's memory.
+     * Absent when the question named one app.
+     */
+    daemon?: {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        indicators: Array<{
+            name: string;
+            status: 'pass' | 'warn' | 'fail';
+            message?: string;
+        }>;
+    };
+    /** Each managed app, as the app itself answered — every child process, not the first. */
     apps: Record<string, {
         status: 'healthy' | 'degraded' | 'unhealthy';
         checks: Array<{
@@ -802,6 +1062,90 @@ export interface LogEntryDto {
     message: string;
     data?: Record<string, unknown>;
 }
+/**
+ * Crash diagnostic context attached to `AppDiagnosticsDto` when
+ * the app died. Mirrors `LastExitInfo` on the orchestrator side
+ * — exposed verbatim so the CLI (and future Console UI) can
+ * render it without re-modelling the shape.
+ */
+export interface LastExitDto {
+    /** ISO timestamp of the exit. */
+    atIso: string;
+    /** Exit code (null when killed by a signal). */
+    code: number | null;
+    /** POSIX signal name when killed by signal (e.g. 'SIGKILL'). */
+    signal: string | null;
+    /** True for deliberate terminate() calls, false for crashes. */
+    expected: boolean;
+    /**
+     * Last N stderr lines captured before exit — the single most
+     * useful diagnostic when an app dies mid-bootstrap.
+     */
+    stderrTail: string[];
+    /** Supervisor-provided summary (typically the underlying Error). */
+    message?: string;
+}
+/**
+ * Per-child diagnostic surface — T#66. A bootstrap-mode app can
+ * spawn multiple children (http, workers, schedulers); operators
+ * need to see each child's identity, OS pid, uptime, listen port,
+ * and the service it exposes. Pre-T#66 `services: string[]`
+ * collapsed all children to a single "name@version" string,
+ * indistinguishable when several children expose `BootstrapApp`
+ * (the default Titan Application service name). The flat list
+ * also hid which child crashed inside a multi-child app.
+ */
+export interface ChildDiagnosticsDto {
+    /** Supervisor name (e.g. "http", "captcha-generator"). */
+    name: string;
+    /** OS process id (or null if the child hasn't started / has exited). */
+    pid: number | null;
+    /** Service the child exposes via Netron, e.g. "BootstrapApp". */
+    serviceName?: string;
+    /** Semantic version reported by the service. */
+    serviceVersion?: string;
+    /** Seconds since the child's last successful start. */
+    uptimeSeconds?: number;
+    /** Titan-PM internal processId — useful for cross-referencing daemon logs. */
+    processId?: string;
+    /** Resident memory in bytes, from the sample the app's total is summed from; absent when not sampled. */
+    rss?: number;
+}
+/**
+ * A topology entry that runs as a pool (`instances > 1`), and its workers.
+ *
+ * Pool workers are not supervisor children, so `children` never had them:
+ * `omnitron inspect storage` listed the http process and neither of the two
+ * transform workers.
+ */
+export interface PoolDiagnosticsDto {
+    /** Topology entry name, e.g. "transform". */
+    name: string;
+    /** Workers the topology declares. */
+    declaredInstances: number;
+    /** Resident memory of all the pool's workers together, bytes; absent when not sampled. */
+    rss?: number;
+    workers: Array<{
+        pid: number | null;
+        processId: string;
+        uptimeSeconds?: number;
+    }>;
+}
+/**
+ * Where to find on-disk diagnostics for this app. Surfaced by
+ * `omnitron inspect` so an operator landing on a hot incident
+ * doesn't need to grep the source tree to learn the log layout.
+ * Project-mode apps live at
+ * `~/.omnitron/projects/{project}/{stack}/logs/{app}/`; standalone
+ * apps live at `~/.omnitron/logs/{app}/`. The exact paths are
+ * resolved by `LogManager.getLogFilePath`.
+ */
+export interface LogPathsDto {
+    /** Absolute path to app.log (stdout + non-error stderr lines). */
+    app: string;
+    /** Absolute path to error.log (level≥50 lines). */
+    error: string;
+}
 export interface AppDiagnosticsDto {
     name: string;
     pid: number | null;
@@ -811,11 +1155,39 @@ export interface AppDiagnosticsDto {
         heapTotal: number;
         external: number;
         arrayBuffers: number;
+        /** The app's: every process it runs, children and pool workers, as `list` sums it. */
         rss: number;
     };
     uptime: number;
     restarts: number;
+    /**
+     * @deprecated T#66 — use `children[].serviceName` for the
+     *   per-child breakdown. This flat list is kept for backwards
+     *   compatibility with older webapp builds; new consumers
+     *   should read `children`.
+     */
     services: string[];
+    /**
+     * Per-child diagnostic surface (T#66). Empty for non-bootstrap
+     * apps; populated for bootstrap-mode apps with one entry per
+     * supervisor child.
+     */
+    children: ChildDiagnosticsDto[];
+    /** The app's worker pools; absent from daemons that predate the field. */
+    pools?: PoolDiagnosticsDto[];
+    /**
+     * Absolute log paths (T#66). Surfaces the on-disk diagnostic
+     * layout so operators don't need to memorise the project-mode
+     * vs standalone path conventions.
+     */
+    logPaths: LogPathsDto;
     config: Record<string, unknown>;
+    /**
+     * Populated when the app's last lifecycle event was a death
+     * (status='errored' or 'crashed'). Cleared the moment a fresh
+     * start brings the app back online — see
+     * `AppHandle.clearLastExit`.
+     */
+    lastExit?: LastExitDto;
 }
 //# sourceMappingURL=types.d.ts.map