@bongos/core 1.17.0

package/scripts/gds/doctor.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+// GDS Doctor — one-shot health check for a builder's local machine.
+//
+// Usage:
+//   node scripts/gds/doctor.js
+//
+// No arguments. Prints a green/red checklist covering:
+//   - Session validity (file present, /me returns 200, identity + rank)
+//   - Toolchain (Node >= 22; the `claude` CLI the grader spawns is launchable —
+//     this is the check that would have surfaced Xenos's Windows grader failure
+//     up front instead of after a deep manual dig)
+//   - Git plumbing (core.hooksPath resolves to a real directory, hook executable)
+//   - Repo state (on a known branch, no uncommitted matches against a held
+//     claim's touches[])
+//   - Environment (.env.local present in main checkout, art-pipeline key
+//     present at ~/.config/otb/env)
+//
+// Exits 0 if every check passes, 1 if any red finding (so it's safe to wire
+// into hooks or CI smoke). Intended to be run by a builder when something
+// feels off ("am I authed? are my hooks installed? is my worktree clean?")
+// and to be the single command we point new builders at first.
+//
+// Designed not to throw — every check catches its own exceptions and renders
+// a red row with the error message rather than blowing up the whole report.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execSync, spawnSync } = require('node:child_process');
+const { cliClient, SESSION_PATH, loadSession } = require('./cli-lib');
+
+// ANSI helpers (only if stdout is a TTY; otherwise emit plain text)
+const TTY = process.stdout.isTTY;
+const C = {
+  green: TTY ? '\x1b[32m' : '',
+  red: TTY ? '\x1b[31m' : '',
+  yellow: TTY ? '\x1b[33m' : '',
+  bold: TTY ? '\x1b[1m' : '',
+  reset: TTY ? '\x1b[0m' : '',
+};
+
+// Accumulate findings across all checks. Each finding has a status (ok / warn /
+// fail), a section name, and a one-line description. Only "fail" rows count
+// toward the non-zero exit code; "warn" is for things that are mildly off but
+// the builder can still work (e.g. art-pipeline key missing — only matters if
+// they touch the pipeline).
+const findings = [];
+
+function ok(section, msg) {
+  findings.push({ status: 'ok', section, msg });
+  console.log(`  ${C.green}✓${C.reset} ${msg}`);
+}
+function warn(section, msg) {
+  findings.push({ status: 'warn', section, msg });
+  console.log(`  ${C.yellow}!${C.reset} ${msg}`);
+}
+function fail(section, msg) {
+  findings.push({ status: 'fail', section, msg });
+  console.log(`  ${C.red}✖${C.reset} ${msg}`);
+}
+
+function section(title) {
+  console.log('');
+  console.log(`${C.bold}${title}${C.reset}`);
+}
+
+function gitOut(cmd, opts = {}) {
+  try {
+    return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// --------------------------------------------------------------------------
+// Check 1 — Session
+// --------------------------------------------------------------------------
+async function checkSession() {
+  section('Session');
+  let s;
+  try {
+    s = await loadSession();
+  } catch (err) {
+    fail('session', `Could not read session file: ${err.message}`);
+    return;
+  }
+  if (!s || !s.token) {
+    fail('session', `No session file at ${SESSION_PATH} (or the legacy fallback).`);
+    fail('session', `Recover with: node scripts/gds/setup.js`);
+    return;
+  }
+  ok('session', `Session file present (${SESSION_PATH.replace(os.homedir(), '~')})`);
+  // Ping /me with allowUnauthenticated so we can render a red row instead of
+  // exiting via the global 401 short-circuit.
+  let me;
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    me = await api.me.getMe();
+  } catch (err) {
+    fail('session', `Could not reach the GDS to verify the token: ${err.message}`);
+    return;
+  }
+  if (me.status === 401) {
+    fail('session', `Token rejected (HTTP 401). Recover with: node scripts/gds/setup.js --force`);
+    return;
+  }
+  if (me.status !== 200) {
+    fail('session', `Unexpected /me response (HTTP ${me.status}). Try: node scripts/gds/setup.js --force`);
+    return;
+  }
+  const b = me.data?.builder || {};
+  ok('session', `Authenticated as ${b.github_login} (id #${b.id}, rank=${b.rank}, ${b.total_credits ?? 0} credits)`);
+  ok('session', `Session is rolling: every authenticated request resets the 1h TTL.`);
+}
+
+// --------------------------------------------------------------------------
+// Check 2 — Toolchain (Node + the claude CLI the grader spawns)
+// --------------------------------------------------------------------------
+//
+// The grader (src/bongos/grader.js) spawns one `claude` subprocess per worker. If
+// that binary can't be launched, every ship fails the grade with
+// SUBAGENT_SPAWN_FAILED (can't launch) or SUBAGENT_NONZERO_EXIT (launches but
+// misbehaves — e.g. the Windows "App execution alias" desktop stub). On Windows
+// this bit a real builder twice and was only diagnosed after a long manual dig.
+// This check makes it the FIRST thing doctor reports, with the one-line fix.
+//
+// Resolution mirrors the grader EXACTLY (OTB_CLAUDE_BIN / CLAUDE_BIN / 'claude',
+// shell:true on win32 so a `claude.cmd` shim resolves) so a green row here means
+// the grader's spawn will work too. Mac/Linux: shell:false, identical to today.
+function checkToolchain() {
+  section('Toolchain');
+
+  // Node — setup-builder.sh requires >= 22; the scripts assume modern Node.
+  const nodeMajor = Number((process.versions.node || '0').split('.')[0]);
+  if (nodeMajor >= 22) {
+    ok('toolchain', `Node ${process.version} (>= 22 required).`);
+  } else {
+    fail('toolchain', `Node ${process.version} is below the required v22. Upgrade Node (e.g. nvm install 22, or https://nodejs.org).`);
+  }
+
+  // claude CLI — same resolution order the grader uses.
+  const fromEnv = process.env.OTB_CLAUDE_BIN
+    ? ' (via OTB_CLAUDE_BIN)'
+    : process.env.CLAUDE_BIN
+    ? ' (via CLAUDE_BIN)'
+    : '';
+  const bin = process.env.OTB_CLAUDE_BIN || process.env.CLAUDE_BIN || 'claude';
+  let r;
+  try {
+    r = spawnSync(bin, ['--version'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+  } catch (err) {
+    r = { error: err };
+  }
+  if (r && !r.error && r.status === 0) {
+    const ver = (r.stdout || '').trim().split('\n')[0] || 'present';
+    ok('toolchain', `claude CLI launches${fromEnv}: ${ver} — the grader can spawn its workers.`);
+    // Windows-only: warn if the resolved binary is the desktop "App execution
+    // alias" stub. It can pass --version yet misbehave under the grader's
+    // stdio redirection (SUBAGENT_NONZERO_EXIT). Learning #42.
+    if (process.platform === 'win32' && !process.env.OTB_CLAUDE_BIN && !process.env.CLAUDE_BIN) {
+      try {
+        const where = spawnSync('where', ['claude'], { encoding: 'utf8', shell: true, timeout: 8000 });
+        if (where.status === 0 && /WindowsApps/i.test(where.stdout || '')) {
+          warn('toolchain', `claude resolves to the WindowsApps desktop alias, which can fail headless grading (SUBAGENT_NONZERO_EXIT). Prefer a real CLI: npm i -g @anthropic-ai/claude-code (learning #42).`);
+        }
+      } catch (_) { /* best-effort */ }
+    }
+  } else {
+    const why = r && r.error ? (r.error.code || r.error.message) : `exited ${r ? r.status : '?'}`;
+    fail('toolchain', `claude CLI not launchable (${bin}: ${why}). The grader spawns it per worker — without it, ships fail grading with SUBAGENT_SPAWN_FAILED.`);
+    fail('toolchain', `Fix: npm i -g @anthropic-ai/claude-code  (puts a real claude on PATH). If it lives elsewhere, set OTB_CLAUDE_BIN to its full path and re-run.`);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Check 3 — Git plumbing
+// --------------------------------------------------------------------------
+function checkGitPlumbing() {
+  section('Git plumbing');
+  const hooksPath = gitOut('git config --get core.hooksPath');
+  if (!hooksPath) {
+    fail('git', `core.hooksPath is unset. Activate the pre-commit secrets guard with:\n      git config core.hooksPath .husky`);
+    return;
+  }
+  // Resolve relative to current worktree root (git's behavior for relative
+  // hooksPath values). Absolute paths resolve as-is.
+  let resolved = hooksPath;
+  if (!path.isAbsolute(hooksPath)) {
+    const top = gitOut('git rev-parse --show-toplevel');
+    if (top) resolved = path.join(top, hooksPath);
+  }
+  if (!fs.existsSync(resolved)) {
+    fail('git', `core.hooksPath="${hooksPath}" resolves to a non-existent path: ${resolved}`);
+    fail('git', `Reset with: git config core.hooksPath .husky`);
+    return;
+  }
+  ok('git', `core.hooksPath="${hooksPath}" → ${resolved} (exists)`);
+  const preCommit = path.join(resolved, 'pre-commit');
+  if (!fs.existsSync(preCommit)) {
+    warn('git', `No pre-commit file at ${preCommit} — secrets-guard hook will not fire.`);
+  } else {
+    try {
+      fs.accessSync(preCommit, fs.constants.X_OK);
+      ok('git', `pre-commit hook is executable.`);
+    } catch (_) {
+      warn('git', `pre-commit exists but is not executable: ${preCommit}`);
+    }
+  }
+}
+
+// --------------------------------------------------------------------------
+// Check 4 — Repo state
+// --------------------------------------------------------------------------
+async function checkRepoState() {
+  section('Repo state');
+  const branch = gitOut('git rev-parse --abbrev-ref HEAD');
+  if (!branch) {
+    fail('repo', `Could not determine current git branch. Are we inside a git repo?`);
+    return;
+  }
+  if (branch === 'HEAD') {
+    warn('repo', `Detached HEAD — most workflows expect a named branch.`);
+  } else {
+    ok('repo', `On branch ${branch}.`);
+  }
+  // If we have a session AND an active claim, optionally surface a touches[]
+  // drift hint. Skip silently if we don't (the /me data is already lost by
+  // this point of the check sequence; we'd have to re-fetch and that's more
+  // failure surface area for marginal value).
+  // (Left as a quiet ok-row to keep the section honest.)
+  const porcelain = gitOut('git status --porcelain');
+  if (!porcelain) {
+    ok('repo', `Working tree clean.`);
+  } else {
+    const lines = porcelain.split('\n').filter(Boolean);
+    warn('repo', `${lines.length} uncommitted change(s) in the working tree.`);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Check 5 — Environment
+// --------------------------------------------------------------------------
+function checkEnvironment() {
+  section('Environment');
+  // Find the main checkout root via the shared common-dir trick (works from
+  // any worktree, survives folder renames).
+  const commonDir = gitOut('git rev-parse --git-common-dir');
+  if (!commonDir) {
+    warn('env', `Could not resolve git common-dir; skipping .env.local check.`);
+    return;
+  }
+  const mainRoot = path.dirname(path.resolve(commonDir));
+  const envLocal = path.join(mainRoot, '.env.local');
+  if (fs.existsSync(envLocal)) {
+    ok('env', `.env.local present in main checkout (${mainRoot.replace(os.homedir(), '~')}/.env.local)`);
+  } else {
+    warn('env', `No .env.local in the main checkout. If you need local secrets, run /builder-setup.`);
+  }
+  // Art-pipeline key — survives worktree churn at ~/.config/otb/env
+  const otbEnv = path.join(os.homedir(), '.config/otb/env');
+  if (fs.existsSync(otbEnv)) {
+    ok('env', `Art-pipeline env present (~/.config/otb/env)`);
+  } else {
+    warn('env', `No ~/.config/otb/env — art pipeline calls will fail if you try them.`);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Check — Deploy tooling (the GitHub CLI the 'ci' deploy mode spawns)
+//
+// #857 / ADR 0042: in 'ci' deploy mode, ship.js's ciLand opens a PR + enables
+// auto-merge via the `gh` CLI on THIS machine. If gh is missing or not
+// authenticated, the ship reaches `confirmed` then fails to land with a cryptic
+// `gh pr create` error. Surface it here as an actionable row so a builder fixes
+// it before shipping. In 'laptop' mode gh isn't used → informational only.
+// (The eventual fix that drops this dependency — server-mediated PR creation —
+// is tracked separately; until then this check is the guardrail.)
+function checkDeployTooling() {
+  section('Deploy tooling');
+
+  // Resolve the mode exactly as ship.js will (env > committed config > laptop).
+  // Lazy + guarded require so doctor never throws if ship.js's load changes.
+  let mode = 'laptop';
+  try {
+    mode = require('./ship.js').resolveDeployMode();
+  } catch (_) {
+    /* keep the safe default; ship.js load is not doctor's concern */
+  }
+
+  if (mode !== 'ci') {
+    ok('deploy', `Deploy mode: laptop — the operator lands ships; the gh CLI is not required here.`);
+    return;
+  }
+
+  // ADR 0055 / task 1025: in ci mode there are two publish paths. A machine with
+  // no GitHub push credential (a dev box) ships SERVER-MEDIATED — it uploads its
+  // branch to the GDS, which pushes + opens the PR with the server's credential —
+  // so gh is NOT needed here. Resolve the same path ship.js will take and skip the
+  // gh requirement when it's server-mediated.
+  let via = 'local';
+  try {
+    via = require('./ship.js').pushVia();
+  } catch (_) {
+    /* keep 'local'; the gh checks below are the safe, stricter default */
+  }
+  if (via === 'server') {
+    ok('deploy', `Deploy mode: ci (server-mediated publish) — this machine has no GitHub push credential, so the GDS pushes your branch + opens the PR for you. gh is not required here. NOTE: on a dev box, run /builder-reauth (browser) first so your session is a real cli session, not the box-scoped one.`);
+    return;
+  }
+
+  // ci mode, local push path → gh is on the critical path for this builder's own ship.
+  let installed = false;
+  try {
+    const v = spawnSync('gh', ['--version'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    installed = !!v && !v.error && v.status === 0;
+  } catch (_) {
+    installed = false;
+  }
+  if (!installed) {
+    fail('deploy', `Deploy mode is 'ci' but the GitHub CLI (gh) is not launchable. ci-mode ship opens a PR via gh — install it (https://cli.github.com) then 'gh auth login', or ships will reach confirmed and fail to land.`);
+    return;
+  }
+
+  let authed = false;
+  try {
+    const a = spawnSync('gh', ['auth', 'status'], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    authed = !!a && !a.error && a.status === 0;
+  } catch (_) {
+    authed = false;
+  }
+  if (authed) {
+    ok('deploy', `Deploy mode: ci — gh CLI present + authenticated; ci-mode ship can open + auto-merge its PR.`);
+  } else {
+    fail('deploy', `Deploy mode is 'ci' and gh is installed but NOT authenticated. Run 'gh auth login' (needs repo scope) or ci-mode ships will fail at 'gh pr create'.`);
+  }
+}
+
+// --------------------------------------------------------------------------
+// main
+// --------------------------------------------------------------------------
+(async () => {
+  console.log(`${C.bold}GDS Doctor${C.reset} — local-machine health check`);
+  await checkSession();
+  checkToolchain();
+  checkDeployTooling();
+  checkGitPlumbing();
+  await checkRepoState();
+  checkEnvironment();
+
+  const fails = findings.filter((f) => f.status === 'fail').length;
+  const warns = findings.filter((f) => f.status === 'warn').length;
+  const oks = findings.filter((f) => f.status === 'ok').length;
+
+  console.log('');
+  if (fails === 0 && warns === 0) {
+    console.log(`${C.green}All ${oks} checks green.${C.reset}`);
+    process.exit(0);
+  }
+  const parts = [];
+  if (fails > 0) parts.push(`${C.red}${fails} fail${C.reset}`);
+  if (warns > 0) parts.push(`${C.yellow}${warns} warn${C.reset}`);
+  parts.push(`${oks} ok`);
+  console.log(`Summary: ${parts.join(', ')}.`);
+  if (fails > 0) {
+    console.log(`Address the fail rows above before continuing builder work.`);
+    process.exit(1);
+  }
+  process.exit(0);
+})().catch((err) => {
+  // Doctor's job is to NEVER throw — every check catches its own exceptions.
+  // If we got here, something is genuinely wrong with the doctor itself.
+  console.error('doctor: unexpected fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/feedback-latest.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// scripts/gds/feedback-latest.js — R13 (BV1.R13): the engine behind the
+// /feedback Claude Code slash command.
+//
+// Resolves the LATEST feedback bundle the Bongos app wrote to
+// ~/CloudBongos/feedback/ (via the shared `latest` pointer in
+// bongos-app/src/handoff.js) and prints it for a Claude Code session:
+//
+//   1. the full prompt.md body (the model-agnostic transcript + ask, R11), and
+//   2. the ABSOLUTE path of every attached frame, on its own line, so Claude's
+//      Read tool can load each image directly.
+//
+// This sidesteps the CLI's unreliable clipboard-image paste: Claude reads the
+// frames from disk by path instead of from a pasted blob.
+//
+// Usage:
+//   node scripts/gds/feedback-latest.js            # human/agent-readable dump
+//   node scripts/gds/feedback-latest.js --json     # { id, dir, promptMarkdown, imagePaths }
+//   node scripts/gds/feedback-latest.js --base DIR # override bundle base dir (tests)
+//
+// Local + read-only: it reads files under your home dir. No GDS session, no
+// network — so it works on any machine the Bongos app runs on.
+
+'use strict';
+
+const path = require('node:path');
+const { resolveLatest, feedbackBaseDir } = require(
+  path.join(__dirname, '..', '..', 'bongos-app', 'src', 'handoff.js'),
+);
+
+function parseArgs(argv) {
+  const out = { json: false, base: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--base') out.base = argv[++i];
+    else if (a.startsWith('--base=')) out.base = a.slice('--base='.length);
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const baseDir = args.base || feedbackBaseDir();
+
+  const latest = await resolveLatest(baseDir);
+
+  if (!latest) {
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, reason: 'no_bundle', baseDir })}\n`);
+    } else {
+      process.stdout.write(
+        `No feedback bundle found under ${baseDir}.\n`
+        + 'Record a walkthrough in the Bongos app and stop the capture — that '
+        + 'writes a bundle here — then run /feedback again.\n',
+      );
+    }
+    return;
+  }
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      id: latest.id,
+      dir: latest.dir,
+      promptPath: latest.promptPath,
+      imagePaths: latest.imagePaths,
+      promptMarkdown: latest.promptMarkdown,
+    }, null, 2)}\n`);
+    return;
+  }
+
+  const lines = [];
+  lines.push(`# Latest Bongos feedback bundle — ${latest.id}`);
+  lines.push(`# dir: ${latest.dir}`);
+  lines.push('');
+  lines.push('---- prompt.md ----');
+  lines.push('');
+  lines.push(latest.promptMarkdown.trimEnd());
+  lines.push('');
+  lines.push('---- attached frames (Read each path to see the screenshots) ----');
+  if (latest.imagePaths.length === 0) {
+    lines.push('(none — this session had no salient frames or markup)');
+  } else {
+    for (const p of latest.imagePaths) lines.push(p);
+  }
+  lines.push('');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`feedback-latest: ${err.message}\n`);
+  process.exitCode = 1;
+});

package/scripts/gds/fetch-art-key.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// scripts/gds/fetch-art-key.js — mirror the GDS-delivered SHARED Gemini key into
+// the local session file so a newcomer's art pipeline can use it (task 1281).
+//
+// The art pipeline (modules/art-pipeline/pipeline/gen_api.py) runs LOCALLY and can't call the API
+// per generation, so SessionStart runs this once: GET /api/gds/me/art-key and,
+// based on the builder's live rank, write or remove the `shared_gemini_api_key`
+// field in ~/.config/otb/gds-session.json. gen_api.py reads that field as a
+// fallback BELOW the builder's own key — so own key always wins, and a newcomer
+// with no own key falls back to the shared one we pay for.
+//
+// This is the SELF-HEALING source of truth for that slot, re-derived every
+// session from the server's rank check:
+//   entitled (xenos) + key delivered → write shared_gemini_api_key
+//   not entitled (thetes+)           → remove it (promotion withdraws the key)
+//   entitled but server has no key   → no-op (pipeline shows its normal message)
+//
+// Best-effort by construction (mirrors fetch-sound-prefs.js):
+//   - No session / not signed in → no-op.
+//   - API down / timeout / any error → leave the file untouched, no-op.
+//   - Read-modify-write preserves every other session field (token, own key, …):
+//     we loadSession() the full object, change ONE field, saveSession() it back.
+
+'use strict';
+
+const { loadSession, saveSession, API_BASE } = require('./cli-lib');
+
+const FETCH_TIMEOUT_MS = 4000;
+const SHARED_FIELD = 'shared_gemini_api_key';
+// The builder's OWN key (task 1013) lands in the same local slot the pipeline
+// already prefers — gemini_api_key. We tag it `_managed` so that REMOVING the key
+// on the server withdraws OUR copy on the next sync WITHOUT clobbering a legacy
+// key a builder hand-entered locally via the CLI (which carries no marker).
+const OWN_FIELD = 'gemini_api_key';
+const OWN_MANAGED_FLAG = 'gemini_api_key_managed';
+
+async function main() {
+  const session = await loadSession();
+  if (!session || !session.token) return; // not signed in — nothing to manage
+
+  const base = session.api_base || API_BASE;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  let data = null;
+  try {
+    const res = await fetch(`${base}/api/gds/me/art-key`, {
+      headers: {
+        Authorization: `Bearer ${session.token}`,
+        'User-Agent': 'amazonprimea-fetch-art-key/1.0',
+      },
+      signal: ctrl.signal,
+    });
+    if (!res.ok) return; // 401 / 5xx — leave any existing key alone
+    data = await res.json();
+  } catch (_) {
+    return; // network/timeout — no-op
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!data || typeof data !== 'object') return;
+
+  // Decide the change against the current file contents.
+  let changed = false;
+  if (data.entitled && typeof data.shared_key === 'string' && data.shared_key) {
+    // Entitled and a key was delivered → store it (only if different).
+    if (session[SHARED_FIELD] !== data.shared_key) {
+      session[SHARED_FIELD] = data.shared_key;
+      changed = true;
+    }
+  } else if (data.entitled === false) {
+    // Explicitly not entitled (e.g. promoted to Thetes) → withdraw the key.
+    if (Object.prototype.hasOwnProperty.call(session, SHARED_FIELD)) {
+      delete session[SHARED_FIELD];
+      changed = true;
+    }
+  }
+  // entitled but no key delivered (configured:false) → leave the file as-is.
+
+  // The builder's OWN server-stored key (task 1013 / ADR 0073). Mirrors the
+  // shared-key logic but writes the gemini_api_key slot (which wins over the
+  // shared key in the pipeline cascade) and only ever removes a copy WE wrote.
+  if (typeof data.own_key === 'string' && data.own_key) {
+    if (session[OWN_FIELD] !== data.own_key || session[OWN_MANAGED_FLAG] !== true) {
+      session[OWN_FIELD] = data.own_key;
+      session[OWN_MANAGED_FLAG] = true;
+      changed = true;
+    }
+  } else if (data.own_key_set === false && session[OWN_MANAGED_FLAG] === true) {
+    // Server says no own key, and the local copy is one we manage → withdraw it.
+    delete session[OWN_FIELD];
+    delete session[OWN_MANAGED_FLAG];
+    changed = true;
+  }
+  // own_key_set true but no plaintext delivered (storage not configured), or a
+  // legacy local key with no marker → leave the file as-is.
+
+  if (changed) {
+    try {
+      await saveSession(session); // writes the full object back, mode 600
+    } catch (_) {
+      /* best-effort — a failed write just leaves the pipeline to fall through */
+    }
+  }
+}
+
+main().then(() => process.exit(0)).catch(() => process.exit(0));

package/scripts/gds/fetch-sound-prefs.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// scripts/gds/fetch-sound-prefs.js — mirror the builder's per-sound prefs to a
+// local file the offline player reads (V3.R91 / #786).
+//
+// The toggle lives server-side (builders.sound_prefs), but the sound plays from
+// a LOCAL Stop hook + ship.js via .claude/sounds/play.js — which can't make a
+// network call on every turn. So SessionStart runs this once: fetch
+// GET /api/gds/me/sound-prefs and write its effective_map to
+// ~/.config/otb/sound-prefs.json. play.js reads that file and skips muted sounds.
+//
+// Best-effort by construction:
+//   - No session token / not signed in → no-op (player fails OPEN = plays all).
+//   - API down / timeout / any error → leave any existing file untouched, no-op.
+//   - A stale file is harmless: it just reflects the builder's last-known prefs
+//     until the next successful session start refreshes it.
+//
+// Mirrors the auth + atomic-write patterns in pull-memory.js.
+
+'use strict';
+
+const fs   = require('node:fs');
+const os   = require('node:os');
+const path = require('node:path');
+const { readSessionToken } = require('./cli-lib');
+
+const FETCH_TIMEOUT_MS = 4000;
+
+
+const PREFS_PATH = require('../../src/instance-config').configPath('sound-prefs.json');
+
+function writeAtomic(targetPath, contents) {
+  const dir = path.dirname(targetPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.sound-prefs.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, contents);
+  fs.renameSync(tmp, targetPath);
+}
+
+async function main() {
+  const sess = readSessionToken();
+  if (!sess) return; // not signed in — player fails open
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  let soundData = null;
+  let eventData = null;
+  try {
+    // Fetch both prefs in parallel; a failure on either leaves both at their
+    // existing cached state (fail-open).
+    const [soundRes, eventRes] = await Promise.all([
+      fetch(`${sess.apiBase}/api/gds/me/sound-prefs`, {
+        headers: { Authorization: `Bearer ${sess.token}`, 'User-Agent': 'amazonprimea-fetch-sound-prefs/1.0' },
+        signal: ctrl.signal,
+      }),
+      fetch(`${sess.apiBase}/api/gds/me/event-sound-prefs`, {
+        headers: { Authorization: `Bearer ${sess.token}`, 'User-Agent': 'amazonprimea-fetch-sound-prefs/1.0' },
+        signal: ctrl.signal,
+      }),
+    ]);
+    if (!soundRes.ok && !eventRes.ok) return;
+    if (soundRes.ok) soundData = await soundRes.json();
+    if (eventRes.ok) eventData = await eventRes.json();
+  } catch (_) {
+    return; // network/timeout — no-op
+  } finally {
+    clearTimeout(timer);
+  }
+
+  // effective_map is { <sound>: <bool> } for every known sound (defaults
+  // already applied server-side); volume is the master 0-100 (#788). The local
+  // file shape is { sounds: {...}, volume: N, event_sounds: {...} } — play.js
+  // reads both (and still tolerates the legacy flat { <sound>: <bool> } shape).
+  const map = soundData && soundData.effective_map;
+  if (!map || typeof map !== 'object') return;
+  const volume = typeof soundData.volume === 'number' ? soundData.volume : 100;
+  // event_sounds: { <eventId>: <wavName> } — resolved wav per event so the
+  // hook can call playSound(wavName) without knowing the variant→wav mapping.
+  const eventSounds = (eventData && typeof eventData.effective_wav === 'object')
+    ? eventData.effective_wav
+    : {};
+  try {
+    writeAtomic(PREFS_PATH, JSON.stringify({ sounds: map, volume, event_sounds: eventSounds }));
+  } catch (_) {
+    /* best-effort — a failed write just leaves the player to fail open */
+  }
+}
+
+main().then(() => process.exit(0)).catch(() => process.exit(0));