@stratusagent/cli 0.10.0 → 0.11.0

package/dist/index.js

@@ -8,18 +8,19 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
-import { AgentRunner, AllowAllApprovalPolicy, EventBus, SkillRegistry, ToolRegistry, matchesSkillAllowlist, missingSkillRequirements, } from '@stratusagent/core';
+import { AgentRunner, AllowAllApprovalPolicy, EventBus, SkillRegistry, ToolRegistry, matchesSkillAllowlist, missingSkillRequirements, originOf, } from '@stratusagent/core';
 import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
 import { loadPlugins } from '@stratusagent/plugins';
-import { createFileCommandWhitelist, createPermissionPolicy, describeCommandScope, } from '@stratusagent/permissions';
+import { createFileCommandWhitelist, createPermissionPolicy, describeCommandScope, describeOriginScope, } from '@stratusagent/permissions';
 import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
 import { DEFAULT_CODEX_MODEL } from '@stratusagent/provider-codex';
-import { canonicalDestination, createForgetTool, createRecallTool, createRememberTool, defineAgent, describeCadence, describeSchedule, FORGET_TOOL_NAME, MEMORY_TOOL_NAME, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, installSkillsFromDirectory, loadOperatorSkills, loadRosterSouls, skillsDirPath, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, resolveConfiguredSoul, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, servedRuntimes, CREDENTIAL_PROVIDER_NAMES, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, newerStateMessage, pendingStateMigrations, readStateStamp, runStateMigrations, STATE_SCHEMA_VERSION, } from '@stratusagent/state';
+import { canonicalDestination, createForgetTool, createRecallTool, createRememberTool, defineAgent, describeCadence, describeSchedule, FORGET_TOOL_NAME, MEMORY_TOOL_NAME, formatSoul, generateAgentName, isLoadableSkillId, isValidAgentId, parseSoul, } from '@stratusagent/agents';
+import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileCredentialResolver, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, loadNamedCredentials, discoverSkillsInDirectory, installSkillsFromDirectory, loadOperatorSkills, loadRosterSouls, skillsDirPath, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, resolveConfiguredSoul, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, saveNamedCredentials, servedRuntimes, CREDENTIAL_PROVIDER_NAMES, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, newerStateMessage, pendingStateMigrations, readStateStamp, runStateMigrations, STATE_SCHEMA_VERSION, } from '@stratusagent/state';
 import { installService, readServiceCommand, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, uninstallService, } from "./service.js";
 export { installService, launchdPlist, readServiceCommand, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, systemdUnit, uninstallService, SERVICE_LABEL, } from "./service.js";
 import { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, readRecentRecords, tailLog, } from "./logs.js";
@@ -123,7 +124,16 @@ const defaultPackageInstaller = async (packages) => {
         });
     });
 };
-export const CLI_VERSION = '0.10.0';
+/**
+ * What a credential name may be: the two conventions in use, and nothing
+ * that would be awkward in a soul's `credentials:` list — `search.apiKey`
+ * and environment-style `SLACK_TOKEN`. Leading letter required, which also
+ * happens to exclude `__proto__`; the store does not *rely* on that (it
+ * keys prototype-free maps), because a credentials file can be written by
+ * something other than this command.
+ */
+export const CREDENTIAL_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+export const CLI_VERSION = '0.11.0';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 /**
  * The range every package declares in its `engines` field. Two floors, not
@@ -243,9 +253,14 @@ Usage:
   stratus agents --gateway http://127.0.0.1:4123
   stratus skill add stratuslabs/skill-code-review
   stratus skill add ./my-skills --skill code-review --agent ava
+  stratus skill validate ./my-skill
   stratus skills
+  stratus skill reload
+  stratus restart
   stratus schedules
   stratus schedules cancel <id>
+  printf %s "$BRAVE_KEY" | stratus credential set search.apiKey
+  stratus credentials
   stratus doctor
   stratus update
   stratus update --check
@@ -269,7 +284,9 @@ Commands:
   run              Execute one local Stratus Agent session
   serve            Run stratusd, the always-on gateway: durable sessions, the
                    whole roster live at once (each agent on its own provider),
-                   delegation, and a watchdog — Ctrl+C / SIGTERM drains cleanly
+                   delegation, and a watchdog — one per home (it refuses to
+                   start over a daemon already serving ~/.stratus), and
+                   Ctrl+C / SIGTERM drains cleanly
                    (--idle-timeout <seconds>, --approvals <headless|remote>,
                    --no-events, --no-log-file, --config <path>); everything it
                    says is also written to ~/.stratus/logs, which
@@ -291,9 +308,39 @@ Commands:
                    (skills.sh-style repos). Installed is not enabled: a soul
                    opts in via skills:, or pass --agent <id> to enable now.
                    --skill <id> picks from a multi-skill repo (repeatable),
-                   --force replaces an already-installed id
+                   --force replaces an already-installed id. A skill that
+                   does not conform to the Agent Skills spec is refused,
+                   naming what is wrong; one that installs with caveats
+                   (fields another host owns, a bundled scripts/) says so.
+                   A running daemon reloads its skills afterwards, no
+                   restart (--no-reload skips that)
+  skill validate   Check a skill directory, a directory of skills, or an
+                   installed skill id against the Agent Skills spec — the
+                   same check "skill add" runs, so what validates installs.
+                   Exit 1 if anything would be refused
   skills           List installed skills and which agents enable each
                    (also: stratus skill list)
+  skill reload     Ask the running daemon to re-read ~/.stratus/skills — for a
+                   skill edited or removed by hand. A skill that will not
+                   load refuses the whole reload and the previous set keeps
+                   serving; nothing becomes reachable to an agent whose soul
+                   does not list it
+  restart          Ask the running daemon for an announced restart — what a
+                   plugin change needs: it refuses new turns, lets in-flight
+                   ones finish for up to --drain-timeout <seconds> (default
+                   30), then comes back with sessions, schedules, and
+                   channels intact, under the service manager or not
+  credential set   Store a named credential an agent can resolve — a search
+                   backend asks for search.apiKey. The value is read from
+                   stdin, never from a flag, so it stays out of your shell
+                   history: printf %s "$KEY" | stratus credential set
+                   search.apiKey. --agent <id> stores one agent's own key,
+                   which outranks the shared entry for that agent. Storing
+                   grants nothing: the soul still needs credentials: [name]
+  credentials      List stored credential names and which agents have their
+                   own — names only, never values (also: credential list)
+  credential remove
+                   Forget one (--agent <id> for that agent's own entry)
   schedules        List every schedule the fleet has set — cadence, prompt,
                    pre-authorized destination, next firing — straight from the
                    daemon's database (--format json). "stratus schedules
@@ -345,9 +392,16 @@ Options:
   --port           dashboard: port for a daemon it starts (default: 4123)
   --host           dashboard: host for a daemon it starts (default: 127.0.0.1)
   --no-open        Do not open the browser automatically
-  --gateway        agents: read the roster from a running daemon's control API
+  --gateway        agents / skill reload / restart: a running daemon's control
+                   API (skill reload and restart default to the daemon
+                   ~/.stratus/gateway.json names)
   --token          Bearer token for --gateway (default: ~/.stratus/gateway-token)
+  --no-reload      skill add: install without reloading a running daemon
+  --reason         restart: why, for the daemon's log
+  --drain-timeout  restart: seconds the daemon lets in-flight turns finish
+                   before aborting them (default: 30)
   --no-api         serve: do not serve the control API
+  --api            serve: serve it even where the config says api.enabled: false
   --api-host       serve: control API interface (default: 127.0.0.1)
   --api-port       serve: control API port (default: 4123, 0 for any free port)
   --help, -h       Show this help message
@@ -401,6 +455,23 @@ const readPromptFromStdin = async (stdin) => {
     }
     return data.trim();
 };
+/**
+ * Stdin exactly as it arrived, for a value where whitespace may be part of
+ * it.
+ *
+ * `readPromptFromStdin` trims, which is right for a prompt and wrong for a
+ * secret: a key whose real value has a leading space would be stored as a
+ * *different* key, reported as stored, and then fail authentication with
+ * nothing to look at — this command never prints a value back.
+ */
+const readSecretFromStdin = async (stdin) => {
+    stdin.setEncoding('utf8');
+    let data = '';
+    for await (const chunk of stdin) {
+        data += chunk;
+    }
+    return data;
+};
 const readOptionValue = (tokens, index, flag) => {
     const value = tokens[index + 1];
     if (!value) {
@@ -497,6 +568,10 @@ export const parseCommand = (argv, env = {}) => {
                 parsed.api = false;
                 continue;
             }
+            if (token === '--api') {
+                parsed.api = true;
+                continue;
+            }
             if (token === '--api-port') {
                 const port = Number(readOptionValue(rest, index, '--api-port'));
                 if (!Number.isInteger(port) || port < 0 || port > 65_535) {
@@ -802,6 +877,63 @@ export const parseCommand = (argv, env = {}) => {
             ...(sessionId ? { sessionId } : {}),
         };
     }
+    if (command === 'credentials' || command === 'credential') {
+        const [subcommand, ...credentialRest] = command === 'credentials' ? ['list', ...rest] : rest;
+        if (subcommand === undefined || subcommand === '--help' || subcommand === '-h') {
+            return { command: 'help' };
+        }
+        if (subcommand !== 'set' && subcommand !== 'list' && subcommand !== 'remove') {
+            throw new Error(`No credential subcommand named ${JSON.stringify(subcommand)}. It is set, list, or remove.`);
+        }
+        let name;
+        let agentId;
+        for (let index = 0; index < credentialRest.length; index += 1) {
+            const token = credentialRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--agent') {
+                agentId = readOptionValue(credentialRest, index, '--agent');
+                index += 1;
+                continue;
+            }
+            if (token.startsWith('--')) {
+                throw new Error(`Unknown option: ${token}`);
+            }
+            if (name !== undefined) {
+                throw new Error(`credential ${subcommand} takes one credential name; got both ${JSON.stringify(name)} and ${JSON.stringify(token)}.`);
+            }
+            name = token;
+        }
+        if (subcommand !== 'list' && name === undefined) {
+            throw new Error(`credential ${subcommand} needs a credential name — for a search backend that is search.apiKey.`);
+        }
+        // A name keys a map that a soul's `credentials:` list also names, so the
+        // two spellings have to be able to meet. The store itself is
+        // prototype-safe whatever lands in it; this rule is what stops a typo —
+        // or a name no soul could ever write — from being stored and then
+        // reported missing forever.
+        if (name !== undefined && !CREDENTIAL_NAME_PATTERN.test(name)) {
+            throw new Error(`${JSON.stringify(name)} is not a credential name. Use letters, digits, dots, dashes, or underscores, `
+                + 'starting with a letter — search.apiKey, or an environment-style SLACK_TOKEN.');
+        }
+        // The agents package's own rule, not a second one: it is already the
+        // answer to "what may key a plain object", and it rejects the names —
+        // `__proto__`, `toString` — that would store a credential nothing could
+        // ever resolve.
+        if (agentId !== undefined && !isValidAgentId(agentId)) {
+            throw new Error(`${JSON.stringify(agentId)} cannot be an agent id, so a credential stored under it could never be resolved.`);
+        }
+        return {
+            command: 'credential',
+            action: subcommand,
+            ...(name !== undefined ? { name } : {}),
+            ...(agentId !== undefined ? { agentId } : {}),
+        };
+    }
     if (command === 'skills' || (command === 'skill' && rest[0] === 'list')) {
         const skillsRest = command === 'skills' ? rest : rest.slice(1);
         for (const token of skillsRest) {
@@ -817,13 +949,57 @@ export const parseCommand = (argv, env = {}) => {
         if (subcommand === '--help' || subcommand === '-h') {
             return { command: 'help' };
         }
+        if (subcommand === 'validate') {
+            let target;
+            for (const token of skillRest) {
+                if (token === '--help' || token === '-h') {
+                    return { command: 'help' };
+                }
+                if (token.startsWith('--')) {
+                    throw new Error(`Unknown option: ${token}`);
+                }
+                if (target !== undefined) {
+                    throw new Error(`skill validate takes one target; got both ${JSON.stringify(target)} and ${JSON.stringify(token)}.`);
+                }
+                target = token;
+            }
+            if (target === undefined) {
+                throw new Error('skill validate needs a target: a skill directory, a directory of skills, or an installed skill id.');
+            }
+            return { command: 'skill-validate', target };
+        }
+        if (subcommand === 'reload') {
+            const parsed = { command: 'skill-reload' };
+            for (let index = 0; index < skillRest.length; index += 1) {
+                const token = skillRest[index];
+                if (!token) {
+                    continue;
+                }
+                if (token === '--help' || token === '-h') {
+                    return { command: 'help' };
+                }
+                if (token === '--gateway') {
+                    parsed.gateway = readOptionValue(skillRest, index, '--gateway');
+                    index += 1;
+                    continue;
+                }
+                if (token === '--token') {
+                    parsed.token = readOptionValue(skillRest, index, '--token');
+                    index += 1;
+                    continue;
+                }
+                throw new Error(`Unknown option: ${token}`);
+            }
+            return parsed;
+        }
         if (subcommand !== 'add') {
-            throw new Error(`Unknown skill subcommand: ${subcommand ?? '(missing)'}. Try: stratus skill add <source>, stratus skills`);
+            throw new Error(`Unknown skill subcommand: ${subcommand ?? '(missing)'}. Try: stratus skill add <source>, stratus skill validate <path>, stratus skill reload, stratus skills`);
         }
         let source;
         const skillIds = [];
         let force = false;
         let agentId;
+        let reload = true;
         for (let index = 0; index < skillRest.length; index += 1) {
             const token = skillRest[index];
             if (!token) {
@@ -846,6 +1022,10 @@ export const parseCommand = (argv, env = {}) => {
                 force = true;
                 continue;
             }
+            if (token === '--no-reload') {
+                reload = false;
+                continue;
+            }
             if (token.startsWith('--')) {
                 throw new Error(`Unknown option: ${token}`);
             }
@@ -863,8 +1043,47 @@ export const parseCommand = (argv, env = {}) => {
             ...(skillIds.length > 0 ? { skillIds } : {}),
             ...(force ? { force } : {}),
             ...(agentId !== undefined ? { agentId } : {}),
+            ...(reload ? {} : { reload }),
         };
     }
+    if (command === 'restart') {
+        const parsed = { command: 'restart' };
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--reason') {
+                parsed.reason = readOptionValue(rest, index, '--reason');
+                index += 1;
+                continue;
+            }
+            if (token === '--drain-timeout') {
+                const seconds = Number(readOptionValue(rest, index, '--drain-timeout'));
+                if (!Number.isFinite(seconds) || seconds < 0) {
+                    throw new Error(`Invalid value for --drain-timeout: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                parsed.drainTimeoutMs = Math.round(seconds * 1000);
+                index += 1;
+                continue;
+            }
+            if (token === '--gateway') {
+                parsed.gateway = readOptionValue(rest, index, '--gateway');
+                index += 1;
+                continue;
+            }
+            if (token === '--token') {
+                parsed.token = readOptionValue(rest, index, '--token');
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return parsed;
+    }
     if (command === 'agent') {
         const [subcommand, ...agentRest] = rest;
         if (subcommand === '--help' || subcommand === '-h') {
@@ -1184,7 +1403,56 @@ export const warnOnCredentialOverride = async (runtime, streams, env = {}) => {
             + 'Unset it to use the subscription, or run `stratus doctor` to see everything that is being overridden.');
     }
 };
-const createApprovalPolicy = (mode, streams, env, ask) => {
+/**
+ * Where a call would act, for a tool that answers that — read through
+ * `originOf` so this and the daemon's engine compare the same thing.
+ */
+const approvalOrigin = (context) => {
+    const reported = context.tool.originFor?.(context.session);
+    return reported === undefined ? undefined : originOf(reported);
+};
+/**
+ * What a local prompt asks about: the tool, where it would act when that is
+ * a question at all, and the arguments.
+ *
+ * The origin is not in the arguments and cannot be — a `browser.act` call
+ * carries a CSS selector, and `#submit` is equally "load more results" and
+ * "confirm purchase". A prompt that showed only the selector would be
+ * asking someone to authorize an effect whose location it withheld, which
+ * is the same reason the daemon's prompt and the Slack request name it.
+ */
+export const describeApprovalCall = (context) => {
+    const origin = approvalOrigin(context);
+    return `${context.call.toolName}${origin ? ` on ${origin}` : ''}`
+        + ` with input ${JSON.stringify(context.call.input)}`;
+};
+/**
+ * Whether the conversation is still on the page the prompt named.
+ *
+ * A y/N at a terminal takes as long as it takes, and the page is live for
+ * all of it: a redirect between the question and the answer would have a
+ * yes given for one site click on another, with the prompt still showing
+ * the first. So the origin is read again and a page that moved refuses —
+ * the same check the daemon's engine makes after its own approval wait.
+ * This local policy needs its own because it is a separate policy sharing
+ * none of that code: `--approvals ask` judges the call, not a scope.
+ *
+ * Said out loud rather than failing quietly: somebody typed `y` and is owed
+ * an explanation for why nothing happened.
+ */
+const stillOnApprovedPage = (context, approved, streams) => {
+    if (context.tool.originFor === undefined) {
+        return true;
+    }
+    const now = approvalOrigin(context);
+    if (now === approved) {
+        return true;
+    }
+    writeLine(streams.stderr, `Not running ${context.call.toolName}: it was approved on ${approved ?? 'a page with no origin'}, `
+        + `and the conversation ${now === undefined ? 'no longer has that page open' : `is on ${now} now`}.`);
+    return false;
+};
+export const createApprovalPolicy = (mode, streams, env, ask) => {
     if (mode === 'always') {
         return new AllowAllApprovalPolicy();
     }
@@ -1199,25 +1467,27 @@ const createApprovalPolicy = (mode, streams, env, ask) => {
     // asker — two readers on one stream would race for the same bytes.
     if (ask) {
         return {
-            async approve({ call }) {
-                const answer = await ask(`Approve tool call ${call.toolName} with input ${JSON.stringify(call.input)}? [y/N] `);
-                return /^y(es)?$/i.test(answer.trim());
+            async approve(context) {
+                const approved = approvalOrigin(context);
+                const answer = await ask(`Approve tool call ${describeApprovalCall(context)}? [y/N] `);
+                return /^y(es)?$/i.test(answer.trim()) && stillOnApprovedPage(context, approved, streams);
             },
         };
     }
     return {
-        async approve({ call }) {
+        async approve(context) {
             const input = env.approvalInput ?? process.stdin;
             const readline = createInterface({ input, terminal: false });
+            const approved = approvalOrigin(context);
             // Prompt on stderr so stdout stays parseable (e.g. --format json).
-            streams.stderr.write(`Approve tool call ${call.toolName} with input ${JSON.stringify(call.input)}? [y/N] `);
+            streams.stderr.write(`Approve tool call ${describeApprovalCall(context)}? [y/N] `);
             try {
                 const answer = await new Promise((resolve) => {
                     readline.once('line', resolve);
                     readline.once('close', () => resolve(''));
                 });
                 writeLine(streams.stderr);
-                return /^y(es)?$/i.test(answer.trim());
+                return /^y(es)?$/i.test(answer.trim()) && stillOnApprovedPage(context, approved, streams);
             }
             finally {
                 readline.close();
@@ -1284,6 +1554,7 @@ const createAgentRuntime = async (streams, options) => {
             tools,
             skills,
             bus,
+            credentials: createFileCredentialResolver(runEnv),
             workspaceRoot: workspacesDirPath(runEnv),
         });
         loadedPlugins.push(...result.loaded);
@@ -3150,9 +3421,10 @@ export const runSetup = async (command, streams, env = {}) => {
         if (chosen.length > 0) {
             const packages = chosen.flatMap((group) => group.packages);
             writeLine(streams.stdout, `Running: npm install -g ${packages.join(' ')}`);
-            // Never fails setup, for the same reason the service install does not:
-            // the config and credentials are already written, and a package that
-            // did not install is a warning at the next start, not a broken machine.
+            // Never fails setup — not even its exit code, unlike the always-on
+            // service step below: the config and credentials are already written,
+            // and a package that did not install is a warning at the next start,
+            // not a broken machine.
             const result = await (env.packageInstaller ?? defaultPackageInstaller)(packages)
                 .catch((error) => ({
                 ok: false,
@@ -3181,20 +3453,24 @@ export const runSetup = async (command, streams, env = {}) => {
     };
     /**
      * Write everything the menu decided, then report whether the always-on
-     * install it performed succeeded.
+     * service step it performed — installing the service, or removing one the
+     * user chose not to run — succeeded.
      *
-     * A boolean rather than a throw: the install is the one optional part of
+     * A boolean rather than a throw: the service is the one optional part of
      * setup and everything else is already on disk by the time it runs, so
      * failing outright would lose the saved config to a service that can be
-     * installed later. The exit code carries it instead — the same answer
-     * `stratus service install` gives for the identical failure, which is what
-     * a script driving setup has to be able to see.
+     * installed (or removed) later. The exit code carries it instead — the
+     * same answer `stratus service install` and `stratus service uninstall`
+     * give for the identical failure, which is what a script driving setup
+     * has to be able to see.
      */
     const save = async () => {
-        // The always-on install is the only step here that can fail without
+        // The always-on service step is the only one here that can fail without
         // taking the rest of setup with it, so it is the only one the exit code
-        // has to carry.
-        let serviceInstallFailed = false;
+        // has to carry. Both signs count: a unit left in place after "do not run
+        // it for me" starts a daemon at login the user asked not to have, which
+        // is no more a successful setup than one that will not come up at all.
+        let serviceStepFailed = false;
         const config = { provider: state.provider };
         if (state.provider !== 'demo') {
             config.model = state.model ?? defaultModelFor(state.provider);
@@ -3287,6 +3563,9 @@ export const runSetup = async (command, streams, env = {}) => {
                 for (const message of removed.messages) {
                     writeLine(removed.ok ? streams.stdout : streams.stderr, message);
                 }
+                if (!removed.ok) {
+                    serviceStepFailed = true;
+                }
             }
         }
         else if (state.service.install && servicePlatform(serviceEnvFor(env))) {
@@ -3312,7 +3591,7 @@ export const runSetup = async (command, streams, env = {}) => {
             }
             if (!result.ok) {
                 writeLine(streams.stderr, `Setup is saved either way — start the daemon yourself with \`${serveCommand()}\`.`);
-                serviceInstallFailed = true;
+                serviceStepFailed = true;
             }
         }
         writeLine(streams.stdout);
@@ -3363,7 +3642,7 @@ export const runSetup = async (command, streams, env = {}) => {
         if (dashboardReady) {
             writeLine(streams.stdout, '  stratus dashboard');
         }
-        return !serviceInstallFailed;
+        return !serviceStepFailed;
     };
     try {
         if (!interactive) {
@@ -3407,11 +3686,12 @@ export const runSetup = async (command, streams, env = {}) => {
                 await testRun();
             }
         }
-        // Non-zero when the always-on install failed, matching `stratus service
-        // install`. Everything setup saved is still saved, and the output above
-        // says so — but a daemon that will not come up at login is not a
-        // successful setup, and a script that only reads the exit code had no
-        // way to tell.
+        // Non-zero when the always-on service step failed, matching `stratus
+        // service install` and `stratus service uninstall`. Everything setup
+        // saved is still saved, and the output above says so — but a daemon that
+        // will not come up at login, or one that will after the user said not to
+        // run it, is not a successful setup, and a script that only reads the
+        // exit code had no way to tell.
         return (await save()) ? 0 : 1;
     }
     finally {
@@ -4461,6 +4741,18 @@ export const runSkillAdd = async (command, streams, env = {}) => {
         });
         for (const skill of result.installed) {
             writeLine(streams.stdout, `installed ${skill.id} — ${skill.description}`);
+            // The spec's compatibility field is written for exactly this reader:
+            // the person deciding whether this environment can carry the skill.
+            if (skill.compatibility !== undefined) {
+                writeLine(streams.stdout, `  compatibility: ${skill.compatibility}`);
+            }
+        }
+        // What installed with a caveat — a field another host owns, the
+        // legacy key form, a bundled scripts/ — is said next to the install,
+        // per skill: the operator deciding to enable it is the one who needs
+        // to hear it, and this is the moment they are looking.
+        for (const warning of result.warnings) {
+            writeLine(streams.stderr, `Warning: ${warning.id}: ${warning.message}`);
         }
         // Present already is a no-op, not a failure — and exactly what the
         // "rerun with --agent" hint below produces, so these stay eligible
@@ -4477,6 +4769,13 @@ export const runSkillAdd = async (command, streams, env = {}) => {
                 : `Error: no skills found in ${command.source}. A skill is a directory with a SKILL.md.`);
             return 1;
         }
+        // The ordinary path needs no second step: a daemon that is running
+        // serves what was just installed from its next turn. Only when
+        // something changed on disk — a re-run that installed nothing has
+        // nothing to reload — and only where a daemon has said it is running.
+        if (result.installed.length > 0 && command.reload !== false) {
+            await reloadRunningDaemonSkills(streams, env);
+        }
         // Installed is not enabled: a soul opts in through its skills:
         // allowlist, and that stays true when the install came through a
         // command. --agent is the explicit way to say both at once.
@@ -4564,6 +4863,279 @@ export const runSchedules = async (command, streams, env = {}) => {
         store.close();
     }
 };
+/**
+ * `stratus credential set|list|remove`: the place a named credential goes.
+ *
+ * A credential nobody can add is a credential nobody has, which is why this
+ * exists at all — a search backend asks for `search.apiKey` and until now
+ * there was nowhere to put one. Three rules it keeps, all of them
+ * deliberate:
+ *
+ * The value is read from **stdin, never from a flag**. A secret in argv is
+ * a secret in shell history and in every `ps` on the machine.
+ *
+ * Nothing here ever prints a value back. `list` reports names and which
+ * agents have their own, the same posture the control API's credential read
+ * already keeps.
+ *
+ * And storing one grants no agent anything: the agent's soul still has to
+ * list the name under `credentials:`, which is the per-identity gate.
+ */
+export const runCredential = async (command, streams, env = {}) => {
+    const named = await loadNamedCredentials(env);
+    if (command.action === 'list') {
+        const shared = Object.keys(named.shared).sort();
+        const agents = Object.entries(named.agents).sort(([a], [b]) => a.localeCompare(b));
+        if (shared.length === 0 && agents.length === 0) {
+            writeLine(streams.stdout, `No named credentials stored in ${credentialsPath(env)}.`);
+            writeLine(streams.stdout, 'A search backend wants `stratus credential set search.apiKey`.');
+            return 0;
+        }
+        if (shared.length > 0) {
+            writeLine(streams.stdout, 'Shared with the whole fleet:');
+            for (const name of shared) {
+                writeLine(streams.stdout, `  ${name}`);
+            }
+        }
+        for (const [agentId, entries] of agents) {
+            writeLine(streams.stdout, `Only ${agentId}:`);
+            for (const name of Object.keys(entries).sort()) {
+                writeLine(streams.stdout, `  ${name}`);
+            }
+        }
+        // Names, never values — and say so, so nobody goes looking for a flag
+        // that prints one.
+        writeLine(streams.stdout, '');
+        writeLine(streams.stdout, `Values are never printed. They live in ${credentialsPath(env)}, readable only by you.`);
+        return 0;
+    }
+    const name = command.name ?? '';
+    if (command.action === 'remove') {
+        const scope = command.agentId;
+        const store = scope === undefined ? named.shared : named.agents[scope];
+        if (!store || store[name] === undefined) {
+            writeLine(streams.stderr, scope === undefined
+                ? `No shared credential named ${name}. \`stratus credentials\` lists what is stored.`
+                : `Agent ${scope} has no credential of its own named ${name}. \`stratus credentials\` lists what is stored.`);
+            return 1;
+        }
+        delete store[name];
+        if (scope !== undefined && Object.keys(store).length === 0) {
+            delete named.agents[scope];
+        }
+        await saveNamedCredentials(env, named);
+        writeLine(streams.stdout, scope === undefined ? `Removed ${name}.` : `Removed ${name} for ${scope}.`);
+        return 0;
+    }
+    writeLine(streams.stderr, `Reading the value for ${name} from stdin — it is never taken from the command line, where it would land in your shell history. Ctrl-D when done.`);
+    const arrived = env.stdin ?? await readSecretFromStdin(env.stdinStream ?? process.stdin);
+    // One trailing line terminator and nothing else. `echo "$KEY" |` appends a
+    // newline that is not part of the key and `printf %s` appends nothing, so
+    // both spellings have to work — while a key whose own value ends in a
+    // space must survive either of them, which a blanket trim would not allow.
+    const value = arrived.replace(/\r?\n$/, '');
+    if (value.trim().length === 0) {
+        writeLine(streams.stderr, `Nothing arrived on stdin, so ${name} was not stored. Pipe the value in: \`printf %s "$KEY" | stratus credential set ${name}\`.`);
+        return 1;
+    }
+    if (command.agentId === undefined) {
+        named.shared[name] = value;
+    }
+    else {
+        named.agents[command.agentId] = { ...(named.agents[command.agentId] ?? {}), [name]: value };
+    }
+    await saveNamedCredentials(env, named);
+    writeLine(streams.stdout, command.agentId === undefined
+        ? `Stored ${name} in ${credentialsPath(env)} (readable only by you).`
+        : `Stored ${name} for ${command.agentId} in ${credentialsPath(env)} (readable only by you). It outranks the shared entry for that agent.`);
+    // Storing grants nothing: the soul is the second gate, and an operator
+    // who stops here gets "not allowed to access credential" on every call.
+    writeLine(streams.stdout, `Each agent that may use it still needs \`credentials: [${name}]\` in its soul.`);
+    return 0;
+};
+/**
+ * `stratus skill validate <target>`: the install-time check, run without
+ * installing — for an author about to publish a skill, or an operator
+ * asking why one was refused. A local path is a skill directory or a
+ * directory of skills, discovered exactly as `skill add` would; a bare id
+ * names an installed skill under `~/.stratus/skills/`. Exit 1 when
+ * anything would be refused, so a publish step can gate on it.
+ */
+export const runSkillValidate = async (command, streams, env = {}) => {
+    let directory;
+    let installed = false;
+    const localPath = path.resolve(readWorkingDirectory(env), command.target);
+    try {
+        if ((await stat(localPath)).isDirectory()) {
+            directory = localPath;
+        }
+    }
+    catch {
+        // Not a local directory; try it as an installed id.
+    }
+    // The loader's rule for the lookup, so a directory that loads with a
+    // pre-spec id can be validated — and told what to rename.
+    if (directory === undefined && isLoadableSkillId(command.target)) {
+        const installedPath = path.join(skillsDirPath(env), command.target);
+        try {
+            if ((await stat(installedPath)).isDirectory()) {
+                directory = installedPath;
+                installed = true;
+            }
+        }
+        catch {
+            // Not installed either.
+        }
+    }
+    if (directory === undefined) {
+        writeLine(streams.stderr, `Error: ${JSON.stringify(command.target)} is neither a directory nor an installed skill id (stratus skills lists those).`);
+        return 1;
+    }
+    // An installed directory IS the layout the spec's directory rule is
+    // about, so its name is checked; a path the author typed is a checkout
+    // or a container, judged as `skill add` would judge it.
+    const { candidates, skipped } = await discoverSkillsInDirectory(directory, installed ? { checkRootDirectoryName: true } : {});
+    if (candidates.length === 0 && skipped.length === 0) {
+        writeLine(streams.stderr, `Error: no skills found in ${directory}. A skill is a directory with a SKILL.md.`);
+        return 1;
+    }
+    for (const candidate of candidates) {
+        const caveat = candidate.warnings.length > 0
+            ? ` — ${candidate.warnings.length} warning${candidate.warnings.length === 1 ? '' : 's'}`
+            : '';
+        writeLine(streams.stdout, `${candidate.id}: ok${caveat}`);
+        for (const warning of candidate.warnings) {
+            writeLine(streams.stdout, `  warning: ${warning}`);
+        }
+    }
+    for (const skip of skipped) {
+        writeLine(streams.stdout, `${skip.id}: refused`);
+        writeLine(streams.stdout, `  error: ${skip.reason}`);
+    }
+    if (skipped.length > 0) {
+        const noun = skipped.length === 1 ? 'skill' : 'skills';
+        writeLine(streams.stderr, `Error: ${skipped.length} ${noun} would be refused at install.`);
+        return 1;
+    }
+    return 0;
+};
+/**
+ * The control API base a command should talk to: `--gateway` when given,
+ * else whatever daemon `~/.stratus/gateway.json` says is serving, else
+ * nothing — the file is written when the API binds and removed when it
+ * stops, so its absence means no daemon has said where it is.
+ */
+const runningGatewayBase = async (env, target) => {
+    if (target.gateway) {
+        return target.gateway.replace(/\/+$/, '');
+    }
+    const info = await readGatewayInfo(env);
+    return info?.url.replace(/\/+$/, '');
+};
+/** One authenticated call to a daemon's control API, with the network and auth failures said plainly. */
+const callRunningGateway = async (env, target, base, pathname, body) => {
+    const token = await gatewayToken(env, target.token);
+    const fetchImpl = env.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('fetch is unavailable, so this runtime cannot reach a daemon.');
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${base}${pathname}`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${token}`,
+                ...(body ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach the gateway at ${base} (${error instanceof Error ? error.message : String(error)}). `
+            + 'Is stratusd running, and does it have @stratusagent/control-api installed?');
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(`The gateway at ${base} rejected this token. Check --token, STRATUS_GATEWAY_TOKEN, or ~/.stratus/gateway-token.`);
+    }
+    return response;
+};
+/** The API's own sentence for a failure, or the status when it sent none. */
+const gatewayErrorMessage = async (response) => {
+    try {
+        const payload = await response.json();
+        if (payload.error?.message) {
+            return payload.error.message;
+        }
+    }
+    catch {
+        // Not JSON; the status is all there is to say.
+    }
+    return `HTTP ${response.status}`;
+};
+const noRunningDaemonMessage = (env) => `no running daemon found — ${gatewayInfoPath(env)} does not exist, and no --gateway was given. `
+    + 'Start one with `stratus serve` or `stratus service start`; a daemon loads ~/.stratus/skills at start.';
+/**
+ * After `skill add`: tell the daemon, if one says it is running. Silent
+ * when none does — a `stratus run` user with no daemon should not read a
+ * note about one — and a warning, never a failure, when the file names a
+ * daemon that did not answer: the install itself succeeded.
+ */
+const reloadRunningDaemonSkills = async (streams, env) => {
+    const info = await readGatewayInfo(env);
+    if (!info) {
+        return;
+    }
+    const base = info.url.replace(/\/+$/, '');
+    try {
+        const response = await callRunningGateway(env, {}, base, '/api/v1/skills/reload');
+        if (!response.ok) {
+            throw new Error(await gatewayErrorMessage(response));
+        }
+        writeLine(streams.stdout, `reloaded the running daemon's skills (${base}) — no restart needed`);
+    }
+    catch (error) {
+        writeLine(streams.stderr, `Warning: ${gatewayInfoPath(env)} names a daemon at ${base}, but its skills were not reloaded: `
+            + `${error instanceof Error ? error.message : String(error)} If it is running, reload it with: stratus skill reload`);
+    }
+};
+export const runSkillReload = async (command, streams, env = {}) => {
+    const base = await runningGatewayBase(env, command);
+    if (!base) {
+        writeLine(streams.stderr, `Error: ${noRunningDaemonMessage(env)}`);
+        return 1;
+    }
+    const response = await callRunningGateway(env, command, base, '/api/v1/skills/reload');
+    if (!response.ok) {
+        writeLine(streams.stderr, `Error: ${await gatewayErrorMessage(response)}`);
+        return 1;
+    }
+    const { skills } = await response.json();
+    const ids = (skills ?? []).map((skill) => skill.id);
+    writeLine(streams.stdout, `reloaded skills in the daemon at ${base} — ${ids.length} skill(s) serving${ids.length > 0 ? `: ${ids.join(', ')}` : ''}`);
+    return 0;
+};
+export const runRestart = async (command, streams, env = {}) => {
+    const base = await runningGatewayBase(env, command);
+    if (!base) {
+        writeLine(streams.stderr, `Error: ${noRunningDaemonMessage(env)}`);
+        return 1;
+    }
+    const response = await callRunningGateway(env, command, base, '/api/v1/restart', {
+        reason: command.reason ?? 'stratus restart',
+        ...(command.drainTimeoutMs !== undefined ? { drainTimeoutMs: command.drainTimeoutMs } : {}),
+    });
+    if (!response.ok) {
+        writeLine(streams.stderr, `Error: ${await gatewayErrorMessage(response)}`);
+        return 1;
+    }
+    const status = await response.json();
+    const inflight = status.inflight ?? 0;
+    const window = Math.round((status.drainTimeoutMs ?? 0) / 1000);
+    writeLine(streams.stdout, `restart announced to the daemon at ${base} — new turns are refused; ${inflight} turn(s) in flight `
+        + `get up to ${window}s to finish, then it comes back.`);
+    writeLine(streams.stdout, 'Watch it come back: stratus logs -f');
+    return 0;
+};
 export const runSkills = async (streams, env = {}) => {
     const registry = new SkillRegistry();
     const skills = await loadOperatorSkills(env, registry, (line) => {
@@ -4808,6 +5380,85 @@ const gatewayAnswering = async (env, base, fetchImpl) => {
         return false;
     }
 };
+/**
+ * Whether a process with this pid exists. EPERM is an answer — the process
+ * is there, it is just not ours to signal.
+ */
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+};
+/**
+ * The error for a home another daemon holds (see `claimHome` in
+ * @stratusagent/gateway — the claim is what decides; this only says who).
+ *
+ * The discovery file names the holder when it has one to name: a daemon
+ * that has bound its API. Read for the message alone, and only trusted as
+ * far as a live pid — a daemon still starting has not written it, a
+ * daemon draining its last turn has already removed it, and a SIGKILLed
+ * one leaves it behind for the next pid to inherit. Not probed over HTTP:
+ * a `STRATUS_GATEWAY_TOKEN` exported for some remote gateway would answer
+ * 401 for the local one, and the claim needs no second opinion.
+ */
+/**
+ * `stratus serve` refused because another daemon holds the home. Its own
+ * type so `stratus dashboard` can tell "a daemon is there, wait for it to
+ * publish" from "the daemon could not start".
+ */
+class HomeHeldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HomeHeldError';
+    }
+}
+/**
+ * Whether a daemon from before the lock existed is serving this home.
+ *
+ * Such a daemon — alive across an upgrade that did not stop it — never
+ * took the claim, so the claim alone cannot see it. The discovery file it
+ * published is its only trace, held to the two proofs the lock made
+ * unnecessary for everything since: the pid it names is alive, and its
+ * URL answers `/health` with this home's own token file — never the
+ * `STRATUS_GATEWAY_TOKEN` override, which names some other gateway and
+ * would make a live daemon read as absent. A stale file fails either
+ * proof and refuses nothing.
+ */
+const legacyDaemonServing = async (env) => {
+    const info = await readGatewayInfo(env);
+    if (info?.pid === undefined || info.pid === process.pid || !processAlive(info.pid)) {
+        return false;
+    }
+    const fetchImpl = env.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        return false;
+    }
+    try {
+        const token = (await readFile(gatewayTokenPath(env), 'utf8')).trim();
+        const response = await fetchImpl(`${info.url}/api/v1/health`, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(2_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+const describeHeldHome = async (env) => {
+    const info = await readGatewayInfo(env);
+    const holder = info?.pid !== undefined && processAlive(info.pid)
+        ? ` (pid ${info.pid}, ${info.url})`
+        : ' — one that is still starting, or still draining its last turns';
+    return `stratusd is already running for this home${holder}. Two daemons on one ~/.stratus `
+        + 'would each fire the other\'s schedules and re-ask its approvals. Stop it first: `stratus service stop` '
+        + 'if it is the installed service, otherwise Ctrl+C where it runs — and let it finish; it holds the home until '
+        + 'its last turn is written.';
+};
 /**
  * `stratus dashboard` — open the web UI against a running daemon, starting
  * one in the foreground when there is none.
@@ -4830,56 +5481,87 @@ export const runDashboard = async (command, streams, env = {}) => {
     if (!base) {
         writeLine(streams.stdout, 'No daemon is running — starting one. It stops when you do.');
         writeLine(streams.stdout, 'Run `stratus service install` to keep one running instead.');
-        serving = runServe({
-            command: 'serve',
-            events: false,
-            // Explicitly on. A trusted config may set `api.enabled: false` — a
-            // reasonable thing for a headless box — but this command exists to
-            // open the dashboard, and honouring it here would start a daemon
-            // with no API and then time out waiting for the one it promised.
-            api: true,
-            ...(command.port !== undefined ? { apiPort: command.port } : {}),
-            // Passed whenever it was asked for, including when it is the default.
-            // `--host 127.0.0.1` against a config saying `0.0.0.0` is an operator
-            // narrowing the bind, and dropping it because it matched the default
-            // did the reverse of what they typed.
-            ...(command.host !== undefined ? { apiHost: command.host } : {}),
-        }, 
-        // The daemon's own chatter belongs on stderr here: stdout is where this
-        // command says where to point a browser, and interleaving the two makes
-        // the one line that matters hard to find.
-        { stdout: streams.stderr, stderr: streams.stderr }, { ...env, shutdownSignal: ownDaemon.signal });
-        // Attached now, not at the end. `runServe` can reject before it publishes
-        // anything — an unreadable roster, a session store that will not open —
-        // and a rejected promise nobody is watching for fifteen seconds is an
-        // unhandled rejection, which terminates the process instead of reaching
-        // the message below. Captured rather than swallowed, so the reason the
-        // daemon gave is the reason this command reports.
+        // One attempt at a daemon of our own. `runServe` can reject before it
+        // publishes anything — an unreadable roster, a session store that will
+        // not open — and a rejected promise nobody is watching for fifteen
+        // seconds is an unhandled rejection, which terminates the process
+        // instead of reaching the message below. Captured rather than
+        // swallowed, so the reason the daemon gave is the reason this command
+        // reports.
         let daemonFailure;
-        const daemonExit = serving.then(() => undefined, (error) => { daemonFailure = error; });
-        // Gated on the daemon actually answering, not on a delay: it publishes
+        let daemonSettled = false;
+        let daemonExit = Promise.resolve();
+        let attemptedAt = 0;
+        const attempt = () => {
+            daemonFailure = undefined;
+            daemonSettled = false;
+            attemptedAt = Date.now();
+            serving = runServe({
+                command: 'serve',
+                events: false,
+                // Explicitly on. A trusted config may set `api.enabled: false` —
+                // a reasonable thing for a headless box — but this command exists
+                // to open the dashboard, and honouring it here would start a
+                // daemon with no API and then time out waiting for the one it
+                // promised.
+                api: true,
+                ...(command.port !== undefined ? { apiPort: command.port } : {}),
+                // Passed whenever it was asked for, including when it is the
+                // default. `--host 127.0.0.1` against a config saying `0.0.0.0`
+                // is an operator narrowing the bind, and dropping it because it
+                // matched the default did the reverse of what they typed.
+                ...(command.host !== undefined ? { apiHost: command.host } : {}),
+            }, 
+            // The daemon's own chatter belongs on stderr here: stdout is where
+            // this command says where to point a browser, and interleaving the
+            // two makes the one line that matters hard to find.
+            { stdout: streams.stderr, stderr: streams.stderr }, { ...env, shutdownSignal: ownDaemon.signal });
+            daemonExit = serving.then(() => { daemonSettled = true; }, (error) => { daemonFailure = error; daemonSettled = true; });
+        };
+        attempt();
+        // Gated on a daemon actually answering, not on a delay: one publishes
         // where it bound the moment it binds, and anything less would be a race
-        // dressed up as a timeout. It also stops the moment the daemon gives up,
-        // rather than waiting out a timeout for a process that is already gone.
+        // dressed up as a timeout. It also stops the moment our daemon gives up
+        // — except when it gave up because another one holds the home. An
+        // installed service still starting has not published its address yet
+        // and is about to: that is the daemon to wait for. And a daemon still
+        // draining may simply exit, with nothing replacing it — so while the
+        // home is held, our own attempt is repeated about once a second, and
+        // takes the home the moment it is free.
         const startedBy = Date.now() + 15_000;
-        let daemonStopped = false;
-        void daemonExit.then(() => { daemonStopped = true; });
-        while (!base && !daemonStopped && Date.now() < startedBy) {
+        while (!base && Date.now() < startedBy) {
             const info = await readGatewayInfo(env);
             if (info && await gatewayAnswering(env, info.url, fetchImpl)) {
                 base = info.url;
                 break;
             }
+            if (daemonSettled) {
+                if (!(daemonFailure instanceof HomeHeldError)) {
+                    break;
+                }
+                if (Date.now() - attemptedAt >= 1_000) {
+                    attempt();
+                }
+            }
             await new Promise((resolve) => setTimeout(resolve, 150));
         }
         if (!base) {
             ownDaemon.abort();
             await daemonExit;
-            writeLine(streams.stderr, daemonFailure
-                ? `Error: the daemon could not start: ${daemonFailure instanceof Error ? daemonFailure.message : String(daemonFailure)}`
-                : 'Error: the daemon did not start serving its control API. Is @stratusagent/control-api installed?');
+            writeLine(streams.stderr, daemonFailure instanceof HomeHeldError
+                ? 'Error: another daemon holds this home but never published its address. It may still be starting or '
+                    + 'draining — try again in a moment, or check `stratus service status`.'
+                : daemonFailure
+                    ? `Error: the daemon could not start: ${daemonFailure instanceof Error ? daemonFailure.message : String(daemonFailure)}`
+                    : 'Error: the daemon did not start serving its control API. Is @stratusagent/control-api installed?');
             return 1;
         }
+        if (daemonFailure instanceof HomeHeldError) {
+            // The daemon that answered is the one that held the home. Ours never
+            // started, so there is nothing of ours to wait for or to stop: from
+            // here this is the found-a-running-daemon case.
+            serving = undefined;
+        }
     }
     let url;
     try {
@@ -4915,7 +5597,15 @@ export const runDashboard = async (command, streams, env = {}) => {
         await new Promise((resolve) => setTimeout(resolve, env.dashboardAutoShutdownMs));
         ownDaemon.abort();
     }
-    return serving;
+    // An attempt still in flight when the daemon answered may yet be refused
+    // — the holder published while ours was claiming. The dashboard found a
+    // daemon; that refusal is not its failure.
+    return serving.catch((error) => {
+        if (error instanceof HomeHeldError) {
+            return 0;
+        }
+        throw error;
+    });
 };
 /**
  * Resolution and loading are separate questions, and only the first one
@@ -5018,6 +5708,214 @@ const loadServePlugins = async (env, configPath, warn) => {
  * roster, accept dispatches, print events, and drain cleanly on SIGTERM,
  * SIGINT, or the injected shutdown signal.
  */
+/**
+ * What a daemon exits with to ask for a fresh process. Only ever seen by the
+ * supervisor below, which is the only thing that starts a daemon with the
+ * environment marker that makes it exit this way instead of supervising.
+ */
+export const RESTART_EXIT_CODE = 75;
+/**
+ * What a daemon exits with when a restart could not drain — a turn that
+ * ignored its abort, a plugin or channel that did not let go. Distinct from
+ * the restart status on purpose: the supervisor answers this one by
+ * exiting with it too, so the process the service manager started ends
+ * and the manager restarts the whole unit — under systemd, cleaning the
+ * cgroup of whatever the plugin left running. A supervisor that started
+ * another daemon instead would keep that cgroup, and its leaks, alive.
+ */
+export const UNDRAINED_RESTART_EXIT_CODE = 76;
+/** Set in a daemon the supervisor started, so its own restart is an exit, not a second supervisor. */
+const SUPERVISED_ENV = 'STRATUS_SERVE_SUPERVISED';
+/**
+ * The control API port the last daemon bound, handed to its replacement by
+ * the supervisor. Honoured only where the replacement's own request — the
+ * flag, else the config it reads afresh — is still for any free port: a
+ * daemon that asked for port 0 comes back on the port it had, so a
+ * dashboard page reconnects to it, while a config since edited to a fixed
+ * port takes effect on that restart, as an `api` block change is meant to.
+ * A hint, never a pin: passing the port back as `--api-port` would outrank
+ * the config for every restart after.
+ */
+const BOUND_API_PORT_ENV = 'STRATUS_SERVE_BOUND_API_PORT';
+const isDashboardSession = (value) => typeof value === 'object' && value !== null
+    && typeof value.id === 'string'
+    && typeof value.expiresAt === 'number'
+    && typeof value.vouchedBy === 'string';
+/** Shape-checked, because the other end of an IPC channel is still another process. */
+const isSupervisorMessage = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const message = value;
+    if (message.type === 'stratusd.bound-api-port') {
+        return typeof message.port === 'number' && Number.isInteger(message.port) && message.port > 0;
+    }
+    if (message.type === 'stratusd.sessions') {
+        return Array.isArray(message.sessions) && message.sessions.every(isDashboardSession);
+    }
+    return false;
+};
+/**
+ * The IPC channel a supervisor opens when it spawns a daemon: what a
+ * supervised daemon says up it (the port it bound, so the supervisor
+ * carries *that* port to the next daemon rather than the first one's; the
+ * dashboard sessions it hands on) and what comes down it. Where there is
+ * no channel — the first daemon, or one a service manager started — there
+ * is no one to say it to, and nothing is said.
+ */
+const defaultSupervisorLink = {
+    send(message) {
+        if (typeof process.send === 'function' && process.channel) {
+            process.send(message);
+        }
+    },
+    receive(handler) {
+        const channel = process.channel;
+        if (!channel) {
+            return;
+        }
+        process.on('message', (message) => {
+            if (isSupervisorMessage(message)) {
+                handler(message);
+            }
+        });
+        // A 'message' listener refs the channel, which would keep this process
+        // alive after its drain; the daemon's own work is what holds it open.
+        channel.unref?.();
+    },
+};
+/**
+ * The parsed serve command as arguments again — what the fresh daemon is
+ * started with. From the command, not from `process.argv`: `stratus
+ * dashboard` runs the daemon through `runServe` with a command it built,
+ * and the process's own arguments would start a second dashboard.
+ */
+export const serveArgv = (command) => [
+    'serve',
+    ...(command.configPath !== undefined ? ['--config', command.configPath] : []),
+    ...(command.idleTimeoutMs !== undefined ? ['--idle-timeout', String(command.idleTimeoutMs / 1000)] : []),
+    ...(command.approvals !== undefined ? ['--approvals', command.approvals] : []),
+    ...(command.events ? [] : ['--no-events']),
+    ...(command.logToFile === false ? ['--no-log-file'] : []),
+    ...(command.api === false ? ['--no-api'] : command.api === true ? ['--api'] : []),
+    ...(command.apiPort !== undefined ? ['--api-port', String(command.apiPort)] : []),
+    ...(command.apiHost !== undefined ? ['--api-host', command.apiHost] : []),
+];
+/**
+ * The `bin` beside the module at `moduleUrl`, with that module's own
+ * extension: `dist/index.js` respawns `dist/bin.js`, and a source checkout
+ * running `src/index.ts` under type stripping respawns `src/bin.ts` — the
+ * flags that made that possible travel in `process.execArgv`. Assuming
+ * compiled output would hand a source checkout a file that does not exist,
+ * and a daemon that never comes back.
+ */
+export const restartEntrypoint = (moduleUrl) => {
+    const modulePath = fileURLToPath(moduleUrl);
+    return path.join(path.dirname(modulePath), `bin${path.extname(modulePath)}`);
+};
+/**
+ * Run this CLI's own entrypoint as a child with the daemon's streams and
+ * exit code, forwarding the signals a supervisor would otherwise swallow.
+ *
+ * A child, and the parent waits, rather than a detached process and an
+ * exit: under systemd and launchd the process the manager started is the
+ * service, and its exit ends the job — cgroup and all, on Linux — so the
+ * daemon that received the restart has to stay the manager's process and
+ * become the supervisor of the next one. That is what makes the same path
+ * hold in the foreground and under `--no-login`, where nothing else would
+ * bring a clean exit back.
+ */
+const defaultServeRespawn = (env) => (argv, handoff) => new Promise((resolve, reject) => {
+    const entrypoint = restartEntrypoint(import.meta.url);
+    // The daemon's own streams, plus an IPC channel for what it and its
+    // supervisor have to tell each other. See SupervisorLink.
+    const child = spawn(process.execPath, [...process.execArgv, entrypoint, ...argv], {
+        stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+        env: {
+            ...process.env,
+            [SUPERVISED_ENV]: '1',
+            ...(handoff.boundApiPort !== undefined ? { [BOUND_API_PORT_ENV]: String(handoff.boundApiPort) } : {}),
+        },
+    });
+    if (handoff.sessions.length > 0 && child.connected) {
+        // Queued in the channel until the daemon listens, which it does
+        // before its API is up; the API holds them until it can adopt them.
+        // A send that fails (the daemon died before reading) is not this
+        // supervisor's failure: the exit below reports what happened, and a
+        // daemon that never took them simply comes up signed out.
+        const sessions = { type: 'stratusd.sessions', sessions: handoff.sessions };
+        child.send(sessions, () => undefined);
+    }
+    const forward = (signal) => () => {
+        child.kill(signal);
+    };
+    const onTerm = forward('SIGTERM');
+    const onInt = forward('SIGINT');
+    const onAbort = () => {
+        child.kill('SIGTERM');
+    };
+    process.on('SIGTERM', onTerm);
+    process.on('SIGINT', onInt);
+    env.shutdownSignal?.addEventListener('abort', onAbort, { once: true });
+    const done = () => {
+        process.off('SIGTERM', onTerm);
+        process.off('SIGINT', onInt);
+        env.shutdownSignal?.removeEventListener('abort', onAbort);
+    };
+    let reportedPort;
+    let handedBack;
+    child.on('message', (message) => {
+        if (!isSupervisorMessage(message)) {
+            return;
+        }
+        if (message.type === 'stratusd.bound-api-port') {
+            reportedPort = message.port;
+        }
+        else {
+            handedBack = message.sessions;
+        }
+    });
+    child.once('error', (error) => {
+        done();
+        reject(error);
+    });
+    child.once('exit', (code, signal) => {
+        done();
+        // Killed by a signal is a stop, not a request to come back.
+        resolve({
+            code: code ?? (signal ? 1 : 0),
+            ...(reportedPort !== undefined ? { boundApiPort: reportedPort } : {}),
+            ...(handedBack !== undefined ? { sessions: handedBack } : {}),
+        });
+    });
+});
+/**
+ * Keep starting daemons for as long as they exit asking for another; the
+ * first exit that does not is this process's own — an undrained restart's
+ * status included, which ends the supervisor rather than starting a daemon
+ * beside what the last one could not release.
+ */
+const superviseRestarts = async (command, first, streams, env) => {
+    const respawn = env.serveRespawn ?? defaultServeRespawn(env);
+    // The hand-off follows the daemons: the port each one said it bound is
+    // what the next one is told (so a config edited to a fixed port and
+    // back hands on the last address, not the first), and the sessions are
+    // whatever the last one handed back — a daemon that handed nothing
+    // hands nothing on.
+    let handoff = first;
+    let result;
+    do {
+        writeLine(streams.stdout, 'Restarting stratusd.');
+        result = await respawn(serveArgv(command), handoff);
+        handoff = {
+            ...(result.boundApiPort !== undefined || handoff.boundApiPort !== undefined
+                ? { boundApiPort: result.boundApiPort ?? handoff.boundApiPort }
+                : {}),
+            sessions: result.sessions ?? [],
+        };
+    } while (result.code === RESTART_EXIT_CODE);
+    return result.code;
+};
 export const runServe = async (command, streams, env = {}) => {
     // First, before anything that can throw. A broken install makes the
     // gateway import below fail, the manager restarts, and the CLI's error
@@ -5030,7 +5928,46 @@ export const runServe = async (command, streams, env = {}) => {
     // Loaded lazily: the gateway pulls in node:sqlite, which every other CLI
     // command neither needs nor should pay for (Node still prints an
     // experimental warning for it).
-    const { createGateway } = await import('@stratusagent/gateway');
+    const { createGateway, claimHome, HomeClaimedError } = await import('@stratusagent/gateway');
+    // Before anything of this daemon's is written or opened: a second daemon
+    // on this home is refused here, with no log line, no store, and no sweep
+    // or firing of its own.
+    let claim;
+    try {
+        claim = claimHome(env);
+    }
+    catch (error) {
+        if (error instanceof HomeClaimedError) {
+            throw new HomeHeldError(await describeHeldHome(env));
+        }
+        throw error;
+    }
+    let outcome;
+    try {
+        // The one daemon the claim cannot see: one that predates it.
+        if (await legacyDaemonServing(env)) {
+            throw new HomeHeldError(await describeHeldHome(env));
+        }
+        outcome = await serveHeldHome(command, streams, env, createGateway);
+    }
+    finally {
+        // After everything: the store closed by stop(), or whatever a throw
+        // reached — a preflight that rejected before the gateway existed
+        // included, so a host that calls runServe again is not refused for a
+        // daemon that never started. And never sooner, so a replacement cannot
+        // open the store while this one still writes.
+        claim.release();
+    }
+    // An announced restart, once the home is let go — the replacement claims
+    // it next. A daemon the supervisor started asks it for the next one by
+    // exiting; the first daemon becomes the supervisor itself. Either way the
+    // process the service manager (or the terminal) started is what stays.
+    if (outcome.code === RESTART_EXIT_CODE && !readProcessEnv(env)[SUPERVISED_ENV]) {
+        return superviseRestarts(command, { ...(outcome.boundApiPort !== undefined ? { boundApiPort: outcome.boundApiPort } : {}), sessions: outcome.sessions }, streams, env);
+    }
+    return outcome.code;
+};
+const serveHeldHome = async (command, streams, env, createGateway) => {
     // Under a service manager the daemon's stdout is gone, so everything it
     // says is also written to ~/.stratus/logs — that file is what `stratus
     // logs` reads, and the only record of an overnight run.
@@ -5069,6 +6006,8 @@ export const runServe = async (command, streams, env = {}) => {
     // Typed as the seam, not as whatever the first push happens to be: the
     // list holds the control API and the Slack adapter alike.
     const controlApiChannels = [];
+    /** The API adapter itself, for what the seam does not carry: its address, and the sessions it hands across a restart. */
+    let boundApi;
     if (apiWanted) {
         const createControlApi = await loadControlApi();
         // Resolved into locals first. Inlined, `a ?? b !== undefined` parses as
@@ -5077,16 +6016,23 @@ export const runServe = async (command, streams, env = {}) => {
         // Everything still bound and every test still passed, on whichever port
         // nobody happened to be using.
         const apiHost = command.apiHost ?? apiConfig.host;
-        const apiPort = command.apiPort ?? apiConfig.port;
+        const requestedPort = command.apiPort ?? apiConfig.port;
+        // The port the last daemon bound, from the supervisor that started
+        // this one — taken only where this daemon's own request is still for
+        // any free port. See BOUND_API_PORT_ENV.
+        const hinted = Number(readProcessEnv(env)[BOUND_API_PORT_ENV]);
+        const apiPort = requestedPort === 0 && Number.isInteger(hinted) && hinted > 0 ? hinted : requestedPort;
         if (createControlApi) {
-            controlApiChannels.push(createControlApi({
+            const api = createControlApi({
                 env,
                 ...(apiHost !== undefined ? { host: apiHost } : {}),
                 ...(apiPort !== undefined ? { port: apiPort } : {}),
                 ...(command.configPath ? { configPath: command.configPath } : {}),
                 log,
                 warn,
-            }));
+            });
+            boundApi = api;
+            controlApiChannels.push(api);
         }
         else if (command.api === true || apiConfig.enabled === true) {
             // Only when someone asked for it explicitly. A daemon that was never
@@ -5095,6 +6041,18 @@ export const runServe = async (command, streams, env = {}) => {
                 + 'Run `npm install -g @stratusagent/control-api` to bring it online; starting without it.');
         }
     }
+    // Listening before anything else is awaited: what the supervisor hands
+    // this daemon is queued in the channel until then, and the API keeps it
+    // until it is serving.
+    const supervised = Boolean(readProcessEnv(env)[SUPERVISED_ENV]);
+    const link = env.supervisorLink ?? defaultSupervisorLink;
+    if (supervised) {
+        link.receive((message) => {
+            if (message.type === 'stratusd.sessions') {
+                boundApi?.adoptSessions(message.sessions);
+            }
+        });
+    }
     const channelCredentials = await loadChannelCredentials(env);
     const slackAgents = Object.entries(channelCredentials.slack ?? {});
     const channels = [...controlApiChannels];
@@ -5192,7 +6150,10 @@ export const runServe = async (command, streams, env = {}) => {
     // a tool that carries no command string is judged by its risk exactly as
     // before. The whitelist lives beside the agent's soul, per agent.
     const commands = {
-        whitelist: createFileCommandWhitelist({ directory: agentsDirPath(env) }),
+        // A whitelist that exists and will not read is said here, once, and
+        // never written over — the daemon's log is where a grant list going
+        // quiet would otherwise go unnoticed.
+        whitelist: createFileCommandWhitelist({ directory: agentsDirPath(env), warn }),
         onScopeRemembered: ({ agentId, scope }) => {
             // An approval that widens what runs unattended, for every future
             // session, is precisely the decision that must not be the one leaving
@@ -5200,14 +6161,24 @@ export const runServe = async (command, streams, env = {}) => {
             log(`${agentId}: "${describeCommandScope(scope)}" now runs without asking`);
         },
     };
+    // The origin-scope engine, whose grants live in the same file as the
+    // command scopes: one place an operator looks to see what an agent may
+    // do unattended. Wired unconditionally for the same reason — a tool that
+    // names no origin is judged by its risk exactly as before.
+    const origins = {
+        whitelist: commands.whitelist,
+        onScopeRemembered: ({ agentId, scope }) => {
+            log(`${agentId}: ${describeOriginScope(scope)} is now acted on without asking`);
+        },
+    };
     const approvals = (transport) => createPermissionPolicy(
     // The destination scope rides along in BOTH modes — it is what lets a
     // scheduled turn report to the channel a human approved with the
     // schedule, and headless (where every other gated call is refused) is
     // exactly the deployment it exists for.
     approvalMode === 'remote'
-        ? { mode: 'remote', request: transport.request, onDecision, commands, destinations: transport.destinations }
-        : { mode: 'headless', onDecision, commands, destinations: transport.destinations });
+        ? { mode: 'remote', request: transport.request, onDecision, commands, origins, destinations: transport.destinations }
+        : { mode: 'headless', onDecision, commands, origins, destinations: transport.destinations });
     if (approvalMode === 'remote') {
         // Only agents whose channel actually came up can be asked: tokens on
         // disk with the Slack package missing means nothing renders the
@@ -5215,9 +6186,30 @@ export const runServe = async (command, streams, env = {}) => {
         const askable = slackAdapterUp ? slackAgents.map(([agentId]) => agentId) : [];
         log(`approvals: remote — gated calls are parked and asked in Slack (${describeApprovers(approvalsConfig, askable)})`);
     }
+    /**
+     * The one signal handler this daemon has, for the whole of its life —
+     * installed by the wait below, removed in the finally after the drain.
+     * See the wait for why it is never `once` and never removed sooner.
+     */
+    let stopSignal;
+    let repeatWarned = false;
+    // The gateway's restart hands the process back here once it has stopped:
+    // the outcome is kept and the wait below released, and the tail of this
+    // function decides what "come back" means for this process.
+    let restart;
+    /** A signal or the host's abort asked for a stop — set when the wait ends for that reason. */
+    let stopRequested = false;
+    let requestShutdown = () => { };
+    const shutdownRequested = new Promise((resolve) => {
+        requestShutdown = resolve;
+    });
     const gateway = createGateway({
         env,
         approvals,
+        onRestart: (outcome) => {
+            restart = outcome;
+            requestShutdown();
+        },
         ...(Object.keys(pluginsConfig).length > 0
             ? {
                 plugins: pluginsConfig,
@@ -5299,36 +6291,46 @@ export const runServe = async (command, streams, env = {}) => {
         });
     }
     await gateway.start();
-    // The roster is only known once the gateway has loaded it, and in remote
-    // mode an agent no channel can ask for is the quietest failure this
-    // feature has: its gated calls park with nobody rendering them and wait
-    // out the whole timeout before being denied. No channel can detect this
-    // on its own — a request is a broadcast, and no adapter knows whether
-    // another one is about to answer — so it is reported here, where the
-    // roster and the channel list are both in view.
-    if (approvalMode === 'remote') {
-        const askable = new Set(slackAdapterUp ? slackAgents.map(([agentId]) => agentId) : []);
-        const unreachable = gateway.agents().map((agent) => agent.id).filter((id) => !askable.has(id));
-        if (unreachable.length > 0) {
-            warn(`no channel can ask for ${unreachable.join(', ')}, so their gated calls will wait out the `
-                + 'approval timeout and then be denied. Connect a Slack app for them, or run with --approvals headless.');
-        }
-    }
-    writeLine(streams.stdout, 'Press Ctrl+C to stop.');
-    // And periodically, for a long-running daemon that warns steadily
-    // without ever writing enough records to rotate. Unref'd, so it never
-    // holds the process open. Armed only once the daemon is actually
-    // serving: every step above can throw, and runServe is an exported
-    // function as much as a process entry point — in a host that survives
-    // the failure, a timer armed before the throw would outlive the call
-    // and go on truncating that environment's redirect logs. The finally
-    // below takes it down on every other exit path.
+    // Read now, while the API is bound: its stop forgets the address, and
+    // a restart's respawn needs it (see ServeOutcome).
+    const boundApiPort = boundApi?.url !== undefined ? Number(new URL(boundApi.url).port) : undefined;
+    if (supervised && boundApiPort !== undefined && Number.isInteger(boundApiPort) && boundApiPort > 0) {
+        link.send({ type: 'stratusd.bound-api-port', port: boundApiPort });
+    }
+    // Under one finally from here: a throw anywhere after the start — a
+    // host's writable refusing a line, say — must still stop the gateway
+    // before the claim on the home is released, or a live gateway would be
+    // left behind a lock the next daemon can take.
     let redirectTimer;
-    if (logWriter) {
-        redirectTimer = setInterval(() => void truncateRedirectLogs(logsDirPath(env)), 5 * 60_000);
-        redirectTimer.unref?.();
-    }
     try {
+        // The roster is only known once the gateway has loaded it, and in remote
+        // mode an agent no channel can ask for is the quietest failure this
+        // feature has: its gated calls park with nobody rendering them and wait
+        // out the whole timeout before being denied. No channel can detect this
+        // on its own — a request is a broadcast, and no adapter knows whether
+        // another one is about to answer — so it is reported here, where the
+        // roster and the channel list are both in view.
+        if (approvalMode === 'remote') {
+            const askable = new Set(slackAdapterUp ? slackAgents.map(([agentId]) => agentId) : []);
+            const unreachable = gateway.agents().map((agent) => agent.id).filter((id) => !askable.has(id));
+            if (unreachable.length > 0) {
+                warn(`no channel can ask for ${unreachable.join(', ')}, so their gated calls will wait out the `
+                    + 'approval timeout and then be denied. Connect a Slack app for them, or run with --approvals headless.');
+            }
+        }
+        writeLine(streams.stdout, 'Press Ctrl+C to stop.');
+        // And periodically, for a long-running daemon that warns steadily
+        // without ever writing enough records to rotate. Unref'd, so it never
+        // holds the process open. Armed only once the daemon is actually
+        // serving: every step above can throw, and runServe is an exported
+        // function as much as a process entry point — in a host that survives
+        // the failure, a timer armed before the throw would outlive the call
+        // and go on truncating that environment's redirect logs. The finally
+        // below takes it down on every other exit path.
+        if (logWriter) {
+            redirectTimer = setInterval(() => void truncateRedirectLogs(logsDirPath(env)), 5 * 60_000);
+            redirectTimer.unref?.();
+        }
         // Hold the event loop open until a shutdown request, then drain: new
         // dispatches are refused while in-flight turns finish.
         await new Promise((resolve) => {
@@ -5340,12 +6342,46 @@ export const runServe = async (command, streams, env = {}) => {
                 }
                 settled = true;
                 clearInterval(keepAlive);
-                process.off('SIGTERM', shutdown);
-                process.off('SIGINT', shutdown);
                 resolve();
             };
-            process.once('SIGTERM', shutdown);
-            process.once('SIGINT', shutdown);
+            stopSignal = () => {
+                if (!settled) {
+                    shutdown();
+                    return;
+                }
+                // A signal while a drain is already running — a repeat, or a stop
+                // arriving during a restart's drain. Either way the drain goes on,
+                // and a daemon told to stop does not come back.
+                stopRequested = true;
+                if (!repeatWarned) {
+                    repeatWarned = true;
+                    // Said from signal dispatch, outside the promise and its finally:
+                    // a stream that throws on write (a host's injected stderr) would
+                    // otherwise end the process from here — mid-drain, the very
+                    // thing this handler exists to prevent. The word is best effort.
+                    try {
+                        warn('stop signal received while draining; still draining, and this daemon will not come back (SIGKILL ends it at once)');
+                    }
+                    catch {
+                        // Nothing to say it to; the drain is what matters.
+                    }
+                }
+            };
+            // `on`, never `once`, and not removed until the drain is over (the
+            // finally below). `once` drops the listener before running it, Node
+            // uninstalls its native handler the moment no listener is left, and
+            // a second SIGTERM landing in that window ends the process by the
+            // default action — mid-drain, with nothing said. The second signal
+            // is the normal case, not an edge: a stop delivered to the process
+            // group, as systemd's KillMode=control-group and a terminal's Ctrl+C
+            // deliver it, reaches a supervised daemon once from the kernel and
+            // once more forwarded by its supervisor. Reproduced two runs in
+            // three: the replacement died and the supervisor exited 1 on a
+            // `stratus service stop` after a restart. SIGKILL still ends the
+            // process at once.
+            process.on('SIGTERM', stopSignal);
+            process.on('SIGINT', stopSignal);
+            void shutdownRequested.then(shutdown);
             if (env.shutdownSignal?.aborted) {
                 shutdown();
             }
@@ -5353,20 +6389,85 @@ export const runServe = async (command, streams, env = {}) => {
                 env.shutdownSignal?.addEventListener('abort', shutdown, { once: true });
             }
         });
-        writeLine(streams.stdout, 'Stopping — draining in-flight turns.');
-        await gateway.stop();
-        return 0;
+        // Decided now, before the stop below: a restart's drain can still be
+        // running when a stop signal releases this wait, and `onRestart` then
+        // fires during that stop. A daemon told to stop does not come back,
+        // whatever it was told before.
+        if (!restart) {
+            stopRequested = true;
+        }
+        if (restart) {
+            // Already stopped: the gateway drained and closed before handing the
+            // process over, and the stop() below finds nothing to do. Said here,
+            // while the structured log still takes writes — the next lines
+            // belong to a process that has none.
+            if (!restart.drained) {
+                // A turn that ignored its abort is still running in this process,
+                // possibly still writing sessions. Starting a fresh daemon beside
+                // it would be two processes on one store; exiting instead leaves
+                // the service manager, where there is one, to bring it back.
+                warn(`restart: something did not let go; exiting with status ${UNDRAINED_RESTART_EXIT_CODE} for the service manager to restart, instead of starting a new daemon beside it`);
+            }
+            else {
+                log(`restarting stratusd${restart.reason ? ` (${restart.reason})` : ''}`);
+            }
+        }
+        else {
+            writeLine(streams.stdout, 'Stopping — draining in-flight turns.');
+        }
     }
     finally {
-        if (redirectTimer) {
-            clearInterval(redirectTimer);
+        try {
+            await gateway.stop();
+            // Writes are queued and dropped on the hot path so logging never sits
+            // on a streamed token. That makes the tail of the log the part most
+            // likely to be lost — and the tail is the shutdown reason, the last
+            // warning, the line explaining a restart.
+            await logWriter?.flush();
         }
-        // Writes are queued and dropped on the hot path so logging never sits
-        // on a streamed token. That makes the tail of the log the part most
-        // likely to be lost — and the tail is the shutdown reason, the last
-        // warning, the line explaining a restart.
-        await logWriter?.flush();
-    }
+        finally {
+            // The shutdown is over, the flush included: a stop signal from here
+            // on is the process's to handle by default again — and a host that
+            // calls runServe repeatedly (the tests) must not accumulate handlers.
+            // Last, and under its own finally, because the listener is on the
+            // global process: taken off before the flush, a repeated signal
+            // landing during it would end the process by the default action
+            // (which a supervisor reports as a failure, and a service manager
+            // set to restart on failure would then bring back a daemon an
+            // operator just stopped); left on by a stop() that rejects (its last
+            // log line can throw through an injected stream), a settled handler
+            // would swallow the host's next signal.
+            if (stopSignal) {
+                process.off('SIGTERM', stopSignal);
+                process.off('SIGINT', stopSignal);
+            }
+            if (redirectTimer) {
+                clearInterval(redirectTimer);
+            }
+        }
+    }
+    const bound = boundApiPort !== undefined && Number.isInteger(boundApiPort) && boundApiPort > 0
+        ? { boundApiPort }
+        : {};
+    if (!restart || stopRequested) {
+        return { code: 0, ...bound, sessions: [] };
+    }
+    if (!restart.drained) {
+        (env.exitProcess ?? process.exit)(UNDRAINED_RESTART_EXIT_CODE);
+        return { code: UNDRAINED_RESTART_EXIT_CODE, ...bound, sessions: [] };
+    }
+    // Coming back: the browser sessions live at the stop go to the
+    // replacement — up the channel to the supervisor when this daemon has
+    // one, else with the outcome to the supervisor this process becomes.
+    const sessions = boundApi?.sessionsAtStop() ?? [];
+    if (supervised && sessions.length > 0) {
+        link.send({ type: 'stratusd.sessions', sessions });
+    }
+    // Asked to come back. Whether this process starts the next daemon or
+    // exits for its supervisor to is `runServe`'s decision, after the home
+    // is released: the claim is held until this returns, and a daemon
+    // started before that would be refused as a second one on the home.
+    return { code: RESTART_EXIT_CODE, ...bound, sessions };
 };
 export const runCli = async ({ argv, streams = process, env = {} }) => {
     try {
@@ -5405,6 +6506,7 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
                     || command.command === 'run'
                     || command.command === 'skill-add'
                     || command.command === 'dashboard'
+                    || (command.command === 'credential' && command.action !== 'list')
                     || (command.command === 'schedules' && command.action === 'cancel')
                     || (command.command === 'service' && (command.action === 'install' || command.action === 'start'));
                 if (writesState) {
@@ -5444,9 +6546,21 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.command === 'skill-add') {
             return await runSkillAdd(command, streams, resolvedEnv);
         }
+        if (command.command === 'skill-validate') {
+            return await runSkillValidate(command, streams, resolvedEnv);
+        }
         if (command.command === 'skills') {
             return await runSkills(streams, resolvedEnv);
         }
+        if (command.command === 'credential') {
+            return await runCredential(command, streams, resolvedEnv);
+        }
+        if (command.command === 'skill-reload') {
+            return await runSkillReload(command, streams, resolvedEnv);
+        }
+        if (command.command === 'restart') {
+            return await runRestart(command, streams, resolvedEnv);
+        }
         if (command.command === 'schedules') {
             return await runSchedules(command, streams, resolvedEnv);
         }