@stratusagent/gateway 0.11.3 → 0.11.5

package/dist/index.js

@@ -7,25 +7,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { createHash, randomUUID } from 'node:crypto';
-import { chmodSync, mkdirSync } from 'node:fs';
-import path from 'node:path';
-import { DatabaseSync } from 'node:sqlite';
-import { filePathsOf, isUnaddressedTurn, abortErrorFor, AgentRegistry, AgentRunner, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, } from '@stratusagent/core';
-import { createDelegateTool, createForgetTool, createMessageSendTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, } from '@stratusagent/agents';
+import { filePathsOf, isUnaddressedTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, } from '@stratusagent/core';
+import { createDelegateTool, createForgetTool, createPinTool, createMessageSendTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, } from '@stratusagent/agents';
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
+import { ShardedSessionStore } from "./sessions.js";
 export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
+export { SqliteSessionStore, ShardedSessionStore, FleetSessionIndex, SessionIdTakenError, tightenSqliteFile, } from "./sessions.js";
 export { SqliteScheduleStore, createSchedulerRuntime, isScheduleSessionId, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
 import { loadPlugins, } from '@stratusagent/plugins';
-import { createDemoTool, createFileCredentialResolver, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, memoryFilePath, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, applySoulPins, assertStateCompatible, stratusHomePath, workspacesDirPath, withLegacyDefaultMemories, } from '@stratusagent/state';
-const SESSIONS_DB_FILENAME = 'sessions.db';
-/**
- * Where a daemon with no explicit `sessionDbPath` keeps its database — the
- * one rule for it, exported because `stratus schedules` opens the same file
- * from another process and a re-derived copy of this join is how the CLI
- * ends up auditing a database no daemon writes.
- */
-export const defaultSessionDbPath = (env = {}) => path.join(stratusHomePath(env), SESSIONS_DB_FILENAME);
+import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, applySoulPins, assertStateCompatible, stratusHomePath, fleetDbIn, createAgentWorkspaces, foldedAgentId, } from '@stratusagent/state';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 /**
  * How long a parked call waits for a person. Long enough to survive a
@@ -39,179 +30,6 @@ const DEFAULT_APPROVAL_TIMEOUT_MS = 900_000;
  * 30-day approval window would expire every request almost immediately.
  */
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
-export class SqliteSessionStore {
-    db;
-    constructor(filePath, options = {}) {
-        // Sessions hold complete conversations (prompts, replies, tool output,
-        // provider replay state) — owner-only, like the credentials file. The
-        // file chmods below cover databases created earlier under a looser
-        // umask too; directories the store creates are born 0700.
-        const dir = path.dirname(filePath);
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-        if (options.ownedDirectory) {
-            chmodSync(dir, 0o700);
-        }
-        this.db = new DatabaseSync(filePath);
-        // The database file is tightened FIRST: SQLite derives sidecar
-        // permissions from the main file's mode, so everything created later
-        // inherits owner-only.
-        try {
-            chmodSync(filePath, 0o600);
-        }
-        catch (error) {
-            // A database that cannot be tightened must not be used: conversation
-            // bodies would stay readable by other local users for the daemon's
-            // whole lifetime, silently.
-            if (error.code !== 'ENOENT') {
-                throw error;
-            }
-        }
-        // WAL, not the default DELETE journal: DELETE mode recreates a
-        // rollback journal on EVERY write, which a one-time chmod could never
-        // cover in a traversable caller-supplied directory. WAL keeps one
-        // persistent sidecar pair per connection — forced into existence here
-        // (the user_version pragma is a real page-one write) so the loop
-        // below covers them for the connection's whole lifetime.
-        this.db.exec('PRAGMA journal_mode = WAL');
-        // A busy timeout, because this file has a second writer: `stratus
-        // schedules cancel` opens its own connection to the schedules table
-        // living here, and WAL serializes writers file-wide — a session save
-        // racing that delete would otherwise throw `database is locked` rather
-        // than wait its brief turn.
-        this.db.exec('PRAGMA busy_timeout = 5000');
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS sessions (
-        id TEXT PRIMARY KEY,
-        agent_id TEXT NOT NULL,
-        status TEXT NOT NULL,
-        body TEXT NOT NULL,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL
-      )
-    `);
-        this.db.exec('PRAGMA user_version = 0');
-        for (const sensitive of [filePath, `${filePath}-wal`, `${filePath}-shm`, `${filePath}-journal`]) {
-            try {
-                chmodSync(sensitive, 0o600);
-            }
-            catch (error) {
-                // A sidecar that does not exist has nothing to tighten; anything
-                // else means session data stays readable — refuse to run over it.
-                if (error.code !== 'ENOENT') {
-                    throw error;
-                }
-            }
-        }
-    }
-    async create(input) {
-        const now = new Date().toISOString();
-        const session = { ...input, createdAt: now, updatedAt: now };
-        this.db
-            .prepare('INSERT OR REPLACE INTO sessions (id, agent_id, status, body, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)')
-            .run(session.id, session.agent.id, session.status, JSON.stringify(session), session.createdAt, session.updatedAt);
-        return session;
-    }
-    async get(id) {
-        const row = this.db.prepare('SELECT body FROM sessions WHERE id = ?').get(id);
-        return row ? JSON.parse(row.body) : undefined;
-    }
-    async save(session) {
-        const updated = { ...session, updatedAt: new Date().toISOString() };
-        this.db
-            .prepare('INSERT OR REPLACE INTO sessions (id, agent_id, status, body, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)')
-            .run(updated.id, updated.agent.id, updated.status, JSON.stringify(updated), updated.createdAt, updated.updatedAt);
-    }
-    /**
-     * Session ids in a state, oldest first — the index a restarting daemon
-     * sweeps for turns parked on a human. The `status` column carries it, so
-     * no conversation body is deserialized to answer the question.
-     */
-    async listIdsByStatus(status) {
-        const rows = this.db
-            .prepare('SELECT id FROM sessions WHERE status = ? ORDER BY updated_at ASC')
-            .all(status);
-        return rows.map((row) => row.id);
-    }
-    /**
-     * When each agent last did anything, and how many of its sessions are live
-     * right now.
-     *
-     * One aggregate over the indexed columns — no conversation body is
-     * deserialized, for the same reason `listIdsByStatus` returns ids: a
-     * roster view asks this on every load, and it must not cost a JSON parse
-     * per session to answer.
-     *
-     * Both halves are needed and neither is sufficient. `lastActiveAt` alone
-     * reads a turn parked on a human as idle, because the save that recorded
-     * the park is the last thing that touched the row — and a turn waiting
-     * twenty minutes on an approval is exactly when someone wants to see the
-     * agent lit. `activeSessions` alone loses an agent that finished a moment
-     * ago. The caller decides what window counts as "recent"; a daemon that
-     * baked one in would need upgrading to change it.
-     */
-    /**
-     * How many sessions are in each state.
-     *
-     * A grouped count, not a listing that gets counted. The table grows for the
-     * life of an install and a health endpoint is polled, so materialising one
-     * object per historical session to produce five numbers gets steadily
-     * slower at exactly the thing meant to report that the daemon is fine.
-     */
-    countByStatus() {
-        const rows = this.db
-            .prepare('SELECT status, COUNT(*) AS total FROM sessions GROUP BY status')
-            .all();
-        const counts = {};
-        for (const row of rows) {
-            counts[row.status] = Number(row.total);
-        }
-        return counts;
-    }
-    lastActivityByAgent() {
-        const rows = this.db
-            .prepare(`
-        SELECT agent_id,
-               MAX(updated_at) AS last_active_at,
-               SUM(CASE WHEN status IN ('running', 'pending_approval') THEN 1 ELSE 0 END) AS active_sessions
-        FROM sessions
-        GROUP BY agent_id
-      `)
-            .all();
-        const activity = {};
-        for (const row of rows) {
-            activity[row.agent_id] = {
-                lastActiveAt: row.last_active_at,
-                activeSessions: Number(row.active_sessions),
-            };
-        }
-        return activity;
-    }
-    /**
-     * Newest-first session listing for one agent (or all agents).
-     *
-     * `limit` is not decoration: this table grows for the life of an install,
-     * and a surface that renders "recent conversations" would otherwise pull
-     * every session anyone has ever had to show ten of them.
-     */
-    list(agentId, limit) {
-        // -1 is SQLite's "no limit", so one prepared statement serves both cases
-        // rather than four.
-        const bound = limit !== undefined && Number.isInteger(limit) && limit >= 0 ? limit : -1;
-        const rows = (agentId
-            ? this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC LIMIT ?').all(agentId, bound)
-            : this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions ORDER BY updated_at DESC LIMIT ?').all(bound));
-        return rows.map((row) => ({
-            id: row.id,
-            agentId: row.agent_id,
-            status: row.status,
-            createdAt: row.created_at,
-            updatedAt: row.updated_at,
-        }));
-    }
-    close() {
-        this.db.close();
-    }
-}
 /**
  * A soul's provider/model pins, and the daemon-wide defaults they demote.
  *
@@ -288,6 +106,8 @@ export const ROLLED_OVER_FROM_METADATA_KEY = 'rolledOverFrom';
 export const ROLLED_OVER_TO_METADATA_KEY = 'rolledOverTo';
 /** The segment a rollover mints into the archived transcript's id. */
 export const ROLLED_OVER_SESSION_ID_MARKER = ':rolledover:';
+/** Where the session's tool calls ran: `local-command`, or a contributed executor's registered name. */
+export const EXECUTOR_METADATA_KEY = 'executor';
 export const RESERVED_SESSION_METADATA_KEYS = [
     PENDING_APPROVAL_METADATA_KEY,
     FALLBACK_ACTIVE_METADATA_KEY,
@@ -302,6 +122,17 @@ export const RESERVED_SESSION_METADATA_KEYS = [
     SESSION_TAINTED_BY_METADATA_KEY,
     ROLLED_OVER_FROM_METADATA_KEY,
     ROLLED_OVER_TO_METADATA_KEY,
+    // Which executor ran the turn's tool calls is the daemon's record of
+    // where a command ran, and the one audit question a caller must not be
+    // able to answer for it.
+    EXECUTOR_METADATA_KEY,
+    // The context floor is an index into a specific transcript, so it means
+    // nothing next to a different one. Reserved for both halves of that: a
+    // caller cannot seed it, and a rollover drops it with the transcript it
+    // indexed — otherwise the fresh session inherits an absolute floor over
+    // no messages and, once it grows past that index, silently stops sending
+    // its own earliest turns, with no overflow and no trim event to say so.
+    CONTEXT_FLOOR_METADATA_KEY,
 ];
 /**
  * The first reserved key `metadata` carries, or undefined when it carries
@@ -326,18 +157,39 @@ export const createGateway = (options = {}) => {
     const bus = new EventBus({
         onError: (error) => warn(`event handler failed: ${error instanceof Error ? error.message : String(error)}`),
     });
-    // The default database lives in the gateway-owned ~/.stratus, which is
-    // tightened to owner-only; a caller-supplied path may sit in a shared
+    // The default state directory is the gateway-owned ~/.stratus, which is
+    // tightened to owner-only; a caller-supplied one may sit in a shared
     // directory that must not be chmodded from under other processes.
-    const sessionDbPath = options.sessionDbPath ?? defaultSessionDbPath(env);
-    const store = options.sessionDbPath
-        ? new SqliteSessionStore(sessionDbPath)
-        : new SqliteSessionStore(sessionDbPath, { ownedDirectory: true });
-    const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(env)));
+    const stateDir = options.stateDir ?? stratusHomePath(env);
+    const store = new ShardedSessionStore({
+        stateDir,
+        ...(options.stateDir ? {} : { ownedDirectory: true }),
+    });
+    // The built-in store, behind a route that can change its mind: the memory
+    // tools and every runner are built before a plugin has loaded, so the
+    // store they hold is the one that answers *per call* with whichever was
+    // selected once the plugins are up. Per call, not per start, is also
+    // what keeps a contributed store per-agent-resolvable rather than
+    // process-global.
+    const fileMemory = createHomeMemoryStore(env);
+    let selectedMemory = fileMemory;
+    const memory = createRoutedMemoryStore(() => selectedMemory);
+    let selectedExecutor;
+    // What loaded plugins contributed besides tools and skills. The loader
+    // commits into these; the gateway reads them by name — a provider when a
+    // runner is built, the executor and memory store once at start, the
+    // channels when serving begins.
+    const providerContributions = new ContributionRegistry();
+    const channelContributions = new ChannelRegistry();
+    for (const claim of options.hostChannelClaims ?? []) {
+        channelContributions.claim(claim.kind, claim.agents);
+    }
+    const memoryContributions = new ContributionRegistry();
+    const executorContributions = new ContributionRegistry();
     // ---- schedules ----------------------------------------------------------
     // The same database sessions live in — one file to back up — through the
     // schedule store's own connection (see its docs for why).
-    const scheduleStore = new SqliteScheduleStore(sessionDbPath);
+    const scheduleStore = new SqliteScheduleStore(fleetDbIn(stateDir));
     /**
      * The write side of an addressable destination, through whichever
      * started channel serves its kind. Resolution happens per call against
@@ -346,7 +198,31 @@ export const createGateway = (options = {}) => {
      * both callers (schedule creation, `message.send`) hear why.
      */
     const outboundFor = async (agentId, destination) => {
-        const adapter = startedChannels.find((candidate) => candidate.name === destination.channel && candidate.resolveOutbound);
+        const candidates = startedChannels.filter((candidate) => candidate.name === destination.channel && candidate.resolveOutbound);
+        // One kind may be served by several adapters carrying disjoint
+        // agents — two plugins, or the host's adapter beside a plugin's — and
+        // the one that speaks for this agent is the one whose claims include
+        // it: a contribution's agent list, or the host's declared claims for
+        // an adapter no plugin contributed. A host that declared no claims for
+        // the kind left its adapter unclaimed, and an unclaimed adapter speaks
+        // for anyone, as the single host adapter always did. A claim miss is
+        // a refusal, never the first adapter that happens to be running: that
+        // adapter posts under another agent's transport identity, and it is
+        // exactly what a failed start of the right adapter would leave behind.
+        const contributed = channelContributions.list();
+        const hostClaims = (options.hostChannelClaims ?? []).filter((claim) => claim.kind === destination.channel);
+        const carries = (candidate) => {
+            const entry = contributed.find((contribution) => contribution.adapter === candidate);
+            if (entry) {
+                return entry.agents.includes(agentId);
+            }
+            return hostClaims.length === 0 || hostClaims.some((claim) => claim.agents.includes(agentId));
+        };
+        const adapter = candidates.find(carries);
+        if (!adapter?.resolveOutbound && candidates.length > 0) {
+            throw new Error(`No running '${destination.channel}' channel carries agent ${agentId} — `
+                + `the running ${destination.channel} adapters carry other agents, so a message from ${agentId} has no transport identity to post under.`);
+        }
         if (!adapter?.resolveOutbound) {
             throw new Error(`No running channel can deliver to '${destination.channel}' destinations — `
                 + (startedChannels.length === 0
@@ -656,6 +532,24 @@ export const createGateway = (options = {}) => {
         registry.register(source.definition);
         sources.set(source.definition.id, source);
     };
+    /**
+     * An id already registered that would open `agentId`'s state directory
+     * while being a different id — `ava` when asked about `Ava`, on the
+     * filesystems that fold them together.
+     *
+     * `foldedAgentId` owns which pairs those are. What this adds is the
+     * "already registered" half, for the one registration that does not come
+     * through `loadRosterSouls` and so was never folded against anything.
+     */
+    const stateDirectoryPeer = (agentId) => {
+        const folded = foldedAgentId(agentId);
+        for (const other of sources.keys()) {
+            if (other !== agentId && foldedAgentId(other) === folded) {
+                return other;
+            }
+        }
+        return undefined;
+    };
     /**
      * The agent an agentId-less dispatch routes to: the configured default
      * soul when one is set (what `stratus setup` writes to config.json),
@@ -666,9 +560,27 @@ export const createGateway = (options = {}) => {
      * built-in definition.
      */
     let lastDefaultAgentId;
+    /**
+     * What the last default resolution read, for the roster load to judge
+     * — the soul is re-read on every resolution, so a `tools:` key removed
+     * after startup is seen here, where the registered source would still
+     * carry the old definition until the next dispatch refreshes it.
+     */
+    let lastDefaultResolved;
     // The last successfully loaded config snapshot, serving dispatches while
     // the file on disk is temporarily broken (an operator mid-edit).
     let lastGoodConfigSnapshot;
+    /**
+     * Said at load, because the allowlist fails open: `tools` omitted is
+     * every registered tool, the opposite of what `skills` and `credentials`
+     * do when omitted, and a soul that never wrote the key holds `shell.run`
+     * the moment that plugin is enabled. The built-in agent is exempt — it
+     * has no file to add the key to.
+     */
+    const warnNoToolsList = (agentId, soulPath) => {
+        warn(`agent ${agentId} has no tools: list, so it may call every tool this daemon loads — `
+            + `add tools: [...] to ${soulPath} to say which`);
+    };
     const defaultAgentId = async () => {
         // Identity only — never full runtime resolution: credential checks do
         // not belong here, or a daemon default provider without installed keys
@@ -691,9 +603,33 @@ export const createGateway = (options = {}) => {
             // now the cached answer too, so a later transient read failure
             // cannot resurrect the retired soul's identity.
             lastDefaultAgentId = DEFAULT_STRATUS_AGENT.id;
+            lastDefaultResolved = undefined;
             return DEFAULT_STRATUS_AGENT.id;
         }
         const id = resolved.soul.agent.id;
+        // The roster refuses two *souls* whose ids name one state directory,
+        // but this soul never went through it: a config-only default is
+        // resolved here, by path, and registered by exact id. So `Ava` in
+        // config beside `ava` on the roster — or `Stratus` beside the built-in
+        // — passed as two agents sharing one `agents/<id>/`, which is one
+        // `whitelist.json` and therefore one agent acting on the other's
+        // unattended grants.
+        //
+        // Warned and dropped rather than thrown: this runs on every
+        // agentId-less dispatch, and a configuration mistake must not turn
+        // every such turn into an error. Dropping routes to the built-in,
+        // which is the documented answer when there is no usable default, and
+        // leaves the colliding agent serving from its own directory alone.
+        const peer = stateDirectoryPeer(id);
+        if (peer !== undefined) {
+            warn(`the configured default soul at ${resolved.path} declares the agent id ${id}, which names the same `
+                + `state directory as ${peer} — sessions, memories, and the grants that say what may run unattended. `
+                + `Ignoring it and routing to ${DEFAULT_STRATUS_AGENT.id}; rename one of the two ids.`);
+            lastDefaultAgentId = DEFAULT_STRATUS_AGENT.id;
+            lastDefaultResolved = undefined;
+            return DEFAULT_STRATUS_AGENT.id;
+        }
+        lastDefaultResolved = resolved;
         // The normal setup layout has the default soul in ~/.stratus/agents
         // too: keep the roster registration — its soulPath drives per-dispatch
         // refresh. A config-only soul registers with the path it resolved
@@ -739,6 +675,9 @@ export const createGateway = (options = {}) => {
         // no correct winner, and refusing to serve beats letting sort order
         // decide whose sessions, memory, and credentials an agent inherits.
         const entries = await loadRosterSouls(env, warn);
+        // Which souls this pass named for having no tools: list, so the
+        // configured default is not named twice when it is one of them.
+        const namedThisPass = new Set();
         for (const entry of entries) {
             // Against ids claimed by THIS pass, not by any earlier one: a reload
             // must be free to re-register the agent it just re-read, and only the
@@ -752,12 +691,28 @@ export const createGateway = (options = {}) => {
                 continue;
             }
             registerFresh({ definition: entry.soul.agent, soulPath: entry.path, soul: entry.soul });
+            if (entry.soul.agent.tools === undefined) {
+                warnNoToolsList(entry.soul.agent.id, entry.path);
+                namedThisPass.add(entry.path);
+            }
         }
         // The configured default soul is part of the roster too — it is what
         // an agentId-less dispatch answers as. It may live outside the agents
         // directory, and it survives a read failure by name, so what it
         // resolves to is kept whether or not this pass re-registered it.
-        seen.add(await defaultAgentId());
+        const defaultId = await defaultAgentId();
+        seen.add(defaultId);
+        // The same notice for a default soul that lives outside the agents
+        // directory — the one path into the roster that skips the loop above
+        // — on every load, judged on what the resolution just read rather
+        // than on the registered source, so a key removed after startup is
+        // reported at the next reload. A roster-backed default was named by
+        // the loop, and is not named twice.
+        if (lastDefaultResolved !== undefined
+            && lastDefaultResolved.soul.agent.tools === undefined
+            && !namedThisPass.has(lastDefaultResolved.path)) {
+            warnNoToolsList(defaultId, lastDefaultResolved.path);
+        }
         for (const id of [...sources.keys()]) {
             if (!seen.has(id)) {
                 sources.delete(id);
@@ -932,6 +887,7 @@ export const createGateway = (options = {}) => {
     tools.register(createRememberTool(memory));
     tools.register(createRecallTool(memory));
     tools.register(createForgetTool(memory));
+    tools.register(createPinTool(memory));
     // Registered here rather than left to the first runner, so `tools()`
     // lists the reader before anything dispatches. The allowlist resolver
     // mirrors the runner's own sourcing — the definition travelling with the
@@ -995,11 +951,14 @@ export const createGateway = (options = {}) => {
         // The sticky-fallback switch is durable the moment it happens, not
         // when the turn's next save lands — a daemon killed mid-fallback
         // must not retry the primary on restart.
-        (session) => store.save(session));
+        (session) => store.save(session), providerContributions);
         const runner = new AgentRunner({
             provider,
             tools,
-            executor: createLocalCommandExecutor(),
+            // Runners are built on dispatch, after the plugins loaded and the
+            // selection below ran, so a contributed executor is in place for
+            // the first turn.
+            executor: selectedExecutor ?? createLocalCommandExecutor(),
             ...(approvals ? { approvals } : {}),
             store,
             bus,
@@ -1055,13 +1014,23 @@ export const createGateway = (options = {}) => {
     // ten-minute timer instead of the idle timeout the operator set.
     (fallback.provider === 'anthropic' && Boolean(fallback.apiKey || fallback.authToken))
         // The codex harness streams item snapshots in every auth mode.
-        || fallback.provider === 'codex';
+        || fallback.provider === 'codex'
+        // A contributed fallback says for itself, exactly as a contributed
+        // primary does below; a session that switched to one must not lose
+        // the watchdog the plugin declared it could have.
+        || (isRegisteredProviderName(fallback.provider)
+            && providerContributions.get(registeredProviderNameOf(fallback.provider))?.streams === true);
     const streamsDeltas = (config) => 
     // Both Anthropic modes stream now: an API key through the Messages
     // API, a subscription token through the Agent SDK's partial messages —
-    // and the codex harness streams item snapshots in every auth mode.
+    // and the codex harness streams item snapshots in every auth mode. A
+    // contributed provider says for itself, and one that did not say is
+    // read as not streaming: a watchdog armed over a silent-until-done
+    // call would abort every long turn.
     (config.provider === 'anthropic' && Boolean(config.apiKey || config.authToken))
-        || config.provider === 'codex';
+        || config.provider === 'codex'
+        || (isRegisteredProviderName(config.provider)
+            && providerContributions.get(registeredProviderNameOf(config.provider))?.streams === true);
     /**
      * Progress-based abort, armed only while the turn is actually awaiting a
      * streaming provider — the one phase where silence means a stall. Tool
@@ -1388,11 +1357,21 @@ export const createGateway = (options = {}) => {
         }
         const config = await runtimeForAgent(source);
         const runner = runnerFor(config);
+        // Which executor the turn's tool calls run through — the built-in
+        // under the name `stratus run` has always recorded, a contributed one
+        // under its registered name — so a transcript says where a command
+        // ran, not only which model asked for it.
+        const executorRecord = selectedExecutor && options.executor !== undefined ? options.executor : 'local-command';
         const metadata = {
-            ...(config.provider === 'demo'
-                ? { provider: 'demo' }
-                : { provider: config.provider, model: config.model }),
+            provider: config.provider,
+            // A contributed provider may leave the model to its own default, in
+            // which case there is none to record.
+            ...(config.provider !== 'demo' && config.model !== undefined ? { model: config.model } : {}),
             ...input.metadata,
+            // After the caller's metadata, and reserved besides: a dispatch that
+            // could write it could make a transcript claim a sandbox ran what
+            // the host ran.
+            [EXECUTOR_METADATA_KEY]: executorRecord,
         };
         if (existing && existing.agent.id !== agent.id) {
             throw new Error(`Session ${input.sessionId} belongs to agent ${existing.agent.id}, not ${agent.id} — sessions never cross agent identities.`);
@@ -1424,6 +1403,13 @@ export const createGateway = (options = {}) => {
                 if (isDelegatedSession(existing) && existing.metadata) {
                     existing.metadata = withoutDelegation(existing.metadata);
                 }
+                // The executor record follows the daemon, not the session's first
+                // turn: a restart that selected another executor runs this turn's
+                // commands there, and a session from before the record existed
+                // gets one now rather than never.
+                if (existing.metadata?.[EXECUTOR_METADATA_KEY] !== executorRecord) {
+                    existing.metadata = { ...existing.metadata, [EXECUTOR_METADATA_KEY]: executorRecord };
+                }
                 await store.save(existing);
                 // The turn's metadata rides along for the sender's trust: without
                 // it a resumed turn has no way to say who sent it, and a stranger
@@ -1853,11 +1839,20 @@ export const createGateway = (options = {}) => {
             tools,
             skills: skillCatalog,
             bus,
+            providers: providerContributions,
+            channels: channelContributions,
+            memory: memoryContributions,
+            executors: executorContributions,
+            // The host-owned path for a channel's transport secrets: the same
+            // `channels.<kind>.<agentId>` namespace Slack's tokens live in, read
+            // for the kind the plugin declared, and never through the
+            // agent-scoped resolver below.
+            channelSecrets: (kind) => loadChannelTransportSecrets(env, kind),
             // The file-backed resolver, so a plugin needing a key reaches the
             // *calling* agent's — its allowlist checked, its own entry before the
             // fleet's shared one.
             credentials: createFileCredentialResolver(env),
-            workspaceRoot: workspacesDirPath(env),
+            workspaces: createAgentWorkspaces(env),
             // The structured log, so a plugin's lifecycle lines — an MCP server
             // that dropped, a reconnect that failed — are in `stratus logs` and
             // not only on a stderr the service manager owns.
@@ -1870,6 +1865,10 @@ export const createGateway = (options = {}) => {
             const contributed = [
                 ...plugin.tools.map((tool) => `${tool.name} (${tool.risk})`),
                 ...plugin.skills.map((skill) => `skill ${skill.id}`),
+                ...plugin.contributions.providers.map((name) => `provider ${name}`),
+                ...plugin.contributions.channels.map((channel) => `channel ${channel.kind} for ${channel.agents.join(', ') || 'no agent'}`),
+                ...plugin.contributions.memory.map((name) => `memory store ${name}`),
+                ...plugin.contributions.executors.map((name) => `executor ${name}`),
             ];
             log(`plugin ${plugin.package} loaded — ${contributed.join(', ') || 'no tools'}`);
         }
@@ -1877,6 +1876,43 @@ export const createGateway = (options = {}) => {
             warn(`plugin ${failure.package} did not load: ${failure.reason}`);
         }
     };
+    /**
+     * Which package registered a name, for the log line and the refusal.
+     * From the load records rather than a second map: they are the record.
+     */
+    const contributorOf = (kind, name) => loadedPlugins.find((plugin) => plugin.contributions[kind].includes(name))?.package;
+    /**
+     * Put the operator's executor and memory-store selections into effect,
+     * or refuse to start. Refuse, not warn: the built-in executor runs
+     * commands on this host, and an operator who selected a sandbox that
+     * failed to load must not find their agents on the host anyway; a
+     * memory store the same, one write later. A name no plugin registered
+     * is named with what is, so a typo reads as one.
+     */
+    const applyContributionSelections = () => {
+        const executorName = options.executor;
+        if (executorName !== undefined && executorName !== BUILTIN_EXECUTOR_NAME) {
+            const contribution = executorContributions.get(executorName);
+            if (!contribution) {
+                throw new Error(`The config selects executor ${executorName}, which no loaded plugin registers`
+                    + (executorContributions.names().length > 0 ? ` (registered: ${executorContributions.names().join(', ')})` : '')
+                    + `. Enable the plugin that contributes it, or set executor to ${BUILTIN_EXECUTOR_NAME}.`);
+            }
+            selectedExecutor = contribution.executor;
+            log(`executor ${executorName} selected, from ${contributorOf('executors', executorName) ?? 'a plugin'}`);
+        }
+        const memoryName = options.memoryStore;
+        if (memoryName !== undefined && memoryName !== BUILTIN_MEMORY_STORE_NAME) {
+            const contribution = memoryContributions.get(memoryName);
+            if (!contribution) {
+                throw new Error(`The config selects memoryStore ${memoryName}, which no loaded plugin registers`
+                    + (memoryContributions.names().length > 0 ? ` (registered: ${memoryContributions.names().join(', ')})` : '')
+                    + `. Enable the plugin that contributes it, or set memoryStore to ${BUILTIN_MEMORY_STORE_NAME}.`);
+            }
+            selectedMemory = contribution.store;
+            log(`memory store ${memoryName} selected, from ${contributorOf('memory', memoryName) ?? 'a plugin'}`);
+        }
+    };
     /**
      * Load the operator's `~/.stratus/skills/` into the catalog. Before the
      * plugins, deliberately: an operator's bare id outranks a plugin's bare
@@ -1907,6 +1943,42 @@ export const createGateway = (options = {}) => {
         // it is synchronous for the same reason: the check is a file read, and
         // an async one in that stretch failed CI's restart tests twice.
         assertStateCompatible(env);
+        // A home whose pre-15a state has not been moved yet is refused rather
+        // than served, because serving it is the quiet failure: the stores open
+        // on the new paths, find nothing, and the fleet starts writing a second
+        // population beside every session, schedule, and grant it already had.
+        //
+        // Refused rather than migrated, even though this process is the daemon:
+        // the move needs the home to *itself*, and holding the claim is
+        // something the host does (`claimHome`) — a gateway that migrated on
+        // its own would be asserting an exclusivity nobody gave it. `stratus
+        // serve` runs the migration before it ever gets here, so this only
+        // fires for a host wiring the gateway up itself.
+        // Against `stateDir` — the directory the stores were actually opened
+        // on — rather than the one `env` names. A host that pointed them
+        // somewhere else would otherwise be told its home is fine while the
+        // sessions it is stranding sit in the directory it chose.
+        if (await hasBracketedLegacyStateIn(stateDir)) {
+            throw new Error(`${stateDir} still holds pre-per-agent state (a shared sessions.db, or an <id>.whitelist.json beside the souls), `
+                + 'and serving it now would strand every session, schedule, and grant in it. '
+                + (stateDir === stratusHomePath(env)
+                    ? 'Run `stratus update`, or — for a host starting the gateway itself — claim the home with `claimHome` and '
+                        + 'await `runStateMigrations(env, { exclusive: true })` from @stratusagent/state before calling start().'
+                    : 'This is a state directory of your own choosing, which `stratus update` does not migrate: move that state '
+                        + 'into the layout yourself, or point `stateDir` at a directory that has been through it.'));
+        }
+        // Before the sweeps below read a single session id: the index and the
+        // per-agent stores are two durable writes where the shared database had
+        // one primary key, and a crash between them left them disagreeing.
+        // Reconciling here is what makes that disagreement resolve one way —
+        // a claim with no conversation released, a conversation the index lost
+        // re-indexed — rather than leaving an abandoned turn unreachable by the
+        // sweep that was supposed to fail it honestly.
+        const reconciled = await store.reconcile();
+        if (reconciled.released.length > 0 || reconciled.reindexed.length > 0) {
+            log(`session index reconciled: ${reconciled.reindexed.length} re-indexed, `
+                + `${reconciled.released.length} claim(s) released`);
+        }
         await loadRoster();
         const named = registry.list().map((agent) => agent.name).join(', ');
         log(`stratusd ready — ${registry.list().length} agent(s): ${named}`);
@@ -1921,8 +1993,14 @@ export const createGateway = (options = {}) => {
         const orphaned = await listOrphanedDelegations();
         // Channels come up after the roster so their first inbound message
         // already has agents to dispatch to. One failing adapter must not
-        // keep the rest (or the gateway) down.
-        for (const adapter of options.channels ?? []) {
+        // keep the rest (or the gateway) down. The host's adapters first, then
+        // the plugins' in load order — the `plugins` block's order, which is
+        // the one an operator can read.
+        const adapters = [
+            ...(options.channels ?? []),
+            ...channelContributions.list().map((contribution) => contribution.adapter),
+        ];
+        for (const adapter of adapters) {
             try {
                 await adapter.start(gateway);
                 startedChannels.push(adapter);
@@ -2138,6 +2216,13 @@ export const createGateway = (options = {}) => {
         async start() {
             try {
                 await migrateLegacyMemory(env);
+                // And anything still in the shared `memory.jsonl` a pre-15a build
+                // left (or a still-running one of those recreated). Not a
+                // migration and never stamped — see `drainSharedMemory`.
+                const drained = await drainSharedMemory(env);
+                if (drained) {
+                    log(`shared memory drained: ${drained}`);
+                }
                 // Before the roster and before channels: a turn must never arrive
                 // for an agent whose soul lists a tool the daemon has not
                 // registered yet, which would refuse the call as "not permitted"
@@ -2146,6 +2231,7 @@ export const createGateway = (options = {}) => {
                 // startSkills).
                 await startSkills();
                 await startPlugins();
+                applyContributionSelections();
                 await startServing();
             }
             catch (error) {
@@ -2455,6 +2541,10 @@ export const createGateway = (options = {}) => {
                         path: skill.path,
                     };
                 }),
+                providers: plugin.contributions.providers,
+                channels: plugin.contributions.channels,
+                memory: plugin.contributions.memory,
+                executors: plugin.contributions.executors,
             }));
             const failed = pluginFailures.map((failure) => ({
                 package: failure.package,
@@ -2462,6 +2552,10 @@ export const createGateway = (options = {}) => {
             }));
             return [...loaded, ...failed];
         },
+        providers() {
+            const contributed = loadedPlugins.flatMap((plugin) => plugin.contributions.providers.map((name) => ({ name, package: plugin.package })));
+            return [...BUILTIN_PROVIDER_NAMES.map((name) => ({ name })), ...contributed];
+        },
         async servedSouls() {
             // From the registry rather than `sources` directly, so the order and
             // the membership are the roster's own — one entry per agent `agents()`