# Bus and broker core — slice 1 S2 The broker owns `/bus/` and is the only cooperative writer of `bus.sqlite`. Consumers use the local socket. This package does not load or write the system or business configuration, launch a harness, call a service, or implement task verbs. S1 supplies validated/resolved definitions; S3 adds task handlers; S6 supplies trusted launch records. No service credential is returned to a client or written to the database. Slice 1 shares an OS user. Files, capabilities, process ancestry checks and hooks are **not a wall against a hostile same-UID process**. In particular, Linux `/proc` checks here are not SO_PEERCRED authentication. The trusted host and well-behaved clients must follow this protocol. Containers remain later work. ## Start and stop Requires Linux and Node 24 or 26, local disk, no dependencies. The data root must already exist and belong to the user. A broker creates `bus/` mode 0700 and the DB/lock/socket mode 0600. It refuses symlinks or unsafe existing permissions. The trusted host can import `startBroker` from `src/index.mjs`, or fork `src/process.mjs` with an IPC channel. With `fork`, send exactly one boot message: ```js {op: 'boot', config: { dataRoot, businesses, launches, readers: ['business-id'], repoRoots: [repoRoot] }} ``` `businesses` maps business IDs to normalized business definitions. Call `busBusiness(business, resolvedByInstance)` to adapt S1's `loadBusiness` and `resolveInstance` results. It copies resolved authority limits and credential references into each role instance. It never expands an authority map or loads files. Until S1 freezes its interface, callers may supply that normalized shape explicitly: `{id, human, arbiters:{technical,delivery}, roles:{instance:{authority: {withinRole:[],crossRole:[]}, credentials:{gitea?,vikunja?}}}, launch?}`. Empty maps grant no actions; missing maps refuse. The runtime always excludes its own repository root and every declared project root when loading credentials; `repoRoots` adds any other source checkouts. The host owns config/definition validation. Launch records are `{business, role, run, harness, address?, pid, startTime}`. `pid` and kernel `/proc//stat` start time identify the managed process. Harness is `pi` or `claude-code`. Bind only a launch the trusted host actually performed. Binding appends `session.launched`; rebinding after broker restart requires identical recorded identity. A changed role, harness, address or process identity refuses. Never register an arbitrary client-supplied launch record. The launcher must set `MOSAIC_RUN_ID` in every managed process's environment and preserve it for descendants, including after the original process exits. The boot reply is `{ok:true,path,launches:[{business,run,cap}],readers: [{business,cap}]}`. Distribute each random capability only to its intended run/reader, through an inherited private channel. It is a broker capability, not a Gitea/Vikunja token. A capability binds business, role and run; socket requests never declare those identities. Reconnect after restart requires a new capability from the trusted host, not a socket re-registration. For a later real launch the trusted host sends `{op:'bindLaunch',record}` over its original IPC channel, receiving `{ok:true,launch:{business,run,cap}}`. A refused binding returns `{ok:false,error}` and keeps the broker running. The embedded runtime offers the same `bindLaunch(record)` wrapper, which also updates the human ancestry registry. S6 must use that wrapper. Do not use the underlying Broker's test-level binding API to bypass runtime process checks. A rebind of a run that already has `session.ended` refuses with `run-ended`, also after a restart, and a refused bind leaves the run unbound. Row 65 (#1558): the record's `harness` is a plug-in module name (the loader's pattern), else `invalid-harness`; the broker names no harness itself. A new run binds only when `harnessOn(business, name)` says the organization file's `plugins.harness` switches it on now, else `invalid-harness`. A run the store already has binds again even after its harness is switched off, so it can be ended. A broker built without `harnessOn` (the unit tests') lets every module name through. The record may carry `transcript`, an absolute path where the harness keeps the run's session files, for the usage reader; it is held in memory only. A request that carries a safe-integer `id` gets the same `id` on its reply, refusals included, so the host can match each reply to its request (`packages/cli/README.md`). A request without one gets a reply without one. S6 adds launch ops on the same IPC channel, one reply each (`{ok:true,result}` or `{ok:false,error}`), none of them socket verbs: - `{op:'identity',cap}`: the business, role and run a capability names. - `{op:'authorizeLaunch',cap,instance}`: `authorize(cap,'role.launch', {target:instance})`; a refusal is also recorded as `action.refused`. - `{op:'refuse',cap,code,subject?}`: records a refusal the host decided itself (instance list, capacity, a failed spawn, a git socket check) as `action.refused` against the caller, the code only. A task ref as `subject` files the refusal on that task's trail, as a refused verb's does; any other subject, or none, records null (row 93). - `{op:'endLaunch',record}`: `{business,run,reason,exitCode?}` for a run this broker bound. It writes `session.ended` `{reason,exitCode,released}`, releases the run's claim if it still holds it, and drops every capability of the run. A second end refuses with `run-ended`, an unbound run with `unknown-run`. `reason` is an identifier the launcher picks (`packages/cli/README.md`, "Sessions"). - `{op:'credentialStatus',business,role}`: the role's `{service,date,state}` rows, never a token. Row 93 (#1587) adds three ops for the host's git socket (`packages/cli/src/git-socket.mjs`). A refusal from any of them is recorded as `action.refused` on the task's trail. - `{op:'checkPush',cap,task_ref}`: `checkPush(cap,task_ref)` checks the caller's `git.push.working` authority before the host takes a push's bundle. It records nothing unless it refuses. - `{op:'recordPush',cap,push}`: `push` is `{task_ref,project,branch,ref, commit,previous}` once the work ref moved. It checks the authority again and writes the `action.allowed` for `git.push.working`, with the task as subject and `{project,branch,ref,commit,previous}` in its body. That event is the push record: the only `action.allowed` for `git.push.working` that names a commit. The project must be one of the business's. The host moves the ref back when this refuses. - `{op:'reviewFetch',cap,args}`: `args` is `{task_ref,request}`. The caller must hold `review.verdict` and be the role the `review.requested` event was addressed to (`request-not-found` otherwise). Returns the request's `{project,commit,ref}`, which the host bundles for the reviewer. Row 137 (#1631) adds four ops for a landing on a working repository's `main` through the same git socket. The decision checks are land-work's, in `src/landing.mjs` (`readLanding`), which `scripts/land-work/read.mjs` also calls. Each caller names its branch, `refactor` for land-work and the task ref for an agent's landing, and the decision's target has to match it. So a decision raised for one can't land the other. land-work accepts only a decision the human resolved through the CLI (`human/cli`). The broker passes `arbiter: true`, which also accepts a `cross-role` decision its arbiter resolved (REQ-DEC-2). It refuses a decision of any class but `cross-role` with `not-authorized` (REQ-LAND-1). That covers `gated` and `within-role`: only a role granted `git.merge.protected` cross-role lands, whoever resolved the decision. - `{op:'checkLand',cap,args}`: `args` is `{task_ref,decision}`. The caller must hold its claim and the decision: `git.merge.protected`, raised by this role in this thread with the task ref as its target, of class `cross-role` (`not-authorized` otherwise), resolved with its approval option and not yet used (`decision-consumed` otherwise). Then `readLanding`'s checks, and the verdict's commit must be the task's latest push (`ref-moved`). A landing with no subject refuses `no-subject`, since an agent has no `--subject` to pass. Returns a ticket with what the host needs: the project, the work ref, the commit, the verdict and the resolution, with its `via` (`cli` or `broker`). It records nothing unless it refuses. - `{op:'recordLand',ticket,land}`: `land` is `{commit,previous,reviewed, base,patch_id}` once `main` moved. The checks run again inside the transaction. It writes the `action.allowed` for `git.merge.protected` on the task's trail, which spends the decision, and sends the role a RESULT in the decision's thread. When it refuses, the host moves `main` back. - `{op:'landRefused',ticket,args}`: `args` is `{code,detail,notify}`. It writes `action.refused` with the code on the task's trail and ends the landing. With `notify` the role gets a RESULT too, since the git socket had already answered `started`. - `{op:'landHeld',record}`: `record` is `{business,role,thread}`. True when the role, in that thread (null for a role run), holds a `cross-role` merge decision a landing could use. The launcher binds the git socket's land op only then; `checkLand` still checks everything. A ticket lives in the broker's memory from `checkLand` until `recordLand` or `landRefused` ends it, so either may run after the run ended. An unknown ticket refuses `land-unknown`. `{op:'close'}`, SIGTERM and SIGINT close the socket and DB and remove the owned writer lock. Losing the host IPC channel closes with exit 2. Startup or host protocol failures return a static error code and exit 2, never a raw exception. Capabilities vanish with the process. A SIGKILL/crash leaves `writer.lock` and possibly the socket: **there is no automatic stale-lock reclaim**. An operator must establish that the old broker is gone, preserve the DB/WAL/SHM as evidence, and explicitly remove only the stale lock/socket before restarting. Never delete the database to get around an open-time refusal. ## Client protocol Import `Client` from `@mosaic/bus/client` (or `src/client.mjs`). `new Client({path,cap}).call(verb,args)` opens one Unix socket per request and returns plain JSON or throws `BusError` with a static `.code`. One JSON line, 64 KiB request maximum, five-second timeout. There is no SQL verb and no automatic retry. Responses are capped at 4 MiB by the client. Oversized reads refuse; pagination is not part of this first core. A disconnect or timeout reports `outcome-unknown`. A mutation may already have committed. Callers must inspect its evidence before deciding what to do; they must not resend automatically. `message.receive` records delivery when the broker hands the batch to the connection, not when the harness acts on it. A lost response leaves an uncertain delivery, never automatic replay to a new holder. A holder that releases a role without reading what it received leaves those messages stranded: no later holder receives or reads them, and `agents` lists them under `stranded` (Agent state, below). `message.read` is an explicit acknowledgement. `trail(messageId)` lets an operator inspect content and delivery evidence after an uncertain result. | Verb | Arguments and result | |---|---| | `role.claim` | No args; claims capability's role/run. One current holder per business/instance; a revoked run cannot reclaim that role, including after restart. | | `role.release` | No args; only its current holder releases. | | `role.revoke` | `{role,decision}`; needs an approved decision for this exact target and holder incarnation, routed as REQ-DEC-2 says: the human's for an uncited gated raise, the arbiter's for one citing the current spec. A role whose file lists `role.end` (the chief of staff, row 123, REQ-COS-1) sends `{role,reason}` instead: no decision, a reason of 1 to 500 characters, logged in the `action.allowed` body. Sending both is `invalid-request`; the caller's own run is `role-end-refused`; any other role sending `reason` gets `decision-required`. An instance whose definition is in `END_PROTECTED` (the assistant) is ended or revoked only by the chief of staff or with a decision the human resolved through the CLI (`via` `cli`); anyone else's reason, or a decision an arbiter resolved, is `role-end-refused` (Jason's ruling Q169, row 139). A target whose definition is `THREAD_DEFINITION` (the assistant) has no role claim: the end revokes the current claim of each of its threads, refuses `not-held` when none is held, and returns `{revoked:true,threads:N}` (row 155, #1649). | | `organization.set` | `{revision,limits?,models?,instances?,assistants?}`; the keys `limits.set` takes, through the same writer and receipt. Needs `organization.change` in the caller's role file (the chief of staff); the receipt's actor is `.`, e.g. `chief-of-staff.chief`. Every other key is `invalid-request`. `limits.set` stays human-only, and a tester gets `tester-refused` from `organization.set` (row 175, #1673). `assistants` (row 155, Q169) is described in the business README; a refusal from it passes through as its `organization-*` code. The chief of staff learns the revision from `organization.revision` (below); a stale one is `revision-conflict`. | | `organization.revision` | No args (row 134, #1669). Answers `{revision}`, the organization file's current revision, and nothing else the human's `limits` read returns: no limits, models, instances or tokens. Needs `organization.change` in the caller's role file, with the same refusals as `organization.set` (`not-holder`, `read-only`, `tester-refused`, `agent-required` for the human, `decision-required` for a role whose only classification is cross-role; no shipped role is). A read never spends the grant and writes no receipt. Any argument is `invalid-request`. `limits` stays human-only, apart from the tester's read (row 175). | | `decision.raise` | `{action,question,options:[{key,text}],recommendation,blocking,domain?,target?,project?,task_ref?,requirement_ref?,supersedes?,choice?,approvalChoice?}`. Returns decision with decoded options and authorization context. A blocking decision holds a task: `blocking` true with no `task_ref` refuses `task-required`. A non-blocking one needs no task, and an uncited gated action such as `prd.approve` or `role.revoke` still routes to the human's inbox. | | `decision.resolve` | `{id,choice,note?}`; option must exist, resolver must be routed role or outside-agent human CLI. Sends the raising role a DECISION message (Decision close messages, below). | | `decision.seen` | `{id,note?}`; acknowledgement by resolver, not a resolution. | | `decision.withdraw` | `{id,note?}`; raiser or human. Never rewrites the decision. A human withdraw sends the raising role a DECISION message; the raising run's own withdraw sends none. | | `message.send` | `{to,body,class?,in_reply_to?,corrects?,decision?}`; returns `{id,request}`, plus `waiting` when no run holds the target (Launch notices, below). Human instruction's `request` is its `human.input` event ID. `to` is a role instance, its name (row 141, #1635, REQ-MSG-2), `human` or `tester`. A name resolves to its instance before any check; the message stores the instance in `to_role` and the name in `to_name`, null for a send by instance. An instance key, `human`, `tester` and a role definition the business knows win over a name equal to them, so an instance added later with a key some instance holds as a name still gets its messages, and a send to a later definition's name refuses `unknown-role`. A name the business doesn't hold refuses `unknown-role`. | | `message.receive` | No args; up to 100 undelivered messages for current holder, including originating `request` for human instructions. A human decision close's message carries the close's `human.input` answer event as its `request`; a role close's has `null`. | | `message.read` | `{id}`; recipient holder's acknowledgement; no new holder can acknowledge old holder's delivery. | | `name.set` | `{instance,name}`; action `instance.name`, routed under REQ-MSG-2 (row 141, #1635). The outside-agent human CLI may; an agent only when its role file grants `instance.name` within-role, which the chief of staff's does, and the write logs `action.allowed` with the instance as target. A tester may too (row 175, #1673): every name check runs, no authority is spent and `by` is `tester`. Any other class refuses `not-authorized`, so no decision sets a name. `name` matches the business ID pattern. It refuses `name-is-instance` when it equals an instance key, `human` or `tester`, `name-is-role` when it equals a role definition the loaded business knows (one an instance uses or one it defines), and `name-taken` when another instance of the business holds it now. The `instance_names` trigger backs up the last. Naming an instance again replaces its name. Returns `{instance,name}`. | | `assistant.stop` | `{instance}`; outside-agent human CLI only (`human-required`), row 155 (#1649, Q169). `instance` must be a known instance (`unknown-role`) of `THREAD_DEFINITION` (`not-assistant`). Revokes the current claim of every thread of that instance the human made (REQ-USER-2), with `by` the human and reason `stopped by the human`; none held is `not-held`. Each run gets `not-holder` at its next bus call and exits. The launcher starts a run again only for a thread with pending messages or an open. Returns `{stopped:[{thread,run}]}`. | | `names` | No args; human and agent sessions. Each named instance's current `{instance,name,at}`, by instance. | | `staff.request` | `{task_ref,roles,note?,decision?}`; action `message.send` (row 140, #1634, REQ-COS-1). `roles` is 1 to 10 distinct `{role,count}` entries, `count` an integer 1 to 20; any other shape is `invalid-request`. Only an instance of the `pm` definition sends it (`staff-request-refused`), and it goes to the business's launcher, which must be an instance of `chief-of-staff` (`no-chief-of-staff`); the definitions' `messaging` lists apply as for `message.send`. Sends that instance a STAFF-REQUEST message naming the task and the roles with counts, and writes an `action.allowed` event with `operation: staff.request`, `staff_for` and `roles`. `message.send` and `thread.send` refuse the class `invalid-class`, so no other path writes one. It grants nothing: the chief of staff launches through `role.launch` within the organization's limits and replies to the message with the instances it launched or the refusal. Returns `{message,to}`. | | `review.request` | `{task_ref,commit,to,note?,decision?}`; action `review.request` (row 93, #1587). `commit` must be the task's latest pushed commit: an older one refuses `stale-commit`, any other `unknown-commit`. `to` must be another role holding `review.verdict` (`unknown-role`, `self-review`, `not-a-reviewer`). Writes a `review.requested` event `{task_ref,project,ref,commit,to,message,held}` and sends `to` a REVIEW-REQUEST message naming it. `held` is the run id holding the `to` role when the request is routed (row 105, #1599), or `null` when no run holds it: the message then waits for a claim, and the requester should tell whoever launches roles. Returns `{request,message,commit,ref,held}`. | | `review.verdict` | `{task_ref,request,verdict,body,decision?}`; action `review.verdict`. `verdict` is `approve` or `changes`. `request` must be a `review.requested` event on the task addressed to the caller's role (`request-not-found`), with no verdict yet (`verdict-exists`). Writes a `review.verdict` event `{task_ref,request,commit,verdict,message}` and sends the requesting role a REVIEW-RESULT in reply to the request's message. Returns `{verdict,message,commit}`. | | `event.emit` | `{kind:'action.allowed',body:{action:'routine',target?},subject?}`; routine observations only. | | `launch.revoke`, `launch.restore` | No args; outside-agent human CLI only. | | `inbox` | No args; plain JSON projection scoped to capability's business. | | `tasks` | Optional args, scoped to capability's business (row 89, #1583). None: every row of the tasks projection (below). `{task_ref}` alone: that one row, or `task-not-found`. Any of `{done,assignee,label,requirement,limit,after}`: `{tasks,total,next}`, the short form (below). An unknown arg or bad value refuses `invalid-request`. | | `agents` | No args; each held role's latest claim row in the capability's business. Human and reader sessions also get `state`, `working`, `inputNeeded` and `stranded` (Agent state, below); a role session gets the claim rows only. | | `trail` | `{subject}`: task ref, decision UUID or message UUID. Linked records in broker write order. | | `decisions` | `{list}`: `roles` or `recent`; human and reader sessions only. Open decisions routed to a role, or the last 50 closed. | | `credentials` | No args; human and reader sessions only. `[{service,account,role,dateKind,date,state}]` for the capability's business, never a token, file path or variable name. | | `requirements` | No args; role sessions only, as `task.create` is (row 90, #1584). The approved PRD's requirement ids, `{prd,version,requirements:[{id,title}]}`, from `packages/tasks/requirements.json`, loaded when the broker starts; a bad file refuses the start. A human session refuses `agent-required`, a reader `read-only`. | | `state` | No args; role, human and reader sessions (row 109, #1603). `{launch:{state,at,event},tasks:{open:[{task_ref,title}],total,cap}}` for the capability's business. `launch` is the latest `launch.revoked` or `launch.restored` event: `allowed` with `at` and `event` null when none exists. `open` is the tracker snapshot's open tasks in `task_ref` order, at most `cap` (the `tasks` page size, 50); `total` counts every open task. The harness runner reads it before each turn. Writes nothing. | | `replies` | `{id}`: a message UUID; human and reader sessions only. The messages whose `in_reply_to` is that id, oldest first, at most 50. Writes nothing. | | `project.create` | `{name,repo?}`; human sessions only (row 121, #1615). `repo` must name one of the business's `projects` (`unknown-repo`); a second project with the same name refuses `project-exists`. Returns `{id}`. | | `project.list` | No args; human sessions only. The business's projects, oldest first. | | `thread.create` | `{project,name}`; human sessions only. The thread belongs to the caller and to the business's one thread instance (Projects and threads, below). Returns `{id,instance}`. Refuses `project-not-found`, `thread-exists`, `thread-instance-missing` or `thread-instance-ambiguous`. | | `thread.list` | `{project?}`; human sessions only. The caller's own threads, oldest first. | | `thread.open` | `{thread}`; human sessions only. Records a `thread_opens` row, which asks the launcher to start the thread's session. Returns `{opened}`. | | `thread.send` | `{thread,body,class?}`; human sessions only. A message to the thread's instance, in that thread, with its `human.input` event as `request`. Returns `{id,request}`. | | `thread.messages` | `{thread,after?,limit?}`; human sessions only. The thread's messages oldest first, after the message `after` names (`message-not-found` when it isn't in the thread), at most `limit` (default 50, 1 to 200). Writes nothing. | ### Projects and threads (row 121, #1615) A thread is one conversation between a user and the business's thread instance, the role whose definition is `assistant` (REQ-THREAD-1). Projects group threads (REQ-ORG-2). Schema `3e` adds five append-only tables: `projects`, `threads`, `thread_claims`, `message_threads` and `thread_opens`. A message's thread is a `message_threads` row written with the message, so `messages` keeps its old columns. A thread instance's run is for one thread. `bindLaunch` refuses a record for that role without `thread` (`thread-required`) or naming a thread of another instance or business (`thread-not-found`), and a record for any other role that names one (`thread-not-allowed`). The run's `role.claim` writes a `thread_claims` row, not a `role_claims` row. One run holds a thread at a time (`thread-already-held`), and a run holds at most one thread. An idle thread has no run and holds nothing, so it counts against no launch limit (REQ-THREAD-2). Every message to or from a thread instance names its thread (REQ-MSG-1): - A thread run's own message is in its thread. - A human reaches a thread instance only through `thread.send`. A `message.send` to it refuses `thread-required-use-thread-send`. - Any other role's message to a thread instance needs `in_reply_to`. The broker walks the `in_reply_to` chain to the nearest message that has a thread, so the chief of staff's reply returns to the thread that sent the work. The walk stops where the chain ends; there is no depth constant. No threaded ancestor refuses `thread-required-reply-to-thread-message`, which is the whole text a run sees, so it says what to do. A threaded ancestor in another instance's thread refuses `thread-instance-mismatch`. - A thread run's `message.receive` returns only its own thread's messages. Triggers back the broker. `thread_one_holder` and `thread_one_per_run` refuse a second holder and a second thread. `message_threads_match` refuses filing a message under a thread of another business, or under a thread whose instance neither sent nor receives it. `delivery_same_thread` refuses routing or delivering a threaded message to the instance to any run but the thread's current holder. A user reaches only their own threads (REQ-USER-2): `thread.open`, `thread.send` and `thread.messages` refuse `thread-not-found` for an unknown id and `thread-not-owned` for another user's thread. `threadsState(business)` is a trusted launcher API, like `bindLaunch`, not a socket verb. Per thread it returns `{thread,instance,pending,unread,lastMessage,lastOpen,lastClaim,holder}`: messages to the instance not yet delivered, messages delivered to the current holder and not yet read, the latest message, open and claim times, and the holding run or `null`. The launcher reads it to start and stop thread sessions (`packages/cli/README.md`). `threadIdle({business,thread,run})` is the launcher's idle stop, also trusted and not a verb. It rechecks the thread and releases the run's claim in one call, and returns `{released:true}`, or `{released:false,pending,unread}` when a message came in after the launcher's snapshot. The launcher signals the run only after a release, so a message sent after the snapshot gets a turn from the same run or waits as `pending` for the next one. It refuses `not-holder` for a run that doesn't hold that thread and `run-ended` for an ended run. A message delivered to a thread run that then ended without reading it is stranded, as `stranded` (Agent state, below) describes for a role. It counts as neither `pending` nor `unread`, so it neither starts a session nor keeps a later one from idling out. The user sends it again. Row 155 (#1649) makes `role.revoke` reach thread runs. A thread instance has no `role_claims` row, so a decision to revoke it records a null holder run, and the check compares it with the current holder read as null too. The chief of staff's reason path and a decision the human resolved through the CLI both get past the assistant's protection (Q169), and the end then writes a `revoke` row in `thread_claims`, with its decision or reason, for every thread of the instance whose latest claim is held. The human does the same from the Console with `assistant.stop`, for the threads they made. A revoked run can't claim its thread again (`run-revoked`). A stuck thread run can still be stopped another way: the launcher stops it once the thread is idle, the human stops it with `mosaic stop `, and the run's end releases its claim. `thread_revoke_needs_decision` guards the table against a direct write. ### Agent state (row 59, #1548) For a human or reader session, `agents` derives each held role's state from records the bus already keeps. Nothing new is written and no schema changed. - `working` is `{messages, since}` or null: messages to the role that the current holder received and hasn't marked read, and when the oldest was received. The runner receives a batch, takes one turn per message, replies and marks it read, so working means a turn is under way or queued. - `inputNeeded` lists the role's open decisions routed to the human, gated first and then oldest, as the Inbox orders them. Each item is `{id, question, class, blocking, task_ref, at}`. Seen is still open. - `state` is `working` when `working` is set, else `waiting` when `inputNeeded` is nonempty, else `idle`. Working wins over waiting, as on the control board. - `stranded` lists messages to the role that an earlier holder was delivered and never read, as `{id, from, run, at}`: the sender (`human` for the CLI), the run it was delivered to, and when. Oldest first, at most 50, `[]` when none. The bus neither redelivers, routes nor marks these read, and the released run can no longer read them, so they stay listed. A person who still needs one sends it again as a new message. Why the bus and not a seat-to-role map: the business file's `holder` is a display name, and the claim's holder is a run, not a seat, so no committed data joins a seat to a role. The bus already has the claim, the deliveries and the decisions. Limits: a message routed but not yet received shows idle. A reply that fails for a reason other than a gone session leaves its message unread, so the role stays working; `since` shows how long. No error or offline state is derived. A new holder doesn't inherit the previous holder's unread deliveries; decisions stay with the role. Unheld and released roles aren't listed, so a message stranded for a role nobody holds shows once a run claims the role. Unknown keys, roles, references, actions and verbs refuse. If writing refusal evidence fails, the caller receives the static `storage-unavailable` code. `human` is the reserved recipient. Message classes are REQUEST, ASSIGNMENT, REVIEW-REQUEST, REVIEW-RESULT, RESULT, INFO, DECISION, REACTION and BLOCK (row 143). `staff.request` also writes STAFF-REQUEST (row 140); `message.send` and `thread.send` refuse that class. References cannot cross businesses. A BLOCK answers a spec notice (Spec review notices, below). `message.send` accepts it only from a pm or cto instance (`block-sender`), only to the chief-of-staff instance (`block-recipient`; the assistant may hear only from the user and the chief of staff, REQ-ASSIST-2), and only with `in_reply_to` naming a notice the bus sent that sender (`block-reply-required`). The BLOCK sits in no thread, because a message may join only a thread whose instance sent or received it. When the chief of staff relays to the assistant in reply to the BLOCK (or to anything on a chain back to the notice), the reply chain reaches the notice, and the relay is filed in the user's most recently opened thread of the notice's project whose instance is the assistant. With no such thread the relay is refused (`thread-required-reply-to-thread-message`). `thread.send` refuses the class. Routing is immutable at raise: within-role closes atomically with `choice`, cross-role routes to the configured delivery arbiter (or technical arbiter with `domain:'technical'`). A gated raise that cites the project's current spec commit routes the same way, to the arbiter for its domain (PRD 1.5 REQ-DEC-2, row 139, #1633). If that arbiter is the raiser, resolution routes to human while the decision keeps its class. An uncited gated raise routes to human. Unlisted actions are gated. The hard waits (`HARD_WAITS`, REQ-WAIT-1: `spend`, `data.delete`, `network.expose`, `account.create`, `credential.mint`, `message.external`, `git.push.protected`, `deploy`) always route to human, cited or not, and cannot appear in authority maps. An action is a hard wait unless the broker's `ROUTED` list names it (REQ-WAIT-3), and both lists match the business vocabulary. `git.merge.protected`, `policy.change`, `prd.approve` and `role.revoke` left the gated-only list in 1.5, so a role file may grant them. Under Jason's ruling Q169 (PRD 1.6), a `role.revoke` whose target's definition is in `END_PROTECTED` (the assistant) is still gated at every class and routes to human, cited or not, so no arbiter resolves it. A blocking decision requires a strict task ref. `role.launch` is gated unless the business launch block's `by` names the acting role and refused when launch state is revoked. S6 still owns launch allowlists, capacity and actual spawning. Whoever closes a decision messages the raising role, so a cross-role or gated raise also needs the route to be allowed to message the raiser under the role definitions' messaging lists (row 133, #1627). In practice the raiser's `receiveFrom` must list the arbiter's definition, or `human` for a gated route. Otherwise the raise refuses `decision-route-refused`, logs `action.refused` and stores nothing. A within-role raise is exempt. The close itself isn't checked again; the business validator refuses an arbiter whose role definition declares messaging lists. `decision.raise` checks its choices in this order, and each of these codes names one field: | Code | Field | Refused when | |---|---|---| | `invalid-options` | `options` | not an array, fewer than 2 or more than 9 options, an option whose `key` isn't 1 to 160 letters, digits or `_.:/-` starting with a letter or digit, or whose `text` isn't a string of 1 to 1024 characters with no NUL, or duplicate keys | | `invalid-recommendation` | `recommendation` | the value isn't exactly one option key; `"yes: a reason"` refuses, so the reason goes in `question` | | `invalid-approval-choice` | `approvalChoice` | the value, or the default `yes` when it is omitted, isn't an option key | The options come first, so a bad option list refuses `invalid-options` even when the recommendation also misses. An option that isn't an object with exactly `key` and `text` refuses `invalid-request`, like any other malformed argument. Authorization requires the resolved option identified by `approvalChoice` (default `yes`, which must exist), the same raiser role instance, action and target. Row 136 (#1630): the approval binds to the decision, the business and the role instance (`raised_by_role`, the key in the business's `roles` map), not to the run that raised it, so it outlives a restart and any run of that instance holding its claim may consume it. A decision raised by a thread run binds to that run's thread too: only a run holding the same thread consumes it, and a decision a thread instance raised before row 121 matches no thread run. Another instance, or the same instance in another thread, refuses `decision-mismatch`. `role.revoke` still requires the target's holder run recorded at the raise. Inbox projections expose `{action,target,approvalChoice}` as `authorization`: **S4 must display this context when offering resolution**, not infer approval from recommendation or option position. Any other option is a refusal, even if the decision is resolved. Every decision-backed authorization is single-use, including cross-role approval (lead decision 64). `authorize`, `message.send` and `role.revoke` share one authority-and-consumption helper. Each caller keeps the consumption check, `action.allowed` event and any broker-owned effect in one transaction. A later use through any of those paths, by any run and including after restart, refuses with `decision-consumed`. The `decision.raise` context event does not consume approval. A failed transaction rolls consumption back. A mismatch between the decision's recorded class and current policy refuses with `decision-mismatch` before use, in either direction. Within-role `authorize` calls without a decision retain their existing behavior; explicitly supplying a decision to `authorize` subjects it to the same checks. Every agent `message.send` writes `action.allowed`, including within-role sends without a decision; its subject is the recipient role. On a within-role send, `decision` is a citation: the broker checks that it exists in the same business and stores it in `messages.decision`, but omits it from `action.allowed`. An open, unresolved or already-consumed decision can be cited repeatedly, without class matching or consumption. If sending is not within-role, `decision` supplies authority and the full matching, resolution and single-use checks still apply. A consumed approval is not an exactly-once external service operation receipt; an uncertain external outcome must not be retried with that approval. S3/S6 must implement their own external-operation identity and uncertain-outcome handling. Raising/superseding and resolving are transactional. `supersedes` names an open decision raised by the same role instance, in the same thread when it was raised in one, by this run or an earlier one; otherwise the raise refuses `supersede-refused` and withdraws nothing. ### Decision close messages (row 115, #1609) A `decision.resolve` or `decision.withdraw` by anyone but the raising run sends the raising role one message, written in the same transaction as the close, so a refused close sends nothing. It goes to `raised_by_role` with class `DECISION`, `decision` set to the decision's id, and no `in_reply_to` or `corrects`. A human close is sent `from_role 'human'`, `from_run 'human-cli'`; a role close is sent from the closing role and run. It is routed like `message.send`'s: to the role's current holder, or with no holder until the next claim routes it. The body is ``` Decision on was resolved by : (