@indigoai-us/hq-cli 5.345.32 → 5.345.34

package/dist/lib/lanes/keep-alive.js

@@ -187,6 +187,10 @@ function retiredLaneRegistryPath(hqRoot) {
 }
 /** Missing registry means no retired lanes; every present invalid file fails closed. */
 export function loadRetiredLaneIds(hqRoot) {
+    return new Set(loadRetiredLaneEntries(hqRoot).map((entry) => entry.lane));
+}
+/** Preserve registry metadata for diagnostics while validating the same shape as the eligibility reader. */
+export function loadRetiredLaneEntries(hqRoot) {
     const filePath = retiredLaneRegistryPath(hqRoot);
     let text;
     try {
@@ -198,7 +202,7 @@ export function loadRetiredLaneIds(hqRoot) {
     }
     catch (err) {
         if (err.code === "ENOENT")
-            return new Set();
+            return [];
         throw new LanesError("keep_alive_retired_list_invalid", `Cannot read retired lane list ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
     }
     let parsed;
@@ -213,21 +217,26 @@ export function loadRetiredLaneIds(hqRoot) {
     }
     const retired = parsed.retired;
     if (retired === undefined)
-        return new Set();
+        return [];
     if (!Array.isArray(retired))
         throw invalidRetiredList(filePath, "retired must be an array");
-    const laneIds = new Set();
+    const entries = [];
     for (const [index, entry] of retired.entries()) {
         if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
             throw invalidRetiredList(filePath, `retired[${index}] must be an object with a lane id`);
         }
-        const laneId = entry.lane;
+        const row = entry;
+        const laneId = row.lane;
         if (typeof laneId !== "string" || laneId.trim() === "") {
             throw invalidRetiredList(filePath, `retired[${index}].lane must be a non-empty string`);
         }
-        laneIds.add(laneId.trim());
+        entries.push({
+            lane: laneId.trim(),
+            index,
+            ...(typeof row.retired_at === "string" ? { retired_at: row.retired_at } : {}),
+        });
     }
-    return laneIds;
+    return entries;
 }
 function invalidRetiredList(filePath, message) {
     return new LanesError("keep_alive_retired_list_invalid", `Invalid retired lane list ${filePath}: ${message}`, { path: filePath });
@@ -242,6 +251,16 @@ function isRetiredLaneId(laneId, retiredLaneIds) {
     }
     return false;
 }
+/** Return the matching registry row using the same bare/host-suffixed ID semantics as keepAliveExclusion. */
+export function findRetiredLaneEntry(hqRoot, laneId) {
+    const entry = loadRetiredLaneEntries(hqRoot).find((candidate) => matchesRetiredLaneEntry(candidate, laneId));
+    return entry === undefined ? undefined : { ...entry, path: retiredLaneRegistryPath(hqRoot) };
+}
+export function matchesRetiredLaneEntry(entry, laneId) {
+    return entry.lane === laneId ||
+        entry.lane.startsWith(`${laneId}_`) ||
+        laneId.startsWith(`${entry.lane}_`);
+}
 export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED, companyForLane) {
     const createdAt = Date.parse(lane.created_at);
     if (!Number.isFinite(createdAt))

package/dist/lib/lanes/reconcile.d.ts

@@ -132,7 +132,7 @@ export declare function timeoutPath(hqRoot: string, laneId: string): string;
 export declare function laneRunsHere(lane: LaneRecord, host: ReconcileHost): boolean;
 export declare function agedAdvanceCount(question: QuestionRecord): number;
 export declare function currentHopStartedAtMs(question: QuestionRecord): number;
-export declare function shouldAgeQuestion(question: QuestionRecord, audience: SeniorRef, nowMs: number, ageWindowMs?: number): boolean;
+export declare function shouldAgeQuestion(question: QuestionRecord, audience: SeniorRef, nowMs: number, ageWindowMs?: number, maxAgedAdvances?: number): boolean;
 export declare function shouldAdvanceAudienceEnded(audience: SeniorRef, liveness: LivenessState | null): boolean;
 export declare function readTimeoutDeadline(hqRoot: string, laneId: string): {
     deadline_at: string;

package/dist/lib/lanes/reconcile.js

@@ -14,6 +14,7 @@ import { effectiveAccountHome } from "./account-home.js";
 import { enforceRegistryApprovalGate } from "./approval-gate.js";
 import { loadLanesConfig, providerQuotaDefaultHoldMs } from "./config.js";
 import { MAX_LANE_DEPTH } from "./constants.js";
+import { laneDepthCap } from "./depth-cap.js";
 import { AccountResolutionError, LanesError, isLaneVersionConflict } from "./errors.js";
 import { loadWorkerProfile } from "./profile.js";
 import { terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./grants.js";
@@ -155,12 +156,12 @@ export function currentHopStartedAtMs(question) {
     const ms = Date.parse(raw);
     return Number.isFinite(ms) ? ms : Number.NEGATIVE_INFINITY;
 }
-export function shouldAgeQuestion(question, audience, nowMs, ageWindowMs = QUESTION_AGE_MS) {
+export function shouldAgeQuestion(question, audience, nowMs, ageWindowMs = QUESTION_AGE_MS, maxAgedAdvances = MAX_AGED_ADVANCES) {
     if (question.status !== "pending")
         return false;
     if (audience.kind === "user")
         return false;
-    if (agedAdvanceCount(question) >= MAX_AGED_ADVANCES)
+    if (agedAdvanceCount(question) >= maxAgedAdvances)
         return false;
     const started = currentHopStartedAtMs(question);
     if (started === Number.NEGATIVE_INFINITY)
@@ -1121,16 +1122,26 @@ export async function runPassBody(hqRoot, deps) {
                 }
                 continue;
             }
-            if (shouldAgeQuestion(question, audience, nowMs, questionAgeWindowMs(audience))) {
+            let maxAgedAdvances;
+            try {
+                maxAgedAdvances = laneDepthCap(hqRoot, question.company?.slug).max * 2;
+            }
+            catch (err) {
+                if (!(err instanceof LanesError))
+                    throw err;
+                maxAgedAdvances = MAX_AGED_ADVANCES;
+                process.stderr.write(`hq lanes reconcile: lane depth config failed for company=${JSON.stringify(question.company?.slug)}; using default ${MAX_LANE_DEPTH}: ${err.message}\n`);
+            }
+            if (shouldAgeQuestion(question, audience, nowMs, questionAgeWindowMs(audience), maxAgedAdvances)) {
                 const nextHop = question.hop + 1;
                 const nextAudience = resolveQuestionAudience({ ...question, hop: nextHop }, readLaneSenior, readSessionSenior);
                 const result = casQuestionIf(hqRoot, question.question_id, (current) => {
                     if (current.status !== "pending" ||
-                        agedAdvanceCount(current) >= MAX_AGED_ADVANCES) {
+                        agedAdvanceCount(current) >= maxAgedAdvances) {
                         return false;
                     }
                     const currentAudience = resolveQuestionAudience(current, readLaneSenior, readSessionSenior);
-                    return shouldAgeQuestion(current, currentAudience, nowMs, questionAgeWindowMs(currentAudience));
+                    return shouldAgeQuestion(current, currentAudience, nowMs, questionAgeWindowMs(currentAudience), maxAgedAdvances);
                 }, (current) => {
                     const entry = {
                         hop: current.hop + 1,

package/dist/lib/mesh/api.d.ts

@@ -51,6 +51,8 @@ export interface MeshProjectStoryInput {
     description?: string;
     acceptanceCriteria?: string[];
     status?: string;
+    /** Source ledger state preserved for Boards whose status enum has four columns. */
+    ledgerState?: string;
     passes?: boolean;
     priority?: number;
     assigneeUid?: string;

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -55,6 +55,8 @@ export interface InstallPaths {
      * host has no conhost (the task then runs node directly).
      */
     windowsHeadlessLauncher?: string;
+    /** Windows command processor used to execute the stable npm .cmd shim. */
+    windowsCommandProcessor?: string;
     /** When true, render the root/ec2-user system unit instead of user unit. */
     systemUser?: string;
     /** Verified HQ root to persist and pass to the installed service. */
@@ -102,7 +104,6 @@ export declare function restartDaemonServiceIfInstalled(opts?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: typeof fs.existsSync;
     readFileSync?: typeof fs.readFileSync;
-    writeFileSync?: typeof fs.writeFileSync;
     run?: (command: string, args: string[]) => {
         status: number | null;
         stdout?: string;
@@ -119,7 +120,7 @@ export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstal
  * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
  * binary when both exist.
  */
-export declare function preferStableHqBinary(entry: string): string;
+export declare function preferStableHqBinary(entry: string, platform?: DaemonInstallPlatform, existsSync?: typeof fs.existsSync): string;
 /**
  * Absolute path of the CLI entry that is executing this process.
  * realpath of argv[1] only — never a PATH lookup of `hq`.
@@ -153,7 +154,6 @@ export declare function installDaemonIfStale(opts: {
     run?: RunCommand;
     uid?: number;
     sleep?: SleepFn;
-    writeFileSync?: typeof fs.writeFileSync;
     mkdirSync?: typeof fs.mkdirSync;
     reloadSystemd?: () => {
         status: number | null;
@@ -193,6 +193,10 @@ export declare function buildInstallPaths(opts: {
     windowsUser?: string;
     /** Windows headless launcher override (tests); defaults to %SystemRoot%\System32\conhost.exe when present. */
     windowsHeadlessLauncher?: string | null;
+    /** Platform override for unit path and command rendering tests. */
+    platform?: DaemonInstallPlatform;
+    /** Filesystem seam for stable hq shim resolution tests. */
+    existsSync?: typeof fs.existsSync;
 }): InstallPaths;
 /** `DOMAIN\user` for the current account, as Task Scheduler expects. */
 export declare function resolveWindowsUser(env?: NodeJS.ProcessEnv): string;
@@ -277,7 +281,6 @@ export declare function installDaemonService(opts: {
     paths?: InstallPaths;
     /** When set, write the system unit template (does not sudo-install). */
     systemUser?: string;
-    writeFileSync?: typeof fs.writeFileSync;
     mkdirSync?: typeof fs.mkdirSync;
     /** Optional: actually load the service (disabled in tests). */
     activate?: (platform: DaemonInstallPlatform, dest: string) => void;

package/dist/lib/mesh/live/daemon/install.js

@@ -16,6 +16,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import semver from "semver";
+import { atomicWrite } from "../../../index-render/shared.js";
 import { resolveDaemonAssetDir } from "./log.js";
 import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, WINDOWS_TASK_NAME, daemonDir, daemonLogPath, daemonPidPath, } from "./paths.js";
 import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
@@ -123,17 +124,25 @@ function migrateLegacyDaemonUnit(opts) {
         // The rendered command only has to name a binary; install already resolved one.
     }
     if (platform === "darwin") {
-        opts.writeFileSync(unitPath, renderLaunchdPlist(paths), { mode: 0o600 });
+        replaceUnitFile(unitPath, renderLaunchdPlist(paths), 0o600, () => {
+            activateLaunchd(unitPath, asRunCommand(opts.run), opts.uid, { sleep: opts.sleep });
+        });
         return;
     }
     if (platform === "linux") {
-        opts.writeFileSync(unitPath, renderSystemdUserUnit(paths), { mode: 0o600 });
-        opts.run("systemctl", ["--user", "daemon-reload"]);
+        replaceUnitFile(unitPath, renderSystemdUserUnit(paths), 0o600, () => {
+            const result = opts.run("systemctl", ["--user", "daemon-reload"]);
+            if (result.status !== 0)
+                throw new Error("systemctl --user daemon-reload failed while repairing the mesh unit");
+        });
         return;
     }
     const rendered = renderWindowsTaskXml(paths);
-    opts.writeFileSync(unitPath, encodeWindowsTaskXml(rendered));
-    opts.run("schtasks.exe", ["/Create", "/TN", WINDOWS_TASK_NAME, "/XML", unitPath, "/F"]);
+    replaceUnitFile(unitPath, encodeWindowsTaskXml(rendered), 0o600, () => {
+        const result = opts.run("schtasks.exe", ["/Create", "/TN", WINDOWS_TASK_NAME, "/XML", unitPath, "/F"]);
+        if (result.status !== 0)
+            throw new Error("schtasks /Create failed while repairing the mesh unit");
+    });
 }
 /**
  * Restart the installed user daemon after a CLI upgrade. This is deliberately
@@ -155,7 +164,6 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
     const home = opts.home ?? os.homedir();
     const existsSync = opts.existsSync ?? fs.existsSync;
     const readFileSync = opts.readFileSync ?? fs.readFileSync;
-    const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
     const run = opts.run ?? ((command, args) => {
         const result = spawnSync(command, args, { encoding: "utf8" });
         return {
@@ -165,7 +173,17 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
         };
     });
     try {
-        migrateLegacyDaemonUnit({ platform, home, hqRoot: opts.hqRoot, env: opts.env, existsSync, readFileSync, writeFileSync, run });
+        migrateLegacyDaemonUnit({
+            platform,
+            home,
+            hqRoot: opts.hqRoot,
+            env: opts.env,
+            existsSync,
+            readFileSync,
+            run,
+            uid: opts.uid,
+            sleep: opts.sleep,
+        });
         if (platform === "darwin") {
             const plist = path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
             if (!existsSync(plist))
@@ -239,14 +257,46 @@ export function detectPlatform(platform = process.platform) {
  * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
  * binary when both exist.
  */
-export function preferStableHqBinary(entry) {
-    const stale = `${path.sep}toolchain${path.sep}node${path.sep}bin${path.sep}`;
-    const stable = `${path.sep}toolchain${path.sep}npm-global${path.sep}bin${path.sep}`;
-    if (!entry.includes(stale))
-        return entry;
-    const candidate = entry.replace(stale, stable);
-    if (candidate !== entry && fs.existsSync(candidate))
-        return path.resolve(candidate);
+export function preferStableHqBinary(entry, platform = detectPlatform(), existsSync = fs.existsSync) {
+    const api = platform === "win32" ? path.win32 : path;
+    const sep = api.sep;
+    const stale = `${sep}toolchain${sep}node${sep}bin${sep}`;
+    const stable = `${sep}toolchain${sep}npm-global${sep}bin${sep}`;
+    if (entry.includes(stale)) {
+        const candidate = entry.replace(stale, stable);
+        if (candidate !== entry && existsSync(candidate))
+            return api.resolve(candidate);
+    }
+    const normalized = entry.replace(/\\/g, "/");
+    const parts = normalized.split("/").filter(Boolean);
+    let packageAt = -1;
+    for (let i = 0; i < parts.length - 2; i += 1) {
+        if (parts[i]?.toLowerCase() === "node_modules"
+            && parts[i + 1]?.toLowerCase() === "@indigoai-us"
+            && parts[i + 2]?.toLowerCase() === "hq-cli") {
+            packageAt = i;
+            break;
+        }
+    }
+    if (packageAt >= 0) {
+        const prefixParts = parts.slice(0, packageAt);
+        let prefix;
+        if (platform === "win32") {
+            const root = path.win32.parse(entry).root;
+            const rootParts = root.replace(/\\+$/, "").split(/[\\/]+/).filter(Boolean);
+            prefix = path.win32.resolve(root, ...prefixParts.slice(rootParts.length));
+        }
+        else {
+            if (prefixParts.at(-1) === "lib")
+                prefixParts.pop();
+            prefix = path.posix.resolve(`/${prefixParts.join("/")}`);
+        }
+        const shim = platform === "win32"
+            ? path.win32.join(prefix, "hq.cmd")
+            : path.posix.join(prefix, "bin", "hq");
+        if (existsSync(shim))
+            return api.resolve(shim);
+    }
     return entry;
 }
 /**
@@ -346,7 +396,6 @@ export function installDaemonIfStale(opts) {
         platform,
         paths: opts.paths,
         systemUser: opts.systemUser,
-        writeFileSync: opts.writeFileSync,
         mkdirSync: opts.mkdirSync,
         reloadSystemd: opts.reloadSystemd,
         schtasks: opts.schtasks,
@@ -357,9 +406,6 @@ export function installDaemonIfStale(opts) {
         uid: opts.uid,
         sleep: opts.sleep,
     });
-    if (platform === "linux" && !opts.systemUser && !opts.paths.systemUser) {
-        activateSystemd(SYSTEMD_UNIT_NAME, run);
-    }
     return {
         reinstalled: true,
         message: `${installed.message} Restarted with ${opts.paths.nodeBinary} ${opts.paths.hqBinary}.`,
@@ -413,7 +459,8 @@ export function buildInstallPaths(opts) {
     const home = opts.home ?? os.homedir();
     const env = opts.env ?? process.env;
     const ddir = daemonDir(opts.meshRoot, home, env);
-    const hqBinary = opts.hqBinary ?? resolveHqBinary(opts.argv, env);
+    const platform = opts.platform ?? detectPlatform();
+    const hqBinary = preferStableHqBinary(opts.hqBinary ?? resolveHqBinary(opts.argv, env), platform, opts.existsSync ?? fs.existsSync);
     const nodeBinary = opts.nodeBinary ?? resolveNodeBinary(opts.execPath, env);
     return {
         home,
@@ -430,6 +477,7 @@ export function buildInstallPaths(opts) {
         windowsHeadlessLauncher: opts.windowsHeadlessLauncher === undefined
             ? resolveWindowsHeadlessLauncher(env)
             : (opts.windowsHeadlessLauncher ?? undefined),
+        windowsCommandProcessor: path.win32.join(env.SystemRoot ?? "C:\\Windows", "System32", "cmd.exe"),
         systemUser: opts.systemUser,
         hqRoot: opts.hqRoot,
         hqRootSource: opts.hqRootSource,
@@ -480,7 +528,12 @@ export function windowsLogonNotice(paths) {
 function describeWindowsLaunchMode(paths) {
     return windowsLaunchMode(paths) === "conhost-headless"
         ? `mode: conhost --headless via ${paths.windowsHeadlessLauncher}`
-        : "mode: direct node (conhost --headless unavailable on this host; a console window may appear at logon)";
+        : isWindowsCommandShim(paths.hqBinary)
+            ? "mode: direct command processor (conhost --headless unavailable on this host; a console window may appear at logon)"
+            : "mode: direct node (conhost --headless unavailable on this host; a console window may appear at logon)";
+}
+function isWindowsCommandShim(file) {
+    return path.win32.extname(file).toLowerCase() === ".cmd";
 }
 function safeUsername() {
     try {
@@ -601,13 +654,19 @@ WantedBy=multi-user.target
  */
 export function renderWindowsTaskXml(paths) {
     const user = escapeXml(paths.windowsUser);
-    const nodeArg = windowsArgQuote(paths.nodeBinary);
+    const stableShim = isWindowsCommandShim(paths.hqBinary);
     const hqArg = windowsArgQuote(paths.hqBinary);
-    const command = paths.windowsHeadlessLauncher ?? paths.nodeBinary;
+    const commandProcessor = paths.windowsCommandProcessor ?? path.win32.join("C:\\Windows", "System32", "cmd.exe");
+    const command = stableShim ? (paths.windowsHeadlessLauncher ?? commandProcessor) : (paths.windowsHeadlessLauncher ?? paths.nodeBinary);
     const rootArgs = paths.hqRoot ? ` --hq-root ${windowsArgQuote(paths.hqRoot)}` : "";
-    const args = paths.windowsHeadlessLauncher
-        ? `--headless ${nodeArg} ${hqArg} mesh daemon run${rootArgs}`
-        : `${hqArg} mesh daemon run${rootArgs}`;
+    const commandLine = `${hqArg} mesh daemon run${rootArgs}`;
+    const args = stableShim
+        ? paths.windowsHeadlessLauncher
+            ? `--headless ${windowsArgQuote(commandProcessor)} /d /s /c "${commandLine}"`
+            : `/d /s /c "${commandLine}"`
+        : paths.windowsHeadlessLauncher
+            ? `--headless ${windowsArgQuote(paths.nodeBinary)} ${hqArg} mesh daemon run${rootArgs}`
+            : `${hqArg} mesh daemon run${rootArgs}`;
     return `<?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <RegistrationInfo>
@@ -769,7 +828,7 @@ export function parseWindowsTaskHqRoot(xml) {
     if (quoted)
         return quoted[1].replace(/\\"/g, '"');
     const bare = /--hq-root (\S+)/.exec(args);
-    return bare ? bare[1] : null;
+    return bare ? bare[1].replace(/"+$/, "") : null;
 }
 /**
  * The HQ root the installed Windows task actually carries: the task XML on
@@ -812,11 +871,40 @@ function shellQuote(value) {
         return value;
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function replaceUnitFile(file, content, mode, reload) {
+    let previous = null;
+    let previousMode = mode;
+    try {
+        previous = fs.readFileSync(file);
+        previousMode = fs.statSync(file).mode & 0o777;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    try {
+        atomicWrite(file, content, { mode });
+        reload?.();
+    }
+    catch (error) {
+        try {
+            if (previous) {
+                atomicWrite(file, previous, { mode: previousMode });
+            }
+            else {
+                fs.rmSync(file, { force: true });
+            }
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `Unit replacement and rollback failed: ${file}`);
+        }
+        throw error;
+    }
+}
 export function installDaemonService(opts) {
     const platform = opts.platform ?? detectPlatform();
     const paths = opts.paths ??
         buildInstallPaths({ systemUser: opts.systemUser });
-    const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
     const mkdirSync = opts.mkdirSync ?? fs.mkdirSync;
     mkdirSync(paths.daemonDir, { recursive: true, mode: 0o700 });
     registerTrustedHqRoot(paths.daemonDir, paths.hqRoot);
@@ -832,13 +920,12 @@ export function installDaemonService(opts) {
     if (platform === "darwin") {
         const rendered = renderLaunchdPlist(paths);
         mkdirSync(paths.launchAgentsDir, { recursive: true });
-        writeFileSync(paths.plistPath, rendered, { mode: 0o600 });
-        if (opts.run) {
-            activateLaunchd(paths.plistPath, opts.run, opts.uid, { sleep: opts.sleep });
-        }
-        else {
-            opts.activate?.(platform, paths.plistPath);
-        }
+        replaceUnitFile(paths.plistPath, rendered, 0o600, () => {
+            if (opts.run)
+                activateLaunchd(paths.plistPath, opts.run, opts.uid, { sleep: opts.sleep });
+            else
+                opts.activate?.(platform, paths.plistPath);
+        });
         return {
             platform,
             action: "install",
@@ -856,7 +943,7 @@ export function installDaemonService(opts) {
             });
             // Write under daemon dir as a template the operator can sudo-install.
             const dest = path.join(paths.daemonDir, SYSTEMD_UNIT_NAME);
-            writeFileSync(dest, rendered, { mode: 0o644 });
+            replaceUnitFile(dest, rendered, 0o644);
             return {
                 platform,
                 action: "install",
@@ -870,9 +957,18 @@ export function installDaemonService(opts) {
         }
         const rendered = renderSystemdUserUnit(paths);
         mkdirSync(paths.systemdUserDir, { recursive: true });
-        writeFileSync(paths.systemdUnitPath, rendered, { mode: 0o600 });
-        (opts.reloadSystemd ?? (() => spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" })))();
-        opts.activate?.(platform, paths.systemdUnitPath);
+        replaceUnitFile(paths.systemdUnitPath, rendered, 0o600, () => {
+            const result = (opts.reloadSystemd ?? (() => {
+                const reload = spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+                return { status: reload.status };
+            }))();
+            if (result.status !== 0)
+                throw new Error("systemctl --user daemon-reload failed while installing the mesh unit");
+            if (opts.run)
+                activateSystemd(SYSTEMD_UNIT_NAME, opts.run);
+            else
+                opts.activate?.(platform, paths.systemdUnitPath);
+        });
         return {
             platform,
             action: "install",
@@ -885,14 +981,15 @@ export function installDaemonService(opts) {
     if (platform === "win32") {
         const schtasks = opts.schtasks ?? defaultSchtasks;
         const rendered = renderWindowsTaskXml(paths);
-        writeFileSync(paths.windowsTaskXmlPath, encodeWindowsTaskXml(rendered), { mode: 0o600 });
-        const created = schtasks([
-            "/Create", "/TN", WINDOWS_TASK_NAME, "/XML", paths.windowsTaskXmlPath, "/F",
-        ]);
-        if (created.status !== 0) {
-            throw new Error(`schtasks /Create failed for ${WINDOWS_TASK_NAME} (exit ${created.status ?? "signal"}): ` +
-                `${(created.stderr || created.stdout).trim()}`);
-        }
+        replaceUnitFile(paths.windowsTaskXmlPath, encodeWindowsTaskXml(rendered), 0o600, () => {
+            const created = schtasks([
+                "/Create", "/TN", WINDOWS_TASK_NAME, "/XML", paths.windowsTaskXmlPath, "/F",
+            ]);
+            if (created.status !== 0) {
+                throw new Error(`schtasks /Create failed for ${WINDOWS_TASK_NAME} (exit ${created.status ?? "signal"}): ` +
+                    `${(created.stderr || created.stdout).trim()}`);
+            }
+        });
         // /F replaced any previous registration without ending its instance; stop
         // the recorded daemon so the fresh task instance can take the pid lock.
         schtasks(["/End", "/TN", WINDOWS_TASK_NAME]);

package/dist/lib/mesh/project-board.d.ts

@@ -4,6 +4,23 @@ export declare function mergeProjectStories(current: MeshProjectStoryInput[], pl
     resetStatus?: boolean;
 }): MeshProjectStoryInput[];
 export declare function boardStoryStatus(story: MeshProjectStoryInput): string;
+export interface ProjectStoryReconciliation {
+    storyId: string;
+    ledgerState: string | null;
+    expectedBoardStatus: string | null;
+    boardStatus: string | null;
+    boardLedgerState: string | null;
+    stateDrift: boolean;
+    missingOnBoard: boolean;
+    extraOnBoard: boolean;
+}
+export interface ProjectStoryReconciliationReport {
+    mismatches: ProjectStoryReconciliation[];
+    ledgerStateUnsupported: string[];
+    stateDriftCount: number;
+}
+/** Compare one PRD ledger with one Board snapshot without changing either. */
+export declare function reconcileProjectStories(ledger: readonly MeshProjectStoryInput[], board: readonly MeshProjectStoryInput[]): ProjectStoryReconciliationReport;
 /**
  * Keep only prd-sync task_status events whose Board status actually differs.
  * Missing Board rows stay (ensure will add them). Same-status replays of

package/dist/lib/mesh/project-board.js

@@ -36,6 +36,34 @@ export function boardStoryStatus(story) {
         return status;
     return story.passes === true ? "done" : "queued";
 }
+/** Compare one PRD ledger with one Board snapshot without changing either. */
+export function reconcileProjectStories(ledger, board) {
+    const ledgerById = new Map(ledger.map((story) => [story.id, story]));
+    const boardById = new Map(board.map((story) => [story.id, story]));
+    const ids = [...ledgerById.keys(), ...[...boardById.keys()].filter((id) => !ledgerById.has(id))];
+    const ledgerStateUnsupported = [];
+    const mismatches = ids.flatMap((storyId) => {
+        const source = ledgerById.get(storyId);
+        const current = boardById.get(storyId);
+        const expectedBoardStatus = source ? boardStoryStatus(source) : null;
+        const boardStatus = current ? boardStoryStatus(current) : null;
+        const ledgerState = source?.ledgerState ?? null;
+        const boardLedgerState = current?.ledgerState ?? null;
+        const missingOnBoard = Boolean(source && !current);
+        const extraOnBoard = Boolean(current && !source);
+        if (source && ledgerState && current && boardLedgerState === null)
+            ledgerStateUnsupported.push(storyId);
+        const stateDrift = Boolean(source && ledgerState && boardLedgerState !== null && boardLedgerState !== ledgerState);
+        if (!missingOnBoard && !extraOnBoard && boardStatus === expectedBoardStatus && !stateDrift)
+            return [];
+        return [{ storyId, ledgerState, expectedBoardStatus, boardStatus, boardLedgerState, stateDrift, missingOnBoard, extraOnBoard }];
+    });
+    return {
+        mismatches,
+        ledgerStateUnsupported,
+        stateDriftCount: mismatches.filter((mismatch) => mismatch.stateDrift).length,
+    };
+}
 /**
  * Keep only prd-sync task_status events whose Board status actually differs.
  * Missing Board rows stay (ensure will add them). Same-status replays of

package/dist/lib/mesh/story-status.d.ts

@@ -1,6 +1,21 @@
 declare const BOARD_STORY_STATUSES: readonly ["queued", "in_progress", "review", "done"];
 export type BoardStoryStatus = (typeof BOARD_STORY_STATUSES)[number];
+/**
+ * The ledger has more states than the Board. `blocked` and the review states
+ * need attention, while `dropped` is terminal; the Board has only one terminal
+ * column (`done`).
+ */
+export declare const LEDGER_STATES: readonly ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
+export declare const ACCEPTED_LEDGER_STATES: readonly ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped", "in_review", "verification"];
+export declare class UnknownProjectStoryStateError extends Error {
+    readonly source: string;
+    readonly storyId: string;
+    readonly value: unknown;
+    readonly code = "PROJECT_STORY_STATE_INVALID";
+    constructor(source: string, storyId: string, value: unknown);
+}
 export declare function mapSourceStoryStatus(story: {
+    id?: unknown;
     status?: unknown;
     state?: unknown;
 }, source: string): BoardStoryStatus | undefined;
@@ -12,6 +27,7 @@ export declare function mapSourceStoryStatus(story: {
 export declare function mapReaderStoryStatus(story: {
     status?: unknown;
     state?: unknown;
+    ledgerState?: unknown;
 }): string | undefined;
 export {};
 //# sourceMappingURL=story-status.d.ts.map