moflo 4.10.28 → 4.10.29-rc.2

package/.claude/guidance/shipped/moflo-cli-reference.md

@@ -189,3 +189,4 @@ findings; if AI-driven security scanning returns it should be an opt-in
 - `.claude/guidance/moflo-subagents.md` — Subagent memory-first protocol and store-back rules
 - `.claude/guidance/moflo-memory-strategy.md` — Memory namespaces, RAG linking, and search query patterns
 - `.claude/guidance/moflo-memorydb-maintenance.md` — How the namespaces above are populated and refreshed
+- `.claude/guidance/moflo-cross-install-memory-sharing.md` — `flo memory sync` / `team-export` / `team-import` and `flo doctor -c shared-db` for sharing durable learnings across worktrees, machines, and teams

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -222,6 +222,7 @@ See `.claude/guidance/moflo-memory-strategy.md` for memory-specific troubleshoot
 - `.claude/guidance/moflo-claude-swarm-cohesion.md` — Task & swarm coordination with TaskCreate/TaskUpdate
 - `.claude/guidance/moflo-memory-strategy.md` — Database schema, namespaces, search commands, RAG linking
 - `.claude/guidance/moflo-memorydb-maintenance.md` — Reindexing, namespace purging, recovery
+- `.claude/guidance/moflo-cross-install-memory-sharing.md` — Sharing durable `learnings` across worktrees / machines / teams (`memory.durable_path`, `flo memory sync`, the team artifact) and the `flo doctor -c shared-db` check
 - `.claude/guidance/moflo-settings-injection.md` — What moflo writes into `.claude/` and how surgical self-heal works
 - `.claude/guidance/moflo-cross-platform.md` — Windows/macOS/Linux portability rules for any code change
 - `.claude/guidance/moflo-verbose-command-filtering.md` — Filter long verbose commands at the source; never tee-then-grep

package/.claude/guidance/shipped/moflo-cross-install-memory-sharing.md

@@ -0,0 +1,126 @@
+# Cross-Installation Memory Sharing
+
+**Purpose:** Decide how to share moflo's durable learnings across git worktrees, machines, or a team — and how to do it WITHOUT corrupting search. Read this before configuring `memory.durable_path`, running `flo memory sync`, or pointing two checkouts at one database.
+
+---
+
+## Share the Durable Slice, Never the Whole DB
+
+moflo's `.moflo/moflo.db` holds three classes of data. Only one is worth sharing.
+
+| Class | Namespaces | Shareable? | Why |
+|-------|-----------|------------|-----|
+| **Durable** | `learnings`, `knowledge` | **Yes** | User-authored, slow to recreate, identical across checkouts |
+| **Structural** | `code-map`, guidance chunks | No | Branch-specific; rebuilds cheaply from the indexers |
+| **Ephemeral** | `tasklist`, `hive-mind`, epic state | No | Per-run scratch; meaningless in another install |
+
+**Never *live-share* the entire `moflo.db` between two running daemons.** node:sqlite + WAL stops concurrent writers from losing rows, but each daemon builds its own in-memory HNSW index — a write in install A never updates install B's index, so search silently returns stale results, and structural namespaces churn across branches. For ongoing sync, share ONLY the durable slice.
+
+> **Not the same thing:** restoring a one-time whole-DB *snapshot* to seed a fresh/empty workspace is safe and fast — each workspace then owns its own copy (no second concurrent daemon, so no index divergence), and the incremental reindex reconciles branch drift. That avoids the cold-start full parse + re-embed and is the right tool when speed-to-ready matters. Use `flo memory backup`/`restore` for it — see "Hydrate a Fresh Workspace from a Snapshot" below. The rule above is specifically about *live concurrent* sharing.
+
+---
+
+## Pick the Mechanism by Topology
+
+Choose by who needs the learnings, not by what is easiest to wire.
+
+| Topology | Mechanism | How |
+|----------|-----------|-----|
+| Same machine, many worktrees / Conductor workspaces | `memory.durable_path` | Point every checkout at one durable-only store; session-start seeds + writes through automatically |
+| One person, many machines | `flo memory sync` | `--to <file>` then `--from <file>` via a synced folder (Dropbox/iCloud) or a hand-copied file |
+| A team sharing one repo | Git-tracked team artifact | `flo memory team-export` writes `.moflo/shared/learnings.jsonl`; teammates' session-start import-merges it after `git pull` |
+| A fresh/empty workspace that must be ready FAST | Whole-DB snapshot (`memory.hydrate_from`) | `flo memory backup --to <snap>` once; a new workspace restores the entire DB so search works on session one — no cold reindex |
+
+The first three move the SAME durable slice and dedupe on `UNIQUE(namespace, key)`, so combining them is conflict-free. The snapshot is a different tool — a one-time whole-DB seed that composes with the durable-slice modes (see the next section but one).
+
+---
+
+## Configure a Same-Machine Shared Store
+
+Set `memory.durable_path` in `moflo.yaml` to a dedicated file — NOT a full `moflo.db`.
+
+```yaml
+memory:
+  durable_path: ~/.moflo-shared/team-learnings.db   # a durable-only store, created on first flush
+```
+
+The path must resolve to a file that is NOT any project's `.moflo/moflo.db`. Pointing it at a real `moflo.db` re-introduces the whole-DB-sharing hazard. `MOFLO_DURABLE_PATH` overrides the config per process; relative paths resolve against the project root.
+
+---
+
+## Carry Learnings Between Your Own Machines
+
+Use `flo memory sync` with a portable artifact you keep in a synced folder.
+
+```bash
+flo memory sync --to   ~/Dropbox/moflo/durable.db   # on machine A
+flo memory sync --from ~/Dropbox/moflo/durable.db   # on machine B
+```
+
+`--from` is idempotent (re-running copies nothing new). After an import, restart the Claude Code session (or run `flo memory rebuild-index`) so the merged rows are embedded and searchable.
+
+---
+
+## Share Learnings Across a Team
+
+Commit a git-tracked JSONL artifact so the whole team accumulates each other's learnings about the repo.
+
+```bash
+flo memory team-export                       # writes .moflo/shared/learnings.jsonl + makes it git-trackable
+git add .moflo/shared/learnings.jsonl && git commit -m "share learnings"
+```
+
+Teammates' session-start import-merges the file after `git pull` (first-write-wins on conflicts; author/host provenance is retained). JSONL keeps git diffs reviewable; embeddings are regenerated on import. Enable it with `memory.team_artifact: .moflo/shared/learnings.jsonl`.
+
+---
+
+## Hydrate a Fresh Workspace from a Snapshot
+
+Use a whole-DB snapshot when a new workspace must be searchable on its FIRST session. An empty `.moflo/moflo.db` forces a full cold reindex — parse every file for `code-map`/`patterns`/`tests`, chunk all `guidance`, AND run ONNX embedding generation over all of it (minutes on a large repo). A snapshot restore skips both the parse and the embed.
+
+```bash
+flo memory backup  --to   ~/moflo-snapshots/myproject.db   # snapshot a warm workspace (VACUUM INTO — consistent even under an active WAL)
+flo memory restore --from ~/moflo-snapshots/myproject.db   # seed a fresh workspace (no-op if the local DB already has content; --force to override)
+```
+
+Auto-hydrate on session-start by setting `memory.hydrate_from` (env `MOFLO_HYDRATE_FROM` overrides):
+
+```yaml
+memory:
+  hydrate_from: /abs/path/to/moflo-snapshot.db   # restored only when the local DB is empty, before the daemon starts
+```
+
+| Behavior | Rule |
+|----------|------|
+| When it restores | Only when the local DB is absent/empty (never clobbers an active workspace unless `--force`) |
+| Ephemeral leak | Source `tasklist`/`hive-mind`/epic-state are purged from the restored copy |
+| Branch drift | Self-heals on the next incremental reindex |
+| Order vs. durable-slice | Hydrate runs BEFORE the durable-slice sync at session-start — snapshot is the fast one-time seed, durable-slice keeps `learnings` converged afterward |
+
+This is NOT whole-DB *live* sharing: each restored workspace owns its own copy, so there is no second concurrent daemon and no HNSW index divergence.
+
+---
+
+## Verify the Setup with `flo doctor`
+
+Run the shared-DB check to confirm you are sharing safely.
+
+```bash
+flo doctor -c shared-db
+```
+
+| Result | Meaning |
+|--------|---------|
+| **pass** — "durable-only shared store configured" | `durable_path` points at a dedicated file — safe |
+| **warn** — "points at a full moflo.db" | `durable_path` aliases or is named like a full DB — repoint it at a dedicated store |
+| **warn** — "is a symlink" | The local `moflo.db` is symlinked into a shared location — replace it with a local DB and use `durable_path` |
+
+A foreign-writer warning from the Writers Audit check (`flo doctor -c writers`) means another process is writing the DB outside the daemon's single-writer routing; under node:sqlite + WAL it won't lose rows, but it leaves the daemon's HNSW index stale until it reindexes.
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-memory-strategy.md` — Namespaces, RAG indexing, and the durable-vs-derived split this doc builds on
+- `.claude/guidance/moflo-memory-protocol.md` — Search-and-traverse protocol for the shared `learnings` once it is populated
+- `.claude/guidance/moflo-core-guidance.md` — CLI, daemon, and `moflo.yaml` reference (the `memory` config block)

package/.claude/guidance/shipped/moflo-memory-strategy.md

@@ -152,6 +152,7 @@ The retrieval-specific rules below only apply to docs you want surfaced via `mem
 ## See Also
 
 - `.claude/guidance/moflo-memorydb-maintenance.md` — Database location, schema, purge/reindex procedures
+- `.claude/guidance/moflo-cross-install-memory-sharing.md` — Sharing the durable `learnings` slice across worktrees, machines, and teams (and why never to share the whole DB)
 - `.claude/guidance/moflo-guidance-rules.md` — Universal authoring rules every guidance doc must follow
 - `.claude/guidance/moflo-subagents.md` — Memory-first subagent protocol that uses these search paths
 - `.claude/guidance/moflo-claude-swarm-cohesion.md` — Task & swarm coordination layered on top of memory

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -60,6 +60,9 @@ memory:
   backend: node-sqlite            # node-sqlite (default) | rvf (pure-TS fallback) | json (last resort). Passed to createDatabase() as the preferred provider (#1144).
   embedding_model: Xenova/all-MiniLM-L6-v2   # 384-dim neural embeddings
   namespace: default              # Default namespace for memory operations
+  # durable_path: ~/.moflo-shared/team-learnings.db   # opt-in (#1232): share durable namespaces (learnings, knowledge) across worktrees / Conductor workspaces. Point at a DEDICATED store, never a full moflo.db. Env override: MOFLO_DURABLE_PATH.
+  # team_artifact: .moflo/shared/learnings.jsonl       # opt-in (#1234): git-tracked JSONL the team commits; session-start import-merges it. Env override: MOFLO_TEAM_ARTIFACT. See moflo-cross-install-memory-sharing.md.
+  # hydrate_from: /abs/path/to/moflo-snapshot.db       # opt-in (#1244): whole-DB snapshot to seed a fresh/empty workspace on session-start (skips the cold reindex). No-op once the local DB has content. Take one with "flo memory backup --to <path>". Env override: MOFLO_HYDRATE_FROM.
 
 # Hook toggles (all on by default — disable to slim down)
 hooks:

package/README.md

@@ -67,6 +67,7 @@ MoFlo makes deliberate choices so you don't have to:
 |---------|-------------|
 | **Semantic Memory** | 384-dim domain-aware embeddings. Store knowledge, search it instantly. |
 | **Reflection** | Distills durable lessons from your sessions into searchable memory — automatically (auto-meditate), or on demand with `/meditate`. |
+| **Cross-Install Sharing** | Share durable `learnings` across git worktrees, your own machines, or a whole team — via `memory.durable_path`, `flo memory sync`, or a git-tracked artifact. Structural namespaces stay local. [Full documentation →](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md) |
 | **Code Navigation** | Indexes your codebase structure so Claude can answer "where does X live?" without Glob/Grep. |
 | **Guidance Indexing** | Chunks your project docs (`.claude/guidance/`, `docs/`) and makes them searchable. |
 | **Gates** | Enforces memory-first and task-creation patterns via Claude Code hooks. Prevents Claude from skipping steps. |
@@ -262,6 +263,21 @@ auto_meditate:
 
 The two are complementary: auto-meditate is the always-on safety net, `/meditate` is the deliberate, curated pass. Both write to the same `learnings` namespace and both deduplicate, so neither pollutes the other — and anything they store is available to semantic search from then on.
 
+### Sharing learnings across installations
+
+The `learnings` (and `knowledge`) namespaces are the **durable** slice of memory — user-authored and worth carrying across checkouts. The rest of the DB (code-map, guidance chunks, run state) is structural or ephemeral and rebuilds cheaply, so it stays local. For ongoing sync MoFlo shares only the durable slice — **never *live-shares* the whole `moflo.db`** between two daemons, which would make each daemon's in-memory search index diverge.
+
+Pick the mechanism by topology:
+
+| You want to share across… | Use | How |
+|---------------------------|-----|-----|
+| Git worktrees / Conductor workspaces (same machine) | `memory.durable_path` in `moflo.yaml` | Point every checkout at one durable-only store; session-start seeds + writes through automatically |
+| Your own laptop + desktop + CI | `flo memory sync --to/--from <file>` | Export to a synced folder (Dropbox/iCloud) or a copied file, import on the other machine |
+| A whole team on one repo | `flo memory team-export` → commit `.moflo/shared/learnings.jsonl` | Teammates' session-start import-merges it after `git pull` (first-write-wins; author provenance retained) |
+| A fresh workspace that must be ready fast | `flo memory backup/restore` or `memory.hydrate_from` | Seed a new workspace from a **whole-DB snapshot** so it's searchable on session one — no cold reindex. Safe because each workspace owns its own copy (a one-time restore, not live sharing) |
+
+Verify your setup with `flo doctor -c shared-db` (it warns if you've accidentally pointed at a full `moflo.db` for *live* sharing). Full guide: [`moflo-cross-install-memory-sharing.md`](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md).
+
 ## The Gate System
 
 MoFlo installs Claude Code hooks that run on every tool call. Together, these gates create a **feedback loop** that prevents Claude from wasting tokens on blind exploration and ensures it builds on prior knowledge.

package/bin/session-start-launcher.mjs

@@ -247,7 +247,17 @@ function readInstallManifest(manifestPath) {
   return { entries, isLegacy };
 }
 
-const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const plural = (n, word) => {
+  if (n === 1) return `${n} ${word}`;
+  // Pluralize the final word: consonant+y → -ies (entry → entries), sibilant
+  // endings → -es (box → boxes), otherwise → -s. Naive +s mangled every
+  // 'entry'-style word into 'entrys'.
+  let suffixed;
+  if (/[^aeiou]y$/i.test(word)) suffixed = `${word.slice(0, -1)}ies`;
+  else if (/(?:s|x|z|ch|sh)$/i.test(word)) suffixed = `${word}es`;
+  else suffixed = `${word}s`;
+  return `${n} ${suffixed}`;
+};
 
 // Captured inside the upgrade/drift branch so the post-spawn notice writer
 // can persist `.moflo/upgrade-notice.json` for the statusline (#636).
@@ -2037,6 +2047,52 @@ try {
   } catch { /* writing the failure itself must not throw */ }
 }
 
+// ── 3e-1244. Hydrate a fresh workspace from a whole-DB snapshot BEFORE daemon ─
+// When `memory.hydrate_from` (or MOFLO_HYDRATE_FROM) points at a snapshot AND
+// the local .moflo/moflo.db is absent/empty, restore the whole DB (structural +
+// durable + embeddings) so the first session is searchable without a cold full
+// reindex (#1244, epic #1231). Runs BEFORE the daemon spawns so the restored
+// rows are present when the daemon builds its HNSW index, and BEFORE the purge/
+// sync blocks below so they operate on the hydrated DB. No-clobber: a no-op once
+// the local DB has content. Best-effort: a failure must never block session start.
+try {
+  // Cheap pre-gate so the overwhelming majority (no hydrate configured) pay
+  // nothing — no module load, no moflo.yaml parse. Live only when the env
+  // override is set or moflo.yaml has an UNcommented `hydrate_from:` line (the
+  // generated config ships a commented example, which this regex ignores).
+  const hydrateYamlPath = resolve(projectRoot, 'moflo.yaml');
+  let hydrateEnabled = Boolean(process.env.MOFLO_HYDRATE_FROM);
+  if (!hydrateEnabled && existsSync(hydrateYamlPath)) {
+    try {
+      hydrateEnabled = /^[ \t]*hydrate_from[ \t]*:/m.test(readFileSync(hydrateYamlPath, 'utf-8'));
+    } catch { /* unreadable yaml — treat as not-configured */ }
+  }
+  const hydratePaths = hydrateEnabled
+    ? [
+        resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/snapshot-restore.js'),
+        resolve(projectRoot, 'dist/src/cli/services/snapshot-restore.js'),
+      ]
+    : [];
+  const hydratePath = hydratePaths.find((p) => existsSync(p));
+  if (hydratePath) {
+    const { hydrateAtSessionStart } = await import(pathToFileURL(hydratePath).href);
+    const result = await hydrateAtSessionStart({ projectRoot });
+    if (result?.restored) {
+      const mb = ((result.bytes ?? 0) / (1024 * 1024)).toFixed(1);
+      emitMutation(
+        'hydrated workspace from snapshot',
+        `restored ${mb} MB whole-DB snapshot — search ready without a cold reindex`,
+      );
+    }
+  }
+} catch (err) {
+  // Non-fatal — without a snapshot the workspace just cold-indexes as before.
+  try {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write(`snapshot hydration skipped: ${msg}\n`);
+  } catch { /* writing the failure itself must not throw */ }
+}
+
 // ── 3e-728. Hard-delete leftover soft-delete tombstones (#728) ─────────────
 // Soft-delete was retired in story #728 — `status='deleted'` rows are now
 // unrecoverable bloat from prior moflo versions. Purge any stragglers and
@@ -2106,6 +2162,56 @@ try {
   } catch { /* writing the failure itself must not throw */ }
 }
 
+// ── 3e-1232. Sync durable namespaces with the shared store BEFORE daemon ────
+// When `memory.durable_path` (or MOFLO_DURABLE_PATH) is set, flush this
+// worktree's learnings to the shared store and seed any sibling-workspace
+// learnings back into the local DB. Runs BEFORE the daemon spawns so the
+// freshly-seeded rows are present when the daemon builds its in-memory HNSW
+// index — that's what makes the cross-worktree repro (#1231) pass. No-op when
+// the feature is off. Best-effort: a sync failure must never block session start.
+try {
+  // Cheap pre-gate so solo users (the overwhelming majority) pay nothing here —
+  // no module load, no moflo.yaml parse. The feature is only live when the env
+  // override is set or moflo.yaml has an UNcommented `durable_path:` line (the
+  // generated config ships a commented example, which this regex ignores).
+  const durableYamlPath = resolve(projectRoot, 'moflo.yaml');
+  let durableEnabled = Boolean(process.env.MOFLO_DURABLE_PATH);
+  if (!durableEnabled && existsSync(durableYamlPath)) {
+    try {
+      durableEnabled = /^[ \t]*durable_path[ \t]*:/m.test(readFileSync(durableYamlPath, 'utf-8'));
+    } catch { /* unreadable yaml — treat as not-configured */ }
+  }
+  const durablePaths = durableEnabled
+    ? [
+        resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/durable-sync.js'),
+        resolve(projectRoot, 'dist/src/cli/services/durable-sync.js'),
+      ]
+    : [];
+  const durablePath = durablePaths.find((p) => existsSync(p));
+  if (durablePath) {
+    const { syncDurableAtSessionStart } = await import(pathToFileURL(durablePath).href);
+    const result = await syncDurableAtSessionStart({ projectRoot });
+    if (result?.seededToLocal > 0) {
+      emitMutation(
+        'seeded shared learnings',
+        `${plural(result.seededToLocal, 'durable entry')} pulled from the shared store`,
+      );
+    }
+    if (result?.flushedToShared > 0) {
+      emitMutation(
+        'shared local learnings',
+        `${plural(result.flushedToShared, 'durable entry')} pushed to the shared store`,
+      );
+    }
+  }
+} catch (err) {
+  // Non-fatal — durable sync reconciles on the next session start.
+  try {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write(`durable-memory sync skipped: ${msg}\n`);
+  } catch { /* writing the failure itself must not throw */ }
+}
+
 // ── 3e-1057. Run unmet schema migrations BEFORE daemon spawn ────────────────
 // run-migrations.mjs walks `bin/migrations/*.mjs` and invokes each that has
 // not been recorded in `.moflo/migrations.json`. Each migration opens sql.js
@@ -2175,6 +2281,58 @@ function runMigrationsAndAnnounce(runnerPath) {
   }
 }
 
+// ── 3e-1234. Import the git-tracked team learnings artifact BEFORE daemon spawn ─
+// Opt-in (#1234, epic #1231): when memory.team_artifact (or MOFLO_TEAM_ARTIFACT)
+// points at a committed JSONL file, merge it into the local durable namespaces
+// so teammates' learnings (pulled via git) are present when the daemon builds
+// its HNSW index in section 4. INSERT OR IGNORE → idempotent + first-write-wins.
+// Fully guarded: a disabled/absent artifact is a silent no-op, and any failure
+// is non-fatal (the next session-start retries). Runs every session (teammates
+// pull frequently without a moflo version bump), unlike the upgrade-gated
+// cherry-pick in section 3.
+try {
+  // Cheap pre-gate so solo users (the overwhelming majority) pay nothing here —
+  // no module load, no moflo.yaml parse. The feature is only live when an env
+  // override is set, the default artifact already exists, or moflo.yaml has an
+  // UNcommented `team_artifact:` line (the generated config ships a commented
+  // example, which this regex deliberately ignores). Only then import the service.
+  const defaultArtifact = resolve(projectRoot, '.moflo', 'shared', 'learnings.jsonl');
+  const yamlPath = resolve(projectRoot, 'moflo.yaml');
+  let teamEnabled = Boolean(process.env.MOFLO_TEAM_ARTIFACT) || existsSync(defaultArtifact);
+  if (!teamEnabled && existsSync(yamlPath)) {
+    try {
+      teamEnabled = /^[ \t]*team_artifact[ \t]*:/m.test(readFileSync(yamlPath, 'utf-8'));
+    } catch { /* unreadable yaml — treat as not-configured */ }
+  }
+  const teamSyncPaths = teamEnabled
+    ? [
+        resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/team-artifact-sync.js'),
+        resolve(projectRoot, 'dist/src/cli/services/team-artifact-sync.js'),
+      ]
+    : [];
+  const teamSyncPath = teamSyncPaths.find((p) => existsSync(p));
+  if (teamSyncPath) {
+    const mod = await import(pathToFileURL(teamSyncPath).href);
+    if (typeof mod.resolveTeamArtifactPath === 'function' && typeof mod.importTeamArtifact === 'function') {
+      const artifactPath = mod.resolveTeamArtifactPath(projectRoot);
+      if (artifactPath && existsSync(artifactPath)) {
+        const report = mod.importTeamArtifact({ projectRoot, artifactPath });
+        if (report?.imported > 0) {
+          emitMutation(
+            'merged team learnings',
+            `${plural(report.imported, 'shared learning')} imported from the git-tracked team artifact`,
+          );
+        }
+      }
+    }
+  }
+} catch (err) {
+  try {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write(`team-artifact import skipped: ${msg}\n`);
+  } catch { /* stderr write must not throw */ }
+}
+
 // ── 3f. Flip the upgrade notice to "completed" (#636, #738) ─────────────────
 // See the TTL rationale at the constants above for why we switch to a
 // short-TTL completed badge instead of clearing the file.

package/dist/src/cli/commands/doctor-checks-shared-db.js

@@ -0,0 +1,116 @@
+/**
+ * Doctor check: shared full-`moflo.db` detection (#1235, epic #1231).
+ *
+ * Cross-installation learning-sharing is SAFE when only the durable slice
+ * (`learnings`, `knowledge`) travels — via `memory.durable_path` (#1232),
+ * `flo memory sync` (#1233), or the git-tracked team artifact (#1234). It is
+ * UNSAFE to share the *whole* `moflo.db` between two installs (two git
+ * worktrees, two Conductor workspaces, a symlinked `.moflo/`): node:sqlite+WAL
+ * keeps concurrent writers from losing rows, but each daemon builds its own
+ * in-memory HNSW index, so a write from install A never updates install B's
+ * index — searches silently return stale results, and the structural namespaces
+ * (`code-map`, guidance chunks) churn across branches.
+ *
+ * This check warns when the project is *configured toward* a shared full DB and
+ * blesses the durable-only setup (no warning). It is pure `fs` (realpath +
+ * lstat) — no shelling to `grep`/`ps` (Rule #1).
+ *
+ * @module cli/commands/doctor-checks-shared-db
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { memoryDbPath } from '../services/moflo-paths.js';
+import { findProjectRoot } from '../services/project-root.js';
+import { loadMofloConfig } from '../config/moflo-config.js';
+import { errorDetail } from '../shared/utils/error-detail.js';
+const NAME = 'Shared Full DB';
+/**
+ * Resolve a path through symlinks for identity comparison. Realpaths BOTH sides
+ * of any later `===` (macOS `/var`→`/private/var`, Windows case-fold) per Rule #1;
+ * falls back to the absolute literal when the target doesn't exist yet.
+ */
+function realOrAbs(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * True when `p` resolves to a full `moflo.db`. Compared case-insensitively —
+ * Windows + macOS filesystems are case-insensitive, so a `durable_path` of
+ * `MOFLO.DB` is still a full DB (Rule #1). Any path ending in `.../moflo.db`
+ * has basename `moflo.db`, so basename alone covers the nested case too.
+ */
+function looksLikeFullDb(absPath) {
+    return path.basename(absPath).toLowerCase() === 'moflo.db';
+}
+export async function checkSharedFullDb(deps) {
+    try {
+        const root = deps?.root ?? findProjectRoot();
+        const localDb = memoryDbPath(root);
+        const config = deps?.config ?? loadMofloConfig(root);
+        // `durable_path` ships in #1232 and may not exist in the config type on a
+        // branch without it — read defensively so this check stands alone.
+        const mem = config.memory;
+        const durableRaw = typeof mem.durable_path === 'string' ? mem.durable_path.trim() : '';
+        // 1. A symlinked local moflo.db is the classic "two installs, one full DB"
+        //    setup (a symlinked `.moflo/` across Conductor workspaces / worktrees).
+        if (fs.existsSync(localDb)) {
+            let isLink = false;
+            try {
+                isLink = fs.lstatSync(localDb).isSymbolicLink();
+            }
+            catch {
+                /* lstat race / perms — treat as not-a-link */
+            }
+            if (isLink) {
+                return {
+                    name: NAME,
+                    status: 'warn',
+                    message: `${localDb} is a symlink — sharing one full moflo.db across installs makes each daemon's ` +
+                        `in-memory HNSW index diverge, so search returns stale results (node:sqlite+WAL prevents row ` +
+                        `loss, not index drift). Keep a local DB and share only the durable slice via memory.durable_path.`,
+                    fix: 'Replace the symlinked moflo.db with a real local DB, then set memory.durable_path to a dedicated durable-only store.',
+                };
+            }
+        }
+        // 2. `durable_path` pointed at a FULL moflo.db (aliases the local DB, or is
+        //    itself a canonical .moflo/moflo.db) — that shares the whole DB, the very
+        //    thing durable-only sharing exists to avoid.
+        if (durableRaw) {
+            const absDurable = path.isAbsolute(durableRaw) ? path.resolve(durableRaw) : path.resolve(root, durableRaw);
+            const aliasesLocal = fs.existsSync(absDurable) && fs.existsSync(localDb) && realOrAbs(absDurable) === realOrAbs(localDb);
+            if (aliasesLocal || looksLikeFullDb(absDurable)) {
+                return {
+                    name: NAME,
+                    status: 'warn',
+                    message: `memory.durable_path (${durableRaw}) points at a full moflo.db — that shares the whole database, ` +
+                        `causing HNSW index divergence / stale search across installs. Point it at a dedicated durable-only ` +
+                        `store (a file NOT named moflo.db) so only learnings/knowledge travel.`,
+                    fix: 'Set memory.durable_path to a dedicated file such as <shared>/moflo-learnings.db (not a full moflo.db).',
+                };
+            }
+            // Blessed: a dedicated durable-only store. Structural namespaces stay local.
+            return {
+                name: NAME,
+                status: 'pass',
+                message: `Durable-only shared store configured (${durableRaw}) — safe; structural namespaces stay local.`,
+            };
+        }
+        return {
+            name: NAME,
+            status: 'pass',
+            message: 'No shared full moflo.db detected (local DB is not symlinked; no durable_path override).',
+        };
+    }
+    catch (e) {
+        return {
+            name: NAME,
+            status: 'warn',
+            message: `Unable to check shared-DB config: ${errorDetail(e, { firstLineOnly: true })}`,
+        };
+    }
+}
+//# sourceMappingURL=doctor-checks-shared-db.js.map

package/dist/src/cli/commands/doctor-checks-writers-audit.js

@@ -153,7 +153,9 @@ export async function checkWritersAudit(cwd = process.cwd()) {
             name,
             status: 'fail',
             message: `${foreign.length} non-daemon writer(s) running concurrently with daemon (PID ${daemonPid}): ${detail}. ` +
-                `Each will clobber the daemon's sql.js snapshot on flush — #1054 bug class.`,
+                `Each bypasses the daemon's single-writer routing (#981): under node:sqlite+WAL they no longer clobber ` +
+                `the DB file (the sql.js whole-snapshot flush #1054 guarded against is gone), but concurrent writes leave ` +
+                `the daemon's in-memory HNSW index stale, so search returns outdated results until it reindexes.`,
             fix: process.platform === 'win32'
                 ? `taskkill /F /PID ${foreign.map((p) => p.pid).join(' /PID ')}`
                 : `kill ${foreign.map((p) => p.pid).join(' ')}`,

package/dist/src/cli/commands/doctor-registry.js

@@ -9,6 +9,7 @@ import { checkEmbeddingHygiene } from './doctor-embedding-hygiene.js';
 import { checkDaemonVersionSkew } from './doctor-checks-version-skew.js';
 import { checkEmbeddingCoverageTruth } from './doctor-checks-coverage-truth.js';
 import { checkWritersAudit } from './doctor-checks-writers-audit.js';
+import { checkSharedFullDb } from './doctor-checks-shared-db.js';
 import { checkSwarmFunctional, checkHiveMindFunctional, } from './doctor-checks-swarm.js';
 import { checkMemoryAccessFunctional } from './doctor-checks-memory-access.js';
 import { checkBuildTools, checkClaudeCode, checkDiskSpace, checkGit, checkGitRepo, checkNodeVersion, checkNpmVersion, } from './doctor-checks-runtime.js';
@@ -43,6 +44,9 @@ export const allChecks = [
     checkDaemonOrphan,
     checkDaemonWriteRouting,
     checkWritersAudit,
+    // #1235 — warn when configured toward a shared *full* moflo.db (symlinked DB
+    // or durable_path aliasing a full DB); blesses a durable-only shared store.
+    checkSharedFullDb,
     checkMemoryDatabase,
     // Surfaces nested `.moflo/moflo.db` directories — every nested instance is
     // a daemon island in a monorepo (#1174). Runs cheap (depth-bounded BFS,
@@ -118,6 +122,9 @@ export const componentMap = {
     'orphans': checkDaemonOrphan,
     'writers-audit': checkWritersAudit,
     'writers': checkWritersAudit,
+    'shared-db': checkSharedFullDb,
+    'shared-full-db': checkSharedFullDb,
+    'sharing': checkSharedFullDb,
     'memory': checkMemoryDatabase,
     'nested-moflo': checkNestedMofloIslands,
     'nested': checkNestedMofloIslands,