@webpieces/ai-hook-rules 0.3.201 → 0.3.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.3.201",
+  "version": "0.3.202",
   "description": "Pluggable write-time validation framework for AI coding agents (@webpieces/ai-hook-rules). Claude Code PreToolUse + openclaw before_tool_call adapters share one rule engine.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -35,7 +35,7 @@
     "directory": "packages/tooling/ai-hook-rules"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.3.201"
+    "@webpieces/rules-config": "0.3.202"
   },
   "publishConfig": {
     "access": "public"

package/src/core/main-sync-log.d.ts

@@ -0,0 +1,15 @@
+export type SyncPhase = 'SPAWN_ATTEMPT' | 'START' | 'SKIP_INPROGRESS' | 'FINISH' | 'ERROR';
+export declare class SyncLogEvent {
+    phase: SyncPhase;
+    pid: number;
+    branchArg: string;
+    detail: string;
+    constructor(phase: SyncPhase, pid: number, branchArg: string, detail: string);
+}
+/**
+ * Append one tab-separated line per refresher event to `.webpieces/hooks/main-sync.log`. `root` is
+ * the workspace root holding `.webpieces`. Swallows all errors — logging must never block or fail
+ * the refresher (or the hook that spawns it).
+ */
+export declare function logSyncEvent(root: string, event: SyncLogEvent): void;
+export declare function syncStderrLogPath(root: string): string;

package/src/core/main-sync-log.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncLogEvent = void 0;
+exports.logSyncEvent = logSyncEvent;
+exports.syncStderrLogPath = syncStderrLogPath;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const to_error_1 = require("./to-error");
+// Observability for the detached background refresher (sync-main.ts). The refresher runs AFTER the
+// spawning hook has exited, with stdio discarded, so when it fails to update main-sync-status.json
+// there is normally no trace at all. This log captures its lifecycle — SPAWN_ATTEMPT (parent side),
+// then START / SKIP_INPROGRESS / FINISH / ERROR (child side) — so we can tell whether the detached
+// child never launched, was killed mid-run (START with no FINISH), or threw. Modeled on
+// decision-log.ts: same .webpieces/hooks dir, 512KB size rotation, toError-compliant catches.
+const HOOKS_DIR = '.webpieces/hooks';
+const LOG_FILE = 'main-sync.log';
+const LOG_FILE_PREV = 'main-sync.1.log';
+const STDERR_FILE = 'main-sync.stderr.log';
+const MAX_LOG_BYTES = 512 * 1024; // 512 KB — rotate when exceeded (mirrors decision-log)
+const MAX_DETAIL_LEN = 300;
+// Data-only record of one refresher lifecycle event (per CLAUDE.md: classes for data).
+class SyncLogEvent {
+    phase;
+    pid;
+    branchArg;
+    detail;
+    constructor(phase, pid, branchArg, detail) {
+        this.phase = phase;
+        this.pid = pid;
+        this.branchArg = branchArg;
+        this.detail = detail;
+    }
+}
+exports.SyncLogEvent = SyncLogEvent;
+/**
+ * Append one tab-separated line per refresher event to `.webpieces/hooks/main-sync.log`. `root` is
+ * the workspace root holding `.webpieces`. Swallows all errors — logging must never block or fail
+ * the refresher (or the hook that spawns it).
+ */
+function logSyncEvent(root, event) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const timestamp = new Date().toISOString();
+        const hooksDir = path.join(root, HOOKS_DIR);
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const logPath = path.join(hooksDir, LOG_FILE);
+        rotateLogFile(logPath, path.join(hooksDir, LOG_FILE_PREV));
+        const line = [
+            `[${timestamp}]`,
+            event.phase,
+            `pid=${String(event.pid)}`,
+            event.branchArg,
+            oneLine(event.detail),
+        ].join('\t') + '\n';
+        fs.appendFileSync(logPath, line);
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        void error;
+    }
+}
+// Absolute path the detached child's stdout/stderr are redirected to (opened with fs.openSync(p,'a')
+// by the spawner), so even a crash BEFORE our own logging runs — e.g. a module-load failure — is
+// captured instead of vanishing into /dev/null. Callers must ensure the hooks dir exists first
+// (logSyncEvent's mkdir, called for SPAWN_ATTEMPT, does that).
+function syncStderrLogPath(root) {
+    return path.join(root, HOOKS_DIR, STDERR_FILE);
+}
+// Collapse newlines/tabs and cap length so one event is always one log line.
+function oneLine(value) {
+    const flat = value.replace(/[\t\r\n]+/g, ' ').trim();
+    return flat.length <= MAX_DETAIL_LEN ? flat : flat.slice(0, MAX_DETAIL_LEN) + '…';
+}
+function rotateLogFile(logPath, prevPath) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size > MAX_LOG_BYTES) {
+            if (fs.existsSync(prevPath))
+                fs.unlinkSync(prevPath);
+            fs.renameSync(logPath, prevPath);
+        }
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        void error;
+    }
+}
+//# sourceMappingURL=main-sync-log.js.map

package/src/core/main-sync-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-sync-log.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/main-sync-log.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\nimport { toError } from './to-error';\n\n// Observability for the detached background refresher (sync-main.ts). The refresher runs AFTER the\n// spawning hook has exited, with stdio discarded, so when it fails to update main-sync-status.json\n// there is normally no trace at all. This log captures its lifecycle — SPAWN_ATTEMPT (parent side),\n// then START / SKIP_INPROGRESS / FINISH / ERROR (child side) — so we can tell whether the detached\n// child never launched, was killed mid-run (START with no FINISH), or threw. Modeled on\n// decision-log.ts: same .webpieces/hooks dir, 512KB size rotation, toError-compliant catches.\nconst HOOKS_DIR = '.webpieces/hooks';\nconst LOG_FILE = 'main-sync.log';\nconst LOG_FILE_PREV = 'main-sync.1.log';\nconst STDERR_FILE = 'main-sync.stderr.log';\nconst MAX_LOG_BYTES = 512 * 1024; // 512 KB — rotate when exceeded (mirrors decision-log)\nconst MAX_DETAIL_LEN = 300;\n\nexport type SyncPhase = 'SPAWN_ATTEMPT' | 'START' | 'SKIP_INPROGRESS' | 'FINISH' | 'ERROR';\n\n// Data-only record of one refresher lifecycle event (per CLAUDE.md: classes for data).\nexport class SyncLogEvent {\n    phase: SyncPhase;\n    pid: number;\n    branchArg: string;\n    detail: string;\n\n    constructor(phase: SyncPhase, pid: number, branchArg: string, detail: string) {\n        this.phase = phase;\n        this.pid = pid;\n        this.branchArg = branchArg;\n        this.detail = detail;\n    }\n}\n\n/**\n * Append one tab-separated line per refresher event to `.webpieces/hooks/main-sync.log`. `root` is\n * the workspace root holding `.webpieces`. Swallows all errors — logging must never block or fail\n * the refresher (or the hook that spawns it).\n */\nexport function logSyncEvent(root: string, event: SyncLogEvent): void {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const timestamp = new Date().toISOString();\n        const hooksDir = path.join(root, HOOKS_DIR);\n        fs.mkdirSync(hooksDir, { recursive: true });\n\n        const logPath = path.join(hooksDir, LOG_FILE);\n        rotateLogFile(logPath, path.join(hooksDir, LOG_FILE_PREV));\n\n        const line = [\n            `[${timestamp}]`,\n            event.phase,\n            `pid=${String(event.pid)}`,\n            event.branchArg,\n            oneLine(event.detail),\n        ].join('\\t') + '\\n';\n        fs.appendFileSync(logPath, line);\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n    }\n}\n\n// Absolute path the detached child's stdout/stderr are redirected to (opened with fs.openSync(p,'a')\n// by the spawner), so even a crash BEFORE our own logging runs — e.g. a module-load failure — is\n// captured instead of vanishing into /dev/null. Callers must ensure the hooks dir exists first\n// (logSyncEvent's mkdir, called for SPAWN_ATTEMPT, does that).\nexport function syncStderrLogPath(root: string): string {\n    return path.join(root, HOOKS_DIR, STDERR_FILE);\n}\n\n// Collapse newlines/tabs and cap length so one event is always one log line.\nfunction oneLine(value: string): string {\n    const flat = value.replace(/[\\t\\r\\n]+/g, ' ').trim();\n    return flat.length <= MAX_DETAIL_LEN ? flat : flat.slice(0, MAX_DETAIL_LEN) + '…';\n}\n\nfunction rotateLogFile(logPath: string, prevPath: string): void {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const stat = fs.statSync(logPath);\n        if (stat.size > MAX_LOG_BYTES) {\n            if (fs.existsSync(prevPath)) fs.unlinkSync(prevPath);\n            fs.renameSync(logPath, prevPath);\n        }\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n    }\n}\n"]}

package/src/core/main-sync-refresh.d.ts

@@ -3,5 +3,10 @@
  * not a bin). The child outlives this hook process (`detached` + `unref`), does the slow
  * merged-PR/fetch/merge-base/overlap work, and writes the cache the feature-branch-guard reads on
  * the NEXT call. This is the first detached spawn in the codebase — every existing hook is synchronous.
+ *
+ * Observability: we log SPAWN_ATTEMPT here and the child logs START/FINISH/ERROR, all to
+ * `.webpieces/hooks/main-sync.log`. The child's stdout/stderr are redirected to a sibling file (not
+ * /dev/null) so a crash before the child's own logging is still captured. If main-sync.log shows
+ * SPAWN_ATTEMPT but never START, the detached child was killed before it ran.
  */
 export declare function triggerMainSyncRefresh(workspaceRoot: string, hangTimeoutMinutes?: number): void;

package/src/core/main-sync-refresh.js

@@ -3,24 +3,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.triggerMainSyncRefresh = triggerMainSyncRefresh;
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const rules_config_1 = require("@webpieces/rules-config");
 const to_error_1 = require("./to-error");
+const main_sync_log_1 = require("./main-sync-log");
 /**
  * Fire-and-forget spawn of the detached refresher (sync-main.js in this same dir — spawned by path,
  * not a bin). The child outlives this hook process (`detached` + `unref`), does the slow
  * merged-PR/fetch/merge-base/overlap work, and writes the cache the feature-branch-guard reads on
  * the NEXT call. This is the first detached spawn in the codebase — every existing hook is synchronous.
+ *
+ * Observability: we log SPAWN_ATTEMPT here and the child logs START/FINISH/ERROR, all to
+ * `.webpieces/hooks/main-sync.log`. The child's stdout/stderr are redirected to a sibling file (not
+ * /dev/null) so a crash before the child's own logging is still captured. If main-sync.log shows
+ * SPAWN_ATTEMPT but never START, the detached child was killed before it ran.
  */
 function triggerMainSyncRefresh(workspaceRoot, hangTimeoutMinutes = rules_config_1.DEFAULT_HANG_TIMEOUT_MINUTES) {
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
         const refresher = path.join(__dirname, 'sync-main.js');
+        // SPAWN_ATTEMPT first — this also creates .webpieces/hooks so the stderr fd below can open.
+        (0, main_sync_log_1.logSyncEvent)(workspaceRoot, new main_sync_log_1.SyncLogEvent('SPAWN_ATTEMPT', process.pid, '-', `refresher=${refresher}`));
+        // Redirect the detached child's stdout+stderr to a file (not /dev/null) so an uncaught crash
+        // before the child's own logging — e.g. a module-load failure — is still captured.
+        const errFd = fs.openSync((0, main_sync_log_1.syncStderrLogPath)(workspaceRoot), 'a');
         const child = (0, child_process_1.spawn)(process.execPath, [refresher, workspaceRoot, String(hangTimeoutMinutes)], {
             detached: true,
-            stdio: 'ignore',
+            stdio: ['ignore', errFd, errFd],
+        });
+        // spawn errors (e.g. ENOENT) arrive asynchronously; record one if it fires. The hook may exit
+        // before this handler runs, but on POSIX a successful exec has already happened by now.
+        child.once('error', (err) => {
+            (0, main_sync_log_1.logSyncEvent)(workspaceRoot, new main_sync_log_1.SyncLogEvent('ERROR', child.pid ?? -1, '-', `spawn failed: ${err.message}`));
         });
         child.unref();
+        // The child has its own dup'd copy of the fd after spawn; close the parent's copy.
+        fs.closeSync(errFd);
     }
     catch (err) {
         const error = (0, to_error_1.toError)(err);

package/src/core/main-sync-refresh.js.map

@@ -1 +1 @@
-{"version":3,"file":"main-sync-refresh.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/main-sync-refresh.ts"],"names":[],"mappings":";;AAaA,wDAcC;;AA3BD,iDAAsC;AACtC,mDAA6B;AAE7B,0DAAuE;AAEvE,yCAAqC;AAErC;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,aAAqB,EAAE,qBAA6B,2CAA4B;IACnH,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACvD,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,kBAAkB,CAAC,CAAC,EAAE;YAC1F,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;SAClB,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,KAAK,CAAC;QACX,0EAA0E;IAC9E,CAAC;AACL,CAAC","sourcesContent":["import { spawn } from 'child_process';\nimport * as path from 'path';\n\nimport { DEFAULT_HANG_TIMEOUT_MINUTES } from '@webpieces/rules-config';\n\nimport { toError } from './to-error';\n\n/**\n * Fire-and-forget spawn of the detached refresher (sync-main.js in this same dir — spawned by path,\n * not a bin). The child outlives this hook process (`detached` + `unref`), does the slow\n * merged-PR/fetch/merge-base/overlap work, and writes the cache the feature-branch-guard reads on\n * the NEXT call. This is the first detached spawn in the codebase — every existing hook is synchronous.\n */\nexport function triggerMainSyncRefresh(workspaceRoot: string, hangTimeoutMinutes: number = DEFAULT_HANG_TIMEOUT_MINUTES): void {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const refresher = path.join(__dirname, 'sync-main.js');\n        const child = spawn(process.execPath, [refresher, workspaceRoot, String(hangTimeoutMinutes)], {\n            detached: true,\n            stdio: 'ignore',\n        });\n        child.unref();\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        // Spawning the background refresh must never block or fail the tool call.\n    }\n}\n"]}
+{"version":3,"file":"main-sync-refresh.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/main-sync-refresh.ts"],"names":[],"mappings":";;AAoBA,wDA2BC;;AA/CD,iDAAsC;AACtC,+CAAyB;AACzB,mDAA6B;AAE7B,0DAAuE;AAEvE,yCAAqC;AACrC,mDAAgF;AAEhF;;;;;;;;;;GAUG;AACH,SAAgB,sBAAsB,CAAC,aAAqB,EAAE,qBAA6B,2CAA4B;IACnH,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACvD,4FAA4F;QAC5F,IAAA,4BAAY,EAAC,aAAa,EAAE,IAAI,4BAAY,CAAC,eAAe,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,aAAa,SAAS,EAAE,CAAC,CAAC,CAAC;QAE3G,6FAA6F;QAC7F,mFAAmF;QACnF,MAAM,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAA,iCAAiB,EAAC,aAAa,CAAC,EAAE,GAAG,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,kBAAkB,CAAC,CAAC,EAAE;YAC1F,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC;SAClC,CAAC,CAAC;QACH,8FAA8F;QAC9F,wFAAwF;QACxF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAU,EAAQ,EAAE;YACrC,IAAA,4BAAY,EAAC,aAAa,EAAE,IAAI,4BAAY,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACjH,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,mFAAmF;QACnF,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,KAAK,CAAC;QACX,0EAA0E;IAC9E,CAAC;AACL,CAAC","sourcesContent":["import { spawn } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nimport { DEFAULT_HANG_TIMEOUT_MINUTES } from '@webpieces/rules-config';\n\nimport { toError } from './to-error';\nimport { logSyncEvent, SyncLogEvent, syncStderrLogPath } from './main-sync-log';\n\n/**\n * Fire-and-forget spawn of the detached refresher (sync-main.js in this same dir — spawned by path,\n * not a bin). The child outlives this hook process (`detached` + `unref`), does the slow\n * merged-PR/fetch/merge-base/overlap work, and writes the cache the feature-branch-guard reads on\n * the NEXT call. This is the first detached spawn in the codebase — every existing hook is synchronous.\n *\n * Observability: we log SPAWN_ATTEMPT here and the child logs START/FINISH/ERROR, all to\n * `.webpieces/hooks/main-sync.log`. The child's stdout/stderr are redirected to a sibling file (not\n * /dev/null) so a crash before the child's own logging is still captured. If main-sync.log shows\n * SPAWN_ATTEMPT but never START, the detached child was killed before it ran.\n */\nexport function triggerMainSyncRefresh(workspaceRoot: string, hangTimeoutMinutes: number = DEFAULT_HANG_TIMEOUT_MINUTES): void {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const refresher = path.join(__dirname, 'sync-main.js');\n        // SPAWN_ATTEMPT first — this also creates .webpieces/hooks so the stderr fd below can open.\n        logSyncEvent(workspaceRoot, new SyncLogEvent('SPAWN_ATTEMPT', process.pid, '-', `refresher=${refresher}`));\n\n        // Redirect the detached child's stdout+stderr to a file (not /dev/null) so an uncaught crash\n        // before the child's own logging — e.g. a module-load failure — is still captured.\n        const errFd = fs.openSync(syncStderrLogPath(workspaceRoot), 'a');\n        const child = spawn(process.execPath, [refresher, workspaceRoot, String(hangTimeoutMinutes)], {\n            detached: true,\n            stdio: ['ignore', errFd, errFd],\n        });\n        // spawn errors (e.g. ENOENT) arrive asynchronously; record one if it fires. The hook may exit\n        // before this handler runs, but on POSIX a successful exec has already happened by now.\n        child.once('error', (err: Error): void => {\n            logSyncEvent(workspaceRoot, new SyncLogEvent('ERROR', child.pid ?? -1, '-', `spawn failed: ${err.message}`));\n        });\n        child.unref();\n        // The child has its own dup'd copy of the fd after spawn; close the parent's copy.\n        fs.closeSync(errFd);\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        // Spawning the background refresh must never block or fail the tool call.\n    }\n}\n"]}

package/src/core/sync-main.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const rules_config_1 = require("@webpieces/rules-config");
 const to_error_1 = require("./to-error");
+const main_sync_log_1 = require("./main-sync-log");
 /**
  * The detached, fire-and-forget refresher spawned (by file path, not a bin) from
  * main-sync-refresh.ts. It does the SLOW work (merged-PR lookup + git fetch + merge-base +
@@ -19,16 +20,24 @@ const to_error_1 = require("./to-error");
 function main() {
     const repoRoot = process.argv[2] ?? process.cwd();
     const hangTimeoutMinutes = Number(process.argv[3]) || rules_config_1.DEFAULT_HANG_TIMEOUT_MINUTES;
+    const startedMs = Date.now();
+    // First action: prove the detached child actually started. If main-sync.log has no START line
+    // for a spawn, the child never launched (or died before this point).
+    (0, main_sync_log_1.logSyncEvent)(repoRoot, new main_sync_log_1.SyncLogEvent('START', process.pid, '-', `argv=${process.argv.slice(2).join(' ')}`));
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
-        if ((0, rules_config_1.isRefreshInProgress)(repoRoot, hangTimeoutMinutes))
+        if ((0, rules_config_1.isRefreshInProgress)(repoRoot, hangTimeoutMinutes)) {
+            (0, main_sync_log_1.logSyncEvent)(repoRoot, new main_sync_log_1.SyncLogEvent('SKIP_INPROGRESS', process.pid, '-', 'another refresh is in progress'));
             return;
+        }
         const lock = (0, rules_config_1.inProcessLock)();
         (0, rules_config_1.writeMainSyncLock)(repoRoot, lock);
         // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
         try {
             const status = (0, rules_config_1.computeMainSyncStatus)(repoRoot);
             (0, rules_config_1.writeMainSyncStatus)(repoRoot, status);
+            // FINISH after a successful write — START-without-FINISH means we were killed mid-run.
+            (0, main_sync_log_1.logSyncEvent)(repoRoot, new main_sync_log_1.SyncLogEvent('FINISH', process.pid, status.branch, `merged=${String(status.branchAlreadyMerged)} mergedPr=${status.mergedPr} forkPoint=${String(status.hasForkPoint)} conflict=${String(status.conflict)} ms=${String(Date.now() - startedMs)}`));
         }
         finally {
             // Always flip the lock off so a compute failure can't wedge the guard until the
@@ -38,9 +47,9 @@ function main() {
     }
     catch (err) {
         const error = (0, to_error_1.toError)(err);
-        void error;
-        // Detached: swallow so a transient git/fs error never leaves poison state. The next hook
-        // call spawns a fresh refresher.
+        // Detached: swallow so a transient git/fs error never leaves poison state (the next hook call
+        // spawns a fresh refresher) — but record WHY it died so the failure isn't invisible.
+        (0, main_sync_log_1.logSyncEvent)(repoRoot, new main_sync_log_1.SyncLogEvent('ERROR', process.pid, '-', `${error.message} | ${error.stack ?? ''}`));
     }
 }
 if (require.main === module) {

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

@@ -1 +1 @@
-{"version":3,"file":"sync-main.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/sync-main.ts"],"names":[],"mappings":";;AAyBA,oBAyBC;AAlDD,0DAQiC;AAEjC,yCAAqC;AAErC;;;;;;;;;;;;GAYG;AACH,SAAgB,IAAI;IAChB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAClD,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,2CAA4B,CAAC;IAEnF,8DAA8D;IAC9D,IAAI,CAAC;QACD,IAAI,IAAA,kCAAmB,EAAC,QAAQ,EAAE,kBAAkB,CAAC;YAAE,OAAO;QAE9D,MAAM,IAAI,GAAG,IAAA,4BAAa,GAAE,CAAC;QAC7B,IAAA,gCAAiB,EAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAClC,8DAA8D;QAC9D,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAA,oCAAqB,EAAC,QAAQ,CAAC,CAAC;YAC/C,IAAA,kCAAmB,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;gBAAS,CAAC;YACP,gFAAgF;YAChF,8BAA8B;YAC9B,IAAA,gCAAiB,EAAC,QAAQ,EAAE,IAAA,2BAAY,EAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,KAAK,CAAC;QACX,yFAAyF;QACzF,iCAAiC;IACrC,CAAC;AACL,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,CAAC;AACX,CAAC","sourcesContent":["import {\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    computeMainSyncStatus,\n    writeMainSyncStatus,\n    writeMainSyncLock,\n    isRefreshInProgress,\n    inProcessLock,\n    finishedLock,\n} from '@webpieces/rules-config';\n\nimport { toError } from './to-error';\n\n/**\n * The detached, fire-and-forget refresher spawned (by file path, not a bin) from\n * main-sync-refresh.ts. It does the SLOW work (merged-PR lookup + git fetch + merge-base +\n * same-file-overlap) and writes `.webpieces/main-sync-status.json` so the next hook call reads it\n * instantly. Nobody reads our exit code or output — we run after the spawning hook has returned.\n *\n * Concurrency: a lock file (`.webpieces/main-sync.lock.json`) holds `inprocess`/`finished` + a start\n * epoch. If another refresher is already `inprocess` and younger than hangTimeoutMinutes, we exit\n * immediately (don't pile up `git fetch`es). If it's `inprocess` but older than hangTimeoutMinutes,\n * we assume it hung and proceed anyway.\n *\n * argv: [, , repoRoot, hangTimeoutMinutes]\n */\nexport function main(): void {\n    const repoRoot = process.argv[2] ?? process.cwd();\n    const hangTimeoutMinutes = Number(process.argv[3]) || DEFAULT_HANG_TIMEOUT_MINUTES;\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        if (isRefreshInProgress(repoRoot, hangTimeoutMinutes)) return;\n\n        const lock = inProcessLock();\n        writeMainSyncLock(repoRoot, lock);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const status = computeMainSyncStatus(repoRoot);\n            writeMainSyncStatus(repoRoot, status);\n        } finally {\n            // Always flip the lock off so a compute failure can't wedge the guard until the\n            // staleness reclaim kicks in.\n            writeMainSyncLock(repoRoot, finishedLock(lock.started));\n        }\n    } catch (err: unknown) {\n        const error = toError(err);\n        void error;\n        // Detached: swallow so a transient git/fs error never leaves poison state. The next hook\n        // call spawns a fresh refresher.\n    }\n}\n\nif (require.main === module) {\n    main();\n}\n"]}
+{"version":3,"file":"sync-main.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/sync-main.ts"],"names":[],"mappings":";;AA0BA,oBAsCC;AAhED,0DAQiC;AAEjC,yCAAqC;AACrC,mDAA6D;AAE7D;;;;;;;;;;;;GAYG;AACH,SAAgB,IAAI;IAChB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAClD,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,2CAA4B,CAAC;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,8FAA8F;IAC9F,qEAAqE;IACrE,IAAA,4BAAY,EAAC,QAAQ,EAAE,IAAI,4BAAY,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/G,8DAA8D;IAC9D,IAAI,CAAC;QACD,IAAI,IAAA,kCAAmB,EAAC,QAAQ,EAAE,kBAAkB,CAAC,EAAE,CAAC;YACpD,IAAA,4BAAY,EAAC,QAAQ,EAAE,IAAI,4BAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,gCAAgC,CAAC,CAAC,CAAC;YAChH,OAAO;QACX,CAAC;QAED,MAAM,IAAI,GAAG,IAAA,4BAAa,GAAE,CAAC;QAC7B,IAAA,gCAAiB,EAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAClC,8DAA8D;QAC9D,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAA,oCAAqB,EAAC,QAAQ,CAAC,CAAC;YAC/C,IAAA,kCAAmB,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACtC,uFAAuF;YACvF,IAAA,4BAAY,EAAC,QAAQ,EAAE,IAAI,4BAAY,CACnC,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EACpC,UAAU,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,aAAa,MAAM,CAAC,QAAQ,cAAc,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,aAAa,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,EAAE,CAC/L,CAAC,CAAC;QACP,CAAC;gBAAS,CAAC;YACP,gFAAgF;YAChF,8BAA8B;YAC9B,IAAA,gCAAiB,EAAC,QAAQ,EAAE,IAAA,2BAAY,EAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,8FAA8F;QAC9F,qFAAqF;QACrF,IAAA,4BAAY,EAAC,QAAQ,EAAE,IAAI,4BAAY,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,OAAO,MAAM,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACnH,CAAC;AACL,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,CAAC;AACX,CAAC","sourcesContent":["import {\n    DEFAULT_HANG_TIMEOUT_MINUTES,\n    computeMainSyncStatus,\n    writeMainSyncStatus,\n    writeMainSyncLock,\n    isRefreshInProgress,\n    inProcessLock,\n    finishedLock,\n} from '@webpieces/rules-config';\n\nimport { toError } from './to-error';\nimport { logSyncEvent, SyncLogEvent } from './main-sync-log';\n\n/**\n * The detached, fire-and-forget refresher spawned (by file path, not a bin) from\n * main-sync-refresh.ts. It does the SLOW work (merged-PR lookup + git fetch + merge-base +\n * same-file-overlap) and writes `.webpieces/main-sync-status.json` so the next hook call reads it\n * instantly. Nobody reads our exit code or output — we run after the spawning hook has returned.\n *\n * Concurrency: a lock file (`.webpieces/main-sync.lock.json`) holds `inprocess`/`finished` + a start\n * epoch. If another refresher is already `inprocess` and younger than hangTimeoutMinutes, we exit\n * immediately (don't pile up `git fetch`es). If it's `inprocess` but older than hangTimeoutMinutes,\n * we assume it hung and proceed anyway.\n *\n * argv: [, , repoRoot, hangTimeoutMinutes]\n */\nexport function main(): void {\n    const repoRoot = process.argv[2] ?? process.cwd();\n    const hangTimeoutMinutes = Number(process.argv[3]) || DEFAULT_HANG_TIMEOUT_MINUTES;\n    const startedMs = Date.now();\n\n    // First action: prove the detached child actually started. If main-sync.log has no START line\n    // for a spawn, the child never launched (or died before this point).\n    logSyncEvent(repoRoot, new SyncLogEvent('START', process.pid, '-', `argv=${process.argv.slice(2).join(' ')}`));\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        if (isRefreshInProgress(repoRoot, hangTimeoutMinutes)) {\n            logSyncEvent(repoRoot, new SyncLogEvent('SKIP_INPROGRESS', process.pid, '-', 'another refresh is in progress'));\n            return;\n        }\n\n        const lock = inProcessLock();\n        writeMainSyncLock(repoRoot, lock);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const status = computeMainSyncStatus(repoRoot);\n            writeMainSyncStatus(repoRoot, status);\n            // FINISH after a successful write — START-without-FINISH means we were killed mid-run.\n            logSyncEvent(repoRoot, new SyncLogEvent(\n                'FINISH', process.pid, status.branch,\n                `merged=${String(status.branchAlreadyMerged)} mergedPr=${status.mergedPr} forkPoint=${String(status.hasForkPoint)} conflict=${String(status.conflict)} ms=${String(Date.now() - startedMs)}`,\n            ));\n        } finally {\n            // Always flip the lock off so a compute failure can't wedge the guard until the\n            // staleness reclaim kicks in.\n            writeMainSyncLock(repoRoot, finishedLock(lock.started));\n        }\n    } catch (err: unknown) {\n        const error = toError(err);\n        // Detached: swallow so a transient git/fs error never leaves poison state (the next hook call\n        // spawns a fresh refresher) — but record WHY it died so the failure isn't invisible.\n        logSyncEvent(repoRoot, new SyncLogEvent('ERROR', process.pid, '-', `${error.message} | ${error.stack ?? ''}`));\n    }\n}\n\nif (require.main === module) {\n    main();\n}\n"]}