Skip to main content

Module worktree

Module worktree 

Source
Expand description

Worktree-aware path resolution for edit tools.

SymForge indexes one repo path and stores absolute file paths in its index. When an agent runs from inside a parallel git worktree that shares the same .git objects, an edit that resolves against the indexed absolute path silently writes to the indexed repo copy instead of the agent’s own working tree. The resolver below implements explicit call-time routing through the working_directory edit parameter.

The edit handlers call resolve_target_path before writing. When working_directory is None, behavior is byte-identical to pre-routing releases (write to the indexed absolute path). When Some, the path is re-rooted against the working directory and validated against a cached git worktree list, refreshed on cache miss.

Structs§

ResolvedTarget
Outcome of resolve_target_path: where the edit should land, plus where the index believes the file lives, plus a flag flipping true iff the two differ.
WorktreeAwareEditHook
EditHook implementation that reroutes edits into a sibling git worktree when the caller supplies working_directory. Holds one shared WorktreeCache so repeated calls in the same session avoid re-shelling out to git worktree list.
WorktreeCache
Cache of known worktrees for one indexed root. Populated on demand by refresh(); lookup() refreshes once on cache miss before concluding the directory is unknown.
WorktreeEntry
A worktree known to be associated with the indexed root.
WorktreeMisuseCounter
Counts edit-tool calls that omitted working_directory while the transitional worktree observability knob is on. Exposed through the health tool as a rolling “last hour” signal so regressions stay visible after the feature ships.

Enums§

WorktreeError
Errors produced by worktree-aware resolution.

Constants§

WORKTREE_ROUTING_ENV

Functions§

canonicalize
Canonicalize a path, returning a clean form without the \\?\ UNC prefix on Windows. Delegates to dunce::canonicalize which falls back to std::fs::canonicalize on non-Windows.
register_if_feature_enabled
Install WorktreeAwareEditHook on the process-wide edit-hook registry, exactly once. Routing policy is resolved inside the hook so callers can request worktree routing at call time with working_directory.
resolve_target_path
Re-root an indexed absolute path against an optional working directory, applying the spec §2.2 resolution algorithm.
routing_policy_from_env
Interpret the transitional worktree-routing env var as policy. Unset means explicit call-time routing is allowed; false/off/disabled values block requested routing before any write.