sneakoscope 4.8.6 → 5.1.2

package/dist/commands/doctor.js

@@ -1,6 +1,9 @@
+import os from 'node:os';
+import path from 'node:path';
 import { projectRoot, exists, formatBytes } from '../core/fsx.js';
 import { flag } from '../cli/args.js';
 import { printJson } from '../cli/output.js';
+import { ui as cliUi } from '../cli/cli-theme.js';
 import { getCodexInfo } from '../core/codex-adapter.js';
 import { rustInfo } from '../core/rust-accelerator.js';
 import { codexAppIntegrationStatus } from '../core/codex-app.js';
@@ -40,18 +43,33 @@ import { doctorRepairPostcheck } from '../core/doctor/doctor-repair-postcheck.js
 import { withSecretPreservationGuard } from '../core/config/config-migration-journal.js';
 import { writeProjectUpdateMigrationReceipt } from '../core/update/update-migration-state.js';
 import { installSksMenuBar } from '../core/codex-app/sks-menubar.js';
+import { sweepSksTempDirs } from '../core/retention.js';
+import { reconcileSkills } from '../core/init/skills.js';
+import { codexHookTrustDoctor } from '../core/codex-hooks/codex-hook-trust-doctor.js';
+import { detectImagegenCapability } from '../core/imagegen/imagegen-capability.js';
+import { repairCodexImagegen } from '../core/doctor/imagegen-repair.js';
 export async function run(_command, args = []) {
     const root = await projectRoot();
     const doctorFix = flag(args, '--fix');
+    if (!flag(args, '--json')) {
+        cliUi.banner('doctor');
+        cliUi.step(doctorFix ? 'repairing and validating' : 'validating');
+    }
     if (doctorFix)
         return withSecretPreservationGuard(root, 'doctor-fix', () => runDoctor(args, root, doctorFix));
     return runDoctor(args, root, doctorFix);
 }
 async function runDoctor(args = [], root, doctorFix) {
     const startedAtMs = Date.now();
+    const sksTempSweep = doctorFix ? await sweepSksTempDirs(root, { maxAgeHours: 24 }).catch((err) => ({
+        ok: false,
+        error: err?.message || String(err),
+        actions: []
+    })) : { ok: true, skipped: true, reason: 'doctor_without_fix', actions: [] };
     const doctorProfile = doctorProfileFromArgs(args, doctorFix);
     const machineOnly = flag(args, '--machine-only');
     const reportFile = readOption(args, '--report-file', null);
+    const argWarnings = doctorArgWarnings(args);
     const deepDiagnostics = doctorProfile === 'full' || doctorProfile === 'capabilities';
     const codexBin = readOption(args, '--codex-bin', process.env.SKS_DOCTOR_CODEX_BIN || '');
     const actualCodexProbeRequested = flag(args, '--actual-codex') || flag(args, '--require-actual-codex') || Boolean(codexBin);
@@ -99,6 +117,20 @@ async function runDoctor(args = [], root, doctorFix) {
                 : deepDiagnostics ? await ensureGlobalCodexFastModeDuringInstall().catch((err) => ({ status: 'failed', error: err?.message || String(err) })) : { status: 'skipped', reason: 'default_doctor_no_global_fast_mode_regeneration' }
         };
     }
+    const skillsReconcile = doctorFix
+        ? {
+            global: await reconcileSkills({
+                targetDir: path.join(os.homedir(), '.agents', 'skills'),
+                scope: 'global',
+                fix: true
+            }).catch((err) => ({ ok: false, error: err?.message || String(err) })),
+            project: await reconcileSkills({
+                targetDir: path.join(root, '.agents', 'skills'),
+                scope: 'project',
+                fix: true
+            }).catch((err) => ({ ok: false, error: err?.message || String(err) }))
+        }
+        : { skipped: true, reason: 'doctor_without_fix' };
     const commandAliasCleanup = await runDoctorCommandAliasCleanup({
         root,
         fix: doctorFix
@@ -278,7 +310,8 @@ async function runDoctor(args = [], root, doctorFix) {
     const sksMenuBar = await installSksMenuBar({
         root,
         apply: doctorFix,
-        launch: doctorFix
+        launch: doctorFix,
+        quiet: machineOnly || flag(args, '--json')
     }).catch((err) => ({
         schema: 'sks.codex-app-sks-menubar.v1',
         ok: false,
@@ -289,10 +322,18 @@ async function runDoctor(args = [], root, doctorFix) {
         executable_path: null,
         launch_agent_path: null,
         action_script_path: null,
+        build_stamp_path: null,
         report_path: `${root}/.sneakoscope/reports/sks-menubar.json`,
         menu_items: [],
         actions: [],
         launch: { requested: doctorFix, method: 'none', ok: false, error: err?.message || String(err) },
+        tcc_automation_status: 'unknown',
+        next_actions: [
+            'Run: sks menubar status',
+            'Run: sks menubar install',
+            'Run: sks menubar restart',
+            'Rotate CODEX_LB_API_KEY and OPENROUTER_API_KEY if they were previously exposed in launchd.'
+        ],
         blockers: [err?.message || String(err)],
         warnings: []
     }));
@@ -383,10 +424,22 @@ async function runDoctor(args = [], root, doctorFix) {
             raw_secret_values_recorded: false
         }))
         : null;
+    const hookTrustRepair = doctorFix && doctorPhaseIds.includes('hook_trust_repair')
+        ? await codexHookTrustDoctor(root, { fix: true, managed: true, actual: true }).catch((err) => ({
+            schema: 'sks.codex-hook-trust-doctor.v2',
+            ok: false,
+            actual: true,
+            blockers: [`hook_trust_repair_failed:${err?.message || String(err)}`],
+            warnings: [],
+            repair_actions: ['sks codex trust-doctor --fix --managed --actual']
+        }))
+        : null;
     const doctorFixTransaction = doctorFix
         ? await runDoctorFixTransaction({
             root,
             dirtyPlan: doctorDirtyPlan,
+            json: flag(args, '--json'),
+            machineOnly,
             phases: [
                 {
                     id: 'setup',
@@ -456,6 +509,17 @@ async function runDoctor(args = [], root, doctorFix) {
                         rollback_evidence: 'optional_supabase_no_ready_mutation_required'
                     })
                 },
+                {
+                    id: 'hook_trust_repair',
+                    run: async () => ({
+                        id: 'hook_trust_repair',
+                        ok: hookTrustRepair?.ok !== false,
+                        repaired: doctorFix,
+                        blockers: hookTrustRepair?.blockers || [],
+                        warnings: hookTrustRepair?.warnings || [],
+                        rollback_evidence: hookTrustRepair?.fixed?.managed_hook_file || 'codex_hook_trust_repair_idempotent'
+                    })
+                },
                 {
                     id: 'sks_menubar',
                     required_for_ready: false,
@@ -540,10 +604,29 @@ async function runDoctor(args = [], root, doctorFix) {
     const globalSksInstallCleanup = flag(args, '--fix') && !flag(args, '--local-only')
         ? await cleanDuplicateGlobalSksInstalls({ root, fix: true }).catch((err) => ({ schema: 'sks.global-sks-install-cleanup.v1', ok: false, fix: true, error: err?.message || String(err), blockers: ['global_sks_install_cleanup_exception'] }))
         : null;
-    const { detectImagegenCapability } = await import('../core/imagegen/imagegen-capability.js');
-    const imagegen = deepDiagnostics
-        ? await detectImagegenCapability({ codexBin: codexBin || undefined }).catch((err) => ({ ok: false, error: err.message, auth_readiness: null }))
-        : { ok: false, skipped: true, auth_readiness: null, warnings: ['imagegen_optional_diagnostic_skipped'] };
+    const imagegen = await detectImagegenCapability({ codexBin: codexBin || undefined }).catch((err) => ({ ok: false, error: err.message, auth_readiness: null, core_ready: false, blockers: ['imagegen_detection_exception'] }));
+    const imagegenRepair = imagegen.core_ready === true
+        ? {
+            schema: 'sks.doctor-imagegen-repair.v1',
+            ok: true,
+            attempted: false,
+            apply: doctorFix,
+            recovered: true,
+            before: imagegen,
+            after: imagegen,
+            steps: [],
+            blockers: [],
+            manual_actions: []
+        }
+        : await repairCodexImagegen({ root, apply: doctorFix, codexBin: codexBin || null }).catch((err) => ({
+            schema: 'sks.doctor-imagegen-repair.v1',
+            ok: false,
+            attempted: true,
+            apply: doctorFix,
+            recovered: false,
+            blockers: [err?.message || String(err)],
+            manual_actions: ['Run `sks doctor --fix --json` after enabling Codex App image_generation.']
+        }));
     const codex0138Capability = deepDiagnostics
         ? await writeCodex0138CapabilityArtifacts(root, { codexBin: codexBin || null }).catch((err) => ({ error: err?.message || String(err), report: null }))
         : { skipped: true, report: null };
@@ -687,8 +770,9 @@ async function runDoctor(args = [], root, doctorFix) {
     const result = {
         schema: 'sks.doctor-status.v2',
         elapsed_ms: Date.now() - startedAtMs,
-        ok: ready.ready && (!sksUpdate || sksUpdate.ok !== false) && commandAliasCleanup.ok !== false && codexStartupRepair.ok !== false && (!doctorFixPostcheck || doctorFixPostcheck.ok !== false),
+        ok: ready.ready && (!sksUpdate || sksUpdate.ok !== false) && commandAliasCleanup.ok !== false && codexStartupRepair.ok !== false,
         root,
+        arg_warnings: argWarnings,
         node: { ok: Number(process.versions.node.split('.')[0]) >= 20, version: process.version },
         codex,
         codex_config: codexConfig,
@@ -712,16 +796,30 @@ async function runDoctor(args = [], root, doctorFix) {
         supabase_mcp_repair: supabaseMcpRepair,
         doctor_fix_transaction: doctorFixTransaction,
         doctor_fix_postcheck: doctorFixPostcheck,
+        postcheck: doctorFixPostcheck ? {
+            ok: doctorFixPostcheck.ok === true,
+            pending_manual: doctorFixPostcheck.pending_manual || [],
+            required_blockers: doctorFixPostcheck.required_blockers || [],
+            optional_warnings: doctorFixPostcheck.optional_warnings || []
+        } : null,
         local_model: localModel,
         agent_role_config: agentRoleConfigRepair,
         zellij_readiness: zellijReadiness,
         codex_permission_profiles: permissionProfiles,
         command_aliases: commandAliasCleanup,
+        sks_temp_sweep: {
+            ok: sksTempSweep.ok !== false,
+            skipped: sksTempSweep.skipped === true,
+            action_count: Array.isArray(sksTempSweep.actions) ? sksTempSweep.actions.length : 0,
+            reason: sksTempSweep.reason || null,
+            error: sksTempSweep.error || null
+        },
         imagegen: {
             ok: imagegen.auth_readiness?.available_paths?.length > 0,
             auth_readiness: imagegen.auth_readiness || null,
             codex_app_builtin_available: imagegen.codex_app?.available === true
         },
+        imagegen_repair: imagegenRepair,
         codex_0138: {
             capability: codex0138Capability.report || null,
             doctor: codex0138Doctor,
@@ -735,7 +833,8 @@ async function runDoctor(args = [], root, doctorFix) {
         ready,
         sneakoscope: { ok: await exists(`${root}/.sneakoscope`) },
         package: { bytes: pkgBytes, human: formatBytes(pkgBytes) },
-        repair: { sks_update: sksUpdate, setup: setupRepair, codex_config: configRepair, migration_journal: migrationJournal, global_sks_installs: globalSksInstallCleanup, agent_role_config: agentRoleConfigRepair, zellij: zellijRepair, context7: context7Repair, codex_startup: codexStartupRepair, startup_config: startupConfigRepair, context7_mcp: context7McpRepair, supabase_mcp: supabaseMcpRepair, sks_menubar: sksMenuBar, doctor_transaction: doctorFixTransaction, doctor_dirty_plan: doctorDirtyPlan, doctor_postcheck: doctorFixPostcheck, codex_native: codexNativeRepair, doctor_native_capability: doctorNativeCapabilityRepair, command_aliases: commandAliasCleanup }
+        skills: skillsReconcile,
+        repair: { sks_update: sksUpdate, setup: setupRepair, codex_config: configRepair, migration_journal: migrationJournal, global_sks_installs: globalSksInstallCleanup, agent_role_config: agentRoleConfigRepair, zellij: zellijRepair, context7: context7Repair, codex_startup: codexStartupRepair, startup_config: startupConfigRepair, context7_mcp: context7McpRepair, supabase_mcp: supabaseMcpRepair, imagegen: imagegenRepair, hook_trust: hookTrustRepair, sks_menubar: sksMenuBar, doctor_transaction: doctorFixTransaction, doctor_dirty_plan: doctorDirtyPlan, doctor_postcheck: doctorFixPostcheck, codex_native: codexNativeRepair, doctor_native_capability: doctorNativeCapabilityRepair, command_aliases: commandAliasCleanup, skills: skillsReconcile, sks_temp_sweep: sksTempSweep }
     };
     if (reportFile)
         await writeJsonReportFile(reportFile, result);
@@ -751,6 +850,8 @@ async function runDoctor(args = [], root, doctorFix) {
         return;
     }
     console.log('SKS Doctor');
+    for (const warning of argWarnings)
+        console.log(`Argument warning: ${warning}`);
     console.log(`Root:      ${root}`);
     console.log(`Node:      ${result.node.ok ? 'ok' : 'fail'} ${result.node.version}`);
     console.log(`Codex:     ${codex.bin ? 'ok' : 'missing'} ${codex.version || ''}`);
@@ -879,6 +980,9 @@ async function runDoctor(args = [], root, doctorFix) {
                 console.log(`  - ${action}`);
         }
     }
+    console.log(`Image Gen repair: ${imagegenRepair.recovered ? 'ok' : imagegenRepair.attempted ? 'blocked' : 'not-needed'}`);
+    for (const action of imagegenRepair.manual_actions || [])
+        console.log(`  - ${action}`);
     const codex0138 = codex0138Capability.report || {};
     console.log('Codex current compatibility:');
     console.log(`  target: rust-v0.142.0`);
@@ -1017,7 +1121,7 @@ function fallbackCodexNativeFeatureMatrix(codex, blockers = [], warnings = []) {
         warnings
     };
 }
-function doctorProfileFromArgs(args = [], doctorFix = false) {
+export function doctorProfileFromArgs(args = [], doctorFix = false) {
     const explicit = readOption(args, '--profile', null);
     if (explicit === 'migration' || explicit === 'full' || explicit === 'capabilities' || explicit === 'fast' || explicit === 'fix')
         return explicit;
@@ -1027,12 +1131,46 @@ function doctorProfileFromArgs(args = [], doctorFix = false) {
         return 'capabilities';
     return doctorFix ? 'fix' : 'fast';
 }
+export function doctorArgWarnings(args = []) {
+    const warnings = [];
+    const explicit = readOption(args, '--profile', null);
+    if (explicit && !['migration', 'full', 'capabilities', 'fast', 'fix'].includes(String(explicit))) {
+        warnings.push(`unknown_profile:${explicit}; supported profiles: migration, full, capabilities, fast, fix`);
+    }
+    for (const flag of unknownDoctorFlags(args))
+        warnings.push(`unknown_flag:${flag}`);
+    return warnings;
+}
+function unknownDoctorFlags(args = []) {
+    const knownBoolean = new Set([
+        '--fix', '--yes', '-y', '--machine-only', '--actual-codex', '--require-actual-codex',
+        '--full', '--capabilities', '--repair-codex-app-ui', '--repair-zellij', '--install-homebrew',
+        '--repair-native-capabilities', '--repair-codex-native', '--local-only', '--project', '--global',
+        '--dry-run', '--json'
+    ]);
+    const knownValue = new Set(['--profile', '--report-file', '--codex-bin', '--install-scope']);
+    const unknown = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = String(args[index] || '');
+        if (!arg.startsWith('-'))
+            continue;
+        if (knownValue.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (knownBoolean.has(arg))
+            continue;
+        unknown.push(arg);
+    }
+    return unknown;
+}
 function doctorPhaseIdsForProfile(profile) {
     const required = [
         'codex_startup_repair',
         'startup_config_repair',
         'context7_repair',
         'context7_mcp_repair',
+        'hook_trust_repair',
         'command_alias_cleanup'
     ];
     if (profile === 'migration')

package/dist/commands/proof.js

@@ -99,6 +99,7 @@ export async function run(_command, args = []) {
         const result = await writeRouteCompletionProof(root, {
             missionId,
             route: '$SKS',
+            executionClass: 'real',
             status: 'verified_partial',
             evidence,
             summary: {
@@ -119,8 +120,9 @@ export async function run(_command, args = []) {
     if (action === 'smoke') {
         const evidence = await collectProofEvidence(root);
         const result = await writeCompletionProof(root, {
+            execution_class: 'mock_fixture',
             route: '$SKS',
-            status: 'verified_partial',
+            status: 'mock_only',
             summary: {
                 files_changed: evidence.files?.length || 0,
                 commands_run: 1,
@@ -130,8 +132,9 @@ export async function run(_command, args = []) {
             },
             evidence,
             claims: [{ id: 'proof-smoke', status: 'supported', evidence: '.sneakoscope/proof/latest.json' }],
-            unverified: ['Smoke proof is fixture evidence, not a real route completion.']
-        }, { command: { cmd: 'sks proof smoke', status: 'verified_partial' } });
+            unverified: ['Smoke proof is fixture evidence, not a real route completion.'],
+            blockers: ['proof_smoke_fixture_cannot_claim_real_completion']
+        }, { command: { cmd: 'sks proof smoke', status: 'mock_only' } });
         if (flag(args, '--json'))
             return printJson(result);
         console.log(`Completion proof written: ${result.files.latest_json}`);

package/dist/commands/zellij-monitor-pane.js

@@ -0,0 +1,25 @@
+import { readZellijSlotTelemetrySnapshot } from '../core/zellij/zellij-slot-telemetry.js';
+import { renderZellijMonitor } from '../core/zellij/zellij-monitor-renderer.js';
+import { projectRoot } from '../core/fsx.js';
+export async function run(_cmd = 'zellij-monitor-pane', args = []) {
+    const mission = readOption(args, '--mission', 'latest') || 'latest';
+    const root = await projectRoot();
+    const intervalMs = Math.max(500, Number(readOption(args, '--interval-ms', String(process.env.SKS_ZELLIJ_REFRESH_MS || '1000')) || 1000));
+    const once = !flag(args, '--watch');
+    for (;;) {
+        const snapshot = await readZellijSlotTelemetrySnapshot(root, mission).catch(() => null);
+        const text = renderZellijMonitor({ snapshot, missionId: mission, root });
+        process.stdout.write(`\x1b[H${text}\n\x1b[0J`);
+        if (once)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+function readOption(args, name, fallback) {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] ? String(args[index + 1]) : fallback;
+}
+function flag(args, name) {
+    return args.includes(name);
+}
+//# sourceMappingURL=zellij-monitor-pane.js.map

package/dist/commands/zellij-slot-pane.js

@@ -7,6 +7,14 @@ export async function run(_command = 'zellij-slot-pane', args = []) {
     const generationIndex = Number(readOption(args, '--generation', '1') || 1);
     const backend = readOption(args, '--backend', null);
     const role = readOption(args, '--role', null);
+    const envDefaults = {
+        provider: process.env.SKS_SLOT_PROVIDER || null,
+        model: process.env.SKS_SLOT_MODEL || null,
+        serviceTier: process.env.SKS_SLOT_TIER || null,
+        reasoningEffort: process.env.SKS_SLOT_REASONING || null,
+        currentTask: process.env.SKS_SLOT_TASK || null,
+        role: process.env.SKS_SLOT_ROLE || role
+    };
     const mode = readOption(args, '--mode', 'compact-slots');
     const watch = hasFlag(args, '--watch');
     const json = hasFlag(args, '--json');
@@ -16,8 +24,32 @@ export async function run(_command = 'zellij-slot-pane', args = []) {
         console.log(JSON.stringify(status, null, 2));
         return;
     }
+    let staleTicks = 0;
     for (;;) {
-        const text = await renderZellijSlotPaneFromArtifacts({ artifactDir, artifactRoot, missionId, slotId, generationIndex, backend, role, mode });
+        let text = '';
+        let heartbeatAgeMs = null;
+        try {
+            text = await renderZellijSlotPaneFromArtifacts({
+                artifactDir,
+                artifactRoot,
+                missionId,
+                slotId,
+                generationIndex,
+                backend,
+                role: envDefaults.role,
+                provider: envDefaults.provider,
+                model: envDefaults.model,
+                serviceTier: envDefaults.serviceTier,
+                reasoningEffort: envDefaults.reasoningEffort,
+                currentTask: envDefaults.currentTask,
+                mode
+            });
+            const status = await renderZellijSlotPaneStatusFromArtifacts({ artifactDir, artifactRoot, missionId, slotId, generationIndex }).catch(() => null);
+            heartbeatAgeMs = Number.isFinite(Number(status?.telemetry_age_ms)) ? Number(status?.telemetry_age_ms) : null;
+        }
+        catch (err) {
+            text = `render error: ${err?.message || String(err)}`;
+        }
         process.stdout.write(redrawFrame(text));
         if (!watch)
             break;
@@ -27,10 +59,15 @@ export async function run(_command = 'zellij-slot-pane', args = []) {
         const shouldExit = await resolveZellijSlotPaneExit({ artifactDir, artifactRoot, missionId, slotId, generationIndex }).catch(() => false);
         if (shouldExit) {
             await new Promise((resolve) => setTimeout(resolve, 5000));
-            const finalText = await renderZellijSlotPaneFromArtifacts({ artifactDir, artifactRoot, missionId, slotId, generationIndex, backend, role, mode });
+            const finalText = await renderZellijSlotPaneFromArtifacts({ artifactDir, artifactRoot, missionId, slotId, generationIndex, backend, role: envDefaults.role, provider: envDefaults.provider, model: envDefaults.model, serviceTier: envDefaults.serviceTier, reasoningEffort: envDefaults.reasoningEffort, currentTask: envDefaults.currentTask, mode });
             process.stdout.write(redrawFrame(finalText));
             return;
         }
+        staleTicks = heartbeatAgeMs != null && heartbeatAgeMs > 5 * 60 * 1000 ? staleTicks + 1 : 0;
+        if (staleTicks >= 5) {
+            process.stdout.write(redrawFrame(`${text}\n⏱ worker heartbeat lost >5m - pane closing (sks pipeline status 로 확인)`));
+            return;
+        }
         await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
 }

package/dist/commands/zellij-viewport-pane.js

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { flag, readOption } from '../cli/args.js';
+import { projectRoot, readJson } from '../core/fsx.js';
+import { readZellijSlotTelemetrySnapshot } from '../core/zellij/zellij-slot-telemetry.js';
+import { bindViewports } from '../core/zellij/zellij-viewport-binder.js';
+import { renderZellijSlotPaneFromArtifacts } from '../core/zellij/zellij-slot-pane-renderer.js';
+import { ANSI_CODES, paint, resolveZellijTheme } from '../core/zellij/zellij-theme.js';
+let previousBindings = [];
+export async function run(_cmd = 'zellij-viewport-pane', args = []) {
+    const mission = String(readOption(args, '--mission', 'latest') || 'latest');
+    const index = Math.max(1, Number(readOption(args, '--index', '1')) || 1);
+    const of = Math.max(index, Number(readOption(args, '--of', '4')) || 4);
+    const intervalMs = Math.max(500, Number(process.env.SKS_ZELLIJ_REFRESH_MS || 1000));
+    const root = await projectRoot();
+    previousBindings = Array.from({ length: of }, () => null);
+    const once = !flag(args, '--watch');
+    for (;;) {
+        const frame = await renderViewportFrame(root, mission, index, of).catch((err) => `viewport render error: ${err?.message || String(err)}`);
+        process.stdout.write(`\x1b[H${frame}\n\x1b[0J`);
+        if (once)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+async function renderViewportFrame(root, mission, index, of) {
+    const theme = resolveZellijTheme();
+    const snapshot = await readZellijSlotTelemetrySnapshot(root, mission).catch(() => null);
+    const missionId = snapshot?.mission_id || mission;
+    const pins = await readJson(pinsPath(root, missionId), { pins: [] });
+    const bindings = bindViewports({
+        snapshot,
+        pins: pins.pins || [],
+        previous: previousBindings,
+        viewportCount: of
+    });
+    previousBindings = bindings.map((binding) => binding.slotKey);
+    const mine = bindings[index - 1] || { slotKey: null, reason: 'idle' };
+    const badge = mine.reason === 'pinned' ? 'pinned' : mine.reason === 'kept' ? 'auto' : mine.reason;
+    const header = paint(theme, ANSI_CODES.dim, `viewport ${index}/${of} | ${mine.slotKey ?? '-'} (${badge})`);
+    if (!mine.slotKey)
+        return `${header}\n${paint(theme, ANSI_CODES.dim, `idle - no active worker. Pin: sks zellij pin <slot> --viewport ${index}`)}`;
+    const [slotId, rawGen] = mine.slotKey.split(':g');
+    const generationIndex = Math.max(1, Number(rawGen || 1) || 1);
+    const detail = await renderZellijSlotPaneFromArtifacts({
+        artifactRoot: root,
+        missionId,
+        artifactDir: path.join(root, '.sneakoscope', 'missions', missionId, 'agents', 'sessions', slotId || mine.slotKey, `gen-${generationIndex}`, 'worker'),
+        slotId: slotId || mine.slotKey,
+        generationIndex
+    });
+    return `${header}\n${detail}`;
+}
+function pinsPath(root, missionId) {
+    return path.join(root, '.sneakoscope', 'missions', missionId, 'zellij', 'viewport-pins.json');
+}
+//# sourceMappingURL=zellij-viewport-pane.js.map

package/dist/commands/zellij.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs';
-import { projectRoot, readJson } from '../core/fsx.js';
+import { nowIso, projectRoot, readJson, writeJsonAtomic } from '../core/fsx.js';
 import { flag } from '../cli/args.js';
 import { printJson } from '../cli/output.js';
 import { checkZellijCapability } from '../core/zellij/zellij-capability.js';
@@ -8,6 +8,7 @@ import { checkZellijUpdateNotice, upgradeZellijToLatest } from '../core/zellij/z
 import { runZellij } from '../core/zellij/zellij-command.js';
 import { appendZellijLaneCommand, normalizeZellijSlot } from '../core/zellij/zellij-lane-runtime.js';
 import { buildZellijDashboardSnapshot, renderZellijDashboardText } from '../core/zellij/zellij-dashboard-renderer.js';
+import { readZellijSlotTelemetrySnapshot } from '../core/zellij/zellij-slot-telemetry.js';
 export const ZELLIJ_COMMAND_SCHEMA = 'sks.zellij-command.v1';
 export const ZELLIJ_REPAIR_SCHEMA = 'sks.zellij-repair.v1';
 function installHint() {
@@ -37,6 +38,8 @@ export async function run(_command = 'zellij', args = []) {
         return zellijDashboard(root, args, json);
     if (sub === 'close-drained')
         return zellijCloseDrained(root, args, json);
+    if (sub === 'pin' || sub === 'unpin')
+        return zellijViewportPin(root, sub, args, json);
     return zellijStatus(root, args, json);
 }
 async function zellijStatus(root, args, json) {
@@ -230,6 +233,41 @@ async function zellijCloseDrained(root, args, json) {
     if (!out.ok)
         process.exitCode = 1;
 }
+async function zellijViewportPin(root, action, args, json) {
+    const missionId = resolveMissionId(root, readOption(args, '--mission', readOption(args, '--mission-id', 'latest') || 'latest') || 'latest');
+    const slotArg = positionalAfter(args, action) || readOption(args, '--slot', '');
+    const viewport = Math.max(1, Number(readOption(args, '--viewport', '1')) || 1);
+    const file = path.join(root, '.sneakoscope', 'missions', missionId, 'zellij', 'viewport-pins.json');
+    const cur = await readJson(file, { pins: [] });
+    const slotKey = slotArg ? await resolveLatestGenKey(root, missionId, slotArg) : '';
+    const pins = (cur.pins || []).filter((pin) => pin.viewport !== viewport && (!slotKey || pin.slot_key !== slotKey));
+    const blockers = slotArg ? [] : ['slot_required'];
+    if (action === 'pin' && slotKey && blockers.length === 0)
+        pins.push({ viewport, slot_key: slotKey });
+    await writeJsonAtomic(file, {
+        schema: 'sks.zellij-viewport-pins.v1',
+        updated_at: nowIso(),
+        pins
+    });
+    const out = {
+        schema: 'sks.zellij-viewport-pin-command.v1',
+        ok: blockers.length === 0,
+        action,
+        mission_id: missionId,
+        viewport,
+        slot_key: slotKey || null,
+        pins,
+        blockers
+    };
+    if (json)
+        printJson(out);
+    else if (out.ok)
+        console.log(action === 'pin' ? `pinned ${slotKey} -> viewport ${viewport}` : `unpinned ${slotKey}`);
+    else
+        console.log('Usage: sks zellij pin <slot> [--viewport N] [--mission M]');
+    if (!out.ok)
+        process.exitCode = 1;
+}
 async function zellijDispatch(root, args, json) {
     const missionId = readOption(args, '--mission', readOption(args, '--mission-id', 'latest') || 'latest') || 'latest';
     const slotId = normalizeZellijSlot(readOption(args, '--slot', 'slot-001'));
@@ -320,7 +358,7 @@ function printHelp(json) {
         schema: ZELLIJ_COMMAND_SCHEMA,
         subcommand: 'help',
         ok: true,
-        usage: 'sks zellij status|update|repair|dispatch|send|focus-worker|worker-logs|dashboard|close-drained [--json]',
+        usage: 'sks zellij status|update|repair|dispatch|send|focus-worker|worker-logs|dashboard|pin|unpin|close-drained [--json]',
         subcommands: {
             status: 'Report Zellij runtime capability and interactive-route readiness.',
             update: 'Check the latest stable Zellij release; apply the upgrade with --yes (Homebrew).',
@@ -330,6 +368,8 @@ function printHelp(json) {
             'focus-worker': 'Focus a visible right-column worker pane by slot.',
             'worker-logs': 'Print stdout/stderr log paths for worker slots.',
             dashboard: 'Render the latest dashboard snapshot; --watch prints watch metadata.',
+            pin: 'Pin a dynamic worker slot to a viewport.',
+            unpin: 'Remove a worker slot pin from a viewport.',
             'close-drained': 'Close drained right-column panes.',
             capability: 'Alias for status.'
         }
@@ -345,6 +385,8 @@ function printHelp(json) {
         console.log('  sks zellij focus-worker slot-001 [--mission M] [--json]');
         console.log('  sks zellij worker-logs [slot-001] [--mission M] [--json]');
         console.log('  sks zellij dashboard [--mission M] [--watch] [--json]');
+        console.log('  sks zellij pin slot-001 [--viewport 2] [--mission M] [--json]');
+        console.log('  sks zellij unpin slot-001 [--viewport 2] [--mission M] [--json]');
         console.log('  sks zellij close-drained [--mission M] [--json]');
     }
 }
@@ -380,4 +422,15 @@ function resolveMissionId(root, requested) {
         return 'latest';
     }
 }
+async function resolveLatestGenKey(root, missionId, rawSlot) {
+    const raw = String(rawSlot || '').trim();
+    if (raw.includes(':g'))
+        return raw;
+    const slotId = normalizeZellijSlot(raw);
+    const snapshot = await readZellijSlotTelemetrySnapshot(root, missionId).catch(() => null);
+    const candidates = Object.entries(snapshot?.slots || {})
+        .filter(([, row]) => normalizeZellijSlot(row.slot_id) === slotId)
+        .sort(([, a], [, b]) => Number(b.generation_index || 1) - Number(a.generation_index || 1));
+    return candidates[0]?.[0] || `${slotId}:g1`;
+}
 //# sourceMappingURL=zellij.js.map