@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.33 → 0.1.35

package/packages/agent-hooks/src/rules/impl/git-history.ts

@@ -1,18 +1,18 @@
 /**
- * `branch -D`, `tag -d`, `switch -f`, `gc --prune[=<date>]`.
+ * `tag -d`, `switch -f`, `gc --prune[=<date>]`.
  * (`update-ref` in every form lives in git-plumbing.ts.)
  *
  * Ported from `blockedGitHistoryReason` in blocked-reason.mjs:78-86. None of
  * these bypass on a bare `--help`/`--version` the way the "core" rules do —
  * the original's `blockedGitPolicyReason` is called unconditionally, with no
- * `rmIsHelpOnly` gate — so neither does this. All four fall through
+ * `rmIsHelpOnly` gate — so neither does this. All three fall through
  * `classifyReason`'s default arm.
  */
 
 import type { Invocation } from '../shell/invocation.ts'
 import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
-import { branchForceDeletes, gcPrunesExplicitly, switchIsForced, tagDeletes } from './git-helpers.ts'
+import { gcPrunesExplicitly, switchIsForced, tagDeletes } from './git-helpers.ts'
 import { defaultGitMessage, detailString } from './messages.ts'
 
 function git(inv: Invocation): (Invocation & { kind: 'git' }) | null {
@@ -40,15 +40,6 @@ function make(id: string, subcommand: string, reasonFor: () => string, hits: (g:
   }
 }
 
-export const gitBranchForceDelete = make(
-  'git.branch-force-delete',
-  'branch',
-  () => 'git branch -D',
-  (g) => branchForceDeletes(g.rest),
-  ['git branch -D old-feature', 'git branch -aD', 'git branch --delete --force old-feature'],
-  ['git branch -d merged-feature', 'git branch feature-x', 'git branch -a'],
-)
-
 export const gitTagDelete = make(
   'git.tag-delete',
   'tag',
@@ -64,7 +55,7 @@ export const gitSwitchForce = make(
   () => 'git switch -f',
   (g) => switchIsForced(g.rest),
   ['git switch -f main', 'git switch --force main'],
-  ['git switch main', 'git switch -c new-branch'],
+  ['git switch main', 'git switch feat/existing'],
 )
 
 export const gitGcPrune = make(

package/packages/agent-hooks/src/rules/impl/git-target.ts

@@ -0,0 +1,423 @@
+// Best-effort static resolver of the repository a commit-like git command lands on. See docs/architecture/agent-git-branch-rules.md#resolver
+
+import { statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import type { BranchTarget } from '../ports.ts'
+import type { Invocation } from '../shell/invocation.ts'
+import { withoutRedirections } from '../shell/git-internals.ts'
+import { splitShell } from '../shell/split.ts'
+import { findMatchingBacktick, findMatchingParen } from '../shell/substitution.ts'
+import { type Token, basename, tokenValue, tokenize } from '../shell/token.ts'
+
+// Subcommands that add history to the current branch (pull, rebase, reset, amend are excluded: see docs/architecture/agent-git-branch-rules.md)
+export const LANDING_SUBCOMMANDS: ReadonlySet<string> = new Set(['commit', 'merge', 'cherry-pick', 'revert', 'am'])
+
+const ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/
+const SHELLS: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh'])
+/** Commands that re-run another command: a shell `-c` script behind one is followed. */
+const RE_EXECUTORS: ReadonlySet<string> = new Set(['xargs', 'parallel', 'env', 'nice', 'nohup', 'timeout', 'sudo', 'doas'])
+
+// Bash builtins and reserved words: `compgen -b` + `compgen -k` on bash 5.3 (docs/architecture/agent-git-branch-rules.md#closed-builtin-sets-and-their-provenance)
+const BASH_BUILTINS_AND_KEYWORDS: readonly string[] = (
+  '. : [ alias bg bind break builtin caller cd command compgen complete compopt continue declare dirs disown echo enable eval exec exit export false fc fg getopts hash help history jobs kill let local logout mapfile popd printf pushd pwd read readarray readonly return set shift shopt source suspend test times trap true type typeset ulimit umask unalias unset wait if then else elif fi case esac for select while until do done in function time { } ! [[ ]] coproc').split(' ')
+// zsh builtins and reserved words: `zsh -c 'print ${(k)builtins} ${(k)reswords}'` on zsh 5.9 (same doc section)
+const ZSH_BUILTINS_AND_RESERVED_WORDS: readonly string[] = (
+  'unset rehash popd ulimit local jobs disable [ compfiles printf autoload noglob pushln zle readonly exit false times sched setopt getln builtin let bg which unhash pwd zparseopts logout disown type source eval comptags compdescribe compctl r zmodload zregexparse history return exec compadd emulate chdir ttyctl test comparguments pushd functions float zstyle print declare comptry alias shift - . bindkey typeset true hash compset cd compvalues getopts compgroups export enable limit echotc echo wait dirs unsetopt read : integer bye echoti compquote unfunction fc vared unalias kill compcall where fg zformat suspend unlimit break set continue command zcompile whence umask trap log private if else end do then { select coproc } ! case [[ repeat done for while time esac until fi nocorrect foreach elif function'
+).split(' ')
+/** The closed set of shell builtins and reserved words (bash 5.3 + zsh 5.9): a head outside it is an external command or a function. */
+const SHELL_BUILTINS_AND_KEYWORDS: ReadonlySet<string> = new Set([...BASH_BUILTINS_AND_KEYWORDS, ...ZSH_BUILTINS_AND_RESERVED_WORDS])
+/** Builtins that only print or test: neutral (`printf -v` / `print -v` assign a variable and are not). */
+const READ_ONLY_BUILTINS: ReadonlySet<string> = new Set(['echo', 'printf', 'print', 'which', 'whence', 'where', 'true', 'false', 'test', '[', '[[', 'pwd', 'type', 'hash', 'help', ':', 'times', 'dirs', 'jobs'])
+/** Variables whose assignment (or export, or unset) changes what a later cd, `~` or shell startup does: unknown. */
+const SENSITIVE_VARIABLES: ReadonlySet<string> = new Set(['BASH_ENV', 'ENV', 'HOME', 'CDPATH', 'ZDOTDIR', 'PATH'])
+/** Variables that, as a prefix on a launched shell, change what that shell runs or means. */
+const SHELL_STARTUP_VARIABLES: ReadonlySet<string> = new Set(['BASH_ENV', 'ENV', 'ZDOTDIR', 'HOME', 'CDPATH'])
+/** git subcommands that move HEAD (or the worktree it is read from): after one, the branch a later landing command hits is unknown. */
+const HEAD_MOVERS: ReadonlySet<string> = new Set(['switch', 'checkout', 'worktree', 'stash', 'bisect', 'rebase', 'reset'])
+const GIT_VALUE_GLOBALS: ReadonlySet<string> = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env'])
+
+/** Does this piece run `git <HEAD_MOVER> ...` (behind any wrapper)? */
+function movesHead(rest: readonly Token[]): boolean {
+  const gitAt = rest.findIndex((token) => ['git', 'git.exe'].includes(basename(token)))
+  if (gitAt < 0) return false
+  for (let i = gitAt + 1; i < rest.length; i++) {
+    const value = tokenValue(rest[i] as Token)
+    if (value.startsWith('-')) {
+      if (GIT_VALUE_GLOBALS.has(value)) i++
+      continue
+    }
+    const subcommand = value.toLowerCase()
+    if (!HEAD_MOVERS.has(subcommand)) return false
+    // Read-only forms of stash/worktree do not move HEAD: `stash list|show`, `worktree list`.
+    const action = rest.slice(i + 1).map((token) => tokenValue(token)).find((arg) => !arg.startsWith('-'))
+    if (subcommand === 'stash' && (action === 'list' || action === 'show')) return false
+    if (subcommand === 'worktree' && action === 'list') return false
+    return true
+  }
+  return false
+}
+
+function namesDirectory(word: string): boolean {
+  try {
+    return statSync(word).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+interface Mutable {
+  dirs: string[]
+  gitDir?: string
+  workTree?: string
+  /** `HOME=` was assigned for this command: `~` no longer means the home directory we know. */
+  homeUnknown?: boolean
+}
+
+/** `~`, `~/x`, `$HOME`, `${HOME}` expand to the home directory; any other `$` or backtick is not static (`null`). */
+function expandPath(value: string, target: Mutable): string | null {
+  const home = homedir()
+  const tilde = value === '~' || value.startsWith('~/')
+  if (tilde) return target.homeUnknown === true ? null : home + value.slice(1)
+  for (const prefix of ['${HOME}', '$HOME']) {
+    if (value === prefix || value.startsWith(`${prefix}/`)) return target.homeUnknown === true ? null : home + value.slice(prefix.length)
+  }
+  return /[$`]/.test(value) || value === '' ? null : value
+}
+
+/** Apply `NAME=value` env assignments we care about; false when one is not static. */
+function applyEnv(target: Mutable, assignments: readonly string[]): boolean {
+  for (const assignment of assignments) {
+    const match = ASSIGNMENT_RE.exec(assignment)
+    if (!match) continue
+    const name = match[1] as string
+    if (name !== 'GIT_DIR' && name !== 'GIT_WORK_TREE') continue
+    const value = expandPath(match[2] as string, target)
+    if (value === null) return false
+    if (name === 'GIT_DIR') target.gitDir = value
+    else target.workTree = value
+  }
+  return true
+}
+
+function leadingAssignments(tokens: readonly Token[]): { assignments: string[]; rest: Token[] } {
+  let index = 0
+  const assignments: string[] = []
+  while (index < tokens.length && ASSIGNMENT_RE.test(tokenValue(tokens[index] as Token))) assignments.push(tokenValue(tokens[index++] as Token))
+  return { assignments, rest: tokens.slice(index) as Token[] }
+}
+
+/** `--git-dir`, `--work-tree`, `-C` among git's globals; false when one is not static. */
+function applyGlobals(target: Mutable, globals: readonly Token[]): boolean {
+  const values = globals.map((token) => tokenValue(token))
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index] as string
+    const take = (long: string): string | null => {
+      if (value === long) return values[++index] ?? ''
+      if (value.startsWith(`${long}=`)) return value.slice(long.length + 1)
+      return null
+    }
+    const gitDir = take('--git-dir')
+    if (gitDir !== null) {
+      const expanded = expandPath(gitDir, target)
+      if (expanded === null) return false
+      target.gitDir = expanded
+      continue
+    }
+    const workTree = take('--work-tree')
+    if (workTree !== null) {
+      const expanded = expandPath(workTree, target)
+      if (expanded === null) return false
+      target.workTree = expanded
+      continue
+    }
+    if (value === '-C' || (value.startsWith('-C') && value.length > 2)) {
+      const dir = expandPath(value === '-C' ? (values[++index] ?? '') : value.slice(2), target)
+      if (dir === null) return false
+      target.dirs.push(dir)
+    }
+  }
+  return true
+}
+
+/** Does this piece run our git invocation (possibly behind `env`/`command`/`builtin`/another wrapper)? */
+function runsInvocation(piece: readonly Token[], inv: Invocation & { kind: 'git' }): boolean {
+  const tokens = withoutRedirections(piece) // the classifier's `rest` has none either (`git commit -F - <<EOF`)
+  const values = tokens.map((token) => tokenValue(token))
+  const wanted = inv.rest.map((token) => tokenValue(token))
+  const tail = wanted.length === 0 ? values : values.slice(-wanted.length)
+  const gitAt = tokens.findIndex((token) => ['git', 'git.exe'].includes(basename(token)))
+  return gitAt >= 0 && values.indexOf(inv.subcommand, gitAt) > gitAt && tail.length === wanted.length && tail.every((value, index) => value === wanted[index])
+}
+
+/** Assignments reaching git from the piece: leading `NAME=v`, and `env NAME=v ...`. `null` when `env` carries options we do not model. */
+function pieceAssignments(tokens: readonly Token[]): string[] | null {
+  const { assignments, rest } = leadingAssignments(tokens)
+  let index = 0
+  while (index < rest.length && !['git', 'git.exe'].includes(basename(rest[index] as Token))) {
+    const name = basename(rest[index] as Token)
+    if (name === 'env') {
+      index++
+      while (index < rest.length && ASSIGNMENT_RE.test(tokenValue(rest[index] as Token))) assignments.push(tokenValue(rest[index++] as Token))
+      if (index < rest.length && tokenValue(rest[index] as Token).startsWith('-') && !['git', 'git.exe'].includes(basename(rest[index] as Token))) return null
+    } else if (name === 'command' || name === 'builtin') {
+      index++
+      while (index < rest.length && ['-p', '--'].includes(tokenValue(rest[index] as Token))) index++
+    } else {
+      index++ // another wrapper (nohup, time, ...): no environment of ours
+    }
+  }
+  return assignments
+}
+
+interface Parsed {
+  readonly tokens: readonly (readonly Token[] | null)[]
+  /** Text between consecutive pieces (operators, group characters, comments); `null` when the pieces could not be located in the source. */
+  readonly gaps: readonly string[] | null
+  /** Names of functions defined anywhere in the command (`f() {`, `function f`): a piece headed by one is unknown. */
+  readonly functions: ReadonlySet<string>
+}
+
+/** Heredoc delimiters opened by `<<` / `<<-` at the top level of one piece, or `'unparsable'`. Quotes, `\x` and `$(...)` are skipped. */
+function heredocDelimiters(piece: string): string[] | 'unparsable' {
+  const delimiters: string[] = []
+  for (let i = 0; i < piece.length; i++) {
+    const char = piece[i] as string
+    if (char === '\\') i++
+    else if (char === "'") {
+      const close = piece.indexOf("'", i + 1)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '"') {
+      let j = i + 1
+      while (j < piece.length && piece[j] !== '"') j += piece[j] === '\\' ? 2 : 1
+      if (j >= piece.length) return 'unparsable'
+      i = j
+    } else if (char === '`') {
+      const close = findMatchingBacktick(piece, i)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '$' && piece[i + 1] === '(') {
+      const close = findMatchingParen(piece, i + 1)
+      if (close < 0) return 'unparsable'
+      i = close
+    } else if (char === '<' && piece[i + 1] === '<' && piece[i + 2] !== '<' && piece[i - 1] !== '<') {
+      i += 2
+      if (piece[i] === '-') i++
+      while (piece[i] === ' ' || piece[i] === '\t') i++
+      let word = ''
+      let sawWord = false
+      for (; i < piece.length && !/[\s;|&<>()]/.test(piece[i] as string); i++) {
+        sawWord = true
+        const c = piece[i] as string
+        if (c === '\\') word += piece[++i] ?? ''
+        else if (c === "'" || c === '"') {
+          const close = piece.indexOf(c, i + 1)
+          if (close < 0) return 'unparsable'
+          word += piece.slice(i + 1, close)
+          i = close
+        } else word += c
+      }
+      if (!sawWord) return 'unparsable'
+      delimiters.push(word)
+      i--
+    }
+  }
+  return delimiters
+}
+
+/** `null`: unparseable (parse.uncertain refuses it). `'closed'`: a heredoc we cannot account for -- fail closed. */
+function parse(command: string): Parsed | null | 'closed' {
+  const split = splitShell(command)
+  if (split.invalid) return null
+  const tokens: (readonly Token[] | null)[] = split.pieces.map((piece) => {
+    const tokenized = tokenize(piece)
+    return tokenized.invalid ? null : tokenized.tokens
+  })
+  const functions = new Set<string>()
+  for (const match of command.matchAll(/([A-Za-z_][\w.:-]*)\s*\(\s*\)/g)) functions.add(match[1] as string)
+  for (const match of command.matchAll(/\bfunction\s+([A-Za-z_][\w.:-]*)/g)) functions.add(match[1] as string)
+  const gaps: string[] = []
+  let cursor = 0
+  for (const piece of split.pieces) {
+    const at = command.indexOf(piece, cursor)
+    if (at < 0) return { tokens, gaps: null, functions }
+    gaps.push(command.slice(cursor, at))
+    cursor = at + piece.length
+  }
+  // Heredoc body lines are not commands: drop them (docs/architecture/agent-git-branch-rules.md#resolver)
+  for (let i = 0; i < split.pieces.length; i++) {
+    const delimiters = heredocDelimiters(split.pieces[i] as string)
+    if (delimiters === 'unparsable') return 'closed'
+    if (delimiters.length === 0) continue
+    let body = i + 1
+    while (body < split.pieces.length && !(gaps[body] as string).includes('\n')) body++ // rest of the marker's own line
+    for (const delimiter of delimiters) {
+      let closed = false
+      for (; body < split.pieces.length && !closed; body++) {
+        closed = (split.pieces[body] as string).trim() === delimiter
+        tokens[body] = null
+        gaps[body] = '\n'
+      }
+      if (!closed) return 'closed'
+    }
+    i = body - 1
+  }
+  return { tokens, gaps, functions }
+}
+
+/** The gap as an operator when it is exactly `&&`, `;` or a newline; `null` for anything else (`||`, `|`, `&`, `(`, `{`, ...). */
+function plainGap(gap: string): '&&' | ';' | null {
+  const normalized = gap.replace(/#[^\n]*/g, '').replace(/\s*\n\s*/g, ';').replace(/\s+/g, '').replace(/;+/g, ';')
+  return normalized === '&&' ? '&&' : normalized === ';' || normalized === '' ? ';' : null
+}
+
+type StatePiece =
+  | { kind: 'cd'; dir: string }
+  | { kind: 'export'; assignments: string[] }
+  | { kind: 'unset'; names: string[] }
+  | { kind: 'bad' }
+  | { kind: 'neutral' }
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const SET_CLUSTER_RE = /^[-+][eux]*$/
+const SET_O_VALUES: readonly string[] = ['pipefail', 'errexit', 'nounset']
+
+/** `set` with only -e/-u/-x/+e/+u/+x (clusters allowed, `-euo pipefail`) and `-o|+o pipefail|errexit|nounset`. */
+function harmlessSet(args: readonly string[]): boolean {
+  if (args.length === 0) return false
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string
+    const cluster = /^([-+][eux]*)o$/.exec(arg)
+    if (cluster !== null || arg === '-o' || arg === '+o') {
+      if (!SET_O_VALUES.includes(args[++i] ?? '')) return false
+    } else if (!SET_CLUSTER_RE.test(arg) || arg.length < 2) {
+      return false
+    }
+  }
+  return true
+}
+
+function classify(piece: readonly Token[] | null, functions: ReadonlySet<string>): StatePiece {
+  if (piece === null) return { kind: 'neutral' }
+  const { assignments, rest } = leadingAssignments(withoutRedirections(piece))
+  const names = assignments.map((assignment) => assignment.split('=')[0] as string)
+  if (names.some((name) => name.startsWith('GIT_'))) return rest.length === 0 ? { kind: 'bad' } : classifyHead(rest, assignments, functions)
+  if (rest.length === 0) return names.some((name) => SENSITIVE_VARIABLES.has(name)) ? { kind: 'bad' } : { kind: 'neutral' }
+  return classifyHead(rest, assignments, functions)
+}
+
+function classifyHead(rest: readonly Token[], assignments: readonly string[], functions: ReadonlySet<string>): StatePiece {
+  const head = tokenValue(rest[0] as Token)
+  const args = rest.slice(1).map((token) => tokenValue(token))
+  if (/[$`]/.test(head) || functions.has(head)) return { kind: 'bad' }
+  if (!SHELL_BUILTINS_AND_KEYWORDS.has(head)) {
+    if (movesHead(rest)) return { kind: 'bad' }
+    // zsh autocd: a path (or a bare word naming a directory) used as a command changes directory.
+    if (head.includes('/') && !['git', 'git.exe'].includes(basename(rest[0] as Token))) return { kind: 'bad' }
+    if (head.startsWith('~') || head === '..' || (!head.includes('/') && namesDirectory(head))) return { kind: 'bad' }
+    // An external command cannot change this shell, but a shell it launches runs its startup files first.
+    const startup = assignments.some((assignment) => SHELL_STARTUP_VARIABLES.has(assignment.split('=')[0] as string))
+    return startup && (SHELLS.has(basename(rest[0] as Token)) || RE_EXECUTORS.has(basename(rest[0] as Token))) ? { kind: 'bad' } : { kind: 'neutral' }
+  }
+  if (READ_ONLY_BUILTINS.has(head)) return (head === 'printf' || head === 'print') && args.includes('-v') ? { kind: 'bad' } : { kind: 'neutral' }
+  if (head === 'command' && (args[0] === '-v' || args[0] === '-V')) return { kind: 'neutral' }
+  if (head === 'set') return harmlessSet(args) ? { kind: 'neutral' } : { kind: 'bad' }
+  if (head === 'cd' || head === 'pushd') return args.length !== 1 || args[0] === '' || (args[0] as string).startsWith('-') ? { kind: 'bad' } : { kind: 'cd', dir: args[0] as string }
+  if (head === 'export') {
+    if (args.length > 0 && args.every((arg) => /^GIT_(DIR|WORK_TREE)=/.test(arg))) return { kind: 'export', assignments: args }
+    return args.every((arg) => NAME_RE.test(arg.split('=')[0] as string) && !arg.startsWith('GIT_') && !SENSITIVE_VARIABLES.has(arg.split('=')[0] as string)) ? { kind: 'neutral' } : { kind: 'bad' }
+  }
+  if (head === 'unset') return args.every((arg) => NAME_RE.test(arg) && !SENSITIVE_VARIABLES.has(arg)) ? { kind: 'unset', names: args } : { kind: 'bad' }
+  return { kind: 'bad' }
+}
+
+// Credit or reject the pieces before `until`; fail closed on anything unknown. // See docs/architecture/agent-git-branch-rules.md#resolver
+function applyState(parsed: Parsed, until: number, target: Mutable): boolean {
+  for (let i = 0; i < until; i++) {
+    const state = classify(parsed.tokens[i] ?? null, parsed.functions)
+    if (state.kind === 'neutral') continue
+    if (state.kind === 'bad') return false
+    if (state.kind === 'unset') {
+      if (state.names.includes('GIT_DIR')) delete target.gitDir
+      if (state.names.includes('GIT_WORK_TREE')) delete target.workTree
+      continue
+    }
+    if (parsed.gaps === null) return false
+    const before = plainGap(parsed.gaps[i] as string)
+    if (before === null) return false
+    if (before === '&&' && (i === 0 || !['cd', 'export'].includes(classify(parsed.tokens[i - 1] ?? null, parsed.functions).kind))) return false
+    for (let j = i + 1; j <= Math.min(until, parsed.gaps.length - 1); j++) if (plainGap(parsed.gaps[j] as string) === null) return false
+    if (state.kind === 'cd') {
+      const dir = expandPath(state.dir, target)
+      if (dir === null) return false
+      target.dirs.push(dir)
+    } else if (!applyEnv(target, state.assignments)) {
+      return false
+    }
+  }
+  return true
+}
+
+// The `-c` script of a (re-executor-wrapped) shell piece, or 'unsafe' when a startup-file variable is set. // See docs/architecture/agent-git-branch-rules.md#resolver
+function shellScript(tokens: readonly Token[]): string | null | 'unsafe' {
+  const { rest } = leadingAssignments(tokens)
+  if (rest[0] === undefined) return null
+  let shellAt = 0
+  if (!SHELLS.has(basename(rest[0]))) {
+    if (!RE_EXECUTORS.has(basename(rest[0]))) return null
+    shellAt = rest.findIndex((token, index) => index > 0 && SHELLS.has(basename(token)))
+    if (shellAt < 0) return null
+  }
+  for (let index = shellAt + 1; index < rest.length - 1; index++) {
+    if (/^-[a-zA-Z]*c$/.test(tokenValue(rest[index] as Token))) {
+      const assignments = pieceAssignments(tokens)
+      return assignments === null || assignments.some((assignment) => SHELL_STARTUP_VARIABLES.has(assignment.split('=')[0] as string)) ? 'unsafe' : tokenValue(rest[index + 1] as Token)
+    }
+  }
+  return null
+}
+
+/** `undefined`: the invocation is not in `command`. `null`: it is, but its target is not static. */
+function walk(command: string, inv: Invocation & { kind: 'git' }, inherited: Mutable): BranchTarget | null | undefined {
+  const parsed = parse(command)
+  if (parsed === null) return undefined // unparseable: parse.uncertain's job to refuse
+  if (parsed === 'closed') return null
+  for (let i = 0; i < parsed.tokens.length; i++) {
+    const tokens = parsed.tokens[i]
+    if (tokens === null || tokens === undefined) continue
+    const target: Mutable = { ...inherited, dirs: [...inherited.dirs] }
+    if (runsInvocation(tokens, inv)) {
+      const assignments = pieceAssignments(tokens)
+      if (assignments === null || !applyState(parsed, i, target)) return null
+      if (assignments.some((assignment) => assignment.startsWith('HOME='))) target.homeUnknown = true
+      if (!applyEnv(target, assignments) || !applyGlobals(target, inv.globals)) return null
+      return target
+    }
+    const script = shellScript(tokens)
+    if (script === null) continue
+    if (script === 'unsafe') {
+      // The startup file may do anything, but only matters when our git is in there.
+      const unsafeInner = tokens.some((token) => tokenValue(token).includes(inv.subcommand))
+      if (unsafeInner) return null
+      continue
+    }
+    const probe: Mutable = { ...inherited, dirs: [...inherited.dirs] }
+    const inner = walk(script, inv, probe)
+    if (inner === undefined) continue
+    if (inner === null || !applyState(parsed, i, target)) return null
+    const nested = walk(script, inv, target)
+    return nested ?? null
+  }
+  return undefined
+}
+
+/** The statically resolved target of `inv` inside `command`, or `null` when it cannot be resolved. */
+export function resolveGitTarget(inv: Invocation & { kind: 'git' }, command: string | undefined): BranchTarget | null {
+  const found = command === undefined ? undefined : walk(command, inv, { dirs: [] })
+  if (found !== undefined) return found
+  // Not found as a piece (xargs, find -exec, ...): its own globals, after any unconditional cd/export before it.
+  const target: Mutable = { dirs: [] }
+  const parsed = command === undefined ? null : parse(command)
+  if (parsed === 'closed' || (parsed !== null && !applyState(parsed, parsed.tokens.length, target))) return null
+  return applyGlobals(target, inv.globals) ? target : null
+}

package/packages/agent-hooks/src/rules/impl/tool-native-search.ts

@@ -56,13 +56,13 @@ export const toolNativeSearch: RuleSpec = {
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the native Grep/Glob/Search tools; steer at search <semantic query | keywords> (docs/plans), crg (code graph), rg, ast-grep.',
+  summary: 'Deny the native Grep/Glob/Search tools; steer at search <semantic query | keywords> (markdown), crg (code graph), rg, ast-grep.',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'tool-call') return null
     if (!new Set(loadSurfacePolicy().deny.nativeTools).has(inv.tool)) return null
     // Surface the tool input's path-ish field for the message so it can
-    // recommend `search` (the right tool for docs/plans/.scratchpad) over
+    // recommend `search` (the right tool for markdown) over
     // `crg` (the right tool for code-graph queries). Different hosts name
     // this field differently — Claude uses `path`, Codex uses `path`,
     // Cursor uses `target_file` / `target_directory` for Write. The
@@ -77,10 +77,11 @@ export const toolNativeSearch: RuleSpec = {
   },
   message(finding: Finding, ctx: MessageContext) {
     const tool = typeof finding.detail.tool === 'string' ? finding.detail.tool : 'this tool'
-    // Path-aware recommendation. Native Grep on docs/plans/.scratchpad ->
-    // lead with `search`; everywhere else -> lead with `crg`.
+    // Path-aware recommendation. Native Grep on a markdown file (any
+    // docs/plans/.scratchpad tree or *.md path) -> lead with `search`;
+    // code -> lead with `crg`.
     const path = typeof finding.detail.path === 'string' ? finding.detail.path : ''
-    const isDoc = DOC_TREES.some((prefix) => path.startsWith(prefix))
+    const isDoc = DOC_TREES.some((prefix) => path.startsWith(prefix)) || path.endsWith('.md')
 
     const leadTool = isDoc ? 'search' : 'crg'
     const leadExamples = ALLOWED_SEARCH_TOOLS.find((row) => row.binary === leadTool)?.examples ?? []
@@ -93,8 +94,8 @@ export const toolNativeSearch: RuleSpec = {
 
     return {
       user: isDoc
-        ? `Blocked the native ${tool} tool on \`${path}\` (a docs/plans/.scratchpad tree). The right answer is \`search <semantic query | keywords>\` — semantic + keyword, finds the doc that *talks* about X. \`rg\`/\`crg\` are the wrong tools here.`
-        : `Blocked the native ${tool} tool. Lead with \`crg search "<text>"\` for code-graph queries, fall back to \`rg\`/\`ast-grep\` for literal text, \`search <semantic query | keywords>\` only when the path is docs/plans/.scratchpad.`,
+        ? `Blocked the native ${tool} tool on \`${path}\` (markdown). The right answer is \`search <semantic query | keywords>\` — semantic + keyword, finds the doc that *talks* about X, in any markdown file. \`rg\`/\`crg\` are the wrong tools here.`
+        : `Blocked the native ${tool} tool. Lead with \`crg search "<text>"\` for code-graph queries, fall back to \`rg\`/\`ast-grep\` for literal text, \`search <semantic query | keywords>\` for any markdown file.`,
       agent:
         `DENIED the native ${tool} tool. It is routed through the lean-ctx hook but NOT converted — ` +
         'the call still runs natively — so it is a way around the shell search ban rather than an ' +

package/packages/agent-hooks/src/rules/ports.ts

@@ -45,6 +45,14 @@ export interface AgentPort {
  * `git.protected-tree-commit` can fail closed on "could not read the index"
  * instead of silently treating an unreadable index as a clean one.
  */
+/** Where a git invocation points, statically resolved from its command line (see `impl/git-target.ts`). */
+export interface BranchTarget {
+  /** `cd <dir>` and `git -C <dir>` values, in the order git applies them. */
+  readonly dirs: readonly string[]
+  readonly gitDir?: string
+  readonly workTree?: string
+}
+
 export interface RepoIndexPort {
   stagedPaths(): readonly string[] | null
   trackedModifiedPaths(): readonly string[] | null
@@ -64,6 +72,14 @@ export interface RepoIndexPort {
    * absent) the same as `null` (present, resolved to nothing).
    */
   configuredAlias?(verb: string): string | null
+  /**
+   * The checked-out branch of the repo a git invocation targets: the hook's
+   * root with `target.dirs` applied as `-C <dir>` values in order (relative
+   * ones composed), then `--git-dir` / `--work-tree` when given. `''` for a detached HEAD, `null` when it cannot be read (not a
+   * repository, git missing, timeout) so `git.commit-protected-branch` can
+   * fail closed instead of treating an unreadable HEAD as a safe one.
+   */
+  currentBranch(target: BranchTarget): string | null
 }
 
 export const liveEnv: EnvPort = {
@@ -159,6 +175,26 @@ export function liveRepoIndex(root: string): RepoIndexPort {
       }
     },
     resolveRemoteUrl: rewriteUrl,
+    currentBranch: (target) => {
+      try {
+        const out = execFileSync('git', [
+          '-C',
+          root,
+          ...target.dirs.flatMap((dir) => ['-C', dir]),
+          ...(target.gitDir === undefined ? [] : ['--git-dir', target.gitDir]),
+          ...(target.workTree === undefined ? [] : ['--work-tree', target.workTree]),
+          'branch',
+          '--show-current',
+        ], {
+          encoding: 'utf8',
+          timeout: 10_000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        return out.replace(/\n+$/, '')
+      } catch {
+        return null
+      }
+    },
     configuredAlias: (verb) => {
       try {
         const out = execFileSync('git', ['-C', root, 'config', '--get', `alias.${verb}`], {

package/packages/agent-hooks/src/rules/registry.ts

@@ -29,11 +29,11 @@ import { gitStash, gitClean, gitRebase, gitFilterBranch, gitRestore, gitReset, g
 import { gitNoVerify, gitAmend } from './impl/git-verify.ts'
 import { gitProtectedTreeCommit } from './impl/git-protected-tree.ts'
 import {
-  gitBranchForceDelete,
   gitTagDelete,
   gitSwitchForce,
   gitGcPrune,
 } from './impl/git-history.ts'
+import { gitBranchMutation, gitCommitProtectedBranch } from './impl/git-branch.ts'
 import {
   gitUpdateRef,
   gitSymbolicRefWrite,
@@ -95,7 +95,8 @@ export const GIT_RULES: readonly AnyRuleSpec[] = [
   gitNoVerify,
   gitAmend,
   gitProtectedTreeCommit,
-  gitBranchForceDelete,
+  gitBranchMutation,
+  gitCommitProtectedBranch,
   gitTagDelete,
   gitSwitchForce,
   gitWorktree,

package/packages/agent-hooks/src/rules/shell/protected-carriers.ts

@@ -142,7 +142,7 @@ const PROTECTED_CARRIER_DIRS: ReadonlySet<string> = new Set([
  *
  * `path` ending in a literal
  * `/` (BEFORE normalization strips it for the comparison itself) means "a
- * file goes INTO this directory" (`cp GLOBAL-AGENTS.md .claude/`, `mv
+ * file goes INTO this directory" (`cp TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md .claude/`, `mv
  * notes.md .cursor/`) — the directory itself is untouched, only gaining an
  * unrelated file — never "this directory is the thing being moved/
  * overwritten" (`mv .claude .claude-old`, `mv attacker-stuff .codex` — no

package/packages/agent-settings/README.md

@@ -90,7 +90,7 @@ the built-in target allowlist.
 Ownership rule: machine-global agent configuration belongs to enact-vps;
 everything else belongs in the owning repository. The sweep therefore treats
 anything not declared by enact-vps (`protected.json`, the Kimi managed block,
-GLOBAL-AGENTS deployment targets) as foreign:
+global-agents deployment targets) as foreign:
 
 - JSON entries: Claude `settings.json` `hooks`, `mcpServers`, `enabledPlugins`,
   `extraKnownMarketplaces`, `permissions.allow|deny|ask` items; `.claude.json`
@@ -239,13 +239,13 @@ purpose even though it is a real, documented key, so the whole container
 stays a sweep candidate whenever non-empty — see the `reason` field on that
 baseline entry for the specific rationale.
 
-## Global agent instructions (`GLOBAL-AGENTS.md`)
+## Global agent instructions (`TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md`)
 
-[`GLOBAL-AGENTS.md`](./assets/GLOBAL-AGENTS.md) is the single source of truth for
+[`TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md`](./assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md) is the single source of truth for
 every host's global instruction file: `~/.claude/CLAUDE.md`,
 `~/.codex/AGENTS.md`, `~/.cursor/AGENTS.md`, `~/.kimi-code/AGENTS.md`, and
 `~/.config/opencode/AGENTS.md`. Any change to those files must be made in
-`GLOBAL-AGENTS.md`; a direct edit to a target is drift and is overwritten on
+`TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md`; a direct edit to a target is drift and is overwritten on
 the next deploy.
 
 ```bash
@@ -254,6 +254,12 @@ bin/global-agents --home "$HOME" --mode deploy     # forced
 bin/global-agents --home "$HOME" --mode uninstall
 ```
 
+Deploy and status run only on Tarun's fleet (Tarun, 2026-10-10): the device
+name is the first label of the hostname (or `--host NAME`), and it must be a
+`mac.devices` or `linux.devices` key in `packages/fleet/manifest.json`.
+Any other machine writes no global file and prints one `skipped:` line saying
+why; existing files there are left alone, and uninstall is not gated.
+
 Deploy is always forced; there is no `--force` flag and no leave-in-place
 mode. A missing target is created, a target already equal to the source is
 left untouched, and a drifted target (hand-edited, or stale from an older

package/packages/agent-settings/assets/GLOBAL-AGENTS.md

@@ -6,6 +6,11 @@ repo's own `AGENTS.md`.
 ## Communication
 - Address me as **Tarun**.
 - Short, scannable **bullet points** — not long prose. Lead with the answer; keep reasoning tight.
+- **Every reply has three parts, in this order:**
+  - a **TL;DR** of a few lines; information stays brief, and detail is given only when asked;
+  - an explicit **Recommendation**: what you would do and why, in one line;
+  - **one ask**: the single question or decision you need next.
+- **Keep a numbered list of open points** and show it when it changes. I answer them one at a time, so never bundle several questions into one reply.
 - If a task is ambiguous, ask exactly one clarifying question.
 
 ## Truthfulness (non-negotiable)