feat(stack): isolate sibling worktrees and named stacks (CLI-2107)

[jgoux]

Implements CLI-2107: extends the managed-state baseline (#6152) so linked worktrees, ordinary Git checkouts, bare-repository worktrees, branches, and named stacks coexist without sharing mutable runtime state. All identity and isolation policy lives in @supabase/stack/managed; no CLI handler changes.

Git identity storage

• Workspace inspection (managed/git.ts): classifies primary checkouts, linked worktrees, bare-repo worktrees, and ordinary folders by parsing Git metadata files directly (.git file/dir, commondir, HEAD) — read-only inspection performs zero writes and needs no git binary. Repositories using the reftable ref backend are refused with a typed UnsupportedGitWorkspaceError instead of silently collapsing branch contexts (their HEAD compat stub always names refs/heads/.invalid).
• Project ID lives in common-scope git config (supabase.projectId in <commonDir>/config), so all linked worktrees — including worktrees of a bare repository with no primary worktree — share it, and a fresh git clone receives new identity for free (clone copies no config).
• Checkout ID lives in a versioned JSON marker under each checkout's own git directory (<gitDir>/supabase-checkout.json), so every worktree is an independent checkout.
• Branch context IDs live in branch.<name>.supabaseContextId (common scope): worktrees on the same branch share a context, git branch -m carries the ID with the section rename, and branch deletion orphans the context without touching stack data.
• Config claims use append-and-adopt-first-value (git config --add, re-read, adopt the immutable first value, idempotent collapse) with lock-contention retries — a plain set-then-reread protocol demonstrably loses claims under concurrency.
• Identity is never inferred from remotes, branch names, commits, basenames, or path hashes.

Registry schema v4

Branch contexts are project-scoped; detached and workspace contexts are checkout-scoped (partial unique index per checkout). Checkouts record their kind, and each checkout has exactly one canonical location keyed to the checkout root (starting from a nested subdirectory resolves and reuses the same location). The live-stack uniqueness keystone (checkout_id, context_id, name) is unchanged. The registry file is now registry-v4.sqlite3; as with v3, this unreleased POC has no data-migration path.

resolveStack

resolveStack({ workspacePath, stackName?, operation: "start" | "status" }) is the single identity/decision path — provisionOrdinaryStack/inspectOrdinaryWorkspace are folded in, not layered over. status is strictly read-only (no markers, no config keys, no registry rows); start ensures identities and provisions through the existing pending→publish/operation-claim machinery. Interrupt-safety around claim creation was tightened so an op-boundary interrupt cannot leak a pending stack with a live operation claim. Stack names are validated as lowercase DNS labels before any write. deleteStack/updateStack/inspectStack/listStacks remain global-by-opaque-ID with no workspace resolution required, and projections now expose full IDs, checkout kind/path, context kind/branch locator, ports, and lifecycle so every sibling instance is deterministically distinguishable.

Fixtures made executable

The CLI-2102 worktree, bare-repo, named-stack, stack-name, and reclamation fixtures in managed-stack-contract.ts are now driven through the real service against both registry adapters using real git repos/worktrees in temp dirs. Symbolic fixture IDs are checked as equality/inequality relations (shared symbol ⇒ same real UUID, distinct symbols ⇒ distinct UUIDs), so editing fixture data changes test behavior. A three-sibling end-to-end proof (two worktrees + one named stack) shows distinct data roots and ports, and that a global delete-by-ID leaves the survivors' records, ports, and data untouched.

Reviewer notes

• when actions expressed as CLI argv in fixtures are driven through their managed-API equivalents; CLI command wiring and human/JSON rendering are later issues, per the issue's implementation boundary.
• Duplicate-copy claims, branch-copy collisions, and moved-worktree recovery remain with CLI-2108.
• The fixture identity.valid-stack-names-resolve-deterministically names a resolveStackNames method that does not exist; it is honestly expressed as per-name read-only resolveStack calls (zero-write witnessed). A fixture cleanup could rename the method or add the missing stack given-facts.
• Pre-existing (at HEAD, not introduced here): a failed managed-service handle acquisition leaks the opened SQLite handle; tracked as a follow-up outside this PR.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:cf6784a221

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@91d8f4812ee53751deb73840f2143f48c36a233e

Preview package for commit 91d8f48.

[jgoux]

Round-2 review response (external review, commit 2b660c7):

Fixed — git config subsection/precedence parsing (P2).[core "fake"] no longer leaks into [core], and the line scan now applies git's last-value-wins precedence. The reviewer's repro ([core "fake"] bare=true + [core] bare=false classifying as bare-worktree) is a regression test, plus last-wins and reftable-detection sanity cases.

Fixed at the package boundary — runtime stack identity (P1).StackConfig gains an opaque instanceId; when present, container names derive from it instead of the API port and every container carries a com.supabase.stack-id label (port-derived naming is byte-identical when omitted, so the direct ephemeral API is unchanged). This is the "core runtime receives one resolved opaque stack identity" seam from CLI-2107, and it removes the stale port-derived container-name collision between sibling stacks. The identity flows through the daemon config path already, so the later CLI wiring issue only needs to pass resolveStack's stackId at the call site. Deliberately NOT in this PR: CLI commands consuming resolveStack, and live-container crash/stop proofs — those belong to the CLI wiring issues and the CLI-2116 three-worktree dogfood, per the issue's implementation boundary ("CLI callers consume the managed result"). The label is write-only for now; global reclamation by label is part of that follow-up.

Fixed — stale docs count (P3).architecture.md no longer hardcodes the failure-class count, and the cleanup section documents the identity-or-port naming key and label.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:2b660c761f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jgoux]

Round-3 review batch (commit 5abc0d5) — three accepted P2 findings, handled as one closed batch:

1. instanceId validation: rejected at config resolution unless it matches a Docker-name-safe token (/^[a-z0-9][a-z0-9-]{0,63}$/i; managed stack UUIDs pass). The "../bad:id" repro is a regression test; rejection over encoding, per the reviewer's suggestion.
2. Quoted git-config values: configValue now strips outer double quotes (minimal \"/\\ unescape) after comment-stripping, so bare = "true", quoted refStorage, and quoted worktreeConfig read as git reads them. Each repro is a regression test.
3. Telemetry cause discriminant: UnsupportedGitWorkspaceError carries a closed cause union (inside-git-directory | malformed-metadata | reftable) set at every raise site; the CLI actionability table branches on it to emit managed_git_workspace_<cause> fingerprints — one error code kept, no message parsing.

Also per the review: the bot's .git/commondir path-traversal containment suggestion is rejected — following git's metadata pointers is required for legitimate separate git dirs and worktrees, and the proposed containment has no sound trust boundary.

This closes the approved batch; no further automated fix rounds planned on this PR.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:5abc0d51b3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:21d1e05ec1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:b30131fd30

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[avallete]

Review (round 4, human-directed)

Overall assessment: the implementation is sound. I verified the isolation design end to end on the branch: workspace classification reads git metadata directly with typed refusals for every malformed shape, identity claims use append-and-adopt-first-value under git's config lock (the collapse provably preserves the first value under every interleaving I could construct), the v4 schema's scoping rules (project-scoped branch contexts, partial-unique checkout-scoped contexts) are enforced in both adapters and exercised by the same contract fixtures, and registerStack's claim creation is correctly inside the uninterruptible mask with interruption re-raised rather than reported as failure. The runtime instanceId seam is byte-identical for callers that omit it, and nothing in the CLI passes it yet, so there is no user-visible behavior change. The three Codex rounds plus the depthfirst findings were all either fixed with regression tests or rejected with sound reasoning — I agree with both rejections (the .git/commondir containment rule would refuse legitimate --separate-git-dir and worktree topologies, and the git branch -c copy case genuinely needs CLI-2108's re-keying semantics).

check:all passes for packages/stack and apps/cli. One finding from running the suite locally:

SIGNIFICANT (DX / test portability) — the reftable fixture requires git ≥ 2.45 with no guard

git.integration.test.ts ("refuses a repository whose refs are stored in a reftable", line ~424) runs git init --ref-format=reftable unconditionally. --ref-format was added in git 2.45; on stock git 2.43 (Ubuntu 24.04 LTS default, and the remote dev containers this repo's sessions run in — where I reproduced it) the helper throws and pnpm test:core in packages/stack is red out of the box: 1 failed | 303 passed. CI is green only because the runners carry a newer git, so the failure lands on exactly the machines contributors use. Given the repo policy that a failing check in a changed workspace belongs to whoever runs it, this test will mislead the next contributor into debugging "their" failure.

Smallest fix: probe once at module scope (attempt git init --ref-format=reftable in a temp dir, or parse git --version ≥ 2.45) and it.skipIf(!supportsReftable) this one test. The two config-declared reftable refusal tests above it don't need a real reftable repo and keep covering the extensions.refStorage path on old git; only the .invalid HEAD-stub tripwire coverage would be conditionally skipped.

NON-BLOCKING OBSERVATIONS

• Registry v4 leaves registry-v3.sqlite3 and its stacks' data roots orphaned on disk. Acknowledged unreleased-POC policy, just noting the stale file is never cleaned up either.
• Branch-copy context sharing (git branch -c copying supabaseContextId) stays deferred to CLI-2108 per the resolved P1 thread; the deferral is documented in the PR description, which is the right place for it.

Verdict: Approve with non-blocking comments — the reftable test guard is worth fixing in this PR since it's a five-line change to a file the PR adds, but CI is green and it doesn't affect shipped behavior.

---

Generated by Claude Code

[avallete]

The one finding (SIGNIFICANT, DX / test portability)

Running the suite locally: 1 failed | 303 passed. The new reftable test at packages/stack/src/managed/git.integration.test.ts:424 runs git init --ref-format=reftable unconditionally, but --ref-format needs git ≥ 2.45. This environment has git 2.43 (same as stock Ubuntu 24.04 LTS), so pnpm test:core is red out of the box on common contributor machines — CI passes only because runners ship newer git. Smallest fix: probe reftable support once and it.skipIf that single test; the two config-declared reftable tests above it don't need a real reftable repo and keep their coverage on old git.

I also noted two non-blocking observations in the review: the orphaned registry-v3.sqlite3 file (accepted no-migration POC policy) and the CLI-2108 deferral being properly documented. I posted the review as a COMMENT rather than a formal approval since the author declared the automated fix loop closed — the reftable guard is a five-line change worth making in this PR, but it doesn't block merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:91d8f4812e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Verify detached HEAD resolves to a commit

When HEAD contains a syntactically valid 40- or 64-digit hex value that is absent from the object database—or names a non-commit object—this branch reports a valid detached context and allows start to claim identities and register a stack. Git rejects such a checkout; I reproduced the absent-object case with git status exiting 128 with fatal: bad object HEAD. Validate that the object exists and is a commit before returning this detached-head result, otherwise classify it as UnsupportedGitWorkspaceError with malformed-metadata.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Recheck tombstones before reporting stack reuse

When a concurrent deleteStack claims and tombstones this stopped stack after prepareStack returned the stale active record but before requireProjection runs, this branch still reports a successful reuse. The returned stack projection is then tombstoned while stacks excludes it, so one resolution contradicts itself and tells the caller that start settled on a deleted stack. Revalidate the projected status or retry registration when the previously active row has become tombstoned.

Useful? React with 👍 / 👎.