harnery 0.28.0 → 0.30.0

package/src/core/workflow/spawn-failure.ts

@@ -26,3 +26,43 @@ export function vendorFailureText(
   const combined = parts.join("\n");
   return combined.length > maxChars ? `…${combined.slice(-maxChars)}` : combined;
 }
+
+// A 429 or 5xx status, but only where it sits in HTTP-status CONTEXT — not any
+// digits that merely happen to fall in that range. A bare-number match treats a
+// line number ("at line 500"), an item count ("got 429 items"), or a duration
+// ("after 502 seconds") as an upstream refusal, which wrongly withholds a charge
+// for a failure that was entirely our code. Three recognized shapes:
+//   1. after an "HTTP" label:  "HTTP 429", "HTTP/1.1 503 Service Unavailable"
+//   2. after a "status" label: "status 500", "status: 429", "status code 502"
+//   3. a bare status line:     "503 Service Unavailable" (code at line start,
+//      then a reason phrase) — the classic "<code> <Reason-Phrase>" shape.
+// The trailing `(?![0-9])` and the label/line-start anchors also keep a status
+// embedded in a longer number ("4295"/"5031") out. All 5xx are server-side; 429
+// is the only 4xx that means "reached and refused, retry later".
+const STATUS = "(?:429|5[0-9]{2})";
+const UPSTREAM_STATUS = new RegExp(
+  `(?:\\bHTTP\\b[/0-9. ]*|\\bstatus(?:\\s*code)?\\b[\\s:=]*)${STATUS}(?![0-9])` +
+    `|(?:^|\\n)\\s*${STATUS}\\s+[A-Za-z]`,
+  "i",
+);
+// Explicit vendor wording for the same conditions when a numeric status is
+// absent. Deliberately short — see isUpstreamFailureText.
+const UPSTREAM_PHRASES =
+  /circuit[ _-]?open|service unavailable|too many requests|rate[ _-]?limit|overloaded|bad gateway|gateway time-?out|internal server error/i;
+
+/**
+ * Whether failure text names an UPSTREAM refusal — the vendor was reached and
+ * refused (a 5xx/429 status or circuit-open wording), as opposed to a work
+ * failure (the model ran and produced a wrong or incomplete result).
+ *
+ * There is no structural upstream signal the way ENOENT structurally marks a
+ * missing binary, so this is the one text match in the classifier. It is kept
+ * SHORT and documented on purpose: a per-vendor regex zoo would rot, and a
+ * false positive here wrongly withholds a charge, so both the phrase list and
+ * the numeric match stay tight — the number must sit in HTTP-status context, not
+ * merely fall in the 429/5xx range. Anything it does not match falls through to
+ * a charged work failure.
+ */
+export function isUpstreamFailureText(text: string): boolean {
+  return UPSTREAM_STATUS.test(text) || UPSTREAM_PHRASES.test(text);
+}

package/src/core/workflow/types.ts

@@ -99,6 +99,11 @@ export interface WorkflowAgentProof {
   session_id?: string;
   result?: ResultDigest;
   error?: string;
+  /** Set on a failed agent whose spawn was classified uninformative about the
+   * work (ADR 0046): environment (binary absent) or upstream (vendor refused).
+   * Absent ⇒ a work failure. Recorded even when a script's parallel() swallows
+   * the rejection, so the run-level class can still be derived from proof. */
+  class?: SpawnFailureClass;
 }
 
 export interface WorkflowRepoSnapshot {
@@ -186,6 +191,12 @@ export interface WorkflowProof {
     objective?: string;
     error?: string;
     result?: ResultDigest;
+    /** Set on a failed run that was uninformative about the work (ADR 0046):
+     * environment or upstream. Derived from the agents' classes when no agent
+     * produced a result; absent ⇒ the attempt is charged as before. The durable
+     * work projection reads this to decide charging, stopping, and the
+     * uncharged-attempt bound. */
+    class?: SpawnFailureClass;
   };
   acceptance: {
     criteria: AcceptanceResult[];
@@ -298,6 +309,19 @@ export interface WorkflowSpecialistProfile {
   maxTurns?: number;
 }
 
+/**
+ * Why a failed run was uninformative about the work (ADR 0046). Absent means
+ * the attempt produced information about the work (or succeeded), which is the
+ * default and is charged against the attempt budget exactly as before.
+ *
+ * - `environment`: the run never started — a precondition was missing (the
+ *   vendor binary was absent). Uncharged AND not retried: retrying an unchanged
+ *   environment cannot help, so the work item stops and names the precondition.
+ * - `upstream`: the vendor was reached and refused (5xx, 429, circuit open).
+ *   Uncharged, but retry stays available (bounded by max_uncharged_attempts).
+ */
+export type SpawnFailureClass = "environment" | "upstream";
+
 /** What a spawn adapter returns for one subagent run. */
 export interface SpawnResult {
   ok: boolean;
@@ -309,6 +333,9 @@ export interface SpawnResult {
   durationMs: number;
   /** Populated when ok=false. */
   error?: string;
+  /** Set when ok=false and the failure was positively identified as
+   * uninformative about the work. Absent ⇒ a work failure (charged). */
+  class?: SpawnFailureClass;
 }
 
 export interface SpawnRequest {

package/src/core/workflow/workspaces/local-git.ts

@@ -123,16 +123,26 @@ export async function probe(
   if (input.writable_roots.length === 0) {
     unsupported.push(reason("writable_roots_required", "explicit writable roots are required"));
   }
-  for (const root of input.writable_roots) {
+  // Allocation always selects writable_roots[0] (validateRequest pins the selected root
+  // to it), so probe's authority-coverage verdict must be judged against that same root.
+  let selectedRoot: ValidatedRoot | undefined;
+  input.writable_roots.forEach((root, index) => {
     try {
-      validateConfiguredRoot(root);
+      const validated = validateConfiguredRoot(root);
+      if (index === 0) selectedRoot = validated;
     } catch (error) {
       unsupported.push(reason("writable_root_invalid", (error as Error).message));
     }
-  }
+  });
   if (version.ok) {
     try {
-      inspectSourceRepository(input.requested_cwd);
+      const repo = inspectSourceRepository(input.requested_cwd);
+      if (selectedRoot) {
+        const outside = describeAuthorityOutsideRoot(repo, selectedRoot.realpath);
+        if (outside) {
+          unsupported.push(reason("repository_authority_outside_writable_root", outside));
+        }
+      }
     } catch (error) {
       unsupported.push(reason("repository_unsupported", (error as Error).message));
     }
@@ -209,12 +219,8 @@ async function allocate(
     repo.commonDir.realpath,
     "Git common directory",
   );
-  if (
-    !containsPath(root.realpath, repo.sourceRoot.realpath) ||
-    !containsPath(root.realpath, repo.commonDir.realpath)
-  ) {
-    throw new Error("source repository and Git common dir must be inside the writable root");
-  }
+  const authorityOutside = describeAuthorityOutsideRoot(repo, root.realpath);
+  if (authorityOutside) throw new Error(authorityOutside);
   const workspaceRoot = candidateUnderRoot(root, ["harnery-workspaces", bindingId]);
   const activeRoot = resolve(workspaceRoot, repo.requestedRelativePath);
   if (!containsPath(workspaceRoot, activeRoot)) {
@@ -1192,6 +1198,25 @@ async function applyIntegrationUnderLease(
   }
   revalidateClaimResources(claim, validateConfiguredRoot(plan.binding.writable_root.configured));
   inspectIntegrationTarget(current.target_root, plan.binding);
+  // The fast-forward moves the target branch ref, which for a submodule or linked
+  // worktree lives in the common directory outside the checkout tree. allowed_paths is
+  // the real write authority (allocate and cleanup already gate the common directory on
+  // it), so re-authorize both the target checkout and its common directory here rather
+  // than trusting containment alone.
+  const applyCommonDir = plan.binding.repository?.common_dir.realpath;
+  if (!applyCommonDir) {
+    throw new Error("integration binding is missing Git common-dir authority");
+  }
+  assertAllowedPathAuthority(
+    claim.request.allowed_paths,
+    current.target_root,
+    "integration target path",
+  );
+  assertAllowedPathAuthority(
+    claim.request.allowed_paths,
+    applyCommonDir,
+    "integration Git common directory",
+  );
   git(current.target_root, ["merge", "--ff-only", expected.source_commit]);
   const finalCommit = git(current.target_root, ["rev-parse", "HEAD"]);
   const finalTree = git(current.target_root, ["rev-parse", "HEAD^{tree}"]);
@@ -1287,20 +1312,17 @@ function inspectSourceRepository(cwd: string): {
   if (!containsPath(sourceRoot, requestedCwd.realpath)) {
     throw new Error("requested working directory is outside the resolved Git worktree");
   }
-  if (lstatSync(join(sourceRoot, ".git")).isSymbolicLink()) {
-    throw new Error("symlink Git directories are unsupported");
-  }
-  if (!lstatSync(join(sourceRoot, ".git")).isDirectory()) {
-    throw new Error("linked worktree and submodule source repositories are unsupported");
-  }
-  const requestedGitDir = realpathSync(join(sourceRoot, ".git"));
+  const pointedGitDir = resolveGitDirPointer(sourceRoot);
   const gitDir = realpathSync(resolve(sourceRoot, git(sourceRoot, ["rev-parse", "--git-dir"])));
   const commonDir = realpathSync(
     resolve(sourceRoot, git(sourceRoot, ["rev-parse", "--git-common-dir"])),
   );
-  if (gitDir !== requestedGitDir || commonDir !== requestedGitDir) {
+  if (pointedGitDir !== gitDir) {
     throw new Error("resolved Git authority does not match the requested checkout");
   }
+  if (!containsPath(commonDir, gitDir)) {
+    throw new Error("resolved Git directory is not inside its common directory");
+  }
   const branch = gitMaybe(sourceRoot, ["symbolic-ref", "-q", "--short", "HEAD"]);
   if (!branch.ok || !branch.out) throw new Error("detached integration targets are unsupported");
   const targetRef = `refs/heads/${branch.out}`;
@@ -1321,6 +1343,47 @@ function inspectSourceRepository(cwd: string): {
   };
 }
 
+// Resolve the `.git` entry at a checkout root to the real Git directory it names,
+// without trusting the ambient environment. `.git` is a real directory in a plain
+// checkout, and a `gitdir:` pointer file in a linked worktree, submodule, or
+// worktree-of-a-submodule. A symlink is refused: the identity model pins a path to a
+// device and inode, and a symlink lets the target move under a pinned pointer.
+//
+// The caller cross-checks the result against `rev-parse --git-dir`. That is a
+// consistency assertion, not spoof detection: Git honours a `gitdir:` pointer, so a
+// pointer aimed at an unrelated repository agrees with `rev-parse` and is accepted.
+// It cannot be otherwise, because a doctored pointer and a submodule's pointer are
+// the same construct. What the equality buys is that this resolution and Git's own
+// never silently diverge, which is defence in depth over the `GIT_*` stripping in
+// `isolatedGitEnvironment`. The real authority check is containment plus
+// `allowed_paths` on the resolved common directory.
+function resolveGitDirPointer(sourceRoot: string): string {
+  const dotGit = join(sourceRoot, ".git");
+  let stats: ReturnType<typeof lstatSync>;
+  try {
+    stats = lstatSync(dotGit);
+  } catch {
+    throw new Error("requested checkout has no .git entry");
+  }
+  if (stats.isSymbolicLink()) {
+    throw new Error("symlink Git directories are unsupported");
+  }
+  if (stats.isDirectory()) {
+    return realpathSync(dotGit);
+  }
+  if (!stats.isFile()) {
+    throw new Error(".git must be a directory or a gitdir pointer file");
+  }
+  const pointer = readFileSync(dotGit, "utf8").split(/\r?\n/, 1)[0]?.trim() ?? "";
+  const prefix = "gitdir:";
+  if (!pointer.startsWith(prefix)) {
+    throw new Error(".git file is not a gitdir pointer");
+  }
+  const target = pointer.slice(prefix.length).trim();
+  if (!target) throw new Error(".git gitdir pointer is empty");
+  return realpathSync(resolve(sourceRoot, target));
+}
+
 function inspectFrozenSourceAuthority(
   sourceRoot: GitRepositoryBinding["source_root"],
   commonDir: GitRepositoryBinding["common_dir"],
@@ -1680,6 +1743,28 @@ function validFrozenFilesystemPath(
   );
 }
 
+// Explain, in the caller's terms, why a checkout's Git authority falls outside a
+// writable root — naming the offending path so a submodule or linked-worktree user
+// who declared only the inner checkout knows exactly what to widen. Returns undefined
+// when both the source checkout and its common directory are inside the root.
+function describeAuthorityOutsideRoot(
+  repo: ReturnType<typeof inspectSourceRepository>,
+  rootRealpath: string,
+): string | undefined {
+  if (!containsPath(rootRealpath, repo.commonDir.realpath)) {
+    return (
+      `Git keeps this checkout's administrative files in ${repo.commonDir.realpath}, ` +
+      `which is outside the writable root ${rootRealpath}. Linked-worktree and submodule ` +
+      `checkouts keep their Git authority in the enclosing repository, and allocating a ` +
+      `worktree writes there; declare that repository (or a parent of it) as the writable root.`
+    );
+  }
+  if (!containsPath(rootRealpath, repo.sourceRoot.realpath)) {
+    return `the source checkout ${repo.sourceRoot.realpath} is outside the writable root ${rootRealpath}`;
+  }
+  return undefined;
+}
+
 function assertAllowedPathAuthority(
   allowedPaths: WorkspaceAllocationRequest["allowed_paths"],
   candidate: string,
@@ -1783,10 +1868,15 @@ function capabilityDigestForClaim(claim: WorkspaceClaim): string {
 function acquireRepositoryLease(coordRoot: string, claim: WorkspaceClaim): () => void {
   const leaseDir = join(resolve(coordRoot), ".harnery", "workspaces", PROVIDER_ID, ".leases");
   mkdirSync(leaseDir, { recursive: true, mode: 0o700 });
-  const key = stableDigest({
-    common: claim.repository.common_dir.identity,
-    root: claim.writable_root.identity,
-  });
+  // Mutual exclusion keys on the Git common directory alone. `git worktree add`,
+  // `prune`, and the shared-`config` migration all write to the common directory's
+  // administrative area, and once worktrees and submodules are allowed, several
+  // distinct source checkouts (a superproject and its linked worktrees; a submodule
+  // and a worktree of it) share one common directory under different — possibly
+  // nested — writable roots. Including the writable root in the key would hand those
+  // agents different locks and let their admin-area writes race. The writable root
+  // stays in the lease metadata for diagnostics, not in the exclusion key.
+  const key = stableDigest({ common: claim.repository.common_dir.identity });
   return acquireLease(coordRoot, join(leaseDir, `repository-${key}.lock`), claim, "repository");
 }
 

package/src/lib/exec.ts

@@ -17,6 +17,13 @@ export interface ExecResult {
    * child that handles the signal cleanly still exits 0, so the exit code alone
    * cannot distinguish a kill from an ordinary finish. */
   timedOut?: boolean;
+  /** The `code` from a spawn-level failure (`proc` "error" event), e.g.
+   * "ENOENT" when the binary is absent. Absent for an ordinary process exit.
+   * We collapse such failures to exitCode 127 so callers' exit-code branches
+   * still fire, but a shell can legitimately exit 127 too; only this field
+   * distinguishes "the binary was never there" from "the process ran and exited
+   * 127". The process that knows reports it (as ADR 0044 did for `timedOut`). */
+  spawnErrno?: string;
 }
 
 export interface ExecOpts {
@@ -56,7 +63,7 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
       proc.kill();
     }, timeout);
 
-    const finish = (exitCode: number, errOverride?: string): void => {
+    const finish = (exitCode: number, errOverride?: string, spawnErrno?: string): void => {
       clearTimeout(timer);
       const stdout = Buffer.concat(out).toString("utf-8");
       const stderr = errOverride ?? Buffer.concat(err).toString("utf-8");
@@ -66,13 +73,16 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
         stderr: shouldTrim ? stderr.trim() : stderr.replace(/\n$/, ""),
         exitCode,
         ...(timedOut ? { timedOut: true } : {}),
+        ...(spawnErrno ? { spawnErrno } : {}),
       });
     };
 
     // ENOENT (binary not found) and similar spawn failures surface here rather
     // than throwing: resolve with 127 + the message so callers' exitCode
-    // branches handle it instead of crashing on an unhandled rejection.
-    proc.on("error", (e: Error) => finish(127, e.message));
+    // branches handle it instead of crashing on an unhandled rejection. The
+    // errno (e.g. "ENOENT") is carried through so a real missing binary is
+    // distinguishable from a shell that merely exited 127.
+    proc.on("error", (e: Error) => finish(127, e.message, (e as NodeJS.ErrnoException).code));
     proc.on("close", (code) => finish(code ?? 1));
   });
 }