@stratusagent/cli 0.11.0 → 0.11.2

package/dist/index.js

@@ -13,14 +13,14 @@ import { mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from 'node:
 import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
-import { AgentRunner, AllowAllApprovalPolicy, EventBus, SkillRegistry, ToolRegistry, matchesSkillAllowlist, missingSkillRequirements, originOf, } from '@stratusagent/core';
+import { AgentRunner, AllowAllApprovalPolicy, EventBus, SkillRegistry, ToolRegistry, isTrustLevel, matchesSkillAllowlist, escapeControlCharacters, memoryEntryTrust, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, originOf, TRUST_LEVELS, } from '@stratusagent/core';
 import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
 import { loadPlugins } from '@stratusagent/plugins';
 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, 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 { canonicalDestination, createForgetTool, createRecallTool, createRememberTool, defineAgent, describeCadence, describeSchedule, FORGET_TOOL_NAME, MEMORY_TOOL_NAME, formatSoul, generateAgentName, isLoadableSkillId, isValidAgentId, parseSoul, GATEWAY_ONLY_TOOL_NAMES, } 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, resolveAgentPrincipals, 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";
@@ -133,7 +133,7 @@ const defaultPackageInstaller = async (packages) => {
  * 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';
+export const CLI_VERSION = '0.11.2';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 /**
  * The range every package declares in its `engines` field. Two floors, not
@@ -259,6 +259,9 @@ Usage:
   stratus restart
   stratus schedules
   stratus schedules cancel <id>
+  stratus memory list ava
+  stratus memory reassert ava --trust user --all-unknown
+  stratus session rollover slack:ava:T01ABCDEF:D07GHIJKL
   printf %s "$BRAVE_KEY" | stratus credential set search.apiKey
   stratus credentials
   stratus doctor
@@ -347,6 +350,24 @@ Commands:
                    cancel <id>" stops the next firing and revokes the
                    destination that was approved with it
                    (also: stratus schedule list / schedule cancel <id>)
+  memory list      Show an agent's live memory with the trust label each
+                   entry carries — user, agent, unknown (no recorded origin,
+                   or written in a conversation with someone not configured
+                   as a principal), external (recorded after reading content
+                   from outside). --trust <level> filters; --format json
+  memory reassert  Re-label entries as an operator: stratus memory reassert
+                   <agent> --trust user <id>..., or --all-unknown for every
+                   entry with no recorded origin (the upgrade case; an
+                   entry recorded unknown — a stranger's message, a shell
+                   command — is left for you to name by id). Appends
+                   a record to ~/.stratus/memory.jsonl; a running daemon
+                   sees it on its next turn. The only way a label ever
+                   rises — no tool can do this
+  session rollover Start a conversation over under the same session id,
+                   archiving its transcript so far — for a long-lived
+                   session (a Slack DM) that predates provenance tracking
+                   and would otherwise write unknown forever. Asks the
+                   running daemon (--gateway, --token)
   agent new        Create an agent identity (generates a human-ish name + avatar theme)
   agents           List your agents: who they are, where their souls live, what
                    they run on, what they remember (also: stratus agent list).
@@ -392,9 +413,12 @@ 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 / skill reload / restart: a running daemon's control
-                   API (skill reload and restart default to the daemon
+  --gateway        agents / skill reload / restart / session rollover: a running
+                   daemon's control API (all but agents default to the daemon
                    ~/.stratus/gateway.json names)
+  --trust          memory list: show only this label; memory reassert: the
+                   label to record (user, agent, unknown, external)
+  --all-unknown    memory reassert: every live entry with no recorded origin
   --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
@@ -1046,6 +1070,123 @@ export const parseCommand = (argv, env = {}) => {
             ...(reload ? {} : { reload }),
         };
     }
+    if (command === 'memory') {
+        const [action, ...memoryRest] = rest;
+        if (action === undefined || action === '--help' || action === '-h') {
+            return { command: 'help' };
+        }
+        if (action !== 'list' && action !== 'reassert') {
+            throw new Error(`Unknown memory subcommand: ${action}. Try: stratus memory list <agent>, stratus memory reassert <agent> --trust user <id>...`);
+        }
+        let agentId;
+        let trust;
+        let format = 'text';
+        let allUnknown = false;
+        const ids = [];
+        for (let index = 0; index < memoryRest.length; index += 1) {
+            const token = memoryRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--trust') {
+                const value = readOptionValue(memoryRest, index, '--trust');
+                if (!isTrustLevel(value)) {
+                    throw new Error(`Unsupported trust level: ${value}. Use one of ${TRUST_LEVELS.join(', ')}.`);
+                }
+                trust = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--format') {
+                const value = readOptionValue(memoryRest, index, '--format');
+                if (value !== 'text' && value !== 'json') {
+                    throw new Error(`Unsupported format: ${value}`);
+                }
+                format = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--all-unknown' && action === 'reassert') {
+                allUnknown = true;
+                continue;
+            }
+            if (token.startsWith('--')) {
+                throw new Error(`Unknown option: ${token}`);
+            }
+            if (agentId === undefined) {
+                agentId = token;
+                continue;
+            }
+            if (action === 'reassert') {
+                ids.push(token);
+                continue;
+            }
+            throw new Error(`Unexpected argument: ${token}. Try: stratus memory list <agent>`);
+        }
+        if (!agentId) {
+            throw new Error(`memory ${action} needs the agent id: stratus memory ${action} <agent>${action === 'reassert' ? ' --trust user <id>...' : ''}.`);
+        }
+        if (action === 'reassert') {
+            if (trust === undefined) {
+                throw new Error('memory reassert needs --trust <user|agent|external|unknown>: the label you are vouching for.');
+            }
+            if (ids.length === 0 && !allUnknown) {
+                throw new Error('memory reassert needs entry ids, or --all-unknown to re-label every entry that has no recorded origin.');
+            }
+        }
+        return {
+            command: 'memory',
+            action,
+            agentId,
+            ...(trust !== undefined ? { trust } : {}),
+            ids,
+            allUnknown,
+            format,
+        };
+    }
+    if (command === 'session') {
+        const [action, ...sessionRest] = rest;
+        if (action === undefined || action === '--help' || action === '-h') {
+            return { command: 'help' };
+        }
+        if (action !== 'rollover') {
+            throw new Error(`Unknown session subcommand: ${action}. Try: stratus session rollover <session-id>`);
+        }
+        const parsed = { command: 'session', action: 'rollover', sessionId: '' };
+        for (let index = 0; index < sessionRest.length; index += 1) {
+            const token = sessionRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--gateway') {
+                parsed.gateway = readOptionValue(sessionRest, index, '--gateway');
+                index += 1;
+                continue;
+            }
+            if (token === '--token') {
+                parsed.token = readOptionValue(sessionRest, index, '--token');
+                index += 1;
+                continue;
+            }
+            if (token.startsWith('--')) {
+                throw new Error(`Unknown option: ${token}`);
+            }
+            if (parsed.sessionId.length > 0) {
+                throw new Error(`Unexpected argument: ${token}. Try: stratus session rollover <session-id>`);
+            }
+            parsed.sessionId = token;
+        }
+        if (parsed.sessionId.length === 0) {
+            throw new Error('session rollover needs the session id: stratus session rollover <session-id>. `stratus logs` shows ids in its last column.');
+        }
+        return parsed;
+    }
     if (command === 'restart') {
         const parsed = { command: 'restart' };
         for (let index = 0; index < rest.length; index += 1) {
@@ -1291,6 +1432,8 @@ export const formatEvent = (event) => {
             return `• session.completed ${event.sessionId}`;
         case 'session.failed':
             return `• session.failed ${event.error}`;
+        case 'session.tainted':
+            return `• session.tainted ${event.trust} (${event.source})`;
         default:
             return null;
     }
@@ -1341,6 +1484,11 @@ export const eventDetail = (event) => {
             };
         case 'session.failed':
             return { error: event.error };
+        case 'session.tainted':
+            // The label and what lowered it — a tool's name, or `memory`,
+            // `sender`, `legacy`. Never the content that did: same rule as every
+            // other event here.
+            return { trust: event.trust, source: event.source };
         default:
             return undefined;
     }
@@ -1597,6 +1745,26 @@ const createAgentRuntime = async (streams, options) => {
     for (const { skill, missing } of missingSkillRequirements(agent, skills)) {
         writeLine(streams.stderr, `Warning: agent ${agent.id} enables skill ${skill.id}, which expects tools the agent is not allowed: ${missing.join(', ')}`);
     }
+    // And the same for the tools themselves, after `initialize()` so the
+    // plugins have registered theirs: an allowlist entry naming a tool
+    // nothing provides grants nothing and says nothing, and a soul made only
+    // of those runs with no tools while its persona still talks about them.
+    const finding = unmatchedToolAllowlist(agent, tools.describe().map((tool) => tool.name), {
+        mayRegister: loadedPlugins.flatMap((plugin) => plugin.manifest.contributes.toolsDiscovered.map((declared) => declared.namespace)),
+        // A local run has no dispatcher, store, or channels, so it registers
+        // none of the daemon's tools. A soul written for `stratus serve` is
+        // not wrong for naming them here — it is in the wrong process.
+        elsewhere: GATEWAY_ONLY_TOOL_NAMES,
+    });
+    for (const line of finding ? describeToolAllowlistFinding(agent.id, finding) : []) {
+        writeLine(streams.stderr, `Warning: ${line}`);
+    }
+    // The kernel leaves this one to the host, because only the host knows
+    // which process it is not.
+    if (finding && finding.elsewhere.length > 0) {
+        writeLine(streams.stderr, `Warning: agent ${agent.id} lists ${finding.elsewhere.join(', ')}, which only the daemon provides`
+            + ' — the names are right, but stratus run cannot call them; stratus serve can');
+    }
     const metadata = options.runtime.provider === 'demo'
         ? { provider: 'demo', executor: 'local-command' }
         : {
@@ -2259,20 +2427,28 @@ const verifySlackAppToken = async (token, fetchImpl) => {
 // package being installed.
 const SLACK_BOT_SCOPES = [
     'app_mentions:read',
+    // The history family is what lets an agent stay in a conversation it was
+    // brought into: without it Slack delivers only mentions, and a reply in
+    // the agent's own thread never reaches it. It is the workspace's switch
+    // for that — an app installed without these scopes answers mentions and
+    // nothing else, exactly as it always did.
+    'channels:history',
     // The conversations read family backs outbound destination validation
     // (conversations.info): whether a channel a schedule wants to report to
     // exists, and whether this app is a member of it.
     'channels:read',
     'chat:write',
     'files:write',
+    'groups:history',
     'groups:read',
     'im:history',
     'im:read',
     'im:write',
+    'mpim:history',
     'mpim:read',
     'users:read',
 ];
-const SLACK_BOT_EVENTS = ['app_mention', 'message.im'];
+const SLACK_BOT_EVENTS = ['app_mention', 'message.channels', 'message.groups', 'message.im', 'message.mpim'];
 export const slackAppManifest = (agentName) => JSON.stringify({
     display_information: {
         name: agentName,
@@ -4273,6 +4449,37 @@ const loadServeApprovals = async (env, configPath, warn) => {
  * `agentIds` is therefore the agents that can actually be *asked*, not
  * every agent with tokens on disk.
  */
+/**
+ * The `principals` block, read under the same trust rule as `approvals` and
+ * for a sharper reason: it names the people whose messages an agent takes
+ * as its operator's, which is the trust root everything downstream lowers
+ * from. A cloned repo appointing itself the principal would arrive as
+ * `user` in every Slack thread the daemon serves.
+ */
+const loadServePrincipals = async (env, configPath, warn) => {
+    const block = await readTrustedConfigBlock('principals', env, configPath);
+    if (block.status === 'untrusted') {
+        warn(`ignoring the principals config in ${block.path}: a project-local config cannot decide whose messages `
+            + 'this daemon\'s agents treat as their operator\'s. Move it to ~/.stratus/config.json, or pass it with --config.');
+        return {};
+    }
+    if (block.status === 'unreadable') {
+        warn(`ignoring the principals config (${block.error instanceof Error ? block.error.message : String(block.error)}); every Slack sender is unknown`);
+        return {};
+    }
+    return block.status === 'present' ? block.value : {};
+};
+/** One line saying whose messages arrive as the operator's, per Slack agent. */
+const describePrincipals = (principals, agentIds) => {
+    const covered = agentIds.filter((agentId) => (resolveAgentPrincipals(principals, agentId).slackUsers ?? []).length > 0);
+    if (covered.length === 0) {
+        return 'no principals configured, so every Slack sender is unknown and every fact written in Slack carries that label — set principals.slackUsers in ~/.stratus/config.json';
+    }
+    const uncovered = agentIds.filter((agentId) => !covered.includes(agentId));
+    return uncovered.length === 0
+        ? `principals set for ${covered.join(', ')}`
+        : `principals set for ${covered.join(', ')}; none for ${uncovered.join(', ')}, whose Slack senders are all unknown`;
+};
 const describeApprovers = (approvals, agentIds) => {
     if (agentIds.length === 0) {
         return 'but no channel is running to ask through, so gated calls will wait out the approval timeout and then be denied';
@@ -5114,6 +5321,134 @@ export const runSkillReload = async (command, streams, env = {}) => {
     writeLine(streams.stdout, `reloaded skills in the daemon at ${base} — ${ids.length} skill(s) serving${ids.length > 0 ? `: ${ids.join(', ')}` : ''}`);
     return 0;
 };
+/**
+ * `stratus memory list|reassert` — the operator's half of provenance.
+ *
+ * `list` shows what an agent's store holds with the label each entry
+ * carries, because an operator cannot re-assert what they cannot see.
+ * `reassert` is the one way a label ever rises: it appends a re-assertion
+ * record to the JSONL (never rewrites a line), so a running daemon — which
+ * re-reads the file on every read — sees it at once. Operator only, on
+ * purpose: no tool exposes this, because an agent re-labelling its own
+ * memory as trusted is the attack writing its own permission slip.
+ *
+ * `--all-unknown` exists for the upgrade: every entry written before labels
+ * existed reads `unknown`, and the injected slice of such a store makes
+ * every session `unknown` on its first turn. Re-asserting the entries the
+ * agent actually surfaces, once, is the bounded work that drains it.
+ */
+export const runMemory = async (command, streams, env = {}) => {
+    // Only the writer folds a legacy per-directory store in: `list` is the
+    // read-only command a downgraded build is allowed to run against newer
+    // state, and a migration is a write.
+    if (command.action === 'reassert') {
+        await migrateLegacyMemory(env);
+    }
+    const store = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(env)));
+    // Two ways an entry reads `unknown`, and only one is the upgrade case:
+    // no label at all (written before labels existed, or added by hand), or a
+    // recorded `unknown` — a session that heard from a sender nobody vouched
+    // for, or ran a shell command. The bulk re-assertion is for the first;
+    // the second may hold a stranger's text and is named by id, once read.
+    const unlabelled = (entry) => entry.trust === undefined;
+    const describeEntry = (entry) => ({
+        id: entry.id,
+        trust: memoryEntryTrust(entry),
+        content: entry.content,
+        createdAt: entry.createdAt,
+        ...(entry.origin ? { origin: entry.origin } : {}),
+    });
+    if (command.action === 'list') {
+        const live = (await store.list(command.agentId)).entries
+            .filter((entry) => command.trust === undefined || memoryEntryTrust(entry) === command.trust);
+        if (command.format === 'json') {
+            writeLine(streams.stdout, JSON.stringify({ agentId: command.agentId, entries: live.map(describeEntry) }, null, 2));
+            return 0;
+        }
+        if (live.length === 0) {
+            writeLine(streams.stdout, command.trust === undefined
+                ? `${command.agentId} has no live memory entries in ${memoryFilePath(env)}.`
+                : `${command.agentId} has no live memory entries at ${command.trust}.`);
+            return 0;
+        }
+        for (const entry of live) {
+            const taintedBy = entry.origin?.taintedBy ? `  (tainted by ${entry.origin.taintedBy})` : '';
+            const unrecorded = unlabelled(entry) ? '  (no recorded origin)' : '';
+            writeLine(streams.stdout, `${entry.id}  [${memoryEntryTrust(entry)}]${taintedBy}${unrecorded}`);
+            writeLine(streams.stdout, `  ${escapeControlCharacters(entry.content)}`);
+        }
+        if (command.trust === undefined) {
+            const unlabelledCount = live.filter(unlabelled).length;
+            const recordedUnknown = live.filter((entry) => !unlabelled(entry) && memoryEntryTrust(entry) === 'unknown').length;
+            if (unlabelledCount > 0) {
+                writeLine(streams.stdout, '');
+                writeLine(streams.stdout, `${unlabelledCount} entr${unlabelledCount === 1 ? 'y has' : 'ies have'} no recorded origin, so any session that reads one writes unknown. `
+                    + `Review them, then: stratus memory reassert ${command.agentId} --trust user --all-unknown (or name ids).`);
+            }
+            if (recordedUnknown > 0) {
+                writeLine(streams.stdout, '');
+                writeLine(streams.stdout, `${recordedUnknown} entr${recordedUnknown === 1 ? 'y was' : 'ies were'} recorded unknown — written after a message from someone not configured as a principal, or after a shell command — `
+                    + 'and may repeat what a stranger said. --all-unknown leaves these alone; re-assert one by id once you have read it.');
+            }
+        }
+        return 0;
+    }
+    if (!store.reassertTrust) {
+        writeLine(streams.stderr, 'Error: this memory store cannot re-assert trust.');
+        return 1;
+    }
+    const trust = command.trust ?? 'user';
+    const live = (await store.list(command.agentId)).entries;
+    const targets = command.allUnknown
+        ? [...new Set([...live.filter(unlabelled).map((entry) => entry.id), ...command.ids])]
+        : command.ids;
+    if (targets.length === 0) {
+        writeLine(streams.stdout, `${command.agentId} has no live entries with no recorded origin; nothing to re-assert. An entry recorded unknown is named by id.`);
+        return 0;
+    }
+    const missing = [];
+    let changed = 0;
+    for (const id of targets) {
+        if (await store.reassertTrust(command.agentId, id, trust)) {
+            changed += 1;
+        }
+        else {
+            missing.push(id);
+        }
+    }
+    if (command.format === 'json') {
+        writeLine(streams.stdout, JSON.stringify({ agentId: command.agentId, trust, reasserted: changed, missing }, null, 2));
+    }
+    else {
+        writeLine(streams.stdout, `Re-asserted ${changed} entr${changed === 1 ? 'y' : 'ies'} of ${command.agentId} as ${trust}. A running daemon reads the change on its next turn.`);
+    }
+    for (const id of missing) {
+        writeLine(streams.stderr, `No live memory entry with id ${id} belongs to ${command.agentId}; nothing was re-asserted for it.`);
+    }
+    return missing.length === 0 ? 0 : 1;
+};
+/**
+ * `stratus session rollover <id>` — start a conversation over under the
+ * same id, archiving its transcript so far. The daemon does the work, on
+ * the session's own chain, so a turn cannot interleave; this only asks.
+ */
+export const runSessionRollover = 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/sessions/${encodeURIComponent(command.sessionId)}/rollover`);
+    if (!response.ok) {
+        writeLine(streams.stderr, `Error: ${await gatewayErrorMessage(response)}`);
+        return 1;
+    }
+    const outcome = await response.json();
+    writeLine(streams.stdout, `Rolled over ${outcome.sessionId ?? command.sessionId}: the next message starts a fresh conversation, `
+        + `and the transcript so far is archived as ${outcome.archivedAs ?? '(unknown)'}.`);
+    writeLine(streams.stdout, 'A fresh session still reads the memory it injects — if that slice holds entries with no recorded origin, `stratus memory list <agent>` shows them and `stratus memory reassert` re-labels them.');
+    return 0;
+};
 export const runRestart = async (command, streams, env = {}) => {
     const base = await runningGatewayBase(env, command);
     if (!base) {
@@ -5994,6 +6329,7 @@ const serveHeldHome = async (command, streams, env, createGateway) => {
     // approve this" differently from "is anyone being asked at all".
     const approvalsConfig = await loadServeApprovals(env, command.configPath, warn);
     const approvalMode = command.approvals ?? approvalsConfig.mode ?? 'headless';
+    const principalsConfig = await loadServePrincipals(env, command.configPath, warn);
     // Read here rather than inside the gateway for the same reason as the two
     // blocks above: the trust boundary is a property of *which file* said it,
     // and this is where the file precedence is already understood.
@@ -6074,12 +6410,14 @@ const serveHeldHome = async (command, streams, env, createGateway) => {
             channels.push(adapter({
                 agents: slackAgents.map(([agentId, tokens]) => {
                     const route = resolveAgentApprovals(approvalsConfig, agentId);
+                    const principals = resolveAgentPrincipals(principalsConfig, agentId);
                     return {
                         agentId,
                         appToken: tokens.appToken,
                         botToken: tokens.botToken,
                         ...(route.slackApprovers ? { approvers: route.slackApprovers } : {}),
                         ...(route.slackChannel ? { approvalChannel: route.slackChannel } : {}),
+                        ...(principals.slackUsers ? { principals: principals.slackUsers } : {}),
                     };
                 }),
                 log,
@@ -6186,6 +6524,12 @@ const serveHeldHome = async (command, streams, env, createGateway) => {
         const askable = slackAdapterUp ? slackAgents.map(([agentId]) => agentId) : [];
         log(`approvals: remote — gated calls are parked and asked in Slack (${describeApprovers(approvalsConfig, askable)})`);
     }
+    if (slackAdapterUp) {
+        // Said at startup, because the failure it names is silent otherwise: a
+        // daemon with no principals serves every Slack message as `unknown`,
+        // and the operator finds out when their agent's memory reads that way.
+        log(`provenance: ${describePrincipals(principalsConfig, slackAgents.map(([agentId]) => agentId))}`);
+    }
     /**
      * 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.
@@ -6491,6 +6835,17 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         // to be able to report what is pending rather than having just done it.
         if (command.command !== 'update') {
             const stamp = await readStateStamp(resolvedEnv);
+            const writesState = command.command === 'serve'
+                || command.command === 'setup'
+                || command.command === 'chat'
+                || command.command === 'run'
+                || command.command === 'skill-add'
+                || command.command === 'dashboard'
+                || (command.command === 'credential' && command.action !== 'list')
+                || (command.command === 'schedules' && command.action === 'cancel')
+                || (command.command === 'memory' && command.action === 'reassert')
+                || command.command === 'session'
+                || (command.command === 'service' && (command.action === 'install' || command.action === 'start'));
             if (stamp.schemaVersion > STATE_SCHEMA_VERSION) {
                 // Anything that writes under ~/.stratus refuses, not only the
                 // daemon: a downgraded build's setup, chat, or run can discard
@@ -6500,15 +6855,6 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
                 // diagnoses their way OUT of this state; so do `service stop`,
                 // `status`, and `uninstall`, for the same reason. (`agent new`
                 // only prints an identity — it writes nothing.)
-                const writesState = command.command === 'serve'
-                    || command.command === 'setup'
-                    || command.command === 'chat'
-                    || 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) {
                     writeLine(streams.stderr, newerStateMessage(stamp.schemaVersion));
                     writeLine(streams.stderr, `Refusing \`stratus ${command.command}\` — it writes state the newer format owns. Read-only commands (logs, agents, doctor, service status/stop) still work.`);
@@ -6525,10 +6871,21 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
                     }
                 }
                 catch (error) {
-                    // A failed migration must not brick every command, but running
-                    // on unmigrated state is worth a line: silence here is how the
-                    // migrated and unmigrated populations diverge.
-                    writeLine(streams.stderr, `Warning: state migration failed (${error instanceof Error ? error.message : String(error)}). Continuing on unmigrated state — \`stratus update\` retries it.`);
+                    const reason = error instanceof Error ? error.message : String(error);
+                    // A command that writes state must not run on a home whose stamp
+                    // could not be written: the labels it would persist are what the
+                    // stamp protects, and a stamp still reading the old schema lets a
+                    // downgraded build in afterwards to read an `external` fact as
+                    // ordinary memory — the exact hole the stamp closes. A read-only
+                    // command warns and continues, because reading is how someone
+                    // diagnoses their way out; silence here is how the migrated and
+                    // unmigrated populations diverge.
+                    if (writesState) {
+                        writeLine(streams.stderr, `State migration failed (${reason}).`);
+                        writeLine(streams.stderr, `Refusing \`stratus ${command.command}\` — it writes state the migration stamps. Fix ~/.stratus (is state.json writable?) or run \`stratus update\`; read-only commands (logs, agents, doctor, memory list, service status/stop) still work.`);
+                        return 1;
+                    }
+                    writeLine(streams.stderr, `Warning: state migration failed (${reason}). Continuing on unmigrated state — \`stratus update\` retries it.`);
                 }
             }
         }
@@ -6564,6 +6921,12 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.command === 'schedules') {
             return await runSchedules(command, streams, resolvedEnv);
         }
+        if (command.command === 'memory') {
+            return await runMemory(command, streams, resolvedEnv);
+        }
+        if (command.command === 'session') {
+            return await runSessionRollover(command, streams, resolvedEnv);
+        }
         if (command.command === 'doctor') {
             return await runDoctor(command, streams, resolvedEnv);
         }