feat(device-status): report per device whether a new session can take it

Merged
TH
19h ago
+797-50

Summary

device status --json answered how many claim records name a device, not whether a new session can
take it, so a caller that read a non-zero hiddenStaleClaims as "busy" gave up on devices whose owner
had provably exited (#4524).

data.devices[] now carries one entry per claimed device: acquirable, blockedBy when it is not,
and owner naming the holder, or on an acquirable device the reclaimable owner open would settle.
Status asks inspectDeviceClaimAdmission, the one pure verdict that open's pre-acquisition check
(composite-resource-admission) also reads. It wraps inspectDeviceClaimAcquisition and the
retained-resource check, so claim order (host before app), canonical claim paths, abandoned claims and
unreadable claims follow open by construction. Status adds one policy: a reclaimable owner with an
open durable resource reports <kind>-cleanup-pending, since status never runs recovery (#4238).

Out of scope: acquisition's own locked re-decision (acquireDeviceClaim) is pre-existing and still
decides separately under its claim locks. An abandoned claim of a running daemon is reported as blocked
by that live owner; open through that same daemon may still take it (documented).

Scope additions: the refusal-reason table device release --stale kept privately is now
deviceClaimRefusalReason, and the inspection and admission types name their reasons
(ClaimRecoveryRetentionReason, DeviceClaimAdmission.retainedBy), so blockedBy is a typed union.
DeviceClaimReconciliationResult.reason, the reconciler seam below that, stays string. Status
stays daemonless, touches no device and passes no boot observer; human text output is unchanged, and
the acquirability report is computed only for --json. The answer is an inspection, not a
reservation.

agent-device device status --json | jq '.data.devices[] | {deviceKey, acquirable, blockedBy}'
# {"deviceKey":"local:android:none:emulator-5554","acquirable":true,"blockedBy":null}

Validation

Base d78be6c887. The whole-project run below is at 22b06fc11a; later commits were checked with focused tests, tsc, oxlint, check:layering and the eager-closure budget test.

  • vitest run --project unit-core (whole project): 2019 files, 18829 passed, 10 skipped.
  • (22b06fc11a) pnpm build, tsc -b tsconfig.typecheck.json, oxlint --deny-warnings, oxfmt --check — clean.
  • (fd61024fcf, docs-only plus a JSON-only report guard) focused vitest run --project unit-core over packages/daemon-contracts/src, cli-device-status.test.ts, src/commands/schema, cli-help.test.ts, test/repo-guards, plus tsc -b and oxfmt --check — clean. The rule text is owned by cli-help.ts; commands.md and sessions.md match it.
  • device-claim-admission.test.ts covers the verdict; cli-device-status.test.ts has one status-vs-open agreement test per case: abandoned claim of a running daemon, noncanonical file name, unreadable claim root, host-before-app order. Closure budgets and check:layering pass locally; CI validates the rest.
  • CI obligations: unit lanes only; no live-device path changed.
  • Unresolved risk: a concurrent open can change the answer between inspection and acquisition.

Closes #4524

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.