strategy

func AccumulateSessionTokenUsage ¶ added in v0.11.3

func AccumulateSessionTokenUsage(ctx context.Context, sessionID string, delta *agent.TokenUsage) error

AccumulateSessionTokenUsage adds a token-usage delta to both the session-cumulative total and the checkpoint-scoped accumulator, mirroring SaveStep's accounting (manual_commit_git.go). It exists for turns that end with no uncommitted changes — e.g. Antigravity committing all its work mid-turn, its normal flow — where the TurnEnd handler skips SaveStep entirely but the turn's out-of-band token delta must still be recorded so the next condensation (or `entire status`) attributes it. A nil or empty delta is a no-op.

func AnyGitHookInstalled ¶ added in v0.10.1

func AnyGitHookInstalled(ctx context.Context) bool

AnyGitHookInstalled reports whether Entire git hooks are present at all, current or not. This is what uninstall needs: a stale hook is still ours, and still ours to remove.

func AppendNewSkillEvents ¶ added in v0.10.3

func AppendNewSkillEvents(state *SessionState, candidates []agent.SkillEvent) []agent.SkillEvent

AppendNewSkillEvents records candidates into state.SkillEvents, stamping the session's TurnID on events that lack one, and returns those that were not already recorded. It is the single dedupe used by every path that adds skill events — hook-provided (lifecycle) and transcript-extracted (condensation and turn-end finalize) alike — so "already recorded" means the same thing everywhere. Exactly-once telemetry rests on that agreement: two paths with different notions of duplicate would let one re-report what the other recorded.

func AttachTokenUsage ¶ added in v0.11.5

func AttachTokenUsage(ctx context.Context, ag agent.Agent, state *SessionState, transcript []byte, transcriptPath string) (*agent.TokenUsage, int)

AttachTokenUsage returns the tokens `entire session attach` stores for a session's transcript and the transcript end position in the agent's offset units. With existing state it counts only what no checkpoint has counted yet (from TokenStart), falling back to the pending hook-reported usage the way condensation does; without state it counts the whole transcript. The caller records pos with ConsumeAttachTokenWindow once the checkpoint is written. While a turn runs, its subagents' tokens aren't in the pending usage yet (Stop records them), so they are read live as a mid-turn condensation does; that also moves state.TokenUsage's cumulative subagent total, which the caller must keep so the re-baseline covers what this checkpoint stored.

func CheckAndWarnHookManagers ¶ added in v0.4.5

func CheckAndWarnHookManagers(ctx context.Context, w io.Writer, absolutePath bool)

CheckAndWarnHookManagers detects external hook managers and writes a warning to w if any are found. absolutePath embeds the full binary path for GUI git clients.

func CheckpointPushTarget ¶ added in v0.11.5

func CheckpointPushTarget(ctx context.Context, pushRemoteName string) (target string, disabled bool)

CheckpointPushTarget returns where PrePush sends checkpoint metadata for pushRemoteName — the checkpoint_remote URL when one is configured, otherwise the remote itself — and whether push_sessions turns pushing off. Callers use it to confirm delivery after a push, since PrePush is deliberately fail-soft.

func CheckpointReadRemotes ¶ added in v0.10.1

func CheckpointReadRemotes(ctx context.Context) []string

CheckpointReadRemotes returns the ordered, deduped remotes that checkpoint READS consult: the elected sync remote first, then "origin" as the legacy tier (pre-single-remote-sync checkpoints live there, and a fresh clone may lack the local settings that elected a non-origin remote).

Unlike the write-side election, this fails OPEN: on an election error (misconfigured checkpoint_push_remote, unreadable settings) the chain is ["origin"] when configured. Writes fail closed to prevent leaking data; failing reads closed would only prevent FINDING data, with no privacy benefit. Callers must uphold the read-only rule for every candidate after the first: only the elected remote may seed or advance local refs.

An empty result means no candidates — callers needing the "checkpoint absent" classification must gather their own positive evidence (successful remote listing, readable settings); an empty chain alone is not proof.

The election itself is deliberately un-memoized: every call re-runs it, so a settings change or a captured election written mid-invocation is observed immediately. What IS memoized, per invocation, are the two .git/config reads underneath it — which remotes exist, and does remote X exist (see git_remote_cache.go). That split is load-bearing: caching the election result would make #1991's capture invisible to the gate that runs right after it.

func ClaimSessionStartBanner ¶ added in v0.6.0

func ClaimSessionStartBanner(ctx context.Context, sessionID string) (claimed bool, err error)

ClaimSessionStartBanner records that the SessionStart banner has been emitted for a session. First-writer-wins semantics, separate from StoreAgentTypeHint so a non-banner-capable agent winning the ownership race (e.g. Cursor, which doesn't implement HookResponseWriter) doesn't suppress the banner from a banner-capable agent that fires SessionStart for the same session.

Callers MUST only invoke this from within the HookResponseWriter branch — the claim represents "a banner was actually shown", not just "an agent considered showing one". Otherwise a non-writer claimant would re-introduce the bug.

Returns (claimed=true) when this call won the race and the caller should emit the banner; (claimed=false) when an earlier call already claimed it.

func ClearHooksDirCache ¶ added in v0.4.6

func ClearHooksDirCache()

ClearHooksDirCache clears the cached hooks directory. This is primarily useful for testing when changing directories.

func ClearSessionState ¶

func ClearSessionState(ctx context.Context, sessionID string) error

ClearSessionState removes the session state file for the given session ID.

It takes sessionID's gate first, for the same reason (*ManualCommitStrategy).clearSessionState does: this deletes the file that every other mutation of this state writes under MutateSessionState's per-session lock, so an unlocked delete landing mid-mutation destroys the write that was in flight, with nothing surfacing the loss. This is the implementation `entire doctor` reaches (doctor.go's discardSession) -- a separate one from the strategy method, and the command most likely to be run while other sessions are live -- so gating the strategy method alone left the race open exactly where it mattered most.

Calling it from inside a MutateSessionState frame for the same session is refused rather than tolerated. Holding the gate makes the delete safe, not effective: when the frame's closure returns, MutateSessionState writes the state back out, so the file is resurrected and the caller still sees a nil error -- `entire doctor` would report a session discarded and the session would reappear. Clear from inside an active closure with (*ManualCommitStrategy).clearSessionStateLocked instead, and return ErrMutationSkip so the frame does not save (see CondenseSessionByID's clear path, the one caller that legitimately does this).

The wait is not cancellable. With no WithSessionLockWait deadline on ctx, acquireSessionGate falls through to the ctx-free flock.AcquireIn, so ctx cancellation -- a first Ctrl-C included -- does not abort a blocked acquire; only the force-quit path in main.go escapes. ctx is still honored for everything else here. Adding a timeout via ctx alone would silently do nothing; it would have to go through WithSessionLockWait.

func ClearSessionStateWithProgress ¶ added in v0.10.5

func ClearSessionStateWithProgress(ctx context.Context, sessionID string, errW io.Writer, notifyAfter time.Duration) error

ClearSessionStateWithProgress is ClearSessionState with the shared lock-wait notice on errW. This is what user-facing commands should call; the bare ClearSessionState stays for callers with nowhere to print.

func CollectUntrackedFiles ¶ added in v0.7.8

func CollectUntrackedFiles(ctx context.Context) ([]string, error)

CollectUntrackedFiles collects untracked, non-ignored paths relative to the repository root.

func CompleteTaskRecord ¶ added in v0.10.3

func CompleteTaskRecord(ctx context.Context, sessionID string, rec session.TaskRecord) (bool, error)

CompleteTaskRecord marks the record for rec.ToolUseID completed exactly once and attaches the capture's results (files, declared transcript path, tokens) in the same MutateSessionState closure, per session.State.CompleteTaskRecord's contract. When no launch stub exists the record is created first: foreground tasks have no launch hook, so completion is the only event that can produce their record. Returns false without error when a racing Final event already completed the record, or when no session state exists.

func ConsumeAttachTokenWindow ¶ added in v0.11.5

func ConsumeAttachTokenWindow(state *SessionState, pos int)

ConsumeAttachTokenWindow marks the tokens an attach checkpoint stored as counted: the token offset moves to pos and the pending window is reset, so the session's next checkpoint does not count them again. The displayed transcript window (CheckpointTranscriptStart) is left alone.

func CountUnpushedCheckpoints ¶ added in v0.10.0

func CountUnpushedCheckpoints(ctx context.Context, remoteName string) (int, error)

CountUnpushedCheckpoints approximates how many checkpoints exist locally but not on the checkpoint sync remote. Fully local — no network. git-refs primary: push-queue length. git-branch primary: v1 commits ahead of refs/remotes/<remote>/<v1>; an absent tracking ref with a local v1 branch counts every v1 commit (correct for the deferred-publish case; a stale tracking ref overcounts — acceptable for a local, no-network heuristic).

func DeclaredPushRemoteForBranch ¶ added in v0.10.3

func DeclaredPushRemoteForBranch(ctx context.Context, branch string) string

DeclaredPushRemoteForBranch resolves where `git push` would send branch, through git's own precedence: branch.<name>.pushRemote, then remote.pushDefault, then branch.<name>.remote. Empty when branch is empty or nothing is declared — callers supply their own default, since the right one differs per caller ("origin" for a command issuing its own push; "no capture" for the checkpoint gate).

This is the "where does this branch push" question, which is NOT the question ResolveCheckpointSyncRemote answers ("which single remote may carry checkpoint data"). Do not substitute one for the other in either direction; that resolver's doc comment holds the full argument, including why checkpoint sync deliberately does not elect from the declaration returned here. The short version: that objection is about a gate deciding whether to piggyback on someone else's push, and does not apply to a caller issuing its own.

func DeleteBranchCLI ¶ added in v0.3.13

func DeleteBranchCLI(ctx context.Context, branchName string) error

DeleteBranchCLI deletes a git branch using the git CLI. Uses `git branch -D` instead of go-git's RemoveReference because go-git v5 doesn't properly persist deletions when refs are packed (.git/packed-refs) or in a worktree context. This is the same class of go-git v5 bug that affects checkout and reset --hard (see CheckoutBranch in git_operations.go, which shells out to the git CLI for the same reason).

Returns ErrBranchNotFound if the branch does not exist, allowing callers to use errors.Is for idempotent deletion patterns.

func DeleteLegacyShadowBranches ¶ added in v0.11.5

func DeleteLegacyShadowBranches(ctx context.Context, branches []string) (deleted []string, failed []string)

DeleteLegacyShadowBranches deletes the specified branches from the repository. Returns two slices: successfully deleted branches and branches that failed to delete. Individual branch deletion failures do not stop the operation - all branches are attempted.

func DeleteOrphanedCheckpoints ¶

func DeleteOrphanedCheckpoints(ctx context.Context, checkpointIDs []string) (deleted []string, failed []string, err error)

DeleteOrphanedCheckpoints removes checkpoint directories from the entire/checkpoints/v1 branch.

func DeleteOrphanedSessionStates ¶

func DeleteOrphanedSessionStates(ctx context.Context, sessionIDs []string) (deleted []string, failed []string, err error)

DeleteOrphanedSessionStates deletes the specified session state files.

func EmitSkillInvocationTelemetry ¶ added in v0.10.3

func EmitSkillInvocationTelemetry(ctx context.Context, events []agent.SkillEvent)

EmitSkillInvocationTelemetry forwards newly recorded skill events to telemetry. Gated on the same opt-in telemetry setting as command tracking; skill names are additionally allowlisted inside the telemetry package, so custom names never leave the machine verbatim. Skill names and signal kinds only, never prompt text or transcript content.

Hand this to MutateSessionStateOnSaved as the post-save effect rather than calling it inside the mutation closure. That helper runs the effect only once the state was durably written, and only after the session gate is released: the settings load (disk I/O) and detached-process spawn must not extend the gate hold time and block concurrent hooks, and emitting only after a save keeps reporting exactly-once — events whose append was never persisted are re-derived, and re-announced, by the next extraction pass.

func EnsureEntireGitignore ¶

func EnsureEntireGitignore(ctx context.Context) error

EnsureEntireGitignore ensures all required entries are in .entire/.gitignore Works correctly from any subdirectory within the repository.

func EnsurePrimaryRef ¶ added in v0.7.6

func EnsurePrimaryRef(ctx context.Context, repo *git.Repository) error

func EnsureRedactionConfigured ¶ added in v0.5.1

func EnsureRedactionConfigured(ctx context.Context) error

EnsureRedactionConfigured loads redaction settings and configures the redact package: scanner engines, PII detection (opt-in), inline custom_redactions, and rule packs auto-discovered from .entire/redactors/.

Must be called at each process entry point before checkpoint writes. Returns an error ONLY for scanner-specific failures (invalid scanner config, goredact engine construction) — proceeding would run a scanner set the team's committed settings did not choose. All other settings problems keep the historical warn-and-default behavior.

Pass a context descended from the root pre-run, so redact's diagnostics reach .entire/logs/: hook contexts swallow stderr, so otherwise a user grepping for component=redaction finds nothing and concludes their rules never ran. Without a context logger they fall back to stderr and the load-time summary is skipped.

sync.Once: the first caller's context wins, and every caller is an entry point that just built one.

func EnsureSetup ¶ added in v0.4.8

func EnsureSetup(ctx context.Context) error

EnsureSetup ensures the strategy is properly set up.

func ExtractFirstPrompt ¶

func ExtractFirstPrompt(content string) string

ExtractFirstPrompt extracts and truncates the first meaningful prompt from prompt content. Prompts are separated by "\n\n---\n\n". Skips empty prompts and separator-only content. Returns empty string if no valid prompt is found.

func FetchMetadataBranch ¶ added in v0.5.3

func FetchMetadataBranch(ctx context.Context, remoteURL string) error

FetchMetadataBranch fetches the metadata branch from the checkpoint remote URL and updates the local branch. Unlike fetchMetadataBranchIfMissing, this always fetches regardless of whether the branch exists locally (for resume scenarios where the local branch may be stale).

The fetch is unfiltered (NoFilter: true) because resume needs blob content (transcripts, metadata JSON) — not just tree objects, and it runs on the foreground budget for the same reason: it is the call that actually moves the transcript archive.

func FilterTrackableChanges ¶ added in v0.11.5

func FilterTrackableChanges(ctx context.Context, repoRoot string, modified, added, deleted []string) (keptModified, keptAdded, keptDeleted []string)

FilterTrackableChanges removes, from repo-relative path lists, the paths that are not the session's committable file work, so they never enter FilesTouched on any route (turn end, task-record completion, per-tool hooks, Codex child files, and the transcript extraction a mid-turn commit falls back to):

• gitignored files, from modified and added: no commit can carry them. Deleted paths are never ignore-checked: a deletion reported by git status is of a tracked path by construction, and `git check-ignore` reports a path whose deletion is staged (it has left the index), which would drop the deletion of a tracked file that matches an ignore rule;
• submodule gitlinks (mode 160000 in HEAD or the index), and every path beneath one, from all three: a submodule pointer is not a file, the prepare hook would stamp a trailer for it, and PostCommit could never match it. Edits inside a submodule are not tracked by the superproject's session at all: they belong to the nested repository, whose own session records them. Each path's ancestor directories are part of the gitlink query, so sub/lib.txt is recognized by its gitlink ancestor sub, and such paths are dropped before the ignore check, where git would refuse them;
• paths git refuses to ignore-check (gitrepo.IgnoredPaths' refused set), such as one beneath a symlinked directory: git cannot commit them through that path either.

Either kind would keep the session pending forever: it stays in carry-forward, re-condenses the full transcript on every later commit, and leaves an ENDED session for the zombie sweep.

If git cannot answer either question, the affected paths are kept: tracking a path that turns out to be uncommittable is recoverable, silently dropping real work is not.

Answers are cached per process (trackablePathCache), so the several sessions one hook processes — a commit hook walks every session of the worktree — ask git about each path once.

func FindMostRecentSessionInCurrentWorktree ¶ added in v0.7.8

func FindMostRecentSessionInCurrentWorktree(ctx context.Context) string

FindMostRecentSessionInCurrentWorktree returns the most recently interacted session from the current worktree only, never falling back to another worktree's.

This is the whole of what it does, deliberately. Anything asking "which session is running me" must go through strategy.ResolveCallerSession, which identifies the caller first and reports which tier answered; a bare most-recent lookup cannot tell "mine" from "whichever moved last", and worktrees share one session store, so guessing there returns an unrelated session that looks exactly like a real answer.

func FirstDisplayPrompt ¶ added in v0.10.1

func FirstDisplayPrompt(prompts []string) string

FirstDisplayPrompt returns the first prompt in the list worth showing as a title/preview: the first entry that is non-empty, not separator-only, and not agent-injected (runtime preambles, AGENTS.md dumps — see textutil.IsInjectedPrompt). Returns "" if none qualifies, which callers that must show something should treat as "fall back to the raw first prompt".

The returned text is not truncated; callers that render it into a fixed-width display are responsible for that (see restoredPromptPreview).

func FirstReadCandidateTrackingRef ¶ added in v0.10.1

func FirstReadCandidateTrackingRef(ctx context.Context, repo *git.Repository, primary plumbing.ReferenceName) (string, plumbing.ReferenceName, bool)

FirstReadCandidateTrackingRef returns the remote name and remote-tracking ref of the first checkpoint read candidate (elected sync remote first, then the legacy origin tier) whose tracking ref for primary exists locally. Pure read; ok is false when no candidate has a tracking ref (or the chain is empty).

func FormatSubagentEndMessage ¶

func FormatSubagentEndMessage(agentType, description, toolUseID string) string

FormatSubagentEndMessage formats a commit message for when a subagent completes. Format: "Completed '<agent-type>' agent: <description> (<tool-use-id>)"

Edge cases:

• Empty description: "Completed '<agent-type>' agent (<tool-use-id>)"
• Empty agentType: "Completed agent: <description> (<tool-use-id>)"
• Both empty: "Task: <tool-use-id>"

func FormatSubagentRunningMessage ¶ added in v0.10.3

func FormatSubagentRunningMessage(agentType, description, toolUseID string) string

FormatSubagentRunningMessage is FormatSubagentEndMessage's in-flight counterpart, for pending-list rows whose task record is still live.

func GetCurrentBranchName ¶

func GetCurrentBranchName(repo *git.Repository) string

GetCurrentBranchName returns the short name of the current branch if HEAD points to a branch. Returns an empty string if in detached HEAD state or if there's an error reading HEAD. This is used to capture branch metadata for checkpoints.

func GetDefaultBranchName ¶

func GetDefaultBranchName(repo *git.Repository) string

GetDefaultBranchName returns the name of the default branch. First checks origin/HEAD, then falls back to checking if main/master exists. Returns empty string if unable to determine. NOTE: Duplicated from cli/git_operations.go - see ENT-129 for consolidation.

func GetGitAuthorFromRepo ¶

func GetGitAuthorFromRepo(repo *git.Repository) (name, email string)

GetGitAuthorFromRepo retrieves the git user.name and user.email, checking both the repository-local config and the global ~/.gitconfig. Delegates to checkpoint.GetGitAuthorFromRepo — this wrapper exists so callers within the strategy package don't need a qualified import.

func GetGitCommonDir ¶

func GetGitCommonDir(ctx context.Context) (string, error)

GetGitCommonDir returns the path to the shared git directory. In a regular checkout, this is .git/ In a worktree, this is the main repo's .git/ (not .git/worktrees/<name>/) Uses git rev-parse --git-common-dir for reliable handling of worktrees.

func GetGitDir ¶

func GetGitDir(ctx context.Context) (string, error)

GetGitDir returns the actual git directory path by delegating to git itself. This handles both regular repositories and worktrees, and inherits git's security validation for gitdir references.

func GetHooksDir ¶ added in v0.4.5

func GetHooksDir(ctx context.Context) (string, error)

GetHooksDir returns the active hooks directory path. This respects core.hooksPath and correctly resolves to the common hooks directory when called from a linked worktree. The result is cached per working directory.

func GetMainBranchHash ¶

func GetMainBranchHash(repo *git.Repository) plumbing.Hash

getMainBranchHash returns the hash of the main branch (main or master). Returns ZeroHash if no main branch is found.

func GetMetadataRefTree ¶ added in v0.7.6

func GetMetadataRefTree(repo *git.Repository, ref plumbing.ReferenceName) (*object.Tree, error)

GetMetadataRefTree returns the tree object at the given committed-metadata ref.

func GetRemotePrimaryTree ¶ added in v0.7.6

func GetRemotePrimaryTree(ctx context.Context, repo *git.Repository) (*object.Tree, error)

GetRemotePrimaryTree returns the tree at the first checkpoint read candidate's remote-tracking ref for the configured Primary (elected sync remote first, then the legacy origin tier; first existing tracking ref wins). Pure read — it never writes local refs. Errors when Primary isn't in Push (no remote-tracking shadow), when no read candidate is configured, or when no candidate's tracking ref exists (surfacing the first candidate's error).

func GitOperationInProgress ¶ added in v0.11.5

func GitOperationInProgress(ctx context.Context) string

GitOperationInProgress names the git operation the worktree is in the middle of (rebase or am, cherry-pick, revert, merge, bisect), or returns "" when none is. A command about to move a branch must not do so mid-operation. A git dir that can't be read reports none, as isGitSequenceOperation does.

func HooksDirLinkTarget ¶ added in v0.11.0

func HooksDirLinkTarget(hooksDir string) (string, bool)

HooksDirLinkTarget resolves a symlinked hooks directory to the absolute directory it names, reporting false when it cannot be resolved (a dangling link, or one whose target is unreadable).

Exported because doctor prints the same remedy, and it must print the same path: os.Readlink returns the link's raw contents, which for a relative link is relative to the link's own parent rather than to anywhere the user's shell will be. Pasting that into `git config core.hooksPath` sets a path git then resolves from somewhere else entirely.

func HooksPathCommand ¶ added in v0.11.0

func HooksPathCommand(dir string) string

HooksPathCommand renders the `git config core.hooksPath <dir>` remedy with dir quoted so the line survives being pasted into a shell.

Exported because doctor prints the same remedy, and printing it twice means getting the quoting right twice. A hooks directory containing a space is ordinary -- a macOS "Application Support" path, a Windows "C:\Users\First Last\..." -- and unquoted it produces `git config core.hooksPath /tmp/my hooks dir`, which git rejects with "error: no action specified" because it sees four arguments. The remedy is presented as a command to paste, so it has to be one.

Quoted only when it needs to be, so the common clean path stays readable.

func InstallGitHook ¶

func InstallGitHook(ctx context.Context, silent, absolutePath bool) (int, error)

InstallGitHook installs generic git hooks that delegate to `entire hook` commands. These hooks work with any strategy - the strategy is determined at runtime. If silent is true, no output is printed (except backup notifications, which always print). absolutePath embeds the full binary path in hooks for GUI git clients. Returns the number of hooks that were installed (0 if all already up to date).

Hooks always invoke the "entire" binary. Git hooks written by older versions in local-dev mode ran a repo-relative launcher script instead; they still carry entireHookMarker, so the content comparison below rewrites them to the binary form on the next install rather than leaving them pointed at repo content.

func InvalidateGitRemoteCache ¶ added in v0.10.1

func InvalidateGitRemoteCache(ctx context.Context)

InvalidateGitRemoteCache drops the memoized remote reads for every repository. Callers that add, rename, remove or re-point a git remote must call this, or later elections in the same command answer from the pre-mutation config. A caller performing several mutations needs one call after the last of them.

func IsCondensableEndedSession ¶ added in v0.10.3

func IsCondensableEndedSession(state *SessionState) bool

IsCondensableEndedSession reports whether an ENDED, not fully condensed session still carries uncondensed content (State.HasPendingWork), which condensing (CondenseSessionByID) can always salvage: turn-end steps condense from the session's transcript and recorded files, task records from their own transcripts. Used by the PostCommit stale-session warning and the background zombie sweep.

func IsEmptyRepository ¶ added in v0.4.3

func IsEmptyRepository(repo *git.Repository) bool

IsEmptyRepository returns true if the repository has no commits yet. After git-init, HEAD points to an unborn branch (e.g., refs/heads/main) whose target does not yet exist. repo.Head() returns ErrReferenceNotFound in this case.

func IsGitHookInstalled ¶

func IsGitHookInstalled(ctx context.Context) bool

IsGitHookInstalled reports whether a CURRENT set of Entire git hooks is installed. Callers that need to tell "none" from "ours but stale" — uninstall, doctor — must use CheckGitHookState instead, or they will treat a stale hook as if it were not there.

func IsGitHookInstalledInDir ¶ added in v0.4.4

func IsGitHookInstalledInDir(ctx context.Context, repoDir string) bool

IsGitHookInstalledInDir checks if a current set of Entire CLI hooks is installed in the given repo directory. Useful for tests that must not change cwd.

func IsLegacyShadowBranch ¶ added in v0.11.5

func IsLegacyShadowBranch(branchName string) bool

IsLegacyShadowBranch reports whether the branch name has the shape of a shadow branch written by an older CLI. The metadata and trails branches are never shadow branches.

This is a name-shape check, not an ownership check -- see the legacyShadowBranchPattern doc comment. Do not use it to gate deletion a human has not reviewed; use isAutoDeletableLegacyShadowBranch for that.

func IsMetadataDisconnected ¶ added in v0.5.0

func IsMetadataDisconnected(ctx context.Context, repo *git.Repository, remoteRefName plumbing.ReferenceName) (bool, error)

IsMetadataDisconnected reports whether the local primary metadata ref and the provided fetched or remote-tracking ref exist but share no common ancestor.

func IsOnDefaultBranch ¶

func IsOnDefaultBranch(repo *git.Repository) (bool, string)

IsOnDefaultBranch checks if the repository HEAD is on the default branch. Returns (isOnDefault, currentBranchName). NOTE: Duplicated from cli/git_operations.go - see ENT-129 for consolidation.

func LeadCheckpointReadRemote ¶ added in v0.11.0

func LeadCheckpointReadRemote(ctx context.Context) string

LeadCheckpointReadRemote returns the head of the read-candidate chain (the elected sync remote) for remote.FetchURL's ownership vote. Callers that resolve a configured checkpoint_remote pass it as FetchURLOptions.LeadReadRemote so the fetch-side inherited check sees the same fork-shaped identity the push side sees: in the "cloned the base, added a fork" topology only the elected remote's owner exposes the mismatch. Returns "" when no candidate resolves.

Pass it only on paths that already confirmed a checkpoint_remote is configured. On the no-config path a lead does more than vote: it selects which remote serves the fetch.

func ListLegacyShadowBranches ¶ added in v0.11.5

func ListLegacyShadowBranches(ctx context.Context) ([]string, error)

ListLegacyShadowBranches returns the local branches that look like shadow branches written by an older CLI (IsLegacyShadowBranch), sorted. Returns an empty slice (not nil) if there are none.

func ListRemovableLegacyShadowBranches ¶ added in v0.11.5

func ListRemovableLegacyShadowBranches(ctx context.Context) ([]string, error)

ListRemovableLegacyShadowBranches returns the local shadow branches older CLIs left behind that are safe to delete without listing them for a human first: the strict worktree-suffixed shape only (see autoDeletableLegacyShadowBranchPattern), sorted.

func LoadAgentTypeHint ¶ added in v0.6.0

func LoadAgentTypeHint(ctx context.Context, sessionID string) types.AgentType

LoadAgentTypeHint reads the agent type hint written by SessionStart. Returns empty string if the hint file doesn't exist, can't be read, or the value isn't a registered agent type.

func LoadModelHint ¶ added in v0.5.0

func LoadModelHint(ctx context.Context, sessionID string) string

LoadModelHint reads the LLM model name from the hint file for the given session. Returns empty string if the hint file doesn't exist or can't be read.

func ManagedGitHookNames ¶ added in v0.4.4

func ManagedGitHookNames() []string

ManagedGitHookNames returns the list of git hooks managed by Entire CLI. This is useful for tests that need to manipulate hooks.

func MergeUnhashedFilesTouched ¶ added in v0.11.5

func MergeUnhashedFilesTouched(state *SessionState, fileLists ...[]string)

MergeUnhashedFilesTouched merges paths into state.FilesTouched for every route other than a turn-end step: task-record completion, per-tool hooks, and subagent child-file merges. Those routes do not hash what they add, so any hash recorded for a merged path by an earlier step is dropped and the path falls back to name matching, exactly as applyTouchedFileHashes does for a changed path it could not hash. Keeping the older hash would make a commit of the newer content read as "the human replaced the agent's work".

Every non-SaveStep write that adds to FilesTouched must go through here.

func MutateSessionState ¶ added in v0.6.2

func MutateSessionState(ctx context.Context, sessionID string, fn func(*SessionState) error) error

MutateSessionState is the safe load → mutate → save helper. It takes an OS-level advisory lock against .git/entire-session-locks/<id>.lock for the duration of the read+write so concurrent processes cannot lose each other's updates. fn receives the freshly-loaded state and mutates it in place; returning ErrMutationSkip skips the save. Reentrant within the same goroutine: nested calls share the outer's state pointer and skip the inner load/save, so all mutations are flushed by the outermost call.

fn may hold the lock for slow operations — PostCommit's callback, for example, runs CondenseSession (transcript redaction and compaction, checkpoint tree builds) inside the gate. That's deliberate: PostToolUse must not slip in mid-condense and revert CheckpointTranscriptStart or files_touched. A concurrent PostToolUse on the same session waits for the commit to finish.

Returns ErrStateNotFound if the state file doesn't exist (event arrived before InitializeSession). Errors from fn or from load/save propagate.

All session-state mutations funnel through this helper so the hot-path PostToolUse hook cannot revert fields written by lifecycle handlers (TurnEnd, PostCommit, ModelUpdate) that ran between our load and our save.

A nil return is not proof that anything was written. Callers with a side effect that must follow a durable write want MutateSessionStateOnSaved.

func MutateSessionStateOnSaved ¶ added in v0.10.3

func MutateSessionStateOnSaved(ctx context.Context, sessionID string, fn func(*SessionState) error, onSaved func()) error

MutateSessionStateOnSaved is MutateSessionState plus onSaved, an effect that runs only once the state fn mutated has been durably written — and never while the session gate is held.

It exists because a nil error is not proof of a save (ErrMutationSkip reports success without writing) and because *this* frame is not necessarily the one that saves. Only the outermost frame loads and saves; a nested frame's mutations are flushed by whoever owns that save. So a nested frame cannot answer "was this persisted?" at the moment it returns — the answer arrives later, from a frame further up the stack. Handing the effect to the helper rather than returning a bool moves the decision to the only frame that can make it: nested registrations are queued on the gate, and the outermost frame runs them after its own save succeeds, discarding them if it skips or fails.

That distinction is load-bearing for anything irreversible. Skill-invocation telemetry is the motivating case: extraction re-derives from transcript offset 0 on every pass and dedupes against a ledger in session state, so announcing an event whose ledger entry never landed does not self-correct — the next pass sees an unrecorded event and reports it again, duplicating it in PostHog. Not emitting is the recoverable direction: the append is re-derived and re-announced by the next pass.

onSaved runs after the gate is released, so its I/O (settings load, detached process spawn) never extends the hold time for a concurrent hook. Effects run in registration order, so nested registrations precede the outermost frame's own effect.

One gap this does not close: a nested frame whose fn *errors* has already mutated the shared state, and an outer frame that swallows that error still saves those mutations — with no effect registered. That direction loses an announcement rather than duplicating one, and is inherent to nested frames sharing a state pointer.

func OpenRepository ¶

func OpenRepository(ctx context.Context) (*git.Repository, error)

OpenRepository opens the git repository from the repo root. It uses 'git rev-parse --show-toplevel' to find the repository root, which works correctly even when called from a subdirectory or a linked worktree.

func PrepareSessionEndCondensation ¶ added in v0.10.3

func PrepareSessionEndCondensation(ctx context.Context, state *SessionState) error

PrepareSessionEndCondensation reserves an ID for content-bearing ENDED sessions or marks empty ENDED sessions fully condensed. File-bearing sessions remain eligible for PostCommit.

func PromoteTmpRefSafely ¶ added in v0.5.6

func PromoteTmpRefSafely(ctx context.Context, tmpRefName, destRefName plumbing.ReferenceName, label string) error

PromoteTmpRefSafely reads tmpRefName (the ref a fetch just landed into), advances destRefName to its hash via SafelyAdvanceLocalRef, then removes the tmp ref. The cleanup is deferred so the tmp ref is reaped even when the advance fails.

label is a short human-readable name used in error messages. Typical use:

// fetch with refspec "+<src>:<tmpRefName>"
refs := checkpoint.ResolveRefs(ctx)
return PromoteTmpRefSafely(ctx, tmpRefName, refs.Primary, refs.Primary.Short())

func PushQueuedCheckpointRefs ¶ added in v0.9.0

func PushQueuedCheckpointRefs(ctx context.Context, repo *git.Repository, remote string) (pushed int, pushDisabled bool, err error)

PushQueuedCheckpointRefs pushes any queued checkpoint refs to the configured checkpoint remote, surfacing errors (unlike the fail-soft pre-push path); the caller owns the repo. It returns the number of refs pushed and whether pushing is disabled in settings — a distinct signal from pushed==0 with pushing enabled (an empty queue), so callers can report the two accurately. Like the pre-push paths, an OPF rewrite that cannot run when OPF is enabled errors with the refs left queued. Currently used by the checkpoint migration command's opt-in "push now".

func ReadAgentTypeFromTree ¶ added in v0.4.4

func ReadAgentTypeFromTree(tree *object.Tree, checkpointPath string) types.AgentType

ReadAgentTypeFromTree reads the agent type from a checkpoint's metadata.json file in a git tree. If metadata.json doesn't exist, it falls back to detecting the agent from the presence of agent-specific config markers (.claude/, .codex/, .cursor/, etc.). Returns agent.AgentTypeUnknown if the agent type cannot be determined.

func ReadAllSessionPromptsFromTree ¶

func ReadAllSessionPromptsFromTree(tree *object.Tree, checkpointPath string, sessionCount int, sessionIDs []string) []string

ReadAllSessionPromptsFromTree reads the first prompt for all sessions in a multi-session checkpoint. Returns a slice of prompts parallel to sessionIDs (oldest to newest). For single-session checkpoints, returns a slice with just the session prompt.

func ReadLatestSessionPromptFromCommittedTree ¶ added in v0.4.9

func ReadLatestSessionPromptFromCommittedTree(tree *object.Tree, cpID id.CheckpointID, sessionCount int) string

ReadLatestSessionPromptFromCommittedTree reads the first prompt from a committed checkpoint's latest session on the metadata branch tree. This navigates the sharded directory layout: <cpID.Path()>/<latestSessionIndex>/prompt.txt

Falls back through earlier sessions when the latest has no prompt. Avoids reading full transcripts — only reads prompt.txt files. sessionCount is the number of sessions in the checkpoint (from CheckpointInfo.SessionCount).

func ReadSessionPromptFromTree ¶

func ReadSessionPromptFromTree(tree *object.Tree, checkpointPath string) string

ReadSessionPromptFromTree reads the first meaningful prompt from a checkpoint's prompt.txt file in a git tree. Returns an empty string if the prompt cannot be read.

func ReconcileDisconnectedMetadataRef ¶ added in v0.7.6

func ReconcileDisconnectedMetadataRef(
	ctx context.Context,
	repo *git.Repository,
	localRefName plumbing.ReferenceName,
	remoteRefName plumbing.ReferenceName,
	w io.Writer,
) error

ReconcileDisconnectedMetadataRef detects and repairs disconnected local/remote metadata refs. Disconnected means no common ancestor, which only happens due to the empty-orphan bug. Diverged (shared ancestor) is normal and handled by the push path.

Repair strategy: cherry-pick local commits onto remote tip, preserving all data. Checkpoint shards use unique paths (<id[:2]>/<id[2:]>/), so cherry-picks always apply cleanly.

Progress messages are written to w (typically os.Stderr for hooks or cmd.ErrOrStderr() for commands). The remote ref can be either a remote-tracking ref or a temporary fetched ref.

func RecordFilesTouched ¶ added in v0.6.2

func RecordFilesTouched(ctx context.Context, sessionID string, modified, added, deleted []string) error

RecordFilesTouched merges paths into the session's FilesTouched, used by mid-turn lifecycle events (per-tool-use hooks) so PostCommit's carry-forward decision sees an accurate file list. Caller must pre-normalize paths to repo-relative form. No-ops when the session state doesn't exist or the merge produced no changes.

func ReinstallGitHooks ¶ added in v0.10.1

func ReinstallGitHooks(ctx context.Context) (int, error)

ReinstallGitHooks rewrites the managed git hooks using this repo's hook settings — the same pair EnsureSetup runs, exported so callers outside this package cannot open-code it and silently drop absolute_git_hook_path.

func RemoveGitHook ¶

func RemoveGitHook(ctx context.Context) (int, error)

RemoveGitHook removes all Entire CLI git hooks from the repository. If a .pre-entire backup exists, it is restored. Returns the number of hooks removed.

func ResetRedactionConfiguredForTest ¶ added in v0.10.6

func ResetRedactionConfiguredForTest()

ResetRedactionConfiguredForTest reinitializes the EnsureRedactionConfigured sync.Once so a test in another package can assert that a command's entry point configures redaction. Without it the Once may already be consumed by an earlier test in the same process, and the assertion passes or fails on test order rather than on the wiring under test.

func ResolveAgentForResume ¶ added in v0.10.4

func ResolveAgentForResume(agentType types.AgentType) (agent.Agent, error)

ResolveAgentForResume resolves the agent from checkpoint metadata.

func ResolveTranscriptPath ¶ added in v0.6.2

func ResolveTranscriptPath(state *SessionState) (string, error)

ResolveTranscriptPath is the exported wrapper around resolveTranscriptPath for callers outside the strategy package (e.g. CLI commands streaming a live transcript to stdout). The underlying function may update state.TranscriptPath when an agent has relocated the file mid-session.

func RewriteQueuedCheckpointRefsWithOPF ¶ added in v0.10.3

func RewriteQueuedCheckpointRefsWithOPF(ctx context.Context, repo *git.Repository) error

RewriteQueuedCheckpointRefsWithOPF re-redacts the checkpoint refs awaiting push with OPF, rebuilds every un-applied commit on each as a commit carrying Entire-OPF-Applied: true, and points the ref at the new tip. Idempotent: a ref whose tip already carries the trailer is left byte-identical.

Discovery is the push-discovery queue rather than a local-vs-remote diff: it already names exactly the refs this push will carry, so there is no merge-base or divergence analysis. Within a ref, pushing it carries its whole unpushed ancestry, so the walk covers every commit back to the first one already carrying the trailer (unappliedAncestry) — bounded by the same resolveBootstrapLimit the v1 path uses.

Caller checks redact.OPFEnabled() and skips this when OPF is off. Returns the same error taxonomy as RewriteUnpushedV1WithOPF; the caller fails closed by withholding the flush (see prePushCheckpointRefs).

func RewriteUnpushedV1WithOPF ¶ added in v0.7.8

func RewriteUnpushedV1WithOPF(ctx context.Context, repo *git.Repository, target string) (plumbing.Hash, error)

RewriteUnpushedV1WithOPF re-redacts unpushed entire/checkpoints/v1 commits with OPF, builds new commits carrying Entire-OPF-Applied: true, and CAS-updates the local ref. Idempotent: already-applied commits are re-parented without re-running OPF.

Caller checks redact.OPFEnabled() and skips this when OPF is off. Returns one of {V1DivergedError, BootstrapTooLargeError, V1RefMovedError, OPFRuntimeFailedError, OPFNoCategoriesError, OPFBatchTooLargeError, OPFRawBytesTooLargeError} for privacy-critical failures — the pre-push hook propagates these so git push aborts.

func SafelyAdvanceLocalRef ¶ added in v0.5.6

func SafelyAdvanceLocalRef(ctx context.Context, repo *git.Repository, localRefName plumbing.ReferenceName, targetHash plumbing.Hash) error

SafelyAdvanceLocalRef updates localRefName to include targetHash without dropping local-only commits. Missing and behind refs advance to targetHash; already-current or locally-ahead refs are left unchanged; diverged refs replay commits after the merge-base onto targetHash and move localRefName to the replayed tip. If there is no merge-base and the reachable histories are complete, the full local chain is replayed.

func SaveSessionState ¶

func SaveSessionState(ctx context.Context, state *SessionState) error

SaveSessionState saves the session state atomically.

func SetBeforeCondense ¶ added in v0.11.4

func SetBeforeCondense(fn func(ctx context.Context, sessions []*SessionState) bool)

SetBeforeCondense registers the hook PostCommit runs for the sessions it is about to condense (nil clears it). The cli registers the Codex child-ledger refresh here, so child task records are reconciled in exactly the set PostCommit stores.

func ShellQuoteForDisplay ¶ added in v0.11.4

func ShellQuoteForDisplay(s string) string

ShellQuoteForDisplay quotes a value for a command line the USER will paste. It is not for building an argv -- nothing here is executed, and a path that reaches an exec goes as a separate argument instead (see docs/development/git-safety.md's "Never Put a Dynamic Value on a cmd.exe Line").

The POSIX branch delegates to shellQuote, this file's existing quoter for the #!/bin/sh hooks it generates, rather than repeating the escaping: single quoting is total, since the only character with meaning inside a single-quoted string is the closing quote. Windows shells have no equivalent, so double quotes are used there, which is what cmd.exe and PowerShell both accept for a path.

Quoted only when it has to be, so the ordinary path stays readable.

func StoreAgentTypeHint ¶ added in v0.6.0

func StoreAgentTypeHint(ctx context.Context, sessionID string, agentType types.AgentType) (created bool, err error)

StoreAgentTypeHint records the agent type that owns a session before SessionState exists. Used by the lifecycle dispatcher when SessionStart fires (state isn't created until TurnStart, so we need a place to remember which agent claimed the session first).

Semantics: first writer wins. When multiple agents fire hooks for the same session ID — e.g., Cursor IDE running cursor-agent while also forwarding to Claude Code's hook system — only the agent that fires SessionStart first gets recorded. Subsequent calls return nil without overwriting.

At TurnStart, InitializeSession reads this hint to override agentType when the hook firing isn't the same agent that owns the session. After the state file is written, the hint is unused but remains until ClearSessionState removes it alongside the state file.

Returns (created=true) when this call wrote the hint, (created=false) when the hint already existed (no-op) or agentType was empty/Unknown.

Banner display is gated separately via ClaimSessionStartBanner — winning the ownership claim does NOT mean this agent should also print the banner, because the winner may not implement HookResponseWriter (e.g., Cursor).

func StoreModelHint ¶ added in v0.5.0

func StoreModelHint(ctx context.Context, sessionID, model string) error

StoreModelHint writes the LLM model name to a lightweight hint file (.git/entire-sessions/{session_id}.model) for cross-process persistence.

Why a separate file instead of SessionState?

SessionState requires BaseCommit (used for commit linking, checkpoint writing, doctor classification, etc.) and is only created during TurnStart when the git repo is fully inspected. Some agents report the model on earlier hooks that fire as separate CLI processes before TurnStart:

• Claude Code sends "model" on SessionStart (before any TurnStart)

The hint is read by handleLifecycleTurnStart/TurnEnd when event.Model is empty, passed to InitializeSession, and persisted in state.ModelName. After that the hint file is redundant — it sits unused until ClearSessionState removes it alongside the session state file.

func TaskMetadataDir ¶

func TaskMetadataDir(sessionMetadataDir, toolUseID string) string

TaskMetadataDir returns the path to a task's metadata directory within the session metadata directory.

func TransitionAndLog ¶ added in v0.3.13

func TransitionAndLog(goCtx context.Context, state *SessionState, event session.Event, ctx session.TransitionContext, handler session.ActionHandler) error

TransitionAndLog runs a session phase transition, applies actions via the handler, and logs the transition. Returns the first handler error from ApplyTransition (if any) so callers can surface it. The error is also logged internally for diagnostics. This is the single entry point for all state machine transitions to ensure consistent logging of phase changes.

func TruncateDescription ¶

func TruncateDescription(s string, maxLen int) string

TruncateDescription truncates a string to maxLen runes, adding "..." if truncated. Uses rune-based slicing to avoid splitting multi-byte UTF-8 characters. If maxLen is less than 3, truncates without ellipsis.

func UpsertCompletedTaskRecord ¶ added in v0.10.3

func UpsertCompletedTaskRecord(ctx context.Context, sessionID string, rec session.TaskRecord) error

UpsertCompletedTaskRecord writes a COMPLETED task record, merging files into any existing record for the same ToolUseID — the multi-turn producer shape (Factory Droid Workers reach turn-end once per Worker turn, all attributed to one parent tool use), unlike CompleteTaskRecord's exactly-once claim.

func WarnIfMetadataDisconnected ¶ added in v0.5.0

func WarnIfMetadataDisconnected(ctx context.Context)

WarnIfMetadataDisconnected checks (once per process) whether the metadata branch is disconnected and prints a warning to stderr if so. The check runs against the first checkpoint read candidate whose remote-tracking ref exists (pure read across both tiers). It does NOT fix the problem — users are directed to 'entire doctor'.

Takes the caller's context rather than context.Background(): the probe below reads git, so a detached context ignored both interrupt cancellation and the invocation-scoped remote-read cache, re-shelling out for answers the caller already had.

Uses sync.Once, so a transient failure on the first call permanently suppresses the warning. This is acceptable because the check is advisory only and 'entire doctor' is the authoritative repair path.

func WithCheckpointRemoteBootstrap ¶ added in v0.9.0

func WithCheckpointRemoteBootstrap(ctx context.Context) context.Context

WithCheckpointRemoteBootstrap marks ctx as permitting EnsurePrimaryRef to fetch a missing primary metadata ref from a configured checkpoint_remote. This must only be set on explicit, user-initiated setup flows (`entire enable`, agent add/setup) — never on the per-turn hook hot path. EnsureSetup runs synchronously on every TurnStart hook and hook execution has a hard timeout; without this guard a slow/unreachable checkpoint remote would repeat an expensive fetch on every turn instead of self-healing once via the empty-orphan fallback.

func WithFreshGitRemoteCache ¶ added in v0.10.1

func WithFreshGitRemoteCache(ctx context.Context) context.Context

WithFreshGitRemoteCache installs a new cache even when the parent context already carries one, giving a long-lived process a per-unit-of-work window instead of one snapshot for its whole lifetime.

func WithGitRemoteCache ¶ added in v0.10.1

func WithGitRemoteCache(ctx context.Context) context.Context

WithGitRemoteCache returns a context whose .git/config remote reads are memoized for the lifetime of that context, reusing an already-installed cache if there is one. Never span a git-remote mutation without calling InvalidateGitRemoteCache.

main() installs this on the root context, which is the whole process. Answers are partitioned per repository (see gitRemoteCache), so a command walking several repositories stays correct. What process scope does NOT give is freshness over time: `entire mcp` serves an agent session from one context, so it installs a fresh window per request rather than pinning one snapshot for hours. A command that runs long enough for a remote to be added underneath it should do the same.

func WithSessionLockWait ¶ added in v0.10.0

func WithSessionLockWait(ctx context.Context, wait time.Duration) context.Context

WithSessionLockWait returns a context whose session-state flock acquisitions are bounded to complete within wait from now (a shared wall-clock budget). Zero or negative leaves the wait unbounded (the default, used by turn-end/condensation which must not drop work). Only the lock acquisition is bounded; the mutation itself still runs under the caller's original context.

func WithSessionStateLocks ¶ added in v0.7.8

func WithSessionStateLocks(ctx context.Context, sessionID string, commonDirs []string, fn func() error) error

WithSessionStateLocks acquires the per-session state lock in each git common dir, then runs fn. Lock paths are deduplicated and sorted so callers that span repositories or worktrees can safely acquire more than one lock.