agent-tempo 1.0.1

package/dist/http/fixtures/empty-ensemble.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyEnsemble = void 0;
+const constants_1 = require("./constants");
+exports.emptyEnsemble = {
+    name: 'empty-ensemble',
+    description: 'No players, no chat, no schedules. Empty-state UI exercise.',
+    snapshot: {
+        v: 1,
+        ensemble: 'demo-empty',
+        capturedAt: '2026-04-27T00:00:00.000Z',
+        lastEventId: `${constants_1.FIXTURE_BOOT_EPOCH}:0`,
+        state: 'online',
+        hasConductor: false,
+        flags: { paused: false, held: false },
+        players: [],
+        schedules: [],
+        chat: { messages: [], total: 0, hasMore: false },
+        hostProfiles: {},
+        description: '',
+        startedAt: '',
+        currentBpm: 0,
+        tempoSeries: [],
+    },
+    events: [],
+};

package/dist/http/fixtures/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Test-fixture mode for the daemon HTTP/SSE surface — PR-3 of #340.
+ *
+ * Adds a `?fixture=<name>` query param to `/v1/state/:ensemble` and
+ * `/v1/events/:ensemble`. When set to a known fixture, the daemon
+ * returns canned data instead of running live Temporal queries / wiring
+ * the aggregate poll loop.
+ *
+ * **Why this exists**: PR-4 onwards (dashboard SPA work) needs
+ * deterministic, reproducible scenarios — a conductor leaving, a
+ * broadcast fan-out, a chat-ring overflow, an SSE reconnect. Real
+ * ensemble events are flaky for UI-driven testing; fixtures aren't.
+ *
+ * **Auth posture**: fixture mode honours the existing bearer-auth gate
+ * (loopback no-auth, non-loopback bearer required). The fixture
+ * endpoint is NOT a backdoor — it's an alternate *projection* of an
+ * authorised request. See `docs/SSE-PROTOCOL.md` § 11a.
+ *
+ * **Type safety**: fixture data imports its types from
+ * {@link ../event-types} so a wire-protocol change here breaks the
+ * `tsc` build of every fixture module. Don't redeclare shapes inside
+ * fixture files.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { TempoEvent, EnsembleStateV1 } from '../event-types';
+export interface FixtureScenario {
+    name: string;
+    description: string;
+    /** Returned by `/v1/state/:ensemble?fixture=<name>` verbatim. */
+    snapshot: EnsembleStateV1;
+    /** Walked in order by `/v1/events/:ensemble?fixture=<name>` after the snapshot prelude. */
+    events: TempoEvent[];
+    /** Delay between events in ms. `0` (default) ⇒ flush all at once. */
+    eventCadenceMs?: number;
+}
+/** Lookup by name. Returns `null` for unknown fixtures. */
+export declare function getFixture(name: string): FixtureScenario | null;
+/** Listing for diagnostics — used by potential future `/v1/fixtures` listing. */
+export declare function listFixtures(): {
+    name: string;
+    description: string;
+}[];
+/** Handler for `GET /v1/state/:ensemble?fixture=<name>`. */
+export declare function handleFixtureSnapshot(res: ServerResponse, fixtureName: string): void;
+/**
+ * Handler for `GET /v1/events/:ensemble?fixture=<name>`. Streams the
+ * fixture's snapshot prelude followed by its event list, with optional
+ * inter-event delays. Closes the connection when all events have been
+ * delivered (or sooner if the client disconnects).
+ *
+ * The snapshot prelude reuses the fixture's `lastEventId` so a consumer
+ * comparing `Last-Event-ID` against subsequent events sees the
+ * snapshot ordered before the live events.
+ */
+export declare function handleFixtureSse(req: IncomingMessage, res: ServerResponse, fixtureName: string): Promise<void>;

package/dist/http/fixtures/index.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFixture = getFixture;
+exports.listFixtures = listFixtures;
+exports.handleFixtureSnapshot = handleFixtureSnapshot;
+exports.handleFixtureSse = handleFixtureSse;
+const responses_1 = require("../responses");
+const sse_handler_1 = require("../sse-handler");
+const empty_ensemble_1 = require("./empty-ensemble");
+const single_conductor_1 = require("./single-conductor");
+const eight_player_broadcast_1 = require("./eight-player-broadcast");
+const conductor_leaving_1 = require("./conductor-leaving");
+const sse_reconnect_1 = require("./sse-reconnect");
+const chat_stress_1 = require("./chat-stress");
+const FIXTURES = {
+    [empty_ensemble_1.emptyEnsemble.name]: empty_ensemble_1.emptyEnsemble,
+    [single_conductor_1.singleConductor.name]: single_conductor_1.singleConductor,
+    [eight_player_broadcast_1.eightPlayerBroadcast.name]: eight_player_broadcast_1.eightPlayerBroadcast,
+    [conductor_leaving_1.conductorLeaving.name]: conductor_leaving_1.conductorLeaving,
+    [sse_reconnect_1.sseReconnect.name]: sse_reconnect_1.sseReconnect,
+    [chat_stress_1.chatStress.name]: chat_stress_1.chatStress,
+};
+/** Lookup by name. Returns `null` for unknown fixtures. */
+function getFixture(name) {
+    return FIXTURES[name] ?? null;
+}
+/** Listing for diagnostics — used by potential future `/v1/fixtures` listing. */
+function listFixtures() {
+    return Object.values(FIXTURES).map((f) => ({ name: f.name, description: f.description }));
+}
+/** Handler for `GET /v1/state/:ensemble?fixture=<name>`. */
+function handleFixtureSnapshot(res, fixtureName) {
+    const fixture = getFixture(fixtureName);
+    if (!fixture) {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'unknown-fixture', fixture: fixtureName });
+    }
+    (0, responses_1.jsonResponse)(res, 200, fixture.snapshot);
+}
+/**
+ * Handler for `GET /v1/events/:ensemble?fixture=<name>`. Streams the
+ * fixture's snapshot prelude followed by its event list, with optional
+ * inter-event delays. Closes the connection when all events have been
+ * delivered (or sooner if the client disconnects).
+ *
+ * The snapshot prelude reuses the fixture's `lastEventId` so a consumer
+ * comparing `Last-Event-ID` against subsequent events sees the
+ * snapshot ordered before the live events.
+ */
+async function handleFixtureSse(req, res, fixtureName) {
+    const fixture = getFixture(fixtureName);
+    if (!fixture) {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'unknown-fixture', fixture: fixtureName });
+    }
+    (0, sse_handler_1.openSseResponse)(res, 'agent-tempo SSE (fixture)');
+    // AbortController is the single source of truth for "client disconnected".
+    // Fires on TCP drop, abort, or natural end-of-events. `once()` ensures
+    // each underlying close event registers exactly one tick, and the
+    // `finally` cleanup detaches the listeners regardless of how we exit.
+    const abort = new AbortController();
+    const onClose = () => abort.abort();
+    req.once('close', onClose);
+    res.once('close', onClose);
+    try {
+        if (abort.signal.aborted)
+            return;
+        res.write((0, sse_handler_1.frameSseEventData)(fixture.snapshot.lastEventId, 'snapshot', fixture.snapshot));
+        const cadence = fixture.eventCadenceMs ?? 0;
+        for (let i = 0; i < fixture.events.length; i++) {
+            if (abort.signal.aborted)
+                return;
+            const ev = fixture.events[i];
+            res.write((0, sse_handler_1.frameSseEventData)(ev.eventId, ev.type, ev.payload));
+            if (cadence > 0 && i < fixture.events.length - 1) {
+                const ok = await delay(cadence, abort.signal);
+                if (!ok)
+                    return;
+            }
+        }
+    }
+    finally {
+        req.removeListener('close', onClose);
+        res.removeListener('close', onClose);
+        if (!res.writableEnded) {
+            try {
+                res.end();
+            }
+            catch { /* socket already gone */ }
+        }
+    }
+}
+/**
+ * Sleep for `ms` milliseconds, returning `false` if the abort signal
+ * fires first. Lets the event loop unblock the moment the client
+ * disconnects rather than running out the cadence timer.
+ */
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve(false);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/http/fixtures/single-conductor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fixture: a single conductor player, no other players, no chat.
+ * Exercises the "conductor-only" lobby state the dashboard renders
+ * before any soloists join.
+ */
+import type { FixtureScenario } from './index';
+export declare const singleConductor: FixtureScenario;

package/dist/http/fixtures/single-conductor.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.singleConductor = void 0;
+const constants_1 = require("./constants");
+exports.singleConductor = {
+    name: 'single-conductor',
+    description: 'One conductor, no other players. Lobby state.',
+    snapshot: {
+        v: 1,
+        ensemble: 'demo-conductor',
+        capturedAt: '2026-04-27T00:00:00.000Z',
+        lastEventId: `${constants_1.FIXTURE_BOOT_EPOCH}:0`,
+        state: 'online',
+        hasConductor: true,
+        flags: { paused: false, held: false },
+        players: [{
+                playerId: 'conductor',
+                ensemble: 'demo-conductor',
+                hostname: 'demo-host',
+                isConductor: true,
+                agentType: 'claude',
+                playerType: 'tempo-conductor',
+                phase: 'attached',
+                part: 'Orchestrating the demo',
+                workDir: '/repo/demo',
+                gitBranch: 'main',
+                lastHeartbeatAt: '2026-04-27T00:00:00.000Z',
+            }],
+        schedules: [],
+        chat: { messages: [], total: 0, hasMore: false },
+        hostProfiles: {
+            'demo-host': {
+                hostname: 'demo-host',
+                version: '0.28.0',
+                defaultAgent: 'claude',
+                platform: 'linux',
+                capabilities: [],
+            },
+        },
+        description: '',
+        startedAt: '',
+        currentBpm: 0,
+        tempoSeries: [],
+    },
+    events: [],
+};

package/dist/http/fixtures/sse-reconnect.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fixture: a normal stream interrupted by a `gap` event mid-stream.
+ * Exercises the dashboard's reconnect / re-fetch flow — when a `gap`
+ * arrives, consumers SHOULD drop their cache and re-pull
+ * `/v1/state/:ensemble` (per SSE-PROTOCOL.md §7.2).
+ */
+import type { FixtureScenario } from './index';
+export declare const sseReconnect: FixtureScenario;

package/dist/http/fixtures/sse-reconnect.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sseReconnect = void 0;
+const constants_1 = require("./constants");
+const ENSEMBLE = 'demo-reconnect';
+exports.sseReconnect = {
+    name: 'sse-reconnect',
+    description: 'Two chat events, then a gap (overflow), then more chat. Tests the dashboard reconnect / re-fetch path.',
+    snapshot: {
+        v: 1,
+        ensemble: ENSEMBLE,
+        capturedAt: '2026-04-27T00:00:00.000Z',
+        lastEventId: `${constants_1.FIXTURE_BOOT_EPOCH}:0`,
+        state: 'online',
+        hasConductor: true,
+        flags: { paused: false, held: false },
+        players: [{
+                playerId: 'conductor',
+                ensemble: ENSEMBLE,
+                hostname: 'demo-host',
+                isConductor: true,
+                agentType: 'claude',
+                phase: 'attached',
+                part: 'Reconnect demo',
+                workDir: '/repo/demo',
+            }],
+        schedules: [],
+        chat: { messages: [], total: 0, hasMore: false },
+        hostProfiles: {},
+        description: '',
+        startedAt: '',
+        currentBpm: 0,
+        tempoSeries: [],
+    },
+    events: [
+        {
+            v: 1,
+            type: 'chat.appended',
+            eventId: `${constants_1.FIXTURE_BOOT_EPOCH}:1`,
+            payload: {
+                id: 'msg-1', from: 'maestro', to: 'conductor',
+                text: 'Hello before the gap.',
+                timestamp: '2026-04-27T00:00:01.000Z',
+                role: 'maestro-out',
+            },
+        },
+        {
+            v: 1,
+            type: 'chat.appended',
+            eventId: `${constants_1.FIXTURE_BOOT_EPOCH}:2`,
+            payload: {
+                id: 'msg-2', from: 'conductor', to: 'maestro',
+                text: 'About to drop a gap...',
+                timestamp: '2026-04-27T00:00:02.000Z',
+                role: 'conductor-in',
+            },
+        },
+        {
+            v: 1,
+            type: 'gap',
+            eventId: `${constants_1.FIXTURE_BOOT_EPOCH}:3`,
+            payload: { from: `${constants_1.FIXTURE_BOOT_EPOCH}:2`, to: `${constants_1.FIXTURE_BOOT_EPOCH}:50`, reason: 'overflow' },
+        },
+        {
+            v: 1,
+            type: 'chat.appended',
+            eventId: `${constants_1.FIXTURE_BOOT_EPOCH}:51`,
+            payload: {
+                id: 'msg-51', from: 'maestro', to: 'conductor',
+                text: 'After the gap — dashboard should have re-fetched.',
+                timestamp: '2026-04-27T00:00:05.000Z',
+                role: 'maestro-out',
+            },
+        },
+    ],
+    eventCadenceMs: 250,
+};

package/dist/http/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Barrel re-exports for the daemon HTTP/SSE event source (#94, #95).
+ *
+ * - PR-1 (this file's first revision): snapshot endpoints + bearer/CORS
+ *   middleware + port-file lifecycle. Drives `/v1/health`, `/v1/ensembles`,
+ *   `/v1/state/:ensemble`, `/v1/hosts`.
+ * - PR-2 (future): `EnsembleEventBus`, ring buffer, `/v1/events*` SSE.
+ * - PR-3 (future, eng-4): `TempoClient.subscribe` AsyncIterable.
+ *
+ * Public surface kept narrow on purpose — implementation modules are the
+ * source of truth.
+ */
+export { startHttpServer, DEFAULT_BIND_ADDR, DEFAULT_PORT, type HttpServerOptions, type HttpServerHandle, } from './server';
+export { PR1_SENTINEL_EVENT_ID, SSE_EVENT_KINDS, type SseEventKind, type TempoEvent, type SubscribeOptions, type SubscribeTopic, type EnsembleStateV1, type PlayerSummaryV1, type HealthV1, } from './event-types';
+export { DAEMON_PORT_PATH, readPortFile, removePortFile, writePortFileAtomic, } from './port-file';
+export { buildEnsembleSnapshot, EnsembleNotFoundError, toPlayerSummaryV1, SNAPSHOT_CHAT_LIMIT, } from './snapshot';
+export { AggregateRunner, DEFAULT_POLL_INTERVAL_MS, canonicalize, hashOf, diffEnsembleSet, diffEnsembleSnapshot, diffHostProfiles, } from './aggregate';
+export { EnsembleEventBus, type EventBus, type Subscription, type BusEvent, type SubscribeOpts, type TopicCategory, topicOf, startHeartbeatTimer, DEFAULT_HEARTBEAT_MS, } from './event-bus';
+export { SeqAllocator, formatEventId, parseEventId, compareEventIds, type EventIdTuple, } from './event-id';
+export { ConnectionCap, DEFAULT_MAX_CONNECTIONS, PER_CONNECTION_BUFFER_LIMIT, frameSseEvent, frameSseComment, parseTopicQuery, handleSseRequest, } from './sse-handler';
+export { createRingBuffer, RING_BUFFER_CAPACITY, type RingBuffer, } from './ring-buffer';

package/dist/http/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RING_BUFFER_CAPACITY = exports.createRingBuffer = exports.handleSseRequest = exports.parseTopicQuery = exports.frameSseComment = exports.frameSseEvent = exports.PER_CONNECTION_BUFFER_LIMIT = exports.DEFAULT_MAX_CONNECTIONS = exports.ConnectionCap = exports.compareEventIds = exports.parseEventId = exports.formatEventId = exports.SeqAllocator = exports.DEFAULT_HEARTBEAT_MS = exports.startHeartbeatTimer = exports.topicOf = exports.EnsembleEventBus = exports.diffHostProfiles = exports.diffEnsembleSnapshot = exports.diffEnsembleSet = exports.hashOf = exports.canonicalize = exports.DEFAULT_POLL_INTERVAL_MS = exports.AggregateRunner = exports.SNAPSHOT_CHAT_LIMIT = exports.toPlayerSummaryV1 = exports.EnsembleNotFoundError = exports.buildEnsembleSnapshot = exports.writePortFileAtomic = exports.removePortFile = exports.readPortFile = exports.DAEMON_PORT_PATH = exports.SSE_EVENT_KINDS = exports.PR1_SENTINEL_EVENT_ID = exports.DEFAULT_PORT = exports.DEFAULT_BIND_ADDR = exports.startHttpServer = void 0;
+/**
+ * Barrel re-exports for the daemon HTTP/SSE event source (#94, #95).
+ *
+ * - PR-1 (this file's first revision): snapshot endpoints + bearer/CORS
+ *   middleware + port-file lifecycle. Drives `/v1/health`, `/v1/ensembles`,
+ *   `/v1/state/:ensemble`, `/v1/hosts`.
+ * - PR-2 (future): `EnsembleEventBus`, ring buffer, `/v1/events*` SSE.
+ * - PR-3 (future, eng-4): `TempoClient.subscribe` AsyncIterable.
+ *
+ * Public surface kept narrow on purpose — implementation modules are the
+ * source of truth.
+ */
+var server_1 = require("./server");
+Object.defineProperty(exports, "startHttpServer", { enumerable: true, get: function () { return server_1.startHttpServer; } });
+Object.defineProperty(exports, "DEFAULT_BIND_ADDR", { enumerable: true, get: function () { return server_1.DEFAULT_BIND_ADDR; } });
+Object.defineProperty(exports, "DEFAULT_PORT", { enumerable: true, get: function () { return server_1.DEFAULT_PORT; } });
+var event_types_1 = require("./event-types");
+Object.defineProperty(exports, "PR1_SENTINEL_EVENT_ID", { enumerable: true, get: function () { return event_types_1.PR1_SENTINEL_EVENT_ID; } });
+Object.defineProperty(exports, "SSE_EVENT_KINDS", { enumerable: true, get: function () { return event_types_1.SSE_EVENT_KINDS; } });
+var port_file_1 = require("./port-file");
+Object.defineProperty(exports, "DAEMON_PORT_PATH", { enumerable: true, get: function () { return port_file_1.DAEMON_PORT_PATH; } });
+Object.defineProperty(exports, "readPortFile", { enumerable: true, get: function () { return port_file_1.readPortFile; } });
+Object.defineProperty(exports, "removePortFile", { enumerable: true, get: function () { return port_file_1.removePortFile; } });
+Object.defineProperty(exports, "writePortFileAtomic", { enumerable: true, get: function () { return port_file_1.writePortFileAtomic; } });
+var snapshot_1 = require("./snapshot");
+Object.defineProperty(exports, "buildEnsembleSnapshot", { enumerable: true, get: function () { return snapshot_1.buildEnsembleSnapshot; } });
+Object.defineProperty(exports, "EnsembleNotFoundError", { enumerable: true, get: function () { return snapshot_1.EnsembleNotFoundError; } });
+Object.defineProperty(exports, "toPlayerSummaryV1", { enumerable: true, get: function () { return snapshot_1.toPlayerSummaryV1; } });
+Object.defineProperty(exports, "SNAPSHOT_CHAT_LIMIT", { enumerable: true, get: function () { return snapshot_1.SNAPSHOT_CHAT_LIMIT; } });
+var aggregate_1 = require("./aggregate");
+Object.defineProperty(exports, "AggregateRunner", { enumerable: true, get: function () { return aggregate_1.AggregateRunner; } });
+Object.defineProperty(exports, "DEFAULT_POLL_INTERVAL_MS", { enumerable: true, get: function () { return aggregate_1.DEFAULT_POLL_INTERVAL_MS; } });
+Object.defineProperty(exports, "canonicalize", { enumerable: true, get: function () { return aggregate_1.canonicalize; } });
+Object.defineProperty(exports, "hashOf", { enumerable: true, get: function () { return aggregate_1.hashOf; } });
+Object.defineProperty(exports, "diffEnsembleSet", { enumerable: true, get: function () { return aggregate_1.diffEnsembleSet; } });
+Object.defineProperty(exports, "diffEnsembleSnapshot", { enumerable: true, get: function () { return aggregate_1.diffEnsembleSnapshot; } });
+Object.defineProperty(exports, "diffHostProfiles", { enumerable: true, get: function () { return aggregate_1.diffHostProfiles; } });
+var event_bus_1 = require("./event-bus");
+Object.defineProperty(exports, "EnsembleEventBus", { enumerable: true, get: function () { return event_bus_1.EnsembleEventBus; } });
+Object.defineProperty(exports, "topicOf", { enumerable: true, get: function () { return event_bus_1.topicOf; } });
+Object.defineProperty(exports, "startHeartbeatTimer", { enumerable: true, get: function () { return event_bus_1.startHeartbeatTimer; } });
+Object.defineProperty(exports, "DEFAULT_HEARTBEAT_MS", { enumerable: true, get: function () { return event_bus_1.DEFAULT_HEARTBEAT_MS; } });
+var event_id_1 = require("./event-id");
+Object.defineProperty(exports, "SeqAllocator", { enumerable: true, get: function () { return event_id_1.SeqAllocator; } });
+Object.defineProperty(exports, "formatEventId", { enumerable: true, get: function () { return event_id_1.formatEventId; } });
+Object.defineProperty(exports, "parseEventId", { enumerable: true, get: function () { return event_id_1.parseEventId; } });
+Object.defineProperty(exports, "compareEventIds", { enumerable: true, get: function () { return event_id_1.compareEventIds; } });
+var sse_handler_1 = require("./sse-handler");
+Object.defineProperty(exports, "ConnectionCap", { enumerable: true, get: function () { return sse_handler_1.ConnectionCap; } });
+Object.defineProperty(exports, "DEFAULT_MAX_CONNECTIONS", { enumerable: true, get: function () { return sse_handler_1.DEFAULT_MAX_CONNECTIONS; } });
+Object.defineProperty(exports, "PER_CONNECTION_BUFFER_LIMIT", { enumerable: true, get: function () { return sse_handler_1.PER_CONNECTION_BUFFER_LIMIT; } });
+Object.defineProperty(exports, "frameSseEvent", { enumerable: true, get: function () { return sse_handler_1.frameSseEvent; } });
+Object.defineProperty(exports, "frameSseComment", { enumerable: true, get: function () { return sse_handler_1.frameSseComment; } });
+Object.defineProperty(exports, "parseTopicQuery", { enumerable: true, get: function () { return sse_handler_1.parseTopicQuery; } });
+Object.defineProperty(exports, "handleSseRequest", { enumerable: true, get: function () { return sse_handler_1.handleSseRequest; } });
+var ring_buffer_1 = require("./ring-buffer");
+Object.defineProperty(exports, "createRingBuffer", { enumerable: true, get: function () { return ring_buffer_1.createRingBuffer; } });
+Object.defineProperty(exports, "RING_BUFFER_CAPACITY", { enumerable: true, get: function () { return ring_buffer_1.RING_BUFFER_CAPACITY; } });

package/dist/http/port-file.d.ts

@@ -0,0 +1,22 @@
+/** Default location, anchored to `~/.agent-tempo/`. */
+export declare const DAEMON_PORT_PATH: string;
+/**
+ * Atomically write `port` (decimal ASCII, no trailing newline) to
+ * `filePath`. Identical retry shape to `writePidFileAtomic` so Windows
+ * EPERM/EBUSY/EACCES from antivirus scanners don't crash boot.
+ *
+ * Exported so tests can target an isolated path.
+ */
+export declare function writePortFileAtomic(filePath: string, port: number): Promise<void>;
+/**
+ * Best-effort `unlink`. Silent when the file is missing — consumers
+ * cleaning up a half-booted daemon should NOT see a "no such file" stack
+ * trace just because the port file never made it to disk.
+ */
+export declare function removePortFile(filePath?: string): void;
+/**
+ * Read the current port from disk, or `null` when the file is missing,
+ * empty, or not a parseable port. Used by clients (TempoClient HTTP
+ * transport, `agent-tempo daemon status`, …) to discover the live port.
+ */
+export declare function readPortFile(filePath?: string): number | null;

package/dist/http/port-file.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAEMON_PORT_PATH = void 0;
+exports.writePortFileAtomic = writePortFileAtomic;
+exports.removePortFile = removePortFile;
+exports.readPortFile = readPortFile;
+/**
+ * `~/.agent-tempo/daemon.port` — atomic write + cleanup helpers.
+ *
+ * The TUI / CLI / web dashboard read this file to discover the daemon's
+ * bound HTTP port without any out-of-band config. SSE-PROTOCOL.md §1
+ * makes the file part of the public contract, so its lifecycle MUST be:
+ *
+ *   1. Atomic write on daemon boot, after the HTTP listener is `listening`
+ *      (so a racing reader who polls during startup either sees the prior
+ *      file or the new one — never a half-written one).
+ *   2. Removal on graceful shutdown. Best-effort on crash (a stale file
+ *      points at a dead port; consumers MUST also tolerate ECONNREFUSED).
+ *
+ * Both behaviours mirror the existing PID-file pattern in
+ * `src/daemon.ts`. Extracted as its own module so HTTP-server tests
+ * can exercise the contract without booting the daemon.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const promises_1 = require("timers/promises");
+const config_1 = require("../config");
+/** Default location, anchored to `~/.agent-tempo/`. */
+exports.DAEMON_PORT_PATH = path.join(config_1.AGENT_TEMPO_HOME, 'daemon.port');
+/**
+ * Atomically write `port` (decimal ASCII, no trailing newline) to
+ * `filePath`. Identical retry shape to `writePidFileAtomic` so Windows
+ * EPERM/EBUSY/EACCES from antivirus scanners don't crash boot.
+ *
+ * Exported so tests can target an isolated path.
+ */
+async function writePortFileAtomic(filePath, port) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`writePortFileAtomic: invalid port ${port}`);
+    }
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, String(port));
+    const retryCodes = new Set(['EPERM', 'EBUSY', 'EACCES']);
+    const backoffs = [50, 100, 200, 400]; // ≤ 750 ms total
+    let lastErr;
+    for (let attempt = 0; attempt <= backoffs.length; attempt++) {
+        try {
+            fs.renameSync(tmp, filePath);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            const code = err.code;
+            if (!code || !retryCodes.has(code) || attempt === backoffs.length) {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch { /* ignore */ }
+                throw err;
+            }
+            await (0, promises_1.setTimeout)(backoffs[attempt]);
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Best-effort `unlink`. Silent when the file is missing — consumers
+ * cleaning up a half-booted daemon should NOT see a "no such file" stack
+ * trace just because the port file never made it to disk.
+ */
+function removePortFile(filePath = exports.DAEMON_PORT_PATH) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { /* ignore */ }
+}
+/**
+ * Read the current port from disk, or `null` when the file is missing,
+ * empty, or not a parseable port. Used by clients (TempoClient HTTP
+ * transport, `agent-tempo daemon status`, …) to discover the live port.
+ */
+function readPortFile(filePath = exports.DAEMON_PORT_PATH) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const port = Number(trimmed);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    return port;
+}

package/dist/http/responses.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tiny response helpers. Wrap `http.ServerResponse` writes so handlers
+ * stay declarative (`return jsonResponse(res, 200, body)`) and we have
+ * one place to enforce the §1 contract: UTF-8, JSON content-type,
+ * `Cache-Control: no-store` (snapshot endpoints reflect live state).
+ */
+import type { ServerResponse } from 'http';
+/** Snapshot Content-Type per SSE-PROTOCOL.md §1. */
+export declare const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+/**
+ * Write a JSON response. Always serializes via `JSON.stringify`; consumers
+ * that need a custom replacer should encode upstream and use
+ * {@link rawJsonResponse}.
+ */
+export declare function jsonResponse(res: ServerResponse, status: number, body: unknown, extraHeaders?: Record<string, string>): void;
+/**
+ * Write a pre-serialized JSON string (caller has already stringified).
+ * Used by tests that want to verify byte-exact output.
+ */
+export declare function rawJsonResponse(res: ServerResponse, status: number, body: string, extraHeaders?: Record<string, string>): void;
+/** SSE-PROTOCOL.md §9 — error response shape. */
+export interface HttpErrorBody {
+    error: string;
+    /** Optional context, e.g. `{ ensemble: 'foo' }`. */
+    [key: string]: unknown;
+}
+export declare function errorResponse(res: ServerResponse, status: number, body: HttpErrorBody, extraHeaders?: Record<string, string>): void;

package/dist/http/responses.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON_CONTENT_TYPE = void 0;
+exports.jsonResponse = jsonResponse;
+exports.rawJsonResponse = rawJsonResponse;
+exports.errorResponse = errorResponse;
+/** Snapshot Content-Type per SSE-PROTOCOL.md §1. */
+exports.JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+/**
+ * Write a JSON response. Always serializes via `JSON.stringify`; consumers
+ * that need a custom replacer should encode upstream and use
+ * {@link rawJsonResponse}.
+ */
+function jsonResponse(res, status, body, extraHeaders = {}) {
+    const payload = Buffer.from(JSON.stringify(body), 'utf8');
+    res.writeHead(status, {
+        'Content-Type': exports.JSON_CONTENT_TYPE,
+        'Content-Length': payload.length,
+        'Cache-Control': 'no-store',
+        ...extraHeaders,
+    });
+    res.end(payload);
+}
+/**
+ * Write a pre-serialized JSON string (caller has already stringified).
+ * Used by tests that want to verify byte-exact output.
+ */
+function rawJsonResponse(res, status, body, extraHeaders = {}) {
+    const payload = Buffer.from(body, 'utf8');
+    res.writeHead(status, {
+        'Content-Type': exports.JSON_CONTENT_TYPE,
+        'Content-Length': payload.length,
+        'Cache-Control': 'no-store',
+        ...extraHeaders,
+    });
+    res.end(payload);
+}
+function errorResponse(res, status, body, extraHeaders = {}) {
+    jsonResponse(res, status, body, extraHeaders);
+}