@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/services/remote-deployer.service.d.ts

@@ -13,11 +13,160 @@
  *
  * Artifact path on remote: /opt/omnitron/artifacts/<project>/<app>/<version>/
  * Remote daemon config: /etc/omnitron/omnitron.config.ts
+ *
+ * NEVER EXECUTED, as of 2026-09-14. Measured rather than assumed: no log in
+ * `~/.omnitron/logs` carries a single line this class emits ("Starting
+ * deployment to node", "Slave provisioned", "Deployment successful"), no
+ * artifact directory exists, and — decisively — no project config declares
+ * `stacks.nodes`, which `startRemoteStack` requires before it can reach here.
+ * So both entry points are unreachable in every current configuration.
+ *
+ * This matters to anyone reading the code below and taking it for a working
+ * path. It is careful code — arguments are quoted, path segments validated,
+ * heredocs replaced with base64 — and none of that has ever met a real host.
+ * Its first run will be its first test. Treat a green read of this file as
+ * evidence about intent, not about behaviour.
+ *
+ * The first thing that first run found, 2026-09-14: **it could not log in.**
+ * Every command here went through `ssh -o BatchMode=yes` with an optional
+ * `-i <keyfile>`, and `BatchMode=yes` disables every interactive method —
+ * password and key passphrase both. The console's Add Node dialog collects
+ * exactly those, encrypts them in the daemon's vault, and the health monitor
+ * uses them through `ExecutionService.ssh()` on every check round. So the
+ * product had two SSH implementations: one that can present what the operator
+ * gave it, and one — this — that cannot, on the path where it matters most.
+ *
+ * Measured against the test host, whose SSH answers a password in 311 ms:
+ *
+ *   ssh -o BatchMode=yes root@<host> 'echo ok'
+ *   → root@<host>: Permission denied (publickey,password).
+ *
+ * That is the answer to "why can a machine added in the console not be
+ * deployed to": not policy, not a missing feature — the deployer could not
+ * authenticate as the operator had arranged. It goes through the same
+ * `ExecutionService` as the checks now, and takes a `DeployTarget` carrying
+ * the credentials rather than an `IStackNode` whose `ISSHConfig` has nowhere
+ * to put them.
  */
 import type { ILogger } from '@omnitron-dev/titan/module/logger';
+import type { StaticAssetPublication, StaticAssetReceipt } from './static-carry-forward.js';
 import type { IStackNode } from '../config/types.js';
 import type { ArtifactInfo } from '../project/artifact-builder.js';
-export type DeployStatus = 'pending' | 'transferring' | 'extracting' | 'restarting' | 'verifying' | 'success' | 'failed';
+import type { ExecutionService, SSHTarget } from '../execution/execution.service.js';
+import { type InstalledBundle } from './host-upgrade.js';
+import { type LeaseRunner } from './node-deploy-lease.js';
+import { type HostOperationAllowance } from './host-operation-barrier.js';
+/**
+ * A name that is safe to place in a remote filesystem path.
+ *
+ * Project, app and version names are interpolated into
+ * `/opt/omnitron/artifacts/<project>/<app>/<version>` and the result is sent
+ * to a remote shell running as the SSH user, which defaults to root. Quoting
+ * makes that safe against injection but not against the path itself: a
+ * project literally named `../..` resolves outside the artifact root, and
+ * `mkdir -p` then creates it there. Quoting is not a substitute for the
+ * value meaning what the path assumes it means.
+ *
+ * These names come from the project registry and the console's own forms —
+ * operator-supplied, not attacker-supplied in the ordinary case. It is
+ * defence in depth, and the cost of it is a regular expression.
+ *
+ * @throws Error naming the segment and what is allowed.
+ */
+export declare function assertRemotePathSegment(kind: string, value: string): string;
+/**
+ * Where an app's artifact lives on a node — one place, because the install
+ * writes there and the step that starts the app records there.
+ */
+export declare function artifactDirOnNode(project: string, app: string, version: string): string;
+/**
+ * A machine this deployer can reach, and how.
+ *
+ * `IStackNode` cannot be this: its `ISSHConfig` holds `user`, `port` and
+ * `privateKey`, so a node whose credential is a password — the console's
+ * default, and what the operator is offered first — has nowhere to be
+ * expressed. Both registries project into this one shape:
+ * `stackNodeToDeployTarget` for a node declared in a project's `stacks.nodes`,
+ * and `NodeManagerService.nodeToDeployTarget` for one an operator registered
+ * in the console, which resolves its secrets from the vault on the way.
+ */
+export interface DeployTarget {
+    host: string;
+    /**
+     * SSH port. Default 22.
+     *
+     * Spelled out rather than inherited as `port` from `SSHTarget`, because the
+     * other port on this type is the daemon's and both are numbers. An
+     * `IStackNode` — whose `port` IS the daemon's — is structurally assignable
+     * to any type whose only required field is `host`, so inheriting `port`
+     * meant a node passed by mistake would have its daemon port dialled as SSH,
+     * and the compiler would agree. With the field named for what it is, the
+     * same mistake reaches SSH's default instead of the wrong number.
+     */
+    sshPort?: number;
+    username?: string;
+    /** Path to a private key file, read by the SSH engine. */
+    privateKey?: string;
+    /** Passphrase for that key, resolved from the vault by the caller. */
+    passphrase?: string;
+    /** SSH password, resolved from the vault by the caller. */
+    password?: string;
+    /** Omnitron daemon (fleet) port on this node. Default 9700. */
+    daemonPort?: number;
+    /** Restrict deployment to these apps; absent means every app. */
+    apps?: string[];
+    /** What to call this node in logs and progress events. */
+    label?: string;
+}
+/** Project a node declared in a project config into a deploy target. */
+export declare function stackNodeToDeployTarget(node: IStackNode): DeployTarget;
+/**
+ * Fill a stack node's connection details from the node registry.
+ *
+ * A stack says WHICH host an app runs on; the node registry says HOW to
+ * reach it — the user, the port, and the key or password, which are held
+ * encrypted in the daemon's vault because they are credentials and a config
+ * file in a repository is not where those go.
+ *
+ * Nothing joined the two. `stackNodeToDeployTarget` read only the stack's
+ * own `ssh` block, so deploying to a machine that the console had already
+ * registered, provisioned and been connected to failed at the first
+ * connection:
+ *
+ *     Invalid SSH options: Either privateKey or password must be provided
+ *
+ * — for a node the same daemon was, at that moment, holding an SSH tunnel to.
+ *
+ * The stack's explicit values win where it has them: an operator who wrote
+ * `ssh.user` in the stack config meant it, and a registry entry is the
+ * default, not an override. Everything the stack leaves out comes from the
+ * registry.
+ */
+export declare function withNodeCredentials(target: DeployTarget, registered: SSHTarget | null): DeployTarget;
+/** What a provisioning run may do to a host. */
+export interface ProvisionOptions {
+    /**
+     * Allow the host's package manager to be used for missing tools. Default
+     * true — preparing a node is meant to be automatic.
+     *
+     * It is a much smaller permission than it was. The runtime itself now comes
+     * from nodejs.org as a tarball under omnitron's own prefix, so the package
+     * manager is reached only for `curl` and `tar` when a host has neither, and
+     * a host that has them is never touched by it at all.
+     */
+    installRuntime?: boolean;
+    /** Runtime version for a host that has none. Defaults to the pinned LTS. */
+    nodeVersion?: string;
+}
+/**
+ * What a deployment is doing, for a console watching it.
+ *
+ * `installing` is its own value because it is the longest phase by a wide
+ * margin — `npm install` on the node takes minutes where the transfer takes
+ * seconds — and reporting it as `extracting` leaves an operator watching a
+ * message that stopped being true.
+ */
+export type DeployStatus = 'pending' | 'transferring' | 'extracting' | 'installing' | 'restarting' | 'verifying' | 'success' | 'failed';
 export interface DeployResult {
     node: string;
     app: string;
@@ -25,6 +174,19 @@ export interface DeployResult {
     status: DeployStatus;
     duration: number;
     error?: string;
+    /**
+     * The node already had this exact artifact, so nothing was transferred.
+     *
+     * Reported rather than inferred from a duration: the caller decides
+     * whether to restart the app, and "the files are the same" is half of
+     * that decision.
+     */
+    unchanged?: boolean;
+    /**
+     * The artifact's own checksum, carried so the step that STARTS the app can
+     * record it — see `recordRunningArtifact`.
+     */
+    checksum?: string;
 }
 export interface DeployProgress {
     node: string;
@@ -33,11 +195,44 @@ export interface DeployProgress {
     progress: number;
     message: string;
 }
+/** A progress event with the time it happened, for a console that polls. */
+export interface DeployProgressRecord extends DeployProgress {
+    /** ISO 8601. */
+    at: string;
+}
+/**
+ * Is this a gzip stream of a COMPLETE tar archive?
+ *
+ * Two ways to be short, told apart: a gzip stream cut off fails to
+ * decompress («unexpected end of file»), and a tar cut off inside a gzip
+ * that finished — `tar` killed, `gzip` still closing its own stream —
+ * decompresses to something that is not a whole number of 512-byte blocks,
+ * or does not end in the two zero blocks every tar writer closes an archive
+ * with. Answers `true` or the reason it is not.
+ */
+export declare function wholeTarGz(archive: Buffer): true | string;
 export declare class RemoteDeployer {
     private readonly logger;
+    private readonly execution;
+    private readonly deploymentLeases;
     /** Active deployment progress handlers */
     private readonly progressHandlers;
-    constructor(logger: ILogger);
+    /**
+     * The last thing that happened to each app on each node.
+     *
+     * A deployment publishes progress as it goes and the console polls; without
+     * somewhere for an event to WAIT, those two never meet, and a deployment
+     * that takes a quarter of an hour showed the operator one row that said
+     * `deploying` from beginning to end. Everything that said WHERE it was —
+     * transferring, installing, the message naming the failing step — reached a
+     * handler that re-emitted it to nobody.
+     *
+     * Keyed by node and app, so this is bounded by the fleet rather than by how
+     * often anyone deploys, and the entry for an app is always its current
+     * state rather than a scroll an operator has to read to the end of.
+     */
+    private readonly lastProgress;
+    constructor(logger: ILogger, execution: ExecutionService);
     /**
      * Register a progress handler for real-time deployment updates.
      */
@@ -45,13 +240,151 @@ export declare class RemoteDeployer {
     /**
      * Deploy an artifact to a single remote node.
      */
-    deployToNode(node: IStackNode, artifact: ArtifactInfo, project: string): Promise<DeployResult>;
+    deployToNode(target: DeployTarget, artifact: ArtifactInfo, project: string, options?: {
+        /**
+         * Whether to start the app once its artifact is in place.
+         *
+         * False for a stack deployment, which installs everything, writes the
+         * app definitions, and only then starts — because a node cannot start
+         * an app it has no definition for, and the definitions are written from
+         * the set of artifacts that landed.
+         */
+        startAfterInstall?: boolean;
+        /**
+         * Transfer even when the node records the same artifact.
+         *
+         * For an operator with reason to doubt the record — a half-finished
+         * install, a file edited on the node by hand.
+         */
+        force?: boolean;
+    }): Promise<DeployResult>;
     /**
      * Deploy artifacts to all nodes in a stack (parallel).
      */
-    deployToStack(nodes: IStackNode[], artifacts: ArtifactInfo[], project: string, options?: {
+    deployToStack(targets: DeployTarget[], artifacts: ArtifactInfo[], project: string, options?: {
         concurrency?: number;
+        /**
+         * The app definitions these artifacts belong to.
+         *
+         * Without them a node receives artifacts and never learns what to do
+         * with them: its daemon says `No projects registered` and
+         * `omnitron restart main` answers `Unknown app: main`. Optional so the
+         * existing callers keep working, and every one of them should pass it.
+         */
+        apps?: readonly import('../config/types.js').IEcosystemAppEntry[];
+        /**
+         * What each app connects to, resolved by this master for this node.
+         *
+         * Per app rather than as an infrastructure block: a block is a stack
+         * the node PROVISIONS, and writing one made the node build a second
+         * complete set of containers beside the master's and sweep the
+         * master's away. See `NodeConfigInput.appEnv`.
+         */
+        appEnv?: Readonly<Record<string, Record<string, string>>> | undefined;
+        /** The stack these apps belong to — names the docker network to open from. */
+        stack?: string | undefined;
+        /** Ship and restart every app past the node's record — `stack start --reinstall`. */
+        force?: boolean | undefined;
+        /** The project's alert sink, for the node's own alert engine — see `NodeConfigInput.alertSink`. */
+        alertSink?: import('../config/types.js').IAlertSink | undefined;
     }): Promise<DeployResult[]>;
+    /**
+     * Give a node the config that tells it what to run.
+     *
+     * Written, then registered. Registering a path with no config in it leaves
+     * the daemon with a project it cannot read, which reports as a broken
+     * project rather than a missing file.
+     *
+     * Reported and not thrown: artifacts that transferred are on the node
+     * either way, and failing the whole deployment over the registration would
+     * discard a transfer that succeeded. The operator needs to know the apps
+     * are not runnable, which is what the error says.
+     */
+    /**
+     * Let the gateway reach the applications it proxies to.
+     *
+     * The gateway is a container and the apps are host processes, so every
+     * `/api/*` request crosses out of docker and into the host's INPUT chain.
+     * On a hardened host that chain drops it, and the gateway answers a
+     * correct, unhelpful `503` three seconds later while the upstream it could
+     * not reach is listening and healthy on the same machine.
+     *
+     * Measured on the test node with everything else already right: apps on
+     * `0.0.0.0:3001-3007`, answering `404` to the host itself, timing out from
+     * the gateway, `ufw` active with `22/tcp` its only rule and INPUT policy
+     * DROP.
+     *
+     * Derived, not configured: the subnet comes from the network the gateway
+     * is actually on, so a stack cannot be given a rule for the wrong one, and
+     * a subnet that is not a private range is refused outright rather than
+     * turned into a firewall rule nobody can explain.
+     *
+     * Never fatal. A host whose firewall cannot be read is a host that gets a
+     * message; stopping a deployment over it would trade a visible 503 for an
+     * invisible one.
+     */
+    private openGatewayPath;
+    /**
+     * Run each app's migrations, on the node, against the node's database.
+     *
+     * They had never run there. `ProjectService` migrates by executing
+     * `apps/<name>/src/database/migrate.ts` from the PROJECT PATH against
+     * `localhost` — both of which name the machine the master is on. A node has
+     * no project sources and a different localhost, so a remote stack's
+     * databases were created and left empty.
+     *
+     * Measured on the test node after six apps installed and five started:
+     * every one of the six databases existed and held ZERO tables. Five apps
+     * came up anyway, because they touch no table at boot; `payments` does, and
+     * said so —
+     *
+     *     Failed to call @PostConstruct 'bootstrap' on 'PlatformRevenueService':
+     *     relation "accounts" does not exist
+     *
+     * — which is the only reason anyone found out. A platform with no schema
+     * that reports five of six apps healthy is a worse state than one that
+     * refuses to start.
+     *
+     * The artifact already carries what is needed: `dist/database/migrate.js`
+     * beside `dist/database/migrations/` — 160 compiled files for payments. The
+     * same build the app itself runs from, so there is no second copy of the
+     * schema to drift.
+     *
+     * Returns the apps whose migrations failed, with the reason, and the
+     * caller does not start their new code.
+     *
+     * This used to say: «Failure is reported and does not stop the deployment:
+     * an app whose migrations fail will fail its own start with a message
+     * about the table it wanted, which is more specific than anything this
+     * step could say.» True for one of the two ways it goes. An app that
+     * fails to START is caught by `verifyHealth` and marked failed — that
+     * branch was covered, and the sentence is right about it. An app that
+     * starts fine and fails on the first REQUEST that touches the missing
+     * table passes `verifyHealth`, the stack reports `started`, and the only
+     * trace is one ERROR line in the master's log. The justification covered
+     * the branch that was already safe.
+     *
+     * Idempotence is what makes refusing cheap: the migrator records each
+     * migration it applied, in a transaction with the migration itself, so
+     * running the batch again after the cause is fixed applies exactly what
+     * is missing. That holds because `HardenedMigrationRunner` defaults
+     * `useTransactions` to true (`titan-database/src/migration/
+     * hardened-runner.ts:171`) and no sample `migrate.ts` overrides it — it is
+     * conditional in the runner (`:502`), so a migrator that turned it off
+     * would make a refused deployment leave a half-applied migration behind.
+     */
+    private migrateNodeApps;
+    /**
+     * Write the node's app definitions, and say whether they changed.
+     *
+     * The caller decides whether to restart the applications, and "the
+     * configuration moved" is half of that decision — identical files with a
+     * different environment is a different deployment. Compared by the hash of
+     * the rendered body against one written beside it, rather than by reading
+     * the file back: the body holds every generated credential on the node,
+     * and it should cross the wire once, in the direction it has to.
+     */
+    private registerNodeApps;
     /**
      * Provision a remote node as a slave daemon.
      *
@@ -69,17 +402,256 @@ export declare class RemoteDeployer {
      * @param masterHost - The master daemon's reachable address (from slave's perspective)
      * @param masterPort - The master daemon's fleet TCP port
      */
-    provisionSlaveNode(node: IStackNode, masterHost: string, masterPort: number, project: string): Promise<boolean>;
+    provisionSlaveNode(target: DeployTarget, 
+    /**
+     * Where this node should dial to reach the master, or null when there is
+     * nowhere — a master behind NAT, which is where remote stacks are
+     * started from.
+     *
+     * Null is not a failure. Replication is master-PULL: the master opens
+     * the connection, over SSH when the node's daemon port is closed, and
+     * drains the node's buffer. `omnitron up --slave` takes the address
+     * optionally for exactly this reason.
+     */
+    masterHost: string | null, masterPort: number, project: string, options?: ProvisionOptions): Promise<boolean>;
+    /**
+     * Wait for the remote daemon to answer, or report why it did not.
+     *
+     * `omnitron ping` on the far side prints its pid, uptime and version when
+     * the daemon is up, and fails otherwise. The last failure is carried out of
+     * the loop so a caller can say what the host said rather than only that
+     * time ran out.
+     */
+    private awaitDaemon;
+    /**
+     * Install a locally built omnitron on a node, beside whatever it is
+     * running.
+     *
+     * The counterpart to installing from the registry, and the only channel
+     * that can put THIS tree on a node: the published package is whatever was
+     * last released, which on 2026-09-14 was five months and 224 commits
+     * behind, under the same version number.
+     *
+     * Nothing is made live here. The archive is transferred, unpacked into its
+     * own version directory, installed, and run — and `activate` is a separate
+     * call, so a caller that stops after this has spent disk and changed
+     * nothing about what the node is serving.
+     */
+    installBundle(target: DeployTarget, archivePath: string, version: string, prefix?: string): Promise<boolean>;
     /**
-     * Generate omnitron.config.ts content for a slave daemon.
+     * `activateBundle` with the platform held. `omnitron down; up` stops every
+     * app on the node, so each stack gateway there holds its platform
+     * (`maintenance-lock.ts`) — warned first — until its apps answer through it
+     * again, for up to three minutes after the restart; past that the lock is
+     * left to expire by itself. A node with no gateway activates as before.
      */
-    private generateSlaveConfig;
+    activateBundleHeld(target: DeployTarget, version: string, prefix?: string, keepVersions?: number): Promise<boolean>;
+    /** Check all durable operator workflows; a recovery can allow only its exact active journal. */
+    assertNoPendingHostOperations(target: DeployTarget, prefix?: string, allowance?: HostOperationAllowance): Promise<void>;
+    /** Require a settled host and the actual serving immutable daemon build. */
+    inspectInstalledBundle(target: DeployTarget, prefix?: string, allowance?: HostOperationAllowance): Promise<InstalledBundle>;
+    activateBundle(target: DeployTarget, version: string, prefix?: string, keepVersions?: number, verifyPlatform?: () => Promise<void>, allowance?: HostOperationAllowance): Promise<boolean>;
+    /** Recover a recorded interrupted upgrade under the same node lease; never prunes or changes app release versions. */
+    recoverBundleUpgrade(target: DeployTarget, id: string, prefix?: string, verifyPlatform?: () => Promise<void>, allowance?: HostOperationAllowance): Promise<boolean>;
+    private hostUpgradeActions;
     private verifySSH;
+    /**
+     * Run a command on the node, through the daemon's one SSH implementation.
+     *
+     * Throws on a non-zero exit, which is what the callers above are written
+     * against — they use `|| echo ""` where they want to see a failure as an
+     * answer, and expect a throw everywhere else. `ExecutionService.ssh` reports
+     * failure in `exitCode` rather than raising, so the check has to be here;
+     * without it every `if (!result.trim())` in this file would read a failed
+     * command as an empty answer, and the two probes in `provisionSlaveNode`
+     * would install a runtime onto a host that already has one.
+     */
+    /**
+     * How a node deploy lease reaches its node: the lease module writes the
+     * scripts, the deployer owns the SSH. See `node-deploy-lease.ts`.
+     */
+    leaseRunner(target: DeployTarget): LeaseRunner;
+    /**
+     * Run `work` holding the machine's deploy lease — for what changes a node
+     * outside a stack deployment. `fleet upgrade`'s install and activate went
+     * to the node with no lease at all, and are exactly a second writer: the
+     * activation restarts the node's daemon under whatever else is deploying.
+     */
+    underLease<T>(target: DeployTarget, purpose: string, work: () => Promise<T>): Promise<T>;
+    /** Confirm a held lease before the next node operation; outside a lease this is a no-op. */
+    confirmLease(target: DeployTarget, step: string): Promise<void>;
+    /** The node holds its execution fence for the command lifetime, beyond a lost controller. */
+    private guardedCommand;
     private sshExec;
+    /** `sshExec` for a command whose stdout is data — see `readFromNode`. */
+    private sshExecData;
+    /**
+     * Run a command on a node and hand back what it said, exit code included.
+     *
+     * `sshExec` turns every non-zero exit into a throw, which is right for a
+     * deployment step — a step either happened or it did not. A PROBE's exit
+     * code is information: the attestation producer exits 1 when probes failed
+     * (a fact to keep) and 2 when it could not measure at all (nothing to
+     * keep), and a throw would flatten the two into one.
+     */
+    runOnNode(target: DeployTarget, command: string, timeoutMs?: number): Promise<{
+        stdout: string;
+        stderr: string;
+        code: number;
+    }>;
+    /**
+     * `runOnNode` for a command whose stdout is DATA — a record to parse, a
+     * line to store — carried past the transport's masker
+     * (`execution/data-channel.ts`). Its callers are named there and here: the
+     * lease runner (holder records), the attestation (the producer's line), the
+     * operator tool (its answer line). What it returns is unmasked; none of
+     * them logs it whole.
+     *
+     * A channel that came back as something other than its encoding is a
+     * failure with its own code, -2, and its words on stderr — never data.
+     */
+    readFromNode(target: DeployTarget, command: string, timeoutMs?: number): Promise<{
+        stdout: string;
+        stderr: string;
+        code: number;
+    }>;
+    private readFromNodeRaw;
+    /** Use this inside underLease so uploads share the command confirmation boundary. */
+    uploadToNode(target: DeployTarget, localPath: string, remotePath: string): Promise<void>;
     private scpTransfer;
+    /**
+     * Ask the node's daemon to run the app whose artifact just landed.
+     *
+     * This was `omnitron restart <app> 2>/dev/null || true`, and the `|| true`
+     * was hiding the whole of the remote deployment's last mile.
+     *
+     * Measured on the test node, running the command by hand:
+     *
+     *     omnitron restart main  →  Failed: Unknown app: main
+     *
+     * The node's daemon has no app definitions — its own log says `No projects
+     * registered`, and `omnitron status --json` answers `appsTotal: 0` — because
+     * nothing in this deployment ever tells it about the apps. Artifacts land
+     * at `/opt/omnitron/artifacts/<project>/<app>/<version>/` complete with
+     * `config`, `dist` and `package.json`, and a project is "a directory with
+     * omnitron.config.ts", which an artifact is not.
+     *
+     * That gap is not closed here — it is a design question about how a node
+     * learns what to run. What is closed here is its INVISIBILITY: the shell
+     * discarded the only sentence that said so, and the caller reported
+     * `Deployment successful`.
+     */
+    /**
+       * Ship a built frontend to a node and say where it landed.
+       *
+       * The gateway's config travels inside the provisioning RPC — six files, 65
+       * KB. A frontend build is 32 MB, and an RPC argument is the wrong shape for
+       * that: it is held whole in memory on both sides and blocks the call it
+       * rides on. So it goes the way artifacts already go — tar over SSH, extract
+       * on the far side — which is the mechanism this class exists for.
+       *
+       * Idempotent by content: the archive's hash names the directory, so a build
+       * that has not changed is transferred once and every later provisioning pass
+       * finds it already there. A build that HAS changed lands beside the old one
+       * and the gateway's spec hash changes with the path, which is what makes the
+       * container pick it up.
+       */
+    uploadStaticBundle(target: DeployTarget, localDir: string, remoteRoot: string, 
+    /**
+     * The stack's link inside `remoteRoot`, `current-<project>-<stack>`
+     * (`gatewayStaticLinkName`). Given, the delivery points it at the build it
+     * just unpacked — which is what lets the gateway mount the ROOT once and
+     * never be recreated for a new build. Omitted, nothing is linked and the
+     * delivery is exactly what it was.
+     */
+    link?: string): Promise<{
+        remoteDir: string;
+        bytes: number;
+    }>;
+    /**
+     * Point a stack's `current-<project>-<stack>` at the build just unpacked.
+     *
+     * This is the whole reason the gateway stops being recreated on a
+     * deployment: it mounts the static ROOT, whose path never changes, and
+     * serves `/var/www/portal/<link>`. nginx resolves `root` per request and
+     * this config sets no `open_file_cache`, so the swap is picked up with no
+     * reload and no restart. What it replaces cost **1 s of 000** on the
+     * gateway, measured on the release-4 deployment (81 s total).
+     *
+     * RELATIVE, so it resolves inside the container as well as on the host — the
+     * host path is not the container path.
+     *
+     * And swapped with `mv -T`, never `ln -sfn`: `-f` unlinks before it
+     * symlinks, and a request arriving in that window gets a 404 from a web root
+     * that does not exist. `rename(2)` has no window at all. The temporary name
+     * carries the digest so two deliveries racing on one node cannot collide on
+     * it.
+     */
+    private pointStaticLinkAt;
+    /**
+     * The owner-scoped overload publishes a retained asset pool and fails closed.
+     * The legacy positional overload retains its previous best-effort gateway
+     * carry-forward behavior; it does not provide the owner-scoped guarantee.
+     */
+    carryPreviousBuildForward(target: DeployTarget, input: StaticAssetPublication): Promise<StaticAssetReceipt>;
+    carryPreviousBuildForward(target: DeployTarget, root: string, fresh: string): Promise<void>;
     private signalRemoteDaemon;
+    /**
+     * Record that the app now runs this artifact — written only after it came
+     * up healthy on it, never at unpack time, so a deployment interrupted
+     * between installing and starting leaves the old record and the next one
+     * ships and starts again. No checksum, no record: the next deployment then
+     * cannot tell, and «cannot tell» deploys.
+     *
+     * A write that fails is said and not fatal: the app runs; the next
+     * deployment transfers once more than it needed to.
+     */
+    private recordRunningArtifact;
+    /**
+     * The apps this node reports as online, by their bare names.
+     *
+     * One question for the whole node. The per-app check beside this one asks
+     * the same command, and asking it six times to decide six restarts is six
+     * SSH round trips for one answer.
+     *
+     * An empty set on any failure: not knowing what is running is not a claim
+     * that nothing is, and the caller's fallback — restart it — is the safe
+     * reading of "we could not tell".
+     */
+    private appsOnline;
+    /**
+     * Whether the app is actually running on the node.
+     *
+     * This returned `void` on every path — a match, a mismatch, a parse failure,
+     * an unreachable node — under a comment reading "Health check is
+     * best-effort". A verification that cannot fail is not a verification, and
+     * it is worse than none: its presence in the sequence is what persuades a
+     * reader that the deployment was checked.
+     *
+     * The reading itself is in `readNodeHealth`, where the test can reach it.
+     */
     private verifyHealth;
-    private buildSSHArgs;
+    /**
+     * `omnitron status --json` on a node: its stdout is DATA, so it comes
+     * through the data channel — past the transport's masker, which rewrites a
+     * value such as `"token": …` into something that is no longer JSON — and
+     * its stderr stays words, masked, and separate. `2>&1` used to fold the two
+     * together, so an answer that could not be parsed was quoted into the log
+     * whole. Three readers: the daemon check before a restart, `appsOnline`,
+     * `verifyHealth`. None logs `raw`.
+     *
+     * `UNREADABLE` when the node could not be asked at all, with the reason as
+     * the words.
+     */
+    private askNodeStatus;
     private emitProgress;
+    /**
+     * What each app on each node is doing, newest first.
+     *
+     * For a console that polls. Returned as a list rather than the map so a
+     * caller cannot hold a reference that keeps changing underneath it while
+     * it renders.
+     */
+    getProgress(): DeployProgressRecord[];
 }
 //# sourceMappingURL=remote-deployer.service.d.ts.map

package/dist/services/remote-deployer.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-deployer.service.d.ts","sourceRoot":"","sources":["../../src/services/remote-deployer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAanE,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,cAAc,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,qBAAa,cAAc;IAKvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiD;gBAG/D,MAAM,EAAE,OAAO;IAGlC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAQnE;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC;IA8DxB;;OAEG;IACG,aAAa,CACjB,KAAK,EAAE,UAAU,EAAE,EACnB,SAAS,EAAE,YAAY,EAAE,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,YAAY,EAAE,CAAC;IAkC1B;;;;;;;;;;;;;;;;OAgBG;IACG,kBAAkB,CACtB,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;IAuEnB;;OAEG;IACH,OAAO,CAAC,mBAAmB;YAiDb,SAAS;YAIT,OAAO;YAQP,WAAW;YAmBX,kBAAkB;YAUlB,YAAY;IAc1B,OAAO,CAAC,YAAY;IAuBpB,OAAO,CAAC,YAAY;CAUrB"}
+{"version":3,"file":"remote-deployer.service.d.ts","sourceRoot":"","sources":["../../src/services/remote-deployer.service.ts"],"names":[],"mappings":"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"}