elanous 0.2.8 → 0.2.10

package/src/task-orchestrator/surfaces/pod-lease.ts

@@ -0,0 +1,260 @@
+import type { PodPoolMember, PoolKubectl } from './pod-pool.js';
+import { spawnSync } from 'node:child_process';
+
+// `get pods --all-namespaces -o json` on a busy cluster is several MB — the default spawnSync
+// buffer fails with ENOBUFS (10-03 node-b measured). Same proxy stripping as the Pod launch kubectl.
+const LEASE_KUBECTL_MAX_BUFFER = 256 * 1024 * 1024;
+export function leaseKubectl(args: readonly string[]): { status: number | null; stdout: string; stderr: string } {
+  const env = { ...process.env };
+  for (const k of ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy']) delete env[k];
+  const r = spawnSync('kubectl', [...args], { encoding: 'utf8', env, timeout: 120_000, maxBuffer: LEASE_KUBECTL_MAX_BUFFER });
+  return { status: r.status, stdout: r.stdout ?? '', stderr: (r.stderr ?? '') + (r.error ? String(r.error) : '') };
+}
+
+export interface PodLeaseMember {
+  context: string;
+  capacity: number;
+  running: number | null;
+  pending: number | null;
+  memoryLimitBytes: number | null;
+  /** All-node allocatable memory, before existing reservations. */
+  allocatableMemoryBytes: number | null;
+  allocatableCpuMillicores: number | null;
+  /** Node-by-node memory left after all assigned Pod requests and harness Running limits. */
+  availableMemoryByNodeBytes: number[] | null;
+  reason: string | null;
+}
+
+export interface PoolLeaseMeasure {
+  members: PodLeaseMember[];
+}
+
+export interface PoolLeaseRecommendation {
+  recommended: number | null;
+  limitedBy: 'capacity' | 'memory' | null;
+  reason: string | null;
+  capacitySlots: number | null;
+  memorySlots: number | null;
+  placeableSlots: number | null;
+  accountSlots: number | null;
+  running: number | null;
+  pending: number | null;
+}
+
+/** Kubernetes quantity to bytes (memory) or millicores (CPU). */
+function quantity(raw: string, unit: 'memory' | 'cpu'): number | null {
+  const m = /^(\d+(?:\.\d+)?)(n|u|m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei)?$/.exec(raw);
+  if (!m) return null;
+  const scale: Record<string, number> = { n: 1e-9, u: 1e-6, m: 1e-3, k: 1e3, M: 1e6, G: 1e9, T: 1e12, P: 1e15, E: 1e18, Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4, Pi: 1024 ** 5, Ei: 1024 ** 6 };
+  const suffix = m[2] ?? '';
+  if (unit === 'memory' && ['n', 'u', 'm'].includes(suffix)) return null;
+  if (unit === 'cpu' && suffix.endsWith('i')) return null;
+  const result = Number(m[1]) * (scale[suffix] ?? 1) * (unit === 'cpu' ? 1000 : 1);
+  return Number.isFinite(result) && result >= 0 ? result : null;
+}
+
+function items(value: unknown): Record<string, unknown>[] | null {
+  if (!value || typeof value !== 'object' || !Array.isArray((value as { items?: unknown }).items)) return null;
+  const list = (value as { items: unknown[] }).items;
+  return list.every((v) => v !== null && typeof v === 'object' && !Array.isArray(v)) ? list as Record<string, unknown>[] : null;
+}
+
+function object(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+/** Effective scheduling reservation: max(sum of app requests, largest init request, Pod-level request) + overhead. */
+function requestedMemory(spec: Record<string, unknown>): number | null {
+  const request = (resources: unknown): number | null => {
+    const r = object(resources);
+    if (resources !== undefined && !r) return null;
+    const requests = object(r?.requests);
+    const limits = object(r?.limits);
+    if ((r?.requests !== undefined && !requests) || (r?.limits !== undefined && !limits)) return null;
+    const raw = requests?.memory ?? limits?.memory;
+    return raw === undefined ? 0 : typeof raw === 'string' ? quantity(raw, 'memory') : null;
+  };
+  const containers = spec.containers;
+  if (!Array.isArray(containers) || !containers.length) return null;
+  let app = 0;
+  for (const c of containers) {
+    if (!object(c)) return null;
+    const v = request(object(c)?.resources);
+    if (v === null) return null;
+    app += v;
+  }
+  let init = 0;
+  if (spec.initContainers !== undefined && !Array.isArray(spec.initContainers)) return null;
+  for (const c of (spec.initContainers ?? []) as unknown[]) {
+    if (!object(c)) return null;
+    const v = request(object(c)?.resources);
+    if (v === null) return null;
+    init = Math.max(init, v);
+  }
+  const pod = spec.resources === undefined ? 0 : request(spec.resources);
+  const overheadRaw = object(spec.overhead)?.memory;
+  const overhead = spec.overhead !== undefined && !object(spec.overhead) ? null
+    : overheadRaw === undefined ? 0 : typeof overheadRaw === 'string' ? quantity(overheadRaw, 'memory') : null;
+  return pod === null || overhead === null ? null : Math.max(app, init, pod) + overhead;
+}
+
+function runningLimit(spec: Record<string, unknown>): number | null {
+  if (!Array.isArray(spec.containers) || !spec.containers.length) return null;
+  let total = 0;
+  for (const c of spec.containers) {
+    const raw = object(object(object(c)?.resources)?.limits)?.memory;
+    const value = typeof raw === 'string' ? quantity(raw, 'memory') : null;
+    if (value === null) return null;
+    total += value;
+  }
+  return total;
+}
+
+/** Read only: each cluster probe is kubectl get. Missing reservations cannot become zero. */
+export function measurePoolLease(members: readonly PodPoolMember[], deps: { kubectl?: PoolKubectl } = {}): PoolLeaseMeasure {
+  const kubectl = deps.kubectl ?? leaseKubectl;
+  return { members: members.map((member) => {
+    const base = ['--context', member.context, '--request-timeout=10s'];
+    const result: PodLeaseMember = { context: member.context, capacity: member.capacity, running: null, pending: null, memoryLimitBytes: null, allocatableMemoryBytes: null, allocatableCpuMillicores: null, availableMemoryByNodeBytes: null, reason: null };
+    try {
+      const nodes = kubectl([...base, 'get', 'nodes', '-o', 'json']);
+      const jobs = kubectl([...base, '-n', 'elanous-test', 'get', 'jobs', '-l', 'elanous.substrate=pod', '-o', 'json']);
+      // All namespaces are necessary: unrelated workloads also reserve memory on these nodes.
+      const pods = kubectl([...base, 'get', 'pods', '--all-namespaces', '-o', 'json']);
+      const reasons: string[] = [];
+      const parsedItems = (response: ReturnType<PoolKubectl>): Record<string, unknown>[] | null => {
+        if (response.status !== 0) return null;
+        try { return items(JSON.parse(response.stdout)); } catch { return null; }
+      };
+      const nodeItems = parsedItems(nodes);
+      const nodeFree = new Map<string, number>();
+      const nodeNames = new Set<string>();
+      if (!nodeItems?.length) reasons.push(`cluster nodes: ${nodes.status === 0 ? 'invalid/empty response' : nodes.stderr.trim().split('\n').pop() || `rc=${nodes.status}`}`);
+      else {
+        let memory = 0, cpu = 0, valid = true;
+        for (const node of nodeItems) {
+          const name = object(node.metadata)?.name;
+          const status = object(node.status);
+          const allocatable = object(status?.allocatable);
+          const memRaw = allocatable?.memory, cpuRaw = allocatable?.cpu;
+          const mem = typeof memRaw === 'string' ? quantity(memRaw, 'memory') : null;
+          const cores = typeof cpuRaw === 'string' ? quantity(cpuRaw, 'cpu') : null;
+          const conditions = status?.conditions;
+          const ready = Array.isArray(conditions) ? conditions.filter((c) => object(c)?.type === 'Ready') : [];
+          const spec = object(node.spec);
+          // Harness Pod Jobs declare no tolerations, so a NoSchedule/NoExecute taint keeps them off that node.
+          const taints = spec?.taints;
+          const taintList = taints === undefined ? [] : Array.isArray(taints) ? taints.map(object) : null;
+          if (typeof name !== 'string' || !name || nodeNames.has(name) || mem === null || cores === null ||
+              ready.length !== 1 || !['True', 'False', 'Unknown'].includes(String(object(ready[0])?.status)) ||
+              (node.spec !== undefined && !spec) || (spec?.unschedulable !== undefined && typeof spec.unschedulable !== 'boolean') ||
+              taintList === null || taintList.some((t) => !t || typeof t.effect !== 'string')) {
+            valid = false; break;
+          }
+          nodeNames.add(name);
+          const repels = taintList.some((t) => t!.effect === 'NoSchedule' || t!.effect === 'NoExecute');
+          if (spec?.unschedulable !== true && !repels && object(ready[0])?.status === 'True') nodeFree.set(name, mem);
+          memory += mem; cpu += cores;
+        }
+        if (valid) { result.allocatableMemoryBytes = memory; result.allocatableCpuMillicores = cpu; }
+        else { nodeFree.clear(); nodeNames.clear(); reasons.push('cluster nodes: invalid name/allocatable memory/cpu/readiness'); }
+      }
+      const jobItems = parsedItems(jobs);
+      const podItems = parsedItems(pods);
+      if (!jobItems) reasons.push(`cluster jobs: ${jobs.status === 0 ? 'invalid response' : jobs.stderr.trim().split('\n').pop() || `rc=${jobs.status}`}`);
+      if (!podItems) reasons.push(`cluster pods: ${pods.status === 0 ? 'invalid response' : pods.stderr.trim().split('\n').pop() || `rc=${pods.status}`}`);
+      if (podItems && jobItems) {
+        const jobNames = new Set<string>();
+        let jobsValid = true;
+        for (const job of jobItems) {
+          const meta = object(job.metadata);
+          if (!meta || !object(meta.labels)) { jobsValid = false; continue; }
+          if (object(meta.labels)?.['elanous.substrate'] !== 'pod') continue;
+          if (typeof meta.name !== 'string' || !meta.name) { jobsValid = false; continue; }
+          jobNames.add(meta.name);
+        }
+        if (!jobsValid) reasons.push('cluster jobs: missing name/labels');
+        let running = 0, pending = 0, limits = 0, limitsValid = true, reservationsValid = nodeItems !== null && nodeNames.size === nodeItems.length;
+        let unknownPhase = false;
+        const seenPods = new Set<string>();
+        for (const pod of podItems) {
+          const metadata = object(pod.metadata);
+          const labels = object(metadata?.labels);
+          const phase = object(pod.status)?.phase;
+          if (phase === 'Succeeded' || phase === 'Failed') continue;
+          if (phase !== 'Running' && phase !== 'Pending') { unknownPhase = true; reservationsValid = false; continue; }
+          if (typeof metadata?.namespace !== 'string') reservationsValid = false;
+          const identity = typeof metadata?.namespace === 'string' && typeof metadata.name === 'string' && metadata.name
+            ? `name:${metadata.namespace}/${metadata.name}` : null;
+          if (identity) {
+            if (seenPods.has(identity)) { reservationsValid = false; continue; }
+            seenPods.add(identity);
+          } else reservationsValid = false;
+          const harness = metadata?.namespace === 'elanous-test' &&
+            (labels?.['elanous.substrate'] === 'pod' || jobNames.has(String(labels?.['elanous.job'] ?? '')));
+          const spec = object(pod.spec);
+          let limit: number | null = null;
+          if (harness) {
+            if (phase === 'Pending') pending++;
+            else {
+              running++;
+              limit = spec ? runningLimit(spec) : null;
+              if (limit === null) limitsValid = false;
+              else limits += limit;
+            }
+          }
+          // Pending Pods with no assigned node have no node reservation yet. They already occupy a pool slot.
+          const nodeName = spec?.nodeName;
+          if ((nodeName === undefined || nodeName === '') && phase === 'Pending' && spec && typeof metadata?.namespace === 'string' &&
+              requestedMemory(spec) !== null) continue;
+          const requested = spec ? requestedMemory(spec) : null;
+          if (typeof nodeName !== 'string' || !nodeNames.has(nodeName) || requested === null) { reservationsValid = false; continue; }
+          if (nodeFree.has(nodeName)) nodeFree.set(nodeName, nodeFree.get(nodeName)! - Math.max(requested, limit ?? 0));
+        }
+        if (unknownPhase) reasons.push('cluster pods: missing/Unknown phase');
+        if (jobsValid && !unknownPhase) { result.running = running; result.pending = pending; }
+        if (limitsValid && jobsValid && !unknownPhase) result.memoryLimitBytes = limits;
+        else if (!limitsValid) reasons.push('cluster pods: Running Pod memory limit missing/invalid');
+        if (reservationsValid && limitsValid && jobsValid && !unknownPhase) result.availableMemoryByNodeBytes = [...nodeFree.values()];
+        else if (!reservationsValid && !unknownPhase) reasons.push('cluster reservations: node assignment or memory request/limit missing/invalid');
+      }
+      result.reason = reasons.length ? reasons.join('; ').slice(0, 240) : null;
+    } catch (error) {
+      result.running = null; result.pending = null; result.memoryLimitBytes = null;
+      result.allocatableMemoryBytes = null; result.allocatableCpuMillicores = null; result.availableMemoryByNodeBytes = null;
+      result.reason = `cluster: ${error instanceof Error ? error.message : String(error)}`.split('\n')[0]!.slice(0, 240);
+    }
+    return result;
+  }) };
+}
+
+/** Per-node memory and per-member slots cannot be exchanged across nodes/clusters. */
+export function recommendConcurrency(measure: PoolLeaseMeasure, options: { capacity: number; perGoalMemory?: string; accounts: number; perAccount: number }): PoolLeaseRecommendation {
+  const empty: PoolLeaseRecommendation = { recommended: null, limitedBy: null, reason: null, capacitySlots: null, memorySlots: null, placeableSlots: null, accountSlots: null, running: null, pending: null };
+  const goalBytes = quantity(options.perGoalMemory ?? '16Gi', 'memory');
+  if (goalBytes === null || goalBytes <= 0) return { ...empty, reason: '측정 불가: perGoalMemory' };
+  if (!measure.members.length || measure.members.some((m) => m.running === null || m.pending === null || m.allocatableMemoryBytes === null || m.memoryLimitBytes === null || m.allocatableCpuMillicores === null || m.availableMemoryByNodeBytes === null)) {
+    return { ...empty, reason: `측정 불가: cluster${measure.members.map((m) => m.reason ? ` ${m.context}: ${m.reason}` : '').join('')}` };
+  }
+  if (!Number.isSafeInteger(options.capacity) || options.capacity < 0) return { ...empty, reason: '측정 불가: capacity' };
+  const running = measure.members.reduce((sum, m) => sum + m.running!, 0);
+  const pending = measure.members.reduce((sum, m) => sum + m.pending!, 0);
+  const capacitySlots = Math.max(0, Math.min(options.capacity - running - pending,
+    measure.members.reduce((sum, m) => sum + Math.max(0, m.capacity - m.running! - m.pending!), 0)));
+  const memberMemorySlots = measure.members.map((m) => m.availableMemoryByNodeBytes!.reduce(
+    (sum, bytes) => sum + Math.max(0, Math.floor(bytes / goalBytes)), 0));
+  // Preserve the requested allocatable-minus-harness-limit metric. The node-local
+  // placement bound additionally accounts for every namespace's reservations.
+  const memorySlots = measure.members.reduce((sum, m) => sum + Math.max(0,
+    Math.floor((m.allocatableMemoryBytes! - m.memoryLimitBytes!) / goalBytes)), 0);
+  const placeableSlots = measure.members.reduce((sum, m, i) => sum + Math.min(
+    Math.max(0, m.capacity - m.running! - m.pending!), memberMemorySlots[i]!,
+  ), 0);
+  // Account count is not a concurrency limit (same IP · own accounts, 10-03 decision) — observed only, never a bound.
+  const accountSlots = [options.accounts, options.perAccount].every((n) => Number.isSafeInteger(n) && n >= 0)
+    ? Math.max(0, options.accounts * options.perAccount - running) : null;
+  const memoryBound = Math.min(memorySlots, placeableSlots);
+  const recommended = Math.min(capacitySlots, memoryBound);
+  const limitedBy = recommended === memoryBound && memoryBound < capacitySlots ? 'memory' : 'capacity';
+  return { recommended, limitedBy, reason: null, capacitySlots, memorySlots, placeableSlots, accountSlots, running, pending };
+}

package/src/telegram-card-followup.ts

@@ -0,0 +1,233 @@
+import { chmodSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { debug } from './debug/log.js';
+import { effectiveInstanceRoot } from './instance/resolve.js';
+import { lastJsonObject, runGraph, type GraphRunState } from './graph-runner/runner.js';
+import type { TgIncoming } from './telegram.js';
+
+const GRAPH = resolve(import.meta.dir, '../plugins/card-followup/graphs/card-followup.yaml');
+// Latin keywords are whole words only — «postcard» or «cardinal» is not a card request (review round 3).
+const KEYWORD = /명함|전략|메일\s*초안|초안|팔로업|\bcard\b|\bCRM\b/i;
+/** Untagged albums start one graph run, not one per photo (chatId:mediaGroupId → first seen at). */
+const startedAlbums = new Map<string, number>();
+const ALBUM_TTL_MS = 10 * 60_000;
+function firstOfAlbum(chatId: number, mediaGroupId: string | undefined, now: number): boolean {
+  if (!mediaGroupId) return true;
+  for (const [key, at] of startedAlbums) if (now - at > ALBUM_TTL_MS) startedAlbums.delete(key);
+  const key = `${chatId}:${mediaGroupId}`;
+  if (startedAlbums.has(key)) return false;
+  startedAlbums.set(key, now);
+  return true;
+}
+
+// Captionless photos start a run only when they look like a business card (OP 10-02 18:54 · cheap signals first, ambiguous → nothing).
+export type CardDetectDecision = 'card' | 'skip' | 'ambiguous';
+export function cardShape(width?: number, height?: number): { decision: 'skip' | 'pass'; signal: string } {
+  if (!width || !height) return { decision: 'pass', signal: 'ratio:unknown' };
+  const ratio = Math.max(width, height) / Math.min(width, height);
+  if (ratio < 1.15) return { decision: 'skip', signal: 'ratio:square' };
+  if (ratio > 2.0) return { decision: 'skip', signal: 'ratio:screenshot' };
+  return { decision: 'pass', signal: `ratio:${ratio.toFixed(2)}` };
+}
+const EMAIL = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i;
+const PHONE = /(?:\+?\d{1,3}[\s.-]?)?\(?\d{2,4}\)?[\s.-]?\d{3,4}[\s.-]?\d{4}/;
+const WEB = /\b(?:https?:\/\/|www\.)\S+|\b[a-z0-9-]+\.(?:com|co\.kr|kr|io|ai|net|org)\b/i;
+const TITLE = /대표|이사|팀장|부장|과장|실장|매니저|주식회사|\(주\)|\b(?:CEO|CTO|COO|CFO|Director|Manager|Founder|Inc|Ltd|Corp)\b/i;
+/** Card text is short and carries contact patterns; long text is a document. Returns signal names only, never the text. */
+export function cardText(ocr: string | null): { decision: CardDetectDecision; signal: string } {
+  if (ocr === null) return { decision: 'ambiguous', signal: 'ocr:unavailable' };
+  const chars = ocr.replace(/\s+/g, '').length;
+  if (chars < 15) return { decision: 'ambiguous', signal: `ocr:chars<15` };
+  if (chars > 700) return { decision: 'skip', signal: 'ocr:document' };
+  const hits = ([['email', EMAIL], ['phone', PHONE], ['web', WEB], ['title', TITLE]] as const).filter(([, re]) => re.test(ocr)).map(([name]) => name);
+  const signal = `ocr:${hits.join(',') || 'none'}`;
+  if (hits.length >= 2) return { decision: 'card', signal };
+  return { decision: hits.length === 0 ? 'skip' : 'ambiguous', signal };
+}
+const OCR_SCRIPT = resolve(import.meta.dir, '../scripts/ocr-text-regions.swift');
+/** Local macOS Vision OCR (no network · no new dependency); null where it cannot run. */
+export function localOcrText(path: string, timeoutMs = 30_000): Promise<string | null> {
+  if (process.platform !== 'darwin') return Promise.resolve(null);
+  return new Promise((done) => {
+    let out = '';
+    let child: ReturnType<typeof spawn>;
+    try { child = spawn('swift', [OCR_SCRIPT, path], { stdio: ['ignore', 'pipe', 'ignore'] }); } catch { done(null); return; }
+    const timer = setTimeout(() => { child.kill('SIGKILL'); done(null); }, timeoutMs);
+    child.stdout?.on('data', (chunk) => { out += String(chunk); });
+    child.once('error', () => { clearTimeout(timer); done(null); });
+    child.once('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) { done(null); return; }
+      done(out.split('\n').map((l) => /^\s+[\d.]+\s+(.*?)\s+box=/.exec(l)?.[1]).filter(Boolean).join('\n'));
+    });
+  });
+}
+
+type Picked = 'all' | 'strategy' | 'draft' | 'crm';
+export interface CardPhotoDeps {
+  isOwner: (userId: number) => boolean;
+  isFieldAlbum?: (id: string) => boolean;
+  downloadFile: (fileId: string, destDir: string) => Promise<{ localPath: string }>;
+  sendMessage: (chatId: number, text: string, opts: { replyTo: number; threadId?: number }) => Promise<unknown>;
+  sendDocument: (chatId: number, body: string | Buffer, filename: string, opts: { replyTo: number; threadId?: number; mimeType?: string }) => Promise<unknown>;
+  runGraph?: typeof runGraph;
+  rootDir?: () => string;
+  /** OCR text of a downloaded photo, or null when unavailable (default: local macOS Vision). */
+  ocrText?: (path: string) => Promise<string | null>;
+}
+
+const obj = (value: unknown): Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+const text = (value: unknown): string => typeof value === 'string' ? value.trim() : '';
+const line = (value: unknown): string => (typeof value === 'number' && Number.isFinite(value) ? String(value) : text(value)).replace(/[\r\n]+/g, ' ') || '—';
+
+function isNotACard(state: GraphRunState): boolean {
+  if (state.status !== 'failed') return false;
+  const read = state.nodes.find((node) => node.nodeId === 'read-card');
+  if (!read || !read.ok) return false;
+  const output = lastJsonObject(read.output);
+  if (output?.outcome === 'ok' && output.card && typeof output.card === 'object') {
+    const card = obj(output.card);
+    return !['name', 'company', 'title', 'email', 'phone', 'url', 'linkedin'].some((field) => text(card[field]));
+  }
+  return output?.outcome === 'fail' && typeof output.reason === 'string'
+    && /\bnot a (?:business )?card\b|명함이?\s*아님|명함이?\s*아닙니다/i.test(output.reason);
+}
+
+function validateReport(report: Record<string, unknown>): void {
+  const card = obj(report.card), fit = obj(report.fit), approach = obj(report.approach);
+  const next = obj(report.nextAction), draft = obj(report.draft);
+  const score = fit.score;
+  if (report.sent !== false || !text(card.name) || !text(card.company)
+    || !(score === null || (typeof score === 'number' && Number.isFinite(score)))
+    || !text(fit.label) || !text(approach.problem) || !text(approach.proposal)
+    || !text(approach.channel) || !text(next.what) || !text(next.due)
+    || !text(draft.subject) || !text(draft.body)) {
+    throw new Error('incomplete or sent card report');
+  }
+}
+
+function pick(caption: string): Picked {
+  if (/\bCRM\b/i.test(caption)) return 'crm';
+  if (/메일\s*초안|초안/i.test(caption)) return 'draft';
+  if (/전략/.test(caption)) return 'strategy';
+  return 'all';
+}
+
+/** Starts a private graph run without blocking the Telegram message turn. */
+export async function maybeHandleCardPhoto(ctx: TgIncoming, deps: CardPhotoDeps): Promise<boolean> {
+  const photo = ctx.attachments.find((att) => att.kind === 'photo');
+  const caption = ctx.text.trim();
+  if (!ctx.isDm || ctx.isGroup || !deps.isOwner(ctx.userId) || !photo
+    || (ctx.mediaGroupId && deps.isFieldAlbum?.(ctx.mediaGroupId))
+    || /#현장/.test(caption) || (caption && !KEYWORD.test(caption))) return false;
+  const detect = (decision: CardDetectDecision, signal: string) =>
+    debug.log('telegram.card-followup', 'detect', { chatId: ctx.chatId, decision, signal });
+  if (!caption) {
+    const shape = cardShape(photo.width, photo.height);
+    if (shape.decision === 'skip') { detect('skip', shape.signal); return false; }
+  }
+  // Album items after the first: a keyword caption sits on one item only, so later items follow the normal flow.
+  if (!firstOfAlbum(ctx.chatId, ctx.mediaGroupId, Date.now())) return false;
+
+  const picked = pick(caption);
+  const started = Date.now();
+  const reply = { replyTo: ctx.messageId, ...(ctx.threadId === undefined ? {} : { threadId: ctx.threadId }) };
+  const log = (event: 'started' | 'not-a-card' | 'replied' | 'failed') =>
+    debug.log('card.followup', event, { chatId: ctx.chatId, picked, ms: Date.now() - started });
+
+  try {
+    const root = (deps.rootDir ?? effectiveInstanceRoot)();
+    const base = join(root, 'graph-runs', 'card-followup');
+    const runId = randomUUID();
+    const dir = join(base, runId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(base, 0o700);
+    chmodSync(dir, 0o700);
+    const prepare = async (): Promise<string | null> => {
+      const { localPath } = await deps.downloadFile(photo.fileId, dir);
+      chmodSync(localPath, 0o600);
+      if (!caption) {
+        const verdict = cardText(await (deps.ocrText ?? localOcrText)(localPath));
+        detect(verdict.decision, verdict.signal);
+        if (verdict.decision !== 'card') { rmSync(dir, { recursive: true, force: true }); return null; }
+      }
+      log('started');
+      await deps.sendMessage(ctx.chatId, '명함으로 보고 정리하는 중입니다(1~3분)', reply);
+      return localPath;
+    };
+    // A keyword caption is an explicit request: download before returning. A bare photo is judged in the background.
+    const prepared = caption ? await prepare() : null;
+    void (async () => {
+      let localPath = prepared;
+      try {
+        if (!caption) {
+          try { localPath = await prepare(); } catch { log('failed'); return; }
+          if (!localPath) return;
+        }
+        const state = await (deps.runGraph ?? runGraph)(GRAPH, { runId, deps: { root }, input: {
+          image: localPath!, outDir: dir, ...(caption ? { context: caption } : {}),
+        } });
+        if (!deps.runGraph) {
+          const statePath = join(base, `${runId}.json`);
+          chmodSync(statePath, 0o600);
+          const contexts = `${statePath}.contexts`;
+          try {
+            chmodSync(contexts, 0o700);
+            for (const file of readdirSync(contexts)) chmodSync(join(contexts, file), 0o600);
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+          }
+        }
+        if (isNotACard(state)) {
+          log('not-a-card');
+          return;
+        }
+        if (state.status !== 'done') throw new Error('graph did not finish');
+        const report = obj(JSON.parse(readFileSync(join(dir, 'followup.json'), 'utf8')));
+        validateReport(report);
+        const card = obj(report.card), fit = obj(report.fit), approach = obj(report.approach);
+        const next = obj(report.nextAction), draft = obj(report.draft);
+        const summary = `① 요약\n${line(card.name)} · ${line(card.company)} · ${line(card.title)}\n타겟 판정: ${line(fit.score)} · ${line(fit.label)}`;
+        const strategy = `② 전략\n${[approach.problem, approach.proposal, approach.channel].map(line).join('\n')}\n다음 행동: ${line(next.what)} · ${line(next.due)}`;
+        const mail = `③ 팔로업 초안 (보내지 않았습니다)\n제목: ${line(draft.subject)}\n${text(draft.body)}`;
+        const markdown = readFileSync(join(dir, 'followup.md'));
+        const crmLine = picked === 'crm'
+          ? /^## ② CRM 한 줄\r?\n파일: [^\r\n]*\r?\n([^\r\n]+)/m.exec(markdown.toString('utf8'))?.[1]
+          : undefined;
+        if (picked === 'crm' && !crmLine) throw new Error('CRM row missing from report');
+        const messages = picked === 'strategy' ? [strategy] : picked === 'draft' ? [mail] : picked === 'crm' ? [`CRM 한 줄\n${crmLine}`] : [summary, strategy, mail];
+        for (const message of messages) await deps.sendMessage(ctx.chatId, message, reply);
+        const sent = await deps.sendDocument(ctx.chatId, markdown, 'followup.md', { ...reply, mimeType: 'text/markdown' });
+        if (sent === undefined) throw new Error('document delivery failed');
+        log('replied');
+      } catch {
+        log('failed');
+        try {
+          await deps.sendMessage(ctx.chatId, '명함 정리에 실패했습니다. 다시 시도해 주세요.', reply);
+        } catch { /* Telegram delivery itself failed; the failure is already observed. */ }
+      } finally {
+        if (!deps.runGraph) {
+          // The runner may throw before returning its state; seal any partial state and contexts too.
+          const statePath = join(base, `${runId}.json`);
+          try { chmodSync(statePath, 0o600); } catch { /* no state yet */ }
+          const contexts = `${statePath}.contexts`;
+          try {
+            chmodSync(contexts, 0o700);
+            for (const file of readdirSync(contexts)) chmodSync(join(contexts, file), 0o600);
+          } catch { /* no contexts yet */ }
+        }
+      }
+    })();
+  } catch {
+    log('failed');
+    // A bare photo was never claimed as a card — failing to prepare it stays silent.
+    if (caption) {
+      try {
+        await deps.sendMessage(ctx.chatId, '명함 정리에 실패했습니다. 다시 시도해 주세요.', reply);
+      } catch { /* Telegram delivery itself failed; the failure is already observed. */ }
+    }
+  }
+  return !!caption;
+}

package/src/telegram-commands.ts

@@ -775,6 +775,22 @@ export function defaultTelegramCommands(): TgSlashCommand[] {
         return service.listOpen(String(ctx.chatId));
       },
     },
+    ...(['coo', 'cto', 'cmo', 'cxo'] as const).map((command) => ({
+      name: command,
+      description: `${command.toUpperCase()} 자리에 일을 넘깁니다 — /${command} <할 일> (조율 채널 ⊕ 자리 메시지함)`,
+      handler: async (args: string[], ctx: { chatId: number; userId: number }) => {
+        const [{ handleCeoSeatCommand }, { telegramDecisionOwner }, { runGh }, { getUserConfig }, { openMsgStore }] = await Promise.all([
+          import('./seat-dispatch/ceo-commands.js'), import('./decisions/telegram-decision-cards.js'), import('./decisions/decision-cards.js'),
+          import('./user-config.js'), import('./msg/msg-store.js'),
+        ]);
+        const cfg = getUserConfig();
+        const replyTarget = (cfg.raw?.decisions as { replyGhPr?: unknown } | undefined)?.replyGhPr;
+        return handleCeoSeatCommand(command, args, ctx, {
+          ownerId: telegramDecisionOwner(cfg), replyTarget: typeof replyTarget === 'string' ? replyTarget : null, runGh,
+          append: (message) => { const store = openMsgStore(); try { return store.append(message); } finally { store.close(); } },
+        });
+      },
+    })),
     {
       name: 'work',
       description: '글을 알맞은 곳(흡수·태스크·하니스)에 넣고 결과를 여기로 답합니다 — /work [absorb|tasks|graph] <글>',

package/src/telegram-report.ts

@@ -11,7 +11,7 @@
 // the report channel while interactive Q&A stays on the main bot.
 
 import { TelegramBot } from './telegram.js';
-import { kindRouteTarget } from './domains/telegram-kind-route.js';
+import { isOperationalKind, kindRouteTarget, logKindRouteFallback, mainHomeTarget } from './domains/telegram-kind-route.js';
 export { DEFAULT_KIND_ROLES, roleForKind } from './domains/telegram-kind-route.js';
 import { resolveChannelBotToken } from './channel-bot-token.js';
 import type { UserConfig } from './user-config.js';
@@ -51,18 +51,24 @@ export interface ReportTarget {
   chatId: number;
 }
 
-/** Resolve the send target. With a purpose `kind` that maps to a role and explicit `telegram.channels`,
- *  the channel holding that role wins (fallback: the `default` channel). Otherwise the legacy report
- *  channel: `botToken` falls back to the main Q&A bot token when the report channel is served by the
- *  same bot. Returns null when nothing is configured. */
+/** Explicit role channels win. Without a role channel, operational kinds use the main bot's
+ *  home when the legacy report channel uses another bot; same-bot reports and trading kinds
+ *  keep the legacy report destination. Returns null when no safe target is configured. */
 export function resolveReportTarget(cfg: UserConfig, kind?: string): ReportTarget | null {
   const routed = kindRouteTarget(cfg, kind);
   if (routed) return routed;
   const rc = cfg.telegram.reportChannel;
-  if (!rc || !Number.isFinite(rc.chatId)) return null;
-  const botToken = rc.botToken ?? resolveChannelBotToken('telegram', cfg)?.token;
-  if (!botToken) return null;
-  return { botToken, chatId: rc.chatId };
+  const mainToken = resolveChannelBotToken('telegram', cfg).token;
+  const sameBot = !!mainToken && !!rc && (rc.botToken ?? mainToken) === mainToken;
+  if (isOperationalKind(kind) && !sameBot) {
+    const home = mainHomeTarget(cfg);
+    logKindRouteFallback(kind, home ? 'main-home' : 'none', sameBot);
+    return home;
+  }
+  const botToken = rc?.botToken ?? mainToken;
+  const target = rc && Number.isFinite(rc.chatId) && botToken ? { botToken, chatId: rc.chatId } : null;
+  logKindRouteFallback(kind, target ? 'report-channel' : 'none', sameBot);
+  return target;
 }
 
 export interface SendReportOpts {