@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/brief-writers.ts

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto"
+import { join } from "node:path"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "./adapters/types.ts"
+import { BRIEF_BUDGET, LEAN_BUDGET, buildBrief, toolLabel } from "./brief.ts"
+import { gitInfo } from "./fsutil.ts"
+import { handoffDir, markConsumed, saveHandoff } from "./handoff.ts"
+import { hookInstalled } from "./hooks.ts"
+import type { Session } from "./session/types.ts"
+
+// Continuing a session in any tool by a brief: the universal fallback, and the only way into tools that
+// keep sessions on their servers or in formats nothing else can write. The brief is saved as a pending
+// handoff (for the target's session-start hook, when installed) and as a Markdown file to paste.
+// Cursor gets its own route: its prompt deeplink opens the editor with the brief in the chat box,
+// ready to send, without writing to Cursor's database.
+
+const CURSOR_DEEPLINK_LIMIT = 10_000
+
+export const BRIEF_TARGETS = ["claude-code", "codex", "cursor", "cursor-cli", "gemini-cli", "vscode-copilot", "copilot-cli", "cline", "opencode", "100xprompt", "antigravity", "any"]
+
+/** `cursor://` deeplink that opens Cursor's chat with `text` filled in (Cursor asks before sending). */
+export function cursorPromptLink(text: string): string {
+  return `cursor://anysphere.cursor-deeplink/prompt?text=${encodeURIComponent(text.slice(0, CURSOR_DEEPLINK_LIMIT))}`
+}
+
+export function briefWriter(target: string, named?: string): Writer {
+  const label = named ?? (target === "any" ? "any tool" : target === "cursor" ? "Cursor" : toolLabel(target))
+  return {
+    tool: target,
+    label,
+    way: "brief",
+    async ready(): Promise<Readiness> {
+      return { ok: true }
+    },
+    async write(session: Session, opts: WriteOptions): Promise<WriteResult> {
+      const lean = !!opts.brief?.lean
+      const budget = lean ? LEAN_BUDGET : BRIEF_BUDGET[target] ?? BRIEF_BUDGET.default!
+      const brief = buildBrief(session, { budget, lean, ...(opts.brief?.memory?.length ? { memory: opts.brief.memory } : {}), ...(opts.brief?.map ? { map: opts.brief.map } : {}), fullRecord: `brain session show ${session.header.id}` })
+      const id = `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`
+      const briefPath = join(handoffDir(opts.home), `${id}.md`)
+      const written = [briefPath, join(handoffDir(opts.home), `${id}.json`)]
+      if (!opts.dryRun) {
+        saveHandoff(opts.home, {
+          id,
+          fromTool: session.header.tool,
+          sessionId: session.header.id,
+          ...(session.header.title ? { title: session.header.title } : {}),
+          cwd: opts.cwd,
+          ...(gitInfo(opts.cwd).gitRemote ? { gitRemote: gitInfo(opts.cwd).gitRemote } : {}),
+          target: target === "cursor" ? "cursor-ide" : target,
+          brief,
+        })
+      }
+      let open: string
+      if (target === "cursor" && hookInstalled("cursor-ide", opts.home)) {
+        // Cursor's session-start hook delivers it; the deeplink as well would give the next chat the brief twice.
+        open = `open -a Cursor ${JSON.stringify(opts.cwd)}, then start a new chat: Cursor's session-start hook gives the model the brief.`
+      } else if (target === "cursor") {
+        open = `open -a Cursor ${JSON.stringify(opts.cwd)} && open ${JSON.stringify(cursorPromptLink(`Continue this work.\n\n${brief}`))}`
+        // Delivered by the deeplink: claimed now, so a hook installed later does not deliver it again.
+        if (!opts.dryRun) markConsumed(opts.home, id, "cursor-ide")
+      } else if (hookInstalled(target, opts.home)) {
+        open = `Start ${label} in ${opts.cwd}: its session-start hook gives the model the brief.`
+      } else {
+        open = `Start ${label} in ${opts.cwd} and paste the brief as your first message: ${briefPath}`
+      }
+      return { tool: target, way: "brief", written, open, lost: [lean ? "everything but the brief: the model gets the essentials and what the project remembers; the rest is stored and reachable on demand" : "everything but the brief: the model gets a summary and the latest turns, not the full history"], dryRun: !!opts.dryRun }
+    },
+  }
+}
+
+export const briefWriters: Writer[] = BRIEF_TARGETS.map((t) => briefWriter(t))

package/src/brief.ts

@@ -0,0 +1,238 @@
+import type { Session, Turn } from "./session/types.ts"
+import { asText, firstUserText } from "./session/util.ts"
+
+// The continuation brief: what a model needs to carry on a session it never saw, in a fixed budget.
+// Built without a model call, from the portable session, essentials first: where it came from, the goal,
+// where it stands, files changed, commands run, the latest requests, then as many recent turns as fit.
+// Design: docs/sessions/2026-11-08-session-switcher.md, section 3.2.
+
+/** Characters each target takes at session start (Codex hook output ~2,500 tokens; Claude Code SessionStart 10,000 characters; Cursor's prompt deeplink 10,000). */
+export const BRIEF_BUDGET: Record<string, number> = {
+  "claude-code": 9_500,
+  codex: 8_000,
+  cursor: 8_000,
+  default: 8_000,
+}
+
+const LABEL: Record<string, string> = {
+  "claude-code": "Claude Code",
+  codex: "Codex",
+  "cursor-ide": "Cursor",
+  "cursor-cli": "the Cursor CLI",
+  "gemini-cli": "Gemini CLI",
+  "vscode-copilot": "Copilot Chat in VS Code",
+  "copilot-cli": "the Copilot CLI",
+  cline: "Cline",
+  roo: "Roo Code",
+  opencode: "OpenCode",
+  "100xprompt": "100xprompt",
+  cursor: "Cursor",
+  aider: "Aider",
+  antigravity: "Antigravity",
+  devin: "Devin CLI",
+  hermes: "Hermes Agent",
+  mastracode: "Mastra Code",
+  muse: "Muse Code",
+  omp: "Oh My Pi",
+  "amazon-q-cli": "the Amazon Q CLI",
+  "amazon-q-ide": "Amazon Q in the IDE",
+  auggie: "Auggie",
+  "cline-sdk": "Cline",
+  "cline-cursor": "Cline in Cursor",
+  "cline-windsurf": "Cline in Windsurf",
+  "roo-cursor": "Roo Code in Cursor",
+  "roo-windsurf": "Roo Code in Windsurf",
+  codebuff: "Codebuff",
+  continue: "Continue",
+  crush: "Crush",
+  "factory-droid": "Factory Droid",
+  goose: "Goose",
+  "grok-cli": "Grok CLI",
+  "iflow-cli": "iFlow CLI",
+  "kilo-cli": "Kilo CLI",
+  "kilo-code": "Kilo Code",
+  "kilo-code-cursor": "Kilo Code in Cursor",
+  "kilo-code-windsurf": "Kilo Code in Windsurf",
+  "kimi-code": "Kimi Code",
+  "kiro-cli": "Kiro CLI",
+  "kiro-ide": "Kiro IDE",
+  "letta-code": "Letta Code",
+  "mistral-vibe": "Mistral Vibe",
+  openhands: "OpenHands",
+  pearai: "PearAI",
+  pi: "Pi",
+  "qoder-cli": "Qoder CLI",
+  "qwen-code": "Qwen Code",
+  "tabnine-cli": "Tabnine CLI",
+  void: "Void",
+  zed: "Zed",
+  any: "any tool",
+}
+export const toolLabel = (tool: string) => LABEL[tool] ?? tool
+
+const cut = (s: string, n: number) => (s.length <= n ? s : `${s.slice(0, n - 1).trimEnd()}…`)
+const oneLine = (s: string) => s.replace(/\s+/g, " ").trim()
+
+function ago(when: string | undefined, now: number): string {
+  if (!when) return "at an unknown time"
+  const m = Math.round((now - Date.parse(when)) / 60_000)
+  if (!Number.isFinite(m) || m < 0) return `at ${when}`
+  if (m < 2) return "just now"
+  if (m < 90) return `${m} minutes ago`
+  if (m < 48 * 60) return `${Math.round(m / 60)} hours ago`
+  return `${Math.round(m / 1440)} days ago`
+}
+
+/** Files the session changed, from file_edit turns and edit/write tool calls, in order of first change. */
+export function changedFiles(s: Session): string[] {
+  const out: string[] = []
+  const add = (p: unknown) => {
+    if (typeof p === "string" && p && !out.includes(p)) out.push(p)
+  }
+  for (const t of s.turns) {
+    if (t.kind === "file_edit") add(t.path)
+    if (t.kind === "tool_call" && (t.toolKind === "edit" || t.toolKind === "write")) {
+      const i = (t.input ?? {}) as Record<string, unknown>
+      add(i.file_path ?? i.path ?? i.target_file ?? i.filePath ?? i.relativeWorkspacePath ?? i.file)
+    }
+  }
+  return out
+}
+
+/** Shell commands the session ran, in order. */
+export function commandsRun(s: Session): string[] {
+  const out: string[] = []
+  for (const t of s.turns) {
+    if (t.kind !== "tool_call" || t.toolKind !== "shell") continue
+    const i = (t.input ?? {}) as Record<string, unknown>
+    const c = i.command ?? i.cmd ?? i.commandLine
+    const text = Array.isArray(c) ? c.join(" ") : typeof c === "string" ? c : undefined
+    if (text) out.push(oneLine(text))
+  }
+  return out
+}
+
+function renderTurn(t: Turn, calls: Map<string, string>): string | undefined {
+  switch (t.kind) {
+    case "user":
+      return `USER: ${cut(t.text.trim(), 1_200)}`
+    case "assistant":
+      return t.text.trim() ? `ASSISTANT: ${cut(t.text.trim(), 1_200)}` : undefined
+    case "tool_call":
+      return `TOOL ${t.name}: ${cut(oneLine(asText(t.input)), 240)}`
+    case "tool_result":
+      return `RESULT${t.ok ? "" : " (error)"} of ${calls.get(t.callId) ?? "tool"}: ${cut(oneLine(t.output), 300)}`
+    case "compaction":
+      return `EARLIER (summarised): ${cut(t.summary.trim(), 1_500)}`
+    case "reasoning":
+      return undefined
+    case "file_edit":
+      return `EDITED ${t.path}`
+    case "subagent":
+      return `SUBAGENT${t.description ? `: ${cut(t.description, 200)}` : ""}`
+  }
+}
+
+/** The remembered items as a section, at most MEMORY_CHARS characters, one line each. */
+function memorySection(items: BriefOptions["memory"]): string | undefined {
+  if (!items?.length) return undefined
+  const lines: string[] = []
+  let used = 0
+  for (const m of items) {
+    const line = `- ${m.kind ? `[${m.kind}] ` : ""}${cut(oneLine(m.text), 400)}`
+    if (used + line.length + 1 > MEMORY_CHARS) break
+    lines.push(line)
+    used += line.length + 1
+  }
+  return lines.length ? `\nREMEMBERED FOR THIS PROJECT (from earlier sessions, any tool):\n${lines.join("\n")}` : undefined
+}
+
+export interface BriefOptions {
+  budget?: number
+  now?: number
+  /** How the person can see the whole session, shown at the end. */
+  fullRecord?: string
+  /**
+   * What the project's memory holds that matters for the first request (brain memory, already limited to a token
+   * budget and redacted). Shown as its own section after the goal and state.
+   */
+  memory?: Array<{ kind?: string; text: string; source?: string }>
+  /**
+   * Lean: the essentials plus memory and only the last few turns, in a smaller budget. The rest stays reachable through
+   * the brain tools (`brain_recall`, `brain_expand`) or the CLI, so it costs tokens only when the model asks.
+   */
+  lean?: boolean
+  /** Name the on-demand tools in the closing line. Default true when lean. */
+  mention?: boolean
+  /** A compact repo map (see memory/repomap.ts), shown in its own section in lean briefs only, at most MAP_CHARS characters. */
+  map?: string
+}
+
+/** Characters of a lean brief, and how many recent turns it keeps. */
+export const LEAN_BUDGET = 4_500
+const LEAN_TURNS = 6
+/** The most characters the memory section may take. */
+const MEMORY_CHARS = 1_800
+/** The most characters the project map may take of a lean brief. */
+export const MAP_CHARS = 1_200
+
+/** The map as a section: whole lines only, at most MAP_CHARS characters; shorter text is used as it is. */
+export function mapSection(map: string | undefined): string | undefined {
+  const t = map?.trim()
+  if (!t) return undefined
+  const head = "\nPROJECT MAP (regenerated from the code):\n"
+  const room = MAP_CHARS - head.length + 1
+  let body = t
+  if (body.length > room) {
+    const lines = body.slice(0, room).split("\n")
+    lines.pop() // the last line may be cut mid-way
+    body = lines.join("\n")
+  }
+  return body ? `${head}${body}` : undefined
+}
+
+/** A continuation brief for `s`, at most `budget` characters. */
+export function buildBrief(s: Session, opts: BriefOptions = {}): string {
+  const budget = opts.budget ?? (opts.lean ? LEAN_BUDGET : BRIEF_BUDGET.default!)
+  const now = opts.now ?? Date.now()
+  const h = s.header
+  const where = [h.project.cwd, h.project.gitBranch && `branch ${h.project.gitBranch}`].filter(Boolean).join(", ")
+  const head: string[] = [
+    `You are continuing a session that started in ${toolLabel(h.tool)}${h.title ? ` ("${cut(oneLine(h.title), 120)}")` : ""}, last active ${ago(h.updatedAt, now)}${where ? `, in ${where}` : ""}. The person switched tools and wants to carry on where it left off. Treat what follows as the history of this work; check files before relying on details, since they may have changed.`,
+  ]
+  const goal = firstUserText(s)
+  if (goal) head.push(`\nGOAL (the first request):\n${cut(goal.trim(), 900)}`)
+  const lastAssistant = [...s.turns].reverse().find((t) => t.kind === "assistant" && t.text.trim()) as Extract<Turn, { kind: "assistant" }> | undefined
+  if (lastAssistant) head.push(`\nWHERE IT STANDS (the last reply):\n${cut(lastAssistant.text.trim(), 1_200)}`)
+  const memory = memorySection(opts.memory)
+  if (memory) head.push(memory)
+  const mapText = opts.lean ? mapSection(opts.map) : undefined
+  if (mapText) head.push(mapText)
+  const files = changedFiles(s)
+  if (files.length) head.push(`\nFILES CHANGED (${files.length}):\n${files.slice(0, 30).map((f) => `- ${f}`).join("\n")}${files.length > 30 ? `\n- and ${files.length - 30} more` : ""}`)
+  const cmds = commandsRun(s)
+  if (cmds.length) head.push(`\nLAST COMMANDS RUN:\n${cmds.slice(-8).map((c) => `- ${cut(c, 200)}`).join("\n")}`)
+  const users = s.turns.filter((t) => t.kind === "user" && t.text.trim()) as Array<Extract<Turn, { kind: "user" }>>
+  if (users.length > 1) head.push(`\nLATEST REQUESTS:\n${users.slice(-3).map((u) => `- ${cut(oneLine(u.text), 400)}`).join("\n")}`)
+  const mention = opts.mention ?? !!opts.lean
+  const tail = `\n${opts.fullRecord ? `The whole session: ${opts.fullRecord}. ` : ""}${mention ? "More is stored than shown here: ask with the brain_recall tool (what the project knows) or brain_expand (a full tool output shown as \"output stored\"). " : ""}Pick up from the latest request; ask if the next step is unclear.`
+
+  let text = head.join("\n")
+  const room = budget - text.length - tail.length - 40
+  if (room > 200) {
+    // The most recent turns, newest last, as many as fit.
+    const calls = new Map(s.turns.filter((t) => t.kind === "tool_call").map((t) => [(t as Extract<Turn, { kind: "tool_call" }>).id, (t as Extract<Turn, { kind: "tool_call" }>).name]))
+    const lines: string[] = []
+    let used = 0
+    for (const t of [...s.turns].reverse()) {
+      const line = renderTurn(t, calls)
+      if (!line) continue
+      if (used + line.length + 1 > room || (opts.lean && lines.length >= LEAN_TURNS)) break
+      lines.unshift(line)
+      used += line.length + 1
+    }
+    if (lines.length) text += `\n\nRECENT TURNS:\n${lines.join("\n")}`
+  }
+  text += tail
+  return text.length <= budget ? text : cut(text, budget)
+}

package/src/cli.ts

@@ -0,0 +1,351 @@
+#!/usr/bin/env bun
+import { writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { parseArgs } from "node:util"
+import type { SessionRef, Way, WriteResult } from "./adapters/types.ts"
+import { changedFiles, toolLabel } from "./brief.ts"
+import { gitInfo, homeDir } from "./fsutil.ts"
+import { secureSelf } from "./self.ts"
+import { HOOK_TOOLS, installHooks, runHook, uninstallHooks } from "./hooks.ts"
+import type { Session } from "./session/types.ts"
+import { prepare, sessionTokens } from "./memory/prepare.ts"
+import { countTurns, firstUserText, toJsonl, unpaired } from "./session/util.ts"
+
+// brain session: one working session, any AI coding tool.
+// Design: docs/sessions/2026-11-08-session-switcher.md.
+
+// Adapters load only for commands that use them: every tool's session-start hook runs this file, and
+// one adapter failing to load (or loading slowly) must not hold up or break a session in another tool.
+let loaded: typeof import("./adapters/index.ts") | undefined
+const adapters = async () => (loaded ??= await import("./adapters/index.ts"))
+
+const USAGE = `brain session <command>
+
+  list [--tool <id>] [--here] [--limit 30] [--json]   every session on this machine, newest first
+  show <id> [--json]                                  a session's header, size and what would be lost
+  export <id> [-o file]                               the portable session (brain-session/v1 JSONL)
+  continue <id> --in <tool> [--way native|import|brief] [--cwd dir] [--dry-run] [--no-open]
+  handoff --in <tool> [--from <tool>] [--dry-run] [--no-open]   the newest session in this folder, to <tool>
+  continue/handoff also take  [--lean | --full] [--budget <tokens>] [--no-memory] [--no-tidy]   lean: big tool output becomes digests (automatic on long sessions); budget: mask in levels until the session fits
+  targets                                             where a session can go, and how
+  hooks install|uninstall|status [--tool <id>] [--dry-run]    session-start hooks that deliver briefs
+  hook <event> --tool <id>                            (run by a tool's hook; reads the hook's JSON on stdin)
+
+  <id> is <tool>:<session id> as \`list\` prints it, or a unique start of the session id.
+
+brain memory ingest <id> | search <query> [--project p] | status | forget [--project p] [--source id] | sync [--here] [--limit n]   what projects remember, across tools
+brain tokens audit [--dir <folder>]                static, read-only check of what a project reloads into every request (instruction files, MCP servers, ignore files)
+brain tokens lookups                               how often each kind of stubbed output is asked back (brain_expand); a high rate means its preview is too thin
+brain org login --server <url> --token <t> | logout | whoami | status | promote|demote (--ids a,b | --source <id>) --to <scope> | forget --mine
+brain org admin init|serve|user|token|team|project|policy|audit|retention   shared memory for an organisation (roles, scopes, audit)
+brain mcp serve | install | uninstall | status [--tool <id>]   the brain_recall / brain_expand tools for your AI tools
+brain gateway login [--no-browser] | logout | connect --tool <id> | disconnect --tool <id> | status | tools   sign in to 100xprompt and route a coding tool through its gateway (and back)
+brain dashboard [push|on|off|status] [--quiet] [--no-open]   send this machine's report (tools, gateway, conversions; never chat text) to your 100xprompt account and open its Brain view
+brain --version                                    the version, and where this brain runs from
+brain expand <blob id>                              the full text of a tool output that was replaced by a digest`
+
+const home = homeDir()
+const out = (s: string) => process.stdout.write(`${s}\n`)
+// Output piped into something that stops reading early (`brain session list | head`) ends quietly, not with a trace.
+process.stdout.on("error", (e: NodeJS.ErrnoException) => {
+  if (e.code === "EPIPE") process.exit(0)
+  throw e
+})
+secureSelf()
+const fail = (s: string): never => {
+  process.stderr.write(`brain: ${s}\n`)
+  process.exit(1)
+}
+/** After a command that changes what the dashboard report says: a report in a detached process (src/dashboard/send.ts). */
+async function reportLater() {
+  try {
+    const { reportInBackground } = await import("./dashboard/send.ts")
+    reportInBackground(home)
+  } catch {}
+}
+
+async function allRefs(tool?: string): Promise<{ refs: SessionRef[]; errors: string[] }> {
+  const { READERS } = await adapters()
+  const readers = tool ? READERS.filter((r) => r.tool === tool) : READERS
+  if (tool && !readers.length) fail(`no reader for "${tool}"; readers: ${READERS.map((r) => r.tool).join(", ")}`)
+  const errors: string[] = []
+  const lists = await Promise.all(readers.map(async (r) => {
+    try {
+      return await r.list(home)
+    } catch (e) {
+      errors.push(`${r.tool}: ${(e as Error).message}`)
+      return []
+    }
+  }))
+  return { refs: lists.flat().sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "")), errors }
+}
+
+async function resolveRef(given: string): Promise<SessionRef> {
+  // An id copied from an older, shortened list ends in "…": what comes before it is still a unique start.
+  const id = given.replace(/…$/, "")
+  const { readerFor } = await adapters()
+  const colon = id.indexOf(":")
+  const tool = colon > 0 && readerFor(id.slice(0, colon)) ? id.slice(0, colon) : undefined
+  const want = tool ? id.slice(colon + 1) : id
+  const { refs } = await allRefs(tool)
+  const exact = refs.filter((r) => r.sourceId === want)
+  const matches = exact.length ? exact : refs.filter((r) => r.sourceId.startsWith(want))
+  if (!matches.length) fail(`no session "${id}"; see \`brain session list\``)
+  if (matches.length > 1) fail(`"${id}" matches ${matches.length} sessions (${matches.slice(0, 4).map((r) => `${r.tool}:${r.sourceId}`).join(", ")}…); give more of the id`)
+  return matches[0]!
+}
+
+async function readRef(ref: SessionRef): Promise<Session> {
+  const { readerFor } = await adapters()
+  return readerFor(ref.tool)!.read(ref, home)
+}
+
+/**
+ * Whether a session that ran in `cwd` belongs to the folder `here`: the same folder or one inside it, or a
+ * folder above it in the same git repository. A folder above that is not the same repository (/tmp, home)
+ * is a different project, so a session there is never "here" and never handed off.
+ */
+function inProject(cwd: string | undefined, here: string): boolean {
+  if (!cwd) return false
+  if (cwd === here || cwd.startsWith(`${here}/`)) return true
+  if (!here.startsWith(`${cwd}/`) || cwd === home || home.startsWith(`${cwd}/`)) return false
+  const a = gitInfo(cwd).gitRemote
+  return !!a && a === gitInfo(here).gitRemote
+}
+
+const ago = (when?: string) => {
+  if (!when) return "?"
+  const m = (Date.now() - Date.parse(when)) / 60_000
+  return m < 60 ? `${Math.max(0, Math.round(m))}m ago` : m < 48 * 60 ? `${Math.round(m / 60)}h ago` : `${Math.round(m / 1440)}d ago`
+}
+const short = (p?: string) => (p ? p.replace(home, "~") : "")
+const cut = (s: string, n: number) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`)
+
+function describe(s: Session): string {
+  const c = countTurns(s)
+  const u = unpaired(s)
+  const h = s.header
+  const lines = [
+    `${h.id}  (${toolLabel(h.tool)}${h.toolVersion ? ` ${h.toolVersion}` : ""})`,
+    h.title ? `title     ${h.title}` : "",
+    `project   ${short(h.project.cwd)}${h.project.gitBranch ? ` @ ${h.project.gitBranch}` : ""}`,
+    `when      ${h.startedAt ?? "?"} → ${h.updatedAt ?? "?"}`,
+    `models    ${h.models.join(", ") || "?"}`,
+    `turns     ${c.user} user, ${c.assistant} assistant, ${c.tool_call} tool calls, ${c.tool_result} results, ${c.reasoning} reasoning, ${c.compaction} compactions, ${c.subagent} subagents${s.children?.length ? ` (${s.children.length} read)` : ""}`,
+    `files     ${changedFiles(s).length} changed`,
+    u.calls.length || u.results.length ? `unpaired  ${u.calls.length} calls without a result, ${u.results.length} results without a call` : "",
+    `lost      ${h.lost.length ? h.lost.join("; ") : "nothing"}`,
+    `source    ${short(h.sourcePath)}`,
+    firstUserText(s) ? `first ask ${cut(firstUserText(s)!.replace(/\s+/g, " "), 160)}` : "",
+  ]
+  return lines.filter(Boolean).join("\n")
+}
+
+function report(r: WriteResult) {
+  out(`${r.dryRun ? "Would continue" : "Continued"} in ${r.tool} by ${r.way === "native" ? "a native session" : r.way === "import" ? "its own import" : "a brief"}${r.sessionId ? ` (session ${r.sessionId})` : ""}.`)
+  for (const w of r.written) out(`  ${r.dryRun ? "would write" : "wrote"} ${short(w)}`)
+  if (r.lost.length) out(`  not carried over: ${r.lost.join("; ")}`)
+  out(`Next: ${r.open}`)
+  if (r.note) out(`  then: ${r.note}`)
+}
+
+async function continueIn(source: Session, target: string, opts: { way?: Way; cwd?: string; dryRun: boolean; open: boolean; lean?: boolean; noMemory?: boolean; budget?: number; tidy?: false }) {
+  const { writersFor } = await adapters()
+  const candidates = writersFor(target).filter((w) => !opts.way || w.way === opts.way)
+  if (!candidates.length) fail(`can't continue in "${target}"${opts.way ? ` by ${opts.way}` : ""}; see \`brain session targets\``)
+  const cwd = resolve(opts.cwd ?? source.header.project.cwd ?? process.cwd())
+  const prepared = await prepare(source, { home, cwd, dryRun: opts.dryRun, ...(opts.lean !== undefined ? { lean: opts.lean } : {}), ...(opts.noMemory ? { noMemory: true } : {}), ...(opts.budget ? { budget: opts.budget } : {}), ...(opts.tidy === false ? { tidy: false } : {}) })
+  const session = prepared.session
+  for (const n of prepared.notes) out(n)
+  const wopts = { home, cwd, dryRun: opts.dryRun, brief: prepared.brief }
+  const skipped: string[] = []
+  for (const w of candidates) {
+    const ready = await w.ready(wopts)
+    if (!ready.ok) {
+      skipped.push(`${w.way}: ${ready.why}`)
+      continue
+    }
+    for (const s of skipped) out(`(${s}; using the next way)`)
+    const r = await w.write(session, wopts)
+    report(r)
+    if (!r.dryRun) {
+      // The dashboard's conversion log: tools, way, title, project folder name and sizes; never the chat (src/dashboard/conversions.ts).
+      const { logConversion } = await import("./dashboard/conversions.ts")
+      const { readerFor } = await adapters()
+      const to = r.tool === "cursor" ? "cursor-ide" : r.tool
+      logConversion(home, { from: source.header.tool, fromLabel: readerFor(source.header.tool)?.label ?? toolLabel(source.header.tool), to: r.tool, toLabel: readerFor(to)?.label ?? w.label, way: r.way, title: source.header.title, cwd: source.header.project.cwd ?? cwd, turns: source.turns.length, tokens: sessionTokens(session), lean: prepared.lean })
+    }
+    if (!r.dryRun && r.way === "brief") {
+      const brief = Bun.file(r.written[0]!)
+      // The clipboard where the system has one (pbcopy on macOS, wl-copy or xclip on Linux, clip on Windows); a missing tool is fine.
+      const copy = process.platform === "darwin" ? ["pbcopy"] : process.platform === "win32" ? ["clip"] : Bun.which("wl-copy") ? ["wl-copy"] : ["xclip", "-selection", "clipboard"]
+      let copied = false
+      try {
+        if (await brief.exists()) copied = Bun.spawnSync(copy, { stdin: Buffer.from(await brief.text()) }).exitCode === 0
+      } catch {}
+      if (copied) out("  (the brief is also on the clipboard)")
+    }
+    if (!r.dryRun && opts.open && target === "cursor") Bun.spawnSync(["/bin/sh", "-c", r.open])
+    if (!r.dryRun) await reportLater()
+    return
+  }
+  fail(`no way to continue in "${target}" right now: ${skipped.join("; ")}`)
+}
+
+/** --lean / --full into the option (neither: decided by the session's size). */
+const leanOf = (v: { lean?: boolean; full?: boolean }): { lean?: boolean } => (v.lean && v.full ? fail("--lean and --full together?") : v.lean ? { lean: true } : v.full ? { lean: false } : {})
+
+/** --budget <tokens> into a positive integer (or a clear failure). */
+const budgetOf = (v: { budget?: string }): { budget?: number } => {
+  if (v.budget === undefined) return {}
+  const n = Number(v.budget)
+  if (!Number.isInteger(n) || n < 1_000) fail("--budget needs a whole number of tokens, at least 1000 (for example --budget 80000)")
+  return { budget: n }
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2)
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") return out(USAGE)
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    const { CLI_PATH, PACKAGE, VERSION, isEphemeral } = await import("./self.ts")
+    out(`${PACKAGE} ${VERSION}`)
+    out(`running from ${CLI_PATH}${isEphemeral() ? " (a temporary bunx copy: hooks and MCP entries it installs run the pinned package)" : ""}`)
+    return
+  }
+  // Commands with their own flags: `mcp serve` must keep stdout clean for the protocol, so they run before option parsing.
+  if (cmd === "gateway") {
+    const { gatewayCommand } = await import("./gateway/connect.ts")
+    const code = await gatewayCommand(rest, home)
+    if (code === 0 && ["login", "logout", "connect", "disconnect"].includes(rest[0] ?? "") && !rest.includes("--dry-run")) await reportLater()
+    process.exit(code)
+  }
+  if (cmd === "mcp") {
+    const { mcpCommand } = await import("./memory/mcp-install.ts")
+    const code = await mcpCommand(rest, home)
+    if (code === 0 && ["install", "uninstall"].includes(rest[0] ?? "") && !rest.includes("--dry-run")) await reportLater()
+    process.exit(code)
+  }
+  if (cmd === "dashboard") {
+    const { dashboardCommand } = await import("./dashboard/cli.ts")
+    process.exit(await dashboardCommand(rest, home))
+  }
+  if (cmd === "memory" && rest[0] === "sync") {
+    const { syncMemory } = await import("./memory/sync.ts")
+    const here = rest.includes("--here")
+    const limitAt = rest.indexOf("--limit")
+    const r = await syncMemory({ home, ...(here ? { cwd: process.cwd() } : {}), ...(limitAt >= 0 ? { limit: Number(rest[limitAt + 1]) || 8 } : {}) })
+    if (!rest.includes("--quiet")) {
+      if (r.unavailable) out(`memory sync: memory is not available (${r.unavailable})`)
+      else if (r.busy) out("memory sync: another sync is running")
+      else out(`memory sync: ${r.ingested} session${r.ingested === 1 ? "" : "s"} (${r.items} items) added, ${r.upToDate} already up to date${r.deferred ? `, ${r.deferred} left for the next run` : ""}${r.errors.length ? `; could not read ${r.errors.length}` : ""} (${(r.ms / 1000).toFixed(1)}s)`)
+    }
+    process.exit(0)
+  }
+  if (cmd === "memory") {
+    const { memoryCommand } = await import("./memory/cli.ts")
+    process.exit(await memoryCommand(rest, home, async (id) => readRef(await resolveRef(id)), out))
+  }
+  if (cmd === "tokens") {
+    const { tokensCommand } = await import("./memory/audit.ts")
+    process.exit(await tokensCommand(rest, home, { out }))
+  }
+  if (cmd === "org") {
+    const { orgCommand } = await import("./org/cli.ts")
+    process.exit(await orgCommand(rest, home, { out }))
+  }
+  if (cmd === "expand") {
+    const id = rest[0] ?? fail("expand needs a blob id (from a digest: \"id=...\")")
+    const { openBlobStore } = await import("./memory/blobs.ts")
+    const { expandStub } = await import("./memory/externalize.ts")
+    const text = openBlobStore(home).get(expandStub(id) ?? id)
+    if (text === undefined) fail(`no stored output "${id}" (it may have been pruned)`)
+    process.stdout.write(text!)
+    process.exit(0)
+  }
+  const sub = cmd === "session" ? rest.shift() : cmd
+  const args = cmd === "session" ? rest : rest
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      tool: { type: "string" }, here: { type: "boolean" }, limit: { type: "string" }, json: { type: "boolean" },
+      in: { type: "string" }, way: { type: "string" }, cwd: { type: "string" }, from: { type: "string" },
+      "dry-run": { type: "boolean" }, "no-open": { type: "boolean" }, lean: { type: "boolean" }, full: { type: "boolean" }, "no-memory": { type: "boolean" }, budget: { type: "string" }, "no-tidy": { type: "boolean" }, o: { type: "string" }, help: { type: "boolean", short: "h" },
+    },
+  })
+  if (!sub || values.help) return out(USAGE)
+
+  if (sub === "list") {
+    const { refs, errors } = await allRefs(values.tool)
+    const here = values.here ? process.cwd() : undefined
+    const shown = refs.filter((r) => !here || inProject(r.cwd, here)).slice(0, Number(values.limit ?? 30))
+    if (values.json) return out(JSON.stringify(shown, null, 1))
+    // The id column is never cut: it is what `show` and `continue` take, so it must be copyable whole.
+    const idw = Math.max(48, ...shown.map((r) => r.tool.length + 1 + r.sourceId.length))
+    for (const r of shown) out(`${`${r.tool}:${r.sourceId}`.padEnd(idw)}  ${ago(r.updatedAt).padStart(8)}  ${cut(short(r.cwd), 34).padEnd(34)}  ${cut((r.title ?? "").replace(/\s+/g, " "), 60)}`)
+    out(`${shown.length} of ${refs.length} sessions${errors.length ? `; could not list: ${errors.join("; ")}` : ""}`)
+    return
+  }
+  if (sub === "show" || sub === "export") {
+    const id = positionals[0] ?? fail(`${sub} needs a session id`)
+    const s = await readRef(await resolveRef(id))
+    if (sub === "export") {
+      if (values.o) {
+        writeFileSync(values.o, toJsonl(s))
+        return out(`wrote ${values.o}`)
+      }
+      return process.stdout.write(toJsonl(s))
+    }
+    return out(values.json ? JSON.stringify(s.header, null, 1) : describe(s))
+  }
+  if (sub === "continue") {
+    const id = positionals[0] ?? fail("continue needs a session id")
+    const target = values.in ?? fail("continue needs --in <tool>")
+    const s = await readRef(await resolveRef(id))
+    return continueIn(s, target, { ...(values.way ? { way: values.way as Way } : {}), ...(values.cwd ? { cwd: values.cwd } : {}), dryRun: !!values["dry-run"], open: !values["no-open"], ...leanOf(values), ...budgetOf(values), ...(values["no-tidy"] ? { tidy: false as const } : {}), ...(values["no-memory"] ? { noMemory: true } : {}) })
+  }
+  if (sub === "handoff") {
+    const target = values.in ?? fail("handoff needs --in <tool>")
+    const here = process.cwd()
+    const { refs } = await allRefs(values.from)
+    const ref = refs.find((r) => r.tool !== target && inProject(r.cwd, here))
+    if (!ref) fail(`no session from another tool in ${short(here)}`)
+    out(`Handing off ${ref!.tool}:${ref!.sourceId}${ref!.title ? ` ("${cut(ref!.title, 60)}")` : ""}, ${ago(ref!.updatedAt)}.`)
+    return continueIn(await readRef(ref!), target, { ...(values.way ? { way: values.way as Way } : {}), cwd: here, dryRun: !!values["dry-run"], open: !values["no-open"], ...leanOf(values), ...budgetOf(values), ...(values["no-tidy"] ? { tidy: false as const } : {}), ...(values["no-memory"] ? { noMemory: true } : {}) })
+  }
+  if (sub === "targets") {
+    const { READERS, WRITERS, writersFor } = await adapters()
+    const targets = [...new Set(WRITERS.map((w) => w.tool))]
+    for (const t of targets) {
+      const ways = await Promise.all(writersFor(t).map(async (w) => {
+        const r = await w.ready({ home, cwd: process.cwd(), dryRun: true })
+        return `${w.way}${r.ok ? "" : ` (not now: ${r.why})`}`
+      }))
+      out(`${t.padEnd(16)} ${ways.join(", ")}`)
+    }
+    out(`\nreaders: ${READERS.map((r) => r.tool).join(", ")}`)
+    return
+  }
+  if (sub === "hooks") {
+    const action = positionals[0] ?? "status"
+    const tools = values.tool ? [values.tool] : HOOK_TOOLS
+    const changes = action === "install" ? await installHooks(tools, home, { dryRun: !!values["dry-run"] })
+      : action === "uninstall" ? await uninstallHooks(tools, home, { dryRun: !!values["dry-run"] })
+      : action === "status" ? await installHooks(tools, home, { dryRun: true })
+      : fail(`hooks ${action}? use install, uninstall or status`)
+    for (const c of changes) out(`${c.tool.padEnd(14)} ${c.action}${c.why ? ` (${c.why})` : ""}  ${short(c.path)}`)
+    if (!changes.length) out("no tools with session-start hooks found")
+    if ((action === "install" || action === "uninstall") && !values["dry-run"]) await reportLater()
+    return
+  }
+  if (sub === "hook") {
+    const event = positionals[0] ?? fail("hook needs an event")
+    const tool = values.tool ?? fail("hook needs --tool")
+    const text = await runHook(event, tool, await Bun.stdin.text(), home)
+    if (text) process.stdout.write(text)
+    return
+  }
+  fail(`unknown command "${sub}"\n\n${USAGE}`)
+}
+
+await main()