instar 1.3.40 → 1.3.42

package/dist/core/PostUpdateMigrator.d.ts

@@ -384,6 +384,33 @@ export declare class PostUpdateMigrator {
      * Idempotent: subsequent runs find no legacy key and skip.
      */
     private migrateLegacyMaxSessions;
+    /**
+     * Retire `mentor.dailySpendCapUsd` — a config field that was DECORATIVE (read nowhere
+     * in code; spec MENTOR-LIVE-READINESS §Migration parity called it out as the
+     * silent-dead-config bug we shouldn't repeat at migration time). On a Claude
+     * subscription there's no per-token dollar charge to cap; the real budget is quota-
+     * aware (a separate future PR ships `mentor.stageBTokenCeiling`).
+     *
+     * Behavior:
+     *  - field absent → silent skip
+     *  - field present at the default (0.5) → silent delete (no warning)
+     *  - field present at a NON-default value → delete + LOUD `result.upgraded` entry with
+     *    a REVIEW prefix (operator never set this thinking it was enforced; they deserve
+     *    to know). Don't repeat the original silent-dead-config bug at migration time.
+     * Idempotent via the `_instar_migrations` marker.
+     */
+    private migrateRetireDeadMentorConfig;
+    /**
+     * Retire the legacy `{stateDir}/mentor-outbox/` directory — the file-based mentor
+     * delivery design that Justin's substrate correction replaced (spec MENTOR-LIVE-
+     * READINESS §Migration parity). The new mentor delivery goes through the agent-to-
+     * agent Telegram comms primitive (sendAgentMessage); the outbox files are now dead
+     * state and should be swept so they don't accumulate or mislead a future operator.
+     *
+     * Idempotent via the `_instar_migrations` marker. The first run deletes if present;
+     * subsequent runs are no-ops. Best-effort — a removal failure logs + continues.
+     */
+    private migrateRetireMentorOutbox;
     private migrateSelfKnowledgeTree;
     private migrateGitignore;
     /**

package/dist/core/PostUpdateMigrator.d.ts.map

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

package/dist/core/PostUpdateMigrator.js

@@ -157,6 +157,8 @@ export class PostUpdateMigrator {
         this.migrateSettings(result);
         this.migrateConfig(result);
         this.migrateLegacyMaxSessions(result);
+        this.migrateRetireDeadMentorConfig(result);
+        this.migrateRetireMentorOutbox(result);
         this.migratePrPipelineArtifacts(result);
         this.migrateBackupManifest(result);
         this.migrateGitignore(result);
@@ -3900,6 +3902,141 @@ Create worktrees for collaborator repos with \`instar worktree create <branch>\`
             result.errors.push(`legacy maxSessions migration write: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * Retire `mentor.dailySpendCapUsd` — a config field that was DECORATIVE (read nowhere
+     * in code; spec MENTOR-LIVE-READINESS §Migration parity called it out as the
+     * silent-dead-config bug we shouldn't repeat at migration time). On a Claude
+     * subscription there's no per-token dollar charge to cap; the real budget is quota-
+     * aware (a separate future PR ships `mentor.stageBTokenCeiling`).
+     *
+     * Behavior:
+     *  - field absent → silent skip
+     *  - field present at the default (0.5) → silent delete (no warning)
+     *  - field present at a NON-default value → delete + LOUD `result.upgraded` entry with
+     *    a REVIEW prefix (operator never set this thinking it was enforced; they deserve
+     *    to know). Don't repeat the original silent-dead-config bug at migration time.
+     * Idempotent via the `_instar_migrations` marker.
+     */
+    migrateRetireDeadMentorConfig(result) {
+        const configPath = path.join(this.config.stateDir, 'config.json');
+        if (!fs.existsSync(configPath)) {
+            result.skipped.push('mentor dailySpendCapUsd retirement (config.json not found)');
+            return;
+        }
+        let config;
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch (err) {
+            result.errors.push(`mentor dailySpendCapUsd retirement: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const migrations = (config._instar_migrations ?? []);
+        const marker = 'mentor-dailySpendCapUsd-retire-v1';
+        if (migrations.some(m => m.startsWith(marker))) {
+            result.skipped.push('mentor dailySpendCapUsd retirement (already migrated)');
+            return;
+        }
+        const mentor = config.mentor ?? undefined;
+        if (!mentor || !('dailySpendCapUsd' in mentor)) {
+            // Field never present — mark + skip.
+            migrations.push(`${marker}-${new Date().toISOString()}`);
+            config._instar_migrations = migrations;
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+            result.skipped.push('mentor dailySpendCapUsd retirement (field never present)');
+            return;
+        }
+        const value = mentor.dailySpendCapUsd;
+        const isDefault = value === 0.5;
+        delete mentor.dailySpendCapUsd;
+        config.mentor = mentor;
+        migrations.push(`${marker}-${new Date().toISOString()}`);
+        config._instar_migrations = migrations;
+        try {
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+            if (isDefault) {
+                result.upgraded.push('mentor.dailySpendCapUsd retired (was default 0.5; field was decorative — never read)');
+            }
+            else {
+                // LOUD prefix so the operator notices in post-update output (this is the
+                // "non-silent removal" the spec specifically calls for).
+                result.upgraded.push(`REVIEW: mentor.dailySpendCapUsd=${JSON.stringify(value)} was retired. ` +
+                    `The field was decorative (never enforced) — Echo runs on a Claude subscription, ` +
+                    `so there is no per-token dollar charge to cap. A future update introduces ` +
+                    `mentor.stageBTokenCeiling (quota-aware) as the real replacement. ` +
+                    `If you set this value expecting enforcement, adjust your expectations accordingly.`);
+            }
+        }
+        catch (err) {
+            result.errors.push(`mentor dailySpendCapUsd retirement write: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Retire the legacy `{stateDir}/mentor-outbox/` directory — the file-based mentor
+     * delivery design that Justin's substrate correction replaced (spec MENTOR-LIVE-
+     * READINESS §Migration parity). The new mentor delivery goes through the agent-to-
+     * agent Telegram comms primitive (sendAgentMessage); the outbox files are now dead
+     * state and should be swept so they don't accumulate or mislead a future operator.
+     *
+     * Idempotent via the `_instar_migrations` marker. The first run deletes if present;
+     * subsequent runs are no-ops. Best-effort — a removal failure logs + continues.
+     */
+    migrateRetireMentorOutbox(result) {
+        const configPath = path.join(this.config.stateDir, 'config.json');
+        if (!fs.existsSync(configPath)) {
+            // Still try to retire the outbox if present, even without config.json — but mark
+            // via state-file marker since we can't write to config. Simpler: skip entirely.
+            result.skipped.push('mentor outbox retirement (config.json not found)');
+            return;
+        }
+        let config;
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch (err) {
+            result.errors.push(`mentor outbox retirement: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const migrations = (config._instar_migrations ?? []);
+        const marker = 'mentor-outbox-retire-v1';
+        if (migrations.some(m => m.startsWith(marker))) {
+            result.skipped.push('mentor outbox retirement (already migrated)');
+            return;
+        }
+        const outboxDir = path.join(this.config.stateDir, 'mentor-outbox');
+        let removed = false;
+        let filesRemoved = 0;
+        if (fs.existsSync(outboxDir)) {
+            try {
+                // Count files before removing for the audit entry.
+                try {
+                    filesRemoved = fs.readdirSync(outboxDir).length;
+                }
+                catch { /* ignore, just for the audit */ }
+                SafeFsExecutor.safeRmSync(outboxDir, { recursive: true, force: true, operation: 'migrateRetireMentorOutbox' });
+                removed = true;
+            }
+            catch (err) {
+                result.errors.push(`mentor outbox retirement removeSync failed: ${err instanceof Error ? err.message : String(err)}`);
+                // Don't mark migrated on failure — retry on next run.
+                return;
+            }
+        }
+        migrations.push(`${marker}-${new Date().toISOString()}`);
+        config._instar_migrations = migrations;
+        try {
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+            if (removed) {
+                result.upgraded.push(`mentor-outbox directory retired (removed ${filesRemoved} file(s) — legacy file-based mentor delivery; replaced by the agent-to-agent Telegram comms primitive)`);
+            }
+            else {
+                result.skipped.push('mentor outbox retirement (directory not present; marker set so we don\'t re-check)');
+            }
+        }
+        catch (err) {
+            result.errors.push(`mentor outbox retirement marker write: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     migrateSelfKnowledgeTree(result) {
         const treeFilePath = path.join(this.config.stateDir, 'self-knowledge-tree.json');
         try {