@angar2/taskery 0.8.1 → 1.0.0

package/bin/mcp.js

@@ -1,280 +1,48 @@
 #!/usr/bin/env node
-// taskery MCP 서버 — lib.js core 함수를 구조화 도구로 노출 (CLI와 동일 단일 홈, 로직 중복 0)
-/**
- * bin/mcp.js
- * `npx @angar2/taskery mcp` — stdio MCP 서버. Claude(.mcp.json) / Codex(codex mcp add) 등록.
- *
- * 도구 8종 = CLI 명령과 동일한 lib.js 함수의 다른 입구(네이티브 구조화 인자/반환).
- *   backlog_add / backlog_get / backlog_mark — 활성 plan BACKLOG.md 조작
- *   set_status   — task 헤더 상태 전이 (7×7 유효전이 검증, closed 거부)
- *   plan_init    — plan 생성 (채번+골격+manifest.activePlan 갱신)
- *   task_init    — task 분기 (fork 원자 채번 + §1.3 골격 자동 생성)
- *   task_close   — close 결정적 준비만 (Phase커밋·status=closed·마커). 비가역 머지/정리는 스킬.
- *   status       — 멀티세션 현황 + 활성 plan
- *
- * SDK(@modelcontextprotocol/sdk)는 dual CJS/ESM — require 조건으로 CJS 빌드 해결(검증 완료).
- */
-
-const path = require('path');
+// taskery MCP 서버 — 명령 정의표(commands.js)의 명령을 같은 이름·같은 인자의 MCP 도구로 띄운다
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { z } = require('zod');
-const lib = require('./lib');
-
-const VALID_TYPES = ['feature', 'bug', 'improve', 'refactor', 'docs', 'chore'];
-const VALID_SIZES = ['micro', 'small', 'medium', 'large'];
-
-// 메인 워크트리 검출 + manifest 확인. 실패 시 throw(핸들러 래퍼가 isError 응답으로 변환).
-function resolveMainWt() {
-  const mainWt = lib.getMainWorktreePath();
-  if (!lib.readManifest(path.join(mainWt, lib.MANIFEST_NAME))) {
-    throw new Error(`${lib.MANIFEST_NAME} 없음 — 'npx @angar2/taskery init' 먼저 실행 필요.`);
-  }
-  return mainWt;
+const { COMMANDS, execute } = require('./commands');
+const L = require('./lib');
+
+// 서버를 띄운 폴더의 본진을 처음에 한 번 정한다 — 세션이 워크트리를 오가도, 워크트리가 지워져도 같은 본진을 쓴다
+const startCwd = process.cwd();
+let main = null;
+try {
+  main = L.findMain(startCwd);
+} catch (e) {
+  main = null;
 }
 
-// 'TASK-007' | 'TASK-7' | 7 | '7' → 7 (CLI 관용성 미러링)
-function parseTaskNum(token) {
-  const m = String(token).match(/(\d+)/);
-  return m ? parseInt(m[1], 10) : NaN;
+function schemaOf(cmd) {
+  const shape = {};
+  for (const a of cmd.args) {
+    let t;
+    if (a.type === 'bool') t = z.boolean();
+    else if (a.type === 'list') t = z.array(z.string());
+    else t = z.union([z.string(), z.number()]).transform(String);
+    shape[a.name] = t.optional().describe(a.desc);
+  }
+  return shape;
 }
 
-// 미등록 케이스 문서는 task 워크트리에 있음 — 서버 cwd 고정이라 SSoT로 워크트리 유도.
-function resolveTaskDoc(mainWt, taskNum) {
-  const active = lib.getActiveTasks(mainWt).find((t) => t.taskNum === taskNum);
-  const wtPath = active
-    ? lib.getWorktreePath(lib.getProjectId(mainWt), {
-        taskNum,
-        src: active.src,
-        slug: active.slug,
-      })
-    : mainWt;
-  return lib.resolveTaskDocPath(mainWt, wtPath, { taskNum });
-}
+const server = new McpServer({ name: 'taskery', version: L.getPackageVersion() });
 
-// 구조화 결과(JSON) + 선택 가이드 → MCP content.
-function ok(data, guide) {
-  const text = guide ? `${JSON.stringify(data)}\n\n${guide}` : JSON.stringify(data);
-  return { content: [{ type: 'text', text }] };
-}
-function fail(message) {
-  return { content: [{ type: 'text', text: `오류: ${message}` }], isError: true };
-}
-
-// 핸들러 공통 래퍼 — 예외를 isError 응답으로 변환(서버 크래시 방지).
-function handler(fn) {
-  return async (args) => {
+// wait-reports는 CLI만 — MCP 도구 호출은 결과가 올 때까지 세션을 붙잡는다(§5-3)
+for (const cmd of COMMANDS.filter((c) => !c.cliOnly)) {
+  server.registerTool(cmd.name, { description: cmd.summary, inputSchema: schemaOf(cmd) }, async (args) => {
     try {
-      return await fn(args || {});
+      const out = await execute(cmd, args || {}, { cwd: startCwd, main: main || L.findMain(startCwd) });
+      return { content: [{ type: 'text', text: out || '완료' }] };
     } catch (e) {
-      return fail(e.message);
+      const text = e instanceof L.TaskeryError ? e.message : `taskery ${cmd.name} 실패: ${e.message}`;
+      return { content: [{ type: 'text', text }], isError: true };
     }
-  };
-}
-
-const server = new McpServer({ name: 'taskery', version: lib.getPackageVersion() });
-
-server.registerTool(
-  'backlog_add',
-  {
-    description:
-      '활성 plan BACKLOG.md에 task 후보 1건 추가 (BL-NNN 채번 + withMetaLock 직렬화). 얕은 분석 메타를 인자로 받는다.',
-    inputSchema: {
-      type: z.enum(VALID_TYPES),
-      title: z.string().describe('한 줄 제목(한국어)'),
-      slug: z.string().describe('영어 kebab-case 슬러그'),
-      summary: z.string().describe('한 줄 개요'),
-      target: z.string().describe('한 줄 대상 영역'),
-    },
-  },
-  handler(async (a) => {
-    const mainWt = resolveMainWt();
-    const blNum = await lib.appendBacklogItem(mainWt, a);
-    const blId = `BL-${String(blNum).padStart(3, '0')}`;
-    return ok({ blNum, blId }, `${blId} 추가됨. 진행 의향이면 task_init이 이 메타로 워크트리를 분기한다.`);
-  }),
-);
-
-server.registerTool(
-  'backlog_get',
-  {
-    description:
-      '활성 plan BACKLOG.md에서 BL-NNN 항목 메타 조회 → { blId, status, type, title, slug, summary, target, taskNums }.',
-    inputSchema: { blId: z.string().regex(/^BL-\d+$/, 'BL-NNN 형식') },
-  },
-  handler(async (a) => {
-    const mainWt = resolveMainWt();
-    const item = lib.parseBacklogItem(mainWt, a.blId);
-    if (!item) throw new Error(`${a.blId} 항목 없음.`);
-    return ok(item);
-  }),
-);
-
-server.registerTool(
-  'backlog_mark',
-  {
-    description: 'BL-NNN을 [x] 확인 마킹 + TASK-NNN 연결 (withMetaLock). task_init 직후 호출.',
-    inputSchema: {
-      blId: z.string().regex(/^BL-\d+$/, 'BL-NNN 형식'),
-      task: z.union([z.string(), z.number()]).describe('TASK-NNN 또는 번호'),
-    },
-  },
-  handler(async (a) => {
-    const taskNum = parseTaskNum(a.task);
-    if (!Number.isInteger(taskNum)) throw new Error(`TASK 번호 파싱 실패 (받음: ${a.task}).`);
-    const mainWt = resolveMainWt();
-    await lib.markBacklogChecked(mainWt, a.blId, taskNum);
-    return ok({ blId: a.blId, taskNum });
-  }),
-);
-
-server.registerTool(
-  'set_status',
-  {
-    description:
-      'task 헤더 상태 전이 (TASK_DOC_RULE §1.2 7×7 유효전이 검증). 잘못된 전이 거부. closed 전이는 task_close가 담당하므로 여기선 거부.',
-    inputSchema: {
-      task: z.union([z.string(), z.number()]).describe('TASK-NNN 또는 번호'),
-      state: z.string().describe('전이 목표 상태'),
-    },
-  },
-  handler(async (a) => {
-    const taskNum = parseTaskNum(a.task);
-    if (!Number.isInteger(taskNum)) throw new Error(`TASK 번호 파싱 실패 (받음: ${a.task}).`);
-    if (!Object.prototype.hasOwnProperty.call(lib.TRANSITIONS, a.state)) {
-      throw new Error(`알 수 없는 상태: ${a.state} (유효: ${Object.keys(lib.TRANSITIONS).join(', ')})`);
-    }
-    if (a.state === 'closed') {
-      throw new Error(`closed 전이는 set_status가 아니라 task_close(close 파이프라인)가 담당.`);
-    }
-    const mainWt = resolveMainWt();
-    const resolved = resolveTaskDoc(mainWt, taskNum);
-    if (!resolved) throw new Error(`TASK-${String(taskNum).padStart(3, '0')} 문서를 찾지 못함.`);
-    const result = await lib.setStatus(resolved.file, a.state);
-    return ok({ taskNum, ...result });
-  }),
-);
-
-server.registerTool(
-  'plan_init',
-  {
-    description:
-      'plan(기능 그룹) 생성 — 채번 + 폴더 + ROADMAP/PLAN/BACKLOG 골격 + 활성 plan 갱신. 이후 골격 내용은 LLM이 채움. legacy 폴더 잔존 시 gated 반환(force로 재호출).',
-    inputSchema: {
-      slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, '영어 kebab-case'),
-      force: z.boolean().optional().describe('legacy 게이트 무시'),
-    },
-  },
-  handler(async (a) => {
-    const mainWt = resolveMainWt();
-    const result = lib.initPlan(mainWt, a.slug, { force: !!a.force });
-    if (result.gated) {
-      return ok(
-        { gated: true, legacyDirs: result.legacyDirs },
-        `plans/에 NNN 채번 아닌 폴더(${result.legacyDirs.join(', ')}) 잔존 — 사용자 confirm 후 force:true로 재호출.`,
-      );
-    }
-    return ok(
-      { plan: result.plan, nnn: result.nnn, planDir: result.planDir, tasksDir: result.tasksDir },
-      `골격 생성됨. ROADMAP Stage 내용·PLAN 링크·FEATURES/UX-UI delta는 placeholder를 채운다.`,
-    );
-  }),
-);
-
-server.registerTool(
-  'task_init',
-  {
-    description:
-      'task 분기 — 채번+워크트리+브랜치 생성을 init 락으로 원자 실행. size·title 주면 §1.3 골격 task.md도 자동 생성(생성일·status=draft 자동). 통상 /task-init 경유.',
-    inputSchema: {
-      type: z.enum(VALID_TYPES),
-      dev: z.string().describe('개발자 식별자 (claude / angar2 등)'),
-      src: z.string().regex(/^(BL-\d+|RM-\d+|ST-\d+|DR)$/, 'BL-NNN | ST-N(로드맵 Stage) | DR (구형 RM-NNN 호환)'),
-      slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, '영어 kebab-case'),
-      size: z.enum(VALID_SIZES).optional(),
-      title: z.string().optional().describe('한국어 제목 (size와 함께 주면 골격 생성)'),
-      promote: z.boolean().optional(),
-    },
-  },
-  handler(async (a) => {
-    const mainWt = resolveMainWt();
-    const result = await lib.forkTask(mainWt, {
-      type: a.type,
-      dev: a.dev,
-      src: a.src,
-      slug: a.slug,
-    });
-    let out = result;
-    if (a.size && a.title) {
-      try {
-        const doc = lib.scaffoldTaskDoc(mainWt, result.wtPath, {
-          taskNum: result.taskNum,
-          slug: a.slug,
-          title: a.title,
-          type: a.type,
-          size: a.size,
-          parent: result.parent,
-          promoted: !!a.promote,
-        });
-        out = { ...result, docPath: doc.file, registered: doc.registered, promoted: doc.promoted };
-      } catch (e) {
-        out = { ...result, scaffoldError: e.message };
-      }
-    }
-    return ok(out, `워크트리 생성됨. 제목 확인 후 /task-plan으로 진행.`);
-  }),
-);
-
-server.registerTool(
-  'task_close',
-  {
-    description:
-      'close 결정적 준비만 — Phase 커밋·status=closed·문서 커밋·추적마커. 게이트(status=tested)·매핑 모호 시 blocked 반환. 반환 parent = 스킬 머지 대상 부모 브랜치. 비가역(부모 --no-ff 머지·worktree/branch 정리·충돌 해결)은 스킬(task-close)이 후속 수행.',
-    inputSchema: { task: z.union([z.string(), z.number()]).describe('TASK-NNN 또는 번호') },
-  },
-  handler(async (a) => {
-    const taskNum = parseTaskNum(a.task);
-    if (!Number.isInteger(taskNum)) throw new Error(`TASK 번호 파싱 실패 (받음: ${a.task}).`);
-    const mainWt = resolveMainWt();
-    const result = await lib.closeTask(mainWt, { taskNum });
-    if (result.blocked === 'status') {
-      return ok(result, `게이트 차단 — status=${result.current} (tested 아님). /task-test 통과 후 재호출.`);
-    }
-    if (result.blocked === 'mapping') {
-      return ok(
-        result,
-        `Phase↔파일 매핑 모호 (${result.reason}) — Dev Plan '파일' 필드 확인 후 수동 Phase 커밋 → task_close 재호출.`,
-      );
-    }
-    return ok(result, `prep 완료 (부모=${result.parent}). 비가역(사전 rebase·충돌해결·머지 락·부모 --no-ff 머지·정리)은 task-close 스킬이 후속 수행.`);
-  }),
-);
-
-server.registerTool(
-  'status',
-  {
-    description: '멀티세션 현황 — 진행중 task + 워크트리 + 활성 plan 버전.',
-    inputSchema: {},
-  },
-  handler(async () => {
-    const mainWt = resolveMainWt();
-    const activeTasks = lib.getActiveTasks(mainWt);
-    let activePlan = null;
-    try {
-      activePlan = lib.getActiveVersion(mainWt);
-    } catch (e) {
-      activePlan = null;
-    }
-    return ok({ activePlan, activeTasks });
-  }),
-);
-
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  });
 }
 
-main().catch((e) => {
+server.connect(new StdioServerTransport()).catch((e) => {
   console.error(`taskery mcp 실패: ${e.message}`);
   process.exit(1);
 });

package/bin/orche.js

@@ -0,0 +1,240 @@
+// orca-dispatch-task · report-task · wait-reports — 오케스트레이션의 띄우기·보고·보고 받기(§5-3, §5-4)
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const L = require('./lib');
+
+const AGENTS = ['claude', 'codex'];
+// 보고 없이 기다리는 시간이자 '오래 조용한 탭'의 기준. 환경 변수는 시험 전용 통로다
+const WAIT_MS = Number(process.env.TASKERY_WAIT_REPORTS_MS) || 10 * 60 * 1000;
+const POLL_MS = Math.min(1000, WAIT_MS);
+// 첫 지시문을 보낸 뒤 턴 시작을 지켜보는 시간(orca terminal send --wait-submit)
+const SUBMIT_WAIT_SEC = 30;
+
+function reportsFile(main) {
+  return path.join(main, '.taskery', 'reports.log');
+}
+
+function readPosFile(main) {
+  return path.join(L.stateDir(main), 'reports-read.json');
+}
+
+// orca 명령을 --json으로 부르고 result를 돌려준다. 종료 코드가 0이 아니어도 JSON이 ok면 돌려준다(terminal wait 미충족)
+function orca(args) {
+  let out = '';
+  let err = '';
+  try {
+    out = execFileSync('orca', [...args, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (e) {
+    out = (e.stdout || '').toString();
+    err = ((e.stderr || '').toString().trim() || e.message).split('\n')[0];
+  }
+  let j = null;
+  try {
+    j = JSON.parse(out);
+  } catch (e) {
+    j = null;
+  }
+  if (j && j.ok) return j.result;
+  const why = (j && j.error && (j.error.message || j.error.code)) || err || out.trim() || '알 수 없는 오류';
+  throw new L.TaskeryError(`orca ${args.slice(0, 2).join(' ')} 실패: ${why}`);
+}
+
+// 셸에 그대로 넘길 수 있게 감싼다(--command는 탭의 셸에 입력된다)
+function shq(v) {
+  return /^[A-Za-z0-9_.\/:=@%+-]+$/.test(v) ? v : `'${String(v).replace(/'/g, `'\\''`)}'`;
+}
+
+// 에이전트 실행 명령 — 권한·승인 옵션은 붙이지 않는다(사용자 설정 그대로, I5)
+function agentCommand(main, agent, model) {
+  if (agent === 'claude') return `claude --model ${shq(model)}`;
+  return `codex -m ${shq(model)} --add-dir ${shq(path.join(main, '.taskery'))}`;
+}
+
+// 단계 표에서 비어 있는 첫 단계의 스킬 — 새 태스크면 task-plan
+function startSkill(st) {
+  if (!st.approve) return 'task-plan';
+  if (L.sw(st, 'dev') && !st.testCode) return 'task-dev';
+  if (L.sw(st, 'test') && !st.testDone) return 'task-test';
+  return 'task-close';
+}
+
+function oneLine(text) {
+  return String(text).replace(/\s*\n\s*/g, ' ').trim();
+}
+
+// 첫 지시문 틀(§5-4) — 마지막 줄은 --note를 줬을 때만
+function firstInstruction(st, note) {
+  const label = L.taskLabel(st.num);
+  const lines = [
+    `[오케스트레이션] taskery 태스크 ${label} 「${st.title}」를 맡는다. 이 세션은 태스크 세션이다.`,
+    `- 태스크 문서: ${st.doc} — 먼저 읽는다.`,
+    `- 시작: ${startSkill(st)}부터 한다. 태스크 만들기(task-init)와 워크트리 준비는 끝났다.`,
+    `- 진행 범위: ${st.range}. 범위와 무관하게 사용자 확인·FAIL·풀지 못한 충돌에서는 멈춘다.`,
+    `- 보고: 마무리 완료(병합, 병합이 없는 태스크는 merge-task가 건너뛴 뒤)·사용자 확인 대기·질문·막힘 때 report-task ${label} "<한 줄>"을 부른다.`,
+    '- 마무리(merge-task)까지 끝나면 보고하고 멈춘다. 워크트리 정리와 태스크 닫기는 오케스트레이션이 한다.',
+  ];
+  if (note && oneLine(note)) lines.push(`- 오케스트레이션이 전하는 말: ${oneLine(note)}`);
+  return lines.join('\n');
+}
+
+// 지시문을 보내고 턴 시작이 관측됐는지 돌려준다. 받지 않았으면 refused. 관측할 수 없는 곳(영수증 없음·provider가 보고 못 함)은 보낸 것으로 본다
+function sendPrompt(handle, text) {
+  const r = orca(['terminal', 'send', '--terminal', handle, '--text', text, '--enter', '--wait-submit', String(SUBMIT_WAIT_SEC)]);
+  const send = (r && r.send) || {};
+  if (send.accepted === false) return { refused: send.refusedReason || '거부' };
+  const p = send.prompt;
+  return { observed: !p || (p.stages || []).includes('turn_started') || ['unsupported', 'old-host'].includes(p.provider) };
+}
+
+// 탭 화면에 첫 지시문 첫머리가 보이나 — 보이면 들어간 것이라 다시 보내지 않는다
+function onScreen(handle, marker) {
+  try {
+    const r = orca(['terminal', 'read', '--terminal', handle, '--screen']);
+    const screen = ((r && r.terminal && r.terminal.tail) || []).join('').replace(/\s+/g, '');
+    return screen.includes(marker.replace(/\s+/g, ''));
+  } catch (e) {
+    return false;
+  }
+}
+
+async function orcaDispatchTask(ctx, a) {
+  const main = ctx.main;
+  if (!L.inOrca()) {
+    L.fail(
+      'orca-dispatch-task: Orca 탭 안이 아니라 태스크 세션을 띄울 수 없다(Orca 전용 — Orca 환경 변수 ORCA_TERMINAL_HANDLE이 없다). ' +
+        'Orca 탭에서 연 오케스트레이션 세션에서 부르거나, 사용자가 그 태스크의 워크트리에서 직접 세션을 연다.',
+    );
+  }
+  L.requireInstalled(main);
+  const missing = [];
+  if (!a.task) missing.push('<task> — 태스크 번호 (첫 번째 인자)');
+  if (!a.agent) missing.push(`--agent — ${AGENTS.join(' · ')}`);
+  if (!a.model) missing.push('--model — 에이전트 모델 (사용자가 정한 것)');
+  if (missing.length) L.fail(`orca-dispatch-task: 빠진 입력이 있다.\n${missing.map((m) => `- ${m}`).join('\n')}`);
+  if (!AGENTS.includes(a.agent)) L.fail(`orca-dispatch-task: --agent '${a.agent}'을 모른다. ${AGENTS.join(' · ')} 중 하나를 넣는다.`);
+  const num = L.parseTaskNum(a.task);
+  const st = L.readState(main, num);
+  const label = L.taskLabel(num);
+  if (st.closed) L.fail(`${label}은 이미 닫혔다.`);
+  const dir = L.workDir(main, st);
+  if (!fs.existsSync(dir)) L.fail(`orca-dispatch-task: ${label}의 워크트리가 없다(${dir}). 'status'로 확인한다.`);
+
+  const command = agentCommand(main, a.agent, String(a.model));
+  const created = orca(['terminal', 'create', '--worktree', `path:${dir}`, '--title', label, '--command', command]);
+  const handle = created && created.terminal && created.terminal.handle;
+  if (!handle) L.fail(`orca-dispatch-task: ${label} 탭을 열었지만 Orca가 탭 handle을 돌려주지 않았다. 'orca terminal list'로 확인한다.`);
+
+  // 탭 handle을 메타에 기록한다 — 첫 지시문을 보내기 전이라 태스크 세션의 기록과 겹치지 않는다
+  const fresh = L.readState(main, num);
+  fresh.tab = handle;
+  L.writeState(main, fresh);
+  L.syncDoc(main, fresh);
+
+  const text = firstInstruction(fresh, a.note);
+  const manual = `탭 화면을 'orca terminal read --terminal ${handle}'로 확인하고, 준비되면 아래 첫 지시문을 'orca terminal send --terminal ${handle} --text "<첫 지시문>" --enter'로 보낸다.\n--- 첫 지시문 ---\n${text}`;
+  let waited;
+  try {
+    waited = orca(['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle']);
+  } catch (e) {
+    L.fail(`orca-dispatch-task: ${label} 탭(${handle})을 열었지만 준비를 기다리지 못해 첫 지시문을 보내지 않았다 — ${e.message}\n${manual}`);
+  }
+  if (waited && waited.wait && waited.wait.satisfied === false) {
+    const why = waited.wait.reason || waited.wait.status || '준비 대기 미충족';
+    L.fail(`orca-dispatch-task: ${label} 탭(${handle})을 열었지만 준비(tui-idle)가 되지 않아 첫 지시문을 보내지 않았다 — ${why}\n${manual}`);
+  }
+  const send = () => {
+    let r;
+    try {
+      r = sendPrompt(handle, text);
+    } catch (e) {
+      L.fail(`orca-dispatch-task: ${label} 탭(${handle})에 첫 지시문을 보내지 못했다 — ${e.message}\n${manual}`);
+    }
+    if (r.refused) L.fail(`orca-dispatch-task: ${label} 탭(${handle})이 첫 지시문을 받지 않았다 — ${r.refused}\n${manual}`);
+    return r.observed;
+  };
+  // 턴 시작이 관측되지 않으면 화면을 보고, 지시문이 보이지 않을 때만 한 번 더 보낸다(준비 전 입력이 사라진 경우)
+  let sendNote = null;
+  if (!send()) {
+    if (onScreen(handle, text.split('\n')[0].split(' ').slice(0, 4).join(' '))) {
+      sendNote = '턴 시작은 관측되지 않았지만 탭 화면에 첫 지시문이 보인다 — 탭에서 진행을 확인한다.';
+    } else if (send()) {
+      sendNote = '첫 전송은 턴 시작이 관측되지 않고 화면에도 없어 한 번 더 보냈다.';
+    } else {
+      L.fail(`orca-dispatch-task: ${label} 탭(${handle})에 첫 지시문을 두 번 보냈지만 턴 시작이 관측되지 않았다.\n${manual}`);
+    }
+  }
+  return [
+    `${label} 태스크 세션을 띄웠다 — 탭 ${handle}`,
+    `- 실행: ${command}`,
+    `- 폴더: ${dir}`,
+    `- 첫 지시문을 보냈다(시작: ${startSkill(fresh)}, 범위: ${fresh.range}).`,
+    ...(sendNote ? [`- 알림: ${sendNote}`] : []),
+    '다음: wait-reports를 백그라운드 셸로 걸어 둔다.',
+  ].join('\n');
+}
+
+async function reportTask(ctx, a) {
+  const main = ctx.main;
+  L.requireInstalled(main);
+  if (!a.task || !a.text || !oneLine(a.text)) L.fail('report-task: 태스크 번호와 보고 한 줄을 넣는다. 예: report-task TASK-012 "병합 완료"');
+  const line = `${L.clock(L.nowIso())} ${L.taskLabel(L.parseTaskNum(a.task))} ${oneLine(a.text)}`;
+  // 한 줄을 한 번의 append로 쓴다 — 여러 태스크 세션이 동시에 보고해도 줄이 섞이지 않는다
+  fs.appendFileSync(reportsFile(main), `${line}\n`);
+  return `보고를 남겼다: ${line}`;
+}
+
+function readPos(main) {
+  try {
+    return JSON.parse(fs.readFileSync(readPosFile(main), 'utf8')).offset || 0;
+  } catch (e) {
+    return 0;
+  }
+}
+
+// 읽은 위치 뒤의 완성된 줄들을 읽고 위치를 옮긴다. 파일이 줄었으면(지웠으면) 처음부터 읽는다
+function takeUnread(main) {
+  const file = reportsFile(main);
+  if (!fs.existsSync(file)) return [];
+  const buf = fs.readFileSync(file);
+  let pos = readPos(main);
+  if (pos > buf.length) pos = 0;
+  const end = buf.lastIndexOf(0x0a) + 1;
+  if (end <= pos) return [];
+  const lines = buf.slice(pos, end).toString('utf8').split('\n').filter((l) => l.trim());
+  L.writeJsonAtomic(readPosFile(main), { offset: end });
+  return lines;
+}
+
+// 오래 조용한 태스크 탭 — 열린 태스크 중 탭 기록이 있고 마지막 출력이 기다린 시간보다 오래된 것
+function quietTabs(main) {
+  const out = [];
+  for (const st of L.listStates(main)) {
+    if (st.closed || !st.tab) continue;
+    const label = L.taskLabel(st.num);
+    try {
+      const r = orca(['terminal', 'show', '--terminal', st.tab]);
+      const last = r && r.terminal && r.terminal.lastOutputAt;
+      if (last && Date.now() - last >= WAIT_MS) out.push(`- ${label} 탭 ${st.tab} — 마지막 출력 ${L.minutes(Date.now() - last)} 전`);
+    } catch (e) {
+      out.push(`- ${label} 탭 ${st.tab} — 탭을 읽지 못했다(${e.message.replace(/^orca terminal show 실패: /, '')})`);
+    }
+  }
+  return out;
+}
+
+async function waitReports(ctx) {
+  const main = ctx.main;
+  L.requireInstalled(main);
+  const until = Date.now() + WAIT_MS;
+  for (;;) {
+    const lines = takeUnread(main);
+    if (lines.length) return lines.join('\n');
+    if (Date.now() >= until) break;
+    await new Promise((r) => setTimeout(r, Math.min(POLL_MS, Math.max(0, until - Date.now()))));
+  }
+  const quiet = quietTabs(main);
+  return [`보고 없이 ${L.minutes(WAIT_MS)}이 지났다.`, `오래 조용한 탭: ${quiet.length ? '' : '없음'}`.trimEnd(), ...quiet].join('\n');
+}
+
+module.exports = { orcaDispatchTask, reportTask, waitReports, firstInstruction };