sneakoscope 7.3.0 → 7.5.0

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

@@ -1,10 +1,13 @@
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { ui as cliUi } from '../../cli/cli-theme.js';
 import { createMission, findLatestMission, getOrCreateExplicitNarutoMission, getOrCreateSessionMission, loadStateForSession, loadMission, sessionStateKey, setCurrent, updateCurrentIfMissionAndRun } from '../mission.js';
 import { closeWorkOrderLedgerForRouteResult, createAndWriteWorkOrderLedgerForPrompt } from '../work-order-ledger.js';
 import { appendJsonl, exists, nowIso, readJson, sksRoot, writeJsonAtomic } from '../fsx.js';
-import { SUBAGENT_EVENT_LOG_FILENAME, SUBAGENT_PARENT_SUMMARY_FILENAME, bindTrustworthySubagentParentSummaryToRun, persistOrReuseTrustworthySubagentParentSummary, readSubagentEvents, writeSubagentEvidence } from '../subagents/subagent-evidence.js';
+import { SUBAGENT_EVENT_LOG_FILENAME, SUBAGENT_EVIDENCE_FILENAME, SUBAGENT_PARENT_SUMMARY_FILENAME, bindTrustworthySubagentParentSummaryToRun, normalizeSubagentParentSummary, persistOrReuseTrustworthySubagentParentSummary, readSubagentEvents, writeSubagentEvidence } from '../subagents/subagent-evidence.js';
 import { buildNarutoHelpResult } from '../subagents/naruto-help-contract.js';
+import { resolveNarutoCredentialPolicy } from '../subagents/naruto-host-credentials.js';
+import { DEFAULT_SUBAGENT_EFFORT, DEFAULT_SUBAGENT_MODEL, NARUTO_PARENT_EFFORT, NARUTO_PARENT_MODEL } from '../subagents/model-policy.js';
 import { buildNarutoProofProjection } from '../subagents/naruto-proof-projection.js';
 import { withFileLock } from '../locks/file-lock.js';
 import { codexAppSessionKey, detectCodexAppSession, runOfficialSubagentWorkflow } from '../subagents/official-subagent-runner.js';
@@ -14,7 +17,9 @@ import { effectiveSubagentTarget, refreshSubagentWaveLifecycle } from '../subage
 import { HOST_CAPABILITY_HOOK_RUNTIME_FILENAME, bindParentSummaryToHostCapabilityEvidence, createHostCapabilityHookRuntimeBinding, resolveHostCapabilityHookRuntimeBinding } from '../agent-bridge/host-capability-runtime.js';
 import { renderHostCapabilityBlockedLines } from '../agent-bridge/host-capability-policy.js';
 import { uniqueStrings } from '../text/strings.js';
+import { completeNarutoTerminalBundle, refreshOfficialSubagentCompletionArtifacts } from '../hooks-runtime/official-subagent-lifecycle.js';
 export { buildNarutoGateResult } from '../subagents/official-subagent-preparation.js';
+const MAX_PARENT_SUMMARY_STDIN_BYTES = 1024 * 1024;
 let nextNarutoPreparationFailureInjectionForTest = null;
 export function injectNextNarutoPreparationFailureForTest(value) {
     nextNarutoPreparationFailureInjectionForTest = value;
@@ -24,6 +29,23 @@ export async function narutoCommand(commandOrArgs = 'naruto', maybeArgs = []) {
     if (args.some((arg) => arg === '--glm' || arg.startsWith('--glm=')))
         return blockGlmOverride(args.includes('--json'));
     const parsed = parseNarutoArgs(args);
+    const credentialPolicy = parsed.credentialPolicy;
+    if (credentialPolicy.blockers.length) {
+        const blocked = {
+            schema: 'sks.naruto-credential-policy.v1',
+            ok: false,
+            blockers: credentialPolicy.blockers,
+            hint: 'sks naruto run --auth-mode=host --model-provider=<config.toml provider block> --provider-env-key=<ENV NAME>'
+        };
+        if (args.includes('--json'))
+            console.log(JSON.stringify(blocked, null, 2));
+        else {
+            console.error(`Naruto credential policy blocked: ${credentialPolicy.blockers.join(', ')}`);
+            console.error(blocked.hint);
+        }
+        process.exitCode = 2;
+        return null;
+    }
     if (parsed.argumentErrors.length) {
         const result = argumentBlock(parsed.argumentErrors);
         return emit(parsed, result, () => {
@@ -41,8 +63,185 @@ export async function narutoCommand(commandOrArgs = 'naruto', maybeArgs = []) {
         return narutoSubagents(parsed);
     if (parsed.action === 'proof')
         return narutoProof(parsed);
+    if (parsed.action === 'parent-summary')
+        return narutoParentSummary(parsed);
     return narutoRun(parsed);
 }
+async function narutoParentSummary(parsed) {
+    const root = await sksRoot();
+    const appSession = detectCodexAppSession();
+    const sessionKey = appSession ? codexAppSessionKey() : null;
+    if (!appSession || !sessionKey) {
+        return blockedParentSummary(parsed, ['naruto_parent_summary_app_session_required']);
+    }
+    return withFileLock({
+        lockPath: path.join(root, '.sneakoscope', 'state', `naruto-session-${sessionStateKey(sessionKey)}.lock`),
+        timeoutMs: 20_000,
+        staleMs: 120_000
+    }, () => narutoParentSummaryTransaction(parsed, root, sessionKey));
+}
+async function narutoParentSummaryTransaction(parsed, root, sessionKey) {
+    const state = await loadStateForSession(root, sessionKey).catch(() => null);
+    const route = String(state?.route || state?.route_command || state?.mode || '')
+        .replace(/^\$/, '')
+        .replace(/[-_]/g, '')
+        .toUpperCase();
+    const stateBlockers = uniqueStrings([
+        ...(state?._session_key === sessionStateKey(sessionKey) ? [] : ['naruto_parent_summary_session_state_mismatch']),
+        ...(state?.session_scope === sessionKey ? [] : ['naruto_parent_summary_session_scope_mismatch']),
+        ...(state?.mission_id === parsed.missionId ? [] : ['naruto_parent_summary_active_mission_mismatch']),
+        ...(route === 'NARUTO' ? [] : ['naruto_parent_summary_active_route_mismatch']),
+        ...(state?.route_closed === true ? ['naruto_parent_summary_route_closed'] : [])
+    ]);
+    if (stateBlockers.length > 0)
+        return blockedParentSummary(parsed, stateBlockers);
+    const loaded = await loadMission(root, parsed.missionId).catch(() => null);
+    if (!loaded)
+        return blockedParentSummary(parsed, [`naruto_parent_summary_mission_not_found:${parsed.missionId}`]);
+    const plan = await readJson(path.join(loaded.dir, SUBAGENT_PLAN_FILENAME), null).catch(() => null);
+    const workflowRunId = String(plan?.workflow_run_id || '').trim();
+    const planBlockers = uniqueStrings([
+        ...(plan?.schema === 'sks.subagent-plan.v1' ? [] : ['naruto_parent_summary_plan_schema_invalid']),
+        ...(plan?.workflow === 'official_codex_subagent' ? [] : ['naruto_parent_summary_plan_workflow_invalid']),
+        ...(plan?.mission_id === parsed.missionId ? [] : ['naruto_parent_summary_plan_mission_mismatch']),
+        ...(plan?.session_scope === sessionKey ? [] : ['naruto_parent_summary_plan_session_scope_mismatch']),
+        ...(workflowRunId ? [] : ['naruto_parent_summary_plan_run_id_missing']),
+        ...(workflowRunId && state?.official_subagent_run_id === workflowRunId
+            ? []
+            : ['naruto_parent_summary_active_run_mismatch'])
+    ]);
+    if (planBlockers.length > 0)
+        return blockedParentSummary(parsed, planBlockers);
+    const stdin = await readBoundedParentSummaryStdin();
+    if (!stdin.ok)
+        return blockedParentSummary(parsed, [stdin.blocker]);
+    const raw = stdin.value;
+    let submitted;
+    try {
+        submitted = JSON.parse(raw);
+    }
+    catch {
+        return blockedParentSummary(parsed, ['naruto_parent_summary_stdin_json_invalid']);
+    }
+    if (!submitted || typeof submitted !== 'object' || Array.isArray(submitted)) {
+        return blockedParentSummary(parsed, ['naruto_parent_summary_stdin_object_required']);
+    }
+    const normalized = normalizeSubagentParentSummary(submitted);
+    const summaryBlockers = uniqueStrings([
+        ...(normalized.trustworthy && normalized.raw ? [] : normalized.blockers.length
+            ? normalized.blockers.map((blocker) => `naruto_parent_summary_schema:${blocker}`)
+            : ['naruto_parent_summary_schema_invalid']),
+        ...(!normalized.run_id
+            ? ['naruto_parent_summary_run_id_missing']
+            : normalized.run_id === workflowRunId
+                ? []
+                : ['naruto_parent_summary_run_id_mismatch'])
+    ]);
+    if (summaryBlockers.length > 0)
+        return blockedParentSummary(parsed, summaryBlockers);
+    const submittedSummary = normalized.raw;
+    if (!submittedSummary)
+        return blockedParentSummary(parsed, ['naruto_parent_summary_schema_invalid']);
+    const existing = await readJson(path.join(loaded.dir, SUBAGENT_PARENT_SUMMARY_FILENAME), null).catch(() => null);
+    if (existing !== null) {
+        const normalizedExisting = normalizeSubagentParentSummary(existing);
+        const [existingGate, existingSummary, existingEvidence] = await Promise.all([
+            readJson(path.join(loaded.dir, NARUTO_GATE_FILENAME), null).catch(() => null),
+            readJson(path.join(loaded.dir, NARUTO_SUMMARY_FILENAME), null).catch(() => null),
+            readJson(path.join(loaded.dir, SUBAGENT_EVIDENCE_FILENAME), null).catch(() => null)
+        ]);
+        const terminal = completeNarutoTerminalBundle({
+            workflowRunId,
+            gate: existingGate,
+            summary: existingSummary,
+            evidence: existingEvidence,
+            parentSummary: existing
+        });
+        if (terminal) {
+            if (!normalizedExisting.trustworthy || !normalizedExisting.raw) {
+                return blockedParentSummary(parsed, ['naruto_parent_summary_existing_canonical_invalid']);
+            }
+            if (normalizedExisting.run_id !== workflowRunId) {
+                return blockedParentSummary(parsed, ['naruto_parent_summary_existing_run_id_mismatch']);
+            }
+            if (!sameParentAuthoredSummary(normalizedExisting.raw, submittedSummary)) {
+                return blockedParentSummary(parsed, ['naruto_parent_summary_conflicts_with_canonical']);
+            }
+        }
+    }
+    const evidence = await refreshOfficialSubagentCompletionArtifacts(root, state, submittedSummary, sessionKey);
+    if (!evidence)
+        return blockedParentSummary(parsed, ['naruto_parent_summary_lifecycle_commit_rejected']);
+    const [persisted, summary, gate] = await Promise.all([
+        readJson(path.join(loaded.dir, SUBAGENT_PARENT_SUMMARY_FILENAME), null).catch(() => null),
+        readJson(path.join(loaded.dir, NARUTO_SUMMARY_FILENAME), null).catch(() => null),
+        readJson(path.join(loaded.dir, NARUTO_GATE_FILENAME), null).catch(() => null)
+    ]);
+    const normalizedPersisted = normalizeSubagentParentSummary(persisted);
+    if (!normalizedPersisted.trustworthy
+        || normalizedPersisted.run_id !== workflowRunId
+        || !sameParentAuthoredSummary(normalizedPersisted.raw, submittedSummary)) {
+        return blockedParentSummary(parsed, ['naruto_parent_summary_canonical_commit_mismatch']);
+    }
+    const hardBlocked = normalizedPersisted.status === 'failed';
+    const accepted = gate?.passed === true || hardBlocked;
+    const result = {
+        schema: NARUTO_RESULT_SCHEMA,
+        action: 'parent-summary',
+        ok: gate?.passed === true,
+        accepted,
+        status: summary?.status || evidence?.status || normalizedPersisted.status || 'incomplete',
+        mission_id: parsed.missionId,
+        workflow_run_id: workflowRunId,
+        parent_summary_status: normalizedPersisted.status,
+        completion_evidence: gate?.passed === true,
+        blockers: Array.isArray(gate?.blockers) ? gate.blockers : [],
+        artifacts: narutoArtifactLinks(evidence)
+    };
+    return emit(parsed, result, () => renderParentSummaryResult(result), result.ok !== true);
+}
+async function readBoundedParentSummaryStdin() {
+    let value = '';
+    let bytes = 0;
+    process.stdin.setEncoding('utf8');
+    for await (const chunk of process.stdin) {
+        const text = String(chunk);
+        bytes += Buffer.byteLength(text, 'utf8');
+        if (bytes > MAX_PARENT_SUMMARY_STDIN_BYTES) {
+            return { ok: false, blocker: `naruto_parent_summary_stdin_too_large:${MAX_PARENT_SUMMARY_STDIN_BYTES}` };
+        }
+        value += text;
+    }
+    if (!value.trim())
+        return { ok: false, blocker: 'naruto_parent_summary_stdin_empty' };
+    return { ok: true, value };
+}
+function sameParentAuthoredSummary(left, right) {
+    if (!left || typeof left !== 'object' || Array.isArray(left))
+        return false;
+    if (!right || typeof right !== 'object' || Array.isArray(right))
+        return false;
+    const omitHostReceipts = (value) => {
+        const { artifacts: _artifacts, capabilities_used: _capabilitiesUsed, ...authored } = value;
+        return authored;
+    };
+    return isDeepStrictEqual(omitHostReceipts(left), omitHostReceipts(right));
+}
+function blockedParentSummary(parsed, blockers) {
+    const result = {
+        schema: NARUTO_RESULT_SCHEMA,
+        action: 'parent-summary',
+        ok: false,
+        accepted: false,
+        status: 'blocked',
+        mission_id: parsed.missionId || null,
+        blockers: uniqueStrings(blockers)
+    };
+    return emit(parsed, result, () => {
+        for (const line of renderNarutoBlockedLines(result.blockers))
+            console.error(line);
+    }, true);
+}
 async function narutoRun(parsed) {
     const root = await sksRoot();
     const appSession = detectCodexAppSession();
@@ -152,6 +351,7 @@ async function narutoRunTransaction(parsed, root, appSession, sessionKey, resolv
         missionId: id,
         workflowRunId,
         sessionKey,
+        credentialPolicy: parsed.credentialPolicy,
         ...(missionLease ? { onChildSpawn: missionLease.protectChildPid } : {})
     });
     const result = await withOfficialSubagentLifecycleLock(dir, async () => {
@@ -482,6 +682,7 @@ function narutoHelp(parsed) {
         console.log(`Nesting: max_depth=${result.max_depth}; Naruto children must not spawn children`);
         console.log('Context: bounded TriWiki attention.use_first anchors with on-demand source hydration');
         console.log('Evidence: SubagentStop is lifecycle-only; completion requires subagent-parent-summary.json with one structured outcome per Naruto child thread.');
+        console.log('Codex App finalization: submit the structured object with parent-summary --mission <id> --stdin, then return localized Markdown without exposing JSON.');
     });
 }
 async function resolveRunMission(root, parsed, sessionKey = null) {
@@ -541,7 +742,7 @@ export function parseNarutoArgs(args) {
         : args;
     const first = normalized[0] && !normalized[0].startsWith('-') ? normalized[0] : '';
     const actionName = first;
-    const actions = new Set(['run', 'status', 'subagents', 'proof', 'help']);
+    const actions = new Set(['run', 'status', 'subagents', 'proof', 'parent-summary', 'help']);
     const action = (actions.has(actionName) ? actionName : 'run');
     const explicitAction = actions.has(actionName);
     const rest = explicitAction ? normalized.slice(1) : normalized;
@@ -571,7 +772,7 @@ export function parseNarutoArgs(args) {
         ? positional.join(' ').trim()
         : '';
     const positionalHead = String(positional[0] || '').toLowerCase();
-    const subcommandNames = new Set(['run', 'status', 'subagents', 'proof', 'help']);
+    const subcommandNames = new Set(['run', 'status', 'subagents', 'proof', 'parent-summary', 'help']);
     if (!first && !explicitAction && positionalHead && !subcommandNames.has(positionalHead)) {
         argumentErrors.push(`unknown_subcommand:${positionalHead}`);
     }
@@ -599,6 +800,22 @@ export function parseNarutoArgs(args) {
     }
     if (action === 'run' && !prompt)
         argumentErrors.push('empty_task');
+    if (action === 'parent-summary') {
+        if (!missionOption.present || !missionOption.value || missionOption.value === 'latest') {
+            argumentErrors.push('parent_summary_requires_explicit_mission');
+        }
+        if (missionIdOption.present)
+            argumentErrors.push('parent_summary_mission_id_alias_not_supported');
+        if (!normalized.includes('--stdin'))
+            argumentErrors.push('parent_summary_requires_stdin');
+        if (agentsOption.present || maxThreadsOption.present || normalized.includes('--readonly')
+            || normalized.includes('--read-only') || normalized.includes('--trusted-project')) {
+            argumentErrors.push('parent_summary_unsupported_run_option');
+        }
+    }
+    else if (normalized.includes('--stdin')) {
+        argumentErrors.push('stdin_only_supported_for_parent_summary');
+    }
     return {
         action,
         prompt,
@@ -606,17 +823,28 @@ export function parseNarutoArgs(args) {
         maxThreads,
         missionId: String(missionFlag || positionalMission || 'latest'),
         json: normalized.includes('--json'),
+        stdin: normalized.includes('--stdin'),
         readOnly: normalized.includes('--readonly') || normalized.includes('--read-only'),
         trustedProject: optionArgs.includes('--trusted-project'),
-        argumentErrors: uniqueStrings(argumentErrors)
+        argumentErrors: uniqueStrings(argumentErrors),
+        credentialPolicy: resolveNarutoCredentialPolicy({
+            args: optionArgs,
+            env: process.env,
+            defaultParentModel: NARUTO_PARENT_MODEL,
+            defaultParentEffort: NARUTO_PARENT_EFFORT,
+            defaultSubagentModel: DEFAULT_SUBAGENT_MODEL,
+            defaultSubagentEffort: DEFAULT_SUBAGENT_EFFORT
+        })
     };
 }
 function positionalValues(args) {
     const valueFlags = new Set([
-        '--agents', '--max-threads', '--mission', '--mission-id'
+        '--agents', '--max-threads', '--mission', '--mission-id',
+        '--auth-mode', '--model-provider', '--provider-env-key',
+        '--parent-model', '--parent-effort', '--subagent-model', '--subagent-effort'
     ]);
     const booleanFlags = new Set([
-        '--json', '--readonly', '--read-only', '--trusted-project'
+        '--json', '--stdin', '--readonly', '--read-only', '--trusted-project', '--no-forced-login-method'
     ]);
     const result = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -679,7 +907,7 @@ function optionErrors(name, option, numeric) {
 function unknownOptionErrors(args) {
     const canonical = new Set([
         '--agents', '--max-threads', '--mission', '--mission-id',
-        '--json', '--readonly', '--read-only', '--trusted-project', '--help', '-h', '--'
+        '--json', '--stdin', '--readonly', '--read-only', '--trusted-project', '--help', '-h', '--'
     ]);
     const errors = [];
     const optionArgs = args.includes('--') ? args.slice(0, args.indexOf('--')) : args;
@@ -693,7 +921,7 @@ function unknownOptionErrors(args) {
     return errors;
 }
 function booleanOptionErrors(args) {
-    const booleanNames = new Set(['--json', '--readonly', '--read-only', '--trusted-project', '--help', '-h']);
+    const booleanNames = new Set(['--json', '--stdin', '--readonly', '--read-only', '--trusted-project', '--no-forced-login-method', '--help', '-h']);
     const optionArgs = args.includes('--') ? args.slice(0, args.indexOf('--')) : args;
     const errors = [];
     for (const arg of optionArgs) {
@@ -785,6 +1013,15 @@ function renderRunResult(result) {
     if (result.status === 'delegation_context_ready')
         console.log('Continue in the current Naruto parent and wait for every requested child before summarizing.');
 }
+function renderParentSummaryResult(result) {
+    if (result.ok !== true) {
+        for (const line of renderNarutoBlockedLines(result.blockers || []))
+            console.log(line);
+        return;
+    }
+    console.log(`$sks-naruto parent summary committed: ${result.mission_id}`);
+    console.log(`Workflow run: ${result.workflow_run_id}`);
+}
 function renderStatusResult(result) {
     if (['blocked', 'incomplete'].includes(result.status) && Array.isArray(result.blockers) && result.blockers.length) {
         for (const line of renderNarutoBlockedLines(result.blockers))

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

@@ -47,7 +47,7 @@ export async function pptCommand(command, args = []) {
                 process.exitCode = 1;
                 if (flag(args, '--json'))
                     return printJson(result);
-                console.error('PPT build blocked: Codex App imagegen/gpt-image-2 is unavailable.');
+                console.error('PPT build blocked: no selected Codex imagegen/gpt-image-2 provider is ready.');
                 for (const action of imagegenRequired.blocker?.next_actions || [])
                     console.error(`- ${action}`);
                 return result;
@@ -159,7 +159,7 @@ async function pptImagegenReview(root, command, action, args = []) {
             process.exitCode = 1;
             if (flag(args, '--json'))
                 return printJson(result);
-            console.error('PPT imagegen review blocked: Codex App imagegen/gpt-image-2 is unavailable.');
+            console.error('PPT imagegen review blocked: no selected Codex imagegen/gpt-image-2 provider is ready.');
             for (const action of imagegenRequired.blocker?.next_actions || [])
                 console.error(`- ${action}`);
             return result;

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

@@ -2,7 +2,13 @@ import path from 'node:path';
 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';
+import { loadTelegramConfig, probeTelegramBotReadiness, resolveTelegramBotToken, TelegramActionBroker, TelegramAuditLedger, TelegramBotApiClient, TelegramBotApiError, TelegramHubRouter, TelegramHubRuntime, TelegramIdempotencyLedger, TelegramOwnerLock, TelegramMessageProjector, TelegramPollingHub, TelegramTopicRegistry, installAndStartTelegramHubService, restartTelegramHubService, setupTelegramLocalCoding, stopTelegramHubService, telegramHubPaths, telegramHubServiceStatus, telegramTokenFingerprint, validateTelegramConfig, validateTelegramPrivatePairing } from '../telegram/index.js';
+export const TELEGRAM_STATUS_NATIVE_DEADLINE_MS = 8_000;
+export const TELEGRAM_STATUS_TOKEN_LOOKUP_TIMEOUT_MS = 1_000;
+export const TELEGRAM_STATUS_BOT_REQUEST_TIMEOUT_MS = 1_500;
+export const TELEGRAM_STATUS_BOT_MAX_RETRIES = 0;
+export const TELEGRAM_STATUS_LIVE_PROBE_BUDGET_MS = TELEGRAM_STATUS_TOKEN_LOOKUP_TIMEOUT_MS
+    + TELEGRAM_STATUS_BOT_REQUEST_TIMEOUT_MS * 2;
 export async function telegramCommand(args = []) {
     if (isHelpRequest(args)) {
         printTelegramUsage();
@@ -79,6 +85,7 @@ async function telegramStatus(args, root, paths, configPath) {
     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 servicePromise = telegramHubServiceStatus({ projectRoot: controllingRoot, globalRoot: root });
     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);
@@ -90,17 +97,34 @@ async function telegramStatus(args, root, paths, configPath) {
     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);
+    let liveProbe = telegramLiveProbeStatus(null);
+    const probeConfig = validation.config ?? telegramConfigForStatusProbe(rawConfig);
+    if (probeConfig) {
+        const token = await resolveTelegramBotToken(probeConfig.bot_token_ref, {
+            timeoutMs: TELEGRAM_STATUS_TOKEN_LOOKUP_TIMEOUT_MS
+        }).catch(() => null);
+        tokenConfigured = token !== null;
+        if (token) {
+            try {
+                liveProbe = telegramLiveProbeStatus(await probeTelegramBotReadiness(new TelegramBotApiClient(token, {
+                    timeoutMs: TELEGRAM_STATUS_BOT_REQUEST_TIMEOUT_MS,
+                    maxRetries: TELEGRAM_STATUS_BOT_MAX_RETRIES
+                })));
+            }
+            catch (error) {
+                liveProbe = telegramLiveProbeStatus(null, error);
+            }
+        }
     }
+    const service = await servicePromise;
     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']),
+        ...(liveProbe.blocker ? [liveProbe.blocker] : []),
         ...(pairing.blocker ? [pairing.blocker] : []),
         ...(registered.length ? [] : ['no_registered_codex_session']),
         ...(service.running ? [] : ['telegram_hub_not_running'])
@@ -110,6 +134,12 @@ async function telegramStatus(args, root, paths, configPath) {
         ok: blockers.length === 0,
         configured: rawConfig !== null,
         token_configured: tokenConfigured,
+        bot_verified: liveProbe.bot_verified,
+        bot: liveProbe.bot,
+        webhook_configured: liveProbe.webhook_configured,
+        pending_update_count: liveProbe.pending_update_count,
+        long_poll_ready: liveProbe.long_poll_ready,
+        telegram_probe_error: liveProbe.telegram_probe_error,
         pairing_valid: pairing.pairing_valid,
         pairing_issues: pairing.pairing_issues,
         hub_running: service.running,
@@ -135,7 +165,8 @@ async function telegramStatus(args, root, paths, configPath) {
             updated_at: binding.updated_at
         })),
         remote_config_issues: [...machineValidation.issues, ...sessionValidation.issues],
-        blockers
+        blockers,
+        next_actions: telegramNextActions(blockers)
     };
 }
 function printTelegramUsage() {
@@ -150,26 +181,49 @@ Usage:
   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.
+  1. Open @BotFather, send /newbot, choose a name and a unique username ending in "bot",
+     then copy the HTTP API token BotFather returns.
   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
 
+If status reports telegram_webhook_conflict, remove the webhook in the service
+that configured it, then retry. SKS does not delete external webhook state implicitly.
+If setup or the hub reports telegram_409_conflict, stop the other poller using
+this bot token before retrying.
+Stop the SKS Telegram hub before rerunning setup or rotating its BotFather token.
+
 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);
+    const multipleIds = hasMultipleTelegramPairingIds(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(',')}`
+            : multipleIds
+                ? 'telegram_pairing_multiple_ids_requires_setup'
+                : pairing.missing
+                    ? 'telegram_pairing_missing'
+                    : `telegram_pairing_invalid:${pairing.issues.join(',')}`
+    };
+}
+export function telegramLiveProbeStatus(readiness, error = null) {
+    const probeError = error === null ? null : telegramProbeFailure(error);
+    const webhookConfigured = readiness?.webhook_configured === true;
+    return {
+        bot_verified: readiness !== null,
+        bot: readiness?.bot ?? null,
+        webhook_configured: webhookConfigured,
+        pending_update_count: readiness?.pending_update_count ?? 0,
+        long_poll_ready: readiness !== null && !webhookConfigured,
+        telegram_probe_error: probeError,
+        blocker: probeError ?? (webhookConfigured ? 'telegram_webhook_conflict' : null)
     };
 }
 async function runHub(args, root, paths, configPath, json) {
@@ -243,7 +297,19 @@ async function runHub(args, root, paths, configPath, json) {
 }
 async function assertHubSetupReady(controllingRoot, globalRoot, configPath) {
     const config = await loadTelegramConfig(configPath);
-    await resolveTelegramBotToken(config.bot_token_ref);
+    const token = await resolveTelegramBotToken(config.bot_token_ref);
+    let readiness;
+    try {
+        readiness = await probeTelegramBotReadiness(new TelegramBotApiClient(token, {
+            timeoutMs: 8_000,
+            maxRetries: 1
+        }));
+    }
+    catch (error) {
+        throw new Error(telegramProbeFailure(error));
+    }
+    if (readiness.webhook_configured)
+        throw new Error('telegram_webhook_conflict');
     const registry = await loadRemoteMachineRegistry(remoteMachineRegistryPath(globalRoot));
     const index = await loadRemoteSessionIndex(remoteSessionIndexPath(controllingRoot), registry);
     const bindings = await new RemoteCodexSessionBindingStore(remoteCodexSessionBindingsPath(controllingRoot)).list();
@@ -284,3 +350,50 @@ function publicError(err) {
         .replace(/(?:\/Users|\/home)\/[^\s]+/g, '[path-redacted]')
         .slice(0, 500);
 }
+function telegramProbeFailure(error) {
+    return error instanceof TelegramBotApiError && (error.errorCode === 401 || error.errorCode === 404)
+        ? 'telegram_bot_auth_failed'
+        : 'telegram_bot_probe_failed';
+}
+function telegramNextActions(blockers) {
+    const actions = [];
+    if (blockers.includes('telegram_token_not_available') || blockers.includes('telegram_bot_auth_failed')) {
+        actions.push('Create or regenerate the bot token in @BotFather, then rerun setup with --bot-token-stdin.');
+    }
+    if (blockers.includes('telegram_webhook_conflict')) {
+        actions.push('Remove the existing webhook in the service that configured it, then rerun telegram status.');
+    }
+    if (blockers.includes('telegram_bot_probe_failed')) {
+        actions.push('Check network access to api.telegram.org, then rerun telegram status.');
+    }
+    if (blockers.includes('telegram_pairing_missing') || blockers.some((blocker) => blocker.startsWith('telegram_pairing_invalid:'))) {
+        actions.push('Send /start to the bot in a private chat, then rerun telegram setup.');
+    }
+    if (blockers.includes('telegram_pairing_multiple_ids_requires_setup')) {
+        actions.push('Stop the hub, then rerun telegram setup to replace the ambiguous multi-ID config with one verified private chat and user.');
+    }
+    if (blockers.includes('no_registered_codex_session')) {
+        actions.push('Rerun telegram setup for this project root.');
+    }
+    if (blockers.includes('telegram_hub_not_running')) {
+        actions.push('Run sks telegram hub start --project-root \"$PWD\" --json after other blockers are cleared.');
+    }
+    return actions;
+}
+function hasMultipleTelegramPairingIds(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (Array.isArray(record.paired_chat_ids) && record.paired_chat_ids.length > 1)
+        || (Array.isArray(record.paired_user_ids) && record.paired_user_ids.length > 1);
+}
+function telegramConfigForStatusProbe(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const validation = validateTelegramConfig({
+        ...value,
+        paired_chat_ids: ['1'],
+        paired_user_ids: ['1']
+    });
+    return validation.config;
+}

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

@@ -5,11 +5,21 @@ import { computeTriWikiAffectedGraph } from '../triwiki/triwiki-affected-graph.j
 import { buildTriWikiGateImpactMap } from '../triwiki/triwiki-gate-impact-map.js';
 import { DEFAULT_TRIWIKI_MODULE_CARDS } from '../triwiki/triwiki-module-card.js';
 import { summarizeTriWikiProofBank } from '../triwiki/triwiki-proof-bank.js';
+import { isTriWikiGraphSubcommand, triwikiGraphCommand } from './triwiki-graph-command.js';
 export async function triwikiCommand(args = []) {
     const root = await projectRoot();
     const sub = args[0] && !args[0].startsWith('-') ? args[0] : 'index';
     const json = flag(args, '--json');
     let result;
+    if (isTriWikiGraphSubcommand(sub)) {
+        const answer = await triwikiGraphCommand(root, sub, args.slice(1));
+        process.exitCode = answer.ok ? 0 : 2;
+        if (json)
+            return printJson(answer.result);
+        for (const line of answer.lines)
+            console.log(line);
+        return answer.result;
+    }
     if (sub === 'index') {
         result = {
             schema: 'sks.triwiki-index.v1',
@@ -26,7 +36,7 @@ export async function triwikiCommand(args = []) {
         result = summarizeTriWikiProofBank(root);
     }
     else {
-        console.error('Usage: sks triwiki index|affected|proof-bank [--json]');
+        console.error('Usage: sks triwiki index|affected|proof-bank|graph-status|graph-lint|graph-query [--json]');
         process.exitCode = 1;
         return null;
     }