@webpieces/repo-workflow-core 0.4.957 → 0.4.959

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/repo-workflow-core",
-  "version": "0.4.957",
+  "version": "0.4.959",
   "description": "Shared repository branch, worktree, sync, and identity-stamp mechanics.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -21,7 +21,7 @@
   "dependencies": {
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2",
-    "@webpieces/tooling-common": "0.4.957",
+    "@webpieces/tooling-common": "0.4.959",
     "tslib": "2.8.1"
   },
   "publishConfig": {

package/src/command-timeouts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The ceiling on every external command the detached main-sync refresher runs (#1342).
+ *
+ * WHY EVERY ONE NEEDS A CEILING. The refresher is single-flight behind `main-sync.lock.json`, and the
+ * lock is reclaimed once its holder is older than `hangTimeoutMinutes` (default 5). Reclaiming used to
+ * be the whole of hang recovery, and it was not enough: no `spawnSync` here carried a `timeout`, so a
+ * `git fetch` stuck on an ssh handshake, or a `gh pr list` stuck on the network, lived forever — and
+ * after every reclaim the next refresher could stack another one beside it. A bounded command makes a
+ * hung run END on its own; the reclaimer's kill (MainSyncLockService.tryAcquireMainSyncLock) is the
+ * backstop for a process that is stuck somewhere no timeout reaches.
+ *
+ * Sized so ONE network command plus a handful of local ones stays well inside the default
+ * 5-minute hang window. Node sends SIGTERM on expiry (the spawnSync default), which lets git clean up
+ * its own `.lock` files rather than leaving them behind as SIGKILL would.
+ */
+export declare class CommandTimeouts {
+    /** `git fetch` and `gh` — the two calls that cross the network. */
+    static readonly NETWORK_MS: number;
+    /** Local git (merge-base, rev-list, worktree list, status, …). Generous: a cold, large repo is slow, never hung. */
+    static readonly LOCAL_GIT_MS: number;
+    /** The ceiling for one captured command: `gh` talks to GitHub, everything else here is local git. */
+    forCommand(cmd: string): number;
+}

package/src/command-timeouts.js

@@ -0,0 +1,37 @@
+"use strict";
+var CommandTimeouts_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandTimeouts = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+/**
+ * The ceiling on every external command the detached main-sync refresher runs (#1342).
+ *
+ * WHY EVERY ONE NEEDS A CEILING. The refresher is single-flight behind `main-sync.lock.json`, and the
+ * lock is reclaimed once its holder is older than `hangTimeoutMinutes` (default 5). Reclaiming used to
+ * be the whole of hang recovery, and it was not enough: no `spawnSync` here carried a `timeout`, so a
+ * `git fetch` stuck on an ssh handshake, or a `gh pr list` stuck on the network, lived forever — and
+ * after every reclaim the next refresher could stack another one beside it. A bounded command makes a
+ * hung run END on its own; the reclaimer's kill (MainSyncLockService.tryAcquireMainSyncLock) is the
+ * backstop for a process that is stuck somewhere no timeout reaches.
+ *
+ * Sized so ONE network command plus a handful of local ones stays well inside the default
+ * 5-minute hang window. Node sends SIGTERM on expiry (the spawnSync default), which lets git clean up
+ * its own `.lock` files rather than leaving them behind as SIGKILL would.
+ */
+let CommandTimeouts = class CommandTimeouts {
+    static { CommandTimeouts_1 = this; }
+    /** `git fetch` and `gh` — the two calls that cross the network. */
+    static NETWORK_MS = 90 * 1000;
+    /** Local git (merge-base, rev-list, worktree list, status, …). Generous: a cold, large repo is slow, never hung. */
+    static LOCAL_GIT_MS = 30 * 1000;
+    /** The ceiling for one captured command: `gh` talks to GitHub, everything else here is local git. */
+    forCommand(cmd) {
+        return cmd === 'gh' ? CommandTimeouts_1.NETWORK_MS : CommandTimeouts_1.LOCAL_GIT_MS;
+    }
+};
+exports.CommandTimeouts = CommandTimeouts;
+exports.CommandTimeouts = CommandTimeouts = CommandTimeouts_1 = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], CommandTimeouts);
+//# sourceMappingURL=command-timeouts.js.map

package/src/command-timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-timeouts.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/command-timeouts.ts"],"names":[],"mappings":";;;;;AAAA,yCAA2D;AAE3D;;;;;;;;;;;;;;GAcG;AAEI,IAAM,eAAe,GAArB,MAAM,eAAe;;IACxB,mEAAmE;IACnE,MAAM,CAAU,UAAU,GAAG,EAAE,GAAG,IAAI,CAAC;IACvC,oHAAoH;IACpH,MAAM,CAAU,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC;IAEzC,qGAAqG;IACrG,UAAU,CAAC,GAAW;QAClB,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,iBAAe,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAe,CAAC,YAAY,CAAC;IACpF,CAAC;;AATQ,0CAAe;0BAAf,eAAe;IAD3B,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,eAAe,CAU3B","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\n\n/**\n * The ceiling on every external command the detached main-sync refresher runs (#1342).\n *\n * WHY EVERY ONE NEEDS A CEILING. The refresher is single-flight behind `main-sync.lock.json`, and the\n * lock is reclaimed once its holder is older than `hangTimeoutMinutes` (default 5). Reclaiming used to\n * be the whole of hang recovery, and it was not enough: no `spawnSync` here carried a `timeout`, so a\n * `git fetch` stuck on an ssh handshake, or a `gh pr list` stuck on the network, lived forever — and\n * after every reclaim the next refresher could stack another one beside it. A bounded command makes a\n * hung run END on its own; the reclaimer's kill (MainSyncLockService.tryAcquireMainSyncLock) is the\n * backstop for a process that is stuck somewhere no timeout reaches.\n *\n * Sized so ONE network command plus a handful of local ones stays well inside the default\n * 5-minute hang window. Node sends SIGTERM on expiry (the spawnSync default), which lets git clean up\n * its own `.lock` files rather than leaving them behind as SIGKILL would.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class CommandTimeouts {\n    /** `git fetch` and `gh` — the two calls that cross the network. */\n    static readonly NETWORK_MS = 90 * 1000;\n    /** Local git (merge-base, rev-list, worktree list, status, …). Generous: a cold, large repo is slow, never hung. */\n    static readonly LOCAL_GIT_MS = 30 * 1000;\n\n    /** The ceiling for one captured command: `gh` talks to GitHub, everything else here is local git. */\n    forCommand(cmd: string): number {\n        return cmd === 'gh' ? CommandTimeouts.NETWORK_MS : CommandTimeouts.LOCAL_GIT_MS;\n    }\n}\n"]}

package/src/index.d.ts

@@ -12,3 +12,5 @@ export * from './branch-archiver';
 export * from './branch-mutation-log';
 export * from './review-identity-stamp';
 export * from './branch-identity';
+export * from './command-timeouts';
+export * from './main-sync-lock';

package/src/index.js

@@ -15,4 +15,6 @@ tslib_1.__exportStar(require("./branch-archiver"), exports);
 tslib_1.__exportStar(require("./branch-mutation-log"), exports);
 tslib_1.__exportStar(require("./review-identity-stamp"), exports);
 tslib_1.__exportStar(require("./branch-identity"), exports);
+tslib_1.__exportStar(require("./command-timeouts"), exports);
+tslib_1.__exportStar(require("./main-sync-lock"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC;AACjC,6DAAmC;AACnC,4DAAkC;AAClC,mEAAyC;AACzC,sDAA4B;AAC5B,0DAAgC;AAChC,4DAAkC;AAClC,gEAAsC;AACtC,mEAAyC;AACzC,mEAAyC;AACzC,4DAAkC;AAClC,gEAAsC;AACtC,kEAAwC;AACxC,4DAAkC","sourcesContent":["export * from './main-sync-file';\nexport * from './main-sync-status';\nexport * from './merged-branches';\nexport * from './merged-branch-verdicts';\nexport * from './worktrees';\nexport * from './branch-reaper';\nexport * from './worktree-reaper';\nexport * from './agent-worktree-lock';\nexport * from './worktree-lock-verdicts';\nexport * from './harness-agent-activity';\nexport * from './branch-archiver';\nexport * from './branch-mutation-log';\nexport * from './review-identity-stamp';\nexport * from './branch-identity';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC;AACjC,6DAAmC;AACnC,4DAAkC;AAClC,mEAAyC;AACzC,sDAA4B;AAC5B,0DAAgC;AAChC,4DAAkC;AAClC,gEAAsC;AACtC,mEAAyC;AACzC,mEAAyC;AACzC,4DAAkC;AAClC,gEAAsC;AACtC,kEAAwC;AACxC,4DAAkC;AAClC,6DAAmC;AACnC,2DAAiC","sourcesContent":["export * from './main-sync-file';\nexport * from './main-sync-status';\nexport * from './merged-branches';\nexport * from './merged-branch-verdicts';\nexport * from './worktrees';\nexport * from './branch-reaper';\nexport * from './worktree-reaper';\nexport * from './agent-worktree-lock';\nexport * from './worktree-lock-verdicts';\nexport * from './harness-agent-activity';\nexport * from './branch-archiver';\nexport * from './branch-mutation-log';\nexport * from './review-identity-stamp';\nexport * from './branch-identity';\nexport * from './command-timeouts';\nexport * from './main-sync-lock';\n"]}

package/src/main-sync-file.d.ts

@@ -44,10 +44,27 @@ export declare class MainSyncStatus {
     forgeReachable: boolean;
     constructor(branch: string, branchAlreadyMerged: boolean, mergedPr: string, hasForkPoint: boolean, forkPoint: string | null, originMain: string, featureHead: string, conflict: boolean, conflictFiles: string[], timestamp: string);
 }
+/** How the last detached refresh ended. Recorded in the status file, never in the lock. */
+export declare enum RefreshOutcome {
+    OK = "ok",
+    ERROR = "error"
+}
 export declare class MainSyncStatusFile {
     version: number;
     timestamp: string;
     branches: Record<string, MainSyncStatus>;
+    /**
+     * Epoch ms the last detached refresh STARTED: the throttle's stamp (#1342). The spawner reads it
+     * before launching anything and launches nothing while it is under MIN_REFRESH_INTERVAL_MINUTES
+     * old. It is the START, not the finish, so a failing run is retried after the interval rather than
+     * on every tool call. Null (an older file, or one pr-gate wrote before any refresh) means "due".
+     *
+     * The refresher writes it BEFORE it deletes main-sync.lock.json, so no process can win the next
+     * lock race and still see the previous stamp.
+     */
+    lastRefreshStartedMs: number | null;
+    /** How that run ended; null until a refresh has recorded one. */
+    lastRefreshOutcome: RefreshOutcome | null;
     constructor(version: number, timestamp: string, branches: Record<string, MainSyncStatus>);
 }
 /**
@@ -106,6 +123,12 @@ export declare class MainSyncFileStore {
      * until the next refresh.
      */
     mergeBranch(statusPath: string, status: MainSyncStatus): void;
+    /**
+     * READ-MODIFY-WRITE the refresh stamp alone, keeping every branch entry. The refresher's failure
+     * path: no new branch data, but the run still counts, so the throttle waits out the interval.
+     */
+    recordRefresh(statusPath: string, startedMs: number, outcome: RefreshOutcome): void;
+    private carryRefreshStamp;
     branchStatus(file: MainSyncStatusFile | null, branch: string): MainSyncStatus | null;
     /**
      * Index `gh pr list --state all --json number,headRefName,state` output by head branch.
@@ -116,6 +139,7 @@ export declare class MainSyncFileStore {
      */
     indexPullRequests(json: string): PullRequestIndex;
     private indexOne;
+    private toOutcome;
     private adapt;
     private toStatus;
 }

package/src/main-sync-file.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MainSyncFileStore = exports.PullRequestIndex = exports.MainSyncStatusFile = exports.MainSyncStatus = exports.MAIN_SYNC_STATUS_VERSION = void 0;
+exports.MainSyncFileStore = exports.PullRequestIndex = exports.MainSyncStatusFile = exports.RefreshOutcome = exports.MainSyncStatus = exports.MAIN_SYNC_STATUS_VERSION = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const inversify_1 = require("inversify");
@@ -72,12 +72,30 @@ class MainSyncStatus {
     }
 }
 exports.MainSyncStatus = MainSyncStatus;
+/** How the last detached refresh ended. Recorded in the status file, never in the lock. */
+var RefreshOutcome;
+(function (RefreshOutcome) {
+    RefreshOutcome["OK"] = "ok";
+    RefreshOutcome["ERROR"] = "error";
+})(RefreshOutcome || (exports.RefreshOutcome = RefreshOutcome = {}));
 // Data-only. The whole document: every branch the last refresh could see, written as one unit.
 class MainSyncStatusFile {
     version;
     // When the map as a whole was written. Each entry also carries its own timestamp.
     timestamp;
     branches;
+    /**
+     * Epoch ms the last detached refresh STARTED: the throttle's stamp (#1342). The spawner reads it
+     * before launching anything and launches nothing while it is under MIN_REFRESH_INTERVAL_MINUTES
+     * old. It is the START, not the finish, so a failing run is retried after the interval rather than
+     * on every tool call. Null (an older file, or one pr-gate wrote before any refresh) means "due".
+     *
+     * The refresher writes it BEFORE it deletes main-sync.lock.json, so no process can win the next
+     * lock race and still see the previous stamp.
+     */
+    lastRefreshStartedMs = null;
+    /** How that run ended; null until a refresh has recorded one. */
+    lastRefreshOutcome = null;
     constructor(version, timestamp, branches) {
         this.version = version;
         this.timestamp = timestamp;
@@ -186,7 +204,28 @@ let MainSyncFileStore = class MainSyncFileStore {
         const existing = this.readFile(statusPath);
         const branches = existing === null ? {} : existing.branches;
         branches[status.branch] = status;
-        this.writeFile(statusPath, new MainSyncStatusFile(exports.MAIN_SYNC_STATUS_VERSION, new Date().toISOString(), branches));
+        const next = new MainSyncStatusFile(exports.MAIN_SYNC_STATUS_VERSION, new Date().toISOString(), branches);
+        this.carryRefreshStamp(existing, next);
+        this.writeFile(statusPath, next);
+    }
+    /**
+     * READ-MODIFY-WRITE the refresh stamp alone, keeping every branch entry. The refresher's failure
+     * path: no new branch data, but the run still counts, so the throttle waits out the interval.
+     */
+    recordRefresh(statusPath, startedMs, outcome) {
+        const existing = this.readFile(statusPath);
+        const next = new MainSyncStatusFile(exports.MAIN_SYNC_STATUS_VERSION, new Date().toISOString(), existing === null ? {} : existing.branches);
+        next.lastRefreshStartedMs = startedMs;
+        next.lastRefreshOutcome = outcome;
+        this.writeFile(statusPath, next);
+    }
+    // A writer that rebuilds the document (mergeBranch) must not erase the throttle's stamp: losing it
+    // would make the very next tool call launch a refresh.
+    carryRefreshStamp(from, to) {
+        if (from === null)
+            return;
+        to.lastRefreshStartedMs = from.lastRefreshStartedMs;
+        to.lastRefreshOutcome = from.lastRefreshOutcome;
     }
     // The entry for one branch, or null when this refresh never saw that branch.
     branchStatus(file, branch) {
@@ -241,6 +280,13 @@ let MainSyncFileStore = class MainSyncFileStore {
         if (state === 'OPEN' && !hasOwn(open, branch))
             open[branch] = number;
     }
+    toOutcome(raw) {
+        if (raw === RefreshOutcome.OK)
+            return RefreshOutcome.OK;
+        if (raw === RefreshOutcome.ERROR)
+            return RefreshOutcome.ERROR;
+        return null;
+    }
     // v2 documents pass through; a v1 document becomes a one-entry map keyed by its own `branch`.
     adapt(raw) {
         const branches = {};
@@ -250,7 +296,10 @@ let MainSyncFileStore = class MainSyncFileStore {
                 if (entry !== null && typeof entry === 'object')
                     branches[name] = this.toStatus(entry);
             }
-            return new MainSyncStatusFile(raw.version ?? exports.MAIN_SYNC_STATUS_VERSION, raw.timestamp ?? '', branches);
+            const file = new MainSyncStatusFile(raw.version ?? exports.MAIN_SYNC_STATUS_VERSION, raw.timestamp ?? '', branches);
+            file.lastRefreshStartedMs = typeof raw.lastRefreshStartedMs === 'number' ? raw.lastRefreshStartedMs : null;
+            file.lastRefreshOutcome = this.toOutcome(raw.lastRefreshOutcome);
+            return file;
         }
         // v1: one bare status at the top level. Key it by the branch it was computed for, so the
         // guard for THAT branch stays armed across the upgrade and every other branch simply misses

package/src/main-sync-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"main-sync-file.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/main-sync-file.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { AtomicFile } from '@webpieces/tooling-common';\nimport { toError } from '@webpieces/tooling-common/to-error';\n\n/**\n * The ON-DISK SHAPE of `<primary>/.webpieces/main-sync-status.json`, and nothing else.\n *\n * WHY this is its own module rather than more of main-sync-status.ts: that file already owns the lock\n * state machine plus the whole slow git/gh computation, and adding the map shape to it pushed it past\n * the 700-line cap. The split is along a real seam — everything here is pure parse/serialise with no\n * process spawning, so it is also the cheap half to test.\n *\n * WHY the file is a MAP of branch -> status (v2) rather than one status (v1): the cache is SHARED by\n * every worktree of the repo (one `.git`, one `origin/main`, one single-flight refresher), but a v1\n * file described exactly ONE branch — whichever tree won the lock. Every guard fails open when the\n * cached branch is not the branch it is judging, so with N worktrees at most one worktree's guards\n * were armed and the rest abstained, thrashing as the lock changed hands. Keeping the payload per\n * branch identical and only changing the LOOKUP means no guard's field access changed.\n */\n\n// Bumped when the shape changes. v1 = one bare status; v2 = branch map; v3 = cached commit distance.\nexport const MAIN_SYNC_STATUS_VERSION = 3;\n\n// Data-only (per CLAUDE.md, classes for data). The per-branch payload — unchanged from v1.\nexport class MainSyncStatus {\n    branch: string;\n    branchAlreadyMerged: boolean;\n    mergedPr: string;\n    hasForkPoint: boolean;\n    forkPoint: string | null;\n    originMain: string;\n    featureHead: string;\n    conflict: boolean;\n    conflictFiles: string[];\n    timestamp: string;\n    // An OPEN (not merged) PR tracking this branch, if any — '' = none or not-yet-known. Advisory.\n    // Kept OUT of the positional constructor (a defaulted field) so existing call sites don't churn.\n    openPr: string = '';\n    // The LOCAL refs/heads/main hash — '' = main does not exist locally (fresh clone / worktree) or\n    // could not be read. Paired with `originMain`, this is what tells the read-stale-guard whether a\n    // checked-out `main` is behind its remote. Defaulted field for the same reason as `openPr`.\n    localMain: string = '';\n    // Computed by the detached refresher as local main..origin/main. Null means an older cache or git\n    // could not establish the distance; stale-main threshold checks fail open in that state.\n    commitsBehind: number | null = null;\n    /**\n     * Did the forge answer when this entry was computed? See PullRequestIndex.forgeReachable.\n     *\n     * `branchAlreadyMerged: false` is produced BOTH by \"this branch has no merged PR\" and by \"we could\n     * not ask\", and the three guards that act on the merged state took the ordinary ALLOW path in both.\n     * Carrying the distinction into the cache is what lets them say ALLOW_FAIL_OPEN / `no-forge`\n     * instead — the typed verdict exists precisely so abstentions are countable.\n     *\n     * Defaults TRUE, matching `openPr`/`localMain` as a non-positional field: an entry written before\n     * this field existed (or hand-edited) is read as \"the forge answered\", which preserves today's\n     * verdicts exactly rather than retro-labelling old caches as abstentions.\n     */\n    forgeReachable: boolean = true;\n\n    constructor(\n        branch: string,\n        branchAlreadyMerged: boolean,\n        mergedPr: string,\n        hasForkPoint: boolean,\n        forkPoint: string | null,\n        originMain: string,\n        featureHead: string,\n        conflict: boolean,\n        conflictFiles: string[],\n        timestamp: string,\n    ) {\n        this.branch = branch;\n        this.branchAlreadyMerged = branchAlreadyMerged;\n        this.mergedPr = mergedPr;\n        this.hasForkPoint = hasForkPoint;\n        this.forkPoint = forkPoint;\n        this.originMain = originMain;\n        this.featureHead = featureHead;\n        this.conflict = conflict;\n        this.conflictFiles = conflictFiles;\n        this.timestamp = timestamp;\n    }\n}\n\n// Data-only. The whole document: every branch the last refresh could see, written as one unit.\nexport class MainSyncStatusFile {\n    version: number;\n    // When the map as a whole was written. Each entry also carries its own timestamp.\n    timestamp: string;\n    branches: Record<string, MainSyncStatus>;\n\n    constructor(version: number, timestamp: string, branches: Record<string, MainSyncStatus>) {\n        this.version = version;\n        this.timestamp = timestamp;\n        this.branches = branches;\n    }\n}\n\n/**\n * The repo's pull requests indexed by head branch — ONE `gh pr list` for the whole refresh.\n *\n * WHY it exists: the per-branch status needs a merged-PR and an open-PR answer, and the old code asked\n * `gh` twice PER BRANCH. Recording N branches per refresh would have meant 2N network round trips and\n * made the refresher scale with worktree count. One repo-wide query indexed locally is 1 call for any N.\n */\nexport class PullRequestIndex {\n    // branch -> PR number, as a string ('' means \"no such PR\"), for MERGED and OPEN respectively.\n    merged: Record<string, string>;\n    open: Record<string, string>;\n    /**\n     * Did the forge actually ANSWER?\n     *\n     * `mergedFor()` returning '' has always meant two completely different things — \"this branch has no\n     * merged PR\" and \"we could not ask\" (`gh` missing, unauthenticated, rate-limited, offline, or the\n     * response unparseable). Both produced the same empty index, so from the decision log you could not\n     * tell whether the merged-branch policy was PROTECTING anything or quietly abstaining. This flag is\n     * the difference, and it is what lets the guards emit ALLOW_FAIL_OPEN instead of a plain ALLOW.\n     *\n     * REQUIRED, not defaulted: an index built on a failure path must say so out loud, and a default of\n     * `true` would make \"we asked and got an answer\" the thing you get by forgetting.\n     */\n    forgeReachable: boolean;\n\n    constructor(merged: Record<string, string>, open: Record<string, string>, forgeReachable: boolean) {\n        this.merged = merged;\n        this.open = open;\n        this.forgeReachable = forgeReachable;\n    }\n\n    // A merged PR for this branch, or '' — the same value the old per-branch `gh` call produced.\n    mergedFor(branch: string): string {\n        if (branch === '' || branch === 'main') return '';\n        return hasOwn(this.merged, branch) ? (this.merged[branch] ?? '') : '';\n    }\n\n    openFor(branch: string): string {\n        if (branch === '' || branch === 'main') return '';\n        return hasOwn(this.open, branch) ? (this.open[branch] ?? '') : '';\n    }\n}\n\n// Raw JSON shapes for the cast at the parse boundary.\ninterface RawStatus {\n    branch?: string;\n    branchAlreadyMerged?: boolean;\n    mergedPr?: string;\n    hasForkPoint?: boolean;\n    forkPoint?: string | null;\n    originMain?: string;\n    featureHead?: string;\n    conflict?: boolean;\n    conflictFiles?: string[];\n    timestamp?: string;\n    openPr?: string;\n    localMain?: string;\n    commitsBehind?: number | null;\n    forgeReachable?: boolean;\n}\n\n// v2 has `branches`; a v1 document instead has the RawStatus fields at the top level.\ninterface RawFile extends RawStatus {\n    version?: number;\n    branches?: Record<string, RawStatus>;\n}\n\n// One row of `gh pr list --json number,headRefName,state`.\ninterface RawPullRequest {\n    number?: number;\n    headRefName?: string;\n    state?: string;\n}\n\n// Own-property lookup only: a branch literally named `constructor` or `toString` must not resolve to\n// something off Object.prototype and be mistaken for a cached status.\n// webpieces-disable no-function-outside-class -- one-line own-property predicate used by the classes in this module\nfunction hasOwn(record: object, key: string): boolean {\n    return Object.prototype.hasOwnProperty.call(record, key);\n}\n\n/**\n * Reads and writes the branch-keyed status document. Every read fails SOFT to null (or to an empty\n * map) — the guards above this treat null as `no-sync-cache (fail-open)`, so a missing, truncated or\n * malformed file must never throw and must never block an edit.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class MainSyncFileStore {\n    constructor(private readonly atomicFile: AtomicFile = new AtomicFile()) {}\n\n    /**\n     * Parse the document at `statusPath`, adapting a v1 file on the way. Returns null when there is\n     * nothing readable there — missing file, unreadable file, or JSON that does not parse.\n     */\n    readFile(statusPath: string): MainSyncStatusFile | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!fs.existsSync(statusPath)) return null;\n            // The cast is the trust boundary: every field of RawFile is optional and every read of it\n            // below is defaulted, so a document of any other shape degrades to an empty map.\n            const parsed = JSON.parse(fs.readFileSync(statusPath, 'utf8')) as RawFile | null;\n            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;\n            return this.adapt(parsed);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    /**\n     * ATOMIC write (temp file + `rename()` in the same directory). The refresher writes this while\n     * guards on the blocking path read it, from other worktrees; a plain `writeFileSync` truncates\n     * first, so a reader landing in that window gets a torn document. Writing the map WHOLE also means\n     * a reader never sees half of one refresh's branches and half of the previous refresh's.\n     */\n    writeFile(statusPath: string, file: MainSyncStatusFile): void {\n        this.atomicFile.writeJsonAtomic(statusPath, file);\n    }\n\n    /**\n     * READ-MODIFY-WRITE a single branch's entry, leaving every sibling entry untouched.\n     *\n     * This is what any writer that is NOT the single-flight refresher must use. `stampCleanMainSyncStatus`\n     * (pr-gate's post-merge stamp) runs without the lock and knows about exactly one branch; if it wrote\n     * a whole document it would silently erase every other worktree's entry and disarm their guards\n     * until the next refresh.\n     */\n    mergeBranch(statusPath: string, status: MainSyncStatus): void {\n        const existing = this.readFile(statusPath);\n        const branches: Record<string, MainSyncStatus> = existing === null ? {} : existing.branches;\n        branches[status.branch] = status;\n        this.writeFile(statusPath, new MainSyncStatusFile(\n            MAIN_SYNC_STATUS_VERSION, new Date().toISOString(), branches));\n    }\n\n    // The entry for one branch, or null when this refresh never saw that branch.\n    branchStatus(file: MainSyncStatusFile | null, branch: string): MainSyncStatus | null {\n        if (file === null) return null;\n        // Defensive: readFile always produces a map, but this method is public and sits on the\n        // blocking path — a caller handing it a raw document must get null, not a throw.\n        if (file.branches === null || file.branches === undefined) return null;\n        if (!hasOwn(file.branches, branch)) return null;\n        return file.branches[branch] ?? null;\n    }\n\n    /**\n     * Index `gh pr list --state all --json number,headRefName,state` output by head branch.\n     *\n     * Newest-first is gh's order, so the FIRST row for a branch wins — matching the old per-branch\n     * `--jq .[0].number`. Anything unparseable yields an empty index, i.e. \"no PR\", which is the same\n     * answer the old code produced when `gh` was missing or offline: fail-open.\n     */\n    indexPullRequests(json: string): PullRequestIndex {\n        const merged: Record<string, string> = {};\n        const open: Record<string, string> = {};\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const parsed = JSON.parse(json) as RawPullRequest[] | null;\n            // Parsed but not an array: `gh` answered with something we do not understand, which is\n            // not the same as it answering \"no PRs\". Unreachable, so the guards abstain rather than allow.\n            if (!Array.isArray(parsed)) return new PullRequestIndex(merged, open, false);\n            for (const row of parsed) {\n                if (row !== null && typeof row === 'object') this.indexOne(row, merged, open);\n            }\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return new PullRequestIndex(merged, open, false);\n        }\n        return new PullRequestIndex(merged, open, true);\n    }\n\n    private indexOne(row: RawPullRequest, merged: Record<string, string>, open: Record<string, string>): void {\n        const branch = row.headRefName ?? '';\n        const number = typeof row.number === 'number' ? String(row.number) : '';\n        if (branch === '' || number === '') return;\n        const state = (row.state ?? '').toUpperCase();\n        // First row wins per branch+state — gh lists newest first, matching the old `.[0].number`.\n        if (state === 'MERGED' && !hasOwn(merged, branch)) merged[branch] = number;\n        if (state === 'OPEN' && !hasOwn(open, branch)) open[branch] = number;\n    }\n\n    // v2 documents pass through; a v1 document becomes a one-entry map keyed by its own `branch`.\n    private adapt(raw: RawFile): MainSyncStatusFile {\n        const branches: Record<string, MainSyncStatus> = {};\n        const rawBranches = raw.branches;\n        if (rawBranches !== undefined && rawBranches !== null && typeof rawBranches === 'object') {\n            for (const [name, entry] of Object.entries(rawBranches)) {\n                if (entry !== null && typeof entry === 'object') branches[name] = this.toStatus(entry);\n            }\n            return new MainSyncStatusFile(raw.version ?? MAIN_SYNC_STATUS_VERSION, raw.timestamp ?? '', branches);\n        }\n        // v1: one bare status at the top level. Key it by the branch it was computed for, so the\n        // guard for THAT branch stays armed across the upgrade and every other branch simply misses\n        // (null → `no-sync-cache (fail-open)`), which is what it did under v1 anyway.\n        if (typeof raw.branch === 'string' && raw.branch !== '') branches[raw.branch] = this.toStatus(raw);\n        return new MainSyncStatusFile(1, raw.timestamp ?? '', branches);\n    }\n\n    // Every field defaulted: a truncated or hand-edited entry degrades to a benign status rather\n    // than to a throw. `hasForkPoint` defaults TRUE because false is the BLOCKING value.\n    private toStatus(raw: RawStatus): MainSyncStatus {\n        const status = new MainSyncStatus(\n            raw.branch ?? '',\n            raw.branchAlreadyMerged ?? false,\n            raw.mergedPr ?? '',\n            raw.hasForkPoint ?? true,\n            raw.forkPoint ?? null,\n            raw.originMain ?? '',\n            raw.featureHead ?? '',\n            raw.conflict ?? false,\n            raw.conflictFiles ?? [],\n            raw.timestamp ?? '',\n        );\n        status.openPr = raw.openPr ?? '';\n        status.localMain = raw.localMain ?? '';\n        status.commitsBehind = typeof raw.commitsBehind === 'number'\n            && Number.isInteger(raw.commitsBehind) && raw.commitsBehind >= 0\n            ? raw.commitsBehind\n            : null;\n        status.forgeReachable = raw.forgeReachable ?? true;\n        return status;\n    }\n}\n"]}
+{"version":3,"file":"main-sync-file.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/main-sync-file.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { AtomicFile } from '@webpieces/tooling-common';\nimport { toError } from '@webpieces/tooling-common/to-error';\n\n/**\n * The ON-DISK SHAPE of `<primary>/.webpieces/main-sync-status.json`, and nothing else.\n *\n * WHY this is its own module rather than more of main-sync-status.ts: that file already owns the lock\n * state machine plus the whole slow git/gh computation, and adding the map shape to it pushed it past\n * the 700-line cap. The split is along a real seam — everything here is pure parse/serialise with no\n * process spawning, so it is also the cheap half to test.\n *\n * WHY the file is a MAP of branch -> status (v2) rather than one status (v1): the cache is SHARED by\n * every worktree of the repo (one `.git`, one `origin/main`, one single-flight refresher), but a v1\n * file described exactly ONE branch — whichever tree won the lock. Every guard fails open when the\n * cached branch is not the branch it is judging, so with N worktrees at most one worktree's guards\n * were armed and the rest abstained, thrashing as the lock changed hands. Keeping the payload per\n * branch identical and only changing the LOOKUP means no guard's field access changed.\n */\n\n// Bumped when the shape changes. v1 = one bare status; v2 = branch map; v3 = cached commit distance.\nexport const MAIN_SYNC_STATUS_VERSION = 3;\n\n// Data-only (per CLAUDE.md, classes for data). The per-branch payload — unchanged from v1.\nexport class MainSyncStatus {\n    branch: string;\n    branchAlreadyMerged: boolean;\n    mergedPr: string;\n    hasForkPoint: boolean;\n    forkPoint: string | null;\n    originMain: string;\n    featureHead: string;\n    conflict: boolean;\n    conflictFiles: string[];\n    timestamp: string;\n    // An OPEN (not merged) PR tracking this branch, if any — '' = none or not-yet-known. Advisory.\n    // Kept OUT of the positional constructor (a defaulted field) so existing call sites don't churn.\n    openPr: string = '';\n    // The LOCAL refs/heads/main hash — '' = main does not exist locally (fresh clone / worktree) or\n    // could not be read. Paired with `originMain`, this is what tells the read-stale-guard whether a\n    // checked-out `main` is behind its remote. Defaulted field for the same reason as `openPr`.\n    localMain: string = '';\n    // Computed by the detached refresher as local main..origin/main. Null means an older cache or git\n    // could not establish the distance; stale-main threshold checks fail open in that state.\n    commitsBehind: number | null = null;\n    /**\n     * Did the forge answer when this entry was computed? See PullRequestIndex.forgeReachable.\n     *\n     * `branchAlreadyMerged: false` is produced BOTH by \"this branch has no merged PR\" and by \"we could\n     * not ask\", and the three guards that act on the merged state took the ordinary ALLOW path in both.\n     * Carrying the distinction into the cache is what lets them say ALLOW_FAIL_OPEN / `no-forge`\n     * instead — the typed verdict exists precisely so abstentions are countable.\n     *\n     * Defaults TRUE, matching `openPr`/`localMain` as a non-positional field: an entry written before\n     * this field existed (or hand-edited) is read as \"the forge answered\", which preserves today's\n     * verdicts exactly rather than retro-labelling old caches as abstentions.\n     */\n    forgeReachable: boolean = true;\n\n    constructor(\n        branch: string,\n        branchAlreadyMerged: boolean,\n        mergedPr: string,\n        hasForkPoint: boolean,\n        forkPoint: string | null,\n        originMain: string,\n        featureHead: string,\n        conflict: boolean,\n        conflictFiles: string[],\n        timestamp: string,\n    ) {\n        this.branch = branch;\n        this.branchAlreadyMerged = branchAlreadyMerged;\n        this.mergedPr = mergedPr;\n        this.hasForkPoint = hasForkPoint;\n        this.forkPoint = forkPoint;\n        this.originMain = originMain;\n        this.featureHead = featureHead;\n        this.conflict = conflict;\n        this.conflictFiles = conflictFiles;\n        this.timestamp = timestamp;\n    }\n}\n\n/** How the last detached refresh ended. Recorded in the status file, never in the lock. */\nexport enum RefreshOutcome {\n    OK = 'ok',\n    ERROR = 'error',\n}\n\n// Data-only. The whole document: every branch the last refresh could see, written as one unit.\nexport class MainSyncStatusFile {\n    version: number;\n    // When the map as a whole was written. Each entry also carries its own timestamp.\n    timestamp: string;\n    branches: Record<string, MainSyncStatus>;\n    /**\n     * Epoch ms the last detached refresh STARTED: the throttle's stamp (#1342). The spawner reads it\n     * before launching anything and launches nothing while it is under MIN_REFRESH_INTERVAL_MINUTES\n     * old. It is the START, not the finish, so a failing run is retried after the interval rather than\n     * on every tool call. Null (an older file, or one pr-gate wrote before any refresh) means \"due\".\n     *\n     * The refresher writes it BEFORE it deletes main-sync.lock.json, so no process can win the next\n     * lock race and still see the previous stamp.\n     */\n    lastRefreshStartedMs: number | null = null;\n    /** How that run ended; null until a refresh has recorded one. */\n    lastRefreshOutcome: RefreshOutcome | null = null;\n\n    constructor(version: number, timestamp: string, branches: Record<string, MainSyncStatus>) {\n        this.version = version;\n        this.timestamp = timestamp;\n        this.branches = branches;\n    }\n}\n\n/**\n * The repo's pull requests indexed by head branch — ONE `gh pr list` for the whole refresh.\n *\n * WHY it exists: the per-branch status needs a merged-PR and an open-PR answer, and the old code asked\n * `gh` twice PER BRANCH. Recording N branches per refresh would have meant 2N network round trips and\n * made the refresher scale with worktree count. One repo-wide query indexed locally is 1 call for any N.\n */\nexport class PullRequestIndex {\n    // branch -> PR number, as a string ('' means \"no such PR\"), for MERGED and OPEN respectively.\n    merged: Record<string, string>;\n    open: Record<string, string>;\n    /**\n     * Did the forge actually ANSWER?\n     *\n     * `mergedFor()` returning '' has always meant two completely different things — \"this branch has no\n     * merged PR\" and \"we could not ask\" (`gh` missing, unauthenticated, rate-limited, offline, or the\n     * response unparseable). Both produced the same empty index, so from the decision log you could not\n     * tell whether the merged-branch policy was PROTECTING anything or quietly abstaining. This flag is\n     * the difference, and it is what lets the guards emit ALLOW_FAIL_OPEN instead of a plain ALLOW.\n     *\n     * REQUIRED, not defaulted: an index built on a failure path must say so out loud, and a default of\n     * `true` would make \"we asked and got an answer\" the thing you get by forgetting.\n     */\n    forgeReachable: boolean;\n\n    constructor(merged: Record<string, string>, open: Record<string, string>, forgeReachable: boolean) {\n        this.merged = merged;\n        this.open = open;\n        this.forgeReachable = forgeReachable;\n    }\n\n    // A merged PR for this branch, or '' — the same value the old per-branch `gh` call produced.\n    mergedFor(branch: string): string {\n        if (branch === '' || branch === 'main') return '';\n        return hasOwn(this.merged, branch) ? (this.merged[branch] ?? '') : '';\n    }\n\n    openFor(branch: string): string {\n        if (branch === '' || branch === 'main') return '';\n        return hasOwn(this.open, branch) ? (this.open[branch] ?? '') : '';\n    }\n}\n\n// Raw JSON shapes for the cast at the parse boundary.\ninterface RawStatus {\n    branch?: string;\n    branchAlreadyMerged?: boolean;\n    mergedPr?: string;\n    hasForkPoint?: boolean;\n    forkPoint?: string | null;\n    originMain?: string;\n    featureHead?: string;\n    conflict?: boolean;\n    conflictFiles?: string[];\n    timestamp?: string;\n    openPr?: string;\n    localMain?: string;\n    commitsBehind?: number | null;\n    forgeReachable?: boolean;\n}\n\n// v2 has `branches`; a v1 document instead has the RawStatus fields at the top level.\ninterface RawFile extends RawStatus {\n    version?: number;\n    lastRefreshStartedMs?: number | null;\n    lastRefreshOutcome?: string | null;\n    branches?: Record<string, RawStatus>;\n}\n\n// One row of `gh pr list --json number,headRefName,state`.\ninterface RawPullRequest {\n    number?: number;\n    headRefName?: string;\n    state?: string;\n}\n\n// Own-property lookup only: a branch literally named `constructor` or `toString` must not resolve to\n// something off Object.prototype and be mistaken for a cached status.\n// webpieces-disable no-function-outside-class -- one-line own-property predicate used by the classes in this module\nfunction hasOwn(record: object, key: string): boolean {\n    return Object.prototype.hasOwnProperty.call(record, key);\n}\n\n/**\n * Reads and writes the branch-keyed status document. Every read fails SOFT to null (or to an empty\n * map) — the guards above this treat null as `no-sync-cache (fail-open)`, so a missing, truncated or\n * malformed file must never throw and must never block an edit.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class MainSyncFileStore {\n    constructor(private readonly atomicFile: AtomicFile = new AtomicFile()) {}\n\n    /**\n     * Parse the document at `statusPath`, adapting a v1 file on the way. Returns null when there is\n     * nothing readable there — missing file, unreadable file, or JSON that does not parse.\n     */\n    readFile(statusPath: string): MainSyncStatusFile | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!fs.existsSync(statusPath)) return null;\n            // The cast is the trust boundary: every field of RawFile is optional and every read of it\n            // below is defaulted, so a document of any other shape degrades to an empty map.\n            const parsed = JSON.parse(fs.readFileSync(statusPath, 'utf8')) as RawFile | null;\n            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;\n            return this.adapt(parsed);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    /**\n     * ATOMIC write (temp file + `rename()` in the same directory). The refresher writes this while\n     * guards on the blocking path read it, from other worktrees; a plain `writeFileSync` truncates\n     * first, so a reader landing in that window gets a torn document. Writing the map WHOLE also means\n     * a reader never sees half of one refresh's branches and half of the previous refresh's.\n     */\n    writeFile(statusPath: string, file: MainSyncStatusFile): void {\n        this.atomicFile.writeJsonAtomic(statusPath, file);\n    }\n\n    /**\n     * READ-MODIFY-WRITE a single branch's entry, leaving every sibling entry untouched.\n     *\n     * This is what any writer that is NOT the single-flight refresher must use. `stampCleanMainSyncStatus`\n     * (pr-gate's post-merge stamp) runs without the lock and knows about exactly one branch; if it wrote\n     * a whole document it would silently erase every other worktree's entry and disarm their guards\n     * until the next refresh.\n     */\n    mergeBranch(statusPath: string, status: MainSyncStatus): void {\n        const existing = this.readFile(statusPath);\n        const branches: Record<string, MainSyncStatus> = existing === null ? {} : existing.branches;\n        branches[status.branch] = status;\n        const next = new MainSyncStatusFile(MAIN_SYNC_STATUS_VERSION, new Date().toISOString(), branches);\n        this.carryRefreshStamp(existing, next);\n        this.writeFile(statusPath, next);\n    }\n\n    /**\n     * READ-MODIFY-WRITE the refresh stamp alone, keeping every branch entry. The refresher's failure\n     * path: no new branch data, but the run still counts, so the throttle waits out the interval.\n     */\n    recordRefresh(statusPath: string, startedMs: number, outcome: RefreshOutcome): void {\n        const existing = this.readFile(statusPath);\n        const next = new MainSyncStatusFile(MAIN_SYNC_STATUS_VERSION, new Date().toISOString(),\n            existing === null ? {} : existing.branches);\n        next.lastRefreshStartedMs = startedMs;\n        next.lastRefreshOutcome = outcome;\n        this.writeFile(statusPath, next);\n    }\n\n    // A writer that rebuilds the document (mergeBranch) must not erase the throttle's stamp: losing it\n    // would make the very next tool call launch a refresh.\n    private carryRefreshStamp(from: MainSyncStatusFile | null, to: MainSyncStatusFile): void {\n        if (from === null) return;\n        to.lastRefreshStartedMs = from.lastRefreshStartedMs;\n        to.lastRefreshOutcome = from.lastRefreshOutcome;\n    }\n\n    // The entry for one branch, or null when this refresh never saw that branch.\n    branchStatus(file: MainSyncStatusFile | null, branch: string): MainSyncStatus | null {\n        if (file === null) return null;\n        // Defensive: readFile always produces a map, but this method is public and sits on the\n        // blocking path — a caller handing it a raw document must get null, not a throw.\n        if (file.branches === null || file.branches === undefined) return null;\n        if (!hasOwn(file.branches, branch)) return null;\n        return file.branches[branch] ?? null;\n    }\n\n    /**\n     * Index `gh pr list --state all --json number,headRefName,state` output by head branch.\n     *\n     * Newest-first is gh's order, so the FIRST row for a branch wins — matching the old per-branch\n     * `--jq .[0].number`. Anything unparseable yields an empty index, i.e. \"no PR\", which is the same\n     * answer the old code produced when `gh` was missing or offline: fail-open.\n     */\n    indexPullRequests(json: string): PullRequestIndex {\n        const merged: Record<string, string> = {};\n        const open: Record<string, string> = {};\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const parsed = JSON.parse(json) as RawPullRequest[] | null;\n            // Parsed but not an array: `gh` answered with something we do not understand, which is\n            // not the same as it answering \"no PRs\". Unreachable, so the guards abstain rather than allow.\n            if (!Array.isArray(parsed)) return new PullRequestIndex(merged, open, false);\n            for (const row of parsed) {\n                if (row !== null && typeof row === 'object') this.indexOne(row, merged, open);\n            }\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return new PullRequestIndex(merged, open, false);\n        }\n        return new PullRequestIndex(merged, open, true);\n    }\n\n    private indexOne(row: RawPullRequest, merged: Record<string, string>, open: Record<string, string>): void {\n        const branch = row.headRefName ?? '';\n        const number = typeof row.number === 'number' ? String(row.number) : '';\n        if (branch === '' || number === '') return;\n        const state = (row.state ?? '').toUpperCase();\n        // First row wins per branch+state — gh lists newest first, matching the old `.[0].number`.\n        if (state === 'MERGED' && !hasOwn(merged, branch)) merged[branch] = number;\n        if (state === 'OPEN' && !hasOwn(open, branch)) open[branch] = number;\n    }\n\n    private toOutcome(raw: string | null | undefined): RefreshOutcome | null {\n        if (raw === RefreshOutcome.OK) return RefreshOutcome.OK;\n        if (raw === RefreshOutcome.ERROR) return RefreshOutcome.ERROR;\n        return null;\n    }\n\n    // v2 documents pass through; a v1 document becomes a one-entry map keyed by its own `branch`.\n    private adapt(raw: RawFile): MainSyncStatusFile {\n        const branches: Record<string, MainSyncStatus> = {};\n        const rawBranches = raw.branches;\n        if (rawBranches !== undefined && rawBranches !== null && typeof rawBranches === 'object') {\n            for (const [name, entry] of Object.entries(rawBranches)) {\n                if (entry !== null && typeof entry === 'object') branches[name] = this.toStatus(entry);\n            }\n            const file = new MainSyncStatusFile(raw.version ?? MAIN_SYNC_STATUS_VERSION, raw.timestamp ?? '', branches);\n            file.lastRefreshStartedMs = typeof raw.lastRefreshStartedMs === 'number' ? raw.lastRefreshStartedMs : null;\n            file.lastRefreshOutcome = this.toOutcome(raw.lastRefreshOutcome);\n            return file;\n        }\n        // v1: one bare status at the top level. Key it by the branch it was computed for, so the\n        // guard for THAT branch stays armed across the upgrade and every other branch simply misses\n        // (null → `no-sync-cache (fail-open)`), which is what it did under v1 anyway.\n        if (typeof raw.branch === 'string' && raw.branch !== '') branches[raw.branch] = this.toStatus(raw);\n        return new MainSyncStatusFile(1, raw.timestamp ?? '', branches);\n    }\n\n    // Every field defaulted: a truncated or hand-edited entry degrades to a benign status rather\n    // than to a throw. `hasForkPoint` defaults TRUE because false is the BLOCKING value.\n    private toStatus(raw: RawStatus): MainSyncStatus {\n        const status = new MainSyncStatus(\n            raw.branch ?? '',\n            raw.branchAlreadyMerged ?? false,\n            raw.mergedPr ?? '',\n            raw.hasForkPoint ?? true,\n            raw.forkPoint ?? null,\n            raw.originMain ?? '',\n            raw.featureHead ?? '',\n            raw.conflict ?? false,\n            raw.conflictFiles ?? [],\n            raw.timestamp ?? '',\n        );\n        status.openPr = raw.openPr ?? '';\n        status.localMain = raw.localMain ?? '';\n        status.commitsBehind = typeof raw.commitsBehind === 'number'\n            && Number.isInteger(raw.commitsBehind) && raw.commitsBehind >= 0\n            ? raw.commitsBehind\n            : null;\n        status.forgeReachable = raw.forgeReachable ?? true;\n        return status;\n    }\n}\n"]}

package/src/main-sync-lock.d.ts

@@ -0,0 +1,142 @@
+import { AtomicFile, DotWebpieces } from '@webpieces/tooling-common';
+import { MainSyncStatusService } from './main-sync-status';
+/**
+ * The fewest minutes between two refresher STARTS, repo-wide (#1342).
+ *
+ * The refresh feeds only main-staleness (commits behind) and the merged-PR/reap data, and neither
+ * needs minute-level freshness: every `wp-*` command that acts on main does its own fetch. Without a
+ * floor the guards started a full refresh (`git fetch` over ssh, `gh pr list --limit 200`, per-branch
+ * merge-base) roughly once a minute per repo, and launched a node child on every single tool call.
+ *
+ * A CONSTANT, not a config knob: it only tunes frequency, and a key would have to wait a release
+ * before this repo's own config could state it (the published validator is one release behind).
+ */
+export declare const MIN_REFRESH_INTERVAL_MINUTES = 10;
+/**
+ * The pid a SPAWNER writes into the lock it takes for a refresher it has not launched yet. The hook
+ * process that wins exits within milliseconds, so its own pid would read as "holder dead" and invite a
+ * reclaim; 0 reads as "holder unknown", which is judged by age alone and is never signalled. The child
+ * replaces it with its own pid the moment it starts (adoptMainSyncLock).
+ */
+export declare const SPAWNER_CLAIM_PID = 0;
+export declare const MAIN_SYNC_LOCK_PURPOSE: string;
+/**
+ * The WHOLE content of `main-sync.lock.json` (data only). The file is a mutex and nothing else: its
+ * EXISTENCE is the lock. `pid` serves the liveness check, the kill of a hung holder and the "is it
+ * still mine" check before delete; `startedMs` serves the hangTimeoutMinutes staleness check. No state,
+ * no results: those are in main-sync-status.json, written before this file is deleted.
+ */
+export declare class MainSyncLock {
+    purpose: string;
+    pid: number;
+    startedMs: number;
+    constructor(pid: number, startedMs: number);
+}
+/** Why a spawner did, or did not, win the right to launch a refresher. */
+export declare enum RefreshClaimOutcome {
+    /** This caller created the lock and must launch the refresher (which adopts it). */
+    CLAIMED = "claimed",
+    /** The last refresh STARTED less than MIN_REFRESH_INTERVAL_MINUTES ago. Nothing to do. */
+    RECENT = "recent",
+    /** The lock exists and its holder is running, or another caller won the create first. */
+    HELD = "held"
+}
+export declare class RefreshClaim {
+    outcome: RefreshClaimOutcome;
+    /** The lock now held; set only for CLAIMED. */
+    lock: MainSyncLock | null;
+    /** The stamp this decision read from main-sync-status.json, or null when none was recorded. */
+    lastRefreshStartedMs: number | null;
+    constructor(outcome: RefreshClaimOutcome, lock: MainSyncLock | null, lastRefreshStartedMs: number | null);
+}
+/**
+ * The single-flight mutex for the detached main-sync refresher, and the spawner's throttle in front of
+ * it (#1342). Two files, two jobs:
+ *
+ *   - `main-sync.lock.json` — the MUTEX. Created with an atomic exclusive create; the creator runs the
+ *     refresh and deletes it when done, after confirming it is still its own. Everybody else gets
+ *     EEXIST and skips.
+ *   - `main-sync-status.json` — the RESULTS, and `lastRefreshStartedMs`, the throttle's stamp. The
+ *     refresher writes it FIRST and deletes the lock LAST, so the stamp is on disk before any process
+ *     can win the next race.
+ *
+ * SHARED scope: one lock for the whole repo, in the primary clone. There is one `.git`, and N
+ * concurrent `git fetch`es against it are what corrupt `.git/FETCH_HEAD`.
+ */
+export declare class MainSyncLockService {
+    private readonly dotDir;
+    private readonly atomicFile;
+    private readonly status;
+    constructor(dotDir?: DotWebpieces, atomicFile?: AtomicFile, status?: MainSyncStatusService);
+    mainSyncLockPath(repoRoot: string): string;
+    /**
+     * THE SPAWNER'S WHOLE DECISION: may this hook process launch a refresher? Called BEFORE anything
+     * is spawned, so a throttled tool call costs one read of the status file: no node child, no git.
+     *
+     * The stamp is the last run's START, and a failed run records one too, so a failing refresh
+     * (offline, gh auth expired) is retried after the interval: never hammered on every call, never
+     * blocked forever. A run that crashes before recording anything leaves its lock behind, and that
+     * lock is reclaimed once older than `hangTimeoutMinutes`.
+     */
+    claimRefresh(repoRoot: string, hangTimeoutMinutes: number, now?: number): RefreshClaim;
+    /**
+     * Take the mutex with an atomic exclusive create. Returns the lock now held, or null.
+     *
+     * Normal case: the file does not exist (the last winner deleted it), the create wins, done. On
+     * EEXIST the holder is judged: alive and inside `hangTimeoutMinutes` means it is working, and we
+     * skip. Otherwise (hung, dead, or a file that is not a lock in this shape at all, such as the
+     * retired `state: finished` format) it is the ONE exception to "the winner deletes": its holder is
+     * killed if still alive, the file unlinked, and the create retried once; only that create's winner
+     * proceeds.
+     *
+     * The create writes the content to a private temp file and LINKS it into place: `link()` fails with
+     * EEXIST exactly like O_EXCL, but the lock appears with its content already in it, so no reader can
+     * ever see an empty lock and mistake it for garbage.
+     */
+    tryAcquireMainSyncLock(repoRoot: string, hangTimeoutMinutes: number, now?: number, pid?: number): MainSyncLock | null;
+    /**
+     * The detached refresher takes over the lock its spawner created: same `startedMs`, its own pid, so
+     * liveness and the reclaimer's kill now target the process doing the work. Null when that lock is no
+     * longer on disk (it was reclaimed while the child booted); the child then does nothing. The child
+     * never creates the lock itself, so it can never race its own spawner.
+     */
+    adoptMainSyncLock(repoRoot: string, claimStartedMs: number, pid?: number): MainSyncLock | null;
+    /**
+     * Delete OUR lock. Returns false, and deletes nothing, when the lock on disk is not ours: a run that
+     * hung past its window was reclaimed, and deleting the NEWER holder's lock would let a third
+     * refresher start beside the second. Call it only after the status file (and its stamp) is written.
+     */
+    releaseMainSyncLock(repoRoot: string, held: MainSyncLock): boolean;
+    /**
+     * The lock on disk, or null when there is none. A file that is not a lock in this shape (the retired
+     * `state`/`started` format, or anything unparseable) reads as a lock with pid 0 started at the epoch:
+     * stale at once, so it is reclaimed rather than honoured as a second spelling of a lock.
+     */
+    readMainSyncLock(repoRoot: string): MainSyncLock | null;
+    writeMainSyncLock(repoRoot: string, lock: MainSyncLock): void;
+    isRefreshInProgress(repoRoot: string, hangTimeoutMinutes: number, now?: number): boolean;
+    isLockStale(lock: MainSyncLock, hangTimeoutMinutes: number, now?: number): boolean;
+    private isHolderRunning;
+    private withinInterval;
+    private readText;
+    private parse;
+    /**
+     * Atomic create-with-content: write a private temp file, then `link()` it to the lock path. The link
+     * fails with EEXIST when the lock exists, which is the O_EXCL contract, and a reader never sees the
+     * lock before its content.
+     */
+    private createExclusive;
+    /**
+     * Best-effort SIGKILL of a reclaimed holder that is still alive: a refresher hung past
+     * `hangTimeoutMinutes`. Never for pid <= 0 (a spawner's unadopted lock, or garbage), our own pid,
+     * or the claimant's. The refresher is spawned `detached`, so it leads its own process group: the
+     * group is signalled first, which takes its in-flight `git fetch` / `gh` children with it; a plain
+     * pid signal is the fallback for a holder that is not a group leader.
+     *
+     * Residual risk, accepted: after a long hang the OS may have reused the pid. The window is
+     * hangTimeoutMinutes, and pids cycle far slower than that on a developer machine.
+     */
+    private killStaleHolder;
+    private sendKill;
+    private isProcessAlive;
+}