switchroom 0.17.6 → 0.18.3

package/telegram-plugin/gateway/inbound-delivery-gate.ts

@@ -116,3 +116,29 @@ export function decideInboundDelivery(
   if (input.turnInFlight) return 'buffer-until-idle'
   return 'deliver'
 }
+
+/**
+ * #2917 — atomic check-and-reserve for per-chat outbound FIFO.
+ *
+ * `decideInboundDelivery` decides deliver-vs-buffer, but on the concurrent
+ * `handleInbound` path that decision and the busy-mark that records "a turn is
+ * now in flight for this chat" are separated by an `await` (attachment
+ * download, composer-clear). Two same-chat inbounds can therefore each read
+ * "idle" during the other's async lead-in and both deliver — the replies then
+ * come back reordered. This helper couples the decision with a `reserve` flag:
+ * a FRESH-TURN deliver must reserve the chat's busy key SYNCHRONOUSLY (before
+ * any await) so the next same-chat inbound sees it and buffers behind it.
+ *
+ * `reserve` is true ONLY for a fresh-turn deliver. Steering / interrupt
+ * inbounds deliver mid-turn WITHOUT starting a turn, so they must not reserve
+ * (reserving would wedge the running turn's key). A buffered decision never
+ * reserves.
+ */
+export function reserveInboundDelivery(
+  input: InboundDeliveryGateInput,
+): { decision: InboundDeliveryDecision; reserve: boolean } {
+  const decision = decideInboundDelivery(input)
+  const reserve =
+    decision === 'deliver' && !input.isSteering && input.isInterrupt !== true
+  return { decision, reserve }
+}

package/telegram-plugin/gateway/inbound-spool.ts

@@ -94,6 +94,28 @@ export function spoolId(msg: InboundMessage): string {
   ) {
     return `s:resume:${msg.meta.resume_turn_key}`
   }
+  // Cron BOOT-REPLAY (#2793 part B): a scheduled fire that the boot
+  // replay re-injects because it was missed across a restart. Keyed on
+  // the minute-aligned fire it is replaying (`replay_fire_ms`) plus the
+  // schedule index, NOT the fresh synthetic `messageId` (=ts, minted per
+  // replay attempt) — so a re-replay of the SAME missed fire across a
+  // subsequent gateway restart collapses to ONE live spool entry instead
+  // of stacking a fresh one each boot. This is what makes routing cron
+  // replays through the durable spool at-least-once WITH dedup, mirroring
+  // the resume/handback stable-id idiom above. Live (non-replay) cron
+  // ticks never set `replay_fire_ms`, so they are unaffected and keep
+  // their per-fire identity.
+  if (
+    msg.meta?.source === 'cron' &&
+    typeof msg.meta?.replay_fire_ms === 'string' &&
+    msg.meta.replay_fire_ms.length > 0
+  ) {
+    const idx =
+      typeof msg.meta?.schedule_index === 'string' && msg.meta.schedule_index.length > 0
+        ? msg.meta.schedule_index
+        : '-'
+    return `s:cron-replay:${msg.chatId}:${idx}:${msg.meta.replay_fire_ms}`
+  }
   if (typeof msg.messageId === 'number' && msg.messageId > 0) {
     return `m:${msg.chatId}:${msg.messageId}`
   }

package/telegram-plugin/gateway/mental-model-propose-card.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure renderer for the agent-initiated mental-model PROPOSAL approval card
+ * (hindsight Phase 5, stacked on #2874).
+ *
+ * Mirrors `vault-request-access-card.ts` exactly — same rich-message (GFM
+ * markdown) escaping discipline:
+ *   - Non-code-span interpolations (`**agent**`, `_reason_`, `_source_query_`)
+ *     are markdown-escaped via `escapeHtmlForTg` so a stray `*`/`_`/`[` can't
+ *     break the surrounding emphasis.
+ *   - Code-span interpolations (`name`) are LITERAL inside the span, so they
+ *     must NOT be markdown-escaped; only the backtick is defused via
+ *     `codeSpanSafe`.
+ *
+ * The card asks the OPERATOR to approve turning a proposed model into a
+ * first-class DECLARED model (`memory.mental_models[]`). The agent can only
+ * PROPOSE — the [Approve]/[Deny] tap is operator-gated in the gateway, exactly
+ * like the vault flow, so an agent can never self-approve.
+ */
+
+import { escapeHtmlForTg } from "../shared/bot-runtime.js";
+import { codeSpanSafe } from "./approval-card.js";
+import { hardenCardBreaks } from "../format.js";
+
+/** Minimal shape the card needs — a subset of the pending proposal. */
+export interface MentalModelProposeCardInput {
+  agent: string;
+  name: string;
+  source_query: string;
+  reason?: string;
+  refresh_after_consolidation?: boolean;
+  max_tokens?: number;
+}
+
+export function renderMentalModelProposeCard(
+  req: MentalModelProposeCardInput,
+): string {
+  const lines: string[] = [];
+  lines.push(`🧠 **${escapeHtmlForTg(req.agent)}** proposes a mental model`);
+  // Code-span content is literal — defuse only the backtick, never
+  // markdown-escape (see file header).
+  lines.push(`name: \`${codeSpanSafe(req.name)}\``);
+  lines.push(`source query: _${escapeHtmlForTg(req.source_query)}_`);
+  const refreshLabel = req.refresh_after_consolidation ? "on" : "off";
+  lines.push(`refresh after consolidation: \`${codeSpanSafe(refreshLabel)}\``);
+  // Always show max_tokens so the operator approves EXACTLY what's applied.
+  // When the proposal omits it, the declared model inherits the bank default —
+  // render that explicitly rather than hiding the field.
+  const maxTokensLabel =
+    typeof req.max_tokens === "number" ? String(req.max_tokens) : "default";
+  lines.push(`max tokens: \`${codeSpanSafe(maxTokensLabel)}\``);
+  // Always render the why-line, even when omitted — a missing rationale is
+  // then visibly an agent-side failure, not a card-template choice (mirrors
+  // the vault card's #1790 behaviour).
+  if (req.reason && req.reason.length > 0) {
+    lines.push(`why: _${escapeHtmlForTg(req.reason)}_`);
+  } else {
+    lines.push(`why: _not provided_`);
+  }
+  lines.push("");
+  lines.push(
+    `_Tap Approve to DECLARE this model — it is appended to ${escapeHtmlForTg(req.agent)}'s ` +
+      `\`memory.mental_models[]\` (operator-approved config edit) and ensured in the bank. ` +
+      `Tap Deny to drop it — nothing is written._`,
+  );
+  // hardenCardBreaks: the labelled field lines would soft-collapse into one
+  // blob under the GFM rich renderer; this card is sent direct via
+  // richMessage, bypassing the switchroomReply chokepoint.
+  return hardenCardBreaks(lines.join("\n"));
+}

package/telegram-plugin/gateway/mental-model-propose-diff.ts

@@ -0,0 +1,171 @@
+/**
+ * Pure (no-network) helpers for the agent-proposes → human-approves
+ * mental-model curation flow (hindsight Phase 5, stacked on #2874).
+ *
+ * #2874 shipped the operator-DECLARED half: a per-agent
+ * `memory.mental_models[]` config that `ensureDeclaredMentalModels`
+ * materialises at scaffold/reconcile. This module is the persistence
+ * primitive for the SECOND half: when an agent PROPOSES a model and the
+ * operator taps Approve, the proposed model must become a first-class
+ * DECLARED model — i.e. it must land in `agents.<agent>.memory.mental_models[]`
+ * in switchroom.yaml so the exact same #2874 ensure/reconcile path
+ * consumes it. Nothing bespoke: the approved proposal is just a new
+ * declared model.
+ *
+ * The persist reuses the proven `config_propose_edit` apply+reconcile
+ * machinery (hostd is the sole config writer — the leash). So this module
+ * only has to produce a git-apply-compatible unified diff that appends the
+ * declared model to the agent's block. We build `after` with the
+ * structure-preserving `yaml` document API and diff it against the live
+ * `before` bytes with the same `git diff --no-index` family hostd applies
+ * with (see src/web/config-diff.ts) — so the patch round-trips.
+ *
+ * Deliberately no I/O here beyond the git-diff subprocess in
+ * `generateUnifiedDiff`; callers read the raw config bytes and feed them in.
+ */
+
+import { parseDocument } from "yaml";
+import { generateUnifiedDiff } from "../../src/web/config-diff.js";
+
+/**
+ * A proposed mental model, in the same snake_case shape the
+ * `memory.mental_models[]` schema (#2874) accepts. `name` + `source_query`
+ * are required; the knobs are opt-in and only serialised when set (a minimal
+ * declaration is the schema-clean default).
+ */
+export interface MentalModelProposeSpec {
+  name: string;
+  source_query: string;
+  refresh_after_consolidation?: boolean;
+  max_tokens?: number;
+}
+
+export type BuildDiffResult =
+  | { ok: true; diff: string; after: string }
+  | { ok: false; error: "agent-not-found" | "duplicate" | "no-change" | "parse-error"; detail: string };
+
+/**
+ * Read the NAMES of the models already DECLARED in
+ * `agents.<agentName>.memory.mental_models[]` of raw config text. Used for the
+ * duplicate-name guard so a proposal for an already-declared model is rejected
+ * BEFORE a card is ever posted. Returns [] when the agent has no declared
+ * models (or the block/keys are absent). Never throws — a parse failure yields
+ * [] so the caller degrades to the (also-guarded) build step.
+ */
+export function readDeclaredMentalModelNames(
+  configText: string,
+  agentName: string,
+): string[] {
+  if (!configText || !agentName) return [];
+  let js: unknown;
+  try {
+    js = parseDocument(configText, { merge: false, strict: false }).toJS();
+  } catch {
+    return [];
+  }
+  const models = navigateMentalModels(js, agentName);
+  if (!Array.isArray(models)) return [];
+  return models
+    .map((m) => (m && typeof m === "object" ? (m as { name?: unknown }).name : undefined))
+    .filter((n): n is string => typeof n === "string");
+}
+
+function navigateMentalModels(js: unknown, agentName: string): unknown {
+  if (!js || typeof js !== "object") return undefined;
+  const agents = (js as Record<string, unknown>).agents;
+  if (!agents || typeof agents !== "object") return undefined;
+  const agent = (agents as Record<string, unknown>)[agentName];
+  if (!agent || typeof agent !== "object") return undefined;
+  const memory = (agent as Record<string, unknown>).memory;
+  if (!memory || typeof memory !== "object") return undefined;
+  return (memory as Record<string, unknown>).mental_models;
+}
+
+/**
+ * Build a git-apply-compatible unified diff that APPENDS `spec` to the target
+ * agent's `memory.mental_models[]` in raw `configText`. Creates the
+ * `memory:` / `mental_models:` keys if absent. Returns a structured error
+ * (never throws) when:
+ *   - the agent block is absent (`agent-not-found`) — we never invent one;
+ *   - a model with the same name is already declared (`duplicate`) — the
+ *     schema's idempotent-ensure key must stay unique;
+ *   - the edit is a no-op (`no-change`);
+ *   - the config doesn't parse (`parse-error`).
+ *
+ * Only fields that are set on `spec` are serialised, matching the minimal,
+ * schema-clean create payload #2874 emits.
+ */
+export function buildMentalModelAppendDiff(args: {
+  configText: string;
+  agentName: string;
+  spec: MentalModelProposeSpec;
+  /** Injectable git binary for tests (defaults to "git"). */
+  gitBin?: string;
+}): BuildDiffResult {
+  const { configText, agentName, spec } = args;
+
+  let doc;
+  try {
+    doc = parseDocument(configText, { merge: false, strict: false });
+  } catch (e) {
+    return { ok: false, error: "parse-error", detail: (e as Error).message };
+  }
+  if (doc.errors && doc.errors.length > 0) {
+    return { ok: false, error: "parse-error", detail: doc.errors[0]!.message };
+  }
+
+  // The agent block must already exist — a proposal never scaffolds a new
+  // agent, only augments the caller's own declared models.
+  if (doc.getIn(["agents", agentName]) === undefined) {
+    return {
+      ok: false,
+      error: "agent-not-found",
+      detail: `agents.${agentName} not present in config`,
+    };
+  }
+
+  // Duplicate-name guard (defense-in-depth; the executor also checks up front
+  // so it never even posts a card for a dupe).
+  const existing = readDeclaredMentalModelNames(configText, agentName);
+  if (existing.includes(spec.name)) {
+    return {
+      ok: false,
+      error: "duplicate",
+      detail: `mental model "${spec.name}" is already declared for ${agentName}`,
+    };
+  }
+
+  // Assemble the minimal, schema-clean declaration node.
+  const item: Record<string, unknown> = {
+    name: spec.name,
+    source_query: spec.source_query,
+  };
+  if (spec.refresh_after_consolidation !== undefined) {
+    item.refresh_after_consolidation = spec.refresh_after_consolidation;
+  }
+  if (spec.max_tokens !== undefined) {
+    item.max_tokens = spec.max_tokens;
+  }
+
+  // Append into agents.<agent>.memory.mental_models[], creating the
+  // intermediate mapping/sequence if they don't exist yet. `addIn` on an
+  // absent path creates the sequence; when it exists we push onto it.
+  const path = ["agents", agentName, "memory", "mental_models"];
+  const seq = doc.getIn(path);
+  if (seq === undefined) {
+    doc.setIn(path, [item]);
+  } else {
+    doc.addIn(path, item);
+  }
+
+  const after = String(doc);
+  if (after === configText) {
+    return { ok: false, error: "no-change", detail: "append produced no change" };
+  }
+
+  const diff = generateUnifiedDiff(configText, after, "switchroom.yaml", args.gitBin ?? "git");
+  if (diff === "") {
+    return { ok: false, error: "no-change", detail: "diff was empty" };
+  }
+  return { ok: true, diff, after };
+}

package/telegram-plugin/gateway/mental-model-propose-inbound-builders.ts

@@ -0,0 +1,147 @@
+/**
+ * Pure builders for the synthetic inbounds the gateway injects after the
+ * operator taps Approve / Deny on a mental-model PROPOSAL card (hindsight
+ * Phase 5, stacked on #2874). Mirrors `vault-grant-inbound-builders.ts`.
+ *
+ * Extracted from `gateway.ts` so the InboundMessage shape is pinned by tests
+ * separately from the config-apply/IPC plumbing. The shape is load-bearing —
+ * `meta.source` is what the bridge keys on to render
+ * `<channel source="mental_model_proposal_applied">` /
+ * `mental_model_proposal_denied` / `mental_model_proposal_failed` blocks, and
+ * the `meta.{agent,name,stage_id,operator_id}` fields are the forensic anchor.
+ *
+ * A regression that drops a meta field or changes the source string would
+ * silently break the agent's wake-up: the bridge wouldn't recognise the source
+ * and would route as a generic channel event, the model wouldn't know its
+ * proposal resolved, and the conversation would drift. Pinning these against
+ * fixture tests is cheaper than catching that downstream.
+ */
+
+import type { InboundMessage } from "./ipc-protocol.js";
+
+/** Subset of the pending proposal the builders need. Kept narrow so callers
+ *  don't have to pass the full pending record. */
+export interface MentalModelProposeInboundContext {
+  agent: string;
+  /** The proposed model's stable name (identity key). */
+  name: string;
+  /** Telegram chat id where the approval card lived. Used as the inbound's
+   *  chatId so the synthesized turn stays associated with the originating
+   *  conversation. */
+  chat_id: string;
+  /** Supergroup forum topic (message_thread_id) the agent was working in when
+   *  it proposed — so the resumed turn's reply lands back in that topic, not
+   *  General. Undefined for DM / non-topic proposals. */
+  threadId?: number;
+}
+
+/**
+ * Build the synthetic InboundMessage for a successful operator approval whose
+ * config edit APPLIED — the proposed model is now a declared model and has
+ * been (or will be, on reconcile) ensured in the bank.
+ */
+export function buildMentalModelProposeAppliedInbound(opts: {
+  ctx: MentalModelProposeInboundContext;
+  stageId: string;
+  operatorId: string;
+  nowMs?: number;
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now();
+  return {
+    type: "inbound",
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts, // synthetic — no Telegram message id exists
+    user: "hindsight-curator",
+    userId: 0,
+    ts,
+    text:
+      `✅ Operator approved your mental-model proposal \`${opts.ctx.name}\`. ` +
+      `It is now a DECLARED model in your \`memory.mental_models[]\` and is ` +
+      `being ensured in your bank (idempotent). Resume whatever you were doing ` +
+      `— the model will refresh from your bank content; no further action is ` +
+      `needed to create it.`,
+    meta: {
+      source: "mental_model_proposal_applied",
+      agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
+      name: opts.ctx.name,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  };
+}
+
+/**
+ * Build the synthetic InboundMessage for an operator denial. The model was
+ * NOT declared and NOTHING was written. Steers the agent to a fallback rather
+ * than re-proposing.
+ */
+export function buildMentalModelProposeDeniedInbound(opts: {
+  ctx: MentalModelProposeInboundContext;
+  stageId: string;
+  operatorId: string;
+  nowMs?: number;
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now();
+  return {
+    type: "inbound",
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts,
+    user: "hindsight-curator",
+    userId: 0,
+    ts,
+    text:
+      `🚫 Operator denied your mental-model proposal \`${opts.ctx.name}\`. ` +
+      `NOTHING was written — the model was not declared or created. Carry on ` +
+      `with the original task without it. Do NOT re-propose the same model ` +
+      `without first asking the user.`,
+    meta: {
+      source: "mental_model_proposal_denied",
+      agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
+      name: opts.ctx.name,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  };
+}
+
+/**
+ * Build the synthetic InboundMessage for an approval whose config edit FAILED
+ * (hostd apply/reconcile error, config-edit disabled, a dupe that raced in,
+ * etc.). The operator tapped Approve but the model did NOT land — be honest so
+ * the agent doesn't assume it exists.
+ */
+export function buildMentalModelProposeFailedInbound(opts: {
+  ctx: MentalModelProposeInboundContext;
+  stageId: string;
+  operatorId: string;
+  reason: string;
+  nowMs?: number;
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now();
+  return {
+    type: "inbound",
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts,
+    user: "hindsight-curator",
+    userId: 0,
+    ts,
+    text:
+      `⚠️ The operator approved your mental-model proposal \`${opts.ctx.name}\` but ` +
+      `persisting it FAILED (${opts.reason}). The model was NOT declared or ` +
+      `created — do NOT assume it exists. Carry on with the original task; the ` +
+      `operator can retry the declaration by hand if it still matters.`,
+    meta: {
+      source: "mental_model_proposal_failed",
+      agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
+      name: opts.ctx.name,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  };
+}

package/telegram-plugin/gateway/mental-model-propose-resolve.ts

@@ -0,0 +1,201 @@
+/**
+ * The approve/deny ORCHESTRATION for the mental-model proposal flow (hindsight
+ * Phase 5, stacked on #2874), factored out of gateway.ts so the invariants are
+ * unit-testable with injected deps (no gateway, no Telegram, no hostd, no
+ * network):
+ *
+ *   - APPROVE appends the model to config (via the injected config-edit
+ *     dispatch) AND ensures it, then wakes the agent with an "applied" inbound.
+ *   - DENY writes NOTHING (never reads config, never builds a diff, never
+ *     dispatches an edit, never ensures) and wakes the agent with a "denied"
+ *     inbound.
+ *   - A duplicate / agent-not-found / no-change proposal is REJECTED before any
+ *     edit is dispatched, and the agent gets a "failed" inbound.
+ *
+ * The gateway callback is a thin adapter that wires the real deps (read live
+ * config bytes, register the single-tap correlation, `config_propose_edit` via
+ * hostd, `ensureMentalModel`, inject-inbound) into `resolveMentalModelProposal`.
+ * Self-approval is impossible by construction: this function is only ever
+ * reached AFTER the gateway callback has verified the tapper is an allow-listed
+ * operator — the agent has no path to invoke it.
+ */
+
+import {
+  buildMentalModelAppendDiff,
+  type MentalModelProposeSpec,
+} from "./mental-model-propose-diff.js";
+import {
+  buildMentalModelProposeAppliedInbound,
+  buildMentalModelProposeDeniedInbound,
+  buildMentalModelProposeFailedInbound,
+  type MentalModelProposeInboundContext,
+} from "./mental-model-propose-inbound-builders.js";
+import type { InboundMessage } from "./ipc-protocol.js";
+
+/** The pending proposal state the resolver needs. */
+export interface MentalModelPendingProposal {
+  agent: string;
+  chat_id: string;
+  threadId?: number;
+  spec: MentalModelProposeSpec;
+  /** Human-readable rationale, echoed into the config-edit reason. */
+  reason?: string;
+}
+
+/** Outcome of dispatching the config edit through hostd's apply+reconcile. */
+export type ConfigEditDispatchResult =
+  | { state: "applied" }
+  | { state: "denied"; reason: string }
+  | { state: "error"; reason: string };
+
+export interface ResolveDeps {
+  /** Read the live switchroom.yaml bytes (before-image for the diff). */
+  readConfigText: () => string;
+  /**
+   * Register a single-tap correlation so hostd's config-approval callback
+   * auto-resolves the edit WITHOUT posting a SECOND operator card — the
+   * operator already approved on THIS proposal card. Forge-resistance is the
+   * caller's job (exact diff byte-match). Called only on the approve path,
+   * only after a diff was successfully built.
+   */
+  registerPreApproval: (agent: string, diff: string) => void;
+  /** Drop a previously-registered correlation (cleanup, single-shot). */
+  clearPreApproval: (agent: string, diff: string) => void;
+  /**
+   * Persist the append diff via hostd `config_propose_edit`
+   * (validate → approve → apply → reconcile). Reconcile runs
+   * `ensureDeclaredMentalModels` (#2874), materialising the model.
+   */
+  dispatchConfigEdit: (args: {
+    agent: string;
+    diff: string;
+    reason: string;
+  }) => Promise<ConfigEditDispatchResult>;
+  /**
+   * Best-effort belt-and-suspenders ensure of the model in the bank
+   * immediately after apply (reconcile is the authoritative suspenders). Must
+   * not throw. Optional — when absent, ensure is left entirely to reconcile.
+   */
+  ensureModel?: (spec: MentalModelProposeSpec) => Promise<void>;
+  /** Deliver a synthetic inbound to wake the agent with the outcome. */
+  injectInbound: (inbound: InboundMessage) => void;
+  /** Injectable clock for deterministic tests. */
+  now?: () => number;
+  /** Injectable git binary for the diff subprocess (tests). */
+  gitBin?: string;
+  log?: (msg: string) => void;
+}
+
+export type ResolveOutcome =
+  | { outcome: "applied" }
+  | { outcome: "denied" }
+  | { outcome: "rejected"; reason: string }
+  | { outcome: "failed"; reason: string };
+
+/**
+ * Resolve an operator's Approve / Deny decision on a mental-model proposal.
+ * Pure orchestration — all side effects go through `deps`.
+ */
+export async function resolveMentalModelProposal(
+  action: "approve" | "deny",
+  pending: MentalModelPendingProposal,
+  stageId: string,
+  operatorId: string,
+  deps: ResolveDeps,
+): Promise<ResolveOutcome> {
+  const nowMs = (deps.now ?? Date.now)();
+  const ctx: MentalModelProposeInboundContext = {
+    agent: pending.agent,
+    name: pending.spec.name,
+    chat_id: pending.chat_id,
+    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+  };
+
+  // ── DENY: write NOTHING. No config read, no diff, no dispatch, no ensure. ──
+  if (action === "deny") {
+    deps.injectInbound(
+      buildMentalModelProposeDeniedInbound({ ctx, stageId, operatorId, nowMs }),
+    );
+    return { outcome: "denied" };
+  }
+
+  // ── APPROVE: append to config (reused apply+reconcile) + ensure. ──
+  const configText = deps.readConfigText();
+  const built = buildMentalModelAppendDiff({
+    configText,
+    agentName: pending.agent,
+    spec: pending.spec,
+    ...(deps.gitBin ? { gitBin: deps.gitBin } : {}),
+  });
+  if (!built.ok) {
+    // Duplicate / agent-not-found / no-change / parse-error — reject BEFORE
+    // any edit is dispatched. Nothing is written.
+    deps.log?.(
+      `mental_model_propose: approve rejected (${built.error}) for ${pending.agent} "${pending.spec.name}": ${built.detail}`,
+    );
+    deps.injectInbound(
+      buildMentalModelProposeFailedInbound({
+        ctx,
+        stageId,
+        operatorId,
+        reason: built.detail,
+        nowMs,
+      }),
+    );
+    return { outcome: "rejected", reason: built.detail };
+  }
+
+  // Pre-register the single-tap correlation so hostd auto-approves the edit
+  // (operator already approved on this proposal card — no second card).
+  deps.registerPreApproval(pending.agent, built.diff);
+  let dispatch: ConfigEditDispatchResult;
+  try {
+    dispatch = await deps.dispatchConfigEdit({
+      agent: pending.agent,
+      diff: built.diff,
+      reason:
+        `Declare agent-proposed mental model "${pending.spec.name}"` +
+        (pending.reason ? ` — ${pending.reason}` : ""),
+    });
+  } catch (err) {
+    dispatch = { state: "error", reason: (err as Error).message };
+  } finally {
+    // Single-shot: drop the correlation whether or not hostd consumed it.
+    deps.clearPreApproval(pending.agent, built.diff);
+  }
+
+  if (dispatch.state !== "applied") {
+    deps.log?.(
+      `mental_model_propose: config edit ${dispatch.state} for ${pending.agent} "${pending.spec.name}": ${dispatch.reason}`,
+    );
+    deps.injectInbound(
+      buildMentalModelProposeFailedInbound({
+        ctx,
+        stageId,
+        operatorId,
+        reason: dispatch.reason,
+        nowMs,
+      }),
+    );
+    return { outcome: "failed", reason: dispatch.reason };
+  }
+
+  // Applied. Belt-and-suspenders ensure (reconcile already ensures via #2874;
+  // this makes the model available without waiting for the restart). Never let
+  // an ensure failure flip a successful declaration into a "failed" inbound —
+  // the model IS declared and will be ensured at reconcile regardless.
+  if (deps.ensureModel) {
+    try {
+      await deps.ensureModel(pending.spec);
+    } catch (err) {
+      deps.log?.(
+        `mental_model_propose: best-effort ensure threw (declaration still applied) for ${pending.agent} "${pending.spec.name}": ${(err as Error).message}`,
+      );
+    }
+  }
+
+  deps.injectInbound(
+    buildMentalModelProposeAppliedInbound({ ctx, stageId, operatorId, nowMs }),
+  );
+  return { outcome: "applied" };
+}