@bongos/core 1.24.9 → 1.24.11

package/modules/hall-ui/public/watch.html

@@ -165,8 +165,8 @@
      chrome exists before the page script runs. -->
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
-<script src="/builders/craft-mode.js?v=2026-10-09-living3"></script>
-<script src="/builders/shell.js?v=2026-10-25-escape"></script>
+<script src="/builders/craft-mode.js?v=2026-10-30-market-watch"></script>
+<script src="/builders/shell.js?v=2026-10-30-market-watch"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- shared component kit (window.OTBKit) — tabs, ledger, pager (task 2166). -->

package/modules/hall-ui/public/work.html

@@ -173,8 +173,8 @@
      time so the chrome exists before the deferred page scripts execute. -->
 <script src="/builders/dom-utils.js?v=2026-10-25-escape"></script>
 <script src="/builders/shell-trail.js?v=2026-10-08-city-tab"></script>
-<script src="/builders/craft-mode.js?v=2026-10-09-living3"></script>
-<script src="/builders/shell.js?v=2026-10-25-escape"></script>
+<script src="/builders/craft-mode.js?v=2026-10-30-market-watch"></script>
+<script src="/builders/shell.js?v=2026-10-30-market-watch"></script>
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <!-- task 1004727: the ONE karma vote control every task/idea list renders -->

package/modules/hall-ui/records/market-watch-settings.md

@@ -0,0 +1,11 @@
+# Market Watch settings, at /market-watch-settings (task 1004938)
+
+**The owner's fuel gauge for Market Watch (goal 1000137), built to `docs/design/mocks/market-watch/settings.html`, option B.** One panel: the gauge (spend this month against the monthly AI cap, with a faint arc for what the next run will use), the on/off pill, the cap slider, the cadence chips (weekly, every 2 weeks, monthly), the strip of recent runs, and the project's Anthropic key. Five things it settled:
+
+- **The routes are the wall, not the page.** `GET`/`PATCH /market-watch/settings` and `PUT`/`DELETE /market-watch/settings/key` are owner-only: the `project.settings.manage` atom, then an in-route owner-seat (Archon) check (modules/market-watch/routes/settings.js). The shell joins `SIGNEDIN_BUILDERS_PAGE_RE` and holds no data; a 403 draws the owner-only panel and a 404 (module off, so its routes are not mounted) the "turn the module on" panel. The nav item sits in Government, `archon`, `module: 'market-watch'`.
+- **The key is write-only.** The page learns `key_set` and nothing else, not the last four. The field is emptied before the request goes out; Clear asks twice by turning into its own question.
+- **The page redraws from the server's answer.** Every write returns the whole view, so the gauge never shows a value the server did not store.
+- **The strip is the run ledger, oldest left.** A ran run shows the names it watched; a skipped one is a hatched dash, with its reason in the cell's label and the legend (`cap reached`, `switched off`, `no key`, …); the dashed tile is the next run and the two after it are empty. When the watch is off the future tiles go. The seed run never shows. At 620px and below the dates stack day over month, or nine tiles overflow at 390px.
+- **Mockup colours were not kept.** The ring, chips and tiles use the hall's `--accent`, `--accent-tint`, `--accent-text`, `--rule*` and `--ok-weak`; the mock's own fonts were dropped for the pack's.
+
+Fixture: `scripts/hall-preview/fixtures/market-watch__settings.json` (the mockup's month). Tests: `tests/market_watch_settings.mjs` (403s for a Metic and a Xenos on all four routes, switching off stops the next run against `run.js`'s own gate, the key never in a response).

package/modules/lifecycle/migrations/lifecycle_018_pay_terms.sql

@@ -0,0 +1,64 @@
+-- lifecycle_018_pay_terms.sql — task 1004990 (goal 1000092; ADR 0385 decision 3
+-- and its 2026-10-29 amendment).
+--
+-- The PROJECT sets the pay, not Bongos. A task can carry zero or more pay terms,
+-- each in the project's own words: a type, an amount and a unit as the project
+-- states them, and a note. A project can also keep standing pay terms that apply
+-- to every task without terms of its own — that is the project's pay policy,
+-- and per the owner's ruling it lives here, in the database, changed on the
+-- project's settings page, never in the branding pack.
+--
+-- A LIFECYCLE MIGRATION, NOT A CORE ONE: these are brand-new tables the lifecycle
+-- module owns (modules/lifecycle/pay-terms.js is their only reader and writer), so
+-- they are lifecycle_-namespaced here, the lifecycle_017_notes precedent — a core
+-- migration is only for a change to a core table.
+--
+-- RECORDS ONLY. Nothing here moves, holds, owes or guarantees money; the amount
+-- is TEXT on purpose, so no code can sum it into a balance (ADR 0387: money stays
+-- with the processor). Bongos suggests no amount: no column has a default.
+--
+-- THE SHAPE IS A HISTORY OF WHOLE SETS. Each change appends one set row (who,
+-- when, which task — NULL for the project's standing terms) and the terms that
+-- set holds. The newest set is current; a set with no terms means "no pay terms".
+-- So the audit trail of who changed what and when is the table itself, and
+-- nothing is ever edited or deleted: a row trigger refuses UPDATE and DELETE on
+-- both tables. (A whole-table wipe is not guarded here: the module-migration gate
+-- keeps module migrations additive and refuses that statement's keyword outright,
+-- and no code path in the tree issues one.)
+
+CREATE TABLE IF NOT EXISTS lifecycle_pay_term_sets (
+  id       bigserial PRIMARY KEY,
+  task_id  bigint REFERENCES tasks(id),          -- NULL = the project's standing terms
+  set_by   bigint NOT NULL REFERENCES builders(id),
+  set_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- The current set for a task (or for the project, task_id NULL): newest first.
+CREATE INDEX IF NOT EXISTS lifecycle_pay_term_sets_current
+  ON lifecycle_pay_term_sets (task_id, set_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS lifecycle_pay_terms (
+  id        bigserial PRIMARY KEY,
+  set_id    bigint NOT NULL REFERENCES lifecycle_pay_term_sets(id),
+  position  smallint NOT NULL CHECK (position BETWEEN 0 AND 9),
+  pay_type  text NOT NULL CHECK (pay_type IN
+              ('cash', 'equity', 'module_share', 'credit_pool', 'non_monetary', 'self_managed')),
+  amount    text CHECK (amount IS NULL OR char_length(amount) BETWEEN 1 AND 64),
+  unit      text CHECK (unit IS NULL OR char_length(unit) BETWEEN 1 AND 32),
+  note      text CHECK (note IS NULL OR char_length(note) BETWEEN 1 AND 500),
+  UNIQUE (set_id, position)
+);
+
+CREATE OR REPLACE FUNCTION lifecycle_pay_terms_refuse_change() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'pay terms are a history: % on % is refused; set a new set of terms instead', TG_OP, TG_TABLE_NAME
+    USING ERRCODE = 'check_violation';
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS lifecycle_pay_term_sets_append_only ON lifecycle_pay_term_sets;
+CREATE TRIGGER lifecycle_pay_term_sets_append_only BEFORE UPDATE OR DELETE ON lifecycle_pay_term_sets
+  FOR EACH ROW EXECUTE FUNCTION lifecycle_pay_terms_refuse_change();
+DROP TRIGGER IF EXISTS lifecycle_pay_terms_append_only ON lifecycle_pay_terms;
+CREATE TRIGGER lifecycle_pay_terms_append_only BEFORE UPDATE OR DELETE ON lifecycle_pay_terms
+  FOR EACH ROW EXECUTE FUNCTION lifecycle_pay_terms_refuse_change();

package/modules/lifecycle/pay-terms.js

@@ -0,0 +1,171 @@
+// modules/lifecycle/pay-terms.js — what a task pays, in the PROJECT's words
+// (task 1004990, goal 1000092; ADR 0385 decision 3 and its 2026-10-29 amendment).
+//
+// The project sets the pay, not Bongos. A task carries zero or more pay terms:
+// a type, and an amount, unit and note exactly as the project states them. A
+// project may also keep STANDING terms (task_id NULL) — its pay policy — which a
+// builder sees on any task that has none of its own. Per the owner's ruling that
+// policy lives in the database (modules/lifecycle/migrations/lifecycle_018_pay_terms.sql) and is changed
+// on the project's settings page, with the table itself as the audit trail; it
+// never lives in the branding pack.
+//
+// THREE RULES THIS FILE HOLDS:
+//   1. Bongos suggests no amount. There is no default and nothing is filled in:
+//      a term the project gave no amount has amount null, and every reader shows
+//      it as "not stated" — never a number Bongos chose.
+//   2. Records only. The amount is text as stated; nothing here parses, sums or
+//      converts it, so no balance or amount owed can come out of it (ADR 0387).
+//   3. A self-managed term always carries SELF_MANAGED_LABEL, so wherever it is
+//      shown it says Bongos moves and guarantees none of that money (plan P2.4).
+//
+// Who may write is decided by the ROUTE (task.edit for a task's terms,
+// project.settings.manage for the project's), on the server (ADR 0016).
+
+const api = require('../../src/module-api');
+
+const PAY_TYPES = ['cash', 'equity', 'module_share', 'credit_pool', 'non_monetary', 'self_managed'];
+const PAY_TYPE_LABELS = {
+  cash: 'Cash',
+  equity: 'Equity',
+  module_share: 'A share of a module',
+  credit_pool: 'A share of a credit pool',
+  non_monetary: 'Not money',
+  self_managed: 'Paid by the project itself',
+};
+const SELF_MANAGED_LABEL = 'Paid by the project on its own systems. Bongos does not move or guarantee this money.';
+const MAX_TERMS = 10;
+const LIMITS = { amount: 64, unit: 32, note: 500 };
+
+// PURE. Checks a list of terms as sent by a client. Returns { terms } (each
+// { pay_type, amount, unit, note }, blanks as null) or { error }. It never fills
+// a field in: what the project did not state stays null.
+function normalizePayTerms(input) {
+  if (!Array.isArray(input)) return { error: 'pay_terms is a list (empty for none).' };
+  if (input.length > MAX_TERMS) return { error: `A task carries at most ${MAX_TERMS} pay terms.` };
+  const terms = [];
+  for (let i = 0; i < input.length; i += 1) {
+    const t = input[i];
+    if (!t || typeof t !== 'object' || Array.isArray(t)) return { error: `pay term ${i + 1} is not an object.` };
+    const extra = Object.keys(t).filter((k) => !['pay_type', 'amount', 'unit', 'note'].includes(k));
+    if (extra.length) return { error: `pay term ${i + 1} has an unknown field: ${extra.join(', ')}.` };
+    if (!PAY_TYPES.includes(t.pay_type)) {
+      return { error: `pay term ${i + 1}: pay_type must be one of ${PAY_TYPES.join(', ')}.` };
+    }
+    const out = { pay_type: t.pay_type };
+    for (const field of ['amount', 'unit', 'note']) {
+      const v = t[field];
+      if (v == null) { out[field] = null; continue; }
+      if (typeof v !== 'string') return { error: `pay term ${i + 1}: ${field} is text, as the project states it.` };
+      const s = v.trim();
+      if (s.length > LIMITS[field]) return { error: `pay term ${i + 1}: ${field} is at most ${LIMITS[field]} characters.` };
+      out[field] = s || null;
+    }
+    terms.push(out);
+  }
+  return { terms };
+}
+
+// PURE. One stored term as every reader shows it. The self-managed label rides on
+// the term itself, so no surface can show the term without it.
+function displayTerm(row) {
+  return {
+    pay_type: row.pay_type,
+    type_label: PAY_TYPE_LABELS[row.pay_type] || row.pay_type,
+    amount: row.amount ?? null,
+    unit: row.unit ?? null,
+    note: row.note ?? null,
+    label: row.pay_type === 'self_managed' ? SELF_MANAGED_LABEL : null,
+  };
+}
+
+// Append one set: the whole list of terms for a task (taskId) or for the project
+// (taskId null). One transaction, so a set is never half-written. Returns the set.
+async function setPayTerms({ taskId = null, terms, builderId }, { db } = {}) {
+  const run = async (client) => {
+    const { rows: [set] } = await client.query(
+      'INSERT INTO lifecycle_pay_term_sets (task_id, set_by) VALUES ($1, $2) RETURNING id, task_id, set_by, set_at',
+      [taskId, builderId]);
+    // Every term in ONE statement, positions from unnest's ordinality, so a set of
+    // ten is one round trip, not ten.
+    if (terms.length) {
+      await client.query(
+        `INSERT INTO lifecycle_pay_terms (set_id, position, pay_type, amount, unit, note)
+         SELECT $1, (t.n - 1)::smallint, t.pay_type, t.amount, t.unit, t.note
+           FROM unnest($2::text[], $3::text[], $4::text[], $5::text[])
+                WITH ORDINALITY AS t(pay_type, amount, unit, note, n)`,
+        [set.id, terms.map((t) => t.pay_type), terms.map((t) => t.amount), terms.map((t) => t.unit), terms.map((t) => t.note)]);
+    }
+    return { set_id: set.id, task_id: set.task_id, set_by: set.set_by, set_at: set.set_at, terms: terms.map(displayTerm) };
+  };
+  if (db) return run(db);
+  return api.withTx(run);
+}
+
+// The current sets for these tasks, plus the project's standing set, in two reads
+// (lifecycle_pay_term_sets_current). Returns Map<taskIdString, view>, where a view is
+// { source: 'task' | 'project' | 'none', terms, set_by, set_at }. A task whose
+// newest set is EMPTY says so ('task', no terms): the project chose "no pay terms"
+// for it, which the standing terms must not paper over.
+async function readPayTerms(taskIds, { db } = {}) {
+  const exec = db || api.pool;
+  const ids = [...new Set((taskIds || []).map((x) => String(x)))];
+  const { rows: sets } = await exec.query(
+    `SELECT DISTINCT ON (task_id) id, task_id, set_by, set_at
+       FROM lifecycle_pay_term_sets
+      WHERE task_id = ANY($1::bigint[]) OR task_id IS NULL
+      ORDER BY task_id, set_at DESC, id DESC`, [ids]);
+  const setIds = sets.map((s) => s.id);
+  const termsBySet = new Map();
+  if (setIds.length) {
+    const { rows } = await exec.query(
+      `SELECT set_id, pay_type, amount, unit, note FROM lifecycle_pay_terms
+        WHERE set_id = ANY($1::bigint[]) ORDER BY set_id, position`, [setIds]);
+    for (const r of rows) {
+      const k = String(r.set_id);
+      if (!termsBySet.has(k)) termsBySet.set(k, []);
+      termsBySet.get(k).push(displayTerm(r));
+    }
+  }
+  const view = (s, source) => ({ source, terms: termsBySet.get(String(s.id)) || [], set_by: s.set_by, set_at: s.set_at });
+  const project = sets.find((s) => s.task_id == null);
+  const out = new Map();
+  for (const id of ids) {
+    const own = sets.find((s) => s.task_id != null && String(s.task_id) === id);
+    if (own) out.set(id, view(own, 'task'));
+    else if (project && (termsBySet.get(String(project.id)) || []).length) out.set(id, view(project, 'project'));
+    else out.set(id, { source: 'none', terms: [], set_by: null, set_at: null });
+  }
+  return out;
+}
+
+// The project's standing terms and their history (newest first, at most `limit`
+// sets), for the settings page: who changed what, and when.
+async function readProjectPayTerms({ db, limit = 10 } = {}) {
+  const exec = db || api.pool;
+  const { rows: sets } = await exec.query(
+    `SELECT s.id, s.set_by, s.set_at, b.github_login AS set_by_login
+       FROM lifecycle_pay_term_sets s LEFT JOIN builders b ON b.id = s.set_by
+      WHERE s.task_id IS NULL
+      ORDER BY s.set_at DESC, s.id DESC LIMIT $1`, [limit]);
+  const termsBySet = new Map();
+  if (sets.length) {
+    const { rows } = await exec.query(
+      `SELECT set_id, pay_type, amount, unit, note FROM lifecycle_pay_terms
+        WHERE set_id = ANY($1::bigint[]) ORDER BY set_id, position`, [sets.map((s) => s.id)]);
+    for (const r of rows) {
+      const k = String(r.set_id);
+      if (!termsBySet.has(k)) termsBySet.set(k, []);
+      termsBySet.get(k).push(displayTerm(r));
+    }
+  }
+  const history = sets.map((s) => ({
+    set_by: s.set_by, set_by_login: s.set_by_login || null, set_at: s.set_at,
+    terms: termsBySet.get(String(s.id)) || [],
+  }));
+  return { terms: history.length ? history[0].terms : [], history };
+}
+
+module.exports = {
+  PAY_TYPES, PAY_TYPE_LABELS, SELF_MANAGED_LABEL, MAX_TERMS,
+  normalizePayTerms, displayTerm, setPayTerms, readPayTerms, readProjectPayTerms,
+};

package/modules/lifecycle/routes/project-settings.js

@@ -34,9 +34,49 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const goalCategory = require('../goal-category');
 const autopickup = require('../autopickup');
+const payTermsLib = require('../pay-terms'); // task 1004990
 
 const log = api.logger('lifecycle');
 
+// --- pay terms: the project's standing pay policy (task 1004990) --------------
+//
+// ADR 0385 decision 3: the project, not Bongos, sets the pay. The owner ruled
+// (2026-10-29) that this policy lives in a database table, changed here, with an
+// audit trail — never in the branding pack. The row carries the current terms,
+// the recent history (who, when, what) and the six types, and suggests no amount.
+function payTermsRow(policy) {
+  if (!policy) {
+    return {
+      key: 'pay_terms',
+      title: 'Pay terms',
+      editable: false,
+      state: 'unavailable',
+      sentence: 'The project’s pay terms could not be read just now.',
+      source: 'lifecycle_pay_term_sets / lifecycle_pay_terms tables',
+      reads: { file: 'lifecycle_pay_terms (migration lifecycle_018)', adr: 'ADR 0385' },
+    };
+  }
+  const terms = policy.terms || [];
+  return {
+    key: 'pay_terms',
+    title: 'Pay terms',
+    editable: true,
+    state: 'live',
+    value: {
+      terms,
+      history: (policy && policy.history) || [],
+      types: payTermsLib.PAY_TYPES.map((t) => ({ type: t, label: payTermsLib.PAY_TYPE_LABELS[t] })),
+      max: payTermsLib.MAX_TERMS,
+      self_managed_label: payTermsLib.SELF_MANAGED_LABEL,
+    },
+    sentence: terms.length
+      ? 'What this project pays for its work, in its own words. A builder sees it before claiming any task that has no pay terms of its own. Bongos records it and moves no money.'
+      : 'This project has not stated standing pay terms. A task can still carry its own. Bongos suggests no amount and moves no money.',
+    source: 'lifecycle_pay_term_sets / lifecycle_pay_terms tables',
+    reads: { file: 'lifecycle_pay_terms (migration lifecycle_018)', adr: 'ADR 0385' },
+  };
+}
+
 // --- ship mode: who starts a ship (task 1004628, ADR 0369) -------------------
 //
 // One row shape, two readers: the settings page (inside GET /project-settings) and
@@ -292,6 +332,12 @@ module.exports = function buildProjectSettingsRouter() {
       const categories = await goalCategory.listCategories({ includeInactive: true });
       const shipMode = await api.projectSettings.resolveShipMode();
       const tweak = await api.projectSettings.resolveTweakAutopickup();
+      // One unreadable table must not take the whole page down: the row says it
+      // could not be read, and the other rows still draw.
+      const payPolicy = await payTermsLib.readProjectPayTerms().catch((err) => {
+        log.error(`GET /project-settings: pay terms read failed: ${err && err.message}`);
+        return null;
+      });
 
       // A settings read is a configuration comparison — a cached one is wrong the
       // moment somebody turns a knob (the rot.js precedent).
@@ -339,6 +385,7 @@ module.exports = function buildProjectSettingsRouter() {
             source: 'work_categories table',
             reads: { file: 'work_categories (migration core_226)', adr: 'ADR 0192' },
           },
+          payTermsRow(payPolicy),
           creditRow(),
           equityRow(),
           upmarketRow(),
@@ -464,6 +511,53 @@ module.exports = function buildProjectSettingsRouter() {
     }
   });
 
+  // GET /pay-terms?task_ids=1,2,3 — what each task pays, in the project's words
+  // (task 1004990, ADR 0385 D3), for a list of tasks in one read: the hall task page
+  // and `bongos start` show it so a builder sees the pay BEFORE claiming. Each entry
+  // is { source: 'task' | 'project' | 'none', terms, set_by, set_at }; a task with
+  // none of its own shows the project's standing terms (set below), and a
+  // self-managed term carries its "Bongos does not move or guarantee this money"
+  // label. Records only — no amount here is a Bongos figure. It lives beside the
+  // standing-terms write because both serve the one pay-terms table pair.
+  // rank: any-builder — the same task metadata GET /tasks/:id serves; nothing changed.
+  router.get('/pay-terms', api.requireBuilder, async (req, res) => {
+    const raw = String((req.query && req.query.task_ids) || '');
+    const ids = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (!ids.length || ids.length > 50 || !ids.every((s) => /^\d{1,18}$/.test(s))) {
+      return res.fail('bad_task_ids', { status: 400, message: 'task_ids is a comma list of 1 to 50 task ids.' });
+    }
+    try {
+      const map = await payTermsLib.readPayTerms(ids);
+      res.json({ pay_terms: Object.fromEntries(map) });
+    } catch (err) {
+      log.error(`GET /pay-terms: ${err && err.message}`);
+      res.fail('pay_terms_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /project-settings/pay-terms — body { terms: [{ pay_type, amount?, unit?, note? }] }
+  // (task 1004990; ADR 0385 decision 3 and the owner's 2026-10-29 ruling). The
+  // project's STANDING pay terms: what a builder is shown on any task that carries
+  // none of its own. The whole list replaces the current set; [] means none. Every
+  // change is a new row naming who set it and when, and the old sets stay, so the
+  // table is the audit trail the owner asked for. Bongos fills nothing in.
+  //
+  // rank: project.settings.manage (metic+, government_010), the same atom as the
+  // other writes on this page.
+  router.patch('/project-settings/pay-terms', api.requireBuilder, api.requirePermission('project.settings.manage'), api.requireActAlone('rules'), async (req, res) => {
+    if (api.validateOrRespond(req, res, { terms: { required: true } })) return; // a list; checked by pay-terms.js
+    const parsed = payTermsLib.normalizePayTerms(req.body.terms);
+    if (parsed.error) return res.fail('bad_pay_terms', { status: 400, message: parsed.error });
+    try {
+      await payTermsLib.setPayTerms({ taskId: null, terms: parsed.terms, builderId: req.builder.id });
+      const policy = await payTermsLib.readProjectPayTerms();
+      res.json({ ok: true, row: payTermsRow(policy) });
+    } catch (err) {
+      log.error(`PATCH /project-settings/pay-terms: ${err && err.message}`);
+      res.fail('project_settings_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // --- tweak auto-pickup (task 1004677, ADR 0371 D3/D5) ----------------------
   //
   // GET /project-settings/tweak-autopickup — the switch, the monthly cap, and how

package/modules/lifecycle/routes/task-write-routes.js

@@ -28,6 +28,7 @@ const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
 const { badKind, badNeeds, detectsMigration } = require('./task-route-helpers.js');
 const { describeCheckViolation } = require('../pg-constraint-fail.js');
+const payTermsLib = require('../pay-terms.js'); // task 1004990
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
 const { resolveUpkeepHome, isUpkeepFiling, UPKEEP_HINT } = require('../upkeep-home.js'); // task 1004597
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -39,6 +40,11 @@ module.exports = function registerTaskWriteRoutes(router) {
   // shape tasks. Was Archon-only (task #106 / ADR 0016; three-rank model #360 /
   // ADR 0018). A Xenos/Thetes still cannot author — they file ideas. Setting rank
   // and closing versions stay Archon. The every-route audit is task #231 (V3.R06).
+  // NO pay_terms HERE, on purpose (task 1004990): the task's rule is that only
+  // someone who may EDIT a task sets its pay terms, and this route is gated on
+  // task.create, not task.edit — so terms are set with PATCH /tasks/:id right after
+  // create, under that route's task.edit gate. The strict validator refuses the
+  // field here rather than letting a create quietly widen who may set pay.
   // rank: metic+archon — create work (plan/scope mutation); ADR 0090 (was ADR 0016/0018 archon).
   router.post('/tasks', auth.requireBuilder, auth.requirePermission('task.create'), async (req, res) => {
     if (validateOrRespond(req, res, {
@@ -387,6 +393,10 @@ module.exports = function registerTaskWriteRoutes(router) {
       // the hint had been unreachable dead code behind unknown_field since the
       // R11 strict-validation sweep landed after it.
       status: {},
+      // task 1004990 (ADR 0385 D3): the task's pay terms, in the project's own
+      // words — a list, [] for none. Checked inline by pay-terms.js; the whole list
+      // replaces the current set and the old set stays as history.
+      pay_terms: {},
     })) return;
     const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
     if (id === null) return;
@@ -412,6 +422,7 @@ module.exports = function registerTaskWriteRoutes(router) {
     const hasTitle = Object.prototype.hasOwnProperty.call(body, 'title');
     const hasPriority = Object.prototype.hasOwnProperty.call(body, 'priority');
     const hasValueSummary = Object.prototype.hasOwnProperty.call(body, 'value_summary');
+    const hasPayTerms = Object.prototype.hasOwnProperty.call(body, 'pay_terms');
     // #514: status is a lifecycle field, not a PATCH-able column — it moves only
     // through the dedicated transition routes. The #506 session tried
     // `PATCH status=ready`, got the generic no_supported_fields error, and had
@@ -423,8 +434,8 @@ module.exports = function registerTaskWriteRoutes(router) {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeeds && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, parallel_safe, security_sensitive, automation_tag, needs, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeeds && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription && !hasTitle && !hasPriority && !hasValueSummary && !hasPayTerms) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, title, description, value_summary, priority, pay_terms, parallel_safe, security_sensitive, automation_tag, needs, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -555,6 +566,16 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail(`bad_${field}`, { status: 400, message: `${field} must be a boolean` });
       }
     }
+    // task 1004990: pay terms are checked here with the other gates, so a bad list
+    // refuses the whole request before any field is written. Who may set them is
+    // this route's own task.edit gate (ADR 0016) — the same person who may edit
+    // the task. Nothing is filled in: a term without an amount stays without one.
+    let payTerms = null;
+    if (hasPayTerms) {
+      payTerms = payTermsLib.normalizePayTerms(body.pay_terms);
+      if (payTerms.error) return res.fail('bad_pay_terms', { status: 400, message: payTerms.error });
+      if (!(await db.getTask(id))) return res.fail('task_not_found', 404);
+    }
     // ---- all gates passed: apply the writes. Order preserved from the old ----
     // shape — requires_rank still runs AFTER security_sensitive so a
     // same-request flag flip is already reflected in the derived floor.
@@ -695,10 +716,20 @@ module.exports = function registerTaskWriteRoutes(router) {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
-    if (!hasParent) return res.json({ task: updated });
+    let payTermsSet;
+    if (hasPayTerms) {
+      try {
+        payTermsSet = await payTermsLib.setPayTerms({ taskId: id, terms: payTerms.terms, builderId: req.builder.id });
+        if (!updated) updated = await db.getTask(id);
+      } catch (err) {
+        log.error('[gds] PATCH /tasks/:id pay_terms', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (!hasParent) return res.json(payTermsSet ? { task: updated, pay_terms: payTermsSet } : { task: updated });
     try {
       const task = await hierarchy.attachParent(id, body.parent_task_id);
-      res.json({ task });
+      res.json(payTermsSet ? { task, pay_terms: payTermsSet } : { task });
     } catch (err) {
       if (err && err.code) {
         const status =

package/modules/market-watch/module.json

@@ -1,7 +1,7 @@
 {
   "key": "market-watch",
   "title": "Market Watch (a weekly AI watch on a project's market)",
-  "description": "A weekly AI watch on a project's competitors, partners and topics, with a sourced log per tracked item and a weekly question to members (goal 1000137). Its data model (tables, read queries and the hub seed of the 2026-10-28 research), its weekly run (an hourly poller that researches each tracked item on the project's own Anthropic key, under the monthly cap), the weekly ask card in the hall's attention inbox (task 1004940) and its rules page (the watch rules in plain words, members' proposed changes, and the owner's or the government's decision on each, task 1004941) are in. Off by default, and it cannot be turned on behind an open join door with no payer, because every run will spend the project's AI budget.",
+  "description": "A weekly AI watch on a project's competitors, partners and topics, with a sourced log per tracked item and a weekly question to members (goal 1000137). Its data model (tables, read queries and the hub seed of the 2026-10-28 research), its weekly run (an hourly poller that researches each tracked item on the project's own Anthropic key, under the monthly cap), the weekly ask card in the hall's attention inbox (task 1004940), its rules page (the watch rules in plain words, members' proposed changes, and the owner's or the government's decision on each, task 1004941) and the owner's settings (on/off, monthly cap, cadence, the project key; task 1004938) are in. Off by default, and it cannot be turned on behind an open join door with no payer, because every run will spend the project's AI budget.",
   "version": "0.4.0",
   "coreVersion": "^1.22.0",
   "category": {
@@ -15,7 +15,8 @@
     "migrations": true,
     "routes": [
       "ask",
-      "rules"
+      "rules",
+      "settings"
     ],
     "pollers": [
       "hub-seed",

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;
+};