Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
Review Queue Contract
The Review Hub's cross-domain queue is a live projection of producer-owned records. It is not a durable universal task store, and it does not make an AI provider call. Source records remain authoritative for mutations and detail views.
Response envelope
GET /api/review/queue without query parameters keeps the legacy full-list
response. ?limit=<1..100> opts into the canonical envelope and a short-lived
snapshot:
{
"items": [],
"total": 0,
"totalsBySource": {},
"sources": {},
"nextCursor": null,
"partial": false
}
The response also carries the compatibility counts, generatedAt, and row
fields already consumed by the Review Hub. total and each
totalsBySource value are null when a source failed or its bounded read was
truncated. partial is true in either case; an unavailable source must never
be represented as an empty, healthy inbox.
Each source descriptor includes availability, available, error,
truncation, lowerBound, total, and shown. A numeric lower bound counts
the unique rows collected from that source in the snapshot.
Canonical rows
Rows retain the legacy id, source, sourceLabel, title, summary,
timestamp, severity, drillTo, and mutation fields. New consumers can use
the additive fields sourceRef, actionKind, reason, nextAction,
priority, dueAt, revision, occurrence, required,
isRecommendation, operations, and availability.
operations contains only semantic, allowlisted descriptors such as
resolve, promote, review, investigate, or retry; it never exposes a
producer URL or arbitrary command. The existing route-specific mutation
consumers remain the authority for executing those operations.
The queue may also include triage and triageOperations. triage contains
only snoozedUntil, dismissed, and deliveryGeneration; the latter is kept
separate from notification-read state for the delivery layer. snooze and
unsnooze change presentation only, while dismiss is advertised only for
isRecommendation rows. A triage mutation re-reads the source and rejects
unavailable sources or unsupported capabilities before writing the local
marker. Snoozes are limited to 30 days; the snoozed Actions view exposes
active snoozes so the user can restore one early.
Source-owned rows may also carry sourceOwned: true and triageOnly: true.
Generic Review completion rejects those rows; an explicit source operation
must revalidate the owning record at mutation time. A row with
required: false is a recommendation and remains available to its domain
without becoming an interruptive action.
Rows are deduplicated before totals and page slicing, then ordered by required work, severity, overdue/due time, priority, and stable row ID. Optional recommendations therefore remain below required work even when they are newer.
Snapshot and producer extension points
The first paginated request reads each producer once and stores a process-local
snapshot for 30 seconds. nextCursor is opaque: pass it back unchanged, with
the same query, until it becomes null. An invalid, changed, or expired cursor
returns an explicit error so the caller can restart from the first page.
To add a producer, keep its source identity and mutation primitive in the producer registry, map its raw record through the canonical row projection, bound the upstream read, and report whether the bound was filled. Add a source descriptor and operation to this document and cover the healthy, failed, and truncated paths at the queue boundary. Do not add a second durable task store or invoke an LLM as part of queue assembly.
Action admission matrix
The queue admits an obligation only when its adapter has a stable reference and a concrete human remedy or drill-down. Correlation uses source references and metadata, never matching titles or prose. Two rows with the same proven canonical reference are deduplicated; approval and feedback use different action kinds and are never merged merely because they share a task or agent.
| Producer or bridge | Admission | Source reference and operation | History/context behavior |
|---|---|---|---|
| Brain inbox | Required when needs_review |
Brain entry id; brain.classify / Done |
Source remains authoritative |
| CoS approval store | Required when awaitingApproval |
Task id; task.approval / Approve |
Execution success does not create or complete an action |
| Message drafts | Required only for pending_review |
Draft id; message.approve / Approve |
Unsubmitted draft rows remain optional domain drafts |
| Memory approval | Required with memoryId |
Memory id; memory.approval / Approve or Reject |
Stale or already-resolved memory is a conflict/not-found, not a generic completion |
| Goal-fidelity hold | Required with agent/reference id | Agent id; goal-fidelity.review / Review |
Remains pending until the source workflow resolves it |
| Plan question | Required with agent/app id and link | Agent/app id; plan.question / Review |
The marker stays source-owned; generic warnings remain context |
| Paused automation | Required with series/run id and link | Series/run reference; autopilot.resume / Resume |
Resume remains in the owning automation surface |
| Explicit content review | Required with report/reference id and link | Report or review id; content.review / Review |
Private security and malware reports remain source-owned |
| Health and backup | Required only with a known human remedy | Alert or last-run identity; Investigate or Retry | No generic Complete operation |
| Product recommendations | Optional when a current POST or creative-feedback signal is available | Product action id plus local-day/run occurrence; Open | Feature-disabled signals disappear without deleting their local triage marker |
| Legacy Review alerts | Required as explicit triage | Stored Review item id; review.triage / Review |
Never silently completed or deleted |
| Briefings, generic warnings, client errors, and uncorrelated notifications | Not admitted | No proven obligation contract | Remain in Review history/context |
Product recommendations are admitted once per current occurrence: POST uses the configured local calendar day, while creative feedback uses one row per reviewable commission run. The product source returns every pending run before the queue's bounded read, and a full bound is reported as truncation rather than an inbox-zero claim. Product read failures are reported as an unavailable source; legacy metrics and proactive-alert endpoints keep their existing compatibility projections. Optional Ask promotion is still available from Ask and its API, but it is not required action admission. Routine task-ready/success attention generation is not a queue producer; execution history and private reports remain separate.
Bell, previews, and delivery
The bell, Actions card, and Actions page share the same per-view queue snapshot.
The bell badge counts only unsnoozed required rows, never unread history or
optional recommendations. Partial source reads show lower-bound counts; failed
refreshes retain explicitly stale rows with Retry, never an inbox-zero claim.
Optional recommendations remain separately visible. Preview links select the
canonical row at /review/<encoded-id>?view=today.
Fresh dashboard layouts use one actions card. Saved widget IDs and geometry
are unchanged: review-hub wraps the queue, daily-actions filters product
recommendations, and proactive-alerts filters health, backup, and product rows.
Notification read/clear APIs affect event history only. Clearing a proven
notification-backed obligation hides its history record without deleting the
source marker; domain completion removes it through removeByMetadata.
Uncorrelated legacy records remain ordinary history with their existing clear
behavior. Producers attach canonical metadata.actionId only when the adapter
proves the source reference; title matching is never correlation.
Delivery claims live in the existing machine-local triage store, under a
delivery:<canonical-id> key plus occurrence, independent of text revision.
One marker stores a severity high-water mark, generation, and last delivered
generation per channel (toast, Telegram, scheduled reminder). Escalation
advances the generation without creating another action. Read, clear, snooze,
dismiss, reload, and additional tabs never reset that marker. An unavailable
queue/store cannot grant a delivery claim.
POST /api/review/queue/delivery accepts only the canonical ID. The server
re-reads the current unsnoozed queue, checks POST reminder opt-in and a matching
scheduled occurrence, then durably claims the toast. Daily recommendations do
not interrupt by default. Existing scheduling, feature, forwarding-type,
autonomy, and daily-budget gates still apply. Both Telegram transports share
the canonical claim; uncorrelated legacy forwards retain their old behavior.
Claims precede delivery: a lost response or failed transport can suppress a
nudge, but retrying cannot duplicate an interruption for that generation.
Completion and triage emit payload-free review:queue:changed invalidations,
alongside existing domain events. All subscribed surfaces refetch locally and
discard stale in-flight responses. POST completion, creative feedback, and CoS
approval therefore update other tabs without federating source payloads.