instar 0.28.102 → 0.28.103

package/dist/core/PostUpdateMigrator.js

@@ -27,15 +27,60 @@ import { TreeGenerator } from '../knowledge/TreeGenerator.js';
 import { HTTP_HOOK_TEMPLATES, buildHttpHookSettings } from '../data/http-hook-templates.js';
 import { getMigrationDefaults, applyDefaults } from '../config/ConfigDefaults.js';
 import { installBuiltinSkills } from '../commands/init.js';
+import { installBuiltinJobs } from '../scheduler/InstallBuiltinJobs.js';
+import { jobsMigrate } from '../commands/jobMigrate.js';
+import { snapshotUserNamespace, verifyMigrationInvariants } from '../scheduler/MigrationInvariants.js';
+import { appendMigrationEvent, normalizePerEntryAction } from '../scheduler/MigrationLedger.js';
+import { randomUUID } from 'node:crypto';
 import { ELIGIBILITY_SCHEMA_SQL, ELIGIBILITY_SCHEMA_SQL_SHA256, PUSH_GATE_SH, PUSH_GATE_SH_SHA256, INSTAR_PR_GATE_WORKFLOW_YML, INSTAR_PR_GATE_WORKFLOW_YML_SHA256, PR_GATE_SETUP_MD, PR_GATE_SETUP_MD_SHA256, } from '../data/pr-gate-artifacts.js';
 import { SafeFsExecutor } from './SafeFsExecutor.js';
 import { DegradationReporter } from '../monitoring/DegradationReporter.js';
+import { MigratorStepEngine, } from './MigratorStepEngine.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export class PostUpdateMigrator {
     config;
+    /**
+     * F-7 atomic-step engine. Lazily constructed on first access via
+     * `getStepEngine()` so existing callers that never touch atomic steps
+     * pay zero cost. See `src/core/MigratorStepEngine.ts` for the primitive
+     * docs; see `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §A35/§A50
+     * for the spec.
+     */
+    stepEngine;
     constructor(config) {
         this.config = config;
     }
+    /**
+     * F-7 atomic-step primitive: register a step that will run once on
+     * the release boundary where `step.version <= toVersion`. Idempotent
+     * across runs — the engine records every step's outcome in
+     * `<stateDir>/migrator-steps-completed.json` keyed by
+     * `<version>:<step-name>`.
+     *
+     * Steps are atomic and self-contained: a failure in one step does not
+     * roll back prior steps and does not block subsequent steps.
+     *
+     * See `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §A35 + §A50.
+     */
+    registerStep(step) {
+        this.getStepEngine().registerStep(step);
+    }
+    /**
+     * F-7 atomic-step primitive: execute every pending step. Pending =
+     * step.version <= toVersion AND no ledger entry recorded yet.
+     *
+     * Steps run in registration order. Failures are recorded (never
+     * thrown) and do not stop subsequent steps.
+     */
+    async runPendingSteps(fromVersion, toVersion) {
+        return this.getStepEngine().runPendingSteps(fromVersion, toVersion);
+    }
+    getStepEngine() {
+        if (!this.stepEngine) {
+            this.stepEngine = new MigratorStepEngine(this.config.stateDir);
+        }
+        return this.stepEngine;
+    }
     /**
      * Run all post-update migrations. Safe to call multiple times —
      * each migration is idempotent.
@@ -55,6 +100,8 @@ export class PostUpdateMigrator {
         this.migrateBackupManifest(result);
         this.migrateGitignore(result);
         this.migrateBuiltinSkills(result);
+        this.migrateBuiltinJobs(result);
+        this.autoMigrateLegacyJobsJson(result);
         this.migrateSkillPortHardcoding(result);
         this.migrateSelfKnowledgeTree(result);
         this.migrateSoulMd(result);
@@ -235,6 +282,210 @@ export class PostUpdateMigrator {
             result.errors.push(`built-in skills: ${err}`);
         }
     }
+    /**
+     * Phase 2 — install/refresh built-in agentmd jobs. Copies the shipped
+     * markdown templates into `.instar/jobs/instar/` and writes their
+     * per-slug manifests. Honors operator-disabled state (preserves
+     * `enabled: false` + `disabledAtBodyHash` across updates). Retires
+     * jobs that are no longer shipped.
+     *
+     * The `.instar/jobs/user/` namespace is structurally untouched (Seamless
+     * Migration Guarantee invariant 4).
+     */
+    migrateBuiltinJobs(result) {
+        try {
+            // The package root is two levels up from this compiled module (dist/core/),
+            // which puts us at the installed npm package root in production or the
+            // repo root in dev.
+            const packageRoot = path.resolve(__dirname, '..', '..');
+            const report = installBuiltinJobs({
+                agentStateDir: this.config.stateDir,
+                packageRoot,
+                port: this.config.port,
+            });
+            if (report.installed.length > 0) {
+                result.upgraded.push(`built-in agentmd jobs: ${report.installed.length} installed/refreshed`);
+            }
+            else if (report.errors.length === 0) {
+                result.skipped.push('built-in agentmd jobs: nothing to install');
+            }
+            for (const slug of report.retired) {
+                result.upgraded.push(`built-in agentmd jobs: retired "${slug}"`);
+            }
+            for (const e of report.errors) {
+                result.errors.push(`built-in agentmd jobs${e.slug ? ` [${e.slug}]` : ''}: ${e.reason}`);
+            }
+        }
+        catch (err) {
+            result.errors.push(`built-in agentmd jobs: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Phase 5 — auto-run `instar jobs migrate` for pre-spec agents on update.
+     *
+     * Behavior:
+     *   - SKIP entirely if `.instar/jobs/.migration-complete.json` exists
+     *     (operator already confirmed completion via Dashboard).
+     *   - SKIP entirely if `.instar/jobs/.migration-abandoned.json` exists
+     *     (operator explicitly chose to roll back).
+     *   - SKIP if `.instar/jobs.json` is absent (nothing to migrate).
+     *   - Otherwise, invoke `jobsMigrate({ defaultAction: 'fork' })` —
+     *     fork policy preserves the operator's customized body in user/
+     *     namespace, never silently drops content. This is the
+     *     spec-mandated default for the auto-run path.
+     *   - Emit a Dashboard banner event via the migration result so the
+     *     operator sees "migration ran on update — confirm in Dashboard."
+     *
+     * Seamless Migration Guarantee invariants enforced at this layer
+     * (PR #180 §Seamless Migration Guarantee):
+     *   #6 in-flight protection — JobScheduler.activeRuns() check is
+     *      currently a defensive no-op until Phase 4 wires the scheduler
+     *      back-reference; the migration runs at update time, before the
+     *      new scheduler instance comes up, so by construction nothing is
+     *      in flight.
+     *   #7 transactional safety on interrupt — `jobsMigrate` is structurally
+     *      safe (backup-first, idempotent, rollback via --abandon).
+     *   #8 telemetry — outcome is appended to result.upgraded/errors.
+     */
+    autoMigrateLegacyJobsJson(result) {
+        const runId = randomUUID();
+        const startedAt = new Date().toISOString();
+        try {
+            const stateDir = this.config.stateDir;
+            const jobsJsonPath = path.join(stateDir, 'jobs.json');
+            const jobsRoot = path.join(stateDir, 'jobs');
+            const completedMarker = path.join(jobsRoot, '.migration-complete.json');
+            const abandonedMarker = path.join(jobsRoot, '.migration-abandoned.json');
+            if (!fs.existsSync(jobsJsonPath)) {
+                return; // nothing to migrate
+            }
+            if (fs.existsSync(completedMarker)) {
+                result.skipped.push('legacy jobs.json migration: already complete (operator-confirmed)');
+                return;
+            }
+            if (fs.existsSync(abandonedMarker)) {
+                result.skipped.push('legacy jobs.json migration: explicitly abandoned by operator');
+                return;
+            }
+            // Snapshot pre-migration state so the runtime invariant gate has
+            // ground truth to compare against. Per spec §Gate wiring:
+            // "Before performing any destructive write, the migrator re-verifies
+            //  invariants 1, 2, 4, and 6 against the staged state. Failure aborts
+            //  to fail-closed (invariant 9)."
+            let preMigrationJobs = [];
+            try {
+                preMigrationJobs = JSON.parse(fs.readFileSync(jobsJsonPath, 'utf-8'));
+                if (!Array.isArray(preMigrationJobs))
+                    preMigrationJobs = [];
+            }
+            catch {
+                preMigrationJobs = [];
+            }
+            const preMigrationUserSnapshot = snapshotUserNamespace(stateDir);
+            const packageRoot = path.resolve(__dirname, '..', '..');
+            const instarVersion = this.readBundledInstarVersion(packageRoot);
+            const outcome = jobsMigrate({
+                agentStateDir: stateDir,
+                packageRoot,
+                defaultAction: 'fork',
+            });
+            if (outcome.status === 'completed') {
+                // Runtime invariant gate. Spec §Seamless Migration Guarantee #1, #2, #4.
+                // Invariant 6 (in-flight) is structurally satisfied at update-apply
+                // time because no jobs run mid-update.
+                const verification = verifyMigrationInvariants({
+                    agentStateDir: stateDir,
+                    preMigrationJobs,
+                    preMigrationUserSnapshot,
+                });
+                if (!verification.ok) {
+                    // Fail-closed (invariant 9): roll back via abandon.
+                    try {
+                        jobsMigrate({ agentStateDir: stateDir, packageRoot, abandon: true });
+                    }
+                    catch (rollbackErr) {
+                        result.errors.push(`legacy jobs.json migration: invariant verification failed AND rollback errored — ` +
+                            `${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`);
+                    }
+                    result.errors.push(`legacy jobs.json migration: ${verification.summary} — rolled back to pre-migration state`);
+                    return;
+                }
+                const migratedCount = outcome.perEntry.filter((e) => e.action === 'migrated-instar').length;
+                const forkedCount = outcome.perEntry.filter((e) => e.action === 'forked-user' || e.action === 'kept-user').length;
+                const renamedCount = outcome.perEntry.filter((e) => e.action === 'renamed-user').length;
+                result.upgraded.push(`legacy jobs.json migration: auto-ran on update — ${migratedCount} migrated to instar, ${forkedCount} preserved in user namespace, ${renamedCount} renamed. Invariants verified. Confirm via Dashboard to allow jobs.json removal.`);
+                if (outcome.backupPath) {
+                    result.upgraded.push(`legacy jobs.json migration: backup at ${path.basename(outcome.backupPath)}`);
+                }
+                // Spec invariant 8: telemetry write is the LAST action of a
+                // successful migration. Append the migration.completed event.
+                this.appendMigrationTelemetry({
+                    kind: 'migration.completed',
+                    runId,
+                    startedAt,
+                    completedAt: new Date().toISOString(),
+                    trigger: 'post-update',
+                    perEntry: outcome.perEntry.map((e) => ({
+                        slug: e.slug,
+                        action: normalizePerEntryAction(e.action),
+                        reason: e.reason,
+                    })),
+                    backupPath: outcome.backupPath,
+                    instarVersion,
+                });
+            }
+            else if (outcome.status === 'aborted') {
+                result.errors.push(`legacy jobs.json migration: aborted — ${outcome.errors.join('; ')}`);
+                this.appendMigrationTelemetry({
+                    kind: 'migration.aborted',
+                    runId,
+                    startedAt,
+                    completedAt: new Date().toISOString(),
+                    trigger: 'post-update',
+                    perEntry: outcome.perEntry.map((e) => ({
+                        slug: e.slug,
+                        action: normalizePerEntryAction(e.action),
+                        reason: e.reason,
+                    })),
+                    abortReason: outcome.errors.join('; '),
+                    instarVersion,
+                });
+            }
+        }
+        catch (err) {
+            result.errors.push(`legacy jobs.json migration: ${err instanceof Error ? err.message : String(err)}`);
+            this.appendMigrationTelemetry({
+                kind: 'migration.aborted',
+                runId,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                trigger: 'post-update',
+                perEntry: [],
+                abortReason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /** Read the installed package's version, for the migration event's
+     *  `instarVersion` field. Best-effort — returns undefined on failure. */
+    readBundledInstarVersion(packageRoot) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+            return typeof pkg.version === 'string' ? pkg.version : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Best-effort telemetry write. Missing telemetry is degradation, not a
+     *  release-blocker, so failures are swallowed. */
+    appendMigrationTelemetry(event) {
+        try {
+            appendMigrationEvent(this.config.stateDir, event);
+        }
+        catch {
+            // @silent-fallback-ok — telemetry is non-load-bearing
+        }
+    }
     /**
      * Re-install hooks with the latest templates.
      * Built-in hooks in instar/ are always overwritten.
@@ -1256,7 +1507,7 @@ The user has been talking to you (possibly for days). A generic greeting like "H
 - **Generate a file link**: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/api/files/link?path=.claude/CLAUDE.md"\`
 - **Download a file**: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/api/files/download?path=.claude/CLAUDE.md" -O\`
 - **Default config**: Browsing and editing enabled for the entire project directory (\`./\`) by default.
-- **Never editable**: \`.claude/hooks/\`, \`.claude/scripts/\`, \`node_modules/\` are always read-only regardless of config.
+- **Never editable**: \`.claude/hooks/\`, \`.claude/scripts/\`, \`node_modules/\`, \`.instar/jobs/instar/\` are always read-only regardless of config.
 `;
             // Insert after Dashboard section
             const dashboardIdx = content.indexOf('**Dashboard**');