lazyclaw 3.99.28 → 4.2.0

package/daemon.mjs

@@ -1605,6 +1605,177 @@ export function makeHandler(ctx) {
             }, m.headers || {});
           }
         }
+        // ──── Multi-agent dashboard surface (Phase 15) ────────────────
+        // Routes share the same JSON-only shape the rest of the daemon
+        // uses. The on-disk state is owned by agents.mjs / teams.mjs /
+        // tasks.mjs; we don't touch the files directly here so the CLI
+        // and the dashboard stay coherent.
+        case route === 'GET /agents': {
+          const mod = await import('./agents.mjs');
+          return writeJson(res, 200, mod.listAgents());
+        }
+        case route === 'POST /agents': {
+          const mod = await import('./agents.mjs');
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: e?.message || String(e) }); }
+          try { return writeJson(res, 200, mod.registerAgent(body)); }
+          catch (err) {
+            const code = err?.code === 'AGENT_EXISTS' ? 409 : 400;
+            return writeJson(res, code, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'GET' && /^\/agents\/([^/]+)$/.test(url.pathname): {
+          const name = url.pathname.split('/').pop();
+          const mod = await import('./agents.mjs');
+          const a = mod.getAgent(name);
+          if (!a) return writeJson(res, 404, { error: `no agent "${name}"` });
+          return writeJson(res, 200, a);
+        }
+        case req.method === 'PATCH' && /^\/agents\/([^/]+)$/.test(url.pathname): {
+          const name = url.pathname.split('/').pop();
+          const mod = await import('./agents.mjs');
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: e?.message || String(e) }); }
+          try { return writeJson(res, 200, mod.patchAgent(name, body)); }
+          catch (err) {
+            const code = err?.code === 'AGENT_NO_AGENT' ? 404 : 400;
+            return writeJson(res, code, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'DELETE' && /^\/agents\/([^/]+)$/.test(url.pathname): {
+          const name = url.pathname.split('/').pop();
+          const mod = await import('./agents.mjs');
+          try { return writeJson(res, 200, mod.removeAgent(name)); }
+          catch (err) {
+            return writeJson(res, 404, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'GET' && /^\/agents\/([^/]+)\/memory$/.test(url.pathname): {
+          const name = url.pathname.match(/^\/agents\/([^/]+)\/memory$/)[1];
+          const memMod = await import('./mas/agent_memory.mjs');
+          const text = memMod.readMemory(name);
+          res.writeHead(200, { 'content-type': 'text/markdown; charset=utf-8', 'cache-control': 'no-cache' });
+          return res.end(text);
+        }
+        case req.method === 'PUT' && /^\/agents\/([^/]+)\/memory$/.test(url.pathname): {
+          const name = url.pathname.match(/^\/agents\/([^/]+)\/memory$/)[1];
+          const memMod = await import('./mas/agent_memory.mjs');
+          // Read raw text body — content-type defaults to text/markdown
+          // but JSON {"text": "..."} is also accepted for tooling that
+          // prefers structured bodies.
+          let body = '';
+          await new Promise((resolve) => {
+            req.on('data', (c) => { body += c.toString(); });
+            req.on('end', resolve);
+          });
+          let text = body;
+          if (req.headers['content-type']?.includes('application/json')) {
+            try { text = (JSON.parse(body || '{}').text) || ''; } catch { /* leave raw */ }
+          }
+          try {
+            const p = memMod.writeRaw(name, text);
+            return writeJson(res, 200, { path: p, bytes: Buffer.byteLength(text, 'utf8') });
+          } catch (err) {
+            return writeJson(res, 400, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'DELETE' && /^\/agents\/([^/]+)\/memory$/.test(url.pathname): {
+          const name = url.pathname.match(/^\/agents\/([^/]+)\/memory$/)[1];
+          const memMod = await import('./mas/agent_memory.mjs');
+          const removed = memMod.clear(name);
+          return writeJson(res, 200, { name, cleared: removed });
+        }
+
+        case route === 'GET /teams': {
+          const mod = await import('./teams.mjs');
+          return writeJson(res, 200, mod.listTeams());
+        }
+        case route === 'POST /teams': {
+          const mod = await import('./teams.mjs');
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: e?.message || String(e) }); }
+          try { return writeJson(res, 200, mod.registerTeam(body)); }
+          catch (err) {
+            const code = err?.code === 'TEAM_EXISTS' ? 409 : 400;
+            return writeJson(res, code, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'GET' && /^\/teams\/([^/]+)$/.test(url.pathname): {
+          const name = url.pathname.split('/').pop();
+          const mod = await import('./teams.mjs');
+          const t = mod.getTeam(name);
+          if (!t) return writeJson(res, 404, { error: `no team "${name}"` });
+          return writeJson(res, 200, t);
+        }
+        case req.method === 'PATCH' && /^\/teams\/([^/]+)$/.test(url.pathname): {
+          const name = url.pathname.split('/').pop();
+          const mod = await import('./teams.mjs');
+          let body;
+          try { body = await readJson(req); }
+          catch (e) { return writeJson(res, 400, { error: e?.message || String(e) }); }
+          try { return writeJson(res, 200, mod.patchTeam(name, body)); }
+          catch (err) {
+            const code = err?.code === 'TEAM_NO_TEAM' ? 404 : 400;
+            return writeJson(res, code, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'DELETE' && /^\/teams\/([^/]+)$/.test(url.pathname): {
+          const name = url.pathname.split('/').pop();
+          const mod = await import('./teams.mjs');
+          try { return writeJson(res, 200, mod.removeTeam(name)); }
+          catch (err) {
+            return writeJson(res, 404, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+
+        case route === 'GET /tasks': {
+          const mod = await import('./tasks.mjs');
+          return writeJson(res, 200, mod.listTasks());
+        }
+        case req.method === 'GET' && /^\/tasks\/([^/]+)\/transcript$/.test(url.pathname): {
+          const m = url.pathname.match(/^\/tasks\/([^/]+)\/transcript$/);
+          const id = m[1];
+          const mod = await import('./tasks.mjs');
+          const t = mod.getTask(id);
+          if (!t) return writeJson(res, 404, { error: `no task "${id}"` });
+          const fmt = String(url.searchParams.get('format') || 'text');
+          if (fmt === 'json') return writeJson(res, 200, t);
+          const body = mod.formatTranscript(t, fmt);
+          const mime = fmt === 'md' ? 'text/markdown; charset=utf-8' : 'text/plain; charset=utf-8';
+          res.writeHead(200, { 'content-type': mime, 'cache-control': 'no-cache' });
+          return res.end(body);
+        }
+        case req.method === 'GET' && /^\/tasks\/([^/]+)$/.test(url.pathname): {
+          const id = url.pathname.split('/').pop();
+          const mod = await import('./tasks.mjs');
+          const t = mod.getTask(id);
+          if (!t) return writeJson(res, 404, { error: `no task "${id}"` });
+          return writeJson(res, 200, t);
+        }
+        case req.method === 'DELETE' && /^\/tasks\/([^/]+)$/.test(url.pathname): {
+          const id = url.pathname.split('/').pop();
+          const mod = await import('./tasks.mjs');
+          try { return writeJson(res, 200, mod.removeTask(id)); }
+          catch (err) {
+            return writeJson(res, 404, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+        case req.method === 'POST' && /^\/tasks\/([^/]+)\/(done|abandon)$/.test(url.pathname): {
+          const m = url.pathname.match(/^\/tasks\/([^/]+)\/(done|abandon)$/);
+          const id = m[1];
+          const action = m[2];
+          const mod = await import('./tasks.mjs');
+          try {
+            const next = mod.patchTask(id, { status: action === 'done' ? 'done' : 'abandoned' });
+            return writeJson(res, 200, next);
+          } catch (err) {
+            return writeJson(res, 404, { error: err?.message || String(err), code: err?.code });
+          }
+        }
+
         default:
           return writeJson(res, 404, { error: 'not found', route });
       } /* eslint-disable-line no-fallthrough */

package/docs/multi-agent.md

@@ -0,0 +1,256 @@
+# Multi-Agent Slack System — spec v0.1
+
+> Status: **confirmed 2026-05-18** — §10 decisions locked, Phase 9 may begin.
+
+---
+
+## 1. Goals (in user's words)
+
+1. User opens the **dashboard**, registers agents, defines roles, optionally groups them into teams.
+2. User assigns a task to **one lead agent** (e.g. `@planner`) via the dashboard.
+3. The lead agent picks up the task in **one Slack thread**, decides which teammates to involve, and **@-mentions** them in the same thread.
+4. Mentioned agents (e.g. `@backend`, `@frontend`) do their part — they may call tools (read files, run commands, edit code) — and post their results in the same thread.
+5. Results bubble back to the lead. Lead synthesises and reports the final outcome to the user (dashboard + thread summary).
+6. All conversation history per task lives in one Slack thread + one lazyclaw session, so anyone (incl. the user) can audit.
+
+Concretely: **one Slack channel, many virtual agents, mention-driven routing, with tool-use enabled per agent.**
+
+---
+
+## 2. Vocabulary
+
+| Term | Definition |
+|---|---|
+| **Agent** | A named identity with a role (system prompt), a provider/model, a tool whitelist, and a persona/avatar. Not a Slack user — a virtual identity surfaced through the one real bot. |
+| **Team** | A named set of agents + a default Slack channel + a default lead. Teams scope routing: `@backend` in team `shop` is a different agent than `@backend` in team `growth`. |
+| **Task** | A unit of work with a title, description, owning team, lead agent, status, and a Slack thread ts. Each task = exactly one thread. |
+| **Turn** | One agent saying one thing in a thread. Stored as `{ agent, text, tool_calls?, tool_results?, ts }`. |
+| **Handoff** | An agent's turn that contains `@OtherAgent` mention(s). The router schedules `OtherAgent` to take the next turn(s) with full thread history. |
+
+---
+
+## 3. Data model
+
+Files live under `~/.lazyclaw/`, gitignored, schema versioned via `version` field.
+
+### 3.1 Agent — `~/.lazyclaw/agents/<name>.json`
+
+```jsonc
+{
+  "version": 1,
+  "name": "planner",                     // unique identifier, used in @mentions
+  "displayName": "Planner",              // shown in dashboard + Slack header
+  "role": "You are the project planner. Break work down…",  // system prompt
+  "provider": "claude-cli",              // any lazyclaw provider name
+  "model": "claude-opus-4-7",
+  "tools": ["bash", "read", "write", "grep", "web_search"],  // whitelist
+  "tags": ["lead"],                      // free-form labels (used by router for fallback)
+  "createdAt": "2026-05-18T…",
+  "updatedAt": "2026-05-18T…"
+}
+```
+
+### 3.2 Team — `~/.lazyclaw/teams/<name>.json`
+
+```jsonc
+{
+  "version": 1,
+  "name": "shop",
+  "displayName": "Shop squad",
+  "agents": ["planner", "backend", "frontend"],
+  "lead": "planner",                     // default task lead, overridable per task
+  "slackChannel": "C0B5AGCP8PJ",         // channel id (preferred) or "#shop"
+  "createdAt": "2026-05-18T…"
+}
+```
+
+### 3.3 Task — `~/.lazyclaw/tasks/<id>.json`
+
+```jsonc
+{
+  "version": 1,
+  "id": "t_2026-05-18_001",
+  "title": "ship checkout flow",
+  "description": "…",
+  "team": "shop",
+  "lead": "planner",
+  "status": "running",                   // pending | running | done | failed | abandoned
+  "slackChannel": "C0B5AGCP8PJ",
+  "slackThreadTs": "1700000000.000100",  // root message ts
+  "createdAt": "…",
+  "updatedAt": "…",
+  "turns": [
+    { "agent": "user",     "text": "ship checkout flow", "ts": "1700000000.000100" },
+    { "agent": "planner",  "text": "Step 1 … @backend implement …", "ts": "…" },
+    { "agent": "backend",  "text": "Done — diff at …", "tool_calls": […], "ts": "…" }
+  ]
+}
+```
+
+---
+
+## 4. Slack routing model
+
+### 4.1 One bot, many virtual agents
+
+There is **one** real Slack app/bot (the existing lazyclaw bot). Each agent appears in Slack as a message prefixed with the agent name and (optionally) a custom username/icon via `chat.postMessage`'s `username` + `icon_emoji` params (requires `chat:write.customize` scope).
+
+Why not multiple bots:
+- Slack workspace pollution (1 app per agent ≠ scalable)
+- Re-installation + token management per agent is a ceremony
+- Permission model is per-bot, not per-message — easier with one trusted bot
+
+### 4.2 Inbound trigger
+
+A thread becomes "live" when either:
+- The user starts a task from the dashboard → lazyclaw posts a root message in the team's channel
+- A human posts in any channel where the bot is a member and **@-mentions a specific agent**, e.g. `@planner build me X`. The bot maps `@planner` (by display name → agent name → team) and treats the message as the kickoff turn.
+
+### 4.3 Mention parsing
+
+Agents address each other with **plain text `@AgentName`** (no Slack user_id), because virtual agents have no Slack identity. Router scans every agent-authored message for `@(\w+)` and:
+
+1. Resolves each match to an agent in the **same team** as the speaker (scoped lookup; ambiguous matches across teams are an error reported in-thread).
+2. Schedules each mentioned agent for a turn. Turns are taken **sequentially** (not parallel) to keep the conversation linear and avoid token explosions; future enhancement can fan out.
+3. After the last mentioned agent finishes, **control returns to the lead** if the lead wasn't part of the mentions — the lead gets a synthesised view and decides whether to keep iterating or mark the task done.
+
+### 4.4 Termination
+
+A task is `done` when:
+- The lead emits a turn containing the literal marker `[[TASK_DONE]]` (chosen over `DONE` to avoid false positives when agents discuss the word "done" naturally), **or**
+- A per-task `maxTurns` budget is exhausted (default 30, configurable), **or**
+- The user marks it done from the dashboard or via slash command.
+
+### 4.5 Bot's own messages
+
+Slack delivers `message` events for the bot's own posts. The router **must** filter `subtype === 'bot_message'` and `bot_id === <our bot>` so the bot never reacts to its own agent posts. This is already done in `channels/slack.mjs`.
+
+---
+
+## 5. Tool-use per agent
+
+This is the largest delta vs current code. Today, the Slack handler calls `prov.sendMessage(messages, …)` once and returns text. Multi-agent needs a **tool-use loop**: the model returns either a final text or a tool call; lazyclaw executes the tool and feeds results back; repeat until final text.
+
+### 5.1 Tool whitelist (per agent)
+
+```
+bash         — run a shell command, get stdout/stderr/exit
+read         — read a file (path-scoped)
+write        — write/edit a file
+grep         — search the workspace
+web_search   — call Tavily / Serper / duckduckgo
+web_fetch    — fetch a URL
+slack_post   — post a message into the task's thread (rarely needed — output text auto-posts)
+```
+
+Each agent declares the subset it can use. Tools the agent didn't request are not advertised to the model. **Default whitelist for a dashboard-created agent: `[bash, read, write, grep]`** (per §10 #3 — user opted for the full set; restrict per-agent if needed).
+
+### 5.2 Permission and audit
+
+- Every tool call is logged to `~/.lazyclaw/tasks/<id>.audit.jsonl` with `{ agent, tool, args, result_hash, ts }`.
+- Bash commands are *not* sandboxed by default (per user decision §0). Workspace is constrained to the cwd of the lazyclaw process.
+- **Bash destructive-pattern confirmation is OFF by default** (per §10 #6). The dashboard exposes a per-team toggle so individual teams can opt into the "ask before `rm -rf` / `git push --force` / `DROP TABLE` …" gate; the patterns themselves live in a config file the user can edit.
+- Audit log captures destructive commands either way so post-hoc forensics is possible.
+
+### 5.3 Provider compatibility
+
+Tool-use is supported on **anthropic, openai, and gemini** from Phase 12 (per §10 #5 — user opted for parallel implementation). Each provider has its own tool-call schema; the implementation routes through a small adapter layer (`providers/tool_use.mjs`) that normalises:
+
+- Anthropic: `tools` array + `tool_use` / `tool_result` content blocks
+- OpenAI: `tools` (functions) + `tool_calls` / `tool` role messages
+- Gemini: `function_declarations` + `function_call` / `function_response` parts
+
+claude-cli (subprocess) does NOT support tool-use — those agents are flagged "tool-use disabled" in the dashboard and can only chat.
+
+---
+
+## 6. Dashboard UX
+
+The existing `lazyclaw dashboard` (browser-rendered HTML, served by the daemon) gets four new screens:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Lazyclaw dashboard                          [search …]  │
+├─[ Agents ][ Teams ][ Tasks ][ Live threads ][ …existing ]┤
+│                                                         │
+│  Agents                                  [ + New agent ]│
+│  ┌──────────────────────────────────────────────────┐  │
+│  │ planner     Planner       claude-opus-4-7   ✎ ✕  │  │
+│  │ backend     Backend dev   claude-sonnet-4-6 ✎ ✕  │  │
+│  │ frontend    Frontend dev  claude-haiku-4-5  ✎ ✕  │  │
+│  └──────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+- **Agents tab** — list / create / edit / delete agents. Edit form has role textarea, provider+model dropdown, tool checkboxes.
+- **Teams tab** — list / create / edit teams. Team form picks agents from registered list + Slack channel selector (calls `conversations.list`).
+- **Tasks tab** — list of recent tasks with status, links to live Slack thread, and a "View transcript" detail view that renders the `turns` array as a chat-like timeline.
+- **Live threads** — currently-running tasks with a kill button (sets `status: abandoned`, posts a closing message in thread).
+
+CLI parity (so anyone can manage without a browser):
+
+```
+lazyclaw agent add planner --role "…" --provider claude-cli --model claude-opus-4-7 --tools bash,read,write
+lazyclaw agent list / show / edit / remove
+lazyclaw team  add shop  --lead planner --agents planner,backend,frontend --channel C0B5AGCP8PJ
+lazyclaw team  list / show / edit / remove
+lazyclaw task  start --team shop --title "ship checkout flow"
+lazyclaw task  list / show / abandon / done
+```
+
+REPL slash equivalents (`/agent`, `/team`, `/task`).
+
+---
+
+## 7. Phase plan
+
+Each phase exits 0 on its Playwright suite before the next phase starts.
+
+| Phase | Scope | Tests |
+|---|---|---|
+| **9** | Agent registry + CRUD CLI + dashboard list view | `phase9-agent-registry.spec.ts` |
+| **10** | Team registry + CRUD CLI + dashboard. Channel resolver. | `phase10-team-registry.spec.ts` |
+| **11** | Task registry + `lazyclaw task start` opens a Slack thread with the lead's intro turn. | `phase11-task-start.spec.ts` |
+| **12** | **Tool-use loop** (the big one). Provider abstraction for tool calls, audit log, file/path scoping. | `phase12-tool-use.spec.ts` |
+| **13** | Mention router — agent A's `@B` schedules B for next turn, with full thread context. Handoff back to lead when mentions run out. | `phase13-mention-router.spec.ts` |
+| **14** | Termination policies (DONE marker, maxTurns, manual). Final summary post. | `phase14-termination.spec.ts` |
+| **15** | Dashboard UI screens for agents/teams/tasks. WebSocket live updates. | `phase15-dashboard-mas.spec.ts` |
+| **16** | Polish — `chat:write.customize` per-agent username/icon, agent typing indicators, transcript export. | `phase16-polish.spec.ts` |
+
+Phase 9 + 10 + 11 alone get a working "post-from-dashboard-into-Slack" pipeline (no tool-use, no handoff yet) — that's the first user-visible milestone, ~3-4 days of work.
+
+---
+
+## 8. Cross-cutting
+
+- **Security** — tokens stay in `~/.lazyclaw/.env`, never logged, never in task records. Bash tool runs as the user (no privilege drop) — *only* enable for trusted teams/workspaces.
+- **Rate limits** — each agent turn counts against its provider's RL. Router pauses (not crashes) when an agent hits 429.
+- **Concurrency** — one task = one thread; multiple tasks can run concurrently. Per-task state is independent.
+- **Storage** — flat JSON files (matches lazyclaw's existing pattern: `~/.lazyclaw/goals/`, `~/.lazyclaw/loops/`). Migration story: bump `version` field per schema change, write a one-shot migrator.
+
+---
+
+## 9. Out of scope (v0.1 — deferred)
+
+- Cross-team handoffs (`@team:other/agent` syntax)
+- Parallel mention fan-out (multiple agents replying at the same time)
+- Persistent agent memory / self-improvement (orthogonal — uses `~/.lazyclaw/memory/`)
+- Non-Slack channels (Discord/Telegram) — pattern is identical once Phase 7 channel interface lands. Add post-v0.1.
+- Multi-workspace (one lazyclaw daemon serving more than one Slack workspace)
+- Voice / file attachments inside threads
+- Agent-vs-agent direct messages outside a task thread
+
+---
+
+## 10. Decisions — confirmed 2026-05-18
+
+| # | Question | Decision |
+|---|---|---|
+| 1 | Agent `@mention` form | **Full names** — `@planner`, `@backend`, `@frontend` |
+| 2 | Termination marker | **`[[TASK_DONE]]`** — explicit token, no false positives |
+| 3 | Default tool whitelist for new agents | **`[bash, read, write, grep]`** — full set, restrict per-agent if needed |
+| 4 | Slack channel topology | **One channel per team** — matches §3.2 |
+| 5 | Tool-use provider coverage in Phase 12 | **anthropic + openai + gemini** — all three from launch |
+| 6 | Bash destructive-pattern confirmation | **OFF by default** — dashboard per-team toggle to enable; audit log always on |
+
+Phase 9 work begins immediately after this commit lands.

package/goals.mjs

@@ -0,0 +1,128 @@
+// Persistent goal registry for `/goal` REPL command and `lazyclaw goal`
+// subcommand.
+//
+// Storage layout under <configDir>/goals/<name>.json. One file per goal so
+// concurrent `close` / `tick` writes don't race over a global index. The
+// canonical field set lives in `defaultShape()` below; new fields default
+// to null/empty so reading an older record stays forward-compatible.
+//
+// The name validator is delegated to cron.ensureValidName — the spec
+// requires identical error wording so a fat-finger like `/goal add "has
+// spaces"` produces the same message a user already knows from `cron add`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { ensureValidName as cronEnsureValidName } from './cron.mjs';
+
+const GOALS_DIRNAME = 'goals';
+
+export class GoalError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'GoalError';
+    this.code = code || 'GOAL_ERR';
+  }
+}
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function goalsDir(configDir = defaultConfigDir()) {
+  return path.join(configDir, GOALS_DIRNAME);
+}
+
+export function goalPath(name, configDir = defaultConfigDir()) {
+  ensureValidName(name);
+  return path.join(goalsDir(configDir), `${name}.json`);
+}
+
+export function ensureValidName(name) {
+  try { cronEnsureValidName(name); }
+  catch (e) { throw new GoalError(e.message, 'GOAL_BAD_NAME'); }
+}
+
+function defaultShape(name) {
+  return {
+    name,
+    description: '',
+    createdAt: new Date().toISOString(),
+    status: 'active',
+    schedule: null,
+    channels: [],
+    sessionId: `goal:${name}`,
+    checkIns: [],
+    memoryPath: null,
+  };
+}
+
+function writeAtomic(filePath, obj) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  fs.renameSync(tmp, filePath);
+}
+
+export function registerGoal({ name, description = '', schedule = null, channels = [] } = {}, configDir = defaultConfigDir()) {
+  ensureValidName(name);
+  const p = goalPath(name, configDir);
+  if (fs.existsSync(p)) {
+    throw new GoalError(`goal "${name}" already exists`, 'GOAL_EXISTS');
+  }
+  const data = {
+    ...defaultShape(name),
+    description,
+    schedule,
+    channels: Array.isArray(channels) ? channels : [],
+  };
+  writeAtomic(p, data);
+  return data;
+}
+
+export function getGoal(name, configDir = defaultConfigDir()) {
+  let p;
+  try { p = goalPath(name, configDir); }
+  catch { return null; }
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+export function listGoals(configDir = defaultConfigDir()) {
+  const dir = goalsDir(configDir);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.json')) continue;
+    const name = f.slice(0, -5);
+    const g = getGoal(name, configDir);
+    if (g) out.push(g);
+  }
+  out.sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+  return out;
+}
+
+export function patchGoal(name, patch, configDir = defaultConfigDir()) {
+  const g = getGoal(name, configDir);
+  if (!g) throw new GoalError(`no goal "${name}"`, 'GOAL_NO_GOAL');
+  const next = { ...g, ...patch };
+  writeAtomic(goalPath(name, configDir), next);
+  return next;
+}
+
+export function closeGoal(name, outcome = 'done', configDir = defaultConfigDir()) {
+  if (outcome !== 'done' && outcome !== 'abandoned') {
+    throw new GoalError(`outcome must be done or abandoned, got "${outcome}"`, 'GOAL_BAD_OUTCOME');
+  }
+  return patchGoal(name, { status: outcome, closedAt: new Date().toISOString() }, configDir);
+}
+
+export function appendCheckIn(name, summary, configDir = defaultConfigDir()) {
+  const g = getGoal(name, configDir);
+  if (!g) throw new GoalError(`no goal "${name}"`, 'GOAL_NO_GOAL');
+  const next = { ...g, checkIns: [...(g.checkIns || []), { at: new Date().toISOString(), summary }] };
+  writeAtomic(goalPath(name, configDir), next);
+  return next;
+}