🛤️ feat: Route Linked Worktree Requests into Per-Worktree Lanes

[danny-avila]

Summary

Agents that work in one registered checkout and give each task its own linked worktree (.worktrees/<task>) currently run their workspace calls one at a time, even when the paired worker has several free lease slots. Code API schedules workspace tools per registered root, so every read, write, search and command anywhere under a repository's .worktrees/* shares a single lane, and parallel chats working on different branches of the same repository queue behind each other.

LibreChat-AI/code-interpreter#270 adds linked-worktree lanes: a worker started with --linked-worktree-lanes advertises the git_linked_worktree workspace scope and accepts a worktree: <name> field that runs the request confined to <root>/.worktrees/<name>, scheduled beside its sibling worktrees instead of behind them. This PR is the LibreChat side. When the selected workspace advertises that scope, requests whose target sits inside .worktrees/<name>/ are sent to that worktree's lane, and every path in the result is returned with the .worktrees/<name>/ prefix restored, so the model keeps seeing checkout-relative paths.

Routing is opt-in per attached environment with configSchema.workspaces.linkedWorktrees: true in librechat.yaml; without it, requests stay scoped to the checkout even when the worker advertises lanes, so an administrator can turn it off without touching workers.

LibreChat must ship this before any worker advertises the scope: the status parser rejects unknown workspace descriptor keys, so an older LibreChat would treat an upgraded worker as invalid.

Related to LibreChat-AI/code-interpreter#268 and LibreChat-AI/code-interpreter#270.

How it works

Only structural targets are routed; anything whose reach cannot be bounded stays root-scoped and runs exactly as before:

read_file / write_file / edit_file / preview_edit   path   .worktrees/fix-a/src/x.ts  -> worktree fix-a, path src/x.ts
search_text / list_files                            path   .worktrees/fix-a[/sub]     -> worktree fix-a, path [sub]
list_files cursor                                   afterPath must be in the same worktree, or the request stays root-scoped
execute_command                                     cwd    .worktrees/fix-a[/sub]     -> worktree fix-a, cwd [sub]

stays root-scoped: root paths, `.worktrees` itself, invalid or `.lock` names, instruction-file reads,
conversation workspace instances, environment actions, and commands that `cd` into a worktree

executeWorkspaceTool gains a linkedWorktrees option. It validates the original request, maps it, computes budgets and validates the result against the mapped request, then restores the prefix on path, matches[].path, paths and nextAfterPath. Result validation therefore still rejects a lane result that escapes the requested worktree scope.

resolveCodeExecutionWorkspaceContext sets codeWorkspace.linkedWorktrees when the environment's configSchema.workspaces.linkedWorktrees is true, the workspace advertises git_linked_worktree, and no conversation workspace instance is active (the worker does not yet combine the two). The flag flows through the workspace file tools, the attached Bash tool and the model-facing tool definitions; /api passes it through unchanged and packages/api accepts only true. When lanes are on, the Bash cwd description tells the model to pass the worktree directory as cwd rather than cd inside the command, since only the former runs in parallel.

Type of change

• Feature

Testing

Tested environments/configuration:

• Unit level only. The end-to-end path needs a worker running code-interpreter#270 with --linked-worktree-lanes, which rolls out after this merges.

Automated tests:

• cd packages/api && npx jest src/code src/agents/handlers src/agents/execution: all pass.
• cd api && npx jest server/services/Files/Code server/services/ToolService: all pass.
• cd packages/api && npx tsc --noEmit: clean.
• Added workspace.lanes.spec.ts, covering each operation's mapping, every root-scoped case listed above, and prefix restoration.
• Added tests in:
  • workspace.spec.ts: the wire body carries worktree and the stripped path; paths come back prefixed; the request is unchanged without the flag; a lane result outside the worktree scope is rejected.
  • bridge.spec.ts: the scope is accepted, and malformed scope values are rejected.
  • config.spec.ts: the toggle accepts only a boolean.
  • tools.spec.ts and initialize.test.ts: the model-facing Bash definition describes worktree cwd routing only when lanes are on.
  • capabilities.spec.ts: lanes are enabled only when configured, advertised, and no conversation instance is active.
  • command.spec.ts: a worktree cwd is routed, and the schema describes it.
  • process.spec.js: the flag is forwarded.

Screenshots / recordings

No user-facing change.

Risk / compatibility

• The change is additive and negotiated. Nothing changes unless a worker advertises git_linked_worktree, and only Code API with code-interpreter#270 accepts the worktree field.
• Rollout order: this PR, then Code API, then workers opting in per machine, then configSchema.workspaces.linkedWorktrees: true on the environments that should route lanes.
• A command that cds into a worktree from the root stays root-scoped. It is still correct, but it waits for every lane in that checkout.

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-29T04:14:14.822173Z	e6f9f36	Manual request

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0914b6df9f

ℹ️ 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".

[danny-avila]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c2d2c20d5

ℹ️ 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".

[danny-avila]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 265cb5d6f5

ℹ️ 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".

[danny-avila]

@codex review

This is the final review for this PR (cycle 4 of 4) of head e6f9f36. Please flag only blocking issues: correctness, security, or data loss.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: e6f9f366cb

ℹ️ 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".