npm - sneakoscope - Versions diffs - 4.8.7 → 5.1.2 - Mend

sneakoscope 4.8.7 → 5.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (288) hide show

package/dist/core/ui/dashboard-html.js ADDED Viewed

@@ -0,0 +1,111 @@
+export const DASHBOARD_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SKS Dashboard</title>
+  <style>
+    :root {
+      --bg:#0d1117; --card:#161b22; --line:#30363d; --text:#e6edf3; --muted:#8b949e;
+      --run:#3fb950; --fail:#f85149; --queue:#8b949e; --verify:#58a6ff; --warn:#d29922;
+    }
+    * { box-sizing: border-box; }
+    body { margin:0; background:var(--bg); color:var(--text); font:14px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+    header { display:grid; grid-template-columns: 1fr auto; gap:16px; align-items:center; padding:18px 22px; border-bottom:1px solid var(--line); background:#0b1016; position:sticky; top:0; z-index:2; }
+    h1 { margin:0; font-size:16px; font-weight:700; letter-spacing:0; }
+    .meta { color:var(--muted); margin-top:4px; display:flex; gap:12px; flex-wrap:wrap; }
+    .badge { display:inline-flex; align-items:center; min-height:28px; padding:0 10px; border:1px solid var(--line); background:var(--card); color:var(--muted); }
+    .badge.pass { color:var(--run); border-color:rgba(63,185,80,.55); }
+    .badge.fail { color:var(--fail); border-color:rgba(248,81,73,.55); }
+    main { display:grid; grid-template-columns:minmax(0,1fr) 360px; gap:18px; padding:18px; }
+    .strip { display:grid; grid-template-columns:repeat(6,minmax(92px,1fr)); gap:10px; margin-bottom:14px; }
+    .metric { border:1px solid var(--line); background:var(--card); padding:10px; min-height:64px; }
+    .metric b { display:block; font-size:20px; color:var(--text); }
+    .metric span { color:var(--muted); font-size:12px; }
+    .grid { display:grid; grid-template-columns:repeat(auto-fill,minmax(220px,1fr)); gap:10px; }
+    .slot { border:1px solid var(--line); border-left:4px solid var(--queue); background:var(--card); min-height:136px; padding:12px; overflow:hidden; }
+    .slot.running { border-left-color:var(--run); }
+    .slot.verifying { border-left-color:var(--verify); }
+    .slot.completed { border-left-color:var(--run); opacity:.86; }
+    .slot.failed { border-left-color:var(--fail); }
+    .slot h2 { margin:0 0 8px; font-size:13px; font-weight:700; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    .row { display:flex; justify-content:space-between; gap:8px; color:var(--muted); font-size:12px; min-width:0; }
+    .model { color:var(--verify); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; max-width:110px; }
+    .task { margin-top:10px; min-height:38px; color:var(--text); overflow:hidden; display:-webkit-box; -webkit-line-clamp:2; -webkit-box-orient:vertical; }
+    .bar { height:6px; background:#0b1016; border:1px solid var(--line); margin-top:12px; overflow:hidden; }
+    .bar i { display:block; height:100%; width:0; background:var(--verify); transition:width .25s ease; }
+    aside { display:grid; gap:14px; align-content:start; }
+    section { border-top:1px solid var(--line); padding-top:12px; }
+    section h2 { margin:0 0 10px; font-size:13px; }
+    .feed, .gates { display:grid; gap:8px; }
+    .event, .gate { background:var(--card); border:1px solid var(--line); padding:9px; color:var(--muted); min-height:34px; overflow-wrap:anywhere; }
+    .gate.pass { color:var(--run); }
+    .gate.fail { color:var(--fail); }
+    .pulse { display:inline-block; width:8px; height:8px; border-radius:50%; background:var(--run); margin-right:7px; animation:pulse 1.6s infinite; }
+    @keyframes pulse { 0%,100%{opacity:.35} 50%{opacity:1} }
+    @media (max-width: 900px) { main { grid-template-columns:1fr; } .strip { grid-template-columns:repeat(2,minmax(0,1fr)); } header { grid-template-columns:1fr; } }
+  </style>
+</head>
+<body>
+  <header>
+    <div>
+      <h1><span class="pulse"></span><span id="mission">SKS mission</span></h1>
+      <div class="meta"><span id="route">route</span><span id="elapsed">00:00</span><span id="updated">waiting</span></div>
+    </div>
+    <div id="gateBadge" class="badge">● proof pending</div>
+  </header>
+  <main>
+    <div>
+      <div class="strip" id="strip"></div>
+      <div class="grid" id="slots"></div>
+    </div>
+    <aside>
+      <section><h2>Events</h2><div class="feed" id="events"></div></section>
+      <section><h2>Gates</h2><div class="gates" id="gates"></div></section>
+    </aside>
+  </main>
+  <script>
+    const state = { started: Date.now() };
+    function render(payload) {
+      const data = payload && payload.snapshot ? payload : { snapshot: payload };
+      const snapshot = data.snapshot || {};
+      const gates = data.gates || [];
+      const events = data.events || [];
+      const slots = Object.values(snapshot.slots || {});
+      document.getElementById('mission').textContent = snapshot.mission_id || data.mission_id || 'latest';
+      document.getElementById('route').textContent = data.route || snapshot.route || 'SKS';
+      document.getElementById('elapsed').textContent = elapsed(state.started);
+      document.getElementById('updated').textContent = snapshot.updated_at || data.ts || 'waiting';
+      const blocked = gates.some(g => g.ok === false);
+      const passed = gates.length > 0 && gates.every(g => g.ok !== false);
+      const badge = document.getElementById('gateBadge');
+      badge.className = 'badge ' + (blocked ? 'fail' : passed ? 'pass' : '');
+      badge.textContent = blocked ? '✖ blocked' : passed ? '✔ gate passed' : '● proof pending';
+      const counts = snapshot.counts || {};
+      const spawned = slots.length;
+      document.getElementById('strip').innerHTML = [
+        ['run', counts.running || 0], ['verify', counts.verifying || 0], ['queue', counts.queued || 0],
+        ['done', counts.completed || 0], ['fail', counts.failed || 0], ['spawned', spawned]
+      ].map(([k,v]) => '<div class="metric"><b>'+v+'</b><span>'+k+'</span></div>').join('');
+      document.getElementById('slots').innerHTML = slots.map(slot => {
+        const status = String(slot.status || 'queued');
+        const progress = slot.progress && slot.progress.total ? Math.max(0, Math.min(100, Math.round(slot.progress.done / slot.progress.total * 100))) : (status === 'completed' ? 100 : 0);
+        return '<article class="slot '+status+'"><h2>'+esc(slot.slot_id || slot.worker_id || 'slot')+'</h2>'
+          + '<div class="row"><span>'+esc(slot.role || 'worker')+'</span><span class="model">'+esc(slot.model || slot.provider || slot.backend || slot.service_tier || '')+'</span></div>'
+          + '<div class="row"><span>'+esc(status)+'</span><span>'+esc(slot.latest_event_type || '')+'</span></div>'
+          + '<div class="task">'+esc(slot.task_title || slot.current_file || slot.log_tail || '')+'</div>'
+          + '<div class="bar"><i style="width:'+progress+'%"></i></div></article>';
+      }).join('') || '<div class="event">No live slots yet.</div>';
+      document.getElementById('events').innerHTML = events.slice(-30).reverse().map(e => '<div class="event">'+esc((e.ts || '')+' '+(e.type || e.event_type || e.event || 'event'))+'</div>').join('') || '<div class="event">No events yet.</div>';
+      document.getElementById('gates').innerHTML = gates.map(g => '<div class="gate '+(g.ok===false?'fail':'pass')+'">'+esc((g.ok===false?'✖ ':'✔ ')+(g.id || g.file || 'gate')+(g.missing&&g.missing.length?' missing '+g.missing.join(', '):''))+'</div>').join('') || '<div class="gate">No gate snapshot yet.</div>';
+    }
+    function esc(v) { return String(v == null ? '' : v).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c])); }
+    function elapsed(ms) { const s = Math.max(0, Math.floor((Date.now()-ms)/1000)); return String(Math.floor(s/60)).padStart(2,'0')+':'+String(s%60).padStart(2,'0'); }
+    fetch('/api/state').then(r => r.json()).then(render).catch(()=>{});
+    const source = new EventSource('/events' + location.search);
+    source.onmessage = (event) => render(JSON.parse(event.data));
+    setInterval(() => { document.getElementById('elapsed').textContent = elapsed(state.started); }, 1000);
+  </script>
+</body>
+</html>`;
+//# sourceMappingURL=dashboard-html.js.map

package/dist/core/update/update-migration-state.js CHANGED Viewed

@@ -1,9 +1,12 @@
 import fsp from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
-import { ensureDir, exists, globalSksRoot, nowIso, packageRoot, PACKAGE_VERSION, projectRoot, readJson, runProcess, sha256, which, writeJsonAtomic, writeReceiptRotated } from '../fsx.js';
+import { ensureDir, exists, globalSksRoot, nowIso, packageRoot, PACKAGE_VERSION, projectRoot, readJson, readText, runProcess, sha256, which, writeJsonAtomic, writeReceiptRotated, writeTextAtomic } from '../fsx.js';
 import { MANAGED_ASSET_VERSION } from '../managed-assets/managed-assets-manifest.js';
 import { enforceRetention } from '../retention.js';
 import { COMMANDS } from '../../cli/command-registry.js';
+import { reconcileSkills } from '../init/skills.js';
+import { codexHookTrustDoctor } from '../codex-hooks/codex-hook-trust-doctor.js';
 export const UPDATE_MIGRATION_SCHEMA = 'sks.project-migration-receipt.v2';
 export const INSTALLATION_EPOCH_SCHEMA = 'sks.installation-epoch.v1';
 export function installationEpochPath() {
@@ -85,15 +88,19 @@ export async function writeProjectUpdateMigrationReceipt(input) {
     const receiptPath = projectUpdateMigrationReceiptPath(input.root);
     const epoch = await ensureInstallationEpoch(input.source);
     const retentionCleanup = await runUpdateRetentionCleanup(input.root, input.source);
-    const requiredBlockers = input.blockers || [];
-    const optionalWarnings = input.warnings || [];
+    const legacyStages = await runLegacyMigrationStages(input.root, { fromVersion: input.fromVersion || null });
+    const stageBlockers = legacyStages.flatMap((stage) => stage.blockers.map((blocker) => `${stage.id}:${blocker}`));
+    const stageWarnings = legacyStages.flatMap((stage) => stage.warnings.map((warning) => `${stage.id}:${warning}`));
+    const requiredBlockers = [...(input.blockers || []), ...stageBlockers];
+    const optionalWarnings = [...(input.warnings || []), ...stageWarnings];
     const receipt = {
         schema: UPDATE_MIGRATION_SCHEMA,
-        status: input.status || 'current',
+        status: input.status || (requiredBlockers.length ? 'blocked' : 'current'),
         sks_version: PACKAGE_VERSION,
         root: input.root,
         source: input.source,
         generated_at: nowIso(),
+        from_version: input.fromVersion || null,
         project_root_hash: projectRootHash(input.root),
         installation_epoch_sha256: installationEpochSha256(epoch),
         project_semantic_hash: await projectSemanticHash(input.root),
@@ -101,7 +108,8 @@ export async function writeProjectUpdateMigrationReceipt(input) {
         installation_epoch_path: installationEpochPath(),
         doctor: input.doctor || null,
         retention_cleanup: retentionCleanup,
-        update_stages: input.updateStages || [],
+        update_stages: [...(input.updateStages || []), ...legacyStages],
+        legacy_migration_stages: legacyStages,
         required_blockers: requiredBlockers,
         optional_warnings: optionalWarnings,
         blockers: requiredBlockers,
@@ -175,6 +183,259 @@ export async function runUpdateRetentionCleanup(root, source = 'update-migration
         };
     }
 }
+const LEGACY_MIGRATION_STAGES = [
+    {
+        id: 'legacy-team-artifacts',
+        min_from_version: '0.0.0',
+        run: runLegacyTeamArtifactsStage
+    },
+    {
+        id: 'session-state-split',
+        min_from_version: '0.0.0',
+        run: runSessionStateSplitStage
+    },
+    {
+        id: 'skills-reconcile',
+        min_from_version: '0.0.0',
+        run: runSkillsReconcileStage
+    },
+    {
+        id: 'menubar-retarget',
+        min_from_version: '0.0.0',
+        run: runMenubarRetargetStage
+    },
+    {
+        id: 'config-fastmode-normalize',
+        min_from_version: '0.0.0',
+        run: runConfigFastModeNormalizeStage
+    },
+    {
+        id: 'hook-trust-refresh',
+        min_from_version: '0.0.0',
+        run: runHookTrustRefreshStage
+    },
+    {
+        id: 'receipt-rotation',
+        min_from_version: '0.0.0',
+        run: runReceiptRotationStage
+    }
+];
+async function runLegacyMigrationStages(root, opts = {}) {
+    const fromVersion = opts.fromVersion || null;
+    const runs = [];
+    for (const stage of LEGACY_MIGRATION_STAGES) {
+        if (!legacyStageApplies(fromVersion, stage.min_from_version)) {
+            runs.push({
+                schema: 'sks.legacy-update-migration-stage.v1',
+                id: stage.id,
+                ok: true,
+                status: 'skipped',
+                min_from_version: stage.min_from_version,
+                from_version: fromVersion,
+                actions: ['skipped_by_from_version'],
+                blockers: [],
+                warnings: []
+            });
+            continue;
+        }
+        try {
+            const result = await stage.run(root, fromVersion);
+            runs.push({
+                schema: 'sks.legacy-update-migration-stage.v1',
+                id: stage.id,
+                min_from_version: stage.min_from_version,
+                from_version: fromVersion,
+                ...result
+            });
+        }
+        catch (err) {
+            runs.push({
+                schema: 'sks.legacy-update-migration-stage.v1',
+                id: stage.id,
+                ok: false,
+                status: 'failed',
+                min_from_version: stage.min_from_version,
+                from_version: fromVersion,
+                actions: [],
+                blockers: [err?.message || String(err)],
+                warnings: []
+            });
+        }
+    }
+    return runs;
+}
+async function runLegacyTeamArtifactsStage(root) {
+    const candidates = [
+        path.join(root, '.sneakoscope', 'team'),
+        path.join(root, '.sneakoscope', 'team-dashboard-state.json'),
+        path.join(root, '.sneakoscope', 'work-order-ledger.json')
+    ];
+    const present = [];
+    for (const candidate of candidates) {
+        if (await exists(candidate))
+            present.push(path.relative(root, candidate));
+    }
+    await writeJsonAtomic(path.join(root, '.sneakoscope', 'update', 'legacy-team-artifacts.json'), {
+        schema: 'sks.legacy-team-artifacts-migration.v1',
+        generated_at: nowIso(),
+        present
+    });
+    return {
+        ok: true,
+        status: 'ok',
+        actions: present.length ? ['recorded_legacy_team_artifacts'] : ['no_legacy_team_artifacts'],
+        blockers: [],
+        warnings: [],
+        detail: { present }
+    };
+}
+async function runSessionStateSplitStage(root) {
+    const legacyCurrent = path.join(root, '.sneakoscope', 'current.json');
+    const stateCurrent = path.join(root, '.sneakoscope', 'state', 'current.json');
+    const sessionsDir = path.join(root, '.sneakoscope', 'state', 'sessions');
+    await ensureDir(sessionsDir);
+    const actions = [];
+    let current = await readJson(stateCurrent, null).catch(() => null);
+    const legacy = await readJson(legacyCurrent, null).catch(() => null);
+    if (!current && legacy) {
+        current = legacy;
+        await writeJsonAtomic(stateCurrent, current);
+        actions.push('copied_legacy_current_json_to_state_current');
+    }
+    const missionId = typeof current?.mission_id === 'string' ? current.mission_id : typeof current?.mission === 'string' ? current.mission : null;
+    if (missionId) {
+        const sessionPath = path.join(sessionsDir, `${safeFileName(missionId)}.json`);
+        if (!(await exists(sessionPath))) {
+            await writeJsonAtomic(sessionPath, { ...current, migrated_from: path.relative(root, stateCurrent), migrated_at: nowIso() });
+            actions.push('wrote_state_session_alias');
+        }
+    }
+    if (!actions.length)
+        actions.push('session_state_current');
+    return { ok: true, status: 'ok', actions, blockers: [], warnings: [], detail: { legacy_present: Boolean(legacy), mission_id: missionId } };
+}
+async function runSkillsReconcileStage(root) {
+    const global = await reconcileSkills({ targetDir: path.join(os.homedir(), '.agents', 'skills'), scope: 'global', fix: true })
+        .catch((err) => ({ ok: false, error: err?.message || String(err) }));
+    const project = await reconcileSkills({ targetDir: path.join(root, '.agents', 'skills'), scope: 'project', fix: true })
+        .catch((err) => ({ ok: false, error: err?.message || String(err) }));
+    const blockers = [
+        ...(global.ok === false || global.error ? [`global:${global.error || 'failed'}`] : []),
+        ...(project.ok === false || project.error ? [`project:${project.error || 'failed'}`] : [])
+    ];
+    return {
+        ok: blockers.length === 0,
+        status: blockers.length ? 'failed' : 'ok',
+        actions: ['reconciled_global_skills', 'reconciled_project_skills'],
+        blockers,
+        warnings: [],
+        detail: {
+            global_installed: Array.isArray(global.installed) ? global.installed.length : null,
+            project_removed: Array.isArray(project.removed) ? project.removed.length : null
+        }
+    };
+}
+async function runMenubarRetargetStage(root) {
+    const actionScript = path.join(os.homedir(), '.codex', 'sks-menubar', 'sks-menubar-action.sh');
+    const text = await readText(actionScript, null);
+    if (typeof text !== 'string')
+        return { ok: true, status: 'ok', actions: ['menubar_action_script_absent'], blockers: [], warnings: [] };
+    const desired = path.join(packageRoot(), 'dist', 'bin', 'sks.js');
+    const line = `SKS_ENTRY=${JSON.stringify(desired)}`;
+    const next = /^\s*SKS_ENTRY\s*=.*$/m.test(text)
+        ? text.replace(/^\s*SKS_ENTRY\s*=.*$/m, line)
+        : `${line}\n${text}`;
+    if (next !== text) {
+        await writeTextAtomic(actionScript, next);
+        return { ok: true, status: 'ok', actions: ['retargeted_menubar_action_script'], blockers: [], warnings: [], detail: { action_script: actionScript } };
+    }
+    return { ok: true, status: 'ok', actions: ['menubar_action_script_current'], blockers: [], warnings: [], detail: { action_script: actionScript } };
+}
+async function runConfigFastModeNormalizeStage() {
+    const configPath = path.join(os.homedir(), '.codex', 'config.toml');
+    const text = await readText(configPath, null);
+    if (typeof text !== 'string')
+        return { ok: true, status: 'ok', actions: ['codex_config_absent'], blockers: [], warnings: [] };
+    const table = text.match(/(^|\n)\[user\.fast_mode\][\s\S]*?(?=\n\[|$)/);
+    const misplaced = table?.[0]?.match(/^\s*default_profile\s*=\s*"([^"]+)"\s*$/m)?.[1] || null;
+    const hasTopLevel = /^\s*default_profile\s*=\s*"[^"]+"\s*$/m.test(text.slice(0, Math.max(0, text.search(/^\s*\[/m))));
+    if (!misplaced)
+        return { ok: true, status: 'ok', actions: ['fastmode_default_profile_current'], blockers: [], warnings: [] };
+    let next = text.replace(/(^|\n)(\[user\.fast_mode\][\s\S]*?)(?=\n\[|$)/, (_match, prefix, block) => {
+        const cleaned = String(block).split(/\r?\n/).filter((line) => !/^\s*default_profile\s*=/.test(line)).join('\n').trimEnd();
+        return `${prefix}${cleaned}`;
+    });
+    if (!hasTopLevel)
+        next = insertTopLevelTomlKey(next, `default_profile = ${JSON.stringify(misplaced)}`);
+    if (next !== text)
+        await writeTextAtomic(configPath, `${next.trim()}\n`);
+    return { ok: true, status: 'ok', actions: ['normalized_fastmode_default_profile'], blockers: [], warnings: [], detail: { config_path: configPath, default_profile: misplaced } };
+}
+async function runHookTrustRefreshStage(root) {
+    const result = await codexHookTrustDoctor(root, { fix: true, managed: true, actual: true });
+    const blockers = result.ok === false ? (result.blockers || ['hook_trust_refresh_failed']) : [];
+    return {
+        ok: blockers.length === 0,
+        status: blockers.length ? 'failed' : 'ok',
+        actions: ['refreshed_hook_trust'],
+        blockers,
+        warnings: result.warnings || [],
+        detail: { entries: result.current_hash_count ?? null }
+    };
+}
+async function runReceiptRotationStage(root) {
+    const receiptPath = projectUpdateMigrationReceiptPath(root);
+    const dir = path.dirname(receiptPath);
+    const base = path.basename(receiptPath);
+    const rows = await fsp.readdir(dir, { withFileTypes: true }).catch(() => []);
+    const rotated = await Promise.all(rows
+        .filter((entry) => entry.isFile() && entry.name.startsWith(`${base}.`) && entry.name.endsWith('.json'))
+        .map(async (entry) => {
+        const file = path.join(dir, entry.name);
+        return { file, stat: await fsp.stat(file).catch(() => null) };
+    }));
+    const removable = rotated
+        .filter((row) => Boolean(row.stat))
+        .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
+        .slice(5);
+    await Promise.all(removable.map((row) => fsp.rm(row.file, { force: true }).catch(() => undefined)));
+    return {
+        ok: true,
+        status: 'ok',
+        actions: removable.length ? ['rotated_old_update_receipts'] : ['receipt_rotation_current'],
+        blockers: [],
+        warnings: [],
+        detail: { removed: removable.length }
+    };
+}
+function legacyStageApplies(fromVersion, minFromVersion) {
+    if (!fromVersion)
+        return true;
+    if (compareVersionLike(fromVersion, PACKAGE_VERSION) > 0)
+        return false;
+    return compareVersionLike(fromVersion, minFromVersion) >= 0;
+}
+function compareVersionLike(a, b) {
+    const pa = String(a || '').split(/[.-]/).map((value) => Number.parseInt(value, 10) || 0);
+    const pb = String(b || '').split(/[.-]/).map((value) => Number.parseInt(value, 10) || 0);
+    for (let index = 0; index < Math.max(pa.length, pb.length, 3); index += 1) {
+        if ((pa[index] || 0) > (pb[index] || 0))
+            return 1;
+        if ((pa[index] || 0) < (pb[index] || 0))
+            return -1;
+    }
+    return 0;
+}
+function safeFileName(value) {
+    return String(value || 'session').replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '') || 'session';
+}
+function insertTopLevelTomlKey(text, line) {
+    const raw = String(text || '').trimEnd();
+    const firstTable = raw.search(/^\s*\[/m);
+    if (firstTable < 0)
+        return `${line}\n${raw}`.trim() + '\n';
+    return `${raw.slice(0, firstTable).trimEnd()}\n${line}\n\n${raw.slice(firstTable).trimStart()}`.trim() + '\n';
+}
 export async function ensureCurrentMigrationBeforeCommand(input) {
     const env = input.env || process.env;
     const command = input.command;
@@ -215,7 +476,8 @@ export async function ensureCurrentMigrationBeforeCommand(input) {
         };
     return withUpdateMigrationLock(root, empty, async () => {
         const reportFile = path.join(root, '.sneakoscope', 'update', 'doctor-migration.json');
-        const doctor = await runPackageLocalDoctor({
+        const baseTimeoutMs = migrationDoctorTimeoutMs(env);
+        let doctor = await runPackageLocalDoctor({
             root,
             args: ['doctor', '--fix', '--yes', '--profile', 'migration', '--machine-only', '--report-file', reportFile],
             env: {
@@ -223,29 +485,51 @@ export async function ensureCurrentMigrationBeforeCommand(input) {
                 SKS_UPDATE_MIGRATION_GATE_DISABLED: '1',
                 SKS_DISABLE_UPDATE_CHECK: '1'
             },
-            timeoutMs: 30_000,
+            timeoutMs: baseTimeoutMs,
             maxOutputBytes: 32 * 1024
         });
+        const timeoutWarnings = [];
+        if (!doctor.ok && doctor.timedOut) {
+            timeoutWarnings.push(`doctor_migration_timeout_retry:timeout_ms=${baseTimeoutMs}`);
+            doctor = await runPackageLocalDoctor({
+                root,
+                args: ['doctor', '--fix', '--yes', '--profile', 'migration', '--machine-only', '--report-file', reportFile],
+                env: {
+                    ...env,
+                    SKS_UPDATE_MIGRATION_GATE_DISABLED: '1',
+                    SKS_DISABLE_UPDATE_CHECK: '1',
+                    SKS_MIGRATION_DOCTOR_RETRY: '1'
+                },
+                timeoutMs: baseTimeoutMs * 2,
+                maxOutputBytes: 32 * 1024
+            });
+        }
         if (!doctor.ok) {
-            const requiredBlockers = doctor.required_blockers.length ? doctor.required_blockers : ['doctor_migration_profile_failed'];
+            const blocker = doctor.timedOut ? 'doctor_migration_timeout' : 'doctor_migration_failed';
+            const requiredBlockers = [blocker, ...(doctor.required_blockers.length ? doctor.required_blockers : [])];
+            const warnings = [
+                ...timeoutWarnings,
+                ...doctor.optional_warnings,
+                ...(doctor.timedOut ? ['doctor_migration_timeout_may_be_network_or_first_compile_slow_run_sks_doctor_fix_yes_for_live_progress'] : [])
+            ];
             const blocked = await writeProjectUpdateMigrationReceipt({
                 root,
                 source: 'first-command-gate',
                 status: 'blocked',
                 doctor,
                 blockers: requiredBlockers,
-                warnings: doctor.optional_warnings
+                warnings
             });
-            return { ...empty, ok: false, status: 'blocked', receipt: blocked, doctor, failed_stage_id: 'doctor:migration-profile', blockers: requiredBlockers, warnings: doctor.optional_warnings };
+            return { ...empty, ok: false, status: 'blocked', receipt: blocked, doctor, failed_stage_id: 'doctor:migration-profile', blockers: requiredBlockers, warnings };
         }
         const current = await writeProjectUpdateMigrationReceipt({
             root,
             source: 'first-command-gate',
             doctor,
             blockers: [],
-            warnings: doctor.optional_warnings
+            warnings: [...timeoutWarnings, ...doctor.optional_warnings]
         });
-        return { ...empty, ok: true, status: 'repaired', receipt: current, doctor, failed_stage_id: null, blockers: [], warnings: [] };
+        return { ...empty, ok: true, status: 'repaired', receipt: current, doctor, failed_stage_id: null, blockers: [], warnings: [...timeoutWarnings, ...doctor.optional_warnings] };
     }, recheck ? { recheck } : {});
 }
 export async function runPostinstallGlobalDoctorAndMarkPending(input = {}) {
@@ -267,7 +551,7 @@ export async function runPostinstallGlobalDoctorAndMarkPending(input = {}) {
             SKS_DISABLE_UPDATE_CHECK: '1',
             SKS_POSTINSTALL_NO_BOOTSTRAP: '1'
         },
-        timeoutMs: 15_000,
+        timeoutMs: migrationDoctorTimeoutMs(env),
         maxOutputBytes: 32 * 1024
     });
     const pending = await writePendingUpdateMigration({
@@ -288,10 +572,18 @@ function commandSkipsMigrationGate(command) {
     const entry = COMMANDS[command];
     return entry?.skipMigrationGate === true || entry?.readonly === true;
 }
+function migrationDoctorTimeoutMs(env) {
+    const override = Number.parseInt(env.SKS_MIGRATION_DOCTOR_TIMEOUT_MS || '', 10);
+    return Number.isFinite(override) && override > 0 ? override : 180_000;
+}
 export async function runPackageLocalDoctor(input = {}) {
     const entrypoint = input.entrypoint || path.join(packageRoot(), 'dist', 'bin', 'sks.js');
     const cwd = input.root || globalSksRoot();
     const args = input.args || ['doctor', '--json'];
+    const env = input.env || process.env;
+    const testRun = testPackageLocalDoctorRun({ entrypoint, cwd, args, env });
+    if (testRun)
+        return testRun;
     if (!(await exists(entrypoint))) {
         return {
             schema: 'sks.package-local-doctor-run.v1',
@@ -306,6 +598,8 @@ export async function runPackageLocalDoctor(input = {}) {
             optional_warnings: [],
             stdout_tail: '',
             stderr_tail: '',
+            timedOut: false,
+            timed_out: false,
             error: `missing package-local sks entrypoint: ${entrypoint}`
         };
     }
@@ -313,7 +607,7 @@ export async function runPackageLocalDoctor(input = {}) {
         cwd,
         env: {
             ...process.env,
-            ...(input.env || {}),
+            ...env,
             SKS_UPDATE_MIGRATION_GATE_DISABLED: '1',
             SKS_DISABLE_UPDATE_CHECK: '1'
         },
@@ -322,7 +616,8 @@ export async function runPackageLocalDoctor(input = {}) {
     }).catch((err) => ({
         code: 1,
         stdout: '',
-        stderr: err?.message || String(err)
+        stderr: err?.message || String(err),
+        timedOut: false
     }));
     const reportFile = reportFileFromArgs(args);
     const parsed = reportFile
@@ -345,9 +640,65 @@ export async function runPackageLocalDoctor(input = {}) {
         optional_warnings: optionalWarnings,
         stdout_tail: tail(result.stdout || ''),
         stderr_tail: tail(result.stderr || ''),
+        timedOut: result.timedOut === true,
+        timed_out: result.timedOut === true,
         error: ok ? null : tail(result.stderr || result.stdout || requiredBlockers.join(', ') || 'doctor failed')
     };
 }
+function testPackageLocalDoctorRun(input) {
+    if (input.env.SKS_TEST_DOCTOR_TIMEOUT_ONCE === '1' && input.env.SKS_MIGRATION_DOCTOR_RETRY !== '1') {
+        return mockPackageLocalDoctorRun(input, {
+            ok: false,
+            timedOut: true,
+            exitCode: 124,
+            blockers: ['test_doctor_timeout_once']
+        });
+    }
+    if (input.env.SKS_TEST_DOCTOR_TIMEOUT_ONCE === '1' && input.env.SKS_MIGRATION_DOCTOR_RETRY === '1') {
+        return mockPackageLocalDoctorRun(input, {
+            ok: true,
+            timedOut: false,
+            exitCode: 0,
+            warnings: ['test_doctor_retry_succeeded']
+        });
+    }
+    if (input.env.SKS_TEST_DOCTOR_FAIL === '1') {
+        return mockPackageLocalDoctorRun(input, {
+            ok: false,
+            timedOut: false,
+            exitCode: 1,
+            blockers: ['test_doctor_failed']
+        });
+    }
+    if (input.env.SKS_TEST_DOCTOR_OK === '1') {
+        return mockPackageLocalDoctorRun(input, {
+            ok: true,
+            timedOut: false,
+            exitCode: 0,
+            warnings: ['test_doctor_ok']
+        });
+    }
+    return null;
+}
+function mockPackageLocalDoctorRun(input, result) {
+    return {
+        schema: 'sks.package-local-doctor-run.v1',
+        ok: result.ok,
+        status: result.ok ? 'ok' : 'failed',
+        entrypoint: input.entrypoint,
+        cwd: input.cwd,
+        args: input.args,
+        exit_code: result.exitCode,
+        parsed_ok: result.ok,
+        required_blockers: result.ok ? [] : result.blockers || [],
+        optional_warnings: result.warnings || [],
+        stdout_tail: result.ok ? '{"ok":true}' : '',
+        stderr_tail: result.ok ? '' : (result.blockers || ['doctor failed']).join(', '),
+        timedOut: result.timedOut,
+        timed_out: result.timedOut,
+        error: result.ok ? null : (result.blockers || ['doctor failed']).join(', ')
+    };
+}
 export async function resolveInstalledSksEntrypoint(input = {}) {
     const packageName = input.packageName || 'sneakoscope';
     const candidates = [