feinai 0.6.7 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [0.7.0] - 2026-06-22
+
+### Added
+- **Project-scoped server port tracking** (`server_state` table in `feinai.db`)
+  - `feinai status` now validates & repairs the server record before printing the exact project URL
+  - `feinai server` auto-increments from port 8272 when the default is busy
+  - `feinai server --down` targets the recorded pid/port for this project
+  - Graceful shutdown clears the server record from the DB
+- 6 unit tests for server-state DB operations
+
+### Changed
+- **Normalized language**: removed all "Claude Code" and provider-specific references across CLI, README, and skill files
+- `feinai-implement` skill fully translated from Spanish to English
+- `CLAUDE.md` references → `AGENTS.md`, `.claude/ARCHITECTURE.md` → `ARCHITECTURE.md`
+- `formatStatus` accepts optional `serverUrl` parameter
+
 ## [0.6.3] - 2026-06-11
 
 ### Fixed

package/README.md

@@ -109,9 +109,9 @@ Agents don't parse `QUEUE.md`. They talk to a small local coordination service i
 
 ---
 
-## Claude Code skills
+## Agent harness skills
 
-feinai ships three Claude Code skills covering the full development loop. They activate automatically when `.feinai/feinai.db` is present:
+feinai ships three skills covering the full development loop. They activate automatically when `.feinai/feinai.db` is present:
 
 | Skill               | Purpose                                                                          |
 |---------------------|----------------------------------------------------------------------------------|
@@ -121,14 +121,14 @@ feinai ships three Claude Code skills covering the full development loop. They a
 
 Together they cover: design → spec → plan → tasks → parallel execution → merge.
 
-### Activating skills in Claude Code
+### Activating skills
 
 ```sh
-mkdir -p ~/.claude/skills
+mkdir -p <your-harness-skills-dir>
 SKILLS=~/.bun/install/global/node_modules/feinai/skills
 
 for skill in feinai-write-spec feinai-dispatch feinai-implement; do
-  ln -sf "$SKILLS/$skill" ~/.claude/skills/$skill
+  ln -sf "$SKILLS/$skill" <your-harness-skills-dir>/$skill
 done
 ```
 
@@ -149,7 +149,7 @@ This installs:
 
 ### PATH setup (non‑interactive SSH)
 
-In interactive shells and for local agents (Claude Code, opencode) it should work out of the box.
+In interactive shells and for local coding agents it should work out of the box.
 
 For non‑interactive SSH sessions (e.g. `ssh host 'feinai status'`), you may need a one‑time setup:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feinai",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Task & spec manager for AI agents — parallel worktrees, live dashboard, SDD skills",
   "type": "module",
   "bin": {
@@ -21,7 +21,6 @@
   "keywords": [
     "task-manager",
     "sdd",
-    "claude-code",
     "ai-agents",
     "sqlite",
     "cli",

package/skills/feinai-dispatch/SKILL.md

@@ -76,19 +76,19 @@ feinai is installed but no DB in this project. Ask the user:
 
 ---
 
-### Failure: skills not activating in Claude Code
+### Failure: skills not activating in your agent harness
 
-If Claude Code doesn't recognize `feinai-dispatch` or other skills after install:
+If your agent harness doesn't recognize `feinai-dispatch` or other skills after install:
 
 > Run this to activate the skills:
 > ```bash
-> mkdir -p ~/.claude/skills
+> mkdir -p <your-harness-skills-dir>
 > SKILLS=~/.bun/install/global/node_modules/feinai/skills
 > for skill in feinai-sdd feinai-write-spec feinai-write-tasks feinai-dispatch feinai-implement; do
->   ln -sf "$SKILLS/$skill" ~/.claude/skills/$skill
+>   ln -sf "$SKILLS/$skill" <your-harness-skills-dir>/$skill
 > done
 > ```
-> Then restart Claude Code.
+> Then restart your agent harness.
 
 **Offer to run it.**
 
@@ -162,7 +162,7 @@ For each iteration:
 For each task to dispatch:
 
 ```bash
-git worktree add .claude/worktrees/TASK-X-id <branch>
+git worktree add .worktrees/TASK-X-id <branch>
 ```
 
 Branch naming: `feature/TASK-X-id-slug` derived from the subject.
@@ -171,7 +171,7 @@ Branch naming: `feature/TASK-X-id-slug` derived from the subject.
 
 ```bash
 feinai take TASK-X --json   # atomic claim, sin worktree aún
-feinai task edit TASK-X --worktree .claude/worktrees/TASK-X-id
+feinai task edit TASK-X --worktree .worktrees/TASK-X-id
 ```
 
 Order matters: take first (atomic reservation), then edit to record the worktree path.
@@ -218,7 +218,7 @@ For each `completed` task:
 
 1. Run the quality gates **again** in the worktree as a final check
 2. Merge worktree branch into the working branch
-3. Remove the worktree: `git worktree remove .claude/worktrees/TASK-X-id`
+3. Remove the worktree: `git worktree remove .worktrees/TASK-X-id`
 4. Clear the worktree field: `feinai task edit TASK-X --worktree ""`
 
 If the merge has conflicts → treat as a failure. Go to Phase 3.
@@ -270,7 +270,7 @@ When `feinai list --spec SPEC-NNN --pending --json` returns empty:
 
 ### Worktree rules (non-negotiable)
 
-- ✅ Each task gets its own worktree under `.claude/worktrees/`
+- ✅ Each task gets its own worktree under `.worktrees/`
 - ✅ Subagent never switches branches, never works outside its worktree
 - ✅ Worktree path is recorded in feinai (`worktree` field) immediately after `take`
 - ❌ Never run `git checkout` on the main working tree during dispatch

package/skills/feinai-implement/SKILL.md

@@ -17,117 +17,117 @@ If any fails: stop and report. Do not improvise.
 
 ---
 
-## AL ARRANCAR
+## On startup
 
-1. `feinai list --pending --json` — encontrá la primera tarea disponible (sin blockers pendientes)
-2. Si no hay ninguna → respondé "No hay tareas pendientes" y pará
-3. `feinai take <TASK-ID> --owner implement-agent` — tomala atómicamente
-4. Si la tarea tiene `spec_id` → `feinai spec content <SPEC-ID>` para contexto
-5. Si la tarea tiene `blocked_by` con tareas no completadas → soltá con `feinai release <TASK-ID>` y pará
+1. `feinai list --pending --json` — find the first available task (no pending blockers)
+2. If none exists → respond "No pending tasks" and stop
+3. `feinai take <TASK-ID> --owner implement-agent` — claim it atomically
+4. If the task has `spec_id` → `feinai spec content <SPEC-ID>` for context
+5. If the task has `blocked_by` with uncompleted tasks → release with `feinai release <TASK-ID>` and stop
 
-Leé `AGENTS.md` del proyecto para arquitectura y convenciones del proyecto específico.
+Read `AGENTS.md` of the project for architecture and project-specific conventions.
 
 ---
 
-## Ejecutar la tarea
+## Execute the task
 
-**Paso 1 — Worktree aislado:**
+**Step 1 — Isolated worktree:**
 ```bash
 feinai git worktree add .worktrees/<TASK-ID> origin/main
 cd .worktrees/<TASK-ID>
 ```
 
-**Paso 2 — Setup del worktree:**
-Instalá dependencias si el proyecto las requiere. Consultá `AGENTS.md` del proyecto para el comando exacto.
+**Step 2 — Worktree setup:**
+Install dependencies if the project requires them. Check `AGENTS.md` of the project for the exact command.
 
-**Paso 3 — Leer antes de escribir:**
-- La descripción completa de la tarea (`feinai show <TASK-ID>`)
-- Los archivos que vas a tocar — léelos antes de editarlos
-- Si hay un **Workplan** en la descripción → ejecutá esos pasos en ese orden exacto
+**Step 3 — Read before writing:**
+- The full task description (`feinai show <TASK-ID>`)
+- The files you will touch — read them before editing
+- If there is a **Workplan** in the description → follow those steps in exact order
 
-**Paso 4 — Implementar:**
-Exactamente lo que dice la tarea. Ni más ni menos.
-- No toques archivos fuera del scope de la tarea
-- Si un archivo "a crear" ya existe → extendelo en lugar de sobrescribirlo si ya tiene contenido válido
+**Step 4 — Implement:**
+Exactly what the task says. No more, no less.
+- Do not touch files outside the task scope
+- If a file "to create" already exists → extend it instead of overwriting if it already contains valid content
 
-**Paso 5 — Commit:**
-Un commit por tarea. Conventional commits:
+**Step 5 — Commit:**
+One commit per task. Conventional commits:
 ```
-feat(scope): descripción concisa
+feat(scope): concise description
 ```
-Tipos: `feat`, `fix`, `refactor`, `test`, `chore`.
+Types: `feat`, `fix`, `refactor`, `test`, `chore`.
 
-**Paso 6 — Quality gates:**
-Corré los gates definidos en la tarea (`quality_gates`). Si la tarea no los especifica, consultá `AGENTS.md` del proyecto para los gates por defecto.
+**Step 6 — Quality gates:**
+Run the gates defined in the task (`quality_gates`). If the task does not specify them, check `AGENTS.md` of the project for default gates.
 
-**Paso 7 — Cerrar:**
+**Step 7 — Close:**
 
-Gates pasan:
+Gates pass:
 ```bash
-# Desde el worktree:
+# From the worktree:
 feinai git push origin HEAD:main
 
-# Desde la raíz del repo:
+# From the repo root:
 feinai git worktree remove .worktrees/<TASK-ID>
 feinai git complete
 
 feinai done <TASK-ID> --result "gates ✓"
 ```
 
-Gates fallan → seguí "Si algo falla".
+Gates fail → follow "If something fails".
 
-**Done = 3 hechos observables:**
-1. Quality gates pasan sin errores
-2. Los archivos de la tarea existen con contenido correcto
-3. Commit limpio en `main` y tarea en estado `completed` en feinai
+**Done = 3 observable facts:**
+1. Quality gates pass without errors
+2. The task files exist with correct content
+3. Clean commit on `main` and task status `completed` in feinai
 
 ---
 
-## Si algo falla
+## If something fails
 
-Gates fallan, push falla, o error en cualquier paso:
+Gates fail, push fails, or error at any step:
 
-1. **No limpies el worktree**
-2. Push a rama backup:
+1. **Do not clean the worktree**
+2. Push to a backup branch:
    ```bash
    feinai git push origin HEAD:backup/<TASK-ID>
    ```
-3. Marcá la tarea como fallida:
+3. Mark the task as failed:
    ```bash
-   feinai fail <TASK-ID> --error "<comando exacto + output relevante>"
+   feinai fail <TASK-ID> --error "<exact command + relevant output>"
    ```
-4. Dejá el worktree intacto para recuperación manual
+4. Leave the worktree intact for manual recovery
 
 ---
 
-## Git — `feinai git` exclusivamente
+## Git — `feinai git` exclusively
 
-`git` y `gh` están bloqueados. Usá `feinai git` para todo — es opengit bundleado con feinai.
+`git` and `gh` are blocked. Use `feinai git` for everything — it is opengit bundled with feinai.
 
-**Permitido:**
+**Allowed:**
 - `feinai git worktree add/list/lock/unlock`
 - `feinai git add`, `commit`, `push`, `status`, `diff`, `log`, `show`
-- `feinai git complete` — sincroniza main local tras push (solo desde raíz del repo)
+- `feinai git complete` — syncs local main after push (only from repo root)
 
-**Prohibido:**
-- `feinai git branch`, `checkout`, `switch` — nunca cambiar branches
+**Prohibited:**
+- `feinai git branch`, `checkout`, `switch` — never switch branches
 - `feinai git merge`, `rebase`, `reset`, `cherry-pick`
 - `feinai git fetch`, `pull`, `remote`, `clone`
 - `feinai git stash`, `tag`
-- `feinai git worktree remove` — solo tras push exitoso
+- `feinai git worktree remove` — only after successful push
 
-Si `feinai git` falla → **STOP**. No reintentes, no uses `git`. Reportá al usuario.
+If `feinai git` fails → **STOP**. Do not retry, do not use `git`. Report to the user.
 
 ---
 
-## Reglas absolutas
+## Absolute rules
 
-**No modifiques:**
+**Do not modify:**
 - `AGENTS.md`, `CLAUDE.md`
-- Archivos de configuración de CI/CD, infra, o secretos (`.env`, `.env.*`)
-- La DB de feinai directamente
+- CI/CD, infrastructure, or secret configuration files (`.env`, `.env.*`)
+- The feinai DB directly
 
-**Código:**
-- Sin `any` sin comentario justificado en la misma línea
-- Si un test falla: corregí el test O la implementación. Nunca silencies, skipees, ni agregues workarounds para que el gate "pase"
-- Si no es obvio cuál es la causa → **STOP**, reportá al usuario con el comando exacto y el output completo
+**Code:**
+- No `any` without a justified comment on the same line
+- If a test fails: fix either the test or the implementation. Never silence, skip, or add workarounds to make the gate "pass"
+- If the cause is not obvious → **STOP**, report to the user with the exact command and the full output

package/skills/feinai-write-spec/SKILL.md

@@ -48,8 +48,8 @@ as a minimal change (just the input + endpoint call) or shall I think wider
 
 Read **in this order, stop early if enough**:
 
-1. `CLAUDE.md` (root) — already in your context normally
-2. `.claude/ARCHITECTURE.md` or `ARCHITECTURE.md` (root)
+1. `AGENTS.md` (root) — already in your context normally
+2. `ARCHITECTURE.md` (root)
 3. `README.md`
 4. `decisions/` directory (just file names, read only if a name matches the topic)
 

package/src/cli.ts

@@ -47,6 +47,13 @@ import {
   formatStatus,
   type OutputFormat,
 } from "./format";
+import {
+  readServerState,
+  writeServerState,
+  clearServerState,
+  findFreePort,
+  repairServerState,
+} from "./server-state";
 
 const VERSION = "0.6.7";
 
@@ -130,7 +137,7 @@ function detectFormat(args: ParsedArgs): OutputFormat {
  *   2. parent process name (on Linux via /proc/$PPID/comm) → "{parent_name}:{ppid}:{user}"
  *   3. fallback: "{user}@{hostname}"
  *
- * The parent process name lets us distinguish "claude:12345:m" from "opencode:23456:m"
+ * The parent process name lets us distinguish "harness-a:12345:m" from "harness-b:23456:m"
  * from "bash:9999:m" in the events audit log without manual configuration.
  */
 function getCurrentUser(): string {
@@ -261,13 +268,13 @@ GLOBAL FLAGS:
 ENV:
   FEINAI_USER                        Override owner/actor identity used in audit log
 
-\x1b[34m\x1b[1m── Claude Code Skills ─────────────────────────────────────────────\x1b[0m
-  \x1b[36mActivate feinai skills for Claude Code (run once after install):\x1b[0m
+\x1b[34m\x1b[1m── Agent Harness Skills ───────────────────────────────────────────\x1b[0m
+  \x1b[36mActivate feinai skills for your agent harness (run once after install):\x1b[0m
 
-  \x1b[33mmkdir -p ~/.claude/skills\x1b[0m
+  \x1b[33mmkdir -p <your-harness-skills-dir>\x1b[0m
   \x1b[33mSKILLS=~/.bun/install/global/node_modules/feinai/skills\x1b[0m
   \x1b[33mfor skill in feinai-sdd feinai-write-spec feinai-write-tasks feinai-dispatch feinai-implement; do\x1b[0m
-  \x1b[33m  ln -sf "$SKILLS/$skill" ~/.claude/skills/$skill\x1b[0m
+  \x1b[33m  ln -sf "$SKILLS/$skill" <your-harness-skills-dir>/$skill\x1b[0m
   \x1b[33mdone\x1b[0m
 
   \x1b[36mSkills included:\x1b[0m
@@ -429,10 +436,11 @@ function cmdStatus(format: OutputFormat): void {
   const specs = (db.prepare(`SELECT COUNT(*) AS n FROM specs`).get() as { n: number }).n;
   const plans = (db.prepare(`SELECT COUNT(*) AS n FROM plans`).get() as { n: number }).n;
 
-  // Check if server is running by probing the port
-  const port = 8272;
-  const lsof = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`]);
-  const serverRunning = lsof.exitCode === 0 && new TextDecoder().decode(lsof.stdout).trim().length > 0;
+  // Check server state: validate and repair stale records first
+  const serverRecord = repairServerState(db);
+  const serverRunning = serverRecord !== null;
+  const serverPort = serverRecord?.port ?? 8272;
+  const serverUrl = serverRunning ? `http://127.0.0.1:${serverPort}` : undefined;
 
   console.log(
     formatStatus(
@@ -443,7 +451,8 @@ function cmdStatus(format: OutputFormat): void {
         specs,
         plans,
         serverRunning,
-        serverPort: port,
+        serverPort,
+        serverUrl,
       },
       format,
     ),
@@ -770,19 +779,47 @@ function cmdSpec(rest: string[], args: ParsedArgs, format: OutputFormat): void {
 async function cmdServer(args: ParsedArgs): Promise<void> {
   const port = Number(args.options.port ?? "8272");
 
-  // --down: kill whatever is listening on the feinai port
+  // --down: stop the project's recorded server, fallback to default port
   if (args.flags["down"]) {
-    if (Number.isNaN(port) || port < 1 || port > 65535) {
+    const db = findDbPath() ? openDb() : null;
+    let targetPort = port;
+    let targetPids: number[] = [];
+
+    if (db) {
+      // Try recorded server first
+      repairServerState(db);
+      const record = readServerState(db);
+      if (record) {
+        targetPort = record.port;
+        targetPids = [record.pid];
+      }
+    }
+
+    if (Number.isNaN(targetPort) || targetPort < 1 || targetPort > 65535) {
       console.error("Error: --port must be a valid port number");
+      if (db) db.close();
       process.exit(1);
     }
-    const result = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`]);
-    const pids = new TextDecoder().decode(result.stdout).trim().split("\n").filter(Boolean);
-    if (pids.length === 0) {
-      console.log(`No process found listening on port ${port}.`);
+
+    // If no recorded pids, fall back to lsof probe on target port
+    if (targetPids.length === 0) {
+      const result = Bun.spawnSync(["lsof", "-ti", `tcp:${targetPort}`]);
+      targetPids = new TextDecoder()
+        .decode(result.stdout)
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((s) => Number(s))
+        .filter((n) => !isNaN(n));
+    }
+
+    if (targetPids.length === 0) {
+      console.log(`No process found listening on port ${targetPort}.`);
+      if (db) db.close();
       return;
     }
-    for (const pid of pids) {
+
+    for (const pid of targetPids) {
       try {
         process.kill(Number(pid), "SIGTERM");
         console.log(`Stopped feinai server (PID ${pid}).`);
@@ -790,6 +827,12 @@ async function cmdServer(args: ParsedArgs): Promise<void> {
         console.error(`Failed to kill PID ${pid}.`);
       }
     }
+
+    // Clear the row after stopping
+    if (db) {
+      clearServerState(db);
+      db.close();
+    }
     return;
   }
 
@@ -799,30 +842,85 @@ async function cmdServer(args: ParsedArgs): Promise<void> {
     process.exit(2);
   }
 
+  const db = ensureDb();
   const host = args.options.host ?? "127.0.0.1";
 
+  // Pre-flight consistency check: repair stale records, reject if valid server exists
+  repairServerState(db);
+  const existing = readServerState(db);
+  if (existing) {
+    console.error(
+      `feinai server is already running for this project at http://127.0.0.1:${existing.port}`,
+    );
+    console.error(`Stop it first with: feinai server --down --port ${existing.port}`);
+    db.close();
+    process.exit(1);
+  }
+
+  // Determine port: if --port is given, use it; otherwise auto-increment from 8272
+  const requestedPort = args.options.port ? Number(args.options.port) : undefined;
+  let resolvedPort: number;
+
+  if (requestedPort !== undefined) {
+    if (isNaN(requestedPort) || requestedPort < 1 || requestedPort > 65535) {
+      console.error("Error: --port must be a valid port number (1-65535)");
+      db.close();
+      process.exit(1);
+    }
+    if (findFreePort(requestedPort) !== requestedPort) {
+      console.error(`Error: port ${requestedPort} is already in use.`);
+      db.close();
+      process.exit(1);
+    }
+    resolvedPort = requestedPort;
+  } else {
+    resolvedPort = findFreePort(8272);
+  }
+
   if (args.flags["daemon"]) {
     // Spawn a detached child WITHOUT starting the server in the parent first.
     const noDaemon = (a: string) => a !== "--daemon" && a !== "-d";
     // In compiled binary argv[1] is a virtual /$bunfs/ path — skip it; user args start at argv[2].
     // In dev mode (bun src/cli.ts) argv[1] is the script path — keep it.
     const isCompiled = process.argv[1]?.startsWith("/$bunfs/");
-    const childArgs = isCompiled
-      ? [process.execPath, ...process.argv.slice(2).filter(noDaemon)]
-      : [process.execPath, ...process.argv.slice(1).filter(noDaemon)];
+    let childArgs: string[];
+    if (isCompiled) {
+      childArgs = [process.execPath, ...process.argv.slice(2).filter(noDaemon)];
+    } else {
+      childArgs = [process.execPath, ...process.argv.slice(1).filter(noDaemon)];
+    }
+    // Pass the resolved port so the child doesn't re-resolve (which could pick a different port)
+    if (!args.options.port) {
+      childArgs.push("--port", String(resolvedPort));
+    }
     const child = Bun.spawn(childArgs, { detached: true, stdio: ["ignore", "ignore", "ignore"] });
     child.unref();
-    console.log(`feinai dashboard → http://${host}:${port}`);
-    console.log(`Stop with: feinai server --down`);
+    console.log(`feinai dashboard → http://${host}:${resolvedPort}`);
+    console.log(`Stop with: feinai server --down --port ${resolvedPort}`);
+    db.close();
     return;
   }
 
   // Lazy import so server.ts and dashboard.ts aren't loaded in non-server CLI invocations.
   const { startServer } = await import("./server");
-  const server = startServer({ port, host });
+  const server = startServer({ port: resolvedPort, host });
+
+  // Write the server state row after successful bind
+  writeServerState(db, resolvedPort, process.pid);
+  db.close();
 
   console.log(`feinai dashboard listening at ${server.url}`);
-  console.log(`Stop with: feinai server --down`);
+  console.log(`Stop with: feinai server --down --port ${resolvedPort}`);
+
+  // Keep process alive until SIGINT
+  process.on("SIGINT", () => {
+    console.log("\nStopping server...");
+    const cleanupDb = ensureDb();
+    clearServerState(cleanupDb);
+    cleanupDb.close();
+    server.stop();
+    process.exit(0);
+  });
 
   // Keep process alive until SIGINT
   process.on("SIGINT", () => {

package/src/dashboard.html

@@ -779,6 +779,7 @@
     let activeTaskStatuses = new Set();
     let activeSpecStatuses = new Set();
     let activeEventFilter = '';
+    let visibleSpecIds = new Set();
     let lastDbEvents = [];
 
     function relativeTime(dateStr) {
@@ -1004,6 +1005,7 @@
 
     function renderSpecs(specs) {
       const filtered = activeSpecStatuses.size > 0 ? specs.filter((s) => activeSpecStatuses.has(s.status)) : specs;
+      visibleSpecIds = new Set(filtered.map(s => s.id));
       $("#specs-count").textContent = filtered.length;
       if (!filtered.length) {
         $("#specs-list").innerHTML = '<div class="empty">no specs match filter</div>';
@@ -1040,7 +1042,14 @@
     }
 
     function renderTasks(tasks) {
-      const filtered = activeTaskStatuses.size > 0 ? tasks.filter((t) => activeTaskStatuses.has(t.status)) : tasks;
+      // Cross-filter: if specs are filtered, only show tasks belonging to visible specs
+      let crossFiltered = tasks;
+      if (activeSpecStatuses.size > 0) {
+        crossFiltered = tasks.filter(t => !t.spec_id || visibleSpecIds.has(t.spec_id));
+      }
+      const filtered = activeTaskStatuses.size > 0
+        ? crossFiltered.filter((t) => activeTaskStatuses.has(t.status))
+        : crossFiltered;
       $("#tasks-count").textContent = filtered.length;
       if (!filtered.length) {
         $("#tasks-list").innerHTML = '<div class="empty">no tasks match filter</div>';

package/src/db.ts

@@ -61,6 +61,14 @@ const SCHEMA_STATEMENTS: string[] = [
     created_at   TEXT NOT NULL DEFAULT (datetime('now'))
   )`,
 
+  `CREATE TABLE IF NOT EXISTS server_state (
+    id          INTEGER PRIMARY KEY CHECK (id = 1),
+    port        INTEGER NOT NULL,
+    pid         INTEGER NOT NULL,
+    started_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+  )`,
+
   `CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)`,
   `CREATE INDEX IF NOT EXISTS idx_tasks_spec_id ON tasks(spec_id)`,
   `CREATE INDEX IF NOT EXISTS idx_tasks_owner ON tasks(owner)`,

package/src/format.ts

@@ -148,12 +148,12 @@ export function formatPlanList(plans: Plan[], format: OutputFormat): string {
 }
 
 export function formatStatus(
-  stats: { pending: number; in_progress: number; completed: number; specs: number; plans: number; serverRunning?: boolean; serverPort?: number },
+  stats: { pending: number; in_progress: number; completed: number; specs: number; plans: number; serverRunning?: boolean; serverPort?: number; serverUrl?: string },
   format: OutputFormat,
 ): string {
   if (format === "json") return JSON.stringify(stats, null, 2);
   const serverLine = stats.serverRunning
-    ? c(format, "green", `server:      running → http://127.0.0.1:${stats.serverPort}`)
+    ? c(format, "green", `server:      running → ${stats.serverUrl ?? `http://127.0.0.1:${stats.serverPort}`}`)
     : c(format, "dim",   `server:      stopped  (feinai server -d to start)`);
   return [
     `${c(format, "yellow", `pending:     ${stats.pending}`)}`,

package/src/server-state.ts

@@ -0,0 +1,180 @@
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import type { DbInstance } from "./db";
+
+export interface ServerState {
+  port: number;
+  pid: number;
+  started_at: string;
+}
+
+/**
+ * Read the single server_state row from the DB.
+ * Returns null if no row exists.
+ */
+export function readServerState(db: DbInstance): ServerState | null {
+  const row = db
+    .prepare("SELECT port, pid, started_at FROM server_state WHERE id = 1")
+    .get() as { port: number; pid: number; started_at: string } | undefined;
+  return row ?? null;
+}
+
+/**
+ * Write (insert or replace) the server_state row.
+ */
+export function writeServerState(db: DbInstance, port: number, pid: number): void {
+  db.run(
+    `INSERT OR REPLACE INTO server_state (id, port, pid, started_at, updated_at)
+     VALUES (1, ?, ?, datetime('now'), datetime('now'))`,
+    port,
+    pid,
+  );
+}
+
+/**
+ * Delete the server_state row.
+ */
+export function clearServerState(db: DbInstance): void {
+  db.run("DELETE FROM server_state WHERE id = 1");
+}
+
+/**
+ * Check whether the given port is in use by any process.
+ * Uses lsof on Linux/macOS.
+ */
+export function isPortInUse(port: number): boolean {
+  try {
+    const result = spawnSync("lsof", ["-ti", `tcp:${port}`]);
+    return result.exitCode === 0 && result.stdout.toString().trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Scan upward from startPort until a free port is found.
+ * Returns the first free port.
+ */
+export function findFreePort(startPort: number): number {
+  let port = startPort;
+  while (isPortInUse(port)) {
+    port++;
+    if (port > startPort + 100) {
+      throw new Error(
+        `No free port found after scanning from ${startPort} to ${port}`,
+      );
+    }
+  }
+  return port;
+}
+
+/**
+ * Return the pid(s) listening on the given port.
+ * Uses lsof -ti tcp:${port} and parses the output.
+ * Returns an array of pids, empty if none.
+ */
+function pidsOnPort(port: number): number[] {
+  try {
+    const result = spawnSync("lsof", ["-ti", `tcp:${port}`]);
+    if (result.exitCode !== 0) return [];
+    const out = result.stdout.toString().trim();
+    if (!out) return [];
+    return out
+      .split("\n")
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => !isNaN(n));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if a specific pid is running.
+ * Uses kill(pid, 0) via /proc on Linux or kill command.
+ */
+function isPidRunning(pid: number): boolean {
+  try {
+    // kill(pid, 0) checks if the process exists without sending a signal
+    return process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the port that a specific pid is listening on.
+ * Returns the port number or null if the pid has no tcp listeners.
+ */
+function portOfPid(pid: number): number | null {
+  try {
+    const result = spawnSync("lsof", ["-iTCP", "-sTCP:LISTEN", "-P", "-n", "-p", String(pid)]);
+    if (result.exitCode !== 0) return null;
+    // Parse lsof output: find "TCP *:{port}" pattern
+    const out = result.stdout.toString();
+    const match = out.match(/TCP\s+\*:(\d+)/);
+    if (match) return parseInt(match[1]!, 10);
+    // Alternate format: "LISTEN" followed by port
+    const altMatch = out.match(/:(\d+)\s.*LISTEN/);
+    if (altMatch) return parseInt(altMatch[1]!, 10);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate the server_state row for consistency.
+ *
+ * A row is considered valid only when:
+ * - The stored pid is running AND
+ * - That pid is listening on the stored port
+ *
+ * If the row is stale (in any way), it is deleted and false is returned.
+ *
+ * Returns { valid: boolean, record: ServerState | null }
+ */
+export function validateServerState(db: DbInstance): {
+  valid: boolean;
+  record: ServerState | null;
+} {
+  const record = readServerState(db);
+  if (!record) return { valid: false, record: null };
+
+  // Check if stored pid is running
+  if (!isPidRunning(record.pid)) {
+    clearServerState(db);
+    return { valid: false, record: null };
+  }
+
+  // Check what pids are listening on the stored port
+  const pids = pidsOnPort(record.port);
+  if (pids.length === 0) {
+    // Port has no listener at all
+    clearServerState(db);
+    return { valid: false, record: null };
+  }
+  if (!pids.includes(record.pid)) {
+    // Port is busy but by a different pid
+    clearServerState(db);
+    return { valid: false, record: null };
+  }
+
+  // Check that the stored pid is listening on the stored port specifically
+  const actualPort = portOfPid(record.pid);
+  if (actualPort !== null && actualPort !== record.port) {
+    // The pid is running but listening on a different port
+    clearServerState(db);
+    return { valid: false, record: null };
+  }
+
+  return { valid: true, record };
+}
+
+/**
+ * Repair the server_state row: validate consistency, delete if stale.
+ * Returns the valid record or null if stale/missing.
+ */
+export function repairServerState(db: DbInstance): ServerState | null {
+  const { valid, record } = validateServerState(db);
+  return valid ? record : null;
+}

package/src/server.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { dirname, basename, resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { openDb, findDbPath, type DbInstance } from "./db";
+import { clearServerState } from "./server-state";
 import {
   listTasks,
   getTask,
@@ -630,7 +631,18 @@ export function startServer(opts: ServerOptions): { url: string; stop: () => voi
 
   return {
     url: `http://${server.hostname}:${server.port}`,
-    stop: () => server.stop(),
+    stop: () => {
+      // Clear the server_state row on graceful shutdown
+      try {
+        const db = openDb();
+        clearServerState(db);
+        db.close();
+      } catch {
+        // DB might not exist or be inaccessible; ignore to avoid masking
+        // the actual server stop.
+      }
+      server.stop();
+    },
   };
 }