The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(adapter-utils): harden the referenced-project ignore scan (#12214)
Nicky Leach198fc8b281db
diff --git a/packages/adapter-utils/src/acpx-engine/execute.test.ts b/packages/adapter-utils/src/acpx-engine/execute.test.tsindex 63c5fe4789..5575b37b46 100644--- a/packages/adapter-utils/src/acpx-engine/execute.test.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.test.ts@@ -38,6 +38,7 @@ import {} from "./execute.js";import { runChildProcess } from "../server-utils.js";import { setExpensiveWorkspaceGitExecutor } from "../git-workspace-sync.js";+import { resolveReferencedSourceIgnore } from "../sandbox-managed-runtime.js";import {getActiveStepContext,runWithRuntimeParent,@@ -1591,6 +1592,37 @@ describe("shared ACPX engine runtime behavior", () => {expect(signature).toBe("unreadable:git status timed out");});+ it("never leaks a raw absolute path into the signature, even when the underlying scan embedded one", async () => {+ const root = await makeTempRoot();+ const localPath = path.join(root, "does-not-exist");++ // A raw toplevel string that makes `localPath` a non-descendant, carrying+ // a sensitive absolute path — exactly the shape a caught Git diagnostic+ // could embed. `resolveReferencedSourceIgnore` is the single choke point+ // that must reduce it to the fixed category before the signature (which+ // embeds `reason` verbatim as `unreadable:${reason}`) ever sees it.+ const sensitivePath = "/home/alice/project";+ let ignoreResolution;+ try {+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${sensitivePath}\n`, stderr: "" };+ }+ return { stdout: "", stderr: "" };+ });+ ignoreResolution = await resolveReferencedSourceIgnore(localPath);+ } finally {+ setExpensiveWorkspaceGitExecutor(null);+ }+ expect(ignoreResolution.kind).toBe("failed");++ const signature = await referencedSourceContentSignature(localPath, ignoreResolution);++ expect(signature).toBe("unreadable:git-toplevel-not-descendant");+ expect(signature).not.toContain(sensitivePath);+ expect(signature).not.toContain(localPath);+ });+it("skips a Git-ignored file (exact match) so its content never affects the signature", async () => {const root = await makeTempRoot();const localPath = path.join(root, "project");diff --git a/packages/adapter-utils/src/git-workspace-sync.test.ts b/packages/adapter-utils/src/git-workspace-sync.test.tsindex 035d3203eb..31ac4590a8 100644--- a/packages/adapter-utils/src/git-workspace-sync.test.ts+++ b/packages/adapter-utils/src/git-workspace-sync.test.ts@@ -14,7 +14,10 @@ import {integrateImportedGitHead,isMissingGitPrerequisiteError,readGitWorkspaceSnapshot,+ ReferencedSourceIgnoreScanLimitExceededError,readReferencedSourceGitIgnoredPaths,+ REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT,+ REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES,runLocalGit,sanitizeGitRemoteUrl,setExpensiveWorkspaceGitExecutor,@@ -64,6 +67,44 @@ describe("git workspace sync", () => {]);});+ it("keeps every filename byte for a padded name in each of the four anchor lanes", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-git-anchor-whitespace-"));+ cleanupDirs.push(rootDir);+ const repo = await createRepo(rootDir);++ // Deleted lane: commit the file first (in isolation, before anything else+ // is staged), then remove it from the work tree.+ const deletedName = " deleted padded ";+ await writeFile(path.join(repo, deletedName), "deleted\n", "utf8");+ await git(repo, ["add", deletedName]);+ await git(repo, ["commit", "-qm", "add deleted padded"]);+ await rm(path.join(repo, deletedName));++ // Overlay lane, staged-new half: `git diff --diff-filter=ACMRTUXB HEAD`+ // reports a staged-but-uncommitted file as added.+ const overlayName = " overlay padded ";+ await writeFile(path.join(repo, overlayName), "overlay\n", "utf8");+ await git(repo, ["add", overlayName]);++ // Overlay lane, untracked half: `ls-files --others --exclude-standard`.+ const untrackedName = " untracked padded ";+ await writeFile(path.join(repo, untrackedName), "untracked\n", "utf8");++ // Ignored lane: a double-wildcard pattern avoids the separate rule that+ // Git trims an unescaped trailing space in a .gitignore PATTERN itself;+ // the padding under test lives in the matched FILE name.+ const ignoredName = " ignored padded ";+ await writeFile(path.join(repo, ".gitignore"), "*ignored*padded*\n", "utf8");+ await writeFile(path.join(repo, ignoredName), "ignored\n", "utf8");++ const snapshot = await readGitWorkspaceSnapshot(repo);++ expect(snapshot?.overlayPaths).toContain(overlayName);+ expect(snapshot?.overlayPaths).toContain(untrackedName);+ expect(snapshot?.deletedPaths).toContain(deletedName);+ expect(snapshot?.ignoredPaths).toContain(ignoredName);+ });+async function createRepo(rootDir: string): Promise<string> {const repo = path.join(rootDir, "repo");await mkdir(repo, { recursive: true });@@ -576,6 +617,157 @@ describe("git workspace sync", () => {expect(scan?.ignoredPaths).toEqual([paddedName]);});+ it("fails closed when the parsed ignored-entry count exceeds the bound", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-bound-count-"));+ cleanupDirs.push(rootDir);+ const repo = await createRepo(rootDir);+ // Synthesize the `git ls-files --others --ignored -z` output directly,+ // rather than creating ten thousand real files, by intercepting the+ // scan at the executor seam. The parser must reject this before it+ // sorts or re-relativizes the list.+ const overLimitCount = REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT + 1;+ const syntheticIgnored = `${Array.from({ length: overLimitCount }, (_, index) => `entry-${index}`).join("\0")}\0`;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ return { stdout: syntheticIgnored, stderr: "" };+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ await expect(readReferencedSourceGitIgnoredPaths(repo)).rejects.toBeInstanceOf(+ ReferencedSourceIgnoreScanLimitExceededError,+ );+ });++ it("fails closed when the summed UTF-8 byte size of ignored paths exceeds the bound", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-bound-bytes-"));+ cleanupDirs.push(rootDir);+ const repo = await createRepo(rootDir);+ // One entry alone exceeds the byte bound, well under the entry-count bound.+ const hugeEntry = "a".repeat(REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES + 1);+ const syntheticIgnored = `${hugeEntry}\0`;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ return { stdout: syntheticIgnored, stderr: "" };+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ await expect(readReferencedSourceGitIgnoredPaths(repo)).rejects.toBeInstanceOf(+ ReferencedSourceIgnoreScanLimitExceededError,+ );+ });++ it("fails closed on the byte bound while it is still accumulating, before it would ever reach a later entry-count breach", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-bound-order-"));+ cleanupDirs.push(rootDir);+ const repo = await createRepo(rootDir);+ // Three entries alone cross the byte bound. Many more small entries+ // follow, so the FULL response also carries more than the entry-count+ // bound. A parser that fully builds the list before checking either+ // bound (post-parse) would report the entry-count breach, because it+ // checks that bound first against the whole materialized list. A+ // parser that checks both bounds while the list accumulates rejects on+ // the byte bound instead, the moment the third entry crosses it, well+ // before the count bound is ever reached.+ const oversizedEntry = "a".repeat(Math.ceil(REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES / 2) + 1);+ const bigEntries = Array.from({ length: 3 }, (_, index) => `${oversizedEntry}-${index}`);+ const trailingEntries = Array.from(+ { length: REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT + 10 },+ (_, index) => `trailing-${index}`,+ );+ const syntheticIgnored = `${[...bigEntries, ...trailingEntries].join("\0")}\0`;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ return { stdout: syntheticIgnored, stderr: "" };+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ await expect(readReferencedSourceGitIgnoredPaths(repo)).rejects.toThrow(/UTF-8 bytes/);+ });++ it("bounds the raw command-output allowance to the ignore-scan limits, not the general-purpose full-tree ceiling", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-raw-buffer-"));+ cleanupDirs.push(rootDir);+ const repo = await createRepo(rootDir);+ let observedMaxBuffer: number | undefined;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ observedMaxBuffer = input.maxBuffer;+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ await readReferencedSourceGitIgnoredPaths(repo);++ // Enough headroom for a scan within bounds to complete, but a small+ // multiple of the byte bound — not the far larger allowance the+ // anchor workspace's general-purpose full-tree reads use.+ expect(observedMaxBuffer).toBeGreaterThan(REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES);+ expect(observedMaxBuffer).toBeLessThan(16 * 1024 * 1024);+ });++ it("does not fail closed on a huge amount of unrelated tracked-change and untracked noise, when the ignored set itself stays in bounds", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-mixed-status-"));+ cleanupDirs.push(rootDir);+ const repo = await createRepo(rootDir);+ await writeFile(path.join(repo, ".gitignore"), "secret.env\n", "utf8");+ await writeFile(path.join(repo, "secret.env"), "TOKEN=abc\n", "utf8");++ // Many long-named, untracked, NOT-ignored files at the repository root.+ // `git status` reports one record per file (root-level files are never+ // collapsed the way an entirely untracked directory is), so this alone+ // makes the raw `git status --ignored` response exceed the raw buffer+ // bound this scan used to apply to the WHOLE response, well before the+ // parser ever got to discard these non-ignored records. The ignored set+ // above stays a single small entry throughout.+ const noiseNameLength = 220;+ const noiseFileCount = 30_000;+ const noiseNames = Array.from(+ { length: noiseFileCount },+ (_, index) => `${"n".repeat(noiseNameLength - 6)}${String(index).padStart(6, "0")}`,+ );+ const writeConcurrency = 200;+ for (let start = 0; start < noiseNames.length; start += writeConcurrency) {+ const batch = noiseNames.slice(start, start + writeConcurrency);+ await Promise.all(batch.map((name) => writeFile(path.join(repo, name), "", "utf8")));+ }++ // Confirm this test actually reproduces the reported defect precondition:+ // the raw `git status --ignored` response for this repository state is+ // larger than the 4 MiB raw buffer bound the scan used to apply to the+ // whole response, not just to the declared ignored-set limits. A large+ // explicit maxBuffer is required here only to observe that raw size;+ // the scan under test never issues this command.+ const rawStatusResult = await runLocalGit(+ repo,+ ["status", "--ignored", "--porcelain=v1", "-z", "--untracked-files=normal"],+ { maxBuffer: 16 * 1024 * 1024 },+ );+ expect(Buffer.byteLength(rawStatusResult.stdout, "utf8")).toBeGreaterThan(REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES * 2);++ const scan = await readReferencedSourceGitIgnoredPaths(repo);++ expect(scan?.ignoredPaths).toEqual(["secret.env"]);+ });+it("routes both scan commands through the registered scheduler instead of spawning git directly", async () => {const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-referenced-scheduler-"));cleanupDirs.push(rootDir);diff --git a/packages/adapter-utils/src/git-workspace-sync.ts b/packages/adapter-utils/src/git-workspace-sync.tsindex b8a354c02c..0d80e76cd4 100644--- a/packages/adapter-utils/src/git-workspace-sync.ts+++ b/packages/adapter-utils/src/git-workspace-sync.ts@@ -40,6 +40,19 @@ export type ExpensiveWorkspaceGitExecutor = (let expensiveWorkspaceGitExecutor: ExpensiveWorkspaceGitExecutor | null = null;+/**+ * The workspace Git scan scheduler's typed code for a saturated queue+ * (`server/src/services/workspace-git-operation-scheduler.ts`,+ * `WORKSPACE_GIT_SCAN_ERROR_CODES.saturated`). Declared again here because+ * `adapter-utils` cannot import from `server` (the reverse direction is+ * allowed, not this one); `server` carries a test that asserts the two+ * literals stay equal. `resolveReferencedSourceIgnore` in+ * `sandbox-managed-runtime.ts` reads this code off a caught error's `code`+ * property, never off its message text, to retry only a saturated queue and+ * fail closed on every other Git scan error.+ */+export const WORKSPACE_GIT_SCAN_SATURATED_CODE = "workspace_git_scan_saturated";+/*** Lets a host process apply its process-wide admission policy to the adapter* package's full-tree Git walks. Standalone adapter-utils consumers retain the@@ -161,7 +174,16 @@ export async function readGitWorkspaceSnapshot(localDir: string): Promise<GitWor]);const branchName = branchResult.stdout.trim();- const splitNul = (value: string) => value.split("\0").map((entry) => entry.trim()).filter(Boolean);+ // `-z` already delimits each record with a NUL byte, so a leading or+ // trailing space in a record is part of the path itself, not padding to+ // remove — trimming it would resolve to a path that does not exist. A+ // length check finds the one genuinely empty record `-z` appends after+ // the last NUL, without eating a real path's own leading or trailing+ // whitespace. This applies to all four NUL-delimited outputs below (the+ // overlay diff, the untracked list, the deleted list, and the ignored+ // list); `branchName` and `headCommit` come from non-`-z` commands and+ // keep their own `.trim()` above and below, which is safe.+ const splitNul = (value: string) => value.split("\0").filter((entry) => entry.length > 0);return {headCommit: headCommitResult.stdout.trim(),branchName: branchName && branchName !== "HEAD" ? branchName : null,@@ -180,7 +202,7 @@ export async function readGitWorkspaceSnapshot(localDir: string): Promise<GitWor}}-/** The `git status --ignored` output for one directory, read by {@link readReferencedSourceGitIgnoredPaths}. */+/** The `git ls-files --others --ignored` output for one directory, read by {@link readReferencedSourceGitIgnoredPaths}. */export interface ReferencedSourceGitIgnoreScan {/** The absolute repository top level `git rev-parse --show-toplevel` reports. */toplevel: string;@@ -261,6 +283,43 @@ function isNotAGitRepositoryError(error: unknown): boolean {return /not a git repository/i.test(stderr) || /not a git repository/i.test(message);}+/** Bound on the number of parsed ignored entries `readReferencedSourceGitIgnoredPaths` accepts before it fails closed. */+export const REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT = 10_000;++/** Bound on the summed UTF-8 byte length of the resolved ignored-path strings `readReferencedSourceGitIgnoredPaths` accepts before it fails closed. */+export const REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES = 2 * 1024 * 1024;++/**+ * Bound on the raw `git ls-files --others --ignored` output+ * `readReferencedSourceGitIgnoredPaths` lets Node buffer, kept proportionate+ * to {@link REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES} instead of the far+ * larger allowance the anchor workspace's general-purpose full-tree reads+ * use. The command reports only ignored entries (see the invocation below),+ * so this raw allowance is not exposed to an unrelated tracked-change or+ * ordinary-untracked record count — a repository with a huge diff or a huge+ * untracked set never grows this command's output. The parser below still+ * enforces the real entry-count and byte bounds while it reads each record,+ * so this value only needs headroom for the NUL delimiter and the trailing+ * slash on every entry, not room for an oversized ignored-path list to land+ * in memory in the first place.+ */+const REFERENCED_SOURCE_IGNORE_MAX_RAW_BUFFER = REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES * 2;++/**+ * Thrown by {@link readReferencedSourceGitIgnoredPaths} when the parsed+ * ignored-path list breaches {@link REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT}+ * or {@link REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES}, so the caller can+ * classify the failure as a bound breach instead of a plain Git read error.+ * The message never leaves this package: `resolveReferencedSourceIgnore`+ * replaces it with a fixed category before the failure reaches any consumer.+ */+export class ReferencedSourceIgnoreScanLimitExceededError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "ReferencedSourceIgnoreScanLimitExceededError";+ }+}+/*** Read the Git-ignored paths of a referenced-project host directory, for the* staging path to exclude them (see `resolveReferencedSourceIgnore` in@@ -270,8 +329,10 @@ function isNotAGitRepositoryError(error: unknown): boolean {** Returns `null` when `localDir` is not a Git work tree — the caller keeps* today's fixed excludes for that case. Throws on any other Git error, a- * timeout, or malformed output, so the caller can fail closed and skip- * staging that one project instead of shipping it unfiltered.+ * timeout, malformed output, or a bound breach (see+ * {@link ReferencedSourceIgnoreScanLimitExceededError}), so the caller can+ * fail closed and skip staging that one project instead of shipping it+ * unfiltered.*/export async function readReferencedSourceGitIgnoredPaths(localDir: string,@@ -295,24 +356,70 @@ export async function readReferencedSourceGitIgnoredPaths(throw new Error(`git rev-parse --show-toplevel returned an empty path for ${localDir}`);}+ // `ls-files --others --ignored --exclude-standard` reports only ignored+ // entries — unlike `git status --ignored`, it never also reports a tracked+ // change or an ordinary untracked file. A repository with a huge diff or a+ // huge untracked set (unrelated to what is ignored) cannot inflate this+ // command's raw output, so the raw buffer bound below only ever has to+ // cover the declared ignored-set limits, not an unbounded amount of+ // unrelated status noise ahead of them.+ // `--directory` collapses an entirely ignored directory into one entry with+ // a trailing slash, matching `git status --ignored`'s traditional mode.+ // `--full-name` reports paths relative to the repository toplevel, so this+ // still matches the toplevel-relative shape `resolveReferencedSourceIgnore`+ // re-relativizes against, regardless of `localDir`'s position under it.const ignoredResult = await runHardenedReadOnlyGit(localDir,- ["status", "--ignored", "--porcelain=v1", "-z", "--untracked-files=normal"],+ ["ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "--full-name", "-z"],"referenced_source.ignored_files",- { timeout: 60_000, maxBuffer: 16 * 1024 * 1024 },+ { timeout: 60_000, maxBuffer: REFERENCED_SOURCE_IGNORE_MAX_RAW_BUFFER },);- // Do not trim each entry: `git status -z` already delimits entries with a- // NUL byte, so a leading or trailing space in an entry is part of the path- // itself, not padding to remove. A length check finds the one genuinely- // empty entry `-z` appends after the last NUL, without eating a real path's- // own leading or trailing whitespace.- const ignoredPaths = ignoredResult.stdout- .split("\0")- .filter((entry) => entry.length > 0)- .filter((entry) => entry.startsWith("!! "))- .map((entry) => entry.slice(3).replace(/\/+$/, ""))- .filter((entry) => entry.length > 0)- .sort((left, right) => left.localeCompare(right));++ // Read one NUL-delimited record at a time and enforce both bounds while the+ // ignored-entry list accumulates, instead of splitting and mapping the+ // whole response into a list first and only then checking its size. A+ // pathologically large ignore set (a huge repository, or one crafted to+ // hold many ignored entries) must fail closed the moment it breaches a+ // bound, without this scan first retaining and transforming the full+ // oversized response.+ //+ // Do not trim each entry: `-z` already delimits entries with a NUL byte, so+ // a leading or trailing space in an entry is part of the path itself, not+ // padding to remove. A length check finds the one genuinely empty record+ // `-z` appends after the last NUL, without eating a real path's own+ // leading or trailing whitespace.+ const rawIgnored = ignoredResult.stdout;+ const parsedIgnoredEntries: string[] = [];+ let totalIgnoredBytes = 0;+ let recordStart = 0;+ while (recordStart < rawIgnored.length) {+ const nulIndex = rawIgnored.indexOf("\0", recordStart);+ const recordEnd = nulIndex === -1 ? rawIgnored.length : nulIndex;+ const record = rawIgnored.slice(recordStart, recordEnd);+ recordStart = nulIndex === -1 ? rawIgnored.length : nulIndex + 1;++ const entry = record.replace(/\/+$/, "");+ if (entry.length === 0) {+ continue;+ }++ if (parsedIgnoredEntries.length + 1 > REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT) {+ throw new ReferencedSourceIgnoreScanLimitExceededError(+ `referenced project ignore scan found more than ${REFERENCED_SOURCE_IGNORE_MAX_ENTRY_COUNT} ignored entries`,+ );+ }+ totalIgnoredBytes += Buffer.byteLength(entry, "utf8");+ if (totalIgnoredBytes > REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES) {+ throw new ReferencedSourceIgnoreScanLimitExceededError(+ `referenced project ignore scan exceeded ${REFERENCED_SOURCE_IGNORE_MAX_TOTAL_BYTES} UTF-8 bytes of ignored paths`,+ );+ }+ parsedIgnoredEntries.push(entry);+ }++ // The list is bounded by both checks above, so sorting and re-relativizing+ // it here never costs more than the accepted bounds allow.+ const ignoredPaths = parsedIgnoredEntries.sort((left, right) => left.localeCompare(right));return { toplevel, ignoredPaths };}diff --git a/packages/adapter-utils/src/remote-managed-runtime.test.ts b/packages/adapter-utils/src/remote-managed-runtime.test.tsindex 35f4134830..89659bb643 100644--- a/packages/adapter-utils/src/remote-managed-runtime.test.ts+++ b/packages/adapter-utils/src/remote-managed-runtime.test.ts@@ -26,6 +26,8 @@ vi.mock("./ssh.js", () => ({}));import { prepareRemoteManagedRuntime } from "./remote-managed-runtime.js";+import { resolveReferencedSourceIgnore } from "./sandbox-managed-runtime.js";+import { setExpensiveWorkspaceGitExecutor } from "./git-workspace-sync.js";describe("remote managed runtime", () => {const cleanupDirs: string[] = [];@@ -262,4 +264,62 @@ describe("remote managed runtime", () => {expect(Object.keys(prepared.additionalSourceDirs)).toEqual(["healthy"]);expect(syncDirectoryToSsh).not.toHaveBeenCalledWith(expect.objectContaining({ localDir: failedDir }));});++ it("never leaks a raw absolute path into the remote per-project staging warning", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-remote-runtime-redact-"));+ cleanupDirs.push(rootDir);+ const workspaceDir = path.join(rootDir, "workspace");+ const failedDir = path.join(rootDir, "referenced-failed");+ await mkdir(workspaceDir, { recursive: true });+ await mkdir(failedDir, { recursive: true });++ // A raw toplevel string that makes `failedDir` a non-descendant, carrying+ // a sensitive absolute path — exactly the shape a caught Git diagnostic+ // could embed. `resolveReferencedSourceIgnore` is the single choke point+ // that must reduce it to the fixed category before anything downstream+ // (here, the remote lane's warning) ever sees it.+ const sensitivePath = "/srv/alice/project";+ let ignoreResolution;+ try {+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${sensitivePath}\n`, stderr: "" };+ }+ return { stdout: "", stderr: "" };+ });+ ignoreResolution = await resolveReferencedSourceIgnore(failedDir);+ } finally {+ setExpensiveWorkspaceGitExecutor(null);+ }+ expect(ignoreResolution.kind).toBe("failed");++ const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);+ try {+ await prepareRemoteManagedRuntime({+ spec: {+ host: "127.0.0.1",+ port: 2222,+ username: "fixture",+ remoteWorkspacePath: "/app",+ remoteCwd: "/app",+ privateKey: "PRIVATE KEY",+ knownHosts: "KNOWN HOSTS",+ strictHostKeyChecking: true,+ },+ runId: "run-redact",+ adapterKey: "codex",+ workspaceLocalDir: workspaceDir,+ workspaceRemoteDir: "/app",+ syncWorkspace: false,+ additionalSources: [{ localPath: failedDir, projectId: "failed", ignoreResolution }],+ });++ const warnedText = warnSpy.mock.calls.map((call) => call.join(" ")).join("\n");+ expect(warnedText).toContain("failed");+ expect(warnedText).not.toContain(sensitivePath);+ expect(warnedText).not.toContain(failedDir);+ } finally {+ warnSpy.mockRestore();+ }+ });});diff --git a/packages/adapter-utils/src/sandbox-managed-runtime.test.ts b/packages/adapter-utils/src/sandbox-managed-runtime.test.tsindex a889f6b34f..be36585a1e 100644--- a/packages/adapter-utils/src/sandbox-managed-runtime.test.ts+++ b/packages/adapter-utils/src/sandbox-managed-runtime.test.ts@@ -6,13 +6,19 @@ import path from "node:path";import { execFile as execFileCallback, spawn } from "node:child_process";import { promisify } from "node:util";import { afterEach, describe, expect, it, vi } from "vitest";-import { resetLocalGitIndexToHead } from "./git-workspace-sync.js";+import {+ resetLocalGitIndexToHead,+ runLocalGit,+ setExpensiveWorkspaceGitExecutor,+ WORKSPACE_GIT_SCAN_SATURATED_CODE,+} from "./git-workspace-sync.js";import {assertSyncOperationsConfined,escapeTarExcludeLiteral,mirrorDirectory,prepareSandboxManagedRuntime,+ REFERENCED_SOURCE_IGNORE_FAILURE_REASONS,resolveReferencedSourceIgnore,type PreparedSandboxManagedRuntime,type ReferencedSourceIgnoreResolution,@@ -1003,6 +1009,65 @@ describe("sandbox managed runtime", () => {expect(downloadMembers.some((entry) => entry.includes("/node_modules/") || entry.endsWith("/node_modules"))).toBe(false);});+ it("excludes an anchor-workspace ignored file whose name has leading and trailing whitespace from the staged tree", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-ignored-whitespace-"));+ cleanupDirs.push(rootDir);+ const workspaceLocalDir = path.join(rootDir, "workspace");+ const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");+ await initGitRepo(workspaceLocalDir);++ // A double-wildcard pattern avoids the separate rule that Git trims an+ // unescaped trailing space in a .gitignore PATTERN itself; the padding+ // under test lives in the matched FILE name, proving the anchor `splitNul`+ // parser keeps it instead of trimming it away and missing the exclude.+ const ignoredName = " ignored padded ";+ await writeFile(path.join(workspaceLocalDir, ".gitignore"), "*ignored*padded*\n", "utf8");+ await writeFile(path.join(workspaceLocalDir, ignoredName), "TOKEN=abc\n", "utf8");+ await writeFile(path.join(workspaceLocalDir, "kept.txt"), "kept\n", "utf8");++ const uploadedTars: { remotePath: string; bytes: Buffer }[] = [];+ const client: SandboxManagedRuntimeClient = {+ makeDir: async (remotePath) => {+ await mkdir(remotePath, { recursive: true });+ },+ writeFile: async (remotePath, bytes) => {+ await mkdir(path.dirname(remotePath), { recursive: true });+ const buffer = Buffer.from(bytes);+ if (remotePath.endsWith("-upload.tar")) uploadedTars.push({ remotePath, bytes: buffer });+ await writeFile(remotePath, buffer);+ },+ readFile: async (remotePath) => await readFile(remotePath),+ listFiles: async () => [],+ remove: async (remotePath) => {+ await rm(remotePath, { recursive: true, force: true });+ },+ run: async (command) => {+ await execFile("sh", ["-c", command], { maxBuffer: 32 * 1024 * 1024 });+ },+ };+ attachFallbackSyncIn(client);++ await prepareSandboxManagedRuntime({+ spec: {+ transport: "sandbox",+ provider: "test",+ sandboxId: "sandbox-1",+ remoteCwd: remoteWorkspaceDir,+ timeoutMs: 30_000,+ apiKey: null,+ },+ adapterKey: "test-adapter",+ client,+ workspaceLocalDir,+ });++ const workspaceUpload = uploadedTars.find((entry) => path.posix.basename(entry.remotePath) === "workspace-upload.tar");+ expect(workspaceUpload).toBeDefined();+ const members = await listTarMembers(rootDir, "ignored-whitespace-workspace-upload.tar", workspaceUpload!.bytes);+ expect(members).not.toContain(ignoredName);+ expect(members).toContain("kept.txt");+ });+it("builds workspace/asset tarballs without a './' self-entry (so untar does not chmod/utime an unowned target dir)", async () => {const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-tarself-"));cleanupDirs.push(rootDir);@@ -2460,8 +2525,272 @@ describe("sandbox managed runtime", () => {const resolution = await resolveReferencedSourceIgnore(repo);- expect(resolution.kind).toBe("failed");- expect((resolution as { reason: string }).reason.length).toBeGreaterThan(0);+ // The reason is the fixed category, never the caught error's own message+ // (which would embed `repo`, an absolute host path).+ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.scanFailed });+ });++ // Nadia's required probes: none of these three example absolute paths —+ // an ordinary POSIX path, a home directory, and a Windows path — may ever+ // reach `reason`, however they arrive (a caught Git error, or a raw+ // toplevel string that makes `localPath` a non-descendant).+ const SENSITIVE_PATH_PROBES = ["/srv/alice/project", "/home/alice/project", "C:\\Users\\alice\\project"];++ for (const sensitivePath of SENSITIVE_PATH_PROBES) {+ it(`redacts a caught Git error embedding ${sensitivePath} to the fixed category`, async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ignore-redact-caught-"));+ cleanupDirs.push(rootDir);+ const repo = path.join(rootDir, "repo");+ await initGitRepo(repo);+ try {+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ throw Object.assign(+ new Error(`fatal: unable to read tree object for ${sensitivePath}, pid 4242`),+ { stderr: `fatal: unable to read tree object for ${sensitivePath}, pid 4242` },+ );+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ const resolution = await resolveReferencedSourceIgnore(repo);++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.scanFailed });+ } finally {+ setExpensiveWorkspaceGitExecutor(null);+ }+ });++ it(`redacts a non-descendant toplevel embedding ${sensitivePath} to the fixed category`, async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ignore-redact-nondescendant-"));+ cleanupDirs.push(rootDir);+ const localPath = path.join(rootDir, "referenced");+ await mkdir(localPath, { recursive: true });+ try {+ // A toplevel string with no relation to `localPath` — the resolver+ // must treat it as a non-descendant and fail closed with the fixed+ // category, never a message built from `sensitivePath` or `localPath`.+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${sensitivePath}\n`, stderr: "" };+ }+ return { stdout: "", stderr: "" };+ });++ const resolution = await resolveReferencedSourceIgnore(localPath);++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.toplevelNotDescendant });+ } finally {+ setExpensiveWorkspaceGitExecutor(null);+ }+ });+ }++ it("fails closed with a fixed category when the parsed ignored-entry count exceeds the bound", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ignore-bound-count-"));+ cleanupDirs.push(rootDir);+ const repo = path.join(rootDir, "repo");+ await initGitRepo(repo);+ const overLimitCount = 10_001;+ const syntheticIgnored = `${Array.from({ length: overLimitCount }, (_, index) => `!! entry-${index}`).join("\0")}\0`;+ try {+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ return { stdout: syntheticIgnored, stderr: "" };+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ const resolution = await resolveReferencedSourceIgnore(repo);++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.limitExceeded });+ } finally {+ setExpensiveWorkspaceGitExecutor(null);+ }+ });++ it("fails closed with a fixed category when the total UTF-8 byte size of ignored paths exceeds the bound", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ignore-bound-bytes-"));+ cleanupDirs.push(rootDir);+ const repo = path.join(rootDir, "repo");+ await initGitRepo(repo);+ // One entry alone exceeds the 2 MiB bound, well under the entry-count bound.+ const hugeEntry = "a".repeat(3 * 1024 * 1024);+ const syntheticIgnored = `!! ${hugeEntry}\0`;+ try {+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.ignored_files") {+ return { stdout: syntheticIgnored, stderr: "" };+ }+ return await runLocalGit(input.localDir, [...input.args], {+ timeout: input.timeout,+ maxBuffer: input.maxBuffer,+ env: input.env,+ });+ });++ const resolution = await resolveReferencedSourceIgnore(repo);++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.limitExceeded });+ } finally {+ setExpensiveWorkspaceGitExecutor(null);+ }+ });++ it("stages no bytes for either a count-breach or a byte-breach project, and stages a healthy sibling", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ignore-bound-staging-"));+ cleanupDirs.push(rootDir);+ const localWorkspaceDir = path.join(rootDir, "local-workspace");+ const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");+ const healthyDir = path.join(rootDir, "referenced-healthy");+ const countBreachDir = path.join(rootDir, "referenced-count-breach");+ const byteBreachDir = path.join(rootDir, "referenced-byte-breach");+ await mkdir(localWorkspaceDir, { recursive: true });+ await mkdir(healthyDir, { recursive: true });+ await mkdir(countBreachDir, { recursive: true });+ await mkdir(byteBreachDir, { recursive: true });+ await writeFile(path.join(localWorkspaceDir, "README.md"), "anchor\n", "utf8");+ await writeFile(path.join(healthyDir, "notes.md"), "healthy\n", "utf8");+ await writeFile(path.join(countBreachDir, "should-never-ship.txt"), "must not stage\n", "utf8");+ await writeFile(path.join(byteBreachDir, "should-never-ship.txt"), "must not stage\n", "utf8");++ const countBreachReason = { kind: "failed" as const, reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.limitExceeded };+ const byteBreachReason = { kind: "failed" as const, reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.limitExceeded };++ const prepared = await prepareCommandManagedRuntime({+ runner: makeInlineSpawnRunner(),+ spec: { remoteCwd: remoteWorkspaceDir, timeoutMs: 30_000 },+ adapterKey: "test-adapter",+ workspaceLocalDir: localWorkspaceDir,+ additionalSources: [+ { localPath: healthyDir, projectId: "healthy", ignoreResolution: { kind: "other" } },+ { localPath: countBreachDir, projectId: "count-breach", ignoreResolution: countBreachReason },+ { localPath: byteBreachDir, projectId: "byte-breach", ignoreResolution: byteBreachReason },+ ],+ });++ expect(Object.keys(prepared.additionalSourceDirs).sort()).toEqual(["healthy"]);+ expect(prepared.additionalSourceFailures.map((failure) => failure.projectId).sort()).toEqual([+ "byte-breach",+ "count-breach",+ ]);+ const runtimeRootDir = path.posix.join(remoteWorkspaceDir, ".paperclip-runtime", "test-adapter");+ await expect(readFile(path.join(runtimeRootDir, "project-count-breach", "should-never-ship.txt"), "utf8")).rejects+ .toMatchObject({ code: "ENOENT" });+ await expect(readFile(path.join(runtimeRootDir, "project-byte-breach", "should-never-ship.txt"), "utf8")).rejects+ .toMatchObject({ code: "ENOENT" });+ });++ describe("saturation retry", () => {+ afterEach(() => {+ vi.useRealTimers();+ setExpensiveWorkspaceGitExecutor(null);+ });++ function throwSaturated(): never {+ throw Object.assign(+ new Error("Changed files are temporarily unavailable because the Git scan queue is full"),+ { code: WORKSPACE_GIT_SCAN_SATURATED_CODE },+ );+ }++ // Every case here synthesizes BOTH scan operations at the executor seam+ // instead of spawning real `git` — the property under test is the+ // retry's own timing and attempt count, and a fake-timer-driven test+ // must not also depend on a real child process's independent, real-time+ // completion. `toplevel` need not exist on disk: `resolveReferencedSourceIgnore`+ // falls back to a plain string compare when `fs.realpath` fails, and the+ // fixture path is used unchanged on both sides of that compare.+ const repo = "/fixture/referenced-project";++ it("retries a saturated scan up to two times and succeeds on the third attempt", async () => {+ let ignoredCallCount = 0;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${repo}\n`, stderr: "" };+ }+ ignoredCallCount += 1;+ if (ignoredCallCount <= 2) throwSaturated();+ return { stdout: "", stderr: "" };+ });++ vi.useFakeTimers();+ const resolutionPromise = resolveReferencedSourceIgnore(repo);+ // Bounded backoff: none before attempt 1, 1 s before attempt 2, 2 s+ // before attempt 3.+ await vi.advanceTimersByTimeAsync(1_000);+ await vi.advanceTimersByTimeAsync(2_000);+ const resolution = await resolutionPromise;++ expect(resolution).toEqual({ kind: "git", ignoredPaths: [] });+ expect(ignoredCallCount).toBe(3);+ });++ it("fails closed after three saturated attempts, with no further Git invocation", async () => {+ let ignoredCallCount = 0;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${repo}\n`, stderr: "" };+ }+ ignoredCallCount += 1;+ throwSaturated();+ });++ vi.useFakeTimers();+ const resolutionPromise = resolveReferencedSourceIgnore(repo);+ await vi.advanceTimersByTimeAsync(1_000);+ await vi.advanceTimersByTimeAsync(2_000);+ const resolution = await resolutionPromise;++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.scanFailed });+ // Three total attempts (the first plus two retries) — no fourth,+ // unscheduled invocation past the retry budget.+ expect(ignoredCallCount).toBe(3);+ });++ it("makes exactly one attempt and fails closed on a timeout, never retrying it", async () => {+ let ignoredCallCount = 0;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${repo}\n`, stderr: "" };+ }+ ignoredCallCount += 1;+ throw Object.assign(new Error("Workspace Git scan timed out after 8000ms"), {+ code: "workspace_git_scan_timeout",+ });+ });++ const resolution = await resolveReferencedSourceIgnore(repo);++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.scanFailed });+ expect(ignoredCallCount).toBe(1);+ });++ it("makes exactly one attempt and fails closed on an output-limit breach, never retrying it", async () => {+ let ignoredCallCount = 0;+ setExpensiveWorkspaceGitExecutor(async (input) => {+ if (input.operation === "referenced_source.toplevel") {+ return { stdout: `${repo}\n`, stderr: "" };+ }+ ignoredCallCount += 1;+ throw Object.assign(new Error("Workspace Git scan exceeded its output limit"), {+ code: "workspace_git_scan_output_limit",+ });+ });++ const resolution = await resolveReferencedSourceIgnore(repo);++ expect(resolution).toEqual({ kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.scanFailed });+ expect(ignoredCallCount).toBe(1);+ });});});diff --git a/packages/adapter-utils/src/sandbox-managed-runtime.ts b/packages/adapter-utils/src/sandbox-managed-runtime.tsindex bd5d5c5e71..d3de812500 100644--- a/packages/adapter-utils/src/sandbox-managed-runtime.ts+++ b/packages/adapter-utils/src/sandbox-managed-runtime.ts@@ -14,9 +14,11 @@ import {GIT_ARCHIVE_EXCLUDES,integrateImportedGitHead,readGitWorkspaceSnapshot,+ ReferencedSourceIgnoreScanLimitExceededError,readReferencedSourceGitIgnoredPaths,resetLocalGitIndexToHead,withShallowGitWorkspaceClone,+ WORKSPACE_GIT_SCAN_SATURATED_CODE,} from "./git-workspace-sync.js";import { captureDirectorySnapshot, mergeDirectoryWithBaseline } from "./workspace-restore-merge.js";import {@@ -147,16 +149,39 @@ export interface SandboxManagedRuntimeAsset {* `resolveReferencedSourceIgnore`).* - `other`: `localPath` is not a Git work tree. The staging path keeps* today's fixed heavy-directory excludes.- * - `failed`: the Git read failed, timed out, or returned output the- * resolver could not parse or safely re-relativize. The project is NOT- * staged (fail closed) — every site records it as a per-project failure- * instead of shipping it unfiltered.+ * - `failed`: the Git read failed, timed out, breached a parse bound, or+ * returned output the resolver could not safely re-relativize. The project+ * is NOT staged (fail closed) — every site records it as a per-project+ * failure instead of shipping it unfiltered. `reason` is always one of+ * {@link REFERENCED_SOURCE_IGNORE_FAILURE_REASONS} — never a raw Git or tar+ * diagnostic, an absolute host path, or a basename.*/export type ReferencedSourceIgnoreResolution =| { kind: "git"; ignoredPaths: string[] }| { kind: "other" }| { kind: "failed"; reason: string };+/**+ * The fixed, allowlisted failure categories a `failed`+ * {@link ReferencedSourceIgnoreResolution} reports as `reason`. This is the+ * ENTIRE vocabulary: no absolute host path, no basename, no opaque token, and+ * no raw Git or tar stderr ever reaches `reason` — only one of these three+ * stable strings, chosen once at the single construction point in+ * `resolveReferencedSourceIgnore`. A `failed` resolution always prevents+ * staging and is always re-resolved before its next use, so two different+ * underlying failures colliding on the same category (e.g. a timeout and a+ * malformed-output error both reporting `scanFailed`) never weakens the+ * fail-closed decision.+ */+export const REFERENCED_SOURCE_IGNORE_FAILURE_REASONS = {+ /** A Git read failed, timed out, was cancelled, or returned malformed output — including a saturated scan queue that never recovered after its retries. */+ scanFailed: "git-ignore-scan-failed",+ /** The parsed ignored-entry count or total UTF-8 byte size breached its bound (see `readReferencedSourceGitIgnoredPaths`). */+ limitExceeded: "git-ignore-scan-limit-exceeded",+ /** The referenced project's `localPath` is not a descendant of its own Git top level. */+ toplevelNotDescendant: "git-toplevel-not-descendant",+} as const;+/*** A referenced (additional) project to stage into the run sandbox as a plain,* read-only tree. `localPath` is the host checkout directory. Upstream code@@ -240,7 +265,7 @@ function relativizeUnderGitToplevel(input: { toplevel: string; localPath: string}/**- * Re-relativize root-relative ignored paths (as `git status --ignored`+ * Re-relativize root-relative ignored paths (as `readReferencedSourceGitIgnoredPaths`* reports them, from the repository toplevel) to `offset`, the position of* the referenced project's `localPath` under that toplevel. Keeps only the* entries that are `offset` itself or a descendant of it — an ignored path@@ -259,23 +284,78 @@ function reRelativizeIgnoredPathsToLocalPath(input: { ignoredPaths: string[]; of.filter(Boolean);}+/**+ * Bounded backoff before each retry of a saturated Git scan: none before the+ * first attempt, 1 second before the second, 2 seconds before the third. Three+ * total attempts (the first plus these two retries) is a liveness parameter,+ * not a security control — the retry only ever fires for the scheduler's+ * typed saturation code (see {@link isWorkspaceGitScanSaturatedError}).+ */+const REFERENCED_SOURCE_IGNORE_SCAN_RETRY_DELAYS_MS = [1_000, 2_000] as const;++async function delay(ms: number): Promise<void> {+ await new Promise<void>((resolve) => setTimeout(resolve, ms));+}++/**+ * True only when `error` carries the workspace Git scan scheduler's typed+ * saturation code on its `code` property. Matches the code alone, never+ * message text — a message can change wording without changing meaning, and+ * matching text would silently stop retrying (or start retrying the wrong+ * failure) the moment it did.+ */+function isWorkspaceGitScanSaturatedError(error: unknown): boolean {+ return (+ typeof error === "object" &&+ error !== null &&+ "code" in error &&+ (error as { code?: unknown }).code === WORKSPACE_GIT_SCAN_SATURATED_CODE+ );+}+/*** Resolve a referenced project's Git-ignored paths ONCE, before any staging* site runs. Called once per project (see `execute.ts`); the sandbox lane,* the SSH lane, and the content-signature walk all consume this one result,* so they can never apply a different exclusion set to the same project.*- * Fails closed: a Git read error, a timeout, malformed output, or a `localPath`- * that is not a plain descendant of its own Git toplevel all return `failed`,- * never an empty ignore list — an empty list means "resolved, nothing extra to- * exclude", which is a different claim than "the resolution did not run".+ * Fails closed: a Git read error, a timeout, malformed output, a parse-bound+ * breach, or a `localPath` that is not a plain descendant of its own Git+ * toplevel all return `failed`, never an empty ignore list — an empty list+ * means "resolved, nothing extra to exclude", which is a different claim than+ * "the resolution did not run".+ *+ * Retries ONLY a saturated scan queue (the shared workspace Git operation+ * scheduler rejecting before spawn because it is at capacity) — a liveness+ * condition, not an integrity one. Three attempts total, with the bounded+ * backoff in {@link REFERENCED_SOURCE_IGNORE_SCAN_RETRY_DELAYS_MS}, retried+ * through the same registered scheduler every time. No direct-spawn fallback+ * exists: bypassing the scheduler would defeat the process-wide concurrency+ * limit it enforces. Every other failure — timeout, cancellation, an output+ * limit, a permission error, malformed output, a real Git failure, or a bound+ * breach — makes exactly one attempt and fails closed immediately.*/export async function resolveReferencedSourceIgnore(localPath: string): Promise<ReferencedSourceIgnoreResolution> {- let scan: Awaited<ReturnType<typeof readReferencedSourceGitIgnoredPaths>>;- try {- scan = await readReferencedSourceGitIgnoredPaths(localPath);- } catch (error) {- return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };+ let scan: Awaited<ReturnType<typeof readReferencedSourceGitIgnoredPaths>> = null;+ let failureReason: string | null = null;+ for (let attempt = 0; attempt <= REFERENCED_SOURCE_IGNORE_SCAN_RETRY_DELAYS_MS.length; attempt += 1) {+ try {+ scan = await readReferencedSourceGitIgnoredPaths(localPath);+ failureReason = null;+ break;+ } catch (error) {+ failureReason = error instanceof ReferencedSourceIgnoreScanLimitExceededError+ ? REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.limitExceeded+ : REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.scanFailed;+ const isLastAttempt = attempt === REFERENCED_SOURCE_IGNORE_SCAN_RETRY_DELAYS_MS.length;+ if (isLastAttempt || !isWorkspaceGitScanSaturatedError(error)) {+ break;+ }+ await delay(REFERENCED_SOURCE_IGNORE_SCAN_RETRY_DELAYS_MS[attempt]!);+ }+ }+ if (failureReason !== null) {+ return { kind: "failed", reason: failureReason };}if (!scan) {return { kind: "other" };@@ -285,10 +365,7 @@ export async function resolveReferencedSourceIgnore(localPath: string): Promise<localPath: await physicalPath(localPath),});if (offset === null) {- return {- kind: "failed",- reason: `referenced project path is not a descendant of its own Git top level: ${localPath} under ${scan.toplevel}`,- };+ return { kind: "failed", reason: REFERENCED_SOURCE_IGNORE_FAILURE_REASONS.toplevelNotDescendant };}return {kind: "git",diff --git a/server/src/services/workspace-git-operation-scheduler.test.ts b/server/src/services/workspace-git-operation-scheduler.test.tsindex abd9a36930..72fbb352a4 100644--- a/server/src/services/workspace-git-operation-scheduler.test.ts+++ b/server/src/services/workspace-git-operation-scheduler.test.ts@@ -9,6 +9,7 @@ import {workspaceGitSchedulerOptionsFromEnv,type WorkspaceGitRunner,} from "./workspace-git-operation-scheduler.js";+import { WORKSPACE_GIT_SCAN_SATURATED_CODE } from "@paperclipai/adapter-utils/git-workspace-sync";const tempPaths: string[] = [];@@ -429,3 +430,13 @@ describe("WorkspaceGitOperationScheduler", () => {expect(scheduler.snapshot()).toMatchObject({ activeCount: 0, queuedCount: 0, inFlightCount: 0 });});});++describe("WORKSPACE_GIT_SCAN_SATURATED_CODE parity", () => {+ it("stays equal to WORKSPACE_GIT_SCAN_ERROR_CODES.saturated", () => {+ // `adapter-utils` cannot import this module (the reverse direction is+ // allowed, not this one), so `resolveReferencedSourceIgnore` declares its+ // own copy of the saturation code to key its retry off. This test is the+ // one place both literals meet, so the two copies cannot drift apart.+ expect(WORKSPACE_GIT_SCAN_SATURATED_CODE).toBe(WORKSPACE_GIT_SCAN_ERROR_CODES.saturated);+ });+});