swarm-orchestrator 7.0.0-alpha.0

package/dist/src/wave-resizer.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdaptiveConcurrencyManager = exports.WaveResizer = void 0;
+/**
+ * dynamic wave resizer - splits waves when rate limits hit
+ * or merges small waves for efficiency
+ */
+class WaveResizer {
+    resizeHistory = [];
+    /**
+     * split wave into smaller chunks
+     */
+    splitWave(wave, chunkSize, reason) {
+        const splitWaves = [];
+        for (let i = 0; i < wave.length; i += chunkSize) {
+            splitWaves.push(wave.slice(i, i + chunkSize));
+        }
+        const event = {
+            originalWave: wave,
+            splitWaves,
+            reason,
+            timestamp: new Date().toISOString()
+        };
+        this.resizeHistory.push(event);
+        return splitWaves;
+    }
+    /**
+     * merge small waves together if safe
+     */
+    mergeWaves(waves, dependencies) {
+        const merged = [];
+        let currentMerge = [];
+        for (const wave of waves) {
+            // check if we can safely merge this wave with current
+            const canMerge = wave.every(step => {
+                const deps = dependencies.get(step) || [];
+                return deps.every(dep => currentMerge.includes(dep) === false ||
+                    merged.flat().includes(dep));
+            });
+            if (canMerge && currentMerge.length + wave.length <= 5) {
+                currentMerge.push(...wave);
+            }
+            else {
+                if (currentMerge.length > 0) {
+                    merged.push(currentMerge);
+                }
+                currentMerge = [...wave];
+            }
+        }
+        if (currentMerge.length > 0) {
+            merged.push(currentMerge);
+        }
+        return merged;
+    }
+    /**
+     * calculate optimal chunk size based on recent failures
+     */
+    calculateOptimalChunkSize(waveSize, recentFailures, queueStats) {
+        // start conservative after failures
+        if (recentFailures >= 3) {
+            return 1; // one at a time
+        }
+        else if (recentFailures >= 1) {
+            return Math.max(1, Math.floor(waveSize / 3));
+        }
+        // normal operation - respect max concurrency
+        return Math.min(waveSize, queueStats.maxConcurrency);
+    }
+    /**
+     * get resize history
+     */
+    getResizeHistory() {
+        return [...this.resizeHistory];
+    }
+}
+exports.WaveResizer = WaveResizer;
+/**
+ * adaptive concurrency manager - adjusts limits based on observed behavior
+ * Starts at maxConcurrency (aggressive) and only backs off on failures.
+ */
+class AdaptiveConcurrencyManager {
+    currentLimit;
+    minLimit = 1;
+    maxLimit;
+    consecutiveSuccesses = 0;
+    consecutiveFailures = 0;
+    constructor(initialLimit = 3, maxLimit = 10) {
+        // Start aggressive: use the configured limit immediately
+        this.currentLimit = initialLimit;
+        this.maxLimit = maxLimit;
+    }
+    /**
+     * record successful execution
+     */
+    recordSuccess() {
+        this.consecutiveSuccesses++;
+        this.consecutiveFailures = 0;
+        // Recover toward maxLimit after backoff (2 successes to step up)
+        if (this.consecutiveSuccesses >= 2 && this.currentLimit < this.maxLimit) {
+            this.currentLimit = Math.min(this.currentLimit + 1, this.maxLimit);
+            this.consecutiveSuccesses = 0;
+        }
+    }
+    /**
+     * record failure (rate limit or error)
+     */
+    recordFailure(reason) {
+        this.consecutiveFailures++;
+        this.consecutiveSuccesses = 0;
+        // aggressive backoff on rate limits
+        if (reason === 'rate_limit') {
+            this.currentLimit = Math.max(this.minLimit, Math.floor(this.currentLimit / 2));
+        }
+        else if (this.consecutiveFailures >= 3) {
+            this.currentLimit = Math.max(this.minLimit, this.currentLimit - 1);
+        }
+    }
+    /**
+     * get current recommended limit
+     */
+    getCurrentLimit() {
+        return this.currentLimit;
+    }
+    /**
+     * force set limit
+     */
+    setLimit(limit) {
+        this.currentLimit = Math.max(this.minLimit, Math.min(limit, this.maxLimit));
+    }
+}
+exports.AdaptiveConcurrencyManager = AdaptiveConcurrencyManager;

package/dist/src/wave-scheduler.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDependencyGraph = buildDependencyGraph;
+exports.identifyExecutionWaves = identifyExecutionWaves;
+/**
+ * Build a dependency graph from an execution plan.
+ * Returns a map of step number → array of dependency step numbers.
+ */
+function buildDependencyGraph(plan) {
+    const graph = new Map();
+    plan.steps.forEach(step => {
+        graph.set(step.stepNumber, step.dependencies);
+    });
+    return graph;
+}
+/**
+ * Identify waves of parallel execution (topological sort by levels).
+ * Each wave contains steps whose dependencies have all been completed
+ * in prior waves.
+ */
+function identifyExecutionWaves(graph) {
+    const waves = [];
+    const completed = new Set();
+    const allSteps = Array.from(graph.keys());
+    while (completed.size < allSteps.length) {
+        const currentWave = [];
+        // find steps whose dependencies are all completed
+        for (const step of allSteps) {
+            if (completed.has(step))
+                continue;
+            const deps = graph.get(step) || [];
+            const allDepsCompleted = deps.every(dep => completed.has(dep));
+            if (allDepsCompleted) {
+                currentWave.push(step);
+            }
+        }
+        if (currentWave.length === 0) {
+            throw new Error('Circular dependency detected or graph issue');
+        }
+        waves.push(currentWave);
+        currentWave.forEach(step => completed.add(step));
+    }
+    return waves;
+}

package/dist/src/worktree-manager.js

@@ -0,0 +1,368 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorktreeManager = void 0;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const defaults_1 = require("./defaults");
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('worktree-manager');
+/**
+ * Manages git worktrees, branches, and initial repo setup for parallel agent isolation.
+ * Extracted from SwarmOrchestrator to keep git operations in a single focused module.
+ */
+class WorktreeManager {
+    workingDir;
+    constructor(workingDir) {
+        this.workingDir = workingDir;
+    }
+    /**
+     * Create an isolated git worktree for a step's agent to work in.
+     * When repoDir differs from workingDir, the worktree forks from
+     * the target repo's history (e.g. bootstrap targeting an external project).
+     */
+    async createAgentWorktree(branchName, fromBranch, runDir, stepNumber, repoDir) {
+        let gitDir = repoDir || this.workingDir;
+        const worktreePath = path.join(runDir, 'worktrees', `step-${stepNumber}`);
+        const worktreesDir = path.dirname(worktreePath);
+        if (!fs.existsSync(worktreesDir)) {
+            fs.mkdirSync(worktreesDir, { recursive: true });
+        }
+        // Guard: verify the resolved git root matches the intended target directory.
+        // Without this, a parent repo (e.g. /home/user/.git) silently captures all
+        // git operations and worktrees fork from the wrong history.
+        gitDir = this.ensureOwnGitRepo(gitDir);
+        // Ensure the target repo has at least one commit (handles freshly-init'd repos)
+        try {
+            (0, child_process_1.execSync)('git rev-parse HEAD', { cwd: gitDir, stdio: 'pipe' });
+        }
+        catch {
+            try {
+                (0, child_process_1.execSync)('git add -A', { cwd: gitDir, stdio: 'pipe' });
+                (0, child_process_1.execSync)('git commit --allow-empty -m "chore: initialize repository"', { cwd: gitDir, stdio: 'pipe' });
+            }
+            catch {
+                try {
+                    (0, child_process_1.execSync)('git commit --allow-empty -m "chore: initialize repository"', { cwd: gitDir, stdio: 'pipe' });
+                }
+                catch {
+                    // Truly cannot commit; worktree add will fail with a clear error
+                }
+            }
+        }
+        // Resolve fromBranch: the target repo may not have the same branch name.
+        // Also handle detached-HEAD repos (SWE-bench checks out a specific commit).
+        let resolvedFromBranch = fromBranch;
+        try {
+            const targetBranch = (0, child_process_1.execSync)('git branch --show-current', { cwd: gitDir, encoding: 'utf8', stdio: 'pipe' }).trim();
+            if (targetBranch) {
+                resolvedFromBranch = targetBranch;
+            }
+            else {
+                // Detached HEAD — use the commit SHA directly as the start point.
+                // `git rev-parse --abbrev-ref HEAD` returns literal "HEAD" in detached state,
+                // which is valid as a start point, but using the full SHA is more explicit.
+                resolvedFromBranch = (0, child_process_1.execSync)('git rev-parse HEAD', { cwd: gitDir, encoding: 'utf8', stdio: 'pipe' }).trim();
+            }
+        }
+        catch {
+            // Keep the original fromBranch as best-effort fallback
+        }
+        // Create the branch without checkout
+        try {
+            (0, child_process_1.execSync)(`git branch ${branchName} ${resolvedFromBranch}`, { cwd: gitDir, stdio: 'pipe' });
+        }
+        catch {
+            // Branch already exists from a prior retry; safe to reuse
+        }
+        // Clean up existing worktree if present (e.g. from a retry)
+        if (fs.existsSync(worktreePath)) {
+            try {
+                (0, child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, { cwd: gitDir, stdio: 'pipe' });
+            }
+            catch {
+                try {
+                    (0, child_process_1.execSync)('git worktree prune', { cwd: gitDir, stdio: 'pipe' });
+                }
+                catch {
+                    // Prune is best-effort cleanup
+                }
+                fs.rmSync(worktreePath, { recursive: true, force: true });
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const proc = (0, child_process_1.spawn)('git', ['worktree', 'add', worktreePath, branchName], {
+                cwd: gitDir
+            });
+            let stderr = '';
+            if (proc.stderr) {
+                proc.stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+            }
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    resolve(worktreePath);
+                }
+                else {
+                    reject(new Error(`Failed to create worktree for step ${stepNumber}: ${stderr}`));
+                }
+            });
+        });
+    }
+    /**
+     * Remove a git worktree. Non-throwing: always resolves even on failure
+     * since worktree cleanup is best-effort post-merge.
+     */
+    async removeAgentWorktree(worktreePath) {
+        return new Promise((resolve) => {
+            const proc = (0, child_process_1.spawn)('git', ['worktree', 'remove', worktreePath, '--force'], {
+                cwd: this.workingDir
+            });
+            proc.on('close', () => {
+                resolve();
+            });
+        });
+    }
+    /**
+     * Create a new git branch (legacy path; kept for replan retry branches).
+     * Stashes uncommitted changes before switching to avoid conflicts from
+     * parallel agents.
+     */
+    async createAgentBranch(branchName, fromBranch) {
+        try {
+            (0, child_process_1.execSync)('git stash --include-untracked', { cwd: this.workingDir, stdio: 'pipe' });
+        }
+        catch {
+            // Stash fails when working tree is clean; expected during normal execution
+        }
+        return new Promise((resolve, reject) => {
+            const proc = (0, child_process_1.spawn)('git', ['checkout', '-b', branchName, fromBranch], {
+                cwd: this.workingDir
+            });
+            let stderr = '';
+            if (proc.stderr) {
+                proc.stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+            }
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Failed to create branch ${branchName}: ${stderr}`));
+                }
+            });
+        });
+    }
+    /**
+     * Switch to a git branch with a 15s timeout safety net.
+     */
+    async switchBranch(branchName) {
+        return new Promise((resolve, reject) => {
+            const proc = (0, child_process_1.spawn)('git', ['checkout', branchName], {
+                cwd: this.workingDir,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+            });
+            const timeout = setTimeout(() => {
+                proc.kill('SIGKILL');
+                reject(new Error(`Timeout switching to branch ${branchName}`));
+            }, defaults_1.DEFAULT_BRANCH_SWITCH_TIMEOUT_MS);
+            proc.on('close', (code) => {
+                clearTimeout(timeout);
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Failed to switch to branch ${branchName}`));
+                }
+            });
+            proc.on('error', (err) => {
+                clearTimeout(timeout);
+                reject(err);
+            });
+        });
+    }
+    getCurrentBranch() {
+        const result = (0, child_process_1.execSync)('git branch --show-current', {
+            cwd: this.workingDir,
+            encoding: 'utf8'
+        });
+        return result.trim() || 'main';
+    }
+    /**
+     * Resolve the repo's default branch — the one the orchestrator treats as the
+     * integration target for merges and rebases.
+     *
+     * Resolution order:
+     *   1. `git symbolic-ref refs/remotes/origin/HEAD` — the repo's upstream default
+     *      (returns `refs/remotes/origin/master` or `refs/remotes/origin/main` etc.)
+     *   2. `git branch --show-current` — whatever branch is currently checked out
+     *   3. The literal "main" as a last resort for brand-new empty repos where
+     *      neither of the above resolves.
+     *
+     * This is what replaced the old `getCurrentBranch() || 'main'` shortcut. The
+     * shortcut broke on any repo whose default isn't `main` (sympy, scikit-learn,
+     * numpy pre-2022, astropy pre-2022, and anything else that predates the
+     * main-rename wave) and on detached-HEAD checkouts like SWE-bench's, where
+     * `git branch --show-current` returns empty.
+     */
+    resolveDefaultBranch() {
+        try {
+            const head = (0, child_process_1.execSync)('git symbolic-ref refs/remotes/origin/HEAD', {
+                cwd: this.workingDir,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            // format: refs/remotes/origin/<branch>
+            const prefix = 'refs/remotes/origin/';
+            if (head.startsWith(prefix)) {
+                return head.slice(prefix.length);
+            }
+        }
+        catch {
+            // origin/HEAD not set — repo has no remote or never fetched it; fall through
+        }
+        try {
+            const current = (0, child_process_1.execSync)('git branch --show-current', {
+                cwd: this.workingDir,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            if (current)
+                return current;
+        }
+        catch {
+            // current-branch lookup failed; fall through to default
+        }
+        return 'main';
+    }
+    /**
+     * Ensure repo has at least one commit (required for branch creation).
+     * Creates an initial commit with a .gitignore if repo is empty.
+     * Also verifies the working directory is its own git root first.
+     */
+    ensureInitialCommit() {
+        // Validate git root before any operations; prevents silently
+        // committing into a parent repo like /home/user/.git
+        this.ensureOwnGitRepo(this.workingDir);
+        try {
+            (0, child_process_1.execSync)('git rev-parse HEAD', {
+                cwd: this.workingDir,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+            return;
+        }
+        catch {
+            // rev-parse fails when repo has no commits; fall through to create one
+        }
+        logger.info('  \u{1F4DD} Empty repo detected, creating initial commit...');
+        const gitignorePath = path.join(this.workingDir, '.gitignore');
+        if (!fs.existsSync(gitignorePath)) {
+            fs.writeFileSync(gitignorePath, `# Swarm orchestrator artifacts
+plans/
+runs/
+proof/
+.quickfix/
+.context/
+.locks/
+node_modules/
+`);
+        }
+        try {
+            (0, child_process_1.execSync)('git add .gitignore', { cwd: this.workingDir, stdio: 'pipe' });
+            (0, child_process_1.execSync)('git commit -m "chore: initialize repository"', { cwd: this.workingDir, stdio: 'pipe' });
+            logger.info('  \u2705 Initial commit created');
+        }
+        catch {
+            try {
+                (0, child_process_1.execSync)('git add -A', { cwd: this.workingDir, stdio: 'pipe' });
+                (0, child_process_1.execSync)('git commit --allow-empty -m "chore: initialize repository"', { cwd: this.workingDir, stdio: 'pipe' });
+                logger.info('  \u2705 Initial commit created (empty)');
+            }
+            catch (innerErr) {
+                const msg = innerErr instanceof Error ? innerErr.message : String(innerErr);
+                logger.warn(`[init] Could not create initial commit: ${msg}`);
+            }
+        }
+    }
+    /**
+     * Verify that targetDir is its own git repository root, not a subdirectory
+     * of a parent repo. If git resolves to a different root (e.g. /home/user),
+     * initialize a dedicated repo at targetDir so worktrees fork from the
+     * correct history instead of the parent's.
+     */
+    ensureOwnGitRepo(targetDir) {
+        const resolved = path.resolve(targetDir);
+        try {
+            const gitRoot = (0, child_process_1.execSync)('git rev-parse --show-toplevel', {
+                cwd: resolved, encoding: 'utf8', stdio: 'pipe'
+            }).trim();
+            if (path.resolve(gitRoot) === resolved) {
+                return resolved;
+            }
+            // Git resolved to a parent directory; targetDir is not its own repo.
+            // Initialize a fresh repo so worktrees use the right history.
+            logger.info(`  ⚠️  ${resolved} is inside parent repo ${gitRoot}; initializing dedicated git repo`);
+        }
+        catch {
+            // No git repo found at all; initialize one
+            logger.info(`  📂 No git repo at ${resolved}; initializing`);
+        }
+        (0, child_process_1.execSync)('git init', { cwd: resolved, stdio: 'pipe' });
+        (0, child_process_1.execSync)('git config user.email "swarm-orchestrator@local"', { cwd: resolved, stdio: 'pipe' });
+        (0, child_process_1.execSync)('git config user.name "Swarm Orchestrator"', { cwd: resolved, stdio: 'pipe' });
+        (0, child_process_1.execSync)('git add -A', { cwd: resolved, stdio: 'pipe' });
+        try {
+            (0, child_process_1.execSync)('git commit -m "initialize project for swarm orchestration"', {
+                cwd: resolved, stdio: 'pipe',
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+            });
+        }
+        catch {
+            (0, child_process_1.execSync)('git commit --allow-empty -m "initialize project for swarm orchestration"', {
+                cwd: resolved, stdio: 'pipe',
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+            });
+        }
+        return resolved;
+    }
+}
+exports.WorktreeManager = WorktreeManager;
+exports.default = WorktreeManager;

package/dist/src/worktree-reserved-paths.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Reserved paths for per-step commit-level exclusion (issue #27 / PR 2).
+ *
+ * Mirrors benchmarks/swe-bench/evaluation-scripts/worktree_reserved_paths.py
+ * one-for-one so that commit-time exclusion (TS side) stays in parity with
+ * capture-time exclusion (Python side). If you update one, update the other.
+ *
+ * Three categories tracked separately so audit decisions stay legible:
+ *
+ *   ORCHESTRATOR_RESERVED_PATHS — paths this codebase writes to during normal
+ *   operation. Scraped from src/**\/*.ts. Update when a new code path starts
+ *   writing to a new top-level directory inside the worktree.
+ *
+ *   BUILD_ARTIFACT_RESERVED_PATHS — paths universal build tooling writes
+ *   (package managers, compilers, test runners, venv tools). Not
+ *   orchestrator-specific; reasonable to exclude from any commit regardless.
+ *
+ *   FILE_GLOB_EXCLUDES — pure file-glob patterns (not directory prefixes).
+ *   Appended separately from the directory dual-form expansion below.
+ *
+ * The consumer is gitPathspecExcludes(), which is called at the per-step
+ * commit site in swarm-orchestrator.ts. See the parity test in
+ * test/worktree-reserved-paths.test.ts for the cross-language invariant.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_GLOB_EXCLUDES = exports.BUILD_ARTIFACT_RESERVED_PATHS = exports.ORCHESTRATOR_RESERVED_PATHS = void 0;
+exports.gitPathspecExcludes = gitPathspecExcludes;
+exports.ORCHESTRATOR_RESERVED_PATHS = [
+    // runDir tree — holds everything orchestrator-scoped:
+    //   .context/shared-context.json (per-step manifest)
+    //   .locks/ (git serialization locks)
+    //   worktrees/step-N/ (per-step isolated worktrees)
+    //   steps/step-N/share.md (transcripts)
+    //   session-state.json, metrics.json, cost-attribution.json
+    //   quality-gates/ (gate output)
+    // Excluding "runs" excludes every nested path; no need to list sub-dirs.
+    'runs',
+    // quick-fix-mode session scratch (src/quick-fix-mode.ts)
+    '.quickfix',
+    // CLI plan commands write plan-*.json here
+    // (src/plan-files.ts)
+    'plans',
+];
+exports.BUILD_ARTIFACT_RESERVED_PATHS = [
+    // Node
+    'node_modules',
+    // Python
+    '__pycache__',
+    '.venv',
+    'venv',
+    'env',
+    // JS build tools
+    '.next',
+    '.turbo',
+    '.cache',
+    // Generic build output
+    'dist',
+    'build',
+    // Test coverage
+    'coverage',
+];
+exports.FILE_GLOB_EXCLUDES = [
+    '**/*.pyc',
+    '**/*.pyo',
+    '**/*.egg-info',
+    '**/*.egg-info/**',
+    // .copilot-instructions.md — written to the repo root by prompt-builder.ts
+    // and committed before step-1 runs. Orchestrator scaffolding, not agent work.
+    // Must be excluded from SWE-bench patches or `git apply` fails in /testbed.
+    // Mirrors Python _FILE_GLOB_EXCLUDES entry added in smoke8 post-mortem fix.
+    '.copilot-instructions.md',
+];
+/**
+ * Return git pathspec :(exclude) directives covering every reserved path.
+ *
+ * For each directory entry, emits both the top-level form (`:(exclude)runs`)
+ * and a tree glob (`:(exclude)runs/**`). Git requires both when the exclude
+ * should match the directory itself AND everything under it; the top-level
+ * form alone can miss deeply nested files on some git versions.
+ *
+ * Emission count: 14 directories × 2 (dual-form) + 4 file globs = 32 args.
+ * Matches Python's git_pathspec_excludes() output one-for-one.
+ *
+ * Consumers pass this list as trailing arguments to `git add` after a
+ * positive pathspec (typically `--`). Note: git add for commits does NOT
+ * need the `.` positive pathspec that capture uses; `git add -A` already
+ * stages the whole tree and the excludes suppress the reserved paths.
+ */
+function gitPathspecExcludes() {
+    const directoryExcludes = [
+        ...exports.ORCHESTRATOR_RESERVED_PATHS,
+        ...exports.BUILD_ARTIFACT_RESERVED_PATHS,
+    ].flatMap(dir => [`:(exclude)${dir}`, `:(exclude)${dir}/**`]);
+    const globExcludes = exports.FILE_GLOB_EXCLUDES.map(g => `:(exclude)${g}`);
+    return [...directoryExcludes, ...globExcludes];
+}