Skip to content

docs(roadmap): add per-mount isolation proposal#116

Merged
donbeave merged 1 commit into
mainfrom
claude/brainstorm-feature-EqZba
Apr 21, 2026
Merged

docs(roadmap): add per-mount isolation proposal#116
donbeave merged 1 commit into
mainfrom
claude/brainstorm-feature-EqZba

Conversation

@donbeave

@donbeave donbeave commented Apr 21, 2026

Copy link
Copy Markdown
Member

Summary

Adds a roadmap design doc for per-mount isolation — a declarative way to stop parallel agents from sharing one working tree.

  • New page at docs/src/content/docs/reference/roadmap/per-mount-isolation.mdx — problem, proposed TOML shape, composition rules, host-side materialization, lifecycle, v1 scope, open questions, related files
  • Registered under Roadmap → Open items in docs/astro.config.ts
  • Cross-linked from the roadmap overview under a new Workflow improvements section

Proposed shape (in the doc)

[workspaces.jackin]
default_isolation = "worktree"   # applies to every mount that doesn't override

[[workspaces.jackin.mounts]]
src = "~/projects/jackin"
dst = "/workspace/jackin"
# inherits → "worktree"

[[workspaces.jackin.mounts]]
src = "~/projects/jackin-docs"
dst = "/workspace/jackin-docs"
isolation = "shared"             # reference repo, don't fork it

Modes: shared (today's behavior, default), worktree (per-agent git worktree), clone (per-agent git clone --local --shared). Existing workspaces keep working unchanged.

Not included

No code changes — this PR is docs-only. Implementation will be a follow-up.

Test plan

  • bun run build in docs/ succeeds
  • New page renders under Reference → Roadmap → Open items
  • Cross-link from reference/roadmap.mdx resolves
  • No broken links from the sidebar entry

Notes

  • Pre-commit cargo fmt passes. cargo clippy --all-targets -- -D warnings reports 24 pre-existing errors on the branch baseline (reproduced by stashing this PR's changes) — unrelated to this docs-only diff.
  • cargo-nextest is not installed in this environment; no Rust behavior changed here.

https://claude.ai/code/session_01YNGGAFytqtVhECN1y1Bit1

@claude
docs(roadmap): add per-mount isolation proposal
6db42af 
Design doc for declarative isolation modes (shared | worktree | clone)
per mount, with a workspace-level default, to stop parallel agents
sharing one working tree. Registers the page under Roadmap → Open items
and cross-links it from the Workflow improvements section of the
roadmap overview.

https://claude.ai/code/session_01YNGGAFytqtVhECN1y1Bit1
@donbeave donbeave merged commit 91a96dd into main Apr 21, 2026
4 checks passed
@donbeave donbeave deleted the claude/brainstorm-feature-EqZba branch April 21, 2026 18:57
@donbeave donbeave mentioned this pull request Apr 24, 2026
Merged
3 tasks
donbeave added a commit that referenced this pull request Apr 24, 2026
@donbeave @claude
docs(roadmap): finalize per-mount isolation v1 requirements (#165)
1978be6 
Finalizes v1 requirements for per-mount isolation (from #116) after a
full decision sweep. Still docs-only — no implementation.

User-facing decisions:
- Back-merge is upstream only (GitHub PR via existing tooling). No
  jackin diff / jackin integrate / merge commands.
- Dirty host tree warns and requires --force (cold path since operators
  launch from clean trees).
- Hooks inherit from the host repo; no --no-hooks flag in v1.
- Branch name hardcoded as jackin/<container>; base = host HEAD. No
  configurable branch_template or base_branch.
- Worktree at <data_dir>/jackin-<container>/isolated/<slug>/.
- jackin cd <container> for navigation.

Scope trims:
- Drop default_isolation. isolation is per-mount only, explicit.
- Drop isolation on global mounts entirely (workspace-scoped only).
- Drop --delete-branches flag on purge; purge silently deletes
  everything, including the local scratch branch.

Correctness:
- Pre-flight validation scoped per isolation type; only checks cases
  where git would silently do the wrong thing (subdir misrouting,
  mid-rebase HEAD).
- Purge refuses on running agents (fixes a pre-existing gap where
  remove_data_dir_if_exists ran unconditionally).
- Enable extensions.worktreeConfig on first worktree creation per host
  repo so per-worktree config writes don't leak to shared .git/config.
- Mount mode flipped between loads: orphan isolated/ dir left in place,
  reclaimed by jackin purge. No auto-prune.

Known limitations documented: submodules/LFS inherit parent-repo
behavior; shared .git/config for remotes/credentials/non-worktree
writes (git limitation); -clone-N naming collision to resolve when
clone mode ships.

Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 6, 2026
@donbeave @claude
docs(roadmap): add per-mount isolation proposal (#116)
9e899ff 
Design doc for declarative isolation modes (shared | worktree | clone)
per mount, with a workspace-level default, to stop parallel agents
sharing one working tree. Registers the page under Roadmap → Open items
and cross-links it from the Workflow improvements section of the
roadmap overview.

https://claude.ai/code/session_01YNGGAFytqtVhECN1y1Bit1

Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 6, 2026
@donbeave @claude
docs(roadmap): finalize per-mount isolation v1 requirements (#165)
a4db4e8 
Finalizes v1 requirements for per-mount isolation (from #116) after a
full decision sweep. Still docs-only — no implementation.

User-facing decisions:
- Back-merge is upstream only (GitHub PR via existing tooling). No
  jackin diff / jackin integrate / merge commands.
- Dirty host tree warns and requires --force (cold path since operators
  launch from clean trees).
- Hooks inherit from the host repo; no --no-hooks flag in v1.
- Branch name hardcoded as jackin/<container>; base = host HEAD. No
  configurable branch_template or base_branch.
- Worktree at <data_dir>/jackin-<container>/isolated/<slug>/.
- jackin cd <container> for navigation.

Scope trims:
- Drop default_isolation. isolation is per-mount only, explicit.
- Drop isolation on global mounts entirely (workspace-scoped only).
- Drop --delete-branches flag on purge; purge silently deletes
  everything, including the local scratch branch.

Correctness:
- Pre-flight validation scoped per isolation type; only checks cases
  where git would silently do the wrong thing (subdir misrouting,
  mid-rebase HEAD).
- Purge refuses on running agents (fixes a pre-existing gap where
  remove_data_dir_if_exists ran unconditionally).
- Enable extensions.worktreeConfig on first worktree creation per host
  repo so per-worktree config writes don't leak to shared .git/config.
- Mount mode flipped between loads: orphan isolated/ dir left in place,
  reclaimed by jackin purge. No auto-prune.

Known limitations documented: submodules/LFS inherit parent-repo
behavior; shared .git/config for remotes/credentials/non-worktree
writes (git limitation); -clone-N naming collision to resolve when
clone mode ships.

Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude @codex
docs(roadmap): add per-mount isolation proposal (#116)
726d80e 
Design doc for declarative isolation modes (shared | worktree | clone)
per mount, with a workspace-level default, to stop parallel agents
sharing one working tree. Registers the page under Roadmap → Open items
and cross-links it from the Workflow improvements section of the
roadmap overview.

https://claude.ai/code/session_01YNGGAFytqtVhECN1y1Bit1

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude @codex
docs(roadmap): finalize per-mount isolation v1 requirements (#165)
8c5cf19 
Finalizes v1 requirements for per-mount isolation (from #116) after a
full decision sweep. Still docs-only — no implementation.

User-facing decisions:
- Back-merge is upstream only (GitHub PR via existing tooling). No
  jackin diff / jackin integrate / merge commands.
- Dirty host tree warns and requires --force (cold path since operators
  launch from clean trees).
- Hooks inherit from the host repo; no --no-hooks flag in v1.
- Branch name hardcoded as jackin/<container>; base = host HEAD. No
  configurable branch_template or base_branch.
- Worktree at <data_dir>/jackin-<container>/isolated/<slug>/.
- jackin cd <container> for navigation.

Scope trims:
- Drop default_isolation. isolation is per-mount only, explicit.
- Drop isolation on global mounts entirely (workspace-scoped only).
- Drop --delete-branches flag on purge; purge silently deletes
  everything, including the local scratch branch.

Correctness:
- Pre-flight validation scoped per isolation type; only checks cases
  where git would silently do the wrong thing (subdir misrouting,
  mid-rebase HEAD).
- Purge refuses on running agents (fixes a pre-existing gap where
  remove_data_dir_if_exists ran unconditionally).
- Enable extensions.worktreeConfig on first worktree creation per host
  repo so per-worktree config writes don't leak to shared .git/config.
- Mount mode flipped between loads: orphan isolated/ dir left in place,
  reclaimed by jackin purge. No auto-prune.

Known limitations documented: submodules/LFS inherit parent-repo
behavior; shared .git/config for remotes/credentials/non-worktree
writes (git limitation); -clone-N naming collision to resolve when
clone mode ships.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @codex
docs(roadmap): add per-mount isolation proposal (#116)
8b898f8 
Design doc for declarative isolation modes (shared | worktree | clone)
per mount, with a workspace-level default, to stop parallel agents
sharing one working tree. Registers the page under Roadmap → Open items
and cross-links it from the Workflow improvements section of the
roadmap overview.

https://claude.ai/code/session_01YNGGAFytqtVhECN1y1Bit1

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude
docs(roadmap): finalize per-mount isolation v1 requirements (#165)
82450a4 
Finalizes v1 requirements for per-mount isolation (from #116) after a
full decision sweep. Still docs-only — no implementation.

User-facing decisions:
- Back-merge is upstream only (GitHub PR via existing tooling). No
  jackin diff / jackin integrate / merge commands.
- Dirty host tree warns and requires --force (cold path since operators
  launch from clean trees).
- Hooks inherit from the host repo; no --no-hooks flag in v1.
- Branch name hardcoded as jackin/<container>; base = host HEAD. No
  configurable branch_template or base_branch.
- Worktree at <data_dir>/jackin-<container>/isolated/<slug>/.
- jackin cd <container> for navigation.

Scope trims:
- Drop default_isolation. isolation is per-mount only, explicit.
- Drop isolation on global mounts entirely (workspace-scoped only).
- Drop --delete-branches flag on purge; purge silently deletes
  everything, including the local scratch branch.

Correctness:
- Pre-flight validation scoped per isolation type; only checks cases
  where git would silently do the wrong thing (subdir misrouting,
  mid-rebase HEAD).
- Purge refuses on running agents (fixes a pre-existing gap where
  remove_data_dir_if_exists ran unconditionally).
- Enable extensions.worktreeConfig on first worktree creation per host
  repo so per-worktree config writes don't leak to shared .git/config.
- Mount mode flipped between loads: orphan isolated/ dir left in place,
  reclaimed by jackin purge. No auto-prune.

Known limitations documented: submodules/LFS inherit parent-repo
behavior; shared .git/config for remotes/credentials/non-worktree
writes (git limitation); -clone-N naming collision to resolve when
clone mode ships.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @codex
docs(roadmap): add per-mount isolation proposal (#116)
3f8fd7c 
Design doc for declarative isolation modes (shared | worktree | clone)
per mount, with a workspace-level default, to stop parallel agents
sharing one working tree. Registers the page under Roadmap → Open items
and cross-links it from the Workflow improvements section of the
roadmap overview.

https://claude.ai/code/session_01YNGGAFytqtVhECN1y1Bit1

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude
docs(roadmap): finalize per-mount isolation v1 requirements (#165)
40a08f8 
Finalizes v1 requirements for per-mount isolation (from #116) after a
full decision sweep. Still docs-only — no implementation.

User-facing decisions:
- Back-merge is upstream only (GitHub PR via existing tooling). No
  jackin diff / jackin integrate / merge commands.
- Dirty host tree warns and requires --force (cold path since operators
  launch from clean trees).
- Hooks inherit from the host repo; no --no-hooks flag in v1.
- Branch name hardcoded as jackin/<container>; base = host HEAD. No
  configurable branch_template or base_branch.
- Worktree at <data_dir>/jackin-<container>/isolated/<slug>/.
- jackin cd <container> for navigation.

Scope trims:
- Drop default_isolation. isolation is per-mount only, explicit.
- Drop isolation on global mounts entirely (workspace-scoped only).
- Drop --delete-branches flag on purge; purge silently deletes
  everything, including the local scratch branch.

Correctness:
- Pre-flight validation scoped per isolation type; only checks cases
  where git would silently do the wrong thing (subdir misrouting,
  mid-rebase HEAD).
- Purge refuses on running agents (fixes a pre-existing gap where
  remove_data_dir_if_exists ran unconditionally).
- Enable extensions.worktreeConfig on first worktree creation per host
  repo so per-worktree config writes don't leak to shared .git/config.
- Mount mode flipped between loads: orphan isolated/ dir left in place,
  reclaimed by jackin purge. No auto-prune.

Known limitations documented: submodules/LFS inherit parent-repo
behavior; shared .git/config for remotes/credentials/non-worktree
writes (git limitation); -clone-N naming collision to resolve when
clone mode ships.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@donbeave @claude