feat(mecak8s): explicitly seed and synchronize local workspaces

Kubernetes context

mecak8s is intentionally file-less by default. The existing Redis-backed filesystem work in #889 establishes durable remote, principal-scoped file contents, but it does not solve getting a developer's local project into that filesystem or returning remote edits to the local checkout.

Problem or feature request

A developer connecting from a local checkout to mecak8s starts with no project files available to the remote agent. Manually creating or uploading files makes the first useful run slow and prevents realistic repository work.

We need an explicitly user-initiated, privacy-preserving workspace sync workflow that can:

1. seed an authorized remote mecak8s workspace from a local checkout; and
2. let the developer review and apply remote changes back to that local checkout.

This is not a request to expose a client's filesystem to a remote server by default, nor to make a cluster pod mount arbitrary client paths.

Expected behavior

• A local client can explicitly select a local directory/repository and create or update an associated remote workspace snapshot.
• The first sync transfers the selected files needed for agent work, subject to clear include/exclude rules and a preview.
• Subsequent syncs identify local and remote changes since a recorded common base and present a reviewable diff/status before applying either direction.
• Remote-to-local changes are fetched to the client and require an explicit local apply step; the server never silently writes a developer's checkout.
• Conflicts are detected and surfaced without overwriting either side. The user chooses how to resolve them.
• A user can inspect sync status: associated remote workspace, last successful sync, pending local changes, pending remote changes, and conflicts.
• The remote agent only sees files in the explicitly synchronized remote workspace. No general host filesystem access, shell access, or implicit local path forwarding is introduced.

Safety and compatibility requirements

• Preserve mecak8s's file-less default. Sync must be an explicit, opt-in workflow.
• Do not send raw local paths as durable server-side identity or expose them in shared logs/telemetry.
• Do not sync credentials, environment files, .git internals, ignored files, or other sensitive content by default. The inclusion policy must be inspectable and conservative.
• Remote workspace ownership and authorization must remain tied to the authenticated caller/tenant; another caller cannot list, read, modify, or sync its contents.
• Every remote-to-local apply must be initiated by the local client and protect uncommitted local changes.
• File transfer and change application must be integrity-checked, resumable or safely retryable, and fail closed rather than silently producing a partial or inconsistent workspace.
• The design must work with multiple mecak8s replicas and durable remote storage; no pod-local filesystem becomes the source of truth.

Acceptance criteria

• A user can explicitly seed a remote mecak8s workspace from a selected local project with a preview of included and excluded files.
• A second sync transfers only detected changes or otherwise has clearly bounded/idempotent behavior.
• A user can fetch a remote change set, review it locally, and explicitly apply it to the selected checkout.
• Divergent local and remote edits to the same file are reported as conflicts; neither side is silently overwritten.
• Local files excluded by the default policy—including credentials, .git, and ignored files—are not transferred.
• Remote workspace contents and sync metadata are isolated by authenticated caller/tenant and survive mecak8s pod replacement.
• Failed/interrupted syncs leave both local and remote workspaces in a recoverable, accurately reported state.
• mecak8s remains shell-less; this feature does not add Bash, arbitrary command execution, host mounts, or automatic client filesystem access.
• User and operator documentation describe setup, privacy boundaries, include/exclude policy, conflict resolution, and rollback/recovery behavior.

Open design questions

• Is the remote unit a new explicitly named/synced workspace, rather than the current principal-wide filesystem namespace from #889?
• What should be the source of truth and common-base representation: content hashes, a snapshot manifest, Git object exchange, or another protocol?
• Which client surface owns synchronization first: mecatui, CLI, API/SDK, or all three?
• Should Git-aware behavior be a later enhancement, with v1 using conservative file synchronization only?
• What quota, file-count, file-size, retention, and deletion lifecycle should apply to remote workspace snapshots?

Out of scope

• Automatically mounting, continuously watching, or silently mirroring a developer's local filesystem.
• Syncing secrets, local credentials, .git metadata, or ignored files by default.
• Arbitrary remote shell/command execution.
• Replacing Git, hosted source control, or code review.
• A general-purpose distributed filesystem.

Related work

• #889 — principal-scoped Redis filesystem for mecak8s. This issue builds on durable remote file contents but adds explicit local seeding and reviewed bidirectional synchronization.
• ADR 0048 / mecak8s file-less default and its remote-storage model.

Start by reading #889 and ADR 0048 to understand the durable remote filesystem and file-less default. Then inspect the existing mecak8s client and API entry points before resolving the open design questions; done means an explicit, reviewable, isolated bidirectional sync with conflict handling, recovery, and documentation.