@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/server/routes/auth.js

@@ -0,0 +1,172 @@
+/**
+ * The §5.4/§5.8 auth routes (core hardening W1 Tasks 3 + 4): browser
+ * login (API token → session cookie), logout (cookie expiry), whoami
+ * (the resolved principal), and the token management surface (`GET/POST
+ * /v1/auth/tokens`, `DELETE /v1/auth/tokens/:id`). The pipeline marks
+ * login/logout public (stage 2); whoami and the token routes are
+ * authenticated routes like any other.
+ *
+ * Login's contract: a valid token replies 200 `{user}` and sets
+ * `sigrun_session=<token>; HttpOnly; SameSite=Strict; Path=/` (plus
+ * `; Secure` when the request is https directly or via
+ * `X-Forwarded-Proto: https` from a trusted proxy peer). An invalid
+ * token waits 1 000 ms (blunting online guessing) before 401; the
+ * per-IP limiter's 429 is checked FIRST, before the credential and the
+ * wait.
+ *
+ * Token routes (Task 4): creation is SELF-ONLY — a body carrying a `user`
+ * field is 403 `forbidden` (minting credentials for another user is
+ * never a delegated act); listing serves the caller's tokens, with
+ * `?user=` the admin-only window into another's; revocation deletes the
+ * caller's own tokens, or any for an admin.
+ */
+import { ipAllowed } from "../auth/ip.js";
+import { LoginLimiter } from "../auth/login-limiter.js";
+/** The session cookie name (spec §5.4). */
+export const SESSION_COOKIE = "sigrun_session";
+/** The failed-login delay (ms), per the brief. */
+const LOGIN_FAILURE_DELAY_MS = 1_000;
+/**
+ * Build the `sigrun_session` cookie for `token`. `Secure` only on https —
+ * direct TLS or a trusted proxy's X-Forwarded-Proto (an untrusted peer's
+ * header is ignored). Shared by login and the onboarding claim's
+ * `issueToken` (Task 4).
+ */
+export function buildSessionCookie(token, request, ctx) {
+    const trusted = ipAllowed(request.socket.remoteAddress, ctx.config.auth.proxy.trustedProxies);
+    const forwarded = request.headers["x-forwarded-proto"];
+    const forwardedProto = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    const secure = request.protocol === "https" || (trusted && forwardedProto === "https");
+    return (`${SESSION_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/` +
+        (secure ? "; Secure" : ""));
+}
+/** The wire form of one token record — never the digest. */
+function tokenWire(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        user: record.user,
+        createdAt: record.createdAt,
+    };
+}
+/** Register the auth routes: login, logout, whoami, and token management. */
+export function registerAuthRoutes(app, ctx) {
+    const limiter = new LoginLimiter();
+    app.post("/v1/auth/login", async (request, reply) => {
+        const source = request.socket.remoteAddress ?? "unknown";
+        // The limiter answers BEFORE the credential is touched — a locked
+        // source never learns whether its token was right.
+        if (!limiter.allowed(source)) {
+            return await reply.code(429).send({ error: "rate_limited" });
+        }
+        const body = request.body;
+        const presented = typeof body === "object" && body !== null && "token" in body
+            ? body.token
+            : undefined;
+        const token = typeof presented === "string" ? presented : undefined;
+        const record = token === undefined
+            ? undefined
+            : ctx.opened.identity.tokens.verify(token);
+        const user = record === undefined
+            ? undefined
+            : ctx.opened.identity.users.get(record.user);
+        if (record === undefined || user === undefined || token === undefined) {
+            limiter.recordFailure(source);
+            await new Promise((resolve) => setTimeout(resolve, LOGIN_FAILURE_DELAY_MS));
+            return await reply.code(401).send({ error: "invalid_token" });
+        }
+        limiter.recordSuccess(source);
+        return await reply
+            .code(200)
+            .header("set-cookie", buildSessionCookie(token, request, ctx))
+            .send({ user: user.user });
+    });
+    app.post("/v1/auth/logout", async (_request, reply) => {
+        return await reply
+            .code(204)
+            .header("set-cookie", `${SESSION_COOKIE}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0`)
+            .send();
+    });
+    app.get("/v1/auth/whoami", async (request) => {
+        const principal = request.principal;
+        return {
+            ...(principal.user === undefined ? {} : { user: principal.user }),
+            ...(principal.name === undefined ? {} : { name: principal.name }),
+            ...(principal.email === undefined ? {} : { email: principal.email }),
+            admin: principal.admin,
+            service: principal.service,
+            method: principal.method,
+        };
+    });
+    // ─── Token management (Task 4) ─────────────────────────────────────
+    app.get("/v1/auth/tokens", async (request, reply) => {
+        const principal = request.principal;
+        const query = request.query;
+        // `?user=` is the admin-only window into another's tokens; a
+        // non-admin may pass their OWN name (the same payload as no query —
+        // the identity is theirs either way) but anyone ELSE's is refused
+        // before the store is read.
+        if (query.user !== undefined) {
+            if (!principal.admin && query.user !== principal.user) {
+                return await reply.code(403).send({ error: "forbidden" });
+            }
+            return { tokens: ctx.opened.identity.tokens.list(query.user).map(tokenWire) };
+        }
+        // The caller's own list — undefined (the naive single-operator
+        // superuser, userless service principal) means "no directory user to
+        // filter by": the whole store, which for that posture IS the
+        // operator's own (single-operator deploy).
+        return {
+            tokens: ctx.opened.identity.tokens.list(principal.user).map(tokenWire),
+        };
+    });
+    app.post("/v1/auth/tokens", async (request, reply) => {
+        const body = request.body;
+        if (typeof body !== "object" ||
+            body === null ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const record = body;
+        for (const key of Object.keys(record)) {
+            if (key !== "name" && key !== "user") {
+                return await reply.code(400).send({ error: "invalid_field", field: key });
+            }
+        }
+        // Self only, ever: an authenticated principal never mints for
+        // another user — the body's `user` is refused, not honored.
+        if (record.user !== undefined) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        if (typeof record.name !== "string" || record.name.trim() === "") {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const owner = request.principal.user;
+        // The naive superuser with no header has no directory identity to
+        // mint for — a mintable token needs a user whose rights it carries.
+        if (owner === undefined) {
+            return await reply.code(400).send({ error: "no_user" });
+        }
+        const minted = await ctx.opened.identity.tokens.create(record.name, owner);
+        const response = {
+            token: minted.token,
+            record: tokenWire(minted.record),
+        };
+        return await reply.code(201).send(response);
+    });
+    app.delete("/v1/auth/tokens/:id", async (request, reply) => {
+        const { id } = request.params;
+        const record = ctx.opened.identity.tokens
+            .list()
+            .find((entry) => entry.id === id);
+        if (record === undefined) {
+            return await reply.code(404).send({ error: "unknown_token" });
+        }
+        const principal = request.principal;
+        if (record.user !== principal.user && !principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        await ctx.opened.identity.tokens.revoke(id);
+        return await reply.code(204).send();
+    });
+}

package/dist/server/routes/conversations.js

@@ -0,0 +1,341 @@
+/**
+ * Conversation lifecycle routes: create, list, get, fork, export, import,
+ * and the session-meta sidebar resource — plus the JSONL body parser the
+ * import route reads its raw text through. Every `:id` route resolves its
+ * conversation through the `loadConversation` pre-handler (404 for an
+ * unknown id, before any body validation); the no-`id` routes (create,
+ * list, import) take no pre-handler.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { isSuperuser } from "../auth/principal.js";
+import { createConversationOp, listConversationsOp, readMetaOp, } from "../conversation-ops.js";
+import { loadConversation } from "../conversation-handler.js";
+import { ID_PARAMS_SCHEMA, readView, stampSessionOwner, storeAgentChange, } from "../helpers.js";
+import { applySessionMetaPatch, DEFAULT_SESSION_META, SessionMetaDoc, validateSessionMetaPatch, } from "../session-meta.js";
+import { JSONL_CONTENT_TYPE, } from "../views.js";
+import { base64BodyLimit } from "../../config.js";
+/** Register the conversation lifecycle + session-meta routes. */
+export function registerConversationRoutes(app, ctx) {
+    const { opened } = ctx;
+    app.post("/v1/conversations", async (request, reply) => {
+        // Create takes no fields (model/thinking changes arrive with
+        // the configure endpoint): an absent body is valid, an
+        // object with any field is a fail-loud 400.
+        const body = request.body;
+        if (body !== undefined &&
+            (typeof body !== "object" ||
+                Object.keys(body).length > 0)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        // The shared create op (W5 Task 5): the SAME code path the
+        // extension host bridge drives — ownerless ownership, the boot
+        // default model + store agent settings, and the identity seam's
+        // owner stamp. The source is the HTTP-create label ("user").
+        const created = await createConversationOp(ctx, {
+            ...(request.principal.user === undefined
+                ? {}
+                : { owner: request.principal.user }),
+            source: "user",
+        });
+        return await reply.code(201).send(created);
+    });
+    app.get("/v1/conversations", async (request, reply) => {
+        // Durable enumeration: the storage scan is authoritative —
+        // conversations this process never created (before a restart, in
+        // another process, or by tasks/tools inside pi-durable) all list.
+        // §5.9: the list is PER-CALLER — conversations the caller may not
+        // see (accessOf "none") are filtered out entirely (hidden is absent
+        // from lists, not just 404s), and every served row carries the
+        // caller's resolved access.
+        //
+        // The shared list op (W5 Task 5): the SAME code path the extension
+        // host bridge drives — lean by construction (spec §7.2 / W3 Task 2:
+        // scan record + SessionMetaDoc snapshot alone, no per-row view
+        // read, so a sidebar poll never re-reads transcripts).
+        //
+        // Query filters: `archived=true|false` (absent = all) and
+        // `mine=true` (owner === the caller). Strict booleans — anything
+        // else is a fail-loud 400, the same posture as body validation.
+        const query = request.query;
+        for (const field of ["archived", "mine"]) {
+            const value = query[field];
+            if (value !== undefined &&
+                value !== "true" &&
+                value !== "false") {
+                return await reply.code(400).send({ error: "invalid_field", field });
+            }
+        }
+        const filters = {
+            ...(query.archived === undefined
+                ? {}
+                : { archivedOnly: query.archived === "true" }),
+            ...(query.mine === "true" ? { mine: true } : {}),
+        };
+        const conversations = await listConversationsOp(ctx, {
+            user: request.principal.user,
+            superuser: isSuperuser(request.principal),
+        }, filters);
+        return { conversations };
+    });
+    app.get("/v1/conversations/:id", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request) => {
+        const conversation = request.conversation;
+        return readView(conversation);
+    });
+    // Fork: a history fork at one visible entry (spec §5 session
+    // management). `at` is the LAST entry id the fork keeps; absent = the
+    // newest entry (resolved through the entries query — never 0, which is
+    // not a real entry id). The fork inherits the parent's agent model and
+    // the same ownerless ownership the create route uses; the response is
+    // the create shape: 201 `{id, view}`.
+    app.post("/v1/conversations/:id/fork", {
+        schema: { params: ID_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx, "write"),
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        // Absent body is valid (`at` defaults to the newest entry); the
+        // object may carry ONLY `at` — the compact/configure convention.
+        const body = request.body;
+        let at;
+        if (body !== undefined && body !== null) {
+            if (typeof body !== "object" || Array.isArray(body)) {
+                return await reply.code(400).send({ error: "invalid_body" });
+            }
+            const record = body;
+            const unknownKey = Object.keys(record).find((key) => key !== "at");
+            if (unknownKey !== undefined) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: unknownKey });
+            }
+            if (record.at !== undefined &&
+                typeof record.at !== "number") {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "at" });
+            }
+            at = record.at;
+        }
+        if (at === undefined) {
+            // The entries query is newest-first: the first item of the first
+            // page is the newest entry. An empty page means there is nothing
+            // to fork — the parent conversation has no history at all.
+            const page = await conversation.entries({}, 1, undefined, BACKGROUND_CONTEXT);
+            if (page.items.length === 0) {
+                return await reply.code(400).send({ error: "empty_conversation" });
+            }
+            at = page.items[0].id;
+        }
+        else {
+            // Validate `at` against the parent's own history: `fork()` accepts
+            // any EntryId, but an id this conversation never had is a client
+            // error, not a silent empty fork.
+            const page = await conversation.entries({ maxEntryId: at }, 1, undefined, BACKGROUND_CONTEXT);
+            const newest = page.items[0];
+            if (newest === undefined || newest.id !== at) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "at" });
+            }
+        }
+        // The fork inherits the parent's agent model — read the resolved
+        // agent, fall back to the boot default like create.
+        const agent = await conversation.agent(BACKGROUND_CONTEXT);
+        const fork = await conversation.fork(at, {
+            ownership: { kind: "ownerless" },
+            agent: { model: agent.model ?? opened.defaultModel },
+        }, BACKGROUND_CONTEXT);
+        // The fork's sidebar identity: the copied meta doc
+        // carries the source's name/autoName and the namer's attempt count;
+        // ONE commit drops all three (a fork is a new conversation, not the
+        // source's name — and it starts naming-fresh: inheriting an exhausted
+        // attempt count would make the fork forever unnameable), re-seeds
+        // it with "<source display name> (fork)"
+        // as its AUTO name when the source had one, and stamps activity so
+        // the fresh fork sorts where it happened.
+        // §5.9 (Review Focus 3): the doc copied the source's `owner` and
+        // `sharing` (fork: "current") — the SAME commit resets them: a fork
+        // is the FORKER's private copy (owner = the caller, sharing deleted;
+        // a header-less caller means no owner at all — the key is removed).
+        const sourceMeta = await opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT);
+        const sourceName = sourceMeta?.name ?? sourceMeta?.autoName;
+        await fork.commit(async (tx) => {
+            const draft = await tx.doc(SessionMetaDoc, fork.id);
+            delete draft.name;
+            delete draft.autoName;
+            delete draft.autoNameAttempts;
+            delete draft.sharing;
+            if (request.principal.user === undefined)
+                delete draft.owner;
+            else
+                draft.owner = request.principal.user;
+            if (sourceName !== undefined)
+                draft.autoName = `${sourceName} (fork)`;
+            draft.lastActivityAt = opened.now().toISOString();
+        }, BACKGROUND_CONTEXT);
+        const view = await readView(fork);
+        return await reply.code(201).send({ id: fork.id, view });
+    });
+    // Export: the conversation's history as JSONL — pi's portable
+    // format. One entry JSON object per line (the same per-entry
+    // serialization the view serves), OLDEST-first (the reverse of the
+    // newest-first entries query), so an import replays the transcript in
+    // order. All history pages, not just the active view.
+    app.get("/v1/conversations/:id/export", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request, reply) => {
+        const conversation = request.conversation;
+        const lines = [];
+        let cursor;
+        // Newest-first pages accumulate reversed; emit oldest-first.
+        const collected = [];
+        do {
+            const page = await conversation.entries({}, 200, cursor, BACKGROUND_CONTEXT);
+            collected.push(...page.items);
+            cursor = page.next;
+        } while (cursor !== undefined);
+        for (let i = collected.length - 1; i >= 0; i--) {
+            lines.push(JSON.stringify(collected[i]));
+        }
+        return await reply
+            .header("content-type", JSONL_CONTENT_TYPE)
+            .send(lines.join("\n") + "\n");
+    });
+    // Import: create a new conversation from JSONL. The body is
+    // the RAW JSONL text (the export format, round-tripped); parse line by
+    // line, create the conversation the create-route way, then append each
+    // parsed entry IN ORDER (oldest-first) inside one commit — fresh entry
+    // ids are assigned by storage (`EntryDraft` carries no id).
+    app.post("/v1/conversations/import", 
+    // Same knob-derived ceiling as the base64 upload route (spec §6.2):
+    // the JSONL text may be as large as the knob-derived body without
+    // hitting Fastify's 1 MiB default.
+    { bodyLimit: base64BodyLimit(ctx.config.maxUploadBytes) }, async (request, reply) => {
+        const raw = request.body;
+        if (typeof raw !== "string") {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const textLines = raw.split("\n");
+        // A trailing newline is the export terminator, not an empty line.
+        const lines = textLines[textLines.length - 1] === ""
+            ? textLines.slice(0, -1)
+            : textLines;
+        if (lines.length === 0) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const drafts = [];
+        for (const [index, line] of lines.entries()) {
+            if (line.trim() === "") {
+                return await reply.code(400).send({ error: "invalid_body" });
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_body", line: index + 1 });
+            }
+            if (typeof parsed !== "object" || parsed === null) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_body", line: index + 1 });
+            }
+            const record = parsed;
+            // An entry line carries `kind` plus the optional model/data/
+            // edits payloads — the EntryDraft shape. Stale identity fields
+            // (id/conversationId/byTaskId) are dropped: storage assigns
+            // fresh ones. A stale `head` EntryId would point at the OLD
+            // numbering — drop it too; the default active-context pointer
+            // starts at the newest appended entry.
+            const draft = {
+                kind: String(record.kind),
+                ...(Array.isArray(record.model)
+                    ? { model: record.model }
+                    : {}),
+                ...("data" in record
+                    ? { data: record.data }
+                    : {}),
+                ...(Array.isArray(record.edits)
+                    ? { edits: record.edits }
+                    : {}),
+            };
+            if (draft.kind === "") {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_body", line: index + 1 });
+            }
+            drafts.push(draft);
+        }
+        const conversation = await opened.harness.createConversation({
+            ownership: { kind: "ownerless" },
+            agent: storeAgentChange(opened, opened.defaultModel),
+        }, BACKGROUND_CONTEXT);
+        // One commit appends every entry in order; the conversation's own
+        // commit binds the transaction to this conversation.
+        await conversation.commit(async (tx) => {
+            for (const draft of drafts) {
+                await tx.appendEntry(conversation.id, draft);
+            }
+        }, BACKGROUND_CONTEXT);
+        // The imported conversation is the IMPORTER's, not the source's
+        // (the JSONL never carries meta — the stamp is the only owner).
+        await stampSessionOwner(conversation, request.principal.user);
+        const view = await readView(conversation);
+        return await reply.code(201).send({ id: conversation.id, view });
+    });
+    // JSONL bodies (the import route above): raw text, never JSON-parsed —
+    // the route itself parses line by line so a bad line is a 400
+    // invalid_body, not Fastify's 415 Unsupported Media Type. Content-type-
+    // only: onRequest hooks (deploy auth etc.) keep their hook semantics.
+    for (const type of [JSONL_CONTENT_TYPE, "text/plain"]) {
+        app.addContentTypeParser(type, { parseAs: "string" }, (_request, body, done) => done(null, body));
+    }
+    // Session meta: the conversation-scoped sidebar resource (spec §5).
+    // GET serves the doc — or the defaults when it was never written; a read
+    // NEVER materializes the doc (defaults are free; a write-per-read would
+    // churn a doc revision on every sidebar poll). PATCH merges per the spec
+    // table (null clears, draft sub-merges, tagged replaces wholesale) inside
+    // ONE commit callback — the read-modify-write pattern keeps concurrent
+    // patches from losing each other's fields (the mutation line serializes
+    // commits, mirroring the decide pattern).
+    app.get("/v1/conversations/:id/meta", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request) => {
+        const conversation = request.conversation;
+        // The shared read op (W5 Task 5): absent doc → defaults, served
+        // (never written — a read that wrote would churn a doc revision
+        // on every sidebar poll).
+        return await readMetaOp(opened, conversation.id);
+    });
+    app.patch("/v1/conversations/:id/meta", {
+        schema: { params: ID_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx, "write"),
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        // Validate FIRST — a rejected patch never touches the doc.
+        const validated = validateSessionMetaPatch(request.body);
+        if ("error" in validated) {
+            return await reply.code(400).send(validated);
+        }
+        // §5.9: `sharing` additionally requires the OWNER or a superuser —
+        // write access (granted by a share) must not let a recipient
+        // re-share the resource.
+        if (validated.sharing !== undefined) {
+            const meta = await opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT);
+            const isOwner = request.principal.user !== undefined &&
+                request.principal.user === meta?.owner;
+            if (!isOwner && !isSuperuser(request.principal)) {
+                return await reply.code(403).send({ error: "forbidden" });
+            }
+        }
+        // Read-modify-write inside ONE commit: tx.doc materializes the doc
+        // (initial()) when absent and the patch mutates the tracked draft.
+        await conversation.commit(async (tx) => {
+            const draft = await tx.doc(SessionMetaDoc, conversation.id);
+            applySessionMetaPatch(draft, validated);
+        }, BACKGROUND_CONTEXT);
+        // The response is a FRESH snapshot, not a draft projection:
+        // reading a newly-SET nested draft value (`sharing`, §5.9) trips
+        // chord's settled-overlay rule, so the reply must never read the
+        // mutated draft — a post-commit snapshot is exactly what was
+        // stored.
+        return ((await opened.harness.snapshot(SessionMetaDoc, conversation.id, BACKGROUND_CONTEXT)) ?? DEFAULT_SESSION_META);
+    });
+}

package/dist/server/routes/events.js

@@ -0,0 +1,161 @@
+/**
+ * The global events stream route (core hardening W3 Task 4, spec §7.4):
+ * `GET /v1/events` — ONE Server-Sent Events stream per client carrying
+ * the hub's `HostEventWire` events, framed `event: <type>\ndata: <json>\n\n`
+ * with a `: ping` heartbeat every 15s (the /stream heartbeat pattern).
+ * No replay: the stream only nudges; a reconnecting client refetches the
+ * list (the events carry no transcript state).
+ *
+ * Filtering (Review Focus 3 — per-event, never a connect-time snapshot):
+ * the visibility decision is an EXHAUSTIVE per-type switch (hardening
+ * review Task 4): a conversation-scoped event (conversation.* / run.* /
+ * interaction.* / ambient.*) is delivered iff `accessOf(principal, meta)`
+ * ≠ `"none"` with the SessionMeta RE-SNAPSHOTTED per event — a share
+ * makes the NEXT event arrive, an un-share withholds the one after.
+ * `providers.changed` reaches every authenticated principal. `job.changed`
+ * (W4 Task 4) resolves `accessOf` against the EVENT's own owner/sharing
+ * (the hub's copy is access-neutral) and is delivered with the caller's
+ * `access` ADDED to the job row — a hidden job's event is withheld
+ * entirely, no extra read. `taskSettled` is never delivered. Any type the
+ * switch does not know is NEVER delivered (deny by construction — the
+ * old fall-through snapshotted a missing conversationId and broadcast
+ * the ownerless result).
+ *
+ * The async re-snapshot runs in the route's own side lane (the bus/hub
+ * listener contract is no-blocking-work): each stream keeps a per-event
+ * serial promise chain, so frames for one connection stay in publish
+ * order without ever blocking the hub. A snapshot failure (a retired
+ * conversation raced the event) withholds THAT event — the honest
+ * read-side posture.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { accessOf } from "@sigrun/shared/access";
+import { SessionMetaDoc } from "../session-meta.js";
+/** The heartbeat cadence (the /stream pattern: proxy idle-timeout survival). */
+const HEARTBEAT_MS = 15_000;
+/** Register the global events stream route. */
+export function registerEventRoutes(app, ctx) {
+    app.get("/v1/events", async (request, reply) => {
+        const principal = request.principal;
+        const { opened } = ctx;
+        reply.hijack();
+        const raw = reply.raw;
+        raw.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+            "x-accel-buffering": "no",
+        });
+        raw.flushHeaders();
+        // Socket-level write errors after teardown have no consumer; swallow
+        // them so a mid-write disconnect cannot crash the process.
+        raw.on("error", () => { });
+        const send = (event) => {
+            raw.write(`event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+        };
+        let finished = false;
+        const heartbeat = setInterval(() => {
+            raw.write(": ping\n\n");
+        }, HEARTBEAT_MS);
+        /**
+         * Whether THIS principal may see one event (Review Focus 3): an
+         * EXHAUSTIVE switch over the HostEventWire members — a new member
+         * added without a case fails the typecheck (Review Focus 4;
+         * test/events-exhaustive.typecheck.ts mirrors this dispatch) and
+         * never falls through to the old ownerless-snapshot broadcast
+         * (accessOf(principal, {}) === "write")). Conversation-scoped
+         * events re-snapshot the SessionMeta PER EVENT; providers.changed is
+         * broadcast; job.changed (W4 Task 4) resolves against the event's own
+         * owner/sharing and, when visible, ENRICHES the row with the caller's
+         * `access` (the hub's copy is access-neutral by contract — the stream
+         * adds it per principal); taskSettled is host machinery (never
+         * principal-facing).
+         */
+        const visible = async (event) => {
+            switch (event.type) {
+                // Conversation-scoped: SessionMeta access, re-snapshotted per
+                // event (share → the NEXT event arrives; un-share withholds the
+                // one after).
+                case "conversation.created":
+                case "conversation.changed":
+                case "run.admitted":
+                case "run.settled":
+                case "interaction.pending":
+                case "interaction.settled":
+                case "ambient.changed": {
+                    let meta;
+                    try {
+                        meta = await opened.harness.snapshot(SessionMetaDoc, event.conversationId, BACKGROUND_CONTEXT);
+                    }
+                    catch (error) {
+                        console.error("events route: SessionMeta snapshot failed:", error);
+                        return undefined; // a raced read withholds that one event
+                    }
+                    return accessOf(principal, meta ?? {}) !== "none" ? event : undefined;
+                }
+                // Broadcast: every authenticated principal.
+                case "providers.changed":
+                    return event;
+                // The event's own owner/sharing decides; the delivered row
+                // carries the caller's access (the wire adds what the hub's
+                // access-neutral copy omits).
+                case "job.changed": {
+                    const access = accessOf(principal, {
+                        ...(event.job.owner === undefined
+                            ? {}
+                            : { owner: event.job.owner }),
+                        ...(event.job.sharing === undefined
+                            ? {}
+                            : { sharing: event.job.sharing }),
+                    });
+                    if (access === "none")
+                        return undefined;
+                    const enriched = { ...event.job, access };
+                    return { ...event, job: enriched };
+                }
+                // Host machinery (the jobs observer's input), never a
+                // principal-facing wire event.
+                case "taskSettled":
+                    return undefined;
+                // An unknown member is NEVER delivered — deny by construction,
+                // not by enumerating the leak shapes. The satisfies check keeps
+                // this arm exhaustive: a new HostEventWire member without a
+                // case fails the typecheck here (and in the mirror file).
+                default:
+                    event;
+                    return undefined;
+            }
+        };
+        // The per-connection side lane: serial promise chain, so frames for
+        // one connection stay in publish order while the hub listener itself
+        // returns immediately (the no-blocking-work contract).
+        let lane = Promise.resolve();
+        const unsubscribe = opened.events.subscribe((event) => {
+            lane = lane.then(async () => {
+                if (finished)
+                    return;
+                const deliverable = await visible(event);
+                if (deliverable === undefined || finished)
+                    return;
+                send(deliverable);
+            });
+        });
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            clearInterval(heartbeat);
+            unsubscribe();
+            raw.end();
+        };
+        // Client disconnect: `response` close (socket termination) — NOT
+        // `request.raw` close (Node 26 fires it at request-message completion,
+        // i.e. immediately for a bodyless GET).
+        raw.on("close", finish);
+        // A client may have disconnected before the close listener existed.
+        if (raw.destroyed) {
+            finish();
+            return;
+        }
+    });
+}