@agent-plan/server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @agent-plan/server
+
+Local HTTP/WebSocket server for Agent Plan.
+
+Used by the dashboard and adapters to expose planner state over web APIs.
+
+See the repository root README for full documentation:
+https://github.com/ovidius72/agent-planner#readme

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+import { serve } from "./serve.js";
+const plannerRoot = resolve(process.cwd(), ".planner");
+const planRoot = process.env.PLAN_ROOT ?? plannerRoot;
+const port = parseInt(process.env.PLAN_PORT ?? "3030", 10);
+const host = process.env.PLAN_HOST ?? "127.0.0.1";
+serve({ port, planRoot, host })
+    .then(({ url }) => {
+    console.log(`[plan-server] running at ${url}`);
+    console.log(`[plan-server] plan root: ${planRoot}`);
+})
+    .catch((err) => {
+    console.error("[plan-server] failed:", err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { serve } from "./serve.js";
+export { WsHub } from "./ws-hub.js";
+export type { ServeOptions, ServeHandle, UiConfig, ShortcutConfigSpec } from "./serve.js";
+export type { WsEvent } from "./ws-hub.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { serve } from "./serve.js";
+export { WsHub } from "./ws-hub.js";

package/dist/serve.d.ts

@@ -0,0 +1,40 @@
+import { WsHub } from "./ws-hub.js";
+export interface ShortcutConfigSpec {
+    key: string;
+    primary?: boolean;
+    meta?: boolean;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+}
+export interface ServerUiConfig {
+    mode: "local" | "lan";
+    bindHost: string;
+    port: number;
+    localUrl: string;
+    lanUrl?: string | undefined;
+}
+export interface UiConfig {
+    shortcuts?: Partial<Record<"create" | "edit" | "delete" | "submit", ShortcutConfigSpec>>;
+    server?: ServerUiConfig | undefined;
+}
+export interface ServeOptions {
+    port?: number;
+    planRoot: string;
+    host?: string | undefined;
+    staticDir?: string | undefined;
+    quiet?: boolean;
+    uiConfig?: UiConfig | undefined;
+    isBusy?: (() => boolean) | undefined;
+}
+export interface ServeHandle {
+    url: string;
+    localUrl: string;
+    lanUrl?: string | undefined;
+    mode: "local" | "lan";
+    bindHost: string;
+    hub: WsHub;
+    close: () => Promise<void>;
+}
+export declare function serve(options: ServeOptions): Promise<ServeHandle>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAiHpC,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACzF,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACrC;AAonBD,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,KAAK,CAAC;IACX,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA0EvE"}

package/dist/serve.js

@@ -0,0 +1,755 @@
+import { watch, existsSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { networkInterfaces } from "node:os";
+import { createAdaptorServer } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { ExportService, PlanStore, PlanStoreError, createFeatureId, createPhaseId, createTaskId, normalizeSlug, withFeatureLock, needsMotivation } from "@agent-plan/core";
+import { WsHub } from "./ws-hub.js";
+// ─── Watcher ────────────────────────────────────────────────────────────
+let watcherAbort = null;
+let watcherHubRef = { current: null };
+function nowISO() {
+    return new Date().toISOString();
+}
+function nextTaskNumber(phase) {
+    const numbers = phase.tasks.map((task) => task.number || 0).filter((n) => Number.isFinite(n));
+    return (numbers.length > 0 ? Math.max(...numbers) : 0) + 1;
+}
+function isPrivateIpv4(address) {
+    return /^10\./.test(address) || /^192\.168\./.test(address) || /^172\.(1[6-9]|2\d|3[01])\./.test(address);
+}
+function detectLanIp() {
+    const nets = networkInterfaces();
+    let fallback;
+    for (const entries of Object.values(nets)) {
+        for (const entry of entries ?? []) {
+            if (entry.family !== "IPv4" || entry.internal)
+                continue;
+            if (isPrivateIpv4(entry.address))
+                return entry.address;
+            fallback ??= entry.address;
+        }
+    }
+    return fallback;
+}
+function buildServerUrls(port, host) {
+    const localUrl = `http://127.0.0.1:${port}`;
+    if (host === "0.0.0.0") {
+        const lanIp = detectLanIp();
+        return {
+            mode: "lan",
+            bindHost: host,
+            localUrl,
+            lanUrl: lanIp ? `http://${lanIp}:${port}` : undefined,
+        };
+    }
+    return { mode: "local", bindHost: host, localUrl, lanUrl: undefined };
+}
+function requiresGovernance(status) {
+    return status === "in-progress" || status === "done" || status === "blocked";
+}
+function entersGovernedState(previousStatus, nextStatus) {
+    return requiresGovernance(nextStatus) && !requiresGovernance(previousStatus);
+}
+function featureGovernanceReady(feature) {
+    return Boolean(feature.discussedAt || (feature.contextReady && feature.contextReadyReason.trim()));
+}
+function phaseGovernanceReady(phase) {
+    return Boolean(phase.discussedAt || (phase.contextReady && phase.contextReadyReason.trim()));
+}
+function applyTaskLifecycleDates(task, nextStatus, now) {
+    const previousStatus = task.status;
+    if (nextStatus === "in-progress" && !task.startedAt) {
+        task.startedAt = now;
+    }
+    if (nextStatus === "done") {
+        if (!task.startedAt)
+            task.startedAt = now;
+        task.completedAt = now;
+    }
+    else if (previousStatus === "done") {
+        task.completedAt = "";
+    }
+    task.status = nextStatus;
+    return task;
+}
+function startWatcher(planRoot, hubRef) {
+    stopWatcher();
+    if (!existsSync(planRoot))
+        return;
+    const ac = new AbortController();
+    watcherAbort = ac;
+    watcherHubRef = hubRef;
+    try {
+        watch(planRoot, { recursive: true, signal: ac.signal }, (_event, filename) => {
+            if (filename && !filename.includes(".tmp.")) {
+                hubRef.current?.broadcast({ type: "file-changed", data: { filename } });
+            }
+        });
+    }
+    catch {
+        // recursive watch may fail on some systems
+    }
+}
+function stopWatcher() {
+    watcherAbort?.abort();
+    watcherAbort = null;
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+async function propagateTaskStatus(phaseId) {
+    // This is now handled by PlanStore.syncStatuses()
+}
+async function propagatePhaseStatus(featureId) {
+    // This is now handled by PlanStore.syncStatuses()
+}
+function createApiApp(store, hubRef, apiPrefix = "", uiConfig, isBusy) {
+    const hub = () => hubRef.current;
+    const route = (path) => `${apiPrefix}${path}`;
+    const app = new Hono();
+    // Global error handler: never let an unhandled exception (e.g. a missing
+    // phase file -> PlanStoreError/ENOENT) bubble up to the host process console
+    // (the agent session). Convert it to a clean HTTP response instead.
+    app.onError((err, c) => {
+        const isStoreRead = err instanceof PlanStoreError || /ENOENT|read failed/i.test(err.message);
+        if (isStoreRead) {
+            return c.json({ error: "not found", message: err.message }, 404);
+        }
+        return c.json({ error: "internal", message: err instanceof Error ? err.message : String(err) }, 500);
+    });
+    app.use("*", cors({ origin: "*", allowHeaders: ["Content-Type"] }));
+    // Internal notify endpoint: lets adapter tools running in ANOTHER process
+    // (where they don't have the WsHub reference) force a live-update broadcast.
+    // Registered BEFORE the busy middleware so it always responds (a notify ping
+    // must never be blocked by a busy window, otherwise live updates are lost).
+    app.post(route("/internal/notify"), (c) => {
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        hub()?.broadcast({ type: "file-changed", data: { filename: "external-notify" } });
+        return c.json({ ok: true });
+    });
+    // While the agent is mutating .planner/ files, avoid serving possibly-inconsistent data.
+    // GET requests get a 503 busy signal the UI retries; mutations are rejected.
+    app.use("*", async (c, next) => {
+        if (isBusy?.()) {
+            const isRead = c.req.method === "GET" || c.req.method === "HEAD";
+            return c.json({ error: "plan-busy", busy: true, message: "Plan files are being updated by the agent. Please retry shortly." }, isRead ? 503 : 409);
+        }
+        await next();
+    });
+    // ── Project ──────────────────────────────────────────────────────
+    app.get(route("/export"), async (c) => {
+        const full = c.req.query("full") === "true";
+        const exportService = new ExportService();
+        const plan = await store.loadAll();
+        const markdown = exportService.exportToMarkdown(plan, full);
+        // Save to disk
+        await writeFile(join(store.root, "EXPORT.md"), markdown, "utf-8");
+        return c.json({ markdown, filePath: "EXPORT.md" });
+    });
+    app.get(route("/project"), async (c) => {
+        const project = await store.loadProject();
+        return c.json({
+            ...project,
+            planRoot: store.root,
+            projectRoot: dirname(store.root),
+        });
+    });
+    app.put(route("/project"), async (c) => {
+        const body = await c.req.json();
+        await store.updateProject(() => body);
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "project-updated", data: body });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        return c.json(body);
+    });
+    // ── Requirements ─────────────────────────────────────────────────
+    app.get(route("/requirements"), async (c) => c.json(await store.loadRequirements()));
+    app.post(route("/requirements"), async (c) => {
+        const body = await c.req.json();
+        const reqs = await store.updateRequirements((doc) => { doc.requirements.push(body); return doc; });
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "requirements-updated", data: reqs });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        return c.json(body, 201);
+    });
+    app.put(route("/requirements/:id"), async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json();
+        let found = false;
+        const reqs = await store.updateRequirements((doc) => {
+            const idx = doc.requirements.findIndex((r) => r.id === id);
+            if (idx === -1)
+                return doc;
+            doc.requirements[idx] = body;
+            found = true;
+            return doc;
+        });
+        if (!found)
+            return c.json({ error: "not found" }, 404);
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "requirements-updated", data: reqs });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        return c.json(body);
+    });
+    // ── Features ─────────────────────────────────────────────────────
+    app.get(route("/features"), async (c) => c.json((await store.loadFeatures()).features));
+    app.post(route("/features"), async (c) => {
+        const body = await c.req.json();
+        const name = body.name?.trim();
+        if (!name)
+            return c.json({ error: "name required" }, 400);
+        const features = await store.loadFeatures();
+        const number = features.features.length + 1;
+        const now = nowISO();
+        const feature = {
+            id: createFeatureId(),
+            number,
+            name,
+            description: body.description ?? "",
+            status: "planned",
+            discussedAt: "",
+            contextReady: false,
+            contextReadyReason: "",
+            startDate: "",
+            endDate: "",
+            workDone: "",
+            workRemaining: "",
+            acceptedDecisions: [],
+            phaseIds: [], dependsOn: [],
+            createdAt: now,
+            updatedAt: now,
+        };
+        features.features.push(feature);
+        await store.updateFeatures((doc) => { doc.features.push(feature); return doc; });
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "features-updated", data: { action: "created", id: feature.id, featureId: feature.id } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.syncStatuses();
+        await store.appendActivity("feature_created", feature.id, `Feature created: ${feature.name}`);
+        return c.json(feature, 201);
+    });
+    app.get(route("/features/:id"), async (c) => {
+        const id = c.req.param("id");
+        const features = await store.loadFeatures();
+        const feature = features.features.find((f) => f.id === id);
+        if (!feature)
+            return c.json({ error: "not found" }, 404);
+        return c.json(feature);
+    });
+    app.put(route("/features/:id"), async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json();
+        if (body.id !== id)
+            return c.json({ error: "id mismatch" }, 400);
+        const features = await store.loadFeatures();
+        const idx = features.features.findIndex((f) => f.id === id);
+        if (idx === -1)
+            return c.json({ error: "not found" }, 404);
+        if (entersGovernedState(features.features[idx]?.status, body.status) && !featureGovernanceReady(body)) {
+            return c.json({ error: "feature governance required: discuss the feature first, or set contextReady=true with a reason before starting work." }, 400);
+        }
+        await store.updateFeatures((doc) => {
+            const i = doc.features.findIndex((f) => f.id === id);
+            if (i !== -1)
+                doc.features[i] = body;
+            return doc;
+        });
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "features-updated", data: { action: "updated", id, featureId: id } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.syncStatuses();
+        return c.json(body);
+    });
+    app.delete(route("/features/:id"), async (c) => {
+        const id = c.req.param("id");
+        await store.updateFeatures((doc) => {
+            doc.features = doc.features.filter((f) => f.id !== id);
+            return doc;
+        });
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "features-updated", data: { action: "deleted", id, featureId: id } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.syncStatuses();
+        return c.json({ deleted: id });
+    });
+    // ── Phases ───────────────────────────────────────────────────────
+    app.get(route("/phases"), async (c) => {
+        const allPhases = await store.loadAllPhases();
+        const featureId = c.req.query("featureId");
+        if (featureId)
+            return c.json(allPhases.filter((p) => p.featureId === featureId));
+        return c.json(allPhases);
+    });
+    app.post(route("/phases"), async (c) => {
+        const body = await c.req.json();
+        // Backward-compatible: accept a full Phase object, or generate one from title.
+        if (body.id && body.slug && body.number && body.tasks && body.taskIds) {
+            const full = body;
+            if (requiresGovernance(full.status) && !phaseGovernanceReady(full)) {
+                return c.json({ error: "phase governance required: discuss the phase first, or set contextReady=true with a reason before starting work." }, 400);
+            }
+            await store.updatePhase(full.id, () => full);
+            await store.writeGenerated();
+            hub()?.broadcast({ type: "phases-updated", data: { action: "created", id: full.id, phaseId: full.id, featureId: full.featureId ?? "" } });
+            hub()?.broadcast({ type: "plan-rendered", data: {} });
+            return c.json(full, 201);
+        }
+        const title = body.title?.trim();
+        if (!title)
+            return c.json({ error: "title required" }, 400);
+        const featureId = body.featureId?.trim();
+        if (!featureId)
+            return c.json({ error: "featureId required: a phase must belong to a feature" }, 400);
+        let phase;
+        await withFeatureLock(featureId, async () => {
+            const allPhases = await store.loadAllPhases();
+            const number = allPhases.filter((p) => p.featureId === featureId).length + 1;
+            const slug = normalizeSlug(title);
+            const now = nowISO();
+            phase = {
+                id: createPhaseId(),
+                featureId,
+                number,
+                slug,
+                title,
+                status: "draft",
+                discussedAt: "",
+                contextReady: false,
+                contextReadyReason: "",
+                summary: body.summary ?? "",
+                description: body.description ?? "",
+                notes: "",
+                goals: [],
+                nonGoals: [],
+                dependencies: [],
+                risks: [],
+                openQuestions: [],
+                completionCriteria: [],
+                decisions: [],
+                acceptedDecisions: [],
+                taskIds: [],
+                tasks: [],
+                dependsOn: [],
+                createdAt: now,
+                updatedAt: now,
+            };
+            await store.savePhase(phase);
+            // Link to feature if featureId provided
+            if (body.featureId) {
+                await store.updateFeatures((features) => {
+                    const feature = features.features.find((f) => f.id === body.featureId);
+                    if (feature && !feature.phaseIds.includes(phase.id)) {
+                        feature.phaseIds.push(phase.id);
+                    }
+                    return features;
+                });
+                hub()?.broadcast({ type: "features-updated", data: { action: "updated", id: body.featureId, featureId: body.featureId } });
+            }
+            await store.writeGenerated();
+        });
+        if (!phase)
+            return c.json({ error: "phase creation failed" }, 500);
+        hub()?.broadcast({ type: "phases-updated", data: { action: "created", id: phase.id, phaseId: phase.id, featureId: phase.featureId ?? "" } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.syncStatuses();
+        return c.json(phase, 201);
+    });
+    app.get(route("/phases/:id"), async (c) => {
+        const id = c.req.param("id");
+        if (!id)
+            return c.json({ error: "id required" }, 400);
+        try {
+            return c.json(await store.loadPhase(id));
+        }
+        catch {
+            return c.json({ error: "phase not found" }, 404);
+        }
+    });
+    app.put(route("/phases/:id"), async (c) => {
+        const id = c.req.param("id");
+        const body = await c.req.json();
+        if (body.id !== id)
+            return c.json({ error: "id mismatch" }, 400);
+        const existingPhase = await store.loadPhase(id).catch(() => null);
+        if (!existingPhase)
+            return c.json({ error: "phase not found" }, 404);
+        if (entersGovernedState(existingPhase.status, body.status) && !phaseGovernanceReady(body)) {
+            return c.json({ error: "phase governance required: discuss the phase first, or set contextReady=true with a reason before starting work." }, 400);
+        }
+        await store.updatePhase(id, () => body);
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "phases-updated", data: { action: "updated", id, phaseId: id, featureId: body.featureId ?? "" } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        // Propagate status up
+        await store.syncStatuses();
+        await store.appendActivity("phase_updated", id, `Phase updated: ${body.title} (${body.status})`);
+        return c.json(body);
+    });
+    app.delete(route("/phases/:id"), async (c) => {
+        const id = c.req.param("id");
+        if (!id)
+            return c.json({ error: "id required" }, 400);
+        const existing = await store.loadPhase(id).catch(() => null);
+        if (!existing)
+            return c.json({ error: "phase not found" }, 404);
+        await store.deletePhase(id);
+        if (existing.featureId) {
+            await store.updateFeatures((features) => {
+                const feature = features.features.find((f) => f.id === existing.featureId);
+                if (feature)
+                    feature.phaseIds = feature.phaseIds.filter((pid) => pid !== id);
+                return features;
+            });
+        }
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "phases-updated", data: { action: "deleted", id, phaseId: id, featureId: existing.featureId ?? "" } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.syncStatuses();
+        await store.appendActivity("phase_deleted", id ?? "", `Phase deleted: ${id}`);
+        return c.json({ deleted: id });
+    });
+    app.post(route("/phases/:phaseId/tasks"), async (c) => {
+        const phaseId = c.req.param("phaseId");
+        if (!phaseId)
+            return c.json({ error: "phaseId required" }, 400);
+        const body = await c.req.json();
+        const title = body.title?.trim();
+        if (!title)
+            return c.json({ error: "title required" }, 400);
+        const phase = await store.loadPhase(phaseId).catch(() => null);
+        if (!phase)
+            return c.json({ error: "phase not found" }, 404);
+        if (requiresGovernance(body.status) && phase.featureId) {
+            const features = await store.loadFeatures();
+            const feature = features.features.find((entry) => entry.id === phase.featureId);
+            if (feature && !featureGovernanceReady(feature)) {
+                return c.json({ error: "feature governance required before starting task work: discuss the feature first, or set contextReady=true with a reason." }, 400);
+            }
+        }
+        const now = nowISO();
+        const taskNumber = nextTaskNumber(phase);
+        const shortName = normalizeSlug(title).trim() || `task-${Date.now().toString(36)}`;
+        const initialStatus = body.status ?? "planned";
+        const task = {
+            id: createTaskId(),
+            phaseId: phase.id,
+            number: taskNumber,
+            shortName,
+            title,
+            status: initialStatus,
+            description: body.description ?? "",
+            notes: "",
+            statusLog: [],
+            decisions: [],
+            acceptedDecisions: [],
+            checklist: [],
+            subtasks: [],
+            dependsOn: [],
+            startedAt: initialStatus === "in-progress" || initialStatus === "done" ? now : "",
+            completedAt: initialStatus === "done" ? now : "",
+            createdAt: now,
+            updatedAt: now,
+        };
+        // Atomic: serialize concurrent task-create on the same phase file.
+        await store.updatePhase(phase.id, (p) => {
+            p.tasks.push(task);
+            p.taskIds.push(task.id);
+            p.updatedAt = now;
+            return p;
+        });
+        await store.writeGenerated();
+        await store.syncTaskStatusRollup(phase.id);
+        hub()?.broadcast({ type: "phases-updated", data: { action: "task-created", id: phase.id, phaseId: phase.id, featureId: phase.featureId ?? "", taskId: task.id } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.appendActivity("task_created", task.id, `Task created: ${task.title} (phase ${phaseId})`);
+        // Build a human-readable composite label so agents echo this instead of the UUID.
+        const featuresDoc = await store.loadFeatures();
+        const featureNum = phase.featureId ? (featuresDoc.features.find((f) => f.id === phase.featureId)?.number ?? 0) : 0;
+        const seq = (n) => String(n && n > 0 ? n : 0).padStart(3, "0");
+        const label = `T${seq(task.number)}(P${seq(phase.number)}/F${seq(featureNum)}) - ${task.title}`;
+        return c.json({ ...task, label }, 201);
+    });
+    // ── Tasks ─────────────────────────────────────────────────────────
+    app.get(route("/tasks/active"), async (c) => {
+        const [phases, featuresDoc] = await Promise.all([store.loadAllPhases(), store.loadFeatures()]);
+        // Build lookups for IDs and numbers
+        const phaseToFeature = new Map();
+        const featureIdToNum = new Map();
+        for (const feature of featuresDoc.features) {
+            featureIdToNum.set(feature.id, feature.number);
+            for (const phaseId of feature.phaseIds) {
+                if (!phaseToFeature.has(phaseId))
+                    phaseToFeature.set(phaseId, feature.id);
+            }
+        }
+        const activeTasksMap = new Map();
+        for (const phase of phases) {
+            for (const task of phase.tasks) {
+                if (task.status === "in-progress") {
+                    const featureId = phase.featureId ?? phaseToFeature.get(phase.id);
+                    if (!featureId)
+                        continue; // Skip tasks without a valid feature link to avoid 404s
+                    activeTasksMap.set(task.id, {
+                        id: task.id,
+                        number: task.number,
+                        title: task.title,
+                        phaseId: phase.id,
+                        phaseNumber: phase.number,
+                        featureId,
+                        featureNumber: featureIdToNum.get(featureId) ?? 0,
+                        status: task.status,
+                    });
+                }
+            }
+        }
+        return c.json(Array.from(activeTasksMap.values()));
+    });
+    app.get(route("/tasks/:id"), async (c) => {
+        const taskId = c.req.param("id");
+        const phases = await store.loadAllPhases();
+        for (const phase of phases) {
+            const task = phase.tasks.find((t) => t.id === taskId);
+            if (task)
+                return c.json(task);
+        }
+        return c.json({ error: "task not found" }, 404);
+    });
+    app.put(route("/tasks/:id"), async (c) => {
+        const taskId = c.req.param("id");
+        const body = await c.req.json();
+        if (!body.phaseId)
+            return c.json({ error: "phaseId required" }, 400);
+        const phase = await store.loadPhase(body.phaseId).catch(() => null);
+        if (!phase)
+            return c.json({ error: "phase not found" }, 404);
+        const existing = phase.tasks.find((t) => t.id === taskId);
+        if (!existing)
+            return c.json({ error: "task not found" }, 404);
+        // Validate motivation requirement for status transitions.
+        if (body.status && body.status !== existing.status && needsMotivation(existing.status, body.status)) {
+            if (!body.motivation || !body.motivation.trim()) {
+                return c.json({ error: `Status transition "${existing.status} → ${body.status}" requires a motivation. Provide the "motivation" field with a detailed explanation.` }, 400);
+            }
+        }
+        if (entersGovernedState(existing.status, body.status) && phase.featureId) {
+            const features = await store.loadFeatures();
+            const feature = features.features.find((entry) => entry.id === phase.featureId);
+            if (feature && !featureGovernanceReady(feature)) {
+                return c.json({ error: "feature governance required before starting task work: discuss the feature first, or set contextReady=true with a reason." }, 400);
+            }
+        }
+        // NOTE: checklist completeness is advisory for the AI agent (enforced via
+        // prompt rules), not a hard API gate. The web UI is for the human
+        // supervisor, who may close a task regardless of checklist state.
+        const now = nowISO();
+        const updated = {
+            ...existing,
+            ...body,
+            id: taskId,
+            phaseId: existing.phaseId,
+            shortName: existing.shortName,
+            createdAt: existing.createdAt,
+            startedAt: existing.startedAt,
+            completedAt: existing.completedAt,
+            updatedAt: now,
+        };
+        if (body.status) {
+            applyTaskLifecycleDates(updated, body.status, now);
+        }
+        // Record status change in the incremental statusLog.
+        if (body.status && body.status !== existing.status) {
+            const entry = {
+                id: createTaskId(),
+                date: now,
+                fromStatus: existing.status,
+                toStatus: body.status,
+                title: body.motivation?.split("\n")[0]?.trim() || `${existing.status} → ${body.status}`,
+                description: body.motivation?.trim() || "",
+            };
+            updated.statusLog = [...(existing.statusLog ?? []), entry];
+        }
+        const tIdx = phase.tasks.findIndex((t) => t.id === taskId);
+        phase.tasks[tIdx] = updated;
+        phase.updatedAt = updated.updatedAt;
+        // Atomic: serialize concurrent task updates on the same phase.
+        await store.updatePhase(phase.id, (p) => {
+            const i = p.tasks.findIndex((t) => t.id === taskId);
+            if (i !== -1)
+                p.tasks[i] = updated;
+            p.updatedAt = updated.updatedAt;
+            return p;
+        });
+        await store.writeGenerated();
+        await store.syncTaskStatusRollup(phase.id);
+        hub()?.broadcast({ type: "phases-updated", data: { action: "task-updated", id: body.phaseId, phaseId: body.phaseId, featureId: phase.featureId ?? "", taskId } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        // Propagate status up
+        if (body.status && body.status !== existing.status) {
+            await store.appendActivity("task_status", taskId ?? "", `Task ${taskId} → ${body.status}`);
+        }
+        else {
+            await store.appendActivity("task_updated", taskId ?? "", `Task updated: ${updated.title}`);
+        }
+        return c.json(updated);
+    });
+    app.delete(route("/tasks/:id"), async (c) => {
+        const taskId = c.req.param("id");
+        const phases = await store.loadAllPhases();
+        const hostPhase = phases.find((entry) => entry.tasks.some((task) => task.id === taskId));
+        if (!hostPhase)
+            return c.json({ error: "task not found" }, 404);
+        const existingTask = hostPhase.tasks.find((task) => task.id === taskId);
+        await store.updatePhase(hostPhase.id, (p) => {
+            p.tasks = p.tasks.filter((task) => task.id !== taskId);
+            p.taskIds = p.taskIds.filter((id) => id !== taskId);
+            p.updatedAt = nowISO();
+            return p;
+        });
+        await store.writeGenerated();
+        hub()?.broadcast({ type: "phases-updated", data: { action: "task-deleted", id: hostPhase.id, phaseId: hostPhase.id, featureId: hostPhase.featureId ?? "", taskId: existingTask?.id ?? taskId } });
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        await store.syncStatuses();
+        await store.appendActivity("task_deleted", taskId ?? "", `Task deleted: ${taskId}`);
+        return c.json({ deleted: taskId });
+    });
+    // ── Integrity / Repair ────────────────────────────────────────
+    app.get(route("/integrity"), async (c) => {
+        const integrity = await store.validateIntegrity();
+        return c.json(integrity);
+    });
+    app.post(route("/repair"), async (c) => {
+        const report = await store.repair();
+        hub()?.broadcast({ type: "plan-rendered", data: {} });
+        hub()?.broadcast({ type: "features-updated", data: { action: "repaired" } });
+        hub()?.broadcast({ type: "phases-updated", data: { action: "repaired" } });
+        return c.json(report);
+    });
+    // ── Render ───────────────────────────────────────────────────────
+    app.post(route("/render"), async (c) => {
+        const files = await store.writeGenerated();
+        hub()?.broadcast({ type: "plan-rendered", data: { files } });
+        return c.json({ files });
+    });
+    // ── Handoff ──────────────────────────────────────────────────────
+    app.get(route("/handoff"), async (c) => {
+        const handoff = await store.loadHandoff();
+        return c.json({
+            exists: Boolean(handoff),
+            content: handoff?.content ?? "",
+            createdAt: handoff?.createdAt ?? "",
+            updatedAt: handoff?.updatedAt ?? "",
+        });
+    });
+    app.delete(route("/handoff"), async (c) => {
+        await store.deleteHandoff();
+        return c.json({ deleted: true });
+    });
+    // ── Health ───────────────────────────────────────────────────────
+    app.get(route("/health"), (c) => c.json({ status: "ok", root: store.root }));
+    app.get(route("/ui-config"), (c) => c.json(uiConfig ?? {}));
+    return app;
+}
+// ─── Serve static files (SPA) ────────────────────────────────────────────
+function createSpaApp(store, hubRef, staticDir, uiConfig, isBusy) {
+    const app = createApiApp(store, hubRef, staticDir ? "/api" : "", uiConfig, isBusy);
+    if (!staticDir) {
+        return app;
+    }
+    // Serve the built React app for all unmatched GET routes
+    app.all("*", async (c) => {
+        if (c.req.method !== "GET")
+            return c.json({ error: "not found" }, 404);
+        // Try exact file first
+        const filePath = join(staticDir, c.req.path === "/" ? "index.html" : c.req.path.slice(1));
+        try {
+            const content = readFileSync(filePath);
+            const ext = filePath.split(".").pop() ?? "";
+            const mime = {
+                html: "text/html",
+                js: "application/javascript",
+                css: "text/css",
+                png: "image/png",
+                svg: "image/svg+xml",
+                json: "application/json",
+            };
+            return new Response(content, { status: 200, headers: { "Content-Type": mime[ext] ?? "application/octet-stream" } });
+        }
+        catch {
+            // SPA fallback: serve index.html for any unmatched path
+            try {
+                const indexContent = readFileSync(join(staticDir, "index.html"));
+                return new Response(indexContent, { status: 200, headers: { "Content-Type": "text/html" } });
+            }
+            catch {
+                return c.json({ error: "not found" }, 404);
+            }
+        }
+    });
+    return app;
+}
+export async function serve(options) {
+    const { port = 3030, planRoot, host = "127.0.0.1" } = options;
+    const store = new PlanStore(planRoot);
+    const runtimeUiConfig = { ...(options.uiConfig ?? {}) };
+    if (!(await store.exists())) {
+        throw new Error(`.planner/ not found at: ${planRoot}. Run plan-init first.`);
+    }
+    // Self-heal stale/legacy persisted statuses before the UI reads them.
+    await store.syncStatuses();
+    // Shared mutable reference — routes see the hub after it's created
+    const hubRef = { current: null };
+    const app = createSpaApp(store, hubRef, options.staticDir, runtimeUiConfig, options.isBusy);
+    return new Promise((resolve, reject) => {
+        // Create the Node HTTP server without listening yet
+        const server = createAdaptorServer({ fetch: app.fetch, hostname: host });
+        // Attach WebSocket hub to the underlying HTTP server
+        const hub = new WsHub(server, options.quiet, (err) => reject(err));
+        hubRef.current = hub; // Now routes can use it
+        // Critical: if listen() fails (e.g. EADDRINUSE), Node emits an 'error' event.
+        // Without a listener this becomes an uncaughtException that crashes Pi.
+        // Reject the promise so callers' .catch() can handle it.
+        server.on("error", (err) => {
+            reject(err);
+        });
+        server.listen(port, host, () => {
+            // When port=0 (random), resolve the actually assigned port from the server address.
+            const actualPort = (() => {
+                try {
+                    const addr = server.address();
+                    if (addr && typeof addr === "object" && addr.port)
+                        return addr.port;
+                }
+                catch { }
+                return port;
+            })();
+            const serverUrls = buildServerUrls(actualPort, host);
+            runtimeUiConfig.server = { ...serverUrls, port: actualPort };
+            const { localUrl, lanUrl } = serverUrls;
+            if (!options.quiet) {
+                console.log(`[plan-server] listening at ${localUrl}`);
+                console.log(`[plan-server] ws endpoint: ws://127.0.0.1:${actualPort}/ws`);
+                if (lanUrl)
+                    console.log(`[plan-server] lan url: ${lanUrl}`);
+            }
+            startWatcher(planRoot, hubRef);
+            resolve({
+                url: localUrl,
+                localUrl,
+                lanUrl,
+                mode: serverUrls.mode,
+                bindHost: serverUrls.bindHost,
+                hub,
+                close: async () => {
+                    stopWatcher();
+                    hub.close();
+                    // Force-close any lingering sockets (browser WebSocket / keep-alive),
+                    // otherwise server.close() hangs until the kernel times them out.
+                    const anyServer = server;
+                    anyServer.closeAllConnections?.();
+                    await new Promise((r) => anyServer.close(() => r()));
+                },
+            });
+        });
+    });
+}

package/dist/ws-hub.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WebSocket Hub — bidirectional real-time sync for plan changes.
+ *
+ * After the HTTP server starts, attach a WsHub to it.
+ * All plan mutations broadcast events so connected clients stay in sync.
+ */
+import type { Server } from "node:http";
+export type WsEvent = {
+    type: "file-changed";
+    data: {
+        filename: string;
+    };
+} | {
+    type: "project-updated";
+    data: unknown;
+} | {
+    type: "requirements-updated";
+    data: unknown;
+} | {
+    type: "features-updated";
+    data: unknown;
+} | {
+    type: "phases-updated";
+    data: unknown;
+} | {
+    type: "plan-rendered";
+    data: unknown;
+};
+export declare class WsHub {
+    private wss;
+    private clients;
+    private quiet;
+    constructor(server: Server, quiet?: boolean, onError?: (err: Error) => void);
+    broadcast(event: WsEvent): void;
+    close(): void;
+}
+//# sourceMappingURL=ws-hub.d.ts.map

package/dist/ws-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-hub.d.ts","sourceRoot":"","sources":["../src/ws-hub.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7C,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAAU;gBAEX,MAAM,EAAE,MAAM,EAAE,KAAK,UAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI;IA0CzE,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAa/B,KAAK,IAAI,IAAI;CASd"}

package/dist/ws-hub.js

@@ -0,0 +1,77 @@
+/**
+ * WebSocket Hub — bidirectional real-time sync for plan changes.
+ *
+ * After the HTTP server starts, attach a WsHub to it.
+ * All plan mutations broadcast events so connected clients stay in sync.
+ */
+import { WebSocketServer, WebSocket } from "ws";
+export class WsHub {
+    wss;
+    clients = new Set();
+    quiet;
+    constructor(server, quiet = false, onError) {
+        this.quiet = quiet;
+        this.wss = new WebSocketServer({ server, path: "/ws" });
+        // Critical: if the underlying HTTP server fails to listen (e.g. EADDRINUSE),
+        // the WebSocketServer also emits 'error'. Without a handler this becomes
+        // an uncaughtException that crashes the host process. Forward to caller.
+        this.wss.on("error", (err) => {
+            if (onError)
+                onError(err);
+            else if (!this.quiet)
+                console.error("[ws] server error:", err);
+        });
+        this.wss.on("connection", (ws) => {
+            this.clients.add(ws);
+            if (!this.quiet)
+                console.log(`[ws] client connected (${this.clients.size} total)`);
+            // Send initial connected event
+            ws.send(JSON.stringify({ type: "connected", data: "ok" }));
+            ws.on("message", (raw) => {
+                try {
+                    const msg = JSON.parse(raw.toString());
+                    if (msg.type === "ping") {
+                        ws.send(JSON.stringify({ type: "pong", data: "" }));
+                    }
+                    // Future: handle client requests like "refresh" or "subscribe"
+                }
+                catch {
+                    // ignore malformed messages
+                }
+            });
+            ws.on("close", () => {
+                this.clients.delete(ws);
+                if (!this.quiet)
+                    console.log(`[ws] client disconnected (${this.clients.size} left)`);
+            });
+            ws.on("error", () => {
+                this.clients.delete(ws);
+            });
+        });
+    }
+    broadcast(event) {
+        const msg = JSON.stringify(event);
+        for (const client of this.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                try {
+                    client.send(msg);
+                }
+                catch {
+                    this.clients.delete(client);
+                }
+            }
+        }
+    }
+    close() {
+        // Terminate every open socket first (browser keeps WebSocket alive, which
+        // would otherwise block the HTTP server from closing and stall process exit).
+        for (const client of this.clients) {
+            try {
+                client.terminate();
+            }
+            catch { }
+        }
+        this.clients.clear();
+        this.wss.close();
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agent-plan/server",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Local HTTP/WebSocket server for Agent Plan dashboards and planner APIs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./serve": "./dist/serve.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ovidius72/agent-planner.git"
+  },
+  "homepage": "https://github.com/ovidius72/agent-planner#readme",
+  "bugs": {
+    "url": "https://github.com/ovidius72/agent-planner/issues"
+  },
+  "keywords": [
+    "planner",
+    "server",
+    "websocket",
+    "dashboard",
+    "ai-agent"
+  ],
+  "dependencies": {
+    "hono": "^4.7.0",
+    "ws": "^8.18.0",
+    "@agent-plan/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.14.0",
+    "@types/ws": "^8.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}