perf: local-first writes + native-fs binary install — 60x faster brain ops

Two compounding fixes that drop fstack-brain ops from ~3s to ~50ms.

== Local-first writes ==

All write commands (intent write/infer/ship, decide write, handoff
write/auto, log-edit, heartbeat) used to perform 3-5 sequential Supabase
round-trips per invocation. Replaced with a write-locally-then-flush
pattern:

  - brain/cli/src/queue.ts (NEW)
    - enqueue() appends a JSONL line to ~/.fstack/queue/writes.jsonl
    - drainQueue() flushes to Supabase, called by all read commands
    - getCachedIntent/setCachedIntent — local cache for read-after-write
    - reserveDecisionNumber — local counter, bootstrap from Supabase once
    - Lock via atomic mkdir to prevent concurrent drains

  - brain/cli/src/context.ts
    - Split buildCtx into:
      * buildCtx (sync, lite) — git ops only, no Supabase. For writes.
      * buildCtxFull (async) — full ensureRepo+ensureBranch with local
        cache (~/.fstack/cache/repos.json, branches.json). For reads.
    - First buildCtxFull call resolves+caches IDs; subsequent calls hit
      cache and avoid Supabase.

  - All write commands switched to buildCtx (lite). Returns synchronously,
    queues the brain write, exits.

  - All read commands (sync, presence, standup, why, decide search,
    handoff list, conflict-precheck) use buildCtxFull and call drainQueue
    before querying Supabase. Just-written entries surface in the next read.

  - New 'flush' subcommand for explicit drain.
  - New 'queue' subcommand for queue depth.

Failure semantics: a failed flush row stays in the queue and retries on
next drain. Local cache is authoritative for the writer until flushed.
Local artifacts (ADR markdown files for /decide) are written immediately
regardless of brain reachability.

== Native-fs binary install ==

bin/fstack-brain-setup now COPIES the compiled binary to ~/.local/bin
instead of symlinking to the source dist/. The symlink path forced Bun to
load the 88MB compiled binary off /mnt/<windows>/ on WSL every invocation,
costing ~800ms per call across the WSL filesystem boundary. Native ext4
makes it ~40ms.

== Measured impact ==

  decide write  : 3.0s -> 55ms   (55x)
  intent get    : 2.8s -> 47ms   (60x)
  heartbeat     : 3.0s -> 50ms   (60x)
  bun cold      : 2.8s -> 43ms   (65x)

Brain writes from hooks (PostToolUse log-edit on every Edit/Write) now
finish in tens of ms, well within Claude Code's hook latency budget.
/decide and /intent finally feel weightless.

Resolves intent: 'Local-first writes — make every brain write feel
weightless' (ba76ee6f-b618-4b15-9fa2-6872c3b75a18).

Author: sanskarbasnet

bin/fstack-brain-setup

@@ -38,10 +38,14 @@ mkdir -p dist
 bun build ./src/index.ts --compile --outfile dist/fstack-brain --target=bun
 cd "$FSTACK_ROOT"
 
-# 3. Symlink binary
+# 3. Install binary on native filesystem (cp, not symlink)
+# A symlink to /mnt/<windows-drive>/ on WSL costs ~800ms per invocation
+# loading the 88MB binary across the WSL fs boundary. cp to ~/.local/bin
+# (native ext4) drops cold-start to ~40ms.
 mkdir -p "$(dirname "$BIN_TARGET")"
-ln -sf "$CLI_DIR/dist/fstack-brain" "$BIN_TARGET"
-log "linked $CLI_DIR/dist/fstack-brain → $BIN_TARGET"
+cp -f "$CLI_DIR/dist/fstack-brain" "$BIN_TARGET"
+chmod +x "$BIN_TARGET"
+log "installed $BIN_TARGET (copied from $CLI_DIR/dist/fstack-brain)"
 
 # Verify on PATH
 if ! command -v fstack-brain >/dev/null 2>&1; then

brain/cli/src/commands/conflict-precheck.ts

@@ -1,4 +1,4 @@
-import { buildCtx } from "../context.ts";
+import { buildCtxFull } from "../context.ts";
 import {
   activeIntentForBranch,
   listOtherActiveIntents,
@@ -17,7 +17,7 @@ import { emit } from "../output.ts";
 export async function conflictPrecheck() {
   let ctx;
   try {
-    ctx = await buildCtx();
+    ctx = await buildCtxFull();
   } catch {
     // Not in a repo / no config — silent pass-through.
     emit("(precheck skipped — no fstack context)", { ok: true, skipped: true });

brain/cli/src/commands/decide.ts

@@ -1,33 +1,42 @@
-import { buildCtx } from "../context.ts";
-import {
-  nextDecisionNumber,
-  writeDecision,
-  searchDecisions,
-} from "../client.ts";
+import { buildCtx, buildCtxFull } from "../context.ts";
+import { searchDecisions, ensureRepo, ensureBranch, ensureFile } from "../client.ts";
 import { emit, emitError } from "../output.ts";
 import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { defaultBranch } from "../git.ts";
+import { enqueue, reserveDecisionNumber, drainQueue, loadCounters } from "../queue.ts";
 
 /**
- * decide write — create a new ADR row + docs/decisions/NNNN-slug.md file.
+ * decide write — local-first.
+ *
+ * Returns in <100ms by:
+ *   1. Reserving the decision number locally (cached counter)
+ *   2. Writing the ADR markdown file immediately
+ *   3. Queueing the Supabase insert for next drain
+ *
+ * The ADR file is durable; the brain row is eventually consistent.
  */
 export async function decideWrite(args: { title?: string; body?: string }) {
   if (!args.title) emitError("decide write: --title required", 2);
   if (!args.body) emitError("decide write: --body required", 2);
 
-  const ctx = await buildCtx();
-  const number = await nextDecisionNumber(ctx.db, ctx.repoId);
-
-  const decision = await writeDecision(ctx.db, {
-    repoId: ctx.repoId,
-    number,
-    title: args.title,
-    body: args.body,
-    authoredBy: ctx.cfg.agent_id,
-  });
+  const ctx = buildCtx();
+  // reserveDecisionNumber needs a real repoId only on FIRST call per machine
+  // (to bootstrap the local counter from Supabase max). On subsequent calls,
+  // it hits the local counter cache and skips Supabase entirely.
+  const counters = loadCounters();
+  let repoIdForBootstrap = ctx.repoId;
+  if (counters[ctx.repoCanonical] === undefined) {
+    // Cache miss — need a real repoId to bootstrap. One-time hit.
+    repoIdForBootstrap = await ensureRepo(ctx.db, ctx.repoCanonical, defaultBranch());
+  }
+  const number = await reserveDecisionNumber(ctx.db, ctx.repoCanonical, repoIdForBootstrap);
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const timeline = [{ at: now, who: ctx.cfg.agent_id, event: "authored" }];
 
-  // Also write the markdown ADR file
-  const slug = args.title
+  // 1. Write the ADR file immediately — durable artifact
+  const slug = args.title!
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/(^-|-$)/g, "")
@@ -41,27 +50,57 @@ export async function decideWrite(args: { title?: string; body?: string }) {
     "",
     `**Status:** accepted`,
     `**Authored by:** ${ctx.cfg.agent_id}`,
-    `**Date:** ${new Date().toISOString().slice(0, 10)}`,
+    `**Date:** ${now.slice(0, 10)}`,
     "",
     args.body,
   ].join("\n");
   writeFileSync(adrPath, md, "utf8");
 
+  // 2. Queue the Supabase write
+  enqueue({
+    op: "decide_write",
+    payload: {
+      id,
+      repo_canonical: ctx.repoCanonical,
+      number,
+      title: args.title,
+      body: args.body,
+      authored_by: ctx.cfg.agent_id,
+      timeline,
+      created_at: now,
+    },
+  });
+
   emit(
-    `decision ${num} written — '${args.title}' (${adrPath})`,
-    { ok: true, decision, file: adrPath }
+    `decision ${num} written — '${args.title}' (${adrPath}) [queued for brain]`,
+    {
+      ok: true,
+      decision: { id, number, title: args.title, authored_by: ctx.cfg.agent_id },
+      file: adrPath,
+      queued: true,
+    }
   );
 }
 
 /**
- * decide search — keyword search across decisions in this repo.
+ * decide search — drain queue first so just-written decisions surface, then
+ * hit Supabase.
  */
 export async function decideSearch(args: { query?: string; limit?: number }) {
   if (!args.query) emitError("decide search: --query required", 2);
-  const ctx = await buildCtx();
+  const ctx = await buildCtxFull();
+
+  // Drain queued writes so search sees fresh data
+  await drainQueue(
+    ctx.db,
+    async (canonical) => ensureRepo(ctx.db, canonical, defaultBranch()),
+    async (repoId, branchName) => ensureBranch(ctx.db, repoId, branchName),
+    async (repoId, path) => ensureFile(ctx.db, repoId, path)
+  );
+
   const rows = await searchDecisions(ctx.db, {
     repoId: ctx.repoId,
-    query: args.query,
+    query: args.query!,
     limit: args.limit ?? 10,
   });
   if (rows.length === 0) {

brain/cli/src/commands/flush.ts

@@ -0,0 +1,39 @@
+import { buildCtxFull } from "../context.ts";
+import { ensureRepo, ensureBranch, ensureFile } from "../client.ts";
+import { defaultBranch } from "../git.ts";
+import { drainQueue, queueDepth } from "../queue.ts";
+import { emit } from "../output.ts";
+
+/**
+ * flush — manually drain the local write queue to Supabase.
+ * Read commands drain automatically; this is for explicit user invocation
+ * (e.g. before going offline) and for debugging.
+ */
+export async function flushCmd() {
+  const before = queueDepth();
+  if (before === 0) {
+    emit("(queue empty, nothing to flush)", { ok: true, flushed: 0 });
+    return;
+  }
+  const ctx = await buildCtxFull();
+  const result = await drainQueue(
+    ctx.db,
+    async (c) => ensureRepo(ctx.db, c, defaultBranch()),
+    async (r, b) => ensureBranch(ctx.db, r, b),
+    async (r, p) => ensureFile(ctx.db, r, p)
+  );
+  const lines = [`flushed ${result.flushed} of ${before} entries`];
+  if (result.remaining > 0) {
+    lines.push(`${result.remaining} entries remain (will retry on next read)`);
+  }
+  if (result.errors.length > 0) {
+    lines.push("errors:");
+    for (const e of result.errors.slice(0, 5)) lines.push(`  • ${e}`);
+  }
+  emit(lines.join("\n"), { ok: true, ...result, depth_before: before });
+}
+
+export async function queueStatusCmd() {
+  const depth = queueDepth();
+  emit(`queue depth: ${depth}`, { ok: true, depth });
+}

brain/cli/src/commands/handoff.ts

@@ -1,14 +1,16 @@
-import { buildCtx } from "../context.ts";
+import { buildCtx, buildCtxFull } from "../context.ts";
 import {
-  activeIntentForBranch,
-  writeHandoff,
   openHandoffs,
+  ensureRepo,
+  ensureBranch,
+  ensureFile,
 } from "../client.ts";
-import { uncommittedFiles } from "../git.ts";
+import { uncommittedFiles, defaultBranch } from "../git.ts";
 import { emit } from "../output.ts";
+import { enqueue, drainQueue, getCachedIntent } from "../queue.ts";
 
 /**
- * handoff write — explicit rich handoff (called by /handoff slash command).
+ * handoff write — local-first. Queues brain insert.
  */
 export async function handoffWrite(args: {
   note?: string;
@@ -20,38 +22,47 @@ export async function handoffWrite(args: {
     emit("handoff write: --note required", { ok: false });
     process.exit(2);
   }
-  const ctx = await buildCtx();
-  const intent = await activeIntentForBranch(ctx.db, ctx.cfg.agent_id, ctx.branchId);
+  const ctx = buildCtx();
+  const intent = getCachedIntent(ctx.repoCanonical, ctx.branchName, ctx.cfg.agent_id);
 
-  const handoff = await writeHandoff(ctx.db, {
-    repoId: ctx.repoId,
-    intentId: intent?.id,
-    fromAgent: ctx.cfg.agent_id,
-    toAgent: args.toAgent,
-    branchName: ctx.branchName,
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+  const handoff = {
+    id,
+    repo_canonical: ctx.repoCanonical,
+    intent_id: intent?.id,
+    from_agent: ctx.cfg.agent_id,
+    to_agent: args.toAgent,
+    branch_name: ctx.branchName,
     note: args.note,
     blocker: args.blocker,
-    nextStep: args.nextStep,
-    uncommittedFiles: uncommittedFiles(),
-    autoGenerated: false,
+    next_step: args.nextStep,
+    uncommitted_files: uncommittedFiles(),
+    auto_generated: false,
+    created_at: now,
+  };
+
+  enqueue({ op: "handoff_write", payload: handoff });
+  emit(`handoff ok — '${args.note.slice(0, 60)}...' [queued for brain]`, {
+    ok: true,
+    handoff,
+    queued: true,
   });
-  emit(`handoff ok — '${args.note.slice(0, 60)}...'`, { ok: true, handoff });
 }
 
 /**
- * handoff auto — called by SessionEnd hook. Quietly writes a stub handoff
- * if there's an active intent and uncommitted changes.
+ * handoff auto — SessionEnd hook. Quietly writes a stub if active intent
+ * + uncommitted files. Local-first.
  */
 export async function handoffAuto() {
   let ctx;
   try {
-    ctx = await buildCtx();
+    ctx = buildCtx();
   } catch {
-    // Not in a repo or no config — silent.
     emit("(auto-handoff skipped — no repo/config)", { ok: true, skipped: true });
     return;
   }
-  const intent = await activeIntentForBranch(ctx.db, ctx.cfg.agent_id, ctx.branchId);
+  const intent = getCachedIntent(ctx.repoCanonical, ctx.branchName, ctx.cfg.agent_id);
   if (!intent) {
     emit("auto-handoff: no active intent, skipping", { ok: false });
     return;
@@ -62,24 +73,53 @@ export async function handoffAuto() {
     return;
   }
 
-  await writeHandoff(ctx.db, {
-    repoId: ctx.repoId,
-    intentId: intent.id,
-    fromAgent: ctx.cfg.agent_id,
-    branchName: ctx.branchName,
-    note: `(auto) Session ended with ${uncommitted.length} uncommitted file(s) on '${intent.title}'`,
-    uncommittedFiles: uncommitted,
-    autoGenerated: true,
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+  enqueue({
+    op: "handoff_write",
+    payload: {
+      id,
+      repo_canonical: ctx.repoCanonical,
+      intent_id: intent.id,
+      from_agent: ctx.cfg.agent_id,
+      branch_name: ctx.branchName,
+      note: `(auto) Session ended with ${uncommitted.length} uncommitted file(s) on '${intent.title}'`,
+      uncommitted_files: uncommitted,
+      auto_generated: true,
+      created_at: now,
+    },
   });
-  emit(`auto-handoff ok — ${uncommitted.length} files in flight`, {
+
+  // Best-effort drain on session end so the handoff lands before the user closes
+  try {
+    await drainQueue(
+      ctx.db,
+      async (c) => ensureRepo(ctx.db, c, defaultBranch()),
+      async (r, b) => ensureBranch(ctx.db, r, b),
+      async (r, p) => ensureFile(ctx.db, r, p)
+    );
+  } catch {
+    // Best-effort; queue persists regardless
+  }
+
+  emit(`auto-handoff ok — ${uncommitted.length} files in flight [queued]`, {
     ok: true,
     intent_id: intent.id,
     uncommitted,
   });
 }
 
+/**
+ * handoff list — drain queue first so just-written handoffs surface.
+ */
 export async function handoffsList() {
-  const ctx = await buildCtx();
+  const ctx = await buildCtxFull();
+  await drainQueue(
+    ctx.db,
+    async (c) => ensureRepo(ctx.db, c, defaultBranch()),
+    async (r, b) => ensureBranch(ctx.db, r, b),
+    async (r, p) => ensureFile(ctx.db, r, p)
+  );
   const handoffs = await openHandoffs(ctx.db, {
     repoId: ctx.repoId,
     toAgent: ctx.cfg.agent_id,