@ricsam/r5d-worker 0.0.51 → 0.0.54

package/dist/mjs/workspace-sync.mjs

@@ -2,7 +2,9 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { managedBranchPath } from "./managed-paths.mjs";
+import { WorkspaceMutationGate } from "./workspace-mutation-gate.mjs";
 const WORKSPACE_BRANCH = "main";
+const WORKSPACE_INTENT_REF_PREFIX = "refs/r5d/workspace-intents/";
 const MAX_WORKSPACE_SYNC_DIFF_BYTES = 5 * 1024 * 1024;
 const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5e3;
 const MAX_REPORTED_WORKSPACE_PATHS = 2e3;
@@ -1072,10 +1074,27 @@ function commitMessage(input) {
     ...input.confirmedLargeDiff ? { confirmedLargeDiff: true, confirmationReason: input.confirmationReason } : {}
   });
 }
-function isNonFastForward(result) {
-  const output = `${result.stdout}
-${result.stderr}`.toLowerCase();
-  return output.includes("non-fast-forward") || output.includes("fetch first") || output.includes("[rejected]");
+function assertWorkspaceQuarantineRef(quarantineRef) {
+  const suffix = quarantineRef.slice(WORKSPACE_INTENT_REF_PREFIX.length);
+  if (!quarantineRef.startsWith(WORKSPACE_INTENT_REF_PREFIX) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(suffix)) {
+    throw new Error(`Workspace candidate ref must be below ${WORKSPACE_INTENT_REF_PREFIX}`);
+  }
+  const result = Bun.spawnSync(["git", "check-ref-format", quarantineRef], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(`Invalid workspace candidate ref ${JSON.stringify(quarantineRef)}`);
+  }
+}
+function uploadWorkspaceCandidate(input, candidateHead) {
+  const quarantineRef = input.quarantineRef;
+  if (!quarantineRef) {
+    throw new Error("A server-issued workspace candidate ref is required before uploading a canonical workspace candidate");
+  }
+  assertWorkspaceQuarantineRef(quarantineRef);
+  return runGitResult(input, input.shadowRoot, ["push", "origin", `HEAD:${quarantineRef}`]);
 }
 function resetShadowToRemote(input, opaqueWorkspaceRoots = []) {
   runGit(input, input.shadowRoot, ["fetch", "origin", "--prune"], "fetch canonical workspace before reset");
@@ -1094,6 +1113,7 @@ function baseResult(input, startingHead) {
     workerLabel: input.workerLabel,
     trigger: input.trigger,
     startingHead,
+    expectedHead: startingHead,
     rebaseCount: 0,
     diffSizeBytes: 0,
     gitStatus: "",
@@ -1103,6 +1123,32 @@ function baseResult(input, startingHead) {
     localChangesDiscarded: false
   };
 }
+function convergeRedundantInboundCandidate(input, result) {
+  if (input.trigger.type !== "inbound_head" || !input.skipVisibleMirror || input.trigger.canonicalCheckoutOnly) return null;
+  const remoteHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+  if (!remoteHead) return null;
+  const stagedTree = runGit(input, input.shadowRoot, ["write-tree"], "write inbound workspace candidate tree");
+  const remoteTree = runGit(
+    input,
+    input.shadowRoot,
+    ["rev-parse", "--verify", `${remoteHead}^{tree}`],
+    "resolve authoritative workspace tree"
+  );
+  if (stagedTree !== remoteTree) return null;
+  const localHead = revParse(input, "HEAD");
+  runGit(input, input.shadowRoot, ["reset", "--hard", remoteHead], "converge redundant inbound workspace candidate");
+  runGit(input, input.shadowRoot, ["clean", "-fd"], "clean redundant inbound workspace candidate");
+  mirrorShadowWorkspaceToVisible(input);
+  return {
+    ...result,
+    outcome: localHead === remoteHead ? "no_change" : "updated",
+    publishedHead: remoteHead,
+    diffSizeBytes: 0,
+    gitStatus: gitStatus(input),
+    affectedProjects: [],
+    affectedPaths: []
+  };
+}
 async function synchronizeWorkspace(rawInput) {
   let input = { ...rawInput, attemptId: rawInput.attemptId ?? crypto.randomUUID() };
   try {
@@ -1136,6 +1182,8 @@ async function synchronizeWorkspace(rawInput) {
     const stagePathspecs = mirroredGitlinkProjection.opaqueRoots.flatMap((root) => [`:(exclude,literal)${root}`]);
     runGit(input, input.shadowRoot, ["add", "-A", "--", ".", ...stagePathspecs], "stage workspace changes");
     forceStageCanonicalCheckoutFiles(input, mirroredGitlinkProjection.entries, mirroredGitlinkProjection.opaqueRoots);
+    const redundantInboundCandidate = convergeRedundantInboundCandidate(input, result);
+    if (redundantInboundCandidate) return redundantInboundCandidate;
     const sampledCanonicalCheckoutTreeHash = sampleCanonicalCheckoutTree(input);
     const stagedWorkingPaths = stagedPaths(input);
     const baseRevision = candidateBaseRevision(input);
@@ -1169,7 +1217,7 @@ async function synchronizeWorkspace(rawInput) {
     if (stagedWorkingPaths.length > 0) {
       runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit workspace changes");
     }
-    const candidateHead = revParse(input, "HEAD");
+    let candidateHead = revParse(input, "HEAD");
     if (candidateHead) assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, candidateHead);
     const hasRemoteMain = Boolean(revParse(input, `origin/${WORKSPACE_BRANCH}`));
     const hasUnpushedCommit = candidateHead ? !hasRemoteMain || !tryGit(input, input.shadowRoot, ["merge-base", "--is-ancestor", candidateHead, `origin/${WORKSPACE_BRANCH}`]) : false;
@@ -1205,58 +1253,59 @@ async function synchronizeWorkspace(rawInput) {
       };
     }
     let rebaseCount = 0;
-    for (let pushAttempt = 0; pushAttempt < 3; pushAttempt += 1) {
-      const push = runGitResult(input, input.shadowRoot, ["push", "origin", `HEAD:refs/heads/${WORKSPACE_BRANCH}`]);
-      if (push.exitCode === 0) {
-        const publishedHead = revParse(input, "HEAD") ?? candidateHead;
-        if (publishedHead) assertPublishedCanonicalCheckoutTree(input, publishedHead, sampledCanonicalCheckoutTreeHash);
-        mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
-        return {
-          ...observed,
-          outcome: "published",
-          candidateHead: candidateHead ?? void 0,
-          publishedHead: publishedHead ?? void 0,
-          rebaseCount,
-          gitStatus: gitStatus(input)
-        };
-      }
-      if (!isNonFastForward(push)) {
-        return {
-          ...observed,
-          outcome: "failed",
-          candidateHead: candidateHead ?? void 0,
-          rebaseCount,
-          error: push.stderr || push.stdout || "Workspace push failed",
-          gitStatus: gitStatus(input)
-        };
-      }
-      runGit(input, input.shadowRoot, ["fetch", "origin", "--prune"], "fetch workspace after push race");
+    const expectedHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+    if (candidateHead && expectedHead && !tryGit(input, input.shadowRoot, ["merge-base", "--is-ancestor", expectedHead, candidateHead])) {
       const rebase = runGitResult(input, input.shadowRoot, ["rebase", `origin/${WORKSPACE_BRANCH}`]);
       rebaseCount += 1;
       if (rebase.exitCode !== 0) {
         const conflicted = runGitResult(input, input.shadowRoot, ["diff", "--name-only", "--diff-filter=U", "-z"]);
-        const discardedPaths = reportedPaths([.../* @__PURE__ */ new Set([...paths, ...conflicted.stdout.split("\0").filter(Boolean)])].sort());
-        const publishedHead = resetShadowToRemote(input, mirroredGitlinkProjection.opaqueRoots);
+        const conflictPaths = reportedPaths([.../* @__PURE__ */ new Set([...paths, ...conflicted.stdout.split("\0").filter(Boolean)])].sort());
+        runGit(input, input.shadowRoot, ["rebase", "--abort"], "preserve workspace candidate after rebase conflict");
         return {
           ...observed,
-          outcome: "conflict_reset",
+          outcome: "failed",
+          expectedHead,
           candidateHead: candidateHead ?? void 0,
-          publishedHead: publishedHead ?? void 0,
           rebaseCount,
-          discardedPaths,
-          localChangesDiscarded: true,
+          affectedPaths: conflictPaths,
+          error: `Workspace candidate conflicts with canonical head ${expectedHead}; local changes were preserved for reconciliation.`,
           gitStatus: gitStatus(input)
         };
       }
+      candidateHead = revParse(input, "HEAD");
       assertPublishedCanonicalCheckoutTree(input, "HEAD", sampledCanonicalCheckoutTreeHash);
       assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, "HEAD");
     }
+    if (!candidateHead) {
+      return {
+        ...observed,
+        outcome: "failed",
+        rebaseCount,
+        error: "Workspace candidate does not have a commit",
+        gitStatus: gitStatus(input)
+      };
+    }
+    const upload = uploadWorkspaceCandidate(input, candidateHead);
+    if (upload.exitCode !== 0) {
+      return {
+        ...observed,
+        outcome: "failed",
+        candidateHead,
+        quarantineRef: input.quarantineRef,
+        rebaseCount,
+        error: upload.stderr || upload.stdout || "Workspace candidate upload failed",
+        gitStatus: gitStatus(input)
+      };
+    }
+    assertPublishedCanonicalCheckoutTree(input, candidateHead, sampledCanonicalCheckoutTreeHash);
+    mirrorShadowWorkspaceToVisible(input, mirroredGitlinkProjection.opaqueRoots);
     return {
       ...observed,
-      outcome: "failed",
-      candidateHead: candidateHead ?? void 0,
+      outcome: "candidate_ready",
+      expectedHead,
+      candidateHead,
+      quarantineRef: input.quarantineRef,
       rebaseCount,
-      error: "Workspace push did not converge after three attempts",
       gitStatus: gitStatus(input)
     };
   } catch (error) {
@@ -1299,9 +1348,10 @@ function calculateWorkspaceDiffFingerprint(rawInput) {
   return createHash("sha256").update(JSON.stringify({ stagedTree, localHead, remoteHead })).digest("hex");
 }
 class WorkspaceSyncSingleFlight {
+  mutationGate = new WorkspaceMutationGate();
   queue = Promise.resolve();
   enqueue(task) {
-    const queued = this.queue.then(task, task);
+    const queued = this.mutationGate.runSync(task);
     this.queue = queued.then(
       () => void 0,
       () => void 0
@@ -1320,6 +1370,12 @@ class WorkspaceSyncSingleFlight {
   fingerprintPrepared(prepare) {
     return this.enqueue(() => calculateWorkspaceDiffFingerprint(prepare()));
   }
+  runMutation(operation) {
+    return this.mutationGate.runMutation(operation);
+  }
+  acquireMutation() {
+    return this.mutationGate.acquireMutation();
+  }
   afterCurrent() {
     return this.queue;
   }
@@ -1327,10 +1383,12 @@ class WorkspaceSyncSingleFlight {
 export {
   MAX_WORKSPACE_SYNC_DIFF_BYTES,
   WORKSPACE_BRANCH,
+  WORKSPACE_INTENT_REF_PREFIX,
   WORKSPACE_NATIVE_PLANS_RELATIVE_PATH,
   WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
   WorkspaceSyncSingleFlight,
   assertCanonicalCheckoutIndexMatchesWorktree,
+  assertWorkspaceQuarantineRef,
   calculateWorkspaceDiffFingerprint,
   encodeWorkspaceBranch,
   mirrorShadowWorkspaceToVisible,

package/dist/types/heartbeat.d.ts

@@ -1,3 +1,10 @@
 export declare const WORKER_HEARTBEAT_INTERVAL_MS = 15000;
 export declare const WORKER_HEARTBEAT_TIMEOUT_MS = 45000;
 export declare function hasWorkerHeartbeatTimedOut(lastHeartbeatAt: number | null, now?: number, timeoutMs?: number): boolean;
+export type WorkerHeartbeatBusyGrace = {
+    heartbeatAt: number;
+    expiresAt: number;
+};
+/** Grant one bounded grace period for one actual server-heartbeat generation. */
+export declare function grantWorkerHeartbeatBusyGrace(lastHeartbeatAt: number | null, currentGrace: WorkerHeartbeatBusyGrace | null, now?: number, timeoutMs?: number, graceMs?: number): WorkerHeartbeatBusyGrace | null;
+export declare function hasWorkerHeartbeatTimedOutWithBusyGrace(lastHeartbeatAt: number | null, busyGrace: WorkerHeartbeatBusyGrace | null, now?: number, timeoutMs?: number): boolean;

package/dist/types/workspace-incident-state.d.ts

@@ -0,0 +1,8 @@
+export type WorkspaceIncidentUpdate = {
+    incidentId: string | null;
+    status: "remediating" | "waiting_for_worker" | "resolved" | "confirmed" | "reset" | null;
+};
+export declare function applyWorkspaceIncidentUpdate(currentIncidentId: string | null, update: WorkspaceIncidentUpdate): string | null;
+export declare function releasePendingWorkspaceHead(previousIncidentId: string | null, currentIncidentId: string | null, terminalIncidentId?: string | null): {
+    syncHead: string | null;
+};

package/dist/types/workspace-mutation-gate.d.ts

@@ -0,0 +1,19 @@
+export type WorkspaceMutationLease = () => void;
+/**
+ * Coordinates the visible workspace with its disposable sync shadow.
+ *
+ * Ordinary worktree activity may overlap other ordinary activity, but a sync
+ * gets exclusive access. Once a sync is queued, later mutations wait behind it
+ * so a busy shell cannot starve canonical publication indefinitely.
+ */
+export declare class WorkspaceMutationGate {
+    private activeMutations;
+    private syncActive;
+    private readonly waiters;
+    acquireMutation(): Promise<WorkspaceMutationLease>;
+    runMutation<T>(operation: () => Promise<T> | T): Promise<T>;
+    runSync<T>(operation: () => Promise<T> | T): Promise<T>;
+    private drain;
+    private releaseMutation;
+    private releaseSync;
+}

package/dist/types/workspace-sync.d.ts

@@ -1,5 +1,7 @@
 import { type CheckoutPathSegments } from "./managed-paths";
+import { type WorkspaceMutationLease } from "./workspace-mutation-gate";
 export declare const WORKSPACE_BRANCH = "main";
+export declare const WORKSPACE_INTENT_REF_PREFIX = "refs/r5d/workspace-intents/";
 export declare const MAX_WORKSPACE_SYNC_DIFF_BYTES: number;
 export declare const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5000;
 export type WorkspaceProjectManifestEntry = {
@@ -30,7 +32,7 @@ export type WorkspaceSyncTrigger = {
     canonicalCheckoutOnly?: boolean;
     detail?: string;
 };
-export type WorkspaceSyncOutcome = "no_change" | "published" | "updated" | "conflict_reset" | "large_diff_blocked" | "reset" | "failed";
+export type WorkspaceSyncOutcome = "no_change" | "candidate_ready" | "published" | "updated" | "conflict_reset" | "large_diff_blocked" | "reset" | "failed";
 export type WorkspaceSyncResult = {
     type: "workspace_sync";
     attemptId: string;
@@ -38,7 +40,9 @@ export type WorkspaceSyncResult = {
     trigger: WorkspaceSyncTrigger;
     outcome: WorkspaceSyncOutcome;
     startingHead: string | null;
+    expectedHead?: string | null;
     candidateHead?: string;
+    quarantineRef?: string;
     publishedHead?: string;
     rebaseCount: number;
     diffSizeBytes: number;
@@ -60,6 +64,11 @@ export type WorkspaceSyncInput = {
     shadowRoot: string;
     projects: WorkspaceProjectManifestEntry[];
     trigger: WorkspaceSyncTrigger;
+    /**
+     * Server-issued, attempt-scoped destination for candidate object uploads.
+     * Workers never publish the canonical workspace branch directly.
+     */
+    quarantineRef?: string;
     confirmedLargeDiff?: boolean;
     confirmationReason?: string;
     resetToCanonical?: boolean;
@@ -91,15 +100,19 @@ type GitlinkProjection = {
 export declare function assertCanonicalCheckoutIndexMatchesWorktree(checkoutPath: string): void;
 export declare function mirrorVisibleWorkspaceToShadow(input: WorkspaceSyncInput, excludedCheckouts?: ReadonlySet<string>): GitlinkProjection;
 export declare function mirrorShadowWorkspaceToVisible(input: WorkspaceSyncInput, opaqueWorkspaceRoots?: readonly string[]): void;
+export declare function assertWorkspaceQuarantineRef(quarantineRef: string): void;
 export declare function synchronizeWorkspace(rawInput: WorkspaceSyncInput): Promise<WorkspaceSyncResult>;
 export declare function calculateWorkspaceDiffFingerprint(rawInput: WorkspaceSyncInput): string;
 export declare class WorkspaceSyncSingleFlight {
+    private readonly mutationGate;
     private queue;
     private enqueue;
     run(input: WorkspaceSyncInput): Promise<WorkspaceSyncResult>;
     runPrepared(prepare: () => WorkspaceSyncInput): Promise<WorkspaceSyncResult>;
     fingerprint(input: WorkspaceSyncInput): Promise<string>;
     fingerprintPrepared(prepare: () => WorkspaceSyncInput): Promise<string>;
+    runMutation<T>(operation: () => Promise<T> | T): Promise<T>;
+    acquireMutation(): Promise<WorkspaceMutationLease>;
     afterCurrent(): Promise<void>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.51",
+  "version": "0.0.54",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",