@gethmy/harness 1.3.0 → 1.4.0

package/dist/cli.js

@@ -473,6 +473,13 @@ var init_playbookStage = __esm(() => {
 
 // ../harmony-shared/dist/projectTemplates.js
 var init_projectTemplates = () => {};
+
+// ../harmony-shared/dist/realtimeChannel.js
+var inFlightDetach;
+var init_realtimeChannel = __esm(() => {
+  init_logger();
+  inFlightDetach = new WeakMap;
+});
 // ../harmony-shared/dist/reviewTools.js
 var REVIEW_DISALLOWED_TOOLS;
 var init_reviewTools = __esm(() => {
@@ -514,6 +521,7 @@ var init_dist = __esm(() => {
   init_playbookCatalog();
   init_playbookStage();
   init_projectTemplates();
+  init_realtimeChannel();
   init_reviewTools();
   init_stageHandoff();
   init_types();

package/dist/index.js

@@ -556,6 +556,13 @@ var init_playbookStage = __esm(() => {
 
 // ../harmony-shared/dist/projectTemplates.js
 var init_projectTemplates = () => {};
+
+// ../harmony-shared/dist/realtimeChannel.js
+var inFlightDetach;
+var init_realtimeChannel = __esm(() => {
+  init_logger();
+  inFlightDetach = new WeakMap;
+});
 // ../harmony-shared/dist/reviewTools.js
 var REVIEW_DISALLOWED_TOOLS;
 var init_reviewTools = __esm(() => {
@@ -597,6 +604,7 @@ var init_dist = __esm(() => {
   init_playbookCatalog();
   init_playbookStage();
   init_projectTemplates();
+  init_realtimeChannel();
   init_reviewTools();
   init_stageHandoff();
   init_types();
@@ -4480,6 +4488,33 @@ function resolveWorktreeStartRef(baseBranch, branchName, continueExisting, branc
   }
   return `origin/${baseBranch}`;
 }
+function resolveContinuationTarget(branchName, continueRequested, failedBranchPrefix, approvedBranchPrefix, branchExistsOnOrigin) {
+  if (branchExistsOnOrigin(branchName)) {
+    return {
+      branchName,
+      continueExisting: true,
+      existsOnOrigin: true,
+      reason: continueRequested ? "requested" : "exists_on_origin"
+    };
+  }
+  if (failedBranchPrefix && approvedBranchPrefix && branchName.startsWith(failedBranchPrefix)) {
+    const sibling = approvedBranchPrefix + branchName.slice(failedBranchPrefix.length);
+    if (branchExistsOnOrigin(sibling)) {
+      return {
+        branchName: sibling,
+        continueExisting: true,
+        existsOnOrigin: true,
+        reason: "approved_rename"
+      };
+    }
+  }
+  return {
+    branchName,
+    continueExisting: continueRequested,
+    existsOnOrigin: false,
+    reason: "fresh"
+  };
+}
 function fetchExistingBranch(repoRoot, branchName, attempts = 3, lsRemoteImpl = (root, branch) => execFileSync8("git", ["ls-remote", "--exit-code", "origin", `refs/heads/${branch}`], { cwd: root, stdio: "pipe" }), fetchImpl = (root, branch) => execFileSync8("git", [
   "fetch",
   "origin",
@@ -4538,7 +4573,7 @@ function createWorktree(basePath, baseBranch, branchName, opts = {}) {
     });
   } catch {}
   fetchBaseBranch(repoRoot, baseBranch);
-  const startRef = resolveWorktreeStartRef(baseBranch, branchName, opts.continueExisting ?? false, () => fetchExistingBranch(repoRoot, branchName));
+  const startRef = resolveWorktreeStartRef(baseBranch, branchName, opts.continueExisting ?? false, () => opts.branchExistsOnOrigin ?? fetchExistingBranch(repoRoot, branchName));
   log.info(TAG16, `Creating worktree: ${worktreeDir} (branch: ${branchName}, base: ${startRef})`);
   try {
     execFileSync8("git", ["worktree", "add", "-B", branchName, worktreeDir, startRef], { cwd: repoRoot, stdio: "pipe" });
@@ -4787,6 +4822,7 @@ export {
   resolvePrUrl,
   resolvePrHeadBranch,
   resolveOracleRunner,
+  resolveContinuationTarget,
   rescueUnpushedBranch,
   rerunFailedJobs,
   requestIndependentReview,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Execution motor for Harmony playbook stages. Runs exactly one stage per invocation: worktree, role-separated subagents, held oracle, gate evidence. It never routes, never judges, never pushes.",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.178",
-    "@gethmy/mcp": "3.0.0",
+    "@gethmy/mcp": "3.1.0",
     "@supabase/supabase-js": "2.95.3"
   },
   "devDependencies": {

package/src/worktree.ts

@@ -114,6 +114,102 @@ export function resolveWorktreeStartRef(
   return `origin/${baseBranch}`;
 }
 
+/** The branch a run should actually build on, decided against origin (#930). */
+export interface ContinuationTarget {
+  /** The branch the run must use — possibly the approved-rename sibling. */
+  branchName: string;
+  /** Whether `createWorktree` should continue the branch's own pushed tip. */
+  continueExisting: boolean;
+  /**
+   * The probe's answer for `branchName`: does it exist on origin? Hand it to
+   * `createWorktree` (`opts.branchExistsOnOrigin`) so the same ref is not
+   * ls-remote'd + fetched a second time inside `resolveWorktreeStartRef` on
+   * every continued run. When true, the probe (`fetchExistingBranch`) has
+   * already fetched the ref, so `refs/remotes/origin/<branchName>` resolves
+   * locally — the promise `createWorktree` needs to skip its own probe.
+   */
+  existsOnOrigin: boolean;
+  /** Why — one legible word for the worker's log line. */
+  reason: "requested" | "exists_on_origin" | "approved_rename" | "fresh";
+}
+
+/**
+ * Final continuation decision for an implement run, consulted against origin
+ * right before `createWorktree` (#930).
+ *
+ * The description-based guard (`recordedBranchForCard` in @harmony/shared)
+ * answers from what the card RECORDS — and the record has two known failure
+ * modes, both in the data-loss class: a verify-failed run pushes its branch
+ * but dies before `postSummary` writes the record (or a human deletes the
+ * auto-appended block as routine cleanup), and a review approval renames the
+ * ref on origin while the record write can fail or predate the rewrite. So
+ * this helper asks origin itself:
+ *
+ * - The branch EXISTS on origin → continue it, whatever the description says.
+ *   `git worktree add -B` would reset it and completion would force-push over
+ *   it; the guard's contract is "failing safe costs a redundant continuation;
+ *   failing open costs the user's work" — this makes that hold even when the
+ *   record is gone.
+ * - The branch is GONE but its approved-rename sibling
+ *   (`<approvedPrefix><rest>` for a `<failedPrefix><rest>` name) exists →
+ *   continue the sibling. That is the ref the approval moved the work to;
+ *   rebuilding `<failedPrefix><rest>` from origin/<base> would reimplement
+ *   from scratch and the next approval would force-rename over the reviewed
+ *   branch behind its open PR.
+ * - Neither exists → nothing on origin to lose; pass `continueRequested`
+ *   through unchanged, and `createWorktree` falls back to a fresh branch
+ *   exactly as before.
+ *
+ * The probe's answer travels with the target (`existsOnOrigin`) so the caller
+ * can hand it to `createWorktree` and origin is asked exactly ONCE per run —
+ * without it, a continued run ls-remote'd + fetched the same ref a second time
+ * inside `resolveWorktreeStartRef` (#930 review).
+ *
+ * `branchExistsOnOrigin` is a thunk for the same reason as
+ * `resolveWorktreeStartRef`'s — the decision is unit-testable without git.
+ * Callers pass `fetchExistingBranch`, which fails CLOSED (throws
+ * `WorktreeBaseError` on an unprobeable remote) — a transient network error
+ * must requeue the run, never read as "branch absent" (#637 follow-up).
+ */
+export function resolveContinuationTarget(
+  branchName: string,
+  continueRequested: boolean,
+  failedBranchPrefix: string,
+  approvedBranchPrefix: string,
+  branchExistsOnOrigin: (ref: string) => boolean,
+): ContinuationTarget {
+  if (branchExistsOnOrigin(branchName)) {
+    return {
+      branchName,
+      continueExisting: true,
+      existsOnOrigin: true,
+      reason: continueRequested ? "requested" : "exists_on_origin",
+    };
+  }
+  if (
+    failedBranchPrefix &&
+    approvedBranchPrefix &&
+    branchName.startsWith(failedBranchPrefix)
+  ) {
+    const sibling =
+      approvedBranchPrefix + branchName.slice(failedBranchPrefix.length);
+    if (branchExistsOnOrigin(sibling)) {
+      return {
+        branchName: sibling,
+        continueExisting: true,
+        existsOnOrigin: true,
+        reason: "approved_rename",
+      };
+    }
+  }
+  return {
+    branchName,
+    continueExisting: continueRequested,
+    existsOnOrigin: false,
+    reason: "fresh",
+  };
+}
+
 /**
  * Fetch a branch from origin so `origin/<branchName>` resolves locally, and
  * report whether the branch exists on the remote.
@@ -209,6 +305,17 @@ export interface CreateWorktreeOptions {
    * when the branch isn't on origin yet.
    */
   continueExisting?: boolean;
+  /**
+   * Pre-answered origin probe for `branchName`, set when the caller already
+   * ran the probe (`resolveContinuationTarget` → `fetchExistingBranch`, #930):
+   * `createWorktree` then skips its own ls-remote + fetch of the same ref.
+   * `true` carries a promise, not just an answer — the ref must have been
+   * FETCHED so `refs/remotes/origin/<branchName>` resolves locally.
+   * `fetchExistingBranch` does both; a bare ls-remote does not, so never pass
+   * its answer here. Leave undefined and `createWorktree` probes itself
+   * (unchanged behaviour).
+   */
+  branchExistsOnOrigin?: boolean;
 }
 
 /**
@@ -278,12 +385,17 @@ export function createWorktree(
   // Pick the base ref. Normally a fresh per-attempt branch from
   // origin/<baseBranch>; for a stage continuation, the branch's own pushed tip
   // so a prior stage's commits survive into this run (#561). `-B` resets the
-  // local branch to whichever ref we chose.
+  // local branch to whichever ref we chose. A caller that already probed
+  // origin (resolveContinuationTarget, #930) passes the answer in
+  // `opts.branchExistsOnOrigin` — its probe also fetched the ref, so
+  // `origin/<branchName>` resolves locally and asking origin again would be a
+  // redundant second ls-remote + fetch of the same ref.
   const startRef = resolveWorktreeStartRef(
     baseBranch,
     branchName,
     opts.continueExisting ?? false,
-    () => fetchExistingBranch(repoRoot, branchName),
+    () =>
+      opts.branchExistsOnOrigin ?? fetchExistingBranch(repoRoot, branchName),
   );
 
   log.info(