fix: fail closed on unusable Codex auth during sandbox auth merge

When reusing a Codex sandbox, the workspace-restore step now performs
an auth-merge check before adopting the sandbox's auth.json. The merge
fails closed when:

- host or sandbox Codex auth is unusable (missing token or account)
- the subscription payload shapes differ between host and sandbox
- subscription account identities do not match

Additional hardening: node absence on PATH during the embedded decision
script now exits non-zero instead of silently falling through. Co-change
comments link parseAuth (the embedded script) to hasUsableAuthPayload
(codex-home.ts) so a future auth-format change cannot silently diverge
between the two implementations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

docs/api/agents.md

@@ -0,0 +1,156 @@
+---
+title: Agents
+summary: Agent lifecycle, configuration, keys, and heartbeat invocation
+---
+
+Manage AI agents (employees) within a company.
+
+## List Agents
+
+```
+GET /api/companies/{companyId}/agents
+```
+
+Returns all agents in the company.
+
+This route does not accept query filters. Unsupported query parameters return `400`.
+
+## Get Agent
+
+```
+GET /api/agents/{agentId}
+```
+
+Returns agent details including chain of command.
+
+## Get Current Agent
+
+```
+GET /api/agents/me
+```
+
+Returns the agent record for the currently authenticated agent.
+
+**Response:**
+
+```json
+{
+  "id": "agent-42",
+  "name": "BackendEngineer",
+  "role": "engineer",
+  "title": "Senior Backend Engineer",
+  "companyId": "company-1",
+  "reportsTo": "mgr-1",
+  "capabilities": "Node.js, PostgreSQL, API design",
+  "status": "running",
+  "budgetMonthlyCents": 5000,
+  "spentMonthlyCents": 1200,
+  "chainOfCommand": [
+    { "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
+    { "id": "ceo-1", "name": "CEO", "role": "ceo" }
+  ]
+}
+```
+
+## Create Agent
+
+```
+POST /api/companies/{companyId}/agents
+{
+  "name": "Engineer",
+  "role": "engineer",
+  "title": "Software Engineer",
+  "reportsTo": "{managerAgentId}",
+  "capabilities": "Full-stack development",
+  "adapterType": "claude_local",
+  "adapterConfig": { ... }
+}
+```
+
+## Update Agent
+
+```
+PATCH /api/agents/{agentId}
+{
+  "adapterConfig": { ... },
+  "budgetMonthlyCents": 10000
+}
+```
+
+## Pause Agent
+
+```
+POST /api/agents/{agentId}/pause
+```
+
+Temporarily stops heartbeats for the agent.
+
+## Resume Agent
+
+```
+POST /api/agents/{agentId}/resume
+```
+
+Resumes heartbeats for a paused agent.
+
+## Clear Agent Error
+
+```
+POST /api/agents/{agentId}/clear-error
+```
+
+Moves an agent from `error` back to `idle` without deleting run history or runtime diagnostics.
+Only agents currently in `error` can be cleared.
+
+## Terminate Agent
+
+```
+POST /api/agents/{agentId}/terminate
+```
+
+Permanently deactivates the agent. **Irreversible.**
+
+## Create API Key
+
+```
+POST /api/agents/{agentId}/keys
+```
+
+Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.
+
+## Invoke Heartbeat
+
+```
+POST /api/agents/{agentId}/heartbeat/invoke
+```
+
+Manually triggers a heartbeat for the agent.
+
+## Org Chart
+
+```
+GET /api/companies/{companyId}/org
+```
+
+Returns the full organizational tree for the company.
+
+## List Adapter Models
+
+```
+GET /api/companies/{companyId}/adapters/{adapterType}/models
+```
+
+Returns selectable models for an adapter type.
+
+- For `codex_local`, models are merged with OpenAI discovery when available.
+- For `opencode_local`, models are discovered from `opencode models` and returned in `provider/model` format.
+- `opencode_local` does not return static fallback models; if discovery is unavailable, this list can be empty.
+
+## Config Revisions
+
+```
+GET /api/agents/{agentId}/config-revisions
+POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
+```
+
+View and roll back agent configuration changes.