@stackbone/cli 0.1.0-alpha.9 → 0.2.0

package/migrations/0001_runs.sql

@@ -1,6 +1,6 @@
 -- 0001_runs.sql — schema and tables for the run-level surface of Studio.
 -- Spec: docs/arquitectura/specs/stackbone-agent-protocol-v1.md §6 (runs, run_steps).
--- ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D2/D7/D9.
+-- ADR:  docs/arquitectura/decisiones/2026-05-30-stackbone-studio.md §D2/D7/D9.
 
 CREATE SCHEMA IF NOT EXISTS stackbone_platform;
 

package/migrations/0002_approvals.sql

@@ -1,7 +1,7 @@
 -- 0002_approvals.sql — HITL approvals queue and audit trail.
 -- Spec: docs/arquitectura/specs/stackbone-agent-protocol-v1.md §6.6/§6.7.
 -- Component: docs/arquitectura/componentes/08-hitl-inbox.md.
--- ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D2.
+-- ADR:  docs/arquitectura/decisiones/2026-05-30-stackbone-studio.md §D2.
 
 CREATE TABLE IF NOT EXISTS stackbone_platform.approvals (
     id                      uuid        PRIMARY KEY DEFAULT gen_random_uuid(),

package/migrations/0003_runs_is_playground_index.sql

@@ -1,6 +1,6 @@
 -- 0003_runs_is_playground_index.sql — billing-friendly partial index over runs.
 -- Spec: docs/tasks/Studio V5 - Playground e Invoke.md (V5#01).
--- ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D5/D9.
+-- ADR:  docs/arquitectura/decisiones/2026-05-30-stackbone-studio.md §D5/D9.
 --
 -- The `is_playground` column itself already lives in 0001_runs.sql (F2 baked it
 -- in defensively so playground writes had a place to land before V5 shipped).

package/migrations/0005_stackbone_viewer.sql

@@ -1,7 +1,7 @@
 -- 0005_stackbone_viewer.sql — read-only role for the Studio DB Explorer.
 -- Spec: docs/arquitectura/componentes/11-stackbone-studio.md §"DB Explorer".
 -- Task: docs/tasks/Studio V6 - DB Explorer read-only.md (V6#01).
--- ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D6.
+-- ADR:  docs/arquitectura/decisiones/2026-05-30-stackbone-studio.md §D6.
 --
 -- The role is `NOLOGIN` because callers (apps/api, apps/cli emulator) reach it
 -- via `SET ROLE stackbone_viewer` on a session opened with the regular owner

package/migrations/0006_secrets.sql

@@ -2,7 +2,7 @@
 -- `stackbone dev` emulator (Studio V10).
 -- Spec: docs/arquitectura/componentes/11-stackbone-studio.md §"Secrets".
 -- Task: docs/tasks/Studio V10 - Secrets.md (V10#02).
--- ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md
+-- ADR:  docs/arquitectura/decisiones/2026-05-30-stackbone-studio.md
 --       (decision V10#01 in the task itself: cloud secrets stay in
 --       `installation_secret` of the control plane; local emulator stores
 --       the same wire shape here so the Studio UI sees identical data.)

package/migrations/0007_agent_config_versions.sql

@@ -2,7 +2,7 @@
 -- payloads for Studio's Config dinámica screen (V11).
 -- Spec: docs/arquitectura/componentes/11-stackbone-studio.md §"Mapa de pantallas / C.Config dinámica".
 -- Task: docs/tasks/Studio V11 - Config dinámica.md (V11#01).
--- ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D2/D7.
+-- ADR:  docs/arquitectura/decisiones/2026-05-30-stackbone-studio.md §D2/D7.
 --
 -- The current config is the row with the highest `version`. Older rows are
 -- kept for the rollback action and the lateral history list. Hot-reload is

package/migrations/0014_rag.sql

@@ -1,6 +1,6 @@
 -- 0014_rag.sql — the canonical RAG store (collections / documents / chunks /
 -- jobs), moved into the platform schema.
--- ADR: docs/adr/2026-06-05-rag-tables-in-platform-schema.md
+-- ADR: docs/adr/2026-06-05-rag.md
 --
 -- Previously these four tables lived in `public` and were installed by the
 -- creator's own migrator (`stackbone db migrate add-rag`). They are a

package/migrations/0015_queue_jobs_lease.sql

@@ -0,0 +1,60 @@
+-- 0015_queue_jobs_lease.sql — lease columns + a terminal NOTIFY on the agent's
+-- `_queue_jobs` journal (P1 "async jobs").
+--
+-- The wrapper around a dispatched handler now leases the in-flight row so the
+-- control-plane reaper can tell a still-running job from a crashed one:
+--
+--   heartbeat_at — touched by the harness roughly every 15s while a dispatched
+--                  handler is running. A stale heartbeat is what lets the
+--                  reaper DERIVE the `lost` state (never written as a column —
+--                  the status CHECK stays `done` / `failed`).
+--   deadline_at  — started_at + the effective handler timeout; the hard ceiling
+--                  past which the reaper treats the lease as expired.
+--   run_id       — correlation key with the `runs` timeline so Studio can join
+--                  a journal row to its run.
+--
+-- All three are nullable and added IF NOT EXISTS: the install saga may re-apply
+-- migrations on a redeploy, and a job journaled before this migration simply
+-- carries NULL leases.
+--
+-- A terminal NOTIFY fans out the NULL→terminal transition on
+-- `stackbone_platform_events` so the dispatcher's tracker can resolve a job the
+-- instant its journal row flips, instead of polling. It mirrors the trigger
+-- style of `0001_runs.sql`.
+
+ALTER TABLE stackbone_platform._queue_jobs
+    ADD COLUMN IF NOT EXISTS heartbeat_at timestamptz;
+ALTER TABLE stackbone_platform._queue_jobs
+    ADD COLUMN IF NOT EXISTS deadline_at  timestamptz;
+ALTER TABLE stackbone_platform._queue_jobs
+    ADD COLUMN IF NOT EXISTS run_id       text;
+
+-- AFTER UPDATE trigger fans out into pg_notify('stackbone_platform_events', ...)
+-- ONLY on the NULL→terminal status transition (the job just finished). The
+-- dispatcher's tracker LISTENs on this channel and resolves the in-flight job
+-- the moment its journal row flips to `done` / `failed`.
+CREATE OR REPLACE FUNCTION stackbone_platform.notify_queue_job_event() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    payload jsonb;
+BEGIN
+    IF (OLD.status IS NULL) AND (NEW.status IS NOT NULL) THEN
+        payload := jsonb_build_object(
+            'type', 'queue_job.finished',
+            'dispatch_id', NEW.dispatch_id,
+            'run_id', NEW.run_id,
+            'status', NEW.status
+        );
+    ELSE
+        RETURN NULL;
+    END IF;
+
+    PERFORM pg_notify('stackbone_platform_events', payload::text);
+    RETURN NULL;
+END;
+$fn$;
+
+DROP TRIGGER IF EXISTS queue_jobs_notify_au ON stackbone_platform._queue_jobs;
+CREATE TRIGGER queue_jobs_notify_au
+AFTER UPDATE ON stackbone_platform._queue_jobs
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.notify_queue_job_event();

package/migrations/0016_runs_job_trigger.sql

@@ -0,0 +1,15 @@
+-- 0016_runs_job_trigger.sql — allow `trigger = 'job'` on stackbone_platform.runs.
+--
+-- Dispatched queue jobs (ADR 2026-05-30) are first-class runs, but until now a
+-- queue dispatch only wrote the `_queue_jobs` journal — it never inserted a
+-- `runs` row. Two consequences: the dispatched run was INVISIBLE in the Studio
+-- runs timeline, and `ctx.progress` / `ctx.step` inside a job handler hit the
+-- `run_steps.run_id REFERENCES runs(id)` FK with no parent row, so the progress
+-- note was silently dropped. The wrapper now materialises a `trigger='job'` run
+-- row when it journals the job's started lifecycle, which fixes both — but the
+-- original `0001_runs.sql` CHECK predates the `job` trigger and would reject the
+-- insert. Widen it to match `runTriggerSchema` (which already carries `job`).
+ALTER TABLE stackbone_platform.runs DROP CONSTRAINT IF EXISTS runs_trigger_check;
+ALTER TABLE stackbone_platform.runs
+    ADD CONSTRAINT runs_trigger_check
+    CHECK (trigger IN ('manual', 'webhook', 'cron', 'event', 'job'));

package/migrations/0017_runs_workflow_chat_triggers.sql

@@ -0,0 +1,25 @@
+-- 0017_runs_workflow_chat_triggers.sql — widen the runs/run_steps CHECKs for
+-- the eve durable runtime (feature 67).
+--
+-- The Workflow World → runs projection (F5) materialises each durable workflow
+-- as a first-class run so it shows up in the Studio timeline; it tags those rows
+-- with `trigger='workflow'` and records each workflow step as a generic
+-- `run_steps.type='workflow_step'`. The chat recorder (F6) persists every eve
+-- chat turn as a run tagged `trigger='chat'` (the chat session id rides the
+-- free-form `runs.metadata` column — no new column is added). The earlier
+-- CHECKs (0001 listed `manual/webhook/cron/event`, 0016 added `job`) predate all
+-- three values and would reject the inserts. Widen `runs_trigger_check` to match
+-- `runTriggerSchema` and `run_steps_type_check` to match the SDK `RunStepType`.
+ALTER TABLE stackbone_platform.runs DROP CONSTRAINT IF EXISTS runs_trigger_check;
+ALTER TABLE stackbone_platform.runs
+    ADD CONSTRAINT runs_trigger_check
+    CHECK (trigger IN ('manual', 'webhook', 'cron', 'event', 'job', 'workflow', 'chat'));
+
+ALTER TABLE stackbone_platform.run_steps DROP CONSTRAINT IF EXISTS run_steps_type_check;
+ALTER TABLE stackbone_platform.run_steps
+    ADD CONSTRAINT run_steps_type_check
+    CHECK (type IN (
+        'agent', 'llm_call', 'db_query', 'http_fetch',
+        'queue_publish', 'hitl_pause', 'tool_call',
+        'rag_query', 'storage_op', 'workflow_step'
+    ));

package/migrations/0018_run_steps_v2.sql

@@ -0,0 +1,167 @@
+-- 0018_run_steps_v2.sql — demolish the legacy run_steps surface and rebuild it
+-- around the eve + Workflow World step telemetry (feature 68, Fase 2 / A4).
+--
+-- The old run_steps table (0001) modelled hand-written SDK steps (`ctx.step`
+-- with types like `llm_call`/`db_query`/…), carried no token columns and was
+-- driven by the now-removed span processor / `ctx.step` writers. Feature 67 only
+-- widened its type CHECK to admit `workflow_step`; feature 68 drops the whole
+-- table and recreates it v2.
+--
+-- v2 projects the durable Workflow World step timeline (one row per World step,
+-- `type='workflow_step'`) plus, for the fast-follow, per-model-call rows
+-- (`type='model_call'`). Each row carries the four eve token counters
+-- (input/output/cache-read/cache-write); the total is derived at read time, not
+-- stored. `world_step_id` is the World correlation/idempotency key the projector
+-- upserts on. No cost column (D5 — tokens only, no $).
+--
+-- This migration also drops `runs.cost_estimated_usd` (the demolished cost
+-- accumulator) and recreates the `approvals.requested_by_step_id` FK against
+-- run_steps v2 (A6), plus the `notify_run_step_event` pg_notify trigger that the
+-- table drop took down with it.
+
+-- --------------------------------------------------------------------------
+-- Demolition (A3): drop the legacy table, the cost column and the dependent FK.
+-- --------------------------------------------------------------------------
+
+-- The FK lives on `approvals` and references the old run_steps; drop it before
+-- the table so the table drop does not have to CASCADE through it. Recreated
+-- against v2 at the end of this migration.
+ALTER TABLE stackbone_platform.approvals
+    DROP CONSTRAINT IF EXISTS approvals_requested_by_step_id_fkey;
+ALTER TABLE stackbone_platform.approvals
+    DROP COLUMN IF EXISTS requested_by_step_id;
+
+-- The AFTER INSERT/UPDATE trigger and its function are owned by the old table;
+-- drop both so the recreate below is unambiguous.
+DROP TRIGGER IF EXISTS run_steps_notify_aiu ON stackbone_platform.run_steps;
+DROP FUNCTION IF EXISTS stackbone_platform.notify_run_step_event();
+
+-- Self-referential parent FK and run FK go away with the table. CASCADE clears
+-- the dependent self-FK in one shot.
+DROP TABLE IF EXISTS stackbone_platform.run_steps CASCADE;
+
+-- The per-run cost accumulator is demolished (no $ cost anywhere in this
+-- feature).
+ALTER TABLE stackbone_platform.runs
+    DROP COLUMN IF EXISTS cost_estimated_usd;
+
+-- Per-turn token counters on `runs` (v1, A5). An eve agent CHAT turn = one
+-- `runs` row (trigger='chat'); the chat recorder stamps the four eve
+-- `data.usage` counters onto that row (the per-model-call granularity stays in
+-- run_steps, used by workflows). All nullable; the total is `input + output`,
+-- derived at read, never stored (D4). The runs timeline and feature 69's
+-- session aggregate read these directly off `runs`.
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS input_tokens       integer,
+    ADD COLUMN IF NOT EXISTS output_tokens      integer,
+    ADD COLUMN IF NOT EXISTS cache_read_tokens  integer,
+    ADD COLUMN IF NOT EXISTS cache_write_tokens integer;
+
+-- --------------------------------------------------------------------------
+-- Recreate run_steps v2.
+-- --------------------------------------------------------------------------
+
+CREATE TABLE stackbone_platform.run_steps (
+    id                  uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    run_id              uuid        NOT NULL
+                                    REFERENCES stackbone_platform.runs(id) ON DELETE CASCADE,
+    -- Nullable self-FK. In practice null for flat "use step" workflows (the
+    -- World fork does not populate step-parent provenance for them), but kept
+    -- for the nested-step tree the projector derives from the event-log writer.
+    parent_step_id      uuid        REFERENCES stackbone_platform.run_steps(id) ON DELETE CASCADE,
+    type                text        NOT NULL
+                                    CHECK (type IN ('workflow_step', 'model_call')),
+    name                text,
+    status              text        NOT NULL DEFAULT 'running'
+                                    CHECK (status IN (
+                                        'pending', 'running', 'completed',
+                                        'failed', 'cancelled'
+                                    )),
+    started_at          timestamptz,
+    completed_at        timestamptz,
+    duration_ms         integer,
+    input               jsonb,
+    output              jsonb,
+    error               jsonb,
+    -- The four eve token counters (data.usage on `step.completed`). All
+    -- nullable: workflow steps carry none (the World has no tokens) and any
+    -- counter may be absent. The total is `input + output`, derived at read
+    -- time — never persisted (D4).
+    input_tokens        integer,
+    output_tokens       integer,
+    cache_read_tokens   integer,
+    cache_write_tokens  integer,
+    -- World correlation / idempotency key (= the World `stepId`). The
+    -- event-driven projector upserts on this so a replayed/retried step updates
+    -- the same row instead of inserting a duplicate.
+    world_step_id       text,
+    created_at          timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS run_steps_run_started_idx
+    ON stackbone_platform.run_steps (run_id, started_at);
+CREATE INDEX IF NOT EXISTS run_steps_parent_idx
+    ON stackbone_platform.run_steps (parent_step_id);
+
+-- Idempotent upsert target for the projector: one row per (run, World step).
+-- Partial so rows without a World correlation (e.g. future synthetic rows)
+-- never block one another on a NULL key.
+CREATE UNIQUE INDEX IF NOT EXISTS run_steps_world_step_uq
+    ON stackbone_platform.run_steps (run_id, world_step_id)
+    WHERE world_step_id IS NOT NULL;
+
+-- --------------------------------------------------------------------------
+-- Recreate the pg_notify trigger on the same `stackbone_platform_events`
+-- channel the SSE handler / emulator bus already LISTEN on. `created` fires on
+-- INSERT; `finished` fires when completed_at transitions from null to a value.
+-- --------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION stackbone_platform.notify_run_step_event() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    payload jsonb;
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        payload := jsonb_build_object(
+            'type', 'run.step.created',
+            'run_id', NEW.run_id,
+            'step_id', NEW.id,
+            'parent_step_id', NEW.parent_step_id,
+            'step_type', NEW.type,
+            'started_at', NEW.started_at
+        );
+    ELSIF TG_OP = 'UPDATE' THEN
+        IF (OLD.completed_at IS NULL) AND (NEW.completed_at IS NOT NULL) THEN
+            payload := jsonb_build_object(
+                'type', 'run.step.finished',
+                'run_id', NEW.run_id,
+                'step_id', NEW.id,
+                'status', NEW.status,
+                'duration_ms', NEW.duration_ms
+            );
+        ELSE
+            RETURN NULL;
+        END IF;
+    ELSE
+        RETURN NULL;
+    END IF;
+
+    PERFORM pg_notify('stackbone_platform_events', payload::text);
+    RETURN NULL;
+END;
+$fn$;
+
+DROP TRIGGER IF EXISTS run_steps_notify_aiu ON stackbone_platform.run_steps;
+CREATE TRIGGER run_steps_notify_aiu
+AFTER INSERT OR UPDATE ON stackbone_platform.run_steps
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.notify_run_step_event();
+
+-- --------------------------------------------------------------------------
+-- Recreate the approvals → run_steps FK against v2 (A6). `requestApproval`
+-- stamps the id of the workflow step that asked for the approval so the inbox
+-- can anchor it to the exact step.
+-- --------------------------------------------------------------------------
+
+ALTER TABLE stackbone_platform.approvals
+    ADD COLUMN IF NOT EXISTS requested_by_step_id uuid
+        REFERENCES stackbone_platform.run_steps(id) ON DELETE SET NULL;

package/migrations/0019_sessions.sql

@@ -0,0 +1,106 @@
+-- 0019_sessions.sql — project eve agent conversations as a first-class entity
+-- (feature 69, Fase 1).
+--
+-- An eve agent conversation is durable in the agent's Workflow World (one
+-- long-lived `workflowEntry` run per session). The control plane never read the
+-- World back, so a conversation had no row/endpoint/screen — only the loose
+-- `runs.metadata.sessionId` jsonb the chat proxy stamped on each turn. This
+-- migration adds the SESSION as a projected entity: a lean `sessions` table fed
+-- by the World→sessions projector (Fase 2), plus a real `runs.session_id` column
+-- so a session's turns join by an indexed key instead of the jsonb.
+--
+-- Lean by design (D6): `sessions` stores ONLY lifecycle (status + timestamps).
+-- The read-time aggregates (turn_count, last_activity_at, preview, tokens) are a
+-- GROUP BY over `runs` keyed on `session_id`; nothing here couples to feature
+-- 68's token columns.
+
+-- --------------------------------------------------------------------------
+-- The sessions table. `id` is the deterministic UUIDv5 the projector derives
+-- from the eve sessionId (= the `workflowEntry` World runId) under its own
+-- namespace — always caller-provided, so no gen_random_uuid default. The
+-- `status` CHECK is intentionally EXTENSIBLE (D5): v1 models only the three
+-- lifecycle states; the later HITL-in-chat feature widens it with
+-- `awaiting_input` via a non-breaking ALTER (the 0017 pattern), not a rewrite.
+-- --------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS stackbone_platform.sessions (
+    id          uuid        PRIMARY KEY,
+    -- The eve agent this conversation targets. Nullable in local (the emulator
+    -- is single-tenant), required in cloud — mirrors `runs.agent_id`.
+    agent_id    text,
+    status      text        NOT NULL DEFAULT 'open'
+                            CHECK (status IN ('open', 'completed', 'failed')),
+    started_at  timestamptz,
+    ended_at    timestamptz,
+    created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+-- Cursor pagination over (created_at, id), the same keyset shape the runs list
+-- uses, so the Studio Sessions list reuses one decoder.
+CREATE INDEX IF NOT EXISTS sessions_created_at_id_idx
+    ON stackbone_platform.sessions (created_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS sessions_agent_status_idx
+    ON stackbone_platform.sessions (agent_id, status, created_at DESC);
+
+-- --------------------------------------------------------------------------
+-- `runs.session_id` — the real join key (D4). Stamped by the chat recorder and
+-- the projector with the SAME deterministic UUIDv5 as `sessions.id`. A LOGICAL
+-- FK only (NOT enforced): a turn can persist before the session row exists
+-- (eventual consistency; the projector and recorder race), so a real FK would
+-- reject the turn. `runs.metadata.sessionId` stays for back-compat but the join
+-- moves to this column. Indexed for the `WHERE session_id = :id` turn lookup.
+-- --------------------------------------------------------------------------
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS session_id uuid;
+
+CREATE INDEX IF NOT EXISTS runs_session_id_idx
+    ON stackbone_platform.runs (session_id, created_at)
+    WHERE session_id IS NOT NULL;
+
+-- --------------------------------------------------------------------------
+-- pg_notify trigger on the SAME `stackbone_platform_events` channel the
+-- runs/run_steps/approvals triggers use, so the cloud `StudioStreamService` (one
+-- LISTEN) and the emulator's run-steps-bridge forward `session.*` with no new
+-- infra. `created` fires on INSERT; `updated` fires when the lifecycle actually
+-- moved (status or ended_at changed) so an idempotent re-upsert of the same
+-- state does not spam the stream.
+-- --------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION stackbone_platform.notify_session_event() RETURNS trigger
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    payload jsonb;
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        payload := jsonb_build_object(
+            'type', 'session.created',
+            'session_id', NEW.id,
+            'agent_id', NEW.agent_id,
+            'status', NEW.status,
+            'started_at', NEW.started_at,
+            'created_at', NEW.created_at
+        );
+    ELSIF TG_OP = 'UPDATE' THEN
+        IF (OLD.status IS DISTINCT FROM NEW.status)
+           OR (OLD.ended_at IS DISTINCT FROM NEW.ended_at) THEN
+            payload := jsonb_build_object(
+                'type', 'session.updated',
+                'session_id', NEW.id,
+                'status', NEW.status,
+                'ended_at', NEW.ended_at
+            );
+        ELSE
+            RETURN NULL;
+        END IF;
+    ELSE
+        RETURN NULL;
+    END IF;
+
+    PERFORM pg_notify('stackbone_platform_events', payload::text);
+    RETURN NULL;
+END;
+$fn$;
+
+DROP TRIGGER IF EXISTS sessions_notify_aiu ON stackbone_platform.sessions;
+CREATE TRIGGER sessions_notify_aiu
+AFTER INSERT OR UPDATE ON stackbone_platform.sessions
+FOR EACH ROW EXECUTE FUNCTION stackbone_platform.notify_session_event();

package/migrations/0020_runs_entity_name.sql

@@ -0,0 +1,23 @@
+-- 0020_runs_entity_name.sql — record which agent/workflow a run belongs to.
+--
+-- The Studio Runs screen lists a run's id, trigger and status but never the
+-- NAME of the agent or workflow that produced it, so a workspace running several
+-- eve agents + workflows could not tell whose run a row was, nor filter by it.
+-- The name is known at run-creation time (the chat proxy has the agent `:name`;
+-- the workflow start has the workflow `:name`) but was dropped.
+--
+-- `entity_name` denormalises that name onto the run so the list renders it as a
+-- column and filters by it without a join. It is the agent name for `chat` runs
+-- and the workflow name for `workflow` runs; combined with the existing
+-- `trigger` the UI knows the kind. Nullable: classic/manual cloud runs (eve is
+-- dev-only) leave it NULL. Distinct from `agent_id`, which in cloud is the agent
+-- TEMPLATE id (a stable identifier, not a display name) and is null for workflows.
+
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS entity_name text;
+
+-- Backs both the exact-match filter (`WHERE entity_name = $1`) and the distinct
+-- list that populates the Runs screen's name dropdown.
+CREATE INDEX IF NOT EXISTS runs_entity_name_idx
+    ON stackbone_platform.runs (entity_name)
+    WHERE entity_name IS NOT NULL;

package/migrations/0021_trigger_subscriptions.sql

@@ -0,0 +1,67 @@
+-- 0021_trigger_subscriptions.sql — the inbound side of Stackbone Connect
+-- (feature 89): an operator links a connector polling TRIGGER to a World
+-- workflow, and a polling intake engine starts that workflow for each new item.
+--
+-- This is the emulator's OWN inbound state — deliberately NOT the classic
+-- `automation*` tables (which live in cloud and feed the deprecated `/invoke`
+-- pipeline). The model mirrors that pipeline's SHAPE (config + cursor state +
+-- a delivery journal) without coupling to it: the classic engine stays running
+-- and untouched; its retirement is tied to the World runtime's port to prod.
+--
+-- `trigger_subscriptions` holds the operator-owned link plus its polling state
+-- (the opaque cursor + last-poll marker, owned by the platform; the
+-- remote-subscription id is reserved for a future webhook/push source).
+-- `trigger_deliveries` is the at-least-once dedup journal: one row per
+-- (subscription, provider item) so two overlapping ticks or a mid-restart
+-- re-poll never start the same item's workflow twice.
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.trigger_subscriptions (
+    id                     uuid        PRIMARY KEY,
+    -- Integration id — the SAME id resolves the credential (broker) and the
+    -- trigger capability (connector kit). e.g. 'gmail'.
+    connector              text        NOT NULL,
+    -- Capability trigger id, e.g. 'message-received'. Not the reserved word
+    -- `trigger`, so the column is `trigger_id`.
+    trigger_id             text        NOT NULL,
+    -- Which broker grant to poll with: 'app' | 'user:<issuer>:<id>'.
+    principal_key          text        NOT NULL,
+    -- The World workflow this link starts.
+    workflow_name          text        NOT NULL,
+    -- Optional JSONata event→input mapping; identity when null.
+    mapping                text,
+    enabled                boolean     NOT NULL DEFAULT true,
+    -- Opaque polling cursor (Gmail historyId, etc), platform-owned. Advanced
+    -- atomically at the END of a tick.
+    poll_cursor            jsonb,
+    -- Reserved for a future push source (a provider-side subscription id); the
+    -- polling path never reads it.
+    remote_subscription_id text,
+    last_polled_at         timestamptz,
+    created_at             timestamptz NOT NULL DEFAULT now(),
+    updated_at             timestamptz NOT NULL DEFAULT now()
+);
+
+-- The reconcile sweep loads ACTIVE links to arm one repeatable each.
+CREATE INDEX IF NOT EXISTS trigger_subscriptions_enabled_idx
+    ON stackbone_platform.trigger_subscriptions (enabled, created_at)
+    WHERE enabled;
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.trigger_deliveries (
+    id               uuid        PRIMARY KEY,
+    subscription_id  uuid        NOT NULL,
+    -- The connector's stable provider item id (Gmail messageId) — the dedup key.
+    provider_item_id text        NOT NULL,
+    status           text        NOT NULL DEFAULT 'claimed'
+                                 CHECK (status IN ('claimed', 'started', 'rejected')),
+    -- The projected World run id once the workflow started.
+    run_id           text,
+    -- Validation/mapping issues when the delivery was rejected.
+    issues           jsonb,
+    created_at       timestamptz NOT NULL DEFAULT now(),
+    updated_at       timestamptz NOT NULL DEFAULT now()
+);
+
+-- The at-least-once dedup guarantee: claiming a delivery is an INSERT that
+-- collapses on this unique pair, so a re-polled item is a no-op, not a re-run.
+CREATE UNIQUE INDEX IF NOT EXISTS trigger_deliveries_dedup_idx
+    ON stackbone_platform.trigger_deliveries (subscription_id, provider_item_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.1.0-alpha.9",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -34,7 +34,8 @@
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "postgres": "^3.4.9",
-    "unpdf": "^0.12.1",
+    "semver": "^7.7.4",
+    "tar": "^7.5.13",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   }