@bongos/core 1.19.276 → 1.19.277

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.276",
-  "core_contract": "1.19.276",
-  "source_commit": "de2f0fb76790e78b4b2c1bb4878fa88233a36c46",
+  "core_version": "1.19.277",
+  "core_contract": "1.19.277",
+  "source_commit": "35b30c3a1c2a68136a144277b48bb750148995a4",
   "source_ref": "HEAD",
-  "built_at": "2026-08-21T15:45:27.022Z",
+  "built_at": "2026-08-21T16:28:45.099Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 318,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1375,
+    "functional_verbatim": 1376,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1715,
-  "tree_sha256": "abe78982ee6e0304610e16ce97f65fc75baf045c6d210c2ab7ee65ced93b4ee7",
+  "file_count": 1716,
+  "tree_sha256": "42012dded2c6108d84ebdea4781e6cf78523e2f6c93cf2eebbc16e032b8a33b2",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -87,7 +87,7 @@
     {
       "path": ".claude/skills/builder-sequence/SKILL.md",
       "mode": "0000644",
-      "sha256": "4284bc0184dd27752202ce02974fa8909fc462f546ee3cae38fa26b4ca071f81"
+      "sha256": "838648912f0f058c58c42d943282346e2c35a90aea507b0ec136e9b0fbda50b0"
     },
     {
       "path": ".claude/skills/builder-setup/SKILL.md",
@@ -3872,7 +3872,7 @@
     {
       "path": "modules/lifecycle/ship-card.js",
       "mode": "0000644",
-      "sha256": "c2c4f75c6fec8a51befbe9e08f9fdb15b47a637654791a98d5eac6ed4a319ece"
+      "sha256": "c08ee0e89f67a2db7ea049353a12bdd6e5d97c6a7ec9039d19bdd797f66c112e"
     },
     {
       "path": "modules/lifecycle/ship-preflight.js",
@@ -4487,12 +4487,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "db42d8af206914a247ba771e7d711b22137bea42d6b4464eaa60a02bf8947c74"
+      "sha256": "296343fcb5f99b8dc4fb410e8b7c983d8c27da94bb23a64ffae6e246b87634d1"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "8918824ec6d64703f4976a6f7863aa7ac0f240af95711972715967dfe973f944"
+      "sha256": "0fa3267232afe7bfab282670e735d0cdd313d21614128c7666a10368f302ae2e"
     },
     {
       "path": "public-docs/index.html",
@@ -6137,7 +6137,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8eb348b653371b264e5c6b6efecddbdf18412e419e7dbd517b87322bdc806aae"
+      "sha256": "3068c942e43140df9169a36c39acb9b3daffb182d2a7f33e89180b3926abfd37"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -8194,6 +8194,11 @@
       "mode": "0000644",
       "sha256": "e76a3baf5fb2cdee08ffe8d80c55630b5ab4f708046f3c63c07c480926ccda31"
     },
+    {
+      "path": "tests/session_boundary_handoff.mjs",
+      "mode": "0000644",
+      "sha256": "8789eb59b2c3984500b4b2eb24d1e812e0ce6c970fc6fc940c06a6daf2613ec2"
+    },
     {
       "path": "tests/session_caps.mjs",
       "mode": "0000644",

package/.claude/skills/builder-sequence/SKILL.md

@@ -35,7 +35,20 @@ This skill owns the **loop and the halt discipline**. It does not re-derive how
 
 5. **Ship it** — `/builder-ship`. The task must reach `shipped`, not stall at `completed` or `confirmed`. A ship that does not land has not unblocked anything, so the chain cannot advance; treat it as a halt (see `ship_failed` below).
 
-6. **Go back to step 2.** The ship you just landed is what promotes the next task to `ready`.
+6. **Hand the chain off before the next link — the chain gets slower otherwise.** This is the step that makes a long run stay fast, and it is easy to skip because nothing breaks without it.
+
+   Every turn re-reads the whole conversation, so a chain worked in one window pays more per turn the further down it goes. Measured on a three-task run (2026-08-21): 11.3M cached tokens on the first task, 36.1M on the second, 78.1M on the third. The third task was not twice the work of the second — it re-processed twice the context.
+
+   A shipped task is the moment almost all of that context turns into dead weight: superseded diffs, resolved test failures, closed grade rounds. **The chain's state is already durable** — dependencies and claims live in the GDS, and `--next` re-derives the plan from them — so a fresh window loses nothing that matters.
+
+   So, when the ship card shows a **heavy session** (it says so itself: `⚠ heavy session (NNM cached) — run /session-handoff…`), or when you have landed **three or more links** in one window:
+
+   - Run `/session-handoff`, scoped to the REMAINDER of the chain — the next task id, the chain's tail, and any decision from the links already landed that the rest depends on. Do not summarise the finished work in detail; it is shipped, and the GDS is its record.
+   - Hand the user that prompt and say plainly that the chain continues in a fresh session. Then **stop.** Do not claim the next task in this window.
+
+   `/session-handoff` composes text and changes nothing, so this is safe at any point — and it cannot be automated away: a hook cannot clear a conversation, which is exactly why this step is the runner's job.
+
+7. **Otherwise, go back to step 2.** The ship you just landed is what promotes the next task to `ready`.
 
 Between passes, report progress in one line — which task landed, what is next, how much of the chain remains. The user is following a long run; they should never have to ask where it is.
 
@@ -73,6 +86,8 @@ node scripts/gds/sequence.js --check <task-id>
 
 ## What NOT to do
 
+- **Do not run a long chain to exhaustion in one window** to avoid the handoff in step 6. It feels like progress and it is the single biggest reason a long run drags: the last link can cost several times the first for identical work. Handing off is not an interruption of the chain; it is how the chain stays cheap.
+
 - **Do not skip a halted task and continue down the chain.** The owner chose stop-and-report precisely so a blocked predecessor does not silently strand its dependents.
 - **Do not batch-claim.** See "The one rule".
 - **Do not widen a task's `touches[]`** to make the chain flow. File a new task instead (`node scripts/gds/capture.js`).

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.276",
+  "version": "1.19.277",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.276",
+      "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.276",
+  "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

@@ -979,8 +979,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.276'; // 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');

package/tests/session_boundary_handoff.mjs

@@ -0,0 +1,184 @@
+// tests/session_boundary_handoff.mjs
+//
+// THE SESSION BOUNDARY — task 1003150 (goal 1000053 "Session efficiency").
+//
+// The mirror of that goal's session-START series (1002435-1002438): those
+// front-load what a session can know at open; this stops a session dragging what
+// it no longer needs at close. A shipped task is the one moment the system KNOWS
+// the work is finished, and the moment almost all of that context becomes dead
+// weight.
+//
+// TWO HALVES, both pinned here:
+//   1. ship-card.js handoffAdvice — PURE, so every branch is a real assertion with
+//      no card, no DB, no session.
+//   2. .claude/skills/builder-sequence/SKILL.md — a DOC-CONTRACT check. The skill
+//      is the only place the between-links handoff can live (a hook cannot clear a
+//      conversation), and a prose step with nothing asserting it is exactly the
+//      kind of instruction that gets tidied away in a later edit. This is the same
+//      posture as the fitness doc checks: assert the RULE is stated, not its wording.
+//
+// WHY A THRESHOLD TEST AT ALL. The failure mode here is not a crash, it is
+// wallpaper: advice that prints on every ship stops being read (the
+// deploy-divergence footer is the in-repo cautionary tale — 21 core versions of
+// identical warning that nobody acted on). So "stays silent on a normal ship" is
+// the assertion that matters most, and it is first.
+//
+// Run:  node tests/session_boundary_handoff.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const card = require('../modules/lifecycle/ship-card.js');
+const { handoffAdvice, HEAVY_SESSION_CACHED_TOKENS, buildCardModel, renderMonospaceCard, renderCardHtml } = card;
+
+const { test, summary } = makeRunner();
+
+// The three real sessions the threshold was calibrated against (2026-08-21).
+const MEASURED = { light: 11.3e6, dragging: 36.1e6, heavy: 78.1e6 };
+
+// =========================================================================
+// 1. handoffAdvice — the decision
+// =========================================================================
+
+await test('SILENT on an ordinary ship — the whole design rests on this', () => {
+  // Advice that fires every time is wallpaper. A short session must never see it.
+  for (const cached of [0, 1, 1e6, MEASURED.light, HEAVY_SESSION_CACHED_TOKENS - 1]) {
+    assert.equal(handoffAdvice({ stage: 'shipped', cachedTokens: cached }), null,
+      `${cached} cached must stay silent`);
+  }
+});
+
+await test('SPEAKS once the session is genuinely heavy', () => {
+  for (const cached of [HEAVY_SESSION_CACHED_TOKENS, MEASURED.dragging, MEASURED.heavy]) {
+    const advice = handoffAdvice({ stage: 'shipped', cachedTokens: cached });
+    assert.ok(advice, `${cached} cached should advise`);
+    assert.match(advice, /session-handoff/, 'and names the command that does something about it');
+    assert.match(advice, /fresh session/, 'and says what to do with it');
+  }
+});
+
+await test('the advice quotes the ACTUAL figure, so it is arguable', () => {
+  // A builder who disagrees can check the number rather than take it on faith.
+  assert.match(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.heavy }), /78\.1M cached/);
+  assert.match(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.dragging }), /36\.1M cached/);
+});
+
+await test('NEVER mid-task — resetting inside a claim is actively wrong', () => {
+  // Mid-task the context is what the work is standing on. Only a stage where the
+  // task has left the builder's hands may advise a reset.
+  for (const stage of ['claimed', 'review', 'built', 'completed', 'failed']) {
+    assert.equal(handoffAdvice({ stage, cachedTokens: MEASURED.heavy }), null,
+      `stage '${stage}' must not advise a reset`);
+  }
+  // ...and the two that may.
+  assert.ok(handoffAdvice({ stage: 'shipped', cachedTokens: MEASURED.heavy }));
+  assert.ok(handoffAdvice({ stage: 'confirmed', cachedTokens: MEASURED.heavy }),
+    'confirmed counts: the task is out of the builder\'s hands even though it has not landed');
+});
+
+await test('hostile or absent input is silence, never a throw', () => {
+  // This runs inside the ship card. A card that CRASHES at the end of a
+  // successful ship would turn a landed task into a scary traceback.
+  for (const args of [undefined, {}, null, { stage: 'shipped' }, { stage: 'shipped', cachedTokens: null },
+    { stage: 'shipped', cachedTokens: 'lots' }, { stage: 'shipped', cachedTokens: NaN },
+    { stage: 'shipped', cachedTokens: -1 }, { stage: null, cachedTokens: 1e9 }]) {
+    assert.doesNotThrow(() => handoffAdvice(args), `${JSON.stringify(args)} must not throw`);
+    assert.equal(handoffAdvice(args), null, `${JSON.stringify(args)} ⇒ silence`);
+  }
+  assert.equal(handoffAdvice(null), null, 'explicit null ⇒ silence, not a crash');
+});
+
+await test('the threshold sits between the session that felt fine and the one that dragged', () => {
+  // Documents the calibration as an assertion: if someone retunes the constant,
+  // this says what the number was chosen to separate.
+  assert.ok(HEAVY_SESSION_CACHED_TOKENS > MEASURED.light,
+    'the 11.3M session was fine and must stay quiet');
+  assert.ok(HEAVY_SESSION_CACHED_TOKENS < MEASURED.dragging,
+    'the 36.1M session had begun to drag and should be caught');
+});
+
+// =========================================================================
+// 2. The card — the advice has to actually reach the builder
+// =========================================================================
+
+await test('a heavy ship card carries the nudge, in BOTH renderers', () => {
+  const model = buildCardModel({
+    stage: 'shipped', taskId: 1003150, title: 'A task',
+    usage: { cachedTokens: MEASURED.heavy, newTokens: 891e3, costUsd: 49.81 },
+  });
+  assert.ok(model.handoff, 'it is on the model');
+  const mono = renderMonospaceCard(model);
+  assert.match(mono, /heavy session/, 'terminal card shows it');
+  assert.match(mono, /Next →/, 'and it sits with the Next action it qualifies');
+  // Position matters: the nudge must come AFTER Next, as a qualifier, not above it.
+  assert.ok(mono.indexOf('Next →') < mono.indexOf('heavy session'), 'below the action, not shouting over it');
+  assert.match(renderCardHtml(model), /heavy session/, 'in-feed card shows it too');
+});
+
+await test('a normal ship card is BYTE-IDENTICAL to before the nudge existed', () => {
+  // The regression that matters: every ordinary ship must look exactly as it did.
+  const usage = { cachedTokens: MEASURED.light, newTokens: 262e3, costUsd: 8.06 };
+  const model = buildCardModel({ stage: 'shipped', taskId: 1003148, title: 'A task', usage });
+  assert.equal(model.handoff, null);
+  const mono = renderMonospaceCard(model);
+  assert.doesNotMatch(mono, /heavy session/);
+  assert.doesNotMatch(mono, /session-handoff/);
+  assert.doesNotMatch(renderCardHtml(model), /heavy session/);
+  // A card with no usage data at all (old breadcrumbs) must also stay clean.
+  const bare = buildCardModel({ stage: 'shipped', taskId: 1, title: 'A task' });
+  assert.equal(bare.handoff, null);
+  assert.doesNotMatch(renderMonospaceCard(bare), /heavy session/);
+});
+
+await test('the nudge is not a Usage/Deploy ROW — it is guidance, not a task fact', () => {
+  const model = buildCardModel({
+    stage: 'shipped', taskId: 1, title: 'A task',
+    usage: { cachedTokens: MEASURED.heavy },
+  });
+  assert.equal(model.rows.some((r) => /heavy session/.test(String(r.v))), false,
+    'rows report facts about the TASK; this is advice about the SESSION');
+  assert.equal(model.facts.some((f) => /heavy session/.test(String(f.value))), false);
+});
+
+// =========================================================================
+// 3. /builder-sequence — the doc contract
+//
+// A hook cannot clear a conversation and /session-handoff is read-only, so the
+// runner skill is the ONLY place the between-links handoff can live. That makes
+// its prose load-bearing, and load-bearing prose needs a test.
+// =========================================================================
+
+const SEQ = fs.readFileSync(path.join(ROOT, '.claude/skills/builder-sequence/SKILL.md'), 'utf8');
+
+await test('the sequence runner states the between-links handoff step', () => {
+  assert.match(SEQ, /\/session-handoff/, 'it names the command');
+  assert.match(SEQ, /fresh session/i, 'and that the chain continues in a fresh one');
+  assert.match(SEQ, /heavy session/i, 'and the ship-card signal it keys off');
+});
+
+await test('...and tells the runner to STOP rather than claim the next link', () => {
+  // The failure mode: a runner that emits the prompt and then helpfully carries on
+  // in the same window has done the paperwork and none of the work.
+  assert.match(SEQ, /do not claim the next task in this window/i,
+    'the halt must be explicit — emitting a prompt and continuing anyway is the trap');
+});
+
+await test('...and says WHY, with the measurement, not just what', () => {
+  // An unexplained instruction is the first thing dropped in a later edit.
+  assert.match(SEQ, /re-?read/i, 'names the mechanism (context re-read per turn)');
+  assert.match(SEQ, /11\.3M|36\.1M|78\.1M/, 'carries the measured figures');
+  assert.match(SEQ, /durable|GDS/, 'and why a fresh window is safe: the chain state is durable');
+});
+
+await test('the runner is warned against running a chain to exhaustion', () => {
+  assert.match(SEQ, /What NOT to do/, 'the section exists');
+  assert.match(SEQ, /exhaustion|one window/i, 'and names the anti-pattern this step prevents');
+});
+
+summary('session_boundary_handoff');