@bongos/core 1.19.275 → 1.19.277

package/modules/ideas/inbox.js

@@ -19,7 +19,7 @@ const api = require('../../src/module-api');
 const { pool } = api;
 // The landing matrix (task 1003065, BV1.R01) — pure, DB-free, its own file so
 // every cell is unit-testable without a Postgres. See ./routing.js.
-const { decideLanding, routedPriority } = require('./routing');
+const { decideLanding, authorizeRoutedLanding, routedPriority } = require('./routing');
 
 const VALID_KINDS = [
   'feature',
@@ -227,6 +227,12 @@ async function captureIdea({
   goalId = null,
   filerRank = null,
   grade = null,
+  // task 1003066 (BV1.R05): OPTIONAL declared blast radius. A human reporting a
+  // bug never supplies this — demanding it as the price of reporting is the
+  // triage tax this goal removes — but a programmatic filer that DOES know
+  // (a hall filing surface, a Discord classifier) can, and when it does the
+  // goal's scope wall is applied to it verbatim. See ./routing.js.
+  touches = null,
 }, deps = {}) {
   if (!title || typeof title !== 'string') {
     throw { code: 'TITLE_REQUIRED' };
@@ -248,7 +254,7 @@ async function captureIdea({
   if (landing.route) {
     return routeIdeaToGoal({
       title, bodyMd, resolvedKind, suggestedVersion, suggestedPriority,
-      capturedBy, goalId, landing,
+      capturedBy, goalId, landing, filerRank, touches,
     }, activePool);
   }
 
@@ -289,7 +295,7 @@ async function captureIdea({
 // the same two-step ratifyCriterionProposal takes.
 async function routeIdeaToGoal({
   title, bodyMd, resolvedKind, suggestedVersion, suggestedPriority,
-  capturedBy, goalId, landing,
+  capturedBy, goalId, landing, filerRank = null, touches = null,
 }, activePool) {
   const client = await activePool.connect();
   try {
@@ -305,7 +311,7 @@ async function routeIdeaToGoal({
     //    catch-all where nobody would ever look again. A closed version cannot
     //    receive new work — the route refuses rather than filing into a tomb.
     const { rows: goalRows } = await client.query(
-      `SELECT g.id, g.status, g.version_id, v.status AS version_status
+      `SELECT g.id, g.status, g.version_id, g.scope_modules, v.status AS version_status
          FROM goals g
          JOIN versions v ON v.id = g.version_id
         WHERE g.id = $1
@@ -341,6 +347,36 @@ async function routeIdeaToGoal({
     );
     const idea = ideaRows[0];
 
+    // b2. THE BINDING GATE (task 1003066, BV1.R05). The matrix said what status;
+    //     this says whether the filing is allowed at all and what rank floor the
+    //     task is born with. Both facts come off the goal row we just LOCKED, so
+    //     a rescope cannot land between the check and the insert.
+    //
+    //     scopeIncludesProtected + goalScopeCheck both come through the published
+    //     doorway — the SAME protected roster the pre-push hook, the grader and
+    //     main-audit read (permission-path-check), so this wall cannot drift from
+    //     them. The wall only runs when touches were declared; see ./routing.js
+    //     for why an absent touches[] moves the protection to the rank floor
+    //     instead of refusing the report.
+    const declaredTouches = Array.isArray(touches) ? touches.filter(Boolean) : [];
+    const authorized = authorizeRoutedLanding({
+      landing,
+      filerRank,
+      scopeProtected: api.moduleScopeMap.scopeIncludesProtected(goal.scope_modules),
+      scopeCheck: declaredTouches.length
+        ? api.goalScopeCheck.check(goal.scope_modules, declaredTouches, filerRank)
+        : null,
+    });
+    if (!authorized.ok) {
+      throw {
+        code: 'ROUTE_NOT_AUTHORIZED',
+        goal_id: goalId,
+        gate: authorized.code,
+        reason: authorized.reason,
+        details: authorized.details ?? null,
+      };
+    }
+
     // c. The task, through the `lifecycle` PORT — never an import of
     //    modules/lifecycle/ (the one-way module rule, ADR 0083). Resolved at call
     //    time; the port registers at boot. Passing `client` enlists the INSERT in
@@ -354,12 +390,13 @@ async function routeIdeaToGoal({
     //    goal fallback, which only runs when goalId is absent and so never on
     //    this path.
     //
-    //    What is deliberately NOT passed: `requiresRank` (createTask derives the
-    //    ADR 0084/0085 floor itself from touches + sensitivity, and an explicit
-    //    value could only raise it — a filer must not be able to lower a floor),
-    //    `creditsReward` (server default — createTask auto-assigns the capped
-    //    suggestion), and `discipline` (left 'unclassified', exactly as the other
-    //    non-authored create vectors leave it).
+    //    `requiresRank` is passed ONLY as the R05 protected-scope floor computed
+    //    above — never from anything the filer said. createTask still derives its
+    //    own floor and takes the HIGHER of the two, so this can raise the bar and
+    //    never lower it. Deliberately NOT passed at all: `creditsReward` (server
+    //    default — createTask auto-assigns the capped suggestion) and
+    //    `discipline` (left 'unclassified', exactly as the other non-authored
+    //    create vectors leave it).
     const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
     if (!lifecycle || !lifecycle.createTask) {
       // A vanilla instance without the lifecycle module cannot hold tasks at all,
@@ -371,10 +408,16 @@ async function routeIdeaToGoal({
       versionId: goal.version_id,
       title,
       description: bodyMd,
-      status: landing.status,
+      status: authorized.status,
       kind: resolvedKind,
       priority: routedPriority(suggestedPriority),
       goalId: goal.id,
+      touches: declaredTouches,
+      // task 1003066 (BV1.R05): the protected-scope floor. null on an ordinary
+      // goal, so createTask derives the floor exactly as for every other vector;
+      // 'metic' when the goal reaches protected territory, and highestRank()
+      // clamps UPWARD only — this can raise a floor, never drop one.
+      ...(authorized.requiresRank ? { requiresRank: authorized.requiresRank } : {}),
       // The provenance pair the create-vector idempotency read keys on
       // (db.findTaskBySourceRef): one idea can only ever mint one routed task.
       source: 'idea-route',
@@ -406,7 +449,8 @@ async function routeIdeaToGoal({
       routing: {
         routed: true,
         reason: landing.reason,
-        status: landing.status,
+        status: authorized.status,
+        requires_rank: authorized.requiresRank,
         goal_id: goal.id,
         version_id: goal.version_id,
         task_id: task.id,
@@ -636,6 +680,66 @@ async function sourceIdeaForTask(taskId) {
   return rows[0] || null;
 }
 
+// listRoutedAwaitingNod — the NOD QUEUE (task 1003066, BV1.R05).
+//
+// A routed filing that soft-landed is a task sitting at 'backlog' in a real goal,
+// one Metic+ promote from claimable. Owner interview Q3 settled where that queue
+// lives: the EXISTING "Needs your attention" card and the EXISTING
+// POST /tasks/:id/promote — no new surface, no new permission. This is the read
+// that card was missing, and without it the soft landing is a silent drop: the
+// filing looks accepted, nothing tells anyone it needs a nod, and it sits at
+// backlog forever. Criterion C2's "one Metic+ promote away" is only true if
+// somebody can SEE it.
+//
+// Scoped by the lineage row (origin='route'), not by status alone — a task can be
+// at backlog for a dozen unrelated reasons, and this queue is specifically "a
+// person reported this and the system is waiting on a human". It reads the FILER
+// too (captured_by), because Q3's copy calls the pending state "awaiting a nod"
+// and shows kind + who filed it.
+//
+// Deliberately NOT filtered by goal membership or by the viewer: any Metic+ may
+// give the nod (Q3 rejected goal-member-first review as surface cost), so every
+// Metic+ sees one queue. The route is what gates rank; this is a plain read.
+async function listRoutedAwaitingNod({ limit = 20 } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT t.id AS task_id, t.title, t.kind, t.status, t.goal_id, t.version_id,
+            t.requires_rank, t.created_at,
+            l.idea_id, i.captured_by, b.github_login AS filed_by_login,
+            g.title AS goal_title
+       FROM ideas_task_lineage l
+       JOIN tasks t      ON t.id = l.task_id
+       JOIN idea_inbox i ON i.id = l.idea_id
+       LEFT JOIN builders b ON b.id = i.captured_by
+       LEFT JOIN goals g    ON g.id = t.goal_id
+      WHERE l.origin = 'route'
+        AND t.status = 'backlog'
+      ORDER BY t.created_at ASC
+      LIMIT $1`,
+    // The origin filter rides idx_ideas_task_lineage_route (ideas_004): a PARTIAL
+    // index on origin='route' keyed by task_id, so this walks the routed rows and
+    // probes tasks from the same structure. Without it this was a full scan of a
+    // monotonically-growing ledger on EVERY Home load for every Metic+ builder.
+    [limit]
+  );
+  return rows;
+}
+
+// The count behind the card's pill — same predicate as the list, so the number a
+// viewer is shown can never disagree with the rows they can see (the
+// countOpenIdeas precedent two functions up).
+async function countRoutedAwaitingNod(deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(
+    `SELECT COUNT(*)::int AS n
+       FROM ideas_task_lineage l
+       JOIN tasks t ON t.id = l.task_id
+      WHERE l.origin = 'route' AND t.status = 'backlog'`
+    // Same predicate ⇒ same index (ideas_004) as the list above.
+  );
+  return rows[0] ? rows[0].n : 0;
+}
+
 // -------------------------------------------------------------------------
 // Grade writes (task 1002916 / BV1.R140)
 //
@@ -959,6 +1063,9 @@ module.exports = {
   linkIdeaTask,
   countShippedTasksForIdea,
   sourceIdeaForTask,
+  // the nod queue (task 1003066, BV1.R05)
+  listRoutedAwaitingNod,
+  countRoutedAwaitingNod,
   // criterion-proposal ratification (V3.R31 / #252)
   ratifyCriterionProposal,
   parseProposalBody,

package/modules/ideas/migrations/ideas_004_lineage_route_index.sql

@@ -0,0 +1,37 @@
+-- ideas_004_lineage_route_index.sql — index the ROUTE lineage lookup
+-- (task 1003066, BV1.R05, goal 1000071 "Idea routing").
+--
+-- WHY. R05 added the nod queue: GET /inbox/awaiting-nod lists routed filings that
+-- soft-landed, filtering `ideas_task_lineage.origin = 'route'` and joining tasks
+-- for status='backlog'. ideas_002 indexes only task_id (the PK) and idea_id —
+-- nothing on `origin` — so that filter was a full scan of a table that grows
+-- monotonically with every promoted or routed idea, forever. And it is not a rare
+-- query: the hall's "Needs your attention" card issues it on EVERY Home page load
+-- for EVERY Metic+ builder, so the scan cost arrives per page view, not per triage
+-- session. (Raised by the grading panel's efficiency worker on the R05 diff.)
+--
+-- WHY PARTIAL, AND WHY KEYED ON task_id. 'route' is one of three origins and will
+-- stay the minority for as long as triage-promotion exists, so `WHERE origin =
+-- 'route'` keeps the index proportional to the routed rows rather than the whole
+-- table. Keying it on task_id means the index serves the JOIN to tasks directly
+-- from the same structure that satisfies the filter — the planner can walk the
+-- routed rows and probe tasks without touching the heap for a discarded origin.
+--
+-- WHY NOT CONCURRENTLY. Same reasoning core_222 recorded for its own index:
+-- CREATE INDEX CONCURRENTLY cannot run inside a transaction block, and this file
+-- is wrapped BEGIN/COMMIT so it lands atomically. The lock is acceptable HERE
+-- specifically because ideas_task_lineage is a low-volume human-filing ledger —
+-- one row per promoted/routed idea, arriving at human pace — so the build is
+-- milliseconds against a small table and no write path of consequence blocks.
+-- This does NOT generalise to a write-hot table.
+--
+-- Module migrations are ADDITIVE and NAMESPACED: every object here is
+-- ideas_-prefixed, no down-migration, idempotent (safe to re-run).
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS idx_ideas_task_lineage_route
+  ON ideas_task_lineage (task_id)
+  WHERE origin = 'route';
+
+COMMIT;

package/modules/ideas/routes/inbox.js

@@ -229,6 +229,15 @@ module.exports = function buildInboxRouter() {
           err.code === 'GOAL_NOT_FOUND' ? 404 :
           err.code === 'GOAL_NOT_OPEN' ? 409 :
           err.code === 'VERSION_NOT_BUILDING' ? 409 :
+          // task 1003066 (BV1.R05): the landing gate refused. Either the goal's
+          // scope reaches protected territory and the filer is below Metic
+          // (gate 'protected_scope'), or they DECLARED touches the wall rejected
+          // (gate 'out_of_scope' / 'protected_path'). 403 and not 400 — the
+          // request is well-formed, the FILER lacks the authority — matching what
+          // POST /goals/:id/tasks returns for the same wall, so one refusal has
+          // one status. `gate` names which rule bit, and the reason tells the
+          // filer the way through: file it without a goal.
+          err.code === 'ROUTE_NOT_AUTHORIZED' ? 403 :
           err.code === 'LIFECYCLE_UNAVAILABLE' ? 503 :
           500;
         return res.fail(err.code, status, { ...err });
@@ -268,6 +277,41 @@ module.exports = function buildInboxRouter() {
     }
   });
 
+  // GET /inbox/awaiting-nod — the NOD QUEUE (task 1003066, BV1.R05).
+  //
+  // REGISTERED BEFORE /inbox/:id ON PURPOSE. Express matches in registration
+  // order, so a literal segment declared after the wildcard is unreachable —
+  // this would arrive as /inbox/:id with id='awaiting-nod' and 400 on parseId.
+  //
+  // rank: metic+ via the EXISTING idea.triage permission, deliberately reused
+  // rather than minting a new one. Owner interview Q3: "any Metic+ gives the nod,
+  // in the existing Needs-your-attention slice. No new surface, no new
+  // permission." The act this queue leads to is POST /tasks/:id/promote, itself
+  // gated task.promote (Metic+), so a reader who can see this queue can act on it
+  // — the two gates agree by construction instead of by coincidence.
+  //
+  // Placed on /inbox rather than /tasks because the row is defined by its LINEAGE
+  // (origin='route'), and ideas_task_lineage is an ideas-owned table — the
+  // lifecycle module must not query it, and this module must not query it from
+  // there. "A task at backlog that a person reported" is an ideas question.
+  router.get('/inbox/awaiting-nod', api.requireBuilder, api.requirePermission('idea.triage'), async (req, res) => {
+    try {
+      const limitRaw = Number(req.query.limit);
+      const limit = Number.isInteger(limitRaw) && limitRaw > 0 && limitRaw <= 100 ? limitRaw : 20;
+      const [awaiting, count] = await Promise.all([
+        inbox.listRoutedAwaitingNod({ limit }),
+        inbox.countRoutedAwaitingNod(),
+      ]);
+      res.json({ awaiting, count });
+    } catch (err) {
+      // Through the published logger seam, not a raw console call: a module logs
+      // via the doorway, and the console_call_count ratchet holds at its floor
+      // (the task 1003148 precedent).
+      api.logger('ideas').error('GET /inbox/awaiting-nod', err && err.message);
+      res.fail('awaiting_nod_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: any-builder — single idea read for the "#NNN" deep-link resolver
   // (#1047). Mirrors GET /blockers/:id. The hall resolves /#/idea/N by id, but
   // the /inbox LIST returns only the open-first-50, so a closed/older idea ref

package/modules/ideas/routing.js

@@ -111,8 +111,119 @@ function routedPriority(suggestedPriority) {
   return p;
 }
 
+// -------------------------------------------------------------------------
+// ENFORCEMENT (task 1003066, BV1.R05) — the matrix decides, this gate BINDS.
+//
+// R01 landed decideLanding: what status a filing lands at. That is a decision
+// about the QUEUE. It is not authority, and on its own it left a real hole:
+// a routed task declares no touches[], so createTask's ADR 0084/0085 rank floor
+// derives from an empty list and comes out 'xenos' — meaning a bug routed into a
+// goal scoped to PROTECTED modules (permission/ship-grade/deploy/migration core)
+// was born claimable by a Xenos the moment any Metic+ nodded it. The matrix's
+// rank split does not close that: it governs who can make work READY, not who
+// can then take it.
+//
+// WHY THIS ISN'T goalScopeCheck.check() CALLED VERBATIM, which is what
+// POST /goals/:id/tasks does. That function DENIES on `empty_touches` — by
+// design, because an AUTHORED task whose blast radius nobody declared cannot be
+// bounded. Applied to a route it would refuse every single filing, since a person
+// reporting a bug does not know which files it lives in; demanding touches[] as
+// the price of reporting is exactly the triage tax this goal removes. So the wall
+// is applied where it has something to bite on:
+//
+//   * touches DECLARED (a programmatic filer that does know) → the real wall,
+//     verbatim, refusals and all.
+//   * touches ABSENT (every human filing) → nothing to subset-check, so the
+//     protection moves to the CLAIM side: the goal's protected scope raises the
+//     task's rank floor, and no sub-Metic can claim it however it got promoted.
+//
+// That is the same protected-roster source (permission-path-check via
+// goalScopeCheck / moduleScopeMap), just enforced at the gate that still exists
+// when touches[] doesn't.
+//
+// MEMBERSHIP IS DELIBERATELY *NOT* REQUIRED, and this is the one place the routed
+// path diverges from the authored one on purpose. authorizeGoalTaskCreate refuses
+// a non-member with not_a_member, because authoring work inside someone's
+// workspace is a member's privilege. REPORTING is not authoring: criterion C5's
+// whole promise is that "the filer never has to know the goal map", and C1's is
+// that a bug filed anywhere lands in its home. Requiring membership would mean
+// only insiders could report against a goal — the opposite of the goal. The
+// safety that membership was carrying is carried here instead by the rank floor
+// (claim side) and the matrix (ready side). Pinned by a test, so a later change
+// has to argue with the test rather than quietly reinstate the wall.
+
+// The rank a routed task must require when its goal's scope reaches protected
+// territory. Metic is the trust boundary docs/canonical-permissions.md draws for
+// the permission/ship/deploy core; createTask's highestRank() clamps UPWARD only,
+// so handing this in can raise a floor and never lower one.
+const PROTECTED_SCOPE_FLOOR = 'metic';
+
+// authorizeRoutedLanding — the FINAL, binding landing decision. PURE: it takes
+// facts the caller already resolved (the matrix verdict, whether the goal's scope
+// includes a protected module, and the scope wall's own verdict if touches were
+// declared) and returns what to stamp on the task, or a refusal.
+//
+// Ordered + fail-closed, the authorizeGoalTaskCreate precedent:
+//   not routing → scope-wall verdict → the floor.
+// Returns { ok: true, status, requiresRank } or { ok: false, code, reason, details }.
+function authorizeRoutedLanding(input) {
+  const { landing = null, scopeProtected = false, scopeCheck = null, filerRank = null } = input || {};
+
+  // Defensive: only a routing verdict may reach here. A caller that lost track of
+  // its own matrix result must not fall through into "authorized".
+  if (!landing || landing.route !== true) {
+    return { ok: false, code: 'not_routing', reason: 'authorizeRoutedLanding was asked to authorize a filing the matrix did not route.', details: null };
+  }
+
+  // The wall, when touches gave it something to check. Its verdict is passed
+  // through UNCHANGED — code, reason and details — so a refusal reads identically
+  // whether it came from a routed filing or an authored task, and there is only
+  // ever one definition of "out of scope" / "protected path".
+  if (scopeCheck && scopeCheck.ok === false) {
+    return { ok: false, code: scopeCheck.code, reason: scopeCheck.reason, details: scopeCheck.details ?? null };
+  }
+
+  // PROTECTED SCOPE + SUB-METIC FILER ⇒ REFUSE, not merely floor-stamp.
+  //
+  // This closes the one place the first cut of R05 was genuinely weaker than the
+  // authored gate rather than differently-shaped. With no touches[] there is no
+  // path for the protected-path arm to inspect, so the earlier version let a
+  // sub-Metic CREATE a task in protected territory and relied on the rank floor to
+  // stop them CLAIMING it. But POST /goals/:id/tasks refuses that author outright
+  // (protected_path), and admission refuses them the goal entirely
+  // (authorizeInvitationAccept: a sub-Metic may not even join a protected-scope
+  // goal). Letting the routed path mint a row there was the odd one out.
+  //
+  // Refusing costs the filer nothing they had before: omit goal_id and the report
+  // files to the inbox exactly as it always did, where a Metic+ triages it. What
+  // it removes is a sub-Metic's ability to put rows — however unclaimable — into
+  // the permission/ship/deploy core's queue, which is precisely what "the scope
+  // wall runs on routed tasks as on authored ones" is asking for.
+  //
+  // The rank floor below still applies to Metic+ filings in protected scope; the
+  // two are layers, not alternatives.
+  if (scopeProtected && !METIC_PLUS.has(String(filerRank || '').toLowerCase())) {
+    return {
+      ok: false,
+      code: 'protected_scope',
+      reason: `This goal's scope reaches protected territory (the permission / ship-grade / deploy / migration core), so a filer below Metic cannot route work into it. File it without a goal — it lands in the inbox and a Metic+ routes it from there.`,
+      details: { required_rank: PROTECTED_SCOPE_FLOOR, filer_rank: filerRank ?? null },
+    };
+  }
+
+  return {
+    ok: true,
+    status: landing.status,
+    // null ⇒ say nothing and let createTask derive the floor exactly as it does
+    // for every other create vector. Only the protected case speaks up.
+    requiresRank: scopeProtected ? PROTECTED_SCOPE_FLOOR : null,
+  };
+}
+
 module.exports = {
   decideLanding,
+  authorizeRoutedLanding,
+  PROTECTED_SCOPE_FLOOR,
   routedPriority,
   DEFAULT_ROUTED_PRIORITY,
   HARD_LAND_KINDS,

package/modules/lifecycle/ship-card.js

@@ -174,6 +174,59 @@ function nextActionFor(stage, { taskId, discipline, sandboxUrl } = {}) {
   return { kind: 'prompt', label: 'Continue', cmd: '/builder-start' };
 }
 
+// ---- the session boundary (task 1003150) -----------------------------------
+//
+// A shipped task is the one moment the system KNOWS a session's work is finished,
+// and it is the only moment when almost everything in that session's context
+// becomes dead weight: superseded diffs, resolved test failures, closed grade
+// rounds. Carrying it into the next task costs real time, because every turn
+// re-reads the whole conversation.
+//
+// MEASURED, session of 2026-08-21 — three tasks shipped in one window:
+//   task 1003148   262K new + 11.3M cached
+//   task 1003065   582K new + 36.1M cached
+//   task 1003066   891K new + 78.1M cached
+// The third was not twice the work of the second; it re-processed twice the
+// context. The builder's own report was that everything felt slow, and this was
+// the largest single contributor.
+//
+// WHY THIS LIVES ON THE CARD AND NOT IN A HOOK. A hook cannot clear a
+// conversation, and /session-handoff is read-only by its own spec ("composes text
+// and changes no state") — it has to be invoked. The harness does auto-compact on
+// context PRESSURE, but that fires on size rather than meaning: as likely to
+// compact mid-task, where the detail is load-bearing, as after a ship, where it is
+// not. The ship card is the only component that is already running, already at the
+// boundary, and already printing to the builder — so the nudge costs one line and
+// no new machinery.
+//
+// THE THRESHOLD is deliberately generous. The advice is only useful if it is rare:
+// a line that prints on every ship is wallpaper (the deploy-divergence footer is
+// the cautionary tale — 21 core versions of identical warning that nobody acted
+// on). 25M cached sits between the 11.3M session that felt fine and the 36.1M one
+// that had begun to drag, so a short session never sees it.
+const HEAVY_SESSION_CACHED_TOKENS = 25_000_000;
+
+// handoffAdvice — PURE. null when there is nothing to say (the overwhelming
+// majority of ships), else the one-line nudge. Exported so every branch is pinned
+// by a DB-free unit test.
+//
+// Gated on a TERMINAL stage, not merely a big number: mid-task the context is what
+// the work is standing on, and telling someone to reset in the middle of a claim is
+// actively wrong. 'shipped' and 'confirmed' are the two stages where the task is
+// out of the builder's hands.
+function handoffAdvice(input) {
+  // Normalise BEFORE destructuring. A default parameter only fires on `undefined`,
+  // so an explicit `null` — what a caller spreading an absent object hands over —
+  // would throw. This runs at the very end of a successful ship, so a crash here
+  // would turn a landed task into a traceback. (Same trap as decideLanding in
+  // modules/ideas/routing.js, task 1003065 — it caught me twice in one session.)
+  const { stage, cachedTokens } = input || {};
+  if (stage !== 'shipped' && stage !== 'confirmed') return null;
+  const cached = Number(cachedTokens);
+  if (!Number.isFinite(cached) || cached < HEAVY_SESSION_CACHED_TOKENS) return null;
+  return `heavy session (${fmtTokens(cached)} cached) — run /session-handoff, then start the next task in a fresh session`;
+}
+
 function safeBrand() {
   try {
     const b = branding();
@@ -219,6 +272,7 @@ function buildCardModel(input = {}) {
 
   const rows = [];
   const facts = [];
+  let handoff = null; // task 1003150 — the session-boundary nudge; null on all but a heavy ship
   const addRow = (k, v) => { if (v != null && v !== '') rows.push({ k, v }); };
   const addFact = (label, value, opts = {}) => { if (value != null && value !== '') facts.push({ label, value, ...opts }); };
 
@@ -319,6 +373,10 @@ function buildCardModel(input = {}) {
 
     addRow('Value', value); addRow('Changed', changed); addRow('Grade', gradeText);
     addRow('Credits', creditsText); addRow('Usage', usageText); addRow('Deploy', deployText);
+    // task 1003150: the session-boundary nudge. Not a row — it qualifies the
+    // Next-> action rather than reporting a fact about the task, so both renderers
+    // hang it off the action. Usually null.
+    handoff = handoffAdvice({ stage, cachedTokens: usage.cachedTokens });
 
     addFact('', changed);
     if (gradeText) addFact('grade', gradeText, { cls: gradeCls });
@@ -345,7 +403,7 @@ function buildCardModel(input = {}) {
     notes: input.notes || '',
     description: input.description || '',
     issues,
-    rows, facts, action,
+    rows, facts, action, handoff,
   };
 }
 
@@ -403,6 +461,9 @@ function renderMonospaceCard(model) {
   for (const r of m.rows) kv(r.k, r.v);
   out.push(bar);
   kv('Next →', m.action.kind === 'link' ? (m.action.url || '(sandbox)') : m.action.cmd);
+  // task 1003150: aligned under the Next action it qualifies, not as a row — this
+  // is guidance about the SESSION, not a fact about the task.
+  if (m.handoff) for (const l of wrap(`⚠ ${m.handoff}`, MONO_W - 9)) out.push('  ' + ' '.repeat(9) + l);
   return out.join('\n');
 }
 
@@ -459,6 +520,12 @@ function renderCardHtml(model) {
     actionHtml = `<button class="cc-link cc-next" onclick="sendPrompt('${cmd}')">${esc(m.action.label)} ↗</button>`;
   }
 
+  // task 1003150: the boundary nudge rides beside the action, muted — it is
+  // advice, not an alarm, and it must not outshout the Next button.
+  const handoffHtml = m.handoff
+    ? `<span class="cc-sep">·</span><span style="color:var(--color-text-tertiary);">${esc(m.handoff)}</span>`
+    : '';
+
   const factsSr = m.facts.map((f) => `${f.label ? f.label + ' ' : ''}${f.value}`).join('. ');
   const srText = `${m.cfg.headline(m.taskId)}. ${factsSr}. A collapsible summary expands on click.`;
 
@@ -490,7 +557,7 @@ function renderCardHtml(model) {
     ${actionHtml}
   </div>
   <div style="display:flex;align-items:baseline;gap:10px;">
-    <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.7;flex:1;min-width:0;">${facts}</div>
+    <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.7;flex:1;min-width:0;">${facts}${handoffHtml}</div>
     <button class="cc-link cc-sum" aria-label="Toggle task summary" onclick="var s=this.parentElement.nextElementSibling;var o=getComputedStyle(s).display==='none';s.style.display=o?'block':'none';this.querySelector('i').style.transform=o?'rotate(90deg)':'';">Summary <span class="cc-chev"><i class="ti ti-chevron-right" aria-hidden="true"></i></span></button>
   </div>
   <div style="display:none;margin-top:0.6rem;padding-top:0.55rem;border-top:0.5px solid var(--color-border-tertiary);font-size:13px;line-height:1.6;">${summaryBody}</div>
@@ -538,5 +605,7 @@ module.exports = {
   STAGES, TONE, stageFor, buildCardModel, renderMonospaceCard, renderCardHtml, emitCard,
   // exported for unit tests:
   fmtTokens, fmtUsd, fmtInt, fmtMins, nextActionFor, esc, wrap, changedText,
+  // task 1003150 — the session-boundary nudge, pure so every branch is pinned.
+  handoffAdvice, HEAVY_SESSION_CACHED_TOKENS,
   PIPELINE, FORMS, trailSteps,
 };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.275",
+  "version": "1.19.277",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.275",
+      "version": "1.19.277",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.275",
+  "version": "1.19.277",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -977,8 +977,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.273 with no explicit bump. run 32490024209. (task 1002620)
 //   1.19.275 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.274 with no explicit bump. run 32492414871. (task 1002620)
+//   1.19.276 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.275 with no explicit bump. run 32499257959. (task 1002620)
+//   1.19.277 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.276 with no explicit bump. run 32503053532. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.275'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.277'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');