@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/scripts/daemon/agent-daemon-design.test.mjs

@@ -0,0 +1,238 @@
+/**
+ * agent-daemon-design.test.mjs — the daemon re-syncs the brand foundation into
+ * DESIGN.md + PRODUCT.md, polled every 15 minutes and rewritten when the
+ * foundation's version moves (WP-M7 mechanic 4).
+ *
+ * Drives the REAL `refreshDesignFoundation` with an injected
+ * `branding.getFoundation` and a fixed clock under a tmp AGENT_DIR — the same
+ * shape as `agent-daemon-board-mine.test.mjs`, including its `imapflow` loader
+ * stub, because importing the daemon module pulls the whole seat in.
+ *
+ * The four claims: the 15-minute gate bounds the reads; a moved version is
+ * detected and named on the poll that sees it; an un-enrolled seat writes
+ * nothing; and no failure of hq's can blank a DESIGN.md already on disk.
+ */
+
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import { register } from "node:module";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, statSync, utimesSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const loaderSrc = `
+export async function resolve(specifier, context, next) {
+  if (specifier === "imapflow") return { url: "imapflow-stub:main", shortCircuit: true };
+  return next(specifier, context);
+}
+export async function load(url, context, next) {
+  if (url === "imapflow-stub:main") return { format: "module", shortCircuit: true, source: "export class ImapFlow {}" };
+  return next(url, context);
+}
+`;
+register(`data:text/javascript,${encodeURIComponent(loaderSrc)}`);
+
+const AGENT_DIR = mkdtempSync(join(tmpdir(), "maestro-daemon-design-"));
+process.env.AGENT_DIR = AGENT_DIR;
+process.env.MAESTRO_DAEMON_NO_AUTOSTART = "1";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+const FIFTEEN_MIN = 15 * 60_000;
+const DESIGN = join(AGENT_DIR, "DESIGN.md");
+const PRODUCT = join(AGENT_DIR, "PRODUCT.md");
+const STATE = join(AGENT_DIR, "state", "design", "foundation.json");
+
+const FIXTURE = JSON.parse(readFileSync(new URL("../../lib/design/fixtures/foundation.json", import.meta.url), "utf8"));
+
+const frame = (over = {}) => ({
+  ok: true,
+  result: {
+    foundation: FIXTURE,
+    version: { id: "bv_01HQZ", seq: 7, label: "V2.7" },
+    headVersionId: "bv_01HQZ",
+    isHead: true,
+    unversioned: false,
+    history: [],
+    ...over,
+  },
+});
+
+let daemon;
+before(async () => {
+  mkdirSync(join(AGENT_DIR, "config"), { recursive: true });
+  mkdirSync(join(AGENT_DIR, "state", "sessions", "locks"), { recursive: true });
+  writeFileSync(
+    join(AGENT_DIR, "config", "org.yaml"),
+    "org:\n  cohort:\n    enabled: true\n    base: https://os.example.test\n    token: nlk_test_token\n    orgId: org_test\n    orgName: Northwind\n",
+  );
+  writeFileSync(join(AGENT_DIR, "config", "agent.json"), JSON.stringify({ firstName: "Nova", lastName: "Reyes" }));
+  const url = new URL("./agent-daemon.mjs", import.meta.url);
+  daemon = await import(`${url.href}?design=${Math.random()}`);
+});
+
+test("the first tick writes DESIGN.md + PRODUCT.md from the seat's own connection", async () => {
+  const calls = [];
+  const getFoundationImpl = async (params, o) => { calls.push({ params, o }); return frame(); };
+
+  const first = await daemon.refreshDesignFoundation({ now: NOW, getFoundationImpl });
+  assert.equal(first.refreshed, true);
+  assert.equal(first.reason, "never", "the gate's own words for a seat that had never synced");
+  assert.deepEqual(first.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.equal(first.version, "bv_01HQZ");
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].params, { historyLimit: 0 });
+  assert.equal(calls[0].o.base, "https://os.example.test", "the daemon's org.yaml connection is what the read gets");
+  assert.equal(calls[0].o.orgId, "org_test");
+
+  assert.match(readFileSync(DESIGN, "utf8"), /^---\nname: "Northwind"\n/);
+  assert.match(readFileSync(PRODUCT, "utf8"), /# Northwind — product voice/);
+  assert.equal(statSync(DESIGN).mode & 0o777, 0o644);
+  assert.equal(JSON.parse(readFileSync(STATE, "utf8")).version, "bv_01HQZ");
+});
+
+test("a tick inside 15 minutes spends no hq call at all", async () => {
+  let calls = 0;
+  const getFoundationImpl = async () => { calls += 1; return frame(); };
+  const soon = await daemon.refreshDesignFoundation({ now: NOW + 14 * 60_000, getFoundationImpl });
+  assert.deepEqual(soon, { refreshed: false, reason: "fresh" });
+  assert.equal(calls, 0, "the gate is asked BEFORE the read, which is the point of it");
+});
+
+test("a tick at 15 minutes reads, finds nothing changed, and touches no file", async () => {
+  const old = new Date(NOW - 86_400_000);
+  utimesSync(DESIGN, old, old);
+  utimesSync(PRODUCT, old, old);
+  const before = [statSync(DESIGN).mtimeMs, statSync(PRODUCT).mtimeMs];
+
+  let calls = 0;
+  const at = await daemon.refreshDesignFoundation({ now: NOW + FIFTEEN_MIN, getFoundationImpl: async () => { calls += 1; return frame(); } });
+  assert.equal(calls, 1, "the interval is what bounds the reads — hq has no cheap etag for this");
+  assert.equal(at.refreshed, false, "an unchanged foundation is not a refresh");
+  assert.equal(at.reason, "interval");
+  assert.deepEqual([statSync(DESIGN).mtimeMs, statSync(PRODUCT).mtimeMs], before, "not one mtime moved");
+});
+
+test("a moved foundation is picked up on the next poll, and named 'version-changed' not 'interval'", async () => {
+  // The honest bound: hq exposes no cheap "has the foundation changed?" etag
+  // the way `integration.toolsetVersion` does, so a version change can only be
+  // SEEN by a read, and the 15-minute gate is what bounds the reads. What the
+  // gate's second call buys is a truthful reason — the daemon logs why this
+  // tick rewrote the file, and "the palette moved" is not "the timer fired".
+  const moved = JSON.parse(JSON.stringify(FIXTURE));
+  moved.colors[2].value = "#0f172a";
+  const r = await daemon.refreshDesignFoundation({
+    now: NOW + 2 * FIFTEEN_MIN,
+    getFoundationImpl: async () => frame({ foundation: moved, headVersionId: "bv_02", version: { id: "bv_02", seq: 8, label: "V2.8" } }),
+  });
+
+  assert.equal(r.refreshed, true);
+  assert.equal(r.reason, "version-changed", "not 'interval' — the gate's second call names the real cause");
+  assert.ok(r.written.includes("DESIGN.md"));
+  assert.match(readFileSync(DESIGN, "utf8"), /primary-moss: "#0f172a"/);
+  assert.match(readFileSync(DESIGN, "utf8"), /\*\*Version:\*\* V2\.8/);
+  assert.equal(JSON.parse(readFileSync(STATE, "utf8")).version, "bv_02");
+});
+
+test("a forced tick inside the interval still sees a version change for what it is", async () => {
+  const moved = JSON.parse(JSON.stringify(FIXTURE));
+  moved.colors[2].value = "#334155";
+  const r = await daemon.refreshDesignFoundation({
+    now: NOW + 2 * FIFTEEN_MIN + 60_000, // one minute later: the gate would say "fresh"
+    force: true,
+    getFoundationImpl: async () => frame({ foundation: moved, headVersionId: "bv_03", version: { id: "bv_03", seq: 9, label: "V2.9" } }),
+  });
+  assert.equal(r.reason, "version-changed");
+  assert.ok(r.written.includes("DESIGN.md"));
+});
+
+test("a fetch failure keeps the DESIGN.md already on disk — fail-open, never blanked", async () => {
+  const good = readFileSync(DESIGN, "utf8");
+  const old = new Date(NOW - 86_400_000);
+  utimesSync(DESIGN, old, old);
+  const mtime = statSync(DESIGN).mtimeMs;
+  const now = NOW + 4 * FIFTEEN_MIN;
+
+  const thrown = await daemon.refreshDesignFoundation({ now, getFoundationImpl: async () => { throw new Error("ECONNREFUSED"); } });
+  assert.deepEqual(thrown, { refreshed: false, reason: "fetch-failed" });
+
+  const errored = await daemon.refreshDesignFoundation({ now, getFoundationImpl: async () => ({ ok: false, error: { code: "UNAUTHORIZED", message: "bad token" } }) });
+  assert.deepEqual(errored, { refreshed: false, reason: "error:UNAUTHORIZED" });
+
+  const empty = await daemon.refreshDesignFoundation({ now, getFoundationImpl: async () => ({ ok: true, result: { foundation: null, headVersionId: null } }) });
+  assert.deepEqual(empty, { refreshed: false, reason: "no-foundation" });
+
+  assert.equal(readFileSync(DESIGN, "utf8"), good, "three failures, and the last-good file is byte-identical");
+  assert.equal(statSync(DESIGN).mtimeMs, mtime);
+});
+
+test("an org-disabled seat writes nothing and spends no call", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "maestro-daemon-design-off-"));
+  try {
+    mkdirSync(join(dir, "config"), { recursive: true });
+    mkdirSync(join(dir, "state", "sessions", "locks"), { recursive: true });
+    writeFileSync(join(dir, "config", "org.yaml"), "org:\n  cohort:\n    enabled: false\n");
+    writeFileSync(join(dir, "config", "agent.json"), JSON.stringify({ firstName: "Nova" }));
+
+    const prev = process.env.AGENT_DIR;
+    process.env.AGENT_DIR = dir;
+    let off;
+    try {
+      const url = new URL("./agent-daemon.mjs", import.meta.url);
+      off = await import(`${url.href}?designoff=${Math.random()}`);
+    } finally {
+      process.env.AGENT_DIR = prev;
+    }
+
+    let calls = 0;
+    const r = await off.refreshDesignFoundation({ now: NOW, getFoundationImpl: async () => { calls += 1; return frame(); } });
+    assert.deepEqual(r, { refreshed: false, reason: "org-disabled" });
+    assert.equal(calls, 0);
+    assert.ok(!existsSync(join(dir, "DESIGN.md")));
+    assert.ok(!existsSync(join(dir, "state", "design", "foundation.json")));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("force skips the gate but nothing else — an unchanged foundation still writes nothing", async () => {
+  // Re-establish the on-disk files from the CURRENT head, then force a second
+  // read one second later: the gate would have said "fresh", the read happens
+  // anyway, and the byte comparison still refuses to touch the files.
+  const now = NOW + 5 * FIFTEEN_MIN;
+  await daemon.refreshDesignFoundation({ now, force: true, getFoundationImpl: async () => frame() });
+  let calls = 0;
+  const r = await daemon.refreshDesignFoundation({ now: now + 1_000, force: true, getFoundationImpl: async () => { calls += 1; return frame(); } });
+  assert.equal(calls, 1, "a forced tick reads even though the gate would have said 'fresh'");
+  assert.deepEqual(r.written, [], "and still writes nothing when the bytes already match");
+  assert.equal(r.refreshed, false);
+});
+
+test("a workspace that never saved a foundation gets nothing written — not hq's stock defaults", async () => {
+  // hq NEVER returns a null foundation: an org with no saved one reads back
+  // `dsDefaults()` (a complete, plausible palette that is nobody's brand) with
+  // `unversioned: true`. Writing it would ground the seat's design skills in
+  // another product's palette, with a generated file's authority behind it.
+  const dir = mkdtempSync(join(tmpdir(), "maestro-daemon-design-unver-"));
+  const prevAgent = process.env.AGENT_DIR;
+  try {
+    mkdirSync(join(dir, "config"), { recursive: true });
+    writeFileSync(
+      join(dir, "config", "org.yaml"),
+      "org:\n  cohort:\n    enabled: true\n    base: https://os.example.test\n    token: nlk_test_token\n    orgId: org_test\n    orgName: Northwind\n",
+    );
+    process.env.AGENT_DIR = dir;
+    const mod = await import(`${new URL("./agent-daemon.mjs", import.meta.url).href}?unver=${Math.random()}`);
+    const r = await mod.refreshDesignFoundation({
+      now: NOW,
+      getFoundationImpl: async () => frame({ headVersionId: null, version: null, unversioned: true }),
+    });
+    assert.deepEqual(r, { refreshed: false, reason: "unversioned" });
+    assert.ok(!existsSync(join(dir, "DESIGN.md")), "no DESIGN.md invented from stock defaults");
+    assert.ok(!existsSync(join(dir, "PRODUCT.md")));
+    assert.ok(!existsSync(join(dir, "state", "design", "foundation.json")));
+  } finally {
+    process.env.AGENT_DIR = prevAgent;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/scripts/daemon/agent-daemon.mjs

@@ -98,6 +98,9 @@ import { isEnabled as orgEnabled, loadOrgConfig, configFromAgent, electResponder
 // read it. The when/what is pure (lib/org/board-mine-cache.mjs); the I/O is here.
 import { shouldRefresh as boardMineShouldRefresh, renderRefresh as renderBoardMineRefresh, cacheTs as boardMineCacheTs, BOARD_MINE_REL } from "../../lib/org/board-mine-cache.mjs";
 import { writeJsonAtomic as writeJsonAtomicFile } from "../../lib/fs-atomic.mjs";
+import { brandingGetFoundation } from "../../lib/org/client.mjs";
+import { shouldRefreshDesign, foundationVersion, isUnversionedFoundation, DESIGN_REFRESH_INTERVAL_MS } from "../../lib/design/refresh-gate.mjs";
+import { syncDesign, readFoundationState, workspaceName as designWorkspaceName } from "../../lib/design/write.mjs";
 import { remember as orgRemember } from "../../lib/org/knowledge.mjs";
 import { sweepSessionOutcomes, resultTextFromStdout } from "./session-outcomes.mjs";
 import { recordWorkStep as orgRecordWorkStep, cohortChannelId, cohortMessageId } from "../../lib/org/work-ledger.mjs";
@@ -1794,6 +1797,101 @@ export async function refreshBoardMineCache(deps = {}) {
   return { refreshed: true, reason: doc.stale ? "kept-previous" : "written", count: doc.items.length };
 }
 
+/**
+ * Re-sync the workspace brand foundation into DESIGN.md + PRODUCT.md (WP-M7
+ * mechanic 4), in the same idiom as `refreshIntegrationTools` in
+ * `lib/org/mesh.mjs`: a cheap gated poll on the beat, fail-open end to end,
+ * keeping the last-good files when hq is unreachable.
+ *
+ * WHY THIS EXISTS AT ALL. Every design skill on the seat is told to read
+ * `$AGENT_ROOT/DESIGN.md` before it picks a colour or a typeface. A designer
+ * working from a palette a human replaced last week is worse than one with no
+ * palette, because the stale file looks authoritative — so the seat follows the
+ * foundation rather than waiting for someone to re-run the CLI.
+ *
+ * THE GATE IS ASKED TWICE (see `lib/design/refresh-gate.mjs`): once before the
+ * read, with the version unknown, to decide whether to spend a call at all
+ * (15-minute floor); once after, with the version hq returned, to say honestly
+ * WHY this tick refreshed. hq exposes no cheap "has the foundation changed"
+ * etag the way `integration.toolsetVersion` does, so the version comparison can
+ * only happen after a read and the interval is what bounds the reads.
+ *
+ * FAIL-OPEN, AND SILENT ABOUT NOTHING. An un-enrolled seat writes nothing and
+ * says so; a fetch failure keeps the files that are already on disk and logs
+ * the reason. The write itself is byte-idempotent (`syncDesign`), so a steady
+ * foundation never touches an mtime — which is what keeps a git tree clean and
+ * an editor's file watcher quiet on a seat that polls every 15 minutes.
+ *
+ * @param {{now?:number, intervalMs?:number, force?:boolean, getFoundationImpl?:Function, fetchImpl?:Function}} [deps]
+ * @returns {Promise<{refreshed:boolean, reason:string, version?:string|null, written?:string[]}>}
+ */
+export async function refreshDesignFoundation(deps = {}) {
+  const now = Number.isFinite(deps.now) ? deps.now : Date.now();
+  const intervalMs = Number.isFinite(deps.intervalMs) ? deps.intervalMs : DESIGN_REFRESH_INTERVAL_MS;
+  const prior = readFoundationState(AGENT_REPO_DIR);
+  const before = shouldRefreshDesign({
+    lastVersion: prior ? prior.version : null,
+    currentVersion: null,
+    lastAt: prior ? prior.fetchedAt : null,
+    now,
+    intervalMs,
+  });
+  if (!deps.force && !before.refresh) return { refreshed: false, reason: "fresh" };
+
+  const cfg = daemonOrgCfg();
+  if (!orgEnabled(cfg)) return { refreshed: false, reason: "org-disabled" };
+  const conn = configFromAgent(cfg) || {};
+
+  let frame;
+  try {
+    frame = await (deps.getFoundationImpl || brandingGetFoundation)(
+      { historyLimit: 0 },
+      { base: conn.base, token: conn.token, orgId: conn.orgId, fetchImpl: deps.fetchImpl },
+    );
+  } catch (err) {
+    console.warn(`[daemon] design sync: foundation read failed (${err && err.message ? err.message : err}) — keeping the DESIGN.md already on disk`);
+    return { refreshed: false, reason: "fetch-failed" };
+  }
+  if (!frame || !frame.ok || !frame.result || typeof frame.result !== "object" || !frame.result.foundation) {
+    const why = frame && frame.error && frame.error.code ? frame.error.code : "no-foundation";
+    return { refreshed: false, reason: why === "no-foundation" ? "no-foundation" : `error:${why}` };
+  }
+  // A workspace that has never SAVED a foundation reads back hq's own product
+  // defaults with `unversioned: true` — a complete palette that is nobody's
+  // brand. Writing it would ground every design skill on the seat in the wrong
+  // palette, with a generated file's authority behind it. Nothing is written
+  // and nothing already on disk is disturbed; see
+  // refresh-gate.mjs#isUnversionedFoundation.
+  if (isUnversionedFoundation(frame.result)) return { refreshed: false, reason: "unversioned" };
+
+  // The second gate call: now that the version is known, say why this tick ran.
+  const after = shouldRefreshDesign({
+    lastVersion: prior ? prior.version : null,
+    currentVersion: foundationVersion(frame.result),
+    lastAt: prior ? prior.fetchedAt : null,
+    now,
+    intervalMs,
+  });
+
+  let out;
+  try {
+    out = syncDesign({
+      agentRoot: AGENT_REPO_DIR,
+      result: frame.result,
+      now,
+      name: designWorkspaceName(cfg),
+      source: "cohort · branding.getFoundation",
+    });
+  } catch (err) {
+    console.warn(`[daemon] design sync: write failed (${err && err.message ? err.message : err})`);
+    return { refreshed: false, reason: "write-failed" };
+  }
+  if (out.written.length) {
+    console.log(`[daemon] design sync (${after.reason}) → wrote ${out.written.join(", ")}${out.version ? ` — foundation ${out.version}` : ""}`);
+  }
+  return { refreshed: out.written.length > 0, reason: after.reason, version: out.version, written: out.written };
+}
+
 /** Longest completion note we will put on a board comment. */
 const COMPLETION_NOTE_CHARS = 1200;
 
@@ -2376,6 +2474,16 @@ async function main() {
     }
   }, POLL_INTERVAL);
 
+  // Brand foundation → DESIGN.md + PRODUCT.md, every 15 min (WP-M7). Fired once
+  // at boot so a seat that has never synced has its design files before the
+  // first session opens, then on its own interval. Fail-open and never awaited:
+  // the design docs are guidance, and no failure to fetch them may hold up the
+  // poll loop.
+  refreshDesignFoundation().catch((err) => console.error("[daemon] design sync error:", err.message));
+  setInterval(() => {
+    refreshDesignFoundation().catch((err) => console.error("[daemon] design sync error:", err.message));
+  }, DESIGN_REFRESH_INTERVAL_MS);
+
   // Fast reactive cohort scan — drains org-push-fetched DMs in ~2s instead of
   // waiting up to 60s for the full poll. Local YAML only; no API/rate-limit cost.
   setInterval(() => {

package/scripts/daemon/cadence-consumer-frontdoor.test.mjs

@@ -26,7 +26,8 @@ import { join, dirname } from "node:path";
 
 import { enqueueTick, listInbox, busDepth, getBusPaths } from "../../lib/cadence-bus.mjs";
 import { listHandoffs, handoffPaths, writeHandoff, ackHandoff, DEFAULT_HANDOFF_DEADLINE_MS, DEFAULT_HANDOFF_RETENTION_MS } from "../../lib/session/handoffs.mjs";
-import { startConsumer as startConsumerRaw } from "./cadence-consumer.mjs";
+import { startConsumer as startConsumerRaw, renderCadencePromptBody } from "./cadence-consumer.mjs";
+import { withParallelism, countParallelism, PARALLELISM_DIRECTIVE } from "../../lib/prompts/parallelism.mjs";
 
 const ADMIT_ALL = { admit: () => ({ decision: "ADMIT", reason: "test", snapshot: {} }), defaultDeps: () => ({}) };
 const RATE_OK = { checkRateLimit: () => ({ allowed: true, retryAt: null }), classifyStderr: () => false, recordRateLimit: () => {}, recordSuccess: () => {} };
@@ -85,7 +86,11 @@ test("live session: an escalate tick is handed to the session — handoff + rend
     assert.equal(open[0].mode, "escalate");
     assert.ok(open[0].deadlineAt, "carries a deadline");
     assert.ok(existsSync(open[0].promptPath), "the rendered prompt is on disk");
-    assert.equal(readFileSync(open[0].promptPath, "utf-8"), "# daily-morning-brief for Nova", "identity tokens rendered");
+    assert.equal(
+      readFileSync(open[0].promptPath, "utf-8"),
+      withParallelism("# daily-morning-brief for Nova"),
+      "identity tokens rendered, and the handed prompt is byte-identical to what a sub-session would have been given",
+    );
     assert.equal(busDepth(root).inbox, 0);
     assert.equal(busDepth(root).claimed, 0);
     const done = processedEvents(root).find((e) => e.id === t.id);
@@ -332,3 +337,57 @@ test("handoff ledger hygiene: the sweep prunes done/ records and prompts past re
     assert.equal(existsSync(join(paths.prompts, "evt-done.md")), false);
   } finally { await consumer.stop(); await rmRoot(root); }
 });
+
+// ── the parallelism directive on the escalate/guarded lane (WP-M7 mechanic 5) ──
+//
+// The spec puts the directive on "every escalate/guarded sub-session prompt".
+// Cadence trigger prompts never pass through `prompt-builder.mjs#buildPrompt`
+// — they are read straight off schedules/triggers/<name>.md — so this lane has
+// its own seam (`renderCadencePromptBody`) and needs its own pins. Without it
+// an `escalate` tick whose trigger asks for six independent audits spawns a
+// sub-session with no standing permission to fan out.
+
+test("escalate: the spawned sub-session prompt leads with the parallelism directive, exactly once", async () => {
+  const root = await makeAgentRoot();
+  plantPrompt(root, "daily-morning-brief", "# daily-morning-brief for {{agent.firstName}}\n\nAudit six things.");
+  const spawns = [];
+  const consumer = startConsumer({
+    agentRoot: root,
+    frontDoorState: NOT_LIVE,
+    spawnSession: async (o) => { spawns.push(o); return { ok: true, exit_code: 0, duration_ms: 1 }; },
+  });
+  try {
+    enqueueTick({ cadence: "daily-morning-brief", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    assert.equal(spawns.length, 1);
+    // The injected spawner is handed the promptPath, not the body — so assert
+    // on the seam the real spawner uses to turn that path into argv.
+    const body = renderCadencePromptBody(root, readFileSync(join(root, spawns[0].promptPath), "utf-8"));
+    assert.ok(body.startsWith(PARALLELISM_DIRECTIVE), "the directive leads");
+    assert.equal(countParallelism(body), 1);
+    assert.ok(body.endsWith("# daily-morning-brief for Nova\n\nAudit six things."), "and the trigger body follows, tokens rendered");
+  } finally { await consumer.stop(); await rmRoot(root); }
+});
+
+test("a trigger that already carries the directive is not given a second copy", () => {
+  const body = renderCadencePromptBody("/nonexistent-agent-root", withParallelism("# already-primed"));
+  assert.equal(countParallelism(body), 1, "idempotent — a repeated directive reads as emphasis and erodes the file-scope rule");
+  assert.equal(body, withParallelism("# already-primed"));
+});
+
+test("the handed-off prompt and the spawned prompt are the same bytes", async () => {
+  const root = await makeAgentRoot();
+  const raw = "# weekly-strategic-memo for {{agent.firstName}}";
+  plantPrompt(root, "weekly-strategic-memo", raw);
+  const consumer = startConsumer({ agentRoot: root, frontDoorState: LIVE, spawnSession: async () => ({ ok: true, exit_code: 0 }) });
+  try {
+    enqueueTick({ cadence: "weekly-strategic-memo", source: "launchd", agentRoot: root });
+    await consumer.tickOnce();
+    const open = listHandoffs(root);
+    assert.equal(open.length, 1);
+    const handed = readFileSync(open[0].promptPath, "utf-8");
+    assert.equal(handed, renderCadencePromptBody(root, raw), "one seam, two lanes");
+    assert.equal(countParallelism(handed), 1);
+    assert.ok(handed.startsWith(PARALLELISM_DIRECTIVE));
+  } finally { await consumer.stop(); await rmRoot(root); }
+});

package/scripts/daemon/cadence-consumer.mjs

@@ -100,6 +100,7 @@ import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
 import { isHumanLaneCadence } from "../../lib/cadences.mjs";
 import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
 import { renderTemplate, buildContext } from "../../lib/render.mjs";
+import { withParallelism } from "../../lib/prompts/parallelism.mjs";
 // Model router (opt-in). A `schema_version: 2` config routes each cadence
 // sub-session's model through resolveChain (SPEC §6.2): the RouteDecision
 // supplies the --model flag, the session-retarget env (third-party backends),
@@ -315,6 +316,43 @@ export function routeCadenceSpawn(agentRoot, cadence) {
   }
 }
 
+/**
+ * A cadence trigger prompt, as the sub-session actually receives it.
+ *
+ * TWO transforms, and BOTH lanes must apply them or the two lanes disagree
+ * about what the same tick asked for:
+ *
+ *   1. `{{agent.*}}` / `{{company.*}}` identity tokens are rendered from
+ *      config/agent.json + config/company.json (lib/render.mjs), so a trigger
+ *      shipped generically in the package resolves to THIS seat. No-op on
+ *      token-free text.
+ *   2. The fleet parallelism directive LEADS the body (WP-M7 mechanic 5). An
+ *      escalate/guarded tick is exactly the sub-session the directive exists
+ *      for — a trigger that asks for six independent audits has, without it,
+ *      no standing permission to fan out, and runs them one at a time. The
+ *      inbox/backlog lane gets this from `prompt-builder.mjs#buildPrompt`;
+ *      cadence prompts never pass through that builder, which is how this lane
+ *      was missed. `withParallelism` is idempotent, so a trigger file that
+ *      already carries the text keeps exactly one copy.
+ *
+ * Pure apart from the two config reads; a missing/invalid config/agent.json
+ * leaves the body's tokens verbatim rather than failing the tick.
+ *
+ * @param {string} agentRoot
+ * @param {string} body the raw trigger prompt as read from disk
+ * @returns {string}
+ */
+export function renderCadencePromptBody(agentRoot, body) {
+  let out = typeof body === "string" ? body : "";
+  try {
+    const agentCfg = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
+    let companyCfg = {};
+    try { companyCfg = JSON.parse(readFileSync(join(agentRoot, "config/company.json"), "utf-8")); } catch { /* optional */ }
+    out = renderTemplate(out, buildContext(agentCfg, null, companyCfg));
+  } catch { /* no/invalid config/agent.json — leave body verbatim */ }
+  return withParallelism(out);
+}
+
 /**
  * Spawn a sub-session running the cadence's trigger prompt and resolve
  * with { exit_code, durationMs, stderr_tail }. Reads the prompt at call
@@ -339,17 +377,9 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
       return;
     }
 
-    // Render {{agent.*}} / {{company.*}} identity tokens at spawn time so framework
-    // triggers stay generic in the package and resolve to THIS agent + company
-    // (see lib/render.mjs). Synchronous, from config/agent.json + config/company.json.
-    // No-op on token-free text, so this is behaviour-preserving for any not-yet-
-    // tokenised trigger.
-    try {
-      const agentCfg = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
-      let companyCfg = {};
-      try { companyCfg = JSON.parse(readFileSync(join(agentRoot, "config/company.json"), "utf-8")); } catch { /* optional */ }
-      body = renderTemplate(body, buildContext(agentCfg, null, companyCfg));
-    } catch { /* no/invalid config/agent.json — leave body verbatim */ }
+    // Identity tokens + the parallelism directive, at spawn time — one seam,
+    // shared with the front-door handoff lane. See renderCadencePromptBody.
+    body = renderCadencePromptBody(agentRoot, body);
 
     const bin = resolveClaudeBin();
     // Permission scoping (audit H1). sessionPermissionArgs() defaults to the
@@ -592,20 +622,14 @@ export function startConsumer(opts = {}) {
   }
 
   /**
-   * Render a cadence prompt the way realSpawnSession does ({{agent.*}} /
-   * {{company.*}} tokens from config/agent.json + config/company.json) and
-   * land it under state/session/handoffs/prompts/<tickId>.md so the session
-   * reads exactly what a sub-session would have been given.
+   * Render a cadence prompt the way realSpawnSession does — the SAME
+   * `renderCadencePromptBody`, so the handed-off prompt is byte-identical to
+   * what a sub-session would have been given, parallelism directive included —
+   * and land it under state/session/handoffs/prompts/<tickId>.md.
    */
   function renderHandoffPrompt(tickId, promptPath) {
     const fullPrompt = join(agentRoot, promptPath);
-    let body = readFileSync(fullPrompt, "utf-8");
-    try {
-      const agentCfg = JSON.parse(readFileSync(join(agentRoot, "config/agent.json"), "utf-8"));
-      let companyCfg = {};
-      try { companyCfg = JSON.parse(readFileSync(join(agentRoot, "config/company.json"), "utf-8")); } catch { /* optional */ }
-      body = renderTemplate(body, buildContext(agentCfg, null, companyCfg));
-    } catch { /* no/invalid config/agent.json — leave body verbatim */ }
+    const body = renderCadencePromptBody(agentRoot, readFileSync(fullPrompt, "utf-8"));
     const out = join(handoffPaths(agentRoot).prompts, `${tickId}.md`);
     writeFileAtomic(out, body);
     return out;

package/scripts/daemon/prompt-builder.mjs

@@ -12,6 +12,7 @@ import { wrapExternalContent } from "../../lib/security/external-content.mjs";
 import { isEnabled as orgEnabled } from "../../lib/org/client.mjs";
 import { recall as orgRecall } from "../../lib/org/knowledge.mjs";
 import { outcomeSourceShareable } from "./session-outcomes.mjs";
+import { withParallelism } from "../../lib/prompts/parallelism.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 
@@ -852,16 +853,23 @@ export async function buildPrompt(item, classResult, options = {}) {
   const parts = [];
 
   // 1. Persona block (cached) — rendered from config/agent.json, which the
-  // Cohort enrollment pull keeps current. Leads the prompt and outranks the
+  // Cohort enrollment pull keeps current. Leads the BODY and outranks the
   // CLAUDE.md preamble below, because a scaffolded CLAUDE.md carries
   // "identity not yet configured" placeholder prose that would otherwise
   // contradict a perfectly good org record.
+  //
+  // THE PRECEDENCE SENTENCE NAMES ITSELF, NOT A POSITION. It used to say "the
+  // section above … anything below", which was true only while the persona was
+  // the first thing in the prompt. The parallelism directive is prepended at
+  // the end of this function (§10) and now leads, so "above" had two candidate
+  // referents and the directive sat outside the rule entirely — above it, not
+  // below. A self-naming sentence stays true wherever the block ends up.
   const persona = loadPersona();
   if (persona) {
     parts.push(persona);
     parts.push("");
     parts.push(
-      "The section above is your identity, resolved from your organisation's record of you. Where anything below conflicts with it, the section above wins.",
+      "This section is your identity, resolved from your organisation's record of you. Where anything else in this prompt conflicts with it, this section wins.",
     );
     parts.push("");
   }
@@ -1025,5 +1033,13 @@ export async function buildPrompt(item, classResult, options = {}) {
   // 9. Audit instruction
   parts.push(`Log all actions taken to logs/audit/${date}-actions.jsonl as a JSON line with: timestamp, action_type, target, result, session context.`);
 
-  return parts.join("\n");
+  // 10. The parallelism directive (WP-M7 mechanic 5). Every prompt this builder
+  // produces is handed to a sub-session that may plan and dispatch work of its
+  // own, and nothing else in the prompt ever says that fanning out is allowed —
+  // which is why sessions handed six independent tasks ran them one at a time.
+  // It LEADS the prompt because it governs how the session plans, before it has
+  // read a word of the item. `withParallelism` is idempotent, so a prompt that
+  // already carries it (composed by a caller, or handed on to `session spawn`,
+  // which applies the same seam) is returned with exactly one copy.
+  return withParallelism(parts.join("\n"));
 }