@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/services/project.service.d.ts

@@ -12,28 +12,150 @@
  * - Remote/cluster stacks have slave daemons that collect data locally
  *   and sync to master when connectivity is available
  */
-import type { ILogger } from '@omnitron-dev/titan/module/logger';
+import { type ILogger, type ILoggerModule } from '@omnitron-dev/titan/module/logger';
+import type { DaemonStateStore } from '../daemon/daemon-state-store.service.js';
+import type { SecretsService } from './secrets.service.js';
+import type { AuditService } from './audit.service.js';
 import { EventEmitter } from '@omnitron-dev/eventemitter';
 import type { OrchestratorService } from '../orchestrator/orchestrator.service.js';
 import type { IEcosystemConfig } from '../config/types.js';
+import type { InfrastructureConfig } from '../infrastructure/types.js';
 import type { IProjectInfo, IStackInfo, StackRuntime, IProjectRequirements } from '../shared/dto/project.js';
 import { StackInfrastructureManager } from '../infrastructure/stack-infra-manager.js';
-import type { FleetService } from './fleet.service.js';
+import { SlaveConnector } from '../cluster/slave-connector.js';
+import { type DeployProgressRecord } from './remote-deployer.service.js';
 import type { SyncService } from './sync.service.js';
+import { type SSHTarget } from '../execution/execution.service.js';
+/**
+ * The infrastructure a stack actually gets: the ecosystem's, plus its own.
+ *
+ * Shallow for the top-level keys — a stack that declares `postgres` replaces
+ * the ecosystem's — and merged for `services`, because those are named
+ * things and a stack adding one must not remove the rest.
+ */
+export declare function mergeInfrastructure(ecosystemConfig: {
+    infrastructure?: InfrastructureConfig | undefined;
+}, stackConfig: {
+    infrastructure?: Partial<InfrastructureConfig> | undefined;
+}): InfrastructureConfig | undefined;
+/**
+ * Who asked for this stack to start.
+ *
+ * Three callers reach `startStack`, and only one of them is a person: the
+ * RPC surface an operator (or the CLI, or an MCP tool) goes through, the
+ * boot resume, and the reconciler that retries an enabled stack after the
+ * daemon restarts. The audit row carries this so «last deployment» stops
+ * meaning «last deployment a human typed».
+ */
+export type StackStartSource = 'operator' | 'boot' | 'auto-resume' | 'unknown';
+/**
+ * The stack's frontend could not be put on a node, twice.
+ *
+ * Its own class because it ends the deployment where every other failure to
+ * bring up a node's infrastructure is logged and deployed past: nothing on
+ * the node has changed yet, and a deployment that continued would recreate
+ * the gateway without a web root — see `shipStackStatics`.
+ */
+export declare class FrontendNotDeliveredError extends Error {
+    constructor(host: string, cause: string);
+}
+/**
+ * Where an on-node attestation's probes got the accounts they sign in with.
+ *
+ *   provisioned      the stack allows it and the release's producer can: the
+ *                    run created them and removed them (`--provision`);
+ *   not-declared     the stack does not declare `release.attest.provision`;
+ *   producer-cannot  it does, and the release was built before its producer
+ *                    knew the flag.
+ *
+ * In the latter two the probes that need a signed-in person say NOT RUN,
+ * which is their floor — and the answer says why, so a reader does not look
+ * for the cause in the release.
+ */
+export type AttestAccounts = 'provisioned' | 'not-declared' | 'producer-cannot';
+/** What `ProjectService` takes beyond its three required collaborators. */
+export interface ProjectServiceOptions {
+    /** Slave→master replication, handed to the lazily built mesh connector. */
+    readonly syncService?: SyncService;
+    /**
+     * The vault, for the secrets a stack's service overrides name. Without it
+     * the references travel unresolved and say so.
+     */
+    readonly secrets?: import('./secrets.service.js').SecretsService;
+    /**
+     * The audit trail, for the one fact an operator asks this service about
+     * afterwards: what was deployed and when.
+     *
+     * Taken HERE rather than left to the RPC layer because the RPC layer is not
+     * the only caller. Measured on 2026-09-21: `omnitron audit` knew about one
+     * deployment of `sample/test` in twenty-four hours; the daemon log knew about
+     * eight. The seven it missed were the boot resume and the reconciler, both
+     * of which call `startStack` directly — so the trail recorded the
+     * deployments a human typed and none of the ones the daemon decided on,
+     * which is the wrong half to have.
+     */
+    readonly audit?: import('./audit.service.js').AuditService;
+}
 export declare class ProjectService extends EventEmitter {
     private readonly logger;
     private readonly orchestrator;
-    private readonly fleetService?;
-    private readonly syncService?;
     private readonly registry;
     private readonly configRegistry;
     private readonly stackStates;
     private readonly infraManager;
     private slaveConnector;
     private readonly deployer;
-    constructor(logger: ILogger, orchestrator: OrchestratorService, fleetService?: FleetService | undefined, syncService?: SyncService | undefined);
+    private resumeTimer;
+    private readonly resumeBackoff;
+    private dockerWasAvailable;
+    private readonly syncService;
+    private readonly secrets;
+    private readonly audit;
+    constructor(logger: ILogger, orchestrator: OrchestratorService, daemonStateStore: import('../daemon/daemon-state-store.service.js').DaemonStateStore, 
     /**
-     * Get or create the SlaveConnector (lazy — only created when first remote/cluster stack starts).
+     * Optional local collaborators — by NAME. Both daemon roles have a vault. These were four more
+     * positional parameters, and the daemon's factory passed them through an
+     * `any`: `new ProjectService(logger, orchestrator, dStore, fleet,
+     * undefined, secrets, audit)`. A slot removed or reordered there moves
+     * every later argument into its neighbour's place and still compiles. The
+     * fourth had been read by nothing since the connector stopped writing the
+     * fleet table (f785d7f0); it went, and the rest became names.
+     */
+    options?: ProjectServiceOptions);
+    /**
+     * Adopt the daemon's mesh connector.
+     *
+     * There must be ONE of these per master. It holds a live connection — and,
+     * for a node whose daemon port is firewalled, an SSH tunnel — per node, so
+     * a second instance means a second connection to every node and two
+     * independent pulls of the same buffer, racing over which one acks an
+     * entry the other has not ingested yet.
+     *
+     * The daemon builds it, because the daemon is what knows how to reach a
+     * node: the SSH credentials live in the node registry's vault, not here.
+     * Absent one, the lazy fallback below keeps the behaviour this class had
+     * on its own, which is what the tests construct.
+     */
+    setSlaveConnector(connector: SlaveConnector): void;
+    /**
+     * How to reach a host the node registry knows about.
+     *
+     * A stack says which host; the registry says how to reach it — the user,
+     * the port, and the credential, which is in the daemon's vault because a
+     * config file in a repository is not where those go. Wired by the daemon,
+     * which is the side that has both.
+     */
+    setNodeCredentialResolver(resolve: (host: string) => Promise<SSHTarget | null>): void;
+    private resolveNodeCredentials;
+    /** A deploy target for a stack node, with the registry filling the gaps. */
+    private targetForStackNode;
+    /**
+     * Get or create the SlaveConnector.
+     *
+     * Created lazily here only when the daemon has not handed one over —
+     * historically this was the sole owner, and it created one when the first
+     * remote or cluster stack started. That is also why a node with no stack
+     * on it was never connected to at all: nothing else ever asked.
      */
     private getSlaveConnector;
     /**
@@ -41,9 +163,39 @@ export declare class ProjectService extends EventEmitter {
      * Keeps in-memory state consistent (unlike creating a separate ProjectRegistry).
      */
     autoDetectProject(cwd?: string): IProjectInfo | null;
+    /**
+     * What each app on each node is doing, for a console that polls.
+     *
+     * A stack deployment publishes progress as it goes — transferring,
+     * installing, the message naming the step that failed — and the console
+     * polls. Without somewhere for an event to wait, those two never met: a
+     * deployment that takes a quarter of an hour showed one row reading
+     * `deploying` from the first second to the last, and every event that said
+     * WHERE it was reached a handler that re-emitted it to nobody.
+     */
+    getDeployProgress(): DeployProgressRecord[];
     listProjects(): IProjectInfo[];
     getProject(name: string): IProjectInfo;
-    addProject(name: string, projectPath: string): IProjectInfo;
+    addProject(name: string, projectPath: string): Promise<IProjectInfo & {
+        reread?: {
+            redefined: number;
+        };
+    }>;
+    /**
+     * Read a registered project's config again, and give every app its running
+     * local stacks supervise the definition that config now describes.
+     *
+     * The processes are not restarted here: each takes its new definition on
+     * its next start (`AppHandle.redefine`) — which a deployment asks for per
+     * app, only where something changed (`decideRedeploy`). Returns how many
+     * running apps were redefined.
+     */
+    rereadProject(name: string): Promise<number>;
+    /** Refresh only local container monitoring from the current validated project config. */
+    refreshInfrastructureOwnership(projectName: string, stackName: string): Promise<{
+        released: string[];
+        adopted: string[];
+    }>;
     updateProject(name: string, data: {
         path?: string;
     }): IProjectInfo;
@@ -62,13 +214,295 @@ export declare class ProjectService extends EventEmitter {
     private deleteUserStack;
     listStacks(projectName: string): IStackInfo[];
     getStack(projectName: string, stackName: string): IStackInfo;
-    startStack(projectName: string, stackName: string): Promise<IStackInfo>;
+    /**
+     * Stack starts in flight, by `project/stack`.
+     *
+     * `stackStates` records `starting`, and it is written AFTER the config is
+     * loaded and the short-circuits above have run — so two callers that arrive
+     * together both see no state and both proceed. Measured on the test stack:
+     * the daemon's own `startProjectStacks` on boot and an operator's
+     * `omnitron stack start sample test` landed within twenty seconds of each
+     * other, and ran the whole remote deployment TWICE, concurrently.
+     *
+     * That is not merely wasteful. The artifact build rebuilds shared packages
+     * whose `build` script is `rm -rf dist && tsc`, so one pass emptied
+     * `@omnitron-dev/titan-database/dist` while the other compiled `@sample/main`
+     * against it:
+     *
+     *     src/modules/rbac/rls-schema.ts(53,41): error TS2307: Cannot find
+     *     module '@omnitron-dev/titan-database/rls'
+     *
+     * — an error about a subpath that exists, reported against a build that is
+     * correct, which sends the reader to the wrong package entirely. Building
+     * the same app by hand a minute later exits zero.
+     *
+     * A second caller gets the FIRST call's promise rather than a refusal:
+     * asking for a stack that is already being started should end when it has
+     * been started, which is what the caller meant.
+     */
+    private readonly startsInFlight;
+    startStack(projectName: string, stackName: string, opts?: {
+        source?: StackStartSource;
+        allowDirty?: boolean;
+        release?: string;
+        reinstall?: boolean;
+    }): Promise<IStackInfo>;
+    /**
+     * One start of a stack, recorded however it ends.
+     *
+     * The row was written on the success path only — inside the `try` at the
+     * end of `runStackStart` — so a start that was refused or failed left
+     * nothing in the trail. Measured on the master 2026-09-23: 178 rows since
+     * the trail began (2026-09-20 15:37Z), not one of them a failure, against
+     * the log's eight operator starts that threw — five dirty-tree refusals
+     * (09-22 04:37:24 … 08:27:49), a release refused for a failed gate
+     * (15:12:41), «sample/test takes releases only» (15:32:43), and the
+     * deployment of 21:19:02 that failed on 6 of 6 apps, followed at 21:20:37
+     * by the redeploy the trail DID record, alone, as if it had been the only
+     * attempt.
+     *
+     * Written as `stack.start.failed`, not as `stack.start` with a flag. Two
+     * readers take every `stack.start` row as a deployment that happened —
+     * `ReleaseRpcService.deployments` (the console's «last deployed») and
+     * `lastDeployedAt` (the attestation freshness refusal) — and a refused
+     * deployment is not one; filed under the same action it would become the
+     * stack's «last deployment». Same shape as `node.upgrade.failed`.
+     *
+     * A remote stack that a restart re-attaches is left out both ways: it
+     * deploys nothing, and the reconciler re-asks a node that does not answer
+     * every few minutes — rows about looking, not about changing anything.
+     */
+    private startStackOnce;
+    private runStackStart;
     stopStack(projectName: string, stackName: string): Promise<IStackInfo>;
-    getStackStatus(projectName: string, stackName: string): StackRuntime;
+    /**
+     * What is running in this stack, asked of whoever is running it.
+     *
+     * For a remote stack that is the node. This counted `this.orchestrator
+     * .list()` — the MASTER's process table — which lists none of a remote
+     * stack's applications, so `stack runtime sample test` answered
+     * `totalApps: 0, onlineApps: 0, connectedNodes: 0` while `stack status`
+     * listed six apps online from the same node, three times in three seconds
+     * (measured 2026-09-22). The JSON surface is the one a script and a
+     * dashboard read.
+     *
+     * The sibling readers were taught this already — `listStacks`, `getStack`
+     * and `startStack` all pass through `withRemoteAppStatuses`, and the
+     * comment beside one of them names the same symptom: «only 0/6 apps came
+     * online» about six that were running. The fix reached three callers of
+     * four.
+     */
+    getStackStatus(projectName: string, stackName: string): Promise<StackRuntime>;
+    /**
+     * Each configured node paired with what it last said about its own
+     * replication — the input the summary is counted from.
+     *
+     * Matching is by `host` and effective `port`, the same rule the node list
+     * below uses; a node with no connection contributes `null`, which the
+     * summary reads as «not heard from» rather than «nothing pending».
+     */
+    private nodesWithSync;
+    /** Where releases are kept on this master — `~/.omnitron/releases`. */
+    private releaseStore;
+    /**
+     * Take a release for a stack, or say why not.
+     *
+     * Three things are checked, each refusing by name. The stack's own
+     * requirements (`decideStackRelease`): every gate the release recorded
+     * passed, the floor it names is among them, every app the stack runs is
+     * carried. The disk: the stack definition is still evaluated HERE — the
+     * project's config keeps machine-local state beside itself (a generated
+     * dev signing key, an admin's saved coverage), so it cannot be run from a
+     * snapshot — and therefore this directory must be exactly the release's
+     * project commit, or the definition deployed is not the release's. And
+     * the statics: a stack whose gateway serves a bundle takes it from the
+     * release, built for this stack, or not at all.
+     */
+    /**
+     * Would this release be taken by this stack? Asked without deploying it.
+     *
+     * The console shows this before an operator presses Deploy, and it is the
+     * DEPLOYMENT'S OWN decision — the same `admitRelease` a start runs, with
+     * nothing skipped and nothing re-implemented. A second copy of these rules
+     * in the browser would drift from these ones within a week, and the only
+     * thing worse than a refusal at deploy time is a console that promised the
+     * opposite.
+     */
+    checkRelease(projectName: string, stackName: string, releaseId: string): Promise<{
+        ok: boolean;
+        because: string;
+    }>;
+    /**
+     * Run a release's probes on the node of the stack that carries it, and
+     * hand back what the producer printed and how it exited.
+     *
+     * Deciding whether to KEEP the result is not done here: that is
+     * `release/attest.ts`, reached through the release service, which also
+     * holds the audit trail the freshness refusal needs. This method is the
+     * transport — the release's own scripts and the stack definition at its
+     * commit, uploaded and run on the node under its deploy lease, so an
+     * attestation never interleaves with a deployment.
+     *
+     * One node only, and refused by name otherwise. The probes reach
+     * `localhost` and the stack's containers; on a stack of several nodes one
+     * run measures one machine, and an attestation is stored per STACK — kept
+     * as it is, it would claim for all of them what was measured on one.
+     */
+    attestOnNode(projectName: string, stackName: string, releaseId: string): Promise<{
+        stdout: string;
+        stderr: string;
+        code: number;
+        node: string;
+        scriptsFrom: 'release' | 'history';
+        sourceFiles: number;
+        accounts: AttestAccounts;
+    }>;
+    /**
+     * Make a named account with a platform role on a remote stack, and keep
+     * its password in this daemon's vault — never in the answer.
+     *
+     * The project's own tool makes it (`scripts/operator-account.mjs` at the
+     * project's HEAD commit), on the stack's node, under its deploy lease
+     * (`withOperatorTool`). The password comes back sealed to a key made for
+     * this run and is opened only to go into the vault — the SSH layer masks
+     * anything that looks like a password on its way back (see
+     * `project/operator-account.ts`).
+     *
+     * Two steps that must both happen or neither: the account on the stand and
+     * its password in the vault. The vault is asked first whether the key is
+     * free — a key already there is somebody's secret, and a new password would
+     * replace it — and if the write still fails, the account just made is taken
+     * away again, by its name AND the id the tool printed: an account whose
+     * password nobody holds is a privileged row under a name every later run
+     * refuses as taken. When the run's outcome is not known at all, the stand is
+     * asked what it holds, and the answer says it — with the command that takes
+     * the account away if it is there.
+     */
+    createOperatorAccount(projectName: string, stackName: string, input: {
+        username: string;
+        role?: string | undefined;
+        displayName?: string | undefined;
+        vaultKey?: string | undefined;
+    }): Promise<import('../shared/dto/project.js').IStackAccount>;
+    /**
+     * The stack's maintenance lock by hand (`maintenance-lock.ts`): the state
+     * as its gateway enforces it, or held for a bounded time, or let go — a lock
+     * a failed deployment left (it also expires by itself), or work outside a
+     * deployment. Not under the node's deploy lease: letting go of the lock is
+     * exactly what an operator does while a stuck deployment holds that lease.
+     * Only omnitron's keys; the administrators' mode is main's, in /admin.
+     */
+    stackMaintenance(projectName: string, stackName: string, request: {
+        action: 'status' | 'on' | 'off';
+        minutes?: number | undefined;
+    }): Promise<import('../shared/dto/project.js').IStackMaintenance>;
+    /**
+     * What the probes left on a stand — the project's own census of it,
+     * `scripts/probe-leftovers.mjs` without a flag: SELECTs and nothing else,
+     * the accounts, organisations and orphans it would take and what would hold
+     * each back. Its removal is not a door here: that takes the owner's word
+     * each time, and this census is what the word is given on.
+     */
+    probeLeftovers(projectName: string, stackName: string, request: {
+        mode: import('../project/operator-account.js').LeftoversMode;
+        /** Accounts no template matches, named after reading the census. */
+        also?: readonly string[] | undefined;
+    }): Promise<import('../shared/dto/project.js').IStackLeftoversCensus>;
+    /**
+     * The stand's accounts counted — by role, by status, by the form their MFA
+     * data is in, and whether the seeded admin still opens with its published
+     * password. Counts only. For decisions that depend on what a stand holds
+     * without reading it: a new MFA root cannot open what the old one sealed,
+     * so how many rows are sealed is asked first.
+     */
+    censusOperatorAccounts(projectName: string, stackName: string): Promise<import('../shared/dto/project.js').IStackAccountCensus>;
+    /** What a remote stack's stand holds under a name — never a secret. */
+    showOperatorAccount(projectName: string, stackName: string, username: string): Promise<import('../shared/dto/project.js').IStackAccountLookup>;
+    /**
+     * Take an account away from a remote stack's stand — the row with this
+     * name AND this id, or nothing — and the password this daemon keeps for it,
+     * if it keeps one: a password for an account that is gone is not a secret
+     * worth keeping, and a vault that still lists it says the account exists.
+     */
+    removeOperatorAccount(projectName: string, stackName: string, input: {
+        username: string;
+        id: string;
+        vaultKey?: string | undefined;
+    }): Promise<import('../shared/dto/project.js').IStackAccountRemoved>;
+    /**
+     * The release this stack last started with, as the audit trail recorded it
+     * (`stack.start`, `details.release`) — or null: no trail, no start, or a
+     * start that was not a release.
+     */
+    private releaseRunningOn;
+    /**
+     * What every operator-account action shares: a remote stack of one node,
+     * the project's tool staged from its HEAD commit, the node's deploy lease,
+     * and the stage taken away again on both sides, whatever `work` did.
+     *
+     * One node, like the attestation: the tool reaches the node's containers,
+     * and which of several nodes holds the stack's database is not decided
+     * here.
+     */
+    private withOperatorTool;
+    /**
+     * The paths of the working tree a deployment of this stack reads, relative
+     * to its root — what admission requires to be the release's commit.
+     *
+     * The definition (`release/definition-inputs.ts`), and the directories the
+     * deployment ships to its nodes (`shippedDirsOf`): the gateway's nginx tree,
+     * a service's scripts. Those were read from the working tree and compared
+     * with nothing, so an uncommitted edit to the gateway's template reached the
+     * test node past every gate a release has.
+     */
+    private deploymentReads;
+    private admitRelease;
+    /** What each of a stack's nodes says its daemon is — the omni its applications load. */
+    private askDaemonVersions;
+    /**
+     * What a restart of THIS daemon may do to a remote stack: look, not ship.
+     *
+     * Boot and the enabled-stacks reconciler resumed every enabled stack through
+     * a full start, and for a remote stack a full start is a deployment — build,
+     * deliver, restart — of whatever this machine's working tree holds, onto
+     * machines other people deploy to as well. Measured 2026-09-22: a master
+     * restarted on a clean tree shipped its tree to the one test server by
+     * itself (`source: 'auto-resume'`, 13:56:56 → 14:00:05, five applications
+     * restarted onto new artifacts); the three restarts before it that morning
+     * were stopped only because the tree happened to be dirty — a condition
+     * that has nothing to do with intent, and a clean tree of an old commit
+     * passes it as easily. Every development machine with the stack enabled did
+     * the same, on every restart, past every gate.
+     *
+     * The applications on a node are supervised by the node's own daemon. What
+     * this master lost in its restart is its own picture of them, so that is
+     * what is rebuilt: the nodes are asked what they run, and the answer becomes
+     * the stack's state — `running`, or `degraded` when some application is not
+     * online (the node restarts its own; this master does not ship over it). A
+     * stack no node answered for is an error the reconciler retries, by asking
+     * again. Deploying stays something an operator asks for.
+     */
+    private attachRemoteStack;
     /**
      * Get the infrastructure manager (for daemon-level access).
      */
     getInfraManager(): StackInfrastructureManager;
+    /**
+     * Periodically converge running stacks onto the persisted desired state
+     * (`project.enabledStacks`). Boot-time resume in daemon.startApps() is
+     * one-shot — on 2026-07-11 it fired seconds after login while Docker
+     * (OrbStack) was still coming up, failed with "Docker is not available",
+     * and the platform stayed appless for days despite a healthy supervised
+     * daemon. The reconciler retries with per-stack exponential backoff until
+     * the stack is running, and picks up any later divergence (a stack that
+     * crashed into 'error', infra that vanished) the same way.
+     *
+     * Manual intent is respected by construction: `stack stop` removes the
+     * stack from enabledStacks (persisted), so a deliberately stopped stack is
+     * never resurrected; 'starting'/'stopping' states are skipped as in-flight.
+     */
+    startEnabledStacksReconciler(intervalMs?: number): void;
+    private reconcileEnabledStacks;
     /**
      * Dispose of all resources held by this service.
      * Called during daemon shutdown.
@@ -76,6 +510,19 @@ export declare class ProjectService extends EventEmitter {
     dispose(): Promise<void>;
     loadProjectConfig(projectName: string): Promise<IEcosystemConfig>;
     getLoadedConfig(projectName: string): IEcosystemConfig | null;
+    /** In-flight loads, so callers arriving together load a project once. */
+    private readonly configLoads;
+    /**
+     * The project's config, loaded now if the daemon has not got to it yet.
+     *
+     * A reader that arrived in the first seconds after a daemon start found no
+     * config and was answered with an error: measured on the master restarted
+     * at 12:07:48 UTC, 20 ERROR lines «Project 'sample' config not loaded» from
+     * the console's `getStack` polls, logged as server failures and counted by
+     * `doctor` — for a project that loads a moment later, which is what the
+     * reconciler already does for itself (`loadProjectConfig` when absent).
+     */
+    ensureConfig(projectName: string): Promise<IEcosystemConfig>;
     reloadConfig(projectName?: string): Promise<void>;
     getRunningStacks(projectName: string): string[];
     /** Build the stack handle key for an app */
@@ -94,12 +541,142 @@ export declare class ProjectService extends EventEmitter {
      * Validate that a stack's infrastructure config satisfies all app requirements.
      * Returns issues if infrastructure is missing for apps that need it.
      */
+    /**
+     * What each node of a stack would find and do on its host for the services
+     * the stack declares — asked, not done (`host-inspection.ts`).
+     *
+     * Built from the parts a deployment sends — the applications'
+     * declarations and the stack's overrides with their references resolved
+     * from this vault — plus the services reached elsewhere, to say whether
+     * they answer. The node that runs mainnet chains could otherwise be read
+     * only by deploying to it: it takes SSH by password, and that stays in
+     * the vault.
+     */
+    inspectStackHost(data: {
+        project: string;
+        stack: string;
+    } & Omit<import('../infrastructure/host-inspection.js').HostInspectionRequest, 'services' | 'overrides'>): Promise<Array<{
+        node: string;
+        inspection?: import('../infrastructure/host-inspection.js').HostInspection;
+        error?: string;
+    }>>;
     validateStackInfrastructure(projectName: string, stackName: string): Promise<{
         valid: boolean;
         issues: string[];
     }>;
     private startLocalStack;
+    /**
+     * Deploy a stack to its nodes, and say what it is doing while it does it.
+     *
+     * Measured on 2026-09-22: 829 seconds between this method's first log line
+     * and its next one, with the work in flight the whole time. The CLI stops
+     * waiting at 600 and says the operation is «probably still running» — true,
+     * and silent about which of its seven steps was running. See
+     * `deploy-phases.ts`.
+     */
     private startRemoteStack;
+    private deployRemoteStack;
+    /**
+     * Warn the platform on this node, then hold it at its gateway for the
+     * deployment (`maintenance-lock.ts`). `null` when the stack opted out, or
+     * when the node has no running gateway and Redis to hold with — a first
+     * deployment, which nobody is using yet.
+     */
+    private holdForDeployment;
+    /**
+     * Ask a node to bring up the infrastructure a stack declares.
+     *
+     * Over the mesh connection rather than over SSH: the node already runs a
+     * reconciler that knows how to wait on a container's health, how to detect
+     * a drifted spec, and how to clean up a phantom endpoint. Driving `docker`
+     * over SSH from here would be a second implementation of all of it, on the
+     * side of the wire with the least information.
+     *
+     * The connection is opened for this and kept — it is the same one the mesh
+     * uses afterwards, so the node is joined by the time its applications
+     * start rather than at the next heartbeat.
+     */
+    /**
+       * Deliver each service's static content to the node, and report where.
+       *
+       * Only services that declare a `staticDir`, which today is the gateway
+       * serving the portal. A stack that declares none sends nothing and this
+       * costs nothing.
+       *
+       * A failure is reported and not thrown: a node whose databases came up and
+       * whose frontend did not is a node worth looking at, and stopping the whole
+       * provisioning over a frontend leaves less working, not more.
+       */
+    /**
+     * What each deployed app should connect to, once it is on the node.
+     *
+     * The same `resolveStack` + `resolvedConfigToEnv` pair a local stack uses,
+     * fed the infrastructure the node actually provisioned — so there is one
+     * implementation of "what is DATABASE_URL" rather than a second one written
+     * for nodes, which would drift from the first the first time either
+     * changed.
+     *
+     * `type: 'local'` is not a pretence: the apps run as host processes on the
+     * node, beside containers whose ports are published on that node's
+     * loopback. Local is what they are from where they stand.
+     */
+    private resolveNodeAppEnv;
+    /**
+     * A stack's service overrides with their secret references resolved.
+     *
+     * An override names its credentials rather than carrying them:
+     *
+     *     "secrets": { "rpc_password": { "secret": "monero.mainnet.rpc_password" } }
+     *
+     * `resolveSecretRefs` has existed for that since it was written and had no
+     * caller at all, so the synchronous resolver downstream turned every one of
+     * these into the literal string `<secret:monero.mainnet.rpc_password>` and
+     * handed it to the application as a password.
+     *
+     * A key the vault does not hold resolves to an empty string, which an
+     * application reports as an authentication failure against a credential it
+     * was never given. That is worth a line naming the key.
+     */
+    private resolveOverrideSecrets;
+    /**
+     * The credentials the NODE resolved, read back from the node.
+     *
+     * `getConnectionInfo` answers from the config `provisionStack` stored after
+     * running `withGeneratedCredentials` against the node's vault, so it is the
+     * only account of these secrets that is true on the machine the apps will
+     * run on.
+     *
+     * `null` is an answer — the node runs no such service — and leaves it as
+     * the stack declared it. A read that did not happen is not an answer. This
+     * was «best-effort per service»: a failed read fell back to the declared
+     * credentials, and for a secret the node generated those are wrong by
+     * construction. Test node, 2026-09-22 21:17:51 UTC: the heartbeat dropped
+     * the peer mid-read («manual disconnect»), the apps were configured with
+     * the declared postgres password, 6 of 6 migrations failed on it, and the
+     * node was left in a mixed state. So a dropped connection is reconnected
+     * and asked once more — this is a read, it can be — and a read that still
+     * fails stops the deployment HERE, before any application is configured
+     * with a password that is not the node's.
+     */
+    private readNodeCredentials;
+    private shipStackStatics;
+    /**
+     * Where the stack's static build lives, absolute, or undefined.
+     *
+     * Both spellings, and the same resolution `shipStackStatics` performs —
+     * named once because two questions ask it: what to ship, and whether the
+     * trees it is built from are the commits they claim.
+     */
+    private staticDirOf;
+    /**
+     * The config files the stack's services need, read from this master.
+     *
+     * Only services that name a directory to ship (`shippedDirOf`) — the
+     * gateway's nginx tree, Nominatim's import scripts. A stack that names none
+     * sends nothing, so this costs nothing where it is not needed.
+     */
+    private readStackConfigFiles;
+    private provisionNodeInfrastructure;
     private startClusterStack;
     /**
      * Run database migrations for apps that declare migrate: true in their
@@ -111,12 +688,6 @@ export declare class ProjectService extends EventEmitter {
      * localhost:{port}/{dbName} with postgres:postgres — matching the stack's provisioned postgres.
      */
     private runStackMigrations;
-    /**
-     * Block until a postgres instance accepts connections, with bounded retries.
-     * Used before running migrations to avoid ECONNREFUSED on freshly-provisioned
-     * containers.
-     */
-    private waitForPostgres;
     /**
      * Resolve stacks from config + user stacks.
      * User-created stacks (from omnitron.stacks.json) are merged with config stacks.
@@ -124,9 +695,110 @@ export declare class ProjectService extends EventEmitter {
      * No implicit fallbacks — stacks must be created explicitly.
      */
     private resolveStacks;
+    /**
+     * The environment a stack gives its apps, vault references resolved
+     * (`project/stack-env.ts`). Throws — the start is refused — for a key the
+     * vault does not hold, an `appEnv` for an app the stack does not run, or a
+     * malformed entry. Values never leave this call except into the apps' env.
+     */
+    private stackEnvFor;
+    /**
+     * How each app of a local stack is started: the entry handed to the
+     * orchestrator — named into its stack, its environment computed from the
+     * stack's resolved configuration and then the project config's own.
+     *
+     * One builder for the start and for a re-read of the project
+     * (`rereadProject`), so a running app is redefined exactly as it would be
+     * started.
+     */
+    private stackEntryBuilder;
+    /**
+     * Every application in a stack, with what it declares it needs.
+     *
+     * Extracted because a remote stack needs exactly this and had no way to
+     * get it: `startRemoteStack` built its own list of app ENTRIES and never
+     * their definitions, so the `infrastructure` an application declares —
+     * its chain daemon, its cache — was invisible on that path. The local
+     * path had it all along, twenty lines up from where it was needed.
+     */
+    private loadAppDefinitions;
+    /**
+     * The infrastructure a stack's applications declare, merged and overridden.
+     *
+     * One entry per service name: two applications that both declare
+     * `postgres` mean one Postgres, which is what `serviceOverrides` keys on
+     * and what the container resolver has always assumed. A later declaration
+     * that disagrees with an earlier one is not merged silently — the first
+     * wins and the disagreement is said, because two applications wanting
+     * different versions of one service is a fact about the stack, not a
+     * detail to resolve by ordering.
+     */
+    private collectDeclaredServices;
     private resolveStackApps;
     private updateEnabledStacks;
     private toProjectInfo;
+    /**
+     * A remote stack's apps, as the NODES report them.
+     *
+     * `toStackInfo` reads this daemon's own orchestrator handles. For a remote
+     * stack there are none — the applications run on the nodes, under the
+     * node's own naming (`<project>/deployed/<app>`) — so every app came back
+     * `stopped` and the report was:
+     *
+     *     Stack sample/test: only 0/6 apps came online.
+     *     Not online: main (stopped), storage (stopped), quotes (stopped),
+     *     payments (stopped), messaging (stopped), geo (stopped)
+     *
+     * measured against a node answering `appsTotal: 6, appsOnline: 6` with
+     * every port listening, thirty seconds after this same master installed,
+     * migrated and started them. The CLI exits 1 on that count, so a correct
+     * deployment fails a script; and the console's stack page shows the same
+     * six rows, stopped.
+     *
+     * A node that cannot be asked leaves its apps exactly as they were, with a
+     * line saying why. "We could not ask" is not "they are down" — and the
+     * local rows are at least honest about being local.
+     */
+    withRemoteAppStatuses(projectName: string, info: IStackInfo): Promise<IStackInfo>;
+    /**
+     * The same question, with the count of nodes that answered it.
+     *
+     * `connectedNodes` used to be read from the connector's registry, which
+     * said 0 about a node that was answering RPCs at that moment — measured
+     * 2026-09-22, three times in three seconds, beside a `stack status` that
+     * listed six apps online from the very same node. A registry is
+     * bookkeeping; an answer is a fact, and this is where the answers are.
+     */
+    private askNodes;
+    /**
+     * One node's infrastructure, named the way the stack names it.
+     *
+     * The node's container names carry ITS prefix (`sample-test-postgres`), and
+     * a reader wants the service — `postgres` — so the same stripping the
+     * local path does is done here. `null` when the node cannot answer or has
+     * no infrastructure of its own, which leaves the master's view in place.
+     */
+    private remoteInfraStatus;
     private toStackInfo;
 }
+/**
+ * How a master's daemon builds this service: the tokens it resolves, in
+ * order, and the factory that receives them.
+ *
+ * Here and not inline in daemon.module.ts so that the ORDER can be held to
+ * account: `inject` and the factory's parameters are two lists that must
+ * agree position by position, and the container hands the values over as
+ * `any`. Swapped there, the vault arrives as the audit trail and neither
+ * complains until a deployment needs one of them. See
+ * `test/unit/a-factory-that-passed-its-arguments-by-position.test.ts`.
+ */
+export declare const MASTER_PROJECT_SERVICE_PROVIDER: {
+    readonly inject: readonly unknown[];
+    readonly useFactory: (loggerModule: ILoggerModule, orchestrator: OrchestratorService, daemonStateStore: DaemonStateStore, secrets: SecretsService, audit: AuditService) => ProjectService;
+};
+/** A slave has its own encrypted vault even though it has no master database/audit service. */
+export declare const SLAVE_PROJECT_SERVICE_PROVIDER: {
+    readonly inject: readonly unknown[];
+    readonly useFactory: (loggerModule: ILoggerModule, orchestrator: OrchestratorService, daemonStateStore: DaemonStateStore, secrets: SecretsService) => ProjectService;
+};
 //# sourceMappingURL=project.service.d.ts.map