@lightpath-dev/daemon 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightpath contributors
+
+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

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @lightpath-dev/daemon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local daemon of [Lightpath](https://github.com/Unknown-333/Lightpath#readme). It receives coverage from the browser and backend agents, builds one trace per action, and serves traces to the editor and MCP clients. It listens on `127.0.0.1` only and requires a token.
+
+You don't need this package directly; [`@lightpath-dev/cli`](https://www.npmjs.com/package/@lightpath-dev/cli) starts it.

package/dist/actions.d.ts

@@ -0,0 +1,19 @@
+import type { ActionRequest, ActionResult, ActionRunner, Trace, TraceId } from '@lightpath-dev/protocol';
+import type { Store } from './store.js';
+/** Longest wait after `traceEnd` for the backend lines of the requests an action sent (D-114). */
+export declare const BACKEND_WAIT_MS = 1500;
+type Tagged = {
+    method: string;
+    path: string;
+};
+/** The tagged requests that have no backend delta in the trace yet, matched by method and path. */
+export declare function missingBackend(trace: Trace | undefined, tagged: readonly Tagged[]): Tagged[];
+/**
+ * One wait for all of an action's requests: ends as soon as each tagged request has its backend
+ * delta in the stored trace, or after `waitMs`. Returns the requests still missing.
+ */
+export declare function waitForBackend(store: Store, traceId: TraceId, tagged: readonly Tagged[], waitMs?: number): Promise<Tagged[]>;
+/** Runs one `/v1/action` request: the runner's action, then the backend wait (section 4.3). */
+export declare function runAction(runner: ActionRunner | undefined, store: Store, request: ActionRequest, waitMs?: number): Promise<ActionResult>;
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -0,0 +1,84 @@
+/** Longest wait after `traceEnd` for the backend lines of the requests an action sent (D-114). */
+export const BACKEND_WAIT_MS = 1500;
+const withoutQuery = (path) => path.split('?')[0] ?? path;
+const key = (r) => `${r.method.toUpperCase()} ${withoutQuery(r.path)}`;
+/** The tagged requests that have no backend delta in the trace yet, matched by method and path. */
+export function missingBackend(trace, tagged) {
+    const have = new Map();
+    for (const r of trace?.requests ?? []) {
+        if (r.collector === 'browser')
+            continue;
+        have.set(key(r), (have.get(key(r)) ?? 0) + 1);
+    }
+    const missing = [];
+    for (const r of tagged) {
+        const n = have.get(key(r)) ?? 0;
+        if (n > 0)
+            have.set(key(r), n - 1);
+        else
+            missing.push(r);
+    }
+    return missing;
+}
+/**
+ * One wait for all of an action's requests: ends as soon as each tagged request has its backend
+ * delta in the stored trace, or after `waitMs`. Returns the requests still missing.
+ */
+export function waitForBackend(store, traceId, tagged, waitMs = BACKEND_WAIT_MS) {
+    const initial = missingBackend(store.get(traceId), tagged);
+    if (initial.length === 0)
+        return Promise.resolve([]);
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            unsubscribe();
+            resolve(missingBackend(store.get(traceId), tagged));
+        };
+        const timer = setTimeout(finish, waitMs);
+        const unsubscribe = store.subscribe((trace) => {
+            if (trace.id === traceId && missingBackend(trace, tagged).length === 0)
+                finish();
+        });
+    });
+}
+/** Runs one `/v1/action` request: the runner's action, then the backend wait (section 4.3). */
+export async function runAction(runner, store, request, waitMs = BACKEND_WAIT_MS) {
+    if (!runner) {
+        return {
+            ok: false,
+            error: {
+                code: 'no_browser',
+                message: 'Lightpath has no browser open to act in. Start it with a browser (lightpath dev -- <your dev command>, ' +
+                    'without --no-browser) and wait until it prints "watching".',
+            },
+        };
+    }
+    const outcome = await runner(request);
+    if (!outcome.ok)
+        return outcome;
+    const missing = await waitForBackend(store, outcome.traceId, outcome.tagged, waitMs);
+    const trace = store.get(outcome.traceId);
+    if (!trace) {
+        return {
+            ok: false,
+            error: { code: 'no_trace', message: `Trace ${outcome.traceId} was evicted before it could be read.` },
+        };
+    }
+    const warnings = [...outcome.warnings];
+    if (missing.length > 0) {
+        warnings.push({
+            code: 'backend_partial',
+            message: `No backend lines arrived within ${waitMs} ms for ${missing.map(key).join(', ')}: a remote API, or a server not started by lightpath dev.`,
+        });
+    }
+    return {
+        ok: true,
+        trace,
+        boundary: outcome.boundary,
+        settled: outcome.settled,
+        backend: missing.length > 0 ? 'partial' : 'complete',
+        pageUrl: outcome.pageUrl,
+        warnings,
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/auth.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage } from 'node:http';
+/** 32 random bytes, base64url-encoded (43 characters). */
+export declare function newToken(): string;
+export declare function tokensEqual(expected: string, actual: string | undefined | null): boolean;
+/**
+ * Checks a request against the daemon's rules (ARCHITECTURE section 7.2):
+ * - no `Origin` header, so web pages in the user's browser can't talk to the daemon;
+ * - the token in `Authorization: Bearer <token>` or, for WebSocket upgrades, `?token=`.
+ */
+export declare function authorize(req: IncomingMessage, token: string): 'ok' | 'forbidden' | 'unauthorized';
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,26 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/** 32 random bytes, base64url-encoded (43 characters). */
+export function newToken() {
+    return randomBytes(32).toString('base64url');
+}
+export function tokensEqual(expected, actual) {
+    if (!actual)
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(actual);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Checks a request against the daemon's rules (ARCHITECTURE section 7.2):
+ * - no `Origin` header, so web pages in the user's browser can't talk to the daemon;
+ * - the token in `Authorization: Bearer <token>` or, for WebSocket upgrades, `?token=`.
+ */
+export function authorize(req, token) {
+    if (req.headers.origin !== undefined)
+        return 'forbidden';
+    const auth = req.headers.authorization;
+    const bearer = auth?.startsWith('Bearer ') ? auth.slice('Bearer '.length) : undefined;
+    const query = new URL(req.url ?? '/', 'http://localhost').searchParams.get('token');
+    return tokensEqual(token, bearer ?? query) ? 'ok' : 'unauthorized';
+}
+//# sourceMappingURL=auth.js.map

package/dist/correlator.d.ts

@@ -0,0 +1,16 @@
+import { type ResolveContext } from '@lightpath-dev/core';
+import { type IngestMessage } from '@lightpath-dev/protocol';
+import type { Store } from './store.js';
+/**
+ * Turns ingest messages into mapped traces (docs/ARCHITECTURE.md sections 3, 4, and 6).
+ * Pure in-memory logic with no I/O, so it's tested without sockets.
+ */
+export declare class Correlator {
+    #private;
+    constructor(store: Store, ctx: ResolveContext);
+    /** Maps URLs served by a dev server (e.g. Vite at http://localhost:5173) onto a directory. */
+    addDevServer(origin: string, root: string): void;
+    get sourceCount(): number;
+    ingest(agentId: string, message: IngestMessage): void;
+}
+//# sourceMappingURL=correlator.d.ts.map

package/dist/correlator.js

@@ -0,0 +1,441 @@
+import { decodeDataUrlSourceMap, mapFunctions, mapScript, mergeLineCounts, newTraceId, originalLocation, PeriodicFunctions, resolveFile, } from '@lightpath-dev/core';
+import { MAX_TRACE_PROBLEMS, } from '@lightpath-dev/protocol';
+/**
+ * Turns ingest messages into mapped traces (docs/ARCHITECTURE.md sections 3, 4, and 6).
+ * Pure in-memory logic with no I/O, so it's tested without sockets.
+ */
+export class Correlator {
+    #agents = new Map();
+    /** Sources are cached by script hash, shared across agents (ADR 0006). */
+    #sources = new Map();
+    #pending = new Map();
+    #store;
+    #ctx;
+    constructor(store, ctx) {
+        this.#store = store;
+        this.#ctx = ctx;
+    }
+    /** Maps URLs served by a dev server (e.g. Vite at http://localhost:5173) onto a directory. */
+    addDevServer(origin, root) {
+        const others = (this.#ctx.devServers ?? []).filter((s) => s.origin !== origin);
+        this.#ctx = { ...this.#ctx, devServers: [...others, { origin, root }] };
+    }
+    get sourceCount() {
+        return this.#sources.size;
+    }
+    ingest(agentId, message) {
+        switch (message.type) {
+            case 'hello':
+                this.#agents.set(agentId, {
+                    kind: message.kind,
+                    pid: message.pid,
+                    scripts: new Map(),
+                    periodic: new PeriodicFunctions(),
+                });
+                return;
+            case 'scripts': {
+                const agent = this.#agent(agentId);
+                for (const s of message.scripts)
+                    agent.scripts.set(s.scriptId, s);
+                return;
+            }
+            case 'source':
+                this.#sources.set(message.hash, message.source);
+                return;
+            case 'traceStart': {
+                // Merge rather than replace, in case a backend delta with this ID arrived first.
+                const existing = this.#pending.get(message.traceId);
+                if (existing) {
+                    existing.trace.label = message.label;
+                    existing.trace.origin = 'browser';
+                    existing.trace.startedAt = Math.min(existing.trace.startedAt, message.at);
+                }
+                else {
+                    this.#pending.set(message.traceId, this.#newPending(message.traceId, message.label, 'browser', message.at));
+                }
+                return;
+            }
+            case 'traceEnd': {
+                const p = this.#pending.get(message.traceId);
+                if (p) {
+                    p.trace.endedAt = message.at;
+                    this.#publish(p);
+                }
+                return;
+            }
+            case 'delta':
+                this.#onDelta(agentId, message);
+                return;
+            case 'lines':
+                this.#onLines(agentId, message);
+                return;
+            case 'problem':
+                this.#onProblem(agentId, message);
+                return;
+        }
+    }
+    /** Attaches an error or failed request to its trace (D-121). Without an open trace, dropped. */
+    #onProblem(agentId, msg) {
+        if (!msg.traceId)
+            return;
+        const agent = this.#agent(agentId);
+        // A backend crash during run_request comes before any delta for its trace: it opens one.
+        const pending = this.#pending.get(msg.traceId) ??
+            this.#fromStore(msg.traceId) ??
+            (agent.kind === 'browser' ? undefined : this.#pendingFor(msg.traceId, 'uncaught error', msg.at));
+        if (!pending)
+            return;
+        pending.trace.problems ??= [];
+        const problems = pending.trace.problems;
+        if (problems.length >= MAX_TRACE_PROBLEMS) {
+            pending.trace.problemsDropped = (pending.trace.problemsDropped ?? 0) + 1;
+            this.#publish(pending);
+            return;
+        }
+        const where = msg.location ? this.#locate(agent, msg.location) : undefined;
+        problems.push({
+            collector: agent.kind,
+            kind: msg.kind,
+            message: msg.message,
+            at: msg.at,
+            ...(where ? { path: where.path, line: where.line } : {}),
+            ...(msg.request ? { request: msg.request } : {}),
+        });
+        this.#publish(pending);
+    }
+    /** A problem's generated location as a workspace path and original line, if it maps there. */
+    #locate(agent, loc) {
+        if (loc.line < 1)
+            return undefined;
+        const info = [...agent.scripts.values()].reverse().find((s) => s.url === loc.url);
+        let source = loc.url;
+        let line = loc.line;
+        if (info?.sourceMapURL) {
+            try {
+                const map = decodeDataUrlSourceMap(info.sourceMapURL);
+                const orig = map ? originalLocation(map, info.url, loc.line, loc.column) : undefined;
+                if (!orig)
+                    return undefined;
+                source = orig.source;
+                line = orig.line;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const r = resolveFile(source, this.#ctx);
+        return r.kind === 'workspace' ? { path: r.path, line } : undefined;
+    }
+    #onDelta(agentId, delta) {
+        const agent = this.#agent(agentId);
+        // Background deltas only feed the periodic-function rule (ARCHITECTURE 4.6); never traces.
+        if (delta.phase === 'background') {
+            agent.periodic.observeBackground(delta.coverage, (id) => agent.scripts.get(id)?.hash);
+            return;
+        }
+        const pending = this.#pendingFor(delta.traceId, delta.request ? `${delta.request.method} ${delta.request.path}` : 'action', delta.startedAt);
+        // Which phase this delta's functions belong to (D-116). A backend phase is made below, once
+        // the request has its index.
+        let phase;
+        if (delta.beforeRequest) {
+            phase = { kind: 'before-request', at: delta.endedAt, leaving: delta.beforeRequest };
+            pending.phases.push(phase);
+        }
+        else if (!delta.request) {
+            phase = this.#closingPhase(pending, delta.endedAt);
+        }
+        else {
+            phase = { kind: 'backend', at: delta.startedAt, request: pending.trace.requests.length };
+            pending.phases.push(phase);
+        }
+        for (const coverage of delta.coverage) {
+            const info = agent.scripts.get(coverage.scriptId);
+            const source = info ? this.#sources.get(info.hash) : undefined;
+            if (source === undefined) {
+                // Without the exact source V8 ran, offsets can't be turned into lines.
+                const r = resolveFile(coverage.url, this.#ctx);
+                this.#drop(pending, r.kind === 'dropped' ? r.reason : 'no-source');
+                continue;
+            }
+            let sourceMap;
+            try {
+                sourceMap = info?.sourceMapURL ? decodeDataUrlSourceMap(info.sourceMapURL) : undefined;
+            }
+            catch {
+                this.#drop(pending, 'no-source-map');
+                continue;
+            }
+            const map = (c) => mapScript({ coverage: c, source, ...(sourceMap ? { sourceMap } : {}) }, this.#ctx);
+            const result = map(coverage);
+            for (const [reason, n] of result.dropped)
+                this.#drop(pending, reason, n);
+            // Lines are never removed. A file whose lit lines all come from periodic code (a timer that
+            // happened to fire during the action) is marked background so clients can tone it down.
+            const fg = info ? agent.periodic.foreground(coverage, info.hash) : coverage;
+            const fgFiles = fg === coverage ? result.files : fg ? map(fg).files : new Map();
+            for (const [path, lines] of result.files) {
+                const fgLines = fgFiles.get(path);
+                const foreground = fgLines !== undefined && [...fgLines.values()].some((c) => c > 0);
+                this.#addFile(pending, path, agent.kind, lines, delta.startedAt, foreground);
+            }
+            const fns = mapFunctions({ coverage, source, ...(sourceMap ? { sourceMap } : {}) }, result.files, this.#ctx);
+            for (const fn of fns)
+                this.#addFunction(pending, phase, agent.kind, fn);
+        }
+        if (delta.request) {
+            pending.trace.requests.push({
+                collector: agent.kind,
+                pid: agent.pid,
+                method: delta.request.method,
+                path: delta.request.path,
+                ...(delta.request.status !== undefined ? { status: delta.request.status } : {}),
+                durationMs: Math.max(0, delta.endedAt - delta.startedAt),
+                overlapped: (delta.overlapped?.length ?? 0) > 0,
+            });
+        }
+        // A browser trace ends only with traceEnd, after the frontend's own delta. Backend deltas
+        // arrive mid-click and must not make the trace look finished to clients.
+        if (pending.trace.origin === 'backend')
+            pending.trace.endedAt = Math.max(pending.trace.endedAt ?? 0, delta.endedAt);
+        this.#publish(pending);
+    }
+    /** Adds one function to its phase, summing calls and keeping lines not run in every delta. */
+    #addFunction(p, phase, collector, fn) {
+        const key = `${p.phases.indexOf(phase)}|${phase.kind}|${fn.path}|${fn.name}|${fn.startLine}`;
+        const prev = p.functions.get(key);
+        if (!prev) {
+            p.functions.set(key, {
+                phase,
+                hit: {
+                    path: fn.path,
+                    collector,
+                    name: fn.name,
+                    startLine: fn.startLine,
+                    endLine: fn.endLine,
+                    count: fn.count,
+                    ...(fn.notRun.length ? { notRun: fn.notRun } : {}),
+                    ...(fn.notRunSpans.length ? { notRunSpans: fn.notRunSpans } : {}),
+                },
+            });
+            return;
+        }
+        const hit = prev.hit;
+        hit.count += fn.count;
+        hit.endLine = Math.max(hit.endLine, fn.endLine);
+        const notRun = (hit.notRun ?? []).filter((l) => fn.notRun.includes(l));
+        const spans = (hit.notRunSpans ?? []).filter((s) => fn.notRunSpans.some((t) => t.line === s.line && t.startColumn === s.startColumn));
+        if (notRun.length)
+            hit.notRun = notRun;
+        else
+            delete hit.notRun;
+        if (spans.length)
+            hit.notRunSpans = spans;
+        else
+            delete hit.notRunSpans;
+    }
+    /** The one browser phase for reads not taken before a request (D-116), made on first use. */
+    #closingPhase(p, at) {
+        if (!p.closing) {
+            p.closing = { kind: 'browser', at };
+            p.phases.push(p.closing);
+        }
+        p.closing.at = Math.max(p.closing.at, at);
+        return p.closing;
+    }
+    #onLines(agentId, msg) {
+        const agent = this.#agent(agentId);
+        const label = msg.request ? `${msg.request.method} ${msg.request.path}` : 'action';
+        const pending = this.#pendingFor(msg.traceId, label, msg.startedAt);
+        // Python files have no function list; the summary lists them by line range in this phase.
+        if (msg.request)
+            pending.phases.push({ kind: 'backend', at: msg.startedAt, request: pending.trace.requests.length });
+        for (const file of msg.files) {
+            const r = resolveFile(file.path, this.#ctx);
+            if (r.kind === 'dropped') {
+                this.#drop(pending, r.reason);
+                continue;
+            }
+            this.#addFile(pending, r.path, 'python', new Map(file.lines.map((l) => [l, 1])), msg.startedAt, true);
+        }
+        if (msg.request) {
+            pending.trace.requests.push({
+                collector: 'python',
+                pid: agent.pid || msg.pid,
+                method: msg.request.method,
+                path: msg.request.path,
+                ...(msg.request.status !== undefined ? { status: msg.request.status } : {}),
+                durationMs: Math.max(0, msg.endedAt - msg.startedAt),
+                overlapped: false,
+            });
+        }
+        if (pending.trace.origin === 'backend')
+            pending.trace.endedAt = Math.max(pending.trace.endedAt ?? 0, msg.endedAt);
+        this.#publish(pending);
+    }
+    #agent(agentId) {
+        let a = this.#agents.get(agentId);
+        if (!a) {
+            // A batch can arrive before (or without) hello, for example after a daemon restart.
+            a = {
+                kind: agentId.startsWith('py-') ? 'python' : 'node',
+                pid: 0,
+                scripts: new Map(),
+                periodic: new PeriodicFunctions(),
+            };
+            this.#agents.set(agentId, a);
+        }
+        return a;
+    }
+    /** Finds the browser-started trace for this ID, or starts a backend-only trace. */
+    #pendingFor(traceId, label, at) {
+        if (traceId) {
+            const existing = this.#pending.get(traceId) ?? this.#fromStore(traceId);
+            if (existing)
+                return existing;
+        }
+        const p = this.#newPending(traceId ?? newTraceId(), label, 'backend', at);
+        this.#pending.set(p.trace.id, p);
+        return p;
+    }
+    #fromStore(traceId) {
+        const trace = this.#store.get(traceId);
+        if (!trace)
+            return undefined;
+        const p = {
+            trace: structuredClone(trace),
+            files: new Map(),
+            dropped: new Map(),
+            phases: [],
+            functions: new Map(),
+        };
+        // Phases keep their published order: their old sort keys are their positions, which sort
+        // before any new read's time. The closing browser phase stays last.
+        for (const [i, ph] of (trace.phases ?? []).entries()) {
+            const open = {
+                kind: ph.kind,
+                at: i,
+                ...(ph.request !== undefined ? { request: ph.request } : {}),
+            };
+            if (ph.kind === 'before-request' && ph.request !== undefined) {
+                const r = trace.requests[ph.request];
+                if (r)
+                    open.leaving = { method: r.method, path: r.path };
+            }
+            if (ph.kind === 'browser' || ph.kind === 'after-response')
+                p.closing = open;
+            p.phases.push(open);
+        }
+        for (const f of trace.functions ?? []) {
+            const phase = p.phases[f.phase];
+            if (!phase)
+                continue;
+            const { phase: _, ...hit } = f;
+            p.functions.set(`${f.phase}|${phase.kind}|${f.path}|${f.name}|${f.startLine}`, { phase, hit });
+        }
+        for (const f of trace.files) {
+            p.files.set(f.path, {
+                collector: f.collector,
+                lines: new Map(f.lines.map((l) => [l.line, l.count])),
+                firstSeenAt: f.firstSeenAt,
+                foreground: !f.background,
+            });
+        }
+        for (const d of trace.dropped)
+            p.dropped.set(d.reason, d.count);
+        this.#pending.set(traceId, p);
+        return p;
+    }
+    #newPending(id, label, origin, at) {
+        return {
+            trace: { id, label, origin, startedAt: at, files: [], requests: [], dropped: [] },
+            files: new Map(),
+            dropped: new Map(),
+            phases: [],
+            functions: new Map(),
+        };
+    }
+    /**
+     * Orders the phases and numbers them (design section 5.3): reads and requests in time order, the
+     * closing browser phase last. It is `after-response` when any request left the page before it,
+     * else `browser`. Each before-request phase is tied to the first unmatched backend request with
+     * the same method and path.
+     */
+    #phasesOf(p, published) {
+        if (p.phases.length === 0)
+            return undefined;
+        const ordered = p.phases.filter((ph) => ph !== p.closing).sort((a, b) => a.at - b.at);
+        if (p.closing)
+            ordered.push(p.closing);
+        const hasBefore = ordered.some((ph) => ph.kind === 'before-request');
+        const matched = new Set();
+        const phases = ordered.map((ph) => {
+            if (ph === p.closing)
+                return { kind: hasBefore ? 'after-response' : 'browser' };
+            if (ph.kind === 'backend')
+                return { kind: 'backend', ...(ph.request !== undefined ? { request: ph.request } : {}) };
+            if (ph.kind === 'before-request' && ph.leaving) {
+                const { method, path } = ph.leaving;
+                const i = p.trace.requests.findIndex((r, j) => !matched.has(j) && r.collector !== 'browser' && r.method === method && r.path === path);
+                if (i >= 0) {
+                    matched.add(i);
+                    return { kind: 'before-request', request: i };
+                }
+            }
+            return { kind: ph.kind };
+        });
+        const functions = [];
+        for (const { phase, hit } of p.functions.values()) {
+            if (!published.has(hit.path))
+                continue; // its file has no lit line, so it isn't in the trace
+            functions.push({ ...hit, phase: ordered.indexOf(phase) });
+        }
+        functions.sort((a, b) => a.phase - b.phase || a.path.localeCompare(b.path) || a.startLine - b.startLine);
+        return { phases, functions };
+    }
+    #addFile(p, path, collector, lines, at, foreground) {
+        const existing = p.files.get(path);
+        if (existing) {
+            existing.lines = mergeLineCounts(existing.lines, lines);
+            existing.foreground ||= foreground;
+        }
+        else
+            p.files.set(path, { collector, lines, firstSeenAt: at, foreground });
+    }
+    #drop(p, reason, n = 1) {
+        p.dropped.set(reason, (p.dropped.get(reason) ?? 0) + n);
+    }
+    #publish(p) {
+        const files = [];
+        for (const [path, f] of p.files) {
+            const lines = [...f.lines]
+                .filter(([, c]) => c > 0)
+                .sort((a, b) => a[0] - b[0])
+                .map(([line, count]) => ({ line, count }));
+            if (lines.length === 0)
+                continue;
+            files.push({
+                path,
+                collector: f.collector,
+                lines,
+                firstSeenAt: f.firstSeenAt,
+                ...(f.foreground ? {} : { background: true }),
+            });
+        }
+        files.sort((a, b) => a.firstSeenAt - b.firstSeenAt || a.path.localeCompare(b.path));
+        p.trace.files = files;
+        p.trace.dropped = [...p.dropped].map(([reason, count]) => ({ reason, count }));
+        const shaped = this.#phasesOf(p, new Set(files.map((f) => f.path)));
+        if (shaped) {
+            p.trace.phases = shaped.phases;
+            p.trace.functions = shaped.functions;
+        }
+        this.#store.put(structuredClone(p.trace));
+        // Keep at most 50 traces open for late backend deltas; older ones are re-read from the store.
+        if (this.#pending.size > 50) {
+            const oldest = this.#pending.keys().next().value;
+            if (oldest !== undefined)
+                this.#pending.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=correlator.js.map

package/dist/discovery.d.ts

@@ -0,0 +1,15 @@
+import { DaemonDiscovery } from '@lightpath-dev/protocol';
+/** Writes `.lightpath/daemon.json` with user-only permissions, plus a .gitignore for the folder. */
+export declare function writeDiscovery(workspaceRoot: string, info: DaemonDiscovery): Promise<string>;
+/** Reads and validates the discovery file, or returns undefined if it's missing or invalid. */
+export declare function readDiscovery(workspaceRoot: string): Promise<DaemonDiscovery | undefined>;
+export declare function removeDiscovery(workspaceRoot: string): Promise<void>;
+/**
+ * The nearest folder at or above `dir` with a valid discovery file, and what it says. This is where
+ * `lightpath mcp` looks too, so `lightpath doctor` in a subfolder reports the daemon MCP would use.
+ */
+export declare function findDiscovery(dir: string): Promise<{
+    root: string;
+    info: DaemonDiscovery;
+} | undefined>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.js

@@ -0,0 +1,42 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { DaemonDiscovery, DISCOVERY_FILE } from '@lightpath-dev/protocol';
+/** Writes `.lightpath/daemon.json` with user-only permissions, plus a .gitignore for the folder. */
+export async function writeDiscovery(workspaceRoot, info) {
+    const file = join(workspaceRoot, DISCOVERY_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(join(dirname(file), '.gitignore'), '*\n');
+    // mode applies on POSIX; on Windows the file inherits the user's ACL from the workspace.
+    await writeFile(file, `${JSON.stringify(info, null, 2)}\n`, { mode: 0o600 });
+    return file;
+}
+/** Reads and validates the discovery file, or returns undefined if it's missing or invalid. */
+export async function readDiscovery(workspaceRoot) {
+    try {
+        const raw = await readFile(join(workspaceRoot, DISCOVERY_FILE), 'utf8');
+        const parsed = DaemonDiscovery.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function removeDiscovery(workspaceRoot) {
+    await rm(join(workspaceRoot, DISCOVERY_FILE), { force: true });
+}
+/**
+ * The nearest folder at or above `dir` with a valid discovery file, and what it says. This is where
+ * `lightpath mcp` looks too, so `lightpath doctor` in a subfolder reports the daemon MCP would use.
+ */
+export async function findDiscovery(dir) {
+    for (let root = resolve(dir);;) {
+        const info = await readDiscovery(root);
+        if (info)
+            return { root, info };
+        const parent = dirname(root);
+        if (parent === root)
+            return undefined;
+        root = parent;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { BACKEND_WAIT_MS, missingBackend, runAction, waitForBackend } from './actions.js';
+export { authorize, newToken, tokensEqual } from './auth.js';
+export { Correlator } from './correlator.js';
+export { findDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from './discovery.js';
+export { type DaemonOptions, type RunningDaemon, startDaemon } from './server.js';
+export { MemoryStore, type Store, type TraceQuery } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+export { BACKEND_WAIT_MS, missingBackend, runAction, waitForBackend } from './actions.js';
+export { authorize, newToken, tokensEqual } from './auth.js';
+export { Correlator } from './correlator.js';
+export { findDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from './discovery.js';
+export { startDaemon } from './server.js';
+export { MemoryStore } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+import type { ResolveContext } from '@lightpath-dev/core';
+import { type ActionRunner } from '@lightpath-dev/protocol';
+import { Correlator } from './correlator.js';
+import { type Store } from './store.js';
+export interface DaemonOptions {
+    /** Workspace roots; the first one holds `.lightpath/daemon.json`. */
+    workspaceRoots: string[];
+    devServers?: ResolveContext['devServers'];
+    /** Globs for workspace files to leave out of traces (`ignore` in lightpath.config.json). */
+    ignore?: string[];
+    /** 0 picks a free port. */
+    port?: number;
+    token?: string;
+    store?: Store;
+    writeDiscoveryFile?: boolean;
+    log?: (msg: string) => void;
+    /** Longest wait after an action's `traceEnd` for its backend lines (default 1,500 ms). */
+    backendWaitMs?: number;
+}
+export interface RunningDaemon {
+    port: number;
+    url: string;
+    token: string;
+    startedAt: number;
+    store: Store;
+    correlator: Correlator;
+    /**
+     * Registers what runs `POST /v1/action` (the browser collector, once its page is open), or
+     * removes it. Without one, every action answers `no_browser` (D-115).
+     */
+    setActionRunner(runner: ActionRunner | undefined): void;
+    close(): Promise<void>;
+}
+/** Starts the daemon on 127.0.0.1 (docs/ARCHITECTURE.md section 7). */
+export declare function startDaemon(options: DaemonOptions): Promise<RunningDaemon>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,191 @@
+import http, {} from 'node:http';
+import { ActionRequest, ClientMessage, CloseCode, IngestBatch, MAX_ACTION_BYTES, MAX_MESSAGE_BYTES, PROTOCOL_VERSION, } from '@lightpath-dev/protocol';
+import { WebSocketServer } from 'ws';
+import { BACKEND_WAIT_MS, runAction } from './actions.js';
+import { authorize, newToken } from './auth.js';
+import { Correlator } from './correlator.js';
+import { removeDiscovery, writeDiscovery } from './discovery.js';
+import { MemoryStore } from './store.js';
+/** Starts the daemon on 127.0.0.1 (docs/ARCHITECTURE.md section 7). */
+export async function startDaemon(options) {
+    const token = options.token ?? newToken();
+    const store = options.store ?? new MemoryStore();
+    const log = options.log ?? (() => { });
+    const startedAt = Date.now();
+    const backendWaitMs = options.backendWaitMs ?? BACKEND_WAIT_MS;
+    let actionRunner;
+    const correlator = new Correlator(store, {
+        workspaceRoots: options.workspaceRoots,
+        ...(options.devServers ? { devServers: options.devServers } : {}),
+        ...(options.ignore?.length ? { ignore: options.ignore } : {}),
+    });
+    const server = http.createServer((req, res) => {
+        void route(req, res).catch((err) => {
+            log(`request error: ${err.stack ?? err}`);
+            if (!res.headersSent)
+                res.writeHead(500).end();
+        });
+    });
+    async function route(req, res) {
+        const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+        if (req.method === 'GET' && path === '/v1/health') {
+            return json(res, 200, { ok: true, protocolVersion: PROTOCOL_VERSION });
+        }
+        if (req.method === 'POST' && path === '/v1/ingest') {
+            const auth = authorize(req, token);
+            if (auth !== 'ok')
+                return json(res, auth === 'forbidden' ? 403 : 401, { error: auth });
+            const body = await readBody(req, MAX_MESSAGE_BYTES);
+            if (body === undefined)
+                return json(res, 413, { error: 'body too large' });
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return json(res, 400, { error: 'invalid JSON' });
+            }
+            const batch = IngestBatch.safeParse(parsed);
+            if (!batch.success)
+                return json(res, 400, { error: batch.error.issues.slice(0, 5) });
+            if (batch.data.protocolVersion !== PROTOCOL_VERSION)
+                return json(res, 426, { error: 'protocol version mismatch' });
+            for (const message of batch.data.messages)
+                correlator.ingest(batch.data.agentId, message);
+            res.writeHead(204, { 'x-lightpath-started-at': String(startedAt) }).end();
+            return;
+        }
+        if (req.method === 'POST' && path === '/v1/action') {
+            // Same rules as /v1/ingest (D-115). The body holds `fill` values, which are secrets: it is
+            // never logged, and a schema error reply names fields, never values.
+            const auth = authorize(req, token);
+            if (auth !== 'ok')
+                return json(res, auth === 'forbidden' ? 403 : 401, { error: auth });
+            // Drain an oversized body instead of dropping the connection, so the caller sees the 413.
+            const body = await readBody(req, MAX_ACTION_BYTES, true);
+            if (body === undefined)
+                return json(res, 413, { error: 'body too large' });
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return json(res, 400, { error: 'invalid JSON' });
+            }
+            const request = ActionRequest.safeParse(parsed);
+            if (!request.success) {
+                const issues = request.error.issues.slice(0, 5).map((i) => ({ path: i.path, message: i.message }));
+                return json(res, 400, { error: issues });
+            }
+            if (request.data.protocolVersion !== PROTOCOL_VERSION)
+                return json(res, 426, { error: 'protocol version mismatch' });
+            return json(res, 200, await runAction(actionRunner, store, request.data, backendWaitMs));
+        }
+        json(res, 404, { error: 'not found' });
+    }
+    // ── Client feed ───────────────────────────────────────────────────────────
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE_BYTES });
+    server.on('upgrade', (req, socket, head) => {
+        const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+        const auth = authorize(req, token);
+        if (path !== '/v1/client' || auth !== 'ok') {
+            socket.end(`HTTP/1.1 ${auth === 'forbidden' ? '403 Forbidden' : path !== '/v1/client' ? '404 Not Found' : '401 Unauthorized'}\r\n\r\n`);
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => onClient(ws));
+    });
+    function onClient(ws) {
+        const send = (m) => ws.send(JSON.stringify(m));
+        send({ type: 'welcome', protocolVersion: PROTOCOL_VERSION, workspaceRoots: options.workspaceRoots });
+        const unsubscribe = store.subscribe((trace) => send({ type: 'trace', trace }));
+        ws.on('close', unsubscribe);
+        ws.on('message', (data) => {
+            let parsed;
+            try {
+                parsed = ClientMessage.safeParse(JSON.parse(String(data)));
+            }
+            catch {
+                ws.close(CloseCode.BadMessage, 'invalid JSON');
+                return;
+            }
+            if (!parsed.success) {
+                ws.close(CloseCode.BadMessage, 'invalid message');
+                return;
+            }
+            const msg = parsed.data;
+            if (msg.type === 'listTraces') {
+                send({
+                    type: 'traces',
+                    requestId: msg.requestId,
+                    traces: store.list({ limit: msg.limit, label: msg.label }),
+                });
+            }
+            else {
+                send({ type: 'traceResult', requestId: msg.requestId, trace: store.get(msg.traceId) ?? null });
+            }
+        });
+    }
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port ?? 0, '127.0.0.1', () => resolve());
+    });
+    const port = server.address().port;
+    const root = options.workspaceRoots[0];
+    if (options.writeDiscoveryFile !== false && root) {
+        await writeDiscovery(root, {
+            port,
+            token,
+            pid: process.pid,
+            protocolVersion: PROTOCOL_VERSION,
+            startedAt,
+        });
+    }
+    log(`daemon listening on 127.0.0.1:${port}`);
+    return {
+        port,
+        url: `http://127.0.0.1:${port}`,
+        token,
+        startedAt,
+        store,
+        correlator,
+        setActionRunner(runner) {
+            actionRunner = runner;
+        },
+        async close() {
+            for (const client of wss.clients)
+                client.close();
+            wss.close();
+            await new Promise((resolve) => server.close(() => resolve()));
+            if (options.writeDiscoveryFile !== false && root)
+                await removeDiscovery(root);
+        },
+    };
+}
+function json(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+}
+/**
+ * Reads a request body as UTF-8, or returns undefined if it exceeds `limit` bytes. Past the limit
+ * it drops the connection, or with `drain` reads the rest without keeping it.
+ */
+function readBody(req, limit, drain = false) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                chunks.length = 0;
+                if (drain)
+                    return;
+                resolve(undefined);
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(size > limit ? undefined : Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/store.d.ts

@@ -0,0 +1,23 @@
+import type { Trace, TraceId, TraceSummary } from '@lightpath-dev/protocol';
+export interface TraceQuery {
+    limit?: number | undefined;
+    /** Case-insensitive substring match on the trace label. */
+    label?: string | undefined;
+}
+export interface Store {
+    put(trace: Trace): void;
+    get(id: TraceId): Trace | undefined;
+    /** Newest first. */
+    list(query?: TraceQuery): TraceSummary[];
+    subscribe(listener: (trace: Trace) => void): () => void;
+}
+/** Keeps the most recent traces in memory (ARCHITECTURE section 7.3). */
+export declare class MemoryStore implements Store {
+    #private;
+    constructor(capacity?: number);
+    put(trace: Trace): void;
+    get(id: TraceId): Trace | undefined;
+    list(query?: TraceQuery): TraceSummary[];
+    subscribe(listener: (trace: Trace) => void): () => void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.js

@@ -0,0 +1,49 @@
+/** Keeps the most recent traces in memory (ARCHITECTURE section 7.3). */
+export class MemoryStore {
+    #traces = new Map();
+    #listeners = new Set();
+    #capacity;
+    constructor(capacity = 200) {
+        this.#capacity = capacity;
+    }
+    put(trace) {
+        // Re-inserting moves the trace to the newest position.
+        this.#traces.delete(trace.id);
+        this.#traces.set(trace.id, trace);
+        while (this.#traces.size > this.#capacity) {
+            const oldest = this.#traces.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#traces.delete(oldest);
+        }
+        for (const listener of this.#listeners)
+            listener(trace);
+    }
+    get(id) {
+        return this.#traces.get(id);
+    }
+    list(query = {}) {
+        const needle = query.label?.toLowerCase();
+        const out = [];
+        for (const t of [...this.#traces.values()].reverse()) {
+            if (needle && !t.label.toLowerCase().includes(needle))
+                continue;
+            const problems = (t.problems?.length ?? 0) + (t.problemsDropped ?? 0);
+            out.push({
+                id: t.id,
+                label: t.label,
+                startedAt: t.startedAt,
+                fileCount: t.files.length,
+                ...(problems > 0 ? { problemCount: problems } : {}),
+            });
+            if (query.limit && out.length >= query.limit)
+                break;
+        }
+        return out;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+}
+//# sourceMappingURL=store.js.map

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@lightpath-dev/daemon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Local Lightpath daemon: receives coverage from agents, maps it to source lines, and serves traces",
+  "keywords": [
+    "coverage",
+    "trace",
+    "daemon",
+    "websocket"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Unknown-333/Lightpath#readme",
+  "bugs": "https://github.com/Unknown-333/Lightpath/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Unknown-333/Lightpath.git",
+    "directory": "packages/daemon"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lightpath-dev/core": "0.1.0",
+    "@lightpath-dev/protocol": "0.1.0",
+    "ws": "8.22.0"
+  },
+  "devDependencies": {
+    "@types/ws": "8.18.2"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p test"
+  }
 }