@cohortapp/agent-sdk 2.10.0 → 2.11.1

package/scripts/ci/check-no-residual-identity.mjs

@@ -10,9 +10,34 @@
  * the corpus (triggers → agents → lib → templates → docs).
  *
  * These markers are the ORIGINAL client identity (NOT confidential data — that is
- * the job of check-no-confidential.mjs), so they are safe to hardcode here. The
- * generic placeholders the framework now ships (Northwind / Alex / Jordan etc.)
- * are intentional examples and are NOT flagged.
+ * the job of check-no-confidential.mjs), so they are safe to hardcode here.
+ *
+ * ── THE SECOND CLASS: FICTIONAL PLACEHOLDER IDENTITY ──────────────────────────
+ *
+ * This header used to end: "the generic placeholders the framework now ships are
+ * intentional examples and are NOT flagged." That exemption was written for
+ * DOCUMENTATION — an example in a guide is genuinely an example — but it was
+ * applied to the whole corpus, so an invented employer and invented colleagues
+ * sat unguarded inside live prompt-building code: the huddle system prompt
+ * spoken aloud on auto-joined calls, the Twilio relay's inbound-call fallback,
+ * the classifier's identity line (whose summary is carried into the human ack
+ * and the org board row), the outbound validator's internal/external test, and
+ * the information-barrier keyword matcher. None of those is an example. Each
+ * asserted, to real people, a company that does not exist.
+ *
+ * So the exemption is now NARROW and structural, not blanket:
+ *
+ *   FLAGGED   — scripts/, lib/, policies/, agents/, teams/, bin/, services/,
+ *               archetypes/, workflows/, schedules/triggers/ (see
+ *               PLACEHOLDER_SCAN_PATHS): anything that can reach a prompt, a
+ *               classifier, a policy or a send path.
+ *   EXEMPT    — docs/ (never scanned at all), scaffold/ (the example-config
+ *               tree, which is what a placeholder is FOR), any *.example file,
+ *               and test/fixture files by naming convention (see isFixturePath).
+ *   BASELINED — PLACEHOLDER_PENDING: files that still carry the class and are
+ *               not yet cleaned. Every run PRINTS them, so they cannot hide; the
+ *               list is a strict ratchet that can only SHRINK (an entry that has
+ *               become clean is itself a failure, so it gets deleted).
  *
  * Pure, dependency-light: Node builtins only. ESM.
  *
@@ -84,7 +109,14 @@ assertExemptPolicy(EXEMPT_FILES);
 export const IDENTITY_PATTERNS = [
   { label: "agent name (Sophie)", re: /\bSophie\b/i },
   { label: "principal name (Mehran)", re: /\bMehran\b/i },
-  { label: "company (Adaptic)", re: /\bAdaptic\b/ },
+  // Deliberately NOT /i: the all-lowercase form is a legitimate identifier
+  // token across the tree (launchd labels `ai.adaptic.*`, docker tags, hostnames
+  // — deliberate old-brand pins that must not be "cleaned"). But the guard only
+  // matched the Title-case form, so a SHOUT-case header slipped past it — an
+  // `ABOUT ADAPTIC:` block sat in the huddle system prompt, spoken aloud, and
+  // this guard reported the tree clean. Match both prose cases, neither
+  // identifier case.
+  { label: "company (Adaptic)", re: /\b(?:Adaptic|ADAPTIC)\b/ },
   { label: "surname (Granfar)", re: /\bGranfar\b/i },
   { label: "surname (Nguyen)", re: /\bNguyen\b/i },
   { label: "principal first name (Hootan)", re: /\bHootan\b/i },
@@ -107,6 +139,158 @@ export function scanIdentity(text) {
   return hits;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// The FICTIONAL PLACEHOLDER class (see the module header).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The framework's invented employer, counterparties and colleagues. A match in a
+ * prompt-building, policy or send path means the code is asserting something
+ * that is true of no deployment.
+ *
+ * Deliberately NOT here: bare first names used as few-shot illustration
+ * ("Input: CEO DM: can you send this to Jordan?"). A generic first name in a
+ * labelled example teaches format, not identity, and pattern-matching it would
+ * flag half the corpus and get the guard switched off. The full names below are
+ * the ones that appear as roster entries, clearance grants and entity ids.
+ *
+ * @type {Array<{label:string, re:RegExp}>}
+ */
+export const PLACEHOLDER_PATTERNS = [
+  { label: "placeholder employer (Northwind)", re: /\bNorthwind\b/i },
+  { label: "placeholder counterparty (PartnerCo)", re: /\bPartnerCo\b/i },
+  { label: "placeholder colleague (Alex Chen)", re: /\bAlex[\s-]Chen\b/i },
+  { label: "placeholder colleague (Jordan Blake)", re: /\bJordan[\s-]Blake\b/i },
+  { label: "placeholder colleague (Casey Morgan)", re: /\bCasey[\s-]Morgan\b/i },
+  { label: "placeholder agent (Robin Hayes)", re: /\bRobin[\s-]Hayes\b/i },
+];
+
+/**
+ * Where the placeholder class is FLAGGED. Everything here can reach a prompt, a
+ * classifier, a policy or a send path.
+ *
+ * `docs` and `scaffold` are absent on purpose and must stay absent: an example
+ * in a guide is an example, and scaffold/ IS the example-config tree.
+ * @type {string[]}
+ */
+export const PLACEHOLDER_SCAN_PATHS = [
+  "agents",
+  "archetypes",
+  "bin",
+  "lib",
+  "policies",
+  "schedules/triggers",
+  "scripts",
+  "services",
+  "teams",
+  "workflows",
+];
+
+/**
+ * Structural exemption: test, fixture and example files, recognised by naming
+ * convention rather than by a hand-maintained list — a per-file list would grow
+ * into the blanket exemption this change exists to remove.
+ *
+ * A placeholder persona is exactly what a fixture is for (see
+ * scripts/test-information-barriers.py, lib/model-router.test.mjs), so these are
+ * legitimate and must not be "cleaned".
+ *
+ * @param {string} rel repo-relative path (POSIX-ish separators tolerated)
+ * @returns {boolean}
+ */
+export function isFixturePath(rel) {
+  const p = String(rel).split(path.sep).join("/");
+  const base = p.slice(p.lastIndexOf("/") + 1);
+  if (p.startsWith("docs/") || p.includes("/docs/")) return true;
+  if (p.startsWith("scaffold/")) return true;
+  if (p.includes("/fixtures/") || p.startsWith("fixtures/")) return true;
+  if (p.includes("/__tests__/")) return true;
+  if (base.includes(".example")) return true;
+  if (/(^|\.)test\./.test(base)) return true;      // foo.test.mjs, foo.test.py
+  if (/^test[-_]/.test(base)) return true;         // test-voice-parser.mjs
+  if (/[-_]test\.[^.]+$/.test(base)) return true;  // foo_test.py
+  return false;
+}
+
+/**
+ * Files that STILL carry the placeholder class and have not been cleaned yet.
+ *
+ * This is a strict, shrinking ratchet, not an exemption list:
+ *   - a file NOT listed here that carries the class → FAIL (the durable fix);
+ *   - a file listed here that has become clean → FAIL, delete the entry;
+ *   - every entry is PRINTED on every run, so the debt is never invisible.
+ *
+ * Each entry states WHY it is still dirty. Entries are removed, never added:
+ * adding one requires a deliberate edit to this file and is visible in review.
+ *
+ * @type {Array<{file:string, reason:string}>}
+ */
+export const PLACEHOLDER_PENDING = [
+  {
+    file: "scripts/validate_outbound.py",
+    reason: "embedded `--self-test` harness looks up example people in the entity index; the production paths are config-driven",
+  },
+  {
+    file: "scripts/disclosure_assessment.py",
+    reason: "Layer 2 assessor — not yet grounded in config/company.json",
+  },
+  {
+    file: "scripts/daemon/voice-webhook-server.mjs",
+    reason: "inbound voice webhook prompt — not yet grounded in config/agent.json",
+  },
+  {
+    file: "scripts/media-generation/veo-video-client.mjs",
+    reason: "module docblock title still names the example employer",
+  },
+  { file: "scripts/pdf-generation/build-document.mjs", reason: "default PDF author/branding" },
+  { file: "scripts/pdf-generation/templates/board-pack.latex", reason: "document template branding" },
+  { file: "scripts/pdf-generation/templates/corporate-letter.latex", reason: "document template branding" },
+  { file: "scripts/pdf-generation/templates/memo.latex", reason: "document template branding" },
+  { file: "scripts/email-signature.html", reason: "signature template; /init-maestro rewrites it per agent" },
+  { file: "scripts/email-signature-principal.html", reason: "signature template; /init-maestro rewrites it per agent" },
+  { file: "scripts/send-email.sh", reason: "From header + inline signature fallback" },
+  { file: "scripts/send-email-as-principal.py", reason: "From header + inline signature fallback" },
+  { file: "scripts/post-interaction-indexer.py", reason: "author docstring" },
+  { file: "scripts/rag-indexer.py", reason: "author docstring" },
+  { file: "scripts/user-context-search.py", reason: "author docstring" },
+  { file: "scripts/setup/init-agent.sh", reason: "setup wizard copy" },
+  { file: "scripts/setup/init-known-agents.mjs", reason: "docblock claims a shipped roster; scaffold ships `agents: []` — fix the COMMENT, never the code" },
+  { file: "scripts/setup/configure-voice-tunnel.mjs", reason: "setup wizard copy" },
+  { file: "policies/communication-style.md", reason: "style guide worked examples" },
+];
+
+/**
+ * Guard-of-the-guard for the baseline: every entry must name a real, currently
+ * dirty file under a scanned path, and carry a reason. Exported so the test can
+ * drive the throwing branch.
+ * @param {Array<{file:string, reason:string}>} pending
+ */
+export function assertPendingPolicy(pending) {
+  for (const e of pending) {
+    if (!e || typeof e.file !== "string" || !e.file) {
+      throw new Error("check-no-residual-identity: PLACEHOLDER_PENDING entry has no `file`");
+    }
+    if (typeof e.reason !== "string" || e.reason.trim().length < 10) {
+      throw new Error(
+        `check-no-residual-identity: PLACEHOLDER_PENDING entry "${e.file}" needs a real \`reason\` — ` +
+          "an undocumented entry is an escape hatch",
+      );
+    }
+  }
+}
+assertPendingPolicy(PLACEHOLDER_PENDING);
+
+/** Scan a text blob for placeholder markers. Pure. @returns {Array<{label:string, match:string}>} */
+export function scanPlaceholders(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const hits = [];
+  for (const p of PLACEHOLDER_PATTERNS) {
+    const m = text.match(p.re);
+    if (m) hits.push({ label: p.label, match: m[0] });
+  }
+  return hits;
+}
+
 function walkFiles(dir) {
   const out = [];
   for (const name of readdirSync(dir)) {
@@ -144,18 +328,106 @@ export function findResidualIdentity(opts = {}) {
   return offenders;
 }
 
+/**
+ * Scan the executable corpus for the FICTIONAL PLACEHOLDER class.
+ *
+ * @param {object} [opts]
+ *   @param {string} [opts.cwd=REPO_ROOT]
+ *   @param {string[]} [opts.dirs=PLACEHOLDER_SCAN_PATHS]
+ *   @param {Array<{file:string,reason:string}>} [opts.pending=PLACEHOLDER_PENDING]
+ * @returns {{ regressions: Array<{file:string, hits:Array<{label:string,match:string}>}>,
+ *             pendingDirty: Array<{file:string, reason:string}>,
+ *             pendingClean: string[] }}
+ *   regressions  — dirty files NOT on the baseline (this is what fails the build)
+ *   pendingDirty — baselined files still dirty (printed, does not fail)
+ *   pendingClean — baselined files now clean (the entry must be deleted; fails)
+ */
+export function findPlaceholderIdentity(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const dirs = opts.dirs || PLACEHOLDER_SCAN_PATHS;
+  const pending = opts.pending || PLACEHOLDER_PENDING;
+  const exempt = new Set(opts.exemptFiles || EXEMPT_FILES);
+  const pendingByFile = new Map(pending.map((e) => [e.file, e]));
+
+  const regressions = [];
+  const stillDirty = new Set();
+
+  for (const d of dirs) {
+    const abs = path.join(cwd, d);
+    if (!existsSync(abs)) continue;
+    for (const file of walkFiles(abs)) {
+      const rel = path.relative(cwd, file).split(path.sep).join("/");
+      if (exempt.has(rel)) continue;      // the guards' own literals
+      if (isFixturePath(rel)) continue;   // tests, fixtures, docs, scaffold, *.example
+      let body;
+      try { body = readFileSync(file, "utf8"); } catch { continue; }
+      const hits = scanPlaceholders(body);
+      if (!hits.length) continue;
+      if (pendingByFile.has(rel)) { stillDirty.add(rel); continue; }
+      regressions.push({ file: rel, hits });
+    }
+  }
+
+  const pendingDirty = pending.filter((e) => stillDirty.has(e.file));
+  const pendingClean = pending.filter((e) => !stillDirty.has(e.file)).map((e) => e.file);
+  return { regressions, pendingDirty, pendingClean };
+}
+
 /** @param {string} [cwd=REPO_ROOT] @returns {Promise<number>} */
 export async function run(cwd = REPO_ROOT) {
+  let failed = false;
+
   const offenders = findResidualIdentity({ cwd });
   if (offenders.length === 0) {
     console.log(`check-no-residual-identity: OK (${DE_IDENTIFIED_PATHS.length} de-identified path(s) clean)`);
-    return 0;
+  } else {
+    failed = true;
+    console.error("check-no-residual-identity: FAIL — original instance identity reintroduced into de-identified paths:");
+    for (const o of offenders) {
+      for (const h of o.hits) console.error(`  ${o.file} :: ${h.label} ("${h.match}")`);
+    }
   }
-  console.error("check-no-residual-identity: FAIL — original instance identity reintroduced into de-identified paths:");
-  for (const o of offenders) {
-    for (const h of o.hits) console.error(`  ${o.file} :: ${h.label} ("${h.match}")`);
+
+  const ph = findPlaceholderIdentity({ cwd });
+
+  // State what the guard CANNOT see, every run — a silent baseline is a blind spot.
+  if (ph.pendingDirty.length) {
+    console.log(
+      `check-no-residual-identity: ${ph.pendingDirty.length} file(s) still carry fictional placeholder identity ` +
+        "(baselined in PLACEHOLDER_PENDING — this list may only shrink):",
+    );
+    for (const e of ph.pendingDirty) console.log(`  - ${e.file} — ${e.reason}`);
+  }
+
+  if (ph.pendingClean.length) {
+    failed = true;
+    console.error(
+      "check-no-residual-identity: FAIL — PLACEHOLDER_PENDING entries are now CLEAN and must be deleted " +
+        "(the baseline is a ratchet, not a permanent exemption):",
+    );
+    for (const f of ph.pendingClean) console.error(`  ${f}`);
+  }
+
+  if (ph.regressions.length) {
+    failed = true;
+    console.error(
+      "check-no-residual-identity: FAIL — fictional placeholder identity in a prompt/policy/send path. " +
+        "Ground it in config/agent.json + config/company.json and OMIT the clause when unset " +
+        "(lib/identity/persona.mjs#renderPersona is the pattern) — do not add it to PLACEHOLDER_PENDING:",
+    );
+    for (const o of ph.regressions) {
+      for (const h of o.hits) console.error(`  ${o.file} :: ${h.label} ("${h.match}")`);
+    }
   }
-  return 1;
+
+  if (!failed && ph.regressions.length === 0) {
+    console.log(
+      `check-no-residual-identity: OK (${PLACEHOLDER_SCAN_PATHS.length} executable path(s) free of fictional placeholder identity, ` +
+        `${ph.pendingDirty.length} baselined)`,
+    );
+  }
+
+  return failed ? 1 : 0;
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/scripts/ci/check-no-residual-identity.test.mjs

@@ -13,7 +13,7 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -21,9 +21,14 @@ import {
   DE_IDENTIFIED_PATHS,
   EXEMPT_FILES,
   IDENTITY_PATTERNS,
+  PLACEHOLDER_PENDING,
   assertExemptPolicy,
+  assertPendingPolicy,
+  findPlaceholderIdentity,
   findResidualIdentity,
+  isFixturePath,
   scanIdentity,
+  scanPlaceholders,
   run,
 } from "./check-no-residual-identity.mjs";
 
@@ -79,7 +84,10 @@ test("(iii) a seeded marker in a NON-exempt file still fails the ratchet", async
 
 test("scanIdentity flags every 2.0 pattern incl. the package scope; placeholders stay clean", () => {
   assert.ok(scanIdentity("npm i @adaptic/maestro").some((h) => /@adaptic\//.test(h.match)));
-  assert.equal(scanIdentity("Northwind's Alex and Jordan shipped it").length, 0, "generic placeholders are intentional");
+  // scanIdentity is the ORIGINAL-INSTANCE scan only. The fictional placeholder
+  // class is a SEPARATE pass (scanPlaceholders) over its own path set — see the
+  // placeholder tests at the bottom of this file.
+  assert.equal(scanIdentity("Northwind's Alex and Jordan shipped it").length, 0, "different scan");
   assert.equal(scanIdentity("").length, 0);
 });
 
@@ -87,3 +95,108 @@ test("the LIVE repo is clean under the expanded ratchet (the commit that lands i
   const code = await run();
   assert.equal(code, 0, "expanded ratchet must be green in-tree");
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The FICTIONAL PLACEHOLDER class — the exemption that used to say
+// "Northwind / Alex / Jordan are intentional examples and are NOT flagged".
+// That blanket exemption is what let an invented employer sit inside the huddle
+// system prompt, the PSTN relay fallback, the classifier identity line and the
+// outbound validator. These tests pin the narrowed shape.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test("placeholder scan FLAGS a fictional employer in a live prompt path", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "ratchet-ph-"));
+  mkdirSync(join(cwd, "scripts", "huddle"), { recursive: true });
+  writeFileSync(
+    join(cwd, "scripts", "huddle", "huddle-server.mjs"),
+    'const p = `ABOUT: Northwind is a global asset manager`;\n',
+  );
+  const { regressions } = findPlaceholderIdentity({ cwd, pending: [] });
+  assert.equal(regressions.length, 1, "a prompt-path literal is a regression");
+  assert.match(regressions[0].hits[0].label, /Northwind/);
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+test("placeholder scan EXEMPTS tests, fixtures, docs, scaffold and *.example", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "ratchet-ph2-"));
+  mkdirSync(join(cwd, "scripts", "daemon"), { recursive: true });
+  mkdirSync(join(cwd, "lib", "fixtures"), { recursive: true });
+  mkdirSync(join(cwd, "scaffold", "config"), { recursive: true });
+  const body = 'const who = "Alex Chen at Northwind";\n';
+  writeFileSync(join(cwd, "scripts", "daemon", "thing.test.mjs"), body);
+  writeFileSync(join(cwd, "scripts", "test-information-barriers.py"), body);
+  writeFileSync(join(cwd, "lib", "fixtures", "roster.json"), body);
+  writeFileSync(join(cwd, "scaffold", "config", "known-agents.json"), body);
+  writeFileSync(join(cwd, "lib", "voice.yaml.example"), body);
+  const { regressions } = findPlaceholderIdentity({ cwd, pending: [] });
+  assert.deepEqual(regressions, [], "fixtures/tests/scaffold/examples are legitimate placeholders");
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+test("isFixturePath classifies by convention, not by a hand-maintained list", () => {
+  for (const p of [
+    "lib/model-router.test.mjs",
+    "scripts/test-voice-parser.mjs",
+    "scripts/foo_test.py",
+    "docs/guides/voice.md",
+    "scaffold/config/known-agents.json",
+    "lib/channels/__tests__/x.mjs",
+    "config/voice.yaml.example",
+  ]) assert.equal(isFixturePath(p), true, p);
+
+  for (const p of [
+    "scripts/huddle/huddle-server.mjs",
+    "scripts/daemon/classifier.mjs",
+    "policies/information-barriers.yaml",
+    "lib/identity/persona.mjs",
+  ]) assert.equal(isFixturePath(p), false, p);
+});
+
+test("PLACEHOLDER_PENDING is a shrinking ratchet: a baselined file that went clean FAILS", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "ratchet-ph3-"));
+  mkdirSync(join(cwd, "scripts"), { recursive: true });
+  writeFileSync(join(cwd, "scripts", "clean.mjs"), "export const x = 1;\n");
+  const pending = [{ file: "scripts/clean.mjs", reason: "stale baseline entry, ten chars plus" }];
+  const res = findPlaceholderIdentity({ cwd, pending });
+  assert.deepEqual(res.regressions, []);
+  assert.deepEqual(res.pendingClean, ["scripts/clean.mjs"], "clean baseline entry must be deleted");
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+test("PLACEHOLDER_PENDING suppresses only its own listed files, and reports them", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "ratchet-ph4-"));
+  mkdirSync(join(cwd, "scripts"), { recursive: true });
+  writeFileSync(join(cwd, "scripts", "known.mjs"), 'const a = "Northwind";\n');
+  writeFileSync(join(cwd, "scripts", "new.mjs"), 'const b = "PartnerCo";\n');
+  const pending = [{ file: "scripts/known.mjs", reason: "not yet grounded in config/company.json" }];
+  const res = findPlaceholderIdentity({ cwd, pending });
+  assert.deepEqual(res.regressions.map((r) => r.file), ["scripts/new.mjs"], "only the NEW file fails");
+  assert.deepEqual(res.pendingDirty.map((e) => e.file), ["scripts/known.mjs"], "the baseline is reported, not hidden");
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+test("assertPendingPolicy rejects an undocumented baseline entry", () => {
+  assert.throws(() => assertPendingPolicy([{ file: "scripts/x.mjs", reason: "meh" }]), /needs a real/);
+  assert.throws(() => assertPendingPolicy([{ reason: "a perfectly long reason" }]), /no `file`/);
+  assertPendingPolicy(PLACEHOLDER_PENDING); // the shipped baseline is in policy
+});
+
+test("the files this lane grounded are NOT on the baseline and are clean in-tree", () => {
+  const grounded = [
+    "scripts/huddle/huddle-server.mjs",
+    "scripts/daemon/classifier.mjs",
+    "scripts/daemon/prompt-builder.mjs",
+    "scripts/cloud-relay/voice/server.mjs",
+    "scripts/media-generation/generate-assets.mjs",
+    "scripts/media-generation/gemini-image-client.mjs",
+    "scripts/spawn-session.sh",
+    "scripts/pre-draft-context.py",
+    "scripts/disclosure_boundaries.py",
+    "policies/information-barriers.yaml",
+  ];
+  const baselined = new Set(PLACEHOLDER_PENDING.map((e) => e.file));
+  for (const f of grounded) {
+    assert.equal(baselined.has(f), false, `${f} must not be baselined — it is grounded`);
+    assert.equal(scanPlaceholders(readFileSync(new URL(`../../${f}`, import.meta.url), "utf8")).length, 0, f);
+  }
+});

package/scripts/cloud-relay/voice/relay-identity.test.mjs

@@ -0,0 +1,96 @@
+/**
+ * relay-identity.test.mjs — the PSTN relay must never invent an employer.
+ *
+ * WHAT BROKE
+ *   `buildSessionUpdate()` built its last-resort instructions as:
+ *     `You are ${identity.name || "the agent"}, ${identity.role || "an executive
+ *      operator"} at ${identity.company || "Northwind"}.`
+ *   This service is the DEPLOYED Railway relay that answers inbound PSTN calls.
+ *   The fallback fires whenever the local agent queues a call with a bare
+ *   `brief` and no `instructions`, and whatever it says is spoken to a person on
+ *   a phone line — it leaves the org irrecoverably.
+ *
+ * WHY THE FIX IS SERVER-SIDE REFUSAL
+ *   The relay runs on Railway with no access to config/agent.json or
+ *   config/company.json. Everything it knows about the agent arrived in the
+ *   queue entry. A field that did not arrive is a field this process CANNOT
+ *   know, so the only honest behaviour is to drop the clause.
+ *
+ * HOW IT RUNS
+ *   The relay ships its own package.json and depends on `ws`, which is not
+ *   resolvable from this repo root, so server.mjs cannot be imported in-process.
+ *   The identity helpers are pure, so we lift their REAL source out of the
+ *   shipped file and evaluate that — the text under test is the text that ships.
+ *
+ * Run: node --test scripts/cloud-relay/voice/relay-identity.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+const SRC = readFileSync(new URL("./server.mjs", import.meta.url), "utf8");
+
+function extractFunction(src, name) {
+  const re = new RegExp(`(?:export\\s+)?function\\s+${name}\\s*\\(`);
+  const m = re.exec(src);
+  assert.ok(m, `server.mjs no longer defines ${name}() — update this test deliberately`);
+  const open = src.indexOf("{", m.index + m[0].length - 1);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === "{") depth++;
+    else if (src[i] === "}" && --depth === 0) return src.slice(m.index, i + 1).replace(/^export\s+/, "");
+  }
+  throw new Error(`unbalanced braces extracting ${name}`);
+}
+
+const names = ["configured", "fallbackInstructions"];
+const mod = new Function(
+  `${names.map((n) => extractFunction(SRC, n)).join("\n\n")}\nreturn { ${names.join(", ")} };`,
+)();
+const { fallbackInstructions } = mod;
+
+// ── GROUNDED — the local agent shipped a real identity ──────────────────────
+
+test("grounded: the full identity from the queue entry is spoken", () => {
+  const out = fallbackInstructions({ name: "Robin Okafor", role: "VP Operations", company: "Meridian Freight" });
+  assert.equal(out, "You are Robin Okafor, VP Operations at Meridian Freight. Reply briefly in your voice.");
+});
+
+// ── EMPTY — omit the clause, never substitute a default ─────────────────────
+
+test("empty: no company ⇒ the 'at <company>' clause is DROPPED, not defaulted", () => {
+  const out = fallbackInstructions({ name: "Robin Okafor", role: "VP Operations" });
+  assert.equal(out, "You are Robin Okafor, VP Operations. Reply briefly in your voice.");
+  assert.doesNotMatch(out, / at /);
+});
+
+test("empty: the UNCONFIGURED sentinel is treated as absent", () => {
+  const out = fallbackInstructions({ name: "Robin Okafor", role: "VP Operations", company: "UNCONFIGURED" });
+  assert.doesNotMatch(out, /UNCONFIGURED/);
+  assert.doesNotMatch(out, / at /);
+});
+
+test("empty: no role ⇒ no invented role", () => {
+  const out = fallbackInstructions({ name: "Robin Okafor" });
+  assert.equal(out, "You are Robin Okafor. Reply briefly in your voice.");
+  assert.doesNotMatch(out, /executive operator/i);
+});
+
+test("empty: nothing at all ⇒ NO persona is asserted to the caller", () => {
+  for (const id of [{}, { name: "", role: "", company: "" }, { name: "   " }]) {
+    const out = fallbackInstructions(id);
+    assert.equal(out, "Reply briefly in your voice.", JSON.stringify(id));
+    assert.doesNotMatch(out, /You are/);
+  }
+});
+
+// ── The literal is gone from the deployed source ────────────────────────────
+
+test("the deployed relay source carries no default employer", () => {
+  assert.doesNotMatch(SRC, /\bNorthwind\b/i);
+  assert.doesNotMatch(SRC, /identity\.company \|\|/, "no `|| <default>` on the employer");
+  assert.doesNotMatch(SRC, /an executive operator/, "no `|| <default>` on the role");
+});

package/scripts/cloud-relay/voice/server.mjs

@@ -490,6 +490,47 @@ function handleTwilioStream(twilioWs, req) {
   }
 }
 
+/**
+ * A config value the operator has not filled in yet. The scaffold ships
+ * `"name": "UNCONFIGURED"` in config/company.json and empty strings elsewhere,
+ * so BOTH shapes mean "absent" and neither may be rendered into speech.
+ * @param {*} v
+ * @returns {string} the trimmed value, or "" when it is absent/unconfigured
+ */
+function configured(v) {
+  const s = typeof v === "string" ? v.trim() : "";
+  if (!s) return "";
+  if (s.toUpperCase() === "UNCONFIGURED") return "";
+  return s;
+}
+
+/**
+ * Last-resort identity line for a call whose queue entry carried neither
+ * `instructions` nor a `brief`.
+ *
+ * FAIL CLOSED ON IDENTITY. This relay runs on Railway with no access to the
+ * agent's config/agent.json or config/company.json — everything it knows about
+ * who the agent is arrived in the queue entry from lib/voice/outbound.mjs. A
+ * field that did not arrive is a field this process CANNOT know, and this text
+ * is spoken to a person on a PSTN call: a wrong employer leaves the org
+ * irrecoverably. So an absent field drops its clause rather than taking a
+ * default. A generic directive is honest; an invented company is not.
+ *
+ * @param {{name?:string, role?:string, company?:string}} identity
+ * @returns {string}
+ */
+function fallbackInstructions(identity) {
+  const name = configured(identity.name);
+  const role = configured(identity.role);
+  const company = configured(identity.company);
+  const who = [name, role].filter(Boolean).join(", ");
+  const at = company ? ` at ${company}` : "";
+  // No name and no role: say nothing about identity at all rather than assert
+  // a persona the caller never supplied.
+  const lead = who ? `You are ${who}${at}. ` : "";
+  return `${lead}Reply briefly in your voice.`;
+}
+
 function buildSessionUpdate(queued) {
   const voice = queued.voice || "cedar";
   const identity = queued.identity || {};
@@ -497,8 +538,7 @@ function buildSessionUpdate(queued) {
   // local agent shipped — includes identity, memory, RAG, peer info,
   // voice-mode rules) over the bare `brief`. The `brief` describes
   // the task; `instructions` describes the whole agent.
-  const instructions = queued.instructions || queued.brief ||
-    `You are ${identity.name || "the agent"}, ${identity.role || "an executive operator"} at ${identity.company || "Northwind"}. Reply briefly in your voice.`;
+  const instructions = queued.instructions || queued.brief || fallbackInstructions(identity);
   return {
     type: "session.update",
     session: {