sneakoscope 7.1.0 → 7.3.0

package/dist/core/commands/release-command.js

@@ -5,13 +5,37 @@ import { flag } from '../../cli/args.js';
 import { printJson } from '../../cli/output.js';
 import { exists, projectRoot, readJson, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
 import { createMission } from '../mission.js';
+import { stagePublish } from '../release/stage-publish.js';
+export function usage() {
+    return [
+        'Usage: sks release affected|full|background|stage [--json]',
+        '',
+        'Run affected release proof, full release proof, or background release proof explicitly.',
+        '',
+        'Subcommands:',
+        '  affected     Changed-scope release proof (default)',
+        '  full         Full foreground release gate graph',
+        '  background   Full release gate graph, detached logs',
+        '  stage        Drive the staged npm publish up to the human approval step',
+        '',
+        'Options for stage:',
+        '  --confirm            Perform the outward steps: push main, dispatch the',
+        '                       stage workflow, wait, download and verify the tarball.',
+        '                       Without it, stage only reports what it would do.',
+        '  --version <semver>   Version to stage (defaults to package.json).',
+        '',
+        'stage never runs `npm stage approve`; that approval is a human 2FA step.'
+    ].join('\n');
+}
 export async function releaseCommand(args = []) {
     const root = await projectRoot();
     const sub = args[0] && !args[0].startsWith('-') ? args[0] : 'affected';
     const json = flag(args, '--json');
+    if (sub === 'stage')
+        return runStageSubcommand(root, args, json);
     const command = commandForSubcommand(sub);
     if (!command) {
-        console.error('Usage: sks release affected|full|background [--json]');
+        console.error(usage());
         process.exitCode = 1;
         return null;
     }
@@ -63,6 +87,44 @@ export async function releaseCommand(args = []) {
         process.stderr.write(result.stderr);
     return report;
 }
+async function runStageSubcommand(root, args, json) {
+    const report = stagePublish({
+        root,
+        confirm: flag(args, '--confirm'),
+        run: spawnRunner(root),
+        ...(readOption(args, '--version') ? { version: readOption(args, '--version') } : {})
+    });
+    await writeJsonAtomic(path.join(root, '.sneakoscope', 'reports', 'release-stage-publish.json'), report).catch(() => { });
+    if (!report.ok)
+        process.exitCode = 1;
+    if (json)
+        return printJson(report);
+    for (const step of report.steps) {
+        const mark = step.blocker ? '✖' : step.attempted ? '✔' : '·';
+        console.log(`${mark} ${step.id}${step.detail ? ` — ${step.detail}` : ''}${step.blocker ? ` (${step.blocker})` : ''}`);
+    }
+    if (report.stage_id)
+        console.log(`\nStage id: ${report.stage_id}`);
+    for (const action of report.next_actions)
+        console.log(`- ${action}`);
+    return report;
+}
+function spawnRunner(root) {
+    return (command, commandArgs, opts = {}) => {
+        const result = spawnSync(command, [...commandArgs], {
+            cwd: root,
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024 * 20,
+            ...(opts.timeoutMs ? { timeout: opts.timeoutMs } : {})
+        });
+        return { status: result.status, stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
+    };
+}
+function readOption(args, name) {
+    const index = args.indexOf(name);
+    const value = index >= 0 ? args[index + 1] : null;
+    return value && !value.startsWith('-') ? value : null;
+}
 async function findReleaseReadinessReport(root) {
     const candidates = [
         path.join(root, 'release-readiness-report.json'),

package/dist/core/commands/remote-command.js

@@ -1,7 +1,12 @@
 import path from 'node:path';
+import { isHelpRequest } from '../../cli/help.js';
 import { globalSksRoot, projectRoot, readJson, sha256 } from '../fsx.js';
 import { findRemoteMachine, loadRemoteMachineRegistry, remoteMachineRegistryPath, remoteReadiness, RemoteWorker, resolveAllowedProjectRoot, runRemoteWorkerJsonl, selectWorkerMachine, validateRemoteMachineRegistry } from '../remote/index.js';
 export async function remoteCommand(args = []) {
+    if (isHelpRequest(args)) {
+        printRemoteUsage();
+        return { schema: 'sks.remote-command.v1', ok: true, action: 'help' };
+    }
     const action = args[0] ?? 'readiness';
     const rest = args.slice(1);
     const json = args.includes('--json');
@@ -90,6 +95,19 @@ function readOption(args, name) {
     const index = args.indexOf(name);
     return index >= 0 && args[index + 1] ? String(args[index + 1]) : null;
 }
+function printRemoteUsage() {
+    console.log(`SKS Remote — local machine registry and worker transport
+
+Usage:
+  sks remote readiness [--json]
+  sks remote machines list [--json]
+  sks remote machines validate [--json]
+  sks remote worker --stdio
+
+The machine registry and session targets are written by \`sks telegram setup\`;
+see docs/telegram-and-center.md for the end-to-end pairing flow.
+`);
+}
 function fail(error, supported, json) {
     process.exitCode = 2;
     return print({ schema: 'sks.remote-command.v1', ok: false, error, supported }, json);

package/dist/core/commands/search-command.js

@@ -0,0 +1,151 @@
+import { flag } from '../../cli/args.js';
+import { printJson } from '../../cli/output.js';
+import { projectRoot } from '../fsx.js';
+import { buildSearchDoctorReport, printSearchDoctorReport, runSearchEngineBenchmark, search, searchCapabilities, SEARCH_SCHEMA_VERSION } from '../search/index.js';
+export async function searchCommand(subcommand = 'status', args = []) {
+    const action = subcommand || 'status';
+    if (action === 'status')
+        return statusCommand(args);
+    if (action === 'files')
+        return modeCommand('files', args);
+    if (action === 'text')
+        return modeCommand('text', args);
+    if (action === 'structure')
+        return modeCommand('structure', args);
+    if (action === 'symbol')
+        return modeCommand('symbol', args);
+    if (action === 'context')
+        return modeCommand('context', args);
+    if (action === 'benchmark' || action === 'bench')
+        return benchmarkCommand(args);
+    if (action === 'doctor')
+        return doctorCommand(args);
+    if (action === 'help')
+        return helpCommand();
+    return helpCommand();
+}
+async function statusCommand(args) {
+    const root = await projectRoot(process.cwd());
+    const caps = await searchCapabilities(root);
+    if (flag(args, '--json') || args.includes('--json'))
+        return printJson(caps);
+    console.log(`Search engines schemaVersion=${caps.schemaVersion}`);
+    for (const [mode, info] of Object.entries(caps.modes)) {
+        console.log(`- ${mode}: ${info.available ? 'available' : 'unavailable'} via ${info.provider}/${info.engine}`);
+    }
+    console.log(`Rust: ${caps.rust.available ? caps.rust.version : 'js_fallback'}`);
+    if (caps.warnings.length)
+        console.log(`Warnings: ${caps.warnings.join(', ')}`);
+    return caps;
+}
+async function modeCommand(mode, args) {
+    const root = readOption(args, '--root') || (await projectRoot(process.cwd()));
+    const pattern = readOption(args, '--pattern') || positional(args).join(' ').trim();
+    const language = readOption(args, '--language') || undefined;
+    const include = readMulti(args, '--include');
+    const exclude = readMulti(args, '--exclude');
+    const json = flag(args, '--json') || args.includes('--json');
+    if (!pattern && mode !== 'files') {
+        throw new Error(`Usage: sks search ${mode} <pattern> [--json] [--include glob] [--exclude glob]`);
+    }
+    const request = {
+        schemaVersion: SEARCH_SCHEMA_VERSION,
+        mode,
+        root,
+        caseSensitive: !args.includes('--ignore-case'),
+        limits: {
+            maxMatches: numOption(args, '--max-matches', 500),
+            timeoutMs: numOption(args, '--timeout-ms', 30_000)
+        }
+    };
+    if (mode === 'files' || mode === 'symbol' || mode === 'context')
+        request.query = pattern;
+    if (mode === 'text' || mode === 'structure')
+        request.pattern = pattern;
+    if (language)
+        request.language = language;
+    if (include.length)
+        request.include = include;
+    if (exclude.length)
+        request.exclude = exclude;
+    const why = readOption(args, '--why');
+    if (why)
+        request.why = why;
+    const result = await search(request);
+    if (json)
+        return printJson(result);
+    console.log(`${mode}: ${result.ok ? 'ok' : 'failed'} provider=${result.provider} matches=${result.matches.length} spawns=${result.processSpawns}`);
+    for (const m of result.matches.slice(0, 30)) {
+        const loc = m.line ? `:${m.line}${m.column ? `:${m.column}` : ''}` : '';
+        console.log(`  ${m.path}${loc} [${m.confidence}] ${m.text || ''}`.trim());
+    }
+    if (result.matches.length > 30)
+        console.log(`  ... ${result.matches.length - 30} more`);
+    if (result.errors.length)
+        console.log(`Errors: ${result.errors.join(', ')}`);
+    if (!result.ok)
+        process.exitCode = 1;
+    return result;
+}
+async function benchmarkCommand(args) {
+    const report = await runSearchEngineBenchmark({ writeArtifacts: true });
+    if (flag(args, '--json') || args.includes('--json'))
+        return printJson(report);
+    console.log(`Benchmark: ${report.summary.ok_count}/${report.summary.scenario_count} ok`);
+    console.log(`Artifacts: .sneakoscope/reports/search-engine-benchmark.json, docs/performance/search-engine-benchmark.md`);
+    return report;
+}
+async function doctorCommand(args) {
+    const report = await buildSearchDoctorReport(args);
+    printSearchDoctorReport(report, flag(args, '--json') || args.includes('--json'));
+    if (!report.ok)
+        process.exitCode = 1;
+    return report;
+}
+function helpCommand() {
+    console.log(`sks search status --json
+sks search files <query> [--json]
+sks search text <pattern> [--json] [--ignore-case]
+sks search structure <kind> [name] --language typescript [--json]
+sks search symbol <ident> [--json]
+sks search context <query> [--why reason] [--json]
+sks search benchmark --json
+sks search doctor --json`);
+}
+function readOption(args, name) {
+    const idx = args.indexOf(name);
+    if (idx < 0)
+        return null;
+    return args[idx + 1] || null;
+}
+function readMulti(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === name && args[i + 1]) {
+            out.push(args[i + 1]);
+            i += 1;
+        }
+    }
+    return out;
+}
+function numOption(args, name, fallback) {
+    const raw = readOption(args, name);
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
+function positional(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            if (a === '--json' || a === '--ignore-case')
+                continue;
+            i += 1;
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}

package/dist/core/commands/telegram-command.js

@@ -1,125 +1,257 @@
 import path from 'node:path';
-import { globalSksRoot, projectRoot, readJson } from '../fsx.js';
-import { loadRemoteMachineRegistry, loadRemoteSessionIndex, remoteMachineRegistryPath, remoteSessionIndexPath, validateRemoteMachineRegistry, validateRemoteSessionIndex } from '../remote/index.js';
-import { loadTelegramConfig, resolveTelegramBotToken, TelegramActionBroker, TelegramAuditLedger, TelegramBotApiClient, TelegramHubRouter, TelegramHubRuntime, TelegramIdempotencyLedger, TelegramOwnerLock, TelegramMessageProjector, TelegramPollingHub, TelegramTopicRegistry, telegramHubPaths, telegramTokenFingerprint, validateTelegramConfig } from '../telegram/index.js';
+import { isHelpRequest } from '../../cli/help.js';
+import { globalSksRoot, projectRoot, readJson, readStdin } from '../fsx.js';
+import { RemoteCodexSessionBindingStore, loadRemoteMachineRegistry, loadRemoteSessionIndex, remoteCodexSessionBindingsPath, remoteMachineRegistryPath, remoteSessionIndexPath, validateRemoteMachineRegistry, validateRemoteSessionIndex } from '../remote/index.js';
+import { loadTelegramConfig, resolveTelegramBotToken, TelegramActionBroker, TelegramAuditLedger, TelegramBotApiClient, TelegramHubRouter, TelegramHubRuntime, TelegramIdempotencyLedger, TelegramOwnerLock, TelegramMessageProjector, TelegramPollingHub, TelegramTopicRegistry, installAndStartTelegramHubService, restartTelegramHubService, setupTelegramLocalCoding, stopTelegramHubService, telegramHubPaths, telegramHubServiceStatus, telegramTokenFingerprint, validateTelegramConfig, validateTelegramPrivatePairing } from '../telegram/index.js';
 export async function telegramCommand(args = []) {
+    if (isHelpRequest(args)) {
+        printTelegramUsage();
+        return { schema: 'sks.telegram-command.v1', ok: true, action: 'help' };
+    }
     const action = args[0] ?? 'status';
     const root = globalSksRoot();
     const paths = telegramHubPaths(root);
     const configPath = readOption(args, '--config') ?? paths.config;
     const json = args.includes('--json');
-    if (action === 'status') {
-        const rawConfig = await readJson(configPath, null);
-        const validation = validateTelegramConfig(rawConfig);
-        const owner = await readJson(paths.owner, null);
-        const topics = await new TelegramTopicRegistry(paths.topics).list();
-        const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
-        const machineRegistryRaw = await readJson(readOption(args, '--machines') ?? remoteMachineRegistryPath(root), null);
-        const machineValidation = validateRemoteMachineRegistry(machineRegistryRaw);
-        const sessionIndexRaw = await readJson(readOption(args, '--session-index') ?? remoteSessionIndexPath(controllingRoot), null);
-        const sessionValidation = machineValidation.registry
-            ? validateRemoteSessionIndex(sessionIndexRaw, machineValidation.registry)
-            : { ok: false, issues: ['remote_machine_registry_invalid'], index: null };
-        const result = {
-            schema: 'sks.telegram-status.v1',
-            ok: validation.ok && machineValidation.ok && sessionValidation.ok,
-            configured: rawConfig !== null,
-            config_issues: validation.issues,
-            owner: owner ? {
-                pid: owner.pid,
-                host: owner.host,
-                process_start_time: owner.process_start_time,
-                bot_token_fingerprint: owner.bot_token_fingerprint,
-                heartbeat_at: owner.heartbeat_at
-            } : null,
-            topic_count: topics.length,
-            machine_count: machineValidation.registry?.machines.length ?? 0,
-            target_count: sessionValidation.index?.targets.length ?? 0,
-            remote_config_issues: [...machineValidation.issues, ...sessionValidation.issues]
-        };
-        return print(result, json);
-    }
-    if (action === 'validate-config') {
-        const validation = validateTelegramConfig(await readJson(configPath, null));
-        return print({ schema: 'sks.telegram-config-validation.v1', ...validation, config: validation.config ? redactConfig(validation.config) : null }, json);
-    }
-    if (action === 'hub') {
-        const config = await loadTelegramConfig(configPath);
-        const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
-        const machineRegistry = await loadRemoteMachineRegistry(readOption(args, '--machines') ?? remoteMachineRegistryPath(root));
-        const sessionIndex = await loadRemoteSessionIndex(readOption(args, '--session-index') ?? remoteSessionIndexPath(controllingRoot), machineRegistry);
-        const token = await resolveTelegramBotToken(config.bot_token_ref);
-        const fingerprint = telegramTokenFingerprint(token);
-        const owner = new TelegramOwnerLock({
-            lockPath: paths.owner,
-            tokenFingerprint: fingerprint,
-            ...(config.owner_stale_ms === undefined ? {} : { staleMs: config.owner_stale_ms })
-        });
-        await owner.acquire();
-        const topics = new TelegramTopicRegistry(paths.topics);
-        const actions = new TelegramActionBroker(paths.actions);
-        const audit = new TelegramAuditLedger(paths.audit, fingerprint);
-        const router = new TelegramHubRouter({
-            config,
-            topics,
-            idempotency: new TelegramIdempotencyLedger(paths.idempotency),
-            actions,
-            audit
-        });
-        const api = new TelegramBotApiClient(token, { timeoutMs: (config.long_poll_timeout_sec ?? 25) * 1000 + 5_000 });
-        const runtime = new TelegramHubRuntime({
-            config,
-            router,
-            topics,
-            actions,
-            audit,
-            projector: new TelegramMessageProjector(api, {
-                rich_message: true,
-                rich_draft: true,
-                plain_draft: true,
-                reactions: true
-            }, {
-                protectContent: config.protect_content !== false,
-                silent: config.silent_notifications === true
-            }),
-            machineRegistry,
-            sessionIndex,
-            projectionStatePath: paths.projection
-        });
-        const polling = new TelegramPollingHub(api, runtime, owner, config.long_poll_timeout_sec ?? 25);
-        try {
-            await polling.ensureLongPollingAllowed();
-            const sync = await runtime.initialize();
-            if (args.includes('--once')) {
-                const result = await polling.pollOnce();
-                return print({ schema: 'sks.telegram-hub-run.v1', ...result, sync }, json);
+    try {
+        if (action === 'status') {
+            return print(await telegramStatus(args, root, paths, configPath), json);
+        }
+        if (action === 'setup') {
+            if (!args.includes('--bot-token-stdin'))
+                return fail('bot_token_stdin_required', ['setup --bot-token-stdin --project-root <path>'], json);
+            const token = (await readStdin()).trim();
+            const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+            const result = await setupTelegramLocalCoding({
+                token,
+                projectRoot: controllingRoot,
+                pairedChatId: readOption(args, '--paired-chat-id'),
+                pairedUserId: readOption(args, '--paired-user-id'),
+                resetSession: args.includes('--new-session'),
+                globalRoot: root
+            });
+            return print(result, json);
+        }
+        if (action === 'validate-config') {
+            const validation = validateTelegramConfig(await readJson(configPath, null));
+            return print({ schema: 'sks.telegram-config-validation.v1', ...validation, config: validation.config ? redactConfig(validation.config) : null }, json);
+        }
+        if (action === 'hub') {
+            const hubAction = args[1] && !String(args[1]).startsWith('-') ? String(args[1]) : 'run';
+            const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+            if (hubAction === 'start') {
+                await assertHubSetupReady(controllingRoot, root, configPath);
+                return print(await installAndStartTelegramHubService({ projectRoot: controllingRoot, globalRoot: root }), json);
+            }
+            if (hubAction === 'stop') {
+                return print(await stopTelegramHubService({ projectRoot: controllingRoot, globalRoot: root }), json);
             }
-            const controller = new AbortController();
-            const stop = () => controller.abort();
-            process.once('SIGINT', stop);
-            process.once('SIGTERM', stop);
-            try {
-                const result = await polling.run(controller.signal);
-                return print({ schema: 'sks.telegram-hub-run.v1', ...result, sync }, json);
+            if (hubAction === 'restart') {
+                await assertHubSetupReady(controllingRoot, root, configPath);
+                return print(await restartTelegramHubService({ projectRoot: controllingRoot, globalRoot: root }), json);
             }
-            finally {
-                process.off('SIGINT', stop);
-                process.off('SIGTERM', stop);
+            if (hubAction === 'status') {
+                return print(await telegramHubServiceStatus({ projectRoot: controllingRoot, globalRoot: root }), json);
             }
+            if (hubAction !== 'run')
+                return fail('unknown_hub_action', ['hub run', 'hub start', 'hub stop', 'hub restart', 'hub status'], json);
+            return runHub(args, root, paths, configPath, json);
+        }
+    }
+    catch (err) {
+        process.exitCode = 1;
+        return print({
+            schema: 'sks.telegram-command-error.v1',
+            ok: false,
+            error: publicError(err)
+        }, json);
+    }
+    return fail('unknown_action', [
+        'status',
+        'setup --bot-token-stdin --project-root <path>',
+        'validate-config',
+        'hub run|start|stop|restart|status'
+    ], json);
+}
+async function telegramStatus(args, root, paths, configPath) {
+    const rawConfig = await readJson(configPath, null);
+    const validation = validateTelegramConfig(rawConfig);
+    const owner = await readJson(paths.owner, null);
+    const topics = await new TelegramTopicRegistry(paths.topics).list();
+    const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+    const machineRegistryRaw = await readJson(readOption(args, '--machines') ?? remoteMachineRegistryPath(root), null);
+    const machineValidation = validateRemoteMachineRegistry(machineRegistryRaw);
+    const sessionIndexRaw = await readJson(readOption(args, '--session-index') ?? remoteSessionIndexPath(controllingRoot), null);
+    const sessionValidation = machineValidation.registry
+        ? validateRemoteSessionIndex(sessionIndexRaw, machineValidation.registry)
+        : { ok: false, issues: ['remote_machine_registry_invalid'], index: null };
+    const bindings = await new RemoteCodexSessionBindingStore(remoteCodexSessionBindingsPath(controllingRoot)).list().catch(() => []);
+    const targets = sessionValidation.index?.targets ?? [];
+    const registered = bindings.filter((binding) => targets.some((target) => (binding.machine_id === target.machine_id
+        && binding.project_id === target.project_id
+        && path.resolve(binding.project_root) === path.resolve(target.project_root))));
+    const service = await telegramHubServiceStatus({ projectRoot: controllingRoot, globalRoot: root });
+    let tokenConfigured = false;
+    if (validation.config) {
+        tokenConfigured = await resolveTelegramBotToken(validation.config.bot_token_ref).then(() => true).catch(() => false);
+    }
+    const pairing = telegramPairingReadiness(rawConfig);
+    const blockers = [
+        ...validation.issues.map((issue) => `config:${issue}`),
+        ...machineValidation.issues.map((issue) => `machine:${issue}`),
+        ...sessionValidation.issues.map((issue) => `target:${issue}`),
+        ...(tokenConfigured ? [] : ['telegram_token_not_available']),
+        ...(pairing.blocker ? [pairing.blocker] : []),
+        ...(registered.length ? [] : ['no_registered_codex_session']),
+        ...(service.running ? [] : ['telegram_hub_not_running'])
+    ];
+    return {
+        schema: 'sks.telegram-status.v1',
+        ok: blockers.length === 0,
+        configured: rawConfig !== null,
+        token_configured: tokenConfigured,
+        pairing_valid: pairing.pairing_valid,
+        pairing_issues: pairing.pairing_issues,
+        hub_running: service.running,
+        service,
+        config_issues: validation.issues,
+        owner: owner ? {
+            pid: owner.pid,
+            host: owner.host,
+            process_start_time: owner.process_start_time,
+            bot_token_fingerprint: owner.bot_token_fingerprint,
+            heartbeat_at: owner.heartbeat_at
+        } : null,
+        topic_count: topics.length,
+        machine_count: machineValidation.registry?.machines.length ?? 0,
+        target_count: sessionValidation.index?.targets.length ?? 0,
+        registered_session_count: registered.length,
+        registered_sessions: registered.map((binding) => ({
+            session_id: binding.session_id,
+            machine_id: binding.machine_id,
+            project_id: binding.project_id,
+            codex_thread_id: binding.codex_thread_id,
+            last_turn_status: binding.last_turn_status ?? null,
+            updated_at: binding.updated_at
+        })),
+        remote_config_issues: [...machineValidation.issues, ...sessionValidation.issues],
+        blockers
+    };
+}
+function printTelegramUsage() {
+    console.log(`SKS Telegram Hub — private, local, single-operator remote coding
+
+Usage:
+  sks telegram status [--project-root <path>] [--json]
+  sks telegram setup --bot-token-stdin --project-root <path> [--paired-chat-id <id>]
+                     [--paired-user-id <id>] [--new-session] [--json]
+  sks telegram validate-config [--config <path>] [--json]
+  sks telegram hub start|stop|restart|status [--project-root <path>] [--json]
+  sks telegram hub run [--project-root <path>] [--json]
+
+Pairing (do these first):
+  1. Create a private bot with @BotFather in Telegram and copy its token.
+  2. Send /start to that bot from the Telegram account you want to pair.
+  3. printf '%s' "<token>" | sks telegram setup --bot-token-stdin --project-root "$PWD" --json
+     The token is read from stdin only and stored in the macOS Keychain.
+  4. sks telegram hub start --project-root "$PWD" --json
+
+The same flow is available in SKS Center → Remote & Telegram.
+See docs/telegram-and-center.md for the full guide and troubleshooting.
+`);
+}
+export function telegramPairingReadiness(value) {
+    const pairing = validateTelegramPrivatePairing(value);
+    return {
+        pairing_valid: pairing.ok,
+        pairing_issues: pairing.issues,
+        blocker: pairing.ok
+            ? null
+            : pairing.missing
+                ? 'telegram_pairing_missing'
+                : `telegram_pairing_invalid:${pairing.issues.join(',')}`
+    };
+}
+async function runHub(args, root, paths, configPath, json) {
+    const config = await loadTelegramConfig(configPath);
+    const controllingRoot = path.resolve(readOption(args, '--project-root') ?? await projectRoot());
+    const machineRegistry = await loadRemoteMachineRegistry(readOption(args, '--machines') ?? remoteMachineRegistryPath(root));
+    const sessionIndex = await loadRemoteSessionIndex(readOption(args, '--session-index') ?? remoteSessionIndexPath(controllingRoot), machineRegistry);
+    const token = await resolveTelegramBotToken(config.bot_token_ref);
+    const fingerprint = telegramTokenFingerprint(token);
+    const owner = new TelegramOwnerLock({
+        lockPath: paths.owner,
+        tokenFingerprint: fingerprint,
+        ...(config.owner_stale_ms === undefined ? {} : { staleMs: config.owner_stale_ms })
+    });
+    await owner.acquire();
+    const topics = new TelegramTopicRegistry(paths.topics);
+    const actions = new TelegramActionBroker(paths.actions);
+    const audit = new TelegramAuditLedger(paths.audit, fingerprint);
+    const router = new TelegramHubRouter({
+        config,
+        topics,
+        idempotency: new TelegramIdempotencyLedger(paths.idempotency),
+        actions,
+        audit
+    });
+    const api = new TelegramBotApiClient(token, { timeoutMs: (config.long_poll_timeout_sec ?? 25) * 1000 + 5_000 });
+    const runtime = new TelegramHubRuntime({
+        config,
+        router,
+        topics,
+        actions,
+        audit,
+        projector: new TelegramMessageProjector(api, {
+            rich_message: true,
+            rich_draft: true,
+            plain_draft: true,
+            reactions: true
+        }, {
+            protectContent: config.protect_content !== false,
+            silent: config.silent_notifications === true
+        }),
+        machineRegistry,
+        sessionIndex,
+        projectionStatePath: paths.projection
+    });
+    const polling = new TelegramPollingHub(api, runtime, owner, config.long_poll_timeout_sec ?? 25);
+    try {
+        await polling.ensureLongPollingAllowed();
+        const sync = await runtime.initialize();
+        if (args.includes('--once')) {
+            const result = await polling.pollOnce();
+            return print({ schema: 'sks.telegram-hub-run.v1', ...result, sync }, json);
+        }
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            const result = await polling.run(controller.signal);
+            return print({ schema: 'sks.telegram-hub-run.v1', ...result, sync }, json);
         }
         finally {
-            await runtime.close();
-            await owner.release();
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
         }
     }
-    const result = {
-        schema: 'sks.telegram-command.v1',
-        ok: false,
-        error: 'unknown_action',
-        supported: ['status', 'validate-config', 'hub']
-    };
-    process.exitCode = 2;
-    return print(result, json);
+    finally {
+        await runtime.close();
+        await owner.release();
+    }
+}
+async function assertHubSetupReady(controllingRoot, globalRoot, configPath) {
+    const config = await loadTelegramConfig(configPath);
+    await resolveTelegramBotToken(config.bot_token_ref);
+    const registry = await loadRemoteMachineRegistry(remoteMachineRegistryPath(globalRoot));
+    const index = await loadRemoteSessionIndex(remoteSessionIndexPath(controllingRoot), registry);
+    const bindings = await new RemoteCodexSessionBindingStore(remoteCodexSessionBindingsPath(controllingRoot)).list();
+    if (!bindings.some((binding) => index.targets.some((target) => (target.machine_id === binding.machine_id
+        && target.project_id === binding.project_id
+        && path.resolve(target.project_root) === path.resolve(binding.project_root))))) {
+        throw new Error('no_registered_codex_session');
+    }
 }
 function readOption(args, name) {
     const index = args.indexOf(name);
@@ -141,3 +273,14 @@ function print(value, json) {
         console.log(JSON.stringify(value, null, 2));
     return value;
 }
+function fail(error, supported, json) {
+    process.exitCode = 2;
+    return print({ schema: 'sks.telegram-command.v1', ok: false, error, supported }, json);
+}
+function publicError(err) {
+    const value = err instanceof Error ? err.message : String(err);
+    return value
+        .replace(/\b\d{5,}:[A-Za-z0-9_-]{20,}\b/g, '[redacted]')
+        .replace(/(?:\/Users|\/home)\/[^\s]+/g, '[path-redacted]')
+        .slice(0, 500);
+}

package/dist/core/commands/uninstall-command.js

@@ -5,7 +5,7 @@ import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { ensureDir, exists, readJson, readText, runProcess, writeJsonAtomic } from '../fsx.js';
 import { ui as cliUi } from '../../cli/cli-theme.js';
-import { uninstallSksMenuBar } from '../codex-app/sks-menubar.js';
+import { uninstallSksMenuBar } from '../codex-app/menubar/index.js';
 import { writeCodexConfigGuarded } from '../codex/codex-config-guard.js';
 import { sweepSksTempDirs } from '../retention.js';
 import { reconcileSkills } from '../init/skills.js';