@bongos/core 1.23.21 → 1.24.1

package/docs/recipes/google-sign-in.md

@@ -0,0 +1,60 @@
+# Turning on Google sign-in (the hub)
+
+Google sign-in ([task 1004993](https://cloudbongos.com/builders#/task/1004993), [ADR 0396](../adr/0396-google-sign-in-a-stand-in-login-and-a-browser-approved-cli-sign-in.md)) ships **switched off**. Until the two keys below are on the server, the site behaves exactly as before: GitHub only, no chooser page, and the command line still uses GitHub's code page. Adding the keys is what turns it on, so it is also the "go live" step.
+
+It needs a Google sign-in app. The app is **free** and takes about ten minutes to create. Only the owner should create it, signed in with the Google account that should own it.
+
+> **Never paste the client secret into a chat, a task, a commit or Discord.** It goes straight from Google's page into the server's settings file.
+
+## 1. Create the Google sign-in app
+
+1. Open <https://console.cloud.google.com/> and sign in.
+2. In the top bar, click the project picker, then **New project**. Name it `Cloud Bongos sign-in` and click **Create**. When it is ready, make sure it is the selected project in the top bar.
+3. In the left menu open **APIs & Services → OAuth consent screen**. Google may call this **Google Auth Platform**. Click **Get started**.
+   - **App name:** `Cloud Bongos`. **User support email:** your address.
+   - **Audience:** **External**.
+   - **Contact information:** your address. Tick the agreement and click **Create**.
+4. Open **Branding** and fill in:
+   - **Application home page:** `https://cloudbongos.com`
+   - **Privacy policy:** `https://cloudbongos.com/privacy`
+   - **Terms of service:** `https://cloudbongos.com/terms`
+   - **Authorised domains:** `cloudbongos.com`
+
+   Click **Save**. Leave the logo empty: adding one sends the app to Google for a review.
+5. Open **Data access**. Do not add anything. The three basic scopes (name, email address, profile picture) are all Bongos asks for, and they need no review.
+6. Open **Audience** and click **Publish app**, then **Confirm**. Until you do this, only email addresses you list as test users can sign in.
+7. Open **Clients**, click **Create client**, and fill in:
+   - **Application type:** **Web application**
+   - **Name:** `Cloud Bongos web`
+   - **Authorised redirect URIs:** click **Add URI** and enter exactly `https://cloudbongos.com/api/bongos/auth/google/callback`
+   - Leave **Authorised JavaScript origins** empty.
+
+   Click **Create**.
+8. Google shows a **Client ID** and a **Client secret**. Click **Download JSON** and keep the file somewhere private. You need both values in the next step.
+
+## 2. Put the two values on the server
+
+The server keeps its sign-in keys in its settings file, the same file that already holds `…_GITHUB_CLIENT_ID` (on cloudbongos.com: `/etc/cloudbongos/web.env`). Add two lines next to the GitHub ones. Use **the same first word** those lines start with, so that if they read `CLOUDBONGOS_GITHUB_CLIENT_ID`, yours read:
+
+```
+CLOUDBONGOS_GOOGLE_CLIENT_ID=<the Client ID>
+CLOUDBONGOS_GOOGLE_CLIENT_SECRET=<the Client secret>
+```
+
+Then restart the web service, the same way as after any other change to that file. If you would rather not edit the file yourself, ask in a session for help doing it on the server, but still type the secret there yourself.
+
+## 3. Check it
+
+1. Open <https://cloudbongos.com> in a private window and click **Sign in**. You should see **Continue with GitHub** and **Continue with Google**.
+2. Click **Continue with Google** and pick an account. A first sign-in creates an account and lands on the account page so the person can choose their handle.
+3. In a terminal, run the Bongos sign-in. The browser opens a cloudbongos.com page showing the same code as the terminal. Press **Approve**, and the terminal finishes by itself.
+
+## What a Google-only person can and cannot do yet
+
+- **Can:** sign up and sign in on cloudbongos.com and its hall, use the command line, and edit their account.
+- **Cannot yet:** join another project's hall ([task 1004994](https://cloudbongos.com/builders#/task/1004994)) or link GitHub and Google together ([task 1004995](https://cloudbongos.com/builders#/task/1004995)). They are told so in plain words.
+- Until they link GitHub, the hall shows them as `~<their handle>`. The `~` means "no GitHub account".
+
+## Turning it off again
+
+Remove the two lines and restart. Accounts created with Google stay. Their owners cannot sign in again until the lines are back, and their data is not lost.

package/docs/recipes/ops-gotchas.md

@@ -171,7 +171,7 @@ Inside the namespace the file lists as `---------- 1 root root 0`. The runner un
 
 - **Symptom:** on a fresh instance every `/builder-ship` parks at `confirmed`; `GET /tasks/:id/publish-status` answers 503 `push_unconfigured`; the archon has to merge PRs and `POST /tasks/:id/ship` by hand. Silent — work just piles up (gap-list W7, proven live on Spike Harbor task 1).
 - **Root cause:** the ADR 0133 manifest used to request **zero** repo permissions and the conversion's App private key (`pem`) was discarded, so no publish credential (ADR 0055) ever existed on a wizard-born instance. Fixed for newly minted Apps (task 1003049): the manifest now requests `contents: write` + `pull_requests: write` + `actions: read`, `placeManifestCreds` writes `GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` into web.env, and the server discovers the installation id at runtime — the one human step left is **installing the App on the repo** (the onboarding `app-install` step).
-- **Fix for pre-existing instances:** in the App's GitHub settings — (1) **Permissions & events**: grant Contents read/write, Pull requests read/write, Actions read-only; (2) **General → Private keys**: generate a key; (3) put `GITHUB_APP_ID=<id>` and `GITHUB_APP_PRIVATE_KEY=<pem as one line with literal \n>` in `/etc/<slug>/web.env` and restart the unit; (4) **Install App** → pick the project repo (owners must re-approve the new permissions on an already-installed App). Alternative: a fine-grained `GITHUB_PUSH_TOKEN` PAT with the same three scopes (ADR 0055).
+- **Fix for pre-existing instances:** in the App's GitHub settings — (1) **Permissions & events**: grant Contents read/write, Pull requests read/write, Actions read-only; (2) **General → Private keys**: generate a key; (3) put `GITHUB_APP_ID=<id>` and `GITHUB_APP_PRIVATE_KEY="<pem as one line with literal \n>"` in `/etc/<slug>/web.env` — **double-quoted**: systemd drops an unquoted backslash, so the server gets `n` for every line break and fails with `ERR_OSSL_UNSUPPORTED` (task 1005009) — and restart the unit; (4) **Install App** → pick the project repo (owners must re-approve the new permissions on an already-installed App). Alternative: a fine-grained `GITHUB_PUSH_TOKEN` PAT with the same three scopes (ADR 0055).
 - **How you know it worked:** `publish-status` stops 503ing, and the publish-reconciler log line `WARN … not installed` (if the App wasn't installed yet) goes quiet after the install.
 
 ---

package/migrations/core_282_builders_lower_login_idx.sql

@@ -0,0 +1,33 @@
+-- =========================================================================
+-- core_282 — index builders by lower(github_login) (task 1004923, from the DB
+-- performance audit)
+--
+-- builders has NO index on github_login at all: 003_pms declares github_id
+-- UNIQUE and leaves github_login bare, and no later migration indexes it. Yet
+-- the admission paths look a builder up by login, case-insensitively:
+--
+--   the onboarding routes  "is this login already a member?" before an
+--                          invite, an approval and the public POST
+--                          (SELECT 1 FROM builders WHERE lower(github_login) = lower($1))
+--   the access-request     a correlated is-member probe PER access_requests row
+--   lists                  (EXISTS ... WHERE lower(b.github_login) = lower(ar.github_login))
+--
+-- A plain index on github_login could not serve any of them — they compare
+-- lower(), so only an index on the expression can. Each was a sequential scan
+-- of builders, and the list probes paid it once per row.
+--
+-- Not UNIQUE on purpose: logins can be renamed on GitHub and github_id is the
+-- stable key, so two rows may legitimately have held the same login over time.
+--
+-- Additive and idempotent: an index only, no column, constraint or data. Safe to
+-- run forward against a live database; an older release just has an unused
+-- index. Rollback is DROP INDEX.
+
+CREATE INDEX IF NOT EXISTS idx_builders_lower_login
+  ON builders (lower(github_login));
+
+COMMENT ON INDEX idx_builders_lower_login IS
+  'Case-insensitive builder-by-login lookups on the admission paths (modules/onboarding/routes/access-requests.js). github_login had no index of any kind before this (task 1004923).';
+
+INSERT INTO schema_migrations (version) VALUES ('core_282_builders_lower_login_idx')
+  ON CONFLICT DO NOTHING;

package/migrations/core_283_claimable_ignores_page_markers.sql

@@ -0,0 +1,53 @@
+-- core_282 — claimable_tasks ignores an artist's page claim (task 1004947).
+--
+-- An artist claiming a page holds a web claim (no worktree, no session) on a
+-- page-tweak task whose touches list the page's files. It is a MARKER: it says
+-- "this page is being updated" and nothing more. The touches-overlap guard below
+-- hid every ready engineering task on those files while the marker stood. The
+-- two inlined copies (CLAIMABLE_SQL in modules/lifecycle/db-tasks.js and
+-- src/bongos/optimizer.js) carry the same exclusion, and
+-- tests/claimable_blocker_status.mjs pins all three. COALESCE keeps a claim on a
+-- source-less task counted (a NULL source must not make the NOT evaluate to NULL).
+--
+-- Everything else is core_264's definition, byte for byte: DROP VIEW IF EXISTS +
+-- CREATE, the t.* wildcard, the blocker and dependency clauses unchanged.
+
+BEGIN;
+
+DROP VIEW IF EXISTS claimable_tasks;
+CREATE VIEW claimable_tasks AS
+SELECT t.*,
+       pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+  FROM tasks t
+ WHERE t.status = 'ready'
+   AND t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\'
+   AND NOT EXISTS (
+     SELECT 1
+       FROM task_blockers tb
+       LEFT JOIN blockers b ON b.id = tb.blocker_id
+      WHERE tb.task_id = t.id
+        AND (b.id IS NULL OR b.status = 'open')
+   )
+   AND NOT EXISTS (
+     SELECT 1
+       FROM dependencies d
+      WHERE ((d.from_kind = 'task'      AND d.from_id = t.id)
+          OR (d.from_kind = 'goal'      AND d.from_id = t.goal_id)
+          OR (d.from_kind = 'criterion' AND d.from_id IN (
+                SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id)))
+        AND ((d.to_kind = 'task'      AND EXISTS (SELECT 1 FROM tasks              x WHERE x.id = d.to_id AND x.status <> 'shipped'))
+          OR (d.to_kind = 'criterion' AND EXISTS (SELECT 1 FROM done_when_criteria x WHERE x.id = d.to_id AND x.satisfied = false))
+          OR (d.to_kind = 'goal'      AND EXISTS (SELECT 1 FROM goals              x WHERE x.id = d.to_id AND x.status <> 'achieved')))
+   )
+   AND NOT EXISTS (
+     SELECT 1 FROM claims c
+       JOIN tasks t2 ON t2.id = c.task_id
+      WHERE c.released_at IS NULL
+        AND NOT (COALESCE(t2.source, '') = 'page-tweak' AND c.worktree_name IS NULL AND c.creator_session_id IS NULL)
+        AND t2.touches && t.touches
+   );
+
+COMMIT;
+
+INSERT INTO schema_migrations (version) VALUES ('core_283_claimable_ignores_page_markers')
+  ON CONFLICT (version) DO NOTHING;

package/migrations/core_283_payout_approvals.sql

@@ -0,0 +1,183 @@
+-- core_283_payout_approvals.sql — every payout needs a logged, personal approval,
+-- and the approvals are an unchangeable log (task 1004913, goal 1000092 N9;
+-- ADR 0385 decisions 4 and 8, ADR 0387 decision 3).
+--
+-- WHY. The owner's legal framework (Art. I, cited by Article only) says a payout,
+-- equity grant or contract is never executed by the platform or an AI on its own:
+-- each needs a distinct step by the project's authorised person, kept in an
+-- append-only log of who approved what and when. If we cannot prove the person
+-- pressed the button, we were the actor. ADR 0385 decision 4 lets a project sign a
+-- STANDING payout rule once (caps, formula, schedule, a pause window before each
+-- run) instead of approving every payout; equity grants and contracts keep one
+-- signature each; an AI may never create or widen a rule.
+--
+-- SHAPE. One table, one row per event, never edited:
+--
+--   rule_signed      a person signs a standing payout rule. Its row id IS the
+--                    rule id; terms holds caps, formula, schedule, pause_hours.
+--   rule_narrowed    a person tightens a signed rule. The trigger refuses any
+--                    term that would widen it (a higher cap, a shorter pause, a
+--                    different formula, schedule or currency). Widening is
+--                    therefore only possible by signing a NEW rule.
+--   rule_revoked     a person ends a rule. Nothing may follow it.
+--   run_noticed      a run under a rule is announced (who gets what). It is the
+--                    one kind that is not a signature: the runner may file it.
+--                    It may not pay before the rule's pause window has passed.
+--   run_held         a person stops a noticed run inside its pause window.
+--   payout_approved  a person approves ONE payout (recipient, cents, currency).
+--   grant_signed     a person signs ONE equity grant.
+--   contract_signed  a person signs ONE contract.
+--
+-- WHAT THE DATABASE ENFORCES (not only the code that writes here; ADR 0387 D2):
+--   * append-only: UPDATE and DELETE are refused row by row and TRUNCATE by
+--     statement, by trigger, and the privileges are revoked from PUBLIC;
+--   * personal: every kind except run_noticed must name the web session that
+--     pressed it (session_source = 'web'), and the actor must be a human
+--     builder: a machine principal (builders.system_role set) is refused;
+--   * a narrowing never widens, and nothing follows a revocation.
+-- Who may write at all (the payout.approve permission, rank fresh per request,
+-- ADR 0016) is checked by the server before the insert.
+--
+-- Nothing here moves money. A processor does that (ADR 0385); this records the
+-- authority a transfer must cite. Additive and idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS payout_approvals (
+  id              bigserial   PRIMARY KEY,
+  kind            text        NOT NULL CHECK (kind IN (
+                    'rule_signed', 'rule_narrowed', 'rule_revoked',
+                    'run_noticed', 'run_held',
+                    'payout_approved', 'grant_signed', 'contract_signed')),
+  rule_id         bigint      REFERENCES payout_approvals(id) ON DELETE RESTRICT,
+  run_key         text        CHECK (run_key IS NULL OR run_key ~ '^[A-Za-z0-9._:-]{1,80}$'),
+  actor_id        bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  actor_rank      text,
+  session_id      bigint,
+  session_source  text,
+  recipient_id    bigint      REFERENCES builders(id) ON DELETE RESTRICT,
+  amount_cents    bigint      CHECK (amount_cents IS NULL OR amount_cents > 0),
+  currency        text        CHECK (currency IS NULL OR currency ~ '^[A-Z]{3}$'),
+  terms           jsonb       NOT NULL DEFAULT '{}'::jsonb,
+  note            text        CHECK (note IS NULL OR length(note) <= 500),
+  created_at      timestamptz NOT NULL DEFAULT now(),
+
+  -- A signature names the web session that pressed it.
+  CONSTRAINT payout_approvals_personal CHECK (
+    kind = 'run_noticed' OR (session_source = 'web' AND session_id IS NOT NULL)
+  ),
+  -- Each kind carries exactly what it needs.
+  CONSTRAINT payout_approvals_shape CHECK (
+    (kind = 'rule_signed'     AND rule_id IS NULL AND run_key IS NULL AND recipient_id IS NULL AND amount_cents IS NULL AND terms <> '{}'::jsonb) OR
+    (kind = 'rule_narrowed'   AND rule_id IS NOT NULL AND run_key IS NULL AND recipient_id IS NULL AND amount_cents IS NULL AND terms <> '{}'::jsonb) OR
+    (kind = 'rule_revoked'    AND rule_id IS NOT NULL AND run_key IS NULL AND recipient_id IS NULL AND amount_cents IS NULL) OR
+    (kind = 'run_noticed'     AND rule_id IS NOT NULL AND run_key IS NOT NULL AND amount_cents IS NOT NULL AND currency IS NOT NULL) OR
+    (kind = 'run_held'        AND rule_id IS NOT NULL AND run_key IS NOT NULL AND amount_cents IS NULL) OR
+    (kind = 'payout_approved' AND rule_id IS NULL AND recipient_id IS NOT NULL AND amount_cents IS NOT NULL AND currency IS NOT NULL) OR
+    (kind IN ('grant_signed', 'contract_signed') AND rule_id IS NULL AND recipient_id IS NOT NULL AND terms <> '{}'::jsonb)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS payout_approvals_rule_idx ON payout_approvals (rule_id, id) WHERE rule_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS payout_approvals_run_once_idx ON payout_approvals (rule_id, run_key, kind) WHERE run_key IS NOT NULL;
+-- The rules list reads only the three rule kinds; every payout and run row lives
+-- in this same ever-growing table, so the list gets its own small index.
+CREATE INDEX IF NOT EXISTS payout_approvals_rules_idx ON payout_approvals (id)
+  WHERE kind IN ('rule_signed', 'rule_narrowed', 'rule_revoked');
+
+-- Append-only, by the database.
+CREATE OR REPLACE FUNCTION payout_approvals_refuse_change() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION 'payout_approvals is append-only: % refused (a correction is a new row)', TG_OP
+    USING ERRCODE = 'insufficient_privilege';
+END;
+$$;
+
+DROP TRIGGER IF EXISTS payout_approvals_no_update_delete ON payout_approvals;
+CREATE TRIGGER payout_approvals_no_update_delete
+  BEFORE UPDATE OR DELETE ON payout_approvals
+  FOR EACH ROW EXECUTE FUNCTION payout_approvals_refuse_change();
+
+DROP TRIGGER IF EXISTS payout_approvals_no_truncate ON payout_approvals;
+CREATE TRIGGER payout_approvals_no_truncate
+  BEFORE TRUNCATE ON payout_approvals
+  FOR EACH STATEMENT EXECUTE FUNCTION payout_approvals_refuse_change();
+
+REVOKE UPDATE, DELETE, TRUNCATE ON payout_approvals FROM PUBLIC;
+
+-- Personal, never widened, nothing after a revocation.
+CREATE OR REPLACE FUNCTION payout_approvals_check_insert() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  machine   text;
+  rule_kind text;
+  cur       jsonb;
+  oldv      bigint;
+  newv      bigint;
+  cap       text;
+BEGIN
+  IF NEW.kind <> 'run_noticed' THEN
+    SELECT system_role INTO machine FROM builders WHERE id = NEW.actor_id;
+    IF machine IS NOT NULL THEN
+      RAISE EXCEPTION 'payout_approvals: % must be a person''s own act; machine principal % refused', NEW.kind, machine
+        USING ERRCODE = 'insufficient_privilege';
+    END IF;
+  END IF;
+
+  IF NEW.rule_id IS NULL THEN
+    RETURN NEW;
+  END IF;
+
+  SELECT kind INTO rule_kind FROM payout_approvals WHERE id = NEW.rule_id;
+  IF rule_kind IS DISTINCT FROM 'rule_signed' THEN
+    RAISE EXCEPTION 'payout_approvals: rule % is not a signed rule', NEW.rule_id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  IF EXISTS (SELECT 1 FROM payout_approvals WHERE rule_id = NEW.rule_id AND kind = 'rule_revoked') THEN
+    RAISE EXCEPTION 'payout_approvals: rule % is revoked; nothing may follow it', NEW.rule_id
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  IF NEW.kind = 'rule_narrowed' THEN
+    SELECT terms INTO cur FROM payout_approvals
+     WHERE (id = NEW.rule_id OR (rule_id = NEW.rule_id AND kind = 'rule_narrowed'))
+     ORDER BY id DESC LIMIT 1;
+    IF (NEW.terms -> 'formula') IS DISTINCT FROM (cur -> 'formula')
+       OR (NEW.terms -> 'schedule') IS DISTINCT FROM (cur -> 'schedule')
+       OR (NEW.terms ->> 'currency') IS DISTINCT FROM (cur ->> 'currency') THEN
+      RAISE EXCEPTION 'payout_approvals: a narrowing may not change the formula, schedule or currency; sign a new rule'
+        USING ERRCODE = 'check_violation';
+    END IF;
+    IF (NEW.terms ->> 'pause_hours') IS NULL
+       OR (NEW.terms ->> 'pause_hours')::bigint < (cur ->> 'pause_hours')::bigint THEN
+      RAISE EXCEPTION 'payout_approvals: a narrowing may not shorten the pause window'
+        USING ERRCODE = 'check_violation';
+    END IF;
+    FOREACH cap IN ARRAY ARRAY['per_payout_cents', 'per_run_cents', 'per_month_cents'] LOOP
+      oldv := (cur -> 'caps' ->> cap)::bigint;
+      newv := (NEW.terms -> 'caps' ->> cap)::bigint;
+      IF oldv IS NOT NULL AND (newv IS NULL OR newv > oldv) THEN
+        RAISE EXCEPTION 'payout_approvals: a narrowing may not raise or remove the % cap', cap
+          USING ERRCODE = 'check_violation';
+      END IF;
+    END LOOP;
+  END IF;
+
+  IF NEW.kind = 'run_held' AND NOT EXISTS (
+    SELECT 1 FROM payout_approvals WHERE rule_id = NEW.rule_id AND run_key = NEW.run_key AND kind = 'run_noticed'
+  ) THEN
+    RAISE EXCEPTION 'payout_approvals: run % was never noticed', NEW.run_key
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS payout_approvals_insert_rules ON payout_approvals;
+CREATE TRIGGER payout_approvals_insert_rules
+  BEFORE INSERT ON payout_approvals
+  FOR EACH ROW EXECUTE FUNCTION payout_approvals_check_insert();
+
+COMMIT;

package/migrations/core_284_payout_gates.sql

@@ -0,0 +1,179 @@
+-- core_284_payout_gates.sql — who may be paid at all: age tier, sanctions
+-- screening, and a freeze that tells the person (task 1004914, goal 1000092 N10;
+-- ADR 0385 decision 8).
+--
+-- WHY. The owner's legal framework (cited by Article only) puts two gates in front
+-- of every payout. Art. VII, age: under 13 no account takes part in pay at all; 13
+-- to 15 no money; 16 and 17 only with a guardian's co-signature, paid into an
+-- account the guardian controls. Art. X, sanctions: the recipient is screened, and
+-- a match stops the payout. And a stop that touches money someone is owed must
+-- tell them and offer an appeal: pay is never withheld silently.
+--
+-- SHAPE. Six tables, all append-only (a correction is a new row; the latest row
+-- wins), enforced by one shared trigger:
+--
+--   payout_age_records     a builder's age tier as recorded, by whom, on what basis.
+--                          No date of birth is stored: the tier is all a gate needs.
+--   payout_guardians       a guardian link for a 16-17 builder: the guardian (a
+--                          builder), the guardian-controlled processor account, and
+--                          whether the link stands (a later row with active=false
+--                          ends it).
+--   payout_screenings      one sanctions screening result per recipient per check:
+--                          clear | match | error, who screened (the processor once
+--                          N2 chooses one, or a person), and until when a clear
+--                          result counts.
+--   payout_freezes         one stop on a person's payouts: the reason in words, the
+--                          notice they were shown, and the appeal route. A freeze is
+--                          NOTIFIED by construction: notice_text and appeal_route
+--                          are NOT NULL, so a silent freeze cannot be stored.
+--   payout_freeze_events   what happened to a freeze since: appealed, upheld, lifted.
+--   payout_guardian_cosigns a guardian's own co-signature on one payout to a
+--                          16-17 builder, from their own web session.
+--
+-- The gate itself is server code (src/bongos/payout-gates.js), run on every money
+-- route; this file is what it reads and writes.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS payout_age_records (
+  id           bigserial   PRIMARY KEY,
+  builder_id   bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  tier         text        NOT NULL CHECK (tier IN ('under_13', '13_15', '16_17', 'adult')),
+  basis        text        NOT NULL CHECK (basis IN ('self_declared', 'verified_by_processor', 'verified_by_person')),
+  recorded_by  bigint      REFERENCES builders(id) ON DELETE RESTRICT,
+  recorded_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS payout_age_records_builder_idx ON payout_age_records (builder_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS payout_guardians (
+  id                  bigserial   PRIMARY KEY,
+  builder_id          bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  guardian_id         bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  guardian_account    text        CHECK (guardian_account IS NULL OR length(guardian_account) BETWEEN 3 AND 200),
+  active              boolean     NOT NULL,
+  recorded_by         bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  recorded_at         timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payout_guardians_not_self CHECK (guardian_id <> builder_id),
+  CONSTRAINT payout_guardians_account CHECK (active = false OR guardian_account IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS payout_guardians_builder_idx ON payout_guardians (builder_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS payout_screenings (
+  id            bigserial   PRIMARY KEY,
+  builder_id    bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  result        text        NOT NULL CHECK (result IN ('clear', 'match', 'error')),
+  screened_by   text        NOT NULL CHECK (screened_by ~ '^(processor|person):[A-Za-z0-9._-]{1,60}$'),
+  reference     text        CHECK (reference IS NULL OR length(reference) <= 200),
+  valid_until   timestamptz,
+  recorded_by   bigint      REFERENCES builders(id) ON DELETE RESTRICT,
+  screened_at   timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payout_screenings_clear_expires CHECK (result <> 'clear' OR valid_until IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS payout_screenings_builder_idx ON payout_screenings (builder_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS payout_freezes (
+  id            bigserial   PRIMARY KEY,
+  builder_id    bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  reason        text        NOT NULL CHECK (reason IN ('sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown', 'manual')),
+  notice_text   text        NOT NULL CHECK (length(notice_text) BETWEEN 20 AND 1000),
+  appeal_route  text        NOT NULL CHECK (length(appeal_route) BETWEEN 1 AND 300),
+  owed_cents    bigint      CHECK (owed_cents IS NULL OR owed_cents > 0),
+  frozen_by     bigint      REFERENCES builders(id) ON DELETE RESTRICT,
+  frozen_at     timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS payout_freezes_builder_idx ON payout_freezes (builder_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS payout_freeze_events (
+  id          bigserial   PRIMARY KEY,
+  freeze_id   bigint      NOT NULL REFERENCES payout_freezes(id) ON DELETE RESTRICT,
+  kind        text        NOT NULL CHECK (kind IN ('appealed', 'upheld', 'lifted')),
+  actor_id    bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  statement   text        NOT NULL CHECK (length(statement) BETWEEN 1 AND 2000),
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS payout_freeze_events_freeze_idx ON payout_freeze_events (freeze_id, id);
+
+-- A guardian's own co-signature on one payout to a 16-17 builder: either a
+-- one-off approval or one recipient's line in a run. Their own web session only.
+CREATE TABLE IF NOT EXISTS payout_guardian_cosigns (
+  id              bigserial   PRIMARY KEY,
+  builder_id      bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  guardian_id     bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  approval_id     bigint      REFERENCES payout_approvals(id) ON DELETE RESTRICT,
+  rule_id         bigint      REFERENCES payout_approvals(id) ON DELETE RESTRICT,
+  run_key         text,
+  session_id      bigint      NOT NULL,
+  session_source  text        NOT NULL CHECK (session_source = 'web'),
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payout_guardian_cosigns_target CHECK (
+    (approval_id IS NOT NULL AND rule_id IS NULL AND run_key IS NULL) OR
+    (approval_id IS NULL AND rule_id IS NOT NULL AND run_key IS NOT NULL))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS payout_guardian_cosigns_once_idx
+  ON payout_guardian_cosigns (builder_id, COALESCE(approval_id, 0), COALESCE(rule_id, 0), COALESCE(run_key, ''));
+
+-- Only the builder's guardian, in a link that stands now, may co-sign.
+CREATE OR REPLACE FUNCTION payout_guardian_cosigns_check() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE g record;
+BEGIN
+  SELECT guardian_id, active INTO g FROM payout_guardians WHERE builder_id = NEW.builder_id ORDER BY id DESC LIMIT 1;
+  IF g IS NULL OR NOT g.active OR g.guardian_id <> NEW.guardian_id THEN
+    RAISE EXCEPTION 'only the builder''s current guardian may co-sign their payout' USING ERRCODE = 'check_violation';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS payout_guardian_cosigns_rules ON payout_guardian_cosigns;
+CREATE TRIGGER payout_guardian_cosigns_rules
+  BEFORE INSERT ON payout_guardian_cosigns
+  FOR EACH ROW EXECUTE FUNCTION payout_guardian_cosigns_check();
+
+CREATE OR REPLACE FUNCTION payout_gates_refuse_change() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION '% is append-only: % refused (a correction is a new row)', TG_TABLE_NAME, TG_OP
+    USING ERRCODE = 'insufficient_privilege';
+END;
+$$;
+
+DO $$
+DECLARE t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['payout_age_records', 'payout_guardians', 'payout_screenings', 'payout_freezes', 'payout_freeze_events', 'payout_guardian_cosigns'] LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON %I', t || '_no_update_delete', t);
+    EXECUTE format('CREATE TRIGGER %I BEFORE UPDATE OR DELETE ON %I FOR EACH ROW EXECUTE FUNCTION payout_gates_refuse_change()', t || '_no_update_delete', t);
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON %I', t || '_no_truncate', t);
+    EXECUTE format('CREATE TRIGGER %I BEFORE TRUNCATE ON %I FOR EACH STATEMENT EXECUTE FUNCTION payout_gates_refuse_change()', t || '_no_truncate', t);
+    EXECUTE format('REVOKE UPDATE, DELETE, TRUNCATE ON %I FROM PUBLIC', t);
+  END LOOP;
+END;
+$$;
+
+-- An appeal is the frozen person's own; upheld/lifted come after an appeal or
+-- straight from whoever reviews it, and nothing follows a lift.
+CREATE OR REPLACE FUNCTION payout_freeze_events_check() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE owner_id bigint;
+BEGIN
+  SELECT builder_id INTO owner_id FROM payout_freezes WHERE id = NEW.freeze_id;
+  IF EXISTS (SELECT 1 FROM payout_freeze_events WHERE freeze_id = NEW.freeze_id AND kind = 'lifted') THEN
+    RAISE EXCEPTION 'payout freeze % is already lifted', NEW.freeze_id USING ERRCODE = 'check_violation';
+  END IF;
+  IF NEW.kind = 'appealed' AND NEW.actor_id IS DISTINCT FROM owner_id THEN
+    RAISE EXCEPTION 'only the person whose pay is frozen may appeal it' USING ERRCODE = 'check_violation';
+  END IF;
+  IF NEW.kind IN ('upheld', 'lifted') AND NEW.actor_id = owner_id THEN
+    RAISE EXCEPTION 'a person may not decide the appeal on their own freeze' USING ERRCODE = 'check_violation';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS payout_freeze_events_rules ON payout_freeze_events;
+CREATE TRIGGER payout_freeze_events_rules
+  BEFORE INSERT ON payout_freeze_events
+  FOR EACH ROW EXECUTE FUNCTION payout_freeze_events_check();
+
+COMMIT;

package/migrations/core_285_task_needs.sql

@@ -0,0 +1,74 @@
+-- core_285 — a task says what it NEEDS; a builder holds CAPABILITY grants
+-- (task 1004950, ADR 0395).
+--
+-- tasks.needs: what a task needs beyond the ordinary build loop — 'owner' (a
+-- decision, account or permission only the project owner holds) and/or 'server'
+-- (hands on the live host). Empty for most tasks. Its own column on purpose, not a
+-- value of automation_tag (that one says whether work can run unattended).
+--
+-- builders.capability_grants: the capabilities the owner has granted a builder by
+-- hand. Only 'server' today; 'owner' is the seat itself and is never stored here.
+-- Default off.
+--
+-- Both are additive with a default, so a rolled-back release that never names the
+-- columns keeps working.
+--
+-- The claimable_tasks VIEW is re-created with core_283's body byte for byte: a
+-- view freezes `t.*` at CREATE time, so without this it would not carry `needs`.
+-- The two inlined copies (CLAIMABLE_SQL in modules/lifecycle/db-tasks.js and
+-- src/bongos/optimizer.js) read `t.*` at query time and need no change for that;
+-- the viewer filter itself is per-request and lives in those queries, because a
+-- view cannot know who is asking.
+
+BEGIN;
+
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS needs text[] NOT NULL DEFAULT '{}'::text[];
+ALTER TABLE tasks DROP CONSTRAINT IF EXISTS tasks_needs_known;
+ALTER TABLE tasks ADD CONSTRAINT tasks_needs_known
+  CHECK (needs <@ ARRAY['owner', 'server']::text[]);
+-- The board's need filter asks needs @> ARRAY[$1]; most rows need nothing, so a
+-- partial GIN index keeps it small.
+CREATE INDEX IF NOT EXISTS tasks_needs_idx ON tasks USING gin (needs) WHERE cardinality(needs) > 0;
+
+ALTER TABLE builders ADD COLUMN IF NOT EXISTS capability_grants text[] NOT NULL DEFAULT '{}'::text[];
+ALTER TABLE builders DROP CONSTRAINT IF EXISTS builders_capability_grants_known;
+ALTER TABLE builders ADD CONSTRAINT builders_capability_grants_known
+  CHECK (capability_grants <@ ARRAY['server']::text[]);
+
+DROP VIEW IF EXISTS claimable_tasks;
+CREATE VIEW claimable_tasks AS
+SELECT t.*,
+       pms_calibrated_minutes(t.est_minutes, t.kind) AS est_minutes_calibrated
+  FROM tasks t
+ WHERE t.status = 'ready'
+   AND t.title NOT LIKE '\_\_smoke\_\_%' ESCAPE '\'
+   AND NOT EXISTS (
+     SELECT 1
+       FROM task_blockers tb
+       LEFT JOIN blockers b ON b.id = tb.blocker_id
+      WHERE tb.task_id = t.id
+        AND (b.id IS NULL OR b.status = 'open')
+   )
+   AND NOT EXISTS (
+     SELECT 1
+       FROM dependencies d
+      WHERE ((d.from_kind = 'task'      AND d.from_id = t.id)
+          OR (d.from_kind = 'goal'      AND d.from_id = t.goal_id)
+          OR (d.from_kind = 'criterion' AND d.from_id IN (
+                SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id)))
+        AND ((d.to_kind = 'task'      AND EXISTS (SELECT 1 FROM tasks              x WHERE x.id = d.to_id AND x.status <> 'shipped'))
+          OR (d.to_kind = 'criterion' AND EXISTS (SELECT 1 FROM done_when_criteria x WHERE x.id = d.to_id AND x.satisfied = false))
+          OR (d.to_kind = 'goal'      AND EXISTS (SELECT 1 FROM goals              x WHERE x.id = d.to_id AND x.status <> 'achieved')))
+   )
+   AND NOT EXISTS (
+     SELECT 1 FROM claims c
+       JOIN tasks t2 ON t2.id = c.task_id
+      WHERE c.released_at IS NULL
+        AND NOT (COALESCE(t2.source, '') = 'page-tweak' AND c.worktree_name IS NULL AND c.creator_session_id IS NULL)
+        AND t2.touches && t.touches
+   );
+
+COMMIT;
+
+INSERT INTO schema_migrations (version) VALUES ('core_285_task_needs')
+  ON CONFLICT (version) DO NOTHING;

package/modules/ai-studio/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._