@bongos/core 1.19.818 → 1.19.820

package/modules/hall-ui/public/sessions.js

@@ -42,6 +42,39 @@
 
   const shortSid = (sid) => String(sid || '').slice(0, 8) || '—';
 
+  // task 1003975 — what each session type is CALLED, and what it means on hover.
+  // The keys come from the server (`session_types` on the search response); this
+  // map only supplies the words. A type the server adds before this map learns it
+  // still renders — as its raw key — because a missing label must never make a
+  // real row look blank.
+  const KIND_LABEL = {
+    build: 'Build',
+    automated: 'Automated run',
+    exploration: 'Exploring',
+    conversation: 'Conversation',
+    unknown: 'Unclear',
+  };
+  const KIND_TITLE = {
+    build: 'Files were written or edited in this session.',
+    automated: 'One prompt and no edits — a grader, a subagent or a scripted run, not someone working.',
+    exploration: 'Someone steered it through several prompts, reading and running things without editing.',
+    conversation: 'Several prompts and no tools at all — a question or a discussion.',
+    unknown: 'The recorded transcript does not say — usually a session that predates this measure.',
+  };
+  const kindLabel = (t) => KIND_LABEL[t] || String(t);
+
+  // Emits the whole <td>. A row with no type yet (the backfill has not reached it)
+  // is a dash, NOT 'Unclear' — "not classified" and "classified as undecidable"
+  // are different facts and the ledger should not merge them.
+  function kindCell(s) {
+    const t = s.session_type;
+    if (!t) {
+      return '<td class="ledger-kind" title="Not yet classified.">—</td>';
+    }
+    const title = KIND_TITLE[t] || '';
+    return `<td class="ledger-kind" title="${escapeHtml(title)}">${escapeHtml(kindLabel(t))}</td>`;
+  }
+
   // task 1002516 — the transcript accessibility dimension (criterion
   // `accessibility-fluency-profile`, clause 4). Headed "Plain speech" rather than
   // "Accessibility" because this page already lives under a shell whose only
@@ -105,8 +138,12 @@
   function renderTable(sessions) {
     const body = $('#sessions-body');
     if (!sessions.length) {
-      body.innerHTML =
-        '<tr><td colspan="10" class="ledger__empty">No sessions recorded yet. They land here as builders ship and end sessions.</td></tr>';
+      // The empty line has to answer the question the reader is actually asking,
+      // and with a filter on that question is "did I filter everything away?",
+      // not "why has nobody ever worked here".
+      body.innerHTML = state.sessionType
+        ? `<tr><td colspan="11" class="ledger__empty">No ${escapeHtml(kindLabel(state.sessionType).toLowerCase())} sessions recorded. Choose another kind to widen the ledger.</td></tr>`
+        : '<tr><td colspan="11" class="ledger__empty">No sessions recorded yet. They land here as builders ship and end sessions.</td></tr>';
       return;
     }
     body.innerHTML = sessions
@@ -126,6 +163,7 @@
           `<td>${whoHtml}` +
           (s.rank ? ` <span class="ledger-rank">${escapeHtml(rankLabel(s.rank))}</span>` : '') +
           '</td>' +
+          kindCell(s) +
           `<td>${tasks}</td>` +
           `<td class="ledger__num">${fmtInt(s.drachmae_earned)}</td>` +
           `<td class="ledger__num">${fmtInt(s.assistant_turns)}</td>` +
@@ -186,7 +224,24 @@
   // pager first and calls back second, so a failed fetch has to put it back to these —
   // otherwise the bar goes on claiming a page whose rows never arrived. Keeping both
   // (not just the page) means a failed per-page change rolls back cleanly too.
-  const state = { total: 0, shown: 0, page: 1, perPage: pager?.perPage ?? 0 };
+  // `sessionType` is the live filter (null = every kind). It sits in the same
+  // roll-back state as page/perPage because a failed fetch has to put ALL THREE
+  // back — a bar claiming page 1 of "Exploring" whose rows never arrived is the
+  // same lie whichever control moved last.
+  const state = { total: 0, shown: 0, page: 1, perPage: pager?.perPage ?? 0, sessionType: null };
+  // Remembered per viewer, like the pager's per-page choice: a monitoring page is
+  // returned to, and re-picking the same lens every visit is a tax. Wrapped
+  // because storage throws in a private window, where the page must still work.
+  const TYPE_KEY = 'otb.sessions.kind';
+  function readStoredType() {
+    try { return window.localStorage.getItem(TYPE_KEY) || null; } catch { return null; }
+  }
+  function storeType(t) {
+    try {
+      if (t) window.localStorage.setItem(TYPE_KEY, t);
+      else window.localStorage.removeItem(TYPE_KEY);
+    } catch { /* no-op: the filter still works for this visit */ }
+  }
   let loading = false;
   // Two clicks can be in flight at once; only the newest may paint (the profile
   // activity-log idiom, task 1003281).
@@ -201,6 +256,11 @@
     const clamped = kit.renderServerPage(pager, state.total, state.shown);
     const perPage = $(`#${PAGER_PREFIX}-per-page`);
     if (perPage) perPage.disabled = loading;
+    // The kind filter is disabled for the same reason the pager is: a second
+    // change mid-fetch would put a third request in flight behind two that are
+    // already racing to paint.
+    const kind = $('#session-type-filter');
+    if (kind) kind.disabled = loading;
     if (loading) {
       for (const id of ['prev', 'next']) {
         const el = $(`#${PAGER_PREFIX}-${id}`);
@@ -210,6 +270,52 @@
     return clamped;
   }
 
+  // ---- the kind filter -----------------------------------------------------
+
+  // Fill the control from the vocabulary the SERVER sent, once. Re-stamping it on
+  // every paint would reset the open dropdown under a reader's cursor, so it
+  // returns early when the options already match what arrived.
+  let typeOptionsFrom = null;
+  function syncTypeOptions(types) {
+    const el = $('#session-type-filter');
+    if (!el || !Array.isArray(types) || types.length === 0) return;
+    const key = types.join(',');
+    if (typeOptionsFrom === key) return;
+    typeOptionsFrom = key;
+    el.innerHTML =
+      '<option value="">All kinds</option>' +
+      types.map((t) => `<option value="${escapeHtml(t)}">${escapeHtml(kindLabel(t))}</option>`).join('');
+    // A remembered kind is only honoured once the server has confirmed it is
+    // still a kind — otherwise the control would show a value no query accepts.
+    if (state.sessionType && !types.includes(state.sessionType)) {
+      setTypeFilter(null, { reload: false });
+    }
+    el.value = state.sessionType || '';
+  }
+
+  // Move the filter. `reload:false` is the internal correction (a stale stored
+  // value being dropped) — it must not fire a fetch from inside one.
+  function setTypeFilter(type, { reload = true } = {}) {
+    state.sessionType = type || null;
+    storeType(state.sessionType);
+    const el = $('#session-type-filter');
+    if (el) el.value = state.sessionType || '';
+    if (!reload) return;
+    // A narrower corpus makes the open page meaningless — page 7 of Build is not
+    // page 7 of everything — so every change starts at the first page.
+    pager.page = 1;
+    state.page = 1;
+    fetchPage().then((ok) => {
+      if (ok) window.scrollTo({ top: 0, behavior: 'smooth' });
+    });
+  }
+
+  function wireTypeFilter() {
+    const el = $('#session-type-filter');
+    if (!el) return;
+    el.addEventListener('change', () => setTypeFilter(el.value || null));
+  }
+
   // Paint one page. Returns true when the pager clamped — the corpus shrank under an
   // open page, so the caller must re-ask rather than leave a range that lies.
   function showData(data) {
@@ -222,9 +328,15 @@
     $('#sessions-scroll').hidden = false;
     renderStats(totals);
     renderTable(sessions);
+    syncTypeOptions(data.session_types);
     const clamped = renderPager();
+    // With a kind chosen, the count IS the filtered count (the tally shares the
+    // filter clause with the page query), so the line has to say which — a
+    // headline reading "57 sessions" under a control set to Build would otherwise
+    // look like the whole corpus had shrunk.
+    const scope = state.sessionType ? ` ${kindLabel(state.sessionType).toLowerCase()}` : '';
     $('#ledger-sub').textContent =
-      `${fmtInt(totals.total)} session${num(totals.total) === 1 ? '' : 's'} across ${fmtInt(totals.builders)} builder${num(totals.builders) === 1 ? '' : 's'}.`;
+      `${fmtInt(totals.total)}${scope} session${num(totals.total) === 1 ? '' : 's'} across ${fmtInt(totals.builders)} builder${num(totals.builders) === 1 ? '' : 's'}.`;
     $('#ledger-foot').textContent =
       'Most recent first. Each load of this page is itself recorded in the audit log.';
     return clamped;
@@ -238,14 +350,17 @@
   // then calls back — so a failure restores `state.page`/`state.perPage`, the last
   // values that painted. That roll-back is what the old hand-roll did with
   // `state.offset`, and it is the one piece of it worth carrying over.
-  async function fetchPage({ reclamps = 0 } = {}) {
+  async function fetchPage({ reclamps = 0, droppedFilter = false } = {}) {
     const seq = ++inFlight;
     loading = true;
     renderPager();
     try {
+      const typeParam = state.sessionType
+        ? `&session_type=${encodeURIComponent(state.sessionType)}`
+        : '';
       const res = await api.request(
         'GET',
-        `${API}/sessions/search?order=recent&limit=${pager.perPage}&offset=${kit.pageOffset(pager)}`
+        `${API}/sessions/search?order=recent&limit=${pager.perPage}&offset=${kit.pageOffset(pager)}${typeParam}`
       );
       // A newer click already went out; painting this answer would show a page nobody
       // is on any more.
@@ -255,6 +370,15 @@
         showSealed('You do not have access to the session log.');
         return false;
       }
+      // A remembered kind the server no longer accepts (a type retired between
+      // visits) comes back as a named 400. Drop the stale lens and re-ask once,
+      // rather than showing a load failure the reader cannot act on — their only
+      // clue would be a control still displaying the dead value.
+      if (res.status === 400 && state.sessionType && !droppedFilter) {
+        setTypeFilter(null, { reload: false });
+        loading = false;
+        return fetchPage({ reclamps, droppedFilter: true });
+      }
       if (!res.ok) throw new Error(`search → ${res.status}`);
       const clamped = showData(res.data);
       // The corpus shrank under this page (sessions pruned between loads):
@@ -329,6 +453,11 @@
 
     // 2. Fetch the first page (Archon-gated + audited server-side).
     mountPager();
+    // The remembered kind is applied BEFORE the first fetch so a returning reader
+    // lands on their own lens rather than seeing the whole corpus paint and then
+    // snap to a narrower one.
+    state.sessionType = readStoredType();
+    wireTypeFilter();
     await fetchPage();
   }
 

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