@bongos/core 1.24.9 → 1.24.10

package/modules/market-watch/routes/settings.js

@@ -0,0 +1,128 @@
+// modules/market-watch/routes/settings.js — the owner's Market Watch settings (task 1004938,
+// goal 1000137). The page is the hall's /market-watch-settings, built to
+// docs/design/mocks/market-watch/settings.html (option B, the fuel gauge).
+//
+//   GET    /market-watch/settings      the switch, cap, cadence, this month's spend, the next
+//                                      run, recent runs, and whether a key is set
+//   PATCH  /market-watch/settings      change any of { enabled, monthly_cap_usd, cadence }
+//   PUT    /market-watch/settings/key  save or replace the project's Anthropic key  { key }
+//   DELETE /market-watch/settings/key  clear it
+//
+// rank: archon — the owner seat. Two server-side gates on every route, the read included
+// (ADR 0016; the page hiding a control is never the wall):
+//   1. requirePermission('project.settings.manage') — the catalog atom for "the project's
+//      own live knobs" (modules/government/catalog.js, floor metic). Module routes gate on
+//      atoms, never on a rank gate (tests/government_require_permission.mjs).
+//   2. ownerSeat — the owner seat is every active Archon (government leads.ownerOf), and
+//      the task says owner-only, so a Metic who holds the atom is still refused 403
+//      rank_forbidden. No archon-floor atom names this authority, and borrowing an
+//      unrelated one would name the wrong authority (the scouting holdout's reasoning in
+//      that test). The security_sensitive check in lifecycle's task-write-routes is the
+//      precedent for an archon check behind a wider atom.
+// The read is owner-only too: it carries the project's AI spend and whether its key is set.
+//
+// The key is write-only. No route returns it or any part of it; the body field is named
+// `key`, which the audit middleware redacts, and no log line here carries the body.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const settings = require('../settings');
+const { projectKey } = require('../seed');
+
+const log = api.logger('market-watch');
+
+const MAX_KEY_BODY = 512;
+const KEY_MESSAGES = {
+  key_required: 'Paste the key.',
+  key_wrong_length: 'That does not look like an Anthropic key. Paste the whole key.',
+  key_has_spaces: 'That does not look like an Anthropic key. Paste it with no spaces.',
+};
+
+// The project is this instance's own public origin, as the run and the seed read it.
+function currentProject() {
+  try { return projectKey(api.branding().domains.publicOrigin); } catch (_) { return null; }
+}
+
+function ceilingUsd() {
+  try { return require('../research').itemCeilingUsd(); } catch (_) { return null; }
+}
+
+function storageConfigured() {
+  try { return api.secretBox.isConfigured() === true; } catch (_) { return false; }
+}
+
+module.exports = function buildMarketWatchSettingsRouter(deps = {}) {
+  const router = express.Router();
+  // Seams for the tests: the pool, the project and the box. Production passes nothing.
+  const pool = () => deps.pool || api.pool;
+  const project = () => (deps.project !== undefined ? deps.project : currentProject());
+  const box = () => deps.secretBox || api.secretBox;
+  const isStorageConfigured = () => (deps.secretBox ? deps.secretBox.isConfigured() === true : storageConfigured());
+
+  // The owner seat, checked after the atom: holding project.settings.manage is not enough.
+  function ownerSeat(req, res, next) {
+    const actual = req.builder && req.builder.rank;
+    if (!api.rankMeetsThreshold(actual, ['archon'])) {
+      return res.fail('rank_forbidden', 403, { required: ['archon'], actual: actual || null, reason: 'Only the project owner can see or change Market Watch settings.' });
+    }
+    return next();
+  }
+
+  function withProject(res) {
+    const p = project();
+    if (!p) res.fail('project_origin_unset', { status: 409, message: 'This project has no public address set, so Market Watch cannot tell which project it is.' });
+    return p;
+  }
+
+  async function view(p) {
+    return settings.readView(pool(), p, {
+      now: deps.now ? new Date(deps.now()) : new Date(),
+      ceilingUsd: deps.ceilingUsd !== undefined ? deps.ceilingUsd : ceilingUsd(),
+      storageConfigured: isStorageConfigured(),
+    });
+  }
+
+  router.get('/market-watch/settings', api.requireBuilder, api.requirePermission('project.settings.manage'), ownerSeat, api.asyncHandler('GET /market-watch/settings', async (req, res) => {
+    const p = withProject(res);
+    if (!p) return;
+    res.json(await view(p));
+  }));
+
+  router.patch('/market-watch/settings', api.requireBuilder, api.requirePermission('project.settings.manage'), ownerSeat, api.asyncHandler('PATCH /market-watch/settings', async (req, res) => {
+    // Strict field list (unknown fields refused by the envelope); the values are checked by
+    // settings.parsePatch, the one validator the tests also run.
+    if (api.validateOrRespond(req, res, { enabled: {}, monthly_cap_usd: {}, cadence: {} })) return;
+    const parsed = settings.parsePatch(req.body);
+    if (parsed.error) return res.fail(parsed.error, { status: 400, message: parsed.message });
+    const p = withProject(res);
+    if (!p) return;
+    const saved = await settings.writeSettings(pool(), p, parsed.patch, req.builder.id);
+    log.info({ builder_id: req.builder.id, fields: Object.keys(parsed.patch), enabled: saved.enabled }, 'market watch settings changed');
+    res.json(await view(p));
+  }));
+
+  router.put('/market-watch/settings/key', api.requireBuilder, api.requirePermission('project.settings.manage'), ownerSeat, api.asyncHandler('PUT /market-watch/settings/key', async (req, res) => {
+    if (api.validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: MAX_KEY_BODY } })) return;
+    const p = withProject(res);
+    if (!p) return;
+    if (!isStorageConfigured()) {
+      return res.fail('storage_not_configured', { status: 409, message: 'Key storage is not set up on this project yet.' });
+    }
+    const out = await settings.setKey(pool(), p, req.body.key, req.builder.id, { encrypt: (s) => box().encrypt(s) });
+    if (out.error) return res.fail(out.error, { status: 400, message: KEY_MESSAGES[out.error] || 'That key could not be saved.' });
+    log.info({ builder_id: req.builder.id }, 'market watch key saved');
+    res.json(await view(p));
+  }));
+
+  router.delete('/market-watch/settings/key', api.requireBuilder, api.requirePermission('project.settings.manage'), ownerSeat, api.asyncHandler('DELETE /market-watch/settings/key', async (req, res) => {
+    const p = withProject(res);
+    if (!p) return;
+    const out = await settings.clearKey(pool(), p, req.builder.id);
+    log.info({ builder_id: req.builder.id, removed: out.removed }, 'market watch key cleared');
+    res.json(await view(p));
+  }));
+
+  return router;
+};

package/modules/market-watch/settings.js

@@ -0,0 +1,207 @@
+'use strict';
+
+// modules/market-watch/settings.js — the owner's Market Watch settings (task 1004938, goal
+// 1000137). The design of record is docs/design/mocks/market-watch/settings.html, option B,
+// the fuel gauge.
+//
+// What the owner sets here, and what reads it back:
+//
+//   enabled          the watch switch. The weekly run's first pre-check (run.js precheck)
+//                    reads it through store.readSettings: off means the next due tick
+//                    records a skipped run with reason 'off' and spends nothing.
+//   monthly_cap_usd  the monthly AI cap. The run checks it before the run and before every
+//                    item (run.js capAllows).
+//   cadence          weekly | biweekly | monthly (run.js isDue, db.CADENCE_DAYS).
+//   the key          the project's own Anthropic key, sealed by key.js sealProjectKey into
+//                    the columns key.js readProjectKey opens (market_watch_002_run.sql).
+//
+// THE KEY IS WRITE-ONLY. It can be replaced or cleared, never read back: the view answers
+// key_set true or false and nothing else, not the last four characters the table keeps
+// for its CHECK constraint, not the date. Nothing in this file decrypts.
+//
+// Every statement here filters on the project key, like db.js and store.js. Validation is
+// pure (parsePatch) so the route and the tests share it.
+
+const db = require('./db');
+const { sealProjectKey } = require('./key');
+
+const CADENCES = Object.freeze(Object.keys(db.CADENCE_DAYS));
+// The cap's bounds, in dollars. The page's slider walks 5 to 60 in steps of 5 (the
+// mockup); the server accepts any whole-cent amount in this range so a cap set by the API
+// is not refused for being off the slider's grid.
+const MIN_CAP_USD = 1;
+const MAX_CAP_USD = 1000;
+const PATCH_FIELDS = Object.freeze(['enabled', 'monthly_cap_usd', 'cadence']);
+// How many recent runs the strip shows, and how many of them the run estimate averages.
+const RECENT_RUNS = 6;
+const ESTIMATE_FROM = 3;
+
+// parsePatch(body) → { patch } | { error, message }. At least one known field; no others.
+function parsePatch(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return { error: 'bad_settings', message: 'Send the settings to change.' };
+  const unknown = Object.keys(body).filter((k) => !PATCH_FIELDS.includes(k));
+  if (unknown.length) return { error: 'bad_settings', message: `Unknown setting: ${unknown.join(', ')}.` };
+  const patch = {};
+  if (body.enabled !== undefined) {
+    if (typeof body.enabled !== 'boolean') return { error: 'bad_settings', message: 'enabled is true or false.' };
+    patch.enabled = body.enabled;
+  }
+  if (body.monthly_cap_usd !== undefined) {
+    const n = body.monthly_cap_usd;
+    if (typeof n !== 'number' || !Number.isFinite(n) || n < MIN_CAP_USD || n > MAX_CAP_USD) {
+      return { error: 'bad_cap', message: `The monthly cap is between $${MIN_CAP_USD} and $${MAX_CAP_USD}.` };
+    }
+    patch.monthly_cap_usd = Math.round(n * 100) / 100;
+  }
+  if (body.cadence !== undefined) {
+    if (!CADENCES.includes(body.cadence)) return { error: 'bad_cadence', message: `cadence is one of ${CADENCES.join(', ')}.` };
+    patch.cadence = body.cadence;
+  }
+  if (!Object.keys(patch).length) return { error: 'bad_settings', message: 'Send at least one setting to change.' };
+  return { patch };
+}
+
+// One row per project, created on the first write with the defaults every unconfigured
+// project already reads (db.DEFAULT_SETTINGS), so a first write of one field never
+// invents the others.
+const UPSERT_SQL = `
+  INSERT INTO market_watch_settings (project, enabled, monthly_cap_usd, cadence, updated_by, updated_at)
+  VALUES ($1, COALESCE($2::boolean, $6::boolean), COALESCE($3::numeric, $7::numeric), COALESCE($4::text, $8::text), $5, now())
+  ON CONFLICT (project) DO UPDATE SET
+    enabled         = COALESCE($2::boolean, market_watch_settings.enabled),
+    monthly_cap_usd = COALESCE($3::numeric, market_watch_settings.monthly_cap_usd),
+    cadence         = COALESCE($4::text, market_watch_settings.cadence),
+    updated_by      = $5,
+    updated_at      = now()
+  RETURNING enabled, monthly_cap_usd, cadence`;
+
+async function writeSettings(pool, project, patch, builderId) {
+  const d = db.DEFAULT_SETTINGS;
+  const v = (k) => (patch[k] === undefined ? null : patch[k]);
+  const { rows: [r] } = await pool.query(UPSERT_SQL, [
+    need(project), v('enabled'), v('monthly_cap_usd'), v('cadence'), builderId,
+    d.enabled, d.monthly_cap_usd, d.cadence,
+  ]);
+  return { enabled: r.enabled === true, monthly_cap_usd: Number(r.monthly_cap_usd), cadence: r.cadence };
+}
+
+const SET_KEY_SQL = `
+  INSERT INTO market_watch_settings (project, anthropic_key_enc, anthropic_key_last4, anthropic_key_set_at, updated_by, updated_at)
+  VALUES ($1, $2, $3, now(), $4, now())
+  ON CONFLICT (project) DO UPDATE SET
+    anthropic_key_enc    = EXCLUDED.anthropic_key_enc,
+    anthropic_key_last4  = EXCLUDED.anthropic_key_last4,
+    anthropic_key_set_at = now(),
+    updated_by           = EXCLUDED.updated_by,
+    updated_at           = now()
+  RETURNING project`;
+
+// setKey(pool, project, raw, builderId, { encrypt }) → { key_set: true } | { error }.
+// The key goes through key.js sealProjectKey, the writer's half of the one reader the
+// run uses, so what is stored is exactly what readProjectKey opens.
+async function setKey(pool, project, raw, builderId, { encrypt } = {}) {
+  const sealed = sealProjectKey(raw, { encrypt });
+  if (sealed.error) return { error: sealed.error };
+  await pool.query(SET_KEY_SQL, [need(project), sealed.key_enc, sealed.last4, builderId]);
+  return { key_set: true };
+}
+
+const CLEAR_KEY_SQL = `
+  UPDATE market_watch_settings
+     SET anthropic_key_enc = NULL, anthropic_key_last4 = NULL, anthropic_key_set_at = NULL,
+         updated_by = $2, updated_at = now()
+   WHERE project = $1 AND anthropic_key_enc IS NOT NULL
+  RETURNING project`;
+
+async function clearKey(pool, project, builderId) {
+  const { rows } = await pool.query(CLEAR_KEY_SQL, [need(project), builderId]);
+  return { key_set: false, removed: rows.length > 0 };
+}
+
+const KEY_SET_SQL = `SELECT (anthropic_key_enc IS NOT NULL) AS key_set FROM market_watch_settings WHERE project = $1`;
+const ACTIVE_ITEMS_SQL = `SELECT count(*)::int AS n FROM market_watch_items WHERE project = $1 AND status = 'active'`;
+// The newest run of ANY kind, the seed included: what the poller's clock counts from
+// (store.js lastRun). The settings strip hides the seed run, the clock does not.
+const LAST_RUN_SQL = `SELECT created_at FROM market_watch_runs WHERE project = $1 ORDER BY created_at DESC, id DESC LIMIT 1`;
+
+// runEstimate(recentRuns, activeItems, ceilingUsd) → { usd, basis }. What the next run is
+// likely to spend: the mean of the last few runs that ran and cost something, or, before
+// there are any, every active item at its whole ceiling (an upper bound, said so).
+function runEstimate(recentRuns, activeItems, ceilingUsd) {
+  const ran = recentRuns.filter((r) => (r.status === 'done' || r.status === 'partial') && r.cost_usd > 0).slice(0, ESTIMATE_FROM);
+  if (ran.length) return { usd: round2(ran.reduce((s, r) => s + r.cost_usd, 0) / ran.length), basis: 'recent' };
+  const n = Number(activeItems) || 0;
+  if (n > 0 && Number.isFinite(ceilingUsd) && ceilingUsd > 0) return { usd: round2(n * ceilingUsd), basis: 'ceiling' };
+  return { usd: null, basis: 'none' };
+}
+
+// nextRun(enabled, lastRunAt, cadence, now) → { state, due_at }. 'paused' when the switch
+// is off; 'soon' when a run is already due (the poller looks every hour); else the date.
+function nextRun(enabled, lastRunAt, cadence, now) {
+  if (!enabled) return { state: 'paused', due_at: null };
+  const due = db.nextRunDue(lastRunAt, cadence);
+  if (!due || due.getTime() <= new Date(now).getTime()) return { state: 'soon', due_at: null };
+  return { state: 'scheduled', due_at: due.toISOString() };
+}
+
+// readView(pool, project, { now, ceilingUsd, storageConfigured }) — everything the page
+// draws, and nothing secret: the key is a boolean.
+async function readView(pool, project, { now = new Date(), ceilingUsd = null, storageConfigured = false } = {}) {
+  need(project);
+  const [view, { rows: [k] }, { rows: [items] }, { rows: [last] }] = await Promise.all([
+    db.settingsView(pool, { project, now, recent: RECENT_RUNS }),
+    pool.query(KEY_SET_SQL, [project]),
+    pool.query(ACTIVE_ITEMS_SQL, [project]),
+    pool.query(LAST_RUN_SQL, [project]),
+  ]);
+  const s = view.settings;
+  const recent = view.recentRuns.map((r) => ({
+    id: r.id,
+    status: r.status,
+    reason: r.reason || null,
+    created_at: r.created_at,
+    items_total: r.items_total,
+    items_done: r.items_done,
+    cost_usd: r.cost_usd,
+  }));
+  const activeItems = items ? items.n : 0;
+  const estimate = runEstimate(recent, activeItems, ceilingUsd);
+  const spent = round2(view.spentThisMonthUsd);
+  const left = Math.max(0, s.monthly_cap_usd - spent);
+  return {
+    enabled: s.enabled === true,
+    monthly_cap_usd: s.monthly_cap_usd,
+    cadence: s.cadence,
+    configured: s.configured === true,
+    key_set: !!(k && k.key_set === true),
+    storage_configured: storageConfigured === true,
+    spent_this_month_usd: spent,
+    left_this_month_usd: round2(left),
+    month: monthLabel(now),
+    active_items: activeItems,
+    run_estimate_usd: estimate.usd,
+    run_estimate_basis: estimate.basis,
+    runs_left: estimate.usd ? Math.floor(left / estimate.usd) : null,
+    next_run: nextRun(s.enabled === true, last ? last.created_at : null, s.cadence, now),
+    recent_runs: recent,
+    cadences: CADENCES,
+    cap_bounds: { min: MIN_CAP_USD, max: MAX_CAP_USD },
+  };
+}
+
+function monthLabel(now) {
+  return new Date(now).toLocaleString('en-US', { month: 'long', timeZone: 'UTC' }).toLowerCase();
+}
+function round2(n) { return Math.round(Number(n) * 100) / 100; }
+function need(project) {
+  if (typeof project !== 'string' || !project) throw new Error('market-watch settings: a project key is required');
+  return project;
+}
+
+module.exports = {
+  parsePatch, writeSettings, setKey, clearKey, readView,
+  // pure, for the tests
+  runEstimate, nextRun,
+  CADENCES, MIN_CAP_USD, MAX_CAP_USD, PATCH_FIELDS,
+  SQL: { UPSERT_SQL, SET_KEY_SQL, CLEAR_KEY_SQL, KEY_SET_SQL },
+};

package/modules/provisioning/starter-bundles.js

@@ -80,12 +80,9 @@ const ALWAYS_ON_CORE = Object.freeze([
 // investor page: its copy is Cloud Bongos's raise, so offering it to a new project would hand
 // that project someone else's fundraise (task 1004852). `ai-studio` (task 1004916, ADR 0392)
 // bills AI generation through Cloud Bongos's own payment processor account, so it stays on
-// the hub until a project can bring its own billing. `market-watch` (task 1004935) is not
-// hub-only in purpose: it is here because it is still EMPTY (no routes), and a picker entry
-// for a switch that does nothing is worse than none. This list is the one that keeps a
-// default:false module out of the opt-in catalog; the goal 1000137 task that ships the
-// owner's on/off switch moves it to OPTIONAL_MODULES with owner-facing copy.
-const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning', 'npm-release', 'render-deploy', 'raise', 'ai-studio', 'market-watch']);
+// the hub until a project can bring its own billing. `market-watch` sat here while it was
+// empty; task 1004938 shipped the owner's on/off switch and moved it to OPTIONAL_MODULES.
+const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning', 'npm-release', 'render-deploy', 'raise', 'ai-studio']);
 
 // The OPT-IN catalog as the creation picker renders it (BV1.R20, task 1002339):
 // every module an owner may actually choose, in the order the picker lists them,
@@ -148,6 +145,14 @@ const OPTIONAL_MODULES = Object.freeze([
     summary: 'Commands to generate game tiles and sprites, score them against your art rules, and keep a style guide.',
     aliases: Object.freeze(['tileset', 'graphics', 'artwork', 'retro', 'drawing', 'gamedev']),
   }),
+  // task 1004938 (goal 1000137): offered once the owner's switch existed. It runs on the
+  // project's own Anthropic key, under a monthly cap the owner sets, and starts off.
+  Object.freeze({
+    key: 'market-watch',
+    label: 'Market Watch',
+    summary: 'A weekly AI look at your competitors, partners and topics, with a sourced log for each. It runs on your own Anthropic key, under a monthly cap you set.',
+    aliases: Object.freeze(['research', 'rivals', 'intelligence', 'analysis', 'trends', 'landscape']),
+  }),
 ]);
 
 // The opt-in keys alone, for the membership tests the normalizer runs. Derived,

package/modules/ui-design/kit/serve.js

@@ -144,6 +144,7 @@ const STARTER_BUNDLES_FIXTURE = {
     { key: 'discord', label: 'Discord', summary: 'A Discord server that carries your build news, and lets people send ideas and bug reports back.', aliases: ['chatroom', 'talk', 'messaging', 'community', 'announcements', 'notifications'] },
     { key: 'design-styles', label: 'Design styles', summary: 'Extra ways for the AI to style your pages: ready-made looks, a polish pass, and a way to author your own look.', aliases: ['theme', 'branding', 'visual', 'taste', 'aesthetic', 'layout'] },
     { key: 'pixel-art', label: 'Pixel-art tools', summary: 'Commands to generate game tiles and sprites, score them against your art rules, and keep a style guide.', aliases: ['tileset', 'graphics', 'artwork', 'retro', 'drawing', 'gamedev'] },
+    { key: 'market-watch', label: 'Market Watch', summary: 'A weekly AI look at your competitors, partners and topics, with a sourced log for each. It runs on your own Anthropic key, under a monthly cap you set.', aliases: ['research', 'rivals', 'intelligence', 'analysis', 'trends', 'landscape'] },
   ],
 };
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.9",
+  "version": "1.24.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.9",
+      "version": "1.24.10",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.9",
+  "version": "1.24.10",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -10889,5 +10889,11 @@
       "id": "1004989",
       "text": "Modules can now only be priced in cash: credits can no longer price or buy one, and modules that still have an old credit price stay listed as \"price coming\" while their authors are asked to set a cash price."
     }
+  ],
+  "1.24.10": [
+    {
+      "id": "1004938",
+      "text": "The project owner now has a Market Watch settings page where they can switch it on or off, set the monthly AI spending cap and how often it runs, see this month's spend and recent runs, and paste the project's Anthropic key, w"
+    }
   ]
 }

package/src/bongos/module-scope-map.js

@@ -201,6 +201,7 @@ const MODULE_GLOBS = {
     // task 1004941: the rules page (proposals, decisions, the run's prompt fence)
     'tests/market_watch_rules.mjs', 'tests/market_watch_rules_db.mjs',
     'tests/market_watch_ask.mjs', 'tests/market_watch_ask_db.mjs',
+    'tests/market_watch_settings.mjs',
   ],
   // --- builder prefs (wandering/skill/sound/render) + builder-needs ---
   // Carved into modules/builder-settings/ (BV1.R80 / ADR 0093 §1): the five pref

package/src/bongos/serve-internal.js

@@ -1323,9 +1323,9 @@ function mountInternalSurfaces(app) {
   // Claude works for them. Every read behind it is the viewer's own and
   // requireBuilder (GET /me and its /me/* prefs, /specialities), so sign-in is the
   // whole gate; the governing reads it adds are gated by their own routes.
-  // task 1004921: `ai-studio`, the studio's AI pages; every route behind it is the viewer's own.
+  // tasks 1004921 `ai-studio` (the viewer's own routes), 1004938 `market-watch-settings` (no data; owner-only routes).
   const SIGNEDIN_BUILDERS_PAGE_RE =
-    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|ai-studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams|my-agents|commands)(?:\.html)?\/?$/;
+    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|ai-studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams|my-agents|market-watch-settings|commands)(?:\.html)?\/?$/;
   // The diagram image assets under /builders/diagrams/ ride the same tier as the
   // page that embeds them.
   const SIGNEDIN_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.9'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.10'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/hall_nav.mjs

@@ -318,7 +318,9 @@ test('sidebar groups read by audience, in order', () => {
   // the steering surfaces because that is what it is — the owner's third release gate.
   // 'fleet' (task 1001949) follows it at the metic floor of `provisioning.fleet.manage`:
   // what each hosted project costs is an operator surface, like the rest of this group.
-  assert.deepEqual(nav[4].items.map((i) => i.id), ['watch', 'gate', 'sessions', 'project-settings', 'deploy', 'fleet', 'government']);
+  // 'market-watch-settings' (task 1004938) is the owner's Market Watch switch and AI cap,
+  // archon like its four routes, and dropped where the market-watch module is off.
+  assert.deepEqual(nav[4].items.map((i) => i.id), ['watch', 'gate', 'sessions', 'project-settings', 'deploy', 'fleet', 'market-watch-settings', 'government']);
 });
 
 test('Economy lives in Docs and points at the reward-schedule page', () => {
@@ -750,7 +752,7 @@ test('no glyph path data reads as an IP address to the release leak scan', () =>
 // block (task 1004713). These drive the real shell and the real gov-positions.js.
 
 const tick = () => new Promise((resolve) => setImmediate(resolve));
-const GOVERNING = ['board-room', 'city', 'watch', 'gate', 'sessions', 'project-settings', 'deploy', 'fleet', 'government'];
+const GOVERNING = ['board-room', 'city', 'watch', 'gate', 'sessions', 'project-settings', 'deploy', 'fleet', 'market-watch-settings', 'government'];
 const lead = (building, title) => ({ kind: 'lead', seat: 'lead:' + building, building, title });
 const block = (held) => ({ held, title: held.length ? held[0].title : null, has_position: held.length > 0 });
 

package/tests/hall_page_gate_map.mjs

@@ -56,6 +56,10 @@ const ORACLE = {
   // settings. Every read behind it is the viewer's own (GET /me, /me/* prefs,
   // /specialities) and requireBuilder, so sign-in is the whole gate.
   '/builders/my-agents': 'requireBuilderPage',
+  // task 1004938: the owner's Market Watch settings. Its read and writes are
+  // owner-only (atom + owner seat) (tests/market_watch_settings.mjs proves the 403s), and the
+  // shell carries no data, so sign-in is the page tier and the routes are the wall.
+  '/builders/market-watch-settings': 'requireBuilderPage',
   '/builders/goals': 'requireBuilderPage',
   // task 1003479: the goal map, on the goal board's tier. task 1004232 (sky part 4):
   // the URL now serves THE PROJECT SKY (the same page as /thinking, in its whole-project

package/tests/market_watch_data_db.mjs

@@ -31,6 +31,8 @@ const MIGRATION_002 = readFileSync(new URL('../modules/market-watch/migrations/m
 const MIGRATION_003 = readFileSync(new URL('../modules/market-watch/migrations/market_watch_003_ask_pool.sql', import.meta.url), 'utf8');
 const run = require('../modules/market-watch/run.js');
 const store = require('../modules/market-watch/store.js');
+const settings = require('../modules/market-watch/settings.js');
+const key = require('../modules/market-watch/key.js');
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
 try {
@@ -295,6 +297,31 @@ try {
     assert.equal(await store.openRun(pool, P), null);
   });
 
+  // task 1004938: the owner's settings writes, on the real table, read back by the run's
+  // own readers (store.readSettings, key.readProjectKey).
+  await check('the settings page writes what the run reads: switch, cap, cadence and the sealed key', async () => {
+    const box = { encrypt: (s) => `v1.iv.tag.${Buffer.from(s).toString('base64url')}`, decrypt: (b) => Buffer.from(b.split('.')[3], 'base64url').toString() };
+    await q(`DELETE FROM market_watch_settings WHERE project = $1`, [OTHER]);
+    // A first write of one field creates the row with the defaults for the rest.
+    assert.deepEqual(await settings.writeSettings(pool, OTHER, { cadence: 'monthly' }, ALICE), { enabled: false, monthly_cap_usd: 20, cadence: 'monthly' });
+    assert.deepEqual(await settings.writeSettings(pool, OTHER, { enabled: true, monthly_cap_usd: 35.5 }, ALICE), { enabled: true, monthly_cap_usd: 35.5, cadence: 'monthly' });
+    const st = store.createStore(pool);
+    assert.equal((await st.readSettings(OTHER)).enabled, true);
+    await settings.writeSettings(pool, OTHER, { enabled: false }, BOB);
+    assert.deepEqual(await st.readSettings(OTHER), { enabled: false, monthly_cap_usd: 35.5, cadence: 'monthly', configured: true });
+    assert.deepEqual(await settings.setKey(pool, OTHER, 'sk-ant-api03-db-test-key-LMNO', ALICE, { encrypt: box.encrypt }), { key_set: true });
+    assert.equal(await key.readProjectKey(pool, OTHER, { decrypt: box.decrypt }), 'sk-ant-api03-db-test-key-LMNO');
+    const view = await settings.readView(pool, OTHER, { ceilingUsd: 0.27, storageConfigured: true });
+    assert.equal(view.key_set, true);
+    assert.ok(!JSON.stringify(view).includes('LMNO'), 'the view never carries the key or its last four');
+    assert.deepEqual(await settings.clearKey(pool, OTHER, ALICE), { key_set: false, removed: true });
+    assert.deepEqual(await settings.clearKey(pool, OTHER, ALICE), { key_set: false, removed: false });
+    assert.equal(await key.readProjectKey(pool, OTHER, { decrypt: box.decrypt }), null);
+    // P's row was never touched by OTHER's writes.
+    assert.notEqual((await st.readSettings(P)).monthly_cap_usd, 35.5);
+    await q(`DELETE FROM market_watch_settings WHERE project = $1`, [OTHER]);
+  });
+
   await check('one open run per project, and the key must be a secret-box blob', async () => {
     await q(`INSERT INTO market_watch_runs (project, status, trigger) VALUES ($1, 'queued', 'manual')`, [OTHER]);
     await refused(`INSERT INTO market_watch_runs (project, status, trigger) VALUES ($1, 'running', 'poller')`, [OTHER], 'a second open run');

package/tests/market_watch_module.mjs

@@ -2,7 +2,7 @@
 // the loader, and an instance boots with it present and DISABLED (task 1004935, goal
 // 1000137). DB-free, so it runs in the unit lane.
 //
-// Task 1004940 mounted its first routes (the weekly ask); task 1004936 gave it its tables and a one-shot hub seed
+// Task 1004940 mounted its first routes (the weekly ask), task 1004938 the owner settings routes; task 1004936 gave it its tables and a one-shot hub seed
 // poller (tests/market_watch_data.mjs covers those). What this file
 // pins is everything the later Market Watch tasks will stand on:
 //   1. the manifest validates, ships default:false, and declares spend.requiresPayer;
@@ -40,6 +40,7 @@ test('the manifest validates, ships disabled, declares a payer, and contributes
   assert.equal(c.migrations, true);
   for (const p of ['hub-seed', 'weekly-run', 'weekly-ask']) assert.ok(c.pollers.includes(p), `poller ${p}`);
   assert.ok(c.routes.includes('ask'), 'the weekly ask routes');
+  assert.ok(c.routes.includes('settings'), 'the owner settings routes (task 1004938, tests/market_watch_settings.mjs)');
   assert.ok(c.uiSections.includes('weekly-ask'), 'the weekly ask hall slice (hallWidgetScripts needs a uiSection)');
   assert.ok(c.routes.includes('rules'), 'the rules page routes (task 1004941)');
 });
@@ -72,14 +73,17 @@ test('the spend guard bites it: an open door with no payer cannot enable it; a c
   assert.equal(mods.resolveModules({ instance: on, registry, spendGuard: { joinDoorOpen: false, payer: null }, warn: silent })[KEY], true);
 });
 
-test('it has a scope-roster key, and the creation picker does not offer it while it is empty', () => {
+test('it has a scope-roster key, and the creation picker offers it, off, now its switch exists', () => {
   assert.ok(Array.isArray(scopeMap.MODULE_GLOBS[KEY]) && scopeMap.MODULE_GLOBS[KEY].includes('modules/market-watch/'));
   // Every entry is an exact path or a dir prefix (the touches[] convention has no
   // wildcards), and this test's own path resolves to the module's scope.
   for (const g of scopeMap.MODULE_GLOBS[KEY]) assert.ok(!g.includes('*'), `wildcard glob never matches: ${g}`);
   assert.ok(scopeMap.MODULE_GLOBS[KEY].includes('tests/market_watch_module.mjs'));
-  assert.ok(bundles.HUB_ONLY_MODULES.includes(KEY));
-  assert.ok(!bundles.OPTIONAL_MODULES.some((m) => m.key === KEY));
+  // Task 1004938 shipped the owner's switch (routes/settings.js), so it left the hub-only
+  // list for the opt-in catalog, with owner-facing copy. Opt-in, never always-on.
+  assert.ok(!bundles.HUB_ONLY_MODULES.includes(KEY));
+  const offered = bundles.OPTIONAL_MODULES.find((m) => m.key === KEY);
+  assert.ok(offered && offered.label && offered.summary, 'offered with copy an owner can read');
   assert.ok(!bundles.ALWAYS_ON_CORE.includes(KEY));
 });