Skip to content

fix(codex): canonicalize project identity for git worktrees - #530

Closed
Lubrsy706 wants to merge 6 commits into
rohitg00:mainfrom
Lubrsy706:fix/515-codex-worktree-project
Closed

Lubrsy706 wants to merge 6 commits into
rohitg00:mainfrom
Lubrsy706:fix/515-codex-worktree-project

Conversation

@Lubrsy706

@Lubrsy706 Lubrsy706 commented May 19, 2026 •

Copy link
Copy Markdown

Summary

  • canonicalize session project identity to the main git repo root on session start while preserving the actual cwd
  • reuse the shared git worktree detector for branch-aware project metadata
  • let context/search project matching include canonical project, cwd, worktree top-level, main repo root, and project-name aliases so existing worktree-scoped memory can still surface

Fixes #515

Tests

  • npm test -- test/project-identity.test.ts test/context-project-alias.test.ts
  • npm test
  • npm run build

Summary by CodeRabbit

  • New Features

    • Project identity is normalized and expanded into alias sets (including path-like aliases), improving session creation, search, and context selection.
    • Session creation and event handling now persist normalized project/cwd identity so memories saved in worktrees are recognized and reused across main-repo/worktree boundaries.
    • Search and context lookups now match sessions and lessons by expanded project aliases, producing more relevant results across related paths.
  • Tests

    • Added tests validating project identity canonicalization, worktree handling, alias matching, and alias-aware context/search behavior.

Review Change Stack

@vercel

vercel Bot commented May 19, 2026

Copy link
Copy Markdown

@Lubrsy706 is attempting to deploy a commit to the rohitg00's projects Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented May 19, 2026 •

Copy link
Copy Markdown
Contributor

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds project identity resolution and alias expansion (including Git worktree detection), canonicalizes sessions at start, and updates mem::context and mem::search to match lessons/sessions using expanded project aliases so worktree and main-repo paths are treated as the same project.

Changes

Worktree Path Canonicalization

Layer / File(s) Summary
Project Identity Infrastructure
src/functions/project-identity.ts
Exports GitProjectInfo and ProjectIdentity, subprocess helper, alias expansion/normalization (including path and basename variants), project/session matching utilities, detectGitProject (git rev-parse steps), and resolveProjectIdentity that assembles canonical project, cwd, and aliases.
Session Startup Normalization
src/triggers/api.ts, src/triggers/events.ts
Session start handlers call resolveProjectIdentity and persist Session.project/Session.cwd from the resolved identity; triggers to mem::context send the normalized identity.project.
Context Loader Alias Matching
src/functions/context.ts
Context handler computes projectAliases via expandProjectAliases, adds loadProjectProfile fallback that matches aliases, filters/ranks lessons by alias-aware matching, and uses sessionMatchesProjectAliases to select observation sessions (excluding current session).
Search Filter Alias Matching
src/functions/search.ts
Search setup builds projectAliases from project/cwd; first-pass session filtering uses sessionMatchesProjectAliases instead of strict session.project === projectFilter, preserving other search/indexing logic.
Branch Detection Refactoring
src/functions/branch-aware.ts
mem::detect-worktree now delegates to detectGitProject(data.cwd) and returns a default non-git payload when detection fails or spreads the detectGitProject result into the response.
Project Identity Unit Tests
test/project-identity.test.ts
Tests that create real git repos/worktrees to assert canonicalization to main repo root, preservation of original cwd, git.isWorktree flag, alias expansion contents, and sessionMatchesProjectAliases behavior for nested and non-matching cases.
Context Integration Test
test/context-project-alias.test.ts
Integration test with an in-memory KV mock and SDK harness that verifies mem::context retrieves lessons/summaries saved under a worktree alias when invoked with the canonical project.

Sequence Diagram

sequenceDiagram
    participant Client as Codex Client
    participant APIStart as api::session::start
    participant ResolveId as resolveProjectIdentity
    participant GitCmd as git rev-parse
    participant KV as Session Storage
    participant ContextFunc as mem::context
    participant ContextSearch as Context Lesson/Session Matching
    Client->>APIStart: start session (worktree cwd, worktree path)
    APIStart->>ResolveId: canonicalize project identity
    ResolveId->>GitCmd: detect git dirs, branch, top-level
    GitCmd-->>ResolveId: main repo path, worktree info
    ResolveId-->>APIStart: canonical project + aliases (main, worktree, basename)
    APIStart->>KV: store Session (project: main repo, cwd: worktree path)
    APIStart->>ContextFunc: trigger with canonical project
    ContextFunc->>ContextSearch: expand project aliases
    ContextSearch->>KV: match lessons/sessions by alias set
    KV-->>ContextSearch: results from alias variants
    ContextFunc-->>Client: context includes project memories
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • rohitg00/agentmemory#105: Related changes to src/functions/search.ts filtering logic; this PR adds alias-aware session matching.

Poem

🐰 I hopped through worktree tunnels, nose aglow,
aliases stitched the paths I know.
Main roots called; the worktree stayed near,
memories gathered, tidy and clear.
🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title accurately describes the main change: canonicalizing project identity specifically for Git worktrees, which is the core fix in this changeset.
Linked Issues check ✅ Passed The PR fully satisfies issue #515 requirements: canonicalizes session.project to main repo root, preserves cwd, extends project matching to aliases (canonical project, cwd, worktree root, main repo root, basename), and reuses shared Git detector.
Out of Scope Changes check ✅ Passed All changes are directly scoped to issue #515: project-identity resolution, branch-aware refactoring, context/search alias matching, API/event normalization, and comprehensive test coverage.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
test/context-project-alias.test.ts (1)

37-37: 💤 Low value

Replace as never with safer type assertion.

The as never assertion completely disables type checking. Consider using as any or properly typing the mockKV return value to match the expected KV interface for better type safety in tests.

♻️ Safer type assertion
-  registerContextFunction(sdk, kv as never, 4000);
+  registerContextFunction(sdk, kv as any, 4000);
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/context-project-alias.test.ts` at line 37, The test uses a broad unsafe
assertion "kv as never" when calling registerContextFunction(sdk, kv, 4000);
replace this with a safer approach: either cast kv to any (kv as any) or,
better, give kv a proper typed mock that implements the expected KV interface
used by registerContextFunction (e.g., define mockKV: Partial<KVStore> or a
mocked type matching the methods registerContextFunction expects) and pass that
typed mock instead of using never; update the test variable (kv) and its
declaration so the type aligns with registerContextFunction's parameter
signature.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/functions/project-identity.ts`:
- Around line 79-84: projectValueMatches currently lets path-like values match
other projects via bare basenames (e.g., "app"), causing cross-project matches;
fix by detecting if the input value is path-like (e.g., contains '/'), and if so
only consider expanded aliases that are path-like when checking intersection
with the provided aliases set; preserve the existing expandProjectAliases-based
matching for non-path (legacy) values but when value is path-like do:
expandProjectAliases(value).filter(a => a.includes('/')).some(a =>
aliases.has(a)) so basename-only aliases are not used for path-like comparisons
(use function names projectValueMatches and expandProjectAliases to locate the
change).

In `@test/context-project-alias.test.ts`:
- Around line 30-40: Replace the manual SDK object in wireContext with a
module-level mock by adding vi.mock("iii-sdk") at the top of the test and using
the mocked SDK from that module; specifically, update wireContext (and its use
of registerContextFunction and ContextHandler) to obtain the mocked sdk (with
registerFunction/trigger spies) from the vi.mocked "iii-sdk" export instead of
constructing the sdk inline, and ensure the test uses the existing mockKV for
kv.get/set/list per test suite convention so registerContextFunction(kv, ...) is
invoked with the mocked kv and the mocked sdk is used to capture the
mem::context handler.

---

Nitpick comments:
In `@test/context-project-alias.test.ts`:
- Line 37: The test uses a broad unsafe assertion "kv as never" when calling
registerContextFunction(sdk, kv, 4000); replace this with a safer approach:
either cast kv to any (kv as any) or, better, give kv a proper typed mock that
implements the expected KV interface used by registerContextFunction (e.g.,
define mockKV: Partial<KVStore> or a mocked type matching the methods
registerContextFunction expects) and pass that typed mock instead of using
never; update the test variable (kv) and its declaration so the type aligns with
registerContextFunction's parameter signature.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3ee5d146-faec-439b-b5b6-2eaf9cab18c5

📥 Commits

Reviewing files that changed from the base of the PR and between 68fddd4 and 4d49166.

📒 Files selected for processing (8)
  • src/functions/branch-aware.ts
  • src/functions/context.ts
  • src/functions/project-identity.ts
  • src/functions/search.ts
  • src/triggers/api.ts
  • src/triggers/events.ts
  • test/context-project-alias.test.ts
  • test/project-identity.test.ts

Comment thread src/functions/project-identity.ts Resolved
Comment thread test/context-project-alias.test.ts Resolved
Signed-off-by: Lubrsy706 <lubrsy706@gmail.com>
@Lubrsy706
Lubrsy706 force-pushed the fix/515-codex-worktree-project branch from 4d49166 to 4d652dc Compare May 19, 2026 08:16
@rockarxiv

Copy link
Copy Markdown

Have you benchmarked the context retrieval? I had a similar solution, and the SessionStart hooks script started timing out as it has a hard cap of 1.5s in the script, and with the git workspace lookup, it was taking longer, so you may also consider changing that timeout.

@Lubrsy706

Copy link
Copy Markdown
Author

Thanks for calling this out. I checked this path and agreed the previous implementation was too loose for the SessionStart budget: it ran multiple sequential git rev-parse calls, each with a 5s timeout, before storing the canonical project identity.

I pushed 212c89a to tighten that up:

  • collapse the git identity lookup into a single git rev-parse --git-dir --git-common-dir --abbrev-ref HEAD --show-toplevel invocation
  • cap that lookup at 500ms, falling back to the requested project if git is slow/unavailable
  • keep context retrieval itself using the already-stored session project/cwd aliases, so it doesn't shell out on every mem::context call

Local validation:

  • npm test -- test/project-identity.test.ts test/context-project-alias.test.ts passes
  • npm run build passes
  • quick local benchmark over 100 resolveProjectIdentity({ project: cwd, cwd }) runs in this repo: avg 10.87ms, p50 9.38ms, p95 23.82ms, max 42.14ms

So worst-case git detection is now bounded well below the 1.5s SessionStart inject timeout, and normal local lookup is in the low tens of ms.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/functions/project-identity.ts`:
- Line 4: Replace the hardcoded GIT_IDENTITY_TIMEOUT_MS by making it
configurable and avoid silent fallback: introduce a configurable timeout value
(e.g., read from env or config) to replace GIT_IDENTITY_TIMEOUT_MS and, inside
detectGitProject(), on timeout reuse a cached last-known identity (store and
read the last successful identity keyed by repo path) instead of returning null;
also update resolveProjectIdentity() to prefer the cached identity when
detectGitProject() fails. Additionally, in detectGitProject() explicitly treat
the literal "HEAD" string as a detached-HEAD sentinel (do not propagate "HEAD"
as a branch name) and handle that case by using the commit hash or cached
identity. Ensure these changes reference GIT_IDENTITY_TIMEOUT_MS (or its new
config key), detectGitProject(), resolveProjectIdentity(), and the cache
read/write locations so reviewers can find the edits.
- Around line 137-139: The returned branch value currently treats the string
"HEAD" as a valid name; update the return object in the function that builds
project identity so that the branch field normalizes detached HEAD to null
(e.g., set branch to null when the local variable branch is falsy or equals the
literal "HEAD", otherwise keep branch). Locate the return with "isWorktree" and
"branch: branch || null" and replace that assignment with a conditional that
filters out the "HEAD" value.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c5072dd9-dfc8-4157-bbf5-6ce007d87fcc

📥 Commits

Reviewing files that changed from the base of the PR and between 68b2797 and 212c89a.

📒 Files selected for processing (1)
  • src/functions/project-identity.ts

Comment thread src/functions/project-identity.ts Resolved
Comment thread src/functions/project-identity.ts Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/functions/project-identity.ts (1)

23-24: ⚡ Quick win

Bound the git identity cache.

Each successful detection stores up to five keys, and nothing ever evicts them. In a long-lived agent that touches many temporary repos/worktrees, this turns into an unbounded cache of stale git metadata and makes the fallback path less trustworthy over time.

♻️ Minimal way to cap the cache
 const gitProjectCache = new Map<string, GitProjectInfo>();
+const MAX_GIT_PROJECT_CACHE_KEYS = 512;

 function rememberGitProject(cwd: string, git: GitProjectInfo): void {
   for (const key of [
     cwd,
     git.topLevel,
@@
     git.gitDir,
     git.commonDir,
   ]) {
-    gitProjectCache.set(pathKey(key), git);
+    const normalizedKey = pathKey(key);
+    gitProjectCache.delete(normalizedKey);
+    gitProjectCache.set(normalizedKey, git);
+    while (gitProjectCache.size > MAX_GIT_PROJECT_CACHE_KEYS) {
+      const oldestKey = gitProjectCache.keys().next().value;
+      if (!oldestKey) break;
+      gitProjectCache.delete(oldestKey);
+    }
   }
 }

Also applies to: 67-90

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/functions/project-identity.ts` around lines 23 - 24, The gitProjectCache
Map currently grows without bounds; add a fixed-size eviction policy by
introducing a MAX_GIT_CACHE_ENTRIES constant (e.g. 100 or 5 as desired) and
ensure inserts into gitProjectCache evict the oldest/least-recently-used entry
when the size would exceed the limit. Update any accessor functions that touch
gitProjectCache (e.g., the functions around lines 67-90 that read/write the Map)
to maintain LRU order on access (move accessed keys to the "most-recent"
position) or use a simple FIFO eviction on insert, so stale git metadata is
removed and the cache size is always capped.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/functions/project-identity.ts`:
- Around line 23-24: The gitProjectCache Map currently grows without bounds; add
a fixed-size eviction policy by introducing a MAX_GIT_CACHE_ENTRIES constant
(e.g. 100 or 5 as desired) and ensure inserts into gitProjectCache evict the
oldest/least-recently-used entry when the size would exceed the limit. Update
any accessor functions that touch gitProjectCache (e.g., the functions around
lines 67-90 that read/write the Map) to maintain LRU order on access (move
accessed keys to the "most-recent" position) or use a simple FIFO eviction on
insert, so stale git metadata is removed and the cache size is always capped.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2565b12c-3f31-4189-aefa-b070dc4fed43

📥 Commits

Reviewing files that changed from the base of the PR and between 212c89a and eec590a.

📒 Files selected for processing (2)
  • src/functions/project-identity.ts
  • test/project-identity.test.ts

@rohitg00 rohitg00 closed this May 27, 2026
@rohitg00

Copy link
Copy Markdown
Owner

Thanks @Lubrsy706 — closing here, the worktree-fragmentation root cause is being tracked in #515 for a fuller fix.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex worktrees are treated as separate projects, fragmenting context and project-scoped memory

3 participants