@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/memory-bridge.js

@@ -0,0 +1,191 @@
+/**
+ * Memory bridge — ADR-005 §Memory bridge, ADR-003 Phase 2.
+ *
+ * Two thin CAP shims the run loop calls around every spawn cycle:
+ *
+ *   readLongTerm(client)            — GET  /api/agents/runtime/memory,
+ *                                      returns sections.long_term.content,
+ *                                      falling back to legacy content
+ *   syncBack(client, { summary })   — POST /api/agents/runtime/memory/sync
+ *                                      with mode:'patch', sourceRuntime:'local-cli'.
+ *                                      No-op when summary is falsy.
+ *
+ * Identity (agentName, instanceId) is derived server-side from the runtime
+ * token (agentRuntimeAuth), so neither helper needs to pass it. Keeping it
+ * server-derived is invariant-preserving: a bug in the wrapper can't write
+ * to the wrong agent's memory.
+ *
+ * ADR-003 invariant #9: the wrapper supplies `content` + `visibility` ONLY.
+ * `byteSize`, `updatedAt`, and `schemaVersion` are server-stamped; supplying
+ * them from the client is wasted bytes and the kernel discards them.
+ */
+
+import { KEEP_PROCESS_ENV } from '@commonlyai/seats/turn-processes';
+
+export const SOURCE_RUNTIME = 'local-cli';
+
+/**
+ * Row slicing, the runtime-agnostic half of TASK-545. A row too large
+ * for one turn drifts when one seat carries it whole, so the seat splits it on
+ * the board before any code. It names the exact call and field for the reason
+ * the memory cue below names `long_term`: a seat adopts a habit through a
+ * surface it can see. Each adapter decides whether to pass it.
+ */
+export const ROW_SLICING_CUE = 'Slicing: when a row is too large for one turn, split it before '
+  + 'writing any code. Post each slice as a child row (commonly_create_task with parentTask set '
+  + "to the row's taskId) with one assignee, a written file or area boundary, and its own "
+  + 'acceptance line.';
+
+// The turn's leftovers are stopped when it ends (@commonlyai/seats/turn-processes),
+// so a seat that means to reuse a server has to say so when it starts it.
+export const BACKGROUND_PROCESS_CUE = 'Background processes: anything you start in the background is '
+  + 'stopped when this turn ends, including a server that starts on first use, such as tmux, and an agent you '
+  + 'restart with nohup. To keep one for a later turn, such as a dev server you will reuse, start it '
+  + `with ${KEEP_PROCESS_ENV}=1 set, and stop it yourself when you are done with it.`;
+
+/**
+ * The turn preamble, shared by every adapter so the two cannot drift.
+ *
+ * Non-empty memory is prepended verbatim — that path is load-bearing and is
+ * not touched here.
+ *
+ * The EMPTY case used to return the bare prompt, which made two very different
+ * states byte-identical from inside the session: an agent that has never saved
+ * anything, and an agent on a runtime with no memory bridge at all. A seat
+ * cannot adopt a habit whose surface it has no evidence exists, so the empty
+ * case now says so.
+ *
+ * It names `long_term` specifically because that is the only v2 section read
+ * back. Legacy `content` is a fallback for records without that section. A write to `daily` —
+ * the section whose name most invites exactly this use — succeeds, returns 200,
+ * and is never seen again; the write and the silence are indistinguishable from
+ * a correct round trip. Naming the section is the whole point of the cue.
+ *
+ * `workCues` are working habits an adapter teaches on a fresh session, beside
+ * the memory cues and under the same once-per-session rule. An adapter passes
+ * only the habits its CLI can act on; passing none leaves the preamble as it
+ * was.
+ *
+ * `memoryReadOnly` is a public seat on a turn its owner didn't wake (F118, F145):
+ * it reads its memory and is shown the long_term it read, but it is not offered
+ * the save tool, so no cue names one, and it is told why. A resumed session may
+ * hold an earlier turn's offer, so that line goes in every turn, not just fresh
+ * ones. `memoryWithheld` wins over it: that turn reads nothing either.
+ */
+export const buildMemoryPreamble = (
+  prompt,
+  memoryLongTerm,
+  { freshSession = false, workCues = [], memoryWithheld = false, memoryReadOnly = false } = {},
+) => {
+  // `null` is the UNREADABLE signal, and it is deliberately not the same value
+  // as `''`. Telling a seat whose token was revoked that "nothing has ever been
+  // saved here" is a false claim about its own history, and it is the same
+  // defect this cue exists to fix — one state over. When we could not read, say
+  // that, and say nothing about what is stored.
+  const ownerOnly = 'You can read your memory on this turn but not change it: '
+    + 'a memory write works only when your owner started the turn.';
+  let context;
+  if (memoryWithheld) {
+    // A workspace seat's turn that runs public: not unreadable and not empty,
+    // so neither of those cues is true. Its memory tools are off as well.
+    context = `=== Context (your persistent memory) ===\n`
+      + `(withheld this turn — this turn runs as a public seat because not every `
+      + `pod you answer in is confirmed private, so your memory stays out of it and `
+      + `the memory tools are off. This says nothing about what you have saved.)`;
+  } else if (memoryLongTerm === null) {
+    context = `=== Context (your persistent memory) ===\n`
+      + `(unreadable this turn — the memory read failed, so this says NOTHING `
+      + `about what you have saved. Do not treat it as empty`
+      + (memoryReadOnly ? `.)\n${ownerOnly}` : ` and do not re-save state you may already hold.)`);
+  } else if (memoryLongTerm) {
+    context = `=== Context (your persistent memory) ===\n${memoryLongTerm}`
+      + (memoryReadOnly ? `\n(${ownerOnly})` : '');
+  } else if (memoryReadOnly) {
+    // F118: this turn isn't offered the save tool, so the cue that teaches it
+    // would name a tool the seat cannot call.
+    context = `=== Context (your persistent memory) ===\n`
+      + `(empty — nothing has ever been saved here)\n${ownerOnly}`;
+  } else {
+    context = `=== Context (your persistent memory) ===\n`
+      + `(empty — nothing has ever been saved here)\n`
+      + `Only the \`long_term\` section is read back into this prompt. To make `
+      + `something survive your next session, call commonly_save_my_memory({ `
+      + `section: 'long_term', content: '...' }). A write to any other section `
+      + `succeeds and is never shown to you again.`;
+  }
+
+  context = '=== Workspace identity ===\n'
+    + 'This workspace is Space. Always call the product Space when explaining where you are. '
+    + 'The upstream-compatible tools and environment variables keep their commonly_* and COMMONLY_* names.\n'
+    + context;
+
+  if (!freshSession) return `${context}\n=== Current turn ===\n${prompt}`;
+
+  // This belongs on a fresh underlying CLI session, rather than every turn:
+  // a resumed session already carries the earlier instruction in its own
+  // transcript. Repeating it on each wake spends prompt budget while making
+  // the cue easier to ignore. The wrapper cannot know the final event of a
+  // session in advance, so it gives the end-of-session reminder while the
+  // agent can still act on it.
+  const freshReadCue = '=== Fresh session ===\n'
+    + 'This is a fresh session. Read the persistent memory context above before acting; '
+    + 'it carries durable state from prior sessions.\n';
+  let sessionEndCue = '=== Before this session ends ===\n';
+  if (memoryWithheld) {
+    sessionEndCue += 'Memory is withheld this turn, so there is nothing to save.';
+  } else if (memoryReadOnly) {
+    sessionEndCue += 'Memory is read-only on this turn, so there is nothing to save.';
+  } else if (memoryLongTerm === null) {
+    sessionEndCue += 'Memory was unreadable on this fresh session. Do not treat it as empty or '
+      + 'write a replacement based on this cue.';
+  } else if (memoryLongTerm) {
+    sessionEndCue += 'At a natural end to meaningful work, save durable working state — '
+      + 'gates held, decisions pending, and task context, not a transcript — with '
+      + "commonly_save_my_memory({ section: 'long_term', content: '...' }).";
+  } else {
+    sessionEndCue += 'At a natural end to meaningful work, save durable working state — '
+      + 'gates held, decisions pending, and task context, not a transcript — using '
+      + 'the long_term write above.';
+  }
+  const workCue = workCues.length
+    ? `\n=== Working a row ===\n${workCues.map((cue) => `- ${cue}`).join('\n')}\n`
+    : '';
+  return `${context}\n${freshReadCue}${workCue}\n=== Current turn ===\n${prompt}\n${sessionEndCue}`;
+};
+
+export const readLongTerm = async (client, { onError } = {}) => {
+  try {
+    const body = await client.get('/api/agents/runtime/memory');
+    return body?.sections?.long_term?.content ?? body?.content ?? '';
+  } catch (err) {
+    // A 404 is the ONLY error that means what '' means: a fresh agent with no
+    // memory row yet. The kernel upserts on first write, so this is genuine
+    // absence and the empty cue is true.
+    if (err?.status === 404) return '';
+    // Everything else — auth revoked, 500, connection refused — is a failure to
+    // READ, which tells us nothing about what is stored. Returning '' here made
+    // the caller assert emptiness on no evidence.
+    //
+    // `err.status` is undefined for a transport failure, so the old guard
+    // (`err?.status && err.status !== 404`) skipped onError precisely when the
+    // backend was unreachable: the loudest condition was the silent one, and
+    // nothing contradicted the false cue.
+    onError?.(err);
+    return null;
+  }
+};
+
+export const syncBack = async (client, { summary } = {}) => {
+  if (!summary) return { skipped: true };
+  await client.post('/api/agents/runtime/memory/sync', {
+    mode: 'patch',
+    sourceRuntime: SOURCE_RUNTIME,
+    sections: {
+      long_term: {
+        content: summary,
+        visibility: 'private',
+      },
+    },
+  });
+  return { skipped: false };
+};

package/src/lib/memory-import.js

@@ -0,0 +1,156 @@
+/**
+ * Local memory import — Phase C of the retention plan ("your agent arrives
+ * whole"). Detects the memory a local agent already has on this machine
+ * (project CLAUDE.md / MEMORY.md, Claude Code's per-project auto-memory
+ * directory), composes it into one document, and promotes it into the
+ * kernel envelope's `long_term` section via POST /memory/sync.
+ *
+ * Design constraints:
+ *   - Explicitly opt-in with preview (plan D3) — local memory files can
+ *     contain private material; callers must confirm before anything is
+ *     sent. This module only detects/composes/sends; the command layer
+ *     owns the prompt.
+ *   - APPEND, never clobber: `mode: 'patch'` replaces a section wholesale
+ *     (mergePatchSections is section-level), so we read the existing
+ *     long_term and append the import after it.
+ *   - Server stamps byteSize/updatedAt/schemaVersion (ADR-003 invariant
+ *     #9); we send content + visibility only.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+
+export const SOURCE_RUNTIME = 'import-local';
+
+// Envelope sections are curated context, not dumps. The auto-clearer story
+// on the agent side starts caring around 400KB of session; a quarter of
+// that is a generous ceiling for a one-shot import.
+export const MAX_IMPORT_BYTES = 256 * 1024;
+
+// Claude Code keeps per-project auto-memory under
+// ~/.claude/projects/<slug>/memory where <slug> is the project path with
+// every '/' replaced by '-'.
+export const claudeProjectMemoryDir = (cwd, home) => join(
+  home,
+  '.claude',
+  'projects',
+  cwd.replaceAll('/', '-'),
+  'memory',
+);
+
+const fileCandidate = (path, label) => {
+  if (!existsSync(path)) return null;
+  const stat = statSync(path);
+  if (!stat.isFile() || stat.size === 0) return null;
+  return { path, label, bytes: stat.size };
+};
+
+/**
+ * Find importable memory sources. An explicit path wins outright (file, or
+ * directory whose *.md files are all taken); otherwise auto-detect the
+ * well-known locations. Duplicates are collapsed by realpath — this repo,
+ * for instance, symlinks AGENTS.md → CLAUDE.md.
+ */
+export const detectMemorySources = ({
+  cwd = process.cwd(),
+  home = homedir(),
+  explicitPath = null,
+} = {}) => {
+  const candidates = [];
+
+  if (explicitPath) {
+    if (!existsSync(explicitPath)) {
+      throw new Error(`No such file or directory: ${explicitPath}`);
+    }
+    if (statSync(explicitPath).isDirectory()) {
+      for (const f of readdirSync(explicitPath).filter((n) => n.endsWith('.md')).sort()) {
+        const c = fileCandidate(join(explicitPath, f), `from ${basename(explicitPath)}/`);
+        if (c) candidates.push(c);
+      }
+      if (!candidates.length) {
+        throw new Error(`No .md files found in ${explicitPath}`);
+      }
+    } else {
+      const c = fileCandidate(explicitPath, 'explicit');
+      if (!c) throw new Error(`${explicitPath} is empty or not a regular file`);
+      candidates.push(c);
+    }
+  } else {
+    const projectInstructions = fileCandidate(join(cwd, 'CLAUDE.md'), 'project instructions');
+    if (projectInstructions) candidates.push(projectInstructions);
+    const agentsMd = fileCandidate(join(cwd, 'AGENTS.md'), 'project instructions');
+    if (agentsMd) candidates.push(agentsMd);
+    const projectMemory = fileCandidate(join(cwd, 'MEMORY.md'), 'project memory');
+    if (projectMemory) candidates.push(projectMemory);
+
+    const memDir = claudeProjectMemoryDir(cwd, home);
+    if (existsSync(memDir) && statSync(memDir).isDirectory()) {
+      for (const f of readdirSync(memDir).filter((n) => n.endsWith('.md')).sort()) {
+        const c = fileCandidate(join(memDir, f), 'auto-memory');
+        if (c) candidates.push(c);
+      }
+    }
+  }
+
+  // Collapse symlink duplicates (first mention wins its label).
+  const seen = new Set();
+  return candidates.filter((c) => {
+    let real;
+    try {
+      real = realpathSync(c.path);
+    } catch {
+      real = c.path;
+    }
+    if (seen.has(real)) return false;
+    seen.add(real);
+    return true;
+  });
+};
+
+/** Compose the sources into one markdown document with per-file provenance. */
+export const composeImport = (sources) => {
+  if (!sources.length) throw new Error('Nothing to import');
+  const total = sources.reduce((n, s) => n + s.bytes, 0);
+  if (total > MAX_IMPORT_BYTES) {
+    throw new Error(
+      `Import is ${Math.round(total / 1024)}KB — over the ${MAX_IMPORT_BYTES / 1024}KB ceiling. `
+      + 'Pass an explicit --path to a smaller file, or trim the sources.',
+    );
+  }
+  const parts = sources.map((s) => {
+    const content = readFileSync(s.path, 'utf8').trim();
+    return `## Imported: ${basename(s.path)} (${s.label})\n\n${content}`;
+  });
+  return `# Imported local memory\n\n${parts.join('\n\n---\n\n')}`;
+};
+
+/**
+ * Promote the composed document into the agent's long_term section,
+ * appending after any existing content. `client` is an api.js client
+ * authenticated with the agent's runtime token.
+ */
+export const importMemory = async (client, { sources }) => {
+  const imported = composeImport(sources);
+
+  let existing = '';
+  try {
+    const body = await client.get('/api/agents/runtime/memory');
+    existing = body?.sections?.long_term?.content || '';
+  } catch (err) {
+    // Fresh agents 404 — that's the common case. Anything else should stop
+    // the import: appending to memory we couldn't read risks clobbering it.
+    if (err?.status && err.status !== 404) throw err;
+  }
+
+  const content = existing ? `${existing.trimEnd()}\n\n${imported}` : imported;
+  await client.post('/api/agents/runtime/memory/sync', {
+    mode: 'patch',
+    sourceRuntime: SOURCE_RUNTIME,
+    sections: {
+      long_term: { content, visibility: 'private' },
+    },
+  });
+
+  return { files: sources.length, bytes: content.length, appended: Boolean(existing) };
+};

package/src/lib/missing-harness.js

@@ -0,0 +1,31 @@
+// F457: what a quick-try run says when the harness it needs isn't on PATH, and
+// the report it leaves first. The run exits before it ever checks in, so
+// without the report the connect page waits for it forever.
+
+import { NPM } from './cli-hint.js';
+
+// Only harnesses whose install command we have run ourselves get one here.
+const INSTALL = {
+  claude: { label: 'Claude Code', command: `${NPM} i -g @anthropic-ai/claude-code`, signIn: 'claude' },
+  codex: { label: 'Codex', command: `${NPM} i -g @openai/codex`, signIn: 'codex' },
+};
+
+/** One sentence on how to get the named harness, ending with "run this line again". */
+export const missingHarnessHint = (name) => {
+  const known = INSTALL[name];
+  if (!known) return `Install ${name}, then run this line again.`;
+  return `Install ${known.label} (${known.command}), sign in once by running ${known.signIn}, then run this line again.`;
+};
+
+/**
+ * Tell the instance what this run looked for (a harness id, or null for none
+ * of the ones it probes). Best effort: an older instance without the route, or
+ * a failed call, must not hide the message the person needs in the terminal.
+ */
+export const reportMissingHarness = async (client, harness) => {
+  try {
+    await client?.post?.('/api/agents/runtime/harness-missing', { harness });
+  } catch {
+    // The terminal message below is the answer either way.
+  }
+};

package/src/lib/model-unavailable.js

@@ -0,0 +1,154 @@
+/**
+ * F178 — a turn the model provider refused because the model itself is not
+ * available, and the one line the wrapper posts about it.
+ *
+ * Found on a Growth walk, 2026-11-05: a daemon seat with no server-side model
+ * ran claude with a model the person's Anthropic key was not scoped for. Every
+ * turn failed with "403 The requested model ... is not available for this API
+ * key", the seat log said so, and the pod said nothing. The person saw a silent
+ * agent and no way to fix it.
+ *
+ * The match is deliberately narrow. A 403 or 404 alone is not a model problem:
+ * a disabled organization, a revoked key and a wrong route all answer 403/404,
+ * and telling that person to change the model would send them the wrong way.
+ * So a failure counts only when it carries one of these shapes:
+ *
+ *   1. claude / Anthropic 403: "... model ... is not available for this API key",
+ *      with the 403 attached as the status or on the phrase's own line
+ *   2. OpenAI-style error code `model_not_found` (codex, opencode, LiteLLM), as
+ *      the structured `providerCode` adapterFailure keeps, not message text
+ *   3. a 404 whose text is model-shaped, on the same line or in one JSON
+ *      error body: Anthropic's `not_found_error` body,
+ *      kept as "model: <id>" by the adapter's keep-list, or "The model `<id>`
+ *      does not exist", or "model <id> not found".
+ *
+ * A public seat's withheld-tool error quotes a TOOL's vendor text, not the
+ * turn's own provider, so it never counts (public-tool-error.js).
+ */
+import { PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE } from './public-tool-error.js';
+import { CLI } from './cli-hint.js';
+
+/** How long one model's hint stays posted before the seat may post it again. */
+export const MODEL_UNAVAILABLE_HINT_WINDOW_MS = 60 * 60 * 1000;
+
+const NOT_AVAILABLE_FOR_KEY_RE = /\bmodel\b[^\n]{0,160}?\bis not available for (?:this|your) API key\b/i;
+// A status read out of text counts only where a status is written: at a line
+// start, just inside a bracket, or after an explicit HTTP, HTTP/1.1, HTTP status,
+// status, status_code, code, our own `upstream` label (adapterFailure's "(upstream 404)") or
+// claude's `API Error`, each with an optional `:`, `=`, `_` or `-`. It is never
+// followed by a word character, `.` or `-`. So `request_id=404`, `gpt-404-mini`
+// and `claude-403x` are not statuses.
+const statusRe = (code) => new RegExp('(?:^\\s*|[([{]\\s*|\\b(?:HTTP(?:/\\d(?:\\.\\d)?|\\s+status)?'
+  + `|status(?:_?code)?|code|upstream|API\\s+Error)\\s*[:=_-]?\\s*)${code}(?![\\w.-])`, 'i');
+const STATUS_403_RE = statusRe(403);
+const MODEL_404_SHAPES = [
+  /\bmodel:\s*[`'"]?[\w.:/@-]+/i,
+  /\bthe model\b[^\n]{0,120}?\bdoes not exist\b/i,
+  /\bmodel\b[^\n]{0,120}?\bnot found\b/i,
+];
+const STATUS_404_RE = statusRe(404);
+const modelShaped = (text) => MODEL_404_SHAPES.some((pattern) => pattern.test(text));
+
+// A 404 counts only when the status and the model shape are one statement: the
+// same line, or one JSON error body. An unrelated 404 on one stderr line must
+// not be joined to a model mentioned on another.
+const sameLine404 = (text) => text.split('\n').some((line) => STATUS_404_RE.test(line) && modelShaped(line));
+
+const jsonBody404 = (text) => {
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start < 0 || end <= start) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return false;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
+  const error = parsed.error && typeof parsed.error === 'object' ? parsed.error : parsed;
+  const statuses = [parsed.status, parsed.code, error.status, error.code];
+  if (statuses.some((value) => Number(value) >= 500)) return false;
+  const is404 = statuses.some((value) => String(value) === '404') || error.type === 'not_found_error';
+  const message = error.message ?? parsed.message;
+  return is404 && typeof message === 'string' && modelShaped(message);
+};
+
+// The model id, when the provider named it. Only this charset is ever echoed
+// into a pod, so provider prose and anything redacted (`[redacted]`) cannot be.
+const MODEL_NAME_RES = [
+  /\brequested model\s+[`'"]?([\w.:/@-]+?)[`'"]?\s+is not available\b/i,
+  /\bmodel:\s*[`'"]?([\w.:/@-]+)/i,
+  /\bmodel\s+[`'"]([\w.:/@-]+)[`'"]/i,
+  /\bmodel\s+([\w.:/@-]+)\s+(?:not found|does not exist)\b/i,
+];
+// An id read out of prose must look like one ("is", "not" never do); a seat's
+// own configured model may be a bare alias such as `sonnet`.
+const ID_LIKE_RE = /[\d.:/-]/;
+const SAFE_MODEL_RE = /^(?=.*[A-Za-z])[\w.:/@-]{1,100}$/;
+
+const failureText = (error) => [error?.message, error?.stderr, error?.body?.error, error?.body?.message]
+  .filter((value) => typeof value === 'string' && value)
+  .join('\n');
+
+export const safeModelName = (value) => {
+  const text = typeof value === 'string' ? value.trim() : '';
+  // A leading `@` would read as a mention in the pod, and `://` as a link.
+  if (text.startsWith('@') || text.includes('://')) return null;
+  return SAFE_MODEL_RE.test(text) ? text : null;
+};
+
+/**
+ * `{ model }` when the failure is a provider saying the model is unavailable,
+ * else null. `model` is the id the provider named, then `fallbackModel` (the
+ * seat's own setting), then null when neither is known.
+ */
+export const modelUnavailableFailure = (error, { fallbackModel = null } = {}) => {
+  if (!error || error.code === PUBLIC_TOOL_FAILED_CODE || error.code === PUBLIC_MCP_NOT_READY_CODE) return null;
+  const text = failureText(error);
+  if (!text) return null;
+  // The key-scope phrase counts only on a 403: the attached status, or a 403 on
+  // the phrase's own line. The provider's code counts only as the structured
+  // field adapterFailure keeps, never as words in a message.
+  // An attached status is the adapter's own reading of the failure, so it wins:
+  // when it is set, only that status decides, and the text is not searched for
+  // another one. Without it, the status must be written on the same line.
+  const attached = typeof error.status === 'number' ? error.status : null;
+  const lines = text.split('\n');
+  const keyScope = NOT_AVAILABLE_FOR_KEY_RE.test(text) && (attached !== null ? attached === 403
+    : lines.some((line) => STATUS_403_RE.test(line) && NOT_AVAILABLE_FOR_KEY_RE.test(line)));
+  // The attached status reads the message, so its model shape must be on the
+  // message's own first line, not in what later stderr happens to mention.
+  const notFound = attached !== null
+    ? attached === 404 && (modelShaped(String(error.message).split('\n')[0]) || jsonBody404(text))
+    : sameLine404(text) || jsonBody404(text);
+  const matched = keyScope
+    || (error.providerCode === 'model_not_found' && !(attached >= 500))
+    || notFound;
+  if (!matched) return null;
+  for (const pattern of MODEL_NAME_RES) {
+    const named = safeModelName(pattern.exec(text)?.[1]);
+    if (named && ID_LIKE_RE.test(named)) return { model: named };
+  }
+  return { model: safeModelName(fallbackModel) };
+};
+
+const CLI_AGENT_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+/**
+ * The one line posted in the pod. The model is set in the agent's Settings,
+ * under the "How it runs" section, which starts collapsed (F354: a walk missed
+ * it). `cliAgentName` is for a `commonly agent run` seat whose record has no
+ * saved environment: Settings doesn't reach that seat until `agent config`
+ * writes one, so the line names that command instead. A name that can't be
+ * printed safely becomes `<name>`: Settings still wouldn't reach that seat.
+ */
+export const modelUnavailableHint = (model, { cliAgentName = null } = {}) => {
+  const what = model
+    ? `The model provider says ${model} isn't available for this agent.`
+    : "The model provider says this agent's model isn't available.";
+  if (typeof cliAgentName !== 'string' || !cliAgentName) {
+    return `${what} To change it, open the agent's Settings, then How it runs, then Model.`;
+  }
+  const name = CLI_AGENT_NAME_RE.test(cliAgentName) ? cliAgentName : '<name>';
+  return `${what} To change it, run ${CLI} agent config ${name} --model <model> on the computer it runs on, then restart ${CLI} agent run ${name}.`;
+};

package/src/lib/native-runtime-inventory.js

@@ -0,0 +1,40 @@
+import { spawnSync } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveWindowsCommandWithReason } from './windows-command.js';
+
+export const claudeEffortsFromHelp = (help) => {
+  const section = String(help).match(/--effort\s+<[^>]+>([\s\S]*?)(?=\n\s+--|$)/)?.[1];
+  const declared = section?.match(/\((low(?:\s*,\s*(?:medium|high|xhigh|max))*)\)/)?.[1];
+  return declared ? declared.split(',').map((level) => level.trim()) : [];
+};
+export const codexModelsFromCache = (cache) => {
+  const models = Array.isArray(cache?.models) ? cache.models.filter((row) => typeof row.slug === 'string'
+    && row.slug.length > 0 && row.slug.length <= 256 && row.visibility !== 'hidden' && row.visibility !== 'hide') : [];
+  const levels = models.map((row) => (Array.isArray(row.supported_reasoning_levels)
+    ? row.supported_reasoning_levels.flatMap((level) => typeof level.effort === 'string' ? [level.effort] : []) : []));
+  return { models: models.length ? models.map((row) => row.slug) : null,
+    // Only levels supported by every advertised model are offered globally.
+    efforts: levels.length ? levels[0].filter((level) => levels.every((list) => list.includes(level))) : [] };
+};
+export const claudeRuntimeInventory = async ({
+  spawnSyncImpl = spawnSync, env = process.env, commandResolution = {},
+} = {}) => {
+  // Windows: an npm `claude.cmd` is resolved to its target, never run through
+  // a shell (#2141). Elsewhere this is `claude --help`, unchanged.
+  const located = resolveWindowsCommandWithReason('claude', { env, ...commandResolution });
+  if (!located.command) return { models: null, efforts: [] };
+  const result = spawnSyncImpl(located.command, [...located.args, '--help'], {
+    encoding: 'utf8', timeout: 5000, maxBuffer: 128 * 1024, cwd: tmpdir(), env,
+  });
+  return { models: null, efforts: result.status === 0 ? claudeEffortsFromHelp(result.stdout) : [] };
+};
+export const codexRuntimeInventory = async ({ readFileImpl = readFile, statImpl = stat, env = process.env } = {}) => {
+  // Native cache only: no command that could execute workspace extensions.
+  const path = join(env.CODEX_HOME || join(homedir(), '.codex'), 'models_cache.json');
+  try {
+    if ((await statImpl(path)).size > 2 * 1024 * 1024) return { models: null, efforts: [] };
+    return codexModelsFromCache(JSON.parse(await readFileImpl(path, 'utf8')));
+  } catch { return { models: null, efforts: [] }; }
+};

package/src/lib/outsider-grant-mcp.js

@@ -0,0 +1,82 @@
+/**
+ * A confined seat that an outsider-writable grant reaches runs with only the
+ * shipped MCP servers (docs/plans/hosted-mcp-connection-scope.md §12 C).
+ *
+ * While a grant whose source outsiders can write reaches one of a seat's pods,
+ * the server narrows what the seat's token can do (§12 A). It cannot see the
+ * MCP servers the seat loads on this machine, though. The daemon admits a
+ * declared stdio entry that equals one in the local token record
+ * (`auditDeclaredMcp`), so a server its owner installed locally can sit beside
+ * the grant's results, and content an outsider wrote can steer it. So before
+ * each turn, a confined seat that may be narrowed is refused while its MCP set
+ * holds anything but the shipped Commonly server or a shipped grant broker.
+ *
+ * The effective set is the declared one. A confined seat's adapter excludes
+ * user- and project-scope MCP config (claude `--strict-mcp-config`, codex
+ * `--ignore-user-config`, isolated homes for the others), and
+ * `outsider-grant-mcp.test.mjs` pins those flags, so a scope added to an
+ * adapter fails that test before it widens this set.
+ *
+ * Only confined seats (`sandbox.trust` public or workspace, with the legacy
+ * `internal` read as public) are checked. An
+ * unconfined seat named on a grant runs on its owner's machine with a shell,
+ * under the owner's consent that what it reads can leave, so a local MCP
+ * server adds nothing it lacks (§12, the F94 amendment).
+ */
+import { isShippedCommonlyMcpEntry, isShippedGrantBrokerEntry } from './declared-mcp-guard.js';
+import { effectiveSandboxTrust } from './environment.js';
+
+export const OUTSIDER_GRANT_MCP_UNCONFINED = 'outsider_grant_mcp_unconfined';
+
+const CONFINED_TRUSTS = new Set(['public', 'workspace']);
+
+// Read through the legacy table, as the broker guard and the adapters read it:
+// a record still carrying `internal` is confined as `public`, and is handed
+// the broker as a public seat, so it is checked as one.
+export const seatIsConfined = (environment) => CONFINED_TRUSTS.has(
+  effectiveSandboxTrust(environment?.sandbox?.trust),
+);
+
+// The server flags a broker on a grant that names this seat (`byoNamed`). It is
+// a marker for the guard, not something the client reads, so it is set aside
+// before the whole-entry match, and only as exactly `true`.
+const withoutByoNamedFlag = (server) => {
+  if (!server || typeof server !== 'object' || server.byoNamed !== true) return server;
+  const { byoNamed: _byoNamed, ...rest } = server;
+  return rest;
+};
+
+/** The entries of a turn's MCP set that are neither shipped server. */
+export const unshippedMcpEntries = (environment, instanceUrl) => {
+  const servers = Array.isArray(environment?.mcp) ? environment.mcp : [];
+  return servers.filter((server) => !isShippedCommonlyMcpEntry(server)
+    && !isShippedGrantBrokerEntry(withoutByoNamedFlag(server), instanceUrl));
+};
+
+/**
+ * Whether the server's answer leaves the seat possibly narrowed. Only an
+ * explicit `outsiderGrantNarrowed: false` clears it. A server from before the
+ * field, or an answer that lacks it, counts as narrowed, because the CLI
+ * publishes before the server change is deployed.
+ */
+export const mayBeNarrowed = (identity) => identity?.outsiderGrantNarrowed !== false;
+
+/**
+ * @returns {null | { code: string, names: string[], message: string }}
+ */
+export const outsiderGrantMcpRefusal = ({ environment, identity, instanceUrl }) => {
+  if (!seatIsConfined(environment)) return null;
+  const extra = unshippedMcpEntries(environment, instanceUrl);
+  if (!extra.length || !mayBeNarrowed(identity)) return null;
+  const names = extra.map((server) => String(server?.name || '(unnamed)'));
+  const why = identity && 'outsiderGrantNarrowed' in identity
+    ? 'a connector grant whose source outsiders can write reaches one of its pods'
+    : 'the server did not say whether a connector grant reaches its pods, so it is treated as if one does';
+  return {
+    code: OUTSIDER_GRANT_MCP_UNCONFINED,
+    names,
+    message: `${OUTSIDER_GRANT_MCP_UNCONFINED}: this seat loads MCP servers beyond the shipped Space server `
+      + `and grant broker (${names.join(', ')}), and ${why}. Remove them from the seat's environment, `
+      + 'or use a separate agent for the connector pod.',
+  };
+};