@bongos/core 1.19.319 → 1.19.321

package/scripts/gds/ship-resume.js

@@ -0,0 +1,151 @@
+// scripts/gds/ship-resume.js — the claim-less resume + re-grade eligibility decisions and resumeMerge.
+//
+// Carved out of scripts/gds/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 3353-3477 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 { cliClient } = require('./cli-lib');
+const { preflight } = require('./ship-preflight-steps.js');
+const { playShipBell } = require('./ship-io.js');
+const { strandNextStep } = require('./ship-land.js');
+const { mergeAndDeploy, onboardingNudgeBestEffort, postShipSync, printCompletionCard } = require('./ship-finish.js');
+
+// task 1003221 — `pushMode` ('server'|'local') so the 'confirmed' answer names a
+// command the caller can ACTUALLY run: it hardcoded `/merge-mode`, which needs gh +
+// a main checkout (SEC #863) no server-mediated builder has. Defers to
+// strandNextStep; defaults to 'local' so an old caller is unchanged.
+function evaluateRegradeEligibility({ task, lastClaim, builder, pushMode = 'local' }) {
+  if (!task) {
+    return { ok: false, code: 'task_not_found', reason: 'Task not found.' };
+  }
+  const status = task.status;
+  if (status !== 'completed') {
+    let reason;
+    if (status === 'confirmed') {
+      reason = `Task #${task.id} is already 'confirmed' — its grade passed. Nothing to re-grade. `
+        + `If it hasn't shipped: ${strandNextStep(task.id, pushMode)}`;
+    } else if (status === 'shipped') {
+      reason = `Task #${task.id} is already 'shipped'. Done.`;
+    } else if (status === 'active' || status === 'ready') {
+      reason = `Task #${task.id} is '${status}', not 'completed'. Claim it and run a normal /builder-ship — --regrade only re-grades a ship that landed at 'completed'.`;
+    } else {
+      reason = `Task #${task.id} is '${status}'. --regrade only applies to a task stuck at 'completed' after a failed grade.`;
+    }
+    return { ok: false, code: 'not_completed', reason, status };
+  }
+  const isArchon = !!builder && builder.rank === 'archon';
+  const owns = !!lastClaim && !!builder && Number(lastClaim.builder_id) === Number(builder.id);
+  if (!isArchon && !owns) {
+    const holder = lastClaim?.github_login ? `@${lastClaim.github_login}` : 'another builder';
+    return {
+      ok: false,
+      code: 'not_owner',
+      reason: `Task #${task.id} was last claimed by ${holder}. Only that builder or an Archon can re-grade it.`,
+    };
+  }
+  return {
+    ok: true,
+    code: 'eligible',
+    via: owns ? 'owner' : 'archon',
+    reason: owns ? 'you last held this claim' : 'archon re-grade',
+  };
+}
+
+// task 941 (V4.R03 — idempotent ship re-drive): decide what a CLAIM-LESS
+// `ship.js <id>` re-run should do. The claim is consumed at the resolve step, so
+// a ship that fails AFTER it (grade fail → stuck `completed`; merge/deploy fail →
+// stuck `confirmed`, the task-1027 nightmare) left a re-run dead-ending at "you
+// don't have an active claim" — the builder had to know the `--regrade` flag (and
+// for `confirmed` there was NO path at all). This makes a PLAIN re-run resume
+// from the stalled leg: `completed` → re-grade, `confirmed` → re-merge/deploy.
+// Pure + exported so the truth table is unit-tested with no git/network. Returns
+// { action, via?, reason? } where action ∈
+//   resume-grade | resume-merge | done | claim-first | error
+function holderLabel(lastClaim) {
+  return lastClaim?.github_login ? `@${lastClaim.github_login}` : 'another builder';
+}
+function evaluateResumeAction({ task, lastClaim, builder }) {
+  if (!task) return { action: 'error', reason: 'Task not found.' };
+  const status = task.status;
+  if (status === 'shipped') {
+    return { action: 'done', reason: `Task #${task.id} is already 'shipped'. Nothing to do.` };
+  }
+  const isArchon = !!builder && builder.rank === 'archon';
+  const owns = !!lastClaim && !!builder && Number(lastClaim.builder_id) === Number(builder.id);
+  if (status === 'completed' || status === 'confirmed') {
+    const leg = status === 'completed' ? 'grade' : 'merge';
+    if (!isArchon && !owns) {
+      return {
+        action: 'error',
+        reason: `Task #${task.id} is at '${status}' but was last claimed by ${holderLabel(lastClaim)}. ` +
+          `Only that builder or an Archon can resume the ${leg}.`,
+      };
+    }
+    return {
+      action: status === 'completed' ? 'resume-grade' : 'resume-merge',
+      via: owns ? 'owner' : 'archon',
+    };
+  }
+  if (status === 'active') {
+    return {
+      action: 'claim-first',
+      reason: `Task #${task.id} is 'active' (claimed) but not in THIS session. Ship from the session that ` +
+        `claimed it, or \`node scripts/gds/release.js ${task.id} --force\` here, then re-claim.`,
+    };
+  }
+  if (status === 'ready' || status === 'backlog' || status === 'blocked') {
+    return {
+      action: 'claim-first',
+      reason: `Task #${task.id} is '${status}' — claim it first: \`node scripts/gds/claim.js ${task.id}\`.`,
+    };
+  }
+  return { action: 'error', reason: `Task #${task.id} is '${status}'. Nothing to resume.` };
+}
+
+// task 941: resume a `confirmed`-but-unshipped task — the merge/deploy leg only
+// (it already passed the grade + earned credits; this is the leg that stalls when
+// a box can't reach the server publish, a poll window expires, etc.). Mirrors the
+// tail of a normal ship: preflight → mergeAndDeploy → post-ship sync.
+async function resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly = false }) {
+  console.log(`Resuming merge + deploy for task #${taskId}: ${task?.title || ''}`);
+  // Same working-tree-clean / branch-freshness guard a first ship runs before
+  // the land. head_sha is unused on this leg; touches is only for preflight.
+  const claimLike = { touches: task?.touches || [], head_sha: null, task_id: taskId, title: task?.title };
+  console.log('Preflight (working tree + branch freshness)...');
+  const pre = preflight(claimLike, { force });
+  if (!pre.ok) {
+    console.error('');
+    console.error(`Resume aborted: ${pre.reason}. Task stays at confirmed.`);
+    process.exit(1);
+  }
+  // The first ship stored value_summary; reuse it so the merge commit + broadcast
+  // carry meaningful text even when --summary is omitted on the re-run.
+  const effSummary = summary || task?.value_summary || '';
+  const land = await mergeAndDeploy({ taskId, summary: effSummary, advanceToMerge: true, skipMerge, dbOnly });
+  const usage = await postShipSync(taskId, 'confirmed');
+  console.log('');
+  console.log('Done — merge/deploy resume complete.');
+  playShipBell(); // task 1442: ring the bell when a stalled ship finally lands.
+  await onboardingNudgeBestEffort();
+  // task 1275: the resume path lands a stalled ship — show the completion card
+  // too (the gap surfaced on task 1270's own ship). Re-fetch the status so the
+  // card reflects whether it actually reached shipped. Best-effort.
+  try {
+    const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
+    const status = (t.ok && t.data && t.data.task) ? t.data.task.status : 'shipped';
+    await printCompletionCard({
+      taskId, postGradeStatus: status, usage, land,
+      card: { title: task?.title, valueSummary: effSummary, notes: '', creditsAwarded: null },
+    });
+  } catch (_) { /* the resume already succeeded; the card is a bonus */ }
+}
+
+module.exports = {
+  evaluateRegradeEligibility,
+  evaluateResumeAction,
+  resumeMerge,
+};

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

@@ -0,0 +1,216 @@
+// scripts/gds/ship-session-upload.js — session digest, transcript upload + the ADR 0022 scrub/skip bookkeeping.
+//
+// Carved out of scripts/gds/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 { claudeConfigBase, encodeProjectPath, resolveTranscriptPath } = require('./ship-memory-sync.js');
+const { apiErrorLine } = require('./ship-io.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/gds/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, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
+} = require('./session-digest-build');
+
+
+// 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;
+  }
+}
+
+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). Reconstruct the exact
+    // paths resolveTranscriptPath checks so a transcript-not-found skip can name
+    // precisely where it looked (actionable, not a bare "not found").
+    const dirsTried = [process.cwd(), REPO_ROOT].filter(Boolean);
+    const pathsTried = sessionIdSafe
+      ? dirsTried.map((d) =>
+          path.join(claudeConfigBase(), 'projects', encodeProjectPath(path.resolve(d)), `${sessionId}.jsonl`)
+        )
+      : [];
+    const transcriptPath = sessionIdSafe ? resolveTranscriptPath(sessionId, dirsTried) : null;
+
+    const decision = classifyUploadSkip({ sessionId, sessionIdSafe, transcriptPath, pathsTried });
+    if (decision.skip) {
+      recordUploadSkip(taskId, decision);
+      return null;
+    }
+    const raw = fs.readFileSync(transcriptPath, 'utf8');
+    const entries = [];
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        entries.push(JSON.parse(t));
+      } catch (_) {
+        /* skip a malformed line — best-effort */
+      }
+    }
+    // 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 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 r = await (await cliClient({ allowUnauthenticated: true })).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).`
+      );
+    } else if (r.status === 401) {
+      recordUploadSkip(taskId, {
+        code: 'session_invalid',
+        reason:
+          'POST /api/gds/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/gds/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,
+};

package/scripts/gds/ship-state.js

@@ -0,0 +1,73 @@
+// scripts/gds/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/gds/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 } = 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
+
+// Where auto-merge runs — the worktree that has `main` checked out, not the
+// feature worktree this script lives in. Falls back to two-levels-up if we
+// can't ask git (e.g. fresh clone with no `main` worktree set up yet).
+const REPO_ROOT = findMainWorktree(__dirname) || path.resolve(__dirname, '..', '..');
+
+// 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,
+  playSound,
+  BEHIND_MAIN_LIMIT,
+};

package/scripts/gds/ship-surprise.js

@@ -0,0 +1,84 @@
+// scripts/gds/ship-surprise.js — surprise / learning-capture prompt on ship (task #32).
+//
+// Carved out of scripts/gds/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,
+};