hereya-cli 0.89.1 → 0.91.0

package/dist/commands/executor/start/index.js

@@ -1,59 +1,14 @@
 import { Command, Flags } from '@oclif/core';
 import { randomUUID } from 'node:crypto';
-import fs from 'node:fs/promises';
 import os from 'node:os';
-import path from 'node:path';
 import { CloudBackend } from '../../../backend/cloud/cloud-backend.js';
-import { loginWithToken } from '../../../backend/cloud/login.js';
-import { saveCloudCredentials } from '../../../backend/config.js';
 import { clearBackend, getBackend } from '../../../backend/index.js';
 import { LocalExecutor } from '../../../executor/local.js';
-import * as appSourceLib from '../../../lib/app-source.js';
-import { SimpleConfigManager } from '../../../lib/config/simple.js';
-import { cloneWithCredentialHelper, gitUtils } from '../../../lib/git-utils.js';
-import { runShell, shellUtils } from '../../../lib/shell.js';
-/**
- * Workspaces look like `org/name`, which is not filesystem-safe. The
- * write-side in `app deploy --local` (commands/app/deploy/index.ts) MUST use
- * the same sanitization.
- */
-function sanitizeWorkspaceForFilename(workspace) {
-    return workspace.replaceAll('/', '-');
-}
-/**
- * Strip credentials from log strings before flushing them to the cloud.
- * Removes:
- *   - any occurrence of the actual hereyaGitPassword value
- *   - userinfo from URLs (https://user:pass@host -> https://host)
- */
-export function redactCredentials(str, password) {
-    let out = str;
-    if (password) {
-        // Replace every exact occurrence of the password with a placeholder.
-        out = out.split(password).join('[REDACTED]');
-    }
-    // Strip userinfo from URLs (http/https/git).
-    out = out.replaceAll(/(https?:\/\/|git:\/\/)([^/\s@]+@)/g, '$1');
-    return out;
-}
-async function createAuthenticatedBackend(hereyaToken, cloudUrl) {
-    const loginResult = await loginWithToken(cloudUrl, hereyaToken);
-    if (!loginResult.success) {
-        throw new Error(`Failed to authenticate: ${loginResult.error}`);
-    }
-    await saveCloudCredentials({
-        accessToken: loginResult.accessToken,
-        clientId: loginResult.clientId,
-        refreshToken: loginResult.refreshToken,
-        url: cloudUrl,
-    });
-    return new CloudBackend({
-        accessToken: loginResult.accessToken,
-        clientId: loginResult.clientId,
-        refreshToken: loginResult.refreshToken,
-        url: cloudUrl,
-    });
-}
+import { createAuthenticatedBackend } from '../../../lib/executor-start/auth.js';
+import { executeAppJob } from '../../../lib/executor-start/execute-app-job.js';
+import { executeInitJob } from '../../../lib/executor-start/execute-init-job.js';
+import { dispatchJob } from '../../../lib/executor-start/job-dispatch.js';
+export { redactCredentials } from '../../../lib/executor-start/format.js';
 export default class ExecutorStart extends Command {
     static description = `Start the remote executor process (polls for jobs from hereya cloud).
 
@@ -74,6 +29,11 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
             description: 'maximum number of parallel jobs',
             min: 1,
         }),
+        idleTimeout: Flags.integer({
+            char: 'i',
+            description: 'seconds idle before exit; omit to keep running indefinitely',
+            min: 1,
+        }),
         workspace: Flags.string({
             char: 'w',
             description: 'name of the workspace to poll jobs for',
@@ -82,7 +42,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
     };
     async run() {
         const { flags } = await this.parse(ExecutorStart);
-        const { concurrency } = flags;
+        const { concurrency, idleTimeout } = flags;
         const executor = new LocalExecutor();
         const hereyaToken = process.env.HEREYA_TOKEN;
         const cloudUrl = process.env.HEREYA_CLOUD_URL || 'https://cloud.hereya.dev';
@@ -98,9 +58,9 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
             cloudBackend = backend;
         }
         const executorId = `${os.hostname()}-${randomUUID().slice(0, 8)}`;
-        this.log(`Starting executor ${executorId} for workspace: ${flags.workspace} (concurrency: ${concurrency})`);
+        const idleSuffix = idleTimeout ? `, idle-timeout: ${idleTimeout}s` : '';
+        this.log(`Starting executor ${executorId} for workspace: ${flags.workspace} (concurrency: ${concurrency}${idleSuffix})`);
         this.log('Polling for jobs...');
-        // Handle graceful shutdown
         const state = { shuttingDown: false };
         const shutdown = () => {
             this.log('Shutting down executor...');
@@ -109,503 +69,141 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
         const activeJobs = new Set();
-        while (!state.shuttingDown) {
+        const hooks = { log: (m) => this.log(m), warn: (m) => this.warn(m) };
+        // Idle clock advances on every successful poll OR while jobs are running.
+        // Generic transient errors (5xx, network) deliberately do NOT advance it
+        // — a flaky cloud must not keep the EC2 alive forever. Persistent 401s
+        // are handled separately by `consecutive401s` below.
+        const startedAt = Date.now();
+        let lastJobAt = startedAt;
+        let lastSuccessfulPollAt = startedAt;
+        const MAX_CONSECUTIVE_401S = 3;
+        let consecutive401s = 0;
+        let authFailureExit = false;
+        while (!state.shuttingDown && !authFailureExit) {
             try {
-                // Wait for a slot to open up if at concurrency limit
-                if (activeJobs.size >= concurrency) {
-                    // eslint-disable-next-line no-await-in-loop
-                    await Promise.race(activeJobs);
-                    continue;
-                }
                 // eslint-disable-next-line no-await-in-loop
-                const pollResult = await cloudBackend.pollExecutorJobs({
+                const step = await this.runPollIteration({
+                    activeJobs,
+                    cloudBackend,
+                    cloudUrl,
+                    concurrency,
+                    consecutive401s,
+                    executor,
                     executorId,
+                    hereyaToken,
+                    hooks,
+                    idleTimeout,
+                    lastJobAt,
+                    lastSuccessfulPollAt,
+                    maxConsecutive401s: MAX_CONSECUTIVE_401S,
                     workspace: flags.workspace,
                 });
-                if (!pollResult.success) {
-                    if ('unauthorized' in pollResult && pollResult.unauthorized && hereyaToken) {
-                        this.log('Access token expired. Re-authenticating...');
-                        clearBackend();
-                        // eslint-disable-next-line no-await-in-loop
-                        cloudBackend = await createAuthenticatedBackend(hereyaToken, cloudUrl);
-                        continue;
-                    }
-                    this.warn(`Poll error: ${pollResult.reason}`);
-                    // eslint-disable-next-line no-await-in-loop
-                    await new Promise(resolve => {
-                        setTimeout(resolve, 5000);
-                    });
-                    continue;
-                }
-                if (!pollResult.job) {
-                    // No job available, continue polling
-                    continue;
+                consecutive401s = step.consecutive401s;
+                lastJobAt = step.lastJobAt;
+                lastSuccessfulPollAt = step.lastSuccessfulPollAt;
+                if (step.cloudBackend)
+                    cloudBackend = step.cloudBackend;
+                if (step.exit) {
+                    authFailureExit = true;
+                    break;
                 }
-                const { job } = pollResult;
-                this.log(`Received job ${job.id} (${job.type}) [${activeJobs.size + 1}/${concurrency} slots used]`);
-                // Fire off the job without awaiting it
-                const jobPromise = this.executeJob(job, executor, cloudBackend).finally(() => {
-                    activeJobs.delete(jobPromise);
-                });
-                activeJobs.add(jobPromise);
+                if (step.idleShutdown)
+                    break;
             }
             catch (error) {
                 this.warn(`Executor error: ${error.message}`);
-                // Wait before retrying
                 // eslint-disable-next-line no-await-in-loop
                 await new Promise(resolve => {
                     setTimeout(resolve, 5000);
                 });
             }
         }
-        // Wait for all active jobs to complete before exiting
         if (activeJobs.size > 0) {
             this.log(`Waiting for ${activeJobs.size} active job(s) to complete...`);
             await Promise.allSettled(activeJobs);
         }
         this.log('Executor stopped.');
-    }
-    async executeAppJob(job, cloudBackend, logger) {
-        const isDeploy = job.type === 'app-deploy';
-        const subcommand = isDeploy ? 'deploy' : 'destroy';
-        const payload = job.payload;
-        const { appName, commit, parameters: providedParameters, repository, sha256, version, workspace } = payload;
-        if (!appName || !workspace || !repository) {
-            return {
-                reason: `Missing appName, workspace, or repository in ${job.type} job payload`,
-                success: false,
-            };
-        }
-        let cleanup;
-        try {
-            logger.info(`Downloading app source ${repository}${commit ? `@${commit}` : ''}...`);
-            const downloadResult = await appSourceLib.appSource.download({ commit, logger, repository, sha256 });
-            cleanup = downloadResult.cleanup;
-            const { rootDir } = downloadResult;
-            // Mark deployment as deploying / destroying.
-            await cloudBackend.updateAppDeployment({
-                lastJobId: job.id,
-                name: appName,
-                status: isDeploy ? 'deploying' : 'destroying',
-                workspace,
-            });
-            // Build -p flag args from job payload parameters.
-            const parameters = providedParameters ?? {};
-            const paramFlags = [];
-            for (const [key, value] of Object.entries(parameters)) {
-                paramFlags.push('-p', `${key}=${value}`);
-            }
-            // For app-deploy, forward --version so the local command can serialize it into
-            // the deploy-env file's `state` block (which the cloud reads back via PATCH).
-            const versionFlags = isDeploy && version ? ['--version', version] : [];
-            // Shell out to `hereya app <subcommand> <appName> -w <workspace> [-p ...] [--version ...] --local`.
-            // The local command holds the provisioning logic (mirrors deploy/undeploy shell-out pattern).
-            logger.info(`Running hereya app ${subcommand} ${appName} -w ${workspace} --local...`);
-            let runResult;
-            try {
-                runResult = await shellUtils.runShell('hereya', ['app', subcommand, appName, '-w', workspace, ...paramFlags, ...versionFlags, '--local'], {
-                    directory: rootDir,
-                    env: { ...process.env, HEREYA_LOCAL_EXECUTION: 'true', HEREYA_PROJECT_ROOT_DIR: rootDir },
-                    logger,
-                });
-            }
-            catch (error) {
-                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: error.message, workspace }, cloudBackend);
-                return { reason: `hereya app ${subcommand} failed: ${error.message}`, success: false };
-            }
-            if (runResult && runResult.status !== 0) {
-                const reason = `hereya app ${subcommand} exited with code ${runResult.status}`;
-                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason, workspace }, cloudBackend);
-                return { reason, success: false };
-            }
-            // PATCH final state to the cloud.
-            const patchResult = await this.patchAppFinalState({
-                appName,
-                cloudBackend,
-                isDeploy,
-                jobId: job.id,
-                rootDir,
-                workspace,
-            });
-            if (!patchResult.success) {
-                return patchResult;
-            }
-            return { success: true };
-        }
-        catch (error) {
-            try {
-                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: error.message, workspace }, cloudBackend);
-            }
-            catch {
-                // best-effort
-            }
-            return { reason: `app-${subcommand} failed: ${error.message}`, success: false };
-        }
-        finally {
-            if (cleanup) {
-                await cleanup();
-            }
+        if (authFailureExit) {
+            // Hard exit so systemd's `OnFailure=shutdown.target` triggers an EC2
+            // halt on persistent authentication failure (e.g. token revoked).
+            // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+            process.exit(1);
         }
     }
-    async executeDeployJob(job, executor, cloudBackend, logger) {
-        const { gitBranch, project, workspace } = job.payload;
-        if (!project || !workspace) {
-            return { reason: 'Missing project or workspace in job payload', success: false };
-        }
-        // 1. Get project metadata to find git credentials
-        const metadata$ = await cloudBackend.getProjectMetadata({ project });
-        if (!metadata$.found) {
-            return { reason: `No metadata found for project ${project}`, success: false };
-        }
-        const { metadata } = metadata$;
-        if (!metadata.env?.hereyaGitRemoteUrl) {
-            return { reason: 'Project metadata missing hereyaGitRemoteUrl', success: false };
-        }
-        // 2. Resolve git credentials using the local executor
-        const gitEnvToResolve = {};
-        for (const [key, value] of Object.entries(metadata.env)) {
-            if (key.startsWith('hereyaGit'))
-                gitEnvToResolve[key] = value;
-        }
-        const resolvedGitEnv = await executor.resolveEnvValues({ env: gitEnvToResolve, project, workspace });
-        // 3. Clone repo at specified branch into temp dir
-        const tempDir = path.join(os.tmpdir(), `hereya-deploy-${randomUUID()}`);
-        try {
-            const branch = gitBranch || 'main';
-            logger.info(`Cloning ${resolvedGitEnv.hereyaGitRemoteUrl} (branch: ${branch})...`);
-            const cloneResult = await cloneWithCredentialHelper({
-                gitUrl: resolvedGitEnv.hereyaGitRemoteUrl,
-                hereyaBinPath: process.argv[1],
-                password: resolvedGitEnv.hereyaGitPassword,
-                targetDir: tempDir,
-                username: resolvedGitEnv.hereyaGitUsername,
-            });
-            if (!cloneResult.success) {
-                return { reason: `Git clone failed: ${cloneResult.reason}`, success: false };
-            }
-            // Checkout the correct branch if not main/master
-            if (branch !== 'main' && branch !== 'master') {
-                await runShell('git', ['checkout', branch], { directory: tempDir, logger });
-            }
-            // 4. Run hereya deploy/undeploy --local inside the cloned repo
-            const command = job.type === 'deploy' ? 'deploy' : 'undeploy';
-            logger.info(`Running hereya ${command} -w ${workspace} --local...`);
-            const result = await runShell('hereya', [command, '-w', workspace, '--local'], {
-                directory: tempDir,
-                env: { ...process.env, HEREYA_LOCAL_EXECUTION: 'true', HEREYA_PROJECT_ROOT_DIR: tempDir },
-                logger,
-            });
-            logger.info(`hereya ${command} exited with code ${result.status}`);
-            if (result.status !== 0) {
-                return { reason: `hereya ${command} failed (exit code ${result.status})`, success: false };
-            }
-            return { success: true };
-        }
-        finally {
-            // 5. Clean up temp dir
-            try {
-                await fs.rm(tempDir, { force: true, recursive: true });
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-        }
+    // Test-friendly delegators kept on the class for backwards compatibility with
+    // tests that call `(cmd as any).executeInitJob(...)` / `executeAppJob(...)`.
+    executeAppJob(job, cloudBackend, logger) {
+        return executeAppJob(job, cloudBackend, logger);
     }
-    async executeInitJob(job, executor, logger) {
-        const payload = job.payload;
-        const { deployWorkspace, parameters, projectName, template, workspace } = payload;
-        if (!projectName || !workspace || !template || !deployWorkspace) {
-            return {
-                reason: 'Missing projectName, workspace, template, or deployWorkspace in job payload',
-                success: false,
-            };
-        }
-        // Track the password here (captured after provision) so the redacting logger knows what
-        // to strip. Until we have it, redaction still runs for URL userinfo.
-        let password;
-        const redactingLogger = {
-            debug(msg) {
-                logger.debug(redactCredentials(msg, password));
-            },
-            error(msg) {
-                logger.error(redactCredentials(msg, password));
-            },
-            info(msg) {
-                logger.info(redactCredentials(msg, password));
-            },
-        };
-        const scratchDir = await fs.mkdtemp(path.join(os.tmpdir(), 'hereya-init-'));
-        try {
-            // 1. Provision template
-            redactingLogger.info(`Provisioning template ${template}...`);
-            const provisionResult = await executor.provision({
-                logger: redactingLogger,
-                package: template,
-                parameters: {
-                    ...parameters,
-                    deployWorkspace,
-                    projectName,
-                    workspace,
-                },
-                project: projectName,
-                workspace,
-            });
-            if (!provisionResult.success) {
-                return { reason: `Template provisioning failed: ${provisionResult.reason}`, success: false };
-            }
-            const { env } = provisionResult;
-            const { hereyaGitPassword, hereyaGitRemoteUrl, hereyaGitUsername } = env;
-            password = hereyaGitPassword;
-            if (!hereyaGitRemoteUrl) {
-                return { reason: 'Template did not export hereyaGitRemoteUrl', success: false };
-            }
-            // 2. Clone repo into scratch dir.
-            redactingLogger.info(`Cloning ${hereyaGitRemoteUrl}...`);
-            // Clone into a subdirectory so we control the target exactly.
-            const repoDir = path.join(scratchDir, 'repo');
-            const cloneResult = await gitUtils.cloneWithCredentialHelper({
-                gitUrl: hereyaGitRemoteUrl,
-                hereyaBinPath: process.argv[1],
-                password: hereyaGitPassword,
-                targetDir: repoDir,
-                username: hereyaGitUsername,
-            });
-            if (!cloneResult.success) {
-                return { reason: `Git clone failed: ${cloneResult.reason}`, success: false };
-            }
-            // 3. Write hereya.yaml
-            redactingLogger.info('Writing hereya.yaml...');
-            const config = {
-                project: projectName,
-                workspace,
-            };
-            await new SimpleConfigManager().saveConfig({ config, projectRootDir: repoDir });
-            // 4. Commit + push
-            redactingLogger.info('Committing and pushing initial project config...');
-            const gitEnv = {
-                ...process.env,
-                GIT_AUTHOR_EMAIL: 'executor@hereya.dev',
-                GIT_AUTHOR_NAME: 'hereya-executor',
-                GIT_COMMITTER_EMAIL: 'executor@hereya.dev',
-                GIT_COMMITTER_NAME: 'hereya-executor',
-            };
-            if (hereyaGitUsername)
-                gitEnv.hereyaGitUsername = hereyaGitUsername;
-            if (hereyaGitPassword)
-                gitEnv.hereyaGitPassword = hereyaGitPassword;
-            try {
-                await shellUtils.runShell('git', ['add', '.'], { directory: repoDir, env: gitEnv, logger: redactingLogger });
-                await shellUtils.runShell('git', ['commit', '-m', '"chore: hereya init"'], {
-                    directory: repoDir,
-                    env: gitEnv,
-                    logger: redactingLogger,
-                });
-                await shellUtils.runShell('git', ['push', 'origin', 'HEAD'], {
-                    directory: repoDir,
-                    env: gitEnv,
-                    logger: redactingLogger,
-                });
-            }
-            catch (error) {
-                return {
-                    reason: `Git commit/push failed: ${redactCredentials(error.message ?? String(error), password)}`,
-                    success: false,
-                };
-            }
-            return { hereyaGitRemoteUrl, success: true };
-        }
-        catch (error) {
-            return {
-                reason: `Init failed: ${redactCredentials(error.message ?? String(error), password)}`,
-                success: false,
-            };
-        }
-        finally {
-            try {
-                await fs.rm(scratchDir, { force: true, recursive: true });
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-        }
+    executeInitJob(job, executor, logger) {
+        return executeInitJob(job, executor, logger);
     }
-    async executeJob(job, executor, cloudBackend) {
-        // Set up buffered logging
-        let logBuffer = '';
-        const logInterval = setInterval(async () => {
-            if (logBuffer) {
-                const logs = logBuffer;
-                logBuffer = '';
-                try {
-                    await cloudBackend.updateExecutorJob({
-                        jobId: job.id,
-                        logs,
-                    });
-                }
-                catch {
-                    // Log flush errors are non-fatal
-                }
-            }
-        }, 10_000);
-        // Heartbeat every 30 seconds (independent of log flushing)
-        const heartbeatInterval = setInterval(async () => {
-            try {
-                await cloudBackend.updateExecutorJob({ jobId: job.id });
-            }
-            catch {
-                // Heartbeat errors are non-fatal
-            }
-        }, 30_000);
-        const logger = {
-            debug(msg) {
-                logBuffer += msg + '\n';
-            },
-            error(msg) {
-                logBuffer += msg + '\n';
-            },
-            info(msg) {
-                logBuffer += msg + '\n';
-            },
-        };
-        try {
-            if (job.type === 'resolve-env') {
-                // resolve-env job: resolve env values using local executor
-                const resolved = await executor.resolveEnvValues(job.payload);
-                // Send resolved env as result
-                clearInterval(logInterval);
-                clearInterval(heartbeatInterval);
-                await cloudBackend.updateExecutorJob({
-                    jobId: job.id,
-                    logs: logBuffer,
-                    result: { env: resolved, success: true },
-                    status: 'completed',
-                });
-                this.log(`Job ${job.id} completed (resolve-env)`);
-                return;
-            }
-            if (job.type === 'deploy' || job.type === 'undeploy') {
-                const deployResult = await this.executeDeployJob(job, executor, cloudBackend, logger);
-                clearInterval(logInterval);
-                clearInterval(heartbeatInterval);
-                await cloudBackend.updateExecutorJob({
-                    jobId: job.id,
-                    logs: logBuffer,
-                    result: deployResult,
-                    status: deployResult.success ? 'completed' : 'failed',
-                });
-                this.log(`Job ${job.id} ${deployResult.success ? 'completed' : 'failed'} (${job.type})`);
-                return;
-            }
-            if (job.type === 'init') {
-                const initResult = await this.executeInitJob(job, executor, logger);
-                clearInterval(logInterval);
-                clearInterval(heartbeatInterval);
-                await cloudBackend.updateExecutorJob({
-                    jobId: job.id,
-                    logs: logBuffer,
-                    result: initResult,
-                    status: initResult.success ? 'completed' : 'failed',
-                });
-                this.log(`Job ${job.id} ${initResult.success ? 'completed' : 'failed'} (init)`);
-                return;
-            }
-            if (job.type === 'app-deploy' || job.type === 'app-destroy') {
-                const appJobResult = await this.executeAppJob(job, cloudBackend, logger);
-                clearInterval(logInterval);
-                clearInterval(heartbeatInterval);
-                await cloudBackend.updateExecutorJob({
-                    jobId: job.id,
-                    logs: logBuffer,
-                    result: appJobResult,
-                    status: appJobResult.success ? 'completed' : 'failed',
-                });
-                this.log(`Job ${job.id} ${appJobResult.success ? 'completed' : 'failed'} (${job.type})`);
-                return;
-            }
-            const result = job.type === 'provision'
-                ? await executor.provision({
-                    ...job.payload,
-                    logger,
-                })
-                : await executor.destroy({
-                    ...job.payload,
-                    logger,
-                });
-            // Flush remaining logs and send result
-            clearInterval(logInterval);
-            clearInterval(heartbeatInterval);
-            await cloudBackend.updateExecutorJob({
-                jobId: job.id,
-                logs: logBuffer,
-                result,
-                status: result.success ? 'completed' : 'failed',
-            });
-            this.log(`Job ${job.id} ${result.success ? 'completed' : 'failed'}`);
+    async handleUnauthorizedPoll(args) {
+        const { cloudUrl, consecutive401s, hereyaToken, max } = args;
+        if (consecutive401s >= max) {
+            this.warn(`Persistent authentication failure: ${consecutive401s} consecutive 401 responses from hereya cloud. Token likely revoked or expired. Exiting.`);
+            return { exit: true };
         }
-        catch (error) {
-            clearInterval(logInterval);
-            clearInterval(heartbeatInterval);
-            await cloudBackend.updateExecutorJob({
-                jobId: job.id,
-                logs: logBuffer + `\nError: ${error.message}\n`,
-                result: { reason: error.message, success: false },
-                status: 'failed',
-            });
-            this.warn(`Job ${job.id} failed: ${error.message}`);
+        if (hereyaToken) {
+            this.log(`Access token expired (attempt ${consecutive401s}/${max}). Re-authenticating...`);
+            clearBackend();
+            const cloudBackend = await createAuthenticatedBackend(hereyaToken, cloudUrl);
+            return { cloudBackend, exit: false };
         }
+        this.warn(`Unauthorized poll (attempt ${consecutive401s}/${max}); no HEREYA_TOKEN available to re-authenticate.`);
+        return { exit: false };
     }
-    async markAppDeploymentFailed(input, cloudBackend) {
-        try {
-            await cloudBackend.updateAppDeployment({
-                lastJobId: input.jobId,
-                name: input.appName,
-                status: 'failed',
-                workspace: input.workspace,
+    async runPollIteration(args) {
+        const { activeJobs, cloudBackend, cloudUrl, concurrency, executor, executorId, hereyaToken, hooks, idleTimeout, maxConsecutive401s, workspace, } = args;
+        let { consecutive401s, lastJobAt, lastSuccessfulPollAt } = args;
+        if (activeJobs.size > 0) {
+            lastJobAt = Date.now();
+        }
+        if (activeJobs.size >= concurrency) {
+            await Promise.race(activeJobs);
+            return { consecutive401s, lastJobAt, lastSuccessfulPollAt };
+        }
+        const pollResult = await cloudBackend.pollExecutorJobs({ executorId, workspace });
+        if (!pollResult.success && 'unauthorized' in pollResult && pollResult.unauthorized) {
+            consecutive401s += 1;
+            const action = await this.handleUnauthorizedPoll({
+                cloudUrl,
+                consecutive401s,
+                hereyaToken,
+                max: maxConsecutive401s,
             });
-        }
-        catch {
-            // best-effort; failure of the PATCH must not bubble out
-        }
-    }
-    async patchAppFinalState(input) {
-        const { appName, cloudBackend, isDeploy, jobId, rootDir, workspace } = input;
-        if (!isDeploy) {
-            const updateResult = await cloudBackend.updateAppDeployment({
-                env: {},
-                lastJobId: jobId,
-                name: appName,
-                status: 'destroyed',
-                workspace,
+            if (action.exit)
+                return { consecutive401s, exit: true, lastJobAt, lastSuccessfulPollAt };
+            return { cloudBackend: action.cloudBackend, consecutive401s, lastJobAt, lastSuccessfulPollAt };
+        }
+        if (!pollResult.success) {
+            this.warn(`Poll error: ${pollResult.reason}`);
+            await new Promise((resolve) => {
+                setTimeout(resolve, 5000);
             });
-            if (!updateResult.success) {
-                return { reason: `Destroy succeeded but PATCH to deployment failed: ${updateResult.reason}`, success: false };
-            }
-            return { success: true };
-        }
-        // Read .hereya/deploy-env.<workspace>.json that was written by `app deploy --local`.
-        // Filename sanitization MUST match the write side (see `sanitizeWorkspaceForFilename`).
-        const deployEnvFile = path.join(rootDir, '.hereya', `deploy-env.${sanitizeWorkspaceForFilename(workspace)}.json`);
-        let parsed;
-        try {
-            const content = await fs.readFile(deployEnvFile, 'utf8');
-            parsed = JSON.parse(content);
-        }
-        catch (error) {
-            const reason = `Failed to read deploy env file at ${deployEnvFile}: ${error.message}`;
-            await this.markAppDeploymentFailed({ appName, jobId, reason, workspace }, cloudBackend);
-            return { reason, success: false };
+            return { consecutive401s, lastJobAt, lastSuccessfulPollAt };
+        }
+        // Successful poll: clear the 401 counter and advance the idle clock.
+        consecutive401s = 0;
+        lastSuccessfulPollAt = Date.now();
+        if (pollResult.job) {
+            const { job } = pollResult;
+            this.log(`Received job ${job.id} (${job.type}) [${activeJobs.size + 1}/${concurrency} slots used]`);
+            lastJobAt = Date.now();
+            const jobPromise = dispatchJob(job, executor, cloudBackend, hooks).finally(() => {
+                activeJobs.delete(jobPromise);
+            });
+            activeJobs.add(jobPromise);
+            return { consecutive401s, lastJobAt, lastSuccessfulPollAt };
         }
-        const updateResult = await cloudBackend.updateAppDeployment({
-            env: parsed.env ?? {},
-            lastJobId: jobId,
-            name: appName,
-            state: parsed.state,
-            status: 'deployed',
-            workspace,
-        });
-        if (!updateResult.success) {
-            return { reason: `Provisioning succeeded but PATCH to deployment failed: ${updateResult.reason}`, success: false };
+        if (idleTimeout !== undefined &&
+            activeJobs.size === 0 &&
+            Date.now() - lastJobAt > idleTimeout * 1000) {
+            const afterMs = Date.now() - lastJobAt;
+            this.log(JSON.stringify({ afterMs, event: 'executor.idle.shutdown', lastSuccessfulPollAt }));
+            return { consecutive401s, idleShutdown: true, lastJobAt, lastSuccessfulPollAt };
         }
-        return { success: true };
+        return { consecutive401s, lastJobAt, lastSuccessfulPollAt };
     }
 }