elanous 0.2.20 → 0.2.22

package/src/nexus/api/http-server.ts

@@ -19,10 +19,13 @@ import { setInProcessOutbound } from '../../domains/outbound-alert.js';
 import { getUserConfig } from '../../user-config.js';
 import type { TelegramEvent } from '../../workflow-runtime/triggers/telegram-source.js';
 import { spawnSync } from 'node:child_process';
-import { isAbsolute } from 'node:path';
+import { isAbsolute, join, dirname, relative } from 'node:path';
+import { homedir } from 'node:os';
+import { readdirSync, realpathSync, statSync } from 'node:fs';
 import { createProject, listProjects } from '../../project/project-store.js';
 import { handleOutputsGet, type OutputsDeps } from './outputs-route.js';
 import { buildGridData, type GridDeps } from './grid.js';
+import { createDraftMetricsSource, type DraftMetricsSource } from './draft-metrics.js';
 import { DECISIONS_PATH, handleDecisions, type DecisionsRouteDeps } from './decisions-route.js';
 import { OPS_BOARD_PATH, handleOpsBoard, type OpsBoardDeps } from './ops-board-route.js';
 import { CARD_FOLLOWUP_PATH, createCardFollowupJobs, type CardFollowupJobs } from './card-followup-route.js';
@@ -31,6 +34,7 @@ import { compareTokenConstTime } from '../../acp/transport/auth.js';
 import { ensureAuthToken } from '../../auth/acp-token.js';
 import type { NexusState } from '../state/state.js';
 import { DEFAULT_NEXUS_HTTP_PORT } from '../default-port.js';
+
 export { DEFAULT_NEXUS_HTTP_PORT } from '../default-port.js';
 import type { TabRegistry } from '../state/tab-registry.js';
 import type { FeedbackEnvelope } from '../../feedback/envelope.js';
@@ -164,6 +168,7 @@ import {
 } from './vault-api.js';
 import { handleBuildsGet, parseBuildsPath } from './builds-api.js';
 import { handleHarnessAskPost, handleHarnessAskStatusGet, handleHarnessRunEventsGet, handleHarnessRunScreenGet, handleHarnessRunsGet, handleHarnessStopPost } from './harness-api.js';
+import { handleHarnessRunTraversalGet } from './harness-traversal.js';
 import { handleLoopEdgesGet } from './loop-edges.js';
 import { handleFabricPlans, type FabricPlansRouteOpts } from './fabric-plans.js';
 import { dispatchPersonaRoute } from './personas.js';
@@ -365,11 +370,12 @@ import {
 } from './workflows.js';
 import { handleTriggersSnapshot } from './triggers.js';
 import { handleWorkflowTemplatesList } from './workflow-templates.js';
-import { handleGraphVersionsGet, handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
+import { graphAccessForRequest, handleGraphAccess, handleGraphAccessPut, handleGraphVersionsGet, handleGraphsGet, handleGraphsMutation } from './graphs-api.js';
 import { handleGraphKindsGet, handleGraphsValidatePost } from './graph-kinds.js';
+import { handleGraphWizardPost, handleGraphWizardPacksGet } from './graph-wizard-api.js';
 import { syncInstalledPluginNodes } from '../../graph-kinds/installed-plugin-nodes.js';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
-import { handlePluginsIndexGet, handlePluginsGet, handlePluginsMarketRefresh, handlePluginsInstall, handlePluginsRemove } from './plugins-market.js';
+import { handlePluginsIndexGet, handlePluginsGet, handlePluginsMarketRefresh, handlePluginsInstall, handlePluginsRemove, handlePluginWizardList, handlePluginWizardSave } from './plugins-market.js';
 import { handlePluginsCredentialsGet, handlePluginsCredentialsPut } from './plugins-credentials-api.js';
 import {
   handleWorkflowsList,
@@ -426,6 +432,9 @@ import {
   parseShowroomLayoutPath,
 } from './showroom-layouts.js';
 
+/** Process-wide DRAFT-METRIC cache (one background collection per TTL, shared by every page load). */
+let sharedDraftMetrics: DraftMetricsSource | undefined;
+
 export const NEXUS_HTTP_PORT_RANGE = 16;     // try 31415..31430
 /** Short timeout for the pre-bind localhost occupancy probe. */
 export const NEXUS_PORT_PROBE_TIMEOUT_MS = 400;
@@ -480,11 +489,17 @@ export type NexusWsBridgeInit = Omit<WsBridgeOpts, 'hostname' | 'port'>;
 export interface NexusHttpServerOpts {
   /** Optional fabric-plan ledger and decomposition seam; production uses the instance root and existing fabric decomposer. */
   fabricPlans?: FabricPlansRouteOpts;
+  /** GRAPH-WIZARD 시험 주입(LLM·템플릿 뿌리). 운영은 비워 둔다. */
+  graphWizard?: import('../../graph-wizard/generate.js').GraphWizardDeps;
+  /** Roots the remote folder picker may browse (default: the daemon user's home). Tests inject a temp root. */
+  projectFolderRoots?: string[];
   /** Optional installer state root for isolated API consumers and tests. */
   pluginStateRoot?: string;
   outputs?: OutputsDeps;
   /** Read-only grid measurement seam; omitted in production for live HQ and Pod pool reads. */
   grid?: GridDeps;
+  /** DRAFT-METRIC cached source seam; omitted in production for the process-wide TTL cache. */
+  draftMetrics?: DraftMetricsSource;
   decisions?: Pick<DecisionsRouteDeps, 'ledger'>;
   opsBoard?: Pick<OpsBoardDeps, 'openStore'>;
   cardFollowup?: CardFollowupJobs;
@@ -835,6 +850,55 @@ export function handleProjectsGet(): Response {
   return jsonResponse({ projects: listProjects() });
 }
 
+function isWithinRoot(path: string, root: string): boolean {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * Remote folder picker: lists sub-folders under an allow-listed root only.
+ * Every path is resolved with realpath first, so `..` segments and symlinks cannot escape the roots;
+ * dot-folders are hidden and symlinked entries that point outside the roots are not listed.
+ */
+export function handleProjectFoldersGet(req: Request, roots: string[] = [homedir()]): Response {
+  const allowed: string[] = [];
+  for (const root of roots) {
+    try { allowed.push(realpathSync(root)); } catch { /* a missing root grants nothing */ }
+  }
+  if (allowed.length === 0) return jsonResponse({ error: 'folder_unavailable' }, 404);
+  const requested = new URL(req.url).searchParams.get('path') ?? allowed[0]!;
+  if (!isAbsolute(requested) || requested.includes('\0')) return jsonResponse({ error: 'invalid_folder' }, 400);
+  let path: string;
+  try { path = realpathSync(requested); }
+  catch {
+    debug.log('nexus.projects', 'folders-unavailable', { reason: 'missing' });
+    return jsonResponse({ error: 'folder_unavailable' }, 404);
+  }
+  if (!allowed.some(root => isWithinRoot(path, root))) {
+    debug.log('nexus.projects', 'folders-refused', { reason: 'outside-roots' });
+    return jsonResponse({ error: 'outside_allowed_roots' }, 403);
+  }
+  try {
+    if (!statSync(path).isDirectory()) return jsonResponse({ error: 'not_directory' }, 400);
+    const folders = readdirSync(path, { withFileTypes: true })
+      .filter(entry => {
+        if (entry.name.startsWith('.')) return false;
+        if (entry.isDirectory()) return true;
+        if (!entry.isSymbolicLink()) return false;
+        try {
+          const target = realpathSync(join(path, entry.name));
+          return statSync(target).isDirectory() && allowed.some(root => isWithinRoot(target, root));
+        } catch { return false; }
+      })
+      .map(entry => ({ name: entry.name, path: join(path, entry.name) }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    const atRoot = allowed.includes(path);
+    return jsonResponse({ path, parent: atRoot ? null : dirname(path), folders });
+  } catch {
+    return jsonResponse({ error: 'folder_unavailable' }, 404);
+  }
+}
+
 export async function handleProjectsPost(req: Request): Promise<Response> {
   let body: unknown;
   try { body = await req.json(); }
@@ -985,7 +1049,9 @@ export async function routeRequest(
     const offered = req.headers.get('authorization');
     const fallbackAuthorized = fallbackToken !== undefined && offered?.startsWith('Bearer ') === true
       && compareTokenConstTime(offered.slice('Bearer '.length).trim(), fallbackToken);
-    if (!(opts.metaApi ? checkAuth(req, opts.metaApi) : fallbackAuthorized)) {
+    const graphPeerAuthorized = (method === 'GET' || method === 'PUT')
+      && graphAccessForRequest(pathname, method, offered?.startsWith('Bearer ') ? offered.slice(7).trim() : null);
+    if (!(opts.metaApi ? checkAuth(req, opts.metaApi) : fallbackAuthorized) && !graphPeerAuthorized) {
       const name = method === 'POST' && (pathname === '/v1/tasks' || pathname === '/v1/reports/ingest') && opts.metaApi
         ? matchIngestAuthorization(req)?.name
         : undefined;
@@ -1360,6 +1426,13 @@ export async function routeRequest(
     return handleHarnessRunEventsGet(req, opts.metaApi);
   }
 
+  // HARNESS-RUN-LIVE-GRAPH — one run's ordered node steps ⊕ journey band (PWA /live-run).
+  if (pathname === '/v1/harness/run-traversal' && method === 'GET') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-runtime-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleHarnessRunTraversalGet(req);
+  }
+
   // Design direction is a write: check owner auth before the handler reads the body.
   // Keep this POST ahead of the mutation fallback, and never make it a public route.
   if (method === 'POST' && pathname === DESIGN_DIRECTION_PATH) {
@@ -1389,11 +1462,27 @@ export async function routeRequest(
     return handleGraphsValidatePost(req, opts.metaApi);
   }
 
+  // GRAPH-WIZARD — 설치된 팩 목록과 말 → 그래프 YAML(저장 안 함). 같은 소유자 인증.
+  if (method === 'GET' && pathname === '/v1/graphs/wizard/packs') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleGraphWizardPacksGet(opts.graphWizard);
+  }
+  if (method === 'POST' && pathname === '/v1/graphs/wizard') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleGraphWizardPost(req, opts.graphWizard);
+  }
+
   if (pathname === '/v1/fabric/decompose' || pathname.startsWith('/v1/fabric/plans/')) {
     if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
     return handleFabricPlans(req, opts.fabricPlans);
   }
 
+  if (pathname === '/v1/projects/folders' && method === 'GET') {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleProjectFoldersGet(req, opts.projectFolderRoots);
+  }
   if (pathname === '/v1/projects' && (method === 'GET' || method === 'POST')) {
     if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
     return method === 'GET' ? handleProjectsGet() : handleProjectsPost(req);
@@ -1437,6 +1526,12 @@ export async function routeRequest(
     if (method !== 'GET') return jsonResponse({ error: 'method-not-allowed', method }, 405);
     return jsonResponse(buildGridData(opts.grid));
   }
+  // DRAFT-METRIC: answers from memory; a stale/cold cache starts one background collection (never per request).
+  if (pathname === '/v1/drafts/metrics') {
+    if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    if (method !== 'GET') return jsonResponse({ error: 'method-not-allowed', method }, 405);
+    return jsonResponse((opts.draftMetrics ?? (sharedDraftMetrics ??= createDraftMetricsSource())).read());
+  }
   if (method === 'GET' && pathname === '/v1/outputs') {
     if (!opts.metaApi || !checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
     return handleOutputsGet(req, opts.outputs);
@@ -1484,6 +1579,10 @@ export async function routeRequest(
         ...opts.decisions,
       });
     }
+    if (method === 'POST' && pathname === '/v1/plugins/wizard') {
+      if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
+      return handlePluginWizardSave(req, opts.metaApi, opts.pluginStateRoot);
+    }
     if (method === 'POST' && pathname === '/v1/plugins/install') {
       if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
       return handlePluginsInstall(req, opts.metaApi, opts.pluginStateRoot);
@@ -1503,10 +1602,19 @@ export async function routeRequest(
       if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
       return handlePluginsRemove(req, pluginRemove[1]!, opts.metaApi, opts.pluginStateRoot);
     }
+    if (method === 'PUT' && /^\/v1\/graphs\/[^/]+\/access$/.test(pathname)) {
+      if (!opts.metaApi || bearerCredential(req, opts.metaApi) === undefined) return jsonResponse({ error: 'unauthorized' }, 401);
+      return handleGraphAccessPut(pathname, req);
+    }
     if ((method === 'PUT' || method === 'POST') && (pathname.startsWith('/v1/graphs/') || pathname === '/v1/graphs')) {
       if (!opts.metaApi) return jsonResponse({ error: 'meta-api-not-wired' }, 503);
-      if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
-      const mutated = await handleGraphsMutation(pathname, req);
+      const peerMayEdit = method === 'PUT' && graphAccessForRequest(pathname, method,
+        req.headers.get('authorization')?.startsWith('Bearer ') ? req.headers.get('authorization')!.slice(7).trim() : null);
+      const ownerAuthorized = checkAuth(req, opts.metaApi);
+      if (!ownerAuthorized && !peerMayEdit) return jsonResponse({ error: 'unauthorized' }, 401);
+      // A peer save is recorded on the graph so every run path refuses it until the owner approves (W9c run guard).
+      const mutated = await handleGraphsMutation(pathname, req, {}, ownerAuthorized ? null
+        : { peerToken: req.headers.get('authorization')!.slice(7).trim() });
       if (mutated) return mutated;
     }
     const cardClose = /^\/v1\/task-cards\/([^/]+)\/close$/.exec(pathname);
@@ -2798,6 +2906,10 @@ export async function routeRequest(
   // surface (`/v1/workflows` · `~/.elanous/workflows-runs/`) covers the same
   // user need.
 
+  if (method === 'GET' && pathname === '/v1/plugins/wizard') {
+    if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handlePluginWizardList(req, opts.metaApi, opts.pluginStateRoot);
+  }
   const pluginCredentialsGet = /^\/v1\/plugins\/([^/]+)\/credentials$/.exec(pathname);
   if (method === 'GET' && pluginCredentialsGet) {
     if (!opts.metaApi) return jsonResponse({ error: 'unauthorized' }, 401);
@@ -2813,6 +2925,10 @@ export async function routeRequest(
     catch (error) { debug.log('graph.kinds', 'installed-sync-failed', { reason: String(error) }); }
     return handleGraphKindsGet(req, opts.metaApi);
   }
+  if (method === 'GET' && /^\/v1\/graphs\/[^/]+\/access$/.test(pathname)) {
+    if (!opts.metaApi || bearerCredential(req, opts.metaApi) === undefined) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleGraphAccess(pathname, req);
+  }
   // F-M1 read + P-F1 raw YAML. Writes live in the mutation block and never touch core graphs/.
   if (method === 'GET' && (pathname === '/v1/graphs' || /^\/v1\/graphs\/[^/]+$/.test(pathname) || /^\/v1\/graphs\/[^/]+\/yaml$/.test(pathname))) {
     return handleGraphsGet(pathname);

package/src/nexus/api/plugins-market.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { listWizardDrafts, saveWizardDraft, type WizardResearchDraft } from '../../plugins/maker/wizard-generate.js';
 import { dirname, join } from 'node:path';
 import { elanousStateRoot } from '../../autopilot/state-paths.js';
 import { debug } from '../../debug/log.js';
@@ -120,6 +121,29 @@ export function handlePluginsIndexGet(req: Request, opts: MetaApiOpts, root?: st
   return jsonResponse(readMarketIndex(root, configuredTrustedKeys(configPath)));
 }
 
+export function handlePluginWizardList(req: Request, opts: MetaApiOpts, root = elanousStateRoot()): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  return jsonResponse({ plugins: listWizardDrafts(join(root, 'plugins-local')) });
+}
+
+export async function handlePluginWizardSave(req: Request, opts: MetaApiOpts, root = elanousStateRoot()): Promise<Response> {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  let body: unknown;
+  try { body = await req.json(); } catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return jsonResponse({ error: 'bad_request' }, 400);
+  const input = body as { name?: unknown; draft?: unknown; regenerate?: unknown };
+  if (typeof input.name !== 'string' || !/^[a-z0-9][a-z0-9-]{1,31}$/.test(input.name) ||
+    !input.draft || typeof input.draft !== 'object' || Array.isArray(input.draft) ||
+    (input.regenerate !== undefined && typeof input.regenerate !== 'boolean')) return jsonResponse({ error: 'bad_request' }, 400);
+  try {
+    saveWizardDraft(join(root, 'plugins-local'), input.name, input.draft as WizardResearchDraft, input.regenerate === true);
+    return jsonResponse({ name: input.name, saved: true });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'invalid draft';
+    return jsonResponse({ error: 'invalid_wizard_draft', reason: /already exists|research draft/.test(reason) ? reason : 'invalid draft' }, 422);
+  }
+}
+
 export function handlePluginsGet(req: Request, opts: MetaApiOpts, root?: string): Response {
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
   return jsonResponse(listInstalledPlugins(root));

package/src/nexus/index.ts

@@ -2743,11 +2743,12 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     if ((getUserConfig().raw?.decisions as { cards?: unknown } | undefined)?.cards !== false && !isAutonomousRunContext()) {
       try {
         const { DecisionCardService } = await import('../decisions/decision-cards.js');
-        const { webPushDecisionTransport } = await import('../decisions/web-push-decision-cards.js');
+        const { webPushDecisionTransport, webPushUrgency } = await import('../decisions/web-push-decision-cards.js');
         const { listSubscriptions } = await import('../web-push/subscriptions.js');
         const { DecisionLedger } = await import('../decisions/decision-ledger.js');
         const ledger = new DecisionLedger();
-        const service = new DecisionCardService({ transport: webPushDecisionTransport(ledger), ownerIds: [], ledger });
+        const service = new DecisionCardService({ transport: webPushDecisionTransport(ledger), ownerIds: [], ledger,
+          sendFilter: (entry, now) => webPushUrgency(entry, now) !== 'not-urgent', deferredReason: webPushUrgency });
         await service.tick();
         webPushDecisionTimer = setInterval(() => {
           void service.tick().catch((error: unknown) => {

package/src/nexus/outbound/router.ts

@@ -16,7 +16,8 @@
 //       { "type": "discord", "webhookUrl": "https://discord.com/api/webhooks/..." },
 //       { "type": "pushcut", "webhookUrl": "https://api.pushcut.io/.../notifications/..." }
 //     ],
-//     "routes": { "alert": ["telegram", "pushcut"], "report": ["telegram", "discord"] }
+//     "routes": { "alert": ["telegram", "pushcut"], "report": ["telegram", "discord"] },
+//     "awayRoutes": { "alert": ["discord"] }
 //   }
 //
 // Backward compat: when `outbound` is absent/malformed the resolved
@@ -27,6 +28,7 @@
 // that boolean before falling back to direct Telegram).
 
 import { createHash } from 'node:crypto';
+import { readPresence } from '../../away/presence.js';
 import { debug } from '../../debug/log.js';
 import { sendTelegramReport } from '../../telegram-report.js';
 import { getPushcutClient } from '../../pushcut/client.js';
@@ -58,6 +60,8 @@ export interface OutboundFanoutConfig {
    *  `routes.default`, then to ALL configured channels. An explicitly
    *  empty route (`"heartbeat": []`) suppresses that kind. */
   routes?: Record<string, string[]>;
+  /** 외출 중 kind → channel types. 미지정 kind는 awayRoutes.default, 이것도 없으면 기존 routes를 유지한다. */
+  awayRoutes?: Record<string, string[]>;
 }
 
 export interface ChannelResult {
@@ -118,14 +122,17 @@ export function normalizeOutbound(raw: unknown): OutboundFanoutConfig | undefine
     channels.push({ type, ...(webhookUrl ? { webhookUrl } : {}), ...(notification ? { notification } : {}) });
   }
   if (channels.length === 0) return undefined;
-  let routes: Record<string, string[]> | undefined;
-  if (o.routes && typeof o.routes === 'object' && !Array.isArray(o.routes)) {
-    routes = {};
-    for (const [kind, v] of Object.entries(o.routes as Record<string, unknown>)) {
+  const parseRoutes = (value: unknown): Record<string, string[]> | undefined => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const routes: Record<string, string[]> = {};
+    for (const [kind, v] of Object.entries(value as Record<string, unknown>)) {
       if (Array.isArray(v)) routes[kind] = v.filter((t): t is string => typeof t === 'string');
     }
-  }
-  return { channels, ...(routes ? { routes } : {}) };
+    return routes;
+  };
+  const routes = parseRoutes(o.routes);
+  const awayRoutes = parseRoutes(o.awayRoutes);
+  return { channels, ...(routes ? { routes } : {}), ...(awayRoutes ? { awayRoutes } : {}) };
 }
 
 /** Resolve the channel list for one message kind. No/empty config →
@@ -219,7 +226,20 @@ export async function routeOutbound(cfg: UserConfig, msg: OutboundMsg, deps: Rou
     } catch { /* 원장 조회 실패 — 억제 없이 진행 */ }
   }
 
-  const list = resolveChannels(outbound, msg.kind);
+  // 상태 파일이 없거나 읽기에 실패하면 기존 kind 경로를 그대로 사용한다.
+  let list = resolveChannels(outbound, msg.kind);
+  if (outbound?.awayRoutes) {
+    try {
+      if (readPresence().away) {
+        const awayRoute = outbound.awayRoutes[msg.kind] ?? outbound.awayRoutes.default;
+        // kind 도 default 도 없으면 기존 경로로 · 명시적인 빈 배열은 기존 routes 와 같은 규칙(채널 0)을 따른다.
+        if (awayRoute !== undefined) {
+          list = outbound.channels.filter(ch => awayRoute.includes(ch.type));
+          try { debug.log('outbound.send', 'away-route', { kind: msg.kind, channels: list.map(ch => ch.type) }); } catch { /* 관측 실패는 발송 결과에 영향 없음 */ }
+        }
+      }
+    } catch { /* 상태 조회 실패 — 기존 경로 유지 */ }
+  }
   const channels = await Promise.all(list.map(async (ch): Promise<ChannelResult> => {
     try {
       if (ch.type === 'telegram') return await deliverTelegram(cfg, outMsg, deps);

package/src/oauth/claude-pty-maturity.ts

@@ -0,0 +1,24 @@
+export type ClaudePtyMaturity =
+  | { readonly mature: true }
+  | { readonly mature: false; readonly why: 'too-few-samples' | 'completion-below-70' | 'unknown-screen-above-10' | 'intervention-above-0.2' | 'sample-unreadable' };
+
+export type ClaudePtyMaturitySample = {
+  readonly runCount: number;
+  readonly completedCount: number;
+  readonly unknownScreenCount: number;
+  readonly interventionCount: number;
+};
+
+/** 최근 런의 계수만 판정한다. 표본을 못 읽거나 계수가 불가능하면 성숙으로 추정하지 않는다. */
+export function judgeClaudePtyMaturity(sample: ClaudePtyMaturitySample | null | undefined): ClaudePtyMaturity {
+  if (!sample || ![sample.runCount, sample.completedCount, sample.unknownScreenCount, sample.interventionCount]
+    .every((count) => Number.isSafeInteger(count) && count >= 0)
+    || sample.completedCount > sample.runCount || sample.unknownScreenCount > sample.runCount) {
+    return { mature: false, why: 'sample-unreadable' };
+  }
+  if (sample.runCount < 10) return { mature: false, why: 'too-few-samples' };
+  if (sample.completedCount / sample.runCount < 0.7) return { mature: false, why: 'completion-below-70' };
+  if (sample.unknownScreenCount / sample.runCount > 0.1) return { mature: false, why: 'unknown-screen-above-10' };
+  if (sample.interventionCount / sample.runCount > 0.2) return { mature: false, why: 'intervention-above-0.2' };
+  return { mature: true };
+}

package/src/oauth/fallback-chain.ts

@@ -19,9 +19,10 @@
 //   지갑을 여는» 일이 없다. (2026-08-13 실측 · RESEARCH-grok-oauth-… §7b)
 
 import type { RotationCandidate } from './codex-account-rotation.js';
+import type { ClaudePtyMaturity } from './claude-pty-maturity.js';
 
 /** 체인에 놓을 수 있는 칸. ⛔ 모르는 이름은 «조용히 건너뛰지 않고» 거부한다(오타 방어). */
-export const FALLBACK_STEPS = ['codex-rotate', 'grok'] as const;
+export const FALLBACK_STEPS = ['codex-rotate', 'grok', 'claude-pty'] as const;
 export type FallbackStep = (typeof FALLBACK_STEPS)[number];
 
 /** 기본 체인 — ⛔⭐ **2026-08-20 에 `grok` 이 «기본»으로 들어왔다**(대표 지시).
@@ -75,8 +76,8 @@ export type RotationOutcome =
 export type FallbackDecision =
   /** codex 계정을 갈아탄다(종전 동작). */
   | { readonly action: 'codex-rotate'; readonly to: RotationCandidate }
-  /** 백엔드를 통째로 바꾼다. 지금은 grok 뿐. */
-  | { readonly action: 'switch-backend'; readonly backend: 'grok' }
+  /** 백엔드를 통째로 바꾼다. */
+  | { readonly action: 'switch-backend'; readonly backend: 'grok' | 'claude' }
   /** 아무것도 안 한다 — 이유를 «값으로» 남긴다. */
   | { readonly action: 'stay'; readonly why: StayReason };
 
@@ -96,7 +97,9 @@ export type StayReason =
   /** 다음 칸이 grok 인데 grok 자격이 «없다». */
   | 'grok-unavailable'
   /** grok 자격은 있는데 «잔량이 소진»됐다 — 자격 부재와 «다른 값»이다. */
-  | 'grok-exhausted';
+  | 'grok-exhausted'
+  /** claude PTY 의 최근 표본이 성숙 관문을 통과하지 못했거나 읽히지 않는다. */
+  | 'claude-pty-immature';
 
 type FallbackRunPosition =
   | { readonly currentCredentialRateLimited?: false; readonly currentStep?: FallbackStep }
@@ -120,6 +123,8 @@ export type FallbackInput = {
    *   (⇒ 그리고 그 사실은 관측에 값으로 남는다 — 「모르고 갔다」를 셀 수 있다.)
    */
   readonly grokQuota?: 'usable' | 'exhausted' | 'unknown';
+  /** 최근 claude PTY 표본의 순수 성숙 판정. 생략·못 읽음은 전환 불가. */
+  readonly claudePtyMaturity?: ClaudePtyMaturity;
   /**
    * `reset-credit-available` 에서 체인을 타지 않고 머문다.
    * 기본(생략·false)은 `no-candidate` 와 같이 `codex-rotate` 다음 칸을 찾는다.
@@ -148,12 +153,12 @@ export type FallbackInput = {
 export function decideFallback(input: FallbackInput): FallbackDecision {
   const {
     rotation, chain, currentStep, currentCredentialRateLimited = false,
-    grokAvailable, grokQuota = 'unknown', stayOnResetCreditAvailable = false,
+    grokAvailable, grokQuota = 'unknown', claudePtyMaturity, stayOnResetCreditAvailable = false,
   } = input;
 
   if (currentCredentialRateLimited) {
     if (currentStep === undefined) return { action: 'stay', why: 'chain-exhausted' };
-    return stepAfter(chain, currentStep, grokAvailable, grokQuota, 'chain-exhausted');
+    return stepAfter(chain, currentStep, grokAvailable, grokQuota, claudePtyMaturity, 'chain-exhausted');
   }
   if (rotation.reason === 'explicit') return { action: 'stay', why: 'explicit' };
   if (rotation.reason === 'not-reached' || (rotation.reason === 'credit-pace' && !('to' in rotation))) {
@@ -167,13 +172,13 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
     // 회전이 답을 냈는데 체인이 codex-rotate 를 «빼» 놨다면 그 뜻을 존중하고
     // 다음 칸으로 간다(회전을 원치 않는 구성).
     if (chain.includes('codex-rotate')) return { action: 'codex-rotate', to: rotation.to };
-    return stepAfterCodex(chain, grokAvailable, grokQuota, 'chain-exhausted');
+    return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, 'chain-exhausted');
   }
 
   // no-candidate | disabled | reset-credit-available(기본) — codex 축이 끝났다. 다음 칸을 본다.
   // ⛔ 다음 칸이 «없을 때»의 이름만 고른다. 진행(stepAfterCodex)은 그대로다.
   const fallbackWhy = stayReasonWhenCodexAxisEnds(rotation.reason === 'credit-pace' ? 'no-candidate' : rotation.reason);
-  return stepAfterCodex(chain, grokAvailable, grokQuota, fallbackWhy);
+  return stepAfterCodex(chain, grokAvailable, grokQuota, claudePtyMaturity, fallbackWhy);
 }
 
 /** codex 축이 끝났는데 체인 다음 칸도 없을 때 머무는 이유.
@@ -191,9 +196,10 @@ function stepAfterCodex(
   chain: readonly FallbackStep[],
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
+  claudePtyMaturity: ClaudePtyMaturity | undefined,
   whyIfNone: StayReason,
 ): FallbackDecision {
-  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, whyIfNone);
+  return stepAfter(chain, 'codex-rotate', grokAvailable, grokQuota, claudePtyMaturity, whyIfNone);
 }
 
 function stepAfter(
@@ -201,20 +207,27 @@ function stepAfter(
   currentStep: FallbackStep | undefined,
   grokAvailable: boolean,
   grokQuota: 'usable' | 'exhausted' | 'unknown',
+  claudePtyMaturity: ClaudePtyMaturity | undefined,
   whyIfNone: StayReason,
 ): FallbackDecision {
   const idx = currentStep === undefined ? -1 : chain.indexOf(currentStep);
   const rest = idx === -1 ? chain : chain.slice(idx + 1);
+  let unavailableWhy: StayReason | undefined;
   for (const step of rest) {
     if (step === 'grok') {
-      // ⛔ 자격 «먼저» — 자격이 없으면 잔량을 물을 것도 없다(그리고 두 사유는 다른 값이다).
-      if (!grokAvailable) return { action: 'stay', why: 'grok-unavailable' };
-      // ⛔ 「모른다」는 통과시킨다 — 못 읽었다고 갈 곳을 없애지 않는다(위 계약 주석).
-      if (grokQuota === 'exhausted') return { action: 'stay', why: 'grok-exhausted' };
+      // 자격 부재와 소진은 다른 값이다. 다음 칸이 있으면 그 칸을 살핀다.
+      if (!grokAvailable) { unavailableWhy = 'grok-unavailable'; continue; }
+      // 「모른다」는 통과시킨다 — 못 읽었다고 갈 곳을 없애지 않는다.
+      if (grokQuota === 'exhausted') { unavailableWhy = 'grok-exhausted'; continue; }
       return { action: 'switch-backend', backend: 'grok' };
     }
+    if (step === 'claude-pty') {
+      // 미성숙·못 읽음은 «건너뛴다» — 뒤에 다른 칸이 있으면 그 칸을 본다(없으면 이 사유로 머문다).
+      if (claudePtyMaturity?.mature !== true) { unavailableWhy = 'claude-pty-immature'; continue; }
+      return { action: 'switch-backend', backend: 'claude' };
+    }
   }
-  return { action: 'stay', why: whyIfNone };
+  return { action: 'stay', why: unavailableWhy ?? whyIfNone };
 }
 
 /** 사람이 읽는 한 줄 — 관측·CLI 표면용. ⛔ 토큰·계정 홈은 넣지 않는다. */

package/src/onboarding/first-run.ts

@@ -1,6 +1,7 @@
 import * as readline from 'node:readline/promises';
 import { detectProviders, type DetectedProvider } from '../llm/provider-detect.js';
 import { debug } from '../debug/log.js';
+import { unattendedNextStepLine } from './entry-hints.js';
 import { resolveProviderCredential } from '../llm/provider-credentials.js';
 import {
   getUserConfig, saveUserConfig, userConfigPath,
@@ -57,6 +58,8 @@ export async function runFirstRun(deps: FirstRunDeps = {}): Promise<{
   if (!provider) {
     if ((deps.isTTY ?? process.stdin.isTTY) !== true) {
       print('eln setup llm 으로 고르세요');
+      // FIRST-CHAT-NONTTY — bare `elanous` with no TTY gets the same one-line next step as the other entrances.
+      print(unattendedNextStepLine());
       observe('needs-llm', 0);
       return { outcome: 'needs-llm', inputs: 0 };
     }