@cat-factory/executor-harness 1.100.0 → 1.102.0

package/dist/agent.js

@@ -9,7 +9,8 @@ import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './re
 import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, unmergedPaths, } from './git.js';
 import { inferVcsProvider, openPullRequest } from './vcs-api.js';
 import { applyPrDescription } from './pr-description.js';
-import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
+import { makeDirClaimer } from './checkout-dir.js';
+import { noChangesReason, runCodingAgent, runMultiRepoCoding } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
 import { agentCapabilities, mergeEffort } from './agent-shared.js';

package/dist/checkout-dir.d.ts

@@ -0,0 +1,33 @@
+import type { RepoSpec } from './job.js';
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export declare function safeDirSegment(value: string): string;
+/**
+ * A short deterministic digest of the EXACT `owner` / `name` pair, before sanitisation. FNV-1a
+ * over `owner\0name`; the NUL separator makes it a digest of the PAIR rather than of a
+ * concatenation, so `('a', 'bc')` and `('ab', 'c')` cannot share one. Hand-rolled rather than
+ * taken from `node:crypto` because the backend needs the identical function and runs it in
+ * workerd as well as on Node.
+ *
+ * MUST stay byte-identical to the backend's `checkoutDirDigest`
+ * (`@cat-factory/server`, `agents/harnessContract.ts`); see {@link makeDirClaimer}.
+ */
+export declare function checkoutDirDigest(owner: string, name: string): string;
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. A pure function of the pair (`owner__name__digest`), which is
+ * what lets this and the backend compute it independently with no shared ordering or state. Kept
+ * as a factory so the coding + read-only explore fan-outs share ONE scheme, and it MUST stay
+ * byte-identical to the backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in
+ * `@cat-factory/server`, which names this exact directory in the agent's prompt: the two are
+ * computed independently, so a divergent rule would point the agent at a directory that does not
+ * exist.
+ *
+ * The readable `owner__name` prefix does not identify a repo on its own, which is why the digest
+ * is there. {@link safeDirSegment} folds a whole class of characters onto `-`, so a GitLab
+ * namespace path `grp/sub` and a group literally named `grp-sub` sanitise alike; and the `__`
+ * join is ambiguous once a segment may contain `_`, which GitHub owners cannot but GitLab
+ * namespace paths can, so `('a__b', 'c')` and `('a', 'b__c')` both read as `a__b__c`. Either
+ * collision puts two legs on one directory, and the second one's clone then fails against a
+ * directory the first already filled, killing the run in the clone phase naming neither repo.
+ */
+export declare function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string;

package/dist/checkout-dir.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// The HARNESS half of the sibling-checkout-directory contract.
+//
+// The harness CREATES these directories; `@cat-factory/server`'s `agents/harnessContract.ts`
+// NAMES them in the agent's prompt. The image builds from this `src/` plus typescript and may
+// depend on no workspace package, so the two halves are computed INDEPENDENTLY and pinned against
+// each other by `test/harness-contract.conformity.test.ts`. Extracted out of `coding-agent.ts` so
+// the pairing sits in one small module per side rather than buried in the agent runner: the whole
+// point of the pairing is that a reader can see both halves at once.
+// ---------------------------------------------------------------------------
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export function safeDirSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';
+}
+/**
+ * A short deterministic digest of the EXACT `owner` / `name` pair, before sanitisation. FNV-1a
+ * over `owner\0name`; the NUL separator makes it a digest of the PAIR rather than of a
+ * concatenation, so `('a', 'bc')` and `('ab', 'c')` cannot share one. Hand-rolled rather than
+ * taken from `node:crypto` because the backend needs the identical function and runs it in
+ * workerd as well as on Node.
+ *
+ * MUST stay byte-identical to the backend's `checkoutDirDigest`
+ * (`@cat-factory/server`, `agents/harnessContract.ts`); see {@link makeDirClaimer}.
+ */
+export function checkoutDirDigest(owner, name) {
+    const input = `${owner}\u0000${name}`;
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        // The FNV prime (16777619) as shifts, with `>>> 0` folding the result back to uint32 every
+        // step so the arithmetic never drifts into float range and diverges between engines.
+        hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash.toString(36).padStart(7, '0');
+}
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. A pure function of the pair (`owner__name__digest`), which is
+ * what lets this and the backend compute it independently with no shared ordering or state. Kept
+ * as a factory so the coding + read-only explore fan-outs share ONE scheme, and it MUST stay
+ * byte-identical to the backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in
+ * `@cat-factory/server`, which names this exact directory in the agent's prompt: the two are
+ * computed independently, so a divergent rule would point the agent at a directory that does not
+ * exist.
+ *
+ * The readable `owner__name` prefix does not identify a repo on its own, which is why the digest
+ * is there. {@link safeDirSegment} folds a whole class of characters onto `-`, so a GitLab
+ * namespace path `grp/sub` and a group literally named `grp-sub` sanitise alike; and the `__`
+ * join is ambiguous once a segment may contain `_`, which GitHub owners cannot but GitLab
+ * namespace paths can, so `('a__b', 'c')` and `('a', 'b__c')` both read as `a__b__c`. Either
+ * collision puts two legs on one directory, and the second one's clone then fails against a
+ * directory the first already filled, killing the run in the clone phase naming neither repo.
+ */
+export function makeDirClaimer() {
+    return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}__${checkoutDirDigest(repo.owner, repo.name)}`;
+}

package/dist/coding-agent.d.ts

@@ -219,19 +219,6 @@ export declare function runRalphValidation(repoDir: string, cwd: string, validat
     iteration?: number;
     headSha?: string;
 }>;
-/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
-export declare function safeDirSegment(value: string): string;
-/**
- * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
- * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
- * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
- * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
- * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
- * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
- * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
- * independently, so a divergent rule would point the agent at a directory that does not exist.
- */
-export declare function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string;
 /**
  * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
  * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at

package/dist/coding-agent.js

@@ -1,6 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runCapturedCommand } from './captured-command.js';
+import { makeDirClaimer } from './checkout-dir.js';
 import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
@@ -676,23 +677,6 @@ export async function runRalphValidation(repoDir, cwd, validation, logger, opts)
         ...(headSha ? { headSha } : {}),
     };
 }
-/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
-export function safeDirSegment(value) {
-    return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';
-}
-/**
- * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
- * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
- * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
- * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
- * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
- * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
- * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
- * independently, so a divergent rule would point the agent at a directory that does not exist.
- */
-export function makeDirClaimer() {
-    return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}`;
-}
 /**
  * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
  * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at
@@ -711,8 +695,9 @@ export async function runMultiRepoCoding(job, opts = {}) {
     const peers = job.peerRepos ?? [];
     const references = job.referenceRepos ?? [];
     const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
-    // matching the backend prompt's `siblingCheckoutDir`), shared with the read-only explore fan-out.
+    // Assign the sibling directory per repo via the shared deterministic allocator
+    // (`owner__name__digest`, matching the backend prompt's `siblingCheckoutDir`), shared with the
+    // read-only explore fan-out.
     const claimDir = makeDirClaimer();
     const legs = [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.100.0",
+  "version": "1.102.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.13.0",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.272.0",
-    "@cat-factory/server": "0.252.0",
-    "@cat-factory/spend": "0.15.40"
+    "@cat-factory/kernel": "0.273.0",
+    "@cat-factory/server": "0.253.0",
+    "@cat-factory/spend": "0.15.41"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -29,12 +29,8 @@ import {
 import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.js'
 import { applyPrDescription } from './pr-description.js'
-import {
-  makeDirClaimer,
-  noChangesReason,
-  runCodingAgent,
-  runMultiRepoCoding,
-} from './coding-agent.js'
+import { makeDirClaimer } from './checkout-dir.js'
+import { noChangesReason, runCodingAgent, runMultiRepoCoding } from './coding-agent.js'
 import { validationFailureMessage } from './validation-checks.js'
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js'
 import { agentCapabilities, mergeEffort } from './agent-shared.js'

package/src/checkout-dir.ts

@@ -0,0 +1,62 @@
+import type { RepoSpec } from './job.js'
+
+// ---------------------------------------------------------------------------
+// The HARNESS half of the sibling-checkout-directory contract.
+//
+// The harness CREATES these directories; `@cat-factory/server`'s `agents/harnessContract.ts`
+// NAMES them in the agent's prompt. The image builds from this `src/` plus typescript and may
+// depend on no workspace package, so the two halves are computed INDEPENDENTLY and pinned against
+// each other by `test/harness-contract.conformity.test.ts`. Extracted out of `coding-agent.ts` so
+// the pairing sits in one small module per side rather than buried in the agent runner: the whole
+// point of the pairing is that a reader can see both halves at once.
+// ---------------------------------------------------------------------------
+
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export function safeDirSegment(value: string): string {
+  return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_'
+}
+
+/**
+ * A short deterministic digest of the EXACT `owner` / `name` pair, before sanitisation. FNV-1a
+ * over `owner\0name`; the NUL separator makes it a digest of the PAIR rather than of a
+ * concatenation, so `('a', 'bc')` and `('ab', 'c')` cannot share one. Hand-rolled rather than
+ * taken from `node:crypto` because the backend needs the identical function and runs it in
+ * workerd as well as on Node.
+ *
+ * MUST stay byte-identical to the backend's `checkoutDirDigest`
+ * (`@cat-factory/server`, `agents/harnessContract.ts`); see {@link makeDirClaimer}.
+ */
+export function checkoutDirDigest(owner: string, name: string): string {
+  const input = `${owner}\u0000${name}`
+  let hash = 0x811c9dc5
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i)
+    // The FNV prime (16777619) as shifts, with `>>> 0` folding the result back to uint32 every
+    // step so the arithmetic never drifts into float range and diverges between engines.
+    hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0
+  }
+  return hash.toString(36).padStart(7, '0')
+}
+
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. A pure function of the pair (`owner__name__digest`), which is
+ * what lets this and the backend compute it independently with no shared ordering or state. Kept
+ * as a factory so the coding + read-only explore fan-outs share ONE scheme, and it MUST stay
+ * byte-identical to the backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in
+ * `@cat-factory/server`, which names this exact directory in the agent's prompt: the two are
+ * computed independently, so a divergent rule would point the agent at a directory that does not
+ * exist.
+ *
+ * The readable `owner__name` prefix does not identify a repo on its own, which is why the digest
+ * is there. {@link safeDirSegment} folds a whole class of characters onto `-`, so a GitLab
+ * namespace path `grp/sub` and a group literally named `grp-sub` sanitise alike; and the `__`
+ * join is ambiguous once a segment may contain `_`, which GitHub owners cannot but GitLab
+ * namespace paths can, so `('a__b', 'c')` and `('a', 'b__c')` both read as `a__b__c`. Either
+ * collision puts two legs on one directory, and the second one's clone then fails against a
+ * directory the first already filled, killing the run in the clone phase naming neither repo.
+ */
+export function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string {
+  return (repo) =>
+    `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}__${checkoutDirDigest(repo.owner, repo.name)}`
+}

package/src/coding-agent.ts

@@ -1,6 +1,7 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { runCapturedCommand } from './captured-command.js'
+import { makeDirClaimer } from './checkout-dir.js'
 import type {
   AgentJob,
   AgentResult,
@@ -1018,25 +1019,6 @@ export async function runRalphValidation(
   }
 }
 
-/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
-export function safeDirSegment(value: string): string {
-  return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_'
-}
-
-/**
- * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
- * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
- * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
- * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
- * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
- * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
- * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
- * independently, so a divergent rule would point the agent at a directory that does not exist.
- */
-export function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string {
-  return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}`
-}
-
 /** One repository participating in a multi-repo run: where to clone it + what to do after. */
 interface RepoLeg {
   repo: RepoSpec
@@ -1086,8 +1068,9 @@ export async function runMultiRepoCoding(
   const references: ReferenceRepoSpec[] = job.referenceRepos ?? []
   const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch
 
-  // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
-  // matching the backend prompt's `siblingCheckoutDir`), shared with the read-only explore fan-out.
+  // Assign the sibling directory per repo via the shared deterministic allocator
+  // (`owner__name__digest`, matching the backend prompt's `siblingCheckoutDir`), shared with the
+  // read-only explore fan-out.
   const claimDir = makeDirClaimer()
   const legs: RepoLeg[] = [
     {