Cloud publishes commands: registry, manifest and run routes, sidebar tools#1677

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: b17a7508-6a87-4569-a19e-fb7c971454f5

📥 Commits

Reviewing files that changed from the base of the PR and between 341f0d3f3ff5018251f963542b56f0ecf1337fab and bf5608e364f790af73ce79a4dd359b0e93714b4a.

📒 Files selected for processing (33)

• core/DESIGN.md
• core/crates/ployz/tests/fixtures/published-manifest.json
• dashboard/CONTEXT.md
• dashboard/DESIGN.md
• dashboard/package.json
• dashboard/src/components/agent-sidebar/approval-card.tsx
• dashboard/src/components/agent-sidebar/approval-review.ts
• dashboard/src/modules/agent/agent-chat.server.ts
• dashboard/src/modules/agent/agent-tools.test.ts
• dashboard/src/modules/agent/agent-tools.ts
• dashboard/src/modules/approvals/approvals.commands.server.ts
• dashboard/src/modules/approvals/approvals.ts
• dashboard/src/modules/commands/command.server.ts
• dashboard/src/modules/commands/commands.server.ts
• dashboard/src/modules/commands/manifest.test.ts
• dashboard/src/modules/commands/parity.postgres.test.ts
• dashboard/src/modules/commands/registry.server.ts
• dashboard/src/modules/config-store/config-store.server.ts
• dashboard/src/modules/server-upgrade/server-upgrade.commands.server.ts
• dashboard/src/modules/server-upgrade/server-upgrade.functions.ts
• dashboard/src/modules/server-upgrade/server-upgrade.inngest.postgres.test.ts
• dashboard/src/modules/server-upgrade/server-upgrade.server.ts
• dashboard/src/modules/server-upgrade/server-upgrade.ts
• dashboard/src/routeTree.gen.ts
• dashboard/src/routes/api/cli/$.ts
• dashboard/src/routes/api/cli/-handlers.ts
• dashboard/src/routes/api/cli/agent/act.ts
• dashboard/src/routes/api/cli/agent/ask.ts
• dashboard/src/routes/api/cli/cloud/reset.ts
• dashboard/src/routes/api/cli/manifest.ts
• dashboard/src/routes/api/cli/run/$name.ts
• dashboard/src/routes/api/cli/servers/enroll.ts
• dashboard/src/routes/api/cli/servers/enrollment.ts

💤 Files with no reviewable changes (1)

• dashboard/src/components/agent-sidebar/approval-review.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

Summary by CodeRabbit

• New Features
  • Added CLI commands to list, view, approve, and deny pending organization approvals, with optional denial reasons.
  • Destructive Publish, Deploy, Server removal, Drain, and Namespace clean actions now require approval, including actions initiated through the Agent sidebar.
  • Added commands to view and update server upgrade channels and automatic-upgrade settings.
  • Cloud-published commands can now appear in the CLI and Agent sidebar when enabled for agents.

Walkthrough

The change adds a registry of Cloud-published commands for server upgrade policies and organization approvals. It serves a command manifest and named command execution through CLI routes, and exposes agent-enabled commands through the Agent sidebar.

Changes

Published command operations

Layer / File(s)	Summary
Command definitions and domain operations dashboard/src/modules/commands/command.server.ts, dashboard/src/modules/commands/registry.server.ts, dashboard/src/modules/server-upgrade/*, dashboard/src/modules/approvals/*, dashboard/src/components/agent-sidebar/approval-*, dashboard/CONTEXT.md	Adds command input validation, write gating, and refusal handling. Adds commands to read and update server-upgrade settings and to list, show, approve, or deny organization approvals. The settings update accepts either or both optional fields. Approval descriptions are formatted in the approvals module.

CLI publication and execution

Layer / File(s)	Summary
Manifest generation and CLI routes dashboard/src/modules/commands/commands.server.ts, core/crates/ployz/tests/fixtures/published-manifest.json, dashboard/src/routes/api/cli/-handlers.ts, dashboard/src/routes/api/cli/manifest.ts, dashboard/src/routes/api/cli/run/$name.ts, dashboard/src/routeTree.gen.ts, dashboard/src/modules/config-store/config-store.server.ts, dashboard/src/routes/api/cli/*	Generates a revisioned command manifest and adds routes to serve it and run named commands. The run handler passes the caller, input, approval ID, and request key to command execution. CLI routes use the shared response handler, which adds the manifest revision header. unknown_command maps to HTTP 422.

Agent command access and validation

Layer / File(s)	Summary
Agent integration and parity checks dashboard/src/modules/agent/*, dashboard/src/modules/commands/manifest.test.ts, dashboard/src/modules/commands/parity.postgres.test.ts, dashboard/src/modules/agent/agent-tools.test.ts, dashboard/DESIGN.md, core/DESIGN.md, dashboard/package.json	Adds agent-enabled published commands to the Agent sidebar and includes gated commands in the gate set. Tests compare the manifest with the fixture, check route/sidebar results and state changes, and verify gated approval commands are unavailable to agents.

Priority: ➖ Normal

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

Change: Feature

Sequence Diagram(s)

mermaid

1	sequenceDiagram
2	participant ployz
3	participant ManifestRoute as Manifest route
4	participant CommandRegistry
5	participant RunRoute as Run route
6	participant runCommand
7	participant PublishedCommand
8	ployz->>ManifestRoute: Request command manifest
9	ManifestRoute->>CommandRegistry: Read registered commands
10	CommandRegistry-->>ManifestRoute: Command metadata and schemas
11	ManifestRoute-->>ployz: Manifest and revision header
12	ployz->>RunRoute: Submit command name and input
13	RunRoute->>runCommand: Pass caller, input, approval ID, and key
14	runCommand->>PublishedCommand: Invoke matching command
15	PublishedCommand-->>runCommand: Return command result
16	runCommand-->>RunRoute: Return output or refusal
17	RunRoute-->>ployz: Return command response

No actionable merge-blocking issue is established for the published commands or their CLI and Agent paths; normal checks can proceed.

The new execution paths retain authentication and organization scoping. Approval decisions remain protected against stale plans and concurrent decisions, and approval-management commands are excluded from sidebar tools. No authorization bypass was established in the inspected paths, but client confirmation and broader runtime coverage remain incomplete.

Retained concerns No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A compromised valid organization credential or influenced sidebar tool execution can affect the bound organization's upgrade policy, including its release channel and automatic rollout behavior across eligible servers. Approval decisions can release destructive operations in that organization. The inspected commands expose no caller-controlled organization selector or demonstrated cross-organization escalation.

Security Findings and Attack Paths

• observed — The new approval command accepts an approval ID and obtains its digest server-side; typed organization confirmation is manifest metadata rather than server-enforced input. Freshening rejects superseded plans. The base already exposed credential-authorized approval decisions, and the documented boundary explicitly does not resist hostile credential holders. Client confirmation behavior remains unverified rather than a demonstrated new authorization bypass.

Trust Boundaries and Controls

• observed — CLI callers require an unexpired organization token whose maker remains a member, or a session with verified active-organization membership. Sidebar requests use dashboard operate authorization and member/organization thread scoping. Approval reads are organization-scoped; decisions freshen pending plans and conditionally update pending rows, with repeated matching decisions returning the settled result.

Resilience and Maintainability Implications

• observed — Published request keys do not provide recorded replay admission. Retrying automatic-policy writes can emit additional events, and persistence precedes event delivery; this separation existed at base. Rollouts serialize per organization, select servers still behind, skip halted releases and stop on unsuccessful outcomes. Failure, cancellation and stale-attempt cleanup record unknown outcomes, while the periodic sweep re-requests enabled automatic rollouts. These controls bound the retry concern without proving exactly-once delivery.

Hardening Proposals

• proposed — Keep caller-owned authorization and retry convergence explicit requirements for future registry additions. Operations that do not independently converge should use durable replay admission, and agent eligibility should be reviewed separately from ordinary member permission.

^Failed Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	Warning	Docstring coverage is 61.54% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 27 files. (5 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

^Passed Passed checks (4 passed)

Check name	Status	Explanation
Title check	Passed	The title clearly summarizes the main changes: Cloud command publication, the registry, manifest and run routes, and sidebar tools.
Description check	Passed	The description is directly related to the changeset and explains the published command manifest, run routes, shared registry, agent sidebar integration, and parity testing.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 61.54% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 27 files. (5 skipped: 5 unsupported.)

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.