@bongos/core 1.19.357 → 1.19.359

package/modules/agents/migrations/agents_001_definitions.sql

@@ -0,0 +1,301 @@
+-- agents_001_definitions.sql — the agent registry + the fire ledger.
+--
+-- Two tables for the agents module (goal 1000038, Phase 1):
+--
+--   agents_definitions — the REGISTRY. One row per declarative agent definition,
+--     whether it came from a committed `.claude/agents/*.md` file (source='file',
+--     reconciled at deploy by agents-sync.js) or was authored in the instance
+--     against the DB (source='db'). Files-are-source: the sync upserts file rows
+--     and must never clobber a db row, so `source` is load-bearing, not a label.
+--
+--   agents_runs — the LEDGER. One row per fire: what triggered it, what the gate
+--     decided, what the spawn cost, and where the output went. Every fire is
+--     recorded — ESPECIALLY a refusal, for the same reason autonomy_runs records
+--     a no-go: a gate that silently declines is indistinguishable from a gate
+--     that never ran.
+--
+-- NAMESPACE NOTE (why `agents_definitions`, not `agent_definitions`). Module
+-- objects must carry the module key's own prefix, and this module's key is
+-- `agents` — so the wall is `agents_`, and a singular `agent_definitions` fails
+-- the fitness gate (`scripts/gds/fitness.js` Check 11) rather than being a style
+-- quibble. The plural prefix is the price of the namespace; downstream tasks
+-- (1002488 read routes, 1002489 spawn adapter, 1002490 agents-sync) read
+-- `agents_definitions` / `agents_runs`.
+--
+-- FAIL-CLOSED ENUMS. `trigger_type`, `model_tier`, `source`, `provenance` and the
+-- run's `status` are text + CHECK rather than Postgres enum TYPEs: the constraint
+-- pins today's WIRED vocabulary closed (an unwired trigger name is refused, never
+-- silently accepted — the same rule task 1002487's EVENT_CATALOG enforces in JS),
+-- and widening later is a one-line constraint change in a subsequent agents_*
+-- migration instead of an enum-type migration.
+--
+-- A DEFINITION IS NEVER ARMED BY ACCIDENT. Two invariants below are the DB half
+-- of rules the code also enforces, and they exist because "enabled" is the field
+-- that turns a piece of text into something that spends money and reads the repo:
+--   • a definition that tripped the scope wall CANNOT be enabled — the sync
+--     imports it disabled + flagged (task 1002490), and this constraint means a
+--     later stray UPDATE cannot quietly arm it;
+--   • an enabled definition MUST carry an author_rank — authority comes from the
+--     author's LIVE DB rank (ADR 0016), never from anything written in the file,
+--     so a definition with no known author has no authority to run.
+--
+-- STRUCTURE ONLY, NEVER AGENT OUTPUT. `agents_runs.output_ref` is a POINTER to
+-- where a run's output landed — never the output itself. An agent's output is
+-- model-generated text that is later rendered to whoever reads the ledger, so
+-- storing it inline would make this table a delivery path for whatever the agent
+-- read. Same rule, same reason as `security_tool_scans.findings_summary`.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is agents_-prefixed, there is no down-migration, and the filename is
+-- agents_-prefixed (ADR 0108 §5) so its stem never collides across repos.
+-- `scripts/migrate.sh` discovers + applies this only when the agents module is
+-- enabled — and the module ships `default:false` (task 1002485), so on a vanilla
+-- instance this file is correctly skipped. Idempotent: safe to re-run.
+
+BEGIN;
+
+-- ---------------------------------------------------------------------------
+-- agents_definitions — the registry
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS agents_definitions (
+  id                    bigserial PRIMARY KEY,
+
+  -- The agent key. For a file-sourced definition this is the `.claude/agents/`
+  -- filename stem, which is why the format check matches the module-key shape:
+  -- it has to be safe as a filename, a URL path segment, and a CLI argument.
+  name                  text NOT NULL,
+  title                 text,
+  -- The role/system prompt. REQUIRED — task 1002487's validator rejects a
+  -- definition with no persona, and a NOT NULL here means a row that skipped the
+  -- validator still cannot exist without one.
+  persona               text NOT NULL,
+
+  -- What fires it. 'event' consumes the wired event catalog; 'on-demand' is the
+  -- historian-exemplar shape (a builder asks, the agent answers). trigger_spec
+  -- carries the type's parameters — for 'event', at minimum {"event": "..."}.
+  trigger_type          text NOT NULL,
+  trigger_spec          jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+  -- Which subagent tier this spawns at. Resolved to a concrete model id at fire
+  -- time from the branding pack's `models` block (task 1002489) — the tier is
+  -- stored, never the model id, so an instance re-pointing its tiers moves every
+  -- agent with it instead of leaving a pinned model behind.
+  --   'default' → models.subagentDefault   'routine' → models.subagentRoutine
+  -- Deliberately NO 'main' tier: an agent is a subagent, never the main session.
+  model_tier            text NOT NULL DEFAULT 'default',
+
+  -- The declared scope wall. scope_modules names module keys the agent may work
+  -- within; scope_paths narrows further. The wall is re-evaluated SERVER-SIDE at
+  -- sync (task 1002490) — a definition scoped onto protected paths lands with
+  -- scope_violation set, which the constraint below makes un-armable.
+  scope_modules         text[] NOT NULL DEFAULT '{}',
+  scope_paths           text[] NOT NULL DEFAULT '{}',
+  scope_violation       text,
+
+  -- Where this row came from, and whether the sync owns it. 'file' rows are
+  -- rewritten from the committed definition on every deploy; 'db' rows are
+  -- instance-authored and must SURVIVE a deploy untouched (task 1002490).
+  source                text NOT NULL,
+  -- 'built-in' (ships with the core) vs 'instance' (authored by this instance).
+  -- Distinct from `source`: a built-in agent is file-sourced, but an instance can
+  -- also commit its own file. Provenance answers "whose agent is this", source
+  -- answers "who may overwrite the row".
+  provenance            text NOT NULL,
+
+  -- The author's LIVE DB rank at the moment the row was written (ADR 0016).
+  -- Never read from the definition file — a file cannot grant authority.
+  author_rank           text,
+  author_builder_id     bigint REFERENCES builders(id) ON DELETE SET NULL,
+
+  -- File provenance, for source='file'. source_sha256 is over the definition's
+  -- bytes so the sync can tell "unchanged" from "edited" without re-parsing, and
+  -- so a row can be traced back to the exact committed text that produced it.
+  source_path           text,
+  source_sha256         text,
+  last_synced_at        timestamptz,
+
+  -- Shipped != enabled, at the row level as well as the module level. A newly
+  -- synced definition lands OFF; arming it is a separate, deliberate act.
+  enabled               boolean NOT NULL DEFAULT false,
+
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+
+  -- One row per agent name. This is what makes the sync an UPSERT rather than an
+  -- append, and what stops two definitions from answering to the same name.
+  CONSTRAINT agents_definitions_name_uniq UNIQUE (name),
+  -- Filename/CLI/URL-safe, and stable: the same shape a module key must take.
+  CONSTRAINT agents_definitions_name_fmt_chk
+    CHECK (name ~ '^[a-z][a-z0-9-]*$' AND length(name) <= 64),
+  -- v1 wires exactly these two trigger types. Anything else is refused here, not
+  -- silently stored and quietly never fired.
+  CONSTRAINT agents_definitions_trigger_type_chk
+    CHECK (trigger_type IN ('event', 'on-demand')),
+  CONSTRAINT agents_definitions_trigger_spec_shape_chk
+    CHECK (jsonb_typeof(trigger_spec) = 'object'),
+  -- An event-triggered definition with no event name is a definition that can
+  -- never fire; the catalog membership check itself lives in the validator, which
+  -- can name the offending event in its error.
+  CONSTRAINT agents_definitions_event_needs_name_chk
+    CHECK (trigger_type <> 'event'
+           OR (trigger_spec ? 'event' AND length(trigger_spec ->> 'event') > 0)),
+  CONSTRAINT agents_definitions_model_tier_chk
+    CHECK (model_tier IN ('default', 'routine')),
+  CONSTRAINT agents_definitions_source_chk
+    CHECK (source IN ('file', 'db')),
+  CONSTRAINT agents_definitions_provenance_chk
+    CHECK (provenance IN ('built-in', 'instance')),
+  CONSTRAINT agents_definitions_author_rank_chk
+    CHECK (author_rank IS NULL OR author_rank IN ('xenos', 'thetes', 'metic', 'archon')),
+  -- A file-sourced row must say WHICH file, or the next sync cannot reconcile it.
+  CONSTRAINT agents_definitions_file_needs_path_chk
+    CHECK (source <> 'file' OR source_path IS NOT NULL),
+  -- The two arming invariants (see the header). A flagged definition stays
+  -- disabled; an anonymous definition has no rank to act with, so it stays off.
+  CONSTRAINT agents_definitions_flagged_not_armed_chk
+    CHECK (scope_violation IS NULL OR enabled = false),
+  CONSTRAINT agents_definitions_armed_needs_author_chk
+    CHECK (enabled = false OR author_rank IS NOT NULL),
+  -- Defense in depth with the validator's own caps: a persona is a prompt sent to
+  -- a paid model on every fire, so an unbounded one is both a cost and a blast
+  -- radius. trigger_spec is parameters, never payload.
+  CONSTRAINT agents_definitions_persona_size_chk
+    CHECK (length(persona) <= 32768),
+  CONSTRAINT agents_definitions_trigger_spec_size_chk
+    CHECK (length(trigger_spec::text) <= 8192)
+);
+
+-- "Which definitions fire on event X?" — the dispatch lookup, and the only read
+-- on the hot path. Partial: a disabled definition is never dispatched, so its
+-- rows are dead weight in this index.
+CREATE INDEX IF NOT EXISTS agents_definitions_enabled_trigger_idx
+  ON agents_definitions (trigger_type, (trigger_spec ->> 'event'))
+  WHERE enabled;
+
+-- "What does the sync own?" — agents-sync.js walks file rows to reconcile them
+-- and must never touch the db rows beside them (task 1002490).
+CREATE INDEX IF NOT EXISTS agents_definitions_source_idx
+  ON agents_definitions (source, name);
+
+-- "What tripped the scope wall?" — the review queue for flagged imports. Small
+-- by construction, so partial.
+CREATE INDEX IF NOT EXISTS agents_definitions_flagged_idx
+  ON agents_definitions (updated_at DESC)
+  WHERE scope_violation IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- agents_runs — one row per fire
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS agents_runs (
+  id                    bigserial PRIMARY KEY,
+
+  -- The definition that fired. ON DELETE SET NULL, not CASCADE: the ledger is the
+  -- record of what this instance actually spent and ran, and deleting a
+  -- definition must not erase its history. agent_name is denormalized for exactly
+  -- that case — the run stays attributable after the row it pointed at is gone.
+  definition_id         bigint REFERENCES agents_definitions(id) ON DELETE SET NULL,
+  agent_name            text NOT NULL,
+
+  -- What fired it, as a stable reference rather than prose: the event and its
+  -- subject ('task.shipped:1002486'), or the on-demand caller. Kept as text so a
+  -- trigger can reference a record type this module does not own.
+  trigger_ref           text,
+  trigger_type          text NOT NULL,
+
+  -- The gate's decision for this fire, recorded whether or not anything spawned.
+  -- Same vocabulary as autonomy_runs ('go' | 'no-go') so the two ledgers read the
+  -- same way.
+  gate_decision         text NOT NULL,
+  gate_reason           text,
+
+  -- What became of the run. 'skipped' is the terminal state of a no-go (nothing
+  -- spawned); 'pending' covers a run in flight so a crashed spawn is visible as
+  -- unfinished rather than vanishing.
+  status                text NOT NULL DEFAULT 'pending',
+  error_code            text,
+
+  -- The CONCRETE model the tier resolved to at fire time, so an old row is never
+  -- re-read as though it ran on today's tier mapping.
+  model                 text,
+  -- What the fire actually cost. Spawns route through the grade port, which bills
+  -- into the LLM cost cache (task 1002489); this column is the per-agent view of
+  -- that spend, which is what an instance's ~$/agent/month cap reads.
+  cost_usd              numeric(10, 4),
+  duration_ms           integer,
+
+  -- A POINTER to where the output landed — never the output. See the header.
+  output_ref            text,
+
+  requested_by_builder_id bigint REFERENCES builders(id) ON DELETE SET NULL,
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT agents_runs_gate_decision_chk
+    CHECK (gate_decision IN ('go', 'no-go')),
+  CONSTRAINT agents_runs_status_chk
+    CHECK (status IN ('pending', 'ok', 'error', 'skipped')),
+  CONSTRAINT agents_runs_trigger_type_chk
+    CHECK (trigger_type IN ('event', 'on-demand')),
+  -- A refusal must never be readable as a run that happened. A no-go spawned
+  -- nothing, so it is terminal-skipped and carries no output — the mirror of
+  -- security_tool_scans' verdict/completion invariant.
+  CONSTRAINT agents_runs_nogo_is_skipped_chk
+    CHECK (gate_decision = 'go' OR (status = 'skipped' AND output_ref IS NULL)),
+  -- ...and it cannot have cost anything, because nothing ran.
+  CONSTRAINT agents_runs_nogo_free_chk
+    CHECK (gate_decision = 'go' OR cost_usd IS NULL OR cost_usd = 0),
+  -- A failed run must say why. Silent failure is the state this ledger exists to
+  -- make impossible.
+  CONSTRAINT agents_runs_error_needs_code_chk
+    CHECK (status <> 'error' OR error_code IS NOT NULL),
+  CONSTRAINT agents_runs_cost_nonneg_chk
+    CHECK (cost_usd IS NULL OR cost_usd >= 0),
+  CONSTRAINT agents_runs_duration_nonneg_chk
+    CHECK (duration_ms IS NULL OR duration_ms >= 0),
+  CONSTRAINT agents_runs_output_ref_len_chk
+    CHECK (output_ref IS NULL OR length(output_ref) <= 2048)
+);
+
+-- "What has this agent done lately?" — the per-agent history, and the read behind
+-- a per-agent spend rollup.
+CREATE INDEX IF NOT EXISTS agents_runs_agent_idx
+  ON agents_runs (agent_name, created_at DESC);
+
+-- "What did this trigger set off?" — walks back from a shipped task (or any other
+-- subject) to the agents that fired on it.
+CREATE INDEX IF NOT EXISTS agents_runs_trigger_ref_idx
+  ON agents_runs (trigger_ref, created_at DESC)
+  WHERE trigger_ref IS NOT NULL;
+
+-- "What did agents cost this month?" — the spend-cap read. Partial: a no-go row
+-- contributes nothing to spend and would only dilute the scan.
+CREATE INDEX IF NOT EXISTS agents_runs_spend_idx
+  ON agents_runs (created_at DESC)
+  WHERE cost_usd IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- updated_at triggers
+-- ---------------------------------------------------------------------------
+-- Both tables ARE mutated after insert (the sync rewrites definitions; a run goes
+-- pending → ok/error and gains its cost + output_ref), so updated_at needs a real
+-- trigger — without one it silently equals created_at forever, and "when did this
+-- definition last change" becomes unanswerable. Idempotent: OR REPLACE + DROP IF
+-- EXISTS on the trigger.
+CREATE OR REPLACE FUNCTION agents_touch_updated_at() RETURNS trigger AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS agents_definitions_updated_at ON agents_definitions;
+CREATE TRIGGER agents_definitions_updated_at
+  BEFORE UPDATE ON agents_definitions
+  FOR EACH ROW EXECUTE FUNCTION agents_touch_updated_at();
+
+DROP TRIGGER IF EXISTS agents_runs_updated_at ON agents_runs;
+CREATE TRIGGER agents_runs_updated_at
+  BEFORE UPDATE ON agents_runs
+  FOR EACH ROW EXECUTE FUNCTION agents_touch_updated_at();
+
+COMMIT;

package/modules/agents/module.json

@@ -0,0 +1,11 @@
+{
+  "key": "agents",
+  "title": "Agents (declarative agent registry)",
+  "description": "Declarative agent definitions (.claude/agents/*.md) reconciled at deploy into a DB-backed registry (agents_definitions) plus a per-fire ledger (agents_runs) — BONGOS-V1 goal 1000038, Phase 1. Files-are-source: agents-sync upserts file-sourced definitions and never clobbers an instance-authored db row, and stamps author_rank from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING `grade` port (runSubagentCached), which is fixed read-only, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. default:false: shipped is not enabled, and an instance opts in per ADR 0083.",
+  "coreVersion": "^1.19.0",
+  "default": false,
+  "maintenance": { "status": "core-maintained" },
+  "contributes": { "migrations": true },
+  "provides": [],
+  "consumes": ["grade"]
+}

package/modules/agents/spawn.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// modules/agents/spawn.js — the spawn seam (task 1002489, goal 1000038 Phase 1).
+//
+// One fire = resolve the tier to a concrete model, ask the `grade` port to run the
+// subagent, and write exactly one agents_runs row saying what happened. Nothing
+// else. The gate decides WHETHER to fire; this decides HOW and records THAT.
+//
+// THREE CONSTRAINTS THAT ARE NOT NEGOTIABLE HERE, each from the goal's own
+// adversarial critique — a future reader will be tempted by all three:
+//
+//   1. CONSUME grade.runSubagentCached. Not a new `grade.runSubagent` port (the
+//      critique explicitly dropped it), and not a bespoke child_process.spawn. The
+//      port is also what bills every fire into the shared LLM cost cache, so an
+//      agent's spend lands in the same ledger as everything else instead of being
+//      invisible. A bespoke spawn would be free-looking and wrong.
+//
+//   2. REACH IT THROUGH THE DOORWAY, never `require('../grading/…')`. A
+//      module→module require is a hard fitness failure (ADR 0083), and the
+//      resolve-by-name seam is what lets an instance run `agents` with `grading`
+//      disabled — it degrades to a named refusal instead of a boot crash.
+//
+//   3. V1 AGENTS ARE READ-ONLY, and not by policy — by plumbing. grader.js's
+//      runSubagent hardcodes `--tools Read` + bypassPermissions and parametrizes
+//      only model/cwd/timeout. There is no allowlist to widen from here. A
+//      write-capable agent needs a parametrized-capability spawn path in `grading`
+//      first (a PROTECTED_GLOBS edit, Archon-gated), which is deferred to a later
+//      goal. Anything in this file that appears to grant a capability is a bug.
+//
+// THE LEDGER IS WRITTEN EVEN WHEN NOTHING RUNS. A no-go is a row: gate_decision
+// 'no-go', status 'skipped', no output, no cost — the schema enforces all three.
+// The reason is the same one behind every other loud-failure surface in this repo:
+// a refusal that leaves no trace is indistinguishable from a fire that never
+// happened, and "the agent didn't run" then has two causes nobody can tell apart.
+
+const api = require('../../src/module-api');
+
+// tier → concrete model id. The mapping is BRANDING, not a constant here: an
+// instance retunes its own tiers, and the DB constraint already limits the
+// vocabulary to these two.
+//
+// An unknown tier resolves to the DEFAULT tier, never to nothing and never to the
+// cheap one. A definition whose tier is somehow outside the vocabulary is a bug in
+// whatever wrote it; silently downgrading its model would make that bug present as
+// mysteriously poor agent output much later, which is far harder to trace than an
+// unexpected line in the cost ledger.
+function resolveModel(tier, brandingModels) {
+  const m = brandingModels || {};
+  const fallback = m.subagentDefault || m.main || null;
+  if (tier === 'routine') return m.subagentRoutine || fallback;
+  return fallback;
+}
+
+// The insert shape for one fire, decided BEFORE anything spawns. Pure, so the
+// schema's invariants can be tested without a database.
+function plannedRow({ definition = {}, trigger = {}, gate = {}, model = null, requestedByBuilderId = null } = {}) {
+  const go = gate.decision === 'go';
+  return {
+    definition_id: definition.id ?? null,
+    agent_name: definition.name || null,
+    trigger_ref: trigger.ref ?? null,
+    trigger_type: trigger.type === 'on-demand' ? 'on-demand' : 'event',
+    gate_decision: go ? 'go' : 'no-go',
+    gate_reason: gate.reason ?? null,
+    // A no-go is TERMINAL. 'pending' would leave a refusal looking like a run
+    // still in flight, and the crash-visibility argument for 'pending' only
+    // applies to something that actually started.
+    status: go ? 'pending' : 'skipped',
+    // Recorded even on a no-go: it is what the fire WOULD have cost, and the
+    // schema permits it. It is the concrete id, never the tier — an old row must
+    // never be re-read through today's tier mapping.
+    model: go ? model : null,
+    requested_by_builder_id: requestedByBuilderId ?? null,
+  };
+}
+
+// How a finished run is recorded. Pure for the same reason.
+function completedRow({ ok, errorCode = null, costUsd = null, durationMs = null, outputRef = null } = {}) {
+  if (ok) {
+    return { status: 'ok', error_code: null, cost_usd: costUsd, duration_ms: durationMs, output_ref: outputRef };
+  }
+  return {
+    status: 'error',
+    // The schema REFUSES an error row with no code, so this can never be null —
+    // 'agent_run_failed' is the honest fallback when the thrower named nothing.
+    error_code: errorCode || 'agent_run_failed',
+    cost_usd: costUsd,
+    duration_ms: durationMs,
+    // A failed run's partial output is not a result. The pointer stays null.
+    output_ref: null,
+  };
+}
+
+async function insertRun(pool, row) {
+  const cols = Object.keys(row);
+  const vals = cols.map((_, i) => `$${i + 1}`);
+  const r = await pool.query(
+    `INSERT INTO agents_runs (${cols.join(', ')}) VALUES (${vals.join(', ')}) RETURNING id`,
+    cols.map((c) => row[c]),
+  );
+  return r.rows[0].id;
+}
+
+async function finishRun(pool, id, patch) {
+  const cols = Object.keys(patch);
+  const set = cols.map((c, i) => `${c} = $${i + 2}`).join(', ');
+  await pool.query(
+    `UPDATE agents_runs SET ${set}, updated_at = now() WHERE id = $1`,
+    [id, ...cols.map((c) => patch[c])],
+  );
+}
+
+// Fire one agent. Never throws: a spawn failure is a ledger row, not an exception
+// into whatever triggered it — an event fabric must not be taken down by one
+// agent's bad day.
+async function spawnAgent({
+  definition, trigger = {}, gate = { decision: 'go' }, requestedByBuilderId = null, cache = null,
+} = {}, deps = {}) {
+  const pool = deps.pool || api.pool;
+  const now = deps.now || (() => Date.now());
+  const brandingModels = deps.brandingModels || (api.branding && api.branding().models) || {};
+  const model = resolveModel(definition && definition.model_tier, brandingModels);
+
+  const row = plannedRow({ definition, trigger, gate, model, requestedByBuilderId });
+  let runId = null;
+  try {
+    runId = await insertRun(pool, row);
+  } catch (e) {
+    // The ledger write itself failing is the one case with nowhere to record it.
+    // Say so and refuse to spawn: an unledgered fire is exactly what this table
+    // exists to prevent, and spending money we cannot account for is worse than
+    // not firing.
+    return { ok: false, ran: false, runId: null, error_code: 'ledger_write_failed', error: (e && e.message) || String(e) };
+  }
+  if (row.gate_decision !== 'go') {
+    return { ok: true, ran: false, runId, skipped: true, gate_reason: row.gate_reason || null };
+  }
+
+  // Resolved by NAME through the doorway — see constraint 2. resolveOptional so an
+  // instance running `agents` without `grading` gets a named ledger row rather than
+  // a crash at require time.
+  const grade = typeof api.resolveOptional === 'function' ? api.resolveOptional('grade', null) : null;
+  const runner = deps.runSubagentCached
+    || (grade && typeof grade.runSubagentCached === 'function' ? grade.runSubagentCached : null);
+  if (!runner) {
+    await finishRun(pool, runId, completedRow({ ok: false, errorCode: 'grade_port_unavailable' }));
+    return { ok: false, ran: false, runId, error_code: 'grade_port_unavailable' };
+  }
+
+  const started = now();
+  try {
+    const res = await runner({
+      prompt: (definition && definition.persona) || '',
+      // model/cwd/timeout are the ONLY knobs the port takes. No tools, no
+      // permissions — see constraint 3.
+      opts: { model, ...(deps.opts || {}) },
+      cache,
+    });
+    const durationMs = Math.max(0, now() - started);
+    const costUsd = (res && typeof res.cost_usd === 'number' && res.cost_usd >= 0) ? res.cost_usd : null;
+    const ok = !res || res.ok !== false;
+    const patch = completedRow({
+      ok,
+      errorCode: ok ? null : (res && res.error_code) || 'agent_run_failed',
+      costUsd,
+      durationMs,
+      outputRef: ok ? (deps.outputRef || (res && res.output_ref) || null) : null,
+    });
+    await finishRun(pool, runId, patch);
+    return { ok, ran: true, runId, model, cost_usd: costUsd, duration_ms: durationMs };
+  } catch (e) {
+    const durationMs = Math.max(0, now() - started);
+    await finishRun(pool, runId, completedRow({
+      ok: false, errorCode: (e && e.code) || 'agent_spawn_threw', durationMs,
+    })).catch(() => { /* the throw below is the report of last resort */ });
+    return { ok: false, ran: true, runId, error_code: (e && e.code) || 'agent_spawn_threw', error: (e && e.message) || String(e) };
+  }
+}
+
+module.exports = { spawnAgent, resolveModel, plannedRow, completedRow };

package/modules/builder-settings/builder-needs.js

@@ -121,7 +121,34 @@ function helpRequestsNeed(ctx) {
 
 // The registry. To add a future input the system needs from a builder, append a
 // pure (ctx) => need|null function here — every renderer picks it up for free.
-const NEEDS = [artKeyNeed, helpRequestsNeed];
+// Open task RECOMMENDATIONS waiting on this builder (task 1003173 / C03, goal
+// 1000075; criterion collab-pass-a-task). Sibling of helpRequestsNeed above, and
+// here for the same reason C01's grader round put that one here: a recommendation
+// nobody surfaces is merely stored, and the criterion's whole argument is that a
+// recommendation must be a visible, traceable judgement rather than a task
+// quietly changing hands.
+//
+// 'info', NOT a demand, and the message says so. A recommendation grants the
+// recipient nothing and obliges them to nothing — they still claim it themselves
+// if they want it, and declining costs nothing (ADR 0187 §3). Wording that
+// pressured the reader would BE the penalty the decision forbids.
+function taskRecommendationsNeed(ctx) {
+  const n = Number(ctx.openTaskRecommendations) || 0;
+  if (n <= 0) return null;
+  const subject = n === 1 ? 'A task' : `${n} tasks`;
+  const verb = n === 1 ? 'was' : 'were';
+  return {
+    id: 'task_recommendations',
+    title: n === 1 ? 'Someone recommended a task to you' : 'Tasks were recommended to you',
+    what: 'Another builder thought you should look at a task, and said why. It is a suggestion, not an assignment.',
+    state: 'action_needed',
+    severity: 'info',
+    message: `${subject} ${verb} recommended to you. Nothing has been assigned — you would still claim it yourself, and declining costs nothing.`,
+    action: { label: n === 1 ? 'See the recommendation' : 'See the recommendations', href: '/#/collab' },
+  };
+}
+
+const NEEDS = [artKeyNeed, helpRequestsNeed, taskRecommendationsNeed];
 
 // ---- founding grace (task 1002739 / direction §5.6, idea 1000701) -----------
 //
@@ -199,7 +226,7 @@ module.exports = {
   computeNeeds,
   // exported for tests / direct reuse
   artKeyNeed,
-  helpRequestsNeed,
+  helpRequestsNeed, taskRecommendationsNeed,
   foundingGraceActive,
   FOUNDING_GRACE_DAYS,
   SETTINGS_PATH,

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -715,6 +715,16 @@ function createClient(opts = {}) {
       // POST /sso/token — rank: public — POST /sso/token
       postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
     },
+    "taskRecommendations": {
+      // POST /task-recommendations — rank: any-builder — POST /task-recommendations
+      postTaskRecommendations: (args) => request("POST", "/task-recommendations", { hasBody: true }, args),
+      // PATCH /task-recommendations/{id} — rank: any-builder — PATCH /task-recommendations/:id
+      patchTaskRecommendationsId: (args) => request("PATCH", "/task-recommendations/{id}", { hasBody: true }, args),
+      // GET /task-recommendations/for-me — rank: any-builder — GET /task-recommendations/for-me
+      getTaskRecommendationsForMe: (args) => request("GET", "/task-recommendations/for-me", { hasBody: false }, args),
+      // GET /task-recommendations/mine — rank: any-builder — GET /task-recommendations/mine
+      getTaskRecommendationsMine: (args) => request("GET", "/task-recommendations/mine", { hasBody: false }, args),
+    },
     "taskVisuals": {
       // GET /task-visuals/{name} — rank: public — GET /task-visuals/:name
       getTaskVisualsName: (args) => request("GET", "/task-visuals/{name}", { hasBody: false }, args),
@@ -760,6 +770,8 @@ function createClient(opts = {}) {
       postTasksIdPublishBranch: (args) => request("POST", "/tasks/{id}/publish-branch", { hasBody: true }, args),
       // GET /tasks/{id}/publish-status — rank: any-builder — GET /tasks/:id/publish-status
       getTasksIdPublishStatus: (args) => request("GET", "/tasks/{id}/publish-status", { hasBody: false }, args),
+      // GET /tasks/{id}/recommendations — rank: any-builder — GET /tasks/:id/recommendations
+      getTasksIdRecommendations: (args) => request("GET", "/tasks/{id}/recommendations", { hasBody: false }, args),
       // POST /tasks/{id}/ship — rank: any-builder — POST /tasks/:id/ship
       postTasksIdShip: (args) => request("POST", "/tasks/{id}/ship", { hasBody: true }, args),
       // DELETE /tasks/{id}/visual — rank: any-builder — DELETE /tasks/:id/visual

package/modules/lifecycle/lifecycle.js

@@ -19,6 +19,7 @@
 const db = require('./db');
 const classifier = require('./task-classifier');
 const helpRequests = require('./help-requests');
+const taskRecommendations = require('./task-recommendations');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -39,6 +40,10 @@ module.exports = {
   // task 1003171 (C01): the count of open help requests addressed to a builder,
   // so the kernel's /me can put it in the needs ctx WITHOUT importing this module.
   openHelpRequestsFor: (...a) => helpRequests.countOpenForBuilder(...a),
+  // task 1003173 (C03): the count of open task recommendations waiting on a
+  // builder, exposed the same way and for the same reason — a recommendation
+  // nobody surfaces is merely stored.
+  openTaskRecommendationsFor: (...a) => taskRecommendations.countOpenForRecipient(...a),
   getTask: (...a) => db.getTask(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),