kanbango 2.4.0 → 3.0.2

package/.ai/lessons.jsonl

@@ -0,0 +1,4 @@
+{"id":"260729-3h4","ts":"2026-07-29","scope":"proj","tags":["tests","mcp","cli","review"],"rule":"DO Add automated tests for every new public CLI/MCP workflow before shipping","when":"api-review","sev":2,"hits":1}
+{"id":"260729-1ur","ts":"2026-07-29","scope":"proj","tags":["javascript","objects"],"rule":"DON'T Use empty object fallbacks in spreads like `...(obj || {})` since spreading falsy is safe","when":"object spread","sev":2,"hits":1}
+{"id":"260729-5eo","ts":"2026-07-29","scope":"proj","tags":["processes","mcp","ownership"],"rule":"DO Track process ownership before stopping or cleaning up discovered services","when":"gui-process management","sev":2,"hits":1}
+{"id":"260729-1ch","ts":"2026-07-29","scope":"proj","tags":["gui","process","mcp"],"rule":"DO GUI/MCP stop must only SIGTERM processes spawned by the current process; treat port-file PIDs as external_running","when":"gui-process management","sev":2,"hits":1}

package/.ai/retro/close.json

@@ -0,0 +1 @@
+{"goal":"push do npm","done":["session had mutations"],"next":[],"block":[],"lessons":[],"files":["/Users/mkorbas/projects/personal/markdown-kanban/mcp-server.js","/Users/mkorbas/projects/personal/markdown-kanban/kanban.js","/Users/mkorbas/projects/personal/markdown-kanban/tests/mcp-server.test.js","/Users/mkorbas/projects/personal/markdown-kanban/plan.js","/Users/mkorbas/projects/personal/markdown-kanban/CHANGELOG.md","/Users/mkorbas/projects/personal/markdown-kanban/bin/kanban.js","/Users/mkorbas/projects/personal/markdown-kanban/tests/update-tasks.test.js"],"verify":""}

package/.ai/retro/last-run.json

@@ -0,0 +1 @@
+{"ts":"2026-07-29T10:38:42.184Z","sessionID":"ses_052c1be3fffeNPoV7VO6z40X2I","added":["260729-1ch"],"bumped":[]}

package/AGENTS.md

@@ -2,6 +2,17 @@
 
 This document provides build commands, testing procedures, and code style guidelines for working with the kanbango codebase.
 
+## Kanbango MCP — token rules (when using this board)
+
+Source of truth: `agent-playbook.js` (also MCP tool descriptions + `kanban_read` `operation=help`).
+
+- list: `col` filter, `view=summary`; keep `task_id`s; no full-board re-list after every write
+- show: `view=execution` while coding; `full` only if needed
+- create once with `description`, `specs`, `in_scope`, `out_of_scope`, `acceptance_criteria`
+- move/update: `return=none`; subtasks = full array replace (no toggle)
+- non-trivial work: `plan_create` → `plan_advance` → `plan_evidence` (real tests, truncated logs) → `plan_done`
+- gui: `status` before `start`; `stop` only owned; `external_running` = do not kill
+
 ## Build & Development Commands
 
 ### Available Scripts

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to kanbango will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.2] - 2026-07-29
+
+### Added
+- `agent-playbook.js` — single source of truth for agent token rules
+- `kanban_read` `operation=help` returns the playbook (no board I/O)
+- Test that `tools/list` descriptions match the playbook module
+
+### Changed
+- MCP tool descriptions are loaded from `agent-playbook.js` (not duplicated prose)
+- `LLM_AGENTS.md` clarified as human setup docs; agents rely on tool descriptions
+
+## [3.0.1] - 2026-07-29
+
+### Changed
+- MCP tool descriptions encode a token-efficient agent playbook (cheap list/show, fat create once, `return=none`, plan_* only when needed, GUI ownership)
+- `LLM_AGENTS.md`, `AGENTS.md`, and `README.md` document the same rules for project-scoped agents
+
+## [3.0.0] - 2026-07-29
+
+### Breaking
+- New task IDs are zero-padded numeric strings (`001`), not `PI-001-slug`
+- MCP/CLI `toggle` removed; update the full `subtasks` list via `update`
+- Legacy task field alias `tasks` removed; use `subtasks` only
+- `kanban_gui` `stop` only stops a GUI **spawned by the current MCP process**. An external GUI returns `status: "external_running"` and is **not** sent SIGTERM (PID-reuse safety)
+- `kanban_gui` `status` may return `running` (owned), `external_running` (discovered), or `not_running`
+
+### Added
+- Accepted-plan workflow: `plan.js` + CLI `kanban plan <action> --json` + MCP `plan_*` actions on `kanban_manage`
+- `gui-registry.js` — GUI port file, preferred port, discover helpers (extracted from `kanban.js`)
+- Regression tests for plan workflow and GUI process ownership
+
+### Changed
+- Create field policy: only `title` is hard-required; `description`, `specs`, `in_scope`, `out_of_scope`, and `acceptance_criteria` are strongly recommended
+- MCP `kanban_manage` create/plan_create returns `warnings` + `missing_recommended` when recommended fields are omitted (still succeeds)
+- MCP tool descriptions and LLM agent docs push agents to always fill planning boundaries
+
+## [2.5.0] - 2026-07-27
+
+### Changed
+- Create field policy: only `title` is hard-required; `description`, `specs`, `in_scope`, `out_of_scope`, and `acceptance_criteria` are strongly recommended
+- MCP `kanban_manage` create/plan_create returns `warnings` + `missing_recommended` when recommended fields are omitted (still succeeds)
+- MCP tool descriptions and LLM agent docs push agents to always fill planning boundaries
+
 ## [2.4.0] - 2026-07-27
 
 ### Added

package/LLM_AGENTS.md

@@ -1,6 +1,12 @@
 # MCP Server Guide for LLM Agents
 
-Complete guide for integrating kanbango MCP server into LLM agents and AI assistants.
+Human-oriented setup guide. **Agents do not load this file automatically.**
+
+Canonical usage rules live in code (`agent-playbook.js`) and are injected into MCP
+`tools/list` descriptions. After install, the agent only needs the MCP server —
+not this markdown.
+
+Optional refresh in-session: `kanban_read` with `operation: "help"`.
 
 ## Quick Integration
 
@@ -63,11 +69,12 @@ Read tasks from kanban board. Can list all tasks, filter by column/epic, or get
 **Operations:**
 - `list` - Get all tasks (with optional filters)
 - `show` - Get specific task details
+- `help` - Return token playbook from `agent-playbook.js` (no board I/O)
 
 **Parameters:**
 ```json
 {
-  "operation": "list",  // "list" or "show"
+  "operation": "list",  // "list" | "show" | "help"
   "task_id": "014",  // Required for "show"
   "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done"
   "epic": "Phase 1"  // Optional: filter by epic group
@@ -146,20 +153,22 @@ Create, move, or patch-update kanban tasks. Single tool for all mutations.
 ```json
 {
   "action": "create",
-  "title": "New feature",  // Required
+  "title": "New feature",  // Required (only hard requirement)
   "col": "planned",  // Optional, default "planned"
   "epic": "Phase 1",  // Optional, default "—"
-  "description": "Context and plan",
-  "specs": "Technical constraints",
-  "in_scope": ["What is included"],
-  "out_of_scope": ["What is excluded"],
-  "acceptance_criteria": ["Must work"],
-  "test_cases": ["Verify X"],
+  "description": "Context and plan",  // Strongly recommended
+  "specs": "Technical constraints",  // Strongly recommended
+  "in_scope": ["What is included"],  // Strongly recommended
+  "out_of_scope": ["What is excluded"],  // Strongly recommended
+  "acceptance_criteria": ["Must work"],  // Strongly recommended
+  "test_cases": ["Verify X"],  // Recommended
   "subtasks": [{"text": "Do it", "done": false}],
   "notes": "Freeform notes"
 }
 ```
 
+**Create field policy:** only `title` is hard-required (GUI/CLI quick-add stays usable). For agent work, always send the strongly recommended fields. If any are missing, create still succeeds and the response includes `warnings` + `missing_recommended`.
+
 **Parameters (move):**
 ```json
 {
@@ -189,7 +198,12 @@ Create a task:
   "action": "create",
   "title": "Database optimization",
   "col": "planned",
-  "epic": "Performance"
+  "epic": "Performance",
+  "description": "Reduce N+1 queries on board list",
+  "specs": "Keep JSON storage; no new deps",
+  "in_scope": ["list query path"],
+  "out_of_scope": ["GUI redesign"],
+  "acceptance_criteria": ["list stays correct under load"]
 }
 ```
 
@@ -225,6 +239,11 @@ Patch-update task fields:
 
 Control the web GUI server: start, stop, or check status.
 
+**Ownership (important):**
+- `stop` only sends SIGTERM to a GUI **spawned by this MCP process** (`owned: true`).
+- If the GUI was started elsewhere (CLI `kanban serve`, another MCP), `stop` returns `external_running` and does **not** kill that PID.
+- `status` distinguishes `running` (owned), `external_running` (discovered via port file), and `not_running`.
+
 **Port resolution (start):**
 1. Explicit `port` argument, if provided
 2. Else `KANBANGO_GUI_PORT` env
@@ -235,9 +254,9 @@ If the preferred port is busy, the server picks the next free port. Always trust
 **Auto-start with MCP:** set `KANBANGO_AUTO_GUI=1` in the MCP server env. GUI starts when MCP starts; use `status` to read the URL.
 
 **Actions:**
-- `start` - Launch the GUI server
-- `stop` - Kill the GUI server
-- `status` - Check if the GUI is running (reads live process or port file)
+- `start` - Launch the GUI server (or report already_running owned/external)
+- `stop` - Stop only MCP-owned GUI
+- `status` - Check GUI state
 
 **Parameters:**
 ```json
@@ -282,31 +301,57 @@ Check status:
 ```json
 {
   "status": "started",
+  "owned": true,
   "port": 5623,
   "pid": 12345,
   "url": "http://localhost:5623"
 }
 ```
 
-**Response (stop):**
+**Response (stop - owned):**
 ```json
 {
   "status": "stopping",
+  "owned": true,
   "port": 5623,
   "pid": 12345
 }
 ```
 
-**Response (status - running):**
+**Response (stop - external refused):**
+```json
+{
+  "status": "external_running",
+  "owned": false,
+  "port": 5623,
+  "pid": 12345,
+  "url": "http://localhost:5623",
+  "hint": "GUI was not started by this MCP process; stop refused."
+}
+```
+
+**Response (status - running owned):**
 ```json
 {
   "status": "running",
+  "owned": true,
   "port": 5623,
   "pid": 12345,
   "url": "http://localhost:5623"
 }
 ```
 
+**Response (status - external):**
+```json
+{
+  "status": "external_running",
+  "owned": false,
+  "port": 5623,
+  "pid": 99999,
+  "url": "http://localhost:5623"
+}
+```
+
 **Response (status - not running):**
 ```json
 {
@@ -365,8 +410,18 @@ Check status:
 ### Pattern 2: Task Creation Workflow
 
 ```json
-// 1. Create task
-{ "tool": "kanban_manage", "arguments": { "action": "create", "title": "New feature", "col": "planned", "epic": "Phase 1" } }
+// 1. Create task with strongly recommended planning fields
+{ "tool": "kanban_manage", "arguments": {
+  "action": "create",
+  "title": "New feature",
+  "col": "planned",
+  "epic": "Phase 1",
+  "description": "Why this exists",
+  "specs": "APIs and constraints",
+  "in_scope": ["Core path"],
+  "out_of_scope": ["Mobile"],
+  "acceptance_criteria": ["npm test passes"]
+} }
 
 // 2. Get task details to see generated ID
 { "tool": "kanban_read", "arguments": { "operation": "show", "task_id": "015" } }
@@ -394,22 +449,49 @@ Check status:
 // List all tasks in an epic
 { "tool": "kanban_read", "arguments": { "operation": "list", "epic": "Performance" } }
 
-// Create task in specific epic
-{ "tool": "kanban_manage", "arguments": { "action": "create", "title": "Cache optimization", "epic": "Performance" } }
+// Create task in specific epic (still include recommended fields)
+{ "tool": "kanban_manage", "arguments": {
+  "action": "create",
+  "title": "Cache optimization",
+  "epic": "Performance",
+  "description": "Reduce repeated board reads",
+  "specs": "In-memory cache with TTL",
+  "in_scope": ["list endpoint"],
+  "out_of_scope": ["distributed cache"],
+  "acceptance_criteria": ["p95 list latency down"]
+} }
 ```
 
 ---
 
-## Best Practices for LLM Agents
+## Token-efficient playbook (source of truth)
+
+**Edit `agent-playbook.js` only.** MCP tool descriptions and `operation=help` are built from it.
+
+At runtime agents already receive the rules via tool descriptions. Humans can also call:
+
+```json
+{ "operation": "help" }
+```
+
+on `kanban_read` (no board I/O).
+
+### Drop-in for project `AGENTS.md` (optional)
 
-1. **Always use `kanban_read` first** - Discover existing tasks before creating new ones
-2. **Numeric task lookup** - Task IDs are zero-padded numbers (e.g. `"035"`). Unpadded numbers such as `"35"` also work in any `task_id` parameter.
-3. **Use `col` filter** - Narrow down to relevant column when listing
-4. **Use `epic` grouping** - Organize tasks by features/phases
-5. **Work through subtasks** - Toggle each subtask as you complete them
-6. **Move tasks through workflow** - planned → active → done progression
-7. **Use `show` operation** - Get full task details including subtasks
-8. **Handle task IDs** - Always use the full task ID returned from create/show
+Same bullets as `DROP_IN_RULE` in `agent-playbook.js` — copy if you want them outside MCP:
+
+```text
+Kanbango MCP — token rules:
+- list: col filter, view=summary; keep task_ids; no full-board re-list after writes
+- show: view=execution while coding; full only if needed
+- create once with description,specs,in_scope,out_of_scope,acceptance_criteria
+- move/update: return=none; subtasks=full array replace
+- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done
+- gui: status before start; stop only owned; external_running = do not kill
+```
+
+### Columns
+`planned` → `active` (few at a time) → `done`. Use `icebox` for parked work.
 
 ---
 

package/README.md

@@ -129,9 +129,11 @@ Once connected, your agent gets access to these tools:
 
 | Tool | What it does |
 |------|-------------|
-| `kanban_read` | List tasks, filter by column/epic, show details |
-| `kanban_manage` | Create, move, patch-update tasks |
-| `kanban_gui` | Start, stop, or check web GUI status (returns the real URL/port) |
+| `kanban_read` | List/show tasks (`view=summary` by default — cheap) |
+| `kanban_manage` | Create, move, update, plan_* workflow |
+| `kanban_gui` | Start / status / stop (stop only kills GUI this MCP started) |
+
+**Token tip for agents:** rules ship inside MCP tool descriptions (`agent-playbook.js`). Optional: `kanban_read` → `operation: "help"`. Human setup notes: [LLM_AGENTS.md](./LLM_AGENTS.md).
 
 Your agent stays in sync with your real board — every change is persisted as JSON files.
 
@@ -146,6 +148,7 @@ Your agent stays in sync with your real board — every change is persisted as J
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
 | `kanban mcp-init` | Generate MCP config files |
+| `kanban plan <action> --json '{...}'` | Accepted-plan workflow (create/advance/evidence/done/status) |
 
 ## Web GUI
 

package/agent-playbook.js

@@ -0,0 +1,71 @@
+/**
+ * Single source of truth for agent-facing kanbango usage rules.
+ * MCP tool descriptions are built from this module — not from LLM_AGENTS.md.
+ * Docs may quote DROP_IN_RULE; keep them in sync by editing here only.
+ */
+
+const DROP_IN_RULE = [
+  'Kanbango MCP — token rules:',
+  '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
+  '- show: view=execution while coding; full only if needed',
+  '- create once with description,specs,in_scope,out_of_scope,acceptance_criteria',
+  '- move/update: return=none; subtasks=full array replace',
+  '- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done',
+  '- gui: status before start; stop only owned; external_running = do not kill'
+].join('\n');
+
+const TOOL_DESCRIPTIONS = {
+  kanban_read: [
+    'Read board. TOKEN RULES: list defaults to view=summary (id/title/col/progress only).',
+    'Always pass col when possible. Prefer show+view=execution over full.',
+    'Do not re-list the whole board after every write — keep task_id from create/move.',
+    'IDs are numeric ("014" or "14"). views: summary|planning|execution|full; fields[] overrides view.',
+    'operation=help returns this playbook as short text (no board I/O).'
+  ].join(' '),
+
+  kanban_manage: [
+    'Write board / plan. TOKEN RULES: one create with all planning fields beats many updates;',
+    'after write use return=none (or summary). Do not dump full task unless needed.',
+    'Actions: create|move|update (daily); plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'create/plan_create: title required; also send description,specs,in_scope,out_of_scope,acceptance_criteria',
+    '(missing → warnings, not failure). move: task_id+column. update: task_id + fields or subtasks[] full list',
+    '(no toggle). plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
+    'Example create: {"action":"create","title":"Ship image","description":"...","specs":"...","in_scope":["CLI"],',
+    '"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned"}'
+  ].join(' '),
+
+  kanban_gui: [
+    'Web GUI control. Prefer status before start. stop only kills GUI this MCP spawned;',
+    'external_running = do not retry kill — use the returned url or leave it.',
+    'status: running|external_running|not_running. Rarely needed mid-task — open once if user wants UI.'
+  ].join(' ')
+};
+
+const MUST_CONTAIN = [
+  'TOKEN RULES',
+  'view=summary',
+  'return=none',
+  'plan_create',
+  'external_running',
+  'subtasks'
+];
+
+function playbookHelpPayload() {
+  return {
+    source: 'agent-playbook.js',
+    note: 'Canonical rules for agents. Same text drives MCP tool descriptions. LLM_AGENTS.md is human docs only.',
+    drop_in_rule: DROP_IN_RULE,
+    tools: {
+      kanban_read: TOOL_DESCRIPTIONS.kanban_read,
+      kanban_manage: TOOL_DESCRIPTIONS.kanban_manage,
+      kanban_gui: TOOL_DESCRIPTIONS.kanban_gui
+    }
+  };
+}
+
+module.exports = {
+  DROP_IN_RULE,
+  TOOL_DESCRIPTIONS,
+  MUST_CONTAIN,
+  playbookHelpPayload
+};

package/bin/kanban-cmd.js

@@ -13,7 +13,7 @@ function findPython() {
       if (result.status === 0) {
         return cmd;
       }
-    } catch (e) {
+    } catch {
       continue;
     }
   }

package/bin/kanban.js

@@ -2,12 +2,12 @@
 
 const kanban = require('../kanban.js');
 const plan = require('../plan.js');
+const guiRegistry = require('../gui-registry.js');
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
-const COLS = kanban.COLS;
 
 function shortId(taskId) {
   const match = taskId.match(/^(?:[A-Z]+-)?(\d+)/);
@@ -357,11 +357,11 @@ async function serveWeb(port) {
   }
 
   const actualPort = server.address().port;
-  const portInfo = await kanban.writeGuiPortFile({ port: actualPort, pid: process.pid });
+  const portInfo = await guiRegistry.writeGuiPortFile({ port: actualPort, pid: process.pid });
 
   async function cleanupGuiPortFile() {
     try {
-      await kanban.clearGuiPortFile({ pid: process.pid });
+      await guiRegistry.clearGuiPortFile({ pid: process.pid });
     } catch {
       // best-effort cleanup
     }
@@ -458,9 +458,9 @@ async function main() {
   const args = process.argv.slice(2);
   const cmd = args[0];
 
-if (!cmd || cmd === 'serve') {
-  const port = kanban.resolvePreferredGuiPort(args[1]);
-  await serveWeb(port);
+  if (!cmd || cmd === 'serve') {
+    const port = guiRegistry.resolvePreferredGuiPort(args[1]);
+    await serveWeb(port);
   } else if (cmd === 'init') {
     await cliInit();
   } else if (cmd === 'mcp-init') {

package/gui-registry.js

@@ -0,0 +1,148 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+const BACKLOG = path.join(process.cwd(), 'backlog');
+const GUI_PORT_FILE = '.kanbango-gui.json';
+const GUI_PORT_MIN = 5510;
+const GUI_PORT_MAX = 5999;
+const GUI_PORT_SPAN = GUI_PORT_MAX - GUI_PORT_MIN + 1;
+
+function createGuiError(code, message, hint, details = {}, retryable = false, status = 400) {
+  const error = new Error(message);
+  error.code = code;
+  error.hint = hint;
+  error.details = details;
+  error.retryable = retryable;
+  error.status = status;
+  return error;
+}
+
+function guiPortFilePath() {
+  return path.join(BACKLOG, GUI_PORT_FILE);
+}
+
+function hashCwdToPort(cwd = process.cwd()) {
+  let hash = 0;
+  const input = String(cwd);
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) - hash + input.charCodeAt(i)) | 0;
+  }
+  return GUI_PORT_MIN + (Math.abs(hash) % GUI_PORT_SPAN);
+}
+
+function normalizeGuiPort(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+    return null;
+  }
+  return parsed;
+}
+
+function resolvePreferredGuiPort(explicitPort) {
+  if (explicitPort !== undefined && explicitPort !== null && explicitPort !== '') {
+    const fromArg = normalizeGuiPort(explicitPort);
+    if (fromArg) return fromArg;
+  }
+
+  const fromEnv = normalizeGuiPort(process.env.KANBANGO_GUI_PORT);
+  if (fromEnv) return fromEnv;
+
+  return hashCwdToPort(process.cwd());
+}
+
+function isPidAlive(pid) {
+  const n = Number.parseInt(pid, 10);
+  if (!Number.isFinite(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureBacklogDir() {
+  await fs.mkdir(BACKLOG, { recursive: true });
+}
+
+async function writeGuiPortFile({ port, pid = process.pid } = {}) {
+  const normalizedPort = normalizeGuiPort(port);
+  if (!normalizedPort) {
+    throw createGuiError(
+      'VALIDATION_ERROR',
+      'Invalid GUI port',
+      'Use an integer between 1 and 65535',
+      { port },
+      false,
+      400
+    );
+  }
+
+  await ensureBacklogDir();
+  const data = {
+    port: normalizedPort,
+    pid,
+    url: `http://localhost:${normalizedPort}`,
+    cwd: process.cwd(),
+    started_at: new Date().toISOString()
+  };
+  await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+
+async function readGuiPortFile() {
+  try {
+    const raw = await fs.readFile(guiPortFilePath(), 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || !normalizeGuiPort(data.port)) return null;
+    return data;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    return null;
+  }
+}
+
+async function clearGuiPortFile({ pid, force = false } = {}) {
+  const info = await readGuiPortFile();
+  if (!info) return false;
+  if (!force && pid !== undefined && info.pid !== pid) return false;
+  if (!force && pid === undefined && info.pid !== process.pid) return false;
+
+  try {
+    await fs.unlink(guiPortFilePath());
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function discoverRunningGui() {
+  const info = await readGuiPortFile();
+  if (!info || !isPidAlive(info.pid)) {
+    if (info) await clearGuiPortFile({ force: true });
+    return null;
+  }
+  return {
+    status: 'running',
+    port: info.port,
+    pid: info.pid,
+    url: info.url || `http://localhost:${info.port}`,
+    cwd: info.cwd,
+    started_at: info.started_at
+  };
+}
+
+module.exports = {
+  hashCwdToPort,
+  normalizeGuiPort,
+  resolvePreferredGuiPort,
+  isPidAlive,
+  writeGuiPortFile,
+  readGuiPortFile,
+  clearGuiPortFile,
+  discoverRunningGui,
+  guiPortFilePath,
+  GUI_PORT_MIN,
+  GUI_PORT_MAX
+};

package/index.js

@@ -10,8 +10,12 @@
 
 const kanban = require('./kanban.js');
 const plan = require('./plan.js');
+const guiRegistry = require('./gui-registry.js');
+const playbook = require('./agent-playbook.js');
 
 module.exports = {
   kanban,
   plan,
+  guiRegistry,
+  playbook,
 };