feat(workspace): expose `/workspace` Refresh and Sync over `serve` HTTP

Merged
SA
2mo ago
+550-2

Issue for this PR

No public issue — the IDE-side consumer of these routes is the extension's /workspace chat command.

Type of change

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

What does this PR do?

The /workspace menu's Refresh and Sync (#1278) live only in the TUI. The VS Code / Cursor extension runs altimate-code serve headless, so it has no way to reach them — manage.ts already anticipates an HTTP caller, but the route was never written.

Separately, Manage.sync read only the on-disk link, so under an extension pin (#1320) it answered no-binding for the very workspace the process was pinned to, while the per-write memory mirror (pin-aware) was sending to it.

  • POST /altimate/workspace/refresh — body { sessionID? }, returns Manage.RefreshReport plus ok: true. With a session the memory overlay reloads in place; without one it is invalidated for the next turn. A changed skill snapshot is picked up by the existing per-turn refreshSkillRegistry.
  • POST /altimate/workspace/sync — returns Manage.SyncReport plus ok: true.
  • Both refuse with 409 { ok: false, error } when ALTIMATE_WORKSPACE is off (a skill sync with the flag off purges the snapshot), refuse a browser Origin with 403 (any origin on an unsecured server; cross-origin when a password is set), and report thrown errors as 500 { ok: false, error }.
  • Refresh validates its input rather than falling back to a session-less refresh (which resets every session's overlay):
    • malformed or non-object body → 400
    • sessionID present but not a non-empty string → 400
    • unknown session → 404
    • a session from another project directory → 400
    • 409 is reserved for the pilot gate, so a caller can act on the status alone
  • Manage.sync layers the pin arm (resolvePinnedBindingForRouting, the same one #1357 uses) ahead of the cache read. Unpinned sessions keep the cache-only path. A pin that cannot be honoured stays gated as pin-unresolved, distinct from no-binding, rather than falling through to the project's link.

Unlink, status and skill publish are intentionally not exposed yet.

How did you verify your code works?

  • test/server/altimate-workspace-routes.test.ts — flag gate, origin refusal, body validation, session passthrough, report shape, error mapping (22 tests).
  • test/altimate/workspace/manage-pin.test.ts — sync under a pin: never-linked project, pin outranks link, invisible workspace and directory outside the pinned root gate as pin-unresolved, unpinned path unchanged (6 tests). The pin cases fail on main.
  • bun test test/altimate/workspace test/server: all new tests pass; the remaining failures (mcp HttpApi ×2, experimental HttpApi, flushPendingSyncs, one flaky TUI test) fail identically on main.
  • End to end: built linux-arm64, ran serve pinned to a live workspace from the extension's code-server container:
POST /altimate/workspace/sync     → {"ok":true,"gated":false,"sent":0,"failed":0,"skipped":0,"declined":0,"deferred":0}
POST /altimate/workspace/refresh  → {"ok":true,"skillsChanged":true,"memoryInvalidated":true,"errors":[]}
                                     (.altimate-code/skill/_workspace/ populated)
unpinned serve, POST …/sync       → 409 {"ok":false,"error":"Workspace mode is not enabled for this server."}
refresh, body "{bad"              → 400 {"ok":false,"error":"Request body is not valid JSON."}
refresh, own session              → 200 {…,"memory":{"count":1,"ok":true,"status":"loaded"},…}
refresh, unknown session          → 404
refresh, sessionID 42             → 400
sync with Origin header            → 403

The no-Origin calls above were made with code-server's own Node 24 fetch, the runtime the extension host uses.

Screenshots / recordings

The extension side (a /workspace refresh|sync chat command, handled locally like /mcps):

/workspace sync and refresh in the extension chat

Checklist

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

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Workspace sync uses the pinned IDE workspace when available, even if the project has a different local workspace link.
    • If the pinned workspace cannot be confirmed for the project, sync is gated and reports that nothing was synced.
    • Workspace refresh and sync endpoints return operation results or clear error responses. Refresh requests can include a session ID.
  • Bug Fixes
    • Refresh requests reject invalid session IDs and sessions that do not belong to the current project.
    • Browser requests from a different origin are blocked; browser requests to an unsecured server are also refused.