@bongos/core 1.19.442 → 1.19.444

package/scripts/gds/session-digest-build.js

@@ -87,6 +87,16 @@ const UNATTRIBUTED_MODEL = 'claude-opus-4-8';
 function buildSessionDigest(entries, opts = {}) {
   const extra = opts.extraSecrets || [];
   const MAX_TURNS = opts.maxTurns || 4000;
+  // usageOnly — build the token metrics but no `detail`. For the callers that
+  // want ONLY a transcript's model_usage (the subagents-subtree fold, task
+  // 1003435), where the per-turn rows would be discarded anyway and the snippet
+  // scrubbing is the expensive part. It exists so that fold can reuse THIS
+  // function — the one place the token semantics live — instead of a second copy
+  // that could drift, without paying for output nobody reads. The waste is worth
+  // avoiding on both upload paths, and on the SessionEnd one it is load-bearing:
+  // that hook runs under a 6-second watchdog, so a slow pass there doesn't just
+  // cost time, it drops the upload.
+  const usageOnly = opts.usageOnly === true;
   const seenMessageIds = new Set();
   const m = {
     assistant_turns: 0,
@@ -165,15 +175,17 @@ function buildSessionDigest(entries, opts = {}) {
           }
         }
       }
-      const row = { i, role: 'assistant', ts, in: tin, out: tout, cache_read: tcr, cache_creation: tcc };
-      // Marks a line that shares its API call with an earlier one, so a reader
-      // can tell a genuinely-zero-usage turn from a de-duplicated repeat.
-      if (dupUsage) row.dup = 1;
-      if (tools.length) row.tools = tools;
-      if (textLen) row.text_len = textLen;
-      const snip = snippetOf(firstText, extra);
-      if (snip) row.snippet = snip;
-      detail.push(row);
+      if (!usageOnly) {
+        const row = { i, role: 'assistant', ts, in: tin, out: tout, cache_read: tcr, cache_creation: tcc };
+        // Marks a line that shares its API call with an earlier one, so a reader
+        // can tell a genuinely-zero-usage turn from a de-duplicated repeat.
+        if (dupUsage) row.dup = 1;
+        if (tools.length) row.tools = tools;
+        if (textLen) row.text_len = textLen;
+        const snip = snippetOf(firstText, extra);
+        if (snip) row.snippet = snip;
+        detail.push(row);
+      }
       i++;
     } else if (e.type === 'user' && msg) {
       m.user_turns++;
@@ -206,13 +218,15 @@ function buildSessionDigest(entries, opts = {}) {
           }
         }
       }
-      const row = { i, role: 'user', ts };
-      if (results) row.tool_results = results;
-      if (errors) row.tool_errors = errors;
-      if (harnessRetries) row.harness_retries = harnessRetries;
-      const snip = snippetOf(firstResult, extra);
-      if (snip) row.snippet = snip;
-      detail.push(row);
+      if (!usageOnly) {
+        const row = { i, role: 'user', ts };
+        if (results) row.tool_results = results;
+        if (errors) row.tool_errors = errors;
+        if (harnessRetries) row.harness_retries = harnessRetries;
+        const snip = snippetOf(firstResult, extra);
+        if (snip) row.snippet = snip;
+        detail.push(row);
+      }
       i++;
     }
   }
@@ -258,4 +272,22 @@ function buildSessionDigest(entries, opts = {}) {
     detail: boundedDetail,
   };
 }
-module.exports = { snippetOf, buildSessionDigest, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL };
+// mergeModelUsage — fold one model_usage map into another, in place, so a
+// session's tokens can be summed across the several transcripts one session
+// actually writes (the interactive thread + its subagent subtree — task
+// 1003435). PURE apart from mutating `target`, which the caller owns. The four
+// buckets are the session_records model_usage shape, NOT the transcript
+// *_input_tokens shape; keep them in step with buildSessionDigest above.
+function mergeModelUsage(target, addition) {
+  for (const [model, u] of Object.entries(addition || {})) {
+    const bucket = target[model] || (target[model] =
+      { input: 0, output: 0, cache_read: 0, cache_creation: 0 });
+    bucket.input += Number(u && u.input) || 0;
+    bucket.output += Number(u && u.output) || 0;
+    bucket.cache_read += Number(u && u.cache_read) || 0;
+    bucket.cache_creation += Number(u && u.cache_creation) || 0;
+  }
+  return target;
+}
+
+module.exports = { snippetOf, buildSessionDigest, mergeModelUsage, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL };

package/scripts/gds/session-digest.js

@@ -34,7 +34,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { cliClient, loadSession, arg } = require('./cli-lib');
-const { buildSessionDigest, collectEnvSecrets } = require('./ship');
+const { buildSessionDigest, collectEnvSecrets, foldSubagentUsage } = require('./ship');
 
 
 // Claude Code encodes a project transcript dir by replacing every non-alnum
@@ -144,6 +144,10 @@ async function main() {
     if (session.token) extraSecrets.push(session.token);
 
     const digest = buildSessionDigest(parseTranscript(transcriptPath), { extraSecrets });
+    // task 1003435: fold this session's subagents subtree into model_usage, the
+    // same way the on-ship upload does — the whole session's tokens, not just the
+    // interactive thread's.
+    foldSubagentUsage(digest, transcriptPath, sessionId);
 
     // task_ids:[] — the server upsert UNIONs task_ids, so the on-ship task
     // attribution is preserved; this end-of-session upload's job is to refresh
@@ -157,6 +161,12 @@ async function main() {
       ended_at: digest.endedAt,
       detail: digest.detail,
       metrics: digest.metrics,
+      // model_usage is its OWN column, and the upsert overwrites it from the
+      // body — so omitting it here (as this hook did until task 1003435) wiped
+      // the map the on-ship upload had just stored, leaving the reward with
+      // nothing to price. It is the LAST upload of the session, so it must carry
+      // the fullest picture, not the emptiest.
+      model_usage: digest.metrics.model_usage || {},
     };
     const api = await cliClient({ allowUnauthenticated: true });
     const r = await api.sessions.postSessions({ body: payload });

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

@@ -43,9 +43,16 @@ const {
 // shared with session-digest.js. Re-exported below so this file's public surface
 // and tests/session_records.mjs are unchanged.
 const {
-  snippetOf, buildSessionDigest, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
+  snippetOf, buildSessionDigest, mergeModelUsage, HARNESS_RETRY_RE, UNATTRIBUTED_MODEL,
 } = require('./session-digest-build');
 
+// The subagent subtree walker + the grader-transcript signature live in
+// session-cost.js, which already prices that subtree for the SPEND ledger. The
+// reward reads the same tokens, so it must use the SAME two definitions or the
+// two ledgers describe different sessions (task 1003435). session-cost.js guards
+// its own entry point behind require.main, so importing it is side-effect free.
+const { listJsonlRecursive, looksLikeGraderTranscript } = require('./session-cost.js');
+
 
 // classifyUploadSkip — PURE decision for whether the session upload must skip,
 // and the clear, actionable reason why. Separated from I/O so it is unit-tested
@@ -109,6 +116,94 @@ function recordUploadSkip(taskId, { code, reason }, opts = {}) {
   }
 }
 
+// parseJsonl — one transcript file's text into parsed entries, skipping any
+// malformed line (best-effort, exactly like the rest of this path).
+function parseJsonl(raw) {
+  const entries = [];
+  for (const line of String(raw || '').split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      entries.push(JSON.parse(t));
+    } catch (_) {
+      /* skip a malformed line — best-effort */
+    }
+  }
+  return entries;
+}
+
+// subagentModelUsage — the per-model TOKEN counts this session's ad-hoc
+// subagents burned, so the cost-plus reward (ADR 0054) can see them.
+//
+// WHY (task 1003435): Agent/Task-tool spawns persist in a sibling subtree,
+// <project-dir>/<session-id>/subagents/*.jsonl — never in the main transcript.
+// session-cost.js already prices that subtree into a `session:subagent` cost_log
+// row, so the SPEND ledger sees it; the digest read one file, so the REWARD did
+// not. That paid a builder who follows CLAUDE.md's "delegate freely" less than
+// one who did identical work in the main thread, and made the two ledgers
+// disagree about the same session.
+//
+// Grader transcripts are excluded BY SIGNATURE, not by location: a grader run
+// can nest inside a subagents/ dir, and its cost is already captured via the
+// worker envelope, so pricing it here would double-count (the ADR 0028
+// invariant). Each file goes through buildSessionDigest so the token semantics —
+// dedup by message.id, skip `<synthetic>`, fold unlabeled turns into a priceable
+// bucket — are the ONE implementation, never a second one that can drift.
+function subagentModelUsage(sessionDir) {
+  const modelUsage = {};
+  let files = 0;
+  let tokens = 0;
+  let graderSkipped = 0;
+  for (const f of listJsonlRecursive(sessionDir)) {
+    if (looksLikeGraderTranscript(f)) { graderSkipped++; continue; }
+    let digest;
+    try {
+      digest = buildSessionDigest(parseJsonl(fs.readFileSync(f, 'utf8')), { usageOnly: true });
+    } catch (_) {
+      continue; // an unreadable subagent file must never fail a ship
+    }
+    if (!(digest.totalTokens > 0)) continue;
+    files++;
+    tokens += digest.totalTokens;
+    mergeModelUsage(modelUsage, digest.metrics.model_usage);
+  }
+  return { modelUsage, files, tokens, graderSkipped };
+}
+
+// foldSubagentUsage — add the session's subagent tokens to `digest`'s
+// model_usage, IN PLACE, and record what was folded.
+//
+// model_usage ONLY, deliberately (task 1003435). model_usage is the reward's
+// input, so it must describe the whole session. `detail`, `metrics.tokens`,
+// `assistant_turns` and `total_tokens` stay the INTERACTIVE thread's record:
+// they feed the BFG corpus + the inefficiency evaluator, which reason about one
+// agent's turn-by-turn behaviour, and splicing N subagent transcripts into that
+// per-turn story would distort the very signal it exists to measure (and bloat
+// the payload). The three subagent_* counters are how a reader tells the two
+// apart instead of inferring a discrepancy from a mismatch.
+function foldSubagentUsage(digest, transcriptPath, sessionId) {
+  if (!digest || !digest.metrics || !transcriptPath || !sessionId) return digest;
+  // Path-traversal guard. The session id is interpolated into a filesystem path
+  // below, and what comes out of that path is priced into a payout — so a value
+  // carrying `../` could aim the walk at an arbitrary directory and fold
+  // fabricated token counts into the reward's input. Guarded HERE rather than at
+  // each call site: uploadSessionOnShip already screens the id before resolving
+  // the transcript, but the SessionEnd hook takes it straight off stdin, and any
+  // future caller would inherit the same hole. Same shape as the check in
+  // uploadSessionOnShip — a plain UUID-ish token, nothing else.
+  if (!/^[A-Za-z0-9_-]+$/.test(String(sessionId))) return digest;
+  const sessionDir = path.join(path.dirname(transcriptPath), sessionId);
+  const sub = subagentModelUsage(sessionDir);
+  if (sub.files === 0 && sub.graderSkipped === 0) return digest;
+  digest.metrics.model_usage = mergeModelUsage(
+    digest.metrics.model_usage || {}, sub.modelUsage
+  );
+  digest.metrics.subagent_files = sub.files;
+  digest.metrics.subagent_tokens = sub.tokens;
+  digest.metrics.subagent_grader_skipped = sub.graderSkipped;
+  return digest;
+}
+
 async function uploadSessionOnShip(taskId) {
   try {
     const sessionId = process.env.CLAUDE_CODE_SESSION_ID;
@@ -135,17 +230,7 @@ async function uploadSessionOnShip(taskId) {
       recordUploadSkip(taskId, decision);
       return null;
     }
-    const raw = fs.readFileSync(transcriptPath, 'utf8');
-    const entries = [];
-    for (const line of raw.split('\n')) {
-      const t = line.trim();
-      if (!t) continue;
-      try {
-        entries.push(JSON.parse(t));
-      } catch (_) {
-        /* skip a malformed line — best-effort */
-      }
-    }
+    const entries = parseJsonl(fs.readFileSync(transcriptPath, 'utf8'));
     // Dynamic secrets to scrub: every secret-shaped env VALUE (Apple/MAC_* CI
     // creds, a baked GDS/DO token, GITHUB_TOKEN, ANTHROPIC_API_KEY, …) plus this
     // run's live GDS session token. Defense in depth on top of the pattern +
@@ -157,6 +242,10 @@ async function uploadSessionOnShip(taskId) {
     const s = await loadSession();
     if (s && s.token) extraSecrets.push(s.token);
     const digest = buildSessionDigest(entries, { extraSecrets });
+    // task 1003435: the interactive transcript is only part of what this session
+    // spent — fold the subagents subtree into model_usage so the cost-plus reward
+    // prices the same tokens the cost ledger already bills.
+    foldSubagentUsage(digest, transcriptPath, sessionId);
     // task 1270: surface the session usage so the completion card can show
     // Claude tokens + an estimated cost. Returned even when the POST below fails
     // (we already have the digest) — the card is best-effort either way.
@@ -215,4 +304,5 @@ module.exports = {
   classifyUploadSkip,
   recordUploadSkip,
   uploadSessionOnShip,
+  foldSubagentUsage,
 };

package/scripts/gds/ship.js

@@ -99,7 +99,9 @@ const {
   resolveInstanceBase,
   shouldBailOnFetchFailure,
 } = require('./ship-deploy-target.js');
-const { classifyUploadSkip, recordUploadSkip } = require('./ship-session-upload.js');
+const {
+  classifyUploadSkip, recordUploadSkip, foldSubagentUsage,
+} = require('./ship-session-upload.js');
 const {
   classifyLandOutcome,
   formatPublishFailure,
@@ -176,6 +178,10 @@ module.exports = {
   // secret corpus test (tests/scrubber_corpus.mjs) can exercise each layer + tune.
   shannonEntropy, looksHighEntropySecret, redactHighEntropy, collectEnvSecrets,
   classifyUploadSkip, recordUploadSkip,
+  // task 1003435: the subagents-subtree fold, shared with the SessionEnd hook —
+  // both uploads must send the SAME whole-session model_usage or whichever runs
+  // last decides what the builder is paid for.
+  foldSubagentUsage,
   // #678: re-grade path + the grade-step helpers it shares with shipMain.
   // Exporting these formalizes learning #43 (which had to "replicate ~10
   // lines" because runSubagentGrader wasn't reachable).

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

@@ -206,13 +206,15 @@ const MODULE_GLOBS = {
   // (moduleWebSurfaces → serve-internal). Its public read endpoints stay SHARED
   // core in routes/public.js (the hall + the off-box mirror consume them too).
   'status-ui': ['modules/status-ui/'],
-  // The instance's public landing surface (index/projects/create), served by
-  // platform-server.js from the repo-root public-landing/ dir — not yet a carved
-  // module, so the glob lists where the code lives TODAY (the auto-tighten
-  // contract above). Its own key, not provisioning's: the front door is broader
-  // than instance hosting, and the web-surface precedent (hall-ui/status-ui) is
-  // one key per surface (task 1002690, goal 1000059).
-  'public-landing': ['public-landing/'],
+  // Task 1003322 (ADR 0218): the front door graduated to modules/public-landing/ —
+  // public-landing/ moved to modules/public-landing/public/ and is now a loader-
+  // discovered web-surface module. Where hall-ui and status-ui name a Host PREFIX it
+  // declares apexRoot:true, since the apex is whatever host is left once the
+  // subdomains are taken; like the hall it keeps its DEDICATED serving block (in
+  // platform-server.js, re-pointed at the module dir). The KEY is unchanged from
+  // task 1002690 — its own key, not provisioning's, because the front door is broader
+  // than instance hosting and the web-surface precedent is one key per surface.
+  'public-landing': ['modules/public-landing/'],
   // --- the design capability (task 1003324, ADR 0197): the design contract, its
   //     adapters + sync CLIs + validator, the /design playbook, and the reserved homes
   //     for the kit / the vendored UI skills / the style library. default-on,

package/src/bongos/serve-internal.js

@@ -211,7 +211,8 @@ function dropEmptyHrefLinks(html, values) {
 // '<' would otherwise break out of its attribute or close <title> early, and
 // the values now reach four times as many places as when this was written.
 // No token is ever emitted into a <script> or a CSS context (checked across
-// public-landing/, hall-ui/, status-ui/) — that would need different escaping.
+// public-landing/, hall-ui/, status-ui/ — all under modules/ since task 1003322)
+// — that would need different escaping.
 // Ampersand first, or the other replacements get double-escaped.
 function esc(s) {
   return String(s == null ? '' : s)
@@ -701,9 +702,20 @@ function mountInternalSurfaces(app) {
   // non-builders host. (The webSurfaces manifest declaration still makes the hall a
   // loader-DISCOVERED module — it feeds the scope map, the fitness keys, docs, and
   // window.__MODULES__; it is the dedicated serving below that reads the bytes.)
+  //
+  // The APEX-ROOT surface (modules/public-landing/, ADR 0218) is partitioned out the
+  // same way, on its own declaration rather than on a host: it carries no host prefix
+  // at all, because the apex is whatever is LEFT once the subdomains are taken. It is
+  // served by platform-server.js's dedicated landing block (the apex-only strip, the
+  // brand-token stamp, the ?v= content stamp, the five routes). Keeping it out of
+  // isModuleSurfaceHost is load-bearing, not tidiness — that predicate is what the
+  // /builders guards below use to step aside, and a surface matching every host would
+  // make all of them self-skip.
   const buildersHostReq = (host) => ({ headers: { host } });
   const allWebSurfaces = moduleWebSurfaces({ isEnabled: isModuleEnabled });
   const webSurfaces = allWebSurfaces
+    .filter((s) => typeof s.host === 'string')                 // APEX-ROOT surfaces carry no host (ADR 0218): they are not
+                                                               // routed by prefix here, and must stay OUT of isModuleSurfaceHost
     .filter((s) => !isBuildersHost(buildersHostReq(s.host)))   // hall served by the dedicated block, not here
     .map((s) => ({
       key: s.key,

package/src/module-api.js

@@ -33,7 +33,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.442'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.444'; // 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('dev-box'); log.info('mounted');

package/src/module-loader/loader.js

@@ -175,32 +175,49 @@ function hallWidgetScripts({ isEnabled } = {}, opts) {
   return out;
 }
 
-// Host-routed static web surfaces contributed by enabled modules (BV1.R84, ADR 0093
-// §1 / 02-module-map §6 — a web surface is first-class). A module that owns a web
-// surface (e.g. the status dashboard at status.<apex>) declares
-// contributes.webSurfaces:[{ host:"status.", dir:"public" }] in its manifest AND
-// ships that static dir at modules/<key>/<dir>/. This returns, for each discovered +
-// ENABLED module that declares webSurfaces and actually ships the directory, the
-// SERVING descriptor serve-internal.js iterates to route by Host header:
-//   { key, host, dir } — host is the lowercase Host-header prefix; dir is the
-//   ABSOLUTE on-disk path of the static directory.
-// The Host-routed twin of mountModuleRoutes / hallWidgetScripts: an enabled module's
-// surface answers on its host, a disabled one vanishes (it's never returned, so
-// serve-internal never routes its host). No-op (empty list) until a module ships a
-// web surface — same SAFE-BY-CONSTRUCTION posture as every other seam here. Pure
-// (reads disk only). Exported + module-agnostic so serve-internal hardcodes no key.
+// Static web surfaces contributed by enabled modules (BV1.R84, ADR 0093 §1 /
+// 02-module-map §6 — a web surface is first-class). A module that owns a web surface
+// declares contributes.webSurfaces in its manifest AND ships that static dir at
+// modules/<key>/<dir>/. A surface names WHERE it answers in one of two ways, never
+// both and never neither (ADR 0218):
+//   { host: "status.", dir: "public" }  → a Host-header PREFIX (status-UI, hall-UI)
+//   { apexRoot: true,  dir: "public" }  → the APEX ROOT (public-landing) — whatever
+//                                         host is left once the subdomains are taken
+// This returns, for each discovered + ENABLED module that declares a surface and
+// actually ships the directory, the SERVING descriptor its server iterates:
+//   { key, host, dir }            — host is the lowercase Host-header prefix
+//   { key, apexRoot: true, dir }  — NO host field at all
+// dir is the ABSOLUTE on-disk path of the static directory in both shapes.
+//
+// `host: ""` is REJECTED, not treated as "the root" (ADR 0218 §3): the routers match
+// with host.startsWith(s.host), and every string starts with "" — an empty prefix
+// would answer on builders./status. too and make isModuleSurfaceHost() true for every
+// request, which is the predicate the hall's own /builders guards use to step aside.
+// A boolean cannot be mistaken for a prefix, so apex-root says so with a flag.
+//
+// The twin of mountModuleRoutes / hallWidgetScripts: an enabled module's surface
+// answers, a disabled one vanishes (it's never returned, so nothing routes it — for
+// the apex root that means the front door is simply gone and the 404 tail answers).
+// No-op (empty list) until a module ships a web surface — same SAFE-BY-CONSTRUCTION
+// posture as every other seam here. Pure (reads disk only). Exported + module-agnostic
+// so both servers hardcode no key.
 function moduleWebSurfaces({ isEnabled } = {}, opts) {
   const out = [];
   for (const { key, dir, manifest } of discovered(opts).loaded) {
     if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
     const surfaces = (manifest.contributes && manifest.contributes.webSurfaces) || [];
     for (const s of surfaces) {
-      if (!s || typeof s.host !== 'string' || typeof s.dir !== 'string') continue;
+      if (!s || typeof s.dir !== 'string') continue;
+      const apexRoot = s.apexRoot === true;
+      const hasHost = typeof s.host === 'string' && s.host !== '';
+      // exactly one of the two, never both and never neither — and `host: ""` counts
+      // as NEITHER, which is what keeps an empty prefix from matching every host
+      if (apexRoot === hasHost) continue;
       const abs = path.join(dir, s.dir);
       let isDir = false;
       try { isDir = fs.statSync(abs).isDirectory(); } catch { isDir = false; }
-      if (!isDir) continue; // declared but not shipped → skip (no host routed)
-      out.push({ key, host: s.host.toLowerCase(), dir: abs });
+      if (!isDir) continue; // declared but not shipped → skip (nothing routed)
+      out.push(apexRoot ? { key, apexRoot: true, dir: abs } : { key, host: s.host.toLowerCase(), dir: abs });
     }
   }
   return out;

package/src/module-loader/manifest-schema.js

@@ -34,7 +34,9 @@
 //       "disciplines": ["artist"],      //   disciplines this module adds
 //       "skills":      ["otb-…"],       //   slash-command skills it ships
 //       "uiSections":  ["boxes"],       //   hall/status UI sections it owns
-//       "webSurfaces": [{ "host": "status.", "dir": "public" }], // host-routed static web surfaces (BV1.R84)
+//       "webSurfaces": [{ "host": "status.", "dir": "public" }], // static web surfaces. Each names a Host
+//                                       //   PREFIX (BV1.R84) or, as { "apexRoot": true, "dir": "public" },
+//                                       //   the APEX ROOT — never both (ADR 0218).
 //       "migrations":  true             //   true => modules/<key>/migrations/ exists (or an array of names)
 //     },
 //     "provides":      ["reward"],      // OPTIONAL. seam PORTS this module registers a provider for.
@@ -84,13 +86,19 @@ const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
 const isStr = (v) => typeof v === 'string' && v.length > 0;
 const isStrArray = (v) => Array.isArray(v) && v.every(isStr);
 
-// A webSurface entry: { host: "<subdomain-prefix>.", dir: "<static-dir-rel-to-module>" }.
-// `host` is the lowercase Host-header prefix the surface answers on (e.g. "status."
-// → status.<apex>); `dir` is the module-relative directory of static files to serve
-// (e.g. "public"). Both required, non-empty strings; `dir` must stay inside the
-// module (no absolute / "..").
+// A webSurface entry names WHERE the surface answers, in exactly one of two ways
+// (ADR 0218), plus the module-relative directory of static files to serve:
+//   { host: "status.", dir: "public" }  — a lowercase Host-header PREFIX (status.<apex>)
+//   { apexRoot: true,  dir: "public" }  — the APEX ROOT: whatever host is left once
+//                                         the subdomains are taken (the front door)
+// `dir` is required, non-empty, and must stay inside the module (no absolute / "..").
+// A host surface's `host` must be a NON-EMPTY string: routers match with
+// host.startsWith(host), and every string starts with "", so an empty prefix would
+// answer on every host and silently swallow the other surfaces. That is exactly why
+// the apex root is a boolean flag and not the empty prefix it superficially resembles.
+const isWebSurfaceDir = (v) => isStr(v.dir) && !v.dir.startsWith('/') && !v.dir.split(/[\\/]/).includes('..');
 const isWebSurface = (v) =>
-  isObj(v) && isStr(v.host) && isStr(v.dir) && !v.dir.startsWith('/') && !v.dir.split(/[\\/]/).includes('..');
+  isObj(v) && isWebSurfaceDir(v) && (v.apexRoot === true ? !('host' in v) : isStr(v.host));
 const isWebSurfaceArray = (v) => Array.isArray(v) && v.every(isWebSurface);
 
 function validateManifest(obj) {
@@ -172,7 +180,7 @@ function validateManifest(obj) {
       }
     }
     if ('webSurfaces' in obj.contributes && !isWebSurfaceArray(obj.contributes.webSurfaces)) {
-      E('contributes.webSurfaces: must be an array of { host: "<prefix>.", dir: "<module-relative dir>" } objects (dir inside the module, no absolute path or "..")');
+      E('contributes.webSurfaces: must be an array of { host: "<prefix>.", dir: "<module-relative dir>" } or { apexRoot: true, dir: "<module-relative dir>" } objects — a surface names a Host prefix OR the apex root, never both and never neither (ADR 0218); dir stays inside the module (no absolute path or "..")');
     }
     if ('migrations' in obj.contributes) {
       const m = obj.contributes.migrations;

package/src/platform-server.js

@@ -54,13 +54,40 @@ const { logger, requestIdMiddleware } = require('./bongos/logger');
 const PORT = Number(process.env.PORT) || 3000;
 const HOST = process.env.HOST || '127.0.0.1';
 
-// The apex landing page — a game-less instance's home (replaces the bare 404 the
-// apex host used to serve). A deliberately MINIMAL placeholder: the mascot + a
-// way into the Builders' Hall; the full landing is its own task. Served only on
-// the apex host (status./builders. are handled by mountInternalSurfaces). The
-// branding pack is injected once at boot (theme + window.__BRANDING__), exactly
-// as the hall pages are, so the look + identity come from config, not hardcode.
-const LANDING_DIR = path.join(__dirname, '..', 'public-landing');
+// The apex front door — a game-less instance's home (it replaced the bare 404 the
+// apex host used to serve). Served only on the apex host; status./builders. are
+// handled by mountInternalSurfaces. The branding pack is injected once at boot
+// (theme + window.__BRANDING__), exactly as the hall pages are, so the look and the
+// identity come from config, never from hardcode.
+//
+// THE SURFACE IS A MODULE (task 1003322, ADR 0218). The front door used to be a
+// hardcoded path here; it is now modules/public-landing/public/, resolved through the
+// loader's web-surface seam by the APEX-ROOT declaration ({ apexRoot: true, dir }) —
+// the one shape that seam grew for it, because the apex is not a Host PREFIX like
+// "status."/"builders." but whatever is left once the subdomains are taken.
+//
+// Resolved by PREDICATE, never by key: this file names no module (ADR 0083 §Decision
+// #4), so an instance shipping its own front door gets the apex by declaring apexRoot.
+// Lazy + memoised so importing this module reads no disk and a test can build the app
+// after setting up its own module state.
+//
+// null when NO enabled module claims the apex root — the module is disabled, or the
+// instance ships no landing at all. Every consumer below already treats an absent page
+// as "fall through", so the front door simply vanishes and the 404 tail answers.
+let _landingDir;
+function landingDir() {
+  if (_landingDir === undefined) {
+    // The apex root is singular by definition — two modules cannot both be "everything
+    // that is not a subdomain". Serve the first and SAY so, rather than silently
+    // shadowing one of them.
+    const claims = moduleLoader.moduleWebSurfaces({ isEnabled: isModuleEnabled }).filter((s) => s.apexRoot);
+    if (claims.length > 1) {
+      logger.warn({ keys: claims.map((s) => s.key) }, 'more than one enabled module declares an apex-root web surface — serving the first');
+    }
+    _landingDir = claims.length ? claims[0].dir : null;
+  }
+  return _landingDir;
+}
 // ── CONTENT-STAMPED STATIC ASSETS (task 1002766) ──
 // The landing HTML is `cf-cache-status: DYNAMIC` and never cached, but the
 // assets it references come back `Cache-Control: public, max-age=14400` — four
@@ -80,7 +107,7 @@ const LANDING_DIR = path.join(__dirname, '..', 'public-landing');
 // shape serve-internal.js already stamps onto the hall's own scripts.
 //
 // Stamped by RESOLUTION, not by a path allow-list: a URL is an asset if it
-// actually names a file under public-landing/. Routes (`/projects`, `/create`)
+// actually names a file under the landing surface. Routes (`/projects`, `/create`)
 // and API paths resolve to nothing and are left alone, so a new asset is
 // stamped the day it is added and nobody has to remember to list it.
 const _assetStamps = new Map();
@@ -88,9 +115,10 @@ function assetStamp(url) {
   if (!_assetStamps.has(url)) {
     let v = '';
     try {
-      const abs = path.resolve(LANDING_DIR, '.' + url);
+      const root = landingDir();
+      const abs = path.resolve(root, '.' + url);
       // never let a template's own text walk out of the landing dir
-      if (abs.startsWith(LANDING_DIR + path.sep)) {
+      if (abs.startsWith(root + path.sep)) {
         v = require('node:crypto').createHash('sha256')
           .update(fs.readFileSync(abs)).digest('hex').slice(0, 8);
       }
@@ -112,14 +140,14 @@ function landingPage(file) {
     try {
       // stamped LAST, so anything a later transform introduces is stamped too
       html = stampAssets(injectBrandingGlobal(stripApexOnly(
-        fs.readFileSync(path.join(LANDING_DIR, file), 'utf8'))));
-    } catch { /* absent → '' */ }
+        fs.readFileSync(path.join(landingDir(), file), 'utf8'))));
+    } catch { /* absent, or no module claims the apex root → '' */ }
     _landingPages.set(file, html);
   }
   return _landingPages.get(file);
 }
 
-// THE APEX CONDITIONAL (task 1002748). public-landing/ ships wholesale to every
+// THE APEX CONDITIONAL (task 1002748). The landing surface ships wholesale to every
 // instance, so one file has to render two shapes: the platform's own front door,
 // and a child project's. Sections that are true only of the platform — the
 // catalog of OTHER instances, the "capture-resistant commons" claim, the door
@@ -231,11 +259,15 @@ function buildPlatformApp() {
       res.type('html').send(html);
     });
   }
-  const landingAssets = express.static(LANDING_DIR, { index: false, fallthrough: true });
-  app.use((req, res, next) => {
-    if (!isApexHost(req)) return next();
-    return landingAssets(req, res, next);
-  });
+  // Assets fall through to the 404 tail when no module claims the apex root — the
+  // handler is not mounted at all rather than pointed at a missing directory.
+  const landingAssets = landingDir() && express.static(landingDir(), { index: false, fallthrough: true });
+  if (landingAssets) {
+    app.use((req, res, next) => {
+      if (!isApexHost(req)) return next();
+      return landingAssets(req, res, next);
+    });
+  }
 
   // Non-game tail. Anything that did not resolve to /api/gds, the status host,
   // or the builders' hall lands here. There is NO game to fall through to, so:

package/tests/cosmos_token_contrast.mjs

@@ -1,6 +1,6 @@
 // Guards the WCAG AA contrast of the cosmos.css token layer (task 1002749).
 //
-// The tokens are the ONLY input here: this test PARSES public-landing/assets/cosmos.css
+// The tokens are the ONLY input here: this test PARSES the landing surface’s assets/cosmos.css
 // and resolves var()/color-mix() itself, so it measures what the surfaces actually paint.
 // Duplicating the hex values would prove nothing.
 //
@@ -13,10 +13,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const CSS = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  '..', 'public-landing', 'assets', 'cosmos.css'
-);
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+// the front door is a module since task 1003322 (ADR 0218) — one constant, so the path moves once
+const LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const CSS = path.join(LANDING, 'assets', 'cosmos.css');
 const src = fs.readFileSync(CSS, 'utf8');
 
 // The two sheets that actually ship, comment-stripped. Several static guards
@@ -76,7 +76,7 @@ const darkMedia = declarations(blockAfter(':root:not([data-mode="light"]){'));
 // The dark blocks are :root[data-mode="dark"] and :root:not([data-mode="light"]) —
 // both (0,2,0) — so they outrank the pack's (0,1,0) and win back.
 const packColors = JSON.parse(
-  fs.readFileSync(path.join(path.dirname(CSS), '..', '..', 'config', 'branding.neutral.json'), 'utf8')
+  fs.readFileSync(path.join(ROOT, 'config', 'branding.neutral.json'), 'utf8')
 ).theme.ui.colors;
 
 // mirrors COLOR_VARS in src/bongos/serve-internal.js