Skip to content

docs(specs): add the remote hosts from the CLI spec for the remote boxes epic - #1401

Closed
agent-137 wants to merge 3 commits into
mainfrom
docs/spec-remote-hosts-cli
Closed

agent-137 wants to merge 3 commits into
mainfrom
docs/spec-remote-hosts-cli

Conversation

@agent-137

Copy link
Copy Markdown
Member

Adds docs/specs/16-spec-remote-hosts-cli/, id RHC, written from gominimal/inbox#669 through the spec process (interview, prose behaviours, EARS, tiers, review), with the Box Provider API as its architecture of record.

What it covers. The CLI as a provider's client: choosing the provider and host (--provider/MIN_PROVIDER/min provider use, --host/MIN_HOST, placement on providers that can and cannot create hosts), having a host created and enrolled on demand (the §4.4 hand-off, standard host class, the admin-scope and mint preconditions refused up front), the host states shown and the exit statuses on failure, where the box listing's remote entries come from, min host list|rm|resume, and limits (min provider show, refusal before anything is created, and the provider's own refusal reported the same way).

What it deliberately leaves out, and where it lives. Creating the session on the chosen host, attaching, stopping and destroying it: CRA (#1374) as the architecture admits them; in v1 the daemon's remote set is list, show, attach, rename and stop (Gatehouse §7.4, MMI-027), and admitting create and destroy on the CLI's certificate connections is raised in gominimal/arch#65. One listing and one grammar across providers, and addressing an ambiguous name: the box data path (BDP-005/006, gominimal/arch#45). Re-establishing a session's identity after a host resumes: per session, on the next attach (Gatehouse §6.3.3).

Requirements. 40, with 8 at T2 (Kani, in the lane just kani already runs): the placement decision (RHC-001, 005, 008–011) and the limit check (RHC-038, 039). Each T2 names the pure function the implementation has to keep separate from provider calls.

Open questions. How an unanswering host is decided and where its sessions come from; the CLI's custody of the enrolment token and candidate WireGuard key (for #648); how long to wait for READY; automatic host reuse; starting a session on another enrolled machine.

Lint. spec-lint --repo-root .: 40 × P004 (named tests not written yet). The plugin's copy also reports F004 for the missing status: field, which foundry main has removed.

Blocked on. gominimal/arch#65 for the first slice to run end to end with a placed session; gominimal/arch#45 for BDP's ownership of the listing (coordination comment posted there).

Part of gominimal/inbox#494; the epic is gominimal/inbox#669.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UNTrqcfC5J5LwcM5eT8qcZ

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UNTrqcfC5J5LwcM5eT8qcZ
@coderabbitai

coderabbitai Bot commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

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

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Spec lint

docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md — 40 finding(s)

docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:116: P004 RHC-001 names test 'provider_precedence_flag_env_config', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:129: P004 RHC-002 names test 'provider_use_records_default', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:135: P004 RHC-003 names test 'activate_uses_min_provider', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:141: P004 RHC-004 names test 'activate_uses_configured_default_provider', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:146: P004 RHC-005 names test 'host_precedence_flag_env', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:157: P004 RHC-006 names test 'activate_with_provider_places_on_that_provider', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:163: P004 RHC-007 names test 'remote_activation_resolves_same_definition_as_local', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:168: P004 RHC-008 names test 'named_host_receives_session', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:188: P004 RHC-009 names test 'static_single_host_receives_session', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:198: P004 RHC-010 names test 'static_ambiguous_host_refused_exits_2', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:208: P004 RHC-011 names test 'static_provider_never_asked_to_create_host', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:222: P004 RHC-012 names test 'unnamed_host_preregisters_before_create', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:229: P004 RHC-013 names test 'create_host_without_admin_scope_refused_exits_5', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:235: P004 RHC-014 names test 'mint_refused_stops_create_exits_5', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:240: P004 RHC-015 names test 'create_host_requests_standard_class', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:247: P004 RHC-016 names test 'create_host_carries_enrolment_token', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:254: P004 RHC-017 names test 'attested_provider_preregisters_tokenless', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:259: P004 RHC-018 names test 'session_placed_when_new_host_ready', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:265: P004 RHC-019 names test 'host_creation_shows_each_state', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:270: P004 RHC-020 names test 'failed_host_names_state_exits_7', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:276: P004 RHC-021 names test 'unreachable_provider_during_create_exits_7', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:289: P004 RHC-022 names test 'listing_includes_provider_hosts', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:296: P004 RHC-023 names test 'listing_includes_enrolled_machines', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:301: P004 RHC-024 names test 'listing_signed_out_is_local_only', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:306: P004 RHC-025 names test 'listing_signed_out_says_sign_in_needed', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:311: P004 RHC-026 names test 'listing_dedupes_by_host_node_id', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:318: P004 RHC-027 names test 'unanswering_host_sessions_shown_unreachable', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:325: P004 RHC-028 names test 'host_list_shows_created_hosts_with_sessions', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:330: P004 RHC-029 names test 'host_rm_releases_empty_host', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:336: P004 RHC-030 names test 'host_rm_occupied_refused_exits_2', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:341: P004 RHC-031 names test 'host_rm_force_releases_occupied_host', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:347: P004 RHC-032 names test 'attach_to_paused_host_resumes_it_first', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:352: P004 RHC-033 names test 'host_resume_requests_provider_resume', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:357: P004 RHC-034 names test 'resume_shows_each_stage', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:362: P004 RHC-035 names test 'failed_resume_leaves_sessions_unchanged', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:368: P004 RHC-036 names test 'provider_errors_map_to_exit_statuses', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:376: P004 RHC-037 names test 'provider_show_lists_limits_and_usage', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:382: P004 RHC-038 names test 'over_limit_refused_before_any_create', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:398: P004 RHC-039 names test 'over_limit_refusal_names_dimension_exits_5', which was not found in the repository
docs/specs/16-spec-remote-hosts-cli/16-spec-remote-hosts-cli.md:409: P004 RHC-040 names test 'provider_quota_refusal_names_dimension_exits_5', which was not found in the repository

Advisory. None of this blocks the merge; the review decides.

Advisory, and never a merge gate. Linter: gominimal/foundry@3eaebc69, spec format: How Minimal Writes Specs.

@mitodrummer

Copy link
Copy Markdown
Member

Closing for now until we get local + networking story straight.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants