codeep 3.3.3 → 3.4.1

package/dist/utils/planMode.d.ts

@@ -4,8 +4,9 @@
  * Flow:
  *   1. User runs `/plan <task>` — we ask the LLM for a numbered plan
  *      (no tool calls, no file changes) and surface it to the user.
- *   2. We hold the (task, plan) pair as the *pending* plan, scoped to
- *      the current process.
+ *   2. We hold the (task, plan) pair as the *pending* plan. Each
+ *      conversation has its own: callers that serve several at once (ACP
+ *      threads) pass a scope, and everything else shares the default one.
  *   3. User runs `/go` to execute, or `/plan <revised task>` to refine.
  *      `/go` hands the original task + approved plan to the regular
  *      agent loop as a single prompt, so the existing tool execution,
@@ -27,14 +28,19 @@ export interface PendingPlan {
     plan: string;
     createdAt: number;
 }
+/** The scope of callers that hold one conversation per process (the TUI). */
+export declare const DEFAULT_PLAN_SCOPE = "default";
 /**
  * Ask the model for a plan for the given task. Stores the (task, plan)
- * pair as the pending plan so a subsequent `/go` can execute it.
- * Throws on chat failure — caller renders the error.
+ * pair as the pending plan of `scope` so a subsequent `/go` there can
+ * execute it. Throws on chat failure — caller renders the error.
+ * `abortSignal` cancels the request; a cancelled plan is not stored.
  */
-export declare function generatePlan(task: string, onChunk?: (text: string) => void): Promise<string>;
-export declare function getPendingPlan(): PendingPlan | null;
-export declare function clearPendingPlan(): void;
+export declare function generatePlan(task: string, onChunk?: (text: string) => void, scope?: string, abortSignal?: AbortSignal): Promise<string>;
+export declare function getPendingPlan(scope?: string): PendingPlan | null;
+/** Replace the pending plan of `scope`; `null` clears it. */
+export declare function setPendingPlan(plan: PendingPlan | null, scope?: string): void;
+export declare function clearPendingPlan(scope?: string): void;
 /**
  * Compose the prompt the agent loop receives when the user runs `/go`.
  * The agent treats this as a normal task, so tool calls / verification /

package/dist/utils/planMode.js

@@ -4,8 +4,9 @@
  * Flow:
  *   1. User runs `/plan <task>` — we ask the LLM for a numbered plan
  *      (no tool calls, no file changes) and surface it to the user.
- *   2. We hold the (task, plan) pair as the *pending* plan, scoped to
- *      the current process.
+ *   2. We hold the (task, plan) pair as the *pending* plan. Each
+ *      conversation has its own: callers that serve several at once (ACP
+ *      threads) pass a scope, and everything else shares the default one.
  *   3. User runs `/go` to execute, or `/plan <revised task>` to refine.
  *      `/go` hands the original task + approved plan to the regular
  *      agent loop as a single prompt, so the existing tool execution,
@@ -58,25 +59,44 @@ Rules:
   itself. Code generation belongs in execution, not planning.
 - If the task is trivial (single-file rename, single-line edit), say so
   in one sentence and skip the formal plan — don't bloat tiny work.`;
-let pending = null;
+/** The scope of callers that hold one conversation per process (the TUI). */
+export const DEFAULT_PLAN_SCOPE = 'default';
+// One pending plan per conversation. A process-wide slot let /go in one ACP
+// thread run the plan another thread had just made. Plans are returned as
+// stored, not copied: callers tell plans apart by identity.
+const pendingByScope = new Map();
 /**
  * Ask the model for a plan for the given task. Stores the (task, plan)
- * pair as the pending plan so a subsequent `/go` can execute it.
- * Throws on chat failure — caller renders the error.
+ * pair as the pending plan of `scope` so a subsequent `/go` there can
+ * execute it. Throws on chat failure — caller renders the error.
+ * `abortSignal` cancels the request; a cancelled plan is not stored.
  */
-export async function generatePlan(task, onChunk) {
+export async function generatePlan(task, onChunk, scope = DEFAULT_PLAN_SCOPE, abortSignal) {
     const history = [
         { role: 'system', content: PLAN_SYSTEM_PROMPT },
     ];
-    const plan = await chat(task, history, onChunk);
-    pending = { task, plan, createdAt: Date.now() };
+    const plan = await chat(task, history, onChunk, undefined, undefined, abortSignal);
+    // A reply that arrives after the cancel is not a plan the user can /go.
+    if (abortSignal?.aborted) {
+        const abortError = new Error('Plan generation cancelled');
+        abortError.name = 'AbortError';
+        throw abortError;
+    }
+    pendingByScope.set(scope, { task, plan, createdAt: Date.now() });
     return plan;
 }
-export function getPendingPlan() {
-    return pending;
+export function getPendingPlan(scope = DEFAULT_PLAN_SCOPE) {
+    return pendingByScope.get(scope) ?? null;
 }
-export function clearPendingPlan() {
-    pending = null;
+/** Replace the pending plan of `scope`; `null` clears it. */
+export function setPendingPlan(plan, scope = DEFAULT_PLAN_SCOPE) {
+    if (plan)
+        pendingByScope.set(scope, plan);
+    else
+        pendingByScope.delete(scope);
+}
+export function clearPendingPlan(scope = DEFAULT_PLAN_SCOPE) {
+    pendingByScope.delete(scope);
 }
 /**
  * Compose the prompt the agent loop receives when the user runs `/go`.

package/dist/utils/projectIntelligence.d.ts

@@ -52,6 +52,8 @@ export interface ProjectIntelligence {
  * Scan project and generate intelligence
  */
 export declare function scanProject(projectPath: string): Promise<ProjectIntelligence>;
+/** What to tell the user when saveProjectIntelligence returns false. */
+export declare const INTELLIGENCE_NOT_SAVED = "Not saved: .codeep/intelligence.json could not be written (is .codeep a symlink, or read-only?).";
 /**
  * Save intelligence to .codeep/intelligence.json
  */

package/dist/utils/projectIntelligence.js

@@ -2,7 +2,8 @@
  * Project Intelligence - Deep project analysis and caching
  * Scans project once and caches important information for faster AI context
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, statSync, readdirSync } from 'fs';
+import { writeProjectFile } from './projectPaths.js';
 import { join, basename, extname, relative } from 'path';
 import { loadIgnoreRules, isIgnored } from './gitignore.js';
 // ============================================================================
@@ -46,6 +47,24 @@ const FRAMEWORK_INDICATORS = {
 // ============================================================================
 // Main Functions
 // ============================================================================
+/**
+ * Notes from an existing intelligence file. Parsed directly rather than through
+ * loadProjectIntelligence, which returns null for an older schema version —
+ * the rescan that follows a version bump would otherwise drop every note.
+ */
+function readSavedNotes(projectPath) {
+    try {
+        const filePath = join(projectPath, '.codeep', INTELLIGENCE_FILE);
+        if (!existsSync(filePath))
+            return [];
+        const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+        const notes = data && typeof data === 'object' ? data.notes : undefined;
+        return Array.isArray(notes) ? notes.filter((n) => typeof n === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Scan project and generate intelligence
  */
@@ -89,7 +108,9 @@ export async function scanProject(projectPath) {
             testDirectory: null,
             hasTests: false,
         },
-        notes: [],
+        // /memory notes live in the same file a rescan overwrites; they are the
+        // user's, not something a scan can rediscover
+        notes: readSavedNotes(projectPath),
     };
     // Load .gitignore rules once — used by scan and endpoint detection
     const ignoreRules = loadIgnoreRules(projectPath);
@@ -109,17 +130,15 @@ export async function scanProject(projectPath) {
     detectTesting(projectPath, intelligence);
     return intelligence;
 }
+/** What to tell the user when saveProjectIntelligence returns false. */
+export const INTELLIGENCE_NOT_SAVED = 'Not saved: .codeep/intelligence.json could not be written (is .codeep a symlink, or read-only?).';
 /**
  * Save intelligence to .codeep/intelligence.json
  */
 export function saveProjectIntelligence(projectPath, intelligence) {
     try {
-        const codeepDir = join(projectPath, '.codeep');
-        if (!existsSync(codeepDir)) {
-            mkdirSync(codeepDir, { recursive: true });
-        }
-        const filePath = join(codeepDir, INTELLIGENCE_FILE);
-        writeFileSync(filePath, JSON.stringify(intelligence, null, 2));
+        // .codeep/ can come with a cloned repo: never write through a symlink.
+        writeProjectFile(projectPath, join(projectPath, '.codeep', INTELLIGENCE_FILE), JSON.stringify(intelligence, null, 2));
         return true;
     }
     catch {

package/dist/utils/projectPaths.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Guards for files Codeep writes inside a project.
+ *
+ * A project's `.codeep/` directory usually arrives with a cloned repo, so the
+ * repo decides what its entries are. writeFileSync and mkdirSync follow
+ * symlinks: a committed `.codeep/progress.md -> ~/.zshrc`, or a symlinked
+ * `.codeep/` itself, would have Codeep overwrite, append to or delete files the
+ * user never pointed it at.
+ */
+export declare class UnsafeProjectPathError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * True when `dirPath` is a real directory tree under `projectRoot`: it lies
+ * inside the root by name, and every part of it that exists — itself
+ * included — is a directory, not a symlink to one. Missing parts are fine:
+ * mkdirSync creates real directories.
+ *
+ * The root itself may be a symlink; the user chose to open it.
+ */
+export declare function isSafeProjectDir(projectRoot: string, dirPath: string): boolean;
+/**
+ * True when writing `filePath` lands exactly where the path says: the file
+ * lies inside `projectRoot`, no existing directory between the root and the
+ * file is a symlink, and the file itself — if it exists — is a regular file,
+ * not a symlink.
+ */
+export declare function isSafeProjectWriteTarget(projectRoot: string, filePath: string): boolean;
+/** Create `dirPath` under `projectRoot`, refusing a path through a symlink. */
+export declare function ensureProjectDir(projectRoot: string, dirPath: string): void;
+/** Write a file under `projectRoot`, creating its directory, never through a symlink. */
+export declare function writeProjectFile(projectRoot: string, filePath: string, data: string): void;
+/** Append to a file under `projectRoot`, creating its directory, never through a symlink. */
+export declare function appendProjectFile(projectRoot: string, filePath: string, data: string): void;
+/**
+ * writeFileSync that refuses a symlink as the file itself. For files whose
+ * directory was already checked (or is the user's own), where only the last
+ * component can still be a link.
+ */
+export declare function writeFileNoFollow(filePath: string, data: string): void;
+/**
+ * A notice for a project whose `.codeep/` (or its sessions directory) is a
+ * symlink, or null. Codeep does not write through it, so without this the
+ * user would find their sessions, notes and logs silently not saved there.
+ */
+export declare function symlinkedCodeepNotice(projectRoot: string): string | null;
+/**
+ * True when `filePath` exists and, with symlinks resolved, lies outside the
+ * (resolved) project root — a committed `CODEEP.md -> ~/.aws/credentials`.
+ * A path that does not resolve is not judged here; reading it fails on its own.
+ */
+export declare function leadsOutsideProject(filePath: string, projectRoot: string): boolean;

package/dist/utils/projectPaths.js

@@ -0,0 +1,146 @@
+/**
+ * Guards for files Codeep writes inside a project.
+ *
+ * A project's `.codeep/` directory usually arrives with a cloned repo, so the
+ * repo decides what its entries are. writeFileSync and mkdirSync follow
+ * symlinks: a committed `.codeep/progress.md -> ~/.zshrc`, or a symlinked
+ * `.codeep/` itself, would have Codeep overwrite, append to or delete files the
+ * user never pointed it at.
+ */
+import { closeSync, constants, lstatSync, mkdirSync, openSync, realpathSync, writeFileSync, } from 'fs';
+import { dirname, join, relative, resolve, isAbsolute, sep } from 'path';
+export class UnsafeProjectPathError extends Error {
+    path;
+    constructor(path) {
+        super(`Refusing to write ${path}: it is a symlink or lies under one`);
+        this.path = path;
+        this.name = 'UnsafeProjectPathError';
+    }
+}
+/** True if `target` lies strictly inside `root` by name. */
+function insideByName(root, target) {
+    const rel = relative(root, target);
+    return !!rel && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/**
+ * True when `dirPath` is a real directory tree under `projectRoot`: it lies
+ * inside the root by name, and every part of it that exists — itself
+ * included — is a directory, not a symlink to one. Missing parts are fine:
+ * mkdirSync creates real directories.
+ *
+ * The root itself may be a symlink; the user chose to open it.
+ */
+export function isSafeProjectDir(projectRoot, dirPath) {
+    const root = resolve(projectRoot);
+    const dir = resolve(dirPath);
+    if (!insideByName(root, dir))
+        return false;
+    // Stops at the filesystem root too, so a caller that skips the check above
+    // can never spin on dirname('/') === '/'.
+    for (let d = dir; d !== root && d !== dirname(d); d = dirname(d)) {
+        const st = lstatSync(d, { throwIfNoEntry: false });
+        if (st && !st.isDirectory())
+            return false; // a symlinked directory is not a directory to lstat
+    }
+    return true;
+}
+/**
+ * True when writing `filePath` lands exactly where the path says: the file
+ * lies inside `projectRoot`, no existing directory between the root and the
+ * file is a symlink, and the file itself — if it exists — is a regular file,
+ * not a symlink.
+ */
+export function isSafeProjectWriteTarget(projectRoot, filePath) {
+    const root = resolve(projectRoot);
+    const target = resolve(filePath);
+    if (!insideByName(root, target))
+        return false;
+    const final = lstatSync(target, { throwIfNoEntry: false });
+    if (final && !final.isFile())
+        return false; // symlinks, directories, devices, FIFOs
+    const dir = dirname(target);
+    return dir === root || isSafeProjectDir(root, dir);
+}
+/** Create `dirPath` under `projectRoot`, refusing a path through a symlink. */
+export function ensureProjectDir(projectRoot, dirPath) {
+    if (!isSafeProjectDir(projectRoot, dirPath))
+        throw new UnsafeProjectPathError(dirPath);
+    mkdirSync(dirPath, { recursive: true });
+}
+// O_NOFOLLOW makes the open itself fail on a symlinked last component, so
+// nothing can swap one in between the check and the write. Windows has no
+// such flag; there the lstat check in isSafeProjectWriteTarget is what holds.
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const WRITE_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | NOFOLLOW;
+const APPEND_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | NOFOLLOW;
+function checkedTarget(projectRoot, filePath) {
+    const dir = dirname(resolve(filePath));
+    if (dir !== resolve(projectRoot))
+        ensureProjectDir(projectRoot, dir);
+    if (!isSafeProjectWriteTarget(projectRoot, filePath))
+        throw new UnsafeProjectPathError(filePath);
+}
+function writeThroughFd(filePath, data, flags) {
+    const fd = openSync(filePath, flags, 0o644);
+    try {
+        writeFileSync(fd, data, 'utf-8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Write a file under `projectRoot`, creating its directory, never through a symlink. */
+export function writeProjectFile(projectRoot, filePath, data) {
+    checkedTarget(projectRoot, filePath);
+    writeThroughFd(filePath, data, WRITE_FLAGS);
+}
+/** Append to a file under `projectRoot`, creating its directory, never through a symlink. */
+export function appendProjectFile(projectRoot, filePath, data) {
+    checkedTarget(projectRoot, filePath);
+    writeThroughFd(filePath, data, APPEND_FLAGS);
+}
+/**
+ * writeFileSync that refuses a symlink as the file itself. For files whose
+ * directory was already checked (or is the user's own), where only the last
+ * component can still be a link.
+ */
+export function writeFileNoFollow(filePath, data) {
+    const st = lstatSync(filePath, { throwIfNoEntry: false });
+    if (st && !st.isFile())
+        throw new UnsafeProjectPathError(filePath);
+    writeThroughFd(filePath, data, WRITE_FLAGS);
+}
+/**
+ * A notice for a project whose `.codeep/` (or its sessions directory) is a
+ * symlink, or null. Codeep does not write through it, so without this the
+ * user would find their sessions, notes and logs silently not saved there.
+ */
+export function symlinkedCodeepNotice(projectRoot) {
+    const codeep = lstatSync(join(projectRoot, '.codeep'), { throwIfNoEntry: false });
+    if (codeep?.isSymbolicLink()) {
+        return '.codeep in this project is a symlink, so Codeep does not write into it: sessions are saved in ~/.codeep/sessions, and project notes, the progress log and the audit log are not written.';
+    }
+    const sessions = lstatSync(join(projectRoot, '.codeep', 'sessions'), { throwIfNoEntry: false });
+    if (sessions?.isSymbolicLink()) {
+        return '.codeep/sessions in this project is a symlink, so sessions are saved in ~/.codeep/sessions instead.';
+    }
+    return null;
+}
+/**
+ * True when `filePath` exists and, with symlinks resolved, lies outside the
+ * (resolved) project root — a committed `CODEEP.md -> ~/.aws/credentials`.
+ * A path that does not resolve is not judged here; reading it fails on its own.
+ */
+export function leadsOutsideProject(filePath, projectRoot) {
+    let real;
+    let realRoot;
+    try {
+        real = realpathSync(filePath);
+        realRoot = realpathSync(projectRoot);
+    }
+    catch {
+        return false;
+    }
+    const rel = relative(realRoot, real);
+    return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}

package/dist/utils/shell.d.ts

@@ -9,12 +9,23 @@ export interface CommandResult {
     duration: number;
     command: string;
     args: string[];
+    /** Set when the command was stopped through `CommandOptions.signal`. */
+    cancelled?: boolean;
+    /** Set when the command was killed at `CommandOptions.timeout`. Its partial
+     *  stdout and stderr are kept; the timeout note follows the stderr. */
+    timedOut?: boolean;
 }
 export interface CommandOptions {
     cwd?: string;
     timeout?: number;
     env?: Record<string, string>;
     projectRoot?: string;
+    /**
+     * Stops the command when it fires: the child is killed and the result
+     * comes back at once with `cancelled: true`. Honoured by
+     * executeCommandAsync only — the sync runner cannot be interrupted.
+     */
+    signal?: AbortSignal;
 }
 /**
  * Validate if a command is safe to execute (synchronous checks).
@@ -24,6 +35,114 @@ export declare function validateCommand(command: string, args: string[], options
     valid: boolean;
     reason?: string;
 };
+/**
+ * The environment a validated command runs in.
+ *
+ * `git` is on ALLOWED_COMMANDS, so a skill's shell line, a `!` command or the
+ * agent's own execute_command reaches git with whatever the repository put in
+ * its `.git/config` — and several of those settings make git RUN a program:
+ * a `filter.<driver>.clean` fires during the index refresh `git status` does,
+ * before anything looks like it executed code. Route git through the same
+ * hardening Codeep's own git calls use.
+ *
+ * Hooks are deliberately left alone here. The command was approved as
+ * written, so `git commit` through this path runs the repository's
+ * pre-commit hook exactly as it would in the user's terminal.
+ *
+ * A caller's own `env` goes in as the BASE rather than on top of the result:
+ * spread afterwards, their GIT_CONFIG_COUNT would replace ours and silently
+ * drop every override above their count.
+ *
+ * The bare name is the whole test because it has to be: validateCommand()
+ * only lets a command through when ALLOWED_COMMANDS holds it, and that set
+ * holds `git`, not `/usr/bin/git`. A path-spelled git never reaches here.
+ *
+ * The directory scanned comes from the ARGV, not from the spawn's cwd: `git
+ * -C vendor/lib status` reads the vendored checkout's config, so that is the
+ * config that has to be neutralised. The argv forms that redirect git
+ * somewhere this cannot follow (`--git-dir`, `--work-tree`, `--exec-path`,
+ * `--config-env`) never get here — validateCommand() refuses them.
+ *
+ * Throws `GitHardeningError` when the repository's config cannot be scanned —
+ * both runners below turn that into a failed CommandResult, because a refusal
+ * is this command's own failure and the user reads it as such.
+ *
+ * EXPORTED, and this signature is the contract, because the ACP terminal
+ * path spawns its own children and has to harden the SAME repository this
+ * does. Call it with the parsed command, its argv, the cwd the spawn will
+ * get and the caller's own env in `options.env`, and hand the result to the
+ * spawn as `env` — do not spread anything over it, or a later
+ * GIT_CONFIG_COUNT replaces ours and silently drops every override above it.
+ * The argv is not optional there: `git -C vendor/lib status` scans
+ * `vendor/lib`, and a caller that passes only the cwd hardens the wrong
+ * repository. A shell LINE rather than an argv belongs to shellCommandEnv()
+ * below instead. Both throw, and a refusal that escapes a promise executor
+ * never settles it.
+ */
+export declare function commandEnv(command: string, args: string[], cwd: string, options?: CommandOptions): NodeJS.ProcessEnv;
+/**
+ * The environment for a whole SHELL COMMAND LINE that may reach git.
+ *
+ * commandEnv() above can check a parsed binary name; a line handed to a shell
+ * can reach git from anywhere inside it — `cd sub && git status`, `make && git
+ * commit`, `foo | git apply` — so it needs its own entry point. This is that
+ * entry point for the callers that spawn with `shell: true`: the skill runner
+ * in src/acp/commands.ts and the one in src/renderer/agentExecution.ts, both
+ * of which used to reach git raw. A hostile `gpg.program` that createCommit
+ * neutralises still executed through those two spawns (proven, git 2.54).
+ *
+ * This is the ONE helper for that job — an earlier cut of this hotfix also
+ * had a `hardenedShellEnv()` in utils/toolExecution.ts, which hardened every
+ * skill step unconditionally and therefore refused an `echo` in a repository
+ * whose config cannot be scanned. Keep it one: two helpers with two different
+ * answers to "does a refusal stop this line?" is how one of them ends up
+ * wrong and unused.
+ *
+ * The contract, since those two call sites are not this file's to edit:
+ *
+ * - Pass the command line, the cwd the shell will get and any env of your
+ *   own, and hand the RESULT to the spawn as `env`. Do not spread anything
+ *   over it — a later `GIT_CONFIG_COUNT` replaces ours and silently drops
+ *   every override above it.
+ * - It THROWS `GitHardeningError` when the repository's config cannot be
+ *   scanned, or names a program no override can switch off. Catch it and fail
+ *   the command with `error.message`, which is written for the user. Letting
+ *   it escape a `spawnSync` call site turns a refusal into a crash; letting
+ *   it escape inside a promise executor leaves the caller hanging.
+ * - Hooks are left alone, as they are for executeCommand(): the line was
+ *   approved as written, so `git commit` in it runs the repository's
+ *   pre-commit hook exactly as it would in the user's terminal.
+ * - A line that cannot reach git comes back unhardened, so a repository with
+ *   an unreadable config does not also break `echo`. That is also why a
+ *   refusal never reaches a non-git line: an `echo` must not stop working
+ *   because some repository in the project sets `remote.origin.uploadpack`.
+ *
+ * WHAT THIS CAN AND CANNOT PROMISE, because a shell line is not an argv:
+ *
+ * - Scanned: the repository at `cwd`, AND every submodule of it — the ones
+ *   its index records as gitlinks and the ones its config records by name,
+ *   wherever each keeps its git directory (see listSubmoduleConfig in
+ *   utils/git.ts). Every key in REPO_EXECUTING_RULES
+ *   that any of them sets is neutralised, and because the overrides ride in
+ *   the ENVIRONMENT rather than in an argv, they apply wherever in the line
+ *   git ends up — so `cd vendor/lib && git add` is covered in full when
+ *   `vendor/lib` is a submodule, which is the shape a skill step usually has.
+ * - Not scanned: a repository that is not `cwd` and not one of its
+ *   submodules — an independent checkout under `vendor/`, a sibling clone,
+ *   anywhere a `make` target cds to. There is no way to know where a shell
+ *   line ends up without running it, so this does not pretend to. What still
+ *   covers those is the always-on GIT_EXECUTING_CONFIG layer, which is why
+ *   `core.fsmonitor` is blanket there rather than scope-aware. The gap is the
+ *   keys GIT_CONFIG_* cannot wildcard — `filter.*` above all — in an
+ *   unrelated repository below the one scanned. Proven with git 2.54: `cd
+ *   vendor/lib && git status`, with `vendor/lib` a plain nested clone rather
+ *   than a submodule, did not run the nested `core.fsmonitor` and did run the
+ *   nested `filter.<d>.clean`.
+ * - executeCommand()'s argv path has no such gap: it reads `-C` out of the
+ *   argv and scans where git will actually run, and refuses `--git-dir` /
+ *   `--work-tree` / `--exec-path` / `--config-env` outright.
+ */
+export declare function shellCommandEnv(commandLine: string, cwd: string, env?: Record<string, string>): NodeJS.ProcessEnv;
 /**
  * Execute a shell command with safety checks
  */