omp

🧭 Cronsban Full Blueprint

Full dense blueprint for Cron + Kanban + OMP + Discord + Pi WebUI + durable swarm gateway architecture.

Cronsban = Cron + Kanban + OMP/Pi sessions + durable swarm gateway. It is the operating design for converting raw requests, Discord messages, scheduled checks, and WebUI actions into verified, auditable work without unsafe autonomous loops.

0. Mission#

Every incoming intent becomes either:
  1. a Kanban card with acceptance criteria, or
  2. a durable queued job with idempotency, policy, logs, artifacts, and verification.

The system is intentionally boring at the dangerous boundaries: explicit allowlists, durable state before execution, one owner per channel/session, and no public raw runtime state.

1. Non-negotiables#

• Treat Discord access like SSH access.
• Persist jobs before invoking OMP/Pi/AIRI/Red.
• Never put bot tokens, launcher secrets, API keys, RCON, raw sessions, or hidden runtime state into Discord, public wiki pages, Node-RED flows, Red Config, or generated summaries.
• Empty allowlists mean not configured, not public.
• One Discord token/channel/thread is owned by exactly one bridge/gateway process.
• Cron jobs must be bounded, idempotent, locked, and observable.
• pi-schedule-prompt is not a durable daemon: jobs fire only while a Pi session is open in that cwd.
• Local WebUI binds 127.0.0.1 by default; remote access requires HTTPS + authentication.
• Components/buttons are hints, not authority; every click re-checks permissions server-side.
• Done means behavior is proven end-to-end.

2. Source-backed package verdict#

Recommended split:

pi-board      = human-visible work board
pi-kanban     = Pi session/subagent observability
Cronsban DB   = durable execution truth
Nexus/wiki    = safe published status

3. Entire stack#

4. Architecture#

                 ┌────────────────────┐
Discord user ───▶│ Discord adapter     │
                 │ slash/buttons/files │
                 └─────────┬──────────┘
                           │ normalized ingress event
Cron/systemd ──────────────┤
WebUI action ──────────────┤
Pi-board card ─────────────┤
                           ▼
                 ┌────────────────────┐
                 │ Policy + idempotency│
                 │ authz/path/approval │
                 └─────────┬──────────┘
                           ▼
                 ┌────────────────────┐
                 │ SQLite WAL queue   │
                 │ scopes/jobs/events │
                 └─────────┬──────────┘
                           ▼
                 ┌────────────────────┐
                 │ Session router     │
                 │ per-scope FIFO     │
                 └─────────┬──────────┘
                           ▼
        ┌──────────────────┼───────────────────┐
        ▼                  ▼                   ▼
  OMP subprocess     live OMP adapter      AIRI/Red/etc.
        │                  │                   │
        └──────────────────┼───────────────────┘
                           ▼
                 ┌────────────────────┐
                 │ Event/artifact log │
                 └──────┬───────┬─────┘
                        ▼       ▼
                 Discord cards  WebUI/SSE  wiki safe summary

5. Data model#

5.1 Stores#

5.2 Gateway tables#

Required DB defaults:

PRAGMA journal_mode=WAL;
PRAGMA foreign_keys=ON;

CREATE UNIQUE INDEX idx_jobs_idempotency ON jobs(idempotency_key);
CREATE INDEX idx_jobs_scope_status_created ON jobs(scope_id, status, created_at);
CREATE INDEX idx_events_session_id ON events(session_id, id);
CREATE INDEX idx_artifacts_session_id ON artifacts(session_id, created_at);
CREATE INDEX idx_approvals_scope_status ON approvals(scope_id, status, created_at);
CREATE INDEX idx_schedules_enabled_next ON schedules(enabled, next_run_at);

5.3 Event types#

scope.created
session.started
session.resumed
session.archived
job.queued
job.started
job.heartbeat
job.succeeded
job.failed
job.cancelled
assistant.delta
assistant.final
tool.started
tool.finished
approval.requested
approval.resolved
artifact.created
artifact.shared
schedule.fired
render.updated
policy.denied
error

6. Routes and command surfaces#

6.1 Existing OMP launcher#

Launcher rules:

• Bind local unless reverse-proxied with HTTPS/auth.
• Secret must exist before OMP boots.
• Never publish the secret.

6.2 Discord slash commands#

Plain message rules:

• DM: accept only linked/allowlisted users.
• Project channel: accept only mention-mode or explicitly prompt-enabled channels.
• Session thread: route to bound session for allowlisted users/roles.
• Host/control channel: slash commands only; raw prompts rejected with a short hint.

6.3 Discord component IDs#

pgw:v1:<kind>:<dbId>:<action>
pgw:v1:dash:scope_01J:refresh
pgw:v1:session:sess_01J:stop
pgw:v1:approval:apr_01J:approve_once
pgw:v1:artifact:art_01J:upload

Rules:

• custom_id is 1-100 chars and unique per message.
• Store full state in SQLite, not in the custom ID.
• Re-check actor authorization on every click/select/modal submit.
• Disable expired or already-used destructive controls.
• Legacy components are the safer default; Components V2 can be adopted per-message only after testing because the flag cannot be removed from that message.

6.4 Local WebUI routes#

Bind 127.0.0.1 by default.

6.5 Pi package WebUI surfaces#

7. UI/UX blueprint#

7.1 Discord dashboard card#

Gateway: ready | DB: healthy | Discord: connected
Scope: project-channel / thread / workspace
Session: sess_01J | model: provider/model | think: medium
Queue: 1 running, 2 queued | Schedules: 3 enabled
Artifacts: 4 | Approvals: 1 pending

[New] [Stop] [Compact] [Refresh]
<select session>
<select model>
<select thinking>
[Artifacts] [Approvals] [Open WebUI]

Card rules:

• One card = one decision surface.
• One pinned/updatable dashboard message per scope.
• Long output becomes stream pages + artifacts, not giant embeds.
• allowed_mentions: { parse: [] } on bot output unless explicitly approved.
• Tool cards show safe args summary, status, result/error summary, and artifact links.
• Approval cards show operation, risk, requester, expiry, and exact buttons.

7.2 Local WebUI layout#

Top bar:    gateway health | Discord | DB | active adapter | account
Left rail:  scopes, workspaces, Discord channels, sessions
Center:     event timeline, assistant stream, tool cards
Right rail: queue, schedules, approvals, artifacts, controls
Mobile:     tabs: Sessions / Timeline / Controls / Artifacts

WebUI is for admin-heavy operations that Discord is bad at:

• setup wizard;
• policy/allowlist editing;
• multi-session timeline;
• queue and schedule inspection;
• artifact browser;
• Red/Node-RED connector setup;
• metrics and diagnostics.

7.3 Kanban board UX#

Use pi-board columns as the human planning layer:

Backlog → In Progress → Code Review → UAT → Completed

Cronsban status mapping:

Required card fields:

Outcome:
Scope:
Acceptance:
Risk:
Owner:
Source:
Queue/job link:
Artifacts:
Verification:

8. Cron and schedule design#

8.1 Three scheduler tiers#

8.2 Host cron wrapper contract#

set explicit cwd
load explicit env only if required
acquire lock
compute idempotency key
run bounded command or enqueue durable job
write structured status
exit nonzero on failure

Public summary fields:

name
cadence
last_started_at
last_finished_at
status
exit_class
safe_summary
artifact_count

Never publish raw command output by default.

8.3 Durable schedule fields#

type ScheduleKind = 'cron' | 'interval' | 'once';

type GatewaySchedule = {
  id: string;
  scopeId: string;
  sessionId?: string;
  kind: ScheduleKind;
  spec: string;
  promptOrCommand: string;
  enabled: boolean;
  nextRunAt?: string;
  lastRunAt?: string;
  idempotencySeed: string;
  createdBy: string;
  policyId: string;
};

Cron format notes:

• Traditional OS cron uses five fields.
• pi-schedule-prompt uses six fields and includes seconds.
• The gateway should store the parser kind so */15 * * * * is never silently interpreted as * */15 * * * *.

9. Integration plan#

9.1 OMP#

• Keep /home/mc/.env as the OMP/Pi compatibility config source.
• Keep PI_CODING_AGENT_DIR=/home/mc/.omp/agent.
• Spawn child sessions through /home/mc/.local/bin/omp-plugin-env --allow-home.
• Use live extension mode only for current operator session steering.
• Use subprocess mode for durable queue execution.

9.2 Discord#

• Use discord.js v14 for gateway/REST/interactions.
• Register guild-scoped commands first.
• Require guild/channel/user/role allowlists before accepting prompts.
• Download attachments to private artifacts before agent use.
• Use one dashboard message per scope and edit in place.

9.3 Pi board / Pi kanban#

• pi-board owns planning tasks and sprint metrics.
• pi-kanban owns Pi session/todo/subagent observability.
• Cronsban may link to board cards but must not depend on board status as proof of execution.
• If OMP session visibility is needed in pi-kanban, build an explicit adapter/sync; do not fake by copying raw hidden session state into public docs.

9.4 Nexus/Hermes/wiki#

• Nexus/Hermes ingest safe status JSON only.
• Wiki generated pages publish counts, status, and safe summaries.
• Raw diagnostics/log text stays private.
• Every public page must avoid secrets and hidden runtime paths beyond high-level source references.

9.5 Red/Node-RED#

• Red-DiscordBot is a connector cog, not the gateway core.
• Red Config stores non-secret policy only.
• Node-RED can enqueue jobs and subscribe to events over local HTTP/WebSocket.
• Node-RED must not own the Discord token or invoke Pi directly while Cronsban is enabled.

10. Policy and approvals#

Default blocked/approval-gated paths:

.env
.env.*
*.pem
*.key
id_rsa
id_ed25519
.hermes/**
.omp/**
.config/**
browser profiles
token stores
runtime session files
raw generated dashboard state that may contain secrets

Risk actions requiring approval:

11. Rollout phases#

Phase 0 — Inventory and ownership#

• Identify current Discord bridge token/channel/thread ownership.
• Identify safe test guild/channel/token.
• List existing cron/systemd jobs and whether they mutate state.
• Decide board ownership: pi-board for planning, gateway DB for execution.

Acceptance:

• No ambiguous token/channel ownership remains.
• Unsafe or unowned crons are disabled or converted to no-op/report-only drafts before production use.

Phase 1 — Board and observability baseline#

• Install/review pi-board only after source review.
• Install/review pi-kanban only after source review.
• Create card template and status mapping.
• Add public safe wiki summary link targets.

Acceptance:

• Board card can represent one work item with acceptance and verification fields.
• Session observability does not expose secrets or raw hidden state publicly.

Phase 2 — Safe scheduler baseline#

• Wrap host cron jobs with cwd/env/lock/idempotency/status output.
• Document which jobs are host cron vs Pi schedule vs durable gateway schedule.
• Keep pi-schedule-prompt limited to in-session reminders until durable queue exists.

Acceptance:

• Double-run is prevented by lock.
• Failed runs produce safe visible status.
• No scheduled prompt can silently mutate public docs without verification.

Phase 3 — Gateway core#

• SQLite WAL migrations.
• Repositories for policies, scopes, sessions, jobs, events, artifacts, approvals, schedules.
• Per-scope FIFO workers.
• Fake adapter emitting assistant/tool/artifact/approval events.

Acceptance:

• Authorized enqueue creates one job.
• Duplicate idempotency key creates no duplicate job.
• Restart preserves queued jobs.
• Fake adapter event replay reconstructs dashboard state.

Phase 4 — Discord daemon#

• discord.js login and slash command registration.
• /status, /dash, /ask, /stop.
• Component dispatcher and custom ID validation.
• Stream coalescer and dashboard editor.

Acceptance:

• Unauthorized message is ignored and audited.
• Dashboard refresh edits the same message.
• Large output splits safely.
• /stop aborts fake long job.

Phase 5 — OMP/Pi adapters#

• OMP subprocess adapter.
• Optional live OMP extension adapter.
• Session start/resume/compact/abort/model/thinking.
• Thread/session/workspace routing.

Acceptance:

• Test channel can run a harmless prompt.
• Restart behavior is deterministic.
• Existing production bridge remains owner until explicit cutover.

Phase 6 — Artifacts, approvals, and WebUI#

• Artifact ingest/upload policy.
• Approval cards and WebUI approval panel.
• Local WebUI REST/SSE event replay.
• Setup wizard for token/allowlist/policy.

Acceptance:

• Attachment becomes private artifact before agent use.
• Likely secret artifact cannot upload without denial/approval path.
• Approval buttons reject unauthorized users.
• WebUI shows event replay from cursor.

Phase 7 — Connector and production cutover#

• Red connector cog/API.
• Node-RED enqueue/subscribe nodes or HTTP examples.
• Test token/channel soak with harmless operations.
• Stop old bridge for production channel only after gates pass.
• Move allowlists to new gateway.

Acceptance:

• Red/Node-RED can enqueue/status without Discord token access.
• Old and new bridge do not race on the same channel.
• Production gate checklist is complete.

12. Production gate checklist#

• Bot logs in and reaches ready.
• /status works only where allowed.
• Unauthorized user is ignored and audited.
• Authorized prompt creates exactly one job.
• Duplicate Discord interaction/message ID does not duplicate a job.
• Restart during queued job does not lose the job.
• Restart during running job follows adapter recovery policy.
• /stop aborts active work and handles queued work by policy.
• Dashboard refresh edits the same message.
• Large assistant output splits below Discord limits.
• Tool card transitions running → success/error.
• Attachments download privately, hash, and link to artifacts.
• Artifact upload denies likely secrets.
• Approval controls reject unauthorized users.
• Cron/schedule jobs cannot overlap.
• WebUI binds localhost unless explicit remote auth exists.
• Red/Node-RED connectors do not receive Discord tokens.
• Public wiki summaries contain no raw logs, secrets, profiles, or session content.

13. First complete slice#

Ship this first, or do not cut over:

1. SQLite WAL queue + event log.
2. Policy allowlists + idempotency.
3. Discord daemon with /status, /dash, /ask, /stop.
4. One fake adapter test harness.
5. One OMP subprocess adapter.
6. Per-channel/thread session scope.
7. Stream coalescer + dashboard message editor.
8. Private artifact download path.
9. Tests/fixtures covering unauthorized user, duplicate interaction, restart recovery, stop, stream split, artifact, and approval denial.

Hard rule: a pretty dashboard without queue persistence and authorization is worse than no dashboard.

14. Operator runbook#

Create a new work item#

1. Create or link `pi-board` card.
2. Fill Outcome / Acceptance / Risk / Verification.
3. Use `/ask` or WebUI to enqueue job.
4. Watch `/dash` or WebUI event stream.
5. Attach artifacts to card/job.
6. Move to Done only after verification evidence exists.

Create a recurring host job#

1. Decide whether this belongs in OS cron, pi-schedule-prompt, or gateway schedules.
2. If OS cron: write wrapper with cwd/env/lock/idempotency/status.
3. If gateway schedule: store schedule row and enqueue jobs through queue.
4. If pi-schedule-prompt: keep it in-session and non-critical.
5. Publish only safe status summaries.

Handle a risky operation#

1. Policy detects risky path/action/upload.
2. Job pauses and emits approval.requested.
3. Discord/WebUI renders approval card.
4. Authorized actor approves/denies.
5. Decision is appended to events.
6. Job resumes or fails safely.

15. Source links#

Local source material:

• /home/mc/docs/omp-coms.md
• /home/mc/docs/omp-pi-plugin-cheatsheet.md
• /home/mc/docs/discord-gateway-research/INDEX.md
• /home/mc/docs/discord-gateway-research/CHEATSHEET.md
• /home/mc/docs/discord-gateway-research/03-gateway-dashboard-blueprint.md
• /home/mc/docs/discord-gateway-research/04-implementation-contract.md
• /home/mc/docs/discord-gateway-research/06-interactive-discord-ui.md
• /home/mc/docs/discord-gateway-research/07-approved-implementation-queue.md
• /home/mc/wiki/content/hermes/kanban.md
• /home/mc/wiki/content/operations/recurring-logs.md

External source material:

• https://pi.dev/packages/pi-kanban
• https://nikiforovall.github.io/pi-kanban/docs/
• https://pi.dev/packages/pi-board
• https://pi.dev/packages/pi-schedule-prompt
• https://discord.com/developers/docs/interactions/message-components
• https://discord.com/developers/docs/resources/message

Note: the referenced Discord message URL did not expose private message content through unauthenticated web reads, so this blueprint uses observed local repository research and public primary documentation.