feat(cli): cotal provision-acl + spawn provision the full durable-delivery footprint

[mattwilkinsonn]

Problem

Durable @mention-wake delivery to a dormant agent needs two pieces of registry/JetStream state, and two launch paths leave both unwritten:

1. The agent's read-ACL row in cotal_acl_<space> — the delivery daemon authorizes fan-out against it (absent row ⇒ DEFER, never deliver).
2. The agent's bind-only delivery durables — the daemon fans a @mention out to a per-member dlv_<id> DELIVER durable (and dm_<id> for DMs); the agent binds+pumps it (endpoint.ts pumpDlv) but is denied CONSUMER.CREATE on DLV — only a provisioner may create dlv_<id>. pumpDlv silently no-ops when the durable is absent, so even a correct ACL row delivers nothing if the durable was never created.

The two launch paths:

• cotal mint writes creds but is offline (no CotalEndpoint/connect at all), so an agent brought up via cotal mint + exec omp has creds but neither the ACL row nor the durables — it's @mention-wake-blind until something provisions the full footprint.
• cotal spawn hard-coded durableMembership: false, so every foreground-spawned agent stayed live-only even when a delivery daemon was serving.

Change

Implements the option-agnostic correctness core that honors the already-frozen ACL model in the coordination-structure / service-owner records. The mint-strategy decision (best-effort-in-mint vs cotal up auto-hook vs flag) remains OPEN on design PR #3 — this PR implements only the mechanism common to all three branches; the branch selection is still Matt's on #3.

• cotal provision-acl (new command) — a re-runnable, privileged pass that provisions the full durable-delivery footprint for every persona that already has creds: the bind-only dm_<id> + dlv_<id> mailboxes and the read-ACL row (exactly what provisionAgent writes for a spawned agent). It derives each agent's read ACL to match what its creds were minted with (so durable read scope never diverges from live). --dry-run prints the plan offline; a credless persona is skipped (this command never mints — minting is cotal mint's job, and mint-if-absent is the open docs(platform): durable-delivery ACL provisioning design #3 fork); a persona whose creds' baked read scope diverges from its file ACL is fail-loud skipped with a re-mint hint, never silently rewritten. Every write is idempotent (durable create-if-absent + commitAcl atomic CAS put), so the command is re-runnable.
  • Routine: implementations/cli/src/lib/acl-provision.ts — planAclProvision (offline plan) + provisionAcls (connect, then per persona provisionDmInbox + provisionDlvInbox + commitAcl, with ACL read-back verification). The inbox-provisioning is consolidated into the single provisionAcls routine alongside the ACL write, so the whole footprint is one privileged pass.
  • Command: implementations/cli/src/commands/provision-acl.ts, registered in index.ts.
• cotal spawn daemon-gate — replaces the unconditional durableMembership: false with a shard-0 delivery-lease probe (readDeliveryLease(0) !== undefined): daemon live ⇒ provision the durable membership; absent ⇒ stay live-only (absent-row = live-only is the registry's load-bearing semantic). Matches design PR docs(platform): durable-delivery ACL provisioning design #3's Task 3. cotal join's bare console stays intentionally live-only.
• Provisioner grant — provisionerPermissions gains STREAM.MSG.GET on the delivery bucket so the spawn/provision provisioner cred can kv.get the lease. (DM/DLV CONSUMER.CREATE was already granted — provision.ts — so the new durable-create calls need no further grant.)

Mint is byte-identical — untouched. provision-acl replicates mint's read-ACL derivation inline (allowSubscribe ?? subscribe, then ?.length ? it : ["general"]) rather than refactoring a shared helper, so there's no mint diff and no front-running the #3 fork.

Verification

Typecheck + full workspace build clean. Red-green smoke tests (real nats-server, isolated port) defend: the full footprint is created (dm_<id> + dlv_<id> durables exist after a run, not just the ACL row), ACL row written + reads back, creds-parity, drift-skip-not-rewrite, credless-skip, ["general"] default, idempotency (re-run is a no-op), bad-creds isolation (one corrupt persona never aborts its siblings), and the spawn daemon-gate decision (lease present ⇒ durable membership, absent ⇒ live-only). Verified passing locally against a live broker.

Co-Authored-By: seal noreply@sealedsecurity.com

[mattwilkinsonn]

• feat(cli): cotal provision-acl + spawn provision the full durable-delivery footprint #4 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 7 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b60d30b-2def-4b1b-aadc-a2d2eda69224

📥 Commits

Reviewing files that changed from the base of the PR and between 7c423fb and 6692149.

📒 Files selected for processing (2)

• implementations/cli/src/commands/provision-acl.ts
• implementations/cli/src/lib/connect.ts

📝 Walkthrough

Walkthrough

Adds durable read-ACL provisioning with a new CLI command and planner, daemon-gated durable membership in spawn, updated provisioner lease read access, and a live smoke test wired into CI.

Changes

Durable ACL Provisioning

Layer / File(s)	Summary
ACL provisioning core library implementations/cli/src/lib/acl-provision.ts	Adds plan and commit helpers that derive expected read ACLs, detect drift against minted creds, skip invalid personas, pre-create durable delivery mailboxes, and verify stored rows by read-back.
provision-acl CLI command and wiring implementations/cli/src/commands/provision-acl.ts, implementations/cli/src/lib/connect.ts, implementations/cli/src/index.ts	Adds provisionAcl with dry-run output, offline target resolution, and live execution, then registers it under the Mesh command group.
Spawn daemon-gate for durable membership implementations/cli/src/commands/spawn.ts, packages/core/src/provision.ts	Auth-mode spawn now derives durableMembership from delivery lease presence, and provisioner permissions gain delivery lease KV read access.
Live smoke test and script wiring implementations/cli/smoke/provision-acl-live.smoke.ts, package.json	Adds a live NATS smoke test covering ACL parity, drift, missing creds, defaults, idempotency, daemon gating, malformed creds, and DM/DLV durables, then wires it into smoke:ci.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User as CLI User
  participant CLI as provisionAcl
  participant Lib as acl-provision
  participant NATS as NATS/JetStream

  User->>CLI: cotal provision-acl --space ...
  CLI->>Lib: planAclProvision(root, space)
  Lib-->>CLI: per-persona plan
  alt dry-run
    CLI-->>User: print plan and exit
  else live
    CLI->>Lib: provisionAcls(root, space, server, auth)
    Lib->>NATS: start endpoint with provisioner creds
    Lib->>NATS: create dm_<id> and dlv_<id>
    Lib->>NATS: commit ACL row and read back
    Lib-->>CLI: provisioned/skipped result
    CLI-->>User: print summary
  end

Loading

sequenceDiagram
  participant Spawn as cotal spawn
  participant Prov as short-lived provisioner
  participant KV as delivery lease KV
  participant Core as provisionAgent

  Spawn->>Prov: start provisioner endpoint
  Prov->>KV: readDeliveryLease(0)
  KV-->>Prov: lease present or absent
  Prov-->>Spawn: daemonLive boolean
  Spawn->>Core: provisionAgent(durableMembership = daemonLive)
  Core-->>Spawn: ACL row written or skipped

Loading

Poem

A rabbit hops through JetStream bright and wide,
Checking leases, ACLs, side by side. 🐇
Drift or missing creds? Skip with grace,
Durable rows land in their proper place.
Smoke tests purr, the burrow feels secure.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main CLI change: adding provision-acl and updating spawn to provision the durable-delivery footprint.
Description check	✅ Passed	The description matches the implemented changes and their goals, including the new command, spawn gating, and provisioner permissions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cotal-durable-acl-provision

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR adds durable-delivery provisioning for personas and foreground spawns. The main changes are:

• New cotal provision-acl command for persona ACL rows and DM/DLV durables.
• Offline dry-run planning and live provisioning paths.
• Spawn-time delivery lease probe for durable membership.
• Provisioner permission to read the delivery lease bucket.
• Live smoke coverage for provisioning, bad creds, idempotency, and lease gating.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
implementations/cli/src/lib/acl-provision.ts	Adds persona ACL planning and live provisioning for ACL rows plus DM/DLV durables.
implementations/cli/src/commands/provision-acl.ts	Adds the CLI entry point for dry-run planning and live ACL provisioning.
implementations/cli/smoke/provision-acl-live.smoke.ts	Adds live broker smoke coverage for provisioning behavior and spawn lease gating.
implementations/cli/src/commands/spawn.ts	Uses the delivery lease to choose durable membership for foreground-spawned agents.
packages/core/src/provision.ts	Updates the durable membership contract and grants provisioners read access to the delivery lease bucket.
implementations/cli/src/lib/connect.ts	Adds an offline target resolver for dry-run command paths.
package.json	Adds the provision-acl live smoke script to the CI smoke chain.
implementations/cli/src/index.ts	Registers the new provision-acl command.

_{Reviews (4): Last reviewed commit: "docs(cli): document the dry-run prune di..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7bd7574f84

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

implementations/cli/src/lib/acl-provision.ts (1)

30-38: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Triplicated business logic — drift risk despite the safety net.

agentReadAcl deliberately re-implements the allowSubscribe ?? subscribe + ["general"] fallback logic that already lives in mint.ts:84 and provision.ts:411 (per the comment). The runtime drift check mitigates silent divergence, but a shared helper in @cotal-ai/core would remove the need to keep three call sites "in lockstep" by convention/comment alone.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@implementations/cli/src/lib/acl-provision.ts` around lines 30 - 38, The ACL
selection logic in agentReadAcl is duplicated and should be centralized to avoid
drift across mint and provision paths. Move the shared allowSubscribe ??
subscribe plus ["general"] fallback into a reusable helper in `@cotal-ai/core`,
then have agentReadAcl and the existing mint/provision call sites use that
helper instead of re-implementing the same logic. Keep the helper aligned with
the current semantics of allowSubscribe, subscribe, and empty-list handling.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@implementations/cli/src/commands/provision-acl.ts`:
- Around line 24-31: The CLI flag handling in provision-acl parsing is missing
support for --mint-missing, causing parseArgs to reject a documented option.
Update the options map in the parseArgs call inside provision-acl.ts to include
mint-missing (or remove the flag from the CLI registration/help in index.ts if
it is not meant to be supported), and make sure the existing command flow in
provision-acl uses the new parsed value consistently if needed.

In `@implementations/cli/src/index.ts`:
- Around line 151-158: The `provision-acl` command help text is advertising the
unimplemented `--mint-missing` flag, which causes `parseArgs` to reject it with
a crash. Update the command definition in `index.ts` so the `summary` for
`provisionAcl` no longer mentions `--mint-missing`, and keep the documented
options aligned with what `provision-acl.ts` actually supports (`--dry-run` and
`--space` only).

In `@implementations/cli/src/lib/acl-provision.ts`:
- Around line 67-94: `planAclProvision()` currently lets `idFromCreds(creds)`
and `credChatSubAllow(creds, space)` throw, which aborts the whole ACL plan on
one bad `.creds` file. Add per-persona error handling in the same loop that
already handles `p.error`: catch failures around reading/parsing creds, then
push an entry for that persona with `hasCreds` false or an `error` field and
continue to the next persona. Keep the existing `planAclProvision`,
`idFromCreds`, and `credChatSubAllow` flow intact, but make malformed creds a
skipped persona instead of a fatal error.

---

Nitpick comments:
In `@implementations/cli/src/lib/acl-provision.ts`:
- Around line 30-38: The ACL selection logic in agentReadAcl is duplicated and
should be centralized to avoid drift across mint and provision paths. Move the
shared allowSubscribe ?? subscribe plus ["general"] fallback into a reusable
helper in `@cotal-ai/core`, then have agentReadAcl and the existing mint/provision
call sites use that helper instead of re-implementing the same logic. Keep the
helper aligned with the current semantics of allowSubscribe, subscribe, and
empty-list handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 97c9a916-aa2e-49a6-b2f9-845b2e6904ab

📥 Commits

Reviewing files that changed from the base of the PR and between 4b0553c and 7bd7574.

📒 Files selected for processing (7)

• implementations/cli/smoke/provision-acl-live.smoke.ts
• implementations/cli/src/commands/provision-acl.ts
• implementations/cli/src/commands/spawn.ts
• implementations/cli/src/index.ts
• implementations/cli/src/lib/acl-provision.ts
• package.json
• packages/core/src/provision.ts

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Heads up: you’re close to your included review allowance. Set a flex budget so reviews don’t pause.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

_{Heads up: you’re close to your included review allowance. Set a flex budget so reviews don’t pause.}

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>