@awak-app/simy-cli 0.7.23 → 0.7.26

package/src/connection-health.js

@@ -0,0 +1,253 @@
+import { execFile, spawn } from 'node:child_process';
+import { lookup } from 'node:dns/promises';
+import { networkInterfaces, homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { readSession, isSessionValid } from './session-store.js';
+import { readProviderLinks } from './provider-links.js';
+import { inspectProviderStatus } from './desktop-status.js';
+import { resolveWebOrigin } from './web-origin.js';
+
+const execute = promisify(execFile);
+const aliasPattern = /^[a-zA-Z0-9][a-zA-Z0-9._@-]{0,127}$/;
+export const shellQuote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";
+const clean = value => String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, '').slice(0, 180);
+const check = (layer, state, code, message) => ({ layer, state, code, message });
+
+// Fixed messages deliberately exclude response bodies, SSH output and credentials.
+const remedies = {
+  dns: ['名前解決に失敗しました', '接続先名・SSHのHostName・DNS設定を確認してください。社内名やVPN内の名前なら、必要なVPNに接続して再確認してください。'],
+  proxy_dns: ['プロキシの名前解決に失敗しました', 'HTTP_PROXY・HTTPS_PROXY・ALL_PROXYの接続先名と、その名前を解決するVPN/DNSを確認してください。'],
+  proxy_auth: ['プロキシ認証が必要です', 'プロキシの認証期限・アカウントを確認し、組織指定の認証方法で更新してください。'],
+  proxy_config: ['プロキシ設定を解釈できません', 'プロキシ環境変数のURL形式・ポート・対応方式を確認してください。'],
+  proxy_connect: ['プロキシ経由の接続に失敗しました', 'プロキシへの到達性と転送先の許可、NO_PROXYの適用範囲を確認してください。'],
+  refused: ['接続先が接続を拒否しました', '接続先のサービスが起動しているか、ポートと待受アドレス、拒否するファイアウォール規則を確認してください。'],
+  route: ['接続先への経路がありません', 'ネットワーク・VPN・ルーティングと接続先の稼働状態を確認してください。'],
+  timeout: ['接続がタイムアウトしました', 'VPN・ファイアウォール・接続先停止が候補です。タイムアウトだけでは原因を特定できません。経路と接続先の受信規則を確認してください。'],
+  reset: ['接続が途中で切断されました', '接続先サービス・プロキシ・VPNの状態を確認し、診断を再実行してください。'],
+  tls_expired: ['証明書の期限または端末時刻に問題があります', '端末の日付と時刻を確認してください。期限切れのサーバー証明書は管理者が更新し、更新後に再確認してください。'],
+  tls_name: ['証明書と接続先名が一致しません', '証明書が対象とする正しいDNS名を使うか、管理者に証明書の修正を依頼してください。'],
+  tls_trust: ['証明書の信頼を検証できません', '証明書チェーンを管理者に確認してください。社内CAを使う場合は正しいCAをCURL_CA_BUNDLEまたはSSL_CERT_FILEに設定して再確認してください。'],
+  tls_client: ['クライアント証明書を利用できません', 'サービスが要求するクライアント証明書の有効期限・秘密鍵・読取権限を確認してください。'],
+  tls: ['TLS接続に失敗しました', '接続先のHTTPSポート・TLS対応・証明書と、TLSを中継するプロキシを確認してください。'],
+  key_changed: ['SSHホスト鍵が以前と異なります', '相手側でssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pubを実行し、正しい端末か管理者と照合してからknown_hostsを更新してください。'],
+  key_unknown: ['SSHホスト鍵が未確認です', '相手側のホスト鍵指紋を確認したうえで、通常のssh接続で初回登録してください。'],
+  key_permissions: ['SSH秘密鍵の権限が広すぎます', '自分が所有する秘密鍵のアクセス権を本人のみ読書き可能に修正してください。秘密鍵の内容を共有する必要はありません。'],
+  key_missing: ['SSH秘密鍵を読み取れません', 'SSH設定のIdentityFile、鍵ファイルの存在・所有者・読取権限を確認してください。'],
+  ssh_certificate: ['SSH証明書が無効または期限切れです', '端末時刻とSSH証明書の期限を確認し、発行元の手順で更新してください。'],
+  ssh_auth: ['SSH認証に失敗しました', 'SSHのUser・IdentityFile・相手側のauthorized_keysを確認してください。パスフレーズが必要な鍵はssh-agentへ読み込みます。'],
+  ssh_agent: ['SSHエージェントが署名できません', 'ssh-add -lでエージェントの鍵を確認し、鍵のロックやハードウェアキーの状態を確認してください。'],
+  ssh_config: ['SSH設定を読み取れません', 'SSHのHost・HostName・Port・ProxyJump・ProxyCommandの設定とIncludeファイルを確認してください。'],
+  ssh_forward: ['SSHのポート転送が許可されていません', '相手側のAllowTcpForwarding・PermitListen・鍵ごとの転送制限を管理者に確認してください。'],
+  ssh_missing: ['OpenSSHが見つかりません', 'この端末にOpenSSHクライアントをインストールして再確認してください。'],
+  cli_missing: ['相手のSIMY CLIが見つかりません', '相手側にSIMY CLIをインストールし、SSHのログインシェルのPATHでsimyが見つかることを確認してください。'],
+  auth: ['認証が必要、または期限切れです', 'サービスのログイン・OAuth再認証またはAPIキー更新を行ってください。APIキーは--token-envで環境変数名を指定できます。'],
+  permission: ['接続先がアクセスを拒否しました（403）', '対象アカウント・組織・APIスコープとサービス側のアクセス規則を確認してください。403だけでは権限不足とWAFによる拒否を区別できません。'],
+  rate_limit: ['サービスの利用制限に達しました（429）', 'サービスの利用制限と再試行時刻を確認し、待ってから再確認してください。'],
+  service: ['接続先サービスで障害が発生しています', 'サービスの稼働状況を確認し、復旧後に再確認してください。'],
+  endpoint: ['APIの接続先が見つかりません', 'APIのURL・バージョン・パスが正しいか確認してください。'],
+  method: ['この接続先はHEAD診断に対応していません', 'サービスが公開する読取専用のヘルスチェックURLで再確認してください。'],
+  redirect: ['別のページへ転送されました', 'ログイン画面または移転先の可能性があります。サービスの正しい接続先と認証方法を確認してください。'],
+  curl_missing: ['Web診断用のcurlが見つかりません', 'curlをインストールして再確認してください。'],
+  unknown: ['接続状態を確定できません', '対象の接続先と設定を確認し、診断を再実行してください。'],
+};
+
+export function issueFor(code, layer = 'connection', state = 'failed') {
+  const [message, instruction] = remedies[code] || remedies.unknown;
+  return { ...check(layer, state, code, message), instruction };
+}
+
+export function classifySshFailure(error) {
+  const text = `${error?.stderr || ''}\n${error?.stdout || ''}`;
+  if (error?.code === 'ENOENT') return 'ssh_missing';
+  if (/REMOTE HOST IDENTIFICATION HAS CHANGED|Offending .* key/i.test(text)) return 'key_changed';
+  if (/Host key verification failed|No .* host key is known/i.test(text)) return 'key_unknown';
+  if (/UNPROTECTED PRIVATE KEY|bad permissions|Permissions .* too open/i.test(text)) return 'key_permissions';
+  if (/Certificate invalid|certificate has expired|certificate is not yet valid/i.test(text)) return 'ssh_certificate';
+  if (/sign_and_send_pubkey.*signing failed|agent refused operation/i.test(text)) return 'ssh_agent';
+  if (/Load key .* (?:Permission denied|invalid format)|no such identity|Identity file .* not accessible/i.test(text)) return 'key_missing';
+  if (/Permission denied|Too many authentication failures|Authentication failed/i.test(text)) return 'ssh_auth';
+  if (/Could not resolve hostname|Name or service not known|Temporary failure in name resolution/i.test(text)) return 'dns';
+  if (/Connection refused/i.test(text)) return 'refused';
+  if (/No route to host|Network is unreachable/i.test(text)) return 'route';
+  if (/timed out|timeout/i.test(text) || error?.killed) return 'timeout';
+  if (/administratively prohibited|remote port forwarding failed/i.test(text)) return 'ssh_forward';
+  if (/Bad configuration|Bad port|unsupported option|Bad owner or permissions on/i.test(text)) return 'ssh_config';
+  if (/Connection reset|Connection closed|kex_exchange_identification/i.test(text)) return 'reset';
+  if (text.includes('SIMY_CLI_MISSING')) return 'cli_missing';
+  return 'unknown';
+}
+
+export function classifyWebFailure(result) {
+  const error = String(result.stderr || '');
+  if (result.missing) return 'curl_missing';
+  if (result.exitCode) {
+    if (/Unsupported proxy syntax|Unsupported proxy|Malformed.*proxy/i.test(error)) return 'proxy_config';
+    if (result.exitCode === 5) return 'proxy_dns';
+    if (result.exitCode === 6) return 'dns';
+    if (result.exitCode === 28) return 'timeout';
+    if (result.exitCode === 58) return 'tls_client';
+    if ([60, 77, 83, 90].includes(result.exitCode)) {
+      if (/expired|not yet valid/i.test(error)) return 'tls_expired';
+      if (/no alternative certificate subject|does not match|subject name/i.test(error)) return 'tls_name';
+      return 'tls_trust';
+    }
+    if (result.exitCode === 35) return 'tls';
+    if (result.exitCode === 97 || result.connectStatus >= 400) return result.connectStatus === 407 ? 'proxy_auth' : 'proxy_connect';
+    if (/Connection refused|Couldn't connect to server/i.test(error) && result.exitCode === 7) return /Connection refused/i.test(error) ? 'refused' : 'unknown';
+    if (/No route to host|Network is unreachable/i.test(error)) return 'route';
+    if ([52, 55, 56].includes(result.exitCode)) return 'reset';
+    return 'unknown';
+  }
+  const status = result.httpStatus;
+  if (status >= 200 && status < 300) return null;
+  if (status === 401) return 'auth';
+  if (status === 403) return 'permission';
+  if (status === 407) return 'proxy_auth';
+  if (status === 404) return 'endpoint';
+  if (status === 405 || status === 501) return 'method';
+  if (status === 429) return 'rate_limit';
+  if (status >= 500) return 'service';
+  if (status >= 300 && status < 400) return 'redirect';
+  return 'unknown';
+}
+
+export function parseConnectionTarget(value = 'simy', webOrigin = resolveWebOrigin()) {
+  if (value === 'simy') return { kind: 'simy', url: new URL(webOrigin), display: 'SIMY' };
+  if (['provider:codex', 'provider:claude'].includes(value)) return { kind: 'provider', provider: value.slice(9), display: value };
+  if (/^https?:\/\//i.test(value)) {
+    const url = new URL(value);
+    if (url.username || url.password || /[\x00-\x20\x7f]/.test(value)) throw new Error('ログイン名やパスワードを含まないWebアドレスを指定してください。');
+    url.hash = '';
+    return { kind: 'web', url, display: clean(url.origin) };
+  }
+  const alias = value.replace(/^ssh:/, '');
+  if (!aliasPattern.test(alias)) throw new Error('接続先を確認してください。SIMYを調べるなら simy connections recover、別のパソコンを調べるなら simy connections で一覧を確認してください。');
+  return { kind: 'ssh', alias, display: alias };
+}
+
+export function networkContext(env = process.env, interfaces = networkInterfaces()) {
+  return {
+    activeInterfaceCount: Object.values(interfaces).filter(addresses => addresses?.some(address => !address.internal)).length,
+    vpnInterfaces: Object.entries(interfaces).filter(([name, addresses]) => /^(tun|tap|utun|wg|tailscale|ppp)/i.test(name) && addresses?.some(a => !a.internal)).map(([name]) => clean(name)),
+    proxyConfigured: Boolean(env.https_proxy || env.HTTPS_PROXY || env.http_proxy || env.HTTP_PROXY || env.all_proxy || env.ALL_PROXY),
+    noProxyConfigured: Boolean(env.no_proxy || env.NO_PROXY),
+    customCaConfigured: Boolean(env.CURL_CA_BUNDLE || env.SSL_CERT_FILE || env.SSL_CERT_DIR),
+  };
+}
+
+// curl applies the user's proxy/NO_PROXY and CA configuration. Credentials and
+// query strings travel over stdin, not child argv; redirects are never followed.
+export function probeWeb(url, { token, env = process.env, spawnImpl = spawn, timeoutMs = 10_000 } = {}) {
+  if (token && /[\r\n\x00]/.test(token)) throw new Error('APIトークンに改行を含めることはできません。');
+  const configQuote = value => String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+  const config = `url = "${configQuote(url.href)}"\n` + (token ? `header = "Authorization: Bearer ${configQuote(token)}"\n` : '');
+  return new Promise(resolve => {
+    let done = false, stdout = '', stderr = '', timer;
+    const finish = result => { if (done) return; done = true; clearTimeout(timer); resolve(result); };
+    const child = spawnImpl('curl', ['--disable', '--config', '-', '--head', '--silent', '--show-error',
+      '--proto', '=http,https', '--connect-timeout', '5', '--max-time', String(timeoutMs / 1000), '--max-redirs', '0',
+      '--output', process.platform === 'win32' ? 'NUL' : '/dev/null', '--write-out', '%{http_code}\n%{http_connect}\n%{ssl_verify_result}\n'],
+    { stdio: ['pipe', 'pipe', 'pipe'], shell: false, env: { ...env, ...(env.HTTP_PROXY && !env.http_proxy ? { http_proxy: env.HTTP_PROXY } : {}) }, windowsHide: true });
+    timer = setTimeout(() => { child.kill(); finish({ exitCode: 28, httpStatus: 0, stderr: '' }); }, timeoutMs + 1000);
+    child.on('error', error => finish({ exitCode: 1, missing: error.code === 'ENOENT', httpStatus: 0, stderr: '' }));
+    child.stdin.on('error', () => {});
+    child.stdout.on('data', data => { stdout = (stdout + data).slice(-4096); });
+    child.stderr.on('data', data => { stderr = (stderr + data).slice(-8192); });
+    child.on('close', code => {
+      const [status, connect, verify] = stdout.trim().split(/\r?\n/).map(Number);
+      finish({ exitCode: Number.isInteger(code) ? code : 1, httpStatus: status || 0, connectStatus: connect || 0, tlsVerifyResult: verify, stderr });
+    });
+    child.stdin.end(config);
+  });
+}
+
+async function dnsCheck(host, lookupImpl) {
+  let timer;
+  try {
+    await Promise.race([lookupImpl(host.replace(/^\[|\]$/g, '')), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 3000); })]);
+    return check('dns', 'passed', 'dns_resolved', '接続先名を解決できました');
+  } catch { return issueFor('dns', 'dns'); }
+  finally { clearTimeout(timer); }
+}
+
+export async function diagnoseConnection(value, { webOrigin = resolveWebOrigin(), root = process.env.SIMY_HOME?.trim() || join(homedir(), '.simy'),
+  env = process.env, tokenEnv, executeImpl = execute, probeWebImpl = probeWeb, lookupImpl = lookup,
+  inspectProvider = inspectProviderStatus, readLinks = readProviderLinks, readSessionImpl = readSession,
+  interfaces = networkInterfaces(), now = Date.now() } = {}) {
+  const target = parseConnectionTarget(value, webOrigin);
+  if (tokenEnv && (target.kind !== 'web' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokenEnv) || !env[tokenEnv])) throw new Error('接続キーの指定を読み取れませんでした。--token-env は外部Webサービス用です。接続キーを保存した設定の名前を指定してください。分からない場合はサービスの担当者に確認してください。');
+  if (tokenEnv && target.url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(target.url.hostname)) throw new Error('接続キーを送るときは、https:// で始まる安全なWebアドレス（HTTPS）を指定してください。');
+  const report = { schemaVersion: 1, target: { kind: target.kind, display: target.display }, status: 'unverified', checks: [], context: networkContext(env, interfaces), actions: [] };
+  const addAction = (id, title, instructions, command) => report.actions.push({ id, title, instructions, ...(command ? { command } : {}) });
+  if (target.kind === 'ssh') {
+    let config;
+    try {
+      const resolved = await executeImpl('ssh', ['-G', '--', target.alias], { timeout: 5000, maxBuffer: 256 * 1024, env });
+      const fields = new Map(resolved.stdout.split(/\r?\n/).map(line => { const at = line.indexOf(' '); return [line.slice(0, at), line.slice(at + 1)]; }));
+      config = { hostname: fields.get('hostname'), port: Number(fields.get('port')), jump: fields.get('proxyjump'), proxy: fields.get('proxycommand') };
+      report.checks.push(check('ssh_config', 'passed', 'ssh_config_resolved', '現在のSSH設定を読み取りました'));
+      if (config.hostname && ![config.jump, config.proxy].some(v => v && v !== 'none')) {
+        report.checks.push(await dnsCheck(config.hostname, lookupImpl));
+      } else report.checks.push(check('dns', 'unknown', 'ssh_proxy_dns', '踏み台・プロキシ経由の名前解決はSSH接続で確認します'));
+      const result = await executeImpl('ssh', ['-T', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=8', '--', target.alias,
+        "sh -lc 'if command -v simy >/dev/null 2>&1; then printf SIMY_CLI_PRESENT; else printf SIMY_CLI_MISSING; exit 127; fi'"],
+      { timeout: 12_000, maxBuffer: 64 * 1024, env });
+      if (!result.stdout?.endsWith('SIMY_CLI_PRESENT')) throw new Error('unexpected probe');
+      // Successful SSH can resolve a name unavailable to the local DNS probe.
+      report.checks = report.checks.filter(c => !(c.layer === 'dns' && c.state === 'failed'));
+      report.checks.push(check('ssh', 'passed', 'ssh_ready', 'SSH認証と相手のSIMY CLIを確認しました'));
+      report.checks.push(check('cli_auth', 'unknown', 'cli_auth_unverified', '相手のSIMYログインはCLIを開いて確認してください'));
+      addAction('open_cli', '相手のCLIを開く', '相手側のログイン・組織を確認して接続します。', `simy connections connect ${target.alias}`);
+    } catch (error) {
+      const code = classifySshFailure(error);
+      report.checks.push(issueFor(code, 'ssh'));
+      if (['ssh_auth', 'ssh_agent', 'key_missing', 'key_permissions'].includes(code)) {
+        addAction('ssh_login', 'SSHの対話認証を試す', 'パスフレーズや本人の操作が必要な鍵を使って再認証し、その後に再確認します。', `ssh -T -o StrictHostKeyChecking=yes -- ${target.alias} true`);
+      }
+      if (['timeout', 'route', 'refused'].includes(code)) addAction('reverse', '逆向き経路を利用する', '接続を開始できる側で相手のSSHエイリアスを指定します。', 'simy connections tunnel <相手のSSHエイリアス>');
+    }
+  } else if (target.kind === 'provider') {
+    const state = await inspectProvider(target.provider).catch(() => ({ state: 'unknown' }));
+    const links = await readLinks(root).catch(() => ({}));
+    if (state.state === 'ready') report.checks.push(check('provider_auth', 'passed', 'provider_ready', 'CLIのインストールと保存されたログインを確認しました'));
+    else if (state.state === 'signed_out') {
+      report.checks.push(issueFor('auth', 'provider_auth'));
+      addAction('provider_login', 'プロバイダーにログインする', 'プロバイダーの公式ログインを起動し、完了後に再確認します。', target.provider === 'codex' ? 'codex login' : 'claude auth login');
+    } else {
+      report.checks.push(check('provider_auth', 'failed', 'provider_unavailable', 'CLIが未インストール・更新待ち、またはログイン状態を確認できません'));
+      addAction('provider_setup', '公式CLIのインストール・更新を確認', 'プロバイダー公式のインストール手順でCLIを導入・更新し、PATHとログイン状態を確認してください。');
+    }
+    if (links[target.provider]?.connected === true) report.checks.push(check('provider_link', 'passed', 'provider_linked', 'SIMYとの連携は有効です'));
+    else {
+      report.checks.push(check('provider_link', 'failed', 'provider_disconnected', 'SIMYとの連携が無効、または設定を読み取れません'));
+      if (links[target.provider]?.connected === false && !links[target.provider]?.settingsError) addAction('provider_link', 'SIMYとの連携を有効にする', 'このプロバイダーをSIMYに再接続します。会話の実行許可は別途設定します。');
+    }
+    report.checks.push(check('provider_service', 'unknown', 'provider_api_unverified', 'API接続・モデルの利用権限はサービスのURLを指定して診断してください'));
+  } else {
+    report.checks.push(await dnsCheck(target.url.hostname, lookupImpl));
+    const web = await Promise.resolve().then(() => probeWebImpl(target.url, { token: tokenEnv ? env[tokenEnv] : undefined, env })).catch(() => ({ exitCode: 1, httpStatus: 0 }));
+    const code = classifyWebFailure(web);
+    if (!web.exitCode && web.httpStatus > 0) report.checks = report.checks.filter(c => !(c.layer === 'dns' && c.state === 'failed'));
+    if (!web.exitCode && web.httpStatus > 0) report.checks.push(check('http_transport', 'passed', 'http_reached', `HTTP応答を受信しました（${web.httpStatus}）`));
+    report.checks.push(code ? issueFor(code, 'web', ['method', 'redirect', 'unknown'].includes(code) ? 'unknown' : 'failed') : check('web', 'passed', 'web_ready', '指定URLへのHEADリクエストが成功しました'));
+    if (target.kind === 'simy') {
+      const session = await readSessionImpl(webOrigin, root).catch(() => null);
+      if (isSessionValid(session, now, webOrigin)) report.checks.push(check('simy_auth', 'passed', 'session_current', '保存されたSIMY認証の期限は有効です（サーバー側の失効は未確認）'));
+      else {
+        report.checks.push(issueFor('auth', 'simy_auth'));
+        addAction('simy_login', 'SIMYの接続・ログインを開く', '別のターミナルで下のコマンドを実行し、表示されたブラウザで認証を完了してから戻って再確認してください。', `simy --daemon --host ${shellQuote(webOrigin)}`);
+      }
+    } else if (code === 'auth') addAction('web_login', 'サービスのログインページを開く', 'サービス側でログイン・APIキー・OAuthを更新して再確認します。ブラウザのログインとAPIキーは別の認証です。');
+  }
+  for (const item of report.checks.filter(c => c.instruction)) addAction(`resolve_${item.code}`, item.message, item.instruction);
+  if (report.checks.some(c => ['timeout', 'route', 'refused', 'dns'].includes(c.code))) {
+    addAction('network_settings', 'VPN・経路・ファイアウォールを確認', report.context.vpnInterfaces.length
+      ? 'VPN用と思われるネットワークインターフェースはあります。対象のVPNへのログインと到達先ルート、相手側の受信規則を確認してください。'
+      : 'VPN接続・OSの経路設定・相手の稼働状態・必要なポートの受信規則を確認してください。VPNインターフェースがないことだけでVPN障害とは断定できません。');
+  }
+  report.status = report.checks.some(c => c.state === 'failed') ? 'needs_action'
+    : report.checks.some(c => ['web_ready', 'ssh_ready', 'provider_ready'].includes(c.code)) ? 'reachable' : 'unverified';
+  addAction('retry', '修復後に再確認', '設定・認証の更新後、同じ接続先を再診断します。');
+  return report;
+}

package/src/connection-overview.js

@@ -0,0 +1,58 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { defaultSessionRoot } from './session-store.js';
+
+const safeText = (value, limit = 160) => typeof value === 'string' ? value.replace(/[\x00-\x1f\x7f]/g, '').slice(0, limit) : null;
+const scopeKey = ({ endpoint, accountId, organizationId }) => {
+  if (!endpoint || !accountId || !organizationId) return null;
+  try { const url = new URL(endpoint); url.username = ''; url.password = ''; url.search = ''; url.hash = '';
+    return createHash('sha256').update(JSON.stringify([url.href, accountId, organizationId])).digest('hex');
+  } catch { return null; }
+};
+const observationPath = (scope, root) => { const key = scopeKey(scope); return key ? join(root, 'connection-observations', `${key}.json`) : null; };
+
+// Only metadata of an actual online bundle lookup; never credentials, rules,
+// executable checks or inferred cross-organization registrations.
+export async function recordSqmConnectionObservation(scope, result, { root = process.env.SIMY_SQM_CACHE_DIR || join(defaultSessionRoot(), 'sqm'), now = Date.now() } = {}) {
+  const target = observationPath(scope, root);
+  if (!target || !['cloud', 'cache_revalidated', 'unavailable'].includes(result?.source)) return;
+  const bundle = result.bundle;
+  const verified = bundle?.organization_id === scope.organizationId && bundle?.system_scope?.organization_id === scope.organizationId;
+  const repository = safeText(scope.repository, 200);
+  if (!repository || !/^[^/\s]+\/[^/\s]+$/.test(repository)) return;
+  const value = { version: 1, state: verified ? 'verified' : 'unavailable', repository,
+    checkedAt: new Date(now).toISOString(), expiresAt: verified ? bundle.expires_at : null };
+  const temp = `${target}.${randomUUID()}.tmp`;
+  try { await mkdir(join(root, 'connection-observations'), { recursive: true, mode: 0o700 });
+    await writeFile(temp, JSON.stringify(value), { mode: 0o600 }); await rename(temp, target);
+  } finally { await rm(temp, { force: true }); }
+}
+
+export async function readSqmConnectionObservation(scope, { root = process.env.SIMY_SQM_CACHE_DIR || join(defaultSessionRoot(), 'sqm'), now = Date.now() } = {}) {
+  const target = observationPath(scope, root);
+  if (!target) return { state: 'unknown' };
+  try {
+    const raw = await readFile(target, 'utf8'); if (raw.length > 4096) return { state: 'unknown' };
+    const v = JSON.parse(raw), at = Date.parse(v.checkedAt);
+    if (v.version !== 1 || !['verified', 'unavailable'].includes(v.state) || !Number.isFinite(at) || at > now ||
+        typeof v.repository !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(v.repository) || v.repository.length > 200) return { state: 'unknown' };
+    const current = now - at <= 5 * 60 * 1000 && (v.state !== 'verified' || Date.parse(v.expiresAt) > now);
+    return { state: current ? v.state : 'previous', repository: safeText(v.repository, 200), checkedAt: v.checkedAt };
+  } catch { return { state: 'unknown' }; }
+}
+
+export function connectionEnvironment(origin) {
+  try { const url = new URL(origin); if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') return { kind: 'unknown', origin: null };
+    return { kind: url.origin === 'https://app.simy.one' ? 'production' : url.origin === 'https://app-dev.simy.one' ? 'development' : 'custom', origin: url.origin };
+  } catch { return { kind: 'unknown', origin: null }; }
+}
+
+export function connectionOverview({ webOrigin, session, access, signedIn, switching, sqm, deviceName = hostname() }) {
+  const scopeReady = signedIn && !switching && session?.organization_id && access?.organizationId === session.organization_id && access?.state === 'ready';
+  return { device: { name: safeText(deviceName) || null }, environment: connectionEnvironment(webOrigin),
+    organization: { name: signedIn && access?.organizationId === session?.organization_id ? safeText(access?.organizationName) : null,
+      state: switching ? 'switching' : scopeReady ? 'ready' : 'unknown' },
+    sqm: scopeReady ? (sqm || { state: 'unknown' }) : { state: 'unknown' } };
+}

package/src/connection-presentation.js

@@ -0,0 +1,85 @@
+// Everyday guidance stays separate from the technical diagnostic record.
+// JSON and the explicit details view retain the original codes for support.
+const networkSteps = [
+  'このパソコンで、いつも見るWebサイトが開くか確認してください。開けない場合はWi-Fiやケーブルを確認してください。',
+  '接続先が別のパソコンなら、そちらの電源を入れ、スリープを解除してください。',
+  '会社専用の接続アプリ（VPN）を普段使う場合は、そのアプリで接続してください。終わったら「もう一度確認する」を選びます。',
+];
+const adminStep = '自分で設定した覚えがない場合は、接続先を用意した人や会社の担当者に「詳しい情報」を見せてください。';
+const advice = {
+  dns: ['接続先の場所が見つかりませんでした。', ['入力した接続先の名前やWebアドレスに間違いがないか確認してください。', ...networkSteps]],
+  proxy_dns: ['会社などの中継サーバーが見つかりませんでした。', [networkSteps[0], networkSteps[2], adminStep]],
+  proxy_auth: ['会社などの中継サーバーでログインが必要です。', ['会社指定の接続アプリやログイン画面で、ログインし直してください。', adminStep]],
+  proxy_config: ['会社などの中継サーバーの設定を読み取れませんでした。', [adminStep]],
+  proxy_connect: ['会社などの中継サーバーを通って接続できませんでした。', [networkSteps[2], adminStep]],
+  refused: ['接続先は、今この接続を受け付けていません。', ['相手のパソコンやサービスが起動しているか確認してください。', '相手がMacの場合は「システム設定」で「リモートログイン」を検索し、オンになっているか確認してください。', adminStep]],
+  route: ['接続先にたどり着けませんでした。', networkSteps],
+  timeout: ['しばらく待ちましたが、接続先から返事がありませんでした。', networkSteps],
+  reset: ['途中で接続が切れました。', [networkSteps[0], '少し待ってから「もう一度確認する」を選んでください。何度も切れる場合は、接続先の担当者に確認してください。']],
+  tls_expired: ['接続先の安全確認に使う証明書の期限を確認できませんでした。', ['このパソコンの日付と時刻が正しいか確認してください。', '時刻が正しければ、接続先の担当者に証明書の期限を確認してもらってください。']],
+  tls_name: ['開こうとしている接続先と、安全確認の情報が一致しません。', ['Webアドレスが正しいか確認してください。', '正しい場合は、接続先の担当者に確認してください。安全確認を無効にして接続しないでください。']],
+  tls_trust: ['接続先が安全か確認できませんでした。', ['接続先の担当者に、安全確認に使う証明書の設定を確認してもらってください。', '会社独自の設定が必要な場合もあります。安全確認を無効にせず、担当者の手順に従ってください。']],
+  tls_client: ['このパソコンの接続許可を示す証明書が使えません。', [adminStep]],
+  tls: ['安全な通信を始められませんでした。', ['Webアドレスが正しいか確認してください。', adminStep]],
+  key_changed: ['相手のパソコンの身元を確認する情報が以前と変わっています。', ['接続先を管理する人に、パソコンの交換や設定変更があったか確認してください。', '同じ名前の別のパソコンの可能性もあります。確認できるまで、以前の情報を削除したり、安全確認を無効にしたりしないでください。']],
+  key_unknown: ['このパソコンから接続してよい相手か、まだ確認できていません。', ['接続先を用意した人に、相手の身元確認と最初の接続設定を手伝ってもらってください。', '知らない相手をそのまま許可せず、設定が終わってから「もう一度確認する」を選んでください。']],
+  key_permissions: ['接続に使う鍵のファイルを、安全に使える設定にする必要があります。', ['このパソコンの接続設定をした人に、鍵のファイルを自分だけが使える設定にしてもらってください。', '鍵のファイルの中身を送ったり、貼り付けたりする必要はありません。']],
+  key_missing: ['接続に使う鍵のファイルが見つからないか、読み取れません。', [adminStep, '鍵のファイルの中身は共有しないでください。']],
+  ssh_certificate: ['このパソコンの接続許可を更新する必要があります。', ['このパソコンの日付と時刻を確認してください。', '接続先を管理する人に、接続許可の更新方法を確認してください。']],
+  ssh_auth: ['相手のパソコンへのログインができませんでした。', ['「相手のパソコンにログインし直す」を選んでください。', 'パスワードなどを求められたら、このターミナルの案内に従って入力してください。入力中に文字が表示されないことがあります。', '分からない場合は、接続先を用意した人に確認してください。']],
+  ssh_agent: ['接続用の鍵がロックされているか、使用できません。', ['普段使う鍵の管理アプリや、USBなどで接続する認証機器を確認してください。', '「相手のパソコンにログインし直す」を選び、表示される案内に従ってください。']],
+  ssh_config: ['保存されている接続設定を読み取れませんでした。', [adminStep]],
+  ssh_forward: ['相手のパソコンが、一時的な接続経路の作成を許可していません。', ['接続先の担当者に、一時的な接続経路を使ってよいか確認してください。担当者向けの情報は「詳しい情報」で確認できます。']],
+  ssh_missing: ['別のパソコンに接続するためのソフトが見つかりません。', ['このパソコンにOpenSSHという接続用ソフトが必要です。設定を手伝う人にインストールを依頼してください。']],
+  cli_missing: ['相手のパソコンでSIMYを見つけられませんでした。', ['相手のパソコンでSIMYが使えるか確認してください。', '相手側で使えるのにこの表示が出る場合は、接続設定をした人に「詳しい情報」を見せてください。']],
+  auth: ['ログインが必要か、ログインの有効期限が切れています。', ['下のログインの操作を選び、開いた画面の案内に従ってください。', '外部サービス用の接続キーを使っている場合は、そのサービスの担当者に更新方法を確認してください。']],
+  permission: ['接続先から、利用を許可されませんでした。', ['正しいアカウントでログインしているか確認してください。', '正しければ、接続先の担当者に利用許可を確認してください。接続を制限する設定が原因の場合もあります。']],
+  rate_limit: ['接続先の利用回数などの制限に達しています。', ['サービスの利用状況や、再び使える時刻を確認してください。時間を置いてから「もう一度確認する」を選んでください。']],
+  service: ['接続先のサービスで問題が起きています。', ['サービスのお知らせや障害情報を確認してください。復旧してから「もう一度確認する」を選んでください。']],
+  endpoint: ['指定したWebアドレスが見つかりませんでした。', ['接続先のWebアドレスが正しいか、サービスの担当者に確認してください。']],
+  method: ['このサービスは、今回の確認方法には対応していません。', ['これだけでは故障とは判断できません。サービスの担当者に、接続確認用のWebアドレスを教えてもらってください。']],
+  redirect: ['接続先から、別のページへ移動するよう案内されました。', ['ログイン画面や、移転したページかもしれません。サービスの正しいWebアドレスとログイン方法を確認してください。']],
+  curl_missing: ['Webサービスを確認するためのソフトが見つかりません。', ['このパソコンにcurlという確認用ソフトが必要です。設定を手伝う人にインストールを依頼してください。']],
+  unknown: ['今回の確認では、接続できるか判断できませんでした。', [networkSteps[0], adminStep]],
+  provider_unavailable: ['AIサービス用のソフトを使えるか確認できませんでした。', ['このパソコンで、対象のAIサービス用ソフトが使えるか確認してください。', '未インストール・更新待ち・ログイン状態の不明などが考えられます。公式の案内に従って設定してください。']],
+  provider_disconnected: ['SIMYとAIサービスの連携が無効か、設定を読み取れません。', ['「SIMYとの連携を有効にする」が表示されていれば、選んでください。', '表示されない場合は設定を読み取れない可能性があります。設定を手伝う人に「詳しい情報」を見せてください。']],
+};
+const observations = {
+  dns_resolved: '接続先の場所が見つかりました。',
+  ssh_config_resolved: '保存されている接続設定を読み取れました。',
+  ssh_proxy_dns: '別のサーバーを通る設定です。実際の接続で確認します。',
+  ssh_ready: '相手のパソコンにつながり、SIMYが見つかりました。',
+  cli_auth_unverified: '相手側のSIMYへのログインは、開いてから確認してください。',
+  provider_ready: 'AIサービス用のソフトと、保存されたログイン情報を確認できました。',
+  provider_linked: 'SIMYとの連携は有効です。',
+  provider_api_unverified: 'AIサービスで実際に作業できるかは、まだ確認していません。',
+  http_reached: 'Webサービスから返事がありました。',
+  web_ready: 'このWebアドレスにつながりました。',
+  session_current: '保存されているログイン情報の期限は有効です。サービス側で取り消されていないかは未確認です。',
+};
+export function friendlyCheck(item) {
+  const [message, steps] = advice[item.code] || [];
+  return { message: message || observations[item.code] || advice.unknown[0], steps: steps || [] };
+}
+export const targetName = target => target.display === 'provider:codex' ? 'Codex（AIサービス）'
+  : target.display === 'provider:claude' ? 'Claude（AIサービス）' : target.display;
+
+export function friendlyAction(action, target) {
+  const name = targetName(target);
+  const known = {
+    retry: ['もう一度確認する', ['今と同じ接続先を確認します。設定を直したら、この操作を選んでください。']],
+    open_cli: [`${name} のSIMYを開く`, ['このパソコンから、相手のパソコンのSIMYを開きます。', '相手側のSIMY画面が表示されたら接続完了です。相手側のSIMYを終了すると、このパソコンに戻ります。']],
+    ssh_login: ['相手のパソコンにログインし直す', ['このターミナルで相手のパソコンへのログインを試します。表示される案内に従ってください。', 'パスワードの入力中に文字が表示されなくても、そのまま入力してEnterキーを押してください。', '終わったら、同じ接続先をもう一度確認します。']],
+    provider_login: [`${name} にログインし直す`, ['このパソコンでログイン操作を始めます。表示される案内や、開いたブラウザの指示に従ってください。', 'ログインが完了したら、このターミナルに戻ってください。']],
+    provider_link: ['SIMYとの連携を有効にする', ['このパソコンのSIMYで、対象のAIサービスとの連携を有効にします。', '作業の実行許可は別途選ぶ必要があります。停止中の作業は再開しません。']],
+    web_login: ['サービスのWebページを開く', ['このパソコンのブラウザで、サービスのトップページを開きます。そこからログインしてください。', '外部サービス用の接続キーを使う場合は、ブラウザのログインだけでは直らないことがあります。キーの更新方法はサービスの担当者に確認してください。', '手続きが終わったら、このターミナルに戻ってください。']],
+    simy_login: ['SIMYにログインし直す手順を見る', ['このパソコンで、ターミナルのウィンドウをもう1つ開いてください。', '下の1行をコピーして貼り付け、Enterキーを押してください。', '表示されたログイン用のページをブラウザで開き、ログインを完了してください。終わったら、このターミナルに戻ってください。']],
+    reverse: ['相手のパソコンからつなぐ方法を見る', ['今の向きでつながらないときは、相手のパソコンからこのパソコンへつなぐ方法があります。相手からこちらへ接続できる設定が必要です。', '相手のパソコンでターミナルを開き、simy connections を実行してください。', '一覧から「今使っているこのパソコン」の接続先名を確認し、下の「接続先名」を置き換えて実行してください。', '接続経路ができると次のコマンドが表示されます。そのコマンドをこのパソコンの別のターミナルで実行してください。相手側のターミナルは接続中ずっと開いておきます。', '一覧にない・どちらの名前か分からない場合は、接続設定をした人に確認してください。']],
+    network_settings: ['ネット接続や会社の接続アプリを確認する', networkSteps],
+    provider_setup: ['AIサービス用ソフトの準備方法を見る', advice.provider_unavailable[1]],
+  };
+  const remedy = action.id.startsWith('resolve_') ? advice[action.id.slice(8)] : null;
+  const [title, steps] = known[action.id] || (remedy ? ['対処方法を読む: ' + remedy[0], remedy[1]] : ['設定を確認する', [adminStep]]);
+  return { title, steps, command: action.id === 'simy_login' ? action.command
+    : action.id === 'reverse' ? 'simy connections tunnel 接続先名' : undefined };
+}

package/src/connection-recovery.js

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { diagnoseConnection, parseConnectionTarget } from './connection-health.js';
+import { writeProviderLink } from './provider-links.js';
+import { openExternalUrl } from './browser.js';
+import { friendlyAction, friendlyCheck, targetName } from './connection-presentation.js';
+
+export function connectionReportLines(report, { details = false } = {}) {
+  const status = { reachable: '今回の接続確認はできました', needs_action: '確認・操作が必要です', unverified: 'まだ接続を確認できていません' };
+  const lines = [
+    `接続先: ${targetName(report.target)}`,
+    `結果: ${status[report.status] || status.unverified}`,
+    ...report.checks.flatMap(item => {
+      const plain = friendlyCheck(item);
+      return [`${item.state === 'passed' ? '✓' : item.state === 'failed' ? '!' : '?'} ${plain.message}`,
+        ...plain.steps.map((step, i) => `  ${i + 1}. ${step}`)];
+    }),
+    '使いたい機能のすべてを確認したわけではありません。まだ確認できていない項目は上に表示しています。',
+  ];
+  if (details) lines.push('', '詳しい情報（設定を手伝う人向け）',
+    ...report.checks.map(c => `${c.code}: ${c.message}${c.instruction ? `\n  ${c.instruction}` : ''}`),
+    `プロキシ設定: ${report.context.proxyConfigured ? 'あり' : 'なし'} / 独自CA設定: ${report.context.customCaConfigured ? 'あり' : 'なし'}`);
+  return lines;
+}
+
+function interactiveProcess(file, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, { stdio: 'inherit', shell: false });
+    child.once('error', () => reject(new Error('操作を起動できませんでした。インストールと設定を確認してください。')));
+    child.once('exit', code => code === 0 ? resolve() : reject(new Error('操作が完了しませんでした。再診断で状態を確認してください。')));
+  });
+}
+
+export async function performConnectionAction(action, value, options = {}) {
+  const target = parseConnectionTarget(value, options.webOrigin);
+  const run = options.runProcess || interactiveProcess;
+  if (action.id === 'ssh_login' && target.kind === 'ssh') {
+    await run('ssh', ['-T', '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=8', '--', target.alias, 'true']);
+  } else if (action.id === 'open_cli' && target.kind === 'ssh') {
+    const { runRemoteConnectionsCommand } = await import('./remote-connection-guide.js');
+    const code = await runRemoteConnectionsCommand(['connect', target.alias]);
+    if (code !== 0) throw new Error('相手のSIMYを開けませんでした。');
+  } else if (action.id === 'provider_login' && target.kind === 'provider') {
+    await run(target.provider, target.provider === 'codex' ? ['login'] : ['auth', 'login']);
+  } else if (action.id === 'provider_link' && target.kind === 'provider') {
+    await writeProviderLink(options.root, target.provider, true);
+  } else if (action.id === 'web_login' && target.kind === 'web') {
+    await openExternalUrl(target.url.origin);
+  }
+  // Other actions are manual remedies. The caller displays the exact instructions
+  // and waits for the user to finish before making another read-only probe.
+}
+
+export async function runConnectionRecovery(argv, options = {}) {
+  const { output = console.log, diagnose = diagnoseConnection, perform = performConnectionAction,
+    interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY), ask } = options;
+  const [mode, ...args] = argv;
+  let value = 'simy', hasTarget = false, json = false, details = false, tokenEnv;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--json') json = true;
+    else if (args[i] === '--details') details = true;
+    else if (args[i] === '--token-env' && args[i + 1] && !tokenEnv) tokenEnv = args[++i];
+    else if (!args[i].startsWith('-') && !hasTarget) { value = args[i]; hasTarget = true; }
+    else throw new Error('入力内容を確認してください。SIMYを確認するには simy connections recover を実行します。使い方は simy connections --help で確認できます。');
+  }
+  const settings = { ...options, tokenEnv };
+  let reader;
+  const question = ask || (prompt => { reader ||= createInterface({ input: process.stdin, output: process.stdout }); return reader.question(prompt); });
+  try {
+    while (true) {
+      const report = await diagnose(value, settings);
+      if (json) output(JSON.stringify(report, null, 2));
+      else {
+        connectionReportLines(report, { details }).forEach(output);
+        output('');
+        output('次にできること:');
+        report.actions.forEach((a, i) => output(`${i + 1}. ${friendlyAction(a, report.target).title}`));
+        if (mode !== 'recover' || !interactive) {
+          output('操作しながら確認するには、同じ接続先で diagnose を recover に変えて実行してください。recover は文字を入力できるターミナルで使います。');
+          if (!details) output('詳しい情報は、実行したコマンドの末尾に --details を付けると表示できます。');
+        }
+      }
+      if (mode !== 'recover' || json || !interactive) return report.status === 'reachable' ? 0 : 1;
+      const choice = (await question('次にすることの番号を入力してEnter（d: 詳しい情報 / 0: 終了）: ')).trim();
+      if (choice.toLowerCase() === 'd') { details = !details; continue; }
+      if (choice === '0' || choice === '') return report.status === 'reachable' ? 0 : 1;
+      const action = /^\d+$/.test(choice) ? report.actions[Number(choice) - 1] : null;
+      if (!action) { output('表示された操作番号を選んでください。'); continue; }
+      if (action.id !== 'retry') {
+        const guidance = friendlyAction(action, report.target);
+        output(guidance.title);
+        guidance.steps.forEach((step, i) => output(`${i + 1}. ${step}`));
+        if (guidance.command) output(guidance.command);
+        // Release stdin while the selected login program owns the terminal.
+        reader?.close(); reader = undefined;
+        try { await perform(action, value, settings); }
+        catch { output('操作が完了しませんでした。画面の案内を確認し、分からない場合は設定を手伝う人に相談してください。'); }
+        await question('操作が終わったらEnterキーを押してください。同じ接続先をもう一度確認します: ');
+      }
+    }
+  } finally { reader?.close(); }
+}