@bongos/core 1.17.0

package/scripts/gds/install-git-hooks.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// scripts/gds/install-git-hooks.js — activate the project's git hooks (SEC #863).
+//
+// The Off the Boats hooks are TRACKED, committed files under .husky/ (the same
+// pattern as .husky/pre-commit, the secrets guard). Git only runs them when the
+// clone has core.hooksPath pointed at .husky. The pre-commit hook documents
+// "Activate once per clone: git config core.hooksPath .husky" — easy to forget,
+// which means a builder could run with NO secret-scan AND NO push gate.
+//
+// This script makes activation automatic (called by /builder-setup). It does
+// NOT write any hook file — the hooks ship via git. It only ensures
+// core.hooksPath is set so .husky/pre-commit AND .husky/pre-push fire.
+//
+// Idempotent and cross-platform. Runnable standalone:
+//   node scripts/gds/install-git-hooks.js
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+function git(args) {
+  return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+// The regenerating merge driver declared in .gitattributes (task 1243). Without
+// this per-clone config, git ignores the `merge=otb-regen` attribute and falls back
+// to a normal conflict — so registering it here is what makes `git merge` auto-heal
+// the generated files (docs/repo-map.md + the nested CLAUDE.md blocks).
+const MERGE_DRIVER_NAME = 'otb-regen';
+
+function registerMergeDriver(root) {
+  // execFileSync (arg array, no shell) so the literal %O/%A/%B/%P placeholders and
+  // the spaces in the command survive verbatim on every platform (a shell would
+  // mangle %VARS on Windows cmd).
+  try {
+    execFileSync('git', ['config', `merge.${MERGE_DRIVER_NAME}.name`,
+      'Off the Boats generated-file regenerator (task 1243)'], { cwd: root, stdio: 'ignore' });
+    execFileSync('git', ['config', `merge.${MERGE_DRIVER_NAME}.driver`,
+      'node scripts/gds/git-merge-regen.js %O %A %B %P'], { cwd: root, stdio: 'ignore' });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+// Resolve the configured hooks dir (absolute) for reporting / verification.
+function configuredHooksDir() {
+  try {
+    const rel = git('rev-parse --git-path hooks');
+    const root = git('rev-parse --show-toplevel');
+    return path.isAbsolute(rel) ? rel : path.join(root, rel);
+  } catch (_) {
+    return null;
+  }
+}
+
+function activate() {
+  const root = git('rev-parse --show-toplevel');
+  const huskyDir = path.join(root, '.husky');
+  if (!fs.existsSync(huskyDir)) {
+    return { status: 'no-husky-dir',
+      message: `.husky/ not found at ${huskyDir}; nothing to activate (older checkout?).` };
+  }
+
+  // Always (re)register the regenerating merge driver — idempotent, and existing
+  // clones pick it up on any re-run of this script.
+  const mergeDriver = registerMergeDriver(root);
+
+  let current = '';
+  try { current = git('config --get core.hooksPath'); } catch (_) { current = ''; }
+
+  // Already pointed at a .husky dir (relative or absolute) → leave it; both the
+  // tracked pre-commit and pre-push live there. Don't fight an operator who set
+  // an absolute path on purpose (e.g. to share hooks across worktrees).
+  const points = configuredHooksDir();
+  const alreadyHusky = current && points && path.basename(points) === '.husky';
+  if (alreadyHusky) {
+    return { status: 'already-active', hooksPath: current, dir: points, mergeDriver };
+  }
+
+  // Not set (or set elsewhere): activate the project hooks. Relative '.husky'
+  // is husky-standard and resolves per-worktree.
+  git('config core.hooksPath .husky');
+  return { status: 'activated', hooksPath: '.husky', dir: huskyDir, mergeDriver };
+}
+
+if (require.main === module) {
+  try {
+    const r = activate();
+    if (r.status === 'no-husky-dir') {
+      console.error(`⚠ ${r.message}`);
+      process.exit(0);
+    }
+    if (r.status === 'already-active') {
+      console.log(`✓ git hooks already active (core.hooksPath=${r.hooksPath}); pre-commit + pre-push gates live`);
+    } else {
+      console.log(`✓ git hooks activated (core.hooksPath=.husky); pre-commit secrets guard + pre-push permission gate now run`);
+    }
+    if (r.mergeDriver && r.mergeDriver.ok) {
+      console.log(`✓ merge driver '${MERGE_DRIVER_NAME}' registered; generated-file conflicts (docs/repo-map.md, nested CLAUDE.md) auto-regenerate on merge`);
+    } else if (r.mergeDriver) {
+      console.error(`⚠ could not register the '${MERGE_DRIVER_NAME}' merge driver: ${r.mergeDriver.error} (generated-file merges will conflict normally; ship.js still self-heals)`);
+    }
+    process.exit(0);
+  } catch (e) {
+    // Never let activation fail a setup hard — warn and move on.
+    console.error(`⚠ could not activate git hooks: ${e.message} (you can run: git config core.hooksPath .husky)`);
+    process.exit(0);
+  }
+}
+
+module.exports = { activate, configuredHooksDir, registerMergeDriver, MERGE_DRIVER_NAME };

package/scripts/gds/key-card.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// scripts/gds/key-card.js — the "key needed" visual callout (task 1391).
+//
+// The problem: a builder session that hits a missing API key today gets a
+// buried multi-line text error (see modules/art-pipeline/pipeline/gen_api.py's
+// "No image-generation key found" RuntimeError). The owner's ask: render a
+// VISUAL callout instead — same pattern as the ship/claim lifecycle card
+// (modules/lifecycle/ship-card.js) — naming which key + what it's for, a
+// primary "Add it in Settings ↗" action, and the rule "don't paste keys in
+// chat — add via Settings; it syncs to your box automatically."
+//
+// ONE generator, two render paths, both PURE (mirrors ship-card.js):
+//   renderMonospaceKeyCard(model) — the CLI/headless form.
+//   renderKeyCardHtml(model)      — the branded HTML the skills render via
+//     show_widget. Brand tokens come from src/branding.js.
+//
+// buildKeyCardModel() normalizes raw input into the model both consume.
+// emitKeyCard() is the shared I/O helper: prints the monospace card, and (when
+// widgets are on) writes the HTML to a temp file + prints the
+// `[otb-key-card-html] <path>` marker — the PostToolUse lifecycle-card hook
+// (.claude/hooks/lifecycle-card.js) picks this marker up from ANY Bash tool
+// output (it doesn't need to be a node invocation — the art pipeline calls
+// this file as a subprocess from Python) and injects the render directive.
+//
+// This is the FIRST integration (the art pipeline's Gemini key); the model is
+// deliberately key-agnostic (`keyId`/`keyLabel`/`forWhat`/`settingsAnchor` are
+// all caller-supplied) so a future key just calls emitKeyCard with different
+// strings — no new card code.
+//
+// CLI usage (what gen_api.py shells out to):
+//   node scripts/gds/key-card.js --key gemini --label "Image-generation key" \
+//     --for "the art pipeline" --anchor art-key
+//
+// Never throws past main() — a card failure must never mask the real
+// missing-key error the caller is about to raise.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function safeBrand() {
+  try {
+    const b = require('../src/branding').branding();
+    return {
+      productName: (b.identity && b.identity.productName) || 'Cloud Bongos',
+      settingsUrl: (b.domains && b.domains.publicOrigin)
+        ? `${b.domains.publicOrigin}/builders/settings`
+        : 'https://amazonprimea.com/builders/settings',
+    };
+  } catch (_) {
+    return { productName: 'Cloud Bongos', settingsUrl: 'https://amazonprimea.com/builders/settings' };
+  }
+}
+
+// ---- model ------------------------------------------------------------
+// { keyId, keyLabel, forWhat, settingsUrl, brand }
+function buildKeyCardModel(input = {}) {
+  const brand = input.brand || safeBrand();
+  const anchor = input.settingsAnchor ? `#${input.settingsAnchor}` : '';
+  const settingsUrl = input.settingsUrl || `${brand.settingsUrl}${anchor}`;
+  return {
+    keyId: input.keyId || 'key',
+    keyLabel: input.keyLabel || 'API key',
+    forWhat: input.forWhat || '',
+    settingsUrl,
+    brand,
+  };
+}
+
+// ---- monospace renderer (alignment-proof, no right border) -------------
+const MONO_W = 58;
+function wrap(text, width) {
+  const words = String(text == null ? '' : text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let cur = '';
+  for (const w of words) {
+    if (!cur) cur = w;
+    else if ((cur + ' ' + w).length <= width) cur += ' ' + w;
+    else { lines.push(cur); cur = w; }
+  }
+  if (cur) lines.push(cur);
+  return lines.length ? lines : [''];
+}
+function renderMonospaceKeyCard(model) {
+  const m = model;
+  const out = [];
+  const bar = '  ' + '─'.repeat(MONO_W);
+  const left = `${m.brand.productName} · key needed`;
+  const right = 'Action needed';
+  const gap = Math.max(2, MONO_W - left.length - right.length);
+  out.push('  ' + left + ' '.repeat(gap) + right);
+  out.push(bar);
+  const headline = m.forWhat ? `${m.keyLabel} — needed for ${m.forWhat}` : m.keyLabel;
+  for (const l of wrap(headline, MONO_W)) out.push('  ' + l);
+  out.push('');
+  for (const l of wrap("Don't paste keys in chat — add it in Settings; it syncs to your box automatically.", MONO_W)) {
+    out.push('  ' + l);
+  }
+  out.push('');
+  out.push(bar);
+  for (const l of wrap(`Next → Add it in Settings: ${m.settingsUrl}`, MONO_W)) out.push('  ' + l);
+  return out.join('\n');
+}
+
+// ---- HTML renderer (the in-feed branded card) ---------------------------
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+function renderKeyCardHtml(model) {
+  const m = model;
+  const bg = 'var(--color-background-warning)';
+  const fg = 'var(--color-text-warning)';
+  const headline = m.forWhat ? `${m.keyLabel} needed for ${m.forWhat}` : `${m.keyLabel} needed`;
+  const srText = `${headline}. Don't paste keys in chat — add it in Settings, it syncs to your box automatically.`;
+
+  return `<h2 class="cc-sr">${esc(srText)}</h2>
+<style>
+.cc-sr{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0;}
+</style>
+<div style="background:var(--color-background-primary);border:0.5px solid var(--color-border-tertiary);border-radius:var(--border-radius-lg);padding:0.8rem 1.05rem;">
+  <div style="display:flex;align-items:center;gap:8px;background:${bg};border-radius:var(--border-radius-md);padding:7px 12px;margin-bottom:0.65rem;">
+    <i class="ti ti-key" style="font-size:18px;color:${fg};" aria-hidden="true"></i>
+    <span style="font-size:15px;font-weight:500;color:${fg};min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">${esc(headline)}</span>
+  </div>
+  <div style="display:flex;align-items:center;gap:12px;margin-bottom:7px;">
+    <span style="font-family:var(--font-serif);font-size:16.5px;font-weight:500;line-height:1.3;flex:1;min-width:0;">${esc(m.keyLabel)}</span>
+    <a href="${esc(m.settingsUrl)}" class="cc-link cc-next" style="text-decoration:none;background:none;border:none;padding:0;cursor:pointer;font-family:inherit;display:inline-flex;align-items:center;gap:3px;white-space:nowrap;flex:none;font-size:12px;color:var(--color-text-secondary);">Add it in Settings ↗</a>
+  </div>
+  <div style="font-size:13px;color:var(--color-text-secondary);line-height:1.5;">Don't paste keys in chat — add it in Settings; it syncs to your box automatically.</div>
+</div>`;
+}
+
+// ---- emitKeyCard: the shared I/O helper ----------------------------------
+// Prints the monospace card (always), and — when widgetsEnabled — writes the
+// branded HTML to a temp file + prints the [otb-key-card-html] marker.
+// Strictly best-effort: a card failure must never mask the caller's real error.
+function emitKeyCard(model, { log = console.log, widgetsEnabled = true } = {}) {
+  try {
+    log('');
+    log(renderMonospaceKeyCard(model));
+  } catch (_) { return null; }
+  if (!widgetsEnabled) {
+    try {
+      log('');
+      log('[otb-card] widgets are off for this builder — the card above IS the summary; relay it as plain text and do NOT call show_widget.');
+    } catch (_) { /* best-effort */ }
+    return null;
+  }
+  try {
+    const file = path.join(os.tmpdir(), `otb-key-card-${model.keyId}.html`);
+    fs.writeFileSync(file, renderKeyCardHtml(model), 'utf8');
+    log('');
+    log(`[otb-key-card-html] ${file}`);
+    log('[otb-card] render the HTML at the path above in the chat feed via the visualization tool (show_widget), then stop — no prose recap. Never ask the builder to paste the key in chat; point them at the Settings link. If that tool is unavailable, the card above IS the summary.');
+    return file;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---- CLI ------------------------------------------------------------------
+function arg(flag, argv) {
+  const i = argv.indexOf(flag);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+}
+
+async function resolveWidgetsEnabled() {
+  // Best-effort: read the builder's render-widgets knob from /me (task 1279
+  // precedent — claim.js/ship.js do the same). ANY failure (no session,
+  // offline, timeout, non-200) defaults to widgets ON — the common case for an
+  // interactive session — rather than blocking the card on a network call.
+  try {
+    const { loadSession, API_BASE } = require('./cli-lib');
+    const session = await loadSession();
+    if (!session || !session.token) return true;
+    const base = session.api_base || API_BASE;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 3000);
+    try {
+      const res = await fetch(`${base}/api/gds/me`, {
+        headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': 'amazonprimea-key-card/1.0' },
+        signal: ctrl.signal,
+      });
+      if (!res.ok) return true;
+      const data = await res.json();
+      return data?.render?.widgets_enabled !== false;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (_) {
+    return true;
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const model = buildKeyCardModel({
+    keyId: arg('--key', argv) || 'key',
+    keyLabel: arg('--label', argv) || 'API key',
+    forWhat: arg('--for', argv) || '',
+    settingsAnchor: arg('--anchor', argv) || null,
+    settingsUrl: arg('--settings-url', argv) || null,
+  });
+  const widgetsEnabled = await resolveWidgetsEnabled();
+  emitKeyCard(model, { widgetsEnabled });
+}
+
+if (require.main === module) {
+  main().then(() => process.exit(0)).catch(() => process.exit(0)); // best-effort — never fail the caller
+}
+
+module.exports = { buildKeyCardModel, renderMonospaceKeyCard, renderKeyCardHtml, emitKeyCard, wrap, esc, safeBrand };

package/scripts/gds/key-status.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// scripts/gds/key-status.js — the /builder-key backing script (task 1391, part B).
+//
+// Lists which API keys are set/unset for the calling builder, renders the
+// "key needed" visual callout (scripts/gds/key-card.js) for any that are
+// missing, and — after the builder adds one via Settings — re-syncs the local
+// session file (scripts/gds/fetch-art-key.js) and confirms it resolved.
+//
+// HARD RULE (idea 347 + the UI-first auth-flow rule): a key is NEVER accepted
+// as a CLI argument or pasted into chat — the only place a key is ever
+// written is PUT /me/art-key/own, driven by the browser Settings page
+// (modules/hall-ui/public/settings.js). If a builder pastes a key-looking
+// string as an argument anyway, this script refuses and points back to
+// Settings instead of silently ignoring or forwarding it.
+//
+// Usage:
+//   node scripts/gds/key-status.js              # list status; render callout if missing
+//   node scripts/gds/key-status.js --recheck     # re-sync + confirm after adding a key
+
+'use strict';
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { cliClient, requireSession } = require('./cli-lib');
+const keyCard = require('./key-card');
+
+// The known keys this script reports on. One entry today (the art pipeline's
+// Gemini key); a future key adds an entry here, not a new script (mirrors
+// key-card.js's deliberately key-agnostic model).
+const KEYS = [
+  {
+    id: 'gemini',
+    label: 'Image-generation key (Google AI Studio / Gemini)',
+    forWhat: 'the art pipeline',
+    settingsAnchor: 'art-key',
+    fetchStatus: async () => {
+      const api = await cliClient();
+      const r = await api.me.getMeArtKey();
+      if (r.status !== 200 || !r.data) return { known: false };
+      const d = r.data;
+      if (d.own_key_set) return { known: true, set: true, detail: `your own key, ending ${d.own_key_last4 || '????'}` };
+      if (d.entitled && d.configured) return { known: true, set: true, detail: 'the shared newcomer key (floor coverage)' };
+      return { known: true, set: false };
+    },
+  },
+];
+
+// A pasted-secret guard (part 3 of the done-when): refuse any argument that
+// looks like a credential rather than a flag, instead of silently accepting
+// or forwarding it. Google AI Studio keys are ~39 chars of [A-Za-z0-9_-];
+// this is deliberately loose (catches "looks like a key", not just Google's
+// exact shape) since the whole point is to never guess-forward a secret.
+const KEY_LIKE_RE = /^[A-Za-z0-9_-]{20,}$/;
+
+function refuseIfKeyPasted(argv) {
+  const suspect = argv.find((a) => !a.startsWith('--') && KEY_LIKE_RE.test(a));
+  if (!suspect) return false;
+  console.log('');
+  console.log('✖ That looks like an API key — this tool never accepts one as an argument,');
+  console.log('  and keys are never pasted into chat (the transcript is uploaded).');
+  console.log('  Add it in Settings instead — it syncs to your box automatically:');
+  console.log('    https://amazonprimea.com/builders/settings#art-key');
+  return true;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (refuseIfKeyPasted(argv)) { process.exit(1); return; }
+
+  const recheck = argv.includes('--recheck');
+  await requireSession();
+
+  if (recheck) {
+    try { execFileSync(process.execPath, [path.join(__dirname, 'fetch-art-key.js')], { stdio: 'ignore' }); }
+    catch (_) { /* best-effort re-sync */ }
+  }
+
+  console.log('');
+  console.log('Key status:');
+  let anyMissing = false;
+  for (const k of KEYS) {
+    let status;
+    try { status = await k.fetchStatus(); } catch (_) { status = { known: false }; }
+    if (!status.known) {
+      console.log(`  ? ${k.label} — couldn't check (offline or API error)`);
+      continue;
+    }
+    if (status.set) {
+      console.log(`  ✓ ${k.label} — set (${status.detail})`);
+    } else {
+      console.log(`  ✖ ${k.label} — not set`);
+      anyMissing = true;
+      const model = keyCard.buildKeyCardModel({
+        keyId: k.id, keyLabel: k.label, forWhat: k.forWhat, settingsAnchor: k.settingsAnchor,
+      });
+      keyCard.emitKeyCard(model, { widgetsEnabled: await resolveWidgetsEnabled() });
+    }
+  }
+
+  if (recheck) {
+    console.log('');
+    console.log(anyMissing
+      ? 'Re-synced — still missing a key above. Add it in Settings, then run --recheck again.'
+      : 'Re-synced — all keys resolved.');
+  }
+}
+
+async function resolveWidgetsEnabled() {
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.me.getMe();
+    if (r.status !== 200 || !r.data) return true;
+    return r.data?.render?.widgets_enabled !== false;
+  } catch (_) {
+    return true;
+  }
+}
+
+if (require.main === module) {
+  main().then(() => process.exit(0)).catch((err) => {
+    console.error(err && err.message ? err.message : String(err));
+    process.exit(1);
+  });
+}
+
+module.exports = { KEYS, KEY_LIKE_RE, refuseIfKeyPasted };

package/scripts/gds/land-watch.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/land-watch.js — show the SHIPPED banner once an async CI land completes.
+//
+// THE GAP (task 1687). In CI deploy mode /builder-ship arms auto-merge and EXITS at
+// status=confirmed; the real confirmed->shipped land happens minutes later, server-side
+// (GitHub auto-merge + the 5-min publish-reconciler). So the last card the builder sees
+// is the "confirmed — landing" banner — the SHIPPED success banner ship-card.js already
+// models never renders in-session (observed on task 1211/PR #512).
+//
+// THE MECHANISM (non-blocking, next-turn). ship.js drops a small PENDING-LAND breadcrumb
+// when it exits at confirmed (it owns writeBreadcrumb below, so the schema lives in ONE
+// place). On a later prompt the land-watch-card hook runs this in --hook mode: it reads
+// the breadcrumbs, GETs each task, and when one has flipped to `shipped` it renders the
+// shipped lifecycle card (reusing ship-card.js — the same card ship.js would have shown)
+// and clears the breadcrumb. Terminal-non-shipped or stale breadcrumbs are dropped. With
+// no breadcrumb it does nothing (the common case) — the hook is a fast no-op when idle.
+//
+// Read-only + safe: it never mutates GDS state; it only reads task status and renders.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { SESSION_PATH, cliClient } = require('./cli-lib');
+const shipCard = require('../../modules/lifecycle/ship-card');
+
+// Breadcrumbs live beside the session token (per-machine, per-instance config dir —
+// NOT in the repo, so they are never committed). Derive the dir from SESSION_PATH so
+// it tracks the instance-config resolution (OTB → ~/.config/otb/pending-land/).
+const PENDING_DIR = path.join(path.dirname(SESSION_PATH || ''), 'pending-land');
+const DEFAULT_STALE_MS = 30 * 60 * 1000; // stop watching a land that never completes
+
+function ensureDir() {
+  try { fs.mkdirSync(PENDING_DIR, { recursive: true }); } catch (_) { /* best-effort */ }
+}
+
+// Written by ship.js at confirmed-exit. Atomic (tmp + rename) so a concurrent read can
+// never see a half-written file. `data` = { branch, widgetsEnabled, cardInputs } where
+// cardInputs is exactly the object ship.js passed to buildCardModel (postGradeStatus is
+// overridden to 'shipped' at render time).
+function writeBreadcrumb(taskId, data = {}) {
+  const id = String(taskId);
+  if (!/^\d+$/.test(id)) return null;
+  ensureDir();
+  const dest = path.join(PENDING_DIR, `${id}.json`);
+  const tmp = `${dest}.tmp`;
+  const row = { taskId: id, at: new Date().toISOString(), ...data };
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(row), 'utf8');
+    fs.renameSync(tmp, dest);
+    return dest;
+  } catch (_) {
+    try { fs.rmSync(tmp, { force: true }); } catch (__) { /* ignore */ }
+    return null;
+  }
+}
+
+function readBreadcrumbs() {
+  let names = [];
+  try { names = fs.readdirSync(PENDING_DIR); } catch (_) { return []; } // dir absent → none
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(PENDING_DIR, name);
+    try {
+      const row = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (row && typeof row === 'object' && /^\d+$/.test(String(row.taskId))) out.push({ ...row, _file: file });
+    } catch (_) { /* skip a corrupt/partial file */ }
+  }
+  return out;
+}
+
+function removeBreadcrumb(fileOrId) {
+  const file = typeof fileOrId === 'string' && fileOrId.endsWith('.json')
+    ? fileOrId
+    : path.join(PENDING_DIR, `${fileOrId}.json`);
+  try { fs.rmSync(file, { force: true }); } catch (_) { /* ignore */ }
+}
+
+// PURE decision — exported so the truth table is unit-tested with no fs/network.
+//   'emit' → the task has landed (shipped): render the shipped card, then clear.
+//   'drop' → give up watching: stale, OR it left the land path (grade-failed back to
+//            completed, released, …) so the confirmed→shipped transition won't happen.
+//   'keep' → still landing (confirmed), or a transient read failure — retry next turn.
+// emit wins over stale so a just-landed breadcrumb still shows even if old.
+function classifyLand(task, ageMs, { staleMs = DEFAULT_STALE_MS } = {}) {
+  if (task && task.status === 'shipped') return 'emit';
+  if (typeof ageMs === 'number' && ageMs > staleMs) return 'drop';
+  if (!task || typeof task.status !== 'string') return 'keep'; // couldn't read → retry
+  if (task.status === 'confirmed') return 'keep';               // still landing
+  return 'drop';                                                // no longer on the land path
+}
+
+async function fetchTask(taskId) {
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.tasks.getTasksId({ id: taskId });
+    return r?.data?.task ?? r?.data ?? null;
+  } catch (_) {
+    return null; // transient → classifyLand keeps it for a retry
+  }
+}
+
+// Build the { widgets_enabled, html, markdown, warnings, title } envelope (the same
+// shape session-cards.js consumes) for a landed breadcrumb, reusing ship-card.js so the
+// shipped banner is byte-identical to what ship.js emits inline. `nowMs` is injected for
+// determinism in tests.
+function buildShippedEnvelope(crumb, task) {
+  const inputs = (crumb && crumb.cardInputs && typeof crumb.cardInputs === 'object') ? crumb.cardInputs : {};
+  const model = shipCard.buildCardModel({
+    ...inputs,
+    postGradeStatus: 'shipped',
+    taskId: crumb.taskId,
+    // Prefer a fact from the fresh task row when the breadcrumb didn't carry it.
+    title: inputs.title || (task && task.title) || `Task #${crumb.taskId}`,
+    valueSummary: inputs.valueSummary || (task && task.value_summary) || '',
+  });
+  return {
+    widgets_enabled: crumb.widgetsEnabled !== false,
+    html: shipCard.renderCardHtml(model),
+    markdown: shipCard.renderMonospaceCard(model),
+    warnings: [],
+    title: `task_${crumb.taskId}_card`,
+  };
+}
+
+// Walk the breadcrumbs; emit AT MOST ONE shipped card per run (avoid flooding a turn),
+// dropping the give-ups. Returns the envelope to inject, or null. Deps injected for tests.
+async function watch({ nowMs = Date.now(), staleMs = DEFAULT_STALE_MS, getTask = fetchTask, readCrumbs = readBreadcrumbs, removeCrumb = removeBreadcrumb } = {}) {
+  const crumbs = readCrumbs().sort((a, b) => String(b.at).localeCompare(String(a.at))); // newest first
+  let envelope = null;
+  for (const crumb of crumbs) {
+    const ageMs = nowMs - Date.parse(crumb.at || '') || 0;
+    const task = await getTask(crumb.taskId);
+    const verdict = classifyLand(task, Number.isFinite(ageMs) ? ageMs : 0, { staleMs });
+    if (verdict === 'emit') {
+      if (!envelope) { envelope = buildShippedEnvelope(crumb, task); removeCrumb(crumb._file); }
+      // a 2nd shipped crumb waits for the next turn (one card at a time)
+    } else if (verdict === 'drop') {
+      removeCrumb(crumb._file);
+    }
+    // 'keep' → leave it
+  }
+  return envelope;
+}
+
+module.exports = {
+  PENDING_DIR, DEFAULT_STALE_MS,
+  writeBreadcrumb, readBreadcrumbs, removeBreadcrumb,
+  classifyLand, buildShippedEnvelope, watch,
+};
+
+// CLI. `--hook`: print ONLY the envelope JSON on stdout when a card should render (the
+// land-watch-card hook parses it); nothing otherwise. Bare: a human-readable summary.
+if (require.main === module) {
+  const hookMode = process.argv.includes('--hook');
+  (async () => {
+    // Cheap idle fast-path: no breadcrumbs → do nothing (no network).
+    if (readBreadcrumbs().length === 0) { if (!hookMode) console.error('land-watch: no pending lands.'); process.exit(0); }
+    const envelope = await watch();
+    if (hookMode) {
+      if (envelope) process.stdout.write(JSON.stringify(envelope));
+      process.exit(0);
+    }
+    console.error(envelope ? `land-watch: a task landed — shipped card ready (${envelope.title}).` : 'land-watch: nothing landed this pass.');
+    process.exit(0);
+  })().catch(() => process.exit(0)); // never throw from a hook-invoked script
+}