fix: make incomplete-download planning help successful and bounded

[seonghobae]

Purpose

Make three incomplete-download operational CLIs treat a sole --help / -h as a successful terminal action while preserving fail-closed invalid and execution semantics, and ensure opaque or non-UTF-8 arguments cannot escape through reflected diagnostics or a Rust panic.

Covered binaries:

• disksage-incomplete-download-materialization;
• disksage-incomplete-download-recovery;
• disksage-incomplete-download-materialize.

Exact current state

• Exact source head: f7b405ba4bb80ac3bda8785807f87ad491dd8660.
• Live protected main: be418bac9bfbdc8aa41b1a698713833e3dbccfdc.
• Fresh main -> head comparison is ahead, ahead_by = 17, behind_by = 0, with merge base exactly protected main.
• Current semantic delta is exactly four files:
  • src-tauri/src/bin/disksage-incomplete-download-materialization.rs;
  • src-tauri/src/bin/disksage-incomplete-download-recovery.rs;
  • src-tauri/src/bin/disksage-incomplete-download-materialize.rs;
  • src-tauri/tests/cli_help_incomplete_plans_exit.rs.
• GitHub reports the PR open, Draft, and mergeable before the Ready transition in this loop.

Test-first evidence and root cause

• Exact test-only head ed26ae2e1ac93f54f1188b8daea756c427a35dfc added the real-binary process contracts before production changes.
• Test run 31763912086 passed setup, dependency/toolchain installation, and the independent llm-engine-build, then failed in the Rust-test boundary. Cancelled Release/Security runs on that superseded head are not treated as evidence.
• The parsers modeled help as an ordinary error and reflected unknown argument text. The execution CLI also retained a parser-level help arm that could make mixed help/invalid behavior inconsistent with the intended sole-help contract.
• A subsequent CodeRabbit review identified two valid hardening gaps: Unix non-UTF-8 arguments could panic through std::env::args(), and the regression did not yet pin complete usage/error contracts. Both are addressed on the current exact head; the sole inline thread is resolved and outdated.

Narrow implementation

Each binary now:

• reads host arguments with std::env::args_os();
• converts each OsString explicitly and maps conversion failure to that binary's stable unknown-argument token;
• recognizes help only when it is the sole argument;
• emits the complete stable usage synopsis plus one newline on stdout and exits 0;
• keeps unknown and mixed help/invalid requests non-zero with empty stdout;
• uses a bounded stable error token without reflecting arbitrary payloads.

The process regression builds the actual feature-gated binaries with --locked --features cloud-cli in an isolated target directory and verifies sole help, short help, unknown argument, mixed help/invalid, and Unix non-UTF-8 input.

Incomplete-download audit/recovery validation, materialization planning, destination-plan and fingerprint admission, explicit --execute, human attribution/rationale, capacity admission, private create-new evidence/receipts, cloud-root/path safety, JSON stdout purity, filesystem authority, and existing limits remain unchanged.

Exact-head validation

On unchanged head f7b405ba4bb80ac3bda8785807f87ad491dd8660:

• Test 31868643605 — success; the ordinary test job and llm-engine-build both completed successfully;
• Release 31868643606 — success;
• Security Scan 31868643610 — success;
• SAST Semgrep 31868643618 — success.

Formal CodeRabbit review evidence is anchored to predecessor head c1b436dc3cd2e28f576ae2ba48d911822025d50a, not the current head. Its valid findings are addressed, but predecessor review evidence is not approval and does not transfer.

Scope / non-duplication

A temporary Draft #219 was converged into this domain batch and closed without losing its unique test delta. #217 owns local-eviction/destination-plan help, #156 owns repository-wide exact coverage, and #149 owns canonical acquisition documentation. This PR races none of those owners.

Remaining integration blocker

Feature-local/current-head evidence is green, but repository-wide exact 100% owned-production region/statement-equivalent, branch, function, and line coverage remains materially unsatisfied on canonical coverage owner #156. Ready-for-review status is not merge authorization.

Required before merge

Do not merge unless the unchanged exact head satisfies every applicable live required workflow and current finding, every review thread is resolved, fresh live-base ancestry remains current, the live review ruleset is satisfied, and repository-wide exact coverage is satisfied without exclusions or threshold weakening. Pending, queued, skipped-required, neutral-required, failed, stale, predecessor, synthetic, diagnostic-only, status-only, model-only, rate-limited, or infrastructure-only evidence is not passing.

---

[coderabbitai]

Warning

Review limit reached

Next included review available in 34 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 66fd20d4-cd9e-456c-bae4-4fef25b8a2d3

📥 Commits

Reviewing files that changed from the base of the PR and between c1b436d and 33f886c.

📒 Files selected for processing (8)

• .github/scripts/verify-release-artifacts.sh
• .github/workflows/release.yml
• src-tauri/src/bin/disksage-incomplete-download-materialization.rs
• src-tauri/src/bin/disksage-incomplete-download-materialize.rs
• src-tauri/src/bin/disksage-incomplete-download-recovery.rs
• src-tauri/tests/cli_help_incomplete_plans_exit.rs
• src/lib/releaseArtifactVerifierDirectoryContract.test.ts
• src/lib/releaseTagArtifactVerifierContract.test.ts

📝 Walkthrough

Walkthrough

세 불완전 다운로드 CLI가 단독 --help 및 -h를 성공 처리합니다. 알 수 없는 인자는 고정된 오류 문자열을 반환합니다. 새 통합 테스트가 출력, 종료 코드, 진단 및 비 UTF-8 인자 동작을 검증합니다.

Changes

불완전 다운로드 CLI 계약

Layer / File(s)	Summary
CLI 사용법 및 인자 처리 src-tauri/src/bin/disksage-incomplete-download-materialization.rs, src-tauri/src/bin/disksage-incomplete-download-materialize.rs, src-tauri/src/bin/disksage-incomplete-download-recovery.rs	각 CLI에 usage 처리를 추가했습니다. 단독 도움말 인자는 사용법을 stdout에 출력하고 성공 종료합니다. 알 수 없는 인자는 고정된 오류 문자열을 반환합니다.
프로세스 수준 CLI 계약 테스트 src-tauri/tests/cli_help_incomplete_plans_exit.rs	세 바이너리를 빌드한 뒤 도움말, 잘못된 인자, 혼합 인자 및 Unix 비 UTF-8 인자의 종료 코드와 stdout·stderr 진단을 검증합니다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🟡 Moderate · up to c1b43

The three updated CLIs can still panic instead of returning a bounded error when given a non-UTF-8 argument. This is a localized but concrete runtime correctness issue that should be fixed before merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 세 개의 incomplete-download CLI에서 도움말을 성공 처리하고 오류 진단을 제한하는 주요 변경을 명확하게 요약합니다.

✨ 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 fix/cli-help-incomplete-plans-v1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head f7b405ba4bb80ac3bda8785807f87ad491dd8660.

• Head SHA: f7b405ba4bb80ac3bda8785807f87ad491dd8660

• Workflow run: 32167364984

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (4 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (4 files)"]
  R1 --> V1["required checks"]

Loading

[opencode-agent]

OpenCode Review Overview

• Head SHA: f7b405ba4bb80ac3bda8785807f87ad491dd8660
• Workflow run: 32174716369
• Workflow attempt: 1
• Gate result: REQUEST_CHANGES (approval step)

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head f7b405ba4bb80ac3bda8785807f87ad491dd8660.

• Head SHA: f7b405ba4bb80ac3bda8785807f87ad491dd8660

• Workflow run: 32174716369

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (4 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (4 files)"]
  R1 --> V1["required checks"]

Loading

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head f7b405ba4bb80ac3bda8785807f87ad491dd8660.

• Head SHA: f7b405ba4bb80ac3bda8785807f87ad491dd8660

• Workflow run: 32174716369

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (4 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (4 files)"]
  R1 --> V1["required checks"]

Loading

This REQUEST_CHANGES review is anchored to predecessor head f7b405b and its failed predecessor coverage-evidence run. The PR has since been non-destructively converged onto current main and repaired on exact head 6a4b186. Predecessor review evidence cannot remain current-head blocking evidence. This dismissal does not assert approval or passing current-head checks; all current exact-head gates and repository-wide coverage remain required.