bot-bottle/docs/prds/0045-workspace-porting-plan.md

PRD 0045: Workspace Porting Plan

• Status: Active
• Author: didericis-codex
• Created: 2026-06-02
• Issue: #116

Summary

Add a backend-neutral WorkspacePlan that describes how the operator's current workspace is represented inside a bottle. Docker and smolmachines should both use this plan for workspace path, working directory, content copy, .git copy, ownership, and provider trust configuration instead of rediscovering /home/node/workspace in separate launch and provisioning code paths.

Problem

The current --cwd behavior is spread across backend-specific code:

• Docker builds a derived image that copies the host cwd to /home/node/workspace, sets that as WORKDIR, and patches Claude trust in the generated Dockerfile.
• Docker git provisioning separately copies .git into /home/node/workspace/.git.
• smolmachines git provisioning reconstructs <guest_home>/workspace/.git, but does not copy the full working tree.
• Codex provider setup trusts guest_home, not the copied workspace path.

These details create backend drift and make provider-specific workspace fixes easy to hard-code in the wrong layer.

Goals / Success Criteria

• BottleSpec remains the CLI intent shape (copy_cwd, user_cwd), while a resolved WorkspacePlan carries the backend-neutral guest workspace contract.
• BottlePlan exposes workspace_plan so shared and backend-specific provisioning paths consume one resolved object.
• The default in-bottle workspace path remains /home/node/workspace when --cwd is enabled.
• Docker uses WorkspacePlan when building the derived cwd image and when provisioning cwd .git state.
• smolmachines copies the host cwd contents into the same logical workspace path and uses WorkspacePlan when provisioning cwd .git state.
• Provider trust configuration is written for the workspace path when --cwd is enabled, and for the guest home when --cwd is disabled.
• Unit tests cover plan resolution, provider trust path selection, Docker derived image rendering, and both backends' .git copy targets.

Non-goals

• No new user-facing flags for custom workspace paths.
• No manifest schema changes.
• No redesign of git-gate or bottle.git entries.
• No switch from Docker image-copy to bind-mount.
• No unrelated provider auth changes.

Scope

In scope:

• Add a small workspace planning module.
• Add workspace_plan to BottlePlan and populate it in Docker and smolmachines prepare paths.
• Thread the trusted project path into provider provisioning.
• Replace hard-coded /home/node/workspace cwd copy and .git copy sites with WorkspacePlan values.
• Copy full host cwd contents for smolmachines --cwd parity.
• Update focused unit tests.

Out of scope:

• Integration tests that launch real Docker containers or smolmachines VMs.
• Path customization in the bottle manifest or CLI.
• Runtime synchronization after bottle launch; this remains a launch-time copy.

Design

Add bot_bottle/workspace.py:

@dataclass(frozen=True)
class WorkspacePlan:
    enabled: bool
    host_path: Path
    guest_home: str
    guest_path: str
    workdir: str
    owner: str = "node:node"
    mode: str = "755"
    copy_contents: bool = True
    copy_git: bool = True
    has_host_git_dir: bool = False

workspace_plan(spec, guest_home) resolves:

• enabled from spec.copy_cwd.
• host_path from spec.user_cwd.
• guest_path as <guest_home>/workspace when enabled, else guest_home.
• workdir as guest_path when enabled, else guest_home.
• has_host_git_dir from <host_path>/.git.

Backends resolve this in prepare using their existing guest-home knobs:

• Docker: BOT_BOTTLE_CONTAINER_HOME, default /home/node.
• smolmachines: BOT_BOTTLE_GUEST_HOME, default /home/node.

BottlePlan carries the result so launch, git provisioning, and provider provisioning stop consulting spec.copy_cwd and hard-coded paths directly.

Docker

Keep the current derived-image transport. Change build_image_with_cwd(derived, base, cwd) to accept a WorkspacePlan or explicit guest path/workdir fields, then render:

• COPY --chown=node:node . <workspace_plan.guest_path>
• WORKDIR <workspace_plan.workdir>

Claude trust should move out of the generated cwd Dockerfile and into provider provisioning so Docker and smolmachines share the same provider trust behavior.

smolmachines

Copy host cwd contents into workspace_plan.guest_path during provisioning or VM initialization, then chown the resulting workspace to node:node. Continue to copy .git through the existing smolvm transport, but target <workspace_plan.guest_path>/.git.

This intentionally closes the current parity gap where smolmachines receives repo metadata without the working tree.

Provider Trust

Extend provider planning with a trusted_project_path argument. Callers pass workspace_plan.workdir.

Codex writes:

[projects."<trusted_project_path>"]
trust_level = "trusted"

Claude writes or updates .claude.json so projects includes trusted_project_path with hasTrustDialogAccepted: true. This provisioning belongs in AgentProvisionPlan so both backends apply it through their existing provider file-copy primitives.

Testing Strategy

• Unit-test workspace_plan() for enabled and disabled cwd, guest-home overrides, and .git detection.
• Unit-test Docker cwd image rendering to prove it uses the plan's guest path and workdir.
• Unit-test provider planning for Codex and Claude trusted project paths.
• Unit-test Docker and smolmachines git provisioning targets using mocked copy and exec primitives.
• Unit-test smolmachines workspace content copy target and ownership command.

Run:

• python3 -m unittest discover -s tests/unit

Open Questions

None.