fix(cli): preserve existing directories during single-file upload

[shiju-nv]

Summary

Uploading a single file to an existing directory now puts the file inside it, even without a trailing slash. Previously, the upload could report success after replacing an empty directory with the file. Missing destination paths still support intentional filename renames.

Related Issue

Closes #4175

Changes

• Inspect the destination through the authenticated SSH session before choosing the archive entry name.
• Preserve empty and nonempty directories, destination directory symlinks and source symlinks. Keep existing file overwrites, missing-path renames and Git-filtered placement unchanged.
• Recheck the destination type before extraction and inspect it again on transport retries.
• Print the resulting path after an unfiltered upload and explain the placement rules in CLI help and the sandbox docs.
• Add shell-and-tar unit regressions and existing-directory cases to portable file-transfer conformance.

Testing

• Checks appropriate to the affected code and behavior pass
• Unit tests added/updated (if applicable)
• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable): sandbox file-transfer docs and CLI help updated

[github-actions]

Label test:e2e applied for 67b0f80. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[johntmyers]

gator-agent

PR Review Status

The initial review found no blocking issues in the upload destination fix. The existing CI gates pass, and the standard E2E suite is now queued for this head after applying test:e2e and rerunning the workflow as instructed by E2E Label Help.

Blocking findings: None.

Carried findings: None.

Gator metadata

• Validation: Focused fix for the reproducible single-file upload bug in #4175.
• Docs: Published sandbox documentation and CLI help explain destination placement.
• Checks: DCO, Branch Checks, Helm Lint, and Trivy Changes pass on the current head.
• E2E: test:e2e applied; Branch E2E Checks run 37198134708, attempt 2, confirmed queued.
• Head SHA: 67b0f8024477411a0ce7eadcca711c40846f8abb
• Base SHA: 71c3cd957abef062eb7f37010056717cd49f2ed3
• Merge base SHA: 71c3cd957abef062eb7f37010056717cd49f2ed3
• Patch ID: f9a4959b6b75ca9c0f89635e2590fcb1b0a0c74b
• Gator payload: 10
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[johntmyers]

@shiju-nv this will need a rebase etc

[johntmyers]

gator-agent

PR Review Status

Thanks @johntmyers for flagging the rebase. I checked the updated head against the prior reviewed patch, isolated the author changes from upstream changes, and confirmed the upload reporting still works with the new shared planning helper. The independent follow-up review found no new blocking issues, and GitHub reports the head is mergeable.

Branch Checks and the standard E2E suite are running on the current head. Gator will monitor their results before handing this to a maintainer for approval.

Blocking findings: None.

Carried findings: None.

Gator metadata

• Validation: Focused single-file upload destination fix for #4175.
• Docs: Published sandbox docs and CLI help describe destination placement.
• Checks: DCO, Helm Lint, and Trivy Changes pass; Branch Checks are pending.
• E2E: test:e2e retained; current-head Branch E2E Checks run 37581339905 is in progress, attempt 1. No additional dispatch is needed.
• Head SHA: 9b368eed43c74e2be61dbc7e998a38f35b0b7908
• Base SHA: 834b79a8c2351370e7c6c363423f5be18d440256
• Merge base SHA: 834b79a8c2351370e7c6c363423f5be18d440256
• Patch ID: 02746674f19bdf554a7f3808c22f469f7618eb66
• Gator payload: 10
• Review mode: follow_up
• Previous reviewed SHA: 67b0f8024477411a0ce7eadcca711c40846f8abb
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:watch-pipeline