@stratusagent/gateway 0.11.9 → 0.12.0

package/dist/index.js

@@ -6,9 +6,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { createHash, randomUUID } from 'node:crypto';
-import { filePathsOf, isUnaddressedTurn, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, } from '@stratusagent/core';
-import { createCredentialRequestTool, createDelegateTool, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { filePathsOf, isUnaddressedTurn, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, matchesToolAllowlist, } from '@stratusagent/core';
+import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { ShardedSessionStore } from "./sessions.js";
 export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
@@ -16,7 +18,7 @@ export { SqliteSessionStore, ShardedSessionStore, FleetSessionIndex, SessionIdTa
 export { SqliteScheduleStore, createSchedulerRuntime, isScheduleSessionId, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
 import { loadPlugins, } from '@stratusagent/plugins';
-import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, stratusHomePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, createHostProtectedPaths, foldedAgentId, } from '@stratusagent/state';
+import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, stratusHomePath, intakeStatePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, createHostProtectedPaths, foldedAgentId, } from '@stratusagent/state';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 /**
  * How long a parked call waits for a person. Long enough to survive a
@@ -48,6 +50,92 @@ export const RESTARTING_TURN_ERROR = 'Run aborted: stratusd is restarting';
  * operator can hit agree.
  */
 export const DEFAULT_RESTART_DRAIN_TIMEOUT_MS = 30_000;
+/** What a paused daemon says when nobody gave it a sentence of its own. */
+export const DEFAULT_PAUSED_MESSAGE = "I'm paused right now and not taking new work. Please try again later.";
+/** What a held gateway answers a dispatch with, before it is promoted. */
+export const HELD_MESSAGE = "I'm starting up and not taking work yet. Please try again in a moment.";
+/** The longest pause message, so a reply to a refused message stays one. */
+export const MAX_PAUSED_MESSAGE_LENGTH = 500;
+/** A pause message the gateway will not take: empty, or too long. */
+export class PauseMessageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PauseMessageError';
+    }
+}
+/**
+ * A dispatch refused because intake is paused. Its message is the sentence
+ * to show whoever sent the work, as it is: a channel posts it as the reply,
+ * not as a failure.
+ */
+export class IntakePausedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IntakePausedError';
+    }
+}
+/**
+ * The intake state a previous process left, or open when there is none.
+ *
+ * Fails closed: a file that exists but cannot be read or parsed starts the
+ * daemon paused, with a warning naming it. A pause exists to stop work (a
+ * spending cap, a maintenance window), and a file nobody can read is no
+ * evidence that it was lifted.
+ */
+const readIntakeState = async (env, warn) => {
+    const file = intakeStatePath(env);
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { paused: false };
+        }
+        warn(`intake: ${file} could not be read (${error.message}); starting paused. Resume intake to clear it.`);
+        return { paused: true, since: new Date().toISOString() };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Only a pause is ever written here (resuming removes the file), so
+        // anything else in it is not a record this build wrote, and the same
+        // rule as an unreadable file applies.
+        if (typeof parsed !== 'object' || parsed === null || parsed.paused !== true) {
+            warn(`intake: ${file} does not hold a pause record; starting paused. Resume intake to clear it.`);
+            return { paused: true, since: new Date().toISOString() };
+        }
+        return {
+            paused: true,
+            ...(typeof parsed.message === 'string' && parsed.message.trim().length > 0 ? { message: parsed.message } : {}),
+            since: typeof parsed.since === 'string' ? parsed.since : new Date().toISOString(),
+        };
+    }
+    catch {
+        warn(`intake: ${file} is not valid JSON; starting paused. Resume intake to clear it.`);
+        return { paused: true, since: new Date().toISOString() };
+    }
+};
+/**
+ * Record a pause durably (0600, replaced in one atomic step), or remove the
+ * record when intake reopens: open is the default, so nothing on disk
+ * means open.
+ */
+const writeIntakeState = async (env, state) => {
+    const file = intakeStatePath(env);
+    if (!state.paused) {
+        await rm(file, { force: true });
+        return;
+    }
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const staging = `${file}.${randomBytes(8).toString('hex')}`;
+    try {
+        await writeFile(staging, `${JSON.stringify(state)}\n`, { flag: 'wx', mode: 0o600 });
+        await rename(staging, file);
+    }
+    finally {
+        await rm(staging, { force: true });
+    }
+};
 /**
  * `restart()` on a gateway whose host gave it no way back. Exported so the
  * control API can answer it as "not supported here" rather than as a
@@ -256,7 +344,7 @@ export const createGateway = (options = {}) => {
      * "cannot address" rather than a stale reference — and rejecting is how
      * both callers (schedule creation, `message.send`) hear why.
      */
-    const outboundFor = async (agentId, destination) => {
+    const outboundFor = async (agentId, destination, thread) => {
         const { adapter, carriesOthers } = channelCarrying(destination.channel, agentId, (candidate) => candidate.resolveOutbound !== undefined);
         if (!adapter?.resolveOutbound && carriesOthers) {
             throw new Error(`No running '${destination.channel}' channel carries agent ${agentId} — `
@@ -268,7 +356,7 @@ export const createGateway = (options = {}) => {
                     ? 'no channel adapters are running.'
                     : `running channels: ${startedChannels.map((candidate) => candidate.name).join(', ')}.`));
         }
-        return adapter.resolveOutbound({ agentId, to: destination.to });
+        return adapter.resolveOutbound({ agentId, to: destination.to, ...(thread !== undefined ? { thread } : {}) });
     };
     const scheduler = createSchedulerRuntime({
         store: scheduleStore,
@@ -286,6 +374,7 @@ export const createGateway = (options = {}) => {
         // The same stamp check every turn runs, before a slot is claimed — see
         // `SchedulerRuntimeOptions.ready`.
         ready: () => assertStateCompatible(env),
+        paused: () => intakeState.paused,
         log,
         warn,
     });
@@ -329,7 +418,39 @@ export const createGateway = (options = {}) => {
      * so a click racing the timeout — or arriving after an abort — is refused
      * rather than executing a tool for a turn that has already moved on.
      */
-    const requestApproval = (request) => new Promise((resolve) => {
+    /**
+     * The conversation a delegated sub-session's work was asked from, read
+     * from the store rather than from anything the caller wrote: the root
+     * session `agent.delegate` recorded, which is where the person waiting
+     * on the answer is. Undefined for an ordinary session, or a root that no
+     * longer exists — the request is then asked the way it always was.
+     */
+    const delegationOriginOf = async (session) => {
+        if (!isDelegatedSession(session)) {
+            return undefined;
+        }
+        const rootId = session.metadata?.[ROOT_SESSION_ID_METADATA_KEY];
+        if (typeof rootId !== 'string' || rootId === session.id) {
+            return undefined;
+        }
+        let root;
+        try {
+            root = await store.get(rootId);
+        }
+        catch (error) {
+            warn(`${session.id}: could not read the delegating session ${rootId} to route an approval (${error instanceof Error ? error.message : String(error)})`);
+            return undefined;
+        }
+        if (!root) {
+            return undefined;
+        }
+        return { agentId: root.agent.id, sessionId: root.id, ...(root.metadata ? { metadata: root.metadata } : {}) };
+    };
+    const requestApproval = async (request) => {
+        const delegatedFrom = await delegationOriginOf(request.session);
+        return requestApprovalFrom(request, delegatedFrom);
+    };
+    const requestApprovalFrom = (request, delegatedFrom) => new Promise((resolve) => {
         // A shutdown denies what is parked once, at the top of stop(). Turns
         // already running keep going through the drain, though, and one of them
         // can reach a gated tool AFTER that snapshot — finishing a provider
@@ -369,7 +490,17 @@ export const createGateway = (options = {}) => {
          * all and its denial should not wait on an emission that never runs.
          */
         let announced = Promise.resolve();
-        const settle = (answer, reason, actor) => {
+        // Work one agent does for another is allowed one call at a time. The
+        // people asked are the delegating conversation's, and a standing grant
+        // would widen what the other agent may do on its own work for good —
+        // so nothing offers **Always allow** here, and an `always` that
+        // arrives anyway (the control API takes all three answers) runs the
+        // call once, recorded as exactly that.
+        const forAnotherAgent = delegatedFrom !== undefined && delegatedFrom.agentId !== request.session.agent.id;
+        const oneShot = request.oneShot === true || forAnotherAgent;
+        const always = forAnotherAgent ? undefined : request.always;
+        const settle = (given, reason, actor) => {
+            const answer = forAnotherAgent && given === 'always' ? 'once' : given;
             // Identity, not presence: a request that already settled is gone from
             // the registry, and comparing against this exact function is what
             // makes every ending — click, timeout, abort, shutdown — idempotent.
@@ -414,11 +545,12 @@ export const createGateway = (options = {}) => {
                 call: request.call,
                 risk: request.risk,
                 ...(request.origin !== undefined ? { origin: request.origin } : {}),
-                ...(request.oneShot ? { oneShot: true } : {}),
-                ...(request.always !== undefined ? { always: request.always } : {}),
+                ...(oneShot ? { oneShot: true } : {}),
+                ...(always !== undefined ? { always } : {}),
                 parkedAt: request.parkedAt ?? new Date().toISOString(),
                 ...(expiresAt ? { expiresAt } : {}),
                 ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
+                ...(delegatedFrom ? { delegatedFrom } : {}),
             },
         });
         if (effectiveApprovalTimeoutMs > 0 && remainingTimeoutMs <= 0) {
@@ -462,9 +594,10 @@ export const createGateway = (options = {}) => {
             call: request.call,
             risk: request.risk,
             ...(request.origin !== undefined ? { origin: request.origin } : {}),
-            ...(request.oneShot ? { oneShot: true } : {}),
-            ...(request.always !== undefined ? { always: request.always } : {}),
+            ...(oneShot ? { oneShot: true } : {}),
+            ...(always !== undefined ? { always } : {}),
             ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
+            ...(delegatedFrom ? { delegatedFrom } : {}),
             ...(expiresAt ? { expiresAt } : {}),
         });
         // Drained at shutdown alongside the resolutions: a channel that has not
@@ -993,10 +1126,15 @@ export const createGateway = (options = {}) => {
     for (const scheduleTool of createScheduleTools(scheduler.handle)) {
         tools.register(scheduleTool);
     }
-    tools.register(createMessageSendTool(async ({ agentId, destination, text }) => {
-        const connection = await outboundFor(agentId, destination);
-        await connection.post(text);
-    }));
+    tools.register(createMessageSendTool(async ({ agentId, destination, text, thread }) => {
+        const connection = await outboundFor(agentId, destination, thread);
+        const posted = await connection.post(text);
+        // The channel contract's `OutboundMessageRef`, read structurally: the
+        // gateway's mirror of the adapter types `post` loosely, and an adapter
+        // that reports no id simply has none to hand back.
+        const ts = typeof posted === 'object' && posted !== null ? posted.ts : undefined;
+        return typeof ts === 'string' && ts.length > 0 ? { id: ts } : {};
+    }, { defaultThread: (session, destination) => scheduler.reportThreadFor(session, destination) }));
     tools.register(createMessageReadTool(async ({ agentId, source, ...window }) => {
         // The same carrying rule as outbound: a read goes through the app of
         // the agent asking, never whichever adapter of that kind is running,
@@ -1056,6 +1194,12 @@ export const createGateway = (options = {}) => {
                 ...(session.metadata ? { metadata: session.metadata } : {}),
             });
         };
+        // A link only for an agent whose soul lists the tool. Every agent may
+        // ask through a form, because a form goes to an approver; a link is a
+        // bearer credential the model is handed, and whoever it reaches can
+        // store a key and amend the soul. That is the operator's to allow.
+        const allowlist = session.agent.tools ?? registry.get(agentId)?.tools;
+        const linkAllowed = allowlist === undefined || matchesToolAllowlist(CREDENTIAL_REQUEST_TOOL_NAME, allowlist);
         // Why no form went up, said to the agent beside the link that replaces
         // it, so it can tell the person why they are getting a link instead.
         let formUnavailable;
@@ -1099,9 +1243,13 @@ export const createGateway = (options = {}) => {
                 }
             }
             if (request.via === 'form') {
-                throw new Error(`${formUnavailable} Nothing is pending. Ask for a link instead (via: "link"), or ask your operator to store ${request.name} on the machine with ${onMachine} and grant it to you.`);
+                throw new Error(`${formUnavailable} Nothing is pending. ${linkAllowed ? 'Ask for a link instead (via: "link"), or ask' : 'Ask'} your operator to store ${request.name} on the machine with ${onMachine} and grant it to you.`);
             }
         }
+        if (!linkAllowed) {
+            throw new Error(`${formUnavailable !== undefined ? `${formUnavailable} ` : ''}A one-time link needs ${CREDENTIAL_REQUEST_TOOL_NAME} in your soul's tools: list, and it is not there. Nothing is pending. `
+                + `Ask in a conversation that can show your operator a form, or ask your operator to store ${request.name} on the machine with ${onMachine} and grant it to you.`);
+        }
         // A link where no form can go, from whichever adapter issues them: the
         // control API, which is not tied to any one agent's transport.
         const linker = startedChannels.find((candidate) => candidate.requestCredentialLink !== undefined);
@@ -1289,7 +1437,8 @@ export const createGateway = (options = {}) => {
         // runtimes take it as their inner limit), so it is part of the key:
         // two agents on one model with different budgets get their own runners.
         const maxTurns = options.maxTurnsFor?.(agentId) ?? options.maxTurns;
-        const key = `${runnerKeyFor(config)}:${maxTurns ?? 'default'}`;
+        const autoContinue = options.autoContinueFor?.(agentId);
+        const key = `${runnerKeyFor(config)}:${maxTurns ?? 'default'}:${autoContinue ?? 'off'}`;
         const existing = runners.get(key);
         if (existing) {
             return existing;
@@ -1319,10 +1468,16 @@ export const createGateway = (options = {}) => {
             store,
             bus,
             agents: registry,
+            // Asking a person for a key is harmless to grant: they decide
+            // everything after the question, so no soul has to list it.
+            grantedToEveryAgent: [CREDENTIAL_REQUEST_TOOL_NAME],
             skills: skillCatalog,
             memory,
             streaming: true,
             ...(maxTurns !== undefined ? { maxTurns } : {}),
+            ...(autoContinue !== undefined
+                ? { autoContinue, waitingInput: (sessionId) => (waitingDispatches.get(sessionId) ?? 0) > 0 }
+                : {}),
         });
         hostedRunner = runner;
         runners.set(key, runner);
@@ -1585,8 +1740,30 @@ export const createGateway = (options = {}) => {
     // behind the in-flight turn instead of interleaving with it. Sessions
     // are independent — different conversations run concurrently.
     const sessionChains = new Map();
+    /**
+     * Dispatches queued behind a session's running turn, per session: what
+     * tells an auto-continuing turn that somebody wrote meanwhile, so it
+     * wraps up and lets them in rather than keep the session to itself.
+     */
+    const waitingDispatches = new Map();
     const inflight = new Set();
     let stopping = false;
+    // Open until `startServing` reads what the last process left, which it
+    // does before any channel or the scheduler can deliver work.
+    let intakeState = { paused: false };
+    let heldState = options.held === true;
+    /** What a held start left for `promote()`: the channels it did not start, and the sweeps it did not run. */
+    let deferredStart;
+    // Pause and resume run one at a time, each writing the file and then the
+    // state, so the two always agree: overlapping, a pause's write could land
+    // after a resume removed the file, leaving the daemon paused in memory
+    // and open on disk — open again after the next restart.
+    let intakeChain = Promise.resolve();
+    const intakeTransition = (work) => {
+        const run = intakeChain.then(work);
+        intakeChain = run.catch(() => undefined);
+        return run;
+    };
     /**
      * The abort handle of every turn running right now. A restart's drain
      * window ends by aborting these — the same signal the watchdog fires —
@@ -2461,6 +2638,17 @@ export const createGateway = (options = {}) => {
             input.onRepeat?.('live');
             return live.turn;
         }
+        // The one door every external dispatch comes through, so a pause holds
+        // for every channel at once. Work already accepted is not behind this
+        // check: a turn running, a redelivery of a message whose turn is live
+        // (answered above), a message queued behind it, a delegation or
+        // an approval resuming a parked turn all go on.
+        if (intakeState.paused) {
+            throw new IntakePausedError(intakeState.message ?? DEFAULT_PAUSED_MESSAGE);
+        }
+        if (heldState) {
+            throw new IntakePausedError(HELD_MESSAGE);
+        }
         // The live dispatch named no agent, so whose session it is is known
         // only once its turn resolves. Queueing instead would make this a
         // `finished` repeat of a turn the live caller is still rendering — two
@@ -2503,7 +2691,16 @@ export const createGateway = (options = {}) => {
             items.set(key, { turn, agentId: input.agentId, confirmed, addressed: input.addressed !== false });
             liveWorkItems.set(input.sessionId, items);
         };
+        waitingDispatches.set(input.sessionId, (waitingDispatches.get(input.sessionId) ?? 0) + 1);
         const turn = onSessionChain(input.sessionId, async () => {
+            // No longer waiting once it reaches the head of the chain.
+            const left = (waitingDispatches.get(input.sessionId) ?? 1) - 1;
+            if (left > 0) {
+                waitingDispatches.set(input.sessionId, left);
+            }
+            else {
+                waitingDispatches.delete(input.sessionId);
+            }
             // Before `activeTurns` is touched: a repeat that runs nothing must
             // not claim the session's turn id, even for the instant it takes.
             const repeated = idempotencyKey !== undefined ? await settleRepeat(input.sessionId, idempotencyKey, input.agentId, turnId, input.onRepeat) : undefined;
@@ -2767,6 +2964,10 @@ export const createGateway = (options = {}) => {
                 + `${reconciled.released.length} claim(s) released`);
         }
         await loadRoster();
+        intakeState = await readIntakeState(env, warn);
+        if (intakeState.paused) {
+            log(`intake is paused (since ${intakeState.since ?? 'unknown'}); new work will be refused until it resumes`);
+        }
         const named = registry.list().map((agent) => agent.name).join(', ');
         log(`stratusd ready — ${registry.list().length} agent(s): ${named}`);
         // Read before anything can dispatch, so this is exactly what the
@@ -2788,7 +2989,25 @@ export const createGateway = (options = {}) => {
             ...(options.channels ?? []),
             ...channelContributions.list().map((contribution) => contribution.adapter),
         ];
+        if (heldState) {
+            // Held: only the operator's surface comes up, and everything that
+            // would touch work waits for promote(), in the same order.
+            await startChannels(adapters.filter((adapter) => adapter.servesWhileHeld === true));
+            deferredStart = { adapters: adapters.filter((adapter) => adapter.servesWhileHeld !== true), orphaned, abandoned };
+            log('stratusd is held: answering health only, until promoted');
+            return;
+        }
+        await startChannels(adapters);
+        await beginWork(orphaned, abandoned);
+    };
+    const startChannels = async (adapters) => {
         for (const adapter of adapters) {
+            // A stop that began while an earlier channel was starting stops what
+            // is up; starting more after it would leave one it never sees, or
+            // one whose start never returns holding the stop open.
+            if (stopping) {
+                return;
+            }
             try {
                 await adapter.start(gateway);
                 startedChannels.push(adapter);
@@ -2820,6 +3039,8 @@ export const createGateway = (options = {}) => {
                 }
             }
         }
+    };
+    const beginWork = async (orphaned, abandoned) => {
         // After the channels, so a catch-up firing has somewhere to report and
         // the missed-window log lines land in a gateway whose surfaces are
         // listening. The sweep inside is quick (store reads); the firings it
@@ -2839,6 +3060,59 @@ export const createGateway = (options = {}) => {
             warn(`failing abandoned turns failed: ${error instanceof Error ? error.message : String(error)}`);
         });
     };
+    let promoting;
+    /**
+     * Why the work of a promotion could not begin, once it could not. Final:
+     * the scheduler stops for good when its readiness check fails (a newer
+     * build stamped the home), so a retry would report success with every
+     * schedule silently off. The daemon stays held and says why until it is
+     * restarted.
+     */
+    let promotionFailure;
+    const promote = async () => {
+        if (!heldState) {
+            return;
+        }
+        if (stopping) {
+            throw refusal();
+        }
+        // One promotion at a time: a second call while the first is connecting
+        // channels waits for it rather than starting them twice.
+        if (promotionFailure !== undefined) {
+            throw promotionFailure;
+        }
+        promoting ??= (async () => {
+            const pending = deferredStart;
+            if (pending === undefined) {
+                throw new Error('The gateway is held but has not finished starting; promote it once health answers.');
+            }
+            // Skipping any a failed earlier promotion already started, so a retry
+            // never starts one twice.
+            await startChannels(pending.adapters.filter((adapter) => !startedChannels.includes(adapter)));
+            // A stop that began while the channels were connecting has waited
+            // for this (see shutdown), and now stops them all. Nothing past here
+            // may start once it has.
+            if (stopping) {
+                throw refusal();
+            }
+            // Held until the work has actually begun: a scheduler that refuses to
+            // start (a newer build stamped the home meanwhile) must leave the
+            // daemon held, reporting so, and a retry able to try again.
+            try {
+                await beginWork(pending.orphaned, pending.abandoned);
+            }
+            catch (error) {
+                promotionFailure = new Error(`This daemon could not begin its work and stays held until it is restarted: ${error instanceof Error ? error.message : String(error)}`);
+                throw promotionFailure;
+            }
+            deferredStart = undefined;
+            heldState = false;
+            log('stratusd promoted: channels connected, schedules running');
+        })().finally(() => {
+            promoting = undefined;
+        });
+        return promoting;
+    };
     /**
      * Both stores, once. Reached from `stop()` and from a `start()` that
      * failed, and a host may call the one after the other; node:sqlite
@@ -2926,6 +3200,10 @@ export const createGateway = (options = {}) => {
         // drained; a plain stop goes on closing either way.
         let channelsReleased = true;
         const drain = (async () => {
+            // A promotion still connecting channels finishes first, so every
+            // channel it started is in the list stopped below; seeing `stopping`,
+            // it starts nothing after that.
+            await promoting?.catch(() => undefined);
             await Promise.allSettled([...approvalEmissions]);
             const stopping = [...startedChannels];
             const stops = await Promise.allSettled(stopping.map((adapter) => adapter.stop()));
@@ -3395,6 +3673,49 @@ export const createGateway = (options = {}) => {
             })).then((entries) => entries.filter((entry) => entry !== undefined));
         },
         resolveApproval,
+        intake() {
+            return { ...intakeState };
+        },
+        async pauseIntake(input = {}) {
+            let message;
+            if (input.message !== undefined) {
+                const trimmed = input.message.trim();
+                if (trimmed.length === 0) {
+                    throw new PauseMessageError('A pause message cannot be empty; leave it out to use the default.');
+                }
+                if (trimmed.length > MAX_PAUSED_MESSAGE_LENGTH) {
+                    throw new PauseMessageError(`A pause message is at most ${MAX_PAUSED_MESSAGE_LENGTH} characters; this one is ${trimmed.length}.`);
+                }
+                message = trimmed;
+            }
+            return intakeTransition(async () => {
+                const next = {
+                    paused: true,
+                    ...(message !== undefined ? { message } : {}),
+                    since: intakeState.paused && intakeState.since ? intakeState.since : new Date().toISOString(),
+                };
+                // Durable first: a pause the process reports but would forget at
+                // the next crash is the gap the file exists to close.
+                await writeIntakeState(env, next);
+                intakeState = next;
+                log('intake paused: new work will be refused until it resumes');
+                return { ...intakeState };
+            });
+        },
+        held() {
+            return heldState;
+        },
+        promote,
+        async resumeIntake() {
+            return intakeTransition(async () => {
+                await writeIntakeState(env, { paused: false });
+                if (intakeState.paused) {
+                    log('intake resumed');
+                }
+                intakeState = { paused: false };
+                return { ...intakeState };
+            });
+        },
         provideCredential,
     };
     return gateway;