feat(bus): agent pack verbs and the hire proposal pin check (SP5, #1873) #1957

Merged
jason.woltje merged 3 commits from sp5 into refactor 2026-11-13 01:14:11 +00:00
Owner

Starter packs slice SP5 (#1873): the chief applies a pack's non-definition half and raises hires from the pack's proposals. Design: docs/plans/2026-11-12_starter-packs-design.md section 3 "The chief applying a pack" and section 8 SP5. Jason's 11-12 Q2: holders of organization.change write boards and workflows with no decision. Only the chief raises hires.

  • Agent verbs (broker): the unsuffixed packs, pack.preview, pack.apply, board.set and workflow.set now serve an agent session. Reads need organization.change in the role, or they refuse human-required. Writes run the authority check: a role without the grant gets decision-required, or not-holder when unclaimed. The writer re-checks inside beforeWrite and spends the grant once, after the commit. A repeat apply that writes nothing spends nothing. The recorded actor is the definition instance. The .console names stay the owner's, and the agent request has no origin or actor key.
  • Agent apply (runtime packOps): definitions are never written. Each one a human apply would add is marked not-written, and its hire pins the template ref, or {inline, sha256} with the entry stored beside the proposal. A definitions.* rename or a saved pack refuses human-required before anything is read. A workflow step naming a role the agent cannot write is left out and listed in leftOut. A workflow with no steps left is marked left-out and not written.
  • hire.raise {proposal, route, reason?}: checks the agent session, then the chief (role-not-chief), then role.hire (not-authorized), and only then reads the packs list. Template and definition pins go to the existing prepare (decision-stale, definition-rev-conflict). An inline pin's stored entry must still hash to its pin (starter-pack-proposal-stale, new refusal with a table entry) and must not name a noHire template (definition-not-hireable). A raise without proposal is unchanged.

Files: packages/bus/src/{broker,runtime,refusals}.mjs, packages/bus/tests/packs-agent.test.mjs (new, 14 tests), packages/bus/tests/packs.test.mjs. Nothing in webui, organization, roles/ or contracts/.

Tests: red before, packs-agent.test.mjs passes 1 of 13 on BASE. Lane gate on 1fb1b8ab3 (same tree outside webui as this head): 8061/2 over 762 files, plus test-config.sh and test-task.sh rc 0. The 2 fails are the CHAT-01 jsonschema base red. Lead check under env -i on this head (229 files: touched tests, importers of broker, runtime and refusals, refusal and redact tests): 2721/0.

Reviews (fresh Opus 5.5 delegates): the build review and the security review both approved, with 5 and 4 P3s. The full gate then caught a regression both missed: the broker had pulled organization modules into its sandbox import closure. That and five P3s were fixed in 808b2b7cb, each with a test. The security re-check approved it and found one new P3: the inline pin was hashed with digestPrd, whose key order differs from canonicalJson for integer-like keys, so such an entry would refuse as stale on every raise. 34dd33101 fixes that with a local copy of canonicalJson in the broker (no import, to keep the closure). No reviewer read that last change. The Lead read it, checked it against packages/organization/src/util.mjs canonicalJson, and ran both builders over 7 entries: all 7 match, and the old code differed on 2. It fails closed either way.

Deferred:

  • No suite test for the integer-key pin case; it needs a plugin-service fixture with an all-digit scope group.
  • Proposal match carries no origin; the latest entry by id, project and hire name wins. The hire decision recomputes flagged lines from the role, so a wrong match cannot widen a grant unseen.
  • The organization writer's agent-actor fence is a denylist that predates SP5.
  • If a run ends while an async pack.apply is in flight, the write lands but the post-commit spend refuses. organization.set behaves the same; the fix belongs with that shared pattern.
Starter packs slice SP5 (#1873): the chief applies a pack's non-definition half and raises hires from the pack's proposals. Design: `docs/plans/2026-11-12_starter-packs-design.md` section 3 "The chief applying a pack" and section 8 SP5. Jason's 11-12 Q2: holders of `organization.change` write boards and workflows with no decision. Only the chief raises hires. - Agent verbs (broker): the unsuffixed `packs`, `pack.preview`, `pack.apply`, `board.set` and `workflow.set` now serve an agent session. Reads need `organization.change` in the role, or they refuse `human-required`. Writes run the authority check: a role without the grant gets `decision-required`, or `not-holder` when unclaimed. The writer re-checks inside `beforeWrite` and spends the grant once, after the commit. A repeat apply that writes nothing spends nothing. The recorded actor is the definition instance. The `.console` names stay the owner's, and the agent request has no origin or actor key. - Agent apply (runtime `packOps`): definitions are never written. Each one a human apply would add is marked `not-written`, and its hire pins the template ref, or `{inline, sha256}` with the entry stored beside the proposal. A `definitions.*` rename or a saved pack refuses `human-required` before anything is read. A workflow step naming a role the agent cannot write is left out and listed in `leftOut`. A workflow with no steps left is marked `left-out` and not written. - `hire.raise {proposal, route, reason?}`: checks the agent session, then the chief (`role-not-chief`), then `role.hire` (`not-authorized`), and only then reads the packs list. Template and definition pins go to the existing prepare (`decision-stale`, `definition-rev-conflict`). An inline pin's stored entry must still hash to its pin (`starter-pack-proposal-stale`, new refusal with a table entry) and must not name a `noHire` template (`definition-not-hireable`). A raise without `proposal` is unchanged. Files: `packages/bus/src/{broker,runtime,refusals}.mjs`, `packages/bus/tests/packs-agent.test.mjs` (new, 14 tests), `packages/bus/tests/packs.test.mjs`. Nothing in webui, organization, `roles/` or `contracts/`. Tests: red before, `packs-agent.test.mjs` passes 1 of 13 on BASE. Lane gate on `1fb1b8ab3` (same tree outside webui as this head): 8061/2 over 762 files, plus `test-config.sh` and `test-task.sh` rc 0. The 2 fails are the CHAT-01 jsonschema base red. Lead check under `env -i` on this head (229 files: touched tests, importers of broker, runtime and refusals, refusal and redact tests): 2721/0. Reviews (fresh Opus 5.5 delegates): the build review and the security review both approved, with 5 and 4 P3s. The full gate then caught a regression both missed: the broker had pulled organization modules into its sandbox import closure. That and five P3s were fixed in `808b2b7cb`, each with a test. The security re-check approved it and found one new P3: the inline pin was hashed with `digestPrd`, whose key order differs from `canonicalJson` for integer-like keys, so such an entry would refuse as stale on every raise. `34dd33101` fixes that with a local copy of `canonicalJson` in the broker (no import, to keep the closure). No reviewer read that last change. The Lead read it, checked it against `packages/organization/src/util.mjs` `canonicalJson`, and ran both builders over 7 entries: all 7 match, and the old code differed on 2. It fails closed either way. Deferred: - No suite test for the integer-key pin case; it needs a plugin-service fixture with an all-digit scope group. - Proposal match carries no origin; the latest entry by id, project and hire name wins. The hire decision recomputes flagged lines from the role, so a wrong match cannot widen a grant unseen. - The organization writer's agent-actor fence is a denylist that predates SP5. - If a run ends while an async `pack.apply` is in flight, the write lands but the post-commit spend refuses. `organization.set` behaves the same; the fix belongs with that shared pattern.
jason.woltje added 3 commits 2026-11-13 01:14:09 +00:00
pack.preview, pack.apply, board.set and workflow.set accept an agent session whose role
lists organization.change (Jason 11-12 Q2): the check runs before the read, and the grant
is spent once after a write commits. A role without it gets decision-required. The packs
read lists packs for a within-role holder and spends nothing.

An agent apply never writes a definition. A definition a human apply would add is marked
not-written and its hire is pinned to the template or the inline entry. A workflow step
naming such a definition is left out and listed, and a workflow left with no steps is not
written. A definitions rename or a saved template refuses human-required, with the writer's
own guard behind both.

hire.raise takes {proposal: {pack, project?, hire}, route, reason?} from the chief. The broker
reads the recorded proposal, checks an inline pin's hash (starter-pack-proposal-stale) and
launch.noHire, and hands the pin to the hire service, which refuses a moved template or
definition as decision-stale or definition-rev-conflict.
The broker no longer imports organization util or definitions; the proposal
pin digest is digestPrd and the inline composition is built in place, so the
sandbox client import closure project-runtime.test.mjs pins is unchanged.
An agent apply the runtime skips (a repeat that adds nothing) never reaches
beforeWrite and spends no grant. A proposal raise checks role.hire before it
reads the packs list. An agent apply keeps a workflow step only for a pack
role the organization defines or one the pack pins to the template of that
name; an inline definition sharing a template's name is left out. Tests: a
repeat apply spends nothing, apply then raise end to end with the broker
booted from the file, a project pack, the template-name shadow, and a chief
without role.hire; the revision refusal is matched exactly.
digestPrd rebuilds an object, so integer-like keys come first and the JSON
differs from canonicalJson, the digest the pack apply records. An inline
entry with such a key (a credential scope map group) refused as stale on
every raise. The broker now builds the canonical string itself, a local copy
of util.mjs canonicalJson, so the sandbox import closure is unchanged.
jason.woltje merged commit 34dd331016 into refactor 2026-11-13 01:14:11 +00:00
Sign in to join this conversation.