@cohortapp/agent-sdk 2.9.1 → 2.10.0

package/lib/model-router.test.mjs

@@ -8,7 +8,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { promises as fsp } from "fs";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { fileURLToPath } from "node:url";
@@ -27,6 +27,9 @@ import {
   validateRoutingConfig,
 } from "./model-router.mjs";
 import { loadCatalog } from "./model-router/catalog.mjs";
+// Read-only, to PROVE (not assume) that a provider the SDK does not bundle
+// inherits credential pooling from the catalog rather than needing new code.
+import { loadAuthProfiles, authEnvMapFromCatalog } from "./model-router/auth-profiles.mjs";
 
 async function makeAgentRoot() {
   const path = join(
@@ -52,10 +55,15 @@ const ANTHROPIC_BACKEND = {
   base_url: "https://api.anthropic.com",
   capabilities: ["thinking", "vision", "prompt_cache_1h", "tool_use", "parallel_tools", "long_context_1m"],
   pricing: { input_per_m: 3.0, output_per_m: 15.0 },
+  // A CONFIG-DECLARED model map. Deliberately NOT the same ids as
+  // ANTHROPIC_DEFAULT: these tests assert that a config's own map is what
+  // resolveBackend serves, so pinning them to the built-in defaults would make
+  // the assertions vacuous (they would pass even if the config map were being
+  // ignored entirely). The built-in defaults get their own test below.
   models: {
     classifier: "claude-haiku-4-5-20251001",
-    default: "claude-sonnet-4-6",
-    premium: "claude-opus-4-7",
+    default: "config-declared-sonnet",
+    premium: "config-declared-opus",
     fast: "claude-haiku-4-5-20251001",
   },
 };
@@ -252,14 +260,59 @@ test("resolveBackend honours model_hint legacy values (opus/sonnet/haiku)", () =
   const opus = resolveBackend({ model_hint: "opus" }, { config });
   const sonnet = resolveBackend({ model_hint: "sonnet" }, { config });
   const haiku = resolveBackend({ model_hint: "haiku" }, { config });
-  assert.equal(opus.model, "claude-opus-4-7");
-  assert.equal(sonnet.model, "claude-sonnet-4-6");
+  assert.equal(opus.model, "config-declared-opus");
+  assert.equal(sonnet.model, "config-declared-sonnet");
   assert.equal(haiku.model, "claude-haiku-4-5-20251001");
   assert.equal(modelFlagFor(opus, { model_hint: "opus" }), "opus");
   assert.equal(modelFlagFor(sonnet, { model_hint: "sonnet" }), "sonnet");
   assert.equal(modelFlagFor(haiku, { model_hint: "haiku" }), "haiku");
 });
 
+// ---------------------------------------------------------------------------
+// Model freshness — the built-in Anthropic defaults (see the provenance block
+// above ANTHROPIC_DEFAULT in model-router.mjs).
+// ---------------------------------------------------------------------------
+
+test("defaultRoutingConfig ships the CURRENT Anthropic ids, not last quarter's", () => {
+  // The floor an agent with no routing config lands on. A stale id here never
+  // reached the wire (anthropic-cli sends the "opus"/"sonnet" shorthand), but it
+  // DID reach resolved.model, which the cost ledger and telemetry store — so a
+  // stale id mis-prices and mis-attributes every unrouted session.
+  const models = defaultRoutingConfig().backends.anthropic.models;
+  assert.equal(models.premium, "claude-opus-5");
+  assert.equal(models.default, "claude-sonnet-5");
+  // The fast/classifier tier did NOT move in the 2026-08-13 refresh.
+  assert.equal(models.fast, "claude-haiku-4-5-20251001");
+  assert.equal(models.classifier, "claude-haiku-4-5-20251001");
+  // Guard the specific regression: no 4.x id survives anywhere in the map.
+  for (const [tier, id] of Object.entries(models)) {
+    assert.ok(!/^claude-(opus|sonnet)-4/.test(id), `${tier} still pinned to a retired id: ${id}`);
+  }
+});
+
+test("resolveBackend serves the current ids through the no-config default path", () => {
+  // End-to-end through the resolver, not just the constant: an agent with no
+  // config file (useDefault) resolves premium/default to the -5 pair.
+  const config = defaultRoutingConfig();
+  assert.equal(resolveBackend({ model_hint: "opus" }, { config }).model, "claude-opus-5");
+  assert.equal(resolveBackend({ model_hint: "sonnet" }, { config }).model, "claude-sonnet-5");
+  // …while the CLI flag stays version-agnostic, which is WHY the stale ids were
+  // survivable on the wire and only corrupted the ledger.
+  assert.equal(modelFlagFor(resolveBackend({ model_hint: "opus" }, { config }), { model_hint: "opus" }), "opus");
+});
+
+test("a config-declared models map still outranks the built-in defaults (the no-PR refresh path)", () => {
+  // Refresh path #2 in the provenance block: when claude-opus-6 ships, a v1
+  // agent adds backends.anthropic.models to config/model-routing.yaml and is
+  // current WITHOUT an SDK release. normaliseConfig only injects the built-in
+  // map when backends.anthropic is absent, so this must win outright.
+  const config = {
+    backends: { anthropic: { ...ANTHROPIC_BACKEND, models: { ...ANTHROPIC_BACKEND.models, premium: "claude-opus-99" } } },
+    routing_policy: [{ default: true, backend: "anthropic" }],
+  };
+  assert.equal(resolveBackend({ model_hint: "opus" }, { config }).model, "claude-opus-99");
+});
+
 test("resolveBackend returns null when no backend satisfies request and fallback disabled", () => {
   const config = {
     backends: { qwen: QWEN_BACKEND },
@@ -833,6 +886,253 @@ test("resolveChain: no v2 config collapses to the Anthropic safety net", () => {
   assert.equal(d.audit.fallback_reason, "no_v2_config");
 });
 
+// ── safety-net model freshness (pickAnthropicRow's ordered preference) ───────
+//
+// The safety net fires on the three paths that have no chain to walk: the kill
+// switch, "no v2 config", and "nothing survived the gates". It is the ONE place
+// resolve.mjs still names Anthropic model ids, so it is the one place that can
+// go stale. lookupModel is an exact byRef hit (no replaced_by chasing), so the
+// preference list carries the current -5 ids AND the 4-x succession fallback.
+
+/** The bundled catalog plus synthetic claude-*-5 rows (what ships next). */
+const CATALOG_WITH_5 = loadCatalog(MAESTRO_ROOT_FOR_TESTS(), {
+  agentConfig: {
+    catalog_overrides: [
+      {
+        ref: "anthropic/claude-opus-5",
+        status: "available",
+        context_tokens: 950000,
+        max_tokens: 128000,
+        tool_reliability: "A",
+        harness: { session: true, direct: true, batch: true },
+        cost: { input: 5.0, output: 25.0, cache_read: 0.5, cache_write: 10.0 },
+      },
+      {
+        ref: "anthropic/claude-sonnet-5",
+        status: "available",
+        context_tokens: 950000,
+        max_tokens: 64000,
+        tool_reliability: "A",
+        harness: { session: true, direct: true, batch: true },
+        cost: { input: 3.0, output: 15.0, cache_read: 0.3, cache_write: 6.0 },
+      },
+    ],
+  },
+});
+
+test("resolveChain: the safety net prefers claude-opus-5 / claude-sonnet-5 when the catalog has them", () => {
+  const frontier = resolveChain(
+    { task_class: "decision", needs_thinking: true, data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG_WITH_5, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }, now: CLOCK }
+  );
+  assert.equal(frontier.chosen.model, "claude-opus-5", "thinking/critical → current frontier, not opus-4-8");
+
+  const workhorse = resolveChain(
+    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG_WITH_5, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }, now: CLOCK }
+  );
+  assert.equal(workhorse.chosen.model, "claude-sonnet-5", "ordinary work → current workhorse, not sonnet-4-6");
+});
+
+test("resolveChain: the safety net falls back through succession when the catalog has no -5 rows", () => {
+  // This is why the 4-x refs stay in the preference list. Delete them and this
+  // does NOT fail loudly — it degrades to `models.find()` over the bundled rows,
+  // i.e. whatever sits first in anthropic.yaml (opus-4-8), which would hand
+  // ORDINARY work the frontier model and quietly quadruple its cost.
+  const d = resolveChain(
+    { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
+    { catalog: CATALOG, config: V2_CONFIG, env: { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.model, "claude-sonnet-4-6", "succession fallback, ordered — NOT the first row in the file");
+  // Flip this to claude-sonnet-5 (and drop the 4-x refs from pickAnthropicRow)
+  // the day lib/model-router/catalog/anthropic.yaml carries the -5 rows.
+});
+
+test("the SHIPPED catalog is what decides the wire value — the -5 refresh is NOT done", () => {
+  // THE HONEST STATE OF THIS REFRESH, pinned so it cannot be mistaken for
+  // finished. The test above asserts `chosen.model`, which reads as bookkeeping.
+  // This one asserts `spawnArgs.modelFlag` — the string spawn.mjs pushes as
+  // `--model` — against the catalog the SDK actually ships, with `config: null`,
+  // which is the DEFAULT state of every agent because this repo contains no
+  // config/model-routing.yaml at all.
+  //
+  // Unlike the v1 lane (model-router.mjs's modelFlagFor sends the version-
+  // agnostic "opus"/"sonnet" shorthand), resolve.mjs's modelFlagFor returns
+  // row.id verbatim. So on v2 a stale catalog row is a stale id ON THE WIRE, not
+  // merely a mis-stamped ledger entry.
+  //
+  // WHEN THIS FAILS: someone added the -5 rows to anthropic.yaml. Good — that is
+  // the missing step. Update the expectations here, and DELETE the 4-x refs from
+  // pickAnthropicRow's preference lists in the same change, or the museum the
+  // provenance block warns about starts accumulating.
+  const cases = [
+    ["session.responder", {}, "claude-sonnet-4-6"],
+    ["decision", { needs_thinking: true }, "claude-opus-4-8"],
+  ];
+  for (const [task_class, extra, expected] of cases) {
+    const req = { task_class, data_class: "sensitive", token_estimate: 1000, ...extra };
+    for (const [label, env] of [
+      ["kill switch", { MAESTRO_ROUTER_FORCE_ANTHROPIC: "1" }],
+      ["no v2 config", {}],
+    ]) {
+      const d = resolveChain(req, { catalog: CATALOG, config: null, env, now: CLOCK });
+      assert.equal(
+        d.spawnArgs.modelFlag,
+        expected,
+        `${label}/${task_class}: --model is the literal catalog id, and the bundled catalog is still 4-x`
+      );
+      // Not the shorthand: nothing downstream re-resolves this to a current build.
+      assert.ok(!["opus", "sonnet", "haiku"].includes(d.spawnArgs.modelFlag));
+    }
+  }
+});
+
+test("resolveChain: with NO catalog rows at all, the synthetic row's id and ref agree", () => {
+  // The last-ditch path: no catalog, so the id goes straight onto `claude
+  // --model`. It used to emit {model: "claude-opus-4-8", ref:
+  // "anthropic/claude-sonnet-4-6"} for a thinking request — and ref is what
+  // feeds cacheAffinityKey and chain[0].ref, so the pin and the audit trail
+  // both named a different model than the one that ran.
+  const emptyDir = join(tmpdir(), `model-router-empty-catalog-${process.pid}-${Date.now()}`);
+  mkdirSync(emptyDir, { recursive: true });
+  try {
+    const EMPTY = loadCatalog(emptyDir, { bundledDir: emptyDir });
+    assert.equal(EMPTY.models.length, 0, "fixture really is an empty catalog");
+
+    const d = resolveChain(
+      { task_class: "decision", needs_thinking: true, data_class: "sensitive", token_estimate: 1000 },
+      { catalog: EMPTY, config: null, env: {}, now: CLOCK }
+    );
+    assert.equal(d.chosen.model, "claude-opus-5");
+    assert.equal(d.chain[0].ref, "anthropic/claude-opus-5", "ref tracks id");
+    assert.match(d.cacheAffinityKey, /anthropic\/claude-opus-5$/);
+
+    const ordinary = resolveChain(
+      { task_class: "session.responder", data_class: "sensitive", token_estimate: 1000 },
+      { catalog: EMPTY, config: null, env: {}, now: CLOCK }
+    );
+    assert.equal(ordinary.chosen.model, "claude-sonnet-5");
+    assert.equal(ordinary.chain[0].ref, "anthropic/claude-sonnet-5");
+  } finally {
+    rmSync(emptyDir, { recursive: true, force: true });
+  }
+});
+
+// ── cheap tier: an UNBUNDLED provider (xAI/Grok) is routable end to end ──────
+//
+// The SDK bundles catalog rows for anthropic/deepseek/moonshot/qwen only. Grok
+// is NOT bundled — but "not bundled" is not "not routable": catalog.mjs's
+// highest authority layer (config/model-routing.yaml `catalog_overrides:`) may
+// introduce a whole provider, and resolveChain gates it exactly like a bundled
+// one. These tests prove the full path — row → alias → chain → credential gate
+// → chosen — so the remaining work is a bundled YAML file, not plumbing.
+
+const XAI_PROVIDER_DOC = {
+  provider: "xai",
+  auth_env: "XAI_API_KEY",
+  endpoints: { openai: "https://api.x.ai/v1", anthropic: "https://api.x.ai/anthropic" },
+  data_residency: "us",
+  models: [
+    {
+      id: "grok-4-fast",
+      status: "available",
+      context_window: 2000000,
+      context_tokens: 1900000,
+      max_tokens: 30000,
+      cost: { input: 0.2, output: 0.5 },
+      cost_provenance: { source: "unverified", fetched: "2026-08-13", volatile: true },
+      compat: { thinking_format: "openai", cache_control: "implicit" },
+      // Grade B like every other third-party row: good enough for the direct
+      // lane, structurally barred from hosting a tool-using session (§6.6).
+      tool_reliability: "B",
+      harness: { session: true, direct: true, batch: false },
+    },
+  ],
+};
+
+const CATALOG_WITH_XAI = loadCatalog(MAESTRO_ROOT_FOR_TESTS(), {
+  agentConfig: { catalog_overrides: XAI_PROVIDER_DOC },
+});
+
+const XAI_CONFIG = Object.freeze({
+  schema_version: 2,
+  aliases: { cheap: "xai/grok-4-fast", default: "anthropic/claude-sonnet-4-6" },
+  defaults: { needs_tool_use_for_sessions: true, data_class: "sensitive", cache_ttl: "1h" },
+  backends: {
+    anthropic: { allowed_data_classes: ["public", "internal", "sensitive"] },
+    xai: { allowed_data_classes: ["public"] },
+  },
+  routing_policy: [
+    { match: { task_class: "lookup.web" }, harness: "direct", chain: ["cheap", "default"], needs_tool_use: false },
+    { default: true, chain: ["default"] },
+  ],
+  fallback_to_anthropic: true,
+});
+
+test("catalog_overrides can introduce xAI/Grok — loudly, as a warning, never silently", () => {
+  const row = CATALOG_WITH_XAI.byRef.get("xai/grok-4-fast");
+  assert.ok(row, "grok row present after the agent-config merge");
+  assert.equal(row.provider, "xai");
+  assert.equal(row.auth_env, "XAI_API_KEY", "carries its OWN auth env, not a borrowed one");
+  assert.equal(row.endpoints.anthropic, "https://api.x.ai/anthropic");
+  assert.ok(
+    CATALOG_WITH_XAI.warnings.some((w) => /non-bundled provider "xai"/.test(w.warning)),
+    "introducing an unbundled provider warns (typo guard) — it does not fail"
+  );
+});
+
+test("resolveChain routes a cheap-tier task to Grok when its own key is present", () => {
+  const d = resolveChain(
+    { task_class: "lookup.web", data_class: "public", token_estimate: 2000 },
+    { catalog: CATALOG_WITH_XAI, config: XAI_CONFIG, env: { XAI_API_KEY: "xai-k" }, now: CLOCK }
+  );
+  assert.equal(d.chosen.provider, "xai");
+  assert.equal(d.chosen.model, "grok-4-fast");
+  assert.equal(d.chosen.wire, "openai", "third-party direct call speaks the openai wire");
+});
+
+test("resolveChain skips Grok without XAI_API_KEY (key-absence-as-enforcement, §7.1)", () => {
+  const d = resolveChain(
+    { task_class: "lookup.web", data_class: "public", token_estimate: 2000 },
+    { catalog: CATALOG_WITH_XAI, config: XAI_CONFIG, env: {}, now: CLOCK }
+  );
+  const skipped = d.tried.find((t) => t.ref === "xai/grok-4-fast");
+  assert.ok(skipped, "grok recorded in tried[]");
+  assert.equal(skipped.reason, "missing_credential");
+  assert.notEqual(d.chosen.provider, "xai");
+});
+
+test("Grok inherits auth-profile key rotation from the catalog, with no per-provider code", () => {
+  // auth-profiles derives provider → auth_env from the CATALOG, so a provider
+  // the SDK has never heard of gets pooled multi-key rotation for free. This is
+  // the "their own auth profiles" half of the cheap-tier requirement.
+  const profiles = loadAuthProfiles(null, {
+    configDoc: null, // bypass the FS
+    env: { XAI_API_KEY: "k1", XAI_API_KEY_2: "k2", DEEPSEEK_API_KEY: "d1" },
+    authEnvByProvider: authEnvMapFromCatalog(CATALOG_WITH_XAI),
+  });
+  assert.deepEqual(profiles.keysFor("xai"), ["k1", "k2"]);
+  assert.equal(profiles.isPooled("xai"), true, "two keys ⇒ rotation is live");
+  assert.equal(profiles.isPooled("deepseek"), false, "single key ⇒ unchanged single-key behaviour");
+});
+
+test("a session on Grok is still barred by the grade gate, exactly like DeepSeek/Kimi", () => {
+  // Not a bug to fix: §6.6 says a tool-using session needs grade A, and no
+  // third-party row is graded A until the probe ledger earns it. Cheap-tier
+  // reachability must NOT quietly become cheap-tier session hosting.
+  const sessionCfg = {
+    ...XAI_CONFIG,
+    routing_policy: [{ default: true, chain: ["cheap", "default"] }],
+  };
+  const d = resolveChain(
+    { task_class: "session.responder", data_class: "public", token_estimate: 2000 },
+    { catalog: CATALOG_WITH_XAI, config: sessionCfg, env: { XAI_API_KEY: "xai-k" }, now: CLOCK }
+  );
+  const skipped = d.tried.find((t) => t.ref === "xai/grok-4-fast");
+  assert.equal(skipped?.reason, "grade_too_low");
+  assert.equal(d.chosen.provider, "anthropic");
+});
+
 // ── estCostUSD + ledger join fields ──────────────────────────────────────────
 
 test("resolveChain: stamps a finite estCostUSD and a decision_id for the ledger join", () => {

package/lib/org/inbound/project.mjs

@@ -102,11 +102,15 @@ export function toMessageEvent(o = {}) {
     kind: def.kind,
     subject,
     // ONLY ever a real Cohort channel id, never an entity id standing in for
-    // one. `scripts/daemon/responder.mjs sendCohortReply` routes its reply with
-    // `messaging.send({channel: item.channel_id})`, so putting a task/decision
-    // id here would post-to-a-non-channel and 400. A surface with no room leaves
-    // this blank and is routed by `kind` + `raw_ref` instead (see the wiring
-    // note in this directory's module docs).
+    // one. A reply to a room surface routes with
+    // `messaging.send({channelId: item.channel_id})`, so putting a task/decision
+    // id here would post-to-a-non-channel and come back NOT_FOUND. A surface
+    // with no room leaves this BLANK and is routed on its own surface instead —
+    // `scripts/daemon/deliver.mjs cohortReplyRoute` reads `raw_ref` for the
+    // surface and `scope_id`/`thread_id` for the entity, and sends a board
+    // comment to `board.addTaskComment`, a doc comment to `files.commentAdd`,
+    // and so on. That enforcement is new: for months the send path fell back to
+    // `channel_label` below, so a board reply was addressed to a task's TITLE.
     channel_id: channelId,
     channel_label: channelLabel,
     sender: s(from.name || from.id),

package/lib/org/messaging.mjs

@@ -138,8 +138,13 @@ function agentIdOf(cfg) {
  *
  * @param {object} o - { cfg, agentRoot, action, channel }
  * @param {object} deps - { ledgerImpl?, catalog? } injectable for tests
+ *
+ * EXPORTED because room sends are no longer the only attributed outbound:
+ * `scripts/daemon/deliver.mjs` posts board/doc/decision comments straight onto
+ * their entity thread, bypassing `sendMessage`, and an outbound family missing
+ * from the ledger is an outbound family nobody can see.
  */
-async function attributeMessaging(o, deps = {}) {
+export async function attributeMessaging(o, deps = {}) {
   // Opt-out: an explicit `ledgerImpl: null` (or false) disables attribution.
   if (Object.prototype.hasOwnProperty.call(deps, "ledgerImpl") && !deps.ledgerImpl) return;
   try {

package/lib/org/protocol.checksum

@@ -1 +1 @@
-358b95ed6a48faeffa78b7ca717a909905e8ff4e7b75278edf274a0acdaf5dd6
+9ecd8993a6a9aceac04da479c6626a3b3852378b81bfd2b7590d2eee2099c9a9

package/lib/org/protocol.mjs

@@ -76,6 +76,25 @@ export const FAMILIES = Object.freeze([
   // seat can PERSIST one it learned rather than re-deriving it every session.
   // The chain rows carry subject + domain + key only — never the value.
   "preference",
+  // GENESIS (2026-08): the founder's pre-commit workspace draft — the ten-stage
+  // run, its editable sections, and the conversational planner over them. The
+  // family exists so an agent reaches the SAME draft the founder's own form
+  // does; every method is a thin shell over the server action behind the
+  // button, never a second implementation of its gates.
+  //
+  // Its chain rows land in the DRAFTING org — the tenant the founder is signed
+  // into while they draft — and say only that a mutation happened, by whom, to
+  // which section. The content-level provenance is a different spine: the
+  // action's own `GenesisFieldEdit` rows, which `bufferGenesisAudit` replays
+  // into the NEW workspace's chain at commit. Both are true and neither
+  // replaces the other.
+  "genesis",
+  // ARCHITECTURE (2026-08): the four tier review decisions and the one whole-
+  // architecture approval that gate a Genesis commit. Split from `genesis`
+  // because these are REVIEW acts over a draft rather than edits to it, and
+  // because the same surface outlives the run — the Org › Architecture view
+  // reads this state for a workspace that has long since committed.
+  "architecture",
 ]);
 
 /**
@@ -424,7 +443,12 @@ export const METHODS = Object.freeze({
   // --- file ---
   "file.pin": { family: "file", scope: "org.write", sideEffecting: true, idempotent: true },
   "file.unpin": { family: "file", scope: "org.write", sideEffecting: true },
-  "file.addComment": { family: "file", scope: "org.write", sideEffecting: true },
+  // idempotent: a COMMENT CREATE keyed on the caller's message id. Without
+  // the flag hq ignores `x-idempotency-key` entirely (dispatch.ts replays only
+  // for `def.idempotent === true`), so a daemon retry after a timeout-post-
+  // commit posts the same comment two or three times on the thread. Same
+  // reasoning as messaging.send, which has carried the flag from the start.
+  "file.addComment": { family: "file", scope: "org.write", sideEffecting: true, idempotent: true },
   "file.listComments": { family: "file", scope: "org.read", sideEffecting: false },
   "file.listPinned": { family: "file", scope: "org.read", sideEffecting: false },
   // --- memory ---
@@ -458,7 +482,7 @@ export const METHODS = Object.freeze({
   "notification.updatePreferences": { family: "notification", scope: "org.write", sideEffecting: true },
   "notification.getPreferences": { family: "notification", scope: "org.read", sideEffecting: false },
   // --- decision ---
-  "decision.comment": { family: "decision", scope: "decision.write", sideEffecting: true },
+  "decision.comment": { family: "decision", scope: "decision.write", sideEffecting: true, idempotent: true },
   "decision.sign": { family: "decision", scope: "decision.write", sideEffecting: true },
   "decision.reverse": { family: "decision", scope: "decision.write", sideEffecting: true },
   "decision.requestAdjustment": { family: "decision", scope: "decision.write", sideEffecting: true },
@@ -479,7 +503,7 @@ export const METHODS = Object.freeze({
   "board.updateTask": { family: "board", scope: "board.write", sideEffecting: true },
   "board.moveTask": { family: "board", scope: "board.write", sideEffecting: true },
   "board.assignTask": { family: "board", scope: "board.write", sideEffecting: true },
-  "board.addTaskComment": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.addTaskComment": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
   "board.addTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
   "board.updateTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
   "board.removeTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
@@ -933,6 +957,57 @@ export const METHODS = Object.freeze({
   // dispatcher cannot keep: the protocol advertises the method, callers get
   // through scope resolution, and the call 500s. Register it in the same change
   // that adds src/server/methods/escalation/answer.ts.
+  // --- GENESIS + ARCHITECTURE (2026-08): the pre-commit workspace draft and the
+  //     review gates over it. 1:1 with the founder's own form surface — the ask
+  //     was parity, so the bar is EQUAL power, never more.
+  //
+  //     SCOPES REUSE `org.read` / `org.write` rather than minting a genesis.*
+  //     pair. `org.write` is already defined as "EDITOR-equivalent: write
+  //     org-structural content (members, teams, personas, ... reporting lines,
+  //     chart layout)" and already sits in DEFAULT_AGENT_SCOPES under the
+  //     comment "agent UI-parity". A Genesis draft IS that content, one commit
+  //     earlier; a private scope would be a second name for a permission the
+  //     org already grants, and every operator who had reasoned about who may
+  //     edit their structure would have to reason about it twice.
+  //
+  //     WHY REGISTERING THEM AT ALL IS THE FIX. `scopeForMethod()` resolves an
+  //     UNKNOWN method to `admin`, and `admin` is in neither
+  //     HUMAN_DEFAULT_SCOPES nor DEFAULT_AGENT_SCOPES — so an undeclared method
+  //     is not merely undocumented, it is unreachable by every principal that
+  //     exists. That default is correct and it was firing: the handlers shipped
+  //     without descriptors and could not serve one request.
+  //
+  //     EVERY WRITE IS `sideEffecting:true` AND APPENDS ONE CHAIN EVENT, which
+  //     is not bookkeeping — dispatch REQUIRES exactly one append from a
+  //     side-effecting handler and throws INTERNAL on zero. The tempting escape
+  //     (declare a durable write `sideEffecting:false` so the requirement never
+  //     applies) would buy a green test with a lie the whole protocol reads:
+  //     no chain row, no idempotency replay, and `READS`-shaped callers free to
+  //     retry a mutation they were told was safe.
+  //
+  //     `idempotent:true` on the writes is opt-in at the caller (it engages only
+  //     when an idempotencyKey is sent) and it is the honest answer for this
+  //     family: every write already carries an `(attemptId, editSeq)` base and a
+  //     replay of a committed op is refused CONFLICT by the stale-base gate, so
+  //     without the cache a dropped response turns a SUCCEEDED edit into a
+  //     confusing conflict the caller cannot distinguish from a real race.
+  //
+  //     genesis.plan is a READ that spends tokens: it asks a model to turn an
+  //     instruction into ops and mutates nothing. Whether it costs money is not
+  //     what `sideEffecting` means. ---
+  "genesis.outline": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.entity": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.grid": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.plan": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.set": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.insert": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.remove": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.reorder": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.revert": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.applyPlan": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "architecture.status": { family: "architecture", scope: "org.read", sideEffecting: false },
+  "architecture.accept": { family: "architecture", scope: "org.write", sideEffecting: true, idempotent: true },
+  "architecture.approve": { family: "architecture", scope: "org.write", sideEffecting: true, idempotent: true },
 });
 
 /**

package/lib/org/protocol.test.mjs

@@ -134,7 +134,12 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // The 2026-08 protocol-convergence pass adds 4: subagent (the org-scoped
   // sub-agent registry), agent (the agent.wait control lane), mandate (the
   // MANDATE spine) and preference (member-scoped preferences) → 51.
-  assert.equal(FAMILIES.length, 51, "family count");
+  // The 2026-08 Genesis agent-surface pass adds 2: genesis (the founder's
+  // pre-commit workspace draft — the ten-stage run and its editable sections)
+  // and architecture (the four tier review decisions and the one whole-
+  // architecture approval, which outlive the run as the Org › Architecture
+  // view) → 53.
+  assert.equal(FAMILIES.length, 53, "family count");
   // 357 = the mesh-protocol + agent UI-parity + calling + branding + email
   // methods, plus the Live Integrations surface: integration.toolsetVersion +
   // integration.listAgentTools (SP1) and integration.invokeTool (SP5, execute a
@@ -176,7 +181,14 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // `server/work/ledger.ts` directly, the daemon reaches it over this wire, so
   // the threshold and the idempotency cannot fork → 461.
   // the descriptors; the checksum (read at runtime) is the primary drift guard.
-  assert.equal(Object.keys(METHODS).length, 461, "method count");
+  // The 2026-08 Genesis agent-surface pass adds 13, the 1:1 programmatic
+  // parity for the founder's own Generate surface: genesis 10 (outline/entity/
+  // grid/plan reads + set/insert/remove/reorder/revert/applyPlan writes) and
+  // architecture 3 (status read + accept/approve review gates). The handlers
+  // had shipped WITHOUT descriptors, which made all 13 unreachable — dispatch
+  // rejects unknown methods and scopeForMethod resolves them to `admin`, which
+  // no principal holds → 474.
+  assert.equal(Object.keys(METHODS).length, 474, "method count");
 });
 
 test("protocol SP3: messaging + calling families/methods/scopes", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scripts/daemon/assurance.mjs

@@ -225,14 +225,25 @@ export function openObligations() {
  * object is gone. Content is truncated: this file is a debt record, not a
  * message archive.
  */
-function itemSnapshot(item) {
+export function itemSnapshot(item) {
   return {
     id: item.id || null,
     raw_ref: item.raw_ref || null,
     message_id: item.message_id || null,
     service: item.service || null,
+    // `kind` IS AN ADDRESS TOO — `deliver.cohortSurfaceOf` falls back to it when
+    // `raw_ref` carries no surface name, and without it every such item
+    // re-routed from the sweep as a plain `dm` with no channel: undeliverable.
+    kind: item.kind || null,
     channel: item.channel || null,
     channel_id: item.channel_id || null,
+    // `scope_id` IS AN ADDRESS, not decoration. `deliver.cohortReplyRoute` reads
+    // it FIRST for every roomless Cohort surface (board, doc, decision). The
+    // sweep re-delivers from `rec.item`, so leaving it out meant the sweep
+    // routed a DIFFERENT item than the live path did — masked only by every
+    // hydrator happening to set `thread_id` too. Anything the routing table
+    // reads belongs in this snapshot.
+    scope_id: item.scope_id || null,
     thread_id: item.thread_id || null,
     sender: item.sender || null,
     sender_email: item.sender_email || null,