@spexcode/spec-cli 0.6.5

package/dist/session-follow.js

@@ -0,0 +1,179 @@
+import { existsSync } from 'node:fs';
+import { sessionStoreDir } from '@spexcode/spec-core';
+import { advanceFollow, followCursor, unreadSince } from './session-cursors.js';
+import { timelineDisplay, timelineEvents, timelineStamp } from './session-timeline.js';
+import { sessionTitle } from './sessions.js';
+// @@@ session-follow - supervision is FOLLOWING a log past a cursor, never polling a derived board. One tick
+// costs ONE stat per target: if timeline.ndjson has not grown, nothing is opened and nothing is parsed. No
+// call here reaches the backend, a rendezvous socket, or tmux, which is the whole point — M followers over N
+// sessions cost the control plane zero, where the old poll cost one board build (a connect + a tmux spawn per
+// live session) per follower per interval.
+// Actionable = a state whose arrival means "a human/supervisor must now act". `offline` is deliberately ABSENT
+// where the old poll had it: liveness is a present-tense probe derivation, never authored, so it can never
+// appear on a log ([[state]]). A follower learns what a session DECLARED and never that it died.
+const ACTIONABLE = new Set(['review', 'done', 'close-pending', 'error', 'asking']);
+const NEXT = {
+    review: 'merge | close',
+    done: 'merge | close',
+    'close-pending': 'close',
+    error: 'resume (relaunch & retry) | show --capture | close',
+    asking: 'send "<msg>" | show --capture',
+    idle: 'send "<msg>" | show --capture',
+    queued: 'waiting for a free slot — starts automatically | close',
+};
+const trunc = (s, n) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
+export function sessionEvent(s) {
+    const note = s.note ? ` — note: ${s.note}` : '';
+    const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : '';
+    return `[spex] ${s.status} · ${sessionTitle(s)} — act: ${NEXT[s.status] || '—'}${note}${asked}  [id ${s.id}]`;
+}
+// @@@ launchEvent - a session's FIRST sighting, emitted once per id whatever its status, so the stream is a
+// complete lifecycle feed: launched → [transitions] → closed. A launch's own first line is `active` (not
+// actionable), so without this the feed would be blind to new sessions starting.
+export function launchEvent(s) {
+    const note = s.note ? ` — note: ${s.note}` : '';
+    const asked = s.promptPreview ? ` · asked: ${s.promptPreview}` : '';
+    return `[spex] launched · ${sessionTitle(s)} — act: capture | send "<msg>"${note}${asked}  [id ${s.id}]`;
+}
+export async function followSessions(emit, opts) {
+    const { targets, self = null, statuses, includeIdle = false, intervalMs = 1000, as, take = false, timeoutMs = 1_200_000, onObserved, row } = opts;
+    const tag = as ? `[${as}] ` : '';
+    const state = new Map();
+    const memo = new Map(); // cursors for a follower that has no record of its own to store them in
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    // the no-hang wall: a fixed deadline computed ONCE, checked before EVERY sleep below.
+    const deadline = take ? Date.now() + Math.max(1000, timeoutMs) : 0;
+    const isActionable = (st) => ACTIONABLE.has(st) || (includeIdle && st === 'idle');
+    const passes = (st) => !statuses?.length || statuses.includes(st);
+    const anyPath = () => {
+        for (const f of state.values())
+            if (f.path.length)
+                return f.path;
+        return [];
+    };
+    const readCursor = (id) => (self ? followCursor(self, id) : memo.get(id) ?? null);
+    const writeCursor = (id, to) => { if (self)
+        advanceFollow(self, id, to);
+    else
+        memo.set(id, to); };
+    const line = (id, st, note, first) => {
+        const s = row?.(id, st, note);
+        if (!s)
+            return;
+        if (first)
+            emit(tag + launchEvent(s));
+        else if (passes(st) && isActionable(st))
+            emit(tag + sessionEvent(s));
+    };
+    let first = true;
+    let shown = -1; // stream mode: the last inbox line this process printed (see the INBOX read below)
+    for (;;) {
+        const ids = targets();
+        const seen = new Set();
+        for (const id of ids) {
+            if (id === self)
+                continue; // the follower's own log is its INBOX, followed below on its own cursor rule
+            seen.add(id);
+            if (!existsSync(sessionStoreDir(id))) {
+                if (state.delete(id))
+                    emit(`${tag}[spex] closed · removed  [id ${id}]`);
+                if (take)
+                    return { gone: id };
+                continue;
+            }
+            let f = state.get(id);
+            if (!f) {
+                const evs = timelineEvents(id);
+                // A stored cursor always wins — that IS the resume, losing nothing across a follower's death. With
+                // none: a target already present when the follow started predates it, so we begin at the log's END
+                // (its history is not news); a target that appears on a LATER tick genuinely just launched, so its
+                // whole log is read from 0 and its `launched` line reaches the feed.
+                const pos = readCursor(id) ?? (first ? evs.length : 0);
+                // The ARRIVAL state is the last status line BEFORE the cursor — a fact on the log, not whatever a poll
+                // happened to catch. With no such line the first status we read is the arrival instead.
+                let prev = null;
+                for (let i = Math.min(pos, evs.length) - 1; i >= 0; i--) {
+                    const e = evs[i];
+                    if (e.kind === 'status') {
+                        prev = timelineDisplay(e);
+                        break;
+                    }
+                }
+                f = { pos, prev, path: prev ? [prev] : [], stamp: null };
+                state.set(id, f);
+                if (prev) {
+                    onObserved?.(id, prev, null);
+                    line(id, prev, null, true);
+                }
+            }
+            const stamp = timelineStamp(id);
+            if (stamp !== null && stamp === f.stamp)
+                continue; // THE cheap tick: nothing appended, nothing parsed
+            f.stamp = stamp;
+            const evs = timelineEvents(id);
+            const slice = unreadSince(evs, f.pos);
+            let hit = null;
+            for (let k = 0; k < slice.events.length && !hit; k++) {
+                const e = slice.events[k];
+                if (e.kind === 'sent') {
+                    const s = row?.(id, f.prev ?? 'unknown', null);
+                    if (s)
+                        emit(`${tag}[spex] message · ${sessionTitle(s)} — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${id}]`);
+                    continue;
+                }
+                const st = timelineDisplay(e);
+                const was = f.prev;
+                f.prev = st;
+                f.path.push(st);
+                onObserved?.(id, st, was);
+                line(id, st, e.note, was === null);
+                // THE edge: a previously-observed NON-actionable status moving INTO an actionable one. An actionable
+                // ARRIVAL (was === null) is not an edge — that standing level is what a level-triggered wait falsely
+                // returned on; nor is an actionable→actionable hop (review→done). The rise OUT of non-actionable is the
+                // one signal that means "the target needs you AGAIN". The previous state is the previous LINE, so two
+                // moves inside one tick are two edges rather than one collapsed sample.
+                if (take && was !== null && !isActionable(was) && isActionable(st))
+                    hit = { reached: st, id, path: f.path };
+                // Consume exactly up to the event we stopped on, so the lines behind it stay unread for the next wait.
+                if (hit) {
+                    f.pos = slice.at[k] + 1;
+                    writeCursor(id, f.pos);
+                }
+            }
+            if (hit)
+                return hit;
+            f.pos = slice.next;
+            writeCursor(id, f.pos);
+        }
+        for (const id of [...state.keys()]) {
+            if (seen.has(id))
+                continue;
+            state.delete(id);
+            emit(`${tag}[spex] closed · removed  [id ${id}]`);
+        }
+        // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own entry in `cursors.json`. It is
+        // a WATCH, not a delivery: a message reaches the agent as a prompt through the adapter ([[delivery-queue]]),
+        // so this position only decides what THIS process has already reported and can never make an agent miss
+        // mail. Never advanced here in take mode — the waiter stops on the event and the next wait resumes on it.
+        if (self && existsSync(sessionStoreDir(self))) {
+            const mine = unreadSince(timelineEvents(self), followCursor(self, self) ?? 0);
+            for (let k = 0; k < mine.events.length; k++) {
+                const e = mine.events[k];
+                if (e.kind !== 'sent')
+                    continue;
+                if (take)
+                    return { mail: { from: e.from, text: e.text } };
+                // a stream has no turn boundary to advance that cursor, so its own high-water mark — process-local,
+                // never written — is what keeps an unread line from being re-printed on every tick.
+                if (mine.at[k] <= shown)
+                    continue;
+                shown = mine.at[k];
+                emit(`${tag}[spex] message · you — from ${e.from ?? 'human'}: ${trunc(e.text, 120)}  [id ${self}]`);
+            }
+        }
+        first = false;
+        if (take && Date.now() >= deadline)
+            return { timedOut: true, path: anyPath() };
+        await sleep(intervalMs);
+    }
+}

package/dist/session-reparent.d.ts

@@ -0,0 +1,10 @@
+import { type SessionReparentResult } from './sessions.js';
+export declare class SessionReparentRequestError extends Error {
+    constructor(message: string);
+}
+export declare function parseReparentRequest(body: unknown): {
+    children: string[];
+    parent: string | null;
+};
+export declare function reparentRequest(body: unknown): Promise<SessionReparentResult>;
+export declare function reparentSessions(children: string[], parent: string | null): Promise<SessionReparentResult>;

package/dist/session-reparent.js

@@ -0,0 +1,33 @@
+import { apiBaseInfo, reparentSessionRecords } from './sessions.js';
+import { BackendError, backendConnectionRefused, clientReparent } from './client.js';
+export class SessionReparentRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SessionReparentRequestError';
+    }
+}
+export function parseReparentRequest(body) {
+    if (!body || typeof body !== 'object')
+        throw new SessionReparentRequestError('reparent body must be JSON');
+    const raw = body;
+    if (!Array.isArray(raw.children) || !raw.children.length || raw.children.some((id) => typeof id !== 'string' || !id.trim()))
+        throw new SessionReparentRequestError('reparent children must be one or more session ids');
+    if (raw.parent !== null && (typeof raw.parent !== 'string' || !raw.parent.trim()))
+        throw new SessionReparentRequestError('reparent parent must be a session id or null');
+    return { children: raw.children.map((id) => id.trim()), parent: raw.parent === null ? null : raw.parent.trim() };
+}
+export async function reparentRequest(body) {
+    const request = parseReparentRequest(body);
+    return reparentSessionRecords(request.children, request.parent);
+}
+export async function reparentSessions(children, parent) {
+    try {
+        return await clientReparent(children, parent);
+    }
+    catch (error) {
+        if (!(error instanceof BackendError) || (await apiBaseInfo()).source === 'flag' || !backendConnectionRefused(error))
+            throw error;
+        console.error('spex: no backend reachable — reparenting in-process under the session record locks');
+        return reparentSessionRecords(children, parent);
+    }
+}

package/dist/session-timeline.d.ts

@@ -0,0 +1,51 @@
+import type { Lifecycle, Proposal } from './sessions.js';
+import type { ExecutionTurn } from './execution-trace.js';
+export type TimelineEvent = {
+    ts: string;
+    kind: 'status';
+    status: Lifecycle;
+    proposal: Proposal | null;
+    note: string | null;
+    display?: string;
+} | {
+    ts: string;
+    kind: 'sent';
+    mid: string;
+    text: string;
+    from: string | null;
+    replyVia?: 'note';
+};
+export type SentDispatchReceipt = {
+    operation: 'merge';
+    requestDigest: string;
+    payloadHash: string;
+    delivery?: {
+        text: string;
+        from: string | null;
+    };
+};
+export declare function recordStatus(id: string, status: Lifecycle, proposal: Proposal | null, note: string | null): void;
+export declare function appendSent(id: string, text: string, from: string | null, replyVia?: 'note', dispatchReceipt?: SentDispatchReceipt): {
+    mid: string;
+};
+export type SentDispatchState = {
+    mid: string;
+    payloadHash: string;
+    delivery: SentDispatchReceipt['delivery'] | null;
+    delivered: boolean;
+};
+export declare function sentDispatchReceipt(id: string, operation: SentDispatchReceipt['operation'], requestDigest: string): SentDispatchState | null;
+export declare function settleSentDispatch(id: string, mid: string): void;
+export declare function timelineEvents(id: string): TimelineEvent[];
+export declare function timelineStamp(id: string): string | null;
+type DisplayWord = 'working' | 'idle' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued';
+export declare const timelineDisplay: (e: {
+    status: Lifecycle;
+    proposal: Proposal | null;
+}) => DisplayWord;
+export declare function lastHumanSendVia(id: string): 'note' | null;
+export declare function currentHumanTurn(id: string): ExecutionTurn | null;
+export declare function readTimeline(id: string, limit?: number): {
+    events: TimelineEvent[];
+} | null;
+export {};

package/dist/session-timeline.js

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, appendFileSync, mkdirSync, statSync, readdirSync, openSync, closeSync, readSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { sessionStoreDir, sessionArtifactPath, readAliasedRawRecord } from '@spexcode/spec-core';
+const timelinePath = (id) => sessionArtifactPath(id, 'timeline.ndjson');
+const segmentsDir = (id) => sessionArtifactPath(id, 'timeline');
+const SEGMENT = /^(\d+)\.ndjson$/;
+const SEGMENT_NAME_WIDTH = 12;
+const TAIL_BLOCK_BYTES = 64 * 1024;
+// One logical timeline is legacy timeline.ndjson followed by immutable numbered segments. The directory
+// listing is its only index: numbering is append order, so there is no mutable manifest to repair.
+function segmentFiles(id) {
+    try {
+        const dir = segmentsDir(id);
+        const names = readdirSync(dir).filter((name) => SEGMENT.test(name)).sort((a, b) => {
+            const an = BigInt(SEGMENT.exec(a)[1]), bn = BigInt(SEGMENT.exec(b)[1]);
+            return an < bn ? -1 : an > bn ? 1 : 0;
+        });
+        return names.map((name) => join(dir, name));
+    }
+    catch { /* no numbered segments yet */ }
+    return [];
+}
+function timelineFiles(id) {
+    const files = [];
+    const legacy = timelinePath(id);
+    if (existsSync(legacy))
+        files.push(legacy);
+    files.push(...segmentFiles(id));
+    return files;
+}
+const segmentLimit = () => {
+    const configured = Number(process.env.SPEXCODE_TIMELINE_SEGMENT_BYTES);
+    return Number.isFinite(configured) ? Math.max(1024, Math.floor(configured)) : 4 * 1024 * 1024;
+};
+function activeSegment(id, bytes) {
+    const dir = segmentsDir(id);
+    mkdirSync(dir, { recursive: true });
+    const segments = segmentFiles(id);
+    const current = segments.at(-1);
+    if (!current)
+        return join(dir, `${String(1).padStart(SEGMENT_NAME_WIDTH, '0')}.ndjson`);
+    try {
+        if (statSync(current).size === 0 || statSync(current).size + bytes <= segmentLimit())
+            return current;
+    }
+    catch { /* a vanished active segment is recreated under its next number */ }
+    const n = BigInt(SEGMENT.exec(basename(current))[1]) + 1n;
+    return join(dir, `${String(n).padStart(SEGMENT_NAME_WIDTH, '0')}.ndjson`);
+}
+function append(id, ev) {
+    mkdirSync(sessionStoreDir(id), { recursive: true });
+    const line = JSON.stringify(ev) + '\n';
+    appendFileSync(activeSegment(id, Buffer.byteLength(line)), line);
+}
+function parseLines(lines) {
+    return lines.map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    }).filter((e) => e != null && (e.kind === 'status' || e.kind === 'sent' || e.kind === 'dispatch-settled'));
+}
+function tailPublicEvents(path, limit) {
+    let fd = null;
+    try {
+        const size = statSync(path).size;
+        fd = openSync(path, 'r');
+        let start = size;
+        let text = '';
+        while (start > 0) {
+            const next = Math.max(0, start - TAIL_BLOCK_BYTES);
+            const buf = Buffer.alloc(start - next);
+            readSync(fd, buf, 0, buf.length, next);
+            text = buf.toString('utf8') + text;
+            const publicCount = parseLines(text.split('\n').filter(Boolean)).filter((event) => event.kind !== 'dispatch-settled').length;
+            if (publicCount >= limit || next === 0)
+                break;
+            start = next;
+        }
+        return parseLines(text.split('\n').filter(Boolean))
+            .filter((event) => event.kind !== 'dispatch-settled')
+            .slice(-limit);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+// Record a lifecycle value that has already landed in session.json. TypeScript state writers call this
+// synchronously before returning, so a later write cannot erase an intermediate declaration note from the
+// conversation. Best-effort: history is an accessory to the state machine, and failing to write it must never
+// break the transition that already happened.
+export function recordStatus(id, status, proposal, note) {
+    try {
+        append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note });
+    }
+    catch { /* the record already moved; the history line is the only loss */ }
+}
+// The DELIVERY ([[dispatch]]): appending this line IS the send, so unlike a status line it must fail LOUD —
+// the caller reports the throw rather than a false success. `text` is the message BEFORE any mechanism insert
+// (hints are transport, not conversation); `replyVia` is the effective channel the prompt seam chose. Returns
+// the new line's `mid`, which a best-effort poke carries.
+export function appendSent(id, text, from, replyVia, dispatchReceipt) {
+    const mid = randomUUID();
+    append(id, { ts: new Date().toISOString(), kind: 'sent', mid, text, from, ...(replyVia ? { replyVia } : {}), ...(dispatchReceipt ? { dispatchReceipt } : {}) });
+    return { mid };
+}
+export function sentDispatchReceipt(id, operation, requestDigest) {
+    let found = null;
+    const settled = new Set();
+    for (const path of timelineFiles(id)) {
+        for (const event of parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean))) {
+            if (event.kind === 'sent' && !found && event.dispatchReceipt?.operation === operation && event.dispatchReceipt.requestDigest === requestDigest) {
+                found = { mid: event.mid, payloadHash: event.dispatchReceipt.payloadHash, delivery: event.dispatchReceipt.delivery ?? null };
+            }
+            else if (event.kind === 'dispatch-settled' && event.operation === operation && event.requestDigest === requestDigest) {
+                settled.add(event.mid);
+            }
+        }
+    }
+    return found ? { ...found, delivered: settled.has(found.mid) } : null;
+}
+export function settleSentDispatch(id, mid) {
+    let receipt = null;
+    let settled = false;
+    for (const path of timelineFiles(id)) {
+        for (const event of parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean))) {
+            if (event.kind === 'sent' && event.mid === mid && event.dispatchReceipt?.delivery)
+                receipt = event.dispatchReceipt;
+            if (event.kind === 'dispatch-settled' && event.mid === mid)
+                settled = true;
+        }
+    }
+    if (!receipt || settled)
+        return;
+    append(id, { ts: new Date().toISOString(), kind: 'dispatch-settled', operation: receipt.operation, requestDigest: receipt.requestDigest, mid });
+}
+// The unowned read: any process may take it with nothing but filesystem access, and taking it perturbs
+// nothing. Index = event position, which is what a cursor names ([[session-cursors]]).
+export function timelineEvents(id) {
+    try {
+        return timelineFiles(id).flatMap((path) => parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean)))
+            .flatMap((stored) => {
+            if (stored.kind === 'dispatch-settled')
+                return [];
+            if (stored.kind === 'status')
+                return [stored];
+            const { dispatchReceipt: _receipt, ...event } = stored;
+            return [event];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+// the same L0 read taken as CHEAPLY as it can be: a follower ([[session-follow]]) ticks over many logs, so it
+// stats first and parses only what grew. null = no log yet (a session that has authored nothing).
+export function timelineStamp(id) {
+    try {
+        const path = timelineFiles(id).at(-1);
+        if (!path)
+            return null;
+        const s = statSync(path);
+        return `${path}:${s.size}:${s.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+}
+// the display word for an authored state — the SAME vocabulary every other surface speaks (awaiting → its
+// proposal's label, active → working), duplicated here as a tiny read-time map rather than importing the state
+// machine (sessions.ts imports THIS module for appendSent; a value import back would be a cycle — the
+// Lifecycle/Proposal imports above are type-only, erased at runtime).
+const PROPOSAL_DISPLAY = { merge: 'review', nothing: 'done', close: 'close-pending' };
+export const timelineDisplay = (e) => e.status === 'awaiting' ? (PROPOSAL_DISPLAY[e.proposal ?? 'nothing'] ?? 'done')
+    : e.status === 'active' ? 'working' : e.status;
+// the channel of the LAST HUMAN send (from == null): 'note' when the note-reply hint rode along, else null.
+// This is what makes the reply-channel hints SYMMETRIC ([[session-timeline]]): a human send with no note flag
+// arriving after a note-send is the "back at a terminal" transition, and the delivery gets the counter-insert.
+// Derived from the durable log — no new state, and it survives a server restart. Agent senders (`from` set)
+// say nothing about where the HUMAN is reading, so they neither set nor clear it.
+export function lastHumanSendVia(id) {
+    const evs = timelineEvents(id);
+    for (let i = evs.length - 1; i >= 0; i--) {
+        const e = evs[i];
+        if (e.kind === 'sent' && e.from == null)
+            return e.replyVia === 'note' ? 'note' : null;
+    }
+    return null;
+}
+// The current human turn is a durable fact from the accepted-message log, not a backend-local generation.
+export function currentHumanTurn(id) {
+    const evs = timelineEvents(id);
+    for (let i = evs.length - 1; i >= 0; i--) {
+        const e = evs[i];
+        if (e.kind === 'sent' && e.from == null)
+            return { token: e.mid, acceptedAt: e.ts };
+    }
+    return null;
+}
+// the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each status
+// event carrying its composed display word. null = no such session (the route 404s).
+export function readTimeline(id, limit = 500) {
+    let raw;
+    try {
+        raw = readAliasedRawRecord(id);
+    }
+    catch {
+        return null;
+    }
+    if (!raw || !raw.governed)
+        return null;
+    const wanted = Math.max(1, limit);
+    const tail = [];
+    for (const path of timelineFiles(id).reverse()) {
+        const remaining = wanted - tail.length;
+        if (remaining <= 0)
+            break;
+        tail.unshift(...tailPublicEvents(path, remaining));
+    }
+    return { events: tail.map((e) => {
+            if (e.kind === 'status')
+                return { ...e, display: timelineDisplay(e) };
+            const { dispatchReceipt: _receipt, ...event } = e;
+            return event;
+        }) };
+}

package/dist/session-web.d.ts

@@ -0,0 +1,24 @@
+export declare class SessionWebError extends Error {
+    readonly status: 400 | 403 | 404 | 500;
+    constructor(status: 400 | 403 | 404 | 500, message: string);
+}
+type SessionWebLock = <T>(id: string, body: () => T) => T;
+export type SessionWeb = {
+    url: string;
+    key: string;
+};
+export declare function canonicalSessionWebUrl(input: string): string;
+export declare function sessionWebKey(url: string): string;
+export declare function listSessionWebs(id: string, projectRoot?: string): SessionWeb[];
+export declare function readSessionWebs(id: string, projectRoot?: string): SessionWeb[];
+export declare function addSessionWeb(id: string, input: string, lock: SessionWebLock): {
+    url: string;
+    added: boolean;
+};
+export declare function retractSessionWeb(id: string, input: string, lock: SessionWebLock): {
+    url: string;
+    removed: boolean;
+};
+export declare function postedSessionWeb(id: string, key: string, projectRoot?: string): URL;
+export declare const sessionWebsPath: (id: string) => string;
+export {};

package/dist/session-web.js

@@ -0,0 +1,141 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readRecordEntry, sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
+import { projectRuntimeRoot } from '@spexcode/spec-core';
+export class SessionWebError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'SessionWebError';
+    }
+}
+const webPath = (id, projectRoot) => projectRoot
+    ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'web.json')
+    : sessionArtifactPath(id, 'web.json');
+const recordPath = (id, projectRoot) => projectRoot
+    ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'session.json')
+    : join(sessionStoreDir(id), 'session.json');
+function validSessionId(id) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id);
+}
+function requireSession(id, projectRoot) {
+    if (!validSessionId(id))
+        throw new SessionWebError(404, `session ${id} does not exist`);
+    if (!projectRoot) {
+        const record = readRecordEntry(id);
+        if (record.kind === 'absent')
+            throw new SessionWebError(404, `session ${id} does not exist`);
+        if (record.kind === 'corrupt')
+            throw new SessionWebError(500, `session ${id} has an unreadable record: ${record.error}`);
+        return;
+    }
+    const path = recordPath(id, projectRoot);
+    let record;
+    try {
+        record = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new SessionWebError(404, `session ${id} does not exist`);
+        throw new SessionWebError(500, `session ${id} has an unreadable record: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!record || typeof record !== 'object' || record.session_id !== id)
+        throw new SessionWebError(500, `session ${id} has an unreadable record`);
+}
+export function canonicalSessionWebUrl(input) {
+    let url;
+    try {
+        url = new URL(input.trim());
+    }
+    catch {
+        throw new SessionWebError(400, `invalid local web URL: ${input}`);
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1'].includes(host) || !url.port || url.username || url.password) {
+        throw new SessionWebError(400, 'web URL must be http://127.0.0.1:<port>/..., http://localhost:<port>/..., or http://[::1]:<port>/...');
+    }
+    if (url.search || url.hash)
+        throw new SessionWebError(400, 'web URL must not include a query or fragment; publish the service base URL');
+    return url.href;
+}
+export function sessionWebKey(url) {
+    return createHash('sha256').update(url).digest('base64url');
+}
+function readWebs(id, projectRoot) {
+    const path = webPath(id, projectRoot);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new SessionWebError(500, `session web list is unreadable: ${path} — ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== 'string'))
+        throw new SessionWebError(500, `session web list is invalid: ${path}`);
+    try {
+        if (parsed.some((value) => canonicalSessionWebUrl(value) !== value))
+            throw new Error('not canonical');
+    }
+    catch {
+        throw new SessionWebError(500, `session web list is invalid: ${path}`);
+    }
+    return [...new Set(parsed)];
+}
+function writeWebs(id, webs) {
+    const path = webPath(id);
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(webs, null, 2)}\n`);
+        renameSync(tmp, path);
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* rename already consumed the temporary file */ }
+    }
+}
+const toWeb = (url) => ({ url, key: sessionWebKey(url) });
+export function listSessionWebs(id, projectRoot) {
+    requireSession(id, projectRoot);
+    return readSessionWebs(id, projectRoot);
+}
+// Session projections already hold a parsed record; re-checking session.json here would make an in-memory
+// projection depend on the public route's existence guard. The route-facing list keeps that guard above.
+export function readSessionWebs(id, projectRoot) {
+    return readWebs(id, projectRoot).map(toWeb);
+}
+export function addSessionWeb(id, input, lock) {
+    const url = canonicalSessionWebUrl(input);
+    return lock(id, () => {
+        requireSession(id);
+        const webs = readWebs(id);
+        if (webs.includes(url))
+            return { url, added: false };
+        writeWebs(id, [...webs, url]);
+        return { url, added: true };
+    });
+}
+export function retractSessionWeb(id, input, lock) {
+    const url = canonicalSessionWebUrl(input);
+    return lock(id, () => {
+        requireSession(id);
+        const webs = readWebs(id);
+        if (!webs.includes(url))
+            return { url, removed: false };
+        writeWebs(id, webs.filter((web) => web !== url));
+        return { url, removed: true };
+    });
+}
+export function postedSessionWeb(id, key, projectRoot) {
+    requireSession(id, projectRoot);
+    const web = readWebs(id, projectRoot).map(toWeb).find((entry) => entry.key === key);
+    if (!web)
+        throw new SessionWebError(403, 'that web service was not posted by this session');
+    return new URL(web.url);
+}
+export const sessionWebsPath = (id) => webPath(id);