@cohortapp/agent-sdk 2.18.12 → 2.18.14

package/lib/engine/output/json.mjs

@@ -100,6 +100,28 @@ export function buildResult({ outcome, sessionId, durationMs, wire, session = nu
       modelTier: outcome.modelTier,
       requestIds: outcome.requestIds,
       costMicros: outcome.costMicros,
+      // W16 (hq a60b9595): what the gateway says ABOUT `costMicros` above.
+      // `enforcement` is the billing mode that produced it — only "on" means
+      // money moved, `null` means the endpoint did not say — so a consumer
+      // summing `costMicros` (or `total_cost_usd`) as spend must read this in
+      // the same breath. `shadowCostMicros` is what enforcement WOULD have
+      // charged, kept under its own name because folding a counterfactual into
+      // a charge is the misread the gateway split the fields to prevent; it is
+      // null in production today. `quotaSource` says why `quota` is empty when
+      // it is: the ledger answered and there is no allowance, the read failed,
+      // or nothing was read — three answers one `{}` used to collapse.
+      //
+      // SCOPE: these three have the SAME scope as `costMicros` above, on purpose.
+      // On a run with subagents cli.mjs replaces `costMicros` with the
+      // parent+children sum and replaces these three with the fold over the same
+      // set (agents/usage.mjs), so a parent served under "on" whose child was
+      // served under "shadow" reports "mixed" — never "on" beside a total that
+      // includes the child's shadow figure. Per-child modes are on
+      // `cohort.agents[]`. (`gatewayUsage` below does NOT follow that rule; its
+      // own comment says so.)
+      enforcement: outcome.enforcement ?? null,
+      shadowCostMicros: outcome.shadowCostMicros ?? null,
+      quotaSource: outcome.quotaSource ?? null,
       quota: outcome.quota,
       usage: outcome.usage,
       // CF-158: the gateway's own view of the same turns, off the terminal
@@ -151,6 +173,10 @@ export function buildSetupErrorResult({ sessionId, code, message, durationMs, wi
       modelTier: null,
       requestIds: [],
       costMicros: null,
+      // No request was made, so the endpoint stated nothing (W16).
+      enforcement: null,
+      shadowCostMicros: null,
+      quotaSource: null,
       quota: null,
       usage: emptyUsage("estimated"),
       // No request was made, so the gateway reported nothing (CF-158).

package/lib/engine/wire/errors.mjs

@@ -379,6 +379,14 @@ export function readCohortHeaders(headers) {
     // Headers never carry usage — only the terminal frame does (CF-158). The key
     // is present so the merged shape is uniform whether a frame arrived or not.
     usage: null,
+    // §4.6 defines no header for any of these three either: only the terminal
+    // frame — and the identical object on a non-streamed response — carries
+    // them. Present and null so a caller reads one shape whether a frame
+    // arrived or not, and so "the endpoint did not say" is never silently the
+    // same value as a mode it did say.
+    enforcement: null,
+    shadowCostMicros: null,
+    quotaSource: null,
     quota: {
       windows,
       creditsRemainingMicros: micros(credits, true),
@@ -400,6 +408,132 @@ function micros(v, signed) {
   return (signed ? /^-?\d+$/ : /^\d+$/).test(s) ? s : null;
 }
 
+/**
+ * The billing modes the gateway names in the frame's `enforcement` field
+ * (design §4.8, shipped hq a60b9595). `on` is the only one under which a
+ * reported `cost_micros` is money that moved.
+ *
+ * A value outside this set reads as UNKNOWN (`null`), never as `"on"`: the
+ * field exists to say whether a figure is money, and promoting a word this
+ * client has never seen to `"on"` would put a counterfactual charge into a
+ * seat's spend — the very misread this contract was extended to prevent.
+ */
+export const ENFORCEMENT_MODES = new Set(["off", "shadow", "on"]);
+
+/**
+ * `enforcement` as one of the three modes, or null for absent, non-string or
+ * unrecognised. PURE, never throws.
+ * @param {unknown} v @returns {'off'|'shadow'|'on'|null}
+ */
+export function readEnforcement(v) {
+  return typeof v === "string" && ENFORCEMENT_MODES.has(v) ? /** @type {any} */ (v) : null;
+}
+
+/**
+ * The four answers `quota_source` splits a previously-ambiguous empty `quota`
+ * object into (design §4.8):
+ *
+ *   ledger        the ledger answered — this seat genuinely has no included
+ *                 allowance (a money-only band reports no windows by design)
+ *   unreadable    the quota read FAILED. An empty quota here is not headroom.
+ *   not_read      admission is off, so nothing was read.
+ *   not_admitted  a defensive fourth answer no served request produces today:
+ *                 read it as "unknown", not as a state to branch on.
+ *
+ * An unrecognised value is also unknown, and is reported as such rather than
+ * being rounded to the nearest known one.
+ */
+export const QUOTA_SOURCES = new Set(["ledger", "unreadable", "not_read", "not_admitted"]);
+
+/** @param {unknown} v @returns {'ledger'|'unreadable'|'not_read'|'not_admitted'|null} */
+export function readQuotaSource(v) {
+  return typeof v === "string" && QUOTA_SOURCES.has(v) ? /** @type {any} */ (v) : null;
+}
+
+/**
+ * `enforcement` as a CLOSED four-word vocabulary: one of the three modes, the
+ * client's own `"unknown"` when the endpoint stated something else, or null when
+ * it stated nothing. PURE, never throws.
+ *
+ * The fourth word exists so the seam does not erase the difference between "the
+ * endpoint said nothing" and "the endpoint said a word this client has never
+ * seen" — a gateway that ships a fourth mode would otherwise reach a seat as
+ * silence, and nobody would learn it had spoken. `"unknown"` can never be
+ * confused with `"on"`, which is the one guarantee that matters for money.
+ * @param {unknown} v @returns {'off'|'shadow'|'on'|'unknown'|null}
+ */
+export function readEnforcementState(v) {
+  return v == null || v === "" ? null : readEnforcement(v) ?? "unknown";
+}
+
+/**
+ * `quota_source` as the same closed vocabulary: one of the four §4.8 answers,
+ * `"unknown"` for anything else stated, null for silence. PURE.
+ * @param {unknown} v @returns {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|null}
+ */
+export function readQuotaSourceState(v) {
+  return v == null || v === "" ? null : readQuotaSource(v) ?? "unknown";
+}
+
+/**
+ * Fold one request's stated `enforcement` into what a whole run has observed.
+ * PURE. Silence never changes what was already stated; a stated word this
+ * client does not know folds to `"unknown"` (distinct from "never stated");
+ * two different modes in one run fold to `"mixed"`.
+ * @param {'off'|'shadow'|'on'|'unknown'|'mixed'|null|undefined} prev
+ * @param {unknown} next
+ * @returns {'off'|'shadow'|'on'|'unknown'|'mixed'|null}
+ */
+export function foldEnforcement(prev, next) {
+  return fold(prev, next, readEnforcement);
+}
+
+/**
+ * Fold one request's stated `quota_source` into what a whole run has observed.
+ * Same rules as {@link foldEnforcement}.
+ * @param {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|'mixed'|null|undefined} prev
+ * @param {unknown} next
+ * @returns {'ledger'|'unreadable'|'not_read'|'not_admitted'|'unknown'|'mixed'|null}
+ */
+export function foldQuotaSource(prev, next) {
+  return fold(prev, next, readQuotaSource);
+}
+
+/**
+ * Combine two ALREADY-FOLDED statements — each already one of the closed
+ * vocabulary's words, `"mixed"`, or null for "nothing stated". PURE.
+ *
+ * This is the fold one level up: a parent run folds its own requests with
+ * {@link foldEnforcement} (which reads RAW wire values), and then folds that
+ * result with each subagent's. Passing a folded `"mixed"` back through
+ * `foldEnforcement` would flatten it to `"unknown"`, because `"mixed"` is this
+ * client's word and not one the gateway ever sends.
+ *
+ * Silence never unsays a statement; two different statements are `"mixed"`.
+ * @template {string} T
+ * @param {T|'mixed'|null|undefined} a @param {T|'mixed'|null|undefined} b
+ * @returns {T|'mixed'|null}
+ */
+export function combineStated(a, b) {
+  const x = a ?? null;
+  const y = b ?? null;
+  if (y === null) return /** @type {any} */ (x);
+  if (x === null) return /** @type {any} */ (y);
+  return /** @type {any} */ (x === y ? x : "mixed");
+}
+
+/**
+ * @param {any} prev @param {unknown} next @param {(v:unknown)=>string|null} read
+ * @returns {any}
+ */
+function fold(prev, next, read) {
+  const before = prev ?? null;
+  if (next == null || next === "") return before;
+  const m = read(next) ?? "unknown";
+  if (before === null) return m;
+  return before === m ? before : "mixed";
+}
+
 /** SSE event name of the gateway's terminal cost/quota frame. */
 export const COHORT_FRAME_EVENT = "cohort";
 
@@ -435,6 +569,31 @@ export const COHORT_FRAME_EVENT = "cohort";
  * nothing fails when it is absent. See docs/engine/eval.md §3; the fix for the
  * contract itself belongs to hq, which this repo does not edit.
  *
+ * ## W16 — `enforcement`, `shadow_cost_micros`, `quota_source` (hq a60b9595)
+ *
+ * The frame gained three fields, all normative in §4.8, all optional here:
+ *
+ *   `enforcement`         "off" | "shadow" | "on" — the billing mode that
+ *                         produced the two cost figures. Only under `on` is
+ *                         `cost_micros` money that moved. A word outside the
+ *                         three reaches the merged result as `"unknown"`, never
+ *                         as `"on"` and never as silence.
+ *   `shadow_cost_micros`  what enforcement WOULD have charged. It is a separate
+ *                         field on purpose and is carried under the separate key
+ *                         `shadowCostMicros`; it is never folded into
+ *                         `costMicros` and never counted as spend. Non-null only
+ *                         where the retail card is partial — null in production
+ *                         today, which has no published price book.
+ *   `quota_source`        "ledger" | "unreadable" | "not_read" | "not_admitted"
+ *                         — why `quota` is empty when it is. `{}` used to
+ *                         collapse "no allowance" and "the read failed", which
+ *                         call for opposite behaviour.
+ *
+ * Each is read through its own total parser ({@link readEnforcement},
+ * {@link readQuotaSource}, and `micros` for the figure): absent, wrong-typed
+ * and unrecognised all yield null, nothing throws, and an unrecognised
+ * `enforcement` is NEVER promoted to `"on"`.
+ *
  * @param {string} data
  * @returns {Partial<ReturnType<typeof readCohortHeaders>> & { quota?: any }}
  */
@@ -469,6 +628,18 @@ export function readCohortFrame(data) {
   // CF-158: undocumented upstream, so absence is normal and never an error.
   const usage = readFrameUsage(o.usage);
   if (usage) patch.usage = usage;
+  // W16 (hq a60b9595): enforcement, shadow_cost_micros and quota_source. Each
+  // is read defensively and only SET when it is usable, so an omitted or
+  // unrecognised value leaves the merged value at null rather than overwriting
+  // a mode an earlier frame stated. `shadow_cost_micros` lands under a name
+  // that cannot be confused with `costMicros`, because the gateway's whole
+  // reason for splitting the fields is that one is money and the other is not.
+  const mode = readEnforcementState(o.enforcement);
+  if (mode) patch.enforcement = mode;
+  const shadow = micros(o.shadow_cost_micros, false);
+  if (shadow !== null) patch.shadowCostMicros = shadow;
+  const qs = readQuotaSourceState(o.quota_source);
+  if (qs) patch.quotaSource = qs;
   return patch;
 }
 
@@ -486,6 +657,14 @@ export function mergeCohort(base, patch) {
     modelTier: patch.modelTier ?? base.modelTier,
     costMicros: patch.costMicros ?? base.costMicros,
     usage: patch.usage ?? base.usage ?? null,
+    // W16. `enforcement` qualifies `costMicros`: only under "on" is that figure
+    // money that moved. `shadowCostMicros` is what enforcement WOULD have
+    // charged and is never spend. `quotaSource` says why `quota` is empty when
+    // it is. null means the endpoint did not say — read as unknown, and NOT as
+    // a licence to assume "on"; the budget meter decides what to do with that.
+    enforcement: patch.enforcement ?? base.enforcement ?? null,
+    shadowCostMicros: patch.shadowCostMicros ?? base.shadowCostMicros ?? null,
+    quotaSource: patch.quotaSource ?? base.quotaSource ?? null,
     quota: {
       windows: { ...base.quota.windows, ...(pq.windows || {}) },
       creditsRemainingMicros: pq.creditsRemainingMicros ?? base.quota.creditsRemainingMicros,

package/lib/engine/wire/search.mjs

@@ -6,9 +6,19 @@
  *   POST <base>/cohort/v1/search
  *     Authorization: Bearer <seat token>
  *     body  {"query":"…","maxResults":8,"allowedDomains":["…"],"blockedDomains":["…"]}
- *     200   {"results":[{"title":"…","url":"…","snippet":"…"}],"costMicros":"1200"}
+ *     200   {"results":[{"title":"…","url":"…","snippet":"…"}],"costMicros":"1200",
+ *            "shadowCostMicros":"…|null","enforcement":"off|shadow|on"}
  *           (costMicros: decimal integer string of micro-USD, or a safe integer;
  *            `x-cohort-request-id` and `x-cohort-cost-micros` headers as on every route)
+ *
+ * **`costMicros` is money only under `enforcement: "on"` (W16, design §4.8).**
+ * The search body spells the three billing fields in camelCase because it is a
+ * plain JSON response rather than the `cohort` object, but they carry exactly
+ * the frame's meanings: under `shadow` a priced search settles for real and
+ * moves no money, and `shadowCostMicros` is what enforcement WOULD have charged.
+ * All three ride the returned `cohort` object, so the budget meter applies the
+ * same rule to a search as to a model call — a search's cost would otherwise be
+ * the one figure still counted as spend under shadow billing.
  *     404   the gateway has no search → the tool reports search as unavailable
  *     4xx/5xx refusals use the §4.6/§4.8 error bodies
  *
@@ -19,7 +29,7 @@
  * @module lib/engine/wire/search
  */
 
-import { classifyHttpError, classifyTransportError, tokenFailureError, header } from "./errors.mjs";
+import { classifyHttpError, classifyTransportError, tokenFailureError, header, readEnforcementState } from "./errors.mjs";
 
 export const SEARCH_ROUTE = "/cohort/v1/search";
 export const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
@@ -41,7 +51,8 @@ function micros(v) {
 /**
  * Validate the 200 body (pure).
  * @param {unknown} body
- * @returns {{ok:true, results:Array<{title:string, url:string, snippet:string}>, costMicros:string|null}|{ok:false, message:string}}
+ * @returns {{ok:true, results:Array<{title:string, url:string, snippet:string}>, costMicros:string|null,
+ *   shadowCostMicros:string|null, enforcement:'off'|'shadow'|'on'|'unknown'|null}|{ok:false, message:string}}
  */
 export function parseSearchBody(body) {
   if (!body || typeof body !== "object" || !Array.isArray(/** @type any */ (body).results)) return { ok: false, message: "the search response has no results array" };
@@ -49,7 +60,15 @@ export function parseSearchBody(body) {
   const results = b.results
     .filter((r) => r && typeof r === "object" && typeof r.url === "string" && r.url !== "")
     .map((r) => ({ title: typeof r.title === "string" ? r.title : r.url, url: r.url, snippet: typeof r.snippet === "string" ? r.snippet : "" }));
-  return { ok: true, results, costMicros: micros(b.costMicros) };
+  return {
+    ok: true,
+    results,
+    costMicros: micros(b.costMicros),
+    // W16. Read defensively and kept apart from the charge, exactly as on the
+    // frame: an unrecognised enforcement is "unknown", never "on".
+    shadowCostMicros: micros(b.shadowCostMicros),
+    enforcement: readEnforcementState(b.enforcement),
+  };
 }
 
 /**
@@ -65,8 +84,8 @@ export function parseSearchBody(body) {
  * @param {AbortSignal} [p.signal]
  * @param {number} [p.timeoutMs]
  * @param {() => number} [p.now]
- * @returns {Promise<{ok:true, results:Array<{title:string,url:string,snippet:string}>, cohort:{requestId:string|null, costMicros:string|null}}
- *   | {ok:false, error:{kind:string, code:string, status:number|null, message:string}, cohort:{requestId:string|null, costMicros:string|null}|null, accepted:boolean}>}
+ * @returns {Promise<{ok:true, results:Array<{title:string,url:string,snippet:string}>, cohort:{requestId:string|null, costMicros:string|null, shadowCostMicros:string|null, enforcement:string|null}}
+ *   | {ok:false, error:{kind:string, code:string, status:number|null, message:string}, cohort:{requestId:string|null, costMicros:string|null, shadowCostMicros:string|null, enforcement:string|null}|null, accepted:boolean}>}
  */
 export async function searchWeb(p) {
   const fetchImpl = p.fetchImpl ?? globalThis.fetch;
@@ -106,7 +125,15 @@ export async function searchWeb(p) {
         const err = classifyTransportError(e, controller.signal);
         return { ok: false, error: { kind: err.kind, code: err.code, status: null, message: err.message }, cohort: null, accepted: false };
       }
-      const cohort = { requestId: header(res.headers, "x-cohort-request-id"), costMicros: micros(header(res.headers, "x-cohort-cost-micros")) };
+      // §4.6 defines no header for the billing fields; only the body carries
+      // them. Null here so the shape is uniform on a refusal, which has no body
+      // to read them from.
+      const cohort = {
+        requestId: header(res.headers, "x-cohort-request-id"),
+        costMicros: micros(header(res.headers, "x-cohort-cost-micros")),
+        shadowCostMicros: null,
+        enforcement: null,
+      };
       if (res.status === 401 && typeof p.token === "function" && !refresh) {
         await res.body?.cancel().catch(() => {});
         refresh = true;
@@ -130,7 +157,16 @@ export async function searchWeb(p) {
       }
       const parsed = parseSearchBody(json);
       if (!parsed.ok) return { ok: false, error: { kind: "protocol", code: "search_protocol_error", status: res.status, message: parsed.message }, cohort, accepted: true };
-      return { ok: true, results: parsed.results.slice(0, body.maxResults), cohort: { requestId: cohort.requestId, costMicros: parsed.costMicros ?? cohort.costMicros } };
+      return {
+        ok: true,
+        results: parsed.results.slice(0, body.maxResults),
+        cohort: {
+          requestId: cohort.requestId,
+          costMicros: parsed.costMicros ?? cohort.costMicros,
+          shadowCostMicros: parsed.shadowCostMicros,
+          enforcement: parsed.enforcement,
+        },
+      };
     }
     return { ok: false, error: { kind: "auth", code: "http_401", status: 401, message: "the gateway refused the refreshed token" }, cohort: null, accepted: false };
   } finally {

package/lib/identity/claude-md.mjs

@@ -0,0 +1,107 @@
+/**
+ * claude-md.mjs — reading a seat's CLAUDE.md into a prompt preamble.
+ *
+ * WHY THIS MODULE EXISTS
+ *   Both prompt planes scrape the seat's CLAUDE.md for house-style sections:
+ *   the 60-second quick reply (scripts/daemon/responder.mjs#loadPreamble) and
+ *   the full session (scripts/daemon/prompt-builder.mjs#extractPreamble). They
+ *   had SEPARATE copies of the scrape, and only one of them was ever fixed — so
+ *   the fix for "the preamble hands the model an unresolved identity template"
+ *   landed on the quick reply while the session plane, which is the tier a
+ *   substantive reply actually escalates to, kept every defect. One definition,
+ *   two callers, is the only shape that cannot drift that way again.
+ *
+ * PURE. Every function here takes the file's text as a parameter and returns a
+ * string; nothing reads the filesystem, the clock or the environment, so what a
+ * given seat file yields is a unit test (claude-md.test.mjs).
+ */
+
+/**
+ * A scaffold placeholder line — `*Configured by \`maestro setup\`*` and variants.
+ *
+ * The scaffold ships these under `## Company Context` and `### Autonomy Model`,
+ * and the scrape handed them to the model verbatim: a standing note, on every
+ * turn, that the seat's company context and autonomy bands are unconfigured.
+ * That is the same "you are not set up" signal that pushes a model into the
+ * generic-assistant register in which it introduces itself.
+ */
+export const SCAFFOLD_SENTINEL = /^\s*\*?\s*(?:Configured by|To be configured|TBD)\b[^\n]*$/i;
+
+/** Markdown heading depth, 0 for a non-heading. @param {string} l @returns {number} */
+function headingDepth(l) {
+  const m = /^(#{2,6})\s+\S/.exec(l);
+  return m ? m[1].length : 0;
+}
+
+/**
+ * Drop scaffold placeholder lines, and any heading they leave empty. PURE.
+ *
+ * A heading with nothing under it says less than nothing, so it goes with its
+ * placeholder rather than standing as an unanswered promise.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripScaffoldSentinels(text) {
+  const kept = String(text || "").split("\n").filter((l) => !SCAFFOLD_SENTINEL.test(l));
+  // Second pass: a heading whose whole body was a sentinel is now empty.
+  const out = [];
+  for (let i = 0; i < kept.length; i++) {
+    const line = kept[i];
+    const depth = headingDepth(line);
+    if (depth) {
+      let j = i + 1;
+      while (j < kept.length && kept[j].trim() === "") j++;
+      // Empty only when EOF follows, or a heading at the SAME OR SHALLOWER
+      // level. A parent heading followed by its own subheading has a body.
+      const next = j < kept.length ? headingDepth(kept[j]) : 0;
+      if (j >= kept.length || (next && next <= depth)) continue;
+    }
+    out.push(line);
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/**
+ * Scrape the named `##` sections out of a CLAUDE.md. PURE, so which sections a
+ * given seat file yields is a unit test.
+ *
+ * @param {string} raw        CLAUDE.md contents
+ * @param {string[]} targets  `## ` headings to keep
+ * @returns {string}
+ */
+export function scrapeClaudeMdSections(raw, targets) {
+  const sections = [];
+  let capturing = false;
+  for (const line of String(raw || "").split("\n")) {
+    if (targets.some((h) => line.startsWith(h))) { capturing = true; sections.push(line); continue; }
+    if (capturing && /^## [A-Z]/.test(line) && !targets.some((h) => line.startsWith(h))) { capturing = false; continue; }
+    if (capturing) sections.push(line);
+  }
+  return sections.join("\n").trim();
+}
+
+/**
+ * The `##` headings a preamble scrape should keep.
+ *
+ * `## Identity` is kept ONLY when no persona block rendered. On an enrolled
+ * seat the persona is resolved from config/agent.json and the CLAUDE.md
+ * `## Identity` section is still the scaffold template — unresolved
+ * `{{agent.fullName}}` tokens followed by "If those tokens are still
+ * unresolved, your identity has not been configured yet — run … maestro setup".
+ * Rendering both gives the model a correct identity immediately followed by a
+ * notice that its identity is unconfigured; two identity blocks, one of them
+ * unresolved, is worse than either alone.
+ *
+ * On an UNENROLLED seat there is no persona, and the scaffold section — tokens
+ * and all — is the only identity prose there is. It is restored deliberately:
+ * a prompt that says "run maestro setup" is the honest rendering of a seat
+ * that has not been set up.
+ *
+ * @param {boolean} hasPersona  did renderSeatPersona() produce a block?
+ * @param {string[]} houseStyle extra `## ` headings this plane wants
+ * @returns {string[]}
+ */
+export function preambleTargets(hasPersona, houseStyle) {
+  return hasPersona ? [...houseStyle] : ["## Identity", ...houseStyle];
+}

package/lib/identity/disclosure-instructions.mjs

@@ -0,0 +1,148 @@
+/**
+ * disclosure-instructions.mjs — a standing instruction to VOLUNTEER what the
+ * agent is must not reach a prompt, wherever it was written.
+ *
+ * WHAT BROKE
+ *   Seats posted a self-introduction into the middle of live threads — a rendering
+ *   of `channels.<c>.identity_line` from policies/ai-disclosure.yaml, the
+ *   opener naming the agent's own nature and pairing it with its principal —
+ *   on a release-status post and on a correction to the agent's
+ *   OWN earlier figures, in the org's own #risk-compliance channel. Two causes
+ *   were framework-side and are fixed in code (an unresolved identity template,
+ *   and an unframed transcript). The THIRD is not framework-side at all:
+ *
+ *   The preamble scrape copies `## Communication Rules` out of the SEAT'S OWN
+ *   CLAUDE.md, verbatim. A seat file carrying a standing rule of the
+ *   shape "on first message in any thread, introduce yourself as <the
+ *   identity_line>" puts that line straight into every prompt the seat builds, and it survives every
+ *   `maestro` upgrade — the repo cannot see it, and a repo test that renders the
+ *   scaffold will never fail on it.
+ *
+ *   So the check has to run at RUNTIME over the composed preamble, on the text
+ *   that is actually about to be handed to the model, rather than in a test over
+ *   a file the fleet does not use.
+ *
+ * WHAT THIS IS NOT
+ *   It is NOT a disclosure policy and it must never weaken one. The truthfulness
+ *   invariant — a sincere question about whether someone is an AI is answered
+ *   plainly — lives in lib/identity/persona.mjs#voiceRules and
+ *   policies/ai-disclosure.yaml, and is untouched here. What these patterns
+ *   describe is the UNPROMPTED self-introduction: an instruction to open with,
+ *   attach, or lead with a statement of what the agent is.
+ *
+ *   Because of that distinction the patterns are deliberately narrow, and a line
+ *   that FORBIDS the behaviour is kept rather than dropped ({@link PROHIBITION}):
+ *   stripping "never introduce yourself as an AI" would remove a rule that says
+ *   exactly what this module wants said. A pointer to the disclosure policy —
+ *   "policies/ai-disclosure.yaml is the authority on where proactive disclosure
+ *   is legally required" — is likewise a restraint, not an instruction, and is
+ *   kept; every pattern below therefore requires an imperative verb rather than
+ *   matching the bare words "proactive disclosure".
+ *
+ * PURE. No I/O, no clock, no env — the caller supplies the text and receives the
+ * text plus what was dropped, so the exact behaviour is a unit test.
+ */
+
+/**
+ * Instructions to volunteer what the agent is.
+ *
+ * Deliberately narrower than "the word AI appears": the persona block's
+ * truthfulness bullet contains "AI" and MUST keep containing it.
+ */
+export const DISCLOSURE_INSTRUCTION_PATTERNS = Object.freeze([
+  // "state that you are an AI assistant", "mention you're a bot", …
+  /\b(?:state|disclose|declare|mention|note|announce|say|confirm)\b[^.\n]{0,60}\b(?:you are|you're|that you are|yourself as)\b[^.\n]{0,40}\b(?:an? AI\b|AI (?:assistant|agent)|artificial intelligence|a bot\b|a language model)/i,
+  // "introduce yourself", "identify yourself as …"
+  /\bintroduce yourself\b/i,
+  /\bidentify yourself as\b/i,
+  // Prose that IS the self-introduction, quoted as a model to copy.
+  /\ban AI (?:assistant|agent) working (?:with|for|alongside|on behalf of)\b/i,
+  // "add the identity line", "lead with an AI-disclosure statement", …
+  /\b(?:add|include|append|prepend|attach|open with|lead with|start with|begin with|preface \w+ with|end with|sign off with)\b[^.\n]{0,60}\b(?:identity line|proactive[_ ]disclosure|AI[- ]disclosure|disclosure (?:line|statement|notice))/i,
+  // The observed opener itself, as a template to follow.
+  /\bbefore we (?:get into it|begin|start)\b/i,
+]);
+
+/**
+ * A line that FORBIDS the behaviour rather than demanding it.
+ *
+ * Checked against the text BEFORE the match, so "Do not introduce yourself" is
+ * kept while "On first message, introduce yourself" is dropped. Deliberately
+ * generous — keeping a line the stripper was unsure about is the safe error,
+ * because the only cost of a kept prohibition is a duplicate of a rule the
+ * framework already states, while the cost of a dropped one is a rule lost.
+ */
+const PROHIBITION = /\b(?:do not|don'?t|never|no need to|must not|should not|avoid|without|rather than|instead of|refrain from|stop)\b/i;
+
+/**
+ * Does this ONE line read as an instruction to volunteer what the agent is?
+ *
+ * @param {string} line
+ * @returns {RegExp|null} the pattern that matched, or null
+ */
+export function disclosureInstructionMatch(line) {
+  const text = String(line || "");
+  if (!text.trim()) return null;
+  for (const rx of DISCLOSURE_INSTRUCTION_PATTERNS) {
+    const m = rx.exec(text);
+    if (!m) continue;
+    // A prohibition anywhere before the match keeps the line.
+    if (PROHIBITION.test(text.slice(0, m.index))) continue;
+    return rx;
+  }
+  return null;
+}
+
+/**
+ * Drop every line of `text` that instructs the agent to introduce or disclose
+ * itself, and report what went.
+ *
+ * LINE GRANULARITY IS THE POINT. This runs over seat-authored prose whose shape
+ * nothing here controls; a line is the largest unit that can be removed without
+ * guessing where a rule begins and ends. A bullet with indented sub-bullets
+ * therefore loses only its own line, which reads as a truncated rule rather than
+ * a silently rewritten one — and `dropped` is returned so the caller can say so
+ * out loud instead of editing the operator's file behind their back.
+ *
+ * @param {string} text
+ * @returns {{text: string, dropped: string[]}}
+ */
+export function stripDisclosureInstructions(text) {
+  const src = String(text || "");
+  if (!src) return { text: "", dropped: [] };
+  const dropped = [];
+  const kept = src.split("\n").filter((line) => {
+    if (!disclosureInstructionMatch(line)) return true;
+    dropped.push(line.trim());
+    return false;
+  });
+  return { text: kept.join("\n").replace(/\n{3,}/g, "\n\n"), dropped };
+}
+
+/**
+ * Strip, and WARN ONCE PER PROCESS per distinct line, naming the file the line
+ * came from. The seat operator cannot see this from the repo, so silence is the
+ * failure mode that let it run for as long as it did.
+ *
+ * @param {string} text
+ * @param {string} source  a human-readable provenance, e.g. "<seat>/CLAUDE.md"
+ * @param {(msg:string)=>void} [warn]
+ * @returns {string}
+ */
+const _warned = new Set();
+export function stripDisclosureInstructionsAndWarn(text, source, warn = console.error) {
+  const { text: out, dropped } = stripDisclosureInstructions(text);
+  for (const line of dropped) {
+    const key = `${source}::${line}`;
+    if (_warned.has(key)) continue;
+    _warned.add(key);
+    warn(
+      `[identity] dropped a self-introduction instruction from ${source}: ${JSON.stringify(line.slice(0, 200))}` +
+      ` — agents do not announce what they are unprompted; edit that file to remove the line.`,
+    );
+  }
+  return out;
+}
+
+/** For tests. */
+export const _test = { PROHIBITION };