@prohost/cli 0.1.0 → 0.2.0

package/dist/agent/pair.js

@@ -24,6 +24,25 @@ function isUuid(value) {
 function baseFromMcpUrl(mcpUrl, fallback) {
     return mcpUrl.endsWith('/mcp') ? mcpUrl.slice(0, -'/mcp'.length) : fallback;
 }
+/**
+ * The websocket URL the server told us to use, or ``undefined``.
+ *
+ * ``undefined`` covers both "this server predates the field" and "the value is
+ * not a websocket URL". A cosmetic bad value must not fail a redeem — the code
+ * is already spent by the time we read the body — so the caller falls back to
+ * {@link DEFAULT_WS_URL} and says so.
+ */
+function serverWsUrl(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    try {
+        const protocol = new URL(value).protocol;
+        return protocol === 'ws:' || protocol === 'wss:' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Redeem ``code`` and persist the resulting credentials.
  *
@@ -33,7 +52,6 @@ export async function runPair(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const onLine = options.onLine ?? ((line) => process.stdout.write(`${line}\n`));
     const baseUrl = (options.baseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
-    const wsUrl = options.wsUrl ?? DEFAULT_WS_URL;
     if (options.webhookUrl && !options.webhookUrl.startsWith('https://')) {
         throw new PairError('--webhook-url must be an https:// URL');
     }
@@ -111,6 +129,16 @@ export async function runPair(options) {
                     'redeem and has been removed.'
                 : '  Nothing was saved.'));
     }
+    // Where the websocket host comes from, in order:
+    //
+    //   1. `--url` / `$PROHOST_WS_URL` — an explicit operator override, and the
+    //      escape hatch that let the field work around 0.1.0's bad default.
+    //   2. The server's `ws_url`, derived server-side from the same setting as
+    //      `mcp_url` (`shared/agents/connections.py::pairing_endpoints`). This is
+    //      the normal path, and the reason a host move no longer needs a release.
+    //   3. `DEFAULT_WS_URL`, for a server that predates the field.
+    const fromServer = serverWsUrl(body.ws_url);
+    const wsUrl = options.wsUrl ?? fromServer ?? DEFAULT_WS_URL;
     const credentials = {
         version: CREDENTIALS_VERSION,
         base_url: baseFromMcpUrl(body.mcp_url ?? '', baseUrl),
@@ -129,10 +157,22 @@ export async function runPair(options) {
     onLine(`  API key      ${maskSecret(body.api_key)}  (stored, never printed in full)`);
     onLine(`  Credentials  ${file}  (chmod 600)`);
     onLine(`  MCP URL      ${body.mcp_url}`);
+    // Printed because 0.1.0's wrong websocket host was invisible here: pairing
+    // reported success and the mismatch only surfaced as a 403 reconnect loop in
+    // a different command. Showing it makes a bad host obvious at pair time.
+    onLine(`  Stream URL   ${credentials.ws_url}`);
     onLine(`  Events       ${credentials.events.join(', ') || '(none)'}`);
     onLine(`  Delivery     ${credentials.stream_only
         ? 'stream-only — events arrive over the websocket, nothing is POSTed to you'
         : `over the websocket, and POSTed to ${options.webhookUrl ?? 'your registered endpoint'}`}`);
+    if (body.ws_url && !fromServer && !options.wsUrl) {
+        // Present but not a ws:// or wss:// URL. Don't fail the redeem over it —
+        // the code is spent — but don't let the fallback look like the server's
+        // answer either.
+        onLine('');
+        onLine(`  ! The server reported an unusable stream URL (${JSON.stringify(body.ws_url)}).`);
+        onLine(`    Using ${DEFAULT_WS_URL} instead — override with --url if that is wrong.`);
+    }
     if (!credentials.webhook_secret) {
         // Without a secret the runner can't prove an event came from ProhostAI,
         // and a run event makes this machine execute a command — so it refuses to

package/dist/agent/prompt.d.ts

@@ -10,8 +10,23 @@ import type { AgentRunRequest } from './contract.js';
 export interface PromptContext {
     /** Display name of the paired AI employee, e.g. "Ada". */
     agentName: string;
-    /** MCP endpoint the agent can use to act back into the account. */
-    mcpUrl?: string;
+    /**
+     * MCP server name the run's tools are registered under, e.g. `prohost`.
+     *
+     * Set **only** when the harness actually wired those tools into this
+     * invocation. Naming tools the child cannot call is worse than naming
+     * nothing: the agent reports having looked something up when it did not.
+     */
+    mcpServerName?: string;
+    /**
+     * Tools are behind permission prompts this run (`--safe-tools`).
+     *
+     * Changes what is true, so it has to change what the prompt says. Gated, a
+     * tool needing approval will never run and the agent must plan around that.
+     * Ungated — the default — it can act, and telling it otherwise would make it
+     * decline work it is perfectly able to do.
+     */
+    toolsGated?: boolean;
 }
 /** Build the stdin prompt for one run. */
 export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;

package/dist/agent/prompt.js

@@ -6,6 +6,24 @@
  * a shell script that greps it. The reply contract is stated explicitly so an
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
+/**
+ * Render one line of thread history.
+ *
+ * The role is a parenthetical *qualifier* on a name, not a substitute for one:
+ * a row with a role and no author — which is what a system row like
+ * `{role: "event", text: "Reservation confirmed"}` looks like — reads as
+ * `event: …` rather than the nonsense `someone (event): …`.
+ */
+function renderMessage(message) {
+    const who = message.author ?? message.role ?? 'someone';
+    const role = message.author && message.role ? ` (${message.role})` : '';
+    const when = message.at ? `[${message.at}] ` : '';
+    return `${when}${who}${role}: ${message.text}`;
+}
+/** Render one remembered fact. */
+function renderMemory(memory) {
+    return memory.scope ? `- (${memory.scope}) ${memory.content}` : `- ${memory.content}`;
+}
 /** Build the stdin prompt for one run. */
 export function buildPrompt(run, context) {
     const name = run.agent_name ?? context.agentName;
@@ -42,12 +60,18 @@ export function buildPrompt(run, context) {
     // only handle the agent has on what was actually said.
     if (run.trigger_message_id)
         facts.push(`Comment/message id: ${run.trigger_message_id}`);
-    if (context.mcpUrl) {
-        facts.push(`ProhostAI MCP endpoint (for looking things up): ${context.mcpUrl}`);
-    }
     if (facts.length > 0) {
         lines.push('Context:', ...facts.map((f) => `- ${f}`), '');
     }
+    // Memories first, then the thread, then the message that woke the agent:
+    // oldest and most general context at the top, the thing being answered last
+    // and closest to the instruction.
+    if (run.memories?.length) {
+        lines.push('Things you remember (from earlier work in this workspace):', ...run.memories.map(renderMemory), '');
+    }
+    if (run.recent_messages?.length) {
+        lines.push('Conversation so far (oldest first):', ...run.recent_messages.map(renderMessage), '--- end of conversation history ---', '');
+    }
     if (run.trigger_text) {
         // The server caps this excerpt, so say so rather than let an agent assume
         // it has the whole message.
@@ -56,6 +80,34 @@ export function buildPrompt(run, context) {
     else {
         lines.push('The message text was not included in the event.', '');
     }
+    // An agent that doesn't know it is headless narrates as if it were mid-
+    // session — "let me connect to that", "I'll check once the tools load" —
+    // and that text is what gets posted to a customer, describing a lookup that
+    // never happened. Saying the shape of the invocation out loud is the cheapest
+    // fix; the alternative is a reply that is confidently wrong about its own
+    // capabilities.
+    lines.push('How you are running:', '- This is a single non-interactive turn. Nobody is at a terminal, so', context.toolsGated
+        ? '  any tool that would need approval will not run — plan around that\n' +
+            '  rather than asking for permission, which gets no answer.'
+        : '  nothing will stop to ask you for permission: your tools run as soon\n' +
+            '  as you call them. Do the work rather than proposing it — but that\n' +
+            '  also means a mistaken action happens for real, so check before you\n' +
+            '  change or delete anything.', '- Nothing about your access changes after this turn. Do not say a tool is', '  "connecting", "loading", or about to become available, and do not', '  promise to follow up.', "- State limits plainly. If you cannot look something up, say what you don't", '  know and answer with what you do — a short honest answer beats a', '  confident invented one.', 
+    // Deliberately does not list which domains are reachable. A paired
+    // credential holds a narrow, server-chosen scope set — the current default
+    // covers conversations, tasks, cleanings and approvals but NOT reservations
+    // or listings — and any list written here is a promise this CLI cannot
+    // keep across pairings or across changes to the default scopes. Naming
+    // domains the credential can't reach is the same failure as naming an MCP
+    // endpoint it can't call: the agent reports a lookup it never made.
+    context.mcpServerName
+        ? `- You have ProhostAI tools (mcp__${context.mcpServerName}__*). They are the sanctioned ` +
+            'way to look up workspace data, so use them rather than guessing. Your credential is ' +
+            'deliberately narrow and does not reach every part of the workspace: if a tool returns ' +
+            'a permission error, that is a real limit rather than a glitch — say what you could not ' +
+            'look up instead of retrying it or answering as if you had.'
+        : '- You have no ProhostAI tools in this run. Everything you know about this ' +
+            'workspace is what is written above.', '');
     // Postability is a separate question from what the run is about: a task run
     // has no comment route in the external API yet, so the agent must be told its
     // output won't be posted rather than left to assume it will.

package/dist/agent/run.d.ts

@@ -36,7 +36,19 @@ export interface AgentRunOptions {
     dryRun?: boolean;
     /** Execute runs whose signature could not be verified. Off by default. */
     allowUnverified?: boolean;
-    /** Working directory for the agent command. */
+    /**
+     * Gate the agent's tools behind permission prompts instead of bypassing them.
+     *
+     * Off by default: a paired brain is hired to act, and in print mode there is
+     * nobody to approve anything, so a gated agent silently declines to do the
+     * work. `agent run --safe-tools` turns this on. Claude Code only — no other
+     * `--exec` command is shaped at all.
+     */
+    safeTools?: boolean;
+    /**
+     * Working directory for the agent command. Defaults to
+     * ``$PROHOST_HOME/workspace`` — see {@link workspacePath} for why not "here".
+     */
     cwd?: string;
     onLine?: (line: string) => void;
     webSocketCtor?: typeof WebSocket;

package/dist/agent/run.js

@@ -20,10 +20,13 @@
 import os from 'node:os';
 import WebSocket from 'ws';
 import { completeRun, postReply } from './api.js';
+import { MCP_SERVER_NAME, claudeCommand, isClaudeExec, looksLikeResumeFailure, parseClaudeOutput, writeMcpConfig, } from './claude.js';
 import { EVENT_AGENT_RUN_REQUESTED, EVENT_MENTION_CREATED, EVENT_MESSAGE_TEAM_CHAT, eventData, parseRunRequest, } from './contract.js';
+import { ensureWorkspace, streamUrlFor, workspacePath } from './credentials.js';
 import { execAgent } from './exec.js';
 import { buildPrompt, replyFromStdout } from './prompt.js';
 import { RunStore } from './runstore.js';
+import { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.js';
@@ -84,34 +87,192 @@ async function completeWithRetry(api, path, outcome, log, sleep) {
     }
     return result;
 }
+/**
+ * Decide where the agent command runs.
+ *
+ * The default is a dedicated directory rather than the CLI's own cwd, because
+ * coding agents treat their working directory as configuration — a `CLAUDE.md`,
+ * a `.claude/settings.json` permission list, a project `.mcp.json`. Started
+ * from a checkout of some unrelated service (which is how this was first run in
+ * production), the agent picks up that repo's instructions and denials and
+ * answers a customer as if it were working on that codebase.
+ *
+ * A home directory we can't create in costs the isolation, not the run: fall
+ * back to inheriting the CLI's cwd and say what happened.
+ */
+function resolveWorkdir(options, log) {
+    if (options.cwd)
+        return options.cwd;
+    try {
+        return ensureWorkspace(options.env);
+    }
+    catch (err) {
+        log(`${timestamp()} ! could not create ${workspacePath(options.env)} ` +
+            `(${err instanceof Error ? err.message : String(err)}); running in the current directory ` +
+            'instead, which means the agent inherits any agent config it finds there');
+        return undefined;
+    }
+}
+/**
+ * Assemble the per-process runtime: workspace, session ledger, and — for Claude
+ * Code only — the MCP config that gives the agent tools.
+ *
+ * Every step here is allowed to fail without stopping the harness. An agent
+ * that answers from the prompt alone is the product as it shipped; refusing to
+ * start because a config file couldn't be written would be a regression
+ * dressed up as a safety check.
+ */
+function buildRuntime(options, log) {
+    const workdir = resolveWorkdir(options, log);
+    const sessions = SessionStore.load(options.env, log);
+    const claude = isClaudeExec(options.exec);
+    const skipPermissions = options.safeTools !== true;
+    if (!claude)
+        return { workdir, sessions, claude, skipPermissions };
+    let mcpConfigPath;
+    const mcpUrl = options.credentials.mcp_url;
+    if (mcpUrl) {
+        try {
+            mcpConfigPath = writeMcpConfig({
+                mcpUrl,
+                apiKey: options.credentials.api_key,
+                env: options.env,
+            });
+        }
+        catch (err) {
+            // Said out loud rather than swallowed: the visible symptom would
+            // otherwise be an agent that answers "I can't look that up", which reads
+            // like a model problem and sends someone to the wrong file.
+            log(`${timestamp()} ! could not write the MCP config ` +
+                `(${err instanceof Error ? err.message : String(err)}); the agent will run without ` +
+                'ProhostAI tools');
+        }
+    }
+    else {
+        log(`${timestamp()} ! this pairing carries no MCP endpoint; the agent will run without ProhostAI tools`);
+    }
+    log(`${timestamp()} ⚙ Claude Code detected — resuming a session per conversation` +
+        (mcpConfigPath ? `, ProhostAI tools wired in as ${MCP_SERVER_NAME}` : '') +
+        `${workdir ? ` (workspace: ${workdir})` : ''}`);
+    // Said out loud every start-up, not buried in --help. This is the line that
+    // tells an operator their machine will run tool calls, unprompted, on text
+    // written by someone else in their workspace.
+    log(skipPermissions
+        ? `${timestamp()} ⚠ tools run WITHOUT permission prompts ` +
+            '(--dangerously-skip-permissions). The agent acts as you, with your local ' +
+            'access, on instructions from your workspace. Use --safe-tools to gate them.'
+        : `${timestamp()} ⚙ --safe-tools: tools are permission-gated; anything needing ` +
+            'approval will not run (nobody is at a terminal to approve it).');
+    return { workdir, sessions, claude, mcpConfigPath, skipPermissions };
+}
+/**
+ * Run the agent command once and turn its output into a reply.
+ *
+ * The two branches are the whole point of the split: a plain command's stdout
+ * *is* the reply (the contract every other agent speaks), while Claude Code in
+ * print mode is asked for JSON so the harness can pull out the session id and
+ * tell a failed turn from a successful one. A plain command's behaviour here is
+ * byte-for-byte what it was before this function existed.
+ */
+async function runTurn(run, prompt, options, runtime, log) {
+    // `--timeout` is a ceiling on the run, not on each attempt: the retry below
+    // must not let one run take twice what the operator allowed. Both attempts
+    // share one deadline, which costs the retry nothing in practice — a rejected
+    // `--resume` fails in milliseconds, long before any of the budget is spent.
+    const budgetMs = options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
+    const startedAt = Date.now();
+    const remainingMs = () => budgetMs - (Date.now() - startedAt);
+    const exec = (command) => execAgent({
+        command,
+        prompt,
+        timeoutMs: remainingMs(),
+        cwd: runtime.workdir,
+        spawnImpl: options.spawnImpl,
+    });
+    // Wall clock for the whole turn, retry included — what the operator waited,
+    // rather than what the last attempt took.
+    const elapsed = () => Date.now() - startedAt;
+    const failure = (result) => ({
+        ok: false,
+        reason: result.error ??
+            (result.exitCode === null ? 'agent command did not run' : `agent command exited ${result.exitCode}`),
+        detail: result.stderr.trim().slice(-500),
+        durationMs: elapsed(),
+    });
+    if (!runtime.claude) {
+        const result = await exec(options.exec);
+        if (!result.ok)
+            return failure(result);
+        const reply = replyFromStdout(result.stdout);
+        return reply
+            ? { ok: true, reply, durationMs: elapsed() }
+            : { ok: false, reason: 'agent produced no output', durationMs: elapsed() };
+    }
+    // No session bookkeeping on a dry run. `--dry-run` promises to make no
+    // writes, and a resumed turn is a write: Claude Code records it in the
+    // transcript whether or not we post the reply, so remembering the session
+    // would leave the next *real* run continuing from an answer nobody saw.
+    const key = options.dryRun ? undefined : sessionKeyFor(run);
+    const sessionId = runtime.sessions.get(key);
+    const shape = { mcpConfigPath: runtime.mcpConfigPath, skipPermissions: runtime.skipPermissions };
+    let result = await exec(claudeCommand(options.exec, { ...shape, sessionId }));
+    // A remembered session may simply be gone — transcripts are cleaned up and
+    // the ledger can't know. One retry without it, because the alternative is a
+    // surface that fails every run forever over an optimisation.
+    if (!result.ok &&
+        sessionId &&
+        looksLikeResumeFailure(`${result.stderr}\n${result.stdout}`, sessionId) &&
+        // Skipped rather than squeezed into a token budget: a retry with no time
+        // left would be killed on the spot and reported as a timeout, which is a
+        // worse error message than the resume failure it replaced.
+        remainingMs() > 0) {
+        log(`    … session ${sessionId.slice(0, 12)} could not be resumed; starting a fresh one`);
+        runtime.sessions.forget(key);
+        result = await exec(claudeCommand(options.exec, shape));
+    }
+    if (!result.ok)
+        return failure(result);
+    const parsed = parseClaudeOutput(result.stdout);
+    // A denied tool is not an error the agent reports — the turn succeeds and the
+    // reply just quietly lacks whatever the tool would have found. Printing it is
+    // the difference between "the agent seems dumb" and "the agent asked for
+    // WebSearch and there was nobody to approve it".
+    if (parsed.denials.length > 0) {
+        log(`    ! tools the agent asked for and was refused: ${parsed.denials.join(', ')}`);
+    }
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            reason: 'the agent did not produce a usable reply',
+            detail: parsed.error,
+            durationMs: elapsed(),
+        };
+    }
+    return { ok: true, reply: parsed.text, durationMs: elapsed(), sessionId: parsed.sessionId };
+}
 /**
  * Handle one verified run end-to-end.
  *
  * Every path except a dry run — including every failure — calls the completion
  * endpoint before returning.
  */
-async function handleRun(run, options, api, log, sleep) {
+async function handleRun(run, options, runtime, api, log, sleep) {
     const label = `run ${run.run_id.slice(0, 12)}`;
     const surface = run.conversation_id ?? run.kind ?? 'no conversation';
     log(`${timestamp()} ▶ ${label} started (${surface})`);
     const prompt = buildPrompt(run, {
         agentName: options.credentials.agent?.name ?? 'your agent',
-        mcpUrl: options.credentials.mcp_url,
-    });
-    const result = await execAgent({
-        command: options.exec,
-        prompt,
-        timeoutMs: options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS,
-        cwd: options.cwd,
-        spawnImpl: options.spawnImpl,
+        // Named only when the tools are actually reachable from this invocation.
+        // Telling an agent about an endpoint it has no client for is what produced
+        // replies describing lookups that never happened.
+        mcpServerName: runtime.mcpConfigPath ? MCP_SERVER_NAME : undefined,
+        toolsGated: !runtime.skipPermissions,
     });
+    const result = await runTurn(run, prompt, options, runtime, log);
     const seconds = (result.durationMs / 1000).toFixed(1);
     if (!result.ok) {
-        const reason = result.error ??
-            (result.exitCode === null
-                ? 'agent command did not run'
-                : `agent command exited ${result.exitCode}`);
-        const detail = result.stderr.trim().slice(-500);
+        const { reason } = result;
+        const detail = result.detail ?? '';
         log(`${timestamp()} ✗ ${label} failed after ${seconds}s — ${reason}`);
         if (detail)
             log(`    stderr: ${detail}`);
@@ -126,14 +287,7 @@ async function handleRun(run, options, api, log, sleep) {
         }
         return 'failed';
     }
-    const reply = replyFromStdout(result.stdout);
-    if (!reply) {
-        log(`${timestamp()} ✗ ${label} produced no output after ${seconds}s`);
-        if (options.dryRun)
-            return 'skipped';
-        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: 'agent produced no output' }, log, sleep);
-        return reported.ok ? 'failed' : 'unreported';
-    }
+    const { reply } = result;
     if (options.dryRun) {
         const destination = run.reply_surface === 'none' ? '(no reply surface)' : `${run.reply_surface} ${run.reply_path}`;
         log(`${timestamp()} ◦ ${label} dry-run — would post to ${destination}:`);
@@ -158,14 +312,23 @@ async function handleRun(run, options, api, log, sleep) {
             log(`    ! could not mark the run complete (HTTP ${completed.status})`);
             return 'unreported';
         }
+        if (result.sessionId) {
+            runtime.sessions.remember(sessionKeyFor(run), result.sessionId);
+        }
         return 'succeeded';
     }
-    const posted = await postReply(api, run.reply_path, run.reply_body_key, reply, run.run_id);
+    const posted = await postReply(api, run.reply_path, run.reply_body_key, reply, run.run_id, run.reply_body_extra);
     if (!posted.ok) {
         log(`${timestamp()} ✗ ${label} reply rejected (HTTP ${posted.status}) ${posted.error ?? ''}`);
         const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: `posting the reply failed with HTTP ${posted.status}` }, log, sleep);
         return reported.ok ? 'failed' : 'unreported';
     }
+    // Advance continuity only after the answer is durable on its reply surface.
+    // Remembering at process exit would strand the conversation behind an answer
+    // it never received whenever this POST is rejected.
+    if (result.sessionId) {
+        runtime.sessions.remember(sessionKeyFor(run), result.sessionId);
+    }
     const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep);
     if (!completed.ok) {
         // The reply is already in the conversation, so this is a bookkeeping
@@ -189,8 +352,17 @@ export async function runAgentHarness(options) {
     const Ctor = options.webSocketCtor ?? WebSocket;
     const sleep = options.sleepImpl ?? defaultSleep;
     const machine = options.machine ?? os.hostname();
-    const url = options.url ?? options.credentials.ws_url ?? DEFAULT_WS_URL;
+    const url = options.url ?? streamUrlFor(options.credentials, DEFAULT_WS_URL);
     const metrics = newMetrics();
+    const runtime = buildRuntime(options, log);
+    // A credential file written by 0.1.0 stores a socket URL on a host that only
+    // ever answers 403. Upgrading the CLI would not have fixed those installs on
+    // its own — the stored value wins over the constant — so say what happened
+    // rather than silently using a different URL than the file names.
+    if (!options.url && options.credentials.ws_url && url !== options.credentials.ws_url) {
+        log(`${timestamp()} ! stored stream URL ${options.credentials.ws_url} predates this build ` +
+            `and is not used; connecting to ${url} instead (re-pair to refresh the file)`);
+    }
     const api = {
         baseUrl: options.credentials.base_url,
         apiKey: options.credentials.api_key,
@@ -274,7 +446,14 @@ export async function runAgentHarness(options) {
                 if (f.type === 'auth_ok') {
                     authed = true;
                     const name = options.credentials.agent?.name ?? 'agent';
-                    log(`${timestamp()} ● connected as "${name}" — waiting for mentions (exec: ${options.exec})`);
+                    // Names the event, not "mentions". A mention is one of several things
+                    // that make the server request a run — a 1:1 DM to this agent is
+                    // another, and it carries no mention at all — so "waiting for
+                    // mentions" describes a narrower trigger than the one this harness
+                    // actually waits on, and sends anyone debugging a silent agent to
+                    // read mention code instead of the run dispatcher.
+                    log(`${timestamp()} ● connected as "${name}" — waiting for ` +
+                        `${EVENT_AGENT_RUN_REQUESTED} (exec: ${options.exec})`);
                     return;
                 }
                 if (f.type === 'auth_error') {
@@ -307,7 +486,12 @@ export async function runAgentHarness(options) {
                 };
                 if (frame.event !== EVENT_AGENT_RUN_REQUESTED) {
                     if (frame.event === EVENT_MENTION_CREATED || frame.event === EVENT_MESSAGE_TEAM_CHAT) {
-                        log(`${timestamp()} ◦ ${frame.event} (no action — runs are triggered by mentions)`);
+                        // "runs are triggered by mentions" was wrong twice over: the gate
+                        // is the `agent.run_requested` event, and this very frame can BE a
+                        // mention — so the line claimed a mention triggers a run while
+                        // ignoring a mention. State the gate instead.
+                        log(`${timestamp()} ◦ ${frame.event} (no action — this harness runs on ` +
+                            `${EVENT_AGENT_RUN_REQUESTED}, which the server sends separately)`);
                     }
                     metrics.ignored += 1;
                     ack(ACK_IGNORED);
@@ -370,7 +554,7 @@ export async function runAgentHarness(options) {
                         metrics.runsFailed += 1;
                         return;
                     }
-                    const outcome = await handleRun(run, options, api, log, sleep).catch((err) => {
+                    const outcome = await handleRun(run, options, runtime, api, log, sleep).catch((err) => {
                         log(`${timestamp()} ✗ run ${run.run_id} crashed the harness handler: ${String(err)}`);
                         return 'failed';
                     });

package/dist/agent/sessionstore.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Which agent session belongs to which conversation.
+ *
+ * Every run spawns a fresh one-shot process, so without this the agent meets
+ * each message as its first: someone answers a clarifying question and gets a
+ * reply that has forgotten the question. Server-supplied thread history
+ * (`recent_messages`) narrows that gap but does not close it — history is what
+ * was *said*, not what the agent worked out, looked up, or decided on the last
+ * turn.
+ *
+ * Keyed by surface rather than by run: a run is one turn, and continuity is a
+ * property of the thread the turns are in.
+ *
+ * Deliberately a separate ledger from `runs.json`. That one is a safety
+ * mechanism whose entries must never be lost; this one is an optimisation whose
+ * worst failure is an agent starting fresh. Mixing them would give the
+ * important file the churn rate of the unimportant one.
+ */
+import type { AgentRunRequest } from './contract.js';
+export interface SessionRecord {
+    /** Surface key — see {@link sessionKeyFor}. */
+    key: string;
+    session_id: string;
+    updated_at: string;
+}
+/** Cap on retained sessions. Oldest are dropped first (insertion order). */
+export declare const SESSION_LEDGER_LIMIT = 200;
+export declare function sessionLedgerPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * The thread a run belongs to, or ``undefined`` when it belongs to none.
+ *
+ * A trigger fan-out (`reservation.created` and friends) has no surface and no
+ * predecessor, so it deliberately gets no key: resuming an unrelated session
+ * into it would carry over context that has nothing to do with the event, which
+ * is worse than starting clean.
+ *
+ * Keyed by agent as well as surface. The ledger outlives a pairing — re-pair
+ * this machine to a different AI employee and the file is still there — so a
+ * surface-only key would have the new agent resume the old one's session and
+ * answer in its predecessor's voice, carrying its reasoning and tool state.
+ */
+export declare function sessionKeyFor(run: AgentRunRequest): string | undefined;
+/**
+ * Surface → session id, backed by a JSON file.
+ *
+ * Like {@link RunStore}, every persistence failure degrades to memory-only
+ * rather than throwing: a read-only home directory should cost continuity, not
+ * the ability to answer.
+ */
+export declare class SessionStore {
+    private readonly file;
+    private readonly onWarn;
+    private records;
+    private constructor();
+    /** Read the ledger from disk. A missing or corrupt file starts empty. */
+    static load(env?: NodeJS.ProcessEnv, onWarn?: (line: string) => void): SessionStore;
+    /** The session to resume for a surface, if one is remembered. */
+    get(key: string | undefined): string | undefined;
+    /**
+     * Remember the session a surface's last turn ran in.
+     *
+     * Re-inserted rather than mutated in place so the map's insertion order stays
+     * a real least-recently-used order — {@link trim} drops from the front, and
+     * mutating in place would make the busiest thread the first one evicted.
+     */
+    remember(key: string | undefined, sessionId: string): void;
+    /** Drop a surface's session — used when the agent rejected it as unresumable. */
+    forget(key: string | undefined): void;
+    private trim;
+    private persist;
+}