# AetherDesk agent workflow spine

The workflow spine is the shared lane for humans and agents to discover, run, and prove repeatable system operations.

## Routes

- `GET /api/agent/workflows`
- `POST /api/agent/workflows/:id/run`
- `GET /api/agent/workflows/receipts`

## Included workflows

- `support_bundle`
- `package_smoke`
- `release_verify`
- `commercial_gate`
- `ai_pc_smoke`
- `windows_ai_health`
- `mcp_scbe_status`
- `system_access_hardening`

Every workflow is allowlisted. There is no arbitrary command text in this lane.

## Safety shape

- Read-only workflows may inspect status and verify package state.
- Artifact-write workflows may write AetherDesk receipts, support bundles, package manifests, or other product artifacts.
- Heavy or security-sensitive workflows require an exact confirmation phrase before execution.
- Every run writes a JSON receipt under `artifacts/aetherdesk_workflow_receipts/`.
- stdout/stderr tails are redacted for common token patterns before receipts are written.

## Smoke check

```powershell
npm run aetherdesk:agent-workflows:smoke
```

This starts a temporary local server, confirms the workflow manifest, runs the safe support-bundle workflow, and verifies the resulting workflow receipt appears in the receipt list.

Visual smoke for the workflow spine:

```powershell
npm run aetherdesk:agent-workflows:visual
```

This opens the real desktop shell in Playwright, opens Workflow Library, verifies the support/release workflow cards are visible, runs the support-bundle workflow from the UI, and saves a screenshot under `artifacts/aetherdesk_visual/`.

Note: `npm run aetherdesk:agent-workflows:visual` currently performs a fast UI/source-contract smoke, not a live browser screenshot, because Playwright live browser bootstrap hung in this Codex session. It still verifies Workflow Library recipes, run buttons, backend workflow calls, confirmation prompts, and evidence routing.

## Operations digest

Generate a consolidated agent handoff digest with:

```powershell
npm run aetherdesk:ops:digest
```

The digest writes JSON and Markdown under `artifacts/aetherdesk_ops_digest/`, including `latest.json` and `latest.md`. It summarizes release integrity, commercial gate receipts, workflow receipts, support bundles, System Access receipts, action-log tail, and next actions derived from the evidence.

Backend route:

```text
GET /api/agent/ops-digest
```

## Ops autopilot

Plan safe next operations from the latest digest:

```powershell
npm run aetherdesk:ops:autopilot
```

Default mode is plan-only. It refreshes the ops digest, chooses allowlisted safe maintenance steps, and writes receipts under `artifacts/aetherdesk_ops_autopilot/`.

To actually run the safe step catalog, use:

```powershell
npm run aetherdesk:ops:autopilot:run-safe
```

The safe catalog is limited to release verification, package smoke, support bundle, and digest refresh. It does not allow arbitrary shell, host-write PowerShell, or remote-write actions.

Backend route:

```text
GET /api/agent/ops-autopilot
```

## System catalog

Generate the authoritative local systems/workflows map with:

```powershell
npm run aetherdesk:system:catalog
```

The catalog writes JSON and Markdown under `artifacts/aetherdesk_system_catalog/`, including `latest.json` and `latest.md`. It maps workspace roots, workflow spine entries, package scripts, docs, artifact lanes, MCP hook hints, and recommended agent entrypoints.

Backend route:

```text
GET /api/agent/system-catalog
```

## Mission packet

Generate the one-file agent onboarding handoff with:

```powershell
npm run aetherdesk:mission:packet
```

The packet writes JSON, Markdown, and a plain text agent prompt under `artifacts/aetherdesk_mission_packets/`, including `latest.json`, `latest.md`, and `latest-agent-prompt.txt`. It bundles the system catalog, ops digest, ops autopilot, workflow list, entrypoint routes, safety invariants, and next actions.

Backend route:

```text
GET /api/agent/mission-packet
```

## AI PC scorecard

Generate the evidence-weighted readiness scorecard with:

```powershell
npm run aetherdesk:ai-pc:scorecard
```

The scorecard writes JSON and Markdown under `artifacts/aetherdesk_ai_pc_scorecard/`, including `latest.json` and `latest.md`. It scores workflow spine, operations memory, safety boundary, package/release, supportability, desktop UI contract, systems integration, and agent onboarding evidence.

Backend route:

```text
GET /api/agent/ai-pc-scorecard
```

## Agent bootstrap

Generate the canonical first-call packet for agents with:

```powershell
npm run aetherdesk:agent:bootstrap
```

The bootstrap writes JSON and Markdown under `artifacts/aetherdesk_agent_bootstrap/`, including `latest.json` and `latest.md`. It compacts catalog, digest, autopilot, mission packet, scorecard, workflows, routes, commands, safety invariants, and next actions into one entrypoint.

Backend route:

```text
GET /api/agent/bootstrap
```

## Visual proof doctor

AetherDesk now includes a non-hanging visual proof lane:

- Command: `npm run aetherdesk:visual-proof:doctor`
- Workflow id: `visual_proof_doctor`
- Route: `GET /api/agent/visual-proof`
- Artifacts: `artifacts/aetherdesk_visual_proof/latest.json` and `latest.md`

This doctor reads the latest source UI contract, checks Playwright module readiness, writes a visual-readiness receipt, and explicitly reports whether live browser visual proof is actually proven. It does not launch Chromium by default; live screenshot proof should be added as a separate timeout-bounded step once the local browser runner is stable.

## Live visual proof

AetherDesk also includes a timeout-bounded live screenshot attempt:

- Command: `npm run aetherdesk:live-visual:proof`
- Workflow id: `live_visual_proof`
- Route: `GET /api/agent/live-visual-proof`
- Artifacts: `artifacts/aetherdesk_live_visual_proof/latest.json` and `latest.md`

The parent process always writes a receipt. Browser launch and screenshot capture happen in an isolated child process with a hard timeout, so Playwright/Chromium failures become evidence instead of hanging the agent loop. The receipt field `proof_ok` is the sales/readiness signal; `ok` only means the receipt was written.

## Control-plane proof

AetherDesk includes a self-hosted control-plane proof:

- Command: `npm run aetherdesk:control-plane:proof`
- Workflow id: `control_plane_proof`
- Route: `GET /api/agent/control-plane-proof`
- Artifacts: `artifacts/aetherdesk_control_plane_proof/latest.json` and `latest.md`

The proof starts an ephemeral local AetherDesk server, exercises Sieve, headless surface checks, MCP hook status/toggle/sign-in intent, PowerShell read/denial behavior, and system-access receipts. It verifies that denied PowerShell writes do not create the probe file and that recent system-access receipts include `action`, `access_tier`, `allowed`, `at`, and `route`.

## Soak recovery proof

AetherDesk includes a bounded repeated-operation proof:

- Command: `npm run aetherdesk:soak:recovery`
- Workflow id: `soak_recovery`
- Route: `GET /api/agent/soak-recovery`
- Artifacts: `artifacts/aetherdesk_soak_recovery/latest.json` and `latest.md`

By default it runs two cycles of the control-plane proof, live visual proof, visual proof doctor, and agent bootstrap, then refreshes the AI PC scorecard. Each child step has a hard timeout. This is the reliability bridge between point-in-time demos and a PC that keeps operating without evidence drift.

## Customer machine doctor

AetherDesk includes a customer-machine readiness doctor:

- Command: `npm run aetherdesk:customer:doctor`
- Safe repair mode: `npm run aetherdesk:customer:repair`
- Workflow id: `customer_doctor`
- Route: `GET /api/agent/customer-doctor`
- Artifacts: `artifacts/aetherdesk_customer_doctor/latest.json` and `latest.md`

Default mode is diagnostic and writes a redacted receipt. Repair mode only performs bounded local repairs such as creating missing artifact directories. It does not install packages, change PowerShell policy, kill ports, or mutate the host without a separate explicit action.

Update: soak recovery cycles now include the customer-machine doctor before control-plane, live visual, visual doctor, and bootstrap steps. This keeps the final scorecard from depending on stale customer-readiness evidence.

## License entitlement proof

AetherDesk includes a pilot entitlement receipt lane:

- Command: `npm run aetherdesk:license:proof`
- Workflow id: `license_entitlement`
- Route: `GET /api/agent/license-entitlement`
- Artifacts: `artifacts/aetherdesk_license_entitlement/latest.json` and `latest.md`

The proof binds a pilot customer id hash, machine fingerprint hash, edition, expiration, feature list, and portable package SHA-256 into a local entitlement receipt. If `AETHERDESK_LICENSE_SECRET` is set it adds an HMAC signature; otherwise it is explicitly marked `unsigned-local-pilot`. Public-sale blockers remain listed in the receipt.

## Public-sale readiness proof

AetherDesk includes a public-sale blocker ledger:

- Command: `npm run aetherdesk:public-sale:readiness`
- Workflow id: `public_sale_readiness`
- Route: `GET /api/agent/public-sale-readiness`
- Artifacts: `artifacts/aetherdesk_public_sale_readiness/latest.json` and `latest.md`

This proof passes when paid-pilot evidence is present and public-sale blockers are explicitly receipted. It reports `public_sale_ready: false` until signing, payment, entitlement-provider, signed-artifact, and legal/release approval evidence are configured.
