🌳 feat: Provision Conversation-Scoped Code Worktrees

[danny-avila]

Problem and behavior

Multiple conversations using one attached repository currently share one scheduling boundary and checkout. This adds opt-in conversation checkouts: operations within a conversation remain serialized, while independent conversations use the worker's bounded execution slots without sharing writable Git metadata or files.

The worker and Code API negotiate git_worktree support. LibreChat supplies an opaque conversation identity; Code API binds it to the authenticated tenant and user before admission. That identity survives programmatic replay and continuation, signed bridge payloads, executor selection, quarantine, and reset. Requests without it retain their existing behavior.

Provisioning and recovery

• Sources are operator-admitted Git repositories with pinned filesystem identities. Each conversation gets a deterministic branch in an independent clone, with its own Git objects and no source alternates or hardlinks.
• Git/common/object-store identities are pinned separately from the working directory and bound into durable records. Descriptor-relative, no-follow reads create a private Git-data snapshot before any Git process runs. Source hooks/config includes/alternate pointers cannot redirect privileged Git reads. Snapshot copying shares the clone deadline; private staging is removed before setup.
• Owner-controlled storage has a configurable checkout-count quota. A kernel lock serializes provisioning across processes and releases on process exit. Clone time has a separate bounded budget.
• Cancellation reaches lock waits, Git children, and environment setup. The operation waits for child cleanup before releasing ownership; it cannot leave detached setup running after the caller returns.
• A durable reservation is written before launching Git or setup, so a worker crash cannot cause recovery to delete a checkout still owned by a child process. Repository-bound GitHub credentials are installed before setup. Setup completes before the record transitions to ready. Failed provisioning retires its executor before deleting the directory; uncertain cleanup reserves the checkout across restart.
• Recovery removes only recognizable unfinished managed checkouts. Completed checkouts with changed source provenance or invalid completion records are preserved, including uncommitted work. Unrelated directories are never swept.
• Cached file/native executors revalidate root identity. Legacy quarantine keys remain compatible, while instance identities use a disjoint namespace.
• Sidecar-only reservations consume capacity even when the checkout directory never appeared. Cached checkouts revalidate metadata containment, and native executors have no extra Git-object read grant. Embedded workers must provide an instance guard resolver before advertising instances.

The worker option and recovery procedure are documented in packages/code/README.md. This is the Code API/worker foundation for Agents #548 and LibreChat #16107. Operators must enable conversation checkout storage and bounded lease slots to use the capability.

Cold clone/setup work is also bounded by the triggering operation's execution deadline. The clone timeout is an upper bound, not an extension of that deadline. Environments with long setup commands should initialize via a command with a sufficient configured timeout before ordinary file operations.

Verification

• Worker TypeScript build passes.
• Latest security pass: 52 focused local tests across provisioning/routing (33), native pool (8), instance guards (2), sandbox policy (1), native bootstrap (1), and concurrent-worker service integration (7). Regression cases include source replacement after validation, sidecar-only restart, cached object redirection, metadata changes across restart/setup, staging cancellation, linked source worktrees, and SHA-256 Git repositories.
• A local canary with real native executor processes passed: two conversation checkouts concurrently wrote different contents to the same relative filename, the source checkout remained unchanged, and aborting a running shell prevented its delayed write (checked beyond the command's sleep duration).
• Focused Code API admission, replay-state, principal identity, and HTTP ingress tests pass. Same-instance serialization and independent-instance progress are covered.
• Full suites and Node 20/22/24 compatibility run in CI.

The follow-up security review correctly found gaps missed by the prior self-review. Those worker findings are addressed in f255141135e7636c106d506f47cf67b0e4e0dc1f, with focused regressions and a repeated native canary. No additional automated review was requested. LibreChat #16107 is draft: Agents #548 must be merged/released and the actual release pinned before the integration can ship. This PR alone does not establish cross-stack PTC rollout readiness.

[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-20T00:12:52.367763Z	e1804e5	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: 5f6031ba36

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

[danny-avila]

@codex review

[danny-avila]

@codex review

[danny-avila]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa5cdfdd91

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

Please review the current PR head 614a29a. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

[danny-avila]

@codex review

Please review the current PR head 80bb7b9. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 80bb7b980f

ℹ️ 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: a0f2423e14

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

Please review the current PR head a0f2423. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

[danny-avila]

@codex review

Please review the current PR head a7bd224. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a7bd224904

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

Please review the current PR head 4ccdc02. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4ccdc020fc

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

Please review the current PR head fbdb794. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fbdb79443d

ℹ️ 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]

Update: the later security review correctly found gaps in this audit. Four worker findings are fixed in f255141135e7636c106d506f47cf67b0e4e0dc1f: race-safe Git-data staging with pinned metadata identity, removal of redundant object read grants and cached metadata validation, sidecar-only quota accounting, and required per-instance guards. Added transition regressions and reran the real native concurrency/cancellation canary successfully. LibreChat #16107 has been restored to draft pending the Agents release and lockfile pin. No new bot review requested. The prior audit below describes the earlier head, not proof of readiness for the full stack.

Previous ownership/recovery audit: e1804e543f10e1df49cd4b831047d4e204dbd234.

The recurring review findings pointed to one ownership invariant: identity, cancellation, durable state, and executor cleanup must agree on when a checkout becomes usable and when it can be discarded. I traced both ingress paths, replay state and signed payloads, admission/fencing, worker execution, provisioning, setup credentials, and restart recovery.

Additional fixes from this audit:

• Completed checkouts with changed source provenance or invalid records are preserved; recovery no longer silently deletes their uncommitted work.
• Lock waits, Git children, and setup retain the caller's cancellation signal. Cancellation waits for actual cleanup rather than leaving detached provisioning behind after settlement.
• Failed setup retires its executor before directory removal. Unconfirmed cleanup reserves the checkout across restart and consumes quota until operator recovery.
• A durable reservation is written before launching any Git or setup writer. Killing the worker during provisioning cannot make recovery sweep a directory that may still have a live child process.
• Cleanup only sweeps recognizable managed paths. Cached instances revalidate their admitted source. Principal identities use an unambiguous tuple encoding.

Local verification: 32 focused lifecycle tests, 2 CLI/process checks, focused service identity/admission/replay tests, and a passing TypeScript build. A real native-worker canary on macOS also passed concurrent same-filename writes in two isolated checkouts, unchanged source files, and cancellation with no delayed mutation, rerun on the final build. Real child-process tests prove lock release after a crash and preservation of a checkout reserved by a killed provisioning process.

The graph matches the pre-audit PR SHA but has no compiler-level call edges for this repo/ref. Available references were reconciled with source searches; the authoritative selector returned HTTP 401, so local test selection was source-based. Full suites run in CI.

All existing Codex threads are addressed. No new bot review requested for this final self-review pass.

[danny-avila]

@codex review the latest head

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e1804e543f

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