@bongos/core 1.19.819 → 1.19.820

package/modules/sessions/db.js

@@ -28,6 +28,11 @@ const { pool } = api;
 // file, not the doorway: it touches no kernel surface, and keeping the numbers
 // in one place is what stops the route and the poller disagreeing.
 const uploadHealth = require('./upload-health');
+// The PURE session-type verdict (task 1003975). Same reasoning as upload-health:
+// the classifier touches no kernel surface, and keeping the vocabulary in one
+// file is what stops the upload path, the search filter and the backfill from
+// disagreeing about what a type is.
+const sessionType = require('./session-type');
 // `seams` is the doorway's kernel-mediated seam surface (resolveOptional/resolve).
 // upsertSessionRecordWithReward resolves the economy `reward` port through it —
 // the module↔module seam, never a sibling-module require (BV1.R77 / ADR 0093 §2).
@@ -64,11 +69,19 @@ async function upsertSessionRecordTx(executor, {
   const ids = Array.isArray(taskIds)
     ? taskIds.map((n) => Number(n)).filter(Number.isFinite)
     : [];
+  // task 1003975 — the session's shape, derived here and NEVER taken from the
+  // body. Computed on the same digest the row stores, so the column can always be
+  // re-derived from what is beside it; an upload that re-posts a session (the ship
+  // path uploads once per shipped task) re-classifies it from the newest digest,
+  // which is the same rule detail/metrics already follow on conflict.
+  const type = sessionType.classifySession({ detail, metrics });
   const { rows } = await executor.query(
     `INSERT INTO session_records
        (session_id, builder_id, task_ids, drachmae_earned, total_tokens,
-        duration_seconds, started_at, ended_at, detail, metrics, model_usage)
-     VALUES ($1, $2, $3::bigint[], $4, $5, $6, $7, $8, $9::jsonb, $10::jsonb, $11::jsonb)
+        duration_seconds, started_at, ended_at, detail, metrics, model_usage,
+        session_type)
+     VALUES ($1, $2, $3::bigint[], $4, $5, $6, $7, $8, $9::jsonb, $10::jsonb, $11::jsonb,
+             $12)
      ON CONFLICT (session_id) DO UPDATE SET
        task_ids = (
          SELECT COALESCE(array_agg(DISTINCT e ORDER BY e), '{}')
@@ -84,12 +97,13 @@ async function upsertSessionRecordTx(executor, {
        detail           = EXCLUDED.detail,
        metrics          = EXCLUDED.metrics,
        model_usage      = EXCLUDED.model_usage,
+       session_type     = EXCLUDED.session_type,
        uploaded_at      = now()
      -- Ownership guard: a row can only ever be updated by its own builder, so a
      -- builder who guesses another's session_id cannot overwrite their record.
      WHERE session_records.builder_id = EXCLUDED.builder_id
      RETURNING id, session_id, builder_id, task_ids, drachmae_earned,
-               total_tokens, duration_seconds, uploaded_at`,
+               total_tokens, duration_seconds, session_type, uploaded_at`,
     [
       sessionId,
       builderId,
@@ -102,6 +116,7 @@ async function upsertSessionRecordTx(executor, {
       JSON.stringify(detail ?? []),
       JSON.stringify(metrics ?? {}),
       JSON.stringify(modelUsage ?? {}),
+      type,
     ]
   );
   return rows[0] || null; // null only on the ownership-guard no-op (foreign session_id)
@@ -521,9 +536,14 @@ function clampSessionOffset(n) {
 
 // sessionFilterClause — the shared parameterized WHERE used by BOTH searchSessions
 // (the page) and summarizeSessions (the corpus-wide tally), so the two can never
-// drift out of sync. Every filter is a bound parameter ($1..$7); nothing from the
+// drift out of sync. Every filter is a bound parameter ($1..$8); nothing from the
 // caller is interpolated. Returns { clause, params } where clause is the body of
 // a WHERE (no leading 'WHERE'). Pure.
+//
+// task 1003975 added $8 (sessionType). It goes through the SHARED clause like
+// every other facet precisely so the Tally cannot disagree with the rows: a
+// filter applied to the page query alone would show "4,595 sessions" above a
+// table holding 57.
 function sessionFilterClause(f = {}) {
   const clause = `($1::text   IS NULL OR b.rank = $1)
         AND ($2::int    IS NULL OR b.karma >= $2)
@@ -531,7 +551,8 @@ function sessionFilterClause(f = {}) {
         AND ($4::bigint IS NULL OR sr.total_tokens >= $4)
         AND ($5::int    IS NULL OR COALESCE((sr.metrics->>'tool_error_count')::int, 0) >= $5)
         AND ($6::int    IS NULL OR sr.duration_seconds >= $6)
-        AND ($7::int    IS NULL OR (now() - b.created_at) <= ($7 * interval '1 day'))`;
+        AND ($7::int    IS NULL OR (now() - b.created_at) <= ($7 * interval '1 day'))
+        AND ($8::text   IS NULL OR sr.session_type = $8)`;
   const params = [
     f.rank ?? null,
     f.minKarma ?? null,
@@ -540,6 +561,7 @@ function sessionFilterClause(f = {}) {
     f.minToolErrors ?? null,
     f.minDurationSec ?? null,
     f.maxTenureDays ?? null,
+    f.sessionType ?? null,
   ];
   return { clause, params };
 }
@@ -559,6 +581,10 @@ const SESSION_SUMMARY_COLS = `
   -- the ledger does not have to re-derive the thresholds in the browser.
   (sr.metrics->'accessibility'->>'score')::numeric      AS accessibility_score,
   (sr.metrics->'accessibility'->>'band')                AS accessibility_band,
+  -- task 1003975: the session's derived shape. NOT coalesced to a type — a NULL
+  -- here means the row predates the classifier and the backfill has not reached
+  -- it, which the ledger renders as a dash rather than claiming a verdict.
+  sr.session_type,
   sr.uploaded_at`;
 
 // searchSessions — cross-builder search over the corpus, filtered by session
@@ -574,7 +600,7 @@ async function searchSessions(filters = {}) {
   const { clause, params } = sessionFilterClause(f);
   // limit/offset are clamped integers, never raw input — safe to interpolate;
   // keeping them out of the param list keeps the $-indices aligned with the
-  // shared clause (which owns $1..$7).
+  // shared clause (which owns $1..$8).
   const { rows } = await pool.query(
     `SELECT ${SESSION_SUMMARY_COLS}
        FROM session_records sr
@@ -772,6 +798,62 @@ async function sessionUploadHealth({ days, windowHours, sampleLimit } = {}) {
   };
 }
 
+// -------------------------------------------------------------------------
+// Session-type backfill (task 1003975)
+// -------------------------------------------------------------------------
+//
+// The two halves the CLI needs, and NOTHING else. They are here rather than in
+// the script because every other query in this domain is, and because the write
+// half has to be narrow in a way a script cannot enforce for itself: it SETs one
+// column on one id. It cannot touch task_ids, drachmae_earned or any reward
+// column even by accident, which is the lesson the windowed attribution sweep
+// paid for (see the warning in this module's CLAUDE.md) — a backfill that also
+// moves money is the wrong shape whatever its intent.
+
+// unclassifiedSessions — a page of rows still missing a type, oldest first, with
+// the two jsonb fields the classifier reads. Ordered by id so a resumed run walks
+// the corpus deterministically rather than re-drawing a shuffled window.
+async function unclassifiedSessions(limit = 500) {
+  const { rows } = await pool.query(
+    `SELECT id, detail, metrics
+       FROM session_records
+      WHERE session_type IS NULL
+      ORDER BY id ASC
+      LIMIT $1`,
+    [Math.max(1, Math.min(5000, Math.trunc(Number(limit) || 500)))]
+  );
+  return rows;
+}
+
+// setSessionType — write one row's verdict. Refuses anything outside the closed
+// set, so a caller that invents a type gets an error instead of a column full of
+// values no filter will ever match.
+async function setSessionType(id, type) {
+  if (!sessionType.isSessionType(type)) {
+    const err = new Error(`unknown session_type '${type}'`);
+    err.code = 'BAD_SESSION_TYPE';
+    throw err;
+  }
+  const { rowCount } = await pool.query(
+    'UPDATE session_records SET session_type = $2 WHERE id = $1',
+    [Number(id), type]
+  );
+  return rowCount;
+}
+
+// sessionTypeCounts — the corpus tally per type, including the NULL backlog. The
+// backfill prints it as its own progress, and it answers "what is this corpus
+// actually made of" in one query.
+async function sessionTypeCounts() {
+  const { rows } = await pool.query(
+    `SELECT COALESCE(session_type, 'unclassified') AS type, COUNT(*)::int AS n
+       FROM session_records
+      GROUP BY 1
+      ORDER BY 2 DESC`
+  );
+  return rows;
+}
+
 module.exports = {
   // write side (6D.1)
   upsertSessionRecord,
@@ -793,4 +875,8 @@ module.exports = {
   resolveSessionOrder,
   clampSessionLimit,
   clampSessionOffset,
+  // session type (task 1003975) — the backfill's two halves + the corpus tally
+  unclassifiedSessions,
+  setSessionType,
+  sessionTypeCounts,
 };

package/modules/sessions/routes/sessions.js

@@ -46,6 +46,10 @@ const { scoreAccessibility } = require('../accessibility');
 // `days=99999` for a read that ran at 365 is a record of something that did not
 // happen (task 1003865).
 const uploadHealth = require('../upload-health');
+// The closed set of session types + its guard (task 1003975). The route validates
+// the ?session_type filter against the SAME list the classifier writes, so a type
+// can never be filterable on one surface and unwritable on the other.
+const sessionType = require('../session-type');
 const seams = api; // resolveOptional('reward' | 'builder-settings') — kernel-mediated ports
 const { validateOrRespond, parseId } = api;
 
@@ -321,6 +325,13 @@ module.exports = function buildSessionsRouter() {
     if (rank && !VALID_RANKS.has(rank)) {
       return res.fail('bad_rank', 400, { valid: Array.from(VALID_RANKS) });
     }
+    // task 1003975 — validated against the classifier's own closed set, so a
+    // typo is a named 400 rather than a query that quietly matches nothing and
+    // reads as "the corpus holds no exploration sessions".
+    const sessionTypeFilter = q.session_type ? String(q.session_type) : null;
+    if (sessionTypeFilter && !sessionType.isSessionType(sessionTypeFilter)) {
+      return res.fail('bad_session_type', 400, { valid: sessionType.SESSION_TYPES });
+    }
     const numOrNull = (v) => {
       if (v == null) return null;
       const n = Number(v);
@@ -334,6 +345,7 @@ module.exports = function buildSessionsRouter() {
       minToolErrors: numOrNull(q.min_tool_errors),
       minDurationSec: numOrNull(q.min_duration_seconds),
       maxTenureDays: numOrNull(q.max_tenure_days),
+      sessionType: sessionTypeFilter,
       order: q.order ? String(q.order) : 'recent',
       limit: q.limit,
       offset: q.offset,
@@ -345,7 +357,7 @@ module.exports = function buildSessionsRouter() {
       await recordSessionRead(req, {
         route: '/api/bongos/sessions/search',
         targetBuilderId: null,
-        target: `search rank=${rank || '*'} order=${filters.order} offset=${db.clampSessionOffset(filters.offset)}`,
+        target: `search rank=${rank || '*'} type=${sessionTypeFilter || '*'} order=${filters.order} offset=${db.clampSessionOffset(filters.offset)}`,
       });
       // Page + corpus-wide tally in parallel. `totals` reflects EVERY session
       // matching the filter (not just this page), so the Ledger's stats stay
@@ -361,6 +373,11 @@ module.exports = function buildSessionsRouter() {
         totals,
         limit: db.clampSessionLimit(filters.limit),
         offset: db.clampSessionOffset(filters.offset),
+        // task 1003975 — the vocabulary travels WITH the results so the ledger
+        // builds its filter from what this route actually accepts. A page that
+        // hardcoded the list would keep offering a type the server had dropped,
+        // and would hide one it had added.
+        session_types: sessionType.SESSION_TYPES,
       });
     } catch (err) {
       console.error('[gds] GET /sessions/search', err);

package/modules/sessions/session-type.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// modules/sessions/session-type.js — WHAT A SESSION WAS, FOR A LEDGER THAT ONLY
+// KNEW WHETHER IT SHIPPED A TASK (task 1003975, from idea 1001033).
+//
+// THE PROBLEM THIS ANSWERS. The session ledger shows a task chip per row, and a
+// dash when there is none. 54% of the corpus has an empty `task_ids` (the figure
+// upload-health.js already records), so more than half the ledger reads as a
+// column of dashes — every one of them some real session, none of them
+// distinguishable from the next. The owner's words: user behaviour is hard to
+// decipher at present.
+//
+// WHAT THE CORPUS ACTUALLY CONTAINS, MEASURED — and it is not what the ledger's
+// shape implies. 247 sessions were sampled through GET /sessions/:id across
+// offsets 0…3600 of the recent ordering (2026-09-17, corpus of 4595):
+//
+//   automated    179  (72%)   build  57  (23%)   exploration  11  (4%)   conversation  0
+//
+// Two findings drove the design:
+//
+//   * MOST ROWS ARE NOT HUMAN BEHAVIOUR AT ALL. 188 of 247 sessions received one
+//     prompt or fewer — grader workers, panel subagents and hook one-shots, each
+//     a separate `claude -p` process with its own session id and its own
+//     SessionEnd upload. Reading the ledger as a record of what PEOPLE did is
+//     what makes it undecipherable.
+//   * `task_ids` DOES NOT MEAN "the session that built the task". 82 of those 179
+//     automated rows carry a task id, because a grader worker runs inside a ship
+//     and inherits it. So the task chip cannot be the primary signal, and this
+//     classifier deliberately never reads `task_ids`.
+//
+// THE SIGNAL THAT SEPARATES A PERSON FROM A SCRIPT is the prompt count:
+// `user_turns - tool_result_count`. Every tool result is recorded as a user turn,
+// so subtracting them leaves the turns a human (or an orchestrating skill)
+// actually sent. Measured over the sample it is strikingly bimodal — 184 rows sit
+// at exactly 1 and 4 at 0, against a long tail from 2 to 78 — which is why the
+// boundary is `<= 1` and not a tuned percentile. It is the difference between
+// "invoked once" and "steered", not a threshold anyone chose.
+//
+// PURE, AND DELIBERATELY SO. No DB, no clock, no network — the same shape as
+// upload-health.js's verdict. It takes the digest a session already uploads and
+// returns one string. Nothing here calls an LLM: a paid inference per session
+// would cost more than the corpus is worth, and a deterministic read of stored
+// data is reproducible when someone disputes a label.
+
+// The CLOSED set of types. Anything outside it is a bug, not a new category —
+// the column, the route filter and the ledger's control all validate against
+// this one list, so a type cannot exist on one surface and not another.
+const SESSION_TYPES = ['build', 'automated', 'exploration', 'conversation', 'unknown'];
+
+// The tools that CHANGE something. Kept as a named set rather than inlined
+// because it is the one judgement in the file that will need revisiting when the
+// harness grows a new editor — a new write tool missing from here silently
+// demotes real build sessions to exploration, which is the failure mode to watch.
+// Bash is NOT here on purpose: it reads at least as often as it writes (1314 of
+// the sample's 1761 tool calls), so counting it as a write would make almost
+// every session a build and the label would stop meaning anything.
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+// The prompt count above which a session counts as steered rather than invoked.
+// Measured, not chosen — see the header.
+const ONE_SHOT_PROMPT_MAX = 1;
+
+// humanPrompts — the turns a person actually sent: user turns minus the tool
+// results that are also recorded as user turns. Clamped at 0, because a digest
+// whose counters disagree (an old row, a truncated transcript) must not produce a
+// negative that then reads as a one-shot.
+function humanPrompts(metrics) {
+  const m = metrics || {};
+  const userTurns = Number(m.user_turns) || 0;
+  const toolResults = Number(m.tool_result_count) || 0;
+  return Math.max(0, userTurns - toolResults);
+}
+
+// usedWriteTool — did any turn call a tool that changes a file? Reads `detail`,
+// which is the only place tool NAMES survive (metrics counts calls, not what they
+// were). Tolerant of every shape an old row might hold — a missing detail, a
+// turn with no tools, a tools entry that is not a string — because this runs over
+// a corpus written by several versions of the digest builder.
+function usedWriteTool(detail) {
+  if (!Array.isArray(detail)) return false;
+  for (const turn of detail) {
+    if (!turn || !Array.isArray(turn.tools)) continue;
+    for (const name of turn.tools) {
+      if (WRITE_TOOLS.has(String(name))) return true;
+    }
+  }
+  return false;
+}
+
+// classifySession — the verdict: one of SESSION_TYPES, from a session's own
+// digest. Takes `{ detail, metrics }` — exactly what the upload body carries and
+// what a stored row holds — so the upload path and the backfill classify through
+// the same call and cannot drift.
+//
+// The order of the tests is the meaning:
+//   1. It wrote something          → `build`, whatever else it did.
+//   2. It was invoked, not steered → `automated` (the grader worker, the hook).
+//   3. It used tools               → `exploration` (someone reading the codebase).
+//   4. It used none                → `conversation` (someone asking, not building).
+// A digest with no usable counters at all returns `unknown` rather than guessing:
+// an empty transcript is not evidence of a quiet conversation.
+function classifySession({ detail, metrics } = {}) {
+  const m = metrics && typeof metrics === 'object' ? metrics : null;
+  const hasDetail = Array.isArray(detail) && detail.length > 0;
+  if (!m && !hasDetail) return 'unknown';
+  if (usedWriteTool(detail)) return 'build';
+  const turns = Number(m && m.assistant_turns) || 0;
+  const toolUse = Number(m && m.tool_use_count) || 0;
+  // Nothing in the digest describes a session: no turns, no tools, no prompts.
+  // Older rows predating these counters land here, and so does a row whose
+  // upload was truncated. Saying `unknown` keeps them out of every real bucket
+  // instead of inflating `conversation` with rows nobody can account for.
+  if (!turns && !toolUse && !hasDetail) return 'unknown';
+  if (humanPrompts(m) <= ONE_SHOT_PROMPT_MAX) return 'automated';
+  return toolUse > 0 ? 'exploration' : 'conversation';
+}
+
+// isSessionType — the guard the route filter uses, so an unknown ?session_type
+// is a clean 400 rather than a query that silently matches nothing.
+function isSessionType(value) {
+  return typeof value === 'string' && SESSION_TYPES.includes(value);
+}
+
+module.exports = {
+  SESSION_TYPES,
+  WRITE_TOOLS,
+  ONE_SHOT_PROMPT_MAX,
+  humanPrompts,
+  usedWriteTool,
+  classifySession,
+  isSessionType,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.819",
+  "version": "1.19.820",
   "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/scripts/gds/backfill-session-types.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/backfill-session-types.js — classify the sessions that predate the
+// classifier (task 1003975, from idea 1001033).
+//
+// WHAT THIS IS, and what it is NOT. It writes ONE column, `session_records.session_type`,
+// and only where that column is NULL. It moves no money, books no reward, touches
+// no `task_ids` and creates no attribution. That separation is deliberate and it
+// is the lesson this module already paid for once: the attribution sweep had to be
+// windowed because it ran on the same tick as a payout and would have minted a mass
+// retroactive payment nobody authorised (see the warning in modules/sessions/CLAUDE.md).
+// A sweep that both labels and pays is the wrong shape whatever its intent, so this
+// one cannot pay even in principle — db.setSessionType writes that column alone.
+//
+// WHY IT IS NEEDED. The upload path classifies every session from now on, but the
+// corpus is ~4,600 rows old and none of them carry a verdict. Without this pass the
+// ledger's new filter would only ever see today's sessions, which is exactly the
+// half of the corpus nobody needs help reading.
+//
+// SAFETY. DRY-RUN BY DEFAULT: with no flags it classifies in memory, prints the
+// distribution it WOULD write, and writes nothing. `--apply` performs the UPDATEs.
+// Idempotent by construction: the verdict is a pure function of the row's own
+// stored digest, so a re-run lands on the same answer, and a row that already has
+// a type is never revisited (the query selects `WHERE session_type IS NULL`).
+// `--limit N` bounds one pass so the first apply can be small and checked.
+//
+// Run:  node scripts/gds/backfill-session-types.js [--limit N]
+//       node scripts/gds/backfill-session-types.js --apply
+
+const { classifySession, SESSION_TYPES } = require('../../modules/sessions/session-type');
+const db = require('../../modules/sessions/db');
+const { arg, hasFlag } = require('./cli-lib');
+
+const BATCH = 500;
+
+async function main() {
+  const apply = hasFlag('--apply');
+  const limitArg = Number(arg('--limit'));
+  const cap = Number.isFinite(limitArg) && limitArg > 0 ? Math.trunc(limitArg) : Infinity;
+
+  const tally = Object.fromEntries(SESSION_TYPES.map((t) => [t, 0]));
+  let scanned = 0;
+  let written = 0;
+
+  // Paged rather than one big SELECT: `detail` is a jsonb per row and the corpus
+  // is the largest table this module owns, so pulling it whole would hold the
+  // entire transcript corpus in memory at once for no gain.
+  for (;;) {
+    const room = Math.min(BATCH, cap - scanned);
+    if (room <= 0) break;
+    const rows = await db.unclassifiedSessions(room);
+    if (rows.length === 0) break;
+    for (const row of rows) {
+      const type = classifySession({ detail: row.detail, metrics: row.metrics });
+      tally[type] = (tally[type] || 0) + 1;
+      scanned++;
+      if (apply) written += await db.setSessionType(row.id, type);
+    }
+    // A dry run never writes, so the same unclassified page comes back forever.
+    // One page is enough to show the shape; say so rather than looping.
+    if (!apply) break;
+  }
+
+  console.log(`\nsession-type backfill — ${apply ? 'APPLIED' : 'DRY RUN (no writes)'}`);
+  console.log(`  rows classified     ${scanned}`);
+  if (apply) console.log(`  rows written        ${written}`);
+  console.log(`  distribution:`);
+  for (const t of SESSION_TYPES) {
+    const n = tally[t] || 0;
+    const pct = scanned ? ` (${Math.round((n / scanned) * 100)}%)` : '';
+    console.log(`    ${t.padEnd(14)} ${String(n).padStart(6)}${pct}`);
+  }
+
+  if (apply) {
+    console.log(`\n  corpus now:`);
+    for (const r of await db.sessionTypeCounts()) {
+      console.log(`    ${String(r.type).padEnd(14)} ${String(r.n).padStart(6)}`);
+    }
+  } else if (scanned > 0) {
+    console.log(`\n  dry run reads one page of ${BATCH}; re-run with --apply to write and walk the whole corpus.`);
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => { console.error(err); process.exit(1); });

package/scripts/gds/fitness.js

@@ -200,9 +200,19 @@ function checkGeneratedArtifactsFresh() {
   } catch {
     violations.push('docs/api/openapi.json + docs/api-reference.md + docs/routes-permissions.md are STALE (or the spec is not valid OpenAPI 3.1) — run `node scripts/gds/gen-api-docs.js` and commit (task 1918).');
   }
+  try {
+    // task 1003556: the copy registry's rows carry LINE NUMBERS, so editing any scanned
+    // UI file stales it. It was covered only by ship-check's OPTIONAL step, which a
+    // builder has to remember to run — so the first signal was CI failing on the PR's
+    // MERGE ref, where the shift is hardest to attribute. Gated here so a local fitness
+    // run says so first.
+    execFileSync(process.execPath, [path.join(__dirname, 'copy-inventory.js'), '--check'], { cwd: REPO_ROOT, stdio: 'pipe' });
+  } catch {
+    violations.push('docs/copy-registry.json + docs/copy-inventory.md are STALE — every row carries a line number, so editing any scanned UI file shifts them. Run `node scripts/gds/copy-inventory.js` and commit (task 1003556).');
+  }
   // NB the role packs' responsibility blocks are generated too, but their freshness
   // is asserted by role-pack-guard.js — one check owns "the packs are correct".
-  return { name: 'generated artifacts fresh', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: 'Tracked generated content matches source: nested CLAUDE.md symbol blocks (code) + the CLAUDE.md §13 snippet (sessions) via --check-block, plus the CLAUDE.md §2 interaction-posture block (the knob defaults), docs/file-map.md skills/scheduled-tasks sections and docs/api/openapi.json + api-reference.md (API). The gitignored docs/repo-map.md + docs/session-log-index.md are deploy-regenerated (ADR 0110), not gated here.' };
+  return { name: 'generated artifacts fresh', ok: violations.length === 0, hardFail: violations.length > 0, violations, warnings: [], note: 'Tracked generated content matches source: nested CLAUDE.md symbol blocks (code) + the CLAUDE.md §13 snippet (sessions) via --check-block, plus the CLAUDE.md §2 interaction-posture block (the knob defaults), docs/file-map.md skills/scheduled-tasks sections, docs/api/openapi.json + api-reference.md (API) and docs/copy-registry.json + copy-inventory.md (the reader-facing copy, task 1003556). The gitignored docs/repo-map.md + docs/session-log-index.md are deploy-regenerated (ADR 0110), not gated here.' };
 }
 
 // ---- deterministic cron routine boundary (System 4 / ADR 0078) -------------
@@ -1223,6 +1233,7 @@ const CHECKS = [
   // crashes later, so a start-up refusal would trade an outage risk for a cosmetic
   // one (ADR 0289). Rationale + the seam→consumer table live in that file.
   require('./seam-wiring-guard.js').checkSeamWiring,
+  require('./home-isolation-guard.js').checkHomeIsolation, // Check 34 — task 1003763: a test that sets HOME for a child without USERPROFILE isolates NOTHING on win32, so it silently stops testing what its comment says. Three tasks fixed this one site at a time. Rationale in that file.
   require('./adr-namespace.js').checkAdrNumbering, require('./exec-path-guard.js').checkExecPathsStatic, // Check 32 — task 1003371 / B50: what the server EXECUTES, out of whose tree — the blind spot all three 2026-08-29 CRITICALs shared. Rationale + reviewed exemptions live in that file. Sharing Check 31's line (the 19c/19d + 23/24 precedent above): fitness.js is AT the 1,500 ratchet and a new check cannot afford a line until task 1003825 buys it back.
 ];
 

package/scripts/gds/home-isolation-guard.js

@@ -0,0 +1,126 @@
+'use strict';
+
+// scripts/gds/home-isolation-guard.js — setting HOME for a child process isolates
+// nothing on Windows (task 1003763).
+//
+// THE DEFECT, three times now. os.homedir() reads USERPROFILE on win32 and never
+// consults HOME, so `env: { ...process.env, HOME: tmp }` leaves the child looking at
+// the DEVELOPER'S REAL home — and therefore their real CLI session.
+//
+//   tests/cli_sessions.mjs  (task 1003760) — DESTROYED the developer's live session.
+//   tests/cli_surface.mjs   (task 1003941) — guidance printers took the authenticated
+//                                            branch, so the test failed for a false
+//                                            reason on any signed-in Windows box.
+//   tests/cli_package.mjs   (task 1003763) — an unauthenticated-path assertion could
+//                                            pass because the machine was signed in.
+//
+// The last two are the dangerous shape: a test that isolates nothing does not
+// announce itself, it just quietly stops testing what its comment says it tests.
+//
+// WHY A GUARD AND NOT THREE FIXES. Three sites, three separate tasks, each found by
+// accident. tests/memory_pull.mjs, tests/redteam_patrol.mjs and
+// tests/setup_device_flow_fallback.mjs already do it correctly, so the convention
+// exists and is simply easy to miss — which is the definition of something CI should
+// hold rather than a reviewer.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const TESTS_DIR = path.join(REPO_ROOT, 'tests');
+
+// WHAT COUNTS AS A SPAWN ENV. Only a literal that SPREADS process.env and assigns
+// HOME — that is the shape every real defect had. Two narrowings, both learned by
+// getting this wrong on the first run against the tree:
+//
+//   - COMMENTS ARE STRIPPED. All three fixed files now explain the bug by QUOTING
+//     the broken line, so a raw text scan reports the very files that fixed it.
+//   - A HELPER'S CALL SITE IS NOT A SPAWN ENV. tests/setup_smoke.mjs passes
+//     `{ HOME: fakeHome }` to its own runSetup(), which adds USERPROFILE itself.
+//     Requiring `...process.env` in the same literal distinguishes 'building a
+//     child's environment' from 'passing an option to a function', and flags the
+//     helper rather than each of its callers — which is where the fix belongs.
+const HOME_ASSIGN_RE = /(^|[{,\s])HOME\s*:/;
+const USERPROFILE_RE = /(^|[{,\s])USERPROFILE\s*:/;
+const PROCESS_ENV_RE = /\.\.\.process\.env/;
+
+// Strip line and block comments so prose ABOUT the bug is not read as the bug.
+// Errs toward keeping text (a guard should fail loud, not quiet): only the two
+// unambiguous comment forms are removed.
+function stripComments(src) {
+  return String(src || '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+// Files where HOME is the SUBJECT rather than an isolation mechanism, named in task
+// 1003763. An allowlist entry is a claim that the file means something else by HOME,
+// so each one says which.
+const ALLOW = new Map([
+  ['scrubber_corpus.mjs', "HOME:'/root' is literal corpus DATA — a string the scrubber is asked to redact, not an env handed to a child"],
+  ['lib_sh_resolution.mjs', 'exercises POSIX shell HOME resolution; HOME is the thing under test, and a win32 variable would change the subject'],
+  ['home_isolation_guard.mjs', "this guard's OWN tests carry the broken shape as fixture strings — it must not report its own corpus, the same way category-advisory-guard.js had to stop matching its own filename"],
+]);
+
+// PURE — the lines that build a child env with HOME and no USERPROFILE. Exported so
+// the matching is testable without the tree: a scanner whose pattern silently stops
+// matching reports a clean repo, which is the failure mode this whole file is about.
+function offendingLines(src) {
+  const lines = stripComments(src).split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!HOME_ASSIGN_RE.test(lines[i])) continue;
+    // A literal can wrap: read a small window either side for its companions.
+    const window = lines.slice(Math.max(0, i - 4), i + 5).join('\n');
+    if (!PROCESS_ENV_RE.test(window)) continue;   // an option object, not a child env
+    if (USERPROFILE_RE.test(window)) continue;    // already isolated properly
+    out.push({ line: i + 1, text: lines[i].trim() });
+  }
+  return out;
+}
+function checkHomeIsolation() {
+  const name = 'a child env that sets HOME also sets USERPROFILE (task 1003763)';
+  let names = [];
+  try {
+    names = fs.readdirSync(TESTS_DIR).filter((f) => f.endsWith('.mjs'));
+  } catch (e) {
+    return { name, ok: true, hardFail: false, violations: [], warnings: [`tests/ unreadable: ${e.message}`], note: 'skipped.' };
+  }
+  // The scan must not pass by finding nothing.
+  if (names.length === 0) {
+    return {
+      name, ok: false, hardFail: true,
+      violations: ['no tests/*.mjs found at all — that is a broken scan, not a clean one'],
+      warnings: [], note: 'the scan produced an empty file set.',
+    };
+  }
+
+  const violations = [];
+  let scanned = 0;
+  let sitesSeen = 0;
+  for (const n of names) {
+    const src = fs.readFileSync(path.join(TESTS_DIR, n), 'utf8');
+    scanned += 1;
+    const hits = offendingLines(src);
+    if (HOME_ASSIGN_RE.test(stripComments(src)) && PROCESS_ENV_RE.test(stripComments(src))) sitesSeen += 1;
+    if (ALLOW.has(n)) continue;
+    for (const h of hits) {
+      violations.push(`tests/${n}:${h.line} sets HOME for a child without USERPROFILE — \`${h.text.slice(0, 90)}\`. `
+        + 'On Windows os.homedir() reads USERPROFILE and ignores HOME, so this isolates NOTHING: the child sees the '
+        + 'developer\'s real home and real session, and an unauthenticated-path assertion can pass because the machine '
+        + 'happens to be signed in. Set USERPROFILE (and HOMEDRIVE/HOMEPATH) to the same directory.');
+    }
+  }
+
+  return {
+    name,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} test file(s) scanned, ${sitesSeen} of them build a child env with HOME; ${ALLOW.size} allowlisted where HOME is the subject rather than the isolation. `
+      + 'Three separate tasks (1003760, 1003941, 1003763) fixed this one site at a time before it was worth a check.',
+  };
+}
+
+module.exports = { checkHomeIsolation, offendingLines, stripComments, ALLOW, HOME_ASSIGN_RE, USERPROFILE_RE, PROCESS_ENV_RE };

package/scripts/gds/ship-merge.js

@@ -27,7 +27,7 @@ const {
 } = require('./ship-land.js');
 const { runSmoke } = require('./ship-grade.js');
 const { dbOnlyIgnoredNotice } = require('./ship-honesty.js');
-const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
+const { currentBranch, mainWorktreeBusy, regenerateApiClient, regenerateApiDocs, regenerateCopyInventory, regenerateDiagrams, regenerateFileMap, regenerateRepoMap, regenerateSessionIndex } = require('./ship-regen.js');
 const { REPO_ROOT } = require('./ship-state.js');
 
 // zeroCommitVerdict — dbOnly is deliberately consulted ONLY at zero commits
@@ -119,6 +119,10 @@ async function mergeLocally(taskId, valueSummary, { dbOnly = false } = {}) {
   regenerateSessionIndex();
   // Refresh the generated file-map sections (skills + scheduled-tasks) on the same beat (ADR 0066 / task 1276).
   regenerateFileMap();
+  // Refresh the copy registry + inventory on the same beat (task 1003556). Its rows
+  // carry line numbers, so ANY edit to a scanned UI file staled it — and nothing in
+  // the ship path regenerated it, so the PR was born stale and CI said so.
+  regenerateCopyInventory();
   // Refresh the generated OpenAPI spec + API reference from the shipped route tree (task 1918).
   regenerateApiDocs();
   // ...then the typed client FROM that spec (+ the devbox vendored copy) on the same beat (task 2051).