feat(workspace): turn workspaces on by default, with ALTIMATE_DISABLE_WORKSPACE as the kill switch

[sahrizvi]

Issue for this PR

No tracking issue. Workspaces leave the opt-in pilot.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Turns workspaces on by default. The opt-in flag ALTIMATE_WORKSPACE is retired (setting it now does nothing) and ALTIMATE_DISABLE_WORKSPACE=1 is the kill switch that turns every part of the feature off.

Because there is a kill switch, the old "pilot off" code is kept rather than deleted: every gate is inverted, so what used to run for non-pilot users now runs when the switch is set. That includes the hidden link / skill publish stubs, the 409 on the serve workspace routes, and the per-turn cleanup that takes already-synced workspace skills out of service. The five error messages that told users to "restart with ALTIMATE_WORKSPACE unset" to edit a workspace-managed MCP entry by hand now name the kill switch. The serve workspace routes' 409 now says "Workspaces are turned off on this server because ALTIMATE_DISABLE_WORKSPACE is set." instead of "Workspace mode is not enabled for this server."

What reaches every user signed in to Altimate with this change:

• Binding lookups. Each process asks the backend whether the project is linked: 2 requests (by git remote, then by project path) for an unlinked project, 1 for a project linked by remote. They send the origin URL (credentials stripped) and the absolute project path. The "not linked" answer is cached for 5 minutes in memory, so a long-running TUI or serve repeats it at most every 5 minutes, but every separate altimate-code run looks up once. A failed lookup (backend unreachable) is not cached, so it is retried every turn; the turn waits at most 2s for it.
• The post-scan workspace prompt during onboarding: after the first-launch scan gate's "Yes", a dialog offers to set up or link a workspace (Skip hides it for 7 days per project and account).
• The /workspace menu, the sidebar tile, link, skill publish, and the memory_refresh tool.

Users not signed in to Altimate make no workspace requests.

Other changes:

• test/preload.ts sets the kill switch for the whole suite, and the workspace tests clear it and restore it. This keeps the test environment as it was on main: with workspaces on by default, unrelated test files left background skill syncs running against the real network after their fetch stub was restored, which hung later tests. launch-resolve.test.ts now restores the switch instead of deleting it.
• New test/altimate/workspace/kill-switch.test.ts checks the default (unset means on), the switch, and that the retired variable is ignored. It fails if the old opt-in check is put back.
• Docs: usage/cli.md and configure/skills.md drop the pilot wording and document the switch.

Not in this PR: the CHANGELOG entry, which goes in the release PR as usual. It needs to say that workspaces are now on for everyone, including the lookup traffic above.

Known leftovers:

• Synced skills keep alwaysApply / applyPaths from their frontmatter, as they did in the pilot. With default-on, anyone who can upload a skill to a workspace can add standing instructions to every linked member's prompt. This was approved for the pilot and has been re-approved for this change; the note in skill-sync.ts is unchanged.

How did you verify your code works?

• Typecheck (packages/opencode, packages/core) and the strict altimate_change marker check pass.
• The 24 affected test files pass (824 tests). The full packages/opencode suite was run twice on this branch and once on main: no failures unique to this branch. flushPendingSyncs waits for a sync… fails on main too, and the run subprocess tests are flaky on both.
• End-to-end against a live account with a binary built from this branch, in both modes. Approach and results are in a comment below.

Screenshots / recordings

None; TUI checks were captured as text (see the E2E comment).

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_018fJ3X7pcGT4R9yzjsJnqsV

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sahrizvi]

End-to-end verification

Result: every check passed in both modes. Six areas were not exercised; they are listed at the end.

Approach

• Binary: built from this branch with bun run build:local (0.0.0-feat/workspace-on-by-default-202609291215). Not bun run from source.
• Backend: a live account, using that machine's real sign-in.
• Isolation: all CLI state (XDG_DATA_HOME, XDG_STATE_HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME) pointed at throwaway directories, so nothing touched the real install.
• Test project: a scratch git repo (a minimal dbt project) with a unique fake origin URL, so its lookups could never match an existing binding.
• Model: the default gateway model for every agent run, with run given < /dev/null.
• Network: requests counted with BUN_CONFIG_VERBOSE_FETCH=true, which logs every fetch the binary makes, with status codes.
• Interactive parts: link and the TUI were driven in tmux (send-keys / capture-pane).
• Both modes: each check was run with ALTIMATE_DISABLE_WORKSPACE unset and with it set to 1.

Results

#	Check	Default (switch unset)	ALTIMATE_DISABLE_WORKSPACE=1
1	CLI surface	link, skill publish and the TUI --workspace option are listed in --help	All three absent; link and skill publish print "Workspaces are turned off because ALTIMATE_DISABLE_WORKSPACE is set."
2	Signed in, project not linked	Agent answers "no workspace linked". Exactly 2 lookups per process: by git remote (sends the origin URL), then by path (sends the absolute project path)	—
3	link	Picker lists the account's workspaces; "Create a quick workspace" created and linked a new one	—
4	Linked project	Agent names the workspace. skill publish uploaded a test skill. "Remember this for the team: …" uploaded a memory block (create + update requests, both 200). A linked project needs 1 lookup (by remote)	—
4b	Teammate checkout	A fresh clone at a different path, with brand-new state and no local memory file, found the workspace through origin and got both the skill and the memory from it; the agent answered with facts only the workspace held	—
5	serve POST /altimate/workspace/refresh	200 {"ok":true,…}	409 "Workspace mode is not enabled for this server."
6	Linked project, switch set	—	No workspace requests at all (only model calls). The synced skill folder (.altimate-code/skill/_workspace) was removed on the first turn, the agent was not told about the workspace, and a memory write stayed local
7	Same project, switch unset again	Link, identity and synced skill all return	—
8	TUI	/workspace menu opens with Refresh / Sync / Open in browser / Switch / Unlink, and Sync uploaded the memory written while the switch was set. Sidebar tile shows the workspace, memory count and "skills synced just now". Post-scan prompt appears after the onboarding scan	No post-scan prompt after the same scan, no sidebar tile, /workspace gives "No matching items"

Findings

• The post-scan prompt is limited to onboarding. It fires only after the onboarding scan (/onboard-connect scan, which the first-launch scan gate's "Yes" submits), not after any project_scan. An ordinary "run project_scan" prompt did not trigger it.
• The binding-lookup cache lives only as long as the process. In a long-running TUI or serve a "not linked" answer is reused for 5 minutes. Every separate altimate-code run looks up again.
• The 409 message didn't name the kill switch ("Workspace mode is not enabled for this server."). Fixed in this PR after the run: it now says "Workspaces are turned off on this server because ALTIMATE_DISABLE_WORKSPACE is set.", and the route test asserts the exact text.
• Memory written with the switch set is not uploaded automatically once the switch is unset. /workspace → Sync uploads it, which is the intended path.

Not covered

• Warehouse engine setup, routing, and the "managed by workspace" MCP messages: the test workspace had no integrations, so the engine never ran. This needs a workspace with a warehouse integration and the engine installed.
• The --workspace <name> TUI launch flag: only its presence in --help was checked.
• The IDE-extension workspace pin on serve (ALTIMATE_PINNED_WORKSPACE_*).
• The first-launch scan gate dialog itself: the sandbox was not treated as a first run, so the command its "Yes" submits was entered directly. Everything after the gate is the same code path.
• The TUI skill-actions "publish" row: publishing was exercised through the CLI.
• The browser setup handoff.

Cleanup

The test project was unlinked through /workspace → Unlink, and a later run confirmed it reads as unlinked. The test workspace, the test skill and two test memory blocks remain in the account; the CLI has no delete for them.