open-memex 0.4.0-alpha.7 → 0.4.0

package/dist/providers/git.js

@@ -0,0 +1,142 @@
+/**
+ * GitProvider — the git transport for repo-synced shared scopes (§9, D12).
+ *
+ * Git is a transport, not the product boundary: this provider moves the
+ * in-repo memory dir (`.ai/open-memex/`) between the local checkout and the
+ * remote. It never touches the appdata outbox, never force-pushes, never
+ * auto-merges a divergence — those are human decisions.
+ *
+ * Hard rules (from §9 / D12 / D36):
+ * - pull is explicit (`open-memex pull`); pull = fetch + fast-forward only.
+ * - push is explicit (`open-memex push`); the tool never pushes on its own.
+ * - a failed pull/push fails with a clear message and leaves no broken state.
+ */
+import { execFileSync } from "node:child_process";
+function fail(msg) {
+    throw new Error(`[open-memex] ${msg}`);
+}
+/** Run git, raising a readable error. `timeoutMs` guards network calls. */
+function git(root, args, timeoutMs = 0) {
+    try {
+        return execFileSync("git", args, {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+        }).trim();
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ETIMEDOUT")
+            fail(`git ${args.join(" ")} timed out — remote unreachable?`);
+        const detail = (err.stderr ?? err.message ?? "").trim().split("\n")[0];
+        fail(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+    }
+}
+const FETCH_TIMEOUT_MS = 30_000;
+export class GitProvider {
+    name = "git";
+    capabilities = {
+        read: true,
+        write: true,
+        delete: false,
+        history: true,
+        sync: "bidirectional",
+    };
+    /** Current branch + upstream, or a clear failure when git can't answer. */
+    status(root) {
+        git(root, ["rev-parse", "--git-dir"]);
+        const branch = git(root, ["branch", "--show-current"]) ||
+            git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+        let upstream = null;
+        try {
+            upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+        }
+        catch {
+            upstream = null;
+        }
+        let ahead = 0;
+        let behind = 0;
+        if (upstream) {
+            const counts = git(root, ["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+            const [a, b] = counts.split(/\s+/).map((n) => parseInt(n, 10));
+            ahead = Number.isFinite(a) ? a : 0;
+            behind = Number.isFinite(b) ? b : 0;
+        }
+        const remote = upstream ? upstream.split("/")[0] : null;
+        return { branch, upstream, remote, ahead, behind };
+    }
+    /**
+     * Explicit pull: fetch + fast-forward only (§9).
+     * Diverged branches are NOT merged — the user resolves them by hand.
+     */
+    pull(root) {
+        const st = this.status(root);
+        if (!st.upstream || !st.remote) {
+            fail(`branch ${st.branch} has no upstream — set one with ` +
+                `\`git push -u <remote> ${st.branch}\`, then pull again`);
+        }
+        git(root, ["fetch", st.remote], FETCH_TIMEOUT_MS);
+        const before = git(root, ["rev-parse", "HEAD"]);
+        const remoteSha = git(root, ["rev-parse", st.upstream]);
+        if (before === remoteSha) {
+            return {
+                at: new Date().toISOString(),
+                branch: st.branch,
+                remote: st.remote,
+                before,
+                after: before,
+                fastForwarded: false,
+            };
+        }
+        // Fast-forward is possible iff HEAD is an ancestor of the upstream.
+        let ffPossible = false;
+        try {
+            git(root, ["merge-base", "--is-ancestor", "HEAD", st.upstream]);
+            ffPossible = true;
+        }
+        catch {
+            ffPossible = false;
+        }
+        if (!ffPossible) {
+            fail(`branch ${st.branch} has diverged from ${st.upstream} — ` +
+                `open-memex never force-merges; resolve it by hand ` +
+                `(rebase or merge), then pull again`);
+        }
+        git(root, ["merge", "--ff-only", st.upstream]);
+        const after = git(root, ["rev-parse", "HEAD"]);
+        return {
+            at: new Date().toISOString(),
+            branch: st.branch,
+            remote: st.remote,
+            before,
+            after,
+            fastForwarded: true,
+        };
+    }
+    /** Explicit push of the current branch. Never called automatically. */
+    push(root) {
+        const st = this.status(root);
+        if (!st.remote) {
+            // No upstream yet: push explicitly sets it (-u), still user-invoked.
+            const remotes = git(root, ["remote"]);
+            const remote = remotes.split("\n").map((r) => r.trim()).filter(Boolean)[0];
+            if (!remote)
+                fail("no git remote configured — add one before pushing");
+            git(root, ["push", "-u", remote, st.branch], FETCH_TIMEOUT_MS);
+            return {
+                at: new Date().toISOString(),
+                branch: st.branch,
+                remote,
+                head: git(root, ["rev-parse", "HEAD"]),
+            };
+        }
+        git(root, ["push", st.remote, st.branch], FETCH_TIMEOUT_MS);
+        return {
+            at: new Date().toISOString(),
+            branch: st.branch,
+            remote: st.remote,
+            head: git(root, ["rev-parse", "HEAD"]),
+        };
+    }
+}

package/docs/CURATOR.md

@@ -0,0 +1,59 @@
+# Curator Convention
+
+The **curator** is the human who tends a project's shared memory. It is a
+documented convention, not a permission system — anyone on the team can act
+as curator; the tool records *who* did *what* (the audit trail), it doesn't
+decide who is *allowed* to.
+
+## What the curator does
+
+1. **Triage proposals.** `open-memex propose` puts memories up for review.
+   The curator reads them, then `open-memex promote <id>` to approve or
+   `open-memex promote <id> --reject` to send back, with `--note` saying why.
+2. **Resolve conflicts.** `open-memex resolve` lists file-level and semantic
+   conflicts. The curator merges or picks a winner — Core never silently
+   resolves a semantic conflict; both sides stay `active` until a human
+   decides.
+3. **Keep the garden.** Deprecate what's stale (`open-memex status <id>
+   deprecated`), supersede what's been replaced, forget what's noise.
+   Shared memory rots without pruning.
+4. **Watch the pipeline.** `open-memex sync-status` shows the outbox, review
+   states, and uncommitted files; `open-memex pr-status --apply` maps the
+   GitHub PR state back onto `review_state`.
+
+## Admission bar
+
+Approve a memory when it is:
+
+- **True** — you believe it, or it cites something verifiable.
+- **Durable** — it will still matter in a month. Chat logs are not memories.
+- **Scoped right** — project knowledge in project scope; personal stuff stays
+  personal (personal memories are never the curator's business).
+- **Well-typed** — `type` says what it IS (`decision`, `gotcha`, `lesson`…),
+  `tags` say what it's ABOUT.
+
+Send back (don't silently fix) when it's vague, duplicated, or belongs in
+`docs/` as formal documentation instead — memory is the fast-changing long
+tail, `docs/` is the slow-changing core.
+
+## What the curator does NOT do
+
+- **Never rewrite someone else's memory in place.** Propose a superseding
+  memory instead — the chain (`supersedes` / `superseded_by`) is the audit
+  trail.
+- **Never approve their own proposals silently in team mode.** That's what
+  `--local-approve` is for — solo projects only.
+- **Never pull rank with the tool.** If the team disagrees with a call, the
+  disagreement itself is worth a memory.
+
+## Cadence
+
+There is no required cadence. A workable default: triage proposals at the
+end of each work chunk (the same checkpoint where §3.5 distillation runs),
+and do a pruning pass when `sync-status` starts feeling noisy.
+
+## Solo mode
+
+No team, no curator needed. `open-memex propose --local-approve` records
+`approved_by: self` and skips the PR. You are the curator, the proposer,
+and the gardener — the same hygiene rules apply, just faster.

package/docs/TEST-PLAN.md

@@ -0,0 +1,72 @@
+# OpenMemex 测试计划（v0.4.0-alpha.10）
+
+> 自动化部分：`node --experimental-strip-types scripts/test-full.ts`
+> 62 项全过（26 个 CLI 命令 + 11 个 MCP tool），隔离环境运行，不碰真实数据。
+> 下面是机器/账号相关的部分，需要 Stone 在真机上过一遍。
+
+## A. Windows 真机 + VS Code Copilot
+
+- [ ] `npm i -g open-memex@alpha` 全局安装，`open-memex --version` 显示正确版本
+- [ ] 在一个真实项目目录跑 `open-memex init`（不加 `--yes`，走一遍交互）
+  - 确认 `.vscode/mcp.json` 生成，`~/.copilot/copilot-instructions.md` 合并写入（不覆盖已有内容）
+- [ ] 重启 VS Code，Copilot Chat 里问 "what do you remember about this project?"
+  - 预期：MCP 连接成功，能调用 memory_search
+- [ ] `open-memex add "windows 真机测试" --type fact`，再让 Copilot 搜出来
+- [ ] 中文路径项目、中文记忆内容各试一条（CJK 索引）
+
+## B. 真实 GitHub PR 全流程（review 工作流）
+
+在一个真实 repo 里：
+
+- [ ] `open-memex add "PR流程测试" --scope personal` → `propose --to project` → `sync-status` 看到 outbox draft
+- [ ] `open-memex submit <id>`（留在当前分支，本地 commit）
+- [ ] 手动 `git push` + 开 PR
+- [ ] 在 PR 里点 Approve → 回来跑 `open-memex pr-status`（先看 report），再 `pr-status --apply`
+  - 预期：memory 变成 approved，`approved_by` 是 reviewer
+- [ ] 找一条让 reviewer 点 "Request changes" → `pr-status --apply`
+  - 预期：只给 suggestion，**不**自动 reject（D32）
+- [ ] Merge PR → `pr-status --apply`
+  - 预期：memory 变成 published
+- [ ] `open-memex resolve` 无冲突时输出 "(no conflicted memory files)"
+
+## C. 其他编辑器 MCP 集成
+
+- [ ] Cursor：`open-memex mcp --print-config cursor` → 贴到 Cursor MCP 配置 → 能连上
+- [ ] opencode：`open-memex init --client opencode` → `opencode.jsonc` 生效
+- [ ] Claude Code：`open-memex mcp --print-config claude` 给出的 `claude mcp add` 命令能跑通
+
+## D. 跨机迁移（export/import 真实场景）
+
+- [ ] 本机：`open-memex export --all -o migration.tar.gz`（含 private 的全量）
+- [ ] 本机：`open-memex export -o share.tar.gz`（默认排除 private）→ 解包检查 manifest，确认没有 visibility:private 的条目
+- [ ] 另一台机器：`open-memex import migration.tar.gz --dry-run` 先看预览，再正式 import
+  - 预期：project memory re-key 到新机器的 project scope，进 outbox 当 draft；personal 进 personal
+- [ ] 同一个 bundle 导两次 → 第二次 "skipped N identical"
+
+## E. Agent 会话行为（D42 / §3.5）
+
+- [ ] 新开一个 agent 会话（MCP 已接），看 initialize 返回的 instructions 里有没有 session-start 同步指引
+- [ ] 对 agent 说 "sync memory" / "同步记忆"
+  - 预期：agent 走 memory_status → 摘要 → 问你要同步哪条（而不是直接翻 appdata）
+- [ ] 长对话中 agent 是否在检查点提议蒸馏（§3.5），提议后是否等你批准才保存（D42）
+
+## F. 冲突解决（3-way merge）
+
+- [ ] 两台机器（或两个 clone）同时改同一条 project memory，各自 submit + push，一边 pull 制造 diverged
+  - 预期：`open-memex pull` 明确报错退出，不自动 merge
+- [ ] 手动 merge 后 `open-memex resolve <id>` 看 3-way 展示（base/outbox/repo），手动解决
+
+## G. 同事 pilot（1–2 人，Stone 私下选）
+
+- [ ] 对方 `npx open-memex@alpha init` 走通
+- [ ] 对方能 propose → 你这边能看到 PR → promote 流程走通
+- [ ] 收集反馈：哪里卡、哪里不符合直觉
+
+## H. 已知问题观察
+
+- [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）
+- [ ] `memory_list` 默认只列 project scope 是否符合预期（Stone 已定保持现状）
+
+---
+
+测试中发现的 bug 直接记到 GitHub issue；改完后更新本文档的复选框。

package/docs/V2-DESIGN.md

@@ -534,8 +534,10 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 | atlaso-labs/codex | Codex marketplace | long-term memory plugin for Codex (hooks + MCP + cloud-sync upsell) | **direct comparable** for a future Codex plugin; their cloud upsell vs our local-first |
 
 (Star counts / funding as of Sep 2026 — re-verify before quoting publicly.)
-- **Phase 3 — Org layer.** Org memory repo · curator convention · `examples/remote-server/` ·
-  distill-to-AGENTS.md assist · export/import archive command for user portability.
+- **Phase 3 — Org layer.** Org memory repo · `examples/remote-server/` ·
+  curator convention ✅ `docs/CURATOR.md` (2026-09-29, pulled forward) ·
+  distill-to-AGENTS.md assist ✅ `open-memex distill-agents` (2026-09-29, pulled forward) ·
+  export/import archive command ✅ `open-memex export` / `import` (2026-09-29, pulled forward, D40).
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
   sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
   for enterprise knowledge systems.
@@ -858,6 +860,13 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   saved via `memory_add` with the new optional `source` param set to
   `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
   the design's capture loop now reaches the agent. Implemented 2026-09-29.*
+- **D43** — `distill-agents` output gains a "Memory hygiene (open-memex)"
+  footer carrying the §3.5 checkpoint guidance (propose 1–3 distilled captures
+  at checkpoints; save nothing without approval; prefer `reference` over
+  copying). *Rationale: double insurance for opencode users, who never see the
+  MCP handshake instructions or the `init`-written instruction files — but
+  opencode reads AGENTS.md natively, so the distilled snippet teaches the
+  checkpoint habit wherever it lands. Approved 2026-09-29.*
 - **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
   (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
   `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0-alpha.7",
+  "version": "0.4.0",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/test-full.ts

@@ -0,0 +1,345 @@
+// Full feature test — exercises every CLI command and every MCP tool.
+// Usage: node --experimental-strip-types scripts/test-full.ts
+// Isolated: uses temp HOME + MY_O_MEMORY_HOME + temp git repos. Touches nothing real.
+//
+// NOTE on flakiness: better-sqlite3 11.x intermittently crashes at process
+// exit on Node 24 (RemoveEnvironmentCleanupHook assertion, exit 134) — a
+// known pre-existing issue. The work itself always completes; only the exit
+// code/output flush is affected. Id-generating calls retry until an id is
+// parsed, and crash-prone commands retry up to 5 times.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const CLI = path.join(REPO, "dist", "cli.js");
+const MCP_TS = path.join(REPO, "src", "mcp.ts");
+
+const T = fs.mkdtempSync(path.join(os.tmpdir(), "om-full-"));
+const TESTENV = {
+  ...process.env,
+  HOME: path.join(T, "home"),
+  MY_O_MEMORY_HOME: path.join(T, "data"),
+};
+fs.mkdirSync(TESTENV.HOME, { recursive: true });
+
+let pass = 0, fail = 0;
+const failures: string[] = [];
+function ok(name: string, cond: boolean, info?: string) {
+  if (cond) { pass++; console.log(`  ok   ${name}`); }
+  else { fail++; failures.push(name); console.log(`  FAIL ${name}${info ? " — " + info : ""}`); }
+}
+function isCrash(err: string): boolean {
+  return /RemoveEnvironmentCleanupHook|Assertion failed/.test(err);
+}
+// Base runner: transparently retries the known better-sqlite3 exit crash
+// (work completes; only exit code/output flush is affected).
+function cliRaw(args: string[], cwd: string, env: NodeJS.ProcessEnv): { out: string; err: string; code: number } {
+  let last = { out: "", err: "", code: 1 };
+  for (let i = 0; i < 5; i++) {
+    try {
+      const out = execFileSync("node", [CLI, ...args], { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+      return { out, err: "", code: 0 };
+    } catch (e: any) {
+      last = { out: e.stdout ?? "", err: e.stderr ?? "", code: e.status ?? 1 };
+      if (!isCrash(last.err)) break; // real error, not the flaky crash
+    }
+  }
+  return last;
+}
+function cli(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cliRaw(args, cwd, TESTENV);
+}
+function git(args: string[], cwd: string) {
+  execFileSync("git", args, { cwd, env: TESTENV, stdio: "ignore" });
+}
+function mkproj(name: string): string {
+  const p = path.join(T, name);
+  fs.mkdirSync(p, { recursive: true });
+  git(["init", "-q"], p);
+  git(["config", "user.email", "test@example.com"], p);
+  git(["config", "user.name", "Test"], p);
+  fs.writeFileSync(path.join(p, "README.md"), "# test\n");
+  git(["add", "."], p);
+  git(["commit", "-qm", "init"], p);
+  return p;
+}
+const grabId = (out: string) => (out.match(/saved ([A-Z0-9]{26})/) || [])[1] ?? "";
+const grabArrowId = (out: string) => (out.match(/→\s*([A-Z0-9]{26})/) || [])[1] ?? "";
+function tarRead(tarfile: string, member: string): string {
+  try {
+    return execFileSync("tar", ["-xzOf", tarfile, member], { env: TESTENV, encoding: "utf8" });
+  } catch { return ""; }
+}
+function cliRetry(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cli(args, cwd); // retry is built into cliRaw
+}
+// add is the id factory — the known better-sqlite3 exit crash can eat the
+// output, so retry until we actually get an id back.
+function addMem(args: string[], cwd: string): string {
+  for (let i = 0; i < 5; i++) {
+    const id = grabId(cli(["add", ...args], cwd).out);
+    if (id) return id;
+  }
+  return "";
+}
+function proposeMem(id: string, cwd: string): string {
+  for (let i = 0; i < 5; i++) {
+    const d = grabArrowId(cli(["propose", id, "--to", "project"], cwd).out);
+    if (d) return d;
+  }
+  return "";
+}
+// Separate data dir = separate machine (the real export/import scenario).
+const TESTENV2 = { ...TESTENV, MY_O_MEMORY_HOME: path.join(T, "data2") };
+function cli2(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cliRaw(args, cwd, TESTENV2);
+}
+
+console.log("== setup ==");
+const PROJ = mkproj("proj");
+const REMOTE = path.join(T, "remote.git");
+execFileSync("git", ["init", "-q", "--bare", REMOTE], { env: TESTENV });
+git(["remote", "add", "origin", REMOTE], PROJ);
+ok("proj + bare remote ready", fs.existsSync(path.join(PROJ, ".git")));
+
+// ---------- 1. where / scopes / config ----------
+console.log("== where / scopes / config ==");
+let r = cli(["where"], PROJ);
+ok("where shows project scope", /project__/.test(r.out), r.out.slice(0, 120));
+r = cli(["scopes"], PROJ);
+ok("scopes empty → graceful message", /no scopes with memories yet/.test(r.out), r.out.slice(0, 120));
+r = cli(["config", "set", "sync.autoPull", "true"], PROJ);
+r = cli(["config"], PROJ);
+ok("config set/get dotted key", /autoPull/.test(r.out) && /true/.test(r.out), r.out.slice(0, 200));
+cli(["config", "set", "sync.autoPull", "false"], PROJ);
+
+// ---------- 2. add / list / search ----------
+console.log("== add / list / search ==");
+const idFact = addMem(["fulltest fact about deploys", "--type", "fact", "--tag", "t1"], PROJ);
+const idDecision = addMem(["fulltest decision to use ff merges", "--type", "decision", "--tag", "t2"], PROJ);
+const idPersonal = addMem(["fulltest personal pref", "--scope", "personal"], PROJ);
+ok("add returns ids", !!idFact && !!idDecision && !!idPersonal);
+r = cli(["list"], PROJ);
+ok("list default = project only", r.out.includes(idFact) && r.out.includes(idDecision) && !r.out.includes(idPersonal));
+r = cli(["list", "--scope", "personal"], PROJ);
+ok("list --scope personal", r.out.includes(idPersonal) && !r.out.includes(idFact));
+r = cli(["scopes"], PROJ);
+ok("scopes lists populated scopes", /personal/.test(r.out) && /project__/.test(r.out), r.out.slice(0, 160));
+r = cli(["list", "--type", "decision"], PROJ);
+ok("list --type filter", r.out.includes(idDecision) && !r.out.includes(idFact));
+r = cli(["search", "ff merges"], PROJ);
+ok("search finds decision", r.out.includes(idDecision), r.out.slice(0, 150));
+
+// ---------- 3. supersede / status / forget ----------
+console.log("== supersede / status / forget ==");
+r = cli(["supersede", idFact, "fulltest fact about deploys v2"], PROJ);
+const idV2 = grabArrowId(r.out);
+ok("supersede creates new version", !!idV2 && idV2 !== idFact, r.out.slice(0, 150));
+const idDep = addMem(["fulltest to deprecate", "--type", "fact"], PROJ);
+r = cli(["status", idDep, "deprecated"], PROJ);
+ok("status deprecated", r.code === 0, (r.err || r.out).slice(0, 150));
+r = cli(["status", idFact, "deprecated"], PROJ);
+ok("status on superseded chain-member is refused", r.code !== 0 && /chain-managed|supersede/i.test(r.err + r.out), (r.err || r.out).slice(0, 120));
+r = cli(["forget", idDecision], PROJ);
+ok("forget deletes", r.code === 0 && /delet/i.test(r.out), r.out.slice(0, 120));
+r = cli(["list"], PROJ);
+ok("forgotten id gone from list", !r.out.includes(idDecision));
+
+// ---------- 4. propose / submit / promote / sync-status ----------
+console.log("== review workflow: propose / submit / promote ==");
+const idProp = addMem(["fulltest proposal candidate", "--scope", "personal"], PROJ);
+const idDraft = proposeMem(idProp, PROJ);
+ok("propose stages outbox draft", !!idDraft);
+r = cli(["sync-status"], PROJ);
+ok("sync-status shows outbox draft", /outbox/.test(r.out) && r.out.includes(idDraft));
+r = cli(["submit", idDraft], PROJ);
+ok("submit commits locally", r.code === 0, (r.err || r.out).slice(0, 150));
+const log = execFileSync("git", ["log", "--oneline", "-1"], { cwd: PROJ, env: TESTENV, encoding: "utf8" });
+ok("submit created a git commit", /submit|mem/i.test(log), log.trim());
+r = cli(["promote", idDraft, "--note", "fulltest approval"], PROJ);
+ok("promote → approved", r.code === 0, (r.err || r.out).slice(0, 150));
+r = cli(["promote", idDraft, "--note", "fulltest publish"], PROJ);
+ok("promote → published", r.code === 0, (r.err || r.out).slice(0, 150));
+const idRej = addMem(["fulltest reject candidate", "--scope", "personal"], PROJ);
+const idRejDraft = proposeMem(idRej, PROJ);
+r = cliRetry(["submit", idRejDraft], PROJ);
+ok("reject-path submit", r.code === 0, (r.err || r.out).slice(0, 120));
+r = cli(["promote", idRejDraft, "--reject", "--note", "fulltest rejection"], PROJ);
+ok("promote --reject with note", r.code === 0, (r.err || r.out).slice(0, 150));
+
+// ---------- 5. export / import ----------
+console.log("== export / import ==");
+const expFile = path.join(T, "bundle.tar.gz");
+r = cliRetry(["export", "-o", expFile], PROJ);
+ok("export creates bundle", r.code === 0 && fs.existsSync(expFile), (r.err || r.out).slice(0, 120));
+const man = JSON.parse(tarRead(expFile, "manifest.json") || "{}");
+ok("manifest format valid", man.format === "open-memex-export/1" && Array.isArray(man.memories) && man.memories.length > 0, JSON.stringify(man).slice(0, 120));
+r = cliRetry(["export", "--scope", "personal", "--all", "-o", path.join(T, "p.tar.gz")], PROJ);
+const manP = JSON.parse(tarRead(path.join(T, "p.tar.gz"), "manifest.json") || "{}");
+ok("export --all includes private", manP.include_private === true && manP.memories.length >= 2);
+const PROJ2 = mkproj("proj2");
+function cli2Retry(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cli2(args, cwd); // retry is built into cliRaw
+}
+r = cli2Retry(["import", expFile, "--dry-run"], PROJ2);
+ok("import --dry-run", /DRY RUN/.test(r.out), r.out.slice(0, 120));
+r = cli2Retry(["import", expFile], PROJ2);
+ok("import real run", /imported [1-9]/.test(r.out), r.out.slice(0, 120));
+r = cli2(["list"], PROJ2);
+ok("imported memories visible in target project", /fulltest/.test(r.out), r.out.slice(0, 160));
+r = cli2Retry(["import", expFile], PROJ2);
+ok("import identical → skipped", /skipped [1-9]+ identical/.test(r.out), r.out.slice(0, 120));
+// conflict: craft bundle with same id, different content
+const cid = man.memories[0].id;
+const cstage = path.join(T, "cstage");
+fs.mkdirSync(path.join(cstage, "memories", "project"), { recursive: true });
+fs.writeFileSync(path.join(cstage, "memories", "project", cid + ".md"),
+  `---\nid: ${cid}\nscope: project\nscope_key: project__old__x\nvisibility: internal\ntype: fact\nstatus: active\ncreated_at: 2026-01-01T00:00:00Z\nupdated_at: 2026-01-01T00:00:00Z\n---\n\nCONFLICT CONTENT\n`);
+fs.writeFileSync(path.join(cstage, "manifest.json"), JSON.stringify({ format: "open-memex-export/1", exported_at: "2026-01-01T00:00:00Z", open_memex_version: "t", include_private: false, filters: {}, memories: [{ id: cid, scope: "project", file: `memories/project/${cid}.md` }] }));
+const cfile = path.join(T, "conflict.tar.gz");
+execFileSync("tar", ["-czf", cfile, "-C", cstage, "manifest.json", "memories"], { env: TESTENV });
+r = cli2Retry(["import", cfile], PROJ2);
+ok("import conflict reported, never overwritten", /conflict/.test(r.out) && /imported 0/.test(r.out), r.out.slice(0, 160));
+
+// ---------- 6. distill-agents ----------
+console.log("== distill-agents ==");
+addMem(["fulltest distill decision: always fast-forward", "--type", "decision"], PROJ);
+addMem(["fulltest distill gotcha: sqlite crashes on exit", "--type", "gotcha"], PROJ);
+r = cliRetry(["distill-agents"], PROJ);
+ok("distill-agents proposes snippet", /## Learned/.test(r.out), r.out.slice(0, 120));
+r = cliRetry(["distill-agents", "--type", "decision", "-o", path.join(T, "snip.md")], PROJ);
+ok("distill-agents -o writes file", fs.existsSync(path.join(T, "snip.md")));
+
+// ---------- 7. pull / push ----------
+console.log("== pull / push ==");
+r = cliRetry(["push"], PROJ);
+ok("push explicit", r.code === 0, (r.err || r.out).slice(0, 150));
+const PROJ3 = path.join(T, "proj3");
+execFileSync("git", ["clone", "-q", REMOTE, PROJ3], { env: TESTENV });
+git(["config", "user.email", "test@example.com"], PROJ3);
+git(["config", "user.name", "Test"], PROJ3);
+const idRemote = addMem(["fulltest remote memory", "--type", "fact"], PROJ3);
+cliRetry(["submit", idRemote], PROJ3);
+cliRetry(["push"], PROJ3);
+r = cliRetry(["pull"], PROJ);
+ok("pull fast-forward", r.code === 0 && /up.to.date|fast-forward|pulled/i.test(r.out + r.err), (r.out + r.err).slice(0, 150));
+// diverged: commit on both sides
+fs.writeFileSync(path.join(PROJ, "div1.txt"), "a");
+git(["add", "."], PROJ); git(["commit", "-qm", "div1"], PROJ);
+fs.writeFileSync(path.join(PROJ3, "div2.txt"), "b");
+git(["add", "."], PROJ3); git(["commit", "-qm", "div2"], PROJ3);
+cli(["push"], PROJ3);
+r = cli(["pull"], PROJ);
+ok("pull diverged → clear failure", r.code !== 0 && /diverg|behind|ahead/i.test(r.out + r.err), (r.out + r.err).slice(0, 160));
+
+// ---------- 8. migrate / reindex ----------
+console.log("== migrate / reindex ==");
+r = cli(["migrate", "--dry-run"], PROJ);
+ok("migrate bare → graceful no-op message", /no --from given/.test(r.out + r.err), (r.out + r.err).slice(0, 150));
+const idMig = addMem(["fulltest migrate me", "--scope", "personal"], PROJ);
+r = cli(["migrate", "--from", "personal", "--to", "project", "--dry-run"], PROJ);
+ok("migrate personal→project dry-run", r.code === 0, (r.err || r.out).slice(0, 150));
+const dbPath = path.join(TESTENV.MY_O_MEMORY_HOME as string, "index.db");
+fs.rmSync(dbPath);
+const beforeReindex = Date.now();
+cli(["reindex"], PROJ); // exit code unreliable (known sqlite exit crash); verify by artifact
+let dbOk = false;
+try { dbOk = fs.existsSync(dbPath) && fs.statSync(dbPath).mtimeMs >= beforeReindex - 1000; } catch { /* no */ }
+ok("reindex rebuilds", dbOk, `db exists: ${fs.existsSync(dbPath)}`);
+r = cli(["list", "--scope", "personal"], PROJ);
+ok("list works after reindex", r.out.includes(idMig) || r.out.includes(idPersonal));
+
+// ---------- 9. capture / doctor / mcp --print-config / init ----------
+console.log("== capture / doctor / mcp / init ==");
+r = cli(["capture", "--dry-run", "remember: we deploy on Fridays and use ff merges"], PROJ);
+ok("capture --dry-run", r.code === 0 && /deploy|friday/i.test(r.out), r.out.slice(0, 150));
+for (const c of ["vscode", "cursor", "claude", "opencode", "visualstudio"]) {
+  r = cli(["mcp", "--print-config", c], PROJ);
+  ok(`mcp --print-config ${c}`, r.code === 0 && r.out.trim().length > 10, r.err.slice(0, 100));
+}
+r = cli(["init", "--client", "vscode", "--yes"], PROJ);
+ok("init --client vscode --yes", r.code === 0 && fs.existsSync(path.join(PROJ, ".vscode", "mcp.json")), (r.err || r.out).slice(0, 150));
+r = cliRetry(["doctor"], PROJ);
+ok("doctor", r.code === 0 && /All checks passed/.test(r.out), (r.err || r.out).slice(0, 200));
+
+// ---------- 10. MCP: all 11 tools + session-start instructions ----------
+console.log("== MCP tools ==");
+{
+  const child = spawn("node", ["--experimental-strip-types", MCP_TS], {
+    cwd: PROJ, env: TESTENV, stdio: ["pipe", "pipe", "pipe"],
+  });
+  let buf = "";
+  let id = 0;
+  const pending = new Map<number, (v: any) => void>();
+  child.stdout.on("data", (d: Buffer) => {
+    buf += d.toString();
+    let idx: number;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined && pending.has(msg.id)) { pending.get(msg.id)!(msg); pending.delete(msg.id); }
+      } catch { /* ignore */ }
+    }
+  });
+  const req = (method: string, params: any) => new Promise<any>((resolve) => {
+    const i = ++id;
+    pending.set(i, resolve);
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: i, method, params }) + "\n");
+    setTimeout(() => { if (pending.has(i)) { pending.delete(i); resolve({ __timeout: true }); } }, 30000);
+  });
+  const call = async (tool: string, args: any) => {
+    const resp = await req("tools/call", { name: tool, arguments: args });
+    const text = (resp.result?.content || []).map((c: any) => c.text || "").join("\n");
+    return { resp, text };
+  };
+
+  const init = await req("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "t", version: "1" } });
+  const instructions: string = init.result?.instructions || "";
+  ok("MCP initialize returns instructions", instructions.length > 200, instructions.slice(0, 100));
+  ok("instructions mention sync/memory_status", /memory_status|sync/i.test(instructions));
+  await req("notifications/initialized", {});
+  const tools = await req("tools/list", {});
+  const names: string[] = (tools.result?.tools || []).map((t: any) => t.name);
+  const expected = ["memory_add","memory_forget","memory_list","memory_pr_status","memory_promote","memory_propose","memory_resolve","memory_search","memory_status","memory_submit","memory_supersede"];
+  ok("11 MCP tools listed", expected.every((n) => names.includes(n)), names.join(","));
+
+  let m = await call("memory_add", { content: "mcptest fact via MCP", type: "fact" });
+  const mid = (m.text.match(/([A-Z0-9]{26})/) || [])[1] || "";
+  ok("memory_add", !!mid, m.text.slice(0, 120));
+  m = await call("memory_search", { query: "mcptest fact" });
+  ok("memory_search", m.text.includes(mid), m.text.slice(0, 120));
+  m = await call("memory_list", { limit: 5 });
+  ok("memory_list", m.text.includes(mid) || /fact/.test(m.text), m.text.slice(0, 120));
+  m = await call("memory_status", {});
+  ok("memory_status", /project|outbox|sync/i.test(m.text), m.text.slice(0, 120));
+  m = await call("memory_supersede", { id: mid, content: "mcptest fact via MCP v2" });
+  const mid2 = (m.text.match(/with ([A-Z0-9]{26})/) || [])[1] || "";
+  ok("memory_supersede", !!mid2 && mid2 !== mid, m.text.slice(0, 120));
+  // propose → submit → promote via MCP
+  const pid = ((await call("memory_add", { content: "mcptest proposal", scope: "personal" })).text.match(/([A-Z0-9]{26})/) || [])[1] || "";
+  m = await call("memory_propose", { ids: [pid] });
+  const pdraft = (m.text.match(/→\s*([A-Z0-9]{26})/) || m.text.match(/([A-Z0-9]{26})/) || [])[1] || "";
+  ok("memory_propose", !!pdraft && pdraft !== pid, m.text.slice(0, 120));
+  m = await call("memory_submit", { ids: [pdraft] });
+  ok("memory_submit", !/error/i.test(m.text) || /commit|submit/i.test(m.text), m.text.slice(0, 120));
+  m = await call("memory_promote", { id: pdraft, note: "mcptest approve" });
+  ok("memory_promote", !/__timeout/.test(JSON.stringify(m.resp)), m.text.slice(0, 120));
+  m = await call("memory_resolve", {});
+  ok("memory_resolve (list)", !/__timeout/.test(JSON.stringify(m.resp)), m.text.slice(0, 120));
+  m = await call("memory_pr_status", {});
+  ok("memory_pr_status (report)", !/__timeout/.test(JSON.stringify(m.resp)), m.text.slice(0, 120));
+  m = await call("memory_forget", { id: mid2 });
+  ok("memory_forget", /delet|forget/i.test(m.text), m.text.slice(0, 120));
+  child.kill();
+}
+
+console.log("\n================ SUMMARY ================");
+console.log(`pass: ${pass}, fail: ${fail}`);
+if (failures.length) { console.log("failed tests:"); for (const f of failures) console.log("  - " + f); }
+process.exit(fail ? 1 : 0);