@atlaso-labs/opencode 0.1.0

package/lib/connect.ts

@@ -0,0 +1,311 @@
+/** Device connect — the client half of the link-only auth handshake, in TS.
+ *
+ * Gets a token onto this machine and writes the SHARED ~/.atlaso/auth.json (the
+ * same file every connector reads), so the otherwise read-only hooks can talk to
+ * the user's cloud brain. Engine-free; global fetch only.
+ *
+ * Flow (PKCE + loopback, RFC 8252; the brain implements the server side —
+ * identical to the Python `connect.py`):
+ *   1. start a one-shot HTTP listener on 127.0.0.1:<ephemeral>
+ *   2. POST /v1/device/start  → send a PKCE challenge + that loopback redirect_uri,
+ *                               get back a verification link
+ *   3. open the link          → the user clicks "Authorize"; the browser is
+ *                               redirected to OUR loopback with a one-time code
+ *                               (machine-local — a phished link lands on the
+ *                               victim's own 127.0.0.1, not ours)
+ *   4. POST /v1/device/token  → redeem {code, code_verifier} for the token (one-time)
+ *   5. write auth.json (atomic + fsync'd)
+ *
+ * `maybeAutoconnect()` makes 1-2 automatic: a hook calls it and, if this machine
+ * isn't connected, spawns a DETACHED `bun run hooks/connect.ts` (which opens the
+ * browser). Fast + best-effort — never blocks the hook, never throws.
+ */
+import { spawn } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import {
+  appendFileSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync,
+  renameSync, statSync, unlinkSync, writeFileSync, writeSync,
+} from "node:fs";
+import { createServer, type Server } from "node:http";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { atlasoDir, authPath, defaultServer, loadAuth } from "./atlaso";
+import { invalidate as invalidateVerdict } from "./state";
+
+const LOCK_NAME = ".connecting";
+const LOCK_TTL_MS = 15 * 60 * 1000;
+const START_TIMEOUT_MS = 15000;
+const POLL_TIMEOUT_MS = 15000;
+
+export function hasToken(): boolean {
+  return !!loadAuth()?.token;
+}
+
+function lockPath(): string {
+  return join(atlasoDir(), LOCK_NAME);
+}
+
+/** Atomically + durably write {server, token, user_id, device_id} at 0600:
+ *  unpredictable temp name (O_EXCL, no symlink follow), fsync the file, atomic
+ *  rename, then fsync the directory. Mirrors the Python `connect.save_auth`. */
+export function writeAuth(
+  server: string,
+  token: string,
+  user_id: string,
+  device_id: string | null,
+): string {
+  const dir = atlasoDir();
+  mkdirSync(dir, { recursive: true });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    /* ignore */
+  }
+  const p = authPath();
+  const data = JSON.stringify({ server, token, user_id, device_id }, null, 2);
+  const tmp = join(dir, `.auth.${process.pid}.${randomUUID()}.tmp`);
+  const fd = openSync(tmp, "wx", 0o600); // O_CREAT|O_EXCL|O_WRONLY, owner-only
+  try {
+    writeFileSync(fd, data);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, p);
+  try {
+    const dfd = openSync(dir, "r"); // fsync the dir so the rename is durable
+    try {
+      fsyncSync(dfd);
+    } finally {
+      closeSync(dfd);
+    }
+  } catch {
+    /* dir fsync best-effort */
+  }
+  // A fresh token = the link changed: drop any cached entitlement verdict so the
+  // next op re-verifies from scratch (no stale free pass to the new credential).
+  invalidateVerdict();
+  return p;
+}
+
+function openBrowser(url: string): void {
+  if (process.env.ATLASO_NO_BROWSER) return;
+  try {
+    const plt = process.platform;
+    const cmd = plt === "darwin" ? "open" : plt === "win32" ? "cmd" : "xdg-open";
+    const args = plt === "win32" ? ["/c", "start", "", url] : [url];
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** fetch with a hard timeout. null on timeout/transport error. */
+async function fetchT(url: string, init: RequestInit, ms: number): Promise<Response | null> {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), ms);
+  try {
+    return await fetch(url, { ...init, signal: ctrl.signal });
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+const b64url = (b: Buffer): string =>
+  b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/** (code_verifier, code_challenge) — RFC 7636 S256. The verifier never leaves this
+ *  process; only its sha256 challenge is sent at /device/start. */
+function pkcePair(): { verifier: string; challenge: string } {
+  const verifier = b64url(randomBytes(48)); // 64 url-safe chars (within RFC 43..128)
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+/** Serve the one-shot loopback callback. Resolves the one-time code once a request
+ *  arrives with a matching `state` (CSRF guard), or null on timeout. Other requests
+ *  (favicon, wrong state) get a 400 and are ignored. */
+function waitForCode(server: Server, expectedState: string, timeoutMs: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v: string | null) => {
+      if (done) return;
+      done = true;
+      resolve(v);
+    };
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    server.on("request", (req, res) => {
+      const u = new URL(req.url || "/", "http://127.0.0.1");
+      const code = u.searchParams.get("code") || "";
+      const st = u.searchParams.get("state") || "";
+      const ok = !!code && st === expectedState;
+      const msg = ok
+        ? "<h2>Atlaso connected ✓</h2><p>You can close this tab and return to your terminal.</p>"
+        : "<h2>Atlaso: connection failed</h2><p>Return to your terminal and try again.</p>";
+      res.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(`<html><body style='font-family:system-ui;max-width:30rem;margin:4rem auto;text-align:center'>${msg}</body></html>`);
+      if (ok) {
+        clearTimeout(timer);
+        finish(code);
+      }
+    });
+  });
+}
+
+/** Run the connect handshake to completion. 0 on success. Releases the lock. */
+export async function runConnect(): Promise<number> {
+  let server: Server | null = null;
+  try {
+    const base = (process.env.ATLASO_SERVER || loadAuth()?.server || defaultServer()).replace(/\/+$/, "");
+    const label = (hostname() || "this device").slice(0, 80);
+    const tool = process.env.ATLASO_TOOL || "opencode";
+    const existing = loadAuth() || ({} as Record<string, any>);
+    const { verifier, challenge } = pkcePair();
+    const state = b64url(randomBytes(16));
+
+    // Start a one-shot loopback listener on an ephemeral port (127.0.0.1 ONLY) —
+    // RFC 8252 §7.3. The approved code is delivered here, machine-local.
+    server = createServer();
+    const port = await new Promise<number>((resolve) => {
+      server!.once("error", () => resolve(0));
+      server!.listen(0, "127.0.0.1", () => {
+        const a = server!.address();
+        resolve(a && typeof a === "object" ? a.port : 0);
+      });
+    });
+    if (!port) return 1;
+    const redirectUri = `http://127.0.0.1:${port}/cb`;
+
+    const startBody: Record<string, any> = {
+      label, tool: tool.slice(0, 40), code_challenge: challenge, redirect_uri: redirectUri, state,
+    };
+    if (existing.device_id) startBody.device_id = existing.device_id; // reconnect rotates in place
+
+    const r = await fetchT(
+      `${base}/v1/device/start`,
+      { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(startBody) },
+      START_TIMEOUT_MS,
+    );
+    if (!r || !r.ok) return 1;
+    let d: any;
+    try {
+      d = await r.json();
+    } catch {
+      return 1;
+    }
+    const verifyUrl = d?.verification_uri_complete || d?.verification_uri || base;
+    const expiresIn = parseInt(String(d?.expires_in)) || 600;
+
+    // Surface the link even if the browser can't open (headless / xdg-open missing).
+    try {
+      appendFileSync(join(atlasoDir(), "connect.log"),
+        `${new Date().toISOString()} authorize this device: ${verifyUrl}\n`, { mode: 0o600 });
+    } catch {
+      /* best-effort */
+    }
+    console.log(`Atlaso — authorize this device:\n  ${verifyUrl}`);
+    openBrowser(verifyUrl);
+
+    const code = await waitForCode(server, state, expiresIn * 1000);
+    if (!code) return 1;
+
+    const tr = await fetchT(
+      `${base}/v1/device/token`,
+      { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ code, code_verifier: verifier }) },
+      POLL_TIMEOUT_MS,
+    );
+    if (!tr || tr.status !== 200) return 1;
+    let t: any;
+    try {
+      t = await tr.json();
+    } catch {
+      return 1;
+    }
+    if (t?.status === "approved") {
+      if (!t.token || !t.user_id) return 1;
+      writeAuth(base, t.token, t.user_id, t.device_id ?? null);
+      return 0;
+    }
+    return 1;
+  } finally {
+    try {
+      server?.close();
+    } catch {
+      /* ignore */
+    }
+    releaseConnectLock();
+  }
+}
+
+export function releaseConnectLock(): void {
+  try {
+    unlinkSync(lockPath());
+  } catch {
+    /* already gone */
+  }
+}
+
+/** Atomically claim the connect lock (O_EXCL). false if a fresh lock exists; a
+ *  stale lock (> TTL) is reclaimed. */
+function acquireLock(lock: string): boolean {
+  for (let i = 0; i < 2; i++) {
+    try {
+      const fd = openSync(lock, "wx", 0o600); // wx = O_CREAT|O_EXCL|O_WRONLY
+      try {
+        writeSync(fd, String(Date.now()));
+      } finally {
+        closeSync(fd);
+      }
+      return true;
+    } catch {
+      try {
+        if (Date.now() - statSync(lock).mtimeMs >= LOCK_TTL_MS) {
+          unlinkSync(lock); // stale → reclaim and retry
+          continue;
+        }
+      } catch {
+        /* ignore */
+      }
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Auto-trigger (called by the recall hook): if not connected, spawn a DETACHED
+ *  connect (opens the browser) and return true. No-op + false if already
+ *  connected, opted out (ATLASO_NO_CONNECT), extracting, in CI, or a connect is
+ *  already in flight. Fast — never blocks, never touches the network itself. */
+export function maybeAutoconnect(tool = "opencode"): boolean {
+  if (hasToken()) return false;
+  if (process.env.ATLASO_NO_CONNECT || process.env.ATLASO_EXTRACTING || process.env.CI) return false;
+  const dir = atlasoDir();
+  try {
+    mkdirSync(dir, { recursive: true });
+    chmodSync(dir, 0o700);
+  } catch {
+    /* ignore */
+  }
+  const lock = lockPath();
+  if (!acquireLock(lock)) return false;
+  try {
+    // lib/ → ../src/connect-entry.ts (the detached browser-authorize process)
+    const entry = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "connect-entry.ts");
+    spawn("bun", ["run", entry], {
+      stdio: "ignore",
+      detached: true,
+      env: { ...process.env, ATLASO_TOOL: tool },
+    }).unref();
+    return true;
+  } catch {
+    try {
+      unlinkSync(lock); // release so a later hook can retry
+    } catch {
+      /* ignore */
+    }
+    return false;
+  }
+}

package/lib/entitlement.ts

@@ -0,0 +1,75 @@
+/** Cloud-link / tool-entitlement gate — ported from the Python client's
+ *  `_online()` + `_verify_entitlement()` + `cloud_mode()`.
+ *
+ *  The free plan allows ONE active tool per device, and the brain does NOT
+ *  enforce that on the memory endpoints — so before any cloud recall/deposit the
+ *  hooks call `online()`, which checks the cached verdict and (when stale)
+ *  verifies with `/v1/entitlement`, self-claiming the active slot if it's free.
+ *  A non-active tool on a free plan runs LOCAL-ONLY (no cloud calls) and the
+ *  recall hook surfaces an upgrade notice. Verdict is cached + (tool, device)-scoped.
+ */
+import { claimToolCall, entitlementCall, markRevoked, type Auth } from "./atlaso";
+import * as state from "./state";
+
+export type { Verdict } from "./state";
+
+/** Should we attempt a cloud call right now? True = cloud-linked, False =
+ *  local-only this turn. Never throws (memory must never break a turn). Hits the
+ *  network only on a stale/foreign verdict (cached otherwise). */
+export async function online(auth: Auth | null, tool: string, deviceId: string | null): Promise<boolean> {
+  if (!auth) return false;
+  try {
+    const st = state.get();
+    const mine = state.matches(st, tool, deviceId);
+    if (st.mode === state.LOCAL_ONLY) {
+      if (mine && st.reason === state.REVOKED) return false; // sticky until reconnect
+      if (mine && state.isFresh(st)) return false; // trust a fresh local-only (e.g. not_entitled)
+      return await verify(auth, tool, deviceId);
+    }
+    if (mine && state.isFresh(st)) return true; // trust a fresh linked verdict
+    return await verify(auth, tool, deviceId);
+  } catch {
+    return false;
+  }
+}
+
+/** Ask the brain + persist a scoped verdict. */
+async function verify(auth: Auth, tool: string, deviceId: string | null): Promise<boolean> {
+  const ent = await entitlementCall(auth);
+  // null = revoked (call() already retired auth.json on 401/403) OR transient — either
+  // way, don't grant a cloud window this turn; leave state unchanged to retry next time.
+  if (!ent) return false;
+  if (ent.needs_reconnect) {
+    markRevoked(); // device gone server-side → re-authorize next session
+    return false;
+  }
+  const grace: state.Grace | null = ent.in_grace
+    ? { in_grace: true, days_left: ent.grace_days_left ?? null, tools_connected: ent.tools_connected ?? null }
+    : null;
+  // paid (or grace) → multi-tool; a generic/no-tool client is never gated.
+  if (ent.multi_tool || !tool) {
+    state.setLinked({ tool, device_id: deviceId, grace });
+    return true;
+  }
+  // free plan: single active tool.
+  let active: string | null = ent.active_tool ?? null;
+  if (active == null) {
+    const claimed = await claimToolCall(auth, tool); // self-claim the free slot
+    if (!claimed) return false;
+    active = claimed.active_tool ?? null;
+  }
+  if (active === tool) {
+    state.setLinked({ tool, device_id: deviceId });
+    return true;
+  }
+  state.setLocalOnly(state.NOT_ENTITLED, { active_tool: active, tool, device_id: deviceId });
+  return false;
+}
+
+/** The current verdict for surfacing a user notice (no network). */
+export function cloudMode(auth: Auth | null, tool: string, deviceId: string | null): state.Verdict {
+  if (!auth) return { ...state.defaultState(), mode: state.LOCAL_ONLY, reason: state.NOT_CONNECTED };
+  const st = state.get();
+  if (!state.matches(st, tool, deviceId)) return state.defaultState(); // foreign → no notice
+  return st;
+}

package/lib/log.ts

@@ -0,0 +1,16 @@
+/** Opt-in debug log (set ATLASO_DEBUG=1). Off by default — hooks stay quiet.
+ *  Mirrors the Python connector's `_shim.log`: per-hook files in the atlaso dir. */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atlasoDir } from "./atlaso";
+
+export function log(name: string, msg: string): void {
+  if (!process.env.ATLASO_DEBUG) return;
+  try {
+    const d = atlasoDir();
+    mkdirSync(d, { recursive: true });
+    appendFileSync(join(d, `atlaso-opencode-${name}.log`), `${new Date().toISOString()} ${msg}\n`);
+  } catch {
+    /* logging is best-effort */
+  }
+}

package/lib/project.ts

@@ -0,0 +1,168 @@
+/** Derive a stable PROJECT KEY for per-project memory — commodity, never the IP.
+ *
+ * Preserves the "automatic per-project memory" UX (new folder → its own isolated
+ * scope, zero setup) WITHOUT writing anything into the project folder. We only
+ * compute a string key from a directory:
+ *   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`.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, 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;
+  try {
+    cur = resolve(start || process.cwd());
+  } catch {
+    return 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 */
+      }
+    }
+    const parent = dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return cur; // no markers → the cwd itself is the "project"
+}
+
+/** Read remote.origin.url straight from .git/config (no subprocess). Handles a
+ *  `.git` FILE (worktrees) by following gitdir → commondir, so all worktrees of
+ *  one repo resolve to the SAME key. null if absent. */
+function gitOrigin(root: string): string | null {
+  try {
+    const gitpath = join(root, ".git");
+    let cfg: string | null = null;
+    let st;
+    try {
+      st = statSync(gitpath);
+    } catch {
+      return null;
+    }
+    if (st.isDirectory()) {
+      cfg = join(gitpath, "config");
+    } else if (st.isFile()) {
+      const txt = readFileSync(gitpath, "utf-8");
+      const m = txt.match(/gitdir:\s*(.+)/);
+      if (m) {
+        const gd = resolve(root, m[1].trim());
+        let common = gd;
+        const cd = join(gd, "commondir");
+        if (existsSync(cd)) {
+          try {
+            common = resolve(gd, readFileSync(cd, "utf-8").trim());
+          } catch {
+            common = gd;
+          }
+        }
+        cfg = join(common, "config");
+      }
+    }
+    if (!cfg || !existsSync(cfg)) return null;
+    const text = readFileSync(cfg, "utf-8");
+    let inOrigin = false;
+    for (const line of text.split(/\r?\n/)) {
+      const s = line.trim();
+      if (s.startsWith("[")) {
+        inOrigin = s.replace(/\s/g, "").toLowerCase().startsWith('[remote"origin"]');
+      } else if (inOrigin && s.toLowerCase().startsWith("url")) {
+        const val = s.slice(s.indexOf("=") + 1).trim();
+        return val || null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Normalize a git remote to a stable key: drop scheme/creds/.git, lowercase
+ *  host+path. git@github.com:me/app.git & https://github.com/me/app(.git) →
+ *  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)
+  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 {
+  try {
+    const root = projectRoot(start);
+    const origin = gitOrigin(root);
+    if (origin) {
+      const key = normalizeRemote(origin);
+      if (key) return key.slice(0, 120);
+    }
+    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}`;
+  } catch {
+    return null;
+  }
+}
+
+/** (scope, project_key) from a deposit's tags — mirrors the server + Python
+ *  `_project.scope_of`. */
+export function scopeOf(tags: string[] | undefined): [string, string | null] {
+  let scope = "personal";
+  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);
+  }
+  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`. */
+export function visibleInProject(
+  tags: string[] | undefined,
+  project: string | null | undefined,
+): boolean {
+  const [scope, pkey] = scopeOf(tags);
+  if (scope !== "project") return true;
+  if (pkey === null) return false;
+  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.) */
+export function workspaceRoot(payload: Record<string, any>): string | null {
+  const p = payload || {};
+  const candidates: unknown[] = [
+    Array.isArray(p.workspace_roots) ? p.workspace_roots[0] : undefined,
+    Array.isArray(p.workspaceRoots) ? p.workspaceRoots[0] : undefined,
+    p.project?.workspaceRoot,
+    p.workspaceRoot,
+    p.workspace_root,
+    p.cwd,
+  ];
+  for (const c of candidates) if (typeof c === "string" && c.trim()) return c;
+  return process.env.PWD || process.cwd() || null;
+}

package/lib/render.ts

@@ -0,0 +1,62 @@
+/** Build the recalled-memory injection STRING for OpenCode.
+ *
+ * Unlike Cursor (which writes a `.mdc` rules file because its sessionStart
+ * injection is broken), OpenCode lets a plugin inject context directly by pushing
+ * a synthetic text part onto the chat.message output. So here we just build a
+ * plain fenced block:
+ *
+ *   === Atlaso Memory ===
+ *   - <note>  [scope]
+ *   - [conflict] <note> (conflicts with N other notes)  [project]
+ *   === Atlaso Memory ===
+ *
+ * Per-note semantics mirror the Python `_render.recall_block` + Cursor's
+ * `lib/render`: a plain branded block (NO "untrusted data" warning, NO
+ * instructions — the model decides), each conflict flagged with a peer COUNT
+ * (never leaking internal ids), scope appended. Stored content is sanitized so it
+ * can't forge our own `=== Atlaso Memory ===` fence (→ `[atlaso]`).
+ *
+ * Returns null when there are no usable results (caller injects nothing).
+ */
+import type { RecallResult } from "./atlaso";
+
+const BANNER = "Atlaso Memory";
+const FENCE = `=== ${BANNER} ===`;
+// neutralize any forged Atlaso fence inside stored content (memory OR orientation,
+// opening OR closing), so recalled text can never spoof our block boundary.
+const FENCE_RE = /=+\s*(?:END\s+)?Atlaso\s+(?:Memory|Orientation)[^\n]*/gi;
+
+export interface RenderOpts {
+  /** Override the banner (tests / future tools). Defaults to "Atlaso Memory". */
+  banner?: string;
+}
+
+/** Collapse a stored note to a single safe line. */
+function clean(text: string): string {
+  return (text || "").trim().replace(FENCE_RE, "[atlaso]").replace(/\s*\n+\s*/g, " ");
+}
+
+/** One bullet per result: optional [conflict] prefix + peer count + [scope]
+ *  suffix (mirrors Cursor's `line` / the Python recall_block). null if empty. */
+function line(r: RecallResult): string | null {
+  const content = clean(r.content || "");
+  if (!content) return null;
+  const hd = !!r.has_disagreement;
+  let out = "- " + (hd ? "[conflict] " : "") + content;
+  const peers = Array.isArray(r.conflict_peers) ? r.conflict_peers.length : 0;
+  if (hd && peers) out += ` (conflicts with ${peers} other note${peers !== 1 ? "s" : ""})`;
+  if (r.scope) out += `  [${r.scope}]`;
+  return out;
+}
+
+/** The fenced injection string, or null when nothing is worth injecting. */
+export function renderBlock(results: RecallResult[] | null | undefined, opts: RenderOpts = {}): string | null {
+  const fence = opts.banner ? `=== ${opts.banner} ===` : FENCE;
+  const lines: string[] = [];
+  for (const r of results || []) {
+    const l = line(r);
+    if (l) lines.push(l);
+  }
+  if (!lines.length) return null;
+  return `${fence}\n${lines.join("\n")}\n${fence}`;
+}