@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/session-hub.js

@@ -0,0 +1,291 @@
+/**
+ * SessionHub — session-scoped fan-out + re-attach for in-flight chat turns.
+ *
+ * The problem it solves (issue #54): a turn's stream used to be bound to the ONE
+ * socket that sent `chat:send`. Frames were written straight to that socket and
+ * silently dropped whenever it wasn't OPEN. So if the socket died mid-turn (idle
+ * half-open drop, laptop sleep, wifi change, the client's own auto-reconnect
+ * swapping sockets), every remaining frame of the running turn was lost — the
+ * live stream stalled and only a full page reload (which re-hydrates from the
+ * persisted transcript) recovered it.
+ *
+ * The hub decouples a turn from any single socket:
+ *
+ *  - Every emitted frame is buffered on the turn and stamped with a per-turn,
+ *    monotonic `seq`.
+ *  - Frames fan out to the turn's ORIGIN socket PLUS every socket currently
+ *    subscribed to the turn's session (dead sockets are skipped, not dropped-
+ *    on-the-floor-permanently — a live one still gets the frame).
+ *  - A reconnecting client re-`attach`es to the session and replays exactly the
+ *    frames it missed (everything with `seq` greater than the last it applied),
+ *    so the stream resumes seamlessly with no gap and no duplication.
+ *
+ * A just-completed turn's buffer is retained briefly ({@link COMPLETED_TTL_MS})
+ * so a client that reconnects right at the end still receives the tail frames
+ * (including the terminal `chat:complete`) rather than hanging "streaming"
+ * forever.
+ *
+ * The hub is transport-shaped but transport-agnostic: it only needs a socket it
+ * can check `readyState` on and `send` a JSON string to (the `HubSocket`
+ * minimal interface), so it is unit-testable without a real WebSocket.
+ */
+/**
+ * Max frames retained per turn. A turn is a dozen assistant messages + tool
+ * calls → low hundreds of frames typically; 4000 is generous headroom while
+ * bounding memory. Overflow trims the oldest frames and a re-attach that needs
+ * them falls back to a transcript resync (correctness preserved, live-ness lost
+ * only in the pathological case).
+ */
+const MAX_FRAMES = 4000;
+/** How long a completed turn's buffer lingers so an end-of-turn reconnect still gets the tail. */
+export const COMPLETED_TTL_MS = 60_000;
+export class SessionHub {
+    /** sessionId → the current (running or recently-completed) turn for that session. */
+    bySession = new Map();
+    /** sessionId → sockets attached to it (fan-out targets beyond the origin). */
+    subscribers = new Map();
+    /**
+     * Notified on every running-state transition (turn start / stop) so the WS
+     * layer can broadcast a `chat:active` signal to clients — powering the Stop
+     * button restore (#52) and streaming indicators (#53). Set by the WS layer.
+     */
+    onActive = null;
+    /**
+     * Begin tracking a turn. Pass `sessionId` when it's already known (a resumed
+     * chat / a slash command) so the turn is re-attachable from its very first
+     * frame; omit it for a brand-new chat and call {@link TurnHandle.setSession}
+     * once the id arrives on the stream.
+     */
+    startTurn(projectSlug, origin, sessionId) {
+        const turn = {
+            projectSlug,
+            sessionId: null,
+            jobId: null,
+            origin,
+            frames: [],
+            baseSeq: 0,
+            nextSeq: 0,
+            running: true,
+            evictTimer: null,
+        };
+        const handle = new TurnHandle(this, turn);
+        if (sessionId)
+            this.register(turn, sessionId);
+        return handle;
+    }
+    /** Add a socket to a session's fan-out set (idempotent). */
+    subscribe(sessionId, socket) {
+        let set = this.subscribers.get(sessionId);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(sessionId, set);
+        }
+        set.add(socket);
+    }
+    /**
+     * Attach a (re)connecting socket to a session and, when `wantReplay`, catch it
+     * up on a still-live turn by replaying every buffered frame after `afterSeq`.
+     *
+     * `wantReplay` MUST be false for a fresh mount (one that also hydrates the
+     * transcript over REST) so buffered frames don't duplicate the transcript; it
+     * is true only for a genuine reconnect of a socket that was mid-turn, where
+     * `afterSeq` is the last seq the client applied and the replay is exactly the
+     * gap. Replays are written straight to `socket` (not the whole fan-out).
+     */
+    attach(sessionId, socket, opts) {
+        this.subscribe(sessionId, socket);
+        const turn = this.bySession.get(sessionId);
+        if (!turn || !opts.wantReplay)
+            return { status: "none" };
+        const from = opts.afterSeq + 1;
+        if (from < turn.baseSeq) {
+            // The gap the client needs has been trimmed — it must re-hydrate instead.
+            return { status: "resync", projectSlug: turn.projectSlug };
+        }
+        let n = 0;
+        for (const f of turn.frames) {
+            if (f.seq >= from) {
+                SessionHub.write(socket, f.msg);
+                n++;
+            }
+        }
+        return { status: "replayed", frames: n };
+    }
+    /** Drop a socket from every session's fan-out set (call on socket close). */
+    unsubscribeSocket(socket) {
+        for (const [id, set] of this.subscribers) {
+            if (set.delete(socket) && set.size === 0)
+                this.subscribers.delete(id);
+        }
+    }
+    /** Whether a session currently has a RUNNING turn (used by the active-turns signal). */
+    isRunning(sessionId) {
+        return this.bySession.get(sessionId)?.running === true;
+    }
+    /**
+     * Send a one-off control frame to every socket attached to a session — its
+     * (recently-)tracked turn's origin plus every subscribed socket (#245). Unlike
+     * {@link emit} this is not seq-stamped or buffered; it's for out-of-band signals
+     * like `chat:queued_flushed` that must reach a client that reconnected on a new
+     * socket after the origin died.
+     */
+    broadcast(sessionId, msg) {
+        const set = new Set();
+        const turn = this.bySession.get(sessionId);
+        if (turn?.origin)
+            set.add(turn.origin);
+        const subs = this.subscribers.get(sessionId);
+        if (subs)
+            for (const s of subs)
+                set.add(s);
+        for (const s of set)
+            SessionHub.write(s, msg);
+    }
+    // --- internals, driven by TurnHandle -------------------------------------
+    /** Whether a session currently has a RUNNING turn plus its job id, or null. */
+    activeInfo(sessionId) {
+        const turn = this.bySession.get(sessionId);
+        if (!turn || !turn.running)
+            return null;
+        return { sessionId, projectSlug: turn.projectSlug, jobId: turn.jobId, running: true };
+    }
+    /** Snapshot of every session with a running turn (for a newly-connected client). */
+    runningSessions() {
+        const out = [];
+        for (const [sessionId, turn] of this.bySession) {
+            if (turn.running) {
+                out.push({ sessionId, projectSlug: turn.projectSlug, jobId: turn.jobId, running: true });
+            }
+        }
+        return out;
+    }
+    /** Register a turn under its resolved session id, evicting any prior turn there. */
+    register(turn, sessionId) {
+        if (turn.sessionId === sessionId)
+            return;
+        if (turn.sessionId)
+            this.bySession.delete(turn.sessionId);
+        turn.sessionId = sessionId;
+        const prev = this.bySession.get(sessionId);
+        if (prev && prev !== turn)
+            this.evict(prev);
+        this.bySession.set(sessionId, turn);
+        // A turn becomes visible-as-running the moment its session id is known.
+        if (turn.running)
+            this.fireActive(turn);
+    }
+    /** Stamp `seq`, buffer (with trim), and fan out to origin + subscribers. */
+    emit(turn, base) {
+        const seq = turn.nextSeq++;
+        const stamped = {
+            type: base.type,
+            payload: { ...base.payload, seq },
+        };
+        turn.frames.push({ seq, msg: stamped });
+        if (turn.frames.length > MAX_FRAMES) {
+            turn.frames.shift();
+            turn.baseSeq = turn.frames[0]?.seq ?? seq;
+        }
+        for (const socket of this.recipients(turn))
+            SessionHub.write(socket, stamped);
+    }
+    /** Mark a turn finished; retain its buffer briefly for an end-of-turn reconnect. */
+    end(turn) {
+        turn.running = false;
+        if (turn.sessionId) {
+            this.fireActive(turn);
+            turn.evictTimer = setTimeout(() => this.evict(turn), COMPLETED_TTL_MS);
+            turn.evictTimer.unref?.();
+        }
+    }
+    /**
+     * Re-broadcast a running turn's active state once its jobId becomes known, so
+     * clients can arm the Stop button before the first content frame (Paddock#111).
+     * No-op if the turn isn't running or its session id isn't resolved yet (a new
+     * chat learns the jobId together with its session id on the first frame).
+     */
+    jobIdResolved(turn) {
+        if (turn.running)
+            this.fireActive(turn);
+    }
+    fireActive(turn) {
+        if (!this.onActive || !turn.sessionId)
+            return;
+        this.onActive({
+            sessionId: turn.sessionId,
+            projectSlug: turn.projectSlug,
+            jobId: turn.jobId,
+            running: turn.running,
+        });
+    }
+    recipients(turn) {
+        const set = new Set();
+        // A client-less woken turn (Paddock#111) has no origin; frames are still
+        // buffered for replay, they just have no live origin socket to fan out to.
+        if (turn.origin)
+            set.add(turn.origin);
+        if (turn.sessionId) {
+            const subs = this.subscribers.get(turn.sessionId);
+            if (subs)
+                for (const s of subs)
+                    set.add(s);
+        }
+        return set;
+    }
+    evict(turn) {
+        if (turn.evictTimer) {
+            clearTimeout(turn.evictTimer);
+            turn.evictTimer = null;
+        }
+        if (turn.sessionId && this.bySession.get(turn.sessionId) === turn) {
+            this.bySession.delete(turn.sessionId);
+        }
+    }
+    static write(socket, msg) {
+        if (socket.readyState !== socket.OPEN)
+            return;
+        try {
+            socket.send(JSON.stringify(msg));
+        }
+        catch {
+            /* a socket that throws on send is effectively gone; the reconnect path recovers it */
+        }
+    }
+}
+/**
+ * A per-turn handle the WS layer drives: stamp/fan-out frames via {@link emit},
+ * learn the session id via {@link setSession}, and finish via {@link end}.
+ */
+export class TurnHandle {
+    hub;
+    turn;
+    constructor(hub, turn) {
+        this.hub = hub;
+        this.turn = turn;
+    }
+    get jobId() {
+        return this.turn.jobId;
+    }
+    setJobId(id) {
+        this.turn.jobId = id;
+        // Push the now-known jobId to attached clients immediately (via chat:active),
+        // so the Stop button is ARMED even while the model is still "thinking" and no
+        // content frame has yet carried the jobId in its routing metadata. Without
+        // this, Stop silently no-ops during the (often long) pre-output phase because
+        // the client has no jobId to cancel — the original "Stop does nothing" bug
+        // (Paddock#111). Fixes both drive modes (batch + session).
+        this.hub.jobIdResolved(this.turn);
+    }
+    /** Register (or move) this turn under its now-known session id. Idempotent. */
+    setSession(sessionId) {
+        this.hub.register(this.turn, sessionId);
+    }
+    /** Buffer + fan out one frame to every live socket attached to this turn's session. */
+    emit(base) {
+        this.hub.emit(this.turn, base);
+    }
+    /** Finish the turn (buffer retained briefly for a late reconnect). */
+    end() {
+        this.hub.end(this.turn);
+    }
+}

package/packages/server/dist/spawn-capability.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Spawn capability — depth-gated self-MCP injection (issue #262 / DD-3, DD-5).
+ *
+ * A1 (#261) threaded an `origin` + spawn `depth` marker through every
+ * server-initiated turn and persisted it to {@link RunProvenanceStore}. B1 (this
+ * ticket) reads that `depth` to decide whether a SPAWNED turn is handed the
+ * self-management MCP — crucially its WRITE tools, so `send_message` exists and a
+ * child can finally report back to its parent (impossible today, where a spawned
+ * chat gets `send_file` only).
+ *
+ * ── The bound ────────────────────────────────────────────────────────────────
+ * A spawned/scheduled turn running in a chat at depth `d` receives the self-MCP
+ * iff `d <= maxSpawnDepth`:
+ *
+ *   maxSpawnDepth = 0  → no spawned child gets the self-MCP (send_file only).
+ *                        This reproduces EXACTLY today's behaviour.
+ *   maxSpawnDepth = 1  → depth-1 children DO get it (a manager's children can
+ *                        report back AND spawn), but depth-2 grandchildren do NOT.
+ *                        This is the DEFAULT — the manager→children→report-back
+ *                        pattern works out of the box while the tree can't run away.
+ *   maxSpawnDepth = n  → the tree may grow n spawn-hops deep before the tools stop.
+ *
+ * The human/scheduled ROOT (depth 0) is NOT gated here — it keeps today's
+ * instance-flag gating (`selfMcpEnabled`/`selfMcpWriteEnabled`) on the socket path.
+ * The gate only governs the server-initiated (`startAgentTurn`) path.
+ *
+ * ── Why `<=` and not `<` ─────────────────────────────────────────────────────
+ * The gate is evaluated at the CHILD, using the child's OWN depth `d` (that's the
+ * depth `startAgentTurn` knows). "A depth-`d` child may act" with `d <= maxSpawnDepth`
+ * is the same bound as the equivalent parent-side phrasing "a depth-`(d-1)` parent
+ * may spawn" with `(d-1) < maxSpawnDepth`, since a child's depth is always its
+ * parent's depth + 1. We evaluate it at the child, so the comparison is `<=`.
+ * With the default `1`, a depth-1 child satisfies `1 <= 1` and gets the tools;
+ * its depth-2 grandchild fails `2 <= 1` and does not — the bound descends because
+ * every child stamped by a tool-equipped parent is one hop deeper.
+ *
+ * ── Config (DD-5, the `driveMode` pattern) ───────────────────────────────────
+ * `maxSpawnDepth` is an instance default (`PADDOCK_MAX_SPAWN_DEPTH`, YAML later
+ * per #270) with a per-project override (`project.yaml` → Settings). An absent /
+ * invalid override inherits the instance default, resolved at dispatch by
+ * {@link resolveMaxSpawnDepth} — never baked into the DTO (mirrors how `driveMode`
+ * resolves against `cfg.driveMode`).
+ */
+/**
+ * Default max spawn depth (Ed, DD-3 decision 2): `1`. A manager's direct children
+ * get the self-MCP write tools (report-back + spawn), grandchildren do not.
+ */
+export declare const DEFAULT_MAX_SPAWN_DEPTH = 1;
+/**
+ * Hard upper bound on `maxSpawnDepth` (guards the UI slider + PATCH validation +
+ * config loader). Deep trees are deliberately allowed but not unboundedly — a
+ * runaway config can't ask for a thousand-deep fan-out. 8 hops is far past any
+ * real manager pattern.
+ */
+export declare const MAX_SPAWN_DEPTH_LIMIT = 8;
+/**
+ * Whether `n` is a valid `maxSpawnDepth`: a non-negative integer within bounds.
+ * `0` is valid (it disables spawned self-MCP entirely — today's behaviour).
+ */
+export declare function isValidMaxSpawnDepth(n: unknown): n is number;
+/**
+ * Resolve the effective `maxSpawnDepth` for a dispatch: a valid per-project
+ * override wins; otherwise inherit the instance default. Mirrors how `driveMode`
+ * resolves (`project.driveMode ?? cfg.driveMode`) — the override is carried
+ * on disk only when set, so an absent value transparently inherits the instance
+ * (and, later, a YAML file) default. A malformed override is ignored rather than
+ * fatal (defensive: a hand-edited `project.yaml` can't wedge dispatch).
+ */
+export declare function resolveMaxSpawnDepth(override: number | undefined, instanceDefault: number): number;
+/**
+ * The core gate: does a spawned/scheduled turn running in a chat at `depth`
+ * receive the self-MCP? `depth <= maxSpawnDepth` (see the module header for why
+ * `<=`). Both operands are read defensively so a corrupt marker can't throw at the
+ * dispatch hot path — a negative/NaN depth is treated as never-injectable.
+ */
+export declare function spawnedTurnGetsSelfMcp(depth: number, maxSpawnDepth: number): boolean;
+/** The full injection decision for a server-initiated (spawned) turn. */
+export interface SpawnedSelfMcpDecision {
+    /** Inject the self-MCP at all (read tools, and — if {@link includeWrite} — write). */
+    inject: boolean;
+    /** Include the WRITE tools (create/fork/`send_message`) so the child can report back. */
+    includeWrite: boolean;
+}
+/**
+ * The COMPLETE gate for whether a spawned/scheduled turn is handed the self-MCP,
+ * factored out so the exact rule is unit-tested rather than buried in ws.ts.
+ * A spawned turn gets the self-MCP iff the instance opted in
+ * (`selfMcpEnabled`) AND its depth is within the bound
+ * ({@link spawnedTurnGetsSelfMcp}). The WRITE tools are further gated by the
+ * instance write opt-in — in practice always on when a spawn is reachable (a spawn
+ * only happens because a parent already had the write tools), but honoured so an
+ * operator who disabled writes gets read-only spawned children too.
+ */
+export declare function spawnedSelfMcpDecision(params: {
+    selfMcpEnabled: boolean;
+    selfMcpWriteEnabled: boolean;
+    depth: number;
+    maxSpawnDepth: number;
+}): SpawnedSelfMcpDecision;

package/packages/server/dist/spawn-capability.js

@@ -0,0 +1,106 @@
+/**
+ * Spawn capability — depth-gated self-MCP injection (issue #262 / DD-3, DD-5).
+ *
+ * A1 (#261) threaded an `origin` + spawn `depth` marker through every
+ * server-initiated turn and persisted it to {@link RunProvenanceStore}. B1 (this
+ * ticket) reads that `depth` to decide whether a SPAWNED turn is handed the
+ * self-management MCP — crucially its WRITE tools, so `send_message` exists and a
+ * child can finally report back to its parent (impossible today, where a spawned
+ * chat gets `send_file` only).
+ *
+ * ── The bound ────────────────────────────────────────────────────────────────
+ * A spawned/scheduled turn running in a chat at depth `d` receives the self-MCP
+ * iff `d <= maxSpawnDepth`:
+ *
+ *   maxSpawnDepth = 0  → no spawned child gets the self-MCP (send_file only).
+ *                        This reproduces EXACTLY today's behaviour.
+ *   maxSpawnDepth = 1  → depth-1 children DO get it (a manager's children can
+ *                        report back AND spawn), but depth-2 grandchildren do NOT.
+ *                        This is the DEFAULT — the manager→children→report-back
+ *                        pattern works out of the box while the tree can't run away.
+ *   maxSpawnDepth = n  → the tree may grow n spawn-hops deep before the tools stop.
+ *
+ * The human/scheduled ROOT (depth 0) is NOT gated here — it keeps today's
+ * instance-flag gating (`selfMcpEnabled`/`selfMcpWriteEnabled`) on the socket path.
+ * The gate only governs the server-initiated (`startAgentTurn`) path.
+ *
+ * ── Why `<=` and not `<` ─────────────────────────────────────────────────────
+ * The gate is evaluated at the CHILD, using the child's OWN depth `d` (that's the
+ * depth `startAgentTurn` knows). "A depth-`d` child may act" with `d <= maxSpawnDepth`
+ * is the same bound as the equivalent parent-side phrasing "a depth-`(d-1)` parent
+ * may spawn" with `(d-1) < maxSpawnDepth`, since a child's depth is always its
+ * parent's depth + 1. We evaluate it at the child, so the comparison is `<=`.
+ * With the default `1`, a depth-1 child satisfies `1 <= 1` and gets the tools;
+ * its depth-2 grandchild fails `2 <= 1` and does not — the bound descends because
+ * every child stamped by a tool-equipped parent is one hop deeper.
+ *
+ * ── Config (DD-5, the `driveMode` pattern) ───────────────────────────────────
+ * `maxSpawnDepth` is an instance default (`PADDOCK_MAX_SPAWN_DEPTH`, YAML later
+ * per #270) with a per-project override (`project.yaml` → Settings). An absent /
+ * invalid override inherits the instance default, resolved at dispatch by
+ * {@link resolveMaxSpawnDepth} — never baked into the DTO (mirrors how `driveMode`
+ * resolves against `cfg.driveMode`).
+ */
+/**
+ * Default max spawn depth (Ed, DD-3 decision 2): `1`. A manager's direct children
+ * get the self-MCP write tools (report-back + spawn), grandchildren do not.
+ */
+export const DEFAULT_MAX_SPAWN_DEPTH = 1;
+/**
+ * Hard upper bound on `maxSpawnDepth` (guards the UI slider + PATCH validation +
+ * config loader). Deep trees are deliberately allowed but not unboundedly — a
+ * runaway config can't ask for a thousand-deep fan-out. 8 hops is far past any
+ * real manager pattern.
+ */
+export const MAX_SPAWN_DEPTH_LIMIT = 8;
+/**
+ * Whether `n` is a valid `maxSpawnDepth`: a non-negative integer within bounds.
+ * `0` is valid (it disables spawned self-MCP entirely — today's behaviour).
+ */
+export function isValidMaxSpawnDepth(n) {
+    return (typeof n === "number" &&
+        Number.isInteger(n) &&
+        n >= 0 &&
+        n <= MAX_SPAWN_DEPTH_LIMIT);
+}
+/**
+ * Resolve the effective `maxSpawnDepth` for a dispatch: a valid per-project
+ * override wins; otherwise inherit the instance default. Mirrors how `driveMode`
+ * resolves (`project.driveMode ?? cfg.driveMode`) — the override is carried
+ * on disk only when set, so an absent value transparently inherits the instance
+ * (and, later, a YAML file) default. A malformed override is ignored rather than
+ * fatal (defensive: a hand-edited `project.yaml` can't wedge dispatch).
+ */
+export function resolveMaxSpawnDepth(override, instanceDefault) {
+    if (isValidMaxSpawnDepth(override))
+        return override;
+    return isValidMaxSpawnDepth(instanceDefault) ? instanceDefault : DEFAULT_MAX_SPAWN_DEPTH;
+}
+/**
+ * The core gate: does a spawned/scheduled turn running in a chat at `depth`
+ * receive the self-MCP? `depth <= maxSpawnDepth` (see the module header for why
+ * `<=`). Both operands are read defensively so a corrupt marker can't throw at the
+ * dispatch hot path — a negative/NaN depth is treated as never-injectable.
+ */
+export function spawnedTurnGetsSelfMcp(depth, maxSpawnDepth) {
+    if (typeof depth !== "number" || !Number.isFinite(depth) || depth < 0)
+        return false;
+    if (typeof maxSpawnDepth !== "number" || !Number.isFinite(maxSpawnDepth))
+        return false;
+    return depth <= maxSpawnDepth;
+}
+/**
+ * The COMPLETE gate for whether a spawned/scheduled turn is handed the self-MCP,
+ * factored out so the exact rule is unit-tested rather than buried in ws.ts.
+ * A spawned turn gets the self-MCP iff the instance opted in
+ * (`selfMcpEnabled`) AND its depth is within the bound
+ * ({@link spawnedTurnGetsSelfMcp}). The WRITE tools are further gated by the
+ * instance write opt-in — in practice always on when a spawn is reachable (a spawn
+ * only happens because a parent already had the write tools), but honoured so an
+ * operator who disabled writes gets read-only spawned children too.
+ */
+export function spawnedSelfMcpDecision(params) {
+    const inject = params.selfMcpEnabled &&
+        spawnedTurnGetsSelfMcp(params.depth, params.maxSpawnDepth);
+    return { inject, includeWrite: inject && params.selfMcpWriteEnabled };
+}

package/packages/server/dist/star.d.ts

@@ -0,0 +1,26 @@
+export declare class StarStore {
+    private readonly stateFile;
+    /** In-memory set of starred keys (loaded once, written through on change). */
+    private starred;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `starred` set would let several toggles that begin
+     * before the first `fs.readFile` resolves each build their own set and race on
+     * the assignment — a lost update (last writer wins, dropping the others' keys).
+     */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /** Whether a chat is starred. Non-throwing: any load error reads as false. */
+    isStarred(agent: string, sessionId: string): Promise<boolean>;
+    /**
+     * Set (or clear) a chat's starred flag, persisting the change. Idempotent.
+     * Returns whether the flag actually CHANGED, mirroring `ArchiveStore.setArchived`.
+     */
+    setStarred(agent: string, sessionId: string, starred: boolean): Promise<boolean>;
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    private persist;
+}

package/packages/server/dist/star.js

@@ -0,0 +1,94 @@
+/**
+ * StarStore — a Paddock-side sidecar for the per-chat "starred" (pinned) flag (#373).
+ *
+ * Starring pins a chat to the top of its list without touching its transcript —
+ * the flag is purely presentational metadata, exactly like `archived` (#95).
+ * Starring is ORTHOGONAL to archiving: a chat can be starred whether or not it's
+ * archived, and within BOTH the active list and the Archived section starred
+ * chats float to the top of their own population (the client does the ordering).
+ *
+ * This is a near-verbatim copy of {@link ArchiveStore} — the same tiny JSON
+ * sidecar pattern SweepService uses for its watermark state. Keyed by
+ * `<agent>\0<sessionId>` (NUL-separated) so chats under different agents can
+ * never collide — a NUL can occur in neither an agent name (`keeper-<slug>`)
+ * nor a UUID. Only starred entries are stored (an unstar deletes the
+ * key), keeping the file compact. Unlike ArchiveStore there is NO lifecycle event
+ * — starring fires no hooks.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "star-state.json";
+/** Separator in a storage key; a NUL can't occur in an agent name or a UUID. */
+const KEY_SEP = "\u0000";
+/** Compose the storage key for an (agent, session) pair. */
+function keyOf(agent, sessionId) {
+    return `${agent}${KEY_SEP}${sessionId}`;
+}
+export class StarStore {
+    stateFile;
+    /** In-memory set of starred keys (loaded once, written through on change). */
+    starred = null;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `starred` set would let several toggles that begin
+     * before the first `fs.readFile` resolves each build their own set and race on
+     * the assignment — a lost update (last writer wins, dropping the others' keys).
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.starred)
+            return Promise.resolve(this.starred);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                let keys = [];
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed))
+                        keys = parsed.filter((k) => typeof k === "string");
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.starred = new Set(keys);
+                return this.starred;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /** Whether a chat is starred. Non-throwing: any load error reads as false. */
+    async isStarred(agent, sessionId) {
+        const set = await this.ensureLoaded().catch(() => new Set());
+        return set.has(keyOf(agent, sessionId));
+    }
+    /**
+     * Set (or clear) a chat's starred flag, persisting the change. Idempotent.
+     * Returns whether the flag actually CHANGED, mirroring `ArchiveStore.setArchived`.
+     */
+    async setStarred(agent, sessionId, starred) {
+        const set = await this.ensureLoaded();
+        const key = keyOf(agent, sessionId);
+        if (starred === set.has(key))
+            return false; // no-op — avoid a needless write
+        if (starred)
+            set.add(key);
+        else
+            set.delete(key);
+        await this.persist(set);
+        return true;
+    }
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    persist(set) {
+        this.writing = this.writing.then(async () => {
+            const json = JSON.stringify([...set], null, 2);
+            await fs.writeFile(this.stateFile, json, "utf8").catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

package/packages/server/dist/start.d.ts

@@ -0,0 +1 @@
+export declare function start(): Promise<void>;

package/packages/server/dist/start.js

@@ -0,0 +1,21 @@
+/**
+ * Process lifecycle for a Paddock server: bind the port and wire signal-driven
+ * shutdown. Split out of `index.ts` so the `paddock` CLI (src/cli/paddock.ts)
+ * and the plain `node dist/index.js` entrypoint share one implementation.
+ *
+ * Config is resolved INSIDE `buildApp()`, not at module load, so a caller may
+ * still mutate `process.env` right up until this function is invoked. The CLI
+ * depends on that to apply its own defaults (e.g. a data dir under $HOME).
+ */
+import { buildApp } from "./app.js";
+export async function start() {
+    const { app, cfg, close } = await buildApp();
+    const shutdown = async () => {
+        await close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await app.listen({ port: cfg.port, host: cfg.host });
+    app.log.info(`paddock-server listening on http://${cfg.host}:${cfg.port}`);
+}