Skip to content

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

Merged
thymikee merged 8 commits into
mainfrom
feat/4524-device-status-acquirable
Nov 15, 2026
Merged

thymikee merged 8 commits into
mainfrom
feat/4524-device-status-acquirable

Conversation

@thymikee

@thymikee thymikee commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

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 22b06fc; 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.
  • (22b06fc) pnpm build, tsc -b tsconfig.typecheck.json, oxlint --deny-warnings, oxfmt --check — clean.
  • (fd61024, 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.

View guided diff Turn on auto-fix

`device status --json` answered how many claim records name a device, not whether
`open` accepts one now, so a caller that read the hidden stale-claim count as a
block gave up on devices whose owner had provably exited (#4524).

Report each claimed device once with `acquirable`, `blockedBy` when it is not, and
the `owner` to act on. The answer comes from the decisions an acquisition already
applies: the owner half of `foreignClaimSettlement` and the pre-gateway resource
check `open` and `device release --stale` run, so no second classifier decides
ownership. `status` never touches a device, so it passes no boot observer and reads
a live owner as blocking, as `boot`, `install` and `shutdown` do.

Share one refusal vocabulary: the table `device release --stale` kept privately is
now `deviceClaimRefusalReason`, and retention reasons are typed as
`ClaimRecoveryRetentionReason`, so status and release name a block identically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.28 MB 6.28 MB +3.2 kB
Package (unpacked) 6.28 MB 6.28 MB +3.2 kB
Package (download) 1.90 MB 1.91 MB +1.1 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 22.9 ms 23.3 ms +0.3 ms
CLI --help 45.2 ms 44.3 ms -0.9 ms

The acquirability term is defined where device status documents it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed

You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread src/commands/schema/cli-help.ts Resolved
Comment thread website/docs/docs/sessions.md Resolved
Comment thread website/docs/docs/commands.md Resolved
Comment thread website/docs/docs/commands.md Resolved
Comment thread src/commands/schema/cli-help.ts Resolved
Comment thread src/cli/commands/device.ts Resolved
Comment thread src/cli/commands/device.ts Resolved
Comment thread src/commands/schema/cli-help.ts Resolved
thymikee and others added 2 commits November 14, 2026 14:21
…n in device status

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… as a new entry

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review completed against the latest diff

You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread src/cli/commands/device.ts Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 11 files (changes from recent commits).

You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread website/docs/docs/sessions.md Resolved
Comment thread src/commands/schema/cli-help.ts Resolved
Comment thread website/docs/docs/commands.md Resolved
thymikee and others added 2 commits November 14, 2026 14:31
…ck reads

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…verdict replaced

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

apex-sentinel-staging Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 0 no longer raised

No open findings.

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (d78be6c88715).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

Earlier reviews

Review of aa910dfb · 14.11.2026 13:42 UTC

Apex Sentinel · ✅ Approve

No open findings.

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (d78be6c88715).

@thymikee

thymikee commented Nov 14, 2026 •

Copy link
Copy Markdown
Member Author

I reviewed aa910df. CI is green (22 checks, none failing), there is one documentation problem to fix before merge, and I did not run the tests myself. There are no conflicts.

The hiddenStaleClaims sentence in cli-help.ts:314 says it alone never means the device is unavailable. That holds only for hidden dead owners. deviceClaimOwnerCannotRelease (device-claim-inspection.ts:280) lets only dead and superseded owners settle. A hidden claim whose owner PID was reused, or whose state directory is gone, still makes status report acquirable:false, and open refuses with DEVICE_IN_USE. A hidden dead owner with an open recording reports screen-recording-cleanup-pending. So device status --json with claims:[] and hiddenStaleClaims:1 can describe a device that cannot be taken, while the help says it can. Callers act on this text, and it keeps the reading that #4524 set out to replace. Please state one rule: hiddenStaleClaims counts hidden records and is not an availability signal, so read acquirable. A hidden dead or replaced owner with no pending resource does not block. A hidden PID-reused or missing-state-directory owner, or pending resource cleanup, does. Use the cli-help.ts sentence as the owner and make commands.md:90 and sessions.md:194-196 match it.

Not blocking, and you can take or leave these: (1) the four "status and open agree" tests in cli-device-status.test.ts compare inspectDeviceClaimAcquisition with itself, while plain open decides in acquireDeviceClaim, so asserting status against that path for the host-before-app and noncanonical-name cases would pin real agreement, or the test comment and PR body can say they pin status to the shared inspection; (2) the pending-recovery policy in device.ts:139 is a second rule in the CLI, because open stops an open recording and takes the device when it still answers, so inspectNewSessionAdmission could return the pending-recovery fact and either keep acquirable:false or report acquirable:true with a separate pendingCleanup; (3) commands.md:90 still scopes owner under "when the device is not acquirable", so something like "blockedBy names why a device is not acquirable; owner names the claim's owner when its record decodes, the holder that blocks it or, on an acquirable device, the reclaimable dead owner open would settle" fits better; (4) the comment at device.ts:85 says a device no claim names is acquirable, but a macOS or web host is refused while a live app or web-session claim exists or a claim file is unreadable, so drop or qualify it; (5) reportDeviceAcquirability runs for human output too though only JSON reads devices, which costs O(devices x claims), so compute it only for JSON or pass the classified claims in; (6) inspectNewSessionAdmission hardcodes session:'device-status' and an empty stateDir as a placeholder acquirer, which could get a clearer name, and DeviceClaimReconciliationResult.reason is still string, so either type it or drop "typed" from the PR body.

The open inline threads on the commands.md owner sentence and the hidden-stale wording still apply even though they are marked resolved. This thread and this one are fixed at this head, so you can resolve them.

I read the diff but did not run the tests. By reading, the main status test would fail on the merge base because data.devices is new. I compared inspectDeviceClaimAcquisition with claimHeldDevice and withAcquisitionLocks by reading only, for host-before-app, the host-scoped scan and the canonical path. I assumed reading a foreign owner's manifest has no side effects. This PR does not address #4238, and it does not claim to. Before merge, please fix the hiddenStaleClaims wording in cli-help.ts, commands.md and sessions.md.

thymikee and others added 2 commits November 14, 2026 15:00
The sentence claimed a hidden stale claim alone never means a device is unavailable.
Only a dead or superseded owner settles, so a hidden claim whose owner PID was
reused, or whose state directory is gone, still reports acquirable:false and `open`
refuses it with DEVICE_IN_USE, as does a dead owner whose recording still awaits
disposal.

State one rule in the owning help text and match both docs pages: the count names
hidden records and answers nothing about availability, so read acquirable. Name the
hidden owner kinds and pending cleanup that do block.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Acquirability is a --json answer, and each device weighs every claim, so the human
view, which renders claims and notices, should not pay for it.

Drop the claim that a device no claim names is acquirable: a device can be
unreported for another reason, such as a host whose live claims name only its own app
devices. Say what the agreement tests pin: the shared inspection, asked as `open` asks
it, not a claim taken through `acquireDeviceClaim`. Note why the reporter's acquirer
is deliberately unadoptable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

Fixed in fd61024. cli-help.ts now owns the rule and both docs pages match it: hiddenStaleClaims counts the claim records this view hides and is not an availability signal, so read acquirable; a hidden owner whose PID was reused or whose state directory is gone, and pending resource cleanup, each still block the device. The old claim that a hidden stale count never means unavailable is gone from all three surfaces.

On the non-blocking items:

  • (1) agreement tests — took the wording option. They pin status to the shared inspection, asked as open asks it (inspectDeviceClaimAdmission as a session of another daemon). Asserting through acquireDeviceClaim would settle the reclaimable claim the same store is reused for, so the test now says what it proves instead.
  • (3) took it: commands.md no longer scopes owner under "when the device is not acquirable"; it names the blocking holder or, on an acquirable device, the reclaimable owner open would settle.
  • (4) took it: the report's comment no longer says a device no claim names is acquirable; an absent entry carries no answer.
  • (5) took it: reportDeviceAcquirability runs only for --json.
  • (6) placeholder acquirer — kept the name and added why it is deliberately unadoptable (no claim can match that session/workspace/state dir, so every "already the caller's?" half answers no). On the type: ClaimRecoveryInspection/DeviceClaimAdmission.retainedBy, which is what blockedBy reads, are typed; DeviceClaimReconciliationResult.reason stays string (the reconciler seam carries test stubs and daemon-process reasons), and the PR body no longer calls that seam typed.
  • (2) declined: making a pending resource read acquirable: true (or adding pendingCleanup) would tell a caller to open a device whose owner's recording recovery only open itself can run, which is the ambiguity device status: report whether a device is acquirable, not only claim counts #4524 asked us to remove. Reporting it blocked with <kind>-cleanup-pending is the fail-closed answer; open may still take it, and the help says so.

Both still-applying inline threads are resolved at this head, along with the two you marked fixed.

@thymikee

Copy link
Copy Markdown
Member Author

Coverage re-ran on this head, not because of a code change. The job failed once at fd61024 in packages/host-kit/src/internal/host-process-liveness.test.ts:182 (ps-parsed start time came back as the Linux fallback identity, so zombie read false). That file is not in this diff, and the same assertion failure is recorded on main at the merge base d78be6c88, so it is a pre-existing Linux-runner flake. The re-run passes and all checks are green.

@thymikee

Copy link
Copy Markdown
Member Author

I found no problems in fd61024. The two findings from the earlier review (#4547 (comment)) are fixed: hiddenStaleClaims is now one rule owned by cli-help.ts, and commands.md and sessions.md match it, while admission logic is unchanged.

CI shows 22 checks with none failing at this commit. The one Coverage failure was in host-process-liveness.test.ts, which this diff does not touch, and it passed on re-run. I did not run tests locally, and I did not confirm that failure on main. There are no conflicts.

Of the open inline threads from other reviewers, these four are fixed at this commit, so you can resolve them: the --stale help wording (#4547 (comment)), the blockedBy scope in commands.md (#4547 (comment)), the host-before-app admission order (#4547 (comment)), and the claim scan by device (#4547 (comment)).

One small note, not raised before and not required: the help's blockedBy list omits claim-record-unreadable, a value the type admits. I did not check whether any production route emits it.

This is ready for human review.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 14, 2026
@thymikee
thymikee merged commit 567339e into main Nov 15, 2026
26 of 27 checks passed
@thymikee
thymikee deleted the feat/4524-device-status-acquirable branch November 15, 2026 07:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

device status: report whether a device is acquirable, not only claim counts

1 participant