@searls/turbocommit 0.14.1 → 0.15.1

package/README.md

@@ -2,7 +2,7 @@
 
 # turbocommit
 
-turbocommit creates a git commit containing everything Claude Code or Codex
+turbocommit creates a git commit containing the paths Claude Code or Codex
 changes on each turn. Think of it like save state in a game emulator: whenever
 you fall in a pit, you can safely rewind and try again.
 
@@ -18,19 +18,39 @@ sessions concurrently and detangle which agent committed what after the fact.
 
 turbocommit registers hooks with the harnesses you use:
 
-- Claude Code: **PreToolUse**, **SessionStart**, **SessionEnd**, and **Stop**.
-- Codex: **PreToolUse**, **SessionStart**, **PreCompact**, and
-  **Stop**.
-
-- **PreToolUse** tracks which sessions actually modify files (Write, Edit,
-  MultiEdit, NotebookEdit, MCP tools). Read-only sessions (Grep, Read,
-  Bash-only) are never committed.
+- Claude Code: **PreToolUse**, **PostToolUse**, **PostToolUseFailure**,
+  **SessionStart**, **SessionEnd**, and **Stop**.
+- Codex: **PreToolUse**, **PostToolUse**, **SessionStart**, **SessionEnd**,
+  **PreCompact**, and **Stop**.
+
+- **PreToolUse** tentatively claims the paths supplied to editing tools while
+  recovery finishes, promotes the claim only when the tool may proceed, and
+  snapshots the repository before shell commands.
+- **PostToolUse** attributes paths that became dirty during a shell command.
+  Concurrent commands in one session share ownership. Commands from different
+  sessions retain hashed overlap evidence instead of claiming each other's
+  paths. Once every involved turn stops and no shell remains active in that
+  checkout, unchanged and otherwise-unclaimed paths are committed separately
+  as recovered shell changes. Evidence is scoped to its exact worktree and is
+  permanently discarded if file contents or executable modes change, or if an
+  unfinished shell snapshot expires.
+- **PostToolUseFailure**, **Stop**, and **SessionEnd** finalize shell snapshots
+  whose normal post hook did not arrive. Claude normally finishes within its
+  SessionEnd hook. If its internal deadline expires, Turbocommit stores the
+  worktree in a hidden local rescue ref before starting a detached worker. The
+  worker can recreate a removed checkout at its recorded commit, but it leaves
+  the rescue intact if the original checkout identity or branch has changed.
+  Every completed deadline rescue remains reachable through a hidden local
+  safety ref, including detached-HEAD recovery. Codex preserves the transcript
+  and starts the normal commit and recovery path in a detached worker so it can
+  finish beyond Codex's three-second hook deadline. Read-only tracking is then
+  removed.
 - **SessionStart / SessionEnd** chain sessions across `/clear` boundaries
   so planning context survives into the eventual commit.
 - **PreCompact** on Codex buffers visible transcript context before compaction.
-- **Stop** fires after every turn. If the session modified files, it
-  commits with `git add -A`. If not, it buffers the transcript for pickup
-  by a later session that does commit.
+- **Stop** fires after every turn. If the session modified files, it stages and
+  commits only the paths tracked for that session. If not, it buffers the
+  transcript for pickup by a later session that does commit.
 
 ### Changes across multiple repositories
 
@@ -43,7 +63,8 @@ additional repositories.
 Each touched checkout:
 
 - Reads its own merged global and project configuration.
-- Keeps the normal `git add -A` behavior.
+- Stages only paths attributed to the current session, preserving unrelated
+  staged and unstaged work.
 - Gets an independent commit with the full turn transcript.
 - Gives the configured title agent repository-specific bounded diff context.
 
@@ -56,6 +77,29 @@ committed and pushed before enabled parent repositories. When one turn creates
 commits in multiple repositories, each commit includes a shared
 `Turbocommit-Session` trailer.
 
+Relative tool paths are matched to the checkout where that path changed. If the
+same relative path is dirty in multiple worktrees, Turbocommit skips the turn
+with an `ambiguous-tracking` monitor reason instead of guessing which checkout
+owns it, then clears that ambiguous tracking so later turns can proceed. Direct
+editing tools such as `apply_patch` resolve relative paths from their recorded
+working directory. Path-bearing MCP tools may report singular paths, path
+arrays, or local file URIs. Pathless tool calls and directory-valued path fields
+do not claim files or prevent later exact edits in the same session from
+committing.
+
+Before staging, Turbocommit resolves tracked paths to the exact changed files,
+treats Git pathspec metacharacters literally, drops paths that are no longer
+dirty, and excludes newly discovered embedded repositories. Existing tracked
+submodule gitlinks remain eligible so child commits can update their parent.
+During an active merge, cherry-pick, revert, or rebase, Git forbids partial
+commits, so Turbocommit commits the operation's resolved index as a whole.
+Recovered overlap evidence is deferred until the operation ends because its
+generic commit must remain path-scoped.
+
+Retry manifests created by older versions did not record path ownership. On
+upgrade, Turbocommit discards those unsafe retry entries and records a
+`legacy-manifest` monitor event rather than guessing which files they owned.
+
 The commit message headline is generated by a title agent (configurable).
 The body contains the full prompt/response transcript. When planning
 context was buffered from ancestor sessions, it appears under a
@@ -102,10 +146,11 @@ brew uninstall turbocommit
 ## Where turbocommit goes in your hook chain
 
 `turbocommit install` adds one hook group per event for each installed harness.
-The hooks are fire-and-forget: they always exit 0 and never block the agent.
+The hooks ordinarily exit 0. A modifying PreToolUse hook denies the tool when
+turbocommit cannot safely coordinate with an in-progress recovery, so the
+agent can retry instead of making an unowned change.
 
 If you rearrange your hooks manually, the turbocommit hooks can go anywhere.
-Order doesn't matter since they never block.
 
 Codex users should restart Codex and run `/hooks` after install to review and
 trust the hook commands.

package/cli.js

@@ -1,15 +1,32 @@
 #!/usr/bin/env node
 
-const { readStdin } = require('./lib/io')
+const { spawn } = require('child_process')
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const { readStdin, ensureDir } = require('./lib/io')
 const { install, uninstall } = require('./lib/install')
 const { init, deinit } = require('./lib/init')
-const { run, runPreCompact } = require('./lib/run')
-const { handleTrack } = require('./lib/track')
-const { handleSessionStart, handleSessionEnd } = require('./lib/session')
+const { run, runPreCompact, recoverBashOverlaps } = require('./lib/run')
+const { handleTrack, handlePostTrack, finalizeBashSnapshots, recordBashSessionStop, readTracking } = require('./lib/track')
+const { handleSessionStart, handleSessionEnd, turbocommitDir } = require('./lib/session')
 const { doctor } = require('./lib/doctor')
 const { monitor } = require('./lib/monitor')
-const { gitRoot } = require('./lib/git')
+const { gitRoot, pushClean } = require('./lib/git')
+const { activeConfig } = require('./lib/config')
+const { logEvent } = require('./lib/log')
 const { parseHarnessArg, normalizeHookInput } = require('./lib/harness')
+const {
+  createSessionEndRescue,
+  restoreSessionEndRescue,
+  matchesSessionEndRescueRoot,
+  finalizeRestoredSessionEndRescue,
+  preserveSessionEndRecoveredCommit,
+  recordPreservedSessionEndRescue,
+  removeSessionEndRescueWorktree,
+  cleanupSessionEndRescue,
+  isClean
+} = require('./lib/rescue')
 
 const VERSION = require('./package.json').version
 
@@ -59,6 +76,10 @@ function main (argv) {
       return cmdDeinit()
     case 'hook':
       return cmdHook(parsed.args.slice(1), parsed.harness)
+    case 'session-end-worker':
+      return cmdSessionEndWorker(parsed.args.slice(1), parsed.harness)
+    case 'session-end-rescue-worker':
+      return cmdSessionEndRescueWorker(parsed.args.slice(1))
     case 'run':
       return cmdRunDeprecated()
     case '--version':
@@ -165,6 +186,7 @@ function cmdMonitor (harness) {
 }
 
 function cmdHook (argv, harness) {
+  if (process.env.TURBOCOMMIT_DISABLED) return
   const event = argv[0]
   try {
     const input = readStdin()
@@ -173,13 +195,27 @@ function cmdHook (argv, harness) {
     const root = gitRoot(hookInput.cwd || process.cwd())
     switch (event) {
       case 'pre-tool-use':
-        handleTrack(hookInput, root)
+        try {
+          if (handleTrack(hookInput, root) === false) denyPreToolUse()
+        } catch {
+          denyPreToolUse()
+        }
+        return
+      case 'post-tool-use':
+        handlePostTrack(hookInput, root)
         return
       case 'session-start':
         handleSessionStart(hookInput, root)
         return
       case 'session-end':
         handleSessionEnd(hookInput, root)
+        if (hookInput.harness === 'claude') {
+          let completed = false
+          try { completed = completeSessionEnd(hookInput, root, 45000) } catch {}
+          if (!completed) rescueClaudeSessionEnd(hookInput, root)
+        } else {
+          spawnSessionEndWorker(hookInput, root, harness)
+        }
         return
       case 'pre-compact':
         runPreCompact(hookInput)
@@ -196,6 +232,214 @@ function cmdHook (argv, harness) {
   }
 }
 
+function spawnSessionEndWorker (hookInput, root, harness) {
+  if (process.env.TURBOCOMMIT_DISABLED || !root || !hookInput.sessionId) return
+  const transcript = copySessionEndTranscript(root, hookInput.transcriptPath)
+  const payload = Buffer.from(JSON.stringify({
+    sessionId: hookInput.sessionId,
+    event: 'SessionEnd',
+    cwd: root,
+    harness: hookInput.harness || harness,
+    transcriptPath: transcript.path,
+    temporaryTranscript: transcript.temporary,
+    model: hookInput.model
+  })).toString('base64url')
+  const args = [__filename, 'session-end-worker', payload]
+  if (harness) args.push('--harness', harness)
+  const child = spawn(process.execPath, args, {
+    cwd: stableWorkerCwd(root),
+    detached: true,
+    stdio: 'ignore'
+  })
+  child.on('error', () => {
+    if (transcript.temporary) cleanupSessionEndTranscript(root, transcript.path)
+  })
+  child.unref()
+}
+
+function cmdSessionEndWorker (argv, harness) {
+  if (process.env.TURBOCOMMIT_DISABLED) return
+  let hookInput
+  try {
+    hookInput = JSON.parse(Buffer.from(argv[0], 'base64url').toString('utf8'))
+  } catch {
+    return
+  }
+  hookInput.harness = hookInput.harness || harness
+  const root = gitRoot(hookInput.cwd || process.cwd())
+  try {
+    if (!root || !hookInput.sessionId) return
+    completeSessionEnd(hookInput, root, Infinity)
+  } finally {
+    if (hookInput.temporaryTranscript) cleanupTemporarySessionEndTranscript(root, hookInput.transcriptPath)
+  }
+}
+
+function completeSessionEnd (hookInput, root, waitMs, { deferPush = false } = {}) {
+  if (!root || !hookInput.sessionId) return false
+  const deadline = waitMs === Infinity ? Infinity : Date.now() + waitMs
+  const remainingWait = () => deadline === Infinity ? Infinity : Math.max(0, deadline - Date.now())
+  const finalized = finalizeBashSnapshots(root, hookInput.sessionId, Date.now(), remainingWait())
+  if (finalized == null) return false
+  if (readTracking(root, hookInput.sessionId).length > 0) {
+    run(hookInput, { recoveryDeadline: deadline, operationDeadline: deadline, deferPush })
+    return readTracking(root, hookInput.sessionId).length === 0
+  }
+  recordBashSessionStop(root, hookInput.sessionId)
+  const recoveryConfig = deferPush ? { ...activeConfig(root).config, push: false } : undefined
+  recoverBashOverlaps(root, hookInput, recoveryConfig, remainingWait())
+  return true
+}
+
+function rescueClaudeSessionEnd (hookInput, root) {
+  if (!root || !hookInput.sessionId) return
+  const transcript = copySessionEndTranscript(root, hookInput.transcriptPath)
+  const rescueInput = {
+    ...hookInput,
+    transcriptPath: transcript.path,
+    temporaryTranscript: transcript.temporary
+  }
+  const rescue = createSessionEndRescue(root, rescueInput)
+  if (!rescue) {
+    if (transcript.temporary) cleanupTemporarySessionEndTranscript(root, transcript.path)
+    return
+  }
+  spawnSessionEndRescueWorker(rescue)
+}
+
+function spawnSessionEndRescueWorker (rescue) {
+  const payload = Buffer.from(JSON.stringify(rescue)).toString('base64url')
+  const child = spawn(process.execPath, [__filename, 'session-end-rescue-worker', payload], {
+    cwd: stableWorkerCwd(rescue.root),
+    detached: true,
+    stdio: 'ignore'
+  })
+  child.on('error', () => {})
+  child.unref()
+}
+
+function cmdSessionEndRescueWorker (argv) {
+  let rescue
+  try {
+    rescue = JSON.parse(Buffer.from(argv[0], 'base64url').toString('utf8'))
+  } catch {
+    return
+  }
+  let recreated = false
+  let completed = false
+  try {
+    const existingRoot = gitRoot(rescue.root)
+    if (existingRoot) {
+      if (!matchesSessionEndRescueRoot(rescue, existingRoot)) return
+      try { completed = completeSessionEnd(rescue.hookInput, existingRoot, Infinity) } catch {}
+    }
+    if (!completed && !fs.existsSync(rescue.root)) {
+      recreated = restoreRescueWithRetry(rescue)
+      if (recreated) {
+        try { completed = completeSessionEnd(rescue.hookInput, rescue.root, Infinity, { deferPush: true }) } catch {}
+      }
+    }
+    if (!completed) return
+    const clean = isClean(rescue.root)
+    if (!recreated) {
+      const recovered = preserveSessionEndRecoveredCommit(rescue, rescue.root)
+      if (!recovered) return
+      if (clean) {
+        cleanupSessionEndRescue(rescue)
+      } else {
+        recordPreservedSessionEndRescue(rescue, recovered, 'dirty-existing-worktree')
+      }
+    } else {
+      const finalized = finalizeRestoredSessionEndRescue(rescue, { clean })
+      if (finalized.resolved) {
+        pushRestoredSessionEndRescue(rescue, finalized)
+        if (isClean(rescue.root)) {
+          cleanupSessionEndRescue(rescue, { removeWorktree: true })
+        } else {
+          recordPreservedSessionEndRescue(rescue, finalized, 'dirty-attached-worktree')
+        }
+      } else if (finalized.preserved && finalized.removeWorktree) {
+        removeSessionEndRescueWorktree(rescue)
+      }
+    }
+    if (rescue.hookInput?.temporaryTranscript) {
+      cleanupTemporarySessionEndTranscript(rescue.root, rescue.hookInput.transcriptPath)
+    }
+  } catch {
+    // The rescue ref and record remain available for a later retry.
+  }
+}
+
+function pushRestoredSessionEndRescue (rescue, finalized) {
+  const config = activeConfig(rescue.root).config
+  if (config.push !== true) return
+  const pushed = finalized.attached && pushClean(rescue.root)
+  logEvent(pushed ? 'push' : 'push-fail', {
+    harness: rescue.hookInput?.harness,
+    project: path.basename(rescue.root),
+    branch: rescue.branch
+  })
+}
+
+function restoreRescueWithRetry (rescue) {
+  const deadline = Date.now() + 30000
+  const sleeper = new Int32Array(new SharedArrayBuffer(4))
+  while (!fs.existsSync(rescue.root)) {
+    if (restoreSessionEndRescue(rescue)) return true
+    if (Date.now() >= deadline) return false
+    Atomics.wait(sleeper, 0, 0, 100)
+  }
+  return false
+}
+
+function stableWorkerCwd (root) {
+  const base = turbocommitDir(root)
+  return base ? path.dirname(base) : root
+}
+
+function copySessionEndTranscript (root, source) {
+  if (!source) return { path: source, temporary: false }
+  const base = turbocommitDir(root)
+  if (!base) return { path: source, temporary: false }
+  const dir = path.join(base, 'session-end-transcripts')
+  const destination = path.join(dir, `${process.pid}-${crypto.randomUUID()}.jsonl`)
+  try {
+    ensureDir(dir)
+    fs.copyFileSync(source, destination)
+    return { path: destination, temporary: true }
+  } catch {
+    return { path: source, temporary: false }
+  }
+}
+
+function cleanupSessionEndTranscript (root, transcriptPath) {
+  const base = turbocommitDir(root)
+  if (!base || !transcriptPath) return false
+  const dir = path.join(base, 'session-end-transcripts')
+  if (path.dirname(path.resolve(transcriptPath)) !== path.resolve(dir)) return false
+  try { fs.unlinkSync(transcriptPath) } catch {}
+  return !fs.existsSync(transcriptPath)
+}
+
+function cleanupTemporarySessionEndTranscript (root, transcriptPath) {
+  if (root && cleanupSessionEndTranscript(root, transcriptPath)) return
+  if (!transcriptPath) return
+  const resolved = path.resolve(transcriptPath)
+  if (path.basename(path.dirname(resolved)) !== 'session-end-transcripts') return
+  if (!/^\d+-[0-9a-f-]{36}\.jsonl$/i.test(path.basename(resolved))) return
+  try { fs.unlinkSync(resolved) } catch {}
+}
+
+function denyPreToolUse () {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: 'turbocommit could not safely persist path ownership; retry the tool'
+    }
+  }) + '\n')
+}
+
 function cmdRunDeprecated () {
   let hookInput
   try {

package/lib/agent.js

@@ -32,14 +32,18 @@ function renderPrompt (template, transcript) {
   return template.replace(/\{\{transcript\}\}/g, () => transcript)
 }
 
-function runAgent (root, command, prompt) {
+function runAgent (root, command, prompt, opts = {}) {
   const binary = command.split(/\s+/)[0]
   const whichResult = tryRun(`which ${binary}`, {})
   if (whichResult.code !== 0) return null
+  const timeout = Number.isFinite(opts.deadline)
+    ? Math.min(45000, Math.max(0, opts.deadline - Date.now()))
+    : 45000
+  if (timeout <= 0) return null
 
   const result = tryRun(command, {
     cwd: root,
-    timeout: 45000,
+    timeout,
     input: prompt,
     env: { ...process.env, TURBOCOMMIT_DISABLED: '1', CLAUDECODE: '' }
   })
@@ -54,21 +58,21 @@ function defaultCommand (harness) {
   return harness === 'codex' ? DEFAULT_CODEX_COMMAND : DEFAULT_COMMAND
 }
 
-function runTitleAgent (root, titleCfg, transcript, harness) {
+function runTitleAgent (root, titleCfg, transcript, harness, opts) {
   const command = titleCfg.command || defaultCommand(harness)
   const template = titleCfg.prompt || DEFAULT_TITLE_PROMPT
   const prompt = renderPrompt(template, transcript)
-  const result = runAgent(root, command, prompt)
+  const result = runAgent(root, command, prompt, opts)
   if (!result) return null
   // Take only first line and enforce 72 char limit
   return result.split('\n')[0].slice(0, 72) || null
 }
 
-function runBodyAgent (root, bodyCfg, transcript, harness) {
+function runBodyAgent (root, bodyCfg, transcript, harness, opts) {
   const command = bodyCfg.command || defaultCommand(harness)
   const template = bodyCfg.prompt || DEFAULT_BODY_PROMPT
   const prompt = renderPrompt(template, transcript)
-  return runAgent(root, command, prompt)
+  return runAgent(root, command, prompt, opts)
 }
 
 module.exports = {

package/lib/git.js

@@ -13,12 +13,32 @@ function git (args, opts = {}) {
 
 function gitRoot (cwd) {
   try {
-    return git('rev-parse --show-toplevel', { cwd })
+    return canonicalRoot(git('rev-parse --show-toplevel', { cwd }))
   } catch {
     return null
   }
 }
 
+function canonicalRoot (filePath) {
+  const target = path.resolve(filePath)
+  let probe = target
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe)
+    if (parent === probe) return target
+    probe = parent
+  }
+  try {
+    return path.join(fs.realpathSync(probe), path.relative(probe, target))
+  } catch {
+    return target
+  }
+}
+
+function canonicalTrackedPath (filePath) {
+  const target = path.resolve(filePath)
+  return path.join(canonicalRoot(path.dirname(target)), path.basename(target))
+}
+
 function gitRootForPath (filePath) {
   let probe = filePath
   try {
@@ -34,6 +54,25 @@ function gitRootForPath (filePath) {
   return gitRoot(probe)
 }
 
+function gitWorktrees (cwd) {
+  try {
+    return git('worktree list --porcelain', { cwd })
+      .split('\n')
+      .filter(line => line.startsWith('worktree '))
+      .map(line => line.slice('worktree '.length))
+      .map(root => {
+        try {
+          return fs.realpathSync(root)
+        } catch {
+          return null
+        }
+      })
+      .filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
 function gitCommonDir (cwd) {
   try {
     const out = git('rev-parse --git-common-dir', { cwd })
@@ -60,6 +99,10 @@ function hasChanges (cwd) {
   return untracked.length > 0
 }
 
+function hasPathChanges (cwd, filePath) {
+  return changedPaths(cwd, [filePath]).length > 0
+}
+
 function addAndCommit (cwd, headline, body) {
   stageAll(cwd)
   commitStaged(cwd, headline, body)
@@ -70,15 +113,42 @@ function stageAll (cwd) {
   git('add -A', { cwd })
 }
 
+function stagePaths (cwd, filePaths) {
+  const changed = changedPaths(cwd, filePaths)
+  const paths = pathspecs(cwd, changed)
+  if (paths.length === 0) return []
+  git(`add -A -- ${paths.map(quote).join(' ')}`, { cwd })
+  return changed
+}
+
+function commitPaths (cwd, filePaths, headline, body, opts = {}) {
+  if (opts.pathScoped && hasRepositoryOperation(cwd)) return null
+  const changed = stagePaths(cwd, filePaths)
+  return commitStagedPaths(cwd, changed, headline, body, opts)
+}
+
+function commitStagedPaths (cwd, filePaths, headline, body, opts = {}) {
+  const paths = pathspecs(cwd, filePaths)
+  if (paths.length === 0) return null
+  if (hasRepositoryOperation(cwd)) {
+    return opts.pathScoped ? null : commitStaged(cwd, headline, body)
+  }
+  git(`commit --only -m "${esc(headline)}" -m "${esc(body)}" --no-verify -- ${paths.map(quote).join(' ')}`, { cwd })
+  return git('rev-parse HEAD', { cwd })
+}
+
 function commitStaged (cwd, headline, body) {
   git(`commit -m "${esc(headline)}" -m "${esc(body)}" --no-verify`, { cwd })
   return git('rev-parse HEAD', { cwd })
 }
 
-function stagedChangeContext (cwd, budget = 20000) {
-  const status = git('status --short', { cwd })
-  const stat = git('diff --cached --stat', { cwd })
-  const diff = git('diff --cached --no-ext-diff --unified=3', { cwd })
+function stagedChangeContext (cwd, budget = 20000, filePaths) {
+  const selected = filePaths && filePaths.length > 0
+    ? ` -- ${pathspecs(cwd, filePaths).map(quote).join(' ')}`
+    : ''
+  const status = git(`status --short${selected}`, { cwd })
+  const stat = git(`diff --cached --stat${selected}`, { cwd })
+  const diff = git(`diff --cached --no-ext-diff --unified=3${selected}`, { cwd })
   const prefix = `Status:\n${status || '(clean)'}\n\nDiff stat:\n${stat || '(none)'}\n\nDiff:\n`
   const remaining = Math.max(0, budget - prefix.length)
   return prefix + (diff.length > remaining ? diff.slice(0, remaining) + '\n[... diff truncated ...]' : diff)
@@ -88,7 +158,7 @@ function isGitlink (parentRoot, childRoot) {
   const relative = path.relative(parentRoot, childRoot)
   if (!relative || relative.startsWith('..')) return false
   try {
-    return git(`ls-files --stage -- "${esc(relative)}"`, { cwd: parentRoot })
+    return git(`ls-files --stage -- ${quote(literalPathspec(relative))}`, { cwd: parentRoot })
       .split('\n')
       .some(line => line.startsWith('160000 '))
   } catch {
@@ -126,18 +196,102 @@ function esc (s) {
   return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`')
 }
 
+function quote (value) {
+  return `'${value.replace(/'/g, '\'"\'"\'')}'`
+}
+
+function pathspecs (cwd, filePaths) {
+  cwd = canonicalRoot(cwd)
+  return [...new Set(filePaths.map(filePath => path.relative(cwd, canonicalTrackedPath(filePath))))]
+    .filter(relative => relative && !relative.startsWith('..'))
+    .map(literalPathspec)
+}
+
+function literalPathspec (relative) {
+  return `:(literal)${relative}`
+}
+
+function changedPaths (cwd, filePaths) {
+  cwd = canonicalRoot(cwd)
+  const selected = pathspecs(cwd, filePaths)
+  if (selected.length === 0) return []
+  return collectChangedPaths(cwd, selected)
+}
+
+function changedPathsInRepository (cwd) {
+  cwd = canonicalRoot(cwd)
+  return collectChangedPaths(cwd, [])
+}
+
+function collectChangedPaths (cwd, selected) {
+  const args = selected.length > 0 ? ` -- ${selected.map(quote).join(' ')}` : ''
+  const tracked = hasCommits(cwd)
+    ? git(`diff --name-only --no-renames -z HEAD${args}`, { cwd })
+    : git(`ls-files --cached -z${args}`, { cwd })
+  const untracked = git(`ls-files --others --exclude-standard -z${args}`, { cwd })
+  const relativePaths = [...splitNull(tracked), ...splitNull(untracked)]
+  return [...new Set(relativePaths)]
+    .filter(relative => !isEmbeddedRepository(cwd, relative) || isHeadGitlink(cwd, relative))
+    .map(relative => path.join(cwd, relative))
+}
+
+function splitNull (value) {
+  return value ? value.split('\0').filter(Boolean) : []
+}
+
+function isEmbeddedRepository (cwd, relative) {
+  const candidate = path.join(cwd, relative)
+  try {
+    return fs.statSync(candidate).isDirectory() && fs.existsSync(path.join(candidate, '.git'))
+  } catch {
+    return false
+  }
+}
+
+function isHeadGitlink (cwd, relative) {
+  try {
+    return git(`ls-tree HEAD -- ${quote(literalPathspec(relative))}`, { cwd })
+      .split('\n')
+      .some(line => line.startsWith('160000 '))
+  } catch {
+    return false
+  }
+}
+
+function hasRepositoryOperation (cwd) {
+  return ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply']
+    .some(name => {
+      try {
+        const gitPath = git(`rev-parse --git-path ${quote(name)}`, { cwd })
+        return fs.existsSync(path.isAbsolute(gitPath) ? gitPath : path.join(cwd, gitPath))
+      } catch {
+        return false
+      }
+    })
+}
+
 module.exports = {
   git,
+  canonicalRoot,
+  canonicalTrackedPath,
   gitRoot,
   gitRootForPath,
+  gitWorktrees,
   gitCommonDir,
   hasChanges,
+  changedPaths,
+  changedPathsInRepository,
+  hasPathChanges,
   addAndCommit,
   stageAll,
+  stagePaths,
+  commitPaths,
+  commitStagedPaths,
   commitStaged,
   stagedChangeContext,
   hasCommits,
   currentBranch,
   pushClean,
-  isGitlink
+  isGitlink,
+  hasRepositoryOperation
 }