context-mode 1.0.145 → 1.0.147

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.145"
+    "version": "1.0.147"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.145",
+      "version": "1.0.147",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.145",
+  "version": "1.0.147",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",
@@ -27,5 +27,5 @@
       ]
     }
   },
-  "skills": "./.claude/skills/"
+  "skills": "./skills/"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.145",
+  "version": "1.0.147",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.145",
+  "version": "1.0.147",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.145",
+  "version": "1.0.147",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -410,13 +410,7 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 
 **Install:**
 
-1. Install context-mode globally:
-
-   ```bash
-   npm install -g context-mode
-   ```
-
-2. Add to `opencode.json` in your project root (or `~/.config/opencode/opencode.json` for global):
+1. Add to `opencode.json` in your project root (or `~/.config/opencode/opencode.json` for global):
 
    ```json
    {
@@ -427,7 +421,7 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 
    The `plugin` entry registers all 11 `ctx_*` tools natively and enables hooks — OpenCode calls context-mode's TypeScript plugin in-process, so there is no redundant stdio MCP child per session.
 
-3. *(Optional)* Copy the routing rules file. The model needs an `AGENTS.md` file for routing awareness:
+2. *(Optional)* Copy the routing rules file. The model needs an `AGENTS.md` file for routing awareness:
 
    ```bash
    cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
@@ -435,7 +429,7 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
 
    This tells the model which tools to use and which commands are blocked. Without it, hooks still enforce routing — but the model won't know *why* a command was denied.
 
-4. Restart OpenCode.
+3. Restart OpenCode.
 
 **Verify:** In the OpenCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
@@ -456,13 +450,7 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
 
 **Install:**
 
-1. Install context-mode globally:
-
-   ```bash
-   npm install -g context-mode
-   ```
-
-2. Add to `kilo.json` in your project root (or `~/.config/kilo/kilo.json` for global):
+1. Add to `kilo.json` in your project root (or `~/.config/kilo/kilo.json` for global):
 
    ```json
    {
@@ -473,13 +461,13 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
 
    The `plugin` entry registers all 11 `ctx_*` tools natively and enables hooks — KiloCode calls context-mode's TypeScript plugin in-process, so there is no redundant stdio MCP child per session.
 
-3. *(Optional)* Copy the routing rules file. KiloCode shares the OpenCode plugin architecture, so the model needs an `AGENTS.md` file for routing awareness:
+2. *(Optional)* Copy the routing rules file. KiloCode shares the OpenCode plugin architecture, so the model needs an `AGENTS.md` file for routing awareness:
 
    ```bash
    cp node_modules/context-mode/configs/opencode/AGENTS.md AGENTS.md
    ```
 
-4. Restart KiloCode.
+3. Restart KiloCode.
 
 **Verify:** In the KiloCode session, type `ctx stats`. Context-mode tools should appear and respond.
 
@@ -556,6 +544,14 @@ Full documentation: [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md)
    > remains accepted as a legacy alias in current Codex builds. Bundled plugin hooks
    > additionally require `plugin_hooks` until Codex enables plugin hooks by default.
 
+   **Custom storage location:** if Codex cannot write the adapter default storage directory, set
+   `CONTEXT_MODE_DIR` to an absolute writable root in the environment that launches Codex. Sessions
+   and stats use `<root>/sessions`; indexed content uses `<root>/content`.
+
+   ```bash
+   CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codex
+   ```
+
 3. Restart Codex CLI and verify MCP with `ctx stats`.
 
    `ctx stats` proves the plugin MCP server is installed and reachable; it does
@@ -995,7 +991,7 @@ npm install -g context-mode
 | `ctx_execute_file` | Process files in sandbox. Raw content never leaves. | 45 KB → 155 B |
 | `ctx_index` | Chunk markdown into FTS5 with BM25 ranking. | 60 KB → 40 B |
 | `ctx_search` | Query indexed content with multiple queries in one call. | On-demand retrieval |
-| `ctx_fetch_and_index` | Fetch URL, chunk and index. 24h TTL cache — repeat calls skip network. `force: true` to bypass. Pass `requests: [{url, source}, ...]` + `concurrency: 1-8` for parallel multi-URL. | 60 KB → 40 B |
+| `ctx_fetch_and_index` | Fetch URL, chunk and index. Cache reuses content within TTL (default 24h, override per-call with `ttl: <ms>`). `ttl: 0` or `force: true` to bypass. Pass `requests: [{url, source}, ...]` + `concurrency: 1-8` for parallel multi-URL. | 60 KB → 40 B |
 | `ctx_stats` | Show context savings, call counts, and session statistics. | — |
 | `ctx_doctor` | Diagnose installation: runtimes, hooks, FTS5, versions. | — |
 | `ctx_upgrade` | Upgrade to latest version from GitHub, rebuild, reconfigure hooks. | — |
@@ -1040,11 +1036,12 @@ Search results use intelligent extraction instead of truncation. Instead of retu
 
 ### TTL Cache
 
-Indexed content persists in a per-project SQLite database at `~/.context-mode/content/`. When `ctx_fetch_and_index` is called for a URL that was already indexed within the last 24 hours, the fetch is skipped entirely. The model searches the existing index directly.
+Indexed content persists in a per-project SQLite database at `~/.context-mode/content/`. When `ctx_fetch_and_index` is called for a URL that was already indexed within its TTL window, the fetch is skipped entirely and the model searches the existing index directly.
 
-- **Fresh (<24h):** Returns a cache hint (0.3KB) instead of re-fetching (48KB+). Model proceeds to `ctx_search`.
-- **Stale (>24h):** Re-fetches silently. No user action needed.
-- **`force: true`:** Bypasses cache and re-fetches regardless of TTL.
+- **Default TTL:** 24 hours. Override per-call with `ttl: <milliseconds>` (PR #666). Longer for stable specs, shorter for changelogs you want re-checked often.
+- **Cache hit (within TTL):** Returns a cache hint (~0.3KB) instead of re-fetching (48KB+). Model proceeds to `ctx_search`.
+- **Cache miss (TTL expired):** Re-fetches silently. No user action needed.
+- **`ttl: 0`** or **`force: true`:** Bypasses cache and re-fetches regardless of freshness.
 - **14-day cleanup:** Content databases and sources older than 14 days are removed on startup.
 
 This means `--continue` sessions preserve indexed docs across restarts. No re-fetching, no wasted context tokens.
@@ -1389,6 +1386,12 @@ That blocks loopback + RFC1918 + ULA in addition to the always-blocked ranges. U
 
 `tool_input` for any `mcp__*` tool call is also redacted before persistence — the regex matcher in `hooks/posttooluse.mjs` masks `authorization`, `auth_token`, `access_token`, `refresh_token`, `bearer`, `token`, `secret`, `password`, `passwd`, `pwd`, `api_key` / `apikey` / `x_api_key`, `cookie` / `set-cookie`, `signature`, `private_key`, and `client_secret` (case-insensitive, hyphen/underscore-insensitive) to `[REDACTED]` so credentials in MCP arguments don't end up in the session DB.
 
+### Storage environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CONTEXT_MODE_DIR` | Adapter default, for example `~/.codex/context-mode` or `~/.claude/context-mode` | Since v1.0.147. Absolute writable root for context-mode storage. Sessions and stats use `<root>/sessions`; indexed content uses `<root>/content`. Empty or whitespace-only values are treated as unset and shown by `ctx_doctor`; non-empty values must be absolute. `~` is not expanded. |
+
 ### Routing-guidance environment variables
 
 | Variable | Default | Purpose |

package/bin/statusline.mjs

@@ -26,10 +26,14 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
+import {
+  ensureWritableStorageDir,
+  resolveDefaultSessionDir,
+  resolveSessionStorageDir,
+} from "../hooks/session-db.bundle.mjs";
 
 // ── Analytics import — resolved relative to this script ─────────────────
 // statusline.mjs ships in `bin/`; the compiled analytics module lives in
@@ -68,10 +72,10 @@ function platform() {
 
 // Single-shot stderr warning latch — keep noise out of Claude Code's
 // statusline output even when our parent runs us repeatedly per session.
-let __winWarned = false;
+const __warnedKeys = new Set();
 function warnOnce(key, msg) {
-  if (key === "win" && __winWarned) return;
-  if (key === "win") __winWarned = true;
+  if (__warnedKeys.has(key)) return;
+  __warnedKeys.add(key);
   try { process.stderr.write(`context-mode statusline: ${msg}\n`); } catch { /* ignore */ }
 }
 
@@ -98,10 +102,19 @@ function readStdinJson() {
 }
 
 function resolveSessionDir() {
-  if (process.env.CONTEXT_MODE_SESSION_DIR) {
-    return process.env.CONTEXT_MODE_SESSION_DIR;
-  }
-  return join(homedir(), ".claude", "context-mode", "sessions");
+  return ensureWritableStorageDir(
+    resolveSessionStorageDir(() => resolveDefaultSessionDir({
+      configDir: ".claude",
+      configDirEnv: "CLAUDE_CONFIG_DIR",
+      legacySessionDirEnv: "CONTEXT_MODE_SESSION_DIR",
+      onLegacySessionDir: () => {
+        warnOnce(
+          "legacy-session-dir",
+          "CONTEXT_MODE_SESSION_DIR is deprecated; set CONTEXT_MODE_DIR to the parent context-mode root.",
+        );
+      },
+    })),
+  );
 }
 
 /**

package/build/adapters/base.d.ts

@@ -73,15 +73,20 @@ export declare abstract class BaseAdapter {
      */
     getInstructionFiles(): string[];
     /**
-     * Default: <configDir>/memory. Always absolute (configDir is absolute by
-     * contract). Adapters with a different memory dir name (e.g., codex uses
-     * "memories" plural) override this.
+     * Default: <configDir>/memory/<projectHash>. Always absolute (configDir is
+     * absolute by contract). Adapters with a different memory dir name (e.g.,
+     * codex uses "memories" plural) override this.
      *
      * Issue #649: when `CONTEXT_MODE_DATA_DIR` is set, memory follows storage
      * to `<DATA_DIR>/context-mode/memory/` since persistent memory is
      * context-mode-owned state, not platform-native config.
+     *
+     * Issue #663: when `projectDir` is supplied the path is scoped via
+     * `hashProjectDirCanonical(projectDir)` so two projects running in
+     * parallel never share auto-memory contents. When omitted (legacy
+     * callers), the unscoped path is returned for backwards compatibility.
      */
-    getMemoryDir(): string;
+    getMemoryDir(projectDir?: string): string;
     backupSettings(): string | null;
     abstract getSettingsPath(): string;
 }

package/build/adapters/base.js

@@ -37,6 +37,7 @@
 import { join, resolve } from "node:path";
 import { accessSync, copyFileSync, constants, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
+import { hashProjectDirCanonical } from "../session/db.js";
 /**
  * Universal storage-root override. Returns the resolved absolute path when
  * `CONTEXT_MODE_DATA_DIR` is set to a non-blank value, otherwise `null` so
@@ -97,19 +98,27 @@ export class BaseAdapter {
         return ["CLAUDE.md"];
     }
     /**
-     * Default: <configDir>/memory. Always absolute (configDir is absolute by
-     * contract). Adapters with a different memory dir name (e.g., codex uses
-     * "memories" plural) override this.
+     * Default: <configDir>/memory/<projectHash>. Always absolute (configDir is
+     * absolute by contract). Adapters with a different memory dir name (e.g.,
+     * codex uses "memories" plural) override this.
      *
      * Issue #649: when `CONTEXT_MODE_DATA_DIR` is set, memory follows storage
      * to `<DATA_DIR>/context-mode/memory/` since persistent memory is
      * context-mode-owned state, not platform-native config.
+     *
+     * Issue #663: when `projectDir` is supplied the path is scoped via
+     * `hashProjectDirCanonical(projectDir)` so two projects running in
+     * parallel never share auto-memory contents. When omitted (legacy
+     * callers), the unscoped path is returned for backwards compatibility.
      */
-    getMemoryDir() {
+    getMemoryDir(projectDir) {
         const override = resolveContextModeDataRoot();
-        if (override)
-            return join(override, "context-mode", "memory");
-        return join(this.getConfigDir(), "memory");
+        const base = override
+            ? join(override, "context-mode", "memory")
+            : join(this.getConfigDir(), "memory");
+        if (!projectDir)
+            return base;
+        return join(base, hashProjectDirCanonical(projectDir));
     }
     backupSettings() {
         const settingsPath = this.getSettingsPath();

package/build/adapters/codex/index.d.ts

@@ -32,7 +32,7 @@ export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
     getSettingsPath(): string;
     getSessionDir(): string;
     getInstructionFiles(): string[];
-    getMemoryDir(): string;
+    getMemoryDir(projectDir?: string): string;
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(_settings: Record<string, unknown>): void;

package/build/adapters/codex/index.js

@@ -17,6 +17,7 @@ import { readFileSync, writeFileSync, accessSync, copyFileSync, constants, mkdir
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BaseAdapter, resolveContextModeDataRoot } from "../base.js";
+import { hashProjectDirCanonical } from "../../session/db.js";
 import { resolveCodexConfigDir } from "./paths.js";
 // PreToolUse matcher: canonical Codex tool names + context-mode bare MCP tool
 // names + external MCP catch-all literal (#529, #547 hotfix).
@@ -257,16 +258,21 @@ export class CodexAdapter extends BaseAdapter {
         // Codex CLI honors AGENTS.md plus an optional override file.
         return ["AGENTS.md", "AGENTS.override.md"];
     }
-    getMemoryDir() {
+    getMemoryDir(projectDir) {
         // Codex uses "memories" (plural), not the default "memory".
         // Issue #649: honor CONTEXT_MODE_DATA_DIR for context-mode-owned
         // persistent memory while preserving the platform-native plural folder
         // name so legacy Codex tooling continues to find it when DATA_DIR is
         // unset. Under the override, layout is `<DATA_DIR>/context-mode/memories`.
+        // Issue #663: scope by projectDir hash so parallel projects can't
+        // read each other's memory.
         const override = resolveContextModeDataRoot();
-        if (override)
-            return join(override, "context-mode", "memories");
-        return join(this.getConfigDir(), "memories");
+        const base = override
+            ? join(override, "context-mode", "memories")
+            : join(this.getConfigDir(), "memories");
+        if (!projectDir)
+            return base;
+        return join(base, hashProjectDirCanonical(projectDir));
     }
     generateHookConfig(_pluginRoot) {
         return {

package/build/adapters/openclaw/index.d.ts

@@ -38,8 +38,17 @@ export declare class OpenClawAdapter extends BaseAdapter implements HookAdapter
      */
     getConfigDir(projectDir?: string): string;
     getInstructionFiles(): string[];
-    /** Absolute <projectRoot>/memory directory. */
-    getMemoryDir(): string;
+    /**
+     * Absolute <projectRoot>/memory directory.
+     *
+     * OpenClaw's `getConfigDir(projectDir)` already returns the project root,
+     * so the memory dir is naturally project-scoped per the OpenClaw
+     * convention. The `projectDir` parameter is honored for explicit
+     * resolution; without it, falls back to the implicit `process.cwd()`
+     * inside `getConfigDir`. Either way, two projects never share a path
+     * — no hash suffix needed (issue #663).
+     */
+    getMemoryDir(projectDir?: string): string;
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

package/build/adapters/openclaw/index.js

@@ -154,9 +154,18 @@ export class OpenClawAdapter extends BaseAdapter {
     getInstructionFiles() {
         return ["AGENTS.md"];
     }
-    /** Absolute <projectRoot>/memory directory. */
-    getMemoryDir() {
-        return join(this.getConfigDir(), "memory");
+    /**
+     * Absolute <projectRoot>/memory directory.
+     *
+     * OpenClaw's `getConfigDir(projectDir)` already returns the project root,
+     * so the memory dir is naturally project-scoped per the OpenClaw
+     * convention. The `projectDir` parameter is honored for explicit
+     * resolution; without it, falls back to the implicit `process.cwd()`
+     * inside `getConfigDir`. Either way, two projects never share a path
+     * — no hash suffix needed (issue #663).
+     */
+    getMemoryDir(projectDir) {
+        return join(this.getConfigDir(projectDir), "memory");
     }
     generateHookConfig(_pluginRoot) {
         // OpenClaw uses TS plugin paradigm — hooks are registered via

package/build/adapters/openclaw/plugin.js

@@ -34,6 +34,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolveContextModeDataRoot } from "../base.js";
+import { resolveSessionDbPath } from "../../session/db.js";
 import { OpenClawSessionDB } from "./session-db.js";
 import { extractEvents, extractUserEvents } from "../../session/extract.js";
 import { buildResumeSnapshot } from "../../session/snapshot.js";
@@ -83,22 +84,44 @@ function getSessionDir() {
     mkdirSync(dir, { recursive: true });
     return dir;
 }
+// Issue #645 follow-up — route through the canonical per-project
+// resolver the MCP server uses (src/server.ts ctx_stats / ctx_search
+// timeline). The previous raw `sha256(projectDir).slice(0, 16)` shape
+// produced a different file from the `<canonical-hash>.db` the server
+// reads on darwin/win32 (case-fold) and inside linked worktrees
+// (suffix). The result was silent degradation of `ctx_stats` (zero
+// history) and `ctx_search(sort: "timeline")` (sort dropped) for any
+// OpenClaw user with an uppercase character in their projectDir.
+// Mirrors the matching Pi (src/adapters/pi/extension.ts:223) and OMP
+// (src/adapters/omp/plugin.ts:90) fixes, and the opencode plugin
+// pattern (src/adapters/opencode/plugin.ts:307).
 function getDBPath(projectDir) {
-    const hash = createHash("sha256")
-        .update(projectDir)
-        .digest("hex")
-        .slice(0, 16);
-    return join(getSessionDir(), `${hash}.db`);
+    return resolveSessionDbPath({ projectDir, sessionsDir: getSessionDir() });
 }
 // ── Module-level DB singleton ─────────────────────────────
 // Shared across all register() calls (one per agent session).
 // Lazy-initialized on first register() using the first projectDir seen.
 // Uses OpenClawSessionDB for session_key mapping and rename support.
 let _dbSingleton = null;
+let _dbSingletonPath = "";
 function getOrCreateDB(projectDir) {
-    if (!_dbSingleton) {
-        const dbPath = getDBPath(projectDir);
+    // Reopen the singleton if the resolved DB path changes. Production
+    // code normally loads the plugin once per process with a single
+    // workspace, but defensive re-keying on resolved path keeps the
+    // contract honest if a host ever calls register() twice with
+    // different projectDirs, and removes a subtle test-isolation
+    // foot-gun where a stale singleton pointed at a prior test's
+    // `<hash>.db`. Mirrors the Pi/OMP fix (#645).
+    const dbPath = getDBPath(projectDir);
+    if (!_dbSingleton || _dbSingletonPath !== dbPath) {
+        if (_dbSingleton) {
+            try {
+                _dbSingleton.close();
+            }
+            catch { /* best effort */ }
+        }
         _dbSingleton = new OpenClawSessionDB({ dbPath });
+        _dbSingletonPath = dbPath;
         _dbSingleton.cleanupOldSessions(7);
     }
     return _dbSingleton;

package/build/adapters/pi/mcp-bridge.d.ts

@@ -47,6 +47,14 @@ export interface MCPCallResult {
     }>;
     isError?: boolean;
 }
+export declare class PiTextComponent {
+    private text;
+    constructor(text?: string);
+    setText(text: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+export declare function truncateAnsiLine(line: string, maxWidth: number): string;
 interface PiRenderTheme {
     bold(text: string): string;
     fg(color: string, text: string): string;

package/build/adapters/pi/mcp-bridge.js

@@ -121,7 +121,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 // self-healing the transient warm-up case.
 const MAX_INIT_RETRIES = 2;
 const INIT_RETRY_DELAY_MS = 1_000;
-class PiTextComponent {
+export class PiTextComponent {
     text;
     constructor(text = "") {
         this.text = text;
@@ -141,29 +141,132 @@ class PiTextComponent {
             .map((line) => truncateAnsiLine(line, Math.max(1, width)));
     }
 }
-const ANSI_PATTERN = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
-function truncateAnsiLine(line, maxWidth) {
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+function extractTerminalEscape(str, pos) {
+    if (pos >= str.length || str[pos] !== "\x1b")
+        return null;
+    const next = str[pos + 1];
+    // CSI sequence: ESC [ ... final-byte. Covers SGR plus cursor/control codes.
+    if (next === "[") {
+        let j = pos + 2;
+        while (j < str.length) {
+            const code = str.charCodeAt(j);
+            if (code >= 0x40 && code <= 0x7e) {
+                return { code: str.slice(pos, j + 1), length: j + 1 - pos };
+            }
+            j++;
+        }
+        return null;
+    }
+    // OSC/APC sequence: ESC ]/_ ... BEL or ST (ESC \). Stop at the FIRST
+    // terminator so OSC 8 hyperlinks don't swallow visible link text.
+    if (next === "]" || next === "_") {
+        let j = pos + 2;
+        while (j < str.length) {
+            if (str[j] === "\x07")
+                return { code: str.slice(pos, j + 1), length: j + 1 - pos };
+            if (str[j] === "\x1b" && str[j + 1] === "\\") {
+                return { code: str.slice(pos, j + 2), length: j + 2 - pos };
+            }
+            j++;
+        }
+        return null;
+    }
+    return null;
+}
+function couldBeEmoji(segment) {
+    const cp = segment.codePointAt(0) ?? 0;
+    return ((cp >= 0x1f000 && cp <= 0x1fbff) ||
+        (cp >= 0x2300 && cp <= 0x23ff) ||
+        (cp >= 0x2600 && cp <= 0x27bf) ||
+        (cp >= 0x2b50 && cp <= 0x2b55) ||
+        segment.includes("\uFE0F") ||
+        segment.includes("\u200D"));
+}
+function isZeroWidthCodePoint(cp) {
+    return (cp < 0x20 ||
+        (cp >= 0x7f && cp <= 0x9f) ||
+        (cp >= 0x300 && cp <= 0x36f) || // Combining Diacritical Marks
+        (cp >= 0x1ab0 && cp <= 0x1aff) || // Combining Diacritical Marks Extended
+        (cp >= 0x1dc0 && cp <= 0x1dff) || // Combining Diacritical Marks Supplement
+        (cp >= 0x20d0 && cp <= 0x20ff) || // Combining Diacritical Marks for Symbols
+        (cp >= 0xfe00 && cp <= 0xfe0f) || // Variation Selectors
+        (cp >= 0xfe20 && cp <= 0xfe2f) || // Combining Half Marks
+        cp === 0x200b ||
+        cp === 0x200c ||
+        cp === 0x200d ||
+        cp === 0xfeff);
+}
+function isZeroWidthGrapheme(segment) {
+    if (segment.length === 0)
+        return true;
+    for (const char of segment) {
+        if (!isZeroWidthCodePoint(char.codePointAt(0) ?? 0))
+            return false;
+    }
+    return true;
+}
+/**
+ * Returns the terminal display width of a code point.
+ * CJK ideographs, Hangul, fullwidth forms, etc. → 2; everything else → 1.
+ * Mirrors the Unicode east-asian-width "W"/"F" categories.
+ */
+function charWidth(cp) {
+    return cp >= 0x1100 && (cp <= 0x115f || // Hangul Jamo
+        (cp >= 0xa960 && cp <= 0xa97c) || // Hangul Jamo Extended-A
+        cp === 0x2329 || cp === 0x232a ||
+        (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) || // CJK
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+        (cp >= 0xd7b0 && cp <= 0xd7fb) || // Hangul Jamo Extended-B
+        (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat
+        (cp >= 0xfe10 && cp <= 0xfe19) || // Vertical forms
+        (cp >= 0xfe30 && cp <= 0xfe6f) || // CJK compat forms
+        (cp >= 0xff01 && cp <= 0xff60) || // Fullwidth forms
+        (cp >= 0xffe0 && cp <= 0xffe6) || // Fullwidth signs
+        (cp >= 0x20000 && cp <= 0x2fffd) || // CJK extensions
+        (cp >= 0x30000 && cp <= 0x3fffd) // CJK extensions B+
+    ) ? 2 : 1;
+}
+function graphemeWidth(segment) {
+    const cp = segment.codePointAt(0);
+    if (cp === undefined)
+        return 0;
+    if (isZeroWidthGrapheme(segment))
+        return 0;
+    if (couldBeEmoji(segment))
+        return 2;
+    // Regional indicator symbols render as wide emoji flags in Pi's TUI.
+    if (cp >= 0x1f1e6 && cp <= 0x1f1ff)
+        return 2;
+    return charWidth(cp);
+}
+export function truncateAnsiLine(line, maxWidth) {
     if (maxWidth <= 0)
         return "";
     let output = "";
     let visible = 0;
     let index = 0;
-    ANSI_PATTERN.lastIndex = 0;
-    for (;;) {
-        const match = ANSI_PATTERN.exec(line);
-        const end = match?.index ?? line.length;
+    while (index < line.length) {
+        const escape = extractTerminalEscape(line, index);
+        if (escape) {
+            output += escape.code;
+            index += escape.length;
+            continue;
+        }
+        let end = index + 1;
+        while (end < line.length && !extractTerminalEscape(line, end))
+            end++;
         const chunk = line.slice(index, end);
-        for (const char of chunk) {
-            if (visible >= maxWidth)
+        for (const { segment } of GRAPHEME_SEGMENTER.segment(chunk)) {
+            const w = graphemeWidth(segment);
+            if (visible + w > maxWidth)
                 return output;
-            output += char;
-            visible++;
+            output += segment;
+            visible += w;
         }
-        if (!match)
-            return output;
-        output += match[0];
-        index = ANSI_PATTERN.lastIndex;
+        index = end;
     }
+    return output;
 }
 function createContextModeCallRenderer(toolName) {
     return (_args, theme, context) => {

package/build/adapters/types.d.ts

@@ -196,8 +196,14 @@ export interface HookAdapter {
      * Directory where persistent per-user memory is stored
      * (e.g., ~/.claude/memory, ~/.codex/memories). Auto-memory scans
      * *.md files in this directory.
+     *
+     * When `projectDir` is supplied, the path MUST be project-scoped (issue
+     * #663) so two projects running in parallel cannot read each other's
+     * memory. Adapters scope via `hashProjectDirCanonical(projectDir)`.
+     * Callers that pre-date this contract may omit `projectDir`; in that
+     * case the unscoped legacy path is returned.
      */
-    getMemoryDir(): string;
+    getMemoryDir(projectDir?: string): string;
     /** Generate hook registration config for this platform. */
     generateHookConfig(pluginRoot: string): HookRegistration;
     /** Read current platform settings. */

package/build/cli.d.ts

@@ -7,6 +7,8 @@
  *   context-mode doctor                       → Diagnose runtime issues, hooks, FTS5, version
  *   context-mode upgrade                      → Fix hooks, permissions, and settings
  *   context-mode hook <platform> <event>      → Dispatch a hook script (used by platform hook configs)
+ *   CONTEXT_MODE_DIR=/abs/path context-mode   → Override sessions/content storage root
+ *     Empty/whitespace is ignored; non-empty values must be absolute.
  *
  * Platform auto-detection: CLI detects which platform is running
  * (Claude Code, Gemini CLI, OpenCode, etc.) and uses the appropriate adapter.