[RFC] Local Environment Files in Managed Worktrees

[sebasanblas]

This is a discussion-first RFC; I am not proposing a code pull request until maintainers confirm the desired behavior.

Context

I am using Multica with a frontend repository that has different build targets, such as beta, staging, and production.

The repository intentionally keeps environment-specific files out of Git, for example:

• .env.beta.local
• .env.staging.local
• .env.production.local

The project works correctly in its primary local checkout because those files exist there. However, when Multica runs an issue against a github_repo resource, it creates an isolated worktree from the daemon-managed cache. The local environment files ignored by Git are not present in that worktree, so the agent cannot properly run the build or native validation.

The current alternatives have important trade-offs:

• Committing these files is not acceptable for environment-specific configuration or secrets.
• Manually copying them into every task worktree does not scale.
• Using local_directory in direct mode exposes the user's current branch and forces tasks to run serially.
• Using local_directory in worktree mode preserves isolation, but ignored files are still not copied automatically.

Problem

Multica has a strong isolation model for github_repo resources, but there does not appear to be a generic mechanism for a local daemon to provide Git-ignored configuration files to isolated worktrees.

This is not limited to .env files. A repository may need:

• environment files;
• local Firebase configuration for mobile applications;
• test configuration;
• Playwright or browser configuration;
• certificates or signing-related files;
• other machine-specific files intentionally excluded from Git.

The desired behavior is to keep the repository isolated while allowing the local daemon to explicitly provide the configuration required to run the task.

Proposed two-layer model

I would like to ask whether Multica would consider combining the following two layers.

Layer 1: repository-declared files

Support the same convention used by Codex-managed worktrees:

.worktreeinclude
.env.beta.local
.env.staging.local
android/app/google-services.json
ios/App/GoogleService-Info.plist

This file would act as an explicit list of ignored paths that may be copied into a managed worktree.

The convention should be opt-in and explicit. Multica should not automatically copy all .env* files or all ignored files.

Layer 2: daemon-local source or profile

For a github_repo resource, allow a local daemon to register a source checkout or environment profile associated with that repository.

The server would store only metadata such as:

• repository URL;
• daemon identifier;
• profile identifier;
• authorized relative paths.

The actual file contents would remain on the local machine.

Before starting the agent, the daemon would:

1. Create the usual isolated worktree.
2. Resolve the local profile.
3. Copy the paths permitted by .worktreeinclude.
4. Start the agent.
5. Remove those files before finalizing or cleaning up the worktree.

This would allow the repository to remain a normal github_repo resource while still using local configuration available only on the daemon.

Security and lifecycle requirements

Any implementation should:

• copy only explicitly authorized paths;
• reject symlinks and paths outside the configured source;
• avoid broad patterns such as .env*;
• keep file contents out of the Multica server, prompts, comments, logs, and transcripts;
• fail before provider startup when a required file is missing;
• prevent copied files from entering the resulting branch or commit;
• clean up temporary files after successful, failed, cancelled, or retried runs;
• clearly show which local profile is being used;
• keep profiles scoped to a specific daemon and repository resource.

For actual secrets, a future profile could resolve values from the local environment, the macOS Keychain, or another external secret manager without storing the value in Multica.

Alternative approaches

I see three possible directions:

1. Add .worktreeinclude support directly to Multica's local worktree preparation.
2. Add a daemon-local environment profile system that can materialize both files and process variables.
3. Add a trusted post-checkout hook that prepares dependencies and local configuration.

The first option is probably the smallest change. The second seems more extensible for repositories that need multiple environment variants and configuration that is not limited to files.

Questions for maintainers

1. Is support for including ignored files intentionally outside Multica's current scope?
2. Would adopting .worktreeinclude compatibility as a repository-level contract be reasonable?
3. Should the local source be associated with the github_repo resource rather than with the entire project?
4. Would a daemon-local environment profile be preferable to storing values in custom_env?
5. Is there currently any roadmap item, design, or pull request related to local environment materialization?
6. What security and cleanup guarantees would maintainers require before accepting such a feature?

I am primarily looking for architectural guidance before implementing anything. If this direction does not fit Multica's model, I would appreciate guidance on the intended workflow.

Related references

• Issue #6326: setup command after repository checkout
• Issue #4342: runtime- or workspace-level environment variables
• Pull request #6759: worktree mode for local directories