mthds 0.2.1 → 0.3.1

package/dist/agent/commands/upgrade.js

@@ -0,0 +1,155 @@
+/**
+ * mthds-agent upgrade -- upgrade outdated/missing Python binary dependencies.
+ *
+ * Stdout protocol (plain text, consumed by skill upgrade-flow):
+ *   - UPGRADE_NOT_NEEDED          -- all binaries ok
+ *   - UPGRADE_COMPLETE <json>     -- all targets succeeded
+ *   - UPGRADE_PARTIAL <json>      -- some targets succeeded, some failed
+ *   - UPGRADE_FAILED <json>       -- all targets failed
+ *
+ * Architecture: De-duplicates by uv_package to guard against multiple binaries
+ * sharing a PyPI package. Currently pipelex-agent uses "pipelex" and plxt uses
+ * "pipelex-tools", so de-duplication does not trigger — but the guard prevents
+ * double-installs if future binaries share a package. The binary check list
+ * depends on the configured runner: always plxt; add pipelex-agent when
+ * runner === "pipelex".
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { requireUv, uvToolInstallSync } from "../../installer/runtime/installer.js";
+import { checkBinaryVersion } from "../../installer/runtime/version-check.js";
+import { BINARY_RECOVERY } from "../binaries.js";
+import { agentError, AGENT_ERROR_DOMAINS } from "../output.js";
+import { clearCache, ensureStateDir, STATE_DIR } from "../update-cache.js";
+import { clearSnooze } from "../snooze.js";
+import { loadCredentials } from "../../config/credentials.js";
+import { Runners } from "../../runners/types.js";
+function errorMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ── Main ───────────────────────────────────────────────────────────
+export async function agentUpgrade() {
+    // requireUv() — fatal if missing
+    try {
+        requireUv();
+    }
+    catch (err) {
+        agentError(errorMsg(err), "InstallError", {
+            error_domain: AGENT_ERROR_DOMAINS.INSTALL,
+        });
+        return; // unreachable — agentError calls process.exit, but explicit for TypeScript
+    }
+    const creds = loadCredentials();
+    const binaryKeys = ["plxt"];
+    if (creds.runner === Runners.PIPELEX) {
+        binaryKeys.push("pipelex-agent");
+    }
+    // Collect outdated/missing as targets, skip unparseable
+    const targets = [];
+    for (const key of binaryKeys) {
+        const recovery = BINARY_RECOVERY[key];
+        if (!recovery) {
+            process.stderr.write(`Warning: no recovery info for binary "${key}" — skipping upgrade check. This is a bug.\n`);
+            continue;
+        }
+        const check = checkBinaryVersion(recovery);
+        if (check.status === "outdated" || check.status === "missing") {
+            targets.push({
+                binaryKey: key,
+                recovery,
+                oldVersion: check.installed_version,
+            });
+        }
+        // "ok" and "unparseable" are both skipped — unparseable means the binary
+        // exists but we can't parse its version, so don't blindly reinstall.
+    }
+    if (targets.length === 0) {
+        process.stdout.write("UPGRADE_NOT_NEEDED\n");
+        return;
+    }
+    // De-duplicate by uv_package to avoid double-installing shared packages
+    const seen = new Map();
+    for (const t of targets) {
+        if (!seen.has(t.recovery.uv_package)) {
+            seen.set(t.recovery.uv_package, t);
+        }
+    }
+    const uniqueTargets = Array.from(seen.values());
+    // Install each unique uv_package, catching errors per-target
+    const succeeded = new Map();
+    const failed = new Map();
+    for (const target of uniqueTargets) {
+        try {
+            uvToolInstallSync(target.recovery.uv_package, target.recovery.version_constraint);
+            succeeded.set(target.recovery.uv_package, target);
+        }
+        catch (err) {
+            failed.set(target.recovery.uv_package, errorMsg(err));
+        }
+    }
+    // Post-check successful targets to get new version
+    const upgradedEntries = {};
+    for (const [uvPkg, target] of succeeded) {
+        let newVersion = null;
+        try {
+            const postCheck = checkBinaryVersion(target.recovery);
+            if (postCheck.status === "ok" || postCheck.status === "unparseable") {
+                newVersion = postCheck.installed_version;
+            }
+            else if (postCheck.status === "missing") {
+                // PATH issue — binary was installed but not yet visible.
+                // Treat as successful since uvToolInstallSync didn't throw.
+                newVersion = null;
+            }
+            else {
+                // "outdated" — install ran but didn't satisfy the constraint
+                process.stderr.write(`Warning: ${uvPkg} was installed but version ${postCheck.installed_version} still does not meet ${postCheck.version_constraint}.\n`);
+                newVersion = postCheck.installed_version;
+            }
+        }
+        catch (err) {
+            process.stderr.write(`Warning: post-upgrade version check failed for ${uvPkg}: ${errorMsg(err)}.\n`);
+            newVersion = null;
+        }
+        const oldV = target.oldVersion ?? "missing";
+        const newV = newVersion ?? "unknown";
+        upgradedEntries[uvPkg] = `${oldV}->${newV}`;
+    }
+    const failedEntries = Object.fromEntries(failed);
+    // Build marker with old versions keyed by binary name.
+    // The update-check preamble reads and clears this marker to detect a recent upgrade.
+    const markerData = {};
+    for (const target of targets) {
+        // Use binary key as marker key (e.g. "pipelex_agent", "plxt")
+        const markerKey = target.binaryKey.replace(/-/g, "_");
+        markerData[markerKey] = target.oldVersion ?? "missing";
+    }
+    // Determine outcome and emit result
+    const allSucceeded = failed.size === 0;
+    const allFailed = succeeded.size === 0;
+    if (allSucceeded) {
+        // Write marker, clear cache + snooze
+        try {
+            ensureStateDir();
+            writeFileSync(join(STATE_DIR, "just-upgraded-from"), JSON.stringify(markerData), "utf-8");
+        }
+        catch (err) {
+            // Marker write failure should not prevent reporting success
+            process.stderr.write(`Warning: could not write upgrade marker: ${errorMsg(err)}.\n`);
+        }
+        clearCache();
+        clearSnooze();
+        process.stdout.write("UPGRADE_COMPLETE " + JSON.stringify({ upgraded: upgradedEntries }) + "\n");
+    }
+    else if (allFailed) {
+        // Do NOT clear cache/snooze, do NOT write marker
+        process.stdout.write("UPGRADE_FAILED " + JSON.stringify({ failed: failedEntries }) + "\n");
+    }
+    else {
+        // Partial — do NOT clear cache/snooze, do NOT write marker
+        process.stdout.write("UPGRADE_PARTIAL " +
+            JSON.stringify({ upgraded: upgradedEntries, failed: failedEntries }) +
+            "\n");
+    }
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/agent/commands/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/agent/commands/upgrade.ts"],"names":[],"mappings":"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"}

package/dist/agent/passthrough.d.ts

@@ -4,4 +4,5 @@
  */
 export declare function passthrough(bin: string, args: string[], options?: {
     autoInstall?: boolean;
+    skipVersionCheck?: boolean;
 }): void;

package/dist/agent/passthrough.js

@@ -4,39 +4,100 @@
  */
 import { spawnSync } from "node:child_process";
 import { agentError, AGENT_ERROR_DOMAINS } from "./output.js";
-import { BINARY_RECOVERY } from "./binaries.js";
-import { isBinaryInstalled } from "../installer/runtime/check.js";
-import { installPipelexSync, installPlxtSync } from "../installer/runtime/installer.js";
-const AUTO_INSTALL_FN = {
-    pipelex: installPipelexSync,
-    "pipelex-agent": installPipelexSync,
-    plxt: installPlxtSync,
-};
+import { BINARY_RECOVERY, buildInstallCommand } from "./binaries.js";
+import { checkBinaryVersion } from "../installer/runtime/version-check.js";
+import { uvToolInstallSync } from "../installer/runtime/installer.js";
 export function passthrough(bin, args, options) {
     const recovery = BINARY_RECOVERY[bin];
-    // Auto-install: attempt to install the binary before spawning
-    if (options?.autoInstall && recovery?.auto_installable && !isBinaryInstalled(bin)) {
-        const installFn = AUTO_INSTALL_FN[bin];
-        if (installFn) {
-            try {
-                installFn();
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                agentError(`Failed to auto-install ${bin}: ${msg}`, "InstallError", {
-                    error_domain: AGENT_ERROR_DOMAINS.INSTALL,
-                    hint: `Install manually: ${recovery.install_command}`,
-                    recovery,
-                });
-            }
-            // Verify install succeeded
-            if (!isBinaryInstalled(bin)) {
-                agentError(`${bin} was installed but is not reachable in PATH.`, "InstallError", {
-                    error_domain: AGENT_ERROR_DOMAINS.INSTALL,
-                    hint: "You may need to restart your shell or add the install directory to your PATH.",
-                    recovery,
-                });
-            }
+    // Version check runs unconditionally when recovery info exists (unless
+    // explicitly skipped). autoInstall only controls whether to attempt a fix
+    // (install/upgrade). When autoInstall is false and status is missing/outdated,
+    // emit a structured error with install/upgrade instructions.
+    if (!options?.skipVersionCheck && recovery) {
+        const check = checkBinaryVersion(recovery);
+        const autoInstall = options?.autoInstall && recovery.auto_installable;
+        switch (check.status) {
+            case "ok":
+                break;
+            case "missing":
+                if (autoInstall) {
+                    try {
+                        uvToolInstallSync(recovery.uv_package, recovery.version_constraint);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        agentError(`Failed to auto-install ${bin}: ${msg}`, "InstallError", {
+                            error_domain: AGENT_ERROR_DOMAINS.INSTALL,
+                            hint: `Install manually: ${buildInstallCommand(recovery)}`,
+                            recovery,
+                        });
+                    }
+                    // Verify install succeeded and version constraint is satisfied
+                    {
+                        const postCheck = checkBinaryVersion(recovery);
+                        if (postCheck.status === "missing") {
+                            agentError(`${bin} was installed but is not reachable in PATH.`, "InstallError", {
+                                error_domain: AGENT_ERROR_DOMAINS.INSTALL,
+                                hint: "You may need to restart your shell or add the install directory to your PATH.",
+                                recovery,
+                            });
+                        }
+                        else if (postCheck.status !== "ok") {
+                            process.stderr.write(JSON.stringify({
+                                warning: true,
+                                message: `Install of ${bin} may not have taken effect (status: ${postCheck.status}, installed: ${postCheck.installed_version}, needs: ${recovery.version_constraint}).`,
+                            }) + "\n");
+                        }
+                    }
+                }
+                else {
+                    agentError(`${bin} is not installed. Install it to continue.`, "BinaryNotFoundError", {
+                        error_domain: AGENT_ERROR_DOMAINS.BINARY,
+                        hint: `Install: ${buildInstallCommand(recovery)}`,
+                        recovery,
+                    });
+                }
+                break;
+            case "outdated":
+                if (autoInstall) {
+                    try {
+                        uvToolInstallSync(recovery.uv_package, recovery.version_constraint);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        agentError(`Failed to upgrade ${bin} (installed ${check.installed_version}, needs ${recovery.version_constraint}): ${msg}`, "InstallError", {
+                            error_domain: AGENT_ERROR_DOMAINS.INSTALL,
+                            hint: `Upgrade manually: ${buildInstallCommand(recovery)}`,
+                            recovery,
+                        });
+                    }
+                    // Verify upgrade actually satisfied the constraint
+                    {
+                        const recheck = checkBinaryVersion(recovery);
+                        if (recheck.status !== "ok") {
+                            process.stderr.write(JSON.stringify({
+                                warning: true,
+                                message: `Upgrade of ${bin} may not have taken effect (status: ${recheck.status}, installed: ${recheck.installed_version}, needs: ${recovery.version_constraint}).`,
+                            }) + "\n");
+                        }
+                    }
+                }
+                else {
+                    agentError(`${bin} is outdated (installed ${check.installed_version}, needs ${recovery.version_constraint}). Upgrade to continue.`, "InstallError", {
+                        error_domain: AGENT_ERROR_DOMAINS.INSTALL,
+                        hint: `Upgrade: ${buildInstallCommand(recovery)}`,
+                        recovery,
+                    });
+                }
+                break;
+            case "unparseable":
+                // Warn to stderr but don't block execution
+                process.stderr.write(JSON.stringify({
+                    warning: true,
+                    message: `Could not parse version for ${bin}. Proceeding anyway.`,
+                    version_constraint: check.version_constraint,
+                }) + "\n");
+                break;
         }
     }
     const result = spawnSync(bin, args, {
@@ -45,7 +106,7 @@ export function passthrough(bin, args, options) {
     if (result.error) {
         if (result.error.code === "ENOENT") {
             const hint = recovery
-                ? `Install ${recovery.package}: ${recovery.install_command}`
+                ? `Install ${recovery.package}: ${buildInstallCommand(recovery)}`
                 : "Make sure the required CLI binary is installed and in your PATH.";
             agentError(`${bin} not found. Make sure it is installed and in your PATH.`, "BinaryNotFoundError", {
                 error_domain: AGENT_ERROR_DOMAINS.BINARY,

package/dist/agent/passthrough.js.map

@@ -1 +1 @@
-{"version":3,"file":"passthrough.js","sourceRoot":"","sources":["../../src/agent/passthrough.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAExF,MAAM,eAAe,GAA+B;IAClD,OAAO,EAAE,kBAAkB;IAC3B,eAAe,EAAE,kBAAkB;IACnC,IAAI,EAAE,eAAe;CACtB,CAAC;AAEF,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,IAAc,EACd,OAAmC;IAEnC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAEtC,8DAA8D;IAC9D,IAAI,OAAO,EAAE,WAAW,IAAI,QAAQ,EAAE,gBAAgB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAClF,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,SAAS,EAAE,CAAC;YACd,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7D,UAAU,CACR,0BAA0B,GAAG,KAAK,GAAG,EAAE,EACvC,cAAc,EACd;oBACE,YAAY,EAAE,mBAAmB,CAAC,OAAO;oBACzC,IAAI,EAAE,qBAAqB,QAAQ,CAAC,eAAe,EAAE;oBACrD,QAAQ;iBACT,CACF,CAAC;YACJ,CAAC;YACD,2BAA2B;YAC3B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,UAAU,CACR,GAAG,GAAG,8CAA8C,EACpD,cAAc,EACd;oBACE,YAAY,EAAE,mBAAmB,CAAC,OAAO;oBACzC,IAAI,EAAE,+EAA+E;oBACrF,QAAQ;iBACT,CACF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE;QAClC,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,IAAK,MAAM,CAAC,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAG,QAAQ;gBACnB,CAAC,CAAC,WAAW,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,eAAe,EAAE;gBAC5D,CAAC,CAAC,kEAAkE,CAAC;YACvE,UAAU,CACR,GAAG,GAAG,yDAAyD,EAC/D,qBAAqB,EACrB;gBACE,YAAY,EAAE,mBAAmB,CAAC,MAAM;gBACxC,IAAI;gBACJ,QAAQ;aACT,CACF,CAAC;QACJ,CAAC;QACD,UAAU,CACR,mBAAmB,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EACjD,kBAAkB,EAClB,EAAE,YAAY,EAAE,mBAAmB,CAAC,MAAM,EAAE,CAC7C,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"passthrough.js","sourceRoot":"","sources":["../../src/agent/passthrough.ts"],"names":[],"mappings":"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"}

package/dist/agent/snooze.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Snooze state for update-check upgrade prompts.
+ *
+ * Manages ~/.mthds/state/update-snoozed — a single-line file:
+ *   <versionKey> <level> <epoch>
+ *
+ * Version key is a plain concatenation of binary statuses (human-readable).
+ * Escalating backoff: level 1 = 24h, level 2 = 48h, level 3+ = 7d.
+ * Snooze resets when the version key changes (any binary constraint updated).
+ */
+import type { CachePayload } from "./update-cache.js";
+export interface SnoozeState {
+    versionKey: string;
+    level: number;
+    epoch: number;
+}
+/**
+ * Compute a human-readable version key from a cache payload.
+ * Format: "status1:status2:status3" with constraints appended for non-ok entries.
+ * Changes whenever any binary's status or constraint changes.
+ */
+export declare function computeVersionKey(payload: CachePayload): string;
+/** Read current snooze state. Returns null if missing or corrupt. */
+export declare function readSnooze(): SnoozeState | null;
+/**
+ * Write snooze state. Escalates level if same versionKey, resets if different.
+ */
+export declare function writeSnooze(versionKey: string): void;
+/** Check if snooze is active for the given versionKey. */
+export declare function isSnoozed(versionKey: string): boolean;
+/** Clear snooze file. */
+export declare function clearSnooze(): void;

package/dist/agent/snooze.js

@@ -0,0 +1,108 @@
+/**
+ * Snooze state for update-check upgrade prompts.
+ *
+ * Manages ~/.mthds/state/update-snoozed — a single-line file:
+ *   <versionKey> <level> <epoch>
+ *
+ * Version key is a plain concatenation of binary statuses (human-readable).
+ * Escalating backoff: level 1 = 24h, level 2 = 48h, level 3+ = 7d.
+ * Snooze resets when the version key changes (any binary constraint updated).
+ */
+import { join } from "node:path";
+import { readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { STATE_DIR, ensureStateDir } from "./update-cache.js";
+// ── Constants ──────────────────────────────────────────────────────
+const SNOOZE_PATH = join(STATE_DIR, "update-snoozed");
+const SNOOZE_DURATIONS_MS = {
+    1: 24 * 60 * 60 * 1000, // 24h
+    2: 48 * 60 * 60 * 1000, // 48h
+};
+const SNOOZE_DEFAULT_MS = 7 * 24 * 60 * 60 * 1000; // 7d for level 3+
+// ── Functions ──────────────────────────────────────────────────────
+/**
+ * Compute a human-readable version key from a cache payload.
+ * Format: "status1:status2:status3" with constraints appended for non-ok entries.
+ * Changes whenever any binary's status or constraint changes.
+ */
+export function computeVersionKey(payload) {
+    const parts = [
+        payload.mthds_agent.s + (payload.mthds_agent.r ?? ""),
+    ];
+    if (payload.pipelex_agent) {
+        parts.push(payload.pipelex_agent.s + (payload.pipelex_agent.r ?? ""));
+    }
+    parts.push(payload.plxt.s + (payload.plxt.r ?? ""));
+    return parts.join(":");
+}
+/** Read current snooze state. Returns null if missing or corrupt. */
+export function readSnooze() {
+    let content;
+    try {
+        content = readFileSync(SNOOZE_PATH, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+    // Format: "<versionKey> <level> <epoch>"
+    // The version key may contain colons but not spaces, so split from the right.
+    const lastSpace = content.lastIndexOf(" ");
+    if (lastSpace === -1)
+        return null;
+    const epochStr = content.slice(lastSpace + 1);
+    const rest = content.slice(0, lastSpace);
+    const secondLastSpace = rest.lastIndexOf(" ");
+    if (secondLastSpace === -1)
+        return null;
+    const versionKey = rest.slice(0, secondLastSpace);
+    const levelStr = rest.slice(secondLastSpace + 1);
+    const level = parseInt(levelStr, 10);
+    const epoch = parseInt(epochStr, 10);
+    if (isNaN(level) || isNaN(epoch) || level <= 0 || !versionKey)
+        return null;
+    return { versionKey, level, epoch };
+}
+/**
+ * Write snooze state. Escalates level if same versionKey, resets if different.
+ */
+export function writeSnooze(versionKey) {
+    ensureStateDir();
+    const existing = readSnooze();
+    let level;
+    if (existing && existing.versionKey === versionKey) {
+        level = existing.level + 1;
+    }
+    else {
+        level = 1;
+    }
+    const content = `${versionKey} ${level} ${Date.now()}\n`;
+    try {
+        writeFileSync(SNOOZE_PATH, content, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        process.stderr.write(`Warning: could not write snooze state (${code ?? String(err)}).\n`);
+    }
+}
+/** Check if snooze is active for the given versionKey. */
+export function isSnoozed(versionKey) {
+    const state = readSnooze();
+    if (!state)
+        return false;
+    // Different version key means the constraint changed — snooze is invalid
+    if (state.versionKey !== versionKey)
+        return false;
+    const duration = SNOOZE_DURATIONS_MS[state.level] ?? SNOOZE_DEFAULT_MS;
+    const elapsed = Date.now() - state.epoch;
+    // Negative elapsed beyond 1 minute means clock skew — treat snooze as expired
+    return elapsed >= -60_000 && elapsed < duration;
+}
+/** Clear snooze file. */
+export function clearSnooze() {
+    try {
+        unlinkSync(SNOOZE_PATH);
+    }
+    catch {
+        // File may not exist — that's fine
+    }
+}
+//# sourceMappingURL=snooze.js.map

package/dist/agent/snooze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snooze.js","sourceRoot":"","sources":["../../src/agent/snooze.ts"],"names":[],"mappings":"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"}

package/dist/agent/update-cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cache for update-check results.
+ *
+ * Manages ~/.mthds/state/last-update-check — a two-line file:
+ *   Line 1: aggregate status (UP_TO_DATE or UPGRADE_AVAILABLE)
+ *   Line 2: JSON payload with per-binary check results
+ *
+ * TTL is based on file mtime (like gstack), not an embedded timestamp.
+ * Split TTL: 60 min for UP_TO_DATE, 720 min for UPGRADE_AVAILABLE.
+ */
+import type { VersionStatus } from "../installer/runtime/version-check.js";
+export type AggregateStatus = "UP_TO_DATE" | "UPGRADE_AVAILABLE";
+export interface BinaryCheckEntry {
+    /** Version status: "ok", "outdated", "missing", "unparseable" */
+    s: VersionStatus;
+    /** Installed version, or null */
+    v: string | null;
+    /** Required constraint (present when s !== "ok") */
+    r?: string;
+}
+export interface CachePayload {
+    mthds_agent: BinaryCheckEntry;
+    pipelex_agent?: BinaryCheckEntry;
+    plxt: BinaryCheckEntry;
+}
+export interface CacheResult {
+    aggregate: AggregateStatus;
+    payload: CachePayload;
+}
+export declare const STATE_DIR: string;
+/** Ensure the state directory exists. */
+export declare function ensureStateDir(): void;
+/** Compute aggregate status from a payload. */
+export declare function computeAggregate(payload: CachePayload): AggregateStatus;
+/**
+ * Read the update-check cache.
+ * Returns null if the file is missing, corrupt, or expired.
+ */
+export declare function readCache(): CacheResult | null;
+/** Write cache. Creates state directory if needed. */
+export declare function writeCache(result: CacheResult): void;
+/** Delete cache file (used by --force and after upgrade). */
+export declare function clearCache(): void;

package/dist/agent/update-cache.js

@@ -0,0 +1,125 @@
+/**
+ * Cache for update-check results.
+ *
+ * Manages ~/.mthds/state/last-update-check — a two-line file:
+ *   Line 1: aggregate status (UP_TO_DATE or UPGRADE_AVAILABLE)
+ *   Line 2: JSON payload with per-binary check results
+ *
+ * TTL is based on file mtime (like gstack), not an embedded timestamp.
+ * Split TTL: 60 min for UP_TO_DATE, 720 min for UPGRADE_AVAILABLE.
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, } from "node:fs";
+// ── Constants ──────────────────────────────────────────────────────
+export const STATE_DIR = join(homedir(), ".mthds", "state");
+const CACHE_PATH = join(STATE_DIR, "last-update-check");
+const TTL_UP_TO_DATE_MS = 60 * 60 * 1000; // 60 min
+const TTL_UPGRADE_AVAILABLE_MS = 720 * 60 * 1000; // 720 min (12 hours)
+const VALID_AGGREGATES = new Set([
+    "UP_TO_DATE",
+    "UPGRADE_AVAILABLE",
+]);
+// ── Validation ──────────────────────────────────────────────────────
+function isValidPayload(p) {
+    if (!p || typeof p !== "object")
+        return false;
+    const obj = p;
+    // mthds_agent and plxt are always required
+    for (const key of ["mthds_agent", "plxt"]) {
+        const entry = obj[key];
+        if (!entry || typeof entry !== "object")
+            return false;
+        if (typeof entry.s !== "string")
+            return false;
+    }
+    // pipelex_agent is optional, but if present must be valid
+    if (obj.pipelex_agent !== undefined) {
+        const entry = obj.pipelex_agent;
+        if (!entry || typeof entry !== "object")
+            return false;
+        if (typeof entry.s !== "string")
+            return false;
+    }
+    return true;
+}
+// ── Functions ──────────────────────────────────────────────────────
+/** Ensure the state directory exists. */
+export function ensureStateDir() {
+    mkdirSync(STATE_DIR, { recursive: true });
+}
+/** Compute aggregate status from a payload. */
+export function computeAggregate(payload) {
+    const entries = [payload.mthds_agent, payload.plxt];
+    if (payload.pipelex_agent)
+        entries.push(payload.pipelex_agent);
+    // Treat "unparseable" same as "ok" — the binary exists, we just can't parse
+    // its version. Treating it as UPGRADE_AVAILABLE would cause an infinite loop:
+    // preamble says upgrade available -> upgrade skips unparseable -> repeat.
+    return entries.every((e) => e.s === "ok" || e.s === "unparseable")
+        ? "UP_TO_DATE"
+        : "UPGRADE_AVAILABLE";
+}
+/**
+ * Read the update-check cache.
+ * Returns null if the file is missing, corrupt, or expired.
+ */
+export function readCache() {
+    // Stat first so worst-case TOCTOU treats fresh data as stale (safe direction)
+    let mtimeMs;
+    let content;
+    try {
+        mtimeMs = statSync(CACHE_PATH).mtimeMs;
+        content = readFileSync(CACHE_PATH, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const lines = content.split("\n");
+    if (lines.length < 2)
+        return null;
+    const aggregate = lines[0].trim();
+    if (!VALID_AGGREGATES.has(aggregate))
+        return null;
+    let payload;
+    try {
+        const parsed = JSON.parse(lines[1]);
+        if (!isValidPayload(parsed))
+            return null;
+        payload = parsed;
+    }
+    catch {
+        return null;
+    }
+    // Check TTL based on file mtime
+    const ttl = aggregate === "UP_TO_DATE"
+        ? TTL_UP_TO_DATE_MS
+        : TTL_UPGRADE_AVAILABLE_MS;
+    const age = Date.now() - mtimeMs;
+    // Negative age beyond 1 minute means clock skew — treat as expired
+    if (age < -60_000 || age > ttl)
+        return null;
+    return { aggregate: aggregate, payload };
+}
+/** Write cache. Creates state directory if needed. */
+export function writeCache(result) {
+    try {
+        ensureStateDir();
+        const content = result.aggregate + "\n" + JSON.stringify(result.payload) + "\n";
+        writeFileSync(CACHE_PATH, content, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        process.stderr.write(`Warning: could not write update-check cache (${code ?? String(err)}). Check will run again next time.\n`);
+    }
+}
+/** Delete cache file (used by --force and after upgrade). */
+export function clearCache() {
+    try {
+        unlinkSync(CACHE_PATH);
+    }
+    catch {
+        // File may not exist — that's fine
+    }
+}
+//# sourceMappingURL=update-cache.js.map