@rosthq/cli 0.5.8 → 0.5.10

package/dist/index.js

@@ -41785,11 +41785,11 @@ Drafting can be assisted by agents. Activation is a human decision. When authori
     order: 40,
     title: "Agent staffing playbook",
     summary: "How to decide whether a seat should be human, agent, or hybrid, and how to go live safely.",
-    version: "2026-06-19.1",
+    version: "2026-06-19.2",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["staffing"],
-    relatedCommandIds: ["staffing.assign_user", "staffing.assign_agent_dry_run", "agent.go_live", "agent.status", "agent.run_now", "agent.list_runs", "agent.list_tool_calls", "mcp_token.create", "agent_template.list", "agent.create_from_template", "agent_setup.start", "agent_setup.get", "agent_setup.update", "agent.update_schedule", "agent.decommission", "agent.create_custom", "agent.configure_tools", "agent.run_dry_run", "confirmation.approve"],
+    relatedCommandIds: ["staffing.assign_user", "staffing.assign_agent_dry_run", "agent.go_live", "agent.status", "agent.run_now", "agent.get_run", "agent.list_runs", "agent.list_tool_calls", "mcp_token.create", "agent_template.list", "agent.create_from_template", "agent_setup.start", "agent_setup.get", "agent_setup.update", "agent.update_schedule", "agent.decommission", "agent.create_custom", "agent.configure_tools", "agent.run_dry_run", "confirmation.approve"],
     legal: {
       publicRisk: "low",
       notes: [
@@ -41844,7 +41844,7 @@ Two creation paths, both draft-first. Read the stock-agents guide for templates
 - Custom: \`agent_setup.start\` / \`rost_start_agent_setup\` (returns a \`setup_id\`), iterate with \`agent_setup.get\` and \`agent_setup.update\`, then \`agent.create_custom\` / \`rost_create_custom_agent\`. Stage tools with \`agent.configure_tools\` (vault refs only) and sandbox with \`agent.run_dry_run\`.
 - Inspect runtime: \`agent.status\` / \`rost_get_agent_status\` with \`{"seat_id":"<seat-id>"}\` returns lane, live state, steward chain, dry-run result, and Runner availability.
 - Run on demand: \`{{cli}} agent run-now --seat-id <seat-id>\` / \`agent.run_now\` / \`rost_run_agent_now\` queues an immediate live run without changing the saved schedule. Cloud agents dispatch to the Inngest executor; runner agents queue work for the paired runner. The command is ungated but still requires a live staffed agent and the normal server-side tool guard.
-- Audit what an agent did (Trust Card): \`{{cli}} command agent.list_runs --json '{"seat_id":"<seat-id>"}'\` / \`rost_list_agent_runs\` returns the seat's run history with per-run tool-call and guard-held counts; \`{{cli}} command agent.list_tool_calls --json '{"seat_id":"<seat-id>"}'\` / \`rost_list_agent_tool_calls\` returns the tool-call ledger with each call's guard result. Both include a \`denied_tool_call_count\` rollup \u2014 the actions held because they exceeded the charter. Pass \`{"seat_id":"<seat-id>","held_only":true}\` to \`agent.list_tool_calls\` for only the held calls. The web seat page shows the same facts as a Trust Card.
+- Audit what an agent did (Trust Card): \`{{cli}} command agent.list_runs --json '{"seat_id":"<seat-id>"}'\` / \`rost_list_agent_runs\` returns the seat's run history with per-run tool-call and guard-held counts; \`{{cli}} agent get-run --seat-id <seat-id> --run-id <run-id>\` / \`agent.get_run\` / \`rost_get_agent_run_diagnostics\` reads one run's transcript reference, token/cost usage, outcome, and product-visible run errors; \`{{cli}} command agent.list_tool_calls --json '{"seat_id":"<seat-id>"}'\` / \`rost_list_agent_tool_calls\` returns the tool-call ledger with each call's guard result. Both list commands include a \`denied_tool_call_count\` rollup \u2014 the actions held because they exceeded the charter. Pass \`{"seat_id":"<seat-id>","held_only":true}\` to \`agent.list_tool_calls\` for only the held calls. The web seat page shows the same facts as a Trust Card.
 
 ## When to stop for confirmation
 
@@ -42084,7 +42084,7 @@ Decisions should be recorded as human decisions. Handoffs should attach to seats
     order: 45,
     title: "How agents work",
     summary: "How {{brand}} agents operate inside seats, use Charters, report work, and escalate beyond authority.",
-    version: "2026-06-19.4",
+    version: "2026-06-20.1",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["staffing", "operating_rhythm"],
@@ -42167,18 +42167,20 @@ The model is only ever offered the tools the seat's manifest grants \u2014 a den
 3. The action runs bound to the seat's vaulted credential. The secret stays inside the call and never reaches the result, the audit row, the logs, or the model.
 4. Every call \u2014 allowed, denied, escalated, or invalid \u2014 writes a tool-call audit row you can review.
 
+Provider requests carry only the model payload the runtime needs; run attribution, tenant attribution, usage, and cost are recorded in {{brand}} audit tables after the call, not sent as custom provider metadata.
+
 Before an agent goes live, the sandbox dry run rehearses this against fake data and returns a per-tool preview: for each tool the agent would touch, whether it would run it, would be blocked, or would escalate \u2014 no external side effect. Review that preview before you approve go-live.
 
 ## What humans should review
 
-Review the first dry runs, fleet overview, tool-call audit rows, escalations, and Signal impact. The fleet view at \`/agents\` shows every staffed agent seat at a glance; the agent-native equivalent is \`{{cli}} command agent.list_fleet --json '{}'\` / \`rost_list_agent_fleet\`, which returns lane, live state, last real turn, 24h/7d real turns, top measurable status, open escalations, and 7-day spend. Sandbox dry runs do not count as real turns. If the agent is repeatedly blocked, revise the Charter or split the seat. If the agent is taking too much judgment, narrow its autonomous scope.`
+Review the first dry runs, fleet overview, tool-call audit rows, escalations, and Signal impact. The fleet view at \`/agents\` shows every staffed agent seat at a glance; the agent-native equivalent is \`{{cli}} command agent.list_fleet --json '{}'\` / \`rost_list_agent_fleet\`, which returns lane, live state, last real turn, 24h/7d real turns, top measurable status, open escalations, and 7-day spend. Fleet real-turn counts use the same seat-run association as \`agent.list_runs\`, filtered to real runs. Scheduled agents are checked in rounded five-minute buckets, so a minute-level cron inside the bucket queues one work order for that bucket rather than one order per minute. Sandbox dry runs do not count as real turns. If the agent is repeatedly blocked, revise the Charter or split the seat. If the agent is taking too much judgment, narrow its autonomous scope.`
   },
   {
     slug: "tool-access-and-vault",
     order: 46,
     title: "Tool access and vault",
     summary: "How to give agents access to tools without exposing raw credentials or expanding authority by accident.",
-    version: "2026-06-19.2",
+    version: "2026-06-20.1",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["staffing"],
@@ -42222,6 +42224,10 @@ Connecting a tool is a human-controlled step. The agent can recommend a tool, ex
 
 For an API with no dedicated connector, the generic REST tool lets a seat call an HTTP endpoint with a credential you paste through the vault \u2014 no {{brand}}-owned app. It is escalate-by-default: the agent may only call a host a steward has signed onto the allowlist; any other host is refused and escalated, with no request made. The connector sets the Authorization header from the vaulted credential itself \u2014 the agent never sees the token, and the secret is redacted from the response before it reaches the agent, the audit row, or the logs. The token is only ever sent over HTTPS, only to the signed host, and a redirect is never followed \u2014 so an allowlisted endpoint cannot bounce the call (and the token) to another host. A sandbox dry run of a REST tool makes no real request.
 
+## Slack post connector
+
+\`slack.post_message\` reuses the connected Slack workspace credential and the seat's Slack channel binding. A live call posts only to that bound channel, through the server-side guard and vault-bound bot token. If the bound channel is marked sensitive, the handler escalates for human approval instead of posting. A sandbox dry run makes no Slack request and does not open the vault.
+
 ## One write-only credential flow across every surface
 
 There is exactly one way to give a connected tool its credential, and it is the same on every surface (agent setup, Charter Builder, CLI, MCP). Connecting a tool only authorizes the access \u2014 it never captures a secret. When a connected tool needs a credential, you stage a vault-backed *request* (provider, scope, and a credential name \u2014 all labels, never the secret). You then provide the actual secret separately through the vault-backed ingress flow from Settings. No {{brand}} surface ever has a field that accepts raw secret material, so a secret can never reach a prompt, log, event, or tool argument.
@@ -42250,7 +42256,7 @@ There is exactly one way to give a connected tool its credential, and it is the
     order: 47,
     title: "Available tools guide",
     summary: "How to think about tool categories available to seats and what each category should be used for.",
-    version: "2026-06-18.1",
+    version: "2026-06-20.1",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["staffing"],
@@ -42292,14 +42298,14 @@ Agents should explain the job, the required tool category, the minimum permissio
 
 Every tool call passes the server-side guard first: the guard checks the call against the seat's signed permission manifest and records a tool-call audit row for **every** call \u2014 allowed, denied, or escalated. Tool selection is never authorization. Only an allowed call reaches its handler. A connected credential is bound into the handler for the duration of the call only; the secret never appears in the result, the audit summary, logs, or the model's context.
 
-External connectors (such as email, drive, or a generic API) are being rolled out provider by provider, conservatively (read and draft before send; write behind approval). Until a provider's connector is live, a tool you select is configuration only and has no external side effect \u2014 the guard and audit trail are already in force, so nothing runs silently.`
+External connectors are being rolled out provider by provider, conservatively (read and draft before send; write behind approval). A selected tool is only a permission until a live handler exists and the seat has the required credential or binding. Today the built-in execution path supports internal status reporting, the generic REST connector when a signed allowlist and credential exist, and \`slack.post_message\` for a bound Slack channel. Other provider entries remain configuration-only until their connector ships, so nothing runs silently.`
   },
   {
     slug: "mcp-and-cli-guide",
     order: 48,
     title: "CLI and MCP installation guide",
     summary: "Install the public CLI, register remote token-backed MCP clients, and find the full command and tool catalog.",
-    version: "2026-06-19.3",
+    version: "2026-06-20.2",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["company_setup", "staffing"],
@@ -42335,6 +42341,7 @@ External connectors (such as email, drive, or a generic API) are being rolled ou
       "agent.go_live",
       "agent.status",
       "agent.list_fleet",
+      "agent.get_run",
       "agent.list_runs",
       "agent.list_tool_calls"
     ],
@@ -42709,11 +42716,11 @@ These ergonomic wrappers (including the \`{{cli}} agent\` group) require **{{cli
 | \`{{cli}} escalation list|get|resolve|reject\` | \`escalation.list\`, \`escalation.get\`, \`escalation.resolve\`, \`escalation.reject\` | Work the steward escalation queue. | Steward | \`{{cli}} escalation list --json\` |
 | \`{{cli}} sync brief|compile|complete\` | \`sync.brief.get\`, \`sync.brief.compile\`, \`sync.run.complete\` | Compile, read, and complete a weekly Sync. | Tenant | \`{{cli}} sync brief --json\` |
 | \`{{cli}} runner list|status|work-orders|revoke\` | \`runner.list\`, \`runner.status\`, \`work_order.list\`, \`runner.revoke\` | Inspect runners and work orders; revoke a runner. | Tenant | \`{{cli}} runner list --json\` |
-| \`{{cli}} notification settings|test\` | \`notification.settings.get\`, \`notification.test\` | Read notification settings; send a test. | Tenant | \`{{cli}} notification settings --json\` |
+| \`{{cli}} notification settings|test|errors\` | \`notification.settings.get\`, \`notification.test\`, \`notification.list_errors\` | Read notification settings, send a test, and list failed deliveries with linked product error source, seat id, and run id when available. | Tenant | \`{{cli}} notification errors --limit 10 --json\` |
 | \`{{cli}} settings get|update\` | \`settings.get\`, \`settings.update\` | Read tenant settings; update budget caps. | Tenant | \`{{cli}} settings get --json\` |
 | \`{{cli}} member invite|update|remove\` | \`member.invite\`, \`member.update\`, \`member.remove\` | Manage tenant members. | Tenant | \`{{cli}} member invite --email ops@example.com --role member\` |
-| \`{{cli}} agent templates|create|setup|tools|dry-run|go-live|status|run-now|show\` | \`agent_template.list\`, \`agent.create_from_template\`, \`agent.create_custom\`, \`agent_setup.get\`, \`agent_setup.update\`, \`agent.configure_tools\`, \`agent.run_dry_run\`, \`agent.go_live\`, \`agent.status\`, \`agent.run_now\`, \`agent.show_markdown\` | Run the full agent setup and operation flow: list templates, create a draft from a template or guided custom answers (with \`--model\` and \`--effort\`), read or answer setup state, connect or decline tools, dry-run, go live, run on demand, and show a markdown readout. Create and go-live stop at human gates; the dry-run is ungated by human approval but requires a signed manifest first. | Tenant and seat | \`{{cli}} agent templates --json\` |
-| \`{{cli}} tools list\` | \`tool.catalog\` | List the discoverable tool catalog the builder reads (id, scope tiers, credential requirement, access policy). Configuration only; the tools do not execute yet. | Tenant | \`{{cli}} tools list --json\` |
+| \`{{cli}} agent templates|create|setup|tools|dry-run|go-live|status|run-now|get-run|show\` | \`agent_template.list\`, \`agent.create_from_template\`, \`agent.create_custom\`, \`agent_setup.get\`, \`agent_setup.update\`, \`agent.configure_tools\`, \`agent.run_dry_run\`, \`agent.go_live\`, \`agent.status\`, \`agent.run_now\`, \`agent.get_run\`, \`agent.show_markdown\` | Run the full agent setup and operation flow: list templates, create a draft from a template or guided custom answers (with \`--model\` and \`--effort\`), read or answer setup state, connect or decline tools, dry-run, go live, run on demand, read one run's transcript/error diagnostics, and show a markdown readout. Create and go-live stop at human gates; the dry-run is ungated by human approval but requires a signed manifest first. | Tenant and seat | \`{{cli}} agent get-run --seat-id <seat-id> --run-id <run-id> --json\` |
+| \`{{cli}} tools list\` | \`tool.catalog\` | List the discoverable tool catalog the builder reads (id, scope tiers, credential requirement, access policy, and execution-boundary guidance). | Tenant | \`{{cli}} tools list --json\` |
 | \`{{cli}} compass show\` | \`compass.show_markdown\` | Render the current Compass as a clean markdown card for review. | Tenant | \`{{cli}} compass show --markdown\` |
 | \`{{cli}} charter show\` | \`charter.show_markdown\` | Render a seat's Charter as a clean markdown card for review. | Tenant | \`{{cli}} charter show --seat-id <id> --markdown\` |
 
@@ -42735,7 +42742,7 @@ These ergonomic wrappers (including the \`{{cli}} agent\` group) require **{{cli
 This catalog is the canonical machine surface \u2014 the \`rost_*\` tools your MCP client calls. Three different things are called "tools" in {{brand}}; do not confuse them:
 
 1. **The MCP tools below** \u2014 the \`rost_*\` surface your client actually calls to read and act.
-2. **\`{{cli}} tools list\` / \`tool.catalog\`** (MCP \`rost_list_tool_catalog\`) \u2014 the agent-configuration catalog the builder reads when staffing an agent. It is selectable per agent and **does not execute yet**; it is not the surface you call to operate.
+2. **\`{{cli}} tools list\` / \`tool.catalog\`** (MCP \`rost_list_tool_catalog\`) \u2014 the agent-configuration catalog the builder reads when staffing an agent. It is selectable per agent, but selecting a tool is not itself a call; live handlers execute later only behind the signed manifest, guard, credentials, and bindings.
 3. **The "Available tools guide"** (in the sidebar) \u2014 covers tool *categories* and governance, not a callable surface. See the available-tools-guide.
 
 Sections below: Command discovery (2) \xB7 Public reference (3) \xB7 Tenant-admin tools (grouped by domain) \xB7 Seat-scoped operating tools (9) \xB7 MCP operation resources (9).
@@ -42809,9 +42816,10 @@ Several rows here are seat-operating commands (\`task.create\`, the \`signal.*\`
 | \`rost_get_current_compass\` | \`compass.get_current\` | Read the active and draft Compass versions and source documents. | Tenant | Call with \`{}\`. |
 | \`rost_list_compass_gaps\` | \`compass.list_gaps\` | List unanswered and answered Compass context gaps. | Tenant | Call with \`{}\` before answering gaps. |
 | \`rost_get_agent_status\` | \`agent.status\` | Read agent lane, live state, steward chain, dry-run result, Runner availability. | Seat or tenant-admin | Call with \`{"seat_id":"<seat-id>"}\`. |
-| \`rost_list_agent_fleet\` | \`agent.list_fleet\` | Read every staffed agent seat at once: lane, live state, last real turn, 24h/7d real turns, measurable status, escalations, and 7-day spend. | Tenant | Call with \`{}\`; sandbox dry runs are excluded from real turns. |
+| \`rost_list_agent_fleet\` | \`agent.list_fleet\` | Read every staffed agent seat at once: lane, live state, last real turn, 24h/7d real turns, measurable status, escalations, and 7-day spend. | Tenant | Call with \`{}\`; counts use the same seat-run association as \`agent.list_runs\`, with sandbox dry runs excluded from real turns. |
 | \`rost_run_agent_now\` | \`agent.run_now\` | Queue an immediate run for a live staffed agent without changing its saved schedule; cloud lane dispatches to the executor and runner lane queues for the paired runner. | Tenant | Call with \`{"seat_id":"<seat-id>"}\`. |
 | \`rost_list_agent_runs\` | \`agent.list_runs\` | Read a seat's agent run history (status, lane, model, cost, per-run tool-call and guard-held counts) plus the seat's run/tool-call rollup including held-action count. | Seat or tenant-admin | Call with \`{"seat_id":"<seat-id>"}\`; pass \`limit\` for a deeper window. |
+| \`rost_get_agent_run_diagnostics\` | \`agent.get_run\` | Read one run's diagnostic record: transcript reference, token/cost usage, outcome, and linked product-visible run errors. | Seat or tenant-admin | Call with \`{"seat_id":"<seat-id>","run_id":"<run-id>"}\`. |
 | \`rost_list_agent_tool_calls\` | \`agent.list_tool_calls\` | Read a seat's tool-call ledger (tool name, guard result, manifest clause, outcome) with the held-action count as the hero metric. Never returns argument summaries or secret material. | Seat or tenant-admin | Call with \`{"seat_id":"<seat-id>"}\`; pass \`held_only: true\` for only guard-held calls. |
 | \`rost_list_agent_templates\` | \`agent_template.list\` | List stock agent templates and metadata. | Tenant | Call with \`{}\`. |
 | \`rost_create_agent_from_template\` | \`agent.create_from_template\` | Create a draft stock agent and draft Charter from a template (draft-only; occupancy needs a human steward). | Tenant | Call with \`seat_id\` and \`template_slug\`; expect human confirmation. |
@@ -42836,7 +42844,7 @@ Several rows here are seat-operating commands (\`task.create\`, the \`signal.*\`
 | \`rost_get_notification_settings\` | \`notification.settings.get\` | Read tenant notification preferences. | Tenant | Call with \`{}\`. |
 | \`rost_update_notification_settings\` | \`notification.settings.update\` | Update tenant notification preferences. | Tenant | Call with the fields to change. |
 | \`rost_send_test_notification\` | \`notification.test\` | Emit an in-app test notification to the acting human. | Tenant | Call with \`{}\`. |
-| \`rost_list_notification_errors\` | \`notification.list_errors\` | List recent failed notification deliveries. | Tenant | Call with optional \`limit\`. |
+| \`rost_list_notification_errors\` | \`notification.list_errors\` | List recent failed notification deliveries with linked \`error_log_id\`, source, seat id, and run id when available. | Tenant | Call with optional \`limit\`; \`source=run\` rows can be followed with \`agent.get_run\`. |
 | \`rost_invite_member\` | \`member.invite\` | Create a pending tenant invite for a human teammate. | Tenant | Call with \`email\` and \`role\`. |
 | \`rost_update_member_role\` | \`member.update\` | Change a tenant member's role. | Tenant | Call with \`member_id\` and \`role\`; expect human confirmation. |
 | \`rost_remove_member\` | \`member.remove\` | Remove a tenant member. | Tenant | Call with \`member_id\`; blocked if it would orphan an agent steward chain. |
@@ -42870,7 +42878,7 @@ Several rows here are seat-operating commands (\`task.create\`, the \`signal.*\`
 | \`rost_show_compass_as_markdown\` | \`compass.show_markdown\` | Render the current Compass and its open gaps as a clean markdown card for review. | Tenant | Call with \`{}\`. |
 | \`rost_show_charter_as_markdown\` | \`charter.show_markdown\` | Render a seat's active or latest Charter as a clean markdown card for review. | Tenant | Call with \`{"seat_id":"<seat-id>"}\`. |
 | \`rost_show_agent_setup_as_markdown\` | \`agent.show_markdown\` | Render a seat's agent setup, model, steward, tools, and Charter as a clean markdown card for review. | Tenant | Call with \`{"seat_id":"<seat-id>"}\`. |
-| \`rost_list_tool_catalog\` | \`tool.catalog\` | List the discoverable tool catalog the agent builder reads \u2014 id, prescriptive description, scope tiers, credential requirement, access policy. Configuration only; the tools do not execute yet. | Tenant | Call with \`{}\` or \`{"provider":"google"}\`. |
+| \`rost_list_tool_catalog\` | \`tool.catalog\` | List the discoverable tool catalog the agent builder reads \u2014 id, prescriptive description, scope tiers, credential requirement, access policy, and execution-boundary guidance. | Tenant | Call with \`{}\` or \`{"provider":"google"}\`. |
 
 ### Seat-scoped operating tools
 
@@ -42928,7 +42936,7 @@ These rows are quick, at-a-glance triage. For deeper auth, tenant, scope, confir
     order: 49,
     title: "Agent reference map",
     summary: "Where CLI sessions, MCP clients, and in-app agents should retrieve {{brand}} guidance before recommending setup changes.",
-    version: "2026-06-18.1",
+    version: "2026-06-20.1",
     public: true,
     audiences: ["cli", "mcp", "in_app_agent"],
     stages: ["company_setup", "graph_design", "charter_design", "staffing", "operating_rhythm"],
@@ -42978,7 +42986,7 @@ Never guess a command's JSON shape. Before calling a command that changes state,
 
 - List every callable command: {{cli}} command list (CLI) or rost_list_commands (MCP)
 - Read one command's exact input/output schema, help pointer, and a worked example: {{cli}} command schema <id> (CLI) or rost_describe_command with {"command_id":"<id>"} (MCP)
-- List the tool catalog the agent builder reads (id, scope tiers, credential requirement, access policy \u2014 configuration only; the tools do not execute yet): {{cli}} tools list (CLI) or rost_list_tool_catalog (MCP)
+- List the tool catalog the agent builder reads (id, scope tiers, credential requirement, access policy, and execution-boundary guidance): {{cli}} tools list (CLI) or rost_list_tool_catalog (MCP)
 - Show a Compass, Charter, or agent setup as a markdown card to review with your human: {{cli}} compass show --markdown, {{cli}} charter show --seat-id <id> --markdown, {{cli}} agent show --seat-id <id> --markdown
 
 When a command fails, the error returns a machine-readable code, a message, and a help field naming the exact command to run next. Read the help field and run the command it points at \u2014 do not retry the same call blindly. A failed precondition (for example a manifest not yet signed, a dry run that has not passed, or the inference budget hard cap reached) returns COMMAND_PRECONDITION_FAILED with a help pointer, not an opaque internal error.
@@ -43021,7 +43029,7 @@ Read the listed guide before recommending or running each workflow. Every workfl
 - Add an agent through the app (graph or sidebar, visual journey): add-agents-guide.
 - Create an agent from a template: stock-agents-guide, then how-agents-work.
 - Create a custom agent (operational answers, Charter Builder, configure tools, dry run, go live): custom-agents-guide, then agent-staffing-playbook and tool-access-and-vault.
-- Build a controlled agent worker directly on the CLI/MCP path (seat, steward, job, boundaries, tools, credentials, model, schedule, dry-run, go-live): agent-builder-guide \u2014 it shows the full setup sequence, the structured model config, the access tiers, and how to discover tools (tool.catalog) and show your human a markdown readout (agent.show_markdown). The tool catalog is configuration the builder reads; the tools do not execute yet.
+- Build a controlled agent worker directly on the CLI/MCP path (seat, steward, job, boundaries, tools, credentials, model, schedule, dry-run, go-live): agent-builder-guide \u2014 it shows the full setup sequence, the structured model config, the access tiers, how to discover tools (tool.catalog), which connector entries have live execution boundaries, and how to show your human a markdown readout (agent.show_markdown).
 - Connect an existing or local agent to a seat: stock-agents-guide (connect section), then mcp-and-cli-guide and runner-guide.
 - Run the operating loop as a seat (context, tasks, status, escalate): how-agents-work.
 - Track goals: cascade-guide. Track measurables: signal-guide. File and resolve issues, tasks, escalations: friction-guide.
@@ -43453,7 +43461,7 @@ When a user asks to add a person, clarify whether they mean app access, seat occ
     order: 74,
     title: "Notifications guide",
     summary: "How {{brand}} should notify humans about decisions, escalations, stale work, and agent boundaries.",
-    version: "2026-06-13.1",
+    version: "2026-06-19.1",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["operating_rhythm"],
@@ -43478,6 +43486,10 @@ Notifications should move decisions to the right human without turning {{brand}}
 - A Friction item needs a decision.
 - A Sync decision creates a handoff.
 
+## Diagnose failed deliveries
+
+\`{{cli}} notification errors --limit 10\` / \`notification.list_errors\` / \`rost_list_notification_errors\` returns recent failed deliveries. When a failed notification links to a product error, it includes \`error_log_id\`, \`source\`, and any linked \`seat_id\` / \`run_id\`; \`source=run\` means the notification is tied to an agent run and can be followed with \`agent.get_run\` for the transcript reference and run errors.
+
 ## Keep notifications useful
 
 Every notification should include the seat, cause, evidence, and requested decision. Avoid status-only messages when no action is needed.`
@@ -44055,7 +44067,7 @@ This worked document **omits** \`unanswered_boundaries\` and \`seat_type_recomme
     order: 43,
     title: "Agent builder guide",
     summary: "The full agent setup sequence on the CLI/MCP path \u2014 seat, steward, job, boundaries, tools, credentials, model, schedule, dry-run, go-live \u2014 with the structured model config and access tiers.",
-    version: "2026-06-16.1",
+    version: "2026-06-20.1",
     public: true,
     audiences: ["cli", "mcp", "in_app_agent"],
     stages: ["staffing"],
@@ -44101,7 +44113,7 @@ Building teams of controlled agent workers is the product's core differentiator.
 2. **Steward** \u2014 every agent needs a human steward chain (invariant: no orphan agents). Set \`steward_seat_id\` so the chain resolves to a human; without it the occupancy is blocked.
 3. **Job** \u2014 what the seat owns. On \`agent.create_custom\` this is the operational answers (what it owns, what success looks like, what it must never do alone); for a strong contract, submit the full Charter directly via \`charter.update_draft\` (see the charter-authoring deep-dive).
 4. **Boundaries** \u2014 the Charter's \`decision_authority\` (can-do / must-ask / never / escalate), \`escalation_rules\`, and \`budget\`. Conservative by default: send/spend/irreversible actions are approval-gated or escalated.
-5. **Tools** \u2014 pick from the discoverable catalog (\`{{cli}} tools list\`); each tool has a default scope tier and access policy. Connect or decline via \`agent.configure_tools\`. **The catalog is configuration the builder reads \u2014 the tools do not execute yet** (real tool execution is a separate, deferred capability).
+5. **Tools** \u2014 pick from the discoverable catalog (\`{{cli}} tools list\`); each tool has a default scope tier and access policy. Connect or decline via \`agent.configure_tools\`. Selecting a tool records permission; live handlers execute later only behind the signed manifest, server guard, required credential or binding, and connector-specific approval boundary.
 6. **Credentials** \u2014 a tool that needs access declares a credential-ingress request (provider, scope, secret name). The secret itself flows through the vault-backed ingress command as a vault ref \u2014 never paste a secret into a builder command.
 7. **Operating instructions** \u2014 the runtime composes the agent's context from its Charter; you do not write a system prompt.
 8. **Model** \u2014 select the structured model config (see below).
@@ -45004,6 +45016,17 @@ function optionalValue(parsed, key) {
   const value = parsed.values.get(key);
   return value === void 0 || value.length === 0 ? void 0 : value;
 }
+function optionalNumber(parsed, key) {
+  const raw = optionalValue(parsed, key);
+  if (raw === void 0) {
+    return void 0;
+  }
+  const parsedNumber = Number(raw);
+  if (!Number.isSafeInteger(parsedNumber)) {
+    throw new UsageError(`--${key} must be an integer.`);
+  }
+  return parsedNumber;
+}
 function parseNumber(parsed, key, options) {
   const raw = parsed.values.get(key);
   if (raw === void 0 || raw.length === 0) {
@@ -45606,12 +45629,27 @@ var notificationWrapper = (context, args) => dispatch(context, "notification", a
       const record2 = asRecord(output);
       return `Test notification ${field(record2, "notification_id")} (delivered=${field(record2, "delivered")}).`;
     });
+  },
+  errors: (ctx, rest) => {
+    const parsed = parseFlags(rest);
+    const body = withOptional({}, { limit: optionalNumber(parsed, "limit") });
+    return execute(ctx, parsed, "notification.list_errors", body, (output) => {
+      const errors = asArray(asRecord(output).errors);
+      if (errors.length === 0) {
+        return "No failed notification deliveries.";
+      }
+      return errors.map((entry) => {
+        const record2 = asRecord(entry);
+        return `${field(record2, "created_at")}  ${field(record2, "channel")}  source=${field(record2, "source")}  seat=${field(record2, "seat_id")}  run=${field(record2, "run_id")}  ${field(record2, "error_message")}`;
+      }).join("\n");
+    });
   }
 }, notificationUsage(context.binName));
 function notificationUsage(bin) {
-  return `Usage: ${bin} notification settings|test [--json]
+  return `Usage: ${bin} notification settings|test|errors [--json]
   ${bin} notification settings
-  ${bin} notification test`;
+  ${bin} notification test
+  ${bin} notification errors [--limit <n>]`;
 }
 var settingsWrapper = (context, args) => dispatch(context, "settings", args, {
   get: (ctx, rest) => {
@@ -45812,6 +45850,21 @@ ${field(record2, "summary")}`;
       return `queued ${field(workOrder, "lane")} work order ${field(workOrder, "id")} for agent ${field(workOrder, "agent_id")} (${field(workOrder, "status")})`;
     });
   },
+  "get-run": (ctx, rest) => {
+    const parsed = parseFlags(rest);
+    const body = {
+      seat_id: requireValue2(parsed, "seat-id"),
+      run_id: requireValue2(parsed, "run-id")
+    };
+    return execute(ctx, parsed, "agent.get_run", body, (output) => {
+      const run2 = asRecord(asRecord(output).run);
+      const errors = asArray(run2.error_logs);
+      const errorLine = errors.length === 0 ? "errors=0" : `errors=${errors.length} first=${field(asRecord(errors[0]), "message")}`;
+      return `run ${field(run2, "run_id")}  status=${field(run2, "status")}  lane=${field(run2, "lane")}  cost=$${field(run2, "cost_usd")}
+transcript=${field(run2, "transcript_ref")}
+${errorLine}`;
+    });
+  },
   // DER-787 (H8): markdown readout for a seat's agent setup. `--markdown` (or
   // default) prints the composed card; `--json` returns the { markdown } object.
   show: (ctx, rest) => {
@@ -45838,7 +45891,7 @@ function agentConfigureTools(ctx, rest, decision) {
   });
 }
 function agentUsage(bin) {
-  return `Usage: ${bin} agent templates|create|setup|tools|dry-run|go-live|status|run-now|show [--json]
+  return `Usage: ${bin} agent templates|create|setup|tools|dry-run|go-live|status|run-now|get-run|show [--json]
   ${bin} agent templates
   ${bin} agent create --seat-id <id> --template <slug> [--expected-version <v>]
   ${bin} agent create --seat-id <id> --custom [--steward-seat-id <id>] [--lane cloud|mcp_session|runner] [--model triage|balanced|complex|hardest|<id>] [--effort low|medium|high|xhigh|max] [--owns <text>] [--success <text>] [--never-alone <text>]
@@ -45849,6 +45902,7 @@ function agentUsage(bin) {
   ${bin} agent go-live --seat-id <id> --charter-version-id <id>
   ${bin} agent status --seat-id <id>
   ${bin} agent run-now --seat-id <id> [--task-id <id>]
+  ${bin} agent get-run --seat-id <id> --run-id <id>
   ${bin} agent show --seat-id <id> [--markdown]`;
 }
 function agentSetupUsage(bin) {
@@ -45889,7 +45943,7 @@ ${lines.join("\n")}`;
 }, toolsUsage(context.binName));
 function toolsUsage(bin) {
   return `Usage: ${bin} tools list [--provider <name>] [--json]
-  ${bin} tools list \u2014 the discoverable tool catalog the builder reads. Configuration only; the tools do not execute yet.`;
+  ${bin} tools list \u2014 the discoverable tool catalog the builder reads; live handlers execute only behind signed manifests, guards, credentials, and bindings.`;
 }
 var compassWrapper = (context, args) => dispatch(context, "compass", args, {
   show: (ctx, rest) => {
@@ -45987,10 +46041,10 @@ function operationUsageLines(bin) {
     `${bin} escalation list|get|resolve|reject`,
     `${bin} sync brief|compile|complete`,
     `${bin} runner list|status|work-orders|revoke`,
-    `${bin} notification settings|test`,
+    `${bin} notification settings|test|errors`,
     `${bin} settings get|update`,
     `${bin} member invite|update|remove`,
-    `${bin} agent templates|create|setup|tools|dry-run|go-live|status|run-now|show`,
+    `${bin} agent templates|create|setup|tools|dry-run|go-live|status|run-now|get-run|show`,
     `${bin} tools list`,
     `${bin} compass show`,
     `${bin} charter show`