@openrig/cli 0.4.3 → 0.4.6

package/daemon/dist/domain/queue-repository.js

@@ -1,6 +1,8 @@
+import { createHash } from "node:crypto";
 import { QueueTransitionLog } from "./queue-transition-log.js";
 import { wrapPaneEnvelope } from "../lib/pane-envelope.js";
 import { computeClosureRequiredAt, validateClosure, } from "./hot-potato-enforcer.js";
+import { isHumanSeatSession, validateHumanPark, validateHumanRoute } from "./human-route-enforcer.js";
 export const QUEUE_STATES = [
     "pending",
     "in-progress",
@@ -11,6 +13,17 @@ export const QUEUE_STATES = [
     "canceled",
     "handed-off",
 ];
+/** OPR.0.4.6.FS-1 (W2 P1): the queue's terminal state set, named ONCE. The
+ *  archiver (queue-retention.ts) AND the inline closure guards below all consume
+ *  THIS predicate, so a future terminal-state addition can never silently
+ *  diverge the archiver from the queue (arch D3-REFINEMENT P1; widen-never-sibling).
+ *  `['done','handed-off']` is the full terminal set — workflow step closures exit
+ *  `handoff -> state=handed-off`, the highest-volume terminal class. The `satisfies`
+ *  clause is the compile guard: removing a state from QUEUE_STATES fails here. */
+export const TERMINAL_QUEUE_STATES = ["done", "handed-off"];
+export function isTerminalState(state) {
+    return TERMINAL_QUEUE_STATES.includes(state);
+}
 export const QUEUE_PRIORITIES = ["routine", "urgent", "critical"];
 export class QueueRepositoryError extends Error {
     code;
@@ -21,13 +34,61 @@ export class QueueRepositoryError extends Error {
         this.meta = meta;
     }
 }
-function newQitemId() {
+/** OPR.0.4.6.WF5 (guard-named fix shape): exported so the workflow
+ *  domain can PREALLOCATE a gate packet's id — the class-(c) exception
+ *  identity tags need occurrence:<gatePacketId> ON the packet at create
+ *  (one item, tagged in its own create — never a second item, never a
+ *  post-create tag rewrite). The queue still mints ids for every caller
+ *  that does not preallocate. */
+export function newQitemId() {
     const ts = new Date().toISOString().replace(/[-:T.Z]/g, "").slice(0, 14);
     const hex = Math.floor(Math.random() * 0xffffffff)
         .toString(16)
         .padStart(8, "0");
     return `qitem-${ts}-${hex}`;
 }
+/**
+ * OPR.0.4.6.MH3 Q-a: is this the SQLite PRIMARY KEY conflict on
+ * queue_items.qitem_id? better-sqlite3 sets `.code` on its SqliteError; the
+ * message check is a defensive twin so a driver-name change never silently
+ * turns an idempotent absorb into a 500.
+ */
+export function isQitemPrimaryKeyConflict(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code ?? "";
+    if (code === "SQLITE_CONSTRAINT_PRIMARYKEY" || code === "SQLITE_CONSTRAINT_UNIQUE")
+        return true;
+    return /UNIQUE constraint failed: queue_items\.qitem_id/.test(err.message);
+}
+/**
+ * OPR.0.4.6.MH3 D-1 (FR-4/FR-5): the deterministic cross-host SUCCESSOR id.
+ *
+ * A cross-host handoff exposes no caller `--id`, so the successor's dedup
+ * identity must come from the operation itself: the id is a PURE, STATELESS
+ * function of (source qitemId, destination session, destination host). Same
+ * arguments → same id on every re-drive, across daemon restarts, with zero
+ * local state — so the origin-side PRIMARY KEY absorb (Q-a) converges every
+ * interrupted-close re-drive. Source→successor is 1:1 by construction (a
+ * closed source is terminal; nothing re-opens it). The `qitem-xh-` namespace
+ * makes collision with organic `qitem-<ts>-<hex>` ids structurally impossible
+ * (plan R-2). The compound key is JSON-encoded — no hand-rolled separators.
+ *
+ * n1 residual (arch-named, inherent to the ratified at-least-once/no-2PC
+ * fence — NOT a dedup bug): a re-drive naming a DIFFERENT destination before
+ * the source close lands is a NEW handoff decision and derives a DIFFERENT
+ * id, so it cannot absorb the earlier successor — that earlier successor can
+ * remain live on the target host. The chain_of_record + cross-host provenance
+ * tags keep such an orphan visible/traceable; the source-close conflict check
+ * surfaces the disagreement rather than overwriting it.
+ */
+export function deriveCrossHostSuccessorId(sourceQitemId, destinationSession, hostId) {
+    const digest = createHash("sha256")
+        .update(JSON.stringify([sourceQitemId, destinationSession, hostId]))
+        .digest("hex")
+        .slice(0, 16);
+    return `qitem-xh-${digest}`;
+}
 /** PL-007 — defensive column probe. Older test fixtures bypass the
  *  canonical migration list, so target_repo may be absent. Mirrors
  *  the `hasNodeColumn` pattern in rig-repository.ts. */
@@ -62,14 +123,20 @@ export class QueueRepository {
      *  Production daemons always have the column (migration is in startup.ts). */
     hasTargetRepoColumn;
     hasSummaryColumn;
+    hasEvidenceRefColumn;
+    /** OPR.0.4.6.WF3 FR-6 — injected by startup (never imported): the
+     *  workflow domain's is-live-frontier-packet predicate. */
+    workflowFrontierPredicate;
     constructor(db, eventBus, opts) {
         this.db = db;
         this.eventBus = eventBus;
         this.transitionLog = new QueueTransitionLog(db);
         this.validateRig = opts?.validateRig ?? (() => true);
         this.transport = opts?.transport;
+        this.workflowFrontierPredicate = opts?.workflowFrontierPredicate;
         this.hasTargetRepoColumn = detectQueueColumn(db, "target_repo");
         this.hasSummaryColumn = detectQueueColumn(db, "summary");
+        this.hasEvidenceRefColumn = detectQueueColumn(db, "evidence_ref");
         // OPR.0.3.2.20 — register the EXACT human-seat regex predicate as
         // a SQLite function so the attention query can apply the strict
         // check BEFORE LIMIT. LIKE / GLOB patterns are supersets that
@@ -78,11 +145,10 @@ export class QueueRepository {
         // behind them (guard re-verify-3 qitem-20260518193005 BLOCKER 1).
         // better-sqlite3 db.function is idempotent; safe to call once at
         // construction.
-        db.function("is_human_seat_session", { deterministic: true }, (value) => {
-            if (typeof value !== "string")
-                return 0;
-            return /^human(?:-[A-Za-z0-9._-]+)?@(kernel|host)$/.test(value) ? 1 : 0;
-        });
+        // OPR.0.4.4.19: single-source regex — the SQL function delegates to the
+        // human-route-enforcer's exported predicate so SQL-side and TS-side
+        // checks cannot drift.
+        db.function("is_human_seat_session", { deterministic: true }, (value) => isHumanSeatSession(value) ? 1 : 0);
     }
     /**
      * Attach the wake-path transport AFTER construction. Used by daemon
@@ -111,12 +177,14 @@ export class QueueRepository {
      * came from + a reply hint. When undefined, the envelope falls back
      * to the canonical "<unknown sender>" marker (matches wrapPaneEnvelope).
      */
-    async maybeNudge(qitemId, destinationSession, nudgeOpt, sourceSession) {
+    async maybeNudge(qitemId, destinationSession, nudgeOpt, sourceSession, bodyOverride) {
         if (nudgeOpt === false)
             return;
         if (!this.transport)
             return;
-        const bareBody = `Queue handoff: ${qitemId} - check your queue.`;
+        // OPR.0.4.4.19 FR-7: bodyOverride lets the resolve verb carry the
+        // decision text to the parked owner; default stays the handoff nudge.
+        const bareBody = bodyOverride ?? `Queue handoff: ${qitemId} - check your queue.`;
         const text = wrapPaneEnvelope(sourceSession, destinationSession, bareBody);
         try {
             const res = await this.transport.send(destinationSession, text, { verify: true });
@@ -142,7 +210,36 @@ export class QueueRepository {
             throw new QueueRepositoryError("unknown_destination_rig", `destination_session ${input.destinationSession} references an unknown rig`);
         }
         const txn = this.db.transaction(() => this.createInTransactionalContext(input));
-        const { qitemId: id, persistedEvent } = txn();
+        let id;
+        let persistedEvent;
+        try {
+            ({ qitemId: id, persistedEvent } = txn());
+        }
+        catch (err) {
+            // OPR.0.4.6.MH3 Q-a (FR-5): at-least-once cross-host forwards retry with
+            // the SAME minted qitemId, so a PK conflict on an EXISTING row is an
+            // idempotent RE-DELIVERY when the identity fields match — return the
+            // stored row (no second insert, no second event/nudge). A conflict whose
+            // identity fields DIFFER (same id, different destination/source) is a
+            // caller id-reuse bug — a structured error, never a silent overwrite.
+            // Local (non-forwarded) creates that pass an explicit --id keep the same
+            // safety for free.
+            if (input.qitemId && isQitemPrimaryKeyConflict(err)) {
+                const existing = this.getById(input.qitemId);
+                if (existing) {
+                    if (existing.destinationSession === input.destinationSession &&
+                        existing.sourceSession === input.sourceSession) {
+                        return existing;
+                    }
+                    throw new QueueRepositoryError("qitem_id_reuse", `qitem ${input.qitemId} already exists with a different destination/source — id reuse is a caller bug, not an idempotent retry`, {
+                        qitemId: input.qitemId,
+                        existingDestination: existing.destinationSession,
+                        existingSource: existing.sourceSession,
+                    });
+                }
+            }
+            throw err;
+        }
         this.eventBus.notifySubscribers(persistedEvent);
         await this.maybeNudge(id, input.destinationSession, input.nudge, input.sourceSession);
         return this.getByIdOrThrow(id);
@@ -189,6 +286,20 @@ export class QueueRepository {
      * provides the atomic boundary).
      */
     createInTransactionalContext(input) {
+        // OPR.0.4.4.19 FR-4/FR-5 — human-routed items require summary +
+        // evidence_ref at the domain write path (the validateClosure pattern).
+        // The validator is a no-op for non-human-routed items (BR-1).
+        const humanRoute = validateHumanRoute({
+            tier: input.tier ?? null,
+            destinationSession: input.destinationSession,
+            summary: input.summary ?? null,
+            evidenceRef: input.evidenceRef ?? null,
+        });
+        if (!humanRoute.ok) {
+            throw new QueueRepositoryError(humanRoute.code, humanRoute.message, {
+                missingFields: humanRoute.missingFields,
+            });
+        }
         const id = input.qitemId ?? newQitemId();
         const ts = new Date().toISOString();
         const priority = input.priority ?? "routine";
@@ -214,6 +325,7 @@ export class QueueRepository {
                 .run(id, ts, ts, input.sourceSession, input.destinationSession, priority, tier, tags, expiresAt, chain, input.body);
         }
         this.persistSummary(id, input.summary ?? null);
+        this.persistEvidenceRef(id, input.evidenceRef ?? null);
         this.transitionLog.append({
             qitemId: id,
             state: "pending",
@@ -227,6 +339,7 @@ export class QueueRepository {
             destinationSession: input.destinationSession,
             priority,
             tier,
+            summary: input.summary ?? null,
         });
         return { qitemId: id, persistedEvent };
     }
@@ -240,7 +353,7 @@ export class QueueRepository {
         if (!source) {
             throw new QueueRepositoryError("qitem_not_found", `qitem ${input.qitemId} not found`);
         }
-        if (source.state === "done" || source.state === "handed-off") {
+        if (isTerminalState(source.state)) {
             throw new QueueRepositoryError("qitem_already_terminal", `qitem ${input.qitemId} is already in terminal state ${source.state}`);
         }
         if (!this.validateRig(input.toSession)) {
@@ -254,6 +367,20 @@ export class QueueRepository {
         const tags = input.tags ? JSON.stringify(input.tags) : (source.tags ? JSON.stringify(source.tags) : null);
         const chain = JSON.stringify([...(source.chainOfRecord ?? []), source.qitemId]);
         const targetRepo = input.targetRepo === undefined ? source.targetRepo : input.targetRepo;
+        // OPR.0.4.4.19 FR-4/FR-5 — the handoff authors a NEW qitem; when that
+        // new item is human-routed it requires its OWN summary + evidence_ref
+        // (neither is inherited from the source — 044 semantics preserved).
+        const humanRoute = validateHumanRoute({
+            tier,
+            destinationSession: input.toSession,
+            summary: input.summary ?? null,
+            evidenceRef: input.evidenceRef ?? null,
+        });
+        if (!humanRoute.ok) {
+            throw new QueueRepositoryError(humanRoute.code, humanRoute.message, {
+                missingFields: humanRoute.missingFields,
+            });
+        }
         const events = [];
         const txn = this.db.transaction(() => {
             this.db
@@ -290,6 +417,7 @@ export class QueueRepository {
                     .run(newId, ts, ts, input.fromSession, input.toSession, priority, tier, tags, source.qitemId, chain, body);
             }
             this.persistSummary(newId, input.summary ?? null);
+            this.persistEvidenceRef(newId, input.evidenceRef ?? null);
             this.transitionLog.append({
                 qitemId: newId,
                 state: "pending",
@@ -302,6 +430,7 @@ export class QueueRepository {
                 fromSession: input.fromSession,
                 toSession: input.toSession,
                 closureReason: "handed_off_to",
+                summary: source.summary ?? null,
             });
             events.push({ name: "queue.handed_off", payload: handoffEvent });
             const createdEvent = this.eventBus.persistWithinTransaction({
@@ -311,6 +440,7 @@ export class QueueRepository {
                 destinationSession: input.toSession,
                 priority,
                 tier,
+                summary: input.summary ?? null,
             });
             events.push({ name: "queue.created", payload: createdEvent });
         });
@@ -336,7 +466,7 @@ export class QueueRepository {
         if (!source) {
             throw new QueueRepositoryError("qitem_not_found", `qitem ${input.qitemId} not found`);
         }
-        if (source.state === "done" || source.state === "handed-off") {
+        if (isTerminalState(source.state)) {
             throw new QueueRepositoryError("qitem_already_terminal", `qitem ${input.qitemId} is already in terminal state ${source.state}`);
         }
         if (!this.validateRig(input.toSession)) {
@@ -350,6 +480,18 @@ export class QueueRepository {
         const tags = input.tags ? JSON.stringify(input.tags) : (source.tags ? JSON.stringify(source.tags) : null);
         const chain = JSON.stringify([...(source.chainOfRecord ?? []), source.qitemId]);
         const targetRepo = input.targetRepo === undefined ? source.targetRepo : input.targetRepo;
+        // OPR.0.4.4.19 FR-4/FR-5 — same new-item enforcement as handoff().
+        const humanRoute = validateHumanRoute({
+            tier,
+            destinationSession: input.toSession,
+            summary: input.summary ?? null,
+            evidenceRef: input.evidenceRef ?? null,
+        });
+        if (!humanRoute.ok) {
+            throw new QueueRepositoryError(humanRoute.code, humanRoute.message, {
+                missingFields: humanRoute.missingFields,
+            });
+        }
         const events = [];
         const txn = this.db.transaction(() => {
             this.db
@@ -386,6 +528,7 @@ export class QueueRepository {
                     .run(newId, ts, ts, input.fromSession, input.toSession, priority, tier, tags, source.qitemId, chain, body);
             }
             this.persistSummary(newId, input.summary ?? null);
+            this.persistEvidenceRef(newId, input.evidenceRef ?? null);
             this.transitionLog.append({
                 qitemId: newId,
                 state: "pending",
@@ -398,6 +541,7 @@ export class QueueRepository {
                 fromSession: input.fromSession,
                 toSession: input.toSession,
                 closureReason: "handed_off_to",
+                summary: source.summary ?? null,
             });
             events.push({ name: "queue.handed_off", payload: handoffEvent });
             const createdEvent = this.eventBus.persistWithinTransaction({
@@ -407,6 +551,7 @@ export class QueueRepository {
                 destinationSession: input.toSession,
                 priority,
                 tier,
+                summary: input.summary ?? null,
             });
             events.push({ name: "queue.created", payload: createdEvent });
         });
@@ -420,6 +565,85 @@ export class QueueRepository {
             created: this.getByIdOrThrow(newId),
         };
     }
+    /**
+     * OPR.0.4.6.MH3 FR-4 (C2, arch Q-c): the LOCAL half of a cross-host
+     * handoff — close the source row AFTER the successor-create was forwarded
+     * to (and accepted by) the target host. The two sides live in two DBs, so
+     * this is deliberately NOT the atomic close+create of {@link handoff}: the
+     * boundary is bridged by message-passing (successor-create FIRST on the
+     * origin host, this source-close SECOND — never the reverse, so a crash
+     * between the two leaves a live duplicate the idempotent re-drive
+     * converges, never a dropped potato).
+     *
+     * Re-drive semantics (FR-4/FR-5, the interrupted-close case):
+     *   - source already terminal WITH a MATCHING closureTarget → idempotent
+     *     absorb: return the stored row unchanged (`absorbed: true`) — no
+     *     second close, no second event.
+     *   - source already terminal with a MISMATCHED closureTarget → structured
+     *     `cross_host_close_conflict` (someone else closed it meanwhile —
+     *     surface, never overwrite).
+     *   - otherwise → close exactly like the local handoff's close leg:
+     *     `closure_reason=handed_off_to`; `closure_target` carries the OPAQUE
+     *     three-part `<member@rig>@<host>` form (arch R1 — presence-checked
+     *     display/audit metadata, NEVER parsed for routing); `handed_off_to`
+     *     stays the two-part `member@rig` (BR-1 — session-string carriers
+     *     never gain `@host`).
+     */
+    closeCrossHostHandoffSource(input) {
+        const source = this.getById(input.qitemId);
+        if (!source) {
+            throw new QueueRepositoryError("qitem_not_found", `qitem ${input.qitemId} not found`);
+        }
+        if (isTerminalState(source.state)) {
+            if (source.closureTarget === input.closureTarget) {
+                return { item: source, absorbed: true };
+            }
+            throw new QueueRepositoryError("cross_host_close_conflict", `qitem ${input.qitemId} is already closed toward ${source.closureTarget ?? "<no closure_target>"} — this re-drive names ${input.closureTarget}; surfacing the conflict, never overwriting`, {
+                qitemId: input.qitemId,
+                existingClosureTarget: source.closureTarget,
+                attemptedClosureTarget: input.closureTarget,
+            });
+        }
+        const ts = new Date().toISOString();
+        const events = [];
+        const txn = this.db.transaction(() => {
+            this.db
+                .prepare(`UPDATE queue_items
+             SET state = ?,
+                 ts_updated = ?,
+                 handed_off_to = ?,
+                 closure_reason = 'handed_off_to',
+                 closure_target = ?
+           WHERE qitem_id = ?`)
+                .run(input.terminalState, ts, input.toSession, input.closureTarget, input.qitemId);
+            this.transitionLog.append({
+                qitemId: input.qitemId,
+                state: input.terminalState,
+                actorSession: input.fromSession,
+                // BR-1: the minted note carries the TWO-PART toSession only — the
+                // host-qualified 3-part form is allowed in closure_target and nowhere
+                // else, and transition_note is a durable carrier.
+                transitionNote: input.transitionNote ?? `cross-host handoff to ${input.toSession}`,
+                closureReason: "handed_off_to",
+                closureTarget: input.closureTarget,
+            });
+            const handoffEvent = this.eventBus.persistWithinTransaction({
+                type: "queue.handed_off",
+                qitemId: input.qitemId,
+                fromSession: input.fromSession,
+                // The event body is a session-string carrier — two-part only (BR-1).
+                toSession: input.toSession,
+                closureReason: "handed_off_to",
+                summary: source.summary ?? null,
+            });
+            events.push(handoffEvent);
+        });
+        txn();
+        for (const e of events) {
+            this.eventBus.notifySubscribers(e);
+        }
+        return { item: this.getByIdOrThrow(input.qitemId), absorbed: false };
+    }
     /**
      * `whoami` — return the seat's queue position from the daemon's perspective.
      * Counts active qitems (pending + in-progress + blocked) destined for the
@@ -494,6 +718,7 @@ export class QueueRepository {
                 destinationSession: input.destinationSession,
                 claimedAt: ts,
                 closureRequiredAt,
+                summary: qitem.summary ?? null,
             });
         });
         const persistedEvent = txn();
@@ -529,6 +754,7 @@ export class QueueRepository {
                 qitemId,
                 destinationSession,
                 reason,
+                summary: qitem.summary ?? null,
             });
         });
         const persistedEvent = txn();
@@ -602,6 +828,48 @@ export class QueueRepository {
                 validReasons: "validReasons" in validation ? validation.validReasons : undefined,
             });
         }
+        // OPR.0.4.6.WF3 FR-6 — the frontier close-path guard (pm ruling:
+        // PREVENTION over detection). A TERMINAL closure (done/handed-off)
+        // of a LIVE workflow-frontier packet from a NON-workflow verb
+        // would strand the instance: the frontier would reference a
+        // closed packet and the workflow's own bookkeeping (trail,
+        // rebind, events) would never happen. Reject LOUD with
+        // what/why/fix naming the workflow verbs. The workflow domain's
+        // own writers pass viaWorkflowVerb (they hold the invariant);
+        // non-workflow qitems return null from the predicate — closure
+        // behavior byte-identical (the zero-friction negative).
+        const isTerminalClosure = isTerminalState(input.state);
+        if (isTerminalClosure && !input.viaWorkflowVerb && this.workflowFrontierPredicate) {
+            const binding = this.workflowFrontierPredicate(input.qitemId);
+            if (binding) {
+                throw new QueueRepositoryError("workflow_frontier_packet", `qitem ${input.qitemId} is the LIVE frontier packet of workflow instance ${binding.instanceId} (${binding.workflowName}). Closing it out-of-band would strand the workflow. Use the workflow verbs instead: rig workflow project (advance) | rig workflow route (re-target the owner).`, { instanceId: binding.instanceId, workflowName: binding.workflowName, qitemId: input.qitemId });
+            }
+        }
+        // OPR.0.4.4.19 FR-6 — leg-1 park (state=blocked on a HUMAN-seat blocker):
+        // enforce summary + evidence_ref at the park moment, evaluated on the
+        // EFFECTIVE values (provided on this call, else already on the item) so
+        // an item that carried them from create parks without re-entry. The
+        // enforcement is here at the write path — the `rig queue block` verb and
+        // raw `update --state blocked` hit the same validator (no verb-only
+        // enforcement). Blocking on another qitem requires nothing new (BR-1).
+        const effectiveBlockedOn = input.blockedOn ?? qitem.blockedOn;
+        const isHumanPark = input.state === "blocked" && isHumanSeatSession(effectiveBlockedOn);
+        let effectiveSummary = qitem.summary;
+        let effectiveEvidenceRef = qitem.evidenceRef;
+        if (isHumanPark) {
+            effectiveSummary = input.summary ?? qitem.summary;
+            effectiveEvidenceRef = input.evidenceRef ?? qitem.evidenceRef;
+            const park = validateHumanPark({
+                blockedOn: effectiveBlockedOn,
+                summary: effectiveSummary,
+                evidenceRef: effectiveEvidenceRef,
+            });
+            if (!park.ok) {
+                throw new QueueRepositoryError(park.code, park.message, {
+                    missingFields: park.missingFields,
+                });
+            }
+        }
         const ts = new Date().toISOString();
         const fromState = qitem.state;
         this.db
@@ -614,6 +882,13 @@ export class QueueRepository {
                blocked_on = COALESCE(?, blocked_on)
          WHERE qitem_id = ?`)
             .run(input.state, ts, validation.closureReason, validation.closureTarget, input.handedOffTo ?? null, input.blockedOn ?? null, input.qitemId);
+        // FR-6: park-time summary/evidence_ref are PERSISTED onto the existing
+        // item (not merely validated-then-dropped) — visible to the attention
+        // query and to Packet 2. Only the park path writes them.
+        if (isHumanPark) {
+            this.persistSummary(input.qitemId, input.summary ?? null);
+            this.persistEvidenceRef(input.qitemId, input.evidenceRef ?? null);
+        }
         this.transitionLog.append({
             qitemId: input.qitemId,
             state: input.state,
@@ -630,6 +905,9 @@ export class QueueRepository {
             closureReason: validation.closureReason ?? null,
             closureTarget: validation.closureTarget ?? null,
             actorSession: input.actorSession,
+            // FR-1 × FR-6: the event carries the summary as of THIS mutation
+            // (park-time summary included) so surfaces refresh without a fetch.
+            summary: effectiveSummary ?? null,
         });
     }
     getById(qitemId) {
@@ -733,11 +1011,16 @@ export class QueueRepository {
         // (e.g., 'human-@kernel' — empty name segment) are rejected at
         // the SQL stage, BEFORE LIMIT, so they cannot saturate the LIMIT
         // window and hide valid attention items.
+        // OPR.0.4.4.19 FR-6 — the attention predicate gains the leg-1 park
+        // clause: a qitem parked as state=blocked on a HUMAN-seat blocker is a
+        // decision the human owes. Blocking on another qitem (today's shipped
+        // usage) does NOT match — is_human_seat_session rejects qitem ids.
         const conditions = [
             `state IN (${statePlaceholders})`,
             `(
         tier = 'human-gate'
         OR is_human_seat_session(destination_session) = 1
+        OR (state = 'blocked' AND is_human_seat_session(blocked_on) = 1)
       )`,
         ];
         const params = [...states];
@@ -847,6 +1130,13 @@ export class QueueRepository {
             this.db.prepare("UPDATE queue_items SET summary = ? WHERE qitem_id = ?").run(summary, qitemId);
         }
     }
+    /** OPR.0.4.4.19 FR-5 — persist the optional evidence_ref additively, same
+     *  contract as persistSummary (pre-048 fixtures degrade; NULL default). */
+    persistEvidenceRef(qitemId, evidenceRef) {
+        if (this.hasEvidenceRefColumn && evidenceRef !== null) {
+            this.db.prepare("UPDATE queue_items SET evidence_ref = ? WHERE qitem_id = ?").run(evidenceRef, qitemId);
+        }
+    }
     rowToItem(row) {
         return {
             qitemId: row.qitem_id,
@@ -867,6 +1157,9 @@ export class QueueRepository {
             // OPR.0.4.1.18: summary present only when migration 044 has applied;
             // legacy/minimal fixtures supply rows where summary is undefined → null.
             summary: row.summary ?? null,
+            // OPR.0.4.4.19 FR-5: evidence_ref present only when migration 048 has
+            // applied; legacy fixtures degrade to null.
+            evidenceRef: row.evidence_ref ?? null,
             closureReason: row.closure_reason,
             closureTarget: row.closure_target,
             closureRequiredAt: row.closure_required_at,