pi-orchestrator-config 4.22.1 → 4.22.3

package/README.md

@@ -477,23 +477,6 @@ entries) is what pi carries between sessions. Trail's own layer —
 `.trail/learnings/`, `trail note`, the pre-ship `trail check` — is upstream's and
 **we do not use it**. We only read the code map.
 
-### Migrating from Graft
-
-The integration was renamed from Graft to Trail-code. The break is intentional:
-
-- Only `@trailhq/trail-code` is installed and only `trail` is invoked. The `graft`
-  binary is no longer installed and there is no fallback — if you only have
-  `@nanonets/graft`, install trail to get the map tools back.
-- `graft_enable` / `PI_GRAFT_ENABLE` are gone, with no alias and no migration. An
-  existing `graft_enable: true` is a dead key, which is harmless: the feature is
-  default-on when the binary exists.
-- Tools are `trail_find_code`, `trail_find_all`, `trail_file_api`,
-  `trail_trace_calls`, `trail_repo_map`, `trail_refresh`, `trail_blast_radius`.
-- `log_graft` becomes `log_trail` (env `PI_LOG_TRAIL`); the old `~/.pi/logs/graft`
-  directory is neither read nor migrated.
-- `graft/` survives as a _path_ until upstream renames it: it is the map
-  directory, not the product.
-
 ### Cache Miss Notices
 
 Enable `showCacheMissNotices` in pi settings to see transcript notices on significant prompt-cache misses — useful for investigating unexpected token costs:

package/extensions/orchestrator/enforcement-helpers.ts

@@ -6,13 +6,14 @@
 import { createLogger } from "../shared/logger.js";
 import { createHash } from "node:crypto";
 import { lstatSync, realpathSync, mkdirSync, rmdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import { join } from "node:path";
 import { getProjectDataDir } from "./utils.js";
 import { getGlobalSettingsPath, getSettingsPath, loadGlobalSettings, loadProjectSettings } from "./project-settings.js";
 import { readSettingsFile, writeSettingsFile } from "./settings-tui-helpers.js";
-import { DANGEROUS, executableText, getCurrentBranch, isConflictResolutionCommand, segmentRunsGit, tokenize } from "./git-helpers.js";
+import { DANGEROUS, WRAPPER_VALUE_OPTIONS, executableText, getCurrentBranch, isConflictResolutionCommand, segmentRunsGit, tokenize } from "./git-helpers.js";
 
 const enfLog = createLogger("enforcement");
 enfLog.debug("enforcement-helpers module loaded");
@@ -313,7 +314,7 @@ function gitCsIn(segment: string): string[] {
 }
 
 /** Words that run whatever follows them, so an assignment behind one still counts. */
-const WRAPPER_WORDS = new Set(["sudo", "command", "exec", "time", "nohup", "nice", "stdbuf", "setsid", "timeout"]);
+const WRAPPER_WORDS = new Set(["sudo", "command", "exec", "time", "nohup", "nice", "stdbuf", "setsid", "timeout", "rtk"]);
 
 /** env options whose value is a separate word. */
 const ENV_VALUE_OPTIONS = new Set([
@@ -324,6 +325,26 @@ const ENV_VALUE_OPTIONS = new Set([
 const GIT_INDEX_VARS = new Set(["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"]);
 const GIT_INDEX_OPTIONS = new Set(["--git-dir", "--work-tree", "--namespace"]);
 
+/** Command words that hand a quoted string to a shell, which then really runs it. */
+const SHELL_WORDS = new Set(["bash", "sh", "zsh", "dash", "ksh", "eval"]);
+
+/** True when this segment RUNS a shell (behind any wrapper/assignment/env prefix).
+ *  A quoted argument containing shell-looking text is not a shell run: only the
+ *  command word counts. */
+function runsNestedShell(tokens: string[]): boolean {
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (WRAPPER_WORDS.has(tok) || tok === "env" || /^[A-Za-z_][A-Za-z0-9_]*=/.test(tok)) continue;
+    if (tok.startsWith("-")) {
+      // env's own options sit between `env` and the command it runs.
+      if (!tok.includes("=") && ENV_VALUE_OPTIONS.has(tok.split("=")[0])) i++;
+      continue;
+    }
+    return SHELL_WORDS.has(tok.replace(/^[()]+/, "").replace(/.*\//, ""));
+  }
+  return false;
+}
+
 /**
  * Anything that points git at a repository other than the working directory: the
  * GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE environment variables, or the equivalent
@@ -336,21 +357,47 @@ const GIT_INDEX_OPTIONS = new Set(["--git-dir", "--work-tree", "--namespace"]);
  * only count in git's global option region, before the subcommand, so
  * `git add -- --work-tree=x` is a filename too.
  */
-function gitIndexOverride(command: string): string | null {
+/** What a scan looks for: the environment variables, git global options, and
+ *  `-c` config keys that select the repository or identity git runs with. */
+interface GitOverrideTargets {
+  /** Variables that count in assignment position. */
+  env: Set<string>;
+  /** Long options in git's global region, before the subcommand. */
+  flags: Set<string>;
+  /** Keys of `-c <key>=<value>` / `--config-env=<key>=<VAR>`. */
+  configKeys: Set<string>;
+}
+
+const NO_KEYS: Set<string> = new Set();
+
+/**
+ * The one assignment/option walk behind both git override guards
+ * (gitIndexOverride and gitIdentityOverride). Returns a label for what it found,
+ * or null.
+ *
+ * Position matters. An environment variable only counts in *assignment
+ * position* — `GIT_DIR=/x git add a.txt`, optionally through `env` — so
+ * `git add GIT_INDEX_FILE=notes` stages a file with that name. Options only
+ * count in git's global region before the subcommand, so
+ * `git add -- --work-tree=x` is a filename too.
+ */
+function scanGitOverrides(command: string, targets: GitOverrideTargets): string | null {
   const assignment = /^[A-Za-z_][A-Za-z0-9_]*=/;
+  const nameOf = (tok: string) => tok.split("=")[0];
   for (const seg of unquotedSegments(command)) {
     const tokens = tokenize(seg.text);
-    const nameOf = (tok: string) => tok.split("=")[0];
     let i = 0;
     // `export GIT_INDEX_FILE=/x` sets it for later commands in the same shell,
     // so it points git at another index just as an inline assignment does. This
     // segment does not run git itself, so it is checked before that requirement.
-    if (tokens[i] === "export") {
+    // The executable view of a nested shell wraps a segment in `(`, so `(export`
+    // is the same word.
+    if (tokens[i]?.replace(/^\(+/, "") === "export") {
       i++;
       while (i < tokens.length) {
         const name = nameOf(tokens[i]);
-        if (GIT_INDEX_VARS.has(name)) {
-          enfLog.warn("git_index_override", "source", name, "via", "export");
+        if (targets.env.has(name)) {
+          enfLog.warn("git_override", "source", name, "via", "export");
           return name;
         }
         i++;
@@ -358,17 +405,30 @@ function gitIndexOverride(command: string): string | null {
       continue;
     }
     // `echo GIT_INDEX_FILE=/x` only prints the name. An override is something
-    // git is actually run with, so the segment has to run git for it to count.
-    if (!segmentRunsGit(seg.text)) continue;
+    // git is actually run with, so the segment has to run git for it to count —
+    // directly, or through a nested shell that this segment RUNS
+    // (`GIT_AUTHOR_EMAIL=x bash -c 'git commit'`), whose assignment lives here
+    // but whose git runs inside. A quoted argument merely MENTIONING a command
+    // (`gh pr create --body "…git -c user.email=x commit…"`) is prose: the
+    // segment runs `gh`, not a shell, so it is not followed.
+    if (!segmentRunsGit(seg.text) && !(runsNestedShell(tokens) && segmentRunsGit(executableText(seg.text)))) continue;
     // Leading `VAR=value` assignments, then the same again after `env`. A
     // wrapper that runs the rest — `sudo`, `command`, `exec`, `time` — sits in
     // front of both, and can be chained.
     for (let round = 0; round < 4; round++) {
-      while (i < tokens.length && WRAPPER_WORDS.has(tokens[i])) i++;
+      // A wrapper runs the rest, and its OWN options sit in between: in
+      // `rtk -v GIT_AUTHOR_EMAIL=x git commit` the assignment follows rtk's
+      // option, so stepping only over the wrapper word hid it (Qodo, PR #996).
+      while (i < tokens.length && WRAPPER_WORDS.has(tokens[i])) {
+        i++;
+        while (i < tokens.length && tokens[i].startsWith("-") && tokens[i] !== "-") {
+          i += WRAPPER_VALUE_OPTIONS.has(tokens[i]) ? 2 : 1;
+        }
+      }
       while (i < tokens.length && assignment.test(tokens[i])) {
         const name = nameOf(tokens[i]);
-        if (GIT_INDEX_VARS.has(name)) {
-          enfLog.warn("git_index_override", "source", name);
+        if (targets.env.has(name)) {
+          enfLog.warn("git_override", "source", name);
           return name;
         }
         i++;
@@ -384,14 +444,30 @@ function gitIndexOverride(command: string): string | null {
         i++;
       }
     }
-    const g = tokens.indexOf("git");
+    // A segment can start mid-subshell, so `(git` is the git word too.
+    const g = tokens.findIndex((t) => t.replace(/^[()]+|[()]+$/g, "") === "git");
     if (g === -1) continue;
     for (let k = g + 1; k < tokens.length; k++) {
       const tok = tokens[k];
       if (!tok.startsWith("-") || tok === "-") break;
+      // `-c <key>=<value>`, `-c<key>=<value>`, `--config-env=<key>=<VAR>` apply to
+      // this one command only — no config file is written, the effect is the same.
+      let setting: string | undefined;
+      if (tok === "-c") setting = tokens[++k];
+      else if (tok.startsWith("-c")) setting = tok.slice(2);
+      else if (tok.startsWith("--config-env=")) setting = tok.slice("--config-env=".length);
+      if (setting !== undefined) {
+        const key = (setting.split("=")[0] ?? "").toLowerCase();
+        if (targets.configKeys.has(key)) {
+          const label = tok.startsWith("--config-env") ? `--config-env ${key}` : `-c ${key}`;
+          enfLog.warn("git_override", "source", label);
+          return label;
+        }
+        continue;
+      }
       const name = nameOf(tok);
-      if (GIT_INDEX_OPTIONS.has(name)) {
-        enfLog.warn("git_index_override", "source", name);
+      if (targets.flags.has(name)) {
+        enfLog.warn("git_override", "source", name);
         return name;
       }
       if (!tok.includes("=") && tokens[k + 1] && !tokens[k + 1].startsWith("-")) k++;
@@ -400,6 +476,168 @@ function gitIndexOverride(command: string): string | null {
   return null;
 }
 
+function gitIndexOverride(command: string): string | null {
+  const found = scanGitOverrides(command, { env: GIT_INDEX_VARS, flags: GIT_INDEX_OPTIONS, configKeys: NO_KEYS });
+  if (found) enfLog.warn("git_index_override", "source", found);
+  return found;
+}
+
+/** Environment variables that set who a commit is recorded as. */
+const GIT_IDENTITY_VARS = new Set([
+  "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL",
+]);
+
+/** Git config keys that set who a commit is recorded as. */
+const GIT_IDENTITY_KEYS = new Set([
+  "user.name", "user.email", "author.name", "author.email", "committer.name", "committer.email",
+]);
+
+/** `git config` flags that only READ: `git config --get user.email` changes nothing. */
+const CONFIG_READ_FLAGS = new Set(["--get", "--get-all", "--get-regexp", "--list", "-l"]);
+
+/** `git config` flags that remove a key: no value follows, yet the identity moves. */
+const CONFIG_UNSET_FLAGS = new Set(["--unset", "--unset-all"]);
+
+/**
+ * True when a bash command WRITES into a path matching `targetSrc` (a regex
+ * source): a redirect (`>`, `>>`, `>|`) or `tee`/`sponge` taking it as an
+ * argument. Deliberately NARROW (user decision on issue #949 R3): broad
+ * write-verb co-occurrence taxed legitimate work and any text guard is
+ * bypassable anyway — this catches the lazy one-liner.
+ *
+ * Redirect STRUCTURE is read from the prose-masked command; quoted targets are
+ * invisible once masked, so those are matched on the raw command (Qodo #950 R5).
+ */
+export function bashWritesToPath(command: string, maskedCommand: string, targetSrc: string): boolean {
+  // `tee -a <path>` / `tee --append <path>`: tee's own options sit between it and
+  // the path it writes.
+  const STRUCTURAL = String.raw`>+\|?\s*\S*${targetSrc}|(?:^|[\s;&|(])(?:tee|sponge)(?:\s+-[A-Za-z-]+)*\s+\S*${targetSrc}`;
+  const QUOTED = String.raw`>+\s*["'][^"']*${targetSrc}|(?:^|[\s;&|(])(?:tee|sponge)(?:\s+-[A-Za-z-]+)*\s+["'][^"']*${targetSrc}`;
+  let result = new RegExp(STRUCTURAL, "i").test(maskedCommand) || new RegExp(QUOTED, "i").test(command);
+  if (!result) {
+    // A nested shell's script is code, not prose, so a redirect inside it
+    // (`bash -c 'echo x >> .git/config'`) still writes the file. Only segments
+    // that RUN a shell are read this way — a quoted argument merely describing
+    // a command stays prose (Qodo, PR #996).
+    for (const seg of unquotedSegments(command)) {
+      if (!runsNestedShell(tokenize(seg.text))) continue;
+      if (new RegExp(STRUCTURAL, "i").test(executableText(seg.text))) {
+        result = true;
+        break;
+      }
+    }
+  }
+  enfLog.debug("bash_writes_to_path", targetSrc, result);
+  return result;
+}
+
+
+const IDENTITY_TARGETS: GitOverrideTargets = {
+  env: GIT_IDENTITY_VARS,
+  flags: NO_KEYS,
+  configKeys: GIT_IDENTITY_KEYS,
+};
+
+/**
+ * Anything that sets the identity a commit is recorded under (issue #995): the
+ * `GIT_AUTHOR_*` / `GIT_COMMITTER_*` environment variables in assignment
+ * position, a
+ * per-command `git -c user.name=...`, a `git config` WRITE of an identity key,
+ * or `git commit --author`. The identity belongs to the human — an agent that
+ * can change it forges commits in someone else's name.
+ *
+ * Returns a label of what was found, or null.
+ *
+ * shortcut: a `-c` key held in a shell variable (`-c "$VAR=x"`) does not match,
+ * and a quoted value nested two shells deep is seen only if the outer view keeps
+ * it parseable — upgrade if either shows up in the wild.
+ */
+export function gitIdentityOverride(command: string): string | null {
+  // A nested shell string (`bash -c '...'`, `eval`) really runs, so both views
+  // are checked: the raw text keeps quoted option VALUES parseable
+  // (`-c "user.name=x"`), the executable view exposes what a nested shell runs.
+  const executable = executableText(command);
+  for (const text of executable && executable !== command ? [command, executable] : [command]) {
+    const found = scanGitOverrides(text, IDENTITY_TARGETS) ?? identityWritesIn(text);
+    if (found) {
+      enfLog.warn("git_identity_override", "source", found);
+      return found;
+    }
+  }
+  enfLog.debug("git_identity_override", "none", command.length);
+  return null;
+}
+
+/**
+ * The two identity writes the prefix scan cannot see: `git config <identity key>
+ * <value>` (written to disk for every later commit) and `git commit --author`
+ * (this one commit recorded as somebody else).
+ */
+function identityWritesIn(command: string): string | null {
+  // `git config user.email x` — the identity written to disk for every later commit.
+  for (const region of gitSubArgRegions(command, "config")) {
+    // Tokens come from the RAW region: tokenize() drops the quotes but keeps a
+    // quoted value as one token, so `git config user.email "a@b"` and
+    // `git config "user.email" a@b` are both seen, while a value that merely
+    // MENTIONS the key stays a single token and is never a key (Qodo, PR #996).
+    const tokens = tokenize(region);
+    if (tokens.some((t) => CONFIG_READ_FLAGS.has(t))) continue;
+    const at = tokens.findIndex((t) => GIT_IDENTITY_KEYS.has(t.toLowerCase()));
+    if (at === -1) continue;
+    // A key alone is a READ (`git config user.email` prints it): only a value
+    // after it, or an unset, changes the identity.
+    const writes = tokens.some((t) => CONFIG_UNSET_FLAGS.has(t))
+      || tokens.slice(at + 1).some((t) => !t.startsWith("-"));
+    if (writes) return `git config ${tokens[at].toLowerCase()}`;
+  }
+  // `git commit --author` — this one commit is recorded as somebody else.
+  for (const region of gitSubArgRegions(command, "commit")) {
+    // Raw region again: `--author 'A <a@b>'` and `"--author" x` are options the
+    // shell passes to git, while a `-m` message mentioning --author is ONE token.
+    const tokens = tokenize(region);
+    const at = tokens.findIndex((t) => t === "--author" || t.startsWith("--author="));
+    if (at === -1) continue;
+    // A bare `--author` with no value after it sets nothing.
+    if (tokens[at].includes("=") || (tokens[at + 1] !== undefined && !tokens[at + 1].startsWith("-"))) {
+      return "--author";
+    }
+  }
+  return null;
+}
+
+/**
+ * A path that IS git's identity configuration: `~/.gitconfig`, the XDG
+ * `~/.config/git/config`, or a repository's `.git/config`. Writing one of these
+ * changes the identity every later commit is recorded under, so agents are kept
+ * away from them entirely.
+ * The two home files count only under THIS user's home — a `.gitconfig` in
+ * /tmp or a docs fixture is not the identity git reads (Qodo, PR #996).
+ */
+/**
+ * Regex source matching a git identity config path as WRITTEN in a shell
+ * command — `$HOME`/`~`/absolute home forms and repo-local `.git/config`.
+ * One source of truth for the tripwire and its tests (Qodo, PR #996).
+ */
+export function gitIdentityConfigSrc(): string {
+  const homeSrc = homedir().replace(/\\/g, "/").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return String.raw`(?:(?:~|\$HOME|\$\{HOME\}|${homeSrc})/(?:\.gitconfig|\.config/git/config)|\.git/config)(?![A-Za-z0-9._-])`;
+}
+
+export function isGitIdentityConfigPath(p: string): boolean {
+  const norm = p.replace(/\\/g, "/").replace(/\/+$/, "");
+  const base = norm.slice(norm.lastIndexOf("/") + 1);
+  const dir = norm.slice(0, Math.max(norm.lastIndexOf("/"), 0));
+  const home = homedir().replace(/\\/g, "/").replace(/\/+$/, "");
+  const inHome = dir === home || dir === "~";
+  const result =
+    (inHome && base === ".gitconfig")
+    || norm === `${home}/.config/git/config`
+    || norm === "~/.config/git/config"
+    || /(?:^|\/)\.git\/config$/.test(norm);
+  enfLog.debug("is_git_identity_config_path", p, result);
+  return result;
+}
+
 /**
  * Every directory the command could plausibly run git in.
  *
@@ -2039,8 +2277,13 @@ function subArgSpans(command: string, sub: string): Array<{ start: number; end:
   const spans: Array<{ start: number; end: number; text: string; maskedText: string; stripped: string; masked: string }> = [];
   for (const m of masked.matchAll(re)) {
     const start = (m.index ?? 0) + m[0].length;
-    const rest = stripped.slice(start);
-    const end = rest.search(/[;&|\n]/);
+    // Boundaries are searched on the MASKED text, so a separator inside a quoted
+    // argument is prose, not the end of the invocation: in
+    // `git commit -m "message; more message" --author='A <a@b>'` the author
+    // option belongs to this commit and must stay inside its region (Qodo, PR
+    // #996). Masking is length-preserving, so the offset is valid on the
+    // original string and the region content still comes from it.
+    const end = masked.slice(start).search(/[;&|\n]/);
     const stop = end === -1 ? stripped.length : start + end;
     spans.push({
       start,

package/extensions/orchestrator/enforcement.ts

@@ -46,12 +46,16 @@ import {
   checkPythonPipBlock,
   checkRemoteExecBlock,
   checkTempFileEnforcement,
+  bashWritesToPath,
   gitAddPathspecs,
+  gitIdentityConfigSrc,
+  gitIdentityOverride,
   gitSubArgRegions,
   hasGitAddBulk,
   hasGitAddForce,
   injectSignoff,
   injectGhBodySignature,
+  isGitIdentityConfigPath,
   isReadOnlyStatement,
   isRealGitCommitOrPush,
   isRmInProjectTmp,
@@ -755,6 +759,17 @@ export function registerEnforcement(pi: ExtensionAPI, inContainer?: boolean): vo
               "\u26d4 Direct modification of pi-config-settings blocked — it carries the dangerous-command allowlist. Change settings via the /pi-config-settings command or your own editor, never agent tools.",
           };
         }
+        // Git identity config is off-limits to agents too (issue #995): the
+        // identity a commit is recorded under belongs to the human, so no agent
+        // writes it by hand — same alias-proof resolution as the settings guard.
+        if (isGitIdentityConfigPath(resolved) || isGitIdentityConfigPath(toReal(resolved))) {
+          return {
+            block: true,
+            reason:
+              "\u26d4 Git identity config is off-limits to agents. The git identity belongs to the human — " +
+              "if it is wrong, tell the user to fix their own git config.",
+          };
+        }
       }
     }
 
@@ -788,12 +803,7 @@ export function registerEnforcement(pi: ExtensionAPI, inContainer?: boolean): vo
     const maskedCmd = maskQuotedRegions(command);
     if (
       cmdLower.includes("pi-config-settings") &&
-      (/>+\|?\s*\S*pi-config-settings/i.test(maskedCmd) ||
-        /(?:^|[\s;&|(])(?:tee|sponge)\s+\S*pi-config-settings/i.test(maskedCmd) ||
-        // Quoted redirect/tee TARGETS are invisible in the masked text —
-        // catch them on the raw command (Qodo PR #950 R5).
-        />+\s*["'][^"']*pi-config-settings/i.test(command) ||
-        /(?:^|[\s;&|(])(?:tee|sponge)\s+["'][^"']*pi-config-settings/i.test(command))
+      bashWritesToPath(command, maskedCmd, "pi-config-settings")
     ) {
       return {
         block: true,
@@ -802,6 +812,21 @@ export function registerEnforcement(pi: ExtensionAPI, inContainer?: boolean): vo
       };
     }
 
+    // Block bash WRITES targeting a git identity config file (issue #995) —
+    // same narrow tripwire shape as the settings one above. The home files
+    // count only under THIS user's home: a `.gitconfig` in /tmp is not the
+    // identity git reads (Qodo, PR #996). One pattern, shared with the tests.
+    const IDENTITY_CONFIG_SRC = gitIdentityConfigSrc();
+    if (bashWritesToPath(command, maskedCmd, IDENTITY_CONFIG_SRC)) {
+      log.error("git_identity_config_write_blocked");
+      return {
+        block: true,
+        reason:
+          "\u26d4 Bash command writing a git identity config (~/.gitconfig, ~/.config/git/config, .git/config) blocked. " +
+          "The git identity belongs to the human — if it is wrong, tell the user to fix their own git config.",
+      };
+    }
+
     // Block repeated identical commands (polling-by-spam) — orchestrator only.
     // Skip on acpx: async LLM agents are unavailable; foreground polls are expected.
     const parentSupportsAsyncLlm = supportsAsyncLlm(
@@ -896,6 +921,23 @@ export function registerEnforcement(pi: ExtensionAPI, inContainer?: boolean): vo
       }
     }
 
+    // The git identity belongs to the human (issue #995): an agent that can set
+    // user.name/user.email can forge a commit in someone else's name. Checked
+    // before the git-expert split below so it holds for EVERY agent, and before
+    // any git-repo lookup so it holds outside a repo too.
+    const identityOverride = gitIdentityOverride(command);
+    if (identityOverride) {
+      // error, not warn: the command was refused, not recovered from.
+      log.error("git_identity_override_blocked", "source", identityOverride);
+      return {
+        block: true,
+        reason:
+          `\u26d4 Git identity override blocked (${identityOverride}). The git identity belongs to the human: ` +
+          "never set user.name/user.email, GIT_AUTHOR_*/GIT_COMMITTER_*, --author, or `git config user.*`. " +
+          "If the identity is wrong, tell the user to fix their own git config.",
+      };
+    }
+
     // Enforce git commit/push only via git-expert agent.
     // Use isRealGitCommitOrPush (heredoc-stripped + command-position aware) so that
     // file CONTENT / string args / paths that merely MENTION "git commit" do not trip

package/extensions/orchestrator/git-helpers.ts

@@ -771,7 +771,7 @@ const GIT_EXECUTORS = new Set([
 ]);
 
 /** Wrapper options whose operand names something other than the command. */
-const WRAPPER_VALUE_OPTIONS = new Set([
+export const WRAPPER_VALUE_OPTIONS = new Set([
   "-u", "--user", "-g", "--group", "-h", "--host", "-p", "--prompt", "-r", "--role",
   "-t", "--type", "-U", "--other-user", "-C", "--chdir", "--preserve-env",
 ]);
@@ -811,15 +811,36 @@ export function segmentRunsGit(segment: string): boolean {
   return verdict;
 }
 
-function classifySegment(segment: string): boolean {
-  const words = tokenize(segment.trim());
+/**
+ * The index of the word that runs the segment's command: skips control keywords,
+ * inline assignments, and TRANSPARENT prefixes whose own options sit before the
+ * command they run (`rtk -v git add`). Every consumer that needs "what does this
+ * segment actually run" goes through here, so a prefix is never handled in one
+ * parser and forgotten in another (Qodo, PR #996).
+ */
+function skipToCommandWord(words: string[]): number {
   let k = 0;
   while (k < words.length) {
     // `function NAME { ... }` puts the name between the keyword and the body.
     if (words[k] === "function") { k += 2; continue; }
     if (SEGMENT_SKIP.has(words[k]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[k])) { k += 1; continue; }
+    // rtk runs exactly the command after it, so the next word decides. It is not
+    // an executor: `rtk grep git add f` runs grep, it does not stage.
+    if (words[k] === "rtk") {
+      k += 1;
+      while (k < words.length && words[k].startsWith("-") && words[k] !== "-") {
+        k += WRAPPER_VALUE_OPTIONS.has(words[k]) ? 2 : 1;
+      }
+      continue;
+    }
     break;
   }
+  return k;
+}
+
+function classifySegment(segment: string): boolean {
+  const words = tokenize(segment.trim());
+  const k = skipToCommandWord(words);
   if (k < words.length) {
     // A segment can start mid-subshell, so `(git` is still the git command.
     const head = words[k].replace(/^[()]+|[()]+$/g, "");
@@ -847,13 +868,7 @@ function executedGitCommands(cmd: string): string[][] {
   const kept: string[][] = [];
   for (const raw of cmd.split(/[\n;&|()]+/)) {
     const words = tokenize(raw.trim());
-    let k = 0;
-    while (k < words.length) {
-      // `function NAME { ... }` puts the name between the keyword and the body.
-      if (words[k] === "function") { k += 2; continue; }
-      if (SEGMENT_SKIP.has(words[k]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[k])) { k += 1; continue; }
-      break;
-    }
+    const k = skipToCommandWord(words);
     if (k >= words.length) continue;
     // A segment can start mid-subshell, so `(git` is still the git command.
     const head = words[k].replace(/^[()]+|[()]+$/g, "");
@@ -893,10 +908,8 @@ const GLOBAL_LONG_VALUE_OPTIONS = new Set(["--git-dir", "--work-tree", "--namesp
  */
 /** The index of the word that runs git, or -1. */
 function gitWordIndex(words: string[]): number {
-  let k = 0;
-  while (k < words.length) {
-    if (words[k] === "function") { k += 2; continue; }
-    if (SEGMENT_SKIP.has(words[k]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[k])) { k += 1; continue; }
+  const k = skipToCommandWord(words);
+  if (k < words.length) {
     const head = words[k].replace(/^[()]+|[()]+$/g, "");
     if (isGitWord(head)) return k;
     // A wrapper runs whatever follows it. `command -v git` prints the path

package/extensions/orchestrator/trail.ts

@@ -22,6 +22,8 @@ const MIN_PROMPT_CHARS = 12;
 const QUERY_MAX_CHARS = 2_000;
 const QUERY_FALLBACK_CHARS = 200;
 const INTERACTIVE_TIMEOUT_MS = 2_000;
+// The first retrieval of a session pays process spawn plus map load (median 1.4s, #992), so cold gets a larger ceiling than warm.
+const COLD_RETRIEVAL_TIMEOUT_MS = 10_000;
 export const TRAIL_QUERY_TOOLS = ["trail_find_code", "trail_find_all", "trail_file_api", "trail_trace_calls", "trail_repo_map"] as const;
 /**
  * The five read-only Trail query tools, added to a child's tool list when it declares one.
@@ -48,7 +50,7 @@ export function trailToolsArgs(tools: readonly string[] | undefined, cwd: string
 export type TrailState = "syncing" | "ready" | "stale" | "absent" | "failed";
 export type TrailRun = (args: readonly string[], options: { cwd: string; timeoutMs?: number }) => Promise<{ stdout: string; stderr: string; code: number }>;
 type GraphStatus = "fresh" | "stale" | "absent";
-type Options = { enabled: boolean; setting?: (cwd: string, logger?: Logger) => boolean; executable?: () => Promise<boolean>; graph?: (cwd: string) => Promise<GraphStatus> | GraphStatus; retrieve?: (query: string, cwd: string) => Promise<{ pointers: string[] }>; worktree?: (cwd: string) => string | null; run?: TrailRun; interactiveTimeoutMs?: number; logger?: Logger };
+type Options = { enabled: boolean; setting?: (cwd: string, logger?: Logger) => boolean; executable?: () => Promise<boolean>; graph?: (cwd: string) => Promise<GraphStatus> | GraphStatus; retrieve?: (query: string, cwd: string) => Promise<{ pointers: string[] }>; worktree?: (cwd: string) => string | null; run?: TrailRun; interactiveTimeoutMs?: number; coldTimeoutMs?: number; logger?: Logger };
 type StatusTheme = { fg: (color: string, value: string) => string };
 type Hit = { title?: string; pointer?: string; snippet?: string; code?: string };
 type Ask = { coverage?: number; coverageStrong?: number; hits?: Hit[] };
@@ -71,11 +73,11 @@ export function trailMapDir(root: string, logger: Logger = log): string | null {
     logger.debug("map_dir_resolved", { root, layout: "trail", dir: trail });
     return trail;
   }
-  const graft = join(root, "graft");
-  if (existsSync(join(graft, ".graph", "wiring.json"))) {
+  const legacy = join(root, "graft");
+  if (existsSync(join(legacy, ".graph", "wiring.json"))) {
     // Upstream owns this path name; we only read it until trail renames it.
-    logger.debug("map_dir_resolved", { root, layout: "legacy", dir: graft });
-    return graft;
+    logger.debug("map_dir_resolved", { root, layout: "legacy", dir: legacy });
+    return legacy;
   }
   // No map yet: `.trail/cache` or `.trail/learnings` marks a repo on trail before
   // its first build lands, so that is where a map will appear.
@@ -145,7 +147,12 @@ function repoRelative(root: string, value: unknown): string | null {
   return rel.startsWith("..") || isAbsolute(rel) ? null : rel.split(sep).join("/");
 }
 function samePath(left: string, right: string): boolean { return left === right || left.endsWith(`/${right}`) || right.endsWith(`/${left}`); }
-function savedTokens(output: string): number { return [...output.matchAll(/\[(?:trail|graft)\] tokens saved ≈ ([\d,]+)/g)].reduce((total, match) => total + (Number(match[1].replaceAll(",", "")) || 0), 0); }
+function savedTokens(output: string, logger: Logger = log): number {
+  const matches = [...output.matchAll(/\[trail\] tokens saved ≈ ([\d,]+)/g)];
+  const total = matches.reduce((sum, match) => sum + (Number(match[1].replaceAll(",", "")) || 0), 0);
+  logger.debug("saved_tokens", { matches: matches.length, total });
+  return total;
+}
 function savingsStore(ctx: any, root: string, logger: Logger = log): string {
   let id: unknown = process.env.PI_SUBAGENT_CHILD === "1" ? process.env.__PI_PARENT_SESSION_ID : undefined;
   const source = id ? "parent" : "session";
@@ -401,7 +408,7 @@ export function createTrailIntegration(options: Options) {
   // telemetry into ~/.pi/logs/trail, which is the G1-G3 measurement source for #978.
   const log = options.logger ?? createLogger("trail");
   const child = process.env.PI_SUBAGENT_CHILD === "1";
-  const state = { generation: 0, root: "", store: "", dirtySignal: "", enabled: false, toolsRegistered: false, events: undefined as ExtensionAPI["events"] | undefined, value: "stale" as TrailState, nodeCount: 0, tokenSavings: 0, trailReads: 0, sourceReads: 0, repoMapShown: false, dirty: false, buildAttempted: false, refresh: undefined as Promise<boolean> | undefined, mapPaths: new Set<string>(), mapDirs: new Set<string>(), ctx: undefined as any, gate: { active: false, retrieved: false, pointers: new Set<string>() } };
+  const state = { generation: 0, root: "", store: "", dirtySignal: "", enabled: false, toolsRegistered: false, events: undefined as ExtensionAPI["events"] | undefined, value: "stale" as TrailState, nodeCount: 0, tokenSavings: 0, trailReads: 0, sourceReads: 0, repoMapShown: false, dirty: false, buildAttempted: false, warmed: false, coldAttempts: 0, refresh: undefined as Promise<boolean> | undefined, mapPaths: new Set<string>(), mapDirs: new Set<string>(), ctx: undefined as any, gate: { active: false, retrieved: false, pointers: new Set<string>() } };
   const publishSavings = () => {
     if (child || !state.events) return;
     state.events.emit("pidash:trail-savings", { tokenSavings: state.tokenSavings });
@@ -498,7 +505,7 @@ export function createTrailIntegration(options: Options) {
     } catch {}
   };
   const invalidate = (ctx: any, reason: string) => {
-    state.generation++; state.ctx = ctx; state.enabled = false; state.root = ""; state.store = ""; state.dirtySignal = ""; state.refresh = undefined; state.dirty = false; state.buildAttempted = false; state.nodeCount = 0; state.tokenSavings = 0; state.mapPaths = new Set(); state.repoMapShown = false; state.gate = { active: false, retrieved: false, pointers: new Set<string>() };
+    state.generation++; state.ctx = ctx; state.enabled = false; state.root = ""; state.store = ""; state.dirtySignal = ""; state.refresh = undefined; state.dirty = false; state.buildAttempted = false; state.warmed = false; state.coldAttempts = 0; state.nodeCount = 0; state.tokenSavings = 0; state.mapPaths = new Set(); state.repoMapShown = false; state.gate = { active: false, retrieved: false, pointers: new Set<string>() };
     clearSlot("trail", ctx); publishSavings(); log.info("session_invalidated", { reason });
   };
   const invoke = async (args: string[]) => {
@@ -568,7 +575,7 @@ export function createTrailIntegration(options: Options) {
       // they only skip the binary probe, which a one-shot run cannot report on.
       // Returning here instead used to leave those sessions without any map tool.
       const probe = !child && (isEligibleTrailStartup(event, ctx) || ["new", "reload", "resume", "fork"].includes(event?.reason));
-      state.generation++; state.refresh = undefined; state.dirty = false; state.buildAttempted = false; state.root = resolveWorktreeRoot(ctx.cwd); const root = state.root; state.repoMapShown = false; state.gate = { active: false, retrieved: false, pointers: new Set<string>() }; state.trailReads = 0; state.sourceReads = 0;
+      state.generation++; state.refresh = undefined; state.dirty = false; state.buildAttempted = false; state.warmed = false; state.coldAttempts = 0; state.root = resolveWorktreeRoot(ctx.cwd); const root = state.root; state.repoMapShown = false; state.gate = { active: false, retrieved: false, pointers: new Set<string>() }; state.trailReads = 0; state.sourceReads = 0;
       state.enabled = true; loadMap(root); state.value = "syncing";
       try { state.store = savingsStore(ctx, root, log); state.dirtySignal = state.store ? `${state.store}.dirty` : ""; if (state.dirtySignal) { mkdirSync(state.dirtySignal, { recursive: true, mode: 0o700 }); chmodSync(state.dirtySignal, 0o700); } state.tokenSavings = readSavings(state.store); } catch (error: any) { state.store = ""; state.dirtySignal = ""; state.tokenSavings = 0; log.warn("savings_restore_failed", { code: error?.code }); }
       // Provisional state while we probe. This used to be "failed", which made
@@ -624,7 +631,7 @@ export function createTrailIntegration(options: Options) {
         log.info("gate_satisfied", { by: tool.startsWith("trail_") ? "tool" : "auto_pointer_read", tool });
       }
       const kind = !event.isError ? classifyToolUse(event.toolName, event.input) : null;
-      const savings = !event.isError ? savedTokens(toolText(event.content)) : 0;
+      const savings = !event.isError ? savedTokens(toolText(event.content), log) : 0;
       if (kind === "trail") state.trailReads++; else if (kind === "source") state.sourceReads++;
       addSavings(savings);
       if (kind || savings) { setState(state.dirty ? "stale" : state.value === "absent" || state.value === "failed" ? state.value : "ready"); log.info("session_metric", { tool: event.toolName, kind, savings, trailReads: state.trailReads, sourceReads: state.sourceReads, tokenSavings: state.tokenSavings }); }
@@ -682,7 +689,14 @@ export function createTrailIntegration(options: Options) {
       if (!query || !substantive(query)) { finish("guidance_only_control_prompt"); return guidance; }
       state.gate.active = true;
       // One shared budget: a fallback retry must not double the turn's deadline.
-      const deadline = started + (options.interactiveTimeoutMs ?? INTERACTIVE_TIMEOUT_MS);
+      // `warmed` only flips on a successful retrieval, so a cold attempt that
+      // times out or fails keeps the cold ceiling; the attempt cap stops a
+      // genuinely broken CLI from paying it forever.
+      const cold = !state.warmed && state.coldAttempts < 2;
+      if (cold) state.coldAttempts++;
+      const budget = options.interactiveTimeoutMs ?? (cold ? (options.coldTimeoutMs ?? COLD_RETRIEVAL_TIMEOUT_MS) : INTERACTIVE_TIMEOUT_MS);
+      log.debug("retrieval_budget", { cold, budgetMs: budget, attempt: state.coldAttempts });
+      const deadline = started + budget;
       const remaining = () => Math.max(1, deadline - Date.now());
       type Attempt = { hits: Hit[]; failure?: { decision: string; note: string; diagnostic?: string } };
       /** One bounded retrieval attempt; null means the session changed under us. */
@@ -690,15 +704,17 @@ export function createTrailIntegration(options: Options) {
         if (options.retrieve) {
           const result = await withTimeout(options.retrieve(value, root), remaining(), log);
           if (!current()) return null;
+          state.warmed = true;
           return { hits: result.pointers.map(pointer => ({ title: pointer, pointer })) };
         }
         // `--source` inlines the code, so a hit can be used without re-opening the file.
         const result = await withTimeout(run(["ask", value, ".", "--json", "-n", "3", "--source"], { cwd: root, timeoutMs: remaining() }), remaining(), log);
         if (!current()) return null;
-        if (result.code) { const reason = diagnostic(result.stderr); return { hits: [], failure: { decision: "ask_failed", diagnostic: reason, note: `[trail] Retrieval failed: ${reason}. Raw navigation is available.` } }; }
-        const savings = savedTokens(result.stdout); addSavings(savings); setState(state.value); loadMap(root);
+        if (result.code) { const reason = diagnostic(result.stderr); return { hits: [], failure: { decision: "ask_failed", diagnostic: reason, note: `[trail] Retrieval failed: ${reason}. Call trail_find_code (describe the concept, not an identifier) for the map answer; raw navigation is available if it returns nothing relevant.` } }; }
+        const savings = savedTokens(result.stdout, log); addSavings(savings); setState(state.value); loadMap(root);
         const ask = parseAsk(result.stdout);
-        if (!ask) return { hits: [], failure: { decision: "invalid_ask_json", note: "[trail] Retrieval returned malformed output. Raw navigation is available." } };
+        if (!ask) return { hits: [], failure: { decision: "invalid_ask_json", note: "[trail] Retrieval returned malformed output. Call trail_find_code (describe the concept, not an identifier) for the map answer; raw navigation is available if it returns nothing relevant." } };
+        state.warmed = true;
         return { hits: relevant(ask) };
       };
       let hits: Hit[] = [];
@@ -716,7 +732,7 @@ export function createTrailIntegration(options: Options) {
         if (!result) return;
         if (result.failure) { state.gate.active = false; finish(result.failure.decision, result.failure.diagnostic ? { diagnostic: result.failure.diagnostic } : {}); return inject(event, [], result.failure.note); }
         hits = result.hits;
-      } catch (error: any) { if (!current()) return; state.gate.active = false; finish("ask_error"); return inject(event, [], `[trail] Retrieval failed: ${text(error?.message, 240) ?? "unknown error"}. Raw navigation is available.`); }
+      } catch (error: any) { if (!current()) return; state.gate.active = false; finish("ask_error"); return inject(event, [], `[trail] Retrieval failed: ${text(error?.message, 240) ?? "unknown error"}. Call trail_find_code (describe the concept, not an identifier) for the map answer; raw navigation is available if it returns nothing relevant.`); }
       // Still no map on disk (the seed found nothing, or this was never a
       // worktree): fail open rather than blocking navigation on a map we lack.
       if (!state.mapPaths.size) { state.gate.active = false; log.info("gate_skipped", { reason: "no_map" }); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.22.1",
+  "version": "4.22.3",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"