instar 1.2.36 → 1.2.37

package/dist/core/version-skew.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-skew.d.ts","sourceRoot":"","sources":["../../src/core/version-skew.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,cAAc,GAAG,YAAY,GAAG,gCAAgC,CAAC;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CASzG;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,WAAW,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IAClD,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,GAAG,eAAe,GAAG,gBAAgB,CA6ChH;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,qBAAqB,GAAG,IAAI,CAkBlH;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGjE;AAED,8DAA8D;AAC9D,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/core/version-skew.js

@@ -0,0 +1,144 @@
+/**
+ * Version-skew detection + lifeline-restart signal coordination.
+ *
+ * The signal file `state/lifeline-restart-requested.json` is written by THREE
+ * independent channels (no single-point-of-failure):
+ *
+ *   1. AutoUpdater.requestRestart — when an apply crosses major.minor.
+ *   2. Server /internal/telegram-forward 426 handler — direct evidence of skew.
+ *   3. PostUpdateMigrator — one-time bootstrap nudge for currently-stuck lifelines.
+ *
+ * The signal is consumed by THREE independent readers:
+ *
+ *   1. TelegramLifeline tick loop — calls initiateRestart('plannedUpgrade').
+ *   2. ServerSupervisor poll — force-restarts the lifeline if its tick hasn't
+ *      acted within 60s of the signal write.
+ *   3. (Future) v3 Remediator probe — absorbs both channels.
+ *
+ * Spec: docs/specs/auto-updater-lifeline-coordination.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+const SIGNAL_RELPATH = path.join('state', 'lifeline-restart-requested.json');
+/**
+ * Predicate: does going from `prev` to `next` cross a major.minor boundary?
+ *
+ * Examples:
+ *   crossesBreaking('1.1.0', '1.2.28') === true   // minor crossed
+ *   crossesBreaking('1.2.0', '1.2.28') === false  // same major.minor
+ *   crossesBreaking('1.2.28', '2.0.0') === true   // major crossed
+ *   crossesBreaking('1.2.28', '1.2.28') === false // identity
+ *
+ * Malformed inputs are treated as breaking (fail safe — prefer over-signal
+ * to under-signal, since the consequence of false-positive is a single
+ * harmless lifeline restart, and the consequence of false-negative is the
+ * exact incident class we're closing).
+ */
+export function crossesBreaking(prev, next) {
+    if (!prev || !next)
+        return true;
+    const semverRe = /^(\d+)\.(\d+)\./;
+    const mp = semverRe.exec(prev);
+    const mn = semverRe.exec(next);
+    if (!mp || !mn)
+        return true;
+    const [, pMaj, pMin] = mp;
+    const [, nMaj, nMin] = mn;
+    return pMaj !== nMaj || pMin !== nMin;
+}
+/**
+ * Write the lifeline-restart signal atomically. Idempotent: if a non-expired
+ * signal already exists for the SAME targetVersion, no-ops.
+ *
+ * Returns 'written' / 'skipped-fresh' / 'replaced-stale'.
+ */
+export function writeLifelineRestartSignal(opts) {
+    const now = opts.now ?? Date.now();
+    const ttlMs = opts.ttlMs ?? 60 * 60 * 1000;
+    const signalPath = path.join(opts.stateDir, SIGNAL_RELPATH);
+    // Idempotency: if an existing signal targets the same version and hasn't
+    // expired, don't overwrite. This prevents duplicate audit-log entries when
+    // multiple writers fire on the same boundary crossing.
+    let outcome = 'written';
+    try {
+        const existing = JSON.parse(fs.readFileSync(signalPath, 'utf-8'));
+        const existingExpires = Date.parse(existing.expiresAt);
+        if (existing.targetVersion === opts.targetVersion &&
+            Number.isFinite(existingExpires) &&
+            existingExpires > now) {
+            return 'skipped-fresh';
+        }
+        outcome = 'replaced-stale';
+    }
+    catch {
+        // No existing signal or unreadable — proceed to write a fresh one.
+    }
+    const signal = {
+        requestedAt: new Date(now).toISOString(),
+        requestedBy: opts.requestedBy,
+        reason: opts.reason,
+        previousVersion: opts.previousVersion,
+        targetVersion: opts.targetVersion,
+        expiresAt: new Date(now + ttlMs).toISOString(),
+    };
+    // Atomic write: tmp + rename to defend against partial reads under race.
+    const dir = path.dirname(signalPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = `${signalPath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(signal, null, 2));
+        fs.renameSync(tmpPath, signalPath);
+    }
+    catch (err) {
+        try {
+            SafeFsExecutor.safeUnlinkSync(tmpPath, { operation: 'src/core/version-skew.ts:writeLifelineRestartSignal-cleanup' });
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+    return outcome;
+}
+/**
+ * Read the signal. Returns null if missing, malformed, or expired.
+ * The reader is expected to delete the file as the first step of acting on it
+ * (so a respawn doesn't re-fire on the same signal).
+ */
+export function readLifelineRestartSignal(stateDir, now = Date.now()) {
+    const signalPath = path.join(stateDir, SIGNAL_RELPATH);
+    let raw;
+    try {
+        raw = fs.readFileSync(signalPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Corrupt → treat as absent. The next write replaces it cleanly.
+        return null;
+    }
+    const expires = Date.parse(parsed.expiresAt);
+    if (!Number.isFinite(expires) || expires <= now)
+        return null;
+    return parsed;
+}
+/**
+ * Delete the signal. Called by readers as the first step of acting on the
+ * signal so a restart loop can't re-fire on the same write.
+ */
+export function clearLifelineRestartSignal(stateDir) {
+    const signalPath = path.join(stateDir, SIGNAL_RELPATH);
+    try {
+        SafeFsExecutor.safeUnlinkSync(signalPath, { operation: 'src/core/version-skew.ts:clearLifelineRestartSignal' });
+    }
+    catch { /* ok — already gone */ }
+}
+/** Absolute path of the signal file for a given state dir. */
+export function lifelineRestartSignalPath(stateDir) {
+    return path.join(stateDir, SIGNAL_RELPATH);
+}
+//# sourceMappingURL=version-skew.js.map

package/dist/core/version-skew.js.map

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

package/dist/lifeline/RestartOrchestrator.d.ts

@@ -22,7 +22,7 @@ import { DegradationReporter } from '../monitoring/DegradationReporter.js';
 export type RestartState = 'idle' | 'quiescing' | 'persisting' | 'exiting';
 export interface RestartRequest {
     reason: string;
-    bucket: 'watchdog' | 'versionSkew';
+    bucket: 'watchdog' | 'versionSkew' | 'plannedUpgrade';
     context?: Record<string, unknown>;
 }
 export interface OrchestratorDeps {

package/dist/lifeline/RestartOrchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RestartOrchestrator.d.ts","sourceRoot":"","sources":["../../src/lifeline/RestartOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,qGAAqG;IACrG,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,wEAAwE;IACxE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,qEAAqE;IACrE,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,OAAO,CAAC;IACxC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,mBAAmB;IAOlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAC7B,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,YAAY,CAAA;KAAE,GAAG,IAAI,CAAQ;gBAEvD,IAAI,EAAE,gBAAgB;IAMnD,IAAI,KAAK,IAAI,YAAY,CAExB;IAED;;;;OAIG;IACG,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,GAAG,WAAW,CAAC;IAuF9E,4EAA4E;IAC5E,gBAAgB,IAAI,IAAI;CAIzB"}
+{"version":3,"file":"RestartOrchestrator.d.ts","sourceRoot":"","sources":["../../src/lifeline/RestartOrchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,gBAAgB,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,qGAAqG;IACrG,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,wEAAwE;IACxE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,qEAAqE;IACrE,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,OAAO,CAAC;IACxC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,mBAAmB;IAOlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAC7B,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,YAAY,CAAA;KAAE,GAAG,IAAI,CAAQ;gBAEvD,IAAI,EAAE,gBAAgB;IAMnD,IAAI,KAAK,IAAI,YAAY,CAExB;IAED;;;;OAIG;IACG,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,GAAG,WAAW,CAAC;IAuF9E,4EAA4E;IAC5E,gBAAgB,IAAI,IAAI;CAIzB"}

package/dist/lifeline/TelegramLifeline.d.ts

@@ -38,6 +38,7 @@ export declare class TelegramLifeline {
     private offsetPath;
     private stopHeartbeat;
     private replayInterval;
+    private restartSignalInterval;
     private lifelineTopicId;
     private lockPath;
     private consecutive409s;
@@ -136,6 +137,19 @@ export declare class TelegramLifeline {
      * match (loopback impostor), treat as transient.
      */
     private handleVersionSkew;
+    /**
+     * Per-tick check of the coordinated-restart signal file.
+     *
+     * Three independent writers (AutoUpdater on major.minor crossing; the
+     * server on a 426 forward; PostUpdateMigrator's one-time stale-lifeline
+     * bootstrap) drop a signal at `state/lifeline-restart-requested.json`.
+     * We read it, validate, delete it (so a respawn doesn't re-fire), and
+     * call initiateRestart on the `plannedUpgrade` bucket which bypasses
+     * the watchdog cooldown.
+     *
+     * Spec: docs/specs/auto-updater-lifeline-coordination.md
+     */
+    private checkLifelineRestartSignal;
     /** Watchdog-tracked counters/state. */
     private consecutiveForwardFailures;
     private lastForwardSuccessAt;

package/dist/lifeline/TelegramLifeline.d.ts.map

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

package/dist/lifeline/TelegramLifeline.js

@@ -36,6 +36,7 @@ import pc from 'picocolors';
 import { loadConfig, ensureStateDir, detectTmuxPath, getInstarVersion } from '../core/Config.js';
 import { registerAgent, unregisterAgent, startHeartbeat } from '../core/AgentRegistry.js';
 import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
+import { readLifelineRestartSignal, clearLifelineRestartSignal, } from '../core/version-skew.js';
 // setup.ts uses @inquirer/prompts which requires Node 20.12+
 // Dynamic import to avoid breaking the lifeline on older Node versions
 // import { installAutoStart } from '../commands/setup.js';
@@ -199,6 +200,7 @@ export class TelegramLifeline {
     offsetPath;
     stopHeartbeat = null;
     replayInterval = null;
+    restartSignalInterval = null;
     lifelineTopicId = null;
     lockPath;
     consecutive409s = 0;
@@ -360,6 +362,19 @@ export class TelegramLifeline {
                 this.replayQueue();
             }
         }, 15_000);
+        // Coordinated restart channel: every 30s, check for a lifeline-restart
+        // signal written by the AutoUpdater (major.minor crossing), the server
+        // (426 evidence), or the PostUpdateMigrator (one-time stale-lifeline
+        // bootstrap). On match, restart via the planned-upgrade bucket which
+        // bypasses the watchdog cooldown.
+        // Spec: docs/specs/auto-updater-lifeline-coordination.md
+        this.restartSignalInterval = setInterval(() => {
+            this.checkLifelineRestartSignal();
+        }, 30_000);
+        // Run once immediately so a fresh lifeline picks up a signal written
+        // before it started (e.g. by PostUpdateMigrator during the previous
+        // launchctl cycle).
+        this.checkLifelineRestartSignal();
         // Stage B: install the restart orchestrator and health watchdog.
         // In unsupervised mode (no INSTAR_SUPERVISED=1 and no launchd parent),
         // the orchestrator emits signals and logs but skips process.exit.
@@ -429,6 +444,10 @@ export class TelegramLifeline {
             clearInterval(this.replayInterval);
             this.replayInterval = null;
         }
+        if (this.restartSignalInterval) {
+            clearInterval(this.restartSignalInterval);
+            this.restartSignalInterval = null;
+        }
         if (this.watchdog)
             this.watchdog.stop();
         try {
@@ -1161,6 +1180,47 @@ export class TelegramLifeline {
             lifelineVersion: this.lifelineVersion,
         });
     }
+    /**
+     * Per-tick check of the coordinated-restart signal file.
+     *
+     * Three independent writers (AutoUpdater on major.minor crossing; the
+     * server on a 426 forward; PostUpdateMigrator's one-time stale-lifeline
+     * bootstrap) drop a signal at `state/lifeline-restart-requested.json`.
+     * We read it, validate, delete it (so a respawn doesn't re-fire), and
+     * call initiateRestart on the `plannedUpgrade` bucket which bypasses
+     * the watchdog cooldown.
+     *
+     * Spec: docs/specs/auto-updater-lifeline-coordination.md
+     */
+    checkLifelineRestartSignal() {
+        let signal;
+        try {
+            signal = readLifelineRestartSignal(this.projectConfig.stateDir);
+        }
+        catch (err) {
+            console.warn(`[Lifeline] failed to read restart signal: ${err}`);
+            return;
+        }
+        if (!signal)
+            return;
+        // Same-version no-op: a respawned lifeline that already matches the
+        // target version should clear the stale signal and not loop.
+        if (signal.targetVersion === this.lifelineVersion) {
+            clearLifelineRestartSignal(this.projectConfig.stateDir);
+            return;
+        }
+        // First step: delete the file. If initiateRestart goes through, the
+        // process exits and a fresh lifeline starts on the new version — it
+        // must not re-read the same signal.
+        clearLifelineRestartSignal(this.projectConfig.stateDir);
+        console.log(`[Lifeline] coordinated restart signal received from ${signal.requestedBy}: ` +
+            `v${signal.previousVersion} → v${signal.targetVersion} (${signal.reason})`);
+        this.initiateRestart('plannedUpgrade', signal.reason, {
+            requestedBy: signal.requestedBy,
+            previousVersion: signal.previousVersion,
+            targetVersion: signal.targetVersion,
+        });
+    }
     /** Watchdog-tracked counters/state. */
     consecutiveForwardFailures = 0;
     lastForwardSuccessAt = 0;