Doctor v2: surface inventory, injectable probes, JSON contract, verdict-matrix fixtures

[aarontrowbridge]

Closes #525.

The fleet-dev-tools keystone (spec-20260823-094507, D1): six surface records with four-verdict staleness logic — every judgment by version string or content digest, never mtime. Injectable roots + running-binary stub make the 25-test verdict matrix fully hermetic (fake binaries, pinned dates, real git fixtures with local remotes). The committed JSON Schema (minItems 6) + canonical round-trip is the machine contract the panel (#527) and watchdog consume. Doctor v1's studio-binding checks untouched; the report gains a surfaces section.

Typecheck clean; the amico-run suite is 1146 passed with 2 failures proven pre-existing at base e308a45 (both read real machine state — verified in a detached base worktree; details in the notes). Zero new dependencies.

Part of #524.

Summary by CodeRabbit

• New Features

  • Enhanced amico doctor with a machine-readable --json report.
  • Added inventory and status reporting for six installation surfaces.
  • Added root-selection options and running-binary inspection.
  • Human-readable output now includes a surfaces status table.

• Bug Fixes

  • Added validation for report structure and command-line arguments, with clear errors for invalid input.

• Documentation

  • Added documentation for diagnostic status scenarios and test fixtures.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 92643e1d-54c3-44a1-9376-2c20b08c5403

📥 Commits

Reviewing files that changed from the base of the PR and between 5a7c8db and 77aefc0.

📒 Files selected for processing (10)

• packages/amico-run/schemas/doctor-report.schema.json
• packages/amico-run/src/amico.ts
• packages/amico-run/src/doctor.ts
• packages/amico-run/src/doctor_schema.ts
• packages/amico-run/src/surfaces.ts
• packages/amico-run/test/amico.test.ts
• packages/amico-run/test/doctor.test.ts
• packages/amico-run/test/fixtures/surfaces/README.md
• packages/amico-run/test/helpers.ts
• packages/amico-run/test/surfaces.test.ts

---

📝 Walkthrough

Walkthrough

Doctor v2 adds six-surface inventory reporting to amico doctor. It supports injectable roots, --running-binary, canonical --json output, schema validation, deterministic verdicts, human-readable rendering, and hermetic fixture tests.

Changes

Doctor v2 surface inventory

Layer / File(s)	Summary
Report contract and CLI arguments packages/amico-run/schemas/doctor-report.schema.json, packages/amico-run/src/doctor_schema.ts, packages/amico-run/src/doctor.ts, packages/amico-run/src/amico.ts	The doctor command accepts JSON and root-selection options. The report schema and zero-dependency validator enforce the six-record contract.
Surface probes and verdict classification packages/amico-run/src/surfaces.ts	The inventory probes server binaries, extensions, vendored binaries, staged skills, and global and staging agent cards. It classifies records as current, stale, integrity-failure, or unknown.
Doctor report output and routing packages/amico-run/src/doctor.ts, packages/amico-run/src/amico.ts, packages/amico-run/src/surfaces.ts	The report combines studio diagnosis with surface records. It renders the surfaces table and returns canonical JSON without changing diagnosis-based exit status.
Hermetic verdict and integration validation packages/amico-run/test/helpers.ts, packages/amico-run/test/surfaces.test.ts, packages/amico-run/test/doctor.test.ts, packages/amico-run/test/amico.test.ts, packages/amico-run/test/fixtures/surfaces/README.md	Pinned fixture worlds and tests cover verdict matrices, argument parsing, schema constraints, canonical serialization, and router output.

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

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant DoctorReport
  participant SurfaceInventory
  participant Sources
  participant FleetSurfaces
  CLI->>DoctorReport: pass doctor arguments
  DoctorReport->>SurfaceInventory: request six-surface report
  SurfaceInventory->>Sources: refresh remote-tracking state
  SurfaceInventory->>FleetSurfaces: inspect files, binaries, processes, and receipts
  FleetSurfaces-->>SurfaceInventory: return verdicts and evidence
  SurfaceInventory-->>DoctorReport: return surface records
  DoctorReport-->>CLI: return rendered output or canonical JSON

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 525-doctor-v2

---

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