@stackbone/cli 0.2.8 → 0.3.0

package/migrations/0028_browser_provider_system_secrets.sql

@@ -0,0 +1,39 @@
+-- 0028_browser_provider_system_secrets.sql — adopt the browser-provider
+-- credentials an operator created BY HAND (STA-288 / STA-290).
+--
+-- WHY THESE ROWS EXIST AT ALL: until now the documented way to point the browser
+-- tooling at the managed remote browser was to type `BROWSERBASE_API_KEY` and
+-- `BROWSERBASE_PROJECT_ID` straight into the Studio → Secrets screen (see the SDK's
+-- browser-tools reference). Those rows landed the only way that screen can write
+-- them: `is_system = false`. Live boxes therefore carry hand-made, non-system rows
+-- under names that are now RESERVED (`RESERVED_BROWSER_PROVIDER_SECRET_NAMES` in
+-- libs/shared/validators/src/lib/studio/studio-secrets.ts).
+--
+-- WHY RESERVING ALONE IS NOT ENOUGH: reservation blocks creating, overwriting and
+-- deleting a name through the Secrets surface. It does not touch what is already
+-- stored. Without this migration the operator would be left staring at a listed row
+-- they can neither edit nor delete — a dead end. Flipping the flag is what hides the
+-- row from the listing (`listSecrets` filters `is_system = false`), blocks revealing
+-- it, and hands custody to the privileged browser-provider route.
+--
+-- The names are duplicated here on purpose: SQL cannot import the TypeScript
+-- constant, and platform-schema deliberately depends on no other lib. The
+-- browser-provider mode key (`BROWSER_MODE`) is listed too even though nothing wrote
+-- it before this feature — a box cannot have one, and including it keeps the SQL and
+-- the registry readable as the same list. `STACKBONE_BROWSER_CDP_URL` is absent
+-- because the `STACKBONE_` prefix has always been reserved, so a hand-made row under
+-- that name never existed.
+--
+-- ONLY the flag moves — `nonce` and `ciphertext` are untouched, so the value keeps
+-- decrypting with the box's per-agent key and the browser tooling (which reads
+-- through `client.secrets`, a facade that deliberately does not filter system rows)
+-- keeps working across the flip.
+--
+-- IDEMPOTENT: the `is_system = false` guard makes a second run affect zero rows and
+-- stops it churning `updated_at` on rows already adopted. On a box that never had
+-- these secrets the statement is a plain no-op.
+UPDATE stackbone_platform.secrets
+   SET is_system  = true,
+       updated_at = now()
+ WHERE name IN ('BROWSER_MODE', 'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID')
+   AND is_system = false;

package/migrations/0029_workspace_settings.sql

@@ -0,0 +1,37 @@
+-- 0029_workspace_settings.sql — the PLATFORM-owned operational settings of a
+-- workspace (STA-311). One row, one JSON payload, plus the author and the
+-- timestamp of the last change.
+--
+-- Why a table of its own instead of a key inside `agent_config` (0010): that
+-- payload is validated against the JSON Schema the build extracts from the
+-- creator's `config.schema.ts`, and `z.toJSONSchema` emits a CLOSED object by
+-- default (`additionalProperties: false`). The moment a creator declares a config
+-- schema, a platform key living inside their payload would be rejected outright.
+-- These knobs belong to the platform, not to the creator, so they get their own
+-- store with a schema the platform owns.
+--
+-- Why no version history (unlike `agent_config_versions`, 0007): these are
+-- operational settings, not a creator artifact. Last-write-wins with an author
+-- stamp is enough — there is nothing to roll back to.
+--
+-- The payload defaults to `{}`; the DEFAULTS live in the platform schema
+-- (`@stackbone/validators` → `studio-workspace-settings.ts`), never in the DDL,
+-- so the runtime, the SDK and the Studio screen all read one source of truth.
+
+-- `updated_at` is NULLABLE and carries NO default on purpose: the seed row below
+-- would otherwise stamp every fresh box with the migration's wall clock, and
+-- "nobody ever configured this workspace" would be indistinguishable from a real
+-- edit. NULL means untouched; a write always sets it explicitly.
+CREATE TABLE IF NOT EXISTS stackbone_platform.workspace_settings (
+    id         int         PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+    payload    jsonb       NOT NULL DEFAULT '{}'::jsonb,
+    updated_at timestamptz,
+    updated_by text
+);
+
+-- Seed the single row so readers never have to branch on "no row yet".
+-- Idempotent: re-running the migration leaves an already-written payload (and
+-- its author stamp) untouched.
+INSERT INTO stackbone_platform.workspace_settings (id, payload)
+VALUES (1, '{}'::jsonb)
+ON CONFLICT (id) DO NOTHING;

package/migrations/0030_run_steps_connection_hook.sql

@@ -0,0 +1,27 @@
+-- 0030_run_steps_connection_hook.sql — widen the run_steps type CHECK to admit
+-- two new activity step kinds alongside the existing `workflow_step` /
+-- `model_call` rows (0018_run_steps_v2.sql).
+--
+-- `connection` — one row per outbound connector call (`callConnector(...)` /
+-- `connection(id).op(...)`), instrumented in the runtime the same way a direct
+-- `client.ai` call records a `model_call`. Carries the call's input
+-- (connector/operation/args), output and error; no token columns.
+--
+-- `hook`        — one row per `requestApproval(...)` durable pause (the WDK hook
+-- that backs HITL). Projected running when the approval is created and resolved
+-- to completed/failed when a human decides or the wait times out. The
+-- `approvals` row stays the source of truth for the inbox; this row only mirrors
+-- the pause onto the run-step timeline so it reads inline in the trace viewer.
+--
+-- The pg_notify trigger (`notify_run_step_event`) already streams ANY type over
+-- SSE, so no trigger change is needed — new-typed rows flow live for free.
+
+-- The 0018 inline column CHECK is auto-named `run_steps_type_check` by Postgres.
+-- Drop it (guarded) and recreate it widened as a named constraint so future
+-- migrations can target it by a stable name.
+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 ('workflow_step', 'model_call', 'connection', 'hook'));

package/migrations/0031_recurring_job_executions.sql

@@ -0,0 +1,51 @@
+-- 0031_recurring_job_executions.sql — the box's record of WHEN each RECURRING
+-- job last ran, and how it ended (STA-343).
+--
+-- Why a table at all: BullMQ cannot answer "when did this repeatable last run?".
+-- Every recurring job the runtime declares drops its completed ticks by design
+-- (`removeOnComplete: true` in `DEFAULT_RECURRING_JOB_OPTS`), so the finished tick
+-- is gone from Redis the moment it succeeds. The recurring-jobs REGISTRY writes
+-- this row itself, from the wrapper it already puts around every tick handler, so
+-- a job author gets the record for free by declaring an entry.
+--
+-- Writing the PREVIOUS occurrence down also removes work downstream: the
+-- countdown a screen shows is `(now - previous) / (next - previous)`, and BullMQ
+-- only hands out `next` — deriving `previous` from a cron pattern is real work we
+-- would rather not do when the tick already knew the answer.
+--
+--   job_id      — the registry's scheduler id (e.g. `decl:digest#0`,
+--                 `sub:<link-id>`). PRIMARY KEY: ONE row per job, overwritten on
+--                 each tick, so the table is bounded by the number of DECLARED
+--                 jobs and never grows with the number of ticks. This is a "last
+--                 execution" record, not a history.
+--   family      — the scheduler-id prefix that namespaces the job (`decl:`,
+--                 `dyn:`, `sub:`, `connector-token-refresh:`). Kept even though
+--                 the id starts with it: a reader groups by family, and an id
+--                 like `sub:<uuid>` is not self-describing without the registry's
+--                 own declaration.
+--   started_at  — measured by the wrapper BEFORE the handler runs.
+--   finished_at — measured by the wrapper when the handler settles. Both come
+--                 from the BOX's clock (never `now()` here), so a reader can
+--                 compare them against BullMQ's `next` without mixing clocks.
+--   status      — terminal outcome of the tick: `done` or `failed`. Never
+--                 in-flight: the row is written ONCE, when the tick settles, so
+--                 a box that dies mid-tick leaves no half-written row.
+--   error       — the failure reason on `failed`; NULL on `done`. Always
+--                 rewritten (never merged), so a green row can't carry the stale
+--                 reason of the failure before it.
+--
+-- NOT seeded: a job that has never run must report NO last execution rather than
+-- a fabricated one, so nothing here defaults to `now()` and no row is planted for
+-- a declared-but-never-run job.
+--
+-- Idempotent (CREATE TABLE IF NOT EXISTS): every box re-applies the migration set
+-- on boot, and an existing box must keep everything it already recorded.
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.recurring_job_executions (
+    job_id      text        PRIMARY KEY,
+    family      text        NOT NULL,
+    started_at  timestamptz NOT NULL,
+    finished_at timestamptz NOT NULL,
+    status      text        NOT NULL CHECK (status IN ('done', 'failed')),
+    error       text
+);

package/migrations/0032_run_steps_external_step_id.sql

@@ -0,0 +1,48 @@
+-- 0032_run_steps_external_step_id.sql — turn `run_steps` into the journal of ANY
+-- execution, not just a workflow's. Two changes, one migration:
+--
+-- 1. RENAME the correlation key. `world_step_id` (0018_run_steps_v2.sql) was
+--    named after its only producer at the time: the workflow projector storing
+--    the World `stepId`. A deep-agent chat turn now writes its `tool_call_id`
+--    into the same slot, so the column becomes `external_step_id` — "the
+--    producer's own correlation key", whoever the producer is. Persisting it is
+--    not cosmetic: a tool that paused for human approval resumes in ANOTHER
+--    process, which has no row id in memory and can only find the open step by
+--    this key.
+--
+--    Postgres stores an index's predicate and columns by attribute NUMBER, so
+--    renaming the column rewrites `(run_id, external_step_id) WHERE
+--    external_step_id IS NOT NULL` automatically — the partial unique index
+--    keeps biting with no rebuild. Only its NAME has to be fixed by hand, so it
+--    stops lying too.
+--
+-- 2. WIDEN the type CHECK with two kinds the chat journal needs:
+--      `tool_call` — one tool invocation inside a turn.
+--      `agent`     — one subagent delegation (the `task` tool call and the
+--                    subagent boundary folded into ONE row; the tools it calls
+--                    hang off it via parent_step_id).
+--    The four existing types are reused verbatim. 0030 already made
+--    `run_steps_type_check` a NAMED constraint precisely so a later migration
+--    could target it by name — reuse it.
+--
+-- The pg_notify trigger (`notify_run_step_event`) streams ANY type and reads the
+-- correlation column by name nowhere, so no trigger change is needed — rows of
+-- the new types flow live over SSE for free.
+--
+-- Nothing writes `tool_call` / `agent` rows yet: this migration only opens the
+-- door for the instrumentation that follows.
+
+ALTER TABLE stackbone_platform.run_steps
+    RENAME COLUMN world_step_id TO external_step_id;
+
+ALTER INDEX IF EXISTS stackbone_platform.run_steps_world_step_uq
+    RENAME TO run_steps_external_step_uq;
+
+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 (
+            'workflow_step', 'model_call', 'connection', 'hook', 'tool_call', 'agent'
+        ));

package/migrations/0033_runtime_identity.sql

@@ -0,0 +1,25 @@
+-- 0032_runtime_identity.sql — the identity a runtime container derives for
+-- itself on first boot (STA-350).
+--
+-- The image used to demand an installation id and an HMAC secret as environment
+-- variables. Neither is real configuration: the installation id only has to stay
+-- stable across restarts of this container, and the HMAC secret goes unused
+-- until the operator links the deployment to a control plane. Making the
+-- customer invent both before the box will start was pure friction, so the box
+-- now mints them once and remembers them here.
+--
+-- One row, like `workspace_settings` (0029): this table describes THE runtime,
+-- not a collection of anything. The row IS the identity, so there is no seed —
+-- its absence is exactly what "this database has never hosted a runtime" means,
+-- and that absence is the signal the boot warns about before minting a fresh one.
+--
+-- Deliberately NOT encrypted with `STACKBONE_SECRET_KEY`: an operator debugging a
+-- link failure has to be able to read the signing secret out of their own
+-- database, and this database already holds every encrypted secret plus every
+-- run, so storing one more value in it adds no new exposure.
+CREATE TABLE IF NOT EXISTS stackbone_platform.runtime_identity (
+    id              int         PRIMARY KEY DEFAULT 1 CHECK (id = 1),
+    installation_id uuid        NOT NULL,
+    hmac_secret     text        NOT NULL,
+    created_at      timestamptz NOT NULL DEFAULT now()
+);

package/migrations/0034_guardrails.sql

@@ -0,0 +1,92 @@
+-- 0034_guardrails.sql — the box's own GUARDRAIL policies (STA-359): the rules an
+-- operator configures to stop a turn before it ever reaches the agent.
+--
+-- Numbered 0034: slots 0032 and 0033 were taken by the trunk while this feature
+-- was being built (`0032_run_steps_external_step_id`, `0033_runtime_identity`).
+-- The runner keys `schema_migrations` by the 4-digit prefix, so two files sharing
+-- a number are not merely untidy — the second one to sort is read as a rewrite of
+-- a version already applied and aborts the whole boot. Renumber against the tip
+-- you are actually merging into, not the one you branched from.
+--
+-- Why the policy lives in the DATABASE and not in the agent bundle: a guardrail
+-- is an OPERATOR knob, not a creator artifact. It has to be editable from Studio
+-- and take effect on the NEXT turn, with no rebuild and no restart — which it
+-- cannot do if it is baked into a compiled graph. The runtime therefore reads the
+-- effective policy per turn (behind a short cache), straight off these rows.
+--
+--   guardrail_definitions — one row per named rule.
+--     name       — operator-facing, UNIQUE per box: it is what a blocked user
+--                  reads in the reason, so two rules may not share it.
+--     check_type — which catalog check runs (`denylist`, `length_cap`). The
+--                  catalog itself lives in `@stackbone/guardrails` and is served
+--                  over HTTP; this column is deliberately NOT constrained by a
+--                  CHECK, because a box running an older build must be able to
+--                  STORE a check type it cannot run rather than reject the write
+--                  and lose the operator's policy. An unknown type fails CLOSED
+--                  at evaluation time (the engine's own rule), which is the safe
+--                  place for that decision.
+--     target     — which side of the turn it inspects (`input` today).
+--     action     — what it does when it fires (`block` today).
+--     params     — the check's own settings, validated against the CATALOG at the
+--                  handler, never by the DDL. The catalog is the one description
+--                  of each check's shape; a CHECK constraint here would be a
+--                  second one that drifts.
+--     enabled    — a disabled rule NEVER fires. Kept as a flag rather than a
+--                  delete so an operator can switch a policy off for one incident
+--                  and back on afterwards without retyping it.
+--     fail_open  — what to do when the CHECK ITSELF cannot run (bad params, an
+--                  invalid pattern). FALSE = fail closed, the safe default for a
+--                  guard. Never confused with a real policy violation, which
+--                  blocks either way.
+--
+--   guardrail_attachments — which units a rule applies to. Created now, exercised
+--     now only in its workspace-wide shape (`scope = 'workspace'`, `unit_id`
+--     NULL), because the workspace-wide default is IMPLICIT in this slice: every
+--     enabled definition applies. The per-unit resolution (a rule attached to one
+--     agent or one workflow) is a later slice; the table ships now so the
+--     resolver's contract — de-duplication, deterministic order, dangling rows
+--     ignored — is real behaviour with tests rather than a promise.
+--     Deleting a definition CASCADES its attachments: an attachment to a rule
+--     that no longer exists is not a policy, it is a leak.
+--
+-- No defaults for the payload live here — the documented defaults live in the
+-- platform schema (`@stackbone/validators` → `studio-guardrails.ts`), so the
+-- runtime, the facade and the Studio form all read one source of truth. The
+-- column defaults below are structural only (identity, timestamps, and the two
+-- booleans whose absence would otherwise make a row unreadable).
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.guardrail_definitions (
+    id         uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    name       text        NOT NULL,
+    check_type text        NOT NULL,
+    target     text        NOT NULL,
+    action     text        NOT NULL,
+    params     jsonb       NOT NULL DEFAULT '{}'::jsonb,
+    enabled    boolean     NOT NULL DEFAULT true,
+    fail_open  boolean     NOT NULL DEFAULT false,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now(),
+    -- The acting user, as the verified JWT / signed actor header reported them.
+    -- NULL on the un-authenticated `stackbone dev` datapath.
+    created_by text,
+    updated_by text
+);
+
+-- The name is what a blocked user reads. Two rules sharing it would make the
+-- reason ambiguous, so the uniqueness is enforced by the box, not by the screen.
+CREATE UNIQUE INDEX IF NOT EXISTS guardrail_definitions_name_key
+    ON stackbone_platform.guardrail_definitions (name);
+
+CREATE TABLE IF NOT EXISTS stackbone_platform.guardrail_attachments (
+    id            uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    definition_id uuid        NOT NULL
+                  REFERENCES stackbone_platform.guardrail_definitions (id) ON DELETE CASCADE,
+    -- `workspace` is the only scope in this slice. Widened by the per-unit slice.
+    scope         text        NOT NULL,
+    -- The attached unit (an agent name, a workflow name). NULL for `workspace`.
+    unit_id       text,
+    created_at    timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS guardrail_attachments_definition_idx
+    ON stackbone_platform.guardrail_attachments (definition_id);

package/migrations/0035_run_steps_guardrail.sql

@@ -0,0 +1,41 @@
+-- 0035_run_steps_guardrail.sql — widen the run_steps type CHECK to admit the
+-- GUARDRAIL decision step (STA-359), alongside `workflow_step` / `model_call`
+-- (0018), `connection` / `hook` (0030) and `tool_call` / `agent` (0032, from the
+-- trunk — see the note above the constraint below).
+--
+-- `guardrail` — one row per guardrail decision taken at a border. A blocked chat
+-- turn writes exactly one: the name of the rule that fired, the side of the turn
+-- it inspected, and the reason the user was shown. It exists so a blocked turn is
+-- READABLE in the trace viewer — inline with the model calls and tool calls the
+-- turn never got to make — instead of being an invisible non-event that only
+-- shows up as a suspiciously short conversation.
+--
+-- One spelling, everywhere: `guardrail` is the `run_steps.type` value, the
+-- neutral `AgentEvent` variant and the AG-UI `CUSTOM` frame name. The earlier
+-- placeholder `guardrail_triggered` (docs only, never in code) is retired.
+--
+-- The pg_notify trigger (`notify_run_step_event`) already streams ANY type over
+-- SSE, so no trigger change is needed — guardrail rows flow live for free.
+
+-- 0030 recreated this as a NAMED constraint precisely so it could be targeted
+-- here. Drop it (guarded — every box re-applies the whole set on boot) and
+-- recreate it widened.
+--
+-- The list below names `tool_call` and `agent`, which NOTHING IN THIS FEATURE
+-- WRITES: they arrived with `0032_run_steps_external_step_id` and belong to the
+-- deep-agent turn journal. Recreating a named CHECK replaces it WHOLESALE rather
+-- than adding to it, so naming only the types this feature cares about would
+-- revoke those two the moment this file runs after 0032. Nothing would flag it:
+-- the two migrations are different files, so there is no merge conflict, and the
+-- damage would surface much later as a 23514 on the first tool call of every chat
+-- turn. The rule for anyone touching this constraint again: carry the whole
+-- accepted set forward, never just your own additions.
+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 (
+            'workflow_step', 'model_call', 'connection', 'hook',
+            'tool_call', 'agent', 'guardrail'
+        ));

package/migrations/0036_guardrail_attachment_units.sql

@@ -0,0 +1,61 @@
+-- 0036_guardrail_attachment_units.sql — attach a guardrail WHERE IT IS NEEDED
+-- (STA-365), instead of every enabled rule applying to everything.
+--
+-- 0034 shipped `guardrail_attachments` already carrying `scope` + `unit_id`, but
+-- only ever wrote the workspace-wide shape, because resolution at the time was
+-- implicit: an enabled definition applied everywhere. This migration turns that
+-- table into the real thing.
+--
+-- `scope` now takes three values:
+--
+--   `workspace` — the DEFAULT SET (`unit_id` NULL). It covers every agent and
+--     every workflow, including ones added after the rule was written. This is
+--     what makes a newly created agent protected with nobody remembering to do
+--     anything.
+--   `agent` / `workflow` — ONE named unit (`unit_id` = its name), so a high-risk
+--     agent can be stricter than the rest without duplicating the policy.
+--
+-- Deliberately NOT a CHECK constraint on `scope`, for the same reason `check_type`
+-- has none: a box running an older build must be able to STORE a scope it cannot
+-- resolve rather than reject the write and lose the operator's policy. An
+-- unrecognised scope is IGNORED at resolution time (the resolver's own rule),
+-- which is the safe place for that decision — a stale or unreadable attachment
+-- must never take a chat turn down.
+--
+-- Two things this file does add:
+--
+-- 1. UNIQUENESS per (rule, place). Attaching the same rule to the same unit twice
+--    would run the same check twice on one turn — the resolver de-duplicates by
+--    definition id anyway, but a duplicate row is a lie about the policy and it
+--    would show up twice in the blast-radius summary the screen paints before an
+--    edit or a delete. `COALESCE(unit_id, '')` is what makes the workspace shape
+--    unique too: plain SQL NULLs are all distinct from each other, so without it
+--    one rule could hold ten identical workspace attachments.
+--
+-- 2. A BACKFILL. Every definition stored under 0034 relied on the implicit
+--    workspace-wide default. Once resolution is attachment-driven, a definition
+--    with no attachment rows applies NOWHERE — so an upgrade that skipped this
+--    step would silently switch off every guardrail an operator had already
+--    configured. Giving each of them the workspace attachment they implicitly had
+--    keeps behaviour identical across the upgrade.
+
+-- The unique index must exist before the backfill, so a re-run cannot double the
+-- backfilled rows.
+CREATE UNIQUE INDEX IF NOT EXISTS guardrail_attachments_unit_key
+    ON stackbone_platform.guardrail_attachments (definition_id, scope, COALESCE(unit_id, ''));
+
+-- Index the lookup the resolver's read actually makes: every attachment for the
+-- box, joined back onto its definition. `definition_id` is already indexed by
+-- 0034; this one serves the per-unit filter a large box would otherwise scan.
+CREATE INDEX IF NOT EXISTS guardrail_attachments_unit_idx
+    ON stackbone_platform.guardrail_attachments (scope, unit_id);
+
+INSERT INTO stackbone_platform.guardrail_attachments (definition_id, scope, unit_id)
+SELECT d.id, 'workspace', NULL
+  FROM stackbone_platform.guardrail_definitions d
+ WHERE NOT EXISTS (
+       SELECT 1
+         FROM stackbone_platform.guardrail_attachments a
+        WHERE a.definition_id = d.id
+       )
+ON CONFLICT DO NOTHING;

package/migrations/0037_runs_entity_kind.sql

@@ -0,0 +1,45 @@
+-- 0037_runs_entity_kind.sql — record WHICH KIND of entity produced a run, so two
+-- entries that share a name stop contaminating each other (STA-426).
+--
+-- 0020 denormalised the entity NAME onto the run and its comment claimed that
+-- "combined with the existing `trigger` the UI knows the kind". That is not true:
+-- `trigger` records WHY a run started (manual, cron, chat, workflow), not WHAT the
+-- entity is — a workflow run started by cron carries `cron`, and a workflow that
+-- opens an agent turn carries `chat`. So the name was doing identity work on its
+-- own, and a deep agent named `sync` plus a workflow named `sync` landed in one row
+-- set: every screen that filters runs by name showed the two mixed together.
+--
+-- The guardrails side of the codebase already settled this vocabulary — a guardrail
+-- attachment is scoped to an `agent` or a `workflow` unit precisely because the KIND
+-- is part of an entry's identity, never just the name. `entity_kind` brings the runs
+-- table in line with it.
+--
+-- Deliberately NOT a CHECK constraint, for the same reason 0036's `scope` has none:
+-- a box running an older build must be able to STORE a kind it cannot resolve rather
+-- than reject the write and lose the run. An unrecognised kind simply never matches a
+-- filter, which is the safe failure.
+--
+-- NO BACKFILL. Rows written before this migration keep a NULL kind, and the two reads
+-- that filter by kind treat that gap differently, on purpose.
+--
+-- The runs LIST admits a NULL kind under a matching name, so nothing that works today
+-- stops working. Under a name two entries share, such a row shows up on both: nothing
+-- on it says which one it was, and a human reading the list can see that for himself.
+--
+-- The AGGREGATE read admits it only for a name that is unambiguous in the request.
+-- Excluding legacy rows outright reported a workspace that had been running for a week
+-- as idle right after every upgrade, while the list one click away showed them — two
+-- surfaces of one feature contradicting each other. But admitting them under a shared
+-- name would count one run twice and invent activity, so there they stay out of both.
+
+ALTER TABLE stackbone_platform.runs
+    ADD COLUMN IF NOT EXISTS entity_kind text;
+
+-- Backs the (name, kind) exact-match filter and the distinct (name, kind) list that
+-- feeds the Runs screen's dropdown. A NEW index rather than a widened
+-- `runs_entity_name_idx`: dropping and recreating 0020's index under its own name
+-- would silently revoke whatever a later migration or an operator added to it, and
+-- the name-only filter still uses it.
+CREATE INDEX IF NOT EXISTS runs_entity_name_kind_idx
+    ON stackbone_platform.runs (entity_name, entity_kind)
+    WHERE entity_name IS NOT NULL;