@fuzeelogik/myflo 1.0.0-rc.4

package/README.md

@@ -0,0 +1,103 @@
+# flo — local-first developer workbench
+
+Standalone CLI + MCP server + Next.js dashboard. Zero build step on the CLI. Pure ESM, Node ≥ 20. No cloud dependencies.
+
+## Quick start
+
+```bash
+cd apps/cli && npm link              # makes `flo` available globally
+flo setup                            # creates ~/.flo/, registers MCP, runs doctor
+flo notes "First note with #flo"     # quick capture (BM25 search)
+cd ../../web && pnpm dev --port 3030 # localhost:3030 — unified dashboard
+```
+
+`flo setup` is idempotent — safe to re-run. It creates `~/.flo/{memory,messages,logs}/`, initializes the inbox + terminal registries, and registers `flo` as an MCP server in `~/.claude/mcp.json` so Claude Code agents can call its tools.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `flo guidance audit [--scope all\|user\|project] [--json] [--out file]` | Scan `~/.claude/{skills,commands,agents}/` and project `.claude/` for duplicate, undescribed, or orphan capabilities. Markdown report by default, JSON with `--json`. |
+| `flo migrate [--dry-run] [--mcp-path PATH]` | Register `flo` as an MCP server in `~/.claude/mcp.json`. Idempotent. Backs up the existing file before writing. |
+| `flo sessions list [--limit N] [--json]` | List Claude Code session checkpoints from `.claude/checkpoints/` in the current project. |
+| `flo inbox watch <dir> [--once]` | Foreground folder watcher. `.md` drops parse frontmatter (`to:`/`from:`/`subject:`). Audio (`.m4a` `.wav` `.mp3`) is transcribed locally via whisper/mlx-whisper and a sidecar `.txt` is written next to the audio file. Processed files move to `<dir>/.processed/`. Activity logged to `<dir>/inbox.log`. |
+| `flo inbox status [--dir <dir>]` | Show pending/processed/failed counts and the last few log entries. |
+| `flo inbox add <dir> [--slug <name>]` | Register an inbox in `~/.flo/inboxes.json`. Idempotent. |
+| `flo inbox list [--json]` | List registered inboxes with pending/processed/failed counts. |
+| `flo inbox remove <slug>` | Remove from registry (does not delete files). |
+| `flo inbox install <slug> [--interval N]` | **macOS**: generate `~/Library/LaunchAgents/io.myflo.inbox.<slug>.plist` that runs `flo inbox watch --once` every N seconds (default 30). Doesn't auto-load; prints `launchctl bootstrap` command. |
+| `flo inbox uninstall <slug>` | **macOS**: remove the launch agent plist. |
+| `flo transcribe <file> [--save] [--model base\|small\|medium\|large]` | Local audio transcription (whisper / mlx-whisper / whisper-cpp — detected at runtime, no cloud). `--save` writes sidecar `.txt`. `--detect` reports which tool would be used. |
+| `flo swarm status [--json]` | Read `.swarm/state.json` + `.swarm/q-learning-model.json` and render objective/agents/q-learning stats. |
+| `flo memory store --value <text> [--key <k>] [--namespace <ns>] [--tags a,b]` | Append an entry to `~/.flo/memory/<ns>.jsonl`. |
+| `flo memory search <query> [--namespace <ns>] [--tags a,b] [--limit N] [--json]` | Substring + tag search across namespaces. |
+| `flo memory list [--namespace <ns>] [--json]` / `get` / `delete` / `namespaces` | Inspect and tombstone memory entries. |
+| `flo messages list [<recipient>] [--json]` | List inbox-bridged messages by recipient. |
+| `flo messages read <recipient> <filename>` / `archive` | Read or remove a mailbox file. |
+| `flo transcripts list [--json] [--limit N]` | List sidecar `.txt` transcripts produced by audio inbox drops. |
+| `flo doctor [--json]` | Quick health check: Node version, git, `.claude/`, checkpoints, MCP config, flo binary. |
+| `flo mcp start` | Run as a stdio MCP server. Exposes 11 tools (see below). |
+| `flo help` / `flo version` | Self-explanatory. |
+
+## MCP usage
+
+After `flo migrate`, the server appears in `~/.claude/mcp.json` and you can call its tools from Claude Code. **11 tools** registered:
+
+- `flo_sessions_list({ limit? })` — Claude Code checkpoints
+- `flo_guidance_audit({ scope? })` — capability dedup report
+- `flo_memory_store({ value, key?, namespace?, tags?, metadata? })`
+- `flo_memory_search({ query?, namespace?, tags?, limit? })`
+- `flo_memory_list({ namespace?, limit? })`
+- `flo_memory_namespaces({})`
+- `flo_inbox_list({})` — registered inboxes with counts
+- `flo_messages_list({})` — bridged messages by recipient
+- `flo_swarm_status({})` — `.swarm/` state + q-learning summary
+- `flo_transcribe({ file, model? })` — local audio transcription
+- `flo_transcribe_detect({})` — which transcription tool is available
+
+The repo's own `.claude/settings.json` already registers `flo` alongside the existing `claude-flow` server — both coexist.
+
+## Web UI
+
+The local command center at `web/` (Next.js 16, Tailwind v4, shadcn) exposes six flo panels:
+
+- `/swarm` — `.swarm/state.json` + q-learning model summary
+- `/memory` — namespace browser + substring search across `~/.flo/memory/`
+- `/sessions` — table view of `.claude/checkpoints/`
+- `/capabilities` — capability audit summary with duplicate ranking
+- `/inbox` — registered inboxes with pending/processed/failed counts
+- `/transcripts` — sidecar transcripts from inbox audio drops
+
+```bash
+cd web && pnpm install && pnpm dev --port 3030
+```
+
+Then open <http://localhost:3030/sessions> or <http://localhost:3030/capabilities>.
+
+The web pages call `flo` as a subprocess via `web/src/lib/flo.ts` (uses `execFile` with an arg array; no shell interpolation).
+
+## Smoke test
+
+```bash
+bash apps/cli/tests/smoke.sh
+```
+
+Exercises every command end-to-end against an ephemeral temp directory.
+
+## Roadmap
+
+- Vector embeddings on top of the memory store (currently substring-only).
+- `flo session terminal-attach` for Ghostty/iTerm window restore (port of `a-team`).
+- Web `/memory`, `/inbox`, `/plugins`, `/hooks` panels.
+- Full v3/@claude-flow/* → packages/@myflo/* fork (currently `@myflo/{shared,memory,hooks}` are forked; the other ~22 packages still live under `v3/`).
+
+## Status
+
+- ✅ CLI: 9 commands working, 12/12 smoke tests passing.
+- ✅ MCP server: stdio JSON-RPC, 2 tools registered (`flo_sessions_list`, `flo_guidance_audit`).
+- ✅ Web: 5 flo panels (`/swarm`, `/memory`, `/sessions`, `/capabilities`, `/inbox`) alongside existing siege panels.
+- ✅ Audio: real local transcription (auto-detects whisper / mlx-whisper / whisper-cpp).
+- ✅ Inbox: registry in `~/.flo/inboxes.json` + macOS launchd installer.
+- ✅ Memory: file-backed JSON store in `~/.flo/memory/` (substring + tag search, no vectors yet).
+- ✅ Bridge: inbox `.md` drops with `to:` frontmatter write a mailbox file + memory entry — eagent-style cross-process comms.
+- 🟡 v3 fork: 3 of ~25 packages copied with renamed manifests; rest still under `v3/@claude-flow/`.

package/bin/flo.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from '../lib/main.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(`flo: ${err.message || err}`);
+  if (process.env.FLO_DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/lib/activity.js

@@ -0,0 +1,243 @@
+// `flo activity` — cross-subsystem event timeline.
+// Aggregates: task events, memory writes (all namespaces), inbox messages,
+// transcripts, terminal session adds, Claude Code checkpoints.
+// Returns chronologically-sorted events with type / source / snippet.
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { listInboxes } from './inbox-registry.js';
+import { listAllMailboxes } from './messages.js';
+import { collectTranscripts } from './transcripts.js';
+import { readCheckpoints } from './sessions.js';
+
+// terminal-attach is optional — only available once PR #31 lands.
+let loadTerminalRegistry;
+try {
+  ({ loadRegistry: loadTerminalRegistry } = await import('./terminal-attach.js'));
+} catch { /* not available; activity will skip terminal events */ }
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const MEMORY_DIR = join(FLO_HOME, 'memory');
+const TASKS_PATH = join(FLO_HOME, 'tasks.jsonl');
+
+const TYPES = ['task', 'note', 'memory', 'inbox', 'transcript', 'terminal', 'checkpoint'];
+
+export async function activityCommand(args) {
+  const [sub = 'list', ...rest] = args;
+  if (sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
+  if (sub === 'list') return listCmd(rest);
+  console.error(`flo activity: unknown subcommand '${sub}'`);
+  console.error(`Available: list, help`);
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`flo activity — cross-subsystem event timeline
+
+Usage:
+  flo activity list [--since <duration>] [--type <type>] [--limit N] [--json]
+
+  --since 7d / 24h / 30m   Only events newer than this
+  --type <t>               Filter by event type:
+                             ${TYPES.join(', ')}
+  --limit N                Cap results (default: 100)
+  --json                   JSON output
+
+Sources (each event has source + timestamp + snippet):
+  task        ~/.flo/tasks.jsonl (created/updated/completed/deleted events)
+  note        ~/.flo/memory/notes.jsonl (memory store with #note auto-tag)
+  memory      every other ~/.flo/memory/<ns>.jsonl
+  inbox       ~/.flo/messages/<recipient>/ mailbox files
+  transcript  sidecar .txt files in registered inboxes' .processed/
+  terminal    ~/.flo/terminals.json (creation timestamps)
+  checkpoint  .claude/checkpoints/ (Claude Code session checkpoints)
+`);
+}
+
+function parseFlags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--since') out.since = args[++i];
+    else if (a === '--type') out.type = args[++i];
+    else if (a === '--limit') out.limit = Number(args[++i]);
+    else if (a === '--json') out.json = true;
+  }
+  return out;
+}
+
+function parseSince(s) {
+  if (!s) return 0;
+  const m = String(s).match(/^(\d+)\s*(s|m|h|d|w)?$/i);
+  if (!m) return 0;
+  const n = Number(m[1]);
+  const unit = (m[2] || 'd').toLowerCase();
+  const mult = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 7 * 86_400_000 }[unit] || 86_400_000;
+  return Date.now() - n * mult;
+}
+
+export async function collectActivity({ sinceMs = 0, type } = {}) {
+  const events = [];
+  const wantAll = !type;
+
+  if (wantAll || type === 'task') {
+    if (existsSync(TASKS_PATH)) {
+      try {
+        const raw = await readFile(TASKS_PATH, 'utf8');
+        for (const line of raw.split(/\r?\n/)) {
+          if (!line.trim()) continue;
+          let row;
+          try { row = JSON.parse(line); } catch { continue; }
+          const ts = Date.parse(row.ts || row.createdAt || 0);
+          if (ts < sinceMs) continue;
+          let snippet = row.subject || '';
+          const op = row.op || (row.deleted ? 'delete' : 'create');
+          events.push({
+            type: 'task',
+            kind: op,
+            id: row.id,
+            ts,
+            timestamp: new Date(ts).toISOString(),
+            snippet: snippet || (op === 'update' ? `status → ${row.status || '?'}` : ''),
+            source: 'tasks.jsonl',
+          });
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  if ((wantAll || type === 'memory' || type === 'note') && existsSync(MEMORY_DIR)) {
+    try {
+      const files = await readdir(MEMORY_DIR);
+      for (const f of files) {
+        if (!f.endsWith('.jsonl')) continue;
+        const ns = f.replace(/\.jsonl$/, '');
+        const isNote = ns === 'notes';
+        if (type === 'note' && !isNote) continue;
+        if (type === 'memory' && isNote) continue;
+        let raw = '';
+        try { raw = await readFile(join(MEMORY_DIR, f), 'utf8'); } catch { continue; }
+        for (const line of raw.split(/\r?\n/)) {
+          if (!line.trim()) continue;
+          let row;
+          try { row = JSON.parse(line); } catch { continue; }
+          if (row.deleted) continue;
+          const ts = Date.parse(row.createdAt || 0);
+          if (!ts || ts < sinceMs) continue;
+          const snippet = (row.value || '').split('\n')[0].slice(0, 100);
+          events.push({
+            type: isNote ? 'note' : 'memory',
+            kind: 'store',
+            id: row.id,
+            ts,
+            timestamp: new Date(ts).toISOString(),
+            snippet,
+            source: `memory/${ns}`,
+            namespace: ns,
+            tags: row.tags || [],
+          });
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  if (wantAll || type === 'inbox') {
+    try {
+      const mailboxes = await listAllMailboxes();
+      for (const mb of mailboxes) {
+        for (const m of (mb.messages || [])) {
+          if (m.mtime < sinceMs) continue;
+          events.push({
+            type: 'inbox',
+            kind: 'message',
+            id: m.path,
+            ts: m.mtime,
+            timestamp: new Date(m.mtime).toISOString(),
+            snippet: `${mb.recipient} ← ${m.filename}`,
+            source: `messages/${mb.recipient}`,
+          });
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  if (wantAll || type === 'transcript') {
+    try {
+      const ts_list = await collectTranscripts(500);
+      for (const t of ts_list) {
+        if (t.mtime < sinceMs) continue;
+        events.push({
+          type: 'transcript',
+          kind: 'transcribe',
+          id: t.sidecarPath,
+          ts: t.mtime,
+          timestamp: new Date(t.mtime).toISOString(),
+          snippet: `${t.audioFilename} (${t.chars} chars): ${t.snippet.slice(0, 80)}`,
+          source: `inbox/${t.inboxSlug}`,
+        });
+      }
+    } catch { /* skip */ }
+  }
+
+  if (wantAll || type === 'terminal') {
+    try {
+      const reg = await loadTerminalRegistry();
+      for (const t of reg.terminals || []) {
+        const ts = Date.parse(t.createdAt || 0);
+        if (!ts || ts < sinceMs) continue;
+        events.push({
+          type: 'terminal',
+          kind: 'add',
+          id: t.slug,
+          ts,
+          timestamp: new Date(ts).toISOString(),
+          snippet: `${t.slug} (${t.app}) → ${t.cwd}`,
+          source: 'terminals.json',
+        });
+      }
+    } catch { /* skip */ }
+  }
+
+  if (wantAll || type === 'checkpoint') {
+    try {
+      const checkpoints = await readCheckpoints(undefined, 200);
+      for (const c of checkpoints) {
+        if (c.mtime < sinceMs) continue;
+        events.push({
+          type: 'checkpoint',
+          kind: c.type || 'edit',
+          id: c.id,
+          ts: c.mtime,
+          timestamp: c.timestamp || new Date(c.mtime).toISOString(),
+          snippet: c.file || c.tag || '',
+          source: '.claude/checkpoints',
+        });
+      }
+    } catch { /* skip */ }
+  }
+
+  events.sort((a, b) => b.ts - a.ts);
+  return events;
+}
+
+async function listCmd(args) {
+  const opts = parseFlags(args);
+  if (opts.type && !TYPES.includes(opts.type)) {
+    console.error(`flo activity: unknown --type '${opts.type}'. Valid: ${TYPES.join(', ')}`);
+    process.exit(2);
+  }
+  const sinceMs = parseSince(opts.since);
+  let events = await collectActivity({ sinceMs, type: opts.type });
+  events = events.slice(0, opts.limit || 100);
+  if (opts.json) { console.log(JSON.stringify(events, null, 2)); return; }
+  if (!events.length) { console.log(`flo activity: no events${opts.since ? ` since ${opts.since}` : ''}`); return; }
+  for (const e of events) {
+    const time = e.timestamp.replace('T', ' ').slice(0, 19);
+    const type = e.type.padEnd(10).slice(0, 10);
+    const kind = (e.kind || '').padEnd(9).slice(0, 9);
+    console.log(`${time}  ${type} ${kind}  ${e.snippet}`);
+  }
+  console.log(`\n${events.length} event(s).`);
+}

package/lib/agents-cmd.js

@@ -0,0 +1,173 @@
+import {
+  spawnAgent,
+  updateAgent,
+  stopAgent,
+  deleteAgent,
+  listAgents,
+  getAgent,
+  agentHealth,
+  heartbeat,
+  STATUSES,
+} from './agents-store.js';
+
+export async function agentsCommand(args) {
+  const [sub = 'help', ...rest] = args;
+  if (sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
+  if (sub === 'spawn') return spawnCmd(rest);
+  if (sub === 'list') return listCmd(rest);
+  if (sub === 'get' || sub === 'show') return getCmd(rest);
+  if (sub === 'update') return updateCmd(rest);
+  if (sub === 'heartbeat' || sub === 'hb') return hbCmd(rest);
+  if (sub === 'stop') return stopCmd(rest);
+  if (sub === 'delete' || sub === 'rm') return deleteCmd(rest);
+  if (sub === 'health') return healthCmd(rest);
+  console.error(`flo agents: unknown subcommand '${sub}'`);
+  console.error(`Available: spawn, list, get, update, heartbeat, stop, delete, health, help`);
+  process.exit(2);
+}
+
+function printHelp() {
+  console.log(`flo agents — coordination registry for named Claude Code agents
+
+Usage:
+  flo agents spawn <type> [--name <name>] [--role <s>] [--tags a,b] [--parent <id>]
+  flo agents list [--status idle|busy|completed|failed|stopped] [--type <t>] [--json]
+  flo agents get <id> [--json]
+  flo agents update <id> [--status <s>] [--name <n>] [--role <s>]
+  flo agents heartbeat <id>
+  flo agents stop <id>
+  flo agents delete <id>
+  flo agents health [--json]                 # heartbeat-age view of live agents
+
+Stores append-only events at ~/.flo/agents.jsonl. Does NOT spawn a process —
+Claude Code's Task tool does that. This is a coordination record so multiple
+agents can discover each other.
+`);
+}
+
+function parseFlags(args) {
+  const out = { positional: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--name') out.name = args[++i];
+    else if (a === '--role') out.role = args[++i];
+    else if (a === '--tags') out.tags = (args[++i] || '').split(',').map((t) => t.trim()).filter(Boolean);
+    else if (a === '--parent') out.parent = args[++i];
+    else if (a === '--status') out.status = args[++i];
+    else if (a === '--type') out.type = args[++i];
+    else if (!a.startsWith('--')) out.positional.push(a);
+  }
+  return out;
+}
+
+async function spawnCmd(args) {
+  const opts = parseFlags(args);
+  const type = opts.positional[0];
+  if (!type) { console.error(`flo agents spawn: missing <type>`); process.exit(2); }
+  const agent = await spawnAgent({
+    type,
+    name: opts.name,
+    role: opts.role,
+    tags: opts.tags,
+    parent: opts.parent,
+  });
+  if (opts.json) console.log(JSON.stringify(agent));
+  else console.log(`flo agents spawn: ${agent.id} (${agent.type})${agent.name !== agent.id ? ' name=' + agent.name : ''}`);
+}
+
+async function listCmd(args) {
+  const opts = parseFlags(args);
+  const agents = await listAgents({ status: opts.status, type: opts.type });
+  if (opts.json) { console.log(JSON.stringify(agents, null, 2)); return; }
+  if (!agents.length) { console.log(`flo agents: none registered`); return; }
+  console.log(`status      id                      type           name`);
+  console.log(`----------  ----------------------  -------------  ----`);
+  for (const a of agents) {
+    const sts = (a.status || '?').padEnd(10).slice(0, 10);
+    const id = a.id.padEnd(22).slice(0, 22);
+    const type = (a.type || '?').padEnd(13).slice(0, 13);
+    console.log(`${sts}  ${id}  ${type}  ${a.name || ''}`);
+  }
+}
+
+async function getCmd(args) {
+  const opts = parseFlags(args);
+  const id = opts.positional[0];
+  if (!id) { console.error(`flo agents get: missing <id>`); process.exit(2); }
+  const agent = await getAgent(id);
+  if (!agent) { console.error(`flo agents get: no agent ${id}`); process.exit(1); }
+  if (opts.json) console.log(JSON.stringify(agent, null, 2));
+  else {
+    console.log(`${agent.id}`);
+    console.log(`type:           ${agent.type}`);
+    console.log(`name:           ${agent.name}`);
+    console.log(`status:         ${agent.status}`);
+    if (agent.role) console.log(`role:           ${agent.role}`);
+    if (agent.tags?.length) console.log(`tags:           ${agent.tags.join(', ')}`);
+    if (agent.parent) console.log(`parent:         ${agent.parent}`);
+    console.log(`spawnedAt:      ${agent.spawnedAt}`);
+    console.log(`lastHeartbeat:  ${agent.lastHeartbeat}`);
+  }
+}
+
+async function updateCmd(args) {
+  const opts = parseFlags(args);
+  const id = opts.positional[0];
+  if (!id) { console.error(`flo agents update: missing <id>`); process.exit(2); }
+  const patch = {};
+  if (opts.status !== undefined) {
+    if (!STATUSES.includes(opts.status)) {
+      console.error(`flo agents update: invalid status '${opts.status}'. Valid: ${STATUSES.join(', ')}`);
+      process.exit(2);
+    }
+    patch.status = opts.status;
+  }
+  if (opts.name !== undefined) patch.name = opts.name;
+  if (opts.role !== undefined) patch.role = opts.role;
+  if (Object.keys(patch).length === 0) {
+    console.error(`flo agents update: nothing to change`);
+    process.exit(2);
+  }
+  const agent = await updateAgent({ id, ...patch });
+  if (!agent) { console.error(`flo agents update: no agent ${id}`); process.exit(1); }
+  console.log(`flo agents update: ${agent.id} status=${agent.status}`);
+}
+
+async function hbCmd(args) {
+  const id = args[0];
+  if (!id) { console.error(`flo agents heartbeat: missing <id>`); process.exit(2); }
+  const agent = await heartbeat(id);
+  if (!agent) { console.error(`flo agents heartbeat: no agent ${id}`); process.exit(1); }
+  console.log(`flo agents heartbeat: ${agent.id} at ${agent.lastHeartbeat}`);
+}
+
+async function stopCmd(args) {
+  const id = args[0];
+  if (!id) { console.error(`flo agents stop: missing <id>`); process.exit(2); }
+  const agent = await stopAgent(id);
+  if (!agent) { console.error(`flo agents stop: no agent ${id}`); process.exit(1); }
+  console.log(`flo agents stop: ${agent.id} stopped`);
+}
+
+async function deleteCmd(args) {
+  const id = args[0];
+  if (!id) { console.error(`flo agents delete: missing <id>`); process.exit(2); }
+  await deleteAgent(id);
+  console.log(`flo agents delete: tombstoned ${id}`);
+}
+
+async function healthCmd(args) {
+  const opts = parseFlags(args);
+  const health = await agentHealth();
+  if (opts.json) { console.log(JSON.stringify(health, null, 2)); return; }
+  if (!health.length) { console.log(`flo agents health: no live agents`); return; }
+  console.log(`health   id                      heartbeat age   name`);
+  console.log(`-------  ----------------------  --------------  ----`);
+  for (const h of health) {
+    const tag = (h.health || '?').padEnd(7).slice(0, 7);
+    const id = h.id.padEnd(22).slice(0, 22);
+    const ageS = Math.round(h.heartbeatAgeMs / 1000);
+    console.log(`${tag}  ${id}  ${String(ageS).padStart(8)}s    ${h.name || ''}`);
+  }
+}

package/lib/agents-store.js

@@ -0,0 +1,153 @@
+// flo agents store — append-only registry of named agents at ~/.flo/agents.jsonl.
+// Does NOT spawn processes — Claude Code's Task tool does the actual execution.
+// This is a coordination record: agents declare themselves, others discover them,
+// heartbeats track liveness.
+
+import { mkdir, readFile, appendFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+const FLO_HOME = process.env.FLO_HOME || join(homedir(), '.flo');
+const AGENTS_PATH = join(FLO_HOME, 'agents.jsonl');
+
+const HEALTH_STALE_MS = 5 * 60_000; // an agent without a heartbeat for 5min counts as 'stale'
+
+export const STATUSES = ['idle', 'busy', 'completed', 'failed', 'stopped'];
+
+async function ensureHome() {
+  if (!existsSync(FLO_HOME)) await mkdir(FLO_HOME, { recursive: true });
+}
+
+function newId() {
+  return `a-${Date.now()}-${randomBytes(2).toString('hex')}`;
+}
+
+async function appendEvent(event) {
+  await ensureHome();
+  await appendFile(AGENTS_PATH, JSON.stringify(event) + '\n', 'utf8');
+}
+
+async function readEvents() {
+  if (!existsSync(AGENTS_PATH)) return [];
+  let raw = '';
+  try { raw = await readFile(AGENTS_PATH, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+export async function spawnAgent({ type, name, role, tags, parent, metadata }) {
+  if (!type) throw new Error('spawnAgent: type is required');
+  const id = newId();
+  const now = new Date().toISOString();
+  const event = {
+    id,
+    op: 'spawn',
+    ts: now,
+    type: String(type),
+    name: name || id,
+    role: role || null,
+    tags: Array.isArray(tags) ? tags.map(String) : [],
+    parent: parent || null,
+    metadata: metadata && typeof metadata === 'object' ? metadata : {},
+    status: 'idle',
+    spawnedAt: now,
+    lastHeartbeat: now,
+  };
+  await appendEvent(event);
+  return materializeOne([event]);
+}
+
+export async function updateAgent({ id, ...patch }) {
+  if (!id) throw new Error('updateAgent: id is required');
+  const ts = new Date().toISOString();
+  const event = { id, op: 'update', ts, ...patch, lastHeartbeat: patch.lastHeartbeat || ts };
+  await appendEvent(event);
+  const all = await listAgents();
+  return all.find((a) => a.id === id) || null;
+}
+
+export async function heartbeat(id) {
+  return updateAgent({ id, lastHeartbeat: new Date().toISOString() });
+}
+
+export async function stopAgent(id) {
+  return updateAgent({ id, status: 'stopped', stoppedAt: new Date().toISOString() });
+}
+
+export async function deleteAgent(id) {
+  if (!id) throw new Error('deleteAgent: id is required');
+  await appendEvent({ id, op: 'delete', ts: new Date().toISOString() });
+}
+
+function materializeOne(events) {
+  const map = new Map();
+  for (const e of events) {
+    if (e.op === 'delete') {
+      map.delete(e.id);
+      continue;
+    }
+    if (e.op === 'spawn') {
+      const { op, ts, ...record } = e;
+      map.set(e.id, record);
+    } else if (e.op === 'update') {
+      const existing = map.get(e.id);
+      if (!existing) continue;
+      const { op, ts, ...patch } = e;
+      map.set(e.id, { ...existing, ...patch });
+    }
+  }
+  return [...map.values()][0] || null;
+}
+
+export async function listAgents({ status, type, includeStopped = true } = {}) {
+  const events = await readEvents();
+  const map = new Map();
+  for (const e of events) {
+    if (e.op === 'delete') { map.delete(e.id); continue; }
+    if (e.op === 'spawn') {
+      const { op, ts, ...record } = e;
+      map.set(e.id, record);
+    } else if (e.op === 'update') {
+      const existing = map.get(e.id);
+      if (!existing) continue;
+      const { op, ts, ...patch } = e;
+      map.set(e.id, { ...existing, ...patch });
+    }
+  }
+  let agents = [...map.values()];
+  if (!includeStopped) agents = agents.filter((a) => a.status !== 'stopped');
+  if (status) agents = agents.filter((a) => a.status === status);
+  if (type) agents = agents.filter((a) => a.type === type);
+  return agents.sort((a, b) => (a.spawnedAt < b.spawnedAt ? 1 : -1));
+}
+
+export async function getAgent(id) {
+  const all = await listAgents();
+  return all.find((a) => a.id === id) || null;
+}
+
+export async function agentHealth() {
+  const agents = await listAgents({ includeStopped: false });
+  const now = Date.now();
+  return agents.map((a) => {
+    const lastHb = a.lastHeartbeat ? Date.parse(a.lastHeartbeat) : 0;
+    const ageMs = now - lastHb;
+    return {
+      id: a.id,
+      name: a.name,
+      type: a.type,
+      status: a.status,
+      lastHeartbeat: a.lastHeartbeat,
+      heartbeatAgeMs: ageMs,
+      health: ageMs < HEALTH_STALE_MS ? 'healthy' : 'stale',
+    };
+  });
+}
+
+export const _internal = { AGENTS_PATH, HEALTH_STALE_MS };