@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/ship-session-upload.js

@@ -0,0 +1,313 @@
+// scripts/bongos/ship-session-upload.js — session digest, transcript upload + the ADR 0022 scrub/skip bookkeeping.
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 366-559 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { cliClient, loadSession } = require('./cli-lib');
+const { resolveTranscriptPath } = require('./ship-memory-sync.js');
+const { apiErrorLine } = require('./ship-io.js');
+const { uploadSessionTranscript } = require('./session-transcript-upload.js');
+const { REPO_ROOT } = require('./ship-state.js');
+
+// ---------- Session upload-on-ship (6D.1 / ADR 0027) ----------
+//
+// After a successful ship, upload a COMPACT, secret-scrubbed digest of this
+// Claude Code session (POST /api/bongos/sessions), so the BFG (a local Claude Code
+// routine — 6D.3) can later search the corpus (6D.2) and deep-dive the wasteful
+// sessions. We never upload raw transcript CONTENT — only per-turn metadata
+// (role, tool name, error flag, token usage, length) + short scrubbed snippets
+// + token aggregates. That keeps the row small and the secret surface minimal
+// (ADR 0027). BEST-EFFORT: any failure is a warning, never a ship failure —
+// exactly like syncMemoryOnShip.
+
+// The transcript-grade secret scrubber + its ADR-0022 internals now live in
+// modules/security/secret-scrub.js — extracted (task 1211 / GDS-V4 R72) so the
+// public-mirror export pipeline can reuse the ONE copy of the secret shapes
+// without requiring ship.js (whose grader / Discord / sound / session deps are
+// absent in a bare CI job). Imported + re-exported here so this file's public
+// surface and tests/scrubber_corpus.mjs are unchanged. See that module for the
+// recall-first design (a missed secret is a compromise; over-redaction is cosmetic).
+const {
+  REDACTED, scrubSecrets, shannonEntropy, looksHighEntropySecret,
+  redactHighEntropy, collectEnvSecrets,
+} = require('../../modules/security/secret-scrub');
+
+// snippetOf + buildSessionDigest moved to ./session-digest-build (task 1003217,
+// serving the de-monolith goal of task 1003203) — pure, separately tested, and
+// shared with session-digest.js. Re-exported below so this file's public surface
+// and tests/session_records.mjs are unchanged.
+const {
+  snippetOf, buildSessionDigest, mergeModelUsage, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
+} = require('./session-digest-build');
+
+// The subagent subtree walker + the grader-transcript signature live in
+// session-cost.js, which already prices that subtree for the SPEND ledger. The
+// reward reads the same tokens, so it must use the SAME two definitions or the
+// two ledgers describe different sessions (task 1003435). session-cost.js guards
+// its own entry point behind require.main, so importing it is side-effect free.
+const { listJsonlRecursive, looksLikeGraderTranscript } = require('./session-cost.js');
+
+
+// classifyUploadSkip — PURE decision for whether the session upload must skip,
+// and the clear, actionable reason why. Separated from I/O so it is unit-tested
+// (tests/ship_upload_skip.mjs). Every reason names the cause AND states the
+// consequence plainly: a skip means this ship is absent from the BFG session
+// corpus — the silent gap #608 surfaced, this (#617) makes it loud + auditable.
+// Takes already-resolved preconditions so it stays free of env + fs reads.
+function classifyUploadSkip({ sessionId, sessionIdSafe, transcriptPath, pathsTried }) {
+  const tail = 'This ship will NOT appear in the BFG session corpus.';
+  if (!sessionId) {
+    return {
+      skip: true,
+      code: 'no_session_id',
+      reason:
+        'CLAUDE_CODE_SESSION_ID is not set — this ship did not run inside an interactive Claude Code ' +
+        `session (e.g. an autonomous / merge-mode / cron context), so there is no transcript to digest. ${tail}`,
+    };
+  }
+  if (!sessionIdSafe) {
+    return {
+      skip: true,
+      code: 'unsafe_session_id',
+      reason: `CLAUDE_CODE_SESSION_ID is not a plain token, refusing to interpolate it into a filesystem path. ${tail}`,
+    };
+  }
+  if (!transcriptPath) {
+    const where = Array.isArray(pathsTried) && pathsTried.length ? ` Looked in: ${pathsTried.join(' ; ')}.` : '';
+    return {
+      skip: true,
+      code: 'transcript_not_found',
+      reason: `the session transcript .jsonl was not found for ${sessionId}.${where} ${tail}`,
+    };
+  }
+  return { skip: false };
+}
+
+// recordUploadSkip — surface a skipped/failed session upload LOUDLY (not the old
+// quiet console.log that scrolled past + vanished in non-interactive runs) AND
+// leave a durable, append-only trace so a missed capture is auditable after the
+// fact. ~/.config/otb survives worktree churn (same home as the GDS session
+// token). Best-effort: never throws into the ship path. opts.dir overrides the
+// trace dir for tests. Returns the trace file path written, or null.
+function recordUploadSkip(taskId, { code, reason }, opts = {}) {
+  console.log(`  ⚠️  session upload SKIPPED [${code}]: ${reason}`);
+  try {
+    const dir = opts.dir || require('../../src/instance-config').configHome();
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'session-upload-skips.jsonl');
+    const row = {
+      ts: new Date().toISOString(),
+      task_id: taskId != null && Number.isFinite(Number(taskId)) ? Number(taskId) : null,
+      session_id: process.env.CLAUDE_CODE_SESSION_ID || null,
+      code,
+      reason,
+    };
+    fs.appendFileSync(file, JSON.stringify(row) + '\n');
+    return file;
+  } catch (e) {
+    console.log(`  (could not persist skip trace: ${e && e.message ? e.message : e})`);
+    return null;
+  }
+}
+
+// parseJsonl — one transcript file's text into parsed entries, skipping any
+// malformed line (best-effort, exactly like the rest of this path).
+function parseJsonl(raw) {
+  const entries = [];
+  for (const line of String(raw || '').split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      entries.push(JSON.parse(t));
+    } catch (_) {
+      /* skip a malformed line — best-effort */
+    }
+  }
+  return entries;
+}
+
+// subagentModelUsage — the per-model TOKEN counts this session's ad-hoc
+// subagents burned, so the cost-plus reward (ADR 0054) can see them.
+//
+// WHY (task 1003435): Agent/Task-tool spawns persist in a sibling subtree,
+// <project-dir>/<session-id>/subagents/*.jsonl — never in the main transcript.
+// session-cost.js already prices that subtree into a `session:subagent` cost_log
+// row, so the SPEND ledger sees it; the digest read one file, so the REWARD did
+// not. That paid a builder who follows CLAUDE.md's "delegate freely" less than
+// one who did identical work in the main thread, and made the two ledgers
+// disagree about the same session.
+//
+// Grader transcripts are excluded BY SIGNATURE, not by location: a grader run
+// can nest inside a subagents/ dir, and its cost is already captured via the
+// worker envelope, so pricing it here would double-count (the ADR 0028
+// invariant). Each file goes through buildSessionDigest so the token semantics —
+// dedup by message.id, skip `<synthetic>`, fold unlabeled turns into a priceable
+// bucket — are the ONE implementation, never a second one that can drift.
+function subagentModelUsage(sessionDir) {
+  const modelUsage = {};
+  let files = 0;
+  let tokens = 0;
+  let graderSkipped = 0;
+  for (const f of listJsonlRecursive(sessionDir)) {
+    if (looksLikeGraderTranscript(f)) { graderSkipped++; continue; }
+    let digest;
+    try {
+      digest = buildSessionDigest(parseJsonl(fs.readFileSync(f, 'utf8')), { usageOnly: true });
+    } catch (_) {
+      continue; // an unreadable subagent file must never fail a ship
+    }
+    if (!(digest.totalTokens > 0)) continue;
+    files++;
+    tokens += digest.totalTokens;
+    mergeModelUsage(modelUsage, digest.metrics.model_usage);
+  }
+  return { modelUsage, files, tokens, graderSkipped };
+}
+
+// foldSubagentUsage — add the session's subagent tokens to `digest`'s
+// model_usage, IN PLACE, and record what was folded.
+//
+// model_usage ONLY, deliberately (task 1003435). model_usage is the reward's
+// input, so it must describe the whole session. `detail`, `metrics.tokens`,
+// `assistant_turns` and `total_tokens` stay the INTERACTIVE thread's record:
+// they feed the BFG corpus + the inefficiency evaluator, which reason about one
+// agent's turn-by-turn behaviour, and splicing N subagent transcripts into that
+// per-turn story would distort the very signal it exists to measure (and bloat
+// the payload). The three subagent_* counters are how a reader tells the two
+// apart instead of inferring a discrepancy from a mismatch.
+function foldSubagentUsage(digest, transcriptPath, sessionId) {
+  if (!digest || !digest.metrics || !transcriptPath || !sessionId) return digest;
+  // Path-traversal guard. The session id is interpolated into a filesystem path
+  // below, and what comes out of that path is priced into a payout — so a value
+  // carrying `../` could aim the walk at an arbitrary directory and fold
+  // fabricated token counts into the reward's input. Guarded HERE rather than at
+  // each call site: uploadSessionOnShip already screens the id before resolving
+  // the transcript, but the SessionEnd hook takes it straight off stdin, and any
+  // future caller would inherit the same hole. Same shape as the check in
+  // uploadSessionOnShip — a plain UUID-ish token, nothing else.
+  if (!/^[A-Za-z0-9_-]+$/.test(String(sessionId))) return digest;
+  const sessionDir = path.join(path.dirname(transcriptPath), sessionId);
+  const sub = subagentModelUsage(sessionDir);
+  if (sub.files === 0 && sub.graderSkipped === 0) return digest;
+  digest.metrics.model_usage = mergeModelUsage(
+    digest.metrics.model_usage || {}, sub.modelUsage
+  );
+  digest.metrics.subagent_files = sub.files;
+  digest.metrics.subagent_tokens = sub.tokens;
+  digest.metrics.subagent_grader_skipped = sub.graderSkipped;
+  return digest;
+}
+
+async function uploadSessionOnShip(taskId) {
+  try {
+    const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    // Path-traversal guard: the session id is interpolated into a filesystem
+    // path below, so reject anything that isn't a plain UUID-ish token. A
+    // hostile env value with `../` could otherwise point the read elsewhere.
+    const sessionIdSafe = !!sessionId && /^[A-Za-z0-9_-]+$/.test(sessionId);
+    // The transcript is keyed to the session's CWD (the worktree when shipping
+    // from one), so try that before REPO_ROOT (#551), then let the resolver scan
+    // every ~/.claude/projects dir — a session rooted in ANOTHER repo can drive a
+    // ship here, and before task 1002505 that missed both fast paths and silently
+    // wrote no session_record at all. resolveTranscriptPath fills pathsTried with
+    // exactly what it probed, so a transcript-not-found skip names precisely where
+    // it looked (actionable, not a bare "not found") without this file having to
+    // re-derive the encoding and drift from it.
+    const dirsTried = [process.cwd(), REPO_ROOT].filter(Boolean);
+    const pathsTried = [];
+    const transcriptPath = sessionIdSafe
+      ? resolveTranscriptPath(sessionId, dirsTried, { tried: pathsTried })
+      : null;
+
+    const decision = classifyUploadSkip({ sessionId, sessionIdSafe, transcriptPath, pathsTried });
+    if (decision.skip) {
+      recordUploadSkip(taskId, decision);
+      return null;
+    }
+    const entries = parseJsonl(fs.readFileSync(transcriptPath, 'utf8'));
+    // Dynamic secrets to scrub: every secret-shaped env VALUE (Apple/MAC_* CI
+    // creds, a baked GDS/DO token, GITHUB_TOKEN, ANTHROPIC_API_KEY, …) plus this
+    // run's live GDS session token. Defense in depth on top of the pattern +
+    // entropy scrubbers — these literals get redacted even with no known shape.
+    const extraSecrets = collectEnvSecrets();
+    // loadSession() returns null when there's no session — unlike
+    // requireSession(), it never process.exit()s, so the best-effort /
+    // non-blocking contract holds even with no valid session.
+    const s = await loadSession();
+    if (s && s.token) extraSecrets.push(s.token);
+    const digest = buildSessionDigest(entries, { extraSecrets });
+    // task 1003435: the interactive transcript is only part of what this session
+    // spent — fold the subagents subtree into model_usage so the cost-plus reward
+    // prices the same tokens the cost ledger already bills.
+    foldSubagentUsage(digest, transcriptPath, sessionId);
+    // task 1270: surface the session usage so the completion card can show
+    // Claude tokens + an estimated cost. Returned even when the POST below fails
+    // (we already have the digest) — the card is best-effort either way.
+    const usageOut = {
+      totalTokens: digest.totalTokens,
+      modelUsage: (digest.metrics && digest.metrics.model_usage) || {},
+    };
+    // drachmae_earned is computed SERVER-SIDE from the credit_log ledger
+    // (POST /sessions). ship.js no longer fetches or sends it — that removes an
+    // extra apiCall whose 401 path would process.exit(2) and break this
+    // best-effort, non-blocking contract.
+    const payload = {
+      session_id: sessionId,
+      task_ids: [Number(taskId)].filter(Number.isFinite),
+      total_tokens: digest.totalTokens,
+      duration_seconds: digest.durationSeconds,
+      started_at: digest.startedAt,
+      ended_at: digest.endedAt,
+      detail: digest.detail,
+      metrics: digest.metrics,
+      model_usage: digest.metrics.model_usage || {}, // per-model tokens → cost-plus reward (task 1005)
+    };
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.sessions.postSessions({ body: payload });
+    if (r.ok) {
+      console.log(
+        `  session upload: stored digest (${digest.metrics.assistant_turns} assistant turns, ${digest.totalTokens} tokens, ${digest.metrics.tool_error_count} tool errors, ${digest.metrics.harness_retry_count} harness retries).`
+      );
+      // ADR 0051: the full scrubbed transcript rides after the digest (the server
+      // creates it from the digest's row). Non-fatal — its outcome is a log line.
+      console.log(`  session upload: ${await uploadSessionTranscript(api, sessionId, entries, extraSecrets)}`);
+    } else if (r.status === 401) {
+      recordUploadSkip(taskId, {
+        code: 'session_invalid',
+        reason:
+          'POST /api/bongos/sessions returned 401 — the GDS session token is missing or invalid, so the ' +
+          'digest was rejected. Re-auth with /builder-reauth. This ship will NOT appear in the BFG session corpus.',
+      });
+    } else {
+      recordUploadSkip(taskId, {
+        code: `http_${r.status}`,
+        reason:
+          `POST /api/bongos/sessions returned ${r.status}${r.data && r.data.error ? ` (${apiErrorLine(r.data)})` : ''} — ` +
+          'the API rejected or could not store the digest. This ship will NOT appear in the BFG session corpus.',
+      });
+    }
+    return usageOut;
+  } catch (e) {
+    recordUploadSkip(taskId, {
+      code: 'exception',
+      reason:
+        `session upload threw before completing: ${e && e.message ? e.message : e}. ` +
+        'This ship will NOT appear in the BFG session corpus.',
+    });
+    return null;
+  }
+}
+
+module.exports = {
+  classifyUploadSkip,
+  recordUploadSkip,
+  uploadSessionOnShip,
+  foldSubagentUsage,
+};

package/scripts/bongos/ship-state.js

@@ -0,0 +1,110 @@
+// scripts/bongos/ship-state.js — the handful of process-wide facts the ship phases
+// share: two tuning constants, the repo root auto-merge runs in, the cosmetic
+// sound hook, and the instance's reward policy.
+//
+// Carved out of scripts/bongos/ship.js by task 1003204's sibling task 1003205 (goal
+// 1000079, the R03 de-monolith plan). ship.js was 4,613 lines; it is now a
+// facade over ship-*.js phase modules and this shared base.
+//
+// WHY A GETTER FOR serverReward. It is the one piece of MUTABLE module state the
+// carve had to cross a file boundary: `noteServerReward` writes it when a /me
+// lands, and two later phases (the credits print in ship-grade-steps, the
+// completion card in ship-finish) read it. A plain `module.exports.serverReward`
+// would export the value captured at require time — always null — and the ship
+// would silently claim "not paid" on a paying instance. Read it through
+// getServerReward() and the reassignment is visible to every phase, exactly as
+// it was when all of this lived in one file.
+
+'use strict';
+
+const path = require('node:path');
+const { findMainWorktree, findPrimaryWorktree } = require('../../modules/lifecycle/ship-preflight');
+
+// The instance's reward policy, as reported by the server on GET /me (ADR 0146 /
+// task 1002469). Cached module-level because the credits print + the completion
+// card are reached through several call chains and the mode is a single
+// instance-wide fact — threading it through each would be noise. Stays null
+// until a /me lands; rewardPolicy(null) then degrades to the paying default, so
+// a missed fetch under-explains rather than wrongly claiming "not paid".
+let serverReward = null;
+function noteServerReward(meRes) {
+  const r = meRes && meRes.ok && meRes.data && meRes.data.reward;
+  if (r && typeof r.mode === 'string') serverReward = r;
+  return meRes;
+}
+function getServerReward() {
+  return serverReward;
+}
+
+// V3.R18 (#209): cap the diff we feed the Opus subagent grader. Very large
+// diffs blow up prompt size for marginal grading benefit — the subagent has
+// Read access to the post-resolve working tree anyway, so it can pull the
+// full text of any file it wants to inspect closely.
+const GRADER_DIFF_CHAR_CAP = 250_000;
+const GRADER_TIMEOUT_MS = 240_000; // 4 min — Opus on a big diff with Read tool calls
+
+// TWO ROOTS, not one (task 1004584). In the core's own repo they are the same
+// folder, which is how a single REPO_ROOT served both jobs for so long. In a
+// VENDORED instance — the core installed as node_modules/@bongos/core — they are
+// not, and conflating them broke every land (mercury, core 1.21.20):
+//   CORE_ROOT     — where the core's own scripts live (the package dir). Every
+//                   core script ship spawns (smoke-gds.js, …) is addressed from
+//                   here, never by a cwd-relative path.
+//   INSTANCE_ROOT — the instance repo's checkout that auto-merge runs in: the
+//                   worktree with `main` checked out (primary OR linked). With no
+//                   `main` anywhere it is the primary checkout, so the merge leg
+//                   bails with "on X, not main" — never the package dir, which is
+//                   not a repo and turned the bail into an ENOENT on the lock.
+// Git is asked from __dirname first (unchanged for the core repo), then from the
+// process cwd (the feature worktree ship is run from) as a backstop.
+const CORE_ROOT = path.resolve(__dirname, '..', '..');
+
+// resolveRoots — the pure resolution, with git injected so the vendored layouts
+// are unit-testable. `mainCheckedOut` is false when no worktree holds `main`;
+// ship-merge names that case in its bail instead of a generic "on X".
+function resolveRoots({
+  dirname = __dirname,
+  cwd = process.cwd(),
+  findMain = findMainWorktree,
+  findPrimary = findPrimaryWorktree,
+} = {}) {
+  const core = path.resolve(dirname, '..', '..');
+  const main = findMain(dirname) || findMain(cwd);
+  if (main) return { coreRoot: core, instanceRoot: main, mainCheckedOut: true };
+  const primary = findPrimary(dirname) || findPrimary(cwd);
+  return { coreRoot: core, instanceRoot: primary || core, mainCheckedOut: false };
+}
+
+const { instanceRoot: INSTANCE_ROOT, mainCheckedOut: MAIN_CHECKED_OUT } = resolveRoots();
+// The historical name every ship phase imports. It always meant "the checkout
+// auto-merge runs in", i.e. the instance root — kept as an alias so the phases
+// that only ever wanted that do not churn.
+const REPO_ROOT = INSTANCE_ROOT;
+
+// Sound playback is COSMETIC — the ship pipeline must NEVER depend on it. Guard
+// the require so a missing/broken player (e.g. .claude/sounds/ absent on a fresh
+// clone or after a re-seed) degrades to a silent no-op instead of crashing ship.js
+// at load. A cosmetic feature can't be allowed to break shipping (task 1002199).
+const { playSound } = (() => {
+  try {
+    return require(path.resolve(__dirname, '../../.claude/sounds/play.js'));
+  } catch {
+    return { playSound: () => {} };
+  }
+})();
+
+const BEHIND_MAIN_LIMIT = 5;
+
+module.exports = {
+  noteServerReward,
+  getServerReward,
+  GRADER_DIFF_CHAR_CAP,
+  GRADER_TIMEOUT_MS,
+  REPO_ROOT,
+  CORE_ROOT,
+  INSTANCE_ROOT,
+  MAIN_CHECKED_OUT,
+  resolveRoots,
+  playSound,
+  BEHIND_MAIN_LIMIT,
+};

package/scripts/bongos/ship-surprise.js

@@ -0,0 +1,84 @@
+// scripts/bongos/ship-surprise.js — surprise / learning-capture prompt on ship (task #32).
+//
+// Carved out of scripts/bongos/ship.js by task 1003205 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original ship.js lines 132-196 unchanged. ship.js remains the facade that
+// re-exports every name and owns the CLI entry point, so the ship contract and
+// every flag are untouched, and the other scripts that import from it are too.
+
+'use strict';
+
+const readline = require('node:readline');
+const { cliClient } = require('./cli-lib');
+const { computeChangedFiles, computeGraderBaseline } = require('./ship-grade.js');
+
+// ---------- Surprise / learning-capture helpers (Task #32) ----------
+//
+// Forced "anything surprise you?" gate so we never miss a learning. The flag
+// can be supplied explicitly (--surprise "text" / --surprise none / --no-surprise),
+// prompted interactively when stdin is a TTY, or default to no-surprise with a
+// stderr warning in non-interactive contexts.
+
+function promptSurprise() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question('Anything surprise you in this work? (Enter for none, or describe): ', (answer) => {
+      rl.close();
+      resolve(answer == null ? '' : String(answer).trim());
+    });
+  });
+}
+
+function deriveTagsFromPaths(paths) {
+  // Each entry is a path/glob; take its leading folder segment as a tag.
+  // touches[] cleanup [3/8] (task 878): renamed from deriveTagsFromTouches — it
+  // now runs over the committed changed-files (reality), not the predicted
+  // touches[]. Same folder-segment logic, just a more honest input.
+  const tags = new Set();
+  for (const t of paths || []) {
+    if (!t) continue;
+    const first = String(t).split('/')[0].trim();
+    if (first && first !== '*' && first !== '**') tags.add(first);
+  }
+  if (tags.size === 0) tags.add('pms');
+  return [...tags];
+}
+
+async function captureSurpriseLearning(surpriseText, claim, taskId) {
+  const text = String(surpriseText).trim();
+  const title = text.length > 80 ? text.slice(0, 77) + '...' : text;
+  // touches[] cleanup [3/8] (task 878): tag + relate the learning by what was
+  // ACTUALLY shipped (the committed diff), not the predicted touches[]. Fall
+  // back to touches[] only when the diff is unavailable (no git / empty baseline).
+  const baseline = computeGraderBaseline(claim);
+  const changedFiles = computeChangedFiles(baseline);
+  const relatedFiles = changedFiles.length > 0 ? changedFiles : (claim.touches || []);
+  const tags = deriveTagsFromPaths(relatedFiles);
+  const r = await (await cliClient()).learnings.postLearnings({
+    body: {
+      title,
+      body_md: text,
+      tags,
+      related_files: relatedFiles,
+      source: 'ship-surprise',
+      source_ref: `task-${taskId}-claim-${claim.claim_id}`,
+      task_id: taskId,
+    },
+  });
+  if (r.status === 200 && r.data?.skipped) {
+    console.log(`📝 Learning already captured for this claim (skipped duplicate).`);
+    return true;
+  }
+  if (r.status !== 201) {
+    console.error(`  learning capture failed (${r.status}):`, r.data);
+    return false;
+  }
+  console.log(`📝 Captured learning: ${title}`);
+  return true;
+}
+
+module.exports = {
+  captureSurpriseLearning,
+  deriveTagsFromPaths,
+  promptSurprise,
+};

package/scripts/bongos/ship-visual.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// scripts/bongos/ship-visual.js — the `--visual` leg of a ship (task 1003109, goal
+// 1000072 "Human legibility").
+//
+// A shipped task can carry an optional IMAGE alongside its value summary: a
+// screenshot of the surface that changed, a before/after, a diagram — so a reader
+// who does not read code can SEE what shipped instead of reading about it (owner
+// idea 1000400). ship.js owns the ship; this file owns the picture.
+//
+// Its own file, not another 60 lines inside the 4,600-line ship.js, because the
+// size ratchet (fitness-ratchets.js, task 1003129) is shrink-only — and because
+// the two things really are separable: the ship must not care whether a visual
+// came along.
+//
+// THE ONE RULE HERE: a visual never costs a builder their ship. Bad input is
+// caught BEFORE the claim resolves (a usage error, claim intact); a failed upload
+// happens AFTER it and is a warning, never a failure.
+
+const path = require('node:path');
+const { arg } = require('./cli-lib');
+// Reading + screening is the SERVER's own lib, so a terminal refuses exactly what
+// the upload route would refuse.
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+
+// Parse + screen `--visual <file> [--visual-alt "caption"]` from an argv slice.
+// Returns null when no visual was asked for, or { buf, contentType, alt, name }.
+// EXITS (code 2) on bad input: this runs before any heavy work, so a wrong path
+// costs the builder a retyped command, not a claim. Pure enough to reason about;
+// the exit is the deliberate CLI edge.
+//
+// `regrade: true` is the `ship.js <id> --regrade` caller (task 1004665). There is
+// no claim left to resolve on that path, so the wording names what IS true there:
+// the task stays at completed, and the picture goes up before the grade runs.
+function fromArgs(args, { regrade = false } = {}) {
+  const file = arg('--visual', args) || '';
+  if (!file) return null;
+  const read = taskVisuals.readImageFile(file);
+  if (!read.ok) {
+    console.error(`${regrade ? 'Re-grade' : 'Ship'} aborted: --visual ${file} — ${read.message}`);
+    console.error(regrade
+      ? 'Fix the path (or drop --visual: a visual is always optional). Nothing was graded; the task stays at completed.'
+      : 'Fix the path (or drop --visual: a visual is always optional). No claim resolved, no credits awarded.');
+    process.exit(2);
+  }
+  const visual = { ...read, alt: arg('--visual-alt', args) || '', name: path.basename(file) };
+  const when = regrade ? 'uploaded before the re-grade runs' : 'uploaded after the claim resolves';
+  console.log(`--visual: ${visual.name} (${visual.contentType}, ${Math.round(visual.buf.length / 1024)} KB) — ${when}.`);
+  return visual;
+}
+
+// Upload the screened visual to the task. BEST-EFFORT BY DESIGN: called AFTER the
+// claim has resolved, so a failure here must never fail the ship — the work
+// landed, only the picture did not. Returns true when it stuck; prints a
+// one-line, actionable warning and returns false when it did not.
+async function upload({ taskId, visual, client, errorLine }) {
+  if (!visual) return false;
+  const r = await client.tasks.postTasksIdVisual({
+    id: taskId,
+    body: {
+      image_b64: visual.buf.toString('base64'),
+      content_type: visual.contentType,
+      ...(visual.alt ? { alt: visual.alt } : {}),
+    },
+  });
+  if (r.ok) {
+    console.log("Visual attached — it renders wherever this task's value summary does.");
+    return true;
+  }
+  console.warn(`Note: the visual did not upload (${errorLine(r.data, r.status)}). The ship is unaffected — re-attach any time with:`);
+  console.warn(`  node scripts/bongos/task.js visual ${taskId} <image> [--alt "caption"]`);
+  return false;
+}
+
+module.exports = { fromArgs, upload };