@remnic/core 9.3.712 → 9.3.714

package/src/access-service.ts

@@ -57,6 +57,7 @@ import {
   type CorrectionPlan,
   type CorrectionRequest,
 } from "./correction/index.js";
+import { isHandleToken } from "./recall-handles.js";
 import { createVersion } from "./page-versioning.js";
 import { WorkStorage } from "./work/storage.js";
 import {
@@ -1008,6 +1009,8 @@ export interface EngramAccessObserveRequest {
   namespace?: string;
   authenticatedPrincipal?: string;
   skipExtraction?: boolean;
+  /** Optional idempotency key (issue #1649): a retried POST with the same key is deduplicated server-side; divergent reuse is a conflict. */
+  idempotencyKey?: string;
   /**
    * Working directory of the calling agent session (issue #569 wiring).
    * When provided and no `codingContext` is attached for this session,
@@ -1067,6 +1070,8 @@ export interface EngramAccessObserveResponse {
   scopeDebug?: EngramAccessScopeDebug;
   lcmArchived: boolean;
   extractionQueued: boolean;
+  /** True when replayed from the idempotency cache (issue #1649); lets the HTTP surface skip the write-quota slot, matching memory_store replay semantics. */
+  idempotencyReplay?: boolean;
 }
 
 export interface EngramAccessLcmSearchRequest {
@@ -2523,8 +2528,8 @@ export class EngramAccessService {
     }
   }
 
-  private async handleIdempotentWrite<T extends EngramAccessWriteResponse>(options: {
-    operation: T["operation"];
+  private async handleIdempotentWrite<T extends { idempotencyReplay?: boolean }>(options: {
+    operation: string;
     idempotencyKey?: string;
     requestFingerprint: unknown;
     skip?: boolean;
@@ -4487,10 +4492,19 @@ export class EngramAccessService {
     }
   }
 
-  async memoryGet(memoryId: string, namespace?: string, principal?: string): Promise<EngramAccessMemoryResponse> {
+  async memoryGet(
+    memoryId: string,
+    namespace?: string,
+    principal?: string,
+    sessionKey?: string,
+  ): Promise<EngramAccessMemoryResponse> {
+    // Issue #1582 — accept a `[m:xxxx]` handle in place of a memory id; resolve
+    // it against the caller's session via the shared helper (rule 22). A raw id
+    // passes through unchanged, so callers unaware of handles are unaffected.
+    const resolvedId = this.resolveMemoryIdOrHandleInput(memoryId, sessionKey);
     const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const memory = await storage.getMemoryById(memoryId);
+    const memory = await storage.getMemoryById(resolvedId);
     if (!memory) {
       return { found: false, namespace: resolvedNamespace };
     }
@@ -4781,7 +4795,38 @@ export class EngramAccessService {
     return service;
   }
 
+  /**
+   * Issue #1582 — resolve a single memoryId-or-handle reference to a concrete
+   * memory id. Handles resolve against the session's recall history via the
+   * orchestrator's shared helper (rule 22); raw ids pass through unchanged. A
+   * handle that misses or is ambiguous becomes an EngramAccessInputError so the
+   * boundary maps it to a 400 (rule 34/51 — list candidates, never guess).
+   */
+  private resolveMemoryIdOrHandleInput(
+    ref: string,
+    sessionKey: string | undefined,
+  ): string {
+    if (!isHandleToken(ref)) return ref;
+    try {
+      return this.orchestrator.resolveMemoryIdOrHandle(ref, sessionKey);
+    } catch (err) {
+      throw new EngramAccessInputError(
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
   async correctionPlan(request: CorrectionRequest): Promise<CorrectionPlan> {
+    // Issue #1582 — resolve any `[m:xxxx]` handle in targetIds to its memory
+    // id against the caller's session BEFORE planning, so the planner only ever
+    // sees concrete ids. One shared resolve path (rule 22); a handle that
+    // misses or collides is an explicit input error, never silent (rule 34/51).
+    if (request.targetIds?.some((id) => isHandleToken(id))) {
+      const targetIds = request.targetIds.map((id) =>
+        this.resolveMemoryIdOrHandleInput(id, request.sessionKey),
+      );
+      return this.correctionService().plan({ ...request, targetIds });
+    }
     return this.correctionService().plan(request);
   }
 
@@ -5700,7 +5745,63 @@ export class EngramAccessService {
     return shapeMemorySummary(memory, baseDir, disclosure, rawExcerpts);
   }
 
-  async observe(request: EngramAccessObserveRequest): Promise<EngramAccessObserveResponse> {
+  async observe(
+    request: EngramAccessObserveRequest,
+    hooks?: { enforceWriteQuota?: () => void | Promise<void> },
+  ): Promise<EngramAccessObserveResponse> {
+    // Issue #1649: dedup retried observe POSTs server-side. A retry with the
+    // same `idempotencyKey` replays the cached response and skips every side
+    // effect (LCM/extraction/objective-state); divergent payload OR principal
+    // reuse is a conflict (fingerprint folds in authenticatedPrincipal, so a
+    // cross-identity replay can never be silent). `enforceWriteQuota` runs as
+    // `beforeExecute` inside the lock — only on a real miss — so a response-lost
+    // retry never 429s even when the first attempt filled the window (#1434).
+    //
+    // The fingerprint folds in the EFFECTIVE coding context (#1649 codex P2):
+    // runObserve's scope can be derived from the session's ATTACHED coding
+    // context (which takes PRECEDENCE over per-call cwd/projectTag per
+    // resolveMemoryScopePlan), so neither cwd/projectTag NOR the raw ambient
+    // context alone fully captures the effective scope. The effective context
+    // is computed the SAME way resolveMemoryScopePlan does — session-attached
+    // first, per-call cwd/projectTag fallback — but READ-ONLY: it does NOT seed
+    // the session, so a conflict/quota-rejection path leaves no orphaned binding.
+    // The value is stable across replays because resolveMemoryScopePlan's
+    // seeding writes the IDENTICAL context that resolveCodingContextFromOptions
+    // derives — so getCodingContextForSession returns the same object on the
+    // replay as resolveCodingContextFromOptions returned on the first call.
+    // Only computed when a key is present; non-keyed observes skip the work.
+    const idempotencyKey = request.idempotencyKey?.trim();
+    let effectiveCodingContext: CodingContext | null | undefined;
+    if (idempotencyKey && !(typeof request.namespace === "string" && request.namespace.trim().length > 0)) {
+      // Explicit namespace pins the scope (resolveMemoryScopePlan returns early),
+      // so the coding context is irrelevant — skip it to avoid false conflicts
+      // when the session context changes under a namespace-pinned observe.
+      // resolveCodingContextFromOptions self-gates on projectScope (no scattered
+      // config read here).
+      effectiveCodingContext =
+        (typeof this.orchestrator.getCodingContextForSession === "function"
+          ? this.orchestrator.getCodingContextForSession(request.sessionKey)
+          : null) ?? (await this.resolveCodingContextFromOptions(request));
+    }
+    return this.handleIdempotentWrite<EngramAccessObserveResponse>({
+      operation: "observe",
+      idempotencyKey: request.idempotencyKey,
+      requestFingerprint: {
+        sessionKey: request.sessionKey,
+        messages: request.messages,
+        namespace: request.namespace,
+        skipExtraction: request.skipExtraction,
+        authenticatedPrincipal: request.authenticatedPrincipal,
+        cwd: request.cwd,
+        projectTag: request.projectTag,
+        effectiveCodingContext: effectiveCodingContext ?? null,
+      },
+      beforeExecute: hooks?.enforceWriteQuota,
+      execute: () => this.runObserve(request),
+    });
+  }
+
+  private async runObserve(request: EngramAccessObserveRequest): Promise<EngramAccessObserveResponse> {
     if (!request.sessionKey || typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
       throw new EngramAccessInputError("sessionKey is required and must be a non-empty string");
     }

package/src/access-surface-catalog.test.ts

@@ -49,7 +49,9 @@ import {
 // alongside the other GET list routes (baseline 80 from #1525 + 1 = 81). Also a
 // catalog-completeness correction: POST /engram/v1/memories (operation memory_store)
 // was always live but omitted from HTTP_ROUTES — it is migrated, so no count change.
-const UNMIGRATED_HANDLER_BASELINE = 81;
+// #1583 remnic chat adds memory_chat — an unmigrated handler dispatched to
+// processChatMessage (carries user input; not a boundary operation) → 81 + 1 = 82.
+const UNMIGRATED_HANDLER_BASELINE = 82;
 
 // Keep the import live — `getOperation` is the call surfaces use at dispatch
 // time; referencing it here pins the registry's lookup contract.
@@ -72,7 +74,7 @@ function shortToolName(advertised: string): string {
 /** Spin up a server with emitLegacyTools=true and read the deduped short names. */
 async function liveMcpToolShortNames(): Promise<ReadonlySet<string>> {
   const stub = { briefingEnabled: true } as unknown as EngramAccessService;
-  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true, codegraphVisible: true, sessionDeltaVisible: true });
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true, codegraphVisible: true, sessionDeltaVisible: true, chatVisible: true });
   const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
   const result = (response as { result?: { tools?: Array<{ name: string }> } }).result;
   const names = new Set<string>();

package/src/access-surface-catalog.ts

@@ -75,6 +75,9 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   // Correction Contract (issue #1580) — one plan/apply pipeline.
   { tool: "memory_correct_plan", operation: "memory_correct_plan" },
   { tool: "memory_correct_apply", operation: "memory_correct_apply" },
+  // Conversational memory inspection + correction (issue #1583) — unmigrated
+  // handler dispatched to processChatMessage (not a boundary operation).
+  { tool: "memory_chat", operation: null },
   { tool: "coding_decision", operation: "coding_decision" },
   { tool: "coding_architecture", operation: "coding_architecture" },
   // codegraph parity tools (issue #1554)
@@ -229,6 +232,8 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   // streaming lifecycle is owned by the HTTP transport (handleGraphEventsSSE).
   { method: "GET", pathname: "/engram/v1/offline-sync/snapshot-stream", operation: "offline_sync_snapshot_stream" },
   { method: "GET", pathname: "/engram/v1/graph/events", operation: "graph_events" },
+  { method: "POST", pathname: "/engram/v1/chat/message", operation: "chat_message" },
+  { method: "GET", pathname: "/engram/v1/chat/events/:id", operation: "chat_events" },
 ];
 
 /**

package/src/active-memory-bridge.test.ts

@@ -311,3 +311,75 @@ test("getMemoryForActiveMemory ignores explicit namespace overrides when namespa
   assert.equal(result.id, "shared-memory");
   assert.equal(result.text, "shared text");
 });
+
+
+test("getMemoryForActiveMemory resolves a [m:xxxx] handle via the orchestrator resolver (#1582)", async () => {
+  const resolved: string[] = [];
+  const orchestrator = {
+    config: { namespacesEnabled: false },
+    resolveSelfNamespace: () => "readable-session",
+    getStorageForNamespace: async () => ({
+      getMemoryById: async (id: string) =>
+        id === "fact-1" ? ({ content: "text", frontmatter: {} } as never) : null,
+    }),
+    resolveMemoryIdOrHandle: (ref: string) => {
+      resolved.push(ref);
+      return "fact-1";
+    },
+  };
+
+  const result = await getMemoryForActiveMemory(
+    orchestrator as never,
+    "[m:4f2a]",
+    { sessionKey: "session-x" },
+  );
+  assert.deepEqual(resolved, ["[m:4f2a]"]);
+  assert.equal(result.error, undefined);
+  assert.equal(result.id, "fact-1");
+});
+
+test("getMemoryForActiveMemory passes a raw id through unchanged (no resolver call) (#1582)", async () => {
+  const orchestrator = {
+    config: { namespacesEnabled: false },
+    resolveSelfNamespace: () => "readable-session",
+    getStorageForNamespace: async () => ({
+      getMemoryById: async (id: string) =>
+        id === "fact-1" ? ({ content: "text", frontmatter: {} } as never) : null,
+    }),
+    resolveMemoryIdOrHandle: () => {
+      throw new Error("resolver must not be called for a raw id");
+    },
+  };
+
+  const result = await getMemoryForActiveMemory(
+    orchestrator as never,
+    "fact-1",
+    { sessionKey: "session-x" },
+  );
+  assert.equal(result.id, "fact-1");
+});
+
+test("getMemoryForActiveMemory returns not_found when a handle cannot be resolved (#1582, cursor review)", async () => {
+  // A missing session key, unknown handle, or ambiguous handle makes the
+  // orchestrator resolver THROW. The active-memory get path must yield the SAME
+  // not_found contract a bad raw id gets — not propagate the throw and crash an
+  // OpenClaw active-memory caller.
+  const orchestrator = {
+    config: { namespacesEnabled: false },
+    resolveSelfNamespace: () => "readable-session",
+    getStorageForNamespace: async () => ({
+      getMemoryById: async () => null,
+    }),
+    resolveMemoryIdOrHandle: () => {
+      throw new Error("Memory handle [m:dead] cannot be resolved without a session key.");
+    },
+  };
+
+  const result = await getMemoryForActiveMemory(
+    orchestrator as never,
+    "[m:dead]",
+    // No sessionKey → resolver throws "without a session key".
+    {},
+  );
+  assert.equal(result.error, "not_found");
+});

package/src/active-memory-bridge.ts

@@ -1,6 +1,7 @@
 import { canReadNamespace, defaultNamespaceForPrincipal, resolvePrincipal } from "./namespaces/principal.js";
 import type { MemoryFile, PluginConfig } from "./types.js";
 import { collapseWhitespace, truncateCodePointSafe } from "./whitespace.js";
+import { isHandleToken } from "./recall-handles.js";
 
 export interface ActiveMemoryMetadata {
   type?: "fact" | "preference";
@@ -192,6 +193,8 @@ export async function getMemoryForActiveMemory(
     storage?: {
       getMemoryById?: (id: string) => Promise<MemoryFile | null>;
     };
+    /** Issue #1582 — resolves a `[m:xxxx]` handle to a memory id (orchestrator). */
+    resolveMemoryIdOrHandle?: (ref: string, sessionKey?: string) => string;
   },
   id: string,
   options: {
@@ -210,10 +213,26 @@ export async function getMemoryForActiveMemory(
       ? await orchestrator.getStorageForNamespace(namespace)
       : orchestrator.storage;
 
-  const memory = await storage?.getMemoryById?.(id);
+  // Issue #1582 — resolve a `[m:xxxx]` handle to its memory id against the
+  // caller's session before the storage read, so OpenClaw active-memory agents
+  // can cite injected handles through the SAME shared path as memory_get /
+  // correction (cursor review). Raw ids pass through unchanged.
+  //
+  // A handle that misses, collides, or has no session key becomes not_found —
+  // the SAME behavior a bad raw id yields below — instead of throwing, so an
+  // active-memory caller gets a uniform not-found contract (cursor review).
+  let resolvedId = id;
+  if (isHandleToken(id) && typeof orchestrator.resolveMemoryIdOrHandle === "function") {
+    try {
+      resolvedId = orchestrator.resolveMemoryIdOrHandle(id, options.sessionKey);
+    } catch {
+      return { error: "not_found" };
+    }
+  }
+  const memory = await storage?.getMemoryById?.(resolvedId);
   if (!memory) return { error: "not_found" };
   return {
-    id,
+    id: resolvedId,
     text: collapseWhitespace(memory.content),
     metadata: buildActiveMemoryMetadataFromMemory(memory),
   };

package/src/chat/chat-cli.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Chat CLI surface tests (issue #1583 PR 2).
+ *
+ * Tests the non-TTY `--once` scripting mode and the no-LLM error path.
+ * Interactive readline mode is exercised via the golden-transcript pattern
+ * in chat-engine.test.ts (the engine loop is identical); here we cover the
+ * CLI's own input/output contract.
+ */
+
+import { strict as assert } from "node:assert";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import type { EngramAccessService } from "../access-service.js";
+import { parseConfig } from "../config.js";
+import { runChatCli } from "./chat-cli.js";
+import { DEFAULT_CHAT_CONFIG } from "./chat-config.js";
+
+/** Capture stdout.write for the duration of `fn`. */
+async function captureStdout(fn: () => Promise<void>): Promise<string> {
+  const chunks: string[] = [];
+  const original = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk: unknown) => {
+    chunks.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+  try {
+    await fn();
+  } finally {
+    process.stdout.write = original;
+  }
+  return chunks.join("");
+}
+
+function makeService(overrides: Partial<EngramAccessService> = {}): EngramAccessService {
+  return {
+    fallbackLlmRef: {
+      chatCompletion: async () => ({ content: "Based on memory_search, your database uses PostgreSQL [id: abc]." }),
+    },
+    configRef: parseConfig({ memoryDir: "/tmp/chat-cli-test", chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    memoryDir: "/tmp/chat-cli-test",
+    memoryGet: () => Promise.resolve(null),
+    memoryTimeline: () => Promise.resolve([]),
+    memorySearch: () => Promise.resolve({ results: [{ path: "mem/abc.md", score: 0.9, snippet: "PostgreSQL" }], count: 1 }),
+    recallExplain: () => Promise.resolve(null),
+    entityGet: () => Promise.resolve(null),
+    memoryProfile: () => Promise.resolve({}),
+    memoryEntitiesList: () => Promise.resolve({ items: [] }),
+    memoryQuestions: () => Promise.resolve({ items: [] }),
+    reviewQueue: () => Promise.resolve({ items: [] }),
+    ...overrides,
+  } as unknown as EngramAccessService;
+}
+
+async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), "chat-cli-"));
+  try { return await fn(dir); } finally { await rm(dir, { recursive: true, force: true }); }
+}
+
+test("CLI --once mode: prints the assistant reply and session id", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const out = await captureStdout(() =>
+      runChatCli({
+        service,
+        config: service.configRef!.chat,
+        memoryDir,
+        once: true,
+        input: "what database do I use?",
+      }),
+    );
+    assert.ok(out.includes("PostgreSQL"), `expected reply in stdout, got: ${out}`);
+    assert.ok(out.includes("[session:"), "session id should be printed for --once mode");
+  });
+});
+
+test("CLI --once mode: no input → tagged error", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const out = await captureStdout(() =>
+      runChatCli({
+        service,
+        config: service.configRef!.chat,
+        memoryDir,
+        once: true,
+        input: "   ",
+      }),
+    );
+    assert.ok(out.includes("[error]"), `expected error tag, got: ${out}`);
+  });
+});
+
+test("CLI: no LLM available → tagged error reply", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      fallbackLlmRef: null,
+      localLlmRef: null,
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const out = await captureStdout(() =>
+      runChatCli({
+        service,
+        config: service.configRef!.chat,
+        memoryDir,
+        once: true,
+        input: "hi",
+      }),
+    );
+    assert.ok(out.includes("[error]"), `expected error tag, got: ${out}`);
+    assert.ok(out.toLowerCase().includes("llm") || out.toLowerCase().includes("model"), "should mention model availability");
+  });
+});
+
+test("CLI: resumes an existing session by id", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    // First message creates a session.
+    const first = await captureStdout(() =>
+      runChatCli({ service, config: service.configRef!.chat, memoryDir, once: true, input: "hello" }),
+    );
+    const sessionMatch = /\[session: ([^\]]+)\]/.exec(first);
+    assert.ok(sessionMatch, "first run should print a session id");
+    const sessionId = sessionMatch[1]!;
+    // Second message resumes it.
+    const second = await captureStdout(() =>
+      runChatCli({ service, config: service.configRef!.chat, memoryDir, once: true, input: "again", sessionId }),
+    );
+    assert.ok(second.includes("[session:"), "resumed run should also print a session id");
+  });
+});

package/src/chat/chat-cli.ts

@@ -0,0 +1,206 @@
+/**
+ * `remnic chat` CLI implementation (issue #1583 PR 2).
+ *
+ * Interactive readline loop that streams assistant text and renders diffs.
+ * Supports `--daemon-url` for remote daemon over HTTP (Tailscale fleet case)
+ * and `--once` / non-TTY mode for scripting/tests
+ * (`echo "question" | remnic chat --once`).
+ *
+ * This module is imported by cli.ts with a single thin registration line —
+ * the god-file ratchet (#1520) tracks cli.ts LOC.
+ */
+
+import readline from "node:readline";
+import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
+
+import type { EngramAccessService } from "../access-service.js";
+import type { PluginConfig } from "../types.js";
+import type { ChatConfig } from "./chat-types.js";
+import type { ChatTurnResult } from "./chat-types.js";
+import { ChatEngine } from "./chat-engine.js";
+import { createProductionChatLlmAdapter } from "./chat-llm.js";
+import { createChatExecutor } from "./chat-executor.js";
+import {
+  createChatSession,
+  loadChatSession,
+  appendTranscriptEntry,
+  sessionBelongsToPrincipal,
+} from "./chat-session.js";
+import { isConfirmationMessage } from "./chat-engine.js";
+
+/**
+ * Read all of stdin to a UTF-8 string (non-TTY / scripting mode).
+ */
+async function readAllStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+export interface ChatCliOptions {
+  service: EngramAccessService;
+  config: ChatConfig | undefined;
+  memoryDir: string;
+  principal?: string;
+  namespace?: string;
+  sessionKey?: string;
+  /** Existing chat session id to resume. */
+  sessionId?: string;
+  /** Run a single message and exit (non-TTY / scripting mode). */
+  once?: boolean;
+  /** Input text for --once mode. */
+  input?: string;
+}
+
+/**
+ * Run the chat CLI.  In interactive mode, enters a readline loop.  In
+ * `--once` mode, processes a single message and prints the reply to stdout.
+ */
+export async function runChatCli(opts: ChatCliOptions): Promise<void> {
+  if (!opts.config?.enabled) {
+    const msg = "[error] Remnic Chat is disabled. Set \"chat.enabled\": true in your config to enable it.";
+    if (opts.once) { process.stdout.write(msg + "\n"); return; }
+    console.error(msg);
+    return;
+  }
+  const config = opts.config;
+  const llm = opts.service.fallbackLlmRef ?? opts.service.localLlmRef;
+  if (!llm) {
+    const msg = "[error] No LLM model is available. Configure a local or cloud model to use Remnic Chat.";
+    if (opts.once) {
+      process.stdout.write(msg + "\n");
+      return;
+    }
+    console.error(msg);
+    return;
+  }
+
+  const adapter = createProductionChatLlmAdapter(llm as {
+    chatCompletion(
+      messages: Array<{ role: string; content: string }>,
+      options?: { model?: string; signal?: AbortSignal },
+    ): Promise<{ content: string } | null>;
+  });
+
+  // Load or create session FIRST so the executor inherits the session's
+  // stored namespace/sessionKey scope — a resumed session created via MCP
+  // must not lose its scope binding (codex review, Thread 19).
+  let session;
+  if (opts.sessionId) {
+    session = await loadChatSession(opts.memoryDir, opts.sessionId);
+    if (!session) {
+      console.error(`Chat session not found: ${opts.sessionId}`);
+      return;
+    }
+    if (!sessionBelongsToPrincipal(session, opts.principal)) {
+      console.error("Access denied: this chat session belongs to a different principal.");
+      return;
+    }
+  } else {
+    session = await createChatSession(opts.memoryDir, {
+      principal: opts.principal,
+      sessionKey: opts.sessionKey,
+      namespace: opts.namespace,
+    });
+  }
+
+  const executor = createChatExecutor({
+    service: opts.service,
+    principal: opts.principal,
+    ...(session.namespace ? { namespace: session.namespace } : {}),
+    ...(session.sessionKey ? { sessionKey: session.sessionKey } : {}),
+  });
+
+  const engine = new ChatEngine({
+    llm: adapter,
+    executor,
+    maxToolCallsPerTurn: config.maxToolCallsPerTurn,
+    ...(config.model ? { model: config.model } : {}),
+    correctionAvailable: false,
+    scopeInspectAvailable: false,
+  });
+
+  // ── Non-TTY / --once mode ───────────────────────────────────────────
+  if (opts.once) {
+    // Read stdin here (not in cli.ts) so the god-file wiring stays thin.
+    const message = opts.input ?? await readAllStdin();
+    if (!message.trim()) {
+      process.stdout.write("[error] No input provided.\n");
+      return;
+    }
+    const userEntry = await appendTranscriptEntry(opts.memoryDir, session.id, {
+      role: "user",
+      content: message,
+    });
+    session.transcript.push(userEntry);
+    const result = await engine.processMessage(message, session);
+    const assistantEntry = await appendTranscriptEntry(opts.memoryDir, session.id, {
+      role: "assistant",
+      content: result.reply,
+    });
+    session.transcript.push(assistantEntry);
+    process.stdout.write(result.reply + "\n");
+    process.stdout.write(`[session: ${session.id}]\n`);
+    return;
+  }
+
+  // ── Interactive mode ────────────────────────────────────────────────
+  console.log(`Remnic Chat — session ${session.id}`);
+  console.log("Type your message. Type 'exit' or Ctrl-C to quit.\n");
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "you> ",
+  });
+
+  rl.prompt();
+
+  let inFlight: Promise<void> = Promise.resolve();
+  rl.on("line", (line: string) => {
+    const message = line.trim();
+    if (!message) {
+      rl.prompt();
+      return;
+    }
+    if (message === "exit" || message === "quit") {
+      rl.close();
+      return;
+    }
+    // Serialize turns: a second line waits for the first to finish so
+    // transcript updates and engine state don't race on the same session.
+    inFlight = inFlight.then(async () => {
+    const userEntry = await appendTranscriptEntry(opts.memoryDir, session!.id, {
+      role: "user",
+      content: message,
+    });
+    session!.transcript.push(userEntry);
+
+    const result = await engine.processMessage(message, session!);
+    const assistantEntry = await appendTranscriptEntry(opts.memoryDir, session!.id, {
+      role: "assistant",
+      content: result.reply,
+    });
+    session!.transcript.push(assistantEntry);
+
+    console.log(`\nassistant> ${result.reply}\n`);
+    if (result.pendingPlan) {
+      console.log(`[pending plan: ${result.pendingPlan.planId} — reply 'apply' to confirm]\n`);
+    }
+    if (result.skippedTools && result.skippedTools.length > 0) {
+      console.log(`[note: ${result.skippedTools.length} tool(s) skipped due to budget]\n`);
+    }
+    rl.prompt();
+    }).catch(() => {
+      console.error("[error] An unexpected error occurred during this turn. Please try again.");
+      rl.prompt();
+    });
+  });
+
+  await new Promise<void>((resolve) => {
+    rl.on("close", resolve);
+  });
+}