@openrig/cli 0.3.0 → 0.3.2

package/daemon/dist/routes/missions.js

@@ -0,0 +1,195 @@
+// V0.3.1 slice 12 walk-item 1 — mission scope data layer.
+// V0.3.1 slice 13 walk-item 7 — extended with workflow_spec frontmatter
+// + projected topology spec graph.
+//
+// GET /api/missions/:missionId — returns aggregated mission metadata
+// (missionPath + slices + optional workflow_spec declaration + optional
+// projected topology). Powers the Mission Overview / Progress / Topology
+// tabs in the Project surface; pairs with useScopeMarkdown for README /
+// PROGRESS content via the existing /api/files/read route.
+//
+// Returns:
+//   200 {
+//     missionId, missionPath, slices,
+//     workflow_spec: { name, version } | null,
+//     topology: { specGraph: SpecGraphPayload | null } | null
+//   }
+//   404 { error: "mission_not_found" } when no slices match
+//   503 { error: "slices_indexer_unavailable" } when indexer not wired
+//   503 { error: "slices_root_not_configured" } when indexer not ready
+//
+// workflow_spec is parsed lazily from <missionPath>/README.md frontmatter
+// using the same parser the slice-indexer uses. topology.specGraph is
+// projected via projectSpecGraph(spec, null) when the spec is in the
+// WorkflowSpecCache; { specGraph: null } when declared but not cached;
+// null when nothing is declared.
+import { Hono } from "hono";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseWorkflowSpecRef } from "../domain/slices/slice-indexer.js";
+import { projectSpecGraph } from "../domain/workflow/slice-workflow-projection.js";
+export function missionsRoutes() {
+    const app = new Hono();
+    app.get("/:missionId", (c) => {
+        const indexer = c.get("sliceIndexer");
+        if (!indexer) {
+            return c.json({
+                error: "slices_indexer_unavailable",
+                hint: "Mission data layer requires the SliceIndexer to be wired into AppDeps.",
+            }, 503);
+        }
+        if (!indexer.isReady()) {
+            return c.json({
+                error: "slices_root_not_configured",
+                hint: "Run rig config init-workspace, or set workspace.slices_root to workspace/missions. Supported shape: missions/<mission>/slices/<slice>.",
+            }, 503);
+        }
+        const missionId = c.req.param("missionId");
+        const allSlices = indexer.list();
+        const slices = allSlices.filter((s) => s.missionId === missionId);
+        if (slices.length === 0) {
+            return c.json({ error: "mission_not_found", missionId }, 404);
+        }
+        const missionPath = computeMissionPath(slices[0]);
+        const workflowSpec = readMissionWorkflowSpec(missionPath);
+        const topology = computeMissionTopology(workflowSpec, c.get("workflowSpecCache"));
+        const status = readMissionStatus(missionPath);
+        return c.json({
+            missionId,
+            missionPath,
+            slices,
+            workflow_spec: workflowSpec,
+            topology,
+            status,
+        });
+    });
+    // Slice 18 §3.5 — Mark mission complete (Getting Started complete-and-hide).
+    // Writes `status: complete` to the mission README.md frontmatter; the UI
+    // storytelling preview gates on this so completed missions disappear from
+    // the band. The daemon is the audit-trail surface; the UI maintains
+    // an optimistic local mirror via localStorage so the hide is instant.
+    app.post("/:missionId/complete", (c) => {
+        const indexer = c.get("sliceIndexer");
+        if (!indexer) {
+            return c.json({ error: "slices_indexer_unavailable" }, 503);
+        }
+        const missionId = c.req.param("missionId");
+        const allSlices = indexer.list();
+        const slices = allSlices.filter((s) => s.missionId === missionId);
+        if (slices.length === 0) {
+            return c.json({ error: "mission_not_found", missionId }, 404);
+        }
+        const missionPath = computeMissionPath(slices[0]);
+        try {
+            writeMissionStatusComplete(missionPath);
+        }
+        catch (err) {
+            return c.json({
+                error: "mission_complete_write_failed",
+                missionId,
+                message: err.message,
+            }, 500);
+        }
+        return c.json({ missionId, status: "complete" });
+    });
+    return app;
+}
+/** Slice 18 §3.5 — write `status: complete` to a mission README's
+ *  frontmatter, creating the frontmatter block when absent and
+ *  replacing an existing status field when present. Idempotent.
+ *  Preserves unrelated frontmatter fields. */
+function writeMissionStatusComplete(missionPath) {
+    const readmePath = path.join(missionPath, "README.md");
+    let body = fs.existsSync(readmePath) ? fs.readFileSync(readmePath, "utf-8") : "";
+    const fmMatch = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (fmMatch) {
+        const fmInner = fmMatch[1] ?? "";
+        const statusLineRegex = /^\s*status\s*:\s*[^\r\n]*$/m;
+        let newFm;
+        if (statusLineRegex.test(fmInner)) {
+            newFm = fmInner.replace(statusLineRegex, "status: complete");
+        }
+        else {
+            newFm = fmInner.trimEnd() + "\nstatus: complete";
+        }
+        body = body.replace(fmMatch[0], `---\n${newFm}\n---`);
+    }
+    else {
+        body = `---\nstatus: complete\n---\n${body}`;
+    }
+    fs.writeFileSync(readmePath, body);
+}
+/** Derive the mission folder's absolute path from any slice's
+ *  `slicePath`. Slices live at
+ *  `<missionsRoot>/<missionId>/slices/<sliceName>` per the workspace
+ *  contract, so going up two levels yields the mission folder. */
+function computeMissionPath(slice) {
+    return path.resolve(slice.slicePath, "..", "..");
+}
+/** Slice 18 §3.5 — parse the `status` field from the mission README's
+ *  frontmatter. Returns the string when present (no enum validation —
+ *  v0 callers care primarily about the "complete" value but other
+ *  workflow states may appear), or null when the README is missing /
+ *  the field is absent. Powers the durable storytelling-filter for
+ *  Getting Started complete-and-hide. */
+function readMissionStatus(missionPath) {
+    const readmePath = path.join(missionPath, "README.md");
+    if (!fs.existsSync(readmePath))
+        return null;
+    const raw = fs.readFileSync(readmePath, "utf-8");
+    const fm = parseSimpleFrontmatter(raw);
+    const value = fm["status"];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/** V0.3.1 slice 13 walk-item 7 — parse `workflow_spec` from the mission
+ *  README's frontmatter. Returns null when the README is missing or the
+ *  field is absent / malformed. Uses the same parseWorkflowSpecRef
+ *  helper the slice-indexer uses so both surfaces stay in lockstep. */
+function readMissionWorkflowSpec(missionPath) {
+    const readmePath = path.join(missionPath, "README.md");
+    if (!fs.existsSync(readmePath))
+        return null;
+    const raw = fs.readFileSync(readmePath, "utf-8");
+    const fm = parseSimpleFrontmatter(raw);
+    return parseWorkflowSpecRef(fm["workflow_spec"]);
+}
+/** Minimal frontmatter parser. The slice-indexer's parseFrontmatter is
+ *  private; duplicating the v0 shape here is cheaper than exposing
+ *  internal API and keeps the missions route's surface minimal. */
+function parseSimpleFrontmatter(text) {
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m)
+        return {};
+    const out = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = trimmed.slice(0, colonIdx).trim();
+        let value = trimmed.slice(colonIdx + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/** V0.3.1 slice 13 walk-item 7 — project the spec graph when both the
+ *  declaration AND the cached spec are present. Returns the topology
+ *  envelope with `specGraph: null` when declared but not yet cached;
+ *  returns `null` for the whole envelope when nothing is declared. */
+function computeMissionTopology(workflowSpec, specCache) {
+    if (!workflowSpec)
+        return null;
+    if (!specCache)
+        return { specGraph: null };
+    const row = specCache.getByNameVersion(workflowSpec.name, workflowSpec.version);
+    if (!row)
+        return { specGraph: null };
+    // WorkflowSpecRow.spec is the WorkflowSpec object the projector expects.
+    return { specGraph: projectSpecGraph(row.spec, null) };
+}
+//# sourceMappingURL=missions.js.map

package/daemon/dist/routes/missions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missions.js","sourceRoot":"","sources":["../../src/routes/missions.ts"],"names":[],"mappings":"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"}

package/daemon/dist/routes/plugins.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+export declare function pluginsRoutes(): Hono;
+//# sourceMappingURL=plugins.d.ts.map

package/daemon/dist/routes/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/routes/plugins.ts"],"names":[],"mappings":"AAwCA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAkE5B,wBAAgB,aAAa,IAAI,IAAI,CA4HpC"}

package/daemon/dist/routes/plugins.js

@@ -0,0 +1,223 @@
+// Phase 3a slice 3.3 — Plugins HTTP routes (read-only).
+//
+// SC-29 EXCEPTION #8 declared verbatim:
+// "Slice 3.3 (UI plugin surface) requires daemon-side plugin-discovery-service
+// + 3 HTTP routes (GET /api/plugins, GET /api/plugins/:id, GET /api/plugins/:id/used-by)
+// as backing API. No additional state, no SQL migration, no mutation routes.
+// Read-only discovery surface aggregating filesystem-scan unions per
+// DESIGN.md §5.4. Per IMPL-PRD §3.3 'Code touches' this allocation is explicit;
+// documenting in compliance with banked SC-29 verbatim-declaration rule."
+//
+// SC-29 EXCEPTION #11 (slice 28 library-explorer-finishing) declared verbatim:
+// "Slice 28 (Library Explorer finishing — founder-walk follow-up) requires:
+// (a) two additive read-only HTTP routes — GET /api/plugins/:id/files/list
+// and GET /api/plugins/:id/files/read — that wrap the existing path-safety
+// machinery (resolveAllowedDirectory/File) with the discovered plugin's
+// absolute path acting as a synthetic single-root allowlist. Enables
+// docs-browser file navigation of a plugin's on-disk folder without
+// requiring the operator to allowlist ~/.openrig/plugins/ in
+// OPENRIG_FILES_ALLOWLIST.
+// (b) one PluginEntry shape extension — skillCount: number — populated in
+// detectPlugin() by readdir of <plugin>/skills/. Surfaces skill-count in
+// the plugin list response so PluginsIndexPage can render the column
+// without an N+1 detail fetch per row.
+// No additional state, no SQL migration, no write mutations on plugin
+// folders. Read-only docs-browser surface per slice 28 founder direction
+// 'finishing it is 0.3.1 work, not 0.3.2'. Routing decision
+// qitem-20260513042155-f31c11c3 (orch OPT-A authorization)."
+//
+// Endpoint shape:
+//   GET /api/plugins                              → PluginEntry[]   (?runtime=, ?source= filters)
+//   GET /api/plugins/:id                          → PluginDetail    (404 when unknown)
+//   GET /api/plugins/:id/used-by                  → AgentReference[]
+//   GET /api/plugins/:id/files/list?path=<rel>    → FilesListResponse (slice 28)
+//   GET /api/plugins/:id/files/read?path=<rel>    → FilesReadResponse (slice 28)
+//
+// All endpoints return 503 when the service is not provisioned in context
+// (consistent with the existing daemon route pattern for optional services).
+// /files/list + /files/read use the discovered plugin path as a synthetic
+// AllowlistRoot + reuse resolveAllowedDirectory/File for path-safety.
+import { Hono } from "hono";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveAllowedDirectory, resolveAllowedFile, FilePathSafetyError, } from "../domain/files/path-safety.js";
+import { sha256Hex } from "../domain/files/file-write-service.js";
+import { FILE_READ_TRUNCATION_BYTES } from "./files.js";
+function getService(c) {
+    return c.get("pluginDiscoveryService");
+}
+function parseRuntimeFilter(value) {
+    if (value === "claude" || value === "codex")
+        return value;
+    return undefined;
+}
+function parseSourceFilter(value) {
+    if (value === "vendored" || value === "claude-cache" || value === "codex-cache")
+        return value;
+    return undefined;
+}
+function pluginRootAllowlist(absolutePath) {
+    // Synthetic single-root allowlist scoped to the plugin's folder.
+    // Reuses the existing path-safety helpers for ../ escape / symlink
+    // realpath containment checks without any allowlist env-var coupling
+    // (operator does not need to declare plugin paths in OPENRIG_FILES_ALLOWLIST).
+    //
+    // Normalize via fs.realpathSync so the containment check (realpath vs
+    // canonicalPath) holds on platforms where the input path is itself
+    // a symlink chain (e.g. macOS /tmp → /private/tmp, /var/folders →
+    // /private/var/folders). Matches decodeAllowlist's normalization in
+    // path-safety.ts.
+    let canonical;
+    try {
+        canonical = fs.realpathSync(absolutePath);
+    }
+    catch {
+        canonical = path.resolve(absolutePath);
+    }
+    return [{ name: "plugin", canonicalPath: canonical }];
+}
+function pathSafetyErrorResponse(c, err) {
+    const status = err.code === "root_unknown" ? 400
+        : err.code === "path_invalid" || err.code === "path_escape" ? 400
+            : err.code === "stat_failed" ? 404
+                : err.code === "not_a_file" || err.code === "not_a_directory" ? 400
+                    : 500;
+    return c.json({ error: err.code, message: err.message, ...(err.details ?? {}) }, status);
+}
+export function pluginsRoutes() {
+    const router = new Hono();
+    // GET / — list discoverable plugins
+    router.get("/", (c) => {
+        const service = getService(c);
+        if (!service)
+            return c.json({ error: "plugin_discovery_unavailable" }, 503);
+        const runtimeFilter = parseRuntimeFilter(c.req.query("runtime"));
+        const sourceFilter = parseSourceFilter(c.req.query("source"));
+        // Slice 3.3 fix-C — DESIGN §5.4 union 4th category: rig-bundled
+        // <cwd>/.claude/plugins/* + <cwd>/.codex/plugins/*. The API caller
+        // (UI in rig context, CLI in slice 3.4) passes ?cwd=<path> when
+        // they want the rig-cwd discoveries included; the Library page
+        // omits it (cross-cutting view).
+        const cwd = c.req.query("cwd");
+        const cwdScanRoots = cwd ? [cwd] : undefined;
+        const plugins = service.listPlugins({ runtimeFilter, sourceFilter, cwdScanRoots });
+        return c.json(plugins);
+    });
+    // GET /:id/used-by — reverse query for agents referencing this plugin.
+    // Mounted BEFORE /:id so the literal sub-path doesn't get eaten by the
+    // bare-param catchall (per spec-library-routes Phase A R1 SSE route-order
+    // lesson banked in that file).
+    router.get("/:id/used-by", (c) => {
+        const service = getService(c);
+        if (!service)
+            return c.json({ error: "plugin_discovery_unavailable" }, 503);
+        const id = c.req.param("id");
+        return c.json(service.findUsedBy(id));
+    });
+    // Slice 28 — GET /:id/files/list?path=<rel>
+    // Lists directory entries inside the plugin's source folder. Uses the
+    // existing path-safety helpers with a synthetic single-root allowlist
+    // built from the discovered plugin's absolute path. Mounted BEFORE the
+    // bare /:id route (same route-order discipline as /:id/used-by).
+    router.get("/:id/files/list", (c) => {
+        const service = getService(c);
+        if (!service)
+            return c.json({ error: "plugin_discovery_unavailable" }, 503);
+        const id = c.req.param("id");
+        const detail = service.getPlugin(id);
+        if (!detail)
+            return c.notFound();
+        const relativePath = c.req.query("path") ?? "";
+        try {
+            const allowlist = pluginRootAllowlist(detail.entry.path);
+            const resolved = resolveAllowedDirectory(allowlist, "plugin", relativePath);
+            const entries = fs.readdirSync(resolved, { withFileTypes: true });
+            return c.json({
+                pluginId: id,
+                path: relativePath,
+                entries: entries
+                    .map((entry) => {
+                    const fullPath = path.join(resolved, entry.name);
+                    let stat = null;
+                    try {
+                        stat = fs.statSync(fullPath);
+                    }
+                    catch { /* skip stat-failed */ }
+                    return {
+                        name: entry.name,
+                        type: entry.isDirectory() ? "dir" : entry.isFile() ? "file" : "other",
+                        size: stat?.isFile() ? stat.size : null,
+                        mtime: stat ? stat.mtime.toISOString() : null,
+                    };
+                })
+                    .sort((a, b) => {
+                    if (a.type !== b.type)
+                        return a.type === "dir" ? -1 : 1;
+                    return a.name.localeCompare(b.name);
+                }),
+            });
+        }
+        catch (err) {
+            if (err instanceof FilePathSafetyError)
+                return pathSafetyErrorResponse(c, err);
+            return c.json({ error: "list_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    // Slice 28 — GET /:id/files/read?path=<rel>
+    // Reads a file inside the plugin's source folder. Same truncation cap
+    // semantics as /api/files/read (FILE_READ_TRUNCATION_BYTES; hash over
+    // full content for honest edit-conflict semantics — but plugin folders
+    // are read-only at v0 so the hash is informational only).
+    router.get("/:id/files/read", (c) => {
+        const service = getService(c);
+        if (!service)
+            return c.json({ error: "plugin_discovery_unavailable" }, 503);
+        const id = c.req.param("id");
+        const detail = service.getPlugin(id);
+        if (!detail)
+            return c.notFound();
+        const relativePath = c.req.query("path") ?? "";
+        if (!relativePath)
+            return c.json({ error: "path_required" }, 400);
+        try {
+            const allowlist = pluginRootAllowlist(detail.entry.path);
+            const resolved = resolveAllowedFile(allowlist, "plugin", relativePath);
+            const stat = fs.statSync(resolved);
+            const fullContent = fs.readFileSync(resolved);
+            const truncated = stat.size > FILE_READ_TRUNCATION_BYTES;
+            const returnedContent = truncated
+                ? fullContent.subarray(0, FILE_READ_TRUNCATION_BYTES)
+                : fullContent;
+            return c.json({
+                pluginId: id,
+                path: relativePath,
+                absolutePath: resolved,
+                content: returnedContent.toString("utf-8"),
+                mtime: stat.mtime.toISOString(),
+                contentHash: sha256Hex(fullContent),
+                size: stat.size,
+                truncated,
+                truncatedAtBytes: truncated ? FILE_READ_TRUNCATION_BYTES : null,
+                totalBytes: stat.size,
+            });
+        }
+        catch (err) {
+            if (err instanceof FilePathSafetyError)
+                return pathSafetyErrorResponse(c, err);
+            return c.json({ error: "read_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    // GET /:id — plugin detail
+    router.get("/:id", (c) => {
+        const service = getService(c);
+        if (!service)
+            return c.json({ error: "plugin_discovery_unavailable" }, 503);
+        const id = c.req.param("id");
+        const detail = service.getPlugin(id);
+        if (!detail)
+            return c.notFound();
+        return c.json(detail);
+    });
+    return router;
+}
+//# sourceMappingURL=plugins.js.map

package/daemon/dist/routes/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../../src/routes/plugins.ts"],"names":[],"mappings":"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"}

package/daemon/dist/routes/queue.d.ts

@@ -6,5 +6,23 @@ import { Hono } from "hono";
  * Hot-potato strict-rejection happens in the domain layer; routes surface
  * structured errors with the validReasons enum so CLIs can render help.
  */
+/**
+ * OPR.0.3.2.20 — attention-class predicate for the `/list?attention=1`
+ * filter. Mirrors the mission-control read layer's semantics so the
+ * For You Action-required + Approval lenses agree with the
+ * single-pane view:
+ *
+ *   - approval class  → tier === "human-gate"
+ *   - action-required → destinationSession matches
+ *                       /^human(?:-[A-Za-z0-9._-]+)?@(kernel|host)$/
+ *
+ * Exported so the predicate is a discrete, testable surface. The route
+ * layer composes this with the open-state default so only unresolved
+ * items appear — closed/done attention items are not surfaced.
+ */
+export declare function isAttentionItem(q: {
+    tier: string | null;
+    destinationSession: string;
+}): boolean;
 export declare function queueRoutes(): Hono;
 //# sourceMappingURL=queue.d.ts.map

package/daemon/dist/routes/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/routes/queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAa5B;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAkdlC"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/routes/queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAa5B;;;;;;GAMG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAG/F;AAGD,wBAAgB,WAAW,IAAI,IAAI,CA8hBlC"}

package/daemon/dist/routes/queue.js

@@ -9,6 +9,25 @@ import { InboxHandlerError } from "../domain/inbox-handler.js";
  * Hot-potato strict-rejection happens in the domain layer; routes surface
  * structured errors with the validReasons enum so CLIs can render help.
  */
+/**
+ * OPR.0.3.2.20 — attention-class predicate for the `/list?attention=1`
+ * filter. Mirrors the mission-control read layer's semantics so the
+ * For You Action-required + Approval lenses agree with the
+ * single-pane view:
+ *
+ *   - approval class  → tier === "human-gate"
+ *   - action-required → destinationSession matches
+ *                       /^human(?:-[A-Za-z0-9._-]+)?@(kernel|host)$/
+ *
+ * Exported so the predicate is a discrete, testable surface. The route
+ * layer composes this with the open-state default so only unresolved
+ * items appear — closed/done attention items are not surfaced.
+ */
+export function isAttentionItem(q) {
+    if (q.tier === "human-gate")
+        return true;
+    return /^human(?:-[A-Za-z0-9._-]+)?@(kernel|host)$/.test(q.destinationSession ?? "");
+}
 export function queueRoutes() {
     const app = new Hono();
     function getRepo(c) {
@@ -145,7 +164,29 @@ export function queueRoutes() {
             return errorResponse(c, err);
         }
     });
-    // POST /:qitemId/update — general state mutator (incl. done)
+    // POST /:qitemId/update — general state mutator (incl. done).
+    //
+    // OPR.0.3.2.21.FR-4(d-docs) — closure ≠ acceptance.
+    //
+    // `state=done` with `closure_reason=handed_off_to` records that the
+    // source seat has DELIVERED the work to the next stage. It does NOT
+    // record that the next stage has ACCEPTED the work — that's the next
+    // stage's verdict on its own qitem (typically a separate close with
+    // its own closure_reason).
+    //
+    // Closure vocabulary:
+    //   - handed_off_to    delivered to next stage; acceptance pending
+    //                      that stage's verdict on its own qitem
+    //   - blocked_on       waiting on a named blocker (closureTarget)
+    //   - denied           the source seat refuses the work
+    //   - canceled         work no longer needed (no follow-on)
+    //   - no-follow-on     completed in place; no further routing
+    //   - escalation       routed to a higher-authority seat
+    //
+    // The "accepted" state IS NOT a queue state in v0.3.x — the qitem
+    // model captures delivery + the receiving stage owns acceptance as
+    // a separate transaction. (FR-4d-state schema change adding a
+    // distinct "accepted" state is deferred to release-0.3.3.)
     app.post("/:qitemId/update", async (c) => {
         const qitemId = c.req.param("qitemId");
         const body = await c.req.json().catch(() => ({}));
@@ -260,15 +301,66 @@ export function queueRoutes() {
         return c.json(getRepo(c).whoami(session, { recentLimit }));
     });
     // GET /list — list with filters. MUST precede /:qitemId so the literal path wins.
+    //
+    // OPR.0.3.2.20 — `?attention=1` filter for the For You priority
+    // windowing slice. Returns OPEN attention-class qitems (the durable
+    // source of truth for the UI Action-required + Approval lenses) so
+    // those surfaces don't depend on the lossy ephemeral client event
+    // FIFO. Class membership matches the mission-control read layer
+    // semantics: tier='human-gate' OR destination matches
+    // /^human(?:-[A-Za-z0-9._-]+)?@(kernel|host)$/. Open state defaults
+    // to pending|in-progress|blocked (callers can still override via
+    // `state=...`). Composable with destinationSession/sourceSession/
+    // targetRepo/limit.
     app.get("/list", (c) => {
         const destinationSession = c.req.query("destinationSession") || undefined;
         const sourceSession = c.req.query("sourceSession") || undefined;
         const stateRaw = c.req.query("state") || undefined;
         const targetRepo = c.req.query("targetRepo") || undefined;
-        const limit = c.req.query("limit") ? Number.parseInt(c.req.query("limit"), 10) : undefined;
-        const state = stateRaw ? stateRaw.split(",") : undefined;
-        const items = getRepo(c).list({ destinationSession, sourceSession, state, targetRepo, limit });
-        return c.json(items);
+        const userLimit = c.req.query("limit") ? Number.parseInt(c.req.query("limit"), 10) : undefined;
+        const attention = c.req.query("attention") === "1";
+        const state = stateRaw
+            ? stateRaw.split(",")
+            : attention
+                ? ["pending", "in-progress", "blocked"]
+                : undefined;
+        if (!attention) {
+            const items = getRepo(c).list({
+                destinationSession,
+                sourceSession,
+                state,
+                targetRepo,
+                limit: userLimit,
+            });
+            return c.json(items);
+        }
+        // OPR.0.3.2.20 — attention path goes through
+        // QueueRepository.listAttention, which pushes the attention
+        // predicate INTO the SQL WHERE clause so the LIMIT applies AFTER
+        // attention filtering. Window-independent by construction: an
+        // old human-gate item is never evicted by routine open qitems,
+        // however many of them land after it (guard re-verify
+        // qitem-20260518190827 BLOCKER 1). The earlier fetch-then-filter
+        // shape (ATTENTION_FETCH_BOUND) is gone — the LIMIT bound is the
+        // user-facing one only, applied at the SQL layer post-predicate.
+        //
+        // destinationSession/sourceSession/targetRepo are composable with
+        // the attention predicate at the SQL layer (guard re-verify
+        // qitem-20260518192210 BLOCKER 1 — the previous forward-fix
+        // dropped composition). Scoped attention queries (e.g.,
+        // attention=1&destinationSession=...) return ONLY the matching
+        // attention items.
+        const items = getRepo(c).listAttention({
+            limit: userLimit,
+            state,
+            destinationSession,
+            sourceSession,
+            targetRepo,
+        });
+        // Defense-in-depth: refine with the JS predicate so the SQL
+        // LIKE superset cannot leak a malformed destination through.
+        const filtered = items.filter(isAttentionItem);
+        return c.json(filtered);
     });
     // GET /overdue — surfaces in-progress qitems past closure_required_at.
     // MUST precede /:qitemId.