@atlaso-labs/opencode 0.1.1 → 0.2.1

package/lib/project.ts

@@ -6,39 +6,113 @@
  *   1. the git remote origin URL (stable across clones), else
  *   2. "<basename>-<short hash of abspath>".
  * READ-ONLY: never creates a .atlaso folder, never throws (→ null = personal-only).
- * Ported 1:1 from the Python thin client's `_project.py`.
+ * Ported 1:1 from the Python thin client's `_project.py` — the TRI-STATE design
+ * (ok / none / unknown) is load-bearing and must stay in lockstep with it.
  */
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, resolve } from "node:path";
 
 const MARKERS = [
   ".git", "pyproject.toml", "package.json", "Cargo.toml", "go.mod",
   ".hg", ".svn", "Gemfile", "pom.xml", "build.gradle", "requirements.txt",
 ];
 
-export function projectRoot(start?: string): string {
-  let cur: string;
+// Tool-install territory: a "project" resolved inside any of these is the
+// connector's own runtime/extension dir or a package cache, never the user's
+// work. An unguarded cwd walk lands exactly here — one NEW fake project per
+// version-pinned release dir (field deposit 52c7e97d). Membership is by path
+// ANCESTRY over the canonicalized (realpath'd) root — exact-path lists rot on
+// the next versioned release (lab ruling).
+const TOOL_DOT_DIRS = new Set([
+  ".claude", ".codex", ".gemini", ".vscode", ".opencode", ".atlaso",
+  "node_modules", "site-packages", "__pypackages__", ".cache", "Caches",
+]);
+
+function intersects(parts: Set<string>, names: Iterable<string>): boolean {
+  for (const n of names) if (parts.has(n)) return true;
+  return false;
+}
+
+/** Split a path into its named components (drops empty leading/anchor parts). */
+function pathParts(p: string): Set<string> {
+  return new Set(p.split(/[/\\]+/).filter(Boolean));
+}
+
+/** True when `root` is tool-install/cache territory — the measurement itself is
+ *  garbage (we learn nothing about where the user was working). Distinct from
+ *  `noProjectRoot`: garbage → status 'unknown'. */
+function garbageRoot(root: string): boolean {
   try {
-    cur = resolve(start || process.cwd());
+    const parts = pathParts(root);
+    const blocked = new Set([...parts].filter((part) => TOOL_DOT_DIRS.has(part)));
+    // Match Python: only proven managed worktrees exempt .claude/.codex.
+    // A nested plugin/cache directory must still fail the ancestry guard.
+    const sequence = root.split(/[/\\]+/).filter(Boolean);
+    for (const name of [".claude", ".codex"]) {
+      const positions = sequence.flatMap((part, i) => part === name ? [i] : []);
+      if (positions.length && positions.every((i) => {
+        if (sequence[i + 1] !== "worktrees") return false;
+        let ancestor = root;
+        while (ancestor.split(/[/\\]+/).filter(Boolean).length > i + 2) {
+          if (existsSync(join(ancestor, ".git"))) return true;
+          const parent = dirname(ancestor);
+          if (parent === ancestor) break;
+          ancestor = parent;
+        }
+        return false;
+      })) blocked.delete(name);
+    }
+    if (blocked.size) return true;
+    // plugin caches that hide under non-dot dirs (marketplaces/cache/repos
+    // layouts, e.g. "…/plugins/marketplaces/atlaso/atlaso/runtime")
+    if (parts.has("plugins") && intersects(parts, ["cache", "marketplaces", "repos"])) return true;
+    if (parts.has("extensions") && intersects(parts, ["Cursor", "Code", "VSCodium"])) return true;
+    // ~/.cursor hosts BOTH junk (extensions, plugin caches) and real user work
+    // (background-agent worktrees under .cursor/worktrees) — block only its
+    // non-worktree subtrees.
+    if (parts.has(".cursor") && !parts.has("worktrees")) return true;
   } catch {
-    return process.cwd();
+    return true;
   }
+  return false;
+}
+
+/** True when `root` is a real place that simply ISN'T a project ($HOME itself,
+ *  the filesystem root). A trustworthy 'no project here' answer — status 'none',
+ *  genuine personal scope. */
+function noProjectRoot(root: string): boolean {
+  try {
+    // Prefer $HOME (Python's Path.home() does the same on POSIX) so this tracks
+    // the caller's real home even under a modified environment; fall back to the
+    // OS lookup. Compared realpath'd, since `root` is already canonicalized.
+    const raw = process.env.HOME || homedir();
+    let home = raw;
+    try {
+      home = realpathSync(raw);
+    } catch {
+      /* keep raw home */
+    }
+    return root === home || root === raw || root === parse(root).root;
+  } catch {
+    return true;
+  }
+}
+
+export function projectRoot(start?: string): string {
+  const cur = realpathSync(resolve(start || process.cwd()));
   let d = cur;
-  // walk up to the filesystem root looking for a project marker
   while (true) {
-    for (const m of MARKERS) {
-      try {
-        if (existsSync(join(d, m))) return d;
-      } catch {
-        /* ignore */
-      }
-    }
+    // Preserve existing package identities, and do not inherit a home dotfiles
+    // repository when the opened directory is below the home boundary.
+    if (noProjectRoot(d)) return cur;
+    if (MARKERS.some((m) => existsSync(join(d, m)))) return d;
     const parent = dirname(d);
     if (parent === d) break;
     d = parent;
   }
-  return cur; // no markers → the cwd itself is the "project"
+  return cur;
 }
 
 /** Read remote.origin.url straight from .git/config (no subprocess). Handles a
@@ -96,65 +170,148 @@ function gitOrigin(root: string): string | null {
  *  github.com/me/app. */
 function normalizeRemote(url: string): string {
   let u = url.trim();
-  u = u.replace(/^[a-zA-Z]+:\/\//, ""); // strip scheme
-  u = u.replace(/^[^@/]+@/, ""); // strip user@
-  u = u.replace(":", "/"); // scp-style host:path → host/path (first colon only)
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(u)) {
+    try {
+      const parsed = new URL(u);
+      // A transport PORT is not repository identity. Previously the scheme was
+      // stripped and then the first colon became a path separator, so
+      // ssh://git@host:2222/group/repo turned into host/2222/group/repo — a
+      // different project key from the same repo cloned over https, silently
+      // splitting one project's memories in two. (Bugbot #157, "SSH ports break
+      // project keys".) Parsing properly drops the port and the userinfo.
+      u = `${parsed.hostname}${parsed.pathname}`;
+    } catch {
+      u = u.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+    }
+  } else {
+    u = u.replace(/^[^@/]+@/, ""); // strip user@
+    u = u.replace(":", "/"); // scp-style host:path → host/path (first colon only)
+  }
   u = u.replace(/\.git$/, "");
   return u.replace(/^\/+|\/+$/g, "").toLowerCase();
 }
 
-/** A stable identity for the current project. null on any failure → personal-only. */
-export function projectKey(start?: string): string | null {
+/** name-hash key for a non-git project root. Hash basis is the NFC-normalized,
+ *  case-folded path — APFS is case-insensitive-preserving and hands back NFD
+ *  filenames, so two layers producing the same directory's string must never
+ *  hash it differently (lab ruling). Mirrors Python `_fallback_key` 1:1. */
+function fallbackKey(root: string): string {
+  const basis = root.normalize("NFC").toLowerCase();
+  const h = createHash("sha256").update(basis, "utf-8").digest("hex").slice(0, 8);
+  const name = basename(root).normalize("NFC").replace(/[^A-Za-z0-9_.-]/g, "-") || "project";
+  return `${name}-${h}`;
+}
+
+export type ProjectStatus = "ok" | "none" | "unknown";
+export interface ProjectResolution {
+  status: ProjectStatus;
+  key: string | null;
+}
+
+/** (status, key) — the tri-state project measurement. Mirrors Python
+ *  `project_resolution`.
+ *    'ok'      → key is a real project identity (normalized git remote, else
+ *                name-hash of the canonical root).
+ *    'none'    → trustworthy "this work belongs to NO project" ($HOME, the
+ *                filesystem root) → genuine personal scope.
+ *    'unknown' → the measurement itself failed or was garbage (root resolved
+ *                into tool-install/cache territory, unreadable dir, exception)
+ *                → record as an unattributed project memory, visible with a
+ *                provenance marker, never silently buried.
+ *  The none/unknown split is load-bearing: collapsing them is exactly how 298
+ *  memories became indistinguishable from "no project" and disappeared. */
+export function projectResolution(start?: string): ProjectResolution {
   try {
-    const root = projectRoot(start);
-    const origin = gitOrigin(root);
-    if (origin) {
-      const key = normalizeRemote(origin);
-      if (key) return key.slice(0, 120);
+    const supplied = start ?? process.cwd();
+    if (!isAbsolute(supplied) || !statSync(supplied).isDirectory()) {
+      return { status: "unknown", key: null };
     }
-    const h = createHash("sha256").update(root).digest("hex").slice(0, 8);
-    const name = (basename(root).replace(/[^A-Za-z0-9_.-]/g, "-") || "project");
-    return `${name}-${h}`;
+    const current = realpathSync(supplied);
+    if (garbageRoot(current)) return { status: "unknown", key: null };
+    const root = projectRoot(current);
+    if (garbageRoot(root)) return { status: "unknown", key: null };
+    if (noProjectRoot(root)) return { status: "none", key: null };
+    const origin = gitOrigin(root);
+    const key = origin ? normalizeRemote(origin) : fallbackKey(root);
+    return validProjectKey(key) ? { status: "ok", key } : { status: "unknown", key: null };
   } catch {
-    return null;
+    return { status: "unknown", key: null };
   }
 }
 
+/** Exact project identities match the shared Python client; never truncate. */
+function validProjectKey(key: string): boolean {
+  return key.length > 0 && [...key].length <= 512 && key === key.trim()
+    && !/[\s\x00-\x1f\x7f]/u.test(key)
+    && key !== "unknown" && key !== "project-unknown";
+}
+
+/** A stable identity for the current project. null → personal-only (both the
+ *  'none' and 'unknown' cases — recall treats them the same). Mirrors Python
+ *  `project_key`. */
+export function projectKey(start?: string): string | null {
+  const { status, key } = projectResolution(start);
+  return status === "ok" ? key : null;
+}
+
 /** (scope, project_key) from a deposit's tags — mirrors the server + Python
- *  `_project.scope_of`. */
+ *  `_project.scope_of`. Recognizes `scope:orphaned`, the server-side rescue
+ *  scope for memories reattributed away from a bad key. */
 export function scopeOf(tags: string[] | undefined): [string, string | null] {
-  let scope = "personal";
+  // ORDER-INDEPENDENT with precedence orphaned > project > personal
+  // (CodeRedTeam block: last-tag-wins let a crafted tag array leak a project
+  // memory everywhere or revive a rescued orphan). Mirrors _project.scope_of
+  // and the server's _scope_of exactly.
+  const tl = (tags || []).filter((t) => typeof t === "string");
   let pkey: string | null = null;
-  for (const t of tags || []) {
-    if (t === "scope:project") scope = "project";
-    else if (t === "scope:personal") scope = "personal";
-    else if (typeof t === "string" && t.startsWith("project:")) pkey = t.slice("project:".length);
+  for (const t of tl) {
+    if (t.startsWith("project:")) pkey = t.slice("project:".length);
   }
+  const scope = tl.includes("scope:orphaned")
+    ? "orphaned"
+    : tl.includes("scope:project")
+      ? "project"
+      : "personal";
   return [scope, pkey];
 }
 
 /** Per-project visibility — MUST match the server. Personal/untagged → visible
- *  everywhere. Project-scoped → only its own project. Project-scoped with NO key
- *  (orphan) → FAIL CLOSED (hidden), so a capture we couldn't attribute never
- *  leaks across repos. Ported from `_project.visible_in_project`. */
+ *  everywhere. Project-scoped WITH a key → only its own project. Project-scoped
+ *  with NO key (orphan) → VISIBLE everywhere (fail OPEN): hiding is invisible to
+ *  the user so it can never be corrected, while over-visibility of the user's OWN
+ *  memory is observable and fixable (lab ruling — asymmetric loss; the old
+ *  fail-closed rule silently buried every capture the key derivation couldn't
+ *  attribute). `scope:orphaned` (server-side rescue) is HIDDEN from normal recall.
+ *  Ported from `_project.visible_in_project`. */
 export function visibleInProject(
   tags: string[] | undefined,
   project: string | null | undefined,
 ): boolean {
   const [scope, pkey] = scopeOf(tags);
+  if (scope === "orphaned") return false; // rescue scope — not surfaced in normal recall
   if (scope !== "project") return true;
-  if (pkey === null) return false;
+  if (pkey === null) return true; // orphan → visible-with-provenance, never silently buried
   return pkey === (project ?? null);
 }
 
-/** Best-effort workspace root from a hook payload. Cursor's exact field for this
- *  isn't nailed down (docs are thin; `workspace_roots` vs nested `project
- *  .workspaceRoot` both appear in the wild), so we try every plausible shape and
- *  fall back to the cwd Cursor launched the hook from. Shared by the recall +
- *  capture hooks so both scope to the SAME project. (The live field is one of the
- *  things to confirm in the deployed end-to-end test.) */
+/** Best-effort workspace root from a hook payload, with EVERY element of the
+ *  fallback chain guarded (lab RedTeam finding: "the fallback chain will silently
+ *  accept the plugin process's own PWD"). Cursor's exact field isn't nailed down
+ *  (docs are thin; `workspace_roots` vs nested `project.workspaceRoot` both appear
+ *  in the wild), so we try every plausible shape AND the process PWD/cwd — but any
+ *  candidate that canonicalizes into tool-install/cache territory is SKIPPED (the
+ *  hook's own vendored-runtime cwd must never win). Returns the first real
+ *  candidate, or null when every candidate is garbage → the caller records the
+ *  capture as status 'unknown'. Shared by the recall + capture hooks so both scope
+ *  to the SAME project. */
 export function workspaceRoot(payload: Record<string, any>): string | null {
   const p = payload || {};
+  let cwd: string | undefined;
+  try {
+    cwd = process.cwd();
+  } catch {
+    cwd = undefined;
+  }
   const candidates: unknown[] = [
     Array.isArray(p.workspace_roots) ? p.workspace_roots[0] : undefined,
     Array.isArray(p.workspaceRoots) ? p.workspaceRoots[0] : undefined,
@@ -162,7 +319,100 @@ export function workspaceRoot(payload: Record<string, any>): string | null {
     p.workspaceRoot,
     p.workspace_root,
     p.cwd,
+    process.env.PWD,
+    cwd,
   ];
-  for (const c of candidates) if (typeof c === "string" && c.trim()) return c;
-  return process.env.PWD || process.cwd() || null;
+  for (const c of candidates) {
+    if (typeof c !== "string" || !c.trim()) continue;
+    if (candidateIsGarbage(c)) continue; // skip the plugin's own runtime/cache dir
+    return c;
+  }
+  return null; // every candidate was garbage → status 'unknown'
+}
+
+/** True when a raw workspace-root candidate canonicalizes into tool-install
+ *  territory. Guards each element of the workspaceRoot() chain individually. */
+function candidateIsGarbage(candidate: string): boolean {
+  try {
+    let resolved = resolve(candidate);
+    try {
+      resolved = realpathSync(resolved);
+    } catch {
+      /* keep the resolve()'d path */
+    }
+    return garbageRoot(resolved);
+  } catch {
+    return true;
+  }
+}
+
+/** First entry of a workspace-folders list (editors pass these path-separated). */
+function firstWorkspaceFolder(v: string | undefined): string | null {
+  if (!v) return null;
+  const first = v.split(/[:;,]/).map((s) => s.trim()).filter(Boolean)[0];
+  return first || null;
+}
+
+/** Project key for the CURRENT process, resolved from the environment.
+ *
+ *  The MCP server is a standalone process — it gets no hook payload and its cwd is
+ *  wherever the editor happened to launch it, so `projectKey()` alone would key
+ *  memories to the wrong directory (or to none). Resolve the workspace from the env
+ *  the editor exports, then hand it to the tri-state resolver so an unattributable
+ *  root yields null rather than a junk key. */
+/** Tri-state resolution for the CURRENT process. `currentProjectKey()` collapses
+ *  'none' and 'unknown' to the same null, which is NOT the same thing: 'none' is a
+ *  trustworthy "this is genuinely not a project" ($HOME, the filesystem root) and
+ *  belongs in personal scope, while 'unknown' is "the measurement is garbage" and
+ *  must stay project-scoped but unattributed. Callers that act on the difference
+ *  must use this. (Bugbot #157, "Remember skips none-vs-unknown split".) */
+export function currentProjectResolution(): ProjectResolution {
+  // 'none' is a TRUSTWORTHY "this is genuinely not a project", and acting on it
+  // downgrades a memory to personal — visible in every repo forever. It may only
+  // come from a root the editor actually supplied. An MCP server launched without
+  // workspace env vars falls back to cwd, which is frequently $HOME, and $HOME
+  // resolves to 'none': trusting that would file project-specific facts as
+  // personal and follow the user across every repository. Auto-capture already
+  // maps a missing workspace to 'unknown'; this now matches it.
+  // (Bugbot #157, "Remember mis-tags personal scope", HIGH.)
+  const supplied = editorWorkspaceRoot();
+  if (!supplied) return { status: "unknown", key: null };
+  return projectResolution(supplied);
+}
+
+/** The workspace the EDITOR told us about, or null. Deliberately excludes any
+ *  cwd fallback: "the editor said this is the workspace" and "we guessed from the
+ *  process's working directory" are different claims, and only the first can be
+ *  trusted to mean anything. */
+function editorWorkspaceRoot(): string | null {
+  return (
+    process.env.OPENCODE_PROJECT_DIR ||
+    firstWorkspaceFolder(process.env.WORKSPACE_FOLDER_PATHS) ||
+    null
+  );
+}
+
+function currentRoot(): string {
+  return editorWorkspaceRoot() || process.env.PWD || process.cwd();
+}
+
+export function currentProjectKey(): string | null {
+  return projectKey(currentRoot());
+}
+
+/** Visibility for a RECALL RESULT, as opposed to a raw tag list.
+ *
+ *  Some server versions normalize scope into a top-level `scope` field instead of
+ *  leaving `scope:project` in tags. A caller that only inspects tags therefore
+ *  reads such a row as PERSONAL and shows it everywhere — a cross-project leak.
+ *  The MCP path had this right and the sessionStart hook did not, which is exactly
+ *  the kind of drift two copies of one predicate produce, so it lives here now and
+ *  both call it. (Bugbot #157, "Recall filter misses scope field".) */
+export function resultVisibleHere(
+  r: { scope?: string; tags?: string[] },
+  project: string | null,
+): boolean {
+  const tags = Array.isArray(r.tags) ? [...r.tags] : [];
+  if (r.scope === "project" && !tags.includes("scope:project")) tags.push("scope:project");
+  return visibleInProject(tags, project);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaso-labs/opencode",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Long-term memory for OpenCode — recalls what you've decided and remembers what matters, across sessions, projects, and tools. A pure-TypeScript OpenCode plugin (no engine; HTTP to the Atlaso brain only).",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,8 @@
     "AGENTS.md",
     "opencode.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "bun test",
@@ -47,5 +48,8 @@
   },
   "bugs": {
     "url": "https://github.com/atlaso-labs/opencode/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/index.ts

@@ -27,12 +27,16 @@ import { createHash } from "node:crypto";
 import type { Hooks, Plugin } from "@opencode-ai/plugin";
 import type { Part } from "@opencode-ai/sdk";
 
-import { deposit, loadAuth, recall, type DepositItem } from "../lib/atlaso";
+import { depositDetailed, loadAuth, recall, type DepositItem } from "../lib/atlaso";
+import { drainIfPending } from "../lib/drain";
+import { enqueue, quarantine, settle } from "../lib/outbox";
+import { markStatsSent, pendingCaptureStats, recordDepositResults, recordGate } from "../lib/capture_stats";
 import { buildContent, classifyScope, heuristicPolarity, scrub, shouldDeposit } from "../lib/capture";
+import { resolveCredential } from "../lib/credential";
 import { maybeAutoconnect } from "../lib/connect";
 import { online } from "../lib/entitlement";
 import { log } from "../lib/log";
-import { projectKey } from "../lib/project";
+import { projectKey, projectResolution } from "../lib/project";
 import { renderBlock } from "../lib/render";
 
 const TOOL = "opencode";
@@ -104,9 +108,17 @@ export const AtlasoMemory: Plugin = async ({ directory, worktree }): Promise<Hoo
 
         const auth = loadAuth();
         if (!auth) return; // online-first: not linked → nothing to recall
-        if (!(await online(auth, TOOL, auth.device_id ?? null))) return; // local-only this turn
+        if (!(await online(auth, { tool: TOOL, deviceId: auth.device_id ?? null }))) return; // local-only this turn
+        const cred = await resolveCredential(TOOL);
+        if (!cred) return; // no cloud this run
 
-        const results = await recall(auth, userText, RECALL_LIMIT, project, input.sessionID);
+        // THE RECOVERY PATH. If a previous session ended while the brain was down
+        // (or mid-deploy, or the laptop was offline), those memories are still in
+        // the outbox. Catch up here — we already hold a credential and the user is
+        // waiting on a model call anyway. One readdir when the queue is empty.
+        await drainIfPending(TOOL, cred);
+
+        const results = await recall(cred, userText, RECALL_LIMIT, project, input.sessionID);
         const block = renderBlock(results);
         // OpenCode persists + strictly validates injected parts, so we can only build
         // a schema-valid one when THIS turn's real message id (msg_*) is present on
@@ -146,23 +158,43 @@ export const AtlasoMemory: Plugin = async ({ directory, worktree }): Promise<Hoo
         pending.delete(sessionID); // one capture per stashed statement
 
         const user = p.user;
-        if (!shouldDeposit(user)[0]) {
+        // Counter records EVERY gate evaluation (content-free; lab 85a5c41b).
+        const scrubbed = scrub(user)[0];
+        // Tri-state project attribution (mirrors the Python client core.py): resolve
+        // a key only when the scope is "project" — 'ok' tags the key, 'none' ($HOME
+        // etc.) downgrades to personal, 'unknown' (garbage: plugin/cache dir, error)
+        // keeps scope:project with a bare "project-unknown" marker, never a key.
+        let scope = classifyScope(user);
+        let pk: string | null = null;
+        let projectUnknown = false;
+        if (scope === "project") {
+          const { status, key } = projectResolution(directory || worktree);
+          if (status === "none") scope = "personal";
+          else if (status === "unknown") projectUnknown = true;
+          else pk = key; // 'ok'
+        }
+        const preContent = buildContent(scrubbed, "");
+        const dedupeKey = preContent
+          ? clientId(preContent, scope, scope === "project" ? pk : null)
+          : null;
+        const [gateOk, gateReason] = shouldDeposit(user);
+        await recordGate(gateReason, { turnKey: dedupeKey });
+        if (!gateOk) {
           log("capture", "skip (gate)");
           return;
         }
         const auth = loadAuth();
         if (!auth) return;
-        if (!(await online(auth, TOOL, auth.device_id ?? null))) {
+        if (!(await online(auth, { tool: TOOL, deviceId: auth.device_id ?? null }))) {
           log("capture", "skip (not cloud-linked — local-only)");
           return;
         }
 
-        const content = buildContent(scrub(user)[0], ""); // assistant omitted in v1 (see TODO)
+        const content = preContent; // assistant omitted in v1 (see TODO)
         if (!content) return;
-        const scope = classifyScope(user);
-        const pk = projectKey(directory || worktree); // for the project tag + idempotency key
         const tags = ["opencode", "auto", `pol-hint:${heuristicPolarity(user)}`, `scope:${scope}`];
-        if (scope === "project" && pk) tags.push(`project:${pk}`);
+        if (projectUnknown) tags.push("project-unknown"); // unattributed → provenance marker, no key
+        if (pk) tags.push(`project:${pk}`);
 
         const item: DepositItem = {
           client_id: clientId(content, scope, scope === "project" ? pk : null),
@@ -172,10 +204,33 @@ export const AtlasoMemory: Plugin = async ({ directory, worktree }): Promise<Hoo
           scope_note: null,
           tags,
         };
-        const saved = await deposit(auth, [item]);
-        log("capture", `saved=${saved} scope=${scope} session=${sessionID}`);
+        const cred = await resolveCredential(TOOL);
+        if (!cred) {
+          log("capture", "skip (local-only — no tool credential)");
+          return;
+        }
+        // WRITE-AHEAD. Persist BEFORE the network call, never after it fails, so a
+        // process killed inside fetch (session end, machine sleep, a brain restart
+        // mid-deploy) has already durably recorded the memory. Previously any of
+        // those lost it silently. Idempotent on client_id.
+        enqueue(TOOL, item);
+
+        const stats = pendingCaptureStats();
+        const { ok, results, status } = await depositDetailed(cred, [item], stats ?? undefined);
+        if (ok) {
+          if (stats) await markStatsSent(stats);
+          await recordDepositResults(results);
+          const verdict = results.find((r) => r.client_id === item.client_id);
+          if (verdict && verdict.status !== "invalid") settle(TOOL, item.client_id);
+          else if (verdict)
+            quarantine(TOOL, { client_id: item.client_id, item, enqueued_at: Date.now(), attempts: 1 },
+                       `server rejected: ${verdict.status}`);
+        }
+        log("capture", `saved=${ok}${ok ? "" : ` queued (${status || "transport"})`} scope=${scope} session=${sessionID}`);
+        // Opportunistic catch-up between turns; cheap no-op on an empty queue.
+        await drainIfPending(TOOL, cred);
       } catch (e) {
-        log("capture", `error ${e}`); // fail open
+        log("capture", `error ${e} (queued)`); // fail open — the memory is on disk
       }
     },
   };