fix(organization): definition writes go through the bus with the held-secret check (#1873)

Review P1: the CLI wrote definitions with a no-op secret check. setDefinition
now refuses definition-secret-check-required when a write that adds or changes
an entry has no assertClean. New bus verbs definition.import|invent|edit|remove
run the writes for the business's human at the cli with the credential
store's assertClean; the tester, agents and readers refuse. The CLI's
definition writes call the bus and map its codes to messages that never
quote the definition.

packages/bus/src/broker.mjs

@@ -193,6 +193,15 @@ const userLevel = (verb) => (VIEWER_VERBS.includes(verb) ? 'viewer' : 'collabora
 export const BOARD_VERBS = Object.freeze(['inbox', 'agents', 'thread.claims', 'tasks', 'trail', 'decisions', 'credentials', 'replies', 'messages', 'state', 'usage']);
 // The person's task-store writes, distinct from the agent's singular task.* actions.
 export const PERSON_TASK_VERBS = Object.freeze(['tasks.create', 'tasks.edit', 'tasks.archive', 'tasks.unarchive', 'tasks.delete']);
+// #1873 T1: the human's definition writes, each with its [allowed, required] argument keys. Kept here,
+// not imported, as the sandbox client loads this file; runtime.mjs maps each verb to the verb module
+// (organization/src/definition-verbs.mjs names the same four, and a test holds them equal).
+export const DEFINITION_BUS_KEYS = Object.freeze({
+  'definition.import': [['revision', 'template', 'as'], ['revision', 'template']],
+  'definition.invent': [['revision', 'name', 'definition'], ['revision', 'name', 'definition']],
+  'definition.edit': [['revision', 'rev', 'name', 'definition'], ['revision', 'rev', 'name', 'definition']],
+  'definition.remove': [['revision', 'rev', 'name'], ['revision', 'rev', 'name']],
+});
 // Row 175: the organization verbs a tester may call. Its writes run every check the human's do
 // and log actor `tester`; row 176 adds routes reads; limits.set, organization.set and organization.revision refuse it.
 export const TESTER_ORGANIZATION_VERBS = Object.freeze(['limits', 'plugins', 'instances', 'plugins.set', 'instances.set', 'routes.set', 'routes']);
@@ -6082,7 +6091,7 @@ export class Broker {
       }
       if (request.verb === 'grants.scope' || request.verb === 'grants.scope.set')
         return this.#grantScopeVerb(s, request.verb, structuredClone(args));
-      if (["limits", "limits.set", "organization.set", "organization.revision", "plugins", "plugins.set", "instances", "instances.set", "routes", "routes.set", "veto.set", "library.limits.set"].includes(request.verb)) {
+      if (["limits", "limits.set", "organization.set", "organization.revision", "plugins", "plugins.set", "instances", "instances.set", "routes", "routes.set", "veto.set", "library.limits.set"].includes(request.verb) || Object.hasOwn(DEFINITION_BUS_KEYS, request.verb)) {
         // Row 123 (#1617, REQ-COS-1, REQ-LIMIT-1): organization.set is limits.set for a role whose
         // file lists organization.change. It takes the same keys, runs the same write path and
         // logs the same receipt; only the actor differs: the role definition and instance.
@@ -6137,6 +6146,13 @@ export class Broker {
         else if (request.verb === "library.limits.set") {
           keys(args, ["revision", "replyLimits"], ["revision", "replyLimits"]);
           this.#human(s);
+        }
+        // #1873 T1: the definition writes need org.hire. Until row 193, as #mayHuman, the business's
+        // one human (the owner) passes; the tester is refused above and an agent here.
+        else if (Object.hasOwn(DEFINITION_BUS_KEYS, request.verb)) {
+          keys(args, ...DEFINITION_BUS_KEYS[request.verb]);
+          this.#human(s);
+          if (s.human !== this.#business(s.business).human) fail("human-required");
         } else {
           keys(args, ORGANIZATION_KEYS, ["revision"]);
           // Row 194 (D2.4, B7): the chief can't change a kept instance's model, as that replaces it at
@@ -6413,6 +6429,8 @@ export class Broker {
     if ((verb === "instance.hire" || verb === "instance.fire") && e.code === "definition-not-hireable") fail(e.code);
     // Row 194 (B7, webby-0094 N3): the limits writer's keep check, against the file, as well.
     if (e.code === "instance-kept") fail(e.code);
+    // #1873 T1: the definition writer's refusals pass by code; a composition refusal stays invalid-request.
+    if (Object.hasOwn(DEFINITION_BUS_KEYS, verb) && /^definition-[a-z-]+$/.test(e.code ?? "")) fail(e.code);
     // Row 194 (brief item 8): a fire's or a delete's revoke failed, and nothing was written.
     if ((verb === "instance.fire" || verb === "instances.set") && e.code === "credential-revoke-failed") fail(e.code);
     // Row 65: the route checks every write of an instance's route vars runs.

packages/bus/src/runtime.mjs

@@ -35,6 +35,8 @@ import { createProxyLock } from './proxy-lock.mjs';
 import { ModelKeys, modelOrganization, stopModelRuns, MODEL_STOP_TIMEOUT_MS } from './model-keys.mjs';
 import { instanceSettings } from '../../organization/src/instance-settings.mjs';
 import { organizationWriter, OrganizationError, setReplyLimits } from '../../organization/src/organization.mjs';
+import { definitionVerbs, DEFINITION_BUS_VERBS } from '../../organization/src/definition-verbs.mjs';
+import { ROLE_RIGHTS } from '../../organization/src/org-rights.mjs';
 import { getProjectRemote } from '../../organization/src/project-remotes.mjs';
 import { credentialVerbs } from './credential-verbs.mjs';
 import { loadWithCopies } from '../../organization/src/agent-copies.mjs';
@@ -849,6 +851,9 @@ export async function startBroker({
         else if(verb==='grants.scope.set')result=instances.grantScope(id,args,actor);
         // C2-06 M11: the human's replyLimits, through the organization writer's fence.
         else if(verb==='library.limits.set')result=setReplyLimits(organizationWriter({dir:organization.dir,rolesDir:organization.rolesDir}),id,args,actor);
+        // #1873 T1: the human's definition writes. The broker passes only the business's human (the
+        // owner, so ROLE_RIGHTS.owner); the store's assertClean is the held-secret check each write needs.
+        else if(Object.hasOwn(DEFINITION_BUS_VERBS,verb))result=definitionVerbs({writer:organizationWriter({dir:organization.dir,rolesDir:organization.rolesDir}),rolesDir:organization.rolesDir,assertClean:value=>credentials.assertClean(value)})[DEFINITION_BUS_VERBS[verb]](id,args,{actor,rights:[...ROLE_RIGHTS.owner],agent:false});
         // Row 194 (D2.1, D2.2): the chief's hire and fire, with the reason in the change context.
         else if(verb==='instance.hire')result=instances.hire(id,args,{actor,context});
         else if(verb==='instance.fire')result=instances.fire(id,{name:args.name},{actor,context});

packages/bus/tests/definition-verbs.test.mjs

@@ -0,0 +1,74 @@
+// #1873 T1: the definition writes on the bus. Only the business's human at the cli reaches them,
+// and the writer runs the credential store's held-secret check on what it would write.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { appendFileSync, chmodSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFINITION_BUS_KEYS } from '../src/broker.mjs';
+import { startBroker } from '../src/runtime.mjs';
+import { DEFINITION_BUS_VERBS } from '../../organization/src/definition-verbs.mjs';
+import { businessDoc, rolesCopy, systemFor, writeJson } from '../../organization/tests/helpers.mjs';
+
+const TOKEN = 'fixture-held-token-t1-5c0e9a';
+const SCOUT = { role: { tools: ['read'], network: 'none', authority: { withinRole: [], crossRole: [] }, credentials: [] }, instructions: 'Read and report.\n' };
+
+function files(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => e.isDirectory() ? files(join(dir, e.name)) : e.isFile() ? [join(dir, e.name)] : []);
+}
+
+test('T1 the broker checks the same four definition verbs the runtime maps', () => {
+  assert.deepEqual(Object.keys(DEFINITION_BUS_KEYS).sort(), Object.keys(DEFINITION_BUS_VERBS).sort());
+});
+
+test('T1 definition writes: the human at the cli writes, every other caller refuses, and a held token never lands', async (t) => {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-def-bus-'));
+  const rolesDir = rolesCopy(root);
+  const doc = businessDoc(root, 'demo');
+  const file = writeJson(join(root, 'businesses/demo.json'), { ...doc, plugins: { ...doc.plugins, harness: ['pi'] } });
+  const data = join(root, 'data');
+  mkdirSync(data, { mode: 0o700 });
+  const token = join(root, 'held.token');
+  writeFileSync(token, TOKEN, { mode: 0o600 });
+  chmodSync(token, 0o600);
+  const bus = await startBroker({ dataRoot: data, businesses: { demo: { id: 'demo', human: 'jason', arbiters: { technical: 'chief', delivery: 'chief' }, vars: { 'bus.tester': true }, roles: {
+    chief: { definition: 'chief-of-staff', authority: { withinRole: ['decision.resolve.technical', 'decision.resolve.delivery'], crossRole: [] } },
+    coder: { authority: { withinRole: [], crossRole: [] }, credentials: { gitea: { file: token, rotateBy: '2099-01-01' } } },
+  } } }, organization: { dir: root, rolesDir, system: systemFor(root) } });
+  t.after(async () => { await bus.close(); rmSync(root, { recursive: true, force: true }); });
+  const b = bus.broker;
+  const human = b.bindHuman({ business: 'demo', human: 'jason', via: 'cli', outsideAgent: true });
+  const revision = () => b.request(human, { verb: 'limits' }).revision;
+  const invent = (name) => ({ verb: 'definition.invent', args: { revision: revision(), name, definition: SCOUT } });
+
+  // An agent, a reader and the tester never reach the writer.
+  const before = readFileSync(file);
+  const agent = b.bindLaunch({ business: 'demo', role: 'coder', run: 'coder-run', harness: 'pi', address: 'coder-run' });
+  for (const cap of [agent, b.bindReader({ business: 'demo' })]) assert.throws(() => b.request(cap, invent('scout')), /human-required/);
+  assert.throws(() => b.request(b.bindTester({ business: 'demo' }), invent('scout')), /tester-refused/);
+  // Unknown and missing arguments refuse; an actor can't be forged through them.
+  assert.throws(() => b.request(human, { verb: 'definition.invent', args: { ...invent('scout').args, actor: 'mallory' } }), /invalid-request/);
+  assert.throws(() => b.request(human, { verb: 'definition.remove', args: { revision: revision(), name: 'scout' } }), /invalid-request/);
+  assert.deepEqual(readFileSync(file), before);
+
+  // The human's invent commits, as the human, with a receipt that carries no role text.
+  const receipt = b.request(human, invent('scout'));
+  assert.deepEqual({ ...receipt, revision: 0, transaction: 0 }, { verb: 'invent', organization: 'demo', definition: 'scout', rev: 1, revision: 0, transaction: 0 });
+  assert.equal(JSON.parse(readFileSync(file, 'utf8')).definitions.scout.instructions, SCOUT.instructions);
+  const last = JSON.parse(readFileSync(join(root, 'businesses/.history/demo/changes.jsonl'), 'utf8').trim().split('\n').at(-1));
+  assert.equal(last.actor, 'jason');
+  assert.equal(last.state, 'committed');
+  // A writer refusal passes by its code.
+  assert.throws(() => b.request(human, invent('scout')), /definition-exists/);
+
+  // The bus refuses a request that carries the held token, and the writer refuses a template whose
+  // contract carries it (the import request itself holds no token). Neither writes.
+  const written = readFileSync(file);
+  assert.throws(() => b.request(human, { verb: 'definition.invent', args: { revision: revision(), name: 'leak', definition: { ...SCOUT, instructions: `Use ${TOKEN}.\n` } } }),
+    (e) => e.code === 'credential-leak' && !e.message.includes(TOKEN));
+  appendFileSync(join(rolesDir, 'coder.md'), `\nUse ${TOKEN} for the forge.\n`);
+  assert.throws(() => b.request(human, { verb: 'definition.import', args: { revision: revision(), template: 'coder' } }),
+    (e) => e.code === 'invalid-request' && !e.message.includes(TOKEN) && !String(e.stack).includes(TOKEN));
+  assert.deepEqual(readFileSync(file), written);
+  for (const path of [...files(data), ...files(join(root, 'businesses'))]) assert.ok(!readFileSync(path).includes(TOKEN), path);
+});

packages/cli/src/cli.mjs

@@ -37,6 +37,7 @@ import { bootConfig, loadSystem, orgPaths, socketPath } from "./config.mjs";
 import { bootLine, readBootStatus, recordBootOk, recordBootRefused } from "./boot-status.mjs";
 import { businessFilePath, configDir } from "../../organization/src/index.mjs";
 import { busExit, humanTransport, refuseInsideAgent, testerTransport } from "./transport.mjs";
+import { definitionsCommand } from "./org-definitions.mjs";
 import { formatAgents, formatDecision, formatInbox, formatTasks, formatTrail, shortId } from "./format.mjs";
 import { hostStatus, readHostState, startHost, stopHost } from "./host.mjs";
 import { createLauncher } from "./launcher.mjs";
@@ -737,6 +738,8 @@ export async function main(argv, io = { env: process.env, stdin: process.stdin,
   // builds; `org validate FILE` stays orgCommand's draft check.
   if (verb === 'org' && rest[0] === 'config') return orgConfig(rest.slice(1), io);
   if (verb === 'org' && ["instances", "instance", "veto"].includes(rest[0])) return orgInstancesCommand(rest, io, (p) => callFor(p, io, deps));
+  // #1873 T1: definition writes go through the organization's bus, as the human.
+  if (verb === 'org' && rest[0] === 'definitions') return definitionsCommand(rest.slice(1), io, { ...deps, callFor: (p) => callFor(p, io, deps) });
   if (verb === 'org') return orgCommand(rest, io, deps);
   // A2 (#1873): the owner's root and project agent levels. `mosaic agents` without `root` stays the bus read.
   if (verb === "agents" && rest[0] === "root") return agentsRootCommand(rest.slice(1), io);

packages/cli/src/org-definitions.mjs

@@ -1,15 +1,16 @@
 // #1873 T1: `mosaic org definitions`, the human verbs on an organization's own role definitions and
-// the template hash and diff reads. A write runs only from a human shell (refuseInsideAgent) and acts
-// as the organization's human holding the owner's rights: the OS user who owns the config directory
-// owns the organization, the same trust `mosaic org update` rests on. Each write prints its receipt.
+// the template hash and diff reads. Reads run here, from the file. A write runs only from a human
+// shell (refuseInsideAgent) and goes through the organization's bus as its human: the bus holds the
+// credential store, whose held-secret check every definition write needs (R1), and no other process
+// holds the tokens it looks for. Each write prints its receipt.
 import { readFile } from 'node:fs/promises';
 import { configDir } from '../../organization/src/organization-config.mjs';
 import { organizationWriter } from '../../organization/src/organization.mjs';
 import { definitionVerbs } from '../../organization/src/definition-verbs.mjs';
-import { ROLE_RIGHTS } from '../../organization/src/org-rights.mjs';
+import { checkDefinition } from '../../organization/src/definitions.mjs';
 import { rolesDir } from './config.mjs';
 import { CliError } from './errors.mjs';
-import { refuseInsideAgent } from './transport.mjs';
+import { busExit, refuseInsideAgent } from './transport.mjs';
 
 export const DEFINITIONS_USAGE = 'mosaic org definitions templates | definitions ID list | definitions ID show NAME | definitions ID diff NAME | definitions ID import TEMPLATE [--as NAME] | definitions ID invent NAME --from FILE | definitions ID edit NAME --from FILE --if-rev N | definitions ID remove NAME --if-rev N';
 
@@ -39,6 +40,27 @@ async function definitionFile(file) {
   }
 }
 
+// The bus answers a refusal with its code only. These say what the code means for this request;
+// none quotes the definition's text.
+function refusal(code, verb, name, rev, read) {
+  const why = {
+    'definition-in-use': () => `definition ${name} is named by ${read().usedBy.join(', ')}; a change to a hired agent's role is a change decision`,
+    'definition-rev-conflict': () => `definition ${name} is not at rev ${rev}`,
+    'definition-exists': () => `definitions already declares ${name}`,
+    'definition-missing': () => `definitions declares no ${name}`,
+    'revision-conflict': () => 'the organization file changed while this ran; run it again',
+    'credential-leak': () => `the ${verb} request holds a credential the organization's bus holds; nothing was written`,
+    'invalid-request': () => `the bus refused the ${verb}: the definition fails the composition check or holds a held credential`,
+  }[code];
+  let detail = null;
+  try { detail = why?.() ?? null; } catch { detail = null; }
+  const error = new CliError(detail ? `${code}: ${detail}` : code, busExit(code));
+  error.code = code;
+  return error;
+}
+
+// deps.callFor(parsed) returns the human's call(verb, args) for the organization parsed names (cli.mjs
+// passes its callFor). Without one, a write refuses: it never runs without the bus's secret check.
 export async function definitionsCommand(args, io, deps = {}) {
   const { pos, values } = parse(args);
   const allowed = (...keys) => { for (const k of Object.keys(values)) if (!keys.includes(k)) throw new CliError(`unexpected ${k}`, 4); };
@@ -47,18 +69,28 @@ export async function definitionsCommand(args, io, deps = {}) {
   const [id, verb, name] = pos;
   if (WRITES.includes(verb)) refuseInsideAgent(io.env);
   const writer = deps.writer ?? organizationWriter({ dir: configDir(io.env), rolesDir: rolesDir(io.env) });
-  const verbs = definitionVerbs({ writer, rolesDir: rolesDir(io.env), assertClean: deps.assertClean });
+  const verbs = definitionVerbs({ writer, rolesDir: rolesDir(io.env) });
   let result;
   if (id === 'templates' && pos.length === 1) { allowed(); result = verbs.templates(); }
   else if (verb === 'list' && pos.length === 2) { allowed(); result = verbs.list(id); }
   else if (['show', 'diff'].includes(verb) && pos.length === 3) { allowed(); result = verbs[verb](id, name); }
   else if (WRITES.includes(verb) && pos.length === 3) {
-    const { document, revision } = writer.read(id);
-    const caller = { actor: document.human, rights: [...ROLE_RIGHTS.owner], agent: false };
-    if (verb === 'import') { allowed('--as'); result = verbs.import(id, { revision, template: name, as: values['--as'] ?? name }, caller); }
-    else if (verb === 'invent') { allowed('--from'); result = verbs.invent(id, { revision, name, definition: await definitionFile(need('--from')) }, caller); }
-    else if (verb === 'edit') { allowed('--from', '--if-rev'); const rev = ifRev(); result = verbs.edit(id, { revision, rev, name, definition: await definitionFile(need('--from')) }, caller); }
-    else { allowed('--if-rev'); result = verbs.remove(id, { revision, rev: ifRev(), name }, caller); }
+    let request, rev;
+    if (verb === 'import') { allowed('--as'); request = { template: name, as: values['--as'] ?? name }; }
+    else if (verb === 'invent') { allowed('--from'); request = { name, definition: await definitionFile(need('--from')) }; }
+    else if (verb === 'edit') { allowed('--from', '--if-rev'); rev = ifRev(); request = { rev, name, definition: await definitionFile(need('--from')) }; }
+    else { allowed('--if-rev'); rev = ifRev(); request = { rev, name }; }
+    // The file's own checks first, so a bad key is named here; the bus repeats them with its secret check.
+    if (request.definition) checkDefinition(name, { ...request.definition, rev: rev ?? 1 });
+    if (typeof deps.callFor !== 'function') throw new CliError('a definition write goes through the organization bus; run it as `mosaic org definitions`', 3);
+    const call = deps.callFor({ positional: [id], flags: new Set(), values: { '--business': id } });
+    const { revision } = writer.read(id);
+    try {
+      result = await call(`definition.${verb}`, { revision, ...request });
+    } catch (e) {
+      if (typeof e?.code !== 'string' || e.code === '') throw e;
+      throw refusal(e.code, verb, request.as ?? name, rev, () => verbs.show(id, request.as ?? name));
+    }
   } else throw new CliError(DEFINITIONS_USAGE, 4);
   io.stdout.write(JSON.stringify(result, null, 2) + '\n');
 }

packages/cli/tests/org-definitions.test.mjs

@@ -2,9 +2,13 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { join } from 'node:path';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createLauncher } from '../src/launcher.mjs';
 import { main } from '../src/cli.mjs';
+import { orgCommand } from '../src/org.mjs';
+import { bootConfig, loadSystem } from '../src/config.mjs';
+import { BusError } from '../../bus/src/broker.mjs';
+import { startBroker } from '../../bus/src/runtime.mjs';
 import { initializeControl } from '../../processing-control/src/state.mjs';
 import { launchLogFile } from '../../seat/src/session.mjs';
 import { entryFromTemplate, readTemplate, templateHash } from '../../organization/src/definitions.mjs';
@@ -47,16 +51,36 @@ test('T1 an org: instance passes every launch check, and a missing definition re
   assert.throws(() => createLauncher({ host, system: JSON.parse(readFileSync(f.config, 'utf8')), env: f.env, bwrap: '/usr/bin/true', log: () => {} }), /org:ghost/);
 });
 
-test('T1 mosaic org definitions: each write prints its receipt, and an agent shell refuses', async (t) => {
+// The fixture bus holds SENTINEL as coder's gitea token, so the bus's secret check refuses it.
+const SENTINEL = 'sk-test-NOT-A-SECRET-1234';
+function files(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => e.isDirectory() ? files(join(dir, e.name)) : e.isFile() ? [join(dir, e.name)] : []);
+}
+
+test('T1 mosaic org definitions: writes go through the bus and its secret check, each prints its receipt, and an agent shell refuses', async (t) => {
   const root = tmp(t);
-  const f = fixture(root);
+  const builder = entryFromTemplate(readTemplate(REPO_ROLES, 'coder'));
+  const f = fixture(root, 'acme', (doc) => ({ ...doc, definitions: { builder }, roles: { ...doc.roles, coder: { ...doc.roles.coder, definition: 'org:builder' } } }));
   const file = join(root, 'config/businesses/acme.json');
-  const run = async (args, env = f.env) => { const x = io(env); await main(['org', 'definitions', ...args], x, {}); return JSON.parse(x.out.text); };
+  const changes = join(root, 'config/businesses/.history/acme/changes.jsonl');
+  writeFileSync(f.doc.roles.coder.credentials.gitea.file, SENTINEL);
+  const boot = bootConfig({ system: loadSystem({ env: f.env }), businessId: 'acme', env: f.env });
+  const b = await startBroker({ dataRoot: f.dataRoot, businesses: boot.businesses, organization: boot.organization });
+  t.after(() => b.close());
+  const human = b.broker.bindHuman({ business: 'acme', human: f.doc.human, via: 'cli', outsideAgent: true });
+  const calls = [];
+  // The human transport's shape: a bus refusal arrives as its code.
+  const deps = { system: { dataRoot: f.dataRoot }, transport: () => async (verb, args = {}) => {
+    calls.push(verb);
+    try { return structuredClone(b.broker.request(human, { verb, args })); }
+    catch (e) { if (!(e instanceof BusError)) throw e; throw Object.assign(new Error(e.code), { code: e.code }); }
+  } };
+  const run = async (args, env = f.env) => { const x = io(env); await main(['org', 'definitions', ...args], x, deps); return JSON.parse(x.out.text); };
   const hash = templateHash(f.roles, 'coder');
   assert.ok((await run(['templates'])).some((h) => h.template === 'coder' && h.sha256 === hash));
 
-  const imported = await run(['acme', 'import', 'coder', '--as', 'builder']);
-  assert.deepEqual({ ...imported, revision: 0, transaction: 0 }, { verb: 'import', organization: 'acme', definition: 'builder', rev: 1, revision: 0, transaction: 0, from: { template: 'coder', sha256: hash } });
+  const imported = await run(['acme', 'import', 'coder', '--as', 'copy']);
+  assert.deepEqual({ ...imported, revision: 0, transaction: 0 }, { verb: 'import', organization: 'acme', definition: 'copy', rev: 1, revision: 0, transaction: 0, from: { template: 'coder', sha256: hash } });
   const spec = join(root, 'scout.json');
   writeFileSync(spec, JSON.stringify({ role: SCOUT.role, instructions: SCOUT.instructions }));
   assert.equal((await run(['acme', 'invent', 'scout', '--from', spec])).rev, 1);
@@ -64,22 +88,50 @@ test('T1 mosaic org definitions: each write prints its receipt, and an agent she
   const edited = await run(['acme', 'edit', 'scout', '--from', spec, '--if-rev', '1']);
   assert.equal(edited.verb, 'edit');
   assert.equal(edited.rev, 2);
-  assert.deepEqual((await run(['acme', 'list'])).definitions.map((d) => [d.name, d.rev]), [['builder', 1], ['scout', 2]]);
+  assert.deepEqual((await run(['acme', 'list'])).definitions.map((d) => [d.name, d.rev]), [['builder', 1], ['copy', 1], ['scout', 2]]);
   assert.equal((await run(['acme', 'show', 'scout'])).instructions, 'Read, then report.\n');
-  assert.equal((await run(['acme', 'diff', 'builder'])).changed, false);
+  assert.equal((await run(['acme', 'diff', 'copy'])).changed, false);
   assert.equal((await run(['acme', 'remove', 'scout', '--if-rev', '2'])).removedRev, 2);
+  assert.deepEqual(calls, ['definition.import', 'definition.invent', 'definition.edit', 'definition.remove']);
+  const committed = readFileSync(changes, 'utf8').trim().split('\n').map((l) => JSON.parse(l)).filter((e) => e.state === 'committed').slice(-4);
+  assert.deepEqual(committed.map((e) => e.actor), Array(4).fill(f.doc.human));
 
-  // A held-secret-shaped file never echoes; a stale --if-rev refuses.
-  writeFileSync(spec, '{"role": sk-test-NOT-A-SECRET-1234');
-  await assert.rejects(run(['acme', 'invent', 'other', '--from', spec]), (e) => e.exitCode === 2 && !e.message.includes('sk-test'));
-  await assert.rejects(run(['acme', 'remove', 'builder', '--if-rev', '7']), (e) => /^definition-rev-conflict: definition builder is not at rev 7/.test(e.message));
-
-  // Inside an agent run every write refuses before it reads anything; reads still work.
+  // A definition holding a token the bus holds refuses on invent and on edit, in valid JSON, and
+  // the token reaches no message, no organization file and nothing the bus wrote.
   const before = readFileSync(file);
-  const agent = { ...f.env, MOSAIC_RUN_ID: 'run-1' };
-  for (const args of [['acme', 'import', 'reviewer'], ['acme', 'invent', 'x', '--from', spec], ['acme', 'edit', 'builder', '--from', spec, '--if-rev', '1'], ['acme', 'remove', 'builder', '--if-rev', '1']]) {
-    await assert.rejects(run(args, agent), (e) => e.exitCode === 3 && /human shell/.test(e.message));
+  const beforeChanges = readFileSync(changes);
+  writeFileSync(spec, JSON.stringify({ role: SCOUT.role, instructions: `Use ${SENTINEL} to report.\n` }));
+  for (const args of [['acme', 'invent', 'leak', '--from', spec], ['acme', 'edit', 'copy', '--from', spec, '--if-rev', '1']]) {
+    await assert.rejects(run(args), (e) => e.code === 'credential-leak' && e.exitCode === 2 && !e.message.includes(SENTINEL) && !String(e.stack).includes(SENTINEL));
   }
   assert.deepEqual(readFileSync(file), before);
-  assert.equal((await run(['acme', 'list'], agent)).definitions.length, 1);
+  assert.deepEqual(readFileSync(changes), beforeChanges);
+  for (const path of files(f.dataRoot)) assert.ok(!readFileSync(path).includes(SENTINEL), path);
+
+  // An unparsable file never echoes; a key the file's checks refuse is named before the bus is
+  // called; a stale --if-rev and an in-use definition refuse with what they mean.
+  writeFileSync(spec, `{"role": ${SENTINEL}`);
+  await assert.rejects(run(['acme', 'invent', 'other', '--from', spec]), (e) => e.exitCode === 2 && !e.message.includes('sk-test'));
+  writeFileSync(spec, JSON.stringify({ role: { ...SCOUT.role, network: 'everywhere' }, instructions: 'x\n' }));
+  const asked = calls.length;
+  await assert.rejects(run(['acme', 'invent', 'other', '--from', spec]), /definitions\.other/);
+  assert.equal(calls.length, asked);
+  await assert.rejects(run(['acme', 'remove', 'copy', '--if-rev', '7']), (e) => /^definition-rev-conflict: definition copy is not at rev 7/.test(e.message));
+  await assert.rejects(run(['acme', 'remove', 'builder', '--if-rev', '1']), (e) => /^definition-in-use: definition builder is named by coder/.test(e.message));
+  assert.deepEqual(readFileSync(file), before);
+
+  // Inside an agent run every write refuses before it reads anything or calls the bus; reads still work.
+  const agent = { ...f.env, MOSAIC_RUN_ID: 'run-1' };
+  const sent = calls.length;
+  for (const args of [['acme', 'import', 'reviewer'], ['acme', 'invent', 'x', '--from', spec], ['acme', 'edit', 'copy', '--from', spec, '--if-rev', '1'], ['acme', 'remove', 'copy', '--if-rev', '1']]) {
+    await assert.rejects(run(args, agent), (e) => e.exitCode === 3 && /human shell/.test(e.message));
+  }
+  assert.equal(calls.length, sent);
+  assert.deepEqual(readFileSync(file), before);
+  assert.equal((await run(['acme', 'list'], agent)).definitions.length, 2);
+
+  // With no bus call to make, a write refuses rather than writing without the secret check.
+  const x = io(f.env);
+  await assert.rejects(orgCommand(['definitions', 'acme', 'remove', 'copy', '--if-rev', '1'], x), (e) => e.exitCode === 3 && /organization bus/.test(e.message));
+  assert.deepEqual(readFileSync(file), before);
 });

packages/organization/src/definition-verbs.mjs

@@ -24,6 +24,13 @@ export const DEFINITION_VERBS = Object.freeze({
   remove: "definition.remove.console",
 });
 
+// The bus verbs for the writes (the broker's DEFINITION_BUS_KEYS checks their arguments). The bus
+// runs them for the business's human at the cli, with its credential store's secret check; the CLI's
+// writes go through them, as no other process holds the tokens that check looks for.
+export const DEFINITION_BUS_VERBS = Object.freeze({
+  "definition.import": "import", "definition.invent": "invent", "definition.edit": "edit", "definition.remove": "remove",
+});
+
 const fail = (code, message = code) => {
   throw new OrganizationError(code, message);
 };

packages/organization/src/definitions.mjs

@@ -45,7 +45,9 @@ const NO_CHIEF = Object.freeze({
   authority: Object.freeze({ withinRole: Object.freeze([]), crossRole: Object.freeze([]) }),
   credentials: Object.freeze([]), messaging: null,
 });
-// A caller with no credential store holds no token, so its secret check is the empty store's.
+// The file-load check has no credential store: a load runs before the bus builds one from the file.
+// The held-secret scan runs where definitions are written (setDefinition requires it, and the bus
+// passes credentials.assertClean). A load still runs every other composition check.
 const NO_STORE = () => {};
 
 const plain = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
@@ -75,7 +77,7 @@ export function compositionOf(entry) {
 }
 
 // One entry: its own keys, then checkComposition. Returns { composition, flagged }. options.assertClean
-// is the credential store's check when the caller has one.
+// is the credential store's check; a write always passes it (setDefinition), a file load can't.
 export function checkDefinition(name, entry, { assertClean = NO_STORE, where = "definitions" } = {}) {
   const at = `${where}.${checkDefinitionName(name, `${where} key`)}`;
   if (!plain(entry)) refuse(`${at} must be a JSON object`);

packages/organization/src/organization.mjs

@@ -366,7 +366,8 @@ export function organizationWriter({ dir, rolesDir, dataRoot = null, barrier = (
   // An agent or the tester never writes one. A write bumps rev (1 for a new name); `rev`, when given,
   // must be the current one (definition-rev-conflict). Editing or removing a definition an instance
   // names refuses definition-in-use: changing a hired agent's role is a change decision (A4).
-  // assertClean is the credential store's check, when the caller holds one.
+  // assertClean is the credential store's held-secret check (the bus's credentials.assertClean). A
+  // write that adds or changes an entry needs it: with no check to run, the write refuses (R1).
   function setDefinition(id, name, next, { revision, rev, actor, detail, assertClean }) {
     checkDefinitionName(name, "definition name");
     const logged = { ...detail, definition: name, rev: null };
@@ -388,7 +389,8 @@ export function organizationWriter({ dir, rolesDir, dataRoot = null, barrier = (
       if (Object.hasOwn(b, name)) {
         const want = current ? current.rev + 1 : 1;
         if (b[name]?.rev !== want) fail("definition-rev-conflict", `definition ${name} must be written at rev ${want}`);
-        checkDefinition(name, b[name], assertClean ? { assertClean } : {});
+        if (typeof assertClean !== "function") fail("definition-secret-check-required", "a definition write needs the credential store's secret check; write it through the bus");
+        checkDefinition(name, b[name], { assertClean });
       }
     };
     const out = commit(id, (old) => {

packages/organization/tests/definitions.test.mjs

@@ -274,7 +274,7 @@ test("T1 the ordinary writer cannot change definitions, and setDefinition change
   added.definitions.other = { rev: 1, ...PLAIN };
   assert.throws(() => f.writer.write("acme", added, { revision: rev(f), actor: "jason" }), { code: "organization-definitions-protected" });
   // The writer itself checks rev and the composition, whatever builds the entry.
-  assert.throws(() => f.writer.setDefinition("acme", "scout", () => ({ ...PLAIN, role: { ...PLAIN.role, tools: ["no-such-tool"] } }), { revision: rev(f), actor: "jason" }), { name: "BusinessError" });
+  assert.throws(() => f.writer.setDefinition("acme", "scout", () => ({ ...PLAIN, role: { ...PLAIN.role, tools: ["no-such-tool"] } }), { revision: rev(f), actor: "jason", assertClean }), { name: "BusinessError" });
 });
 
 test("T1 an agent cannot call the edit verbs", (t) => {
@@ -334,3 +334,18 @@ test("T1 the template files on disk are never written", (t) => {
   assert.deepEqual(readFileSync(join(f.rolesDir, "coder.json")), before);
   writeFileSync(join(f.root, "touched"), "");
 });
+
+test("T1 a write that adds or changes a definition refuses without the credential store's secret check", (t) => {
+  const f = fixture(t);
+  f.verbs.invent("acme", { revision: rev(f), name: "scout", definition: PLAIN }, OWNER);
+  const unchecked = definitionVerbs({ writer: f.writer, rolesDir: f.rolesDir });
+  const before = readFileSync(f.file);
+  const required = { code: "definition-secret-check-required" };
+  assert.throws(() => unchecked.import("acme", { revision: rev(f), template: "coder" }, OWNER), required);
+  assert.throws(() => unchecked.invent("acme", { revision: rev(f), name: "other", definition: PLAIN }, OWNER), required);
+  assert.throws(() => unchecked.edit("acme", { revision: rev(f), rev: 1, name: "scout", definition: { ...PLAIN, instructions: "Report.\n" } }, OWNER), required);
+  assert.throws(() => f.writer.setDefinition("acme", "other", () => PLAIN, { revision: rev(f), actor: "jason" }), required);
+  assert.deepEqual(readFileSync(f.file), before);
+  // A removal writes no role text, so it needs no secret check.
+  assert.equal(unchecked.remove("acme", { revision: rev(f), rev: 1, name: "scout" }, OWNER).removedRev, 1);
+});