Add run-once fleet hooks and primary-only worker placement

A preDeploy hook runs once per replica, so a migration on a three-server
fleet ran three times. .beforeFleet() and .afterFleet() run exactly once
per roll — the first replica and the last — at the same points in the
lifecycle as preDeploy/postDeploy, so they get the staged release, the
dotenv wrapper and the appRoot for free. A roll that dies partway never
reaches its last replica, so afterFleet correctly never fires.

pm2 apps gain placement: 'primary', which pins a process to the first
server the app is declared on. Schedulers are the case that needs it:
three replicas each running a cron means every job fires three times.
Primary is a property of the server, not of the roll, so narrowing a
deploy with --on cannot promote a secondary and start a second copy.
The schema rejects placement: 'primary' on a pm2 app with a port — the
load balancer would keep routing to replicas serving nothing.

--dry-run now names the replica a pinned worker lands on, shows where
the run-once hooks fire, and warns when preDeploy would multiply.

Author: devalade

src/cli/commands/deploy.ts

@@ -152,7 +152,8 @@ async function rollFleetApp(
   }
 
   const appConfig = scoped.value;
-  let replicas = getServerTargets(appConfig).map((target) => target.name);
+  const allReplicas = getServerTargets(appConfig).map((target) => target.name);
+  let replicas = allReplicas;
   if (options.on) {
     if (!replicas.includes(options.on)) {
       ui.error(`App '${app.name}' does not run on '${options.on}'. It runs on: ${replicas.join(', ')}`);
@@ -165,29 +166,26 @@ async function rollFleetApp(
   ui.banner();
   ui.step(`Rolling ${chalk.bold(app.name)} across ${replicas.join(', ')}`);
 
-  if (app.hooks?.preDeploy) {
-    ui.warn(
-      `${app.name} declares a preDeploy hook, which runs once per replica — ` +
-      `${replicas.length} times for this roll. Database migrations belong somewhere that runs once.`,
-    );
-  }
-
+  for (const warning of renderFleetWarnings(app, replicas)) ui.warn(`${app.name}: ${warning}`);
   for (const warning of renderDependencyWarnings(config, app)) ui.warn(warning);
 
   const result = await deployFleet({
     app,
     fleet: app.fleet!,
     replicas,
+    // From the full list, not the narrowed one: `--on web-b` must not promote
+    // web-b to primary and start a second copy of the scheduler alongside web-a's.
+    primary: allReplicas[0],
     remotePath: appConfig.remotePath,
     connect: async (serverName) => {
       const ssh = new SshConnection();
       await ssh.connect(configForServer(appConfig, serverName).ssh);
       return { executor: ssh, close: () => ssh.disconnect() };
     },
-    deployReplica: async ({ serverName, executor, releaseId }) => {
+    deployReplica: async ({ serverName, executor, releaseId, role }) => {
       const replicaConfig = { ...configForServer(appConfig, serverName), apps: [app], accessories: {} };
       const deployer = new DeployService(new LoggingExecutor(executor), replicaConfig);
-      await deployer.execute(cwd, options.skipBuild ?? false, releaseId);
+      await deployer.execute(cwd, options.skipBuild ?? false, releaseId, role);
     },
     onEvent: (event) => reportFleetEvent(app, event),
   });
@@ -344,11 +342,14 @@ function renderAppPlan(config: ShipnodeConfig, app: ShipnodeApp, skipBuild: bool
       serverRows.push([
         'PM2 apps',
         pm2Apps
-          .map((a) =>
-            a.port !== undefined
-              ? `${getPm2Name(namespace, a.name)}(web:${a.port})`
-              : getPm2Name(namespace, a.name),
-          )
+          .map((a) => {
+            const name = getPm2Name(namespace, a.name);
+            if (a.port !== undefined) return `${name}(web:${a.port})`;
+            // Where a pinned worker actually lands is the thing worth checking
+            // before the first roll — say it rather than leave it implied.
+            if (a.placement === 'primary' && replicas.length > 1) return `${name}(${replicas[0]} only)`;
+            return name;
+          })
           .join(', '),
       ]);
     }
@@ -359,6 +360,7 @@ function renderAppPlan(config: ShipnodeConfig, app: ShipnodeApp, skipBuild: bool
   if (app.dependsOn?.length) serverRows.push(['Depends on', app.dependsOn.join(', ')]);
 
   const dependencyWarnings = renderDependencyWarnings(config, app);
+  const fleetWarnings = renderFleetWarnings(app, replicas);
 
   const caddyPreview = renderCaddyPreview(config, app);
 
@@ -386,13 +388,15 @@ function renderAppPlan(config: ShipnodeConfig, app: ShipnodeApp, skipBuild: bool
     'Rsync files',
     'Install dependencies',
   );
+  if (app.hooks?.beforeFleet) steps.push('Run beforeFleet hook (first replica only)');
   if (app.hooks?.preDeploy) steps.push('Run preDeploy hook');
   steps.push('Switch symlink (atomic)');
   if (app.appType === 'backend') steps.push('Reload PM2');
   if (app.healthCheck.enabled) steps.push(`Health check ${app.healthCheck.path}`);
-  steps.push('Record release', 'Clean old releases');
+  steps.push('Record release');
   if (app.hooks?.postDeploy) steps.push('Run postDeploy hook');
-  steps.push('Release lock');
+  if (app.hooks?.afterFleet) steps.push('Run afterFleet hook (last replica only)');
+  steps.push('Clean old releases', 'Release lock');
   if (app.fleet) {
     steps.push(`Undrain (${app.fleet.readyPath} → 200)`, 'Repeat for the next batch');
   }
@@ -408,11 +412,30 @@ function renderAppPlan(config: ShipnodeConfig, app: ShipnodeApp, skipBuild: bool
     '',
     chalk.bold('  Deploy flow'),
     ...flowRows.map(([k, v]) => `    ${chalk.dim(k.padEnd(4))} ${v}`),
+    ...(fleetWarnings.length ? ['', chalk.bold('  Fleet hints'), ...fleetWarnings.map((line) => `    ${line}`)] : []),
     ...(dependencyWarnings.length ? ['', chalk.bold('  Dependency hints'), ...dependencyWarnings.map((line) => `    ${line}`)] : []),
     ...(caddyPreview ? ['', chalk.bold('  Caddy'), caddyPreview.split('\n').map((line) => `    ${line}`).join('\n')] : []),
   ].join('\n');
 }
 
+/**
+ * Caveats that only bite once an app has more than one replica, and that the
+ * config itself cannot decide for you.
+ */
+function renderFleetWarnings(app: ShipnodeApp, replicas: string[]): string[] {
+  if (replicas.length < 2) return [];
+  const warnings: string[] = [];
+
+  if (app.hooks?.preDeploy) {
+    warnings.push(
+      `preDeploy runs once per replica — ${replicas.length} times for this roll. ` +
+      `Move database migrations to .beforeFleet(), which runs once.`,
+    );
+  }
+
+  return warnings;
+}
+
 function renderDependencyWarnings(config: ShipnodeConfig, app: ShipnodeApp): string[] {
   const dependencies = app.dependsOn ?? [];
   if (dependencies.length === 0) return [];

src/config/builder.ts

@@ -11,6 +11,7 @@ import type {
   BackupConfig,
   CloudflareConfig,
   HookFn,
+  HooksConfig,
   PkgManager,
 } from '../shared/types.js';
 import { assembleConfig } from './assembly.js';
@@ -45,7 +46,7 @@ type BuilderState = {
   sharedDirs?: string[];
   sharedFiles?: string[];
   appRoot?: string;
-  hooks?: { preDeploy?: HookFn; postDeploy?: HookFn };
+  hooks?: HooksConfig;
   dependsOn?: string[];
   apps?: Partial<ShipnodeApp>[];
 };
@@ -260,6 +261,18 @@ export class ShipnodeBuilder {
     return this;
   }
 
+  /** Runs once per roll, on the first replica. Migrations belong here, not in `preDeploy`. */
+  beforeFleet(fn: HookFn): this {
+    this.config.hooks = { ...(this.config.hooks ?? {}), beforeFleet: fn };
+    return this;
+  }
+
+  /** Runs once per roll, on the last replica, after the whole fleet is on the new release. */
+  afterFleet(fn: HookFn): this {
+    this.config.hooks = { ...(this.config.hooks ?? {}), afterFleet: fn };
+    return this;
+  }
+
   aliases(map: Record<string, string>): this {
     this.config.aliases = { ...(this.config.aliases ?? {}), ...map };
     return this;
@@ -464,6 +477,18 @@ export class ShipnodeAppBuilder {
     return this;
   }
 
+  /** Runs once per roll, on the first replica. Migrations belong here, not in `preDeploy`. */
+  beforeFleet(fn: HookFn): this {
+    this.state.hooks = { ...(this.state.hooks ?? {}), beforeFleet: fn };
+    return this;
+  }
+
+  /** Runs once per roll, on the last replica, after the whole fleet is on the new release. */
+  afterFleet(fn: HookFn): this {
+    this.state.hooks = { ...(this.state.hooks ?? {}), afterFleet: fn };
+    return this;
+  }
+
   dependsOn(accessories: string[]): this {
     this.state.dependsOn = accessories;
     return this;

src/config/schema.ts

@@ -74,7 +74,13 @@ export const Pm2AppSchema = z.object({
   maxMemory: z.string().optional(),
   port: z.number().int().min(1).max(65535).optional(),
   env: z.record(z.string(), z.string()).optional(),
-});
+  placement: z.enum(['all', 'primary']).optional(),
+}).refine(
+  // Pinning the web process to one replica would defeat the point of the fleet:
+  // the load balancer would send traffic to replicas running nothing.
+  (app) => !(app.placement === 'primary' && app.port !== undefined),
+  { message: "placement 'primary' is for workers — a pm2 app with a port must run on every replica", path: ['placement'] },
+);
 
 export const Pm2ConfigSchema = z.object({
   apps: z.array(Pm2AppSchema).min(1, 'pm2.apps must contain at least one entry'),
@@ -158,6 +164,8 @@ const HookFnSchema = z
 export const HooksConfigSchema = z.object({
   preDeploy: HookFnSchema.optional(),
   postDeploy: HookFnSchema.optional(),
+  beforeFleet: HookFnSchema.optional(),
+  afterFleet: HookFnSchema.optional(),
 }).optional();
 
 // Per-app fields — anything that differs between two apps deployed to the same server.

src/domain/deploy/backend-strategy.ts

@@ -1,3 +1,4 @@
+import chalk from 'chalk';
 import { execa } from 'execa';
 import { pathExists } from 'fs-extra';
 import { resolve } from 'path';
@@ -115,9 +116,29 @@ export class BackendStrategy implements DeploymentStrategy {
     }
   }
 
+  /**
+   * The pm2 processes this replica is supposed to run.
+   *
+   * `placement: 'primary'` pins a process to one server — a scheduler running on
+   * three replicas fires every job three times — so on every other replica it is
+   * filtered out. This is the only place that decision is made; the namespace is
+   * still taken from the full declared list so `pm2 list` grouping matches
+   * across replicas.
+   */
+  private placedApps(ctx: StrategyContext): Pm2App[] {
+    const apps = this.app.pm2?.apps ?? [];
+    if (ctx.primaryReplica !== false) return apps;
+    return apps.filter((app) => app.placement !== 'primary');
+  }
+
   async startApp(ctx: StrategyContext): Promise<void> {
     if (!this.app.pm2) return;
 
+    if (this.placedApps(ctx).length === 0) {
+      console.log(chalk.dim(`  every pm2 process is placement: 'primary' — nothing to start on this replica`));
+      return;
+    }
+
     const pkgManager = await this.resolvePkgManager();
     const cdPath = `${this.appPath}/current`;
     const mise = `export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:$PATH"`;
@@ -141,7 +162,7 @@ export class BackendStrategy implements DeploymentStrategy {
     cdPath: string,
     mise: string,
   ): Promise<void> {
-    const ecosystemContent = this.generateEcosystemFile(pkgManager);
+    const ecosystemContent = this.generateEcosystemForApps(this.placedApps(ctx), pkgManager);
     // Ecosystem lives inside the release directory (per-release snapshot, ADR-0001).
     // PM2 references it via the `current` symlink so it always resolves to the active release.
     const ecosystemWritePath = `${ctx.workDir}/ecosystem.config.cjs`;
@@ -198,7 +219,7 @@ export class BackendStrategy implements DeploymentStrategy {
     if (!webApp) {
       throw new Error('Blue-green start requires one PM2 app with a port');
     }
-    const workers = pm2.apps.filter((a) => a.port === undefined);
+    const workers = this.placedApps(ctx).filter((a) => a.port === undefined);
     const coloredName = coloredWebName(namespace, webApp.name, target.color);
 
     // Web ecosystem: just the web app, coloured name, target-colour port.
@@ -237,7 +258,7 @@ export class BackendStrategy implements DeploymentStrategy {
   async afterHealthy(ctx: StrategyContext): Promise<void> {
     if (!this.app.zeroDowntime || !ctx.deployTarget || !this.app.pm2) return;
 
-    const workers = this.app.pm2.apps.filter((a) => a.port === undefined);
+    const workers = this.placedApps(ctx).filter((a) => a.port === undefined);
     if (workers.length === 0) return;
 
     const cdPath = `${this.appPath}/current`;
@@ -313,11 +334,6 @@ export class BackendStrategy implements DeploymentStrategy {
     }
   }
 
-  private generateEcosystemFile(pkgManager: string): string {
-    if (!this.app.pm2) return '';
-    return this.generateEcosystemForApps(this.app.pm2.apps, pkgManager);
-  }
-
   /**
    * Render an ecosystem file for a subset of the declared pm2 apps.
    *

src/domain/deploy/fleet.ts

@@ -1,7 +1,7 @@
 import type { FleetConfig, ShipnodeApp } from '../../shared/types.js';
 import type { RemoteExecutor } from '../remote/executor.js';
 import { drain, undrain } from './drain.js';
-import { newReleaseId } from './orchestrator.js';
+import { newReleaseId, type ReplicaRole } from './orchestrator.js';
 
 /**
  * Rolling one app across the servers it runs on.
@@ -39,7 +39,24 @@ export interface FleetDeployOptions {
   remotePath: string;
   connect: ReplicaConnector;
   /** Deploy this app on one replica — normally `DeployService.execute`. */
-  deployReplica: (ctx: { serverName: string; executor: RemoteExecutor; releaseId: string }) => Promise<void>;
+  deployReplica: (ctx: {
+    serverName: string;
+    executor: RemoteExecutor;
+    releaseId: string;
+    /**
+     * This replica's position in the roll, which decides where the run-once
+     * `beforeFleet` / `afterFleet` hooks fire. A roll that dies partway never
+     * reaches its last replica, so `afterFleet` correctly never runs.
+     */
+    role: ReplicaRole;
+  }) => Promise<void>;
+  /**
+   * The fleet's primary server, where `placement: 'primary'` processes run.
+   * Defaults to the first replica of this roll — pass it explicitly when the
+   * roll has been narrowed (`--on`), so a partial roll cannot promote a
+   * secondary replica and start a second scheduler.
+   */
+  primary?: string;
   releaseId?: string;
   onEvent?: (event: FleetEvent) => void;
   /** Injected so tests do not wait out a real drain. */
@@ -108,7 +125,16 @@ export async function deployFleet(options: FleetDeployOptions): Promise<FleetDep
         onEvent?.({ type: 'deploying', server });
 
         try {
-          await deployReplica({ serverName: server, executor: session.executor, releaseId });
+          await deployReplica({
+            serverName: server,
+            executor: session.executor,
+            releaseId,
+            role: {
+              first: server === replicas[0],
+              last: server === replicas[replicas.length - 1],
+              primary: server === (options.primary ?? replicas[0]),
+            },
+          });
         } catch (error) {
           failure = { server, message: error instanceof Error ? error.message : String(error) };
           onEvent?.({ type: 'failed', server, message: failure.message });