@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/server/routes/interactions.js

@@ -0,0 +1,260 @@
+/**
+ * Interaction + ambient seam routes (docs/approval-ux-seams.md): the
+ * pending-interaction list, the ONE generic answer route, and the
+ * conversation's ambient surfaces.
+ *
+ * The polling surfaces (`GET …/interactions`, `GET …/ambient`) take NO
+ * conversation pre-handler — the polling convention (codified on
+ * `loadConversation` in `conversation-handler.ts`): a channel polling a
+ * torn-down conversation must not error, so they read the seam index
+ * docs directly and answer 200 with an empty list for an absent
+ * conversation. They are still §5.9 `:id` routes, so each handler applies
+ * the VISIBILITY half of the access rule itself (`visibleTo`): a caller
+ * with `accessOf === "none"` gets the hidden-is-404
+ * `conversation_not_found`, exactly as the pre-handler would give (read
+ * access suffices — these routes can never write).
+ *
+ * The answer route is a write: it resolves its conversation through the
+ * `loadConversation(ctx, "write")` pre-handler like every other write
+ * `:id` route, with a params schema covering BOTH `id` and `callId` so
+ * Fastify's param validation cannot mask the lookup. A human answer
+ * stamps `answeredByUser` with the principal's user (spec §5.9: who
+ * answered matters to every participant a conversation is shared with).
+ *
+ * The cross-conversation inbox (`GET /v1/interactions?status=pending`,
+ * spec §7.5) also lives here. It has NO `:id`, so no pre-handler — it
+ * snapshots the session-singleton `InteractionsIndexDoc` once per
+ * request (seed/answer/expire commits maintain it; there is no cache to
+ * invalidate), then applies the visibility half of the access rule per
+ * conversation (`accessOf` against its SessionMeta — hidden is ABSENT
+ * from the list, the list-side half of §5.9's hidden-is-404) before
+ * reading each pending record. This is how "answer the agent from my
+ * phone" works without opening each conversation; answers still go
+ * through the per-conversation answer route above.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { AmbientDoc, AmbientOwnersDoc, } from "../../harness/ambient.js";
+import { InteractionDoc, InteractionsIndexDoc, applyAnswer, indexSettled, } from "../../harness/interactions.js";
+import { loadConversation } from "../conversation-handler.js";
+import { ID_PARAMS_SCHEMA, conversationId } from "../helpers.js";
+import { accessOf } from "@sigrun/shared/access";
+import { isSuperuser } from "../auth/principal.js";
+import { SessionMetaDoc } from "../session-meta.js";
+/**
+ * Path params for the answer route — `ID_PARAMS_SCHEMA`'s shape plus the
+ * `callId` segment its address carries. Declaring BOTH params keeps
+ * Fastify's param validation from masking the pre-handler's lookup: a
+ * malformed id is a 400 like every other `:id` route.
+ */
+const ANSWER_PARAMS_SCHEMA = {
+    type: "object",
+    properties: { id: { type: "integer" }, callId: { type: "string" } },
+    required: ["id", "callId"],
+    additionalProperties: false,
+};
+/**
+ * The §5.9 visibility half of the access rule for the pre-handler-free
+ * polling GETs: resolve the conversation's session-meta and answer
+ * whether the caller may SEE it (`accessOf !== "none"`). Absent doc →
+ * defaults → ownerless → visible. These routes are read-only by
+ * construction, so read/write need never be distinguished here.
+ */
+async function visibleTo(ctx, convId, principal) {
+    const meta = await ctx.opened.harness.snapshot(SessionMetaDoc, convId, BACKGROUND_CONTEXT);
+    return (accessOf({ user: principal.user, superuser: isSuperuser(principal) }, meta ?? {}) !== "none");
+}
+/** Register the interaction-seam and ambient-surface routes. */
+export function registerInteractionRoutes(app, ctx) {
+    const { opened } = ctx;
+    // ─── Interaction seam (docs/approval-ux-seams.md) ────────────────────
+    // One generic surface shared by every extension: pending interactions
+    // (list) and answers (the ONE generic route). Resolution semantics stay
+    // extension-owned — the route only writes the envelope's answer field.
+    // ─── Cross-conversation inbox (spec §7.5) ──────────────────────
+    // ONE list over every conversation the caller can see: a single
+    // snapshot of the session-singleton index (seed/answer/expire commits
+    // maintain it — nothing to invalidate), §5.9 visibility per
+    // conversation (hidden is ABSENT, the list-side half of the rule),
+    // then the still-pending records. `pending` is the only indexed
+    // status: any other query value is a fail-loud 400 (absent means
+    // pending).
+    app.get("/v1/interactions", async (request, reply) => {
+        const query = request.query;
+        if (query.status !== undefined && query.status !== "pending") {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "status" });
+        }
+        const index = await opened.harness.snapshot(InteractionsIndexDoc, BACKGROUND_CONTEXT);
+        const pending = index?.pending ?? {};
+        const interactions = [];
+        for (const key of Object.keys(pending)) {
+            const id = Number(key);
+            const convId = conversationId(id);
+            // §5.9 visibility, applied in-handler (a no-`:id` route has no
+            // pre-handler): a hidden conversation contributes nothing.
+            if (!(await visibleTo(ctx, convId, request.principal))) {
+                continue;
+            }
+            for (const callId of pending[key] ?? []) {
+                const record = await opened.harness.snapshot(InteractionDoc, convId, callId, BACKGROUND_CONTEXT);
+                // The index is maintained in the same commits as the records,
+                // but a raced settle can leave a stale entry — serve only
+                // what still reads pending (the per-conversation list's guard).
+                if (record !== undefined && record.status === "pending") {
+                    interactions.push({ ...record, conversationId: id });
+                }
+            }
+        }
+        interactions.sort((a, b) => a.createdAt - b.createdAt);
+        return { interactions };
+    });
+    /** The list route's wire record: envelope + body + details, unmodified. */
+    app.get("/v1/conversations/:id/interactions", { schema: { params: ID_PARAMS_SCHEMA } }, async (request, reply) => {
+        const { id } = request.params;
+        const convId = conversationId(id);
+        // §5.9 visibility (the pre-handler-free polling convention means
+        // the rule is applied HERE): hidden → 404 conversation_not_found.
+        if (!(await visibleTo(ctx, convId, request.principal))) {
+            return await reply
+                .code(404)
+                .send({ error: "conversation_not_found" });
+        }
+        // Absent conversation → empty list (the ambient list's convention:
+        // a channel polling a torn-down conversation must not error).
+        const index = await opened.harness.snapshot(InteractionsIndexDoc, BACKGROUND_CONTEXT);
+        const pending = index?.pending[String(convId)] ?? [];
+        const records = [];
+        for (const callId of pending) {
+            const record = await opened.harness.snapshot(InteractionDoc, convId, callId, BACKGROUND_CONTEXT);
+            if (record !== undefined && record.status === "pending") {
+                records.push(record);
+            }
+        }
+        return { interactions: records };
+    });
+    // The ONE generic answer route: writes `answer` into the envelope with
+    // first-answer-wins inside the commit. 404 for unknown/not-pending;
+    // 400 for a malformed answer. `by` is "human" (the only v1 caller).
+    app.post("/v1/conversations/:id/interactions/:callId/answer", {
+        schema: { params: ANSWER_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx, "write"),
+    }, async (request, reply) => {
+        const { callId } = request.params;
+        const conversation = request.conversation;
+        const body = request.body;
+        // SAFETY: the spread of an explicitly-undefined InteractionAnswer
+        // builds an empty mutable scaffold — every field is optional, and
+        // each is set only after its body value passed validation, so the
+        // loose local type never leaks an unvalidated field.
+        const answer = {
+            ...undefined,
+        };
+        if (body !== undefined && body !== null) {
+            if (typeof body !== "object" || Array.isArray(body)) {
+                return await reply.code(400).send({ error: "invalid_body" });
+            }
+            const b = body;
+            const known = new Set(["ids", "values", "text"]);
+            const unknownKey = Object.keys(b).find((k) => !known.has(k));
+            if (unknownKey !== undefined) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: unknownKey });
+            }
+            if (b.ids !== undefined) {
+                if (!Array.isArray(b.ids) ||
+                    b.ids.some((v) => typeof v !== "string")) {
+                    return await reply
+                        .code(400)
+                        .send({ error: "invalid_body" });
+                }
+                answer.ids = b.ids;
+                // (mutable local; the wire type stays readonly)
+            }
+            if (b.values !== undefined) {
+                if (typeof b.values !== "object" || b.values === null) {
+                    return await reply.code(400).send({ error: "invalid_body" });
+                }
+                const values = {};
+                for (const [k, v] of Object.entries(b.values)) {
+                    if (typeof v !== "string" &&
+                        typeof v !== "number" &&
+                        typeof v !== "boolean") {
+                        return await reply
+                            .code(400)
+                            .send({ error: "invalid_field", field: `values.${k}` });
+                    }
+                    values[k] = v;
+                }
+                answer.values = values;
+            }
+            if (b.text !== undefined) {
+                if (typeof b.text !== "string") {
+                    return await reply.code(400).send({ error: "invalid_body" });
+                }
+                answer.text = b.text;
+            }
+        }
+        // The commit returns a plain outcome; reply shaping happens
+        // AFTER the commit (a Fastify reply must never travel through
+        // the harness mutation line).
+        const committed = await conversation.commit(async (tx) => {
+            const draft = await tx.doc(InteractionDoc, conversation.id, callId, callId);
+            // Unknown callId: the doc materializes empty — detect via kind
+            // never having been seeded (an empty seed has kind "").
+            if (draft.kind === "")
+                return { found: false };
+            const applied = applyAnswer(draft, answer, "human", Date.now(), request.principal.user);
+            if (!applied)
+                return { found: true, applied: false };
+            // NEVER re-read a mutated draft field (even before the next
+            // await): reading a newly-set nested value off the tracked
+            // draft trips chord's settled-overlay check. The response
+            // projects the INPUT answer — identical to what was written.
+            const index = await tx.doc(InteractionsIndexDoc);
+            indexSettled(index, conversation.id, callId);
+            return {
+                found: true,
+                applied: true,
+                answer,
+            };
+        }, BACKGROUND_CONTEXT);
+        if (!committed.found) {
+            return await reply.code(404).send({ error: "no_such_interaction" });
+        }
+        if (!committed.applied) {
+            return await reply.code(404).send({ error: "not_pending" });
+        }
+        return {
+            callId,
+            status: "answered",
+            answer: committed.answer,
+        };
+    });
+    // ─── Ambient seam ────────────────────────────────────────────────────
+    // The conversation's ambient surfaces, replacement-state reads.
+    app.get("/v1/conversations/:id/ambient", { schema: { params: ID_PARAMS_SCHEMA } }, async (request, reply) => {
+        const { id } = request.params;
+        const convId = conversationId(id);
+        // §5.9 visibility, applied in-handler like the interactions list.
+        if (!(await visibleTo(ctx, convId, request.principal))) {
+            return await reply
+                .code(404)
+                .send({ error: "conversation_not_found" });
+        }
+        const index = await opened.harness.snapshot(AmbientOwnersDoc, BACKGROUND_CONTEXT);
+        const keys = Object.keys(index?.owners ?? {});
+        const surfaces = [];
+        for (const key of keys) {
+            const surface = await opened.harness.snapshot(AmbientDoc, convId, key, BACKGROUND_CONTEXT);
+            // A surface owned but never written in THIS conversation is
+            // absent (owner registration is session-global; surfaces are
+            // conversation-scoped).
+            if (surface !== undefined && surface.body !== undefined) {
+                surfaces.push(surface);
+            }
+        }
+        return { ambient: surfaces };
+    });
+}

package/dist/server/routes/jobs.js

@@ -0,0 +1,271 @@
+/**
+ * Jobs Task 4 (spec §8.4 + §5.9): the `/v1/jobs` HTTP surface over
+ * Task 3's JobsService.
+ *
+ * ACCESS (§5.9, the conversations rule applied to job records): every
+ * route resolves `accessOf(principal, {owner, sharing})` against the
+ * job RECORD — hidden is 404 `job_not_found` on every `:id` route and
+ * absence from the list (no 403 tell); a read-only caller on a write
+ * route gets 403. The owner is server-stamped at create
+ * (`principal.user`; a body-carried `owner` is stripped) and moves only
+ * through the transfer path; `sharing` is the PATCH share surface
+ * (mirrored onto the record from the merged spec, exactly like a
+ * declared job).
+ *
+ * The HISTORY routes (`runs`/`revisions`) answer for a RETIRED job too,
+ * until retention trims its records — access is evaluated against the
+ * newest REVISION's owner/sharing then (the record is gone with the
+ * retire). `GET /v1/jobs/:id` itself requires a live record.
+ *
+ * DECLARED jobs (`file:`/`ext:` ids) are immutable: PATCH and DELETE
+ * return 409 `job_declared` (edit the source instead). Run-now honors
+ * the caller's write access and the job's own `overlap`.
+ */
+import { accessOf } from "@sigrun/shared/access";
+import { isSuperuser } from "../auth/principal.js";
+import { JobDeclaredError, JobNotFoundError } from "../../jobs/index.js";
+import { validateJobSpec } from "../../jobs/spec.js";
+/** The principal form `accessOf` takes (§5.9). */
+function accessPrincipal(request) {
+    return {
+        user: request.principal.user,
+        superuser: isSuperuser(request.principal),
+    };
+}
+/** The §5.9 resource form ({owner?, sharing?}) of a job row. */
+function resourceOf(row) {
+    return {
+        ...(row.owner === undefined ? {} : { owner: row.owner }),
+        ...(row.sharing === undefined ? {} : { sharing: row.sharing }),
+    };
+}
+/**
+ * The shared `:id` error mapping: unknown/hidden → 404 `job_not_found`;
+ * visible-but-readonly on a write route → 403 (the callers resolve
+ * access themselves; this only serves the two 404/403 replies).
+ */
+async function deny(reply, error) {
+    if (error === "forbidden") {
+        return await reply.code(403).send({ error: "forbidden" });
+    }
+    return await reply.code(404).send({ error: "job_not_found" });
+}
+/** The service's domain errors → the route's codes (409/404). */
+async function domainError(reply, error) {
+    if (error instanceof JobDeclaredError) {
+        return await reply.code(409).send({ error: "job_declared" });
+    }
+    if (error instanceof JobNotFoundError) {
+        return await reply.code(404).send({ error: "job_not_found" });
+    }
+    throw error;
+}
+/** Register the `/v1/jobs` routes. */
+export function registerJobRoutes(app, ctx) {
+    const { opened } = ctx;
+    const jobs = opened.jobs;
+    /**
+     * Resolve one job for the access rule: the live record's row when it
+     * exists; for a RETIRED job (the history routes' case) the newest
+     * revision's shape. `undefined` only when neither exists (unknown id).
+     */
+    const resolve = async (request, id) => {
+        const principal = accessPrincipal(request);
+        const wire = await jobs.get(id);
+        if (wire !== undefined) {
+            const { access: _ignored, ...row } = wire;
+            return { row, access: accessOf(principal, resourceOf(row)) };
+        }
+        // Retired: the newest revision answers until retention trims it.
+        const [newest] = await jobs.revisions(id);
+        if (newest === undefined)
+            return undefined;
+        const row = {
+            id,
+            name: newest.spec.name,
+            source: newest.source,
+            ...(newest.owner === undefined ? {} : { owner: newest.owner }),
+            ...(newest.sharing === undefined ? {} : { sharing: newest.sharing }),
+            schedule: newest.spec.schedule,
+            action: newest.spec.action,
+            enabled: newest.enabled,
+            version: newest.version,
+        };
+        return {
+            // The retired row's status went with the record; the nudge only
+            // needs identity + definition (clients refetch the list).
+            row: { ...row, state: "disabled" },
+            access: accessOf(principal, resourceOf(row)),
+        };
+    };
+    /** The read guard: unknown/hidden → the 404; the row otherwise. */
+    const visible = async (request, reply, id) => {
+        const resolved = await resolve(request, id);
+        if (resolved === undefined || resolved.access === "none") {
+            await deny(reply, "job_not_found");
+            return { denied: true };
+        }
+        return resolved;
+    };
+    // GET /v1/jobs — the caller-visible rows (hidden absent, access stamped).
+    app.get("/v1/jobs", async (request) => {
+        const principal = accessPrincipal(request);
+        const visibleJobs = [];
+        for (const row of await jobs.list()) {
+            const access = accessOf(principal, resourceOf(row));
+            if (access === "none")
+                continue;
+            visibleJobs.push({ ...row, access });
+        }
+        return { jobs: visibleJobs };
+    });
+    // GET /v1/jobs/:id — a live record only (history routes cover retired).
+    app.get("/v1/jobs/:id", async (request, reply) => {
+        const { id } = request.params;
+        const wire = await jobs.get(id);
+        if (wire === undefined) {
+            return await deny(reply, "job_not_found");
+        }
+        const access = accessOf(accessPrincipal(request), resourceOf(wire));
+        if (access === "none") {
+            return await deny(reply, "job_not_found");
+        }
+        return { job: { ...wire, access } };
+    });
+    // POST /v1/jobs — create (owner = the caller). Validation rejections
+    // carry the offending field path (the shared §6 error vocabulary).
+    app.post("/v1/jobs", async (request, reply) => {
+        const validated = validateJobSpec(request.body);
+        if (!validated.ok) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: validated.field });
+        }
+        // The owner is server-stamped (§5.9): a body-carried `spec.owner`
+        // is inert for api jobs — strip it so the record's spec and the
+        // stamped owner can never disagree.
+        const spec = { ...validated.spec };
+        delete spec.owner;
+        const job = await jobs.createApi(spec, request.principal.user);
+        return await reply.code(201).send({ job: { ...job, access: "write" } });
+    });
+    // PATCH /v1/jobs/:id — write access; the MERGED spec validates whole.
+    app.patch("/v1/jobs/:id", async (request, reply) => {
+        const { id } = request.params;
+        const resolved = await visible(request, reply, id);
+        if ("denied" in resolved)
+            return;
+        if (resolved.access !== "write") {
+            return await deny(reply, "forbidden");
+        }
+        const patch = request.body;
+        if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "spec" });
+        }
+        // §5.9's server-stamped posture: `owner` never moves through a
+        // patch (the transfer path owns it) — the conversations rule.
+        if ("owner" in patch) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "owner" });
+        }
+        // Validate the merged spec: a partial patch that breaks the whole
+        // is a 400, never a half-applied write. The route merges over the
+        // WIRE row minus its record-`owner` key (a wire `owner` would
+        // launder through as `spec.owner` — the stamped owner is preserved
+        // by the service); `overlap`/`catchUp` ride from the stored spec
+        // inside the service (validated at their own writes), and a patch
+        // renaming the job carries its own validated name.
+        const { owner: _recordOwner, ...base } = resolved.row;
+        const merged = validateJobSpec({
+            ...base,
+            ...patch,
+        });
+        if (!merged.ok) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: merged.field });
+        }
+        try {
+            // Pass the VALIDATED rebuilt spec (only declared, validated keys
+            // survive validateJobSpec's rebuild): a body carrying unknown keys
+            // (`id`, `state`, …) can never smuggle them into the stored spec.
+            // The service's own spread over the prior spec keeps prior fields
+            // the patch left absent (`overlap`/`catchUp`).
+            const job = await jobs.updateApi(id, merged.spec, request.principal.user ?? "api");
+            return { job: { ...job, access: "write" } };
+        }
+        catch (error) {
+            return await domainError(reply, error);
+        }
+    });
+    // DELETE /v1/jobs/:id — write access; api jobs only.
+    app.delete("/v1/jobs/:id", async (request, reply) => {
+        const { id } = request.params;
+        const resolved = await visible(request, reply, id);
+        if ("denied" in resolved)
+            return;
+        if (resolved.access !== "write") {
+            return await deny(reply, "forbidden");
+        }
+        try {
+            await jobs.deleteApi(id, request.principal.user ?? "api");
+            return await reply.code(204).send();
+        }
+        catch (error) {
+            return await domainError(reply, error);
+        }
+    });
+    // POST /v1/jobs/:id/run — write access; fires now (overlap honored).
+    // A LIVE record is required (like PATCH/DELETE): a retired job's
+    // revision never satisfies run-now — 404, never fireJob's blocked-200
+    // (a deleted job must not be re-triggerable through its history tail).
+    app.post("/v1/jobs/:id/run", async (request, reply) => {
+        const { id } = request.params;
+        const wire = await jobs.get(id);
+        if (wire === undefined) {
+            return await deny(reply, "job_not_found");
+        }
+        const access = accessOf(accessPrincipal(request), resourceOf(wire));
+        if (access === "none") {
+            return await deny(reply, "job_not_found");
+        }
+        if (access === "read") {
+            return await deny(reply, "forbidden");
+        }
+        return await jobs.runNow(id);
+    });
+    // GET /v1/jobs/:id/runs?limit= — newest first; answers for retired
+    // jobs (the revision-resolved access) until retention trims them.
+    app.get("/v1/jobs/:id/runs", async (request, reply) => {
+        const { id } = request.params;
+        const resolved = await visible(request, reply, id);
+        if ("denied" in resolved)
+            return;
+        // limit: default 20, a positive integer, capped at jobHistory.runs
+        // (read live — a settings PATCH reaches the next call).
+        const query = request.query;
+        const cap = opened.settings.read().jobHistory?.runs ?? 50;
+        let limit = 20;
+        if (query.limit !== undefined) {
+            const parsed = Number(query.limit);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "limit" });
+            }
+            limit = Math.min(parsed, cap);
+        }
+        return { runs: await jobs.runs(id, limit) };
+    });
+    // GET /v1/jobs/:id/revisions — newest first; same retired-job rule.
+    app.get("/v1/jobs/:id/revisions", async (request, reply) => {
+        const { id } = request.params;
+        const resolved = await visible(request, reply, id);
+        if ("denied" in resolved)
+            return;
+        return { revisions: await jobs.revisions(id) };
+    });
+}

package/dist/server/routes/meta.js

@@ -0,0 +1,146 @@
+/**
+ * Boot-fact routes: `GET /v1/meta` (the real health aggregation + seam
+ * inventory + collision record) and `GET /v1/commands` (the slash-command
+ * catalog). Both are pure derivations over boot-retained state — a client
+ * may cache them.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { aggregateHealth } from "../../harness/health.js";
+import { isBackupMarkerStale, readBackupMarker } from "../../backup/marker.js";
+import { expandableTemplates } from "../../commands/expand.js";
+import { discoverTemplates } from "../../commands/templates.js";
+import { listSkills } from "../../skills/index.js";
+import { expandCommandEntries } from "../commands.js";
+import { HARNESS_VERSION, SCHEMA_VERSION } from "../schema-fixture.js";
+/** Register `GET /v1/meta` + `GET /v1/commands`. */
+export function registerMetaRoutes(app, ctx) {
+    const { opened, config, webuiBundle, commandCatalog } = ctx;
+    app.get("/v1/meta", async () => {
+        // Idle-worker projection: re-derived per request (statuses change
+        // over the process lifetime); quarantined extensions never
+        // registered, so a name miss just yields no workers.
+        const workerStatuses = opened.workerStatuses();
+        // §6.8 backup honesty: the last-success marker is read PER REQUEST
+        // from config.stateDir (the CronJob is a separate process — the only
+        // fresh-enough view is the filesystem). Unconfigured stays
+        // presence-derived; configured degrades when the marker is absent,
+        // corrupt, or older than server.backup.staleAfterHours (default 36 h).
+        const backupConfigured = config.backup !== undefined;
+        const marker = backupConfigured
+            ? await readBackupMarker(config.stateDir)
+            : undefined;
+        const backupHealth = !backupConfigured
+            ? "unconfigured"
+            : marker === undefined ||
+                isBackupMarkerStale(marker, config.backupStaleAfterHours)
+                ? "degraded"
+                : "configured";
+        return {
+            harnessVersion: HARNESS_VERSION,
+            schemaVersion: SCHEMA_VERSION,
+            extensions: opened.extensionOutcomes.map((outcome) => {
+                const workers = workerStatuses.get(outcome.name);
+                return {
+                    name: outcome.name,
+                    status: outcome.status,
+                    ...(outcome.error === undefined ? {} : { error: outcome.error }),
+                    ...(workers === undefined || workers.length === 0
+                        ? {}
+                        : { workers }),
+                };
+            }),
+            // §5 health: pure aggregation over boot-retained §3 producers —
+            // memory from the memory extension's producer ("ok" for the no-op
+            // default — quarantines surface via extensions[].status, never
+            // double-reported here), providers aggregated across
+            // contributors (empty → "ok"), and backup from the §6.8 marker
+            // derivation above ("configured" only while a fresh success
+            // exists — the one storage read this route makes).
+            health: {
+                backup: backupHealth,
+                memory: opened.memoryHealth?.() ?? "ok",
+                providers: aggregateHealth(opened.providerHealth),
+            },
+            // The auth block (W1 Task 6, spec §5.7): the effective method list
+            // (resolved once in `createServer`) + the onboarding state — both
+            // pure derivations, never per-request negotiation.
+            auth: {
+                methods: ctx.methods,
+                claimed: opened.identity.users.isClaimed(),
+            },
+            // §6.8: the marker's timestamp — when the last successful backup
+            // ran, whenever one is recorded against a configured target (a
+            // STALE marker still surfaces: "when was the last success" is
+            // exactly what a degraded badge begs for).
+            backup: marker === undefined
+                ? {}
+                : { lastSuccessAt: marker.at },
+            // §5 capabilities: backup affordances exist iff a target is
+            // configured (the badge, not an error, when absent).
+            capabilities: {
+                backup: config.backup !== undefined,
+                // §4.1/§6 channels: the SELECTED bundle's name ("webui" for the
+                // built-in default and explicit paths; a contributed selection's own
+                // name) exactly while the channel bundle is mounted; an API-only
+                // deploy (gate off or absent default) reports [].
+                channels: webuiBundle === undefined ? [] : [webuiBundle.channel],
+            },
+            // The seam inventory: declaration-derived, no doc reads.
+            seam: {
+                interactions: [...opened.seamKinds]
+                    .filter(([, kinds]) => (kinds.interaction?.length ?? 0) > 0)
+                    .map(([name, kinds]) => ({
+                    extension: name,
+                    kinds: [...(kinds.interaction ?? [])],
+                })),
+                ambient: [...opened.seamKinds]
+                    .filter(([, kinds]) => (kinds.ambient?.length ?? 0) > 0)
+                    .map(([name, kinds]) => ({
+                    extension: name,
+                    keys: [...(kinds.ambient ?? [])],
+                })),
+            },
+            // Boot-merge collisions: name collisions among
+            // extension-contributed webui bundles, the provider-merge sink,
+            // and extension command names (W5 Task 3). Last-registered-wins
+            // everywhere; the record is operator visibility, never an error
+            // (a core-name command collision is dropped + warned at build,
+            // deliberately absent here).
+            collisions: {
+                webui: opened.webuiBundleCollisions,
+                providers: opened.providerCollisions,
+                commands: commandCatalog.collisions,
+            },
+        };
+    });
+    // The slash-command catalog: the thin metadata list the composer's `/`
+    // menu consumes — name, description, args hint, and the endpoint each
+    // command drives (pi parity: thin metadata over the endpoints the other
+    // routes serve). Since W5 Task 3 this is the MERGED catalog (the core
+    // table + extension entries, each carrying its `extension` slug and
+    // invoke endpoint). Since Task 2c the response is built PER REQUEST:
+    // the trailing `kind: "expand"` entries (every discovered skill as
+    // `skill:<name>`, plus the templates) are re-scanned live — skills and
+    // templates appear the moment their files land, no reload command. The
+    // core + extension halves remain boot constants; see `commands.ts` for
+    // the scope rulings.
+    app.get("/v1/commands", async () => {
+        // The workspace root (the first of the three) reads through a
+        // workspace env, exactly like skill discovery at generation time;
+        // the catalog scan uses the root conversation's env — the static
+        // workspace every conversation resolves to today.
+        const expansion = opened.commandExpansion;
+        const env = await opened.envBuilder({ conversationId: ctx.rootId, read: opened.harness }, BACKGROUND_CONTEXT);
+        if (env === undefined) {
+            throw new Error("envBuilder returned no ExecutionEnv");
+        }
+        const skills = await listSkills(env, BACKGROUND_CONTEXT, expansion.skills);
+        const templates = expandableTemplates(await discoverTemplates(env, BACKGROUND_CONTEXT, expansion.templates), expansion.commandNames());
+        return {
+            commands: [
+                ...commandCatalog.commands,
+                ...expandCommandEntries(skills, templates),
+            ],
+        };
+    });
+}