elanous 0.2.17 → 0.2.19

package/src/task-agent/shadow.ts

@@ -0,0 +1,258 @@
+/**
+ * TASK-AGENT-SHADOW — 슈퍼바이저가 런의 멈춤을 확정한 자리에서 판단부를 «그림자»로 부른다.
+ *
+ * RFC-task-agent-any-task-to-completion-2026-10-06 §A9 «판단부 호출부 0»을 메운다.
+ * - 입력은 슈퍼바이저 결과에 «이미 실려 있는» 값만 쓴다(네트워크 호출 0): 종료 어휘 ·
+ *   PR 번호/병합 여부(`prNumber`·`merged`). 리뷰 판정·must-fix 는 결과에 없으므로 비운다
+ *   («통과»로 읽지 않는다 — 판단부가 review 수를 고른다).
+ * - 슈퍼바이저의 기본 호출은 shadow: «했을 수»만 기록하고 명령·복사는 하나도 돌리지 않는다.
+ *   전달 과제의 명시적 live 호출만 파일을 복사한다. 설정 `taskAgent.mode=live` 는 기본 호출에 먹지 않는다.
+ * - 관측: `debug.log('task-agent', 'shadow-move', …)` → `elanous logs --category task-agent`.
+ */
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { extname, join, relative, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { readTaskAgentState, readTaskCard, taskAgentStatePath, type CompletionKind, type TaskCard } from './task-hand.js';
+import type { SupervisorJobResult, SupervisorStopReason } from '../self-dev/run-supervisor.js';
+import { executeNextAction, type DeliveryKind, type NextAction } from './actions.js';
+import { judgeNextMove, type TaskJudgeInput, type TaskJudgement } from './judge.js';
+import { configuredTaskAgentLiveMoves, executeLiveGreenProposal, executeLiveReview, type LiveMoveDeps, type LiveMoveResult, type TaskAgentLiveMove } from './live-moves.js';
+
+export interface TaskAgentShadowInput {
+  runId: string | null;
+  stopReason: SupervisorStopReason;
+  results: readonly SupervisorJobResult[];
+}
+
+export interface TaskAgentShadowMove {
+  runId: string | null;
+  stopReason: SupervisorStopReason;
+  move: TaskJudgement['move'];
+  executorKind: TaskJudgement['executorKind'] | null;
+  variant: TaskJudgement['executorVariant'] | null;
+  reason: string;
+  /** 실행부 결과 — 기본 shadow 경로에서는 'shadow'(실행부 밖의 수면 null). */
+  executorResult: string | null;
+  /** 실행부가 남긴 «했을 수» 문면. */
+  wouldDo: string | null;
+  pr: number | null;
+  /** TA-JUDGE-LIVE-SAFE — `taskAgent.liveMoves` 가 이 수를 실제로 했을 때만 실린다(없으면 종전 그대로 그림자). */
+  liveMove?: LiveMoveResult;
+}
+
+export interface TaskAgentShadowDeps {
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+  /** 시험용 — shadow 실행부가 명령을 부르면 여기로 온다(정상이면 0회). */
+  command?: (args: string[]) => Promise<{ status: number; stdout: string; stderr?: string }>;
+  readCard?: (taskId: string) => TaskCard | undefined;
+  /** Explicit live invocation only; supervisor's default hook always uses shadow. */
+  mode?: 'shadow' | 'live';
+  /** TA-JUDGE-LIVE-SAFE — 실제로 할 안전한 수(`review`·`propose-green`). 비면 설정 `taskAgent.liveMoves` 를 읽는다. */
+  liveMoves?: ReadonlySet<TaskAgentLiveMove>;
+  /** live 수의 부작용(리뷰 띄우기·PR 머리 조회·상태 파일) — 시험은 주입한다. */
+  live?: LiveMoveDeps;
+}
+
+/** 파일 산출물로 전달(elanous-out)하는 종결 종류 — 그 밖의 code-pr 밖 종류는 확인 증거를 판단부에서 기다린다. */
+const DELIVERY_KINDS: ReadonlySet<CompletionKind> = new Set<CompletionKind>(['research-report', 'artifact', 'content']);
+function isDeliveryKind(kind: CompletionKind | undefined): kind is DeliveryKind {
+  return kind !== undefined && DELIVERY_KINDS.has(kind);
+}
+
+/**
+ * 슈퍼바이저 결과에서 판단부 입력을 만든다 — 추가 조회 없이 이미 실린 값만.
+ * `completion` 은 카드의 종결 종류(§A4b③) — 있으면 판단부 입력에 싣는다(비면 종전 입력 그대로).
+ */
+export function shadowJudgeInput(stopReason: SupervisorStopReason, results: readonly SupervisorJobResult[], completion?: CompletionKind): TaskJudgeInput {
+  const withPr = results.filter((result) => typeof result.prNumber === 'number' && result.prNumber > 0);
+  const input: TaskJudgeInput = { stopReason };
+  if (completion !== undefined) input.completion = completion;
+  if (withPr.length > 0) {
+    input.pr = withPr[0]!.prNumber!;
+    // 병합 여부만 결과에 실린다 — 닫힘(CLOSED)은 여기서 모른다. 병합이 아니면 OPEN 으로 둔다(판단부는 MERGED 만 본다).
+    input.prState = withPr.every((result) => result.merged === true) ? 'MERGED' : 'OPEN';
+  }
+  return input;
+}
+
+export function selectDeliveryCandidates(worktreePath: string, kind: DeliveryKind): string[] {
+  const allowed = kind === 'research-report' ? new Set(['.md']) : new Set(['.md', '.html', '.pdf', '.png', '.pptx']);
+  try {
+    const root = realpathSync(worktreePath);
+    const gitMarker = join(root, '.git');
+    let gitPointer = '';
+    try { if (lstatSync(gitMarker).isFile()) gitPointer = readFileSync(gitMarker, 'utf8').trim(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    const gitDir = gitPointer.startsWith('gitdir: ') ? resolve(root, gitPointer.slice(8)) : gitMarker;
+    const commonPointer = join(gitDir, 'commondir');
+    const sharedDir = (() => { try { return resolve(gitDir, readFileSync(commonPointer, 'utf8').trim()); } catch { return gitDir; } })();
+    let index: Buffer;
+    try { index = readFileSync(join(gitDir, 'index')); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      index = Buffer.alloc(12);
+      index.write('DIRC');
+      index.writeUInt32BE(2, 4);
+    }
+    const tracked = new Set<string>();
+    if (index.toString('ascii', 0, 4) !== 'DIRC' || ![2, 3].includes(index.readUInt32BE(4))) return [];
+    let offset = 12;
+    const count = index.readUInt32BE(8);
+    for (let i = 0; i < count; i++) {
+      const start = offset;
+      const flags = index.readUInt16BE(start + 60);
+      offset = start + 62;
+      if (flags & 0x4000) offset += 2;
+      const end = index.indexOf(0, offset);
+      if (end < 0) return [];
+      tracked.add(index.toString('utf8', offset, end));
+      offset = start + Math.ceil((end + 1 - start) / 8) * 8;
+    }
+    const ignored = (() => {
+      try { return readFileSync(join(root, '.gitignore'), 'utf8').split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#')); }
+      catch { return [] as string[]; }
+    })();
+    const excluded = (() => {
+      try { return readFileSync(join(sharedDir, 'info', 'exclude'), 'utf8').split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#')); }
+      catch { return [] as string[]; }
+    })();
+    const isIgnored = (name: string): boolean => [...ignored, ...excluded].some(pattern => {
+      const rule = pattern.replace(/^\//, '').replace(/\/$/, '');
+      if (rule.includes('*')) return new RegExp(`^${rule.split('*').map(part => part.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')).join('.*')}$`).test(name);
+      return name === rule || name.startsWith(rule + '/') || name.split('/').includes(rule);
+    });
+    const candidates: string[] = [];
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === 'node_modules') continue;
+        const file = join(dir, entry.name);
+        const name = relative(root, file);
+        if (isIgnored(name)) continue;
+        if (entry.isDirectory()) { walk(file); continue; }
+        if (!entry.isFile()) continue;
+        if (allowed.has(extname(name).toLowerCase()) && !tracked.has(name) && lstatSync(file).isFile() && realpathSync(file) === file) candidates.push(name);
+      }
+    };
+    walk(root);
+    return candidates.sort();
+  } catch { return []; }
+}
+
+/** shadow-move 관측의 종결 종류 — 읽은 카드만 «비면 code-pr» 로 풀고, 조회 실패는 'unmeasured', 카드를 안 봤으면 null. */
+function shadowCompletion(card: TaskCard | undefined, lookupFailed: boolean): CompletionKind | 'unmeasured' | null {
+  if (card) return card.completion ?? 'code-pr';
+  return lookupFailed ? 'unmeasured' : null;
+}
+
+export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, deps: TaskAgentShadowDeps = {}): Promise<TaskAgentShadowMove> {
+  const successful = input.results.find(result => result.ok === true && result.worktreePath);
+  let card: TaskCard | undefined;
+  let cardLookupFailed = false;
+  try {
+    card = successful ? (deps.readCard ?? readTaskCard)(successful.taskId) : undefined;
+    if (!card && successful && !deps.readCard) {
+      const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(taskAgentStatePath()).tasks ?? {};
+      const matches = Object.values(tasks).filter(candidate => candidate.status === 'launched' && candidate.text === successful.feature);
+      if (matches.length === 1) card = matches[0];
+    }
+  } catch {
+    // Card lookup is optional; preserve the original PR judgement when unavailable — but mark the completion kind as unmeasured.
+    cardLookupFailed = true;
+  }
+  const kind = card?.completion;
+  const judgeInput = shadowJudgeInput(input.stopReason, input.results, kind);
+  const delivery = successful?.worktreePath && card?.project?.target && isDeliveryKind(kind)
+    ? { kind, worktreePath: successful.worktreePath, projectTarget: card.project.target, files: selectDeliveryCandidates(successful.worktreePath, kind) }
+    : undefined;
+  const judgement: TaskJudgement = delivery
+    ? delivery.files.length
+      ? { move: 'wait', stage: 'observing', reason: '전달 후보 확인 — 산출물 판독 대기', executorKind: 'deliver' }
+      : { move: 'wait', stage: 'waiting', reason: '전달 후보 없음' }
+    : judgeNextMove(judgeInput);
+  if (cardLookupFailed) judgement.reason = `${judgement.reason} · 종결 종류 미확인(카드 조회 실패)`;
+  let executorResult: string | null = null;
+  let wouldDo: string | null = null;
+  if (judgement.executorKind) {
+    const action: NextAction = {
+      kind: judgement.executorKind,
+      ...(judgement.executorVariant ? { variant: judgement.executorVariant } : {}),
+      taskId: delivery ? card!.id : input.runId ?? 'run-unknown',
+      rationale: judgement.reason,
+      pr: delivery ? 0 : typeof judgeInput.pr === 'number' ? judgeInput.pr : 0,
+      runId: input.runId ?? '',
+      original: [...new Set(input.results.map((result) => result.feature))].join(' · '),
+      checklistId: delivery ? card?.checklistId ?? '' : '',
+      ...(delivery ? { delivery } : {}),
+    };
+    executorResult = await executeNextAction(action, {
+      mode: delivery ? (deps.mode ?? 'shadow') : 'shadow',
+      command: deps.command ?? (async () => { throw new Error('task-agent shadow path must not run commands'); }),
+      observe: (_event, data) => { wouldDo = data.reason; },
+    });
+  }
+  const move: TaskAgentShadowMove = {
+    runId: input.runId,
+    stopReason: input.stopReason,
+    move: judgement.move,
+    executorKind: judgement.executorKind ?? null,
+    variant: judgement.executorVariant ?? null,
+    reason: judgement.reason,
+    executorResult,
+    wouldDo,
+    pr: delivery ? null : typeof judgeInput.pr === 'number' ? judgeInput.pr : null,
+  };
+  if (delivery && deps.mode !== 'live') {
+    move.wouldDo = `${move.wouldDo ?? 'would wait'} → ${join(delivery.projectTarget, 'elanous-out', card!.id)} (${delivery.files.join(', ')})`;
+  }
+  if (delivery && deps.mode === 'live') {
+    move.move = executorResult === 'done' ? 'propose-green' : 'wait';
+    move.reason = wouldDo ?? judgement.reason;
+    move.wouldDo = null;
+  }
+  const liveKind: TaskAgentLiveMove | null = move.move === 'review' || move.move === 'propose-green' ? move.move : null;
+  // 판단마다 해석한다 — 안전하지 않은 수를 판단할 때도 모르는 항목 경고가 남게(실행은 아래 두 수뿐).
+  const liveMoves = deps.liveMoves ?? await configuredTaskAgentLiveMoves();
+  const live = liveKind !== null && liveMoves.has(liveKind);
+  // 카드 id 는 모든 판단 관측에 싣는다(그림자 일치율을 카드로 잇는다) — 읽기 전용 조회.
+  // live 수는 «근거 결과»에 묶는다 — PR 수는 그 PR 을 낸 결과의 카드·작업 트리, 전달은 전달한 카드(다중 결과에서 남의 카드에 쓰지 않게).
+  const prResult = typeof judgeInput.pr === 'number' ? input.results.find((result) => result.prNumber === judgeInput.pr) : undefined;
+  const boundCard = delivery
+    ? card
+    : prResult
+      ? (card && successful?.taskId === prResult.taskId ? card : liveCardFor([prResult], deps))
+      : undefined;
+  // PR 에 묶인 수는 그 PR 의 카드만 관측에 싣는다(못 찾으면 null — 다른 결과의 카드로 대체하지 않는다).
+  const liveCard = prResult || delivery ? boundCard : card ?? (cardLookupFailed ? undefined : liveCardFor(input.results, deps));
+  let liveMove: LiveMoveResult | undefined;
+  if (live) {
+    if (liveKind === 'review') {
+      liveMove = await executeLiveReview(boundCard, prResult?.prNumber,
+        { runId: input.runId, stopReason: input.stopReason, ...(prResult?.worktreePath ? { cwd: prResult.worktreePath } : {}) }, { ...(deps.log ? { log: deps.log } : {}), ...deps.live });
+    } else {
+      const evidence: Record<string, string> = {};
+      if (boundCard && !delivery && judgeInput.prState === 'MERGED' && prResult) evidence[boundCard.id] = `#${prResult.prNumber}`;
+      else if (boundCard && delivery && deps.mode === 'live' && executorResult === 'done') evidence[boundCard.id] = join(delivery.projectTarget, 'elanous-out', boundCard.id);
+      liveMove = executeLiveGreenProposal(boundCard, evidence, { ...(deps.log ? { log: deps.log } : {}), ...deps.live });
+    }
+  }
+  // 판단한 수마다 live/shadow 를 남긴다 — OP 가 «오판 건수»·«그림자 일치율»을 카드·수 종류로 잰다.
+  (deps.log ?? ((category, event, data) => debug.log(category, event, data)))('task-agent', 'shadow-move', {
+    ...move, completion: shadowCompletion(card, cardLookupFailed), card: liveCard?.id ?? null, live, liveExecuted: liveMove?.executed ?? false, ...(liveMove ? { liveOk: liveMove.ok } : {}),
+  });
+  return liveMove ? { ...move, liveMove } : move;
+}
+
+/** live 수의 카드 — 성공한 결과가 없어도(수확 가능 런은 ok 가 아닐 수 있다) 결과의 taskId · 유일한 발사 문장으로 찾는다. */
+function liveCardFor(results: readonly SupervisorJobResult[], deps: TaskAgentShadowDeps): TaskCard | undefined {
+  try {
+    for (const result of results) {
+      const found = deps.readCard ? deps.readCard(result.taskId) : readTaskCard(result.taskId, deps.live?.statePath);
+      if (found) return found;
+    }
+    if (deps.readCard) return undefined;
+    const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(deps.live?.statePath ?? taskAgentStatePath()).tasks ?? {};
+    const features = new Set(results.map((result) => result.feature));
+    const matches = Object.values(tasks).filter(candidate => candidate.status === 'launched' && features.has(candidate.text));
+    return matches.length === 1 ? matches[0] : undefined;
+  } catch { return undefined; }
+}

package/src/task-agent/task-hand.ts

@@ -0,0 +1,337 @@
+/**
+ * TASK-AGENT 과제 넘기기 문 — `elanous task hand "<한 줄>"` (RFC-task-agent-any-task-to-completion §A9 표 1행 · R3).
+ *
+ * - 과제 카드를 실행부와 «같은» 상태 파일(`effectiveInstanceRoot()/task-agent-actions.json`)의 `tasks` 칸에 적는다.
+ *   종전 칸(landingDay·landingsToday·failureCounts)은 그대로 두고 덧붙이기만 한다(하위 호환 — 실행부 쓰기는 `...disk` 로 보존).
+ * - 첫 수는 «launch» = `harness say [--seat <자리>] --substrate pod --merge-by-host "<원문>"`.
+ * - 기본은 SHADOW: 카드와 명령만 남기고 아무것도 띄우지 않는다. `--live` 일 때만 주입된 launcher 로 띄운다.
+ * - 관측: `debug.log('task-agent', 'handed', {taskId, seat, checklistId, mode})`.
+ */
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { resolveDaemonHarnessTarget } from '../intake-plane/harness-target.js';
+import { HARNESS_RUN_ID_ENV, mintRunId, normalizeRunId } from '../harness/harness-space.js';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { withFileLockSync } from '../storage/file-lock.js';
+
+export const TASK_SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+export type TaskSeat = typeof TASK_SEATS[number];
+/** 과제 카드 id 접두 — `task show <id>` 가 이 접두로 TOX 태스크와 갈린다. */
+export const TASK_CARD_PREFIX = 'ta-';
+/**
+ * 과제 종결 종류(RFC-loop-agent-map §A4b③) — 비면 code-pr(PR 병합)로 읽는다.
+ * code-pr 밖의 종류는 «확인 증거»(`judge.ts` TaskJudgeInput.evidence)로 종결한다 — 증거를 만드는 일은 DEFAULT-HANDS 몫.
+ */
+export const COMPLETION_KINDS = ['code-pr', 'artifact', 'research-report', 'ops-action', 'content', 'watch-brief', 'decision-support'] as const;
+export type CompletionKind = typeof COMPLETION_KINDS[number];
+
+/** `run-bound`·`goal-bound`·`pr-bound` 은 runId(⊕ pr)를 싣는다 — 옛 카드의 칸은 at·event·detail 뿐이다. */
+export interface TaskCardEvent { at: string; event: string; detail?: string; runId?: string; pr?: number }
+export interface TaskCardMove { kind: 'launch' | 'wait'; command?: string[]; reason: string }
+export interface TaskCard {
+  id: string;
+  text: string;
+  seat?: TaskSeat;
+  checklistId?: string;
+  /** 종결 종류 — 비면 code-pr. */
+  completion?: CompletionKind;
+  /** 과제 대상 프로젝트(§A4b②) — target 은 절대 경로(git 이 아닐 수 있다). id 는 `task hand --project` 가 싣는다(옛 카드엔 없을 수 있다). */
+  project?: { id?: string; target: string };
+  /** 보드(§A4b① `board.ts`) 소속 — 목표 id · 이정표 id(`task hand --goal/--milestone`). 조각 카드의 `goalId`(골 sha 16자)와 다른 칸이다. */
+  goal?: string;
+  milestone?: string;
+  createdAt: string;
+  /** launch-failed = 발사기가 띄우기에 실패했다(사유는 history 마지막 칸) — 다음 수는 다시 발사. */
+  status: 'handed' | 'launched' | 'launch-failed';
+  history: TaskCardEvent[];
+  /** 미션 카드만 — 조각 카드 id(순서대로) · 쪼갠 출처(`mission.ts` splitMission). */
+  pieces?: string[];
+  splitSource?: string;
+  /** 조각 카드만 — 소속 미션 카드 id · 먼저 착지해야 하는 조각 id(선후). */
+  mission?: string;
+  after?: string[];
+  /**
+   * 이 카드 런이 연 PR · 골 id(16자). 두 출처가 한 칸을 쓴다(UX LOOP-INTERACT 계약 — card.runId → goalId):
+   * - 수동(② `tasks advance --pr|--goal` · 미션 조각만) — PR 은 번호(number) · `refSource: 'manual'`.
+   * - 런 원장 묶기(TA-CARD-RUN-LINK `card-evidence.ts`) — PR 은 `{number, url}` · 비어 있을 때만 «한 번» 채운다 · 수동 근거를 덮지 않는다.
+   * 번호는 `cardPrNumber` 로 읽는다(옛 카드의 number 도 그대로 읽힌다).
+   */
+  pr?: number | TaskCardPr;
+  goalId?: string;
+  /** `manual` = pr/goalId 를 사람이 적었다(`recordPieceRef`) — 런 묶기가 건드리지 않는다. */
+  refSource?: 'manual';
+  /** 조각 카드만 — ② 가 선행 착지 뒤 넘겼다(한 번만 · 같은 잠금 안에서 먼저 적는다). */
+  handed?: { at: string; mode: 'shadow' | 'live'; claim?: string; error?: string };
+  /**
+   * TA-CARD-RUN-LINK — `--live` 발사가 발사기에 넘긴 런 id(`ELANOUS_RUN_ID` 상속 → 하니스 런이 그 id 로 돈다) ⊕ 발사 토큰.
+   * 발사기가 그 id 를 «받았다»고 돌려줄 때만 적는다(한 번만). 원장이 아직 없으면 그 런은 시작 전이거나 대기열로 갔다.
+   */
+  runId?: string;
+  launchId?: string;
+  /** Pod 런이면 PR 을 연 자식 런 id(런 묶기가 PR 과 함께 적는다). */
+  runChildId?: string;
+  /** 미션 카드만 — 모든 조각 착지 → 칸 green «제안»(체크리스트는 손대지 않는다 · OP/주인이 뒤집는다). */
+  greenProposal?: { at: string; checklistId: string | null; evidence: Record<string, string> };
+  /** TA-JUDGE-LIVE-SAFE — live `review` 수가 리뷰를 요청한 PR 머리들(머리마다 한 번 · 띄우기 실패면 error · 이력은 지우지 않는다). */
+  reviewRequests?: Array<{ pr: number; head: string; at: string; error?: string }>;
+}
+
+/** 런 원장에서 묶은 PR — url 은 원장(pr-opened · Pod job-finished)에 있을 때만(지어내지 않는다). */
+export interface TaskCardPr { number: number; url?: string }
+
+/** 카드의 PR 번호 — 수동(number)·묶음(`{number,url}`) 둘 다. */
+export function cardPrNumber(card: Pick<TaskCard, 'pr'>): number | undefined {
+  return typeof card.pr === 'number' ? card.pr : card.pr?.number;
+}
+
+interface TaskAgentStateFile { tasks?: Record<string, TaskCard>; [key: string]: unknown }
+
+function isGitWorkTree(path: string): boolean {
+  try {
+    return execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: path, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === 'true';
+  } catch { return false; }
+}
+
+export function taskAgentStatePath(): string {
+  return join(effectiveInstanceRoot(), 'task-agent-actions.json');
+}
+
+/** 상태 파일을 읽을 수 없거나(ENOENT 제외) 해석할 수 없다 — 덮어쓰기 전에 멈춘다. */
+export class TaskAgentStateError extends Error {
+  constructor(path: string, cause: unknown) {
+    super(`task-agent 상태 파일을 읽을 수 없다 — 덮어쓰지 않고 멈춘다: ${path} (${cause instanceof Error ? cause.message : String(cause)})`);
+    this.name = 'TaskAgentStateError';
+  }
+}
+
+/**
+ * 실행부·과제 넘기기 문이 함께 쓰는 상태 파일(`task-agent-actions.json`)의 엄격한 읽기.
+ * 파일이 «없음»(ENOENT)만 빈 상태다. 그 밖의 읽기·해석 오류(손상된 JSON · 객체 아님 · 권한)는
+ * 던진다 — 빈 상태로 읽고 다시 쓰면 failureCounts·착지 기록·과제 카드가 지워진다.
+ */
+export function readTaskAgentState<T extends object = TaskAgentStateFile>(path: string): T {
+  let raw: string;
+  try { raw = readFileSync(path, 'utf8'); } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return {} as T;
+    return stateError(path, error);
+  }
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch (error) { return stateError(path, error); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return stateError(path, new Error('최상위가 객체가 아니다'));
+  return parsed as T;
+}
+
+function stateError(path: string, cause: unknown): never {
+  const error = new TaskAgentStateError(path, cause);
+  try { debug.log('task-agent', 'state-unreadable', { path, reason: error.message }); } catch { /* fail-soft */ }
+  throw error;
+}
+
+function readState(path: string): TaskAgentStateFile {
+  return readTaskAgentState<TaskAgentStateFile>(path);
+}
+
+/** 카드 여럿을 한 잠금 안에서 적는다(미션 ⊕ 조각) — 종전 칸은 `...disk` 로 보존. */
+export function writeTaskCards(path: string, cards: readonly TaskCard[]): void {
+  withFileLockSync(`${path}.lock`, () => {
+    const disk = readState(path);
+    mkdirSync(dirname(path), { recursive: true });
+    const tasks = { ...(disk.tasks ?? {}) };
+    for (const card of cards) tasks[card.id] = card;
+    writeFileSync(path, JSON.stringify({ ...disk, tasks }));
+  });
+}
+
+/** 카드 하나를 잠금 안에서 읽고 고쳐 쓴다 — `update` 가 undefined 를 돌려주면 쓰지 않는다. 쓴(또는 그대로인) 카드를 돌려준다. */
+export function updateTaskCard(path: string, id: string, update: (card: TaskCard | undefined, tasks: Readonly<Record<string, TaskCard>>) => TaskCard | undefined): TaskCard | undefined {
+  return withFileLockSync(`${path}.lock`, () => {
+    const disk = readState(path);
+    const current = disk.tasks?.[id];
+    const next = update(current, disk.tasks ?? {});
+    if (!next) return current;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ ...disk, tasks: { ...(disk.tasks ?? {}), [id]: next } }));
+    return next;
+  });
+}
+
+export function readTaskCard(id: string, path = taskAgentStatePath()): TaskCard | undefined {
+  return readState(path).tasks?.[id];
+}
+
+/** 첫 수의 elanous 인자(진입점·--config-dir 앞붙임은 launcher 몫). */
+export function launchArgs(card: Pick<TaskCard, 'text' | 'seat'>): string[] {
+  return ['harness', 'say', ...(card.seat ? ['--seat', card.seat] : []), '--substrate', 'pod', '--merge-by-host', card.text];
+}
+
+/**
+ * `landed` = 착지한 조각 id(② 감지가 채운다). 안 주면 «모른다» — 선행은 미착지로 보고(fail-closed)
+ * 이유에 «착지 미확인»을 단다(착지했다/안 했다를 단정하지 않는다).
+ * 미션 카드는 스스로 발사하지 않는다 · 아직 안 뜬 조각의 선행이 덜 착지했으면 `wait after <id>`.
+ */
+export function nextMoveFor(card: TaskCard, landed?: ReadonlySet<string>): TaskCardMove {
+  if (card.pieces) return { kind: 'wait', reason: `미션 — 조각 ${card.pieces.length}장이 선후대로 발사된다` };
+  const unmet = (card.after ?? []).filter((id) => !landed?.has(id));
+  if (card.status !== 'launched' && unmet.length > 0) return { kind: 'wait', reason: `after ${unmet.join(', ')}${landed ? '' : ' · 착지 미확인'}` };
+  if (card.status === 'handed') return { kind: 'launch', command: launchArgs(card), reason: '넘겨받은 과제 — 첫 발사' };
+  if (card.status === 'launch-failed') return { kind: 'launch', command: launchArgs(card), reason: '직전 발사 실패 — 다시 발사' };
+  return { kind: 'wait', reason: '발사됨 — 런 멈춤을 슈퍼바이저 그림자 판단(task-agent.shadow-move)이 받는다' };
+}
+
+export function shellQuote(arg: string): string {
+  return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+}
+
+/** 발사기에 넘기는 연결 — env(`ELANOUS_RUN_ID`)를 자식 환경에 얹으면 하니스 런이 `runId` 로 돈다(`resolveRunIdentity` 상속). launchId 는 카드에만 남는 발사 토큰이다. */
+export interface TaskLaunchContext { runId: string; launchId: string; env: Record<string, string> }
+/** 발사기가 «이 런 id 로 띄웠다»고 돌려주는 영수증 — 없으면 카드에 런 id 를 적지 않는다(추측하지 않는다). */
+export interface TaskLaunchReceipt { runId?: string }
+export type TaskLauncher = (args: string[], cwd?: string, context?: TaskLaunchContext) => void | TaskLaunchReceipt | Promise<void | TaskLaunchReceipt>;
+
+export interface HandTaskOptions {
+  text: string;
+  seat?: TaskSeat;
+  checklistId?: string;
+  completion?: TaskCard['completion'];
+  /** `--project <id> --target <dir>` — target 은 존재 확인 뒤 절대 경로로 바꿔 싣는다. */
+  project?: { id: string; target: string };
+  /** 보드 소속 목표·이정표 id — 카드에 그대로 싣는다. */
+  goal?: string;
+  milestone?: string;
+  live?: boolean;
+  statePath?: string;
+  /** `--live` 일 때만 불린다. */
+  launcher?: TaskLauncher;
+  now?: () => Date;
+  id?: string;
+  /** 미션 조각으로 넘길 때 — 카드에 소속 미션·선후를 싣는다. */
+  mission?: string;
+  after?: string[];
+  /** 착지한 조각 id — `after` 가 모두 여기 있어야 발사한다(② 의 자리). */
+  landed?: ReadonlySet<string>;
+  /** 카드에 그대로 싣는 칸(② 의 넘김 표지·착지 근거) — handTask 가 카드를 새로 적을 때 지워지지 않게. */
+  cardFields?: Pick<TaskCard, 'pr' | 'goalId' | 'handed'>;
+  /**
+   * 있으면 카드 쓰기마다 잠금 안에서 디스크 카드를 보고 참일 때만 쓴다(② 의 claim 소유 확인).
+   * 거짓이면 쓰지 않고 `TaskCardSupersededError` — 다른 넘김이 그 카드를 가져갔다(발사 전이면 발사하지 않는다).
+   */
+  writeGuard?: (current: TaskCard | undefined) => boolean;
+}
+
+/** `writeGuard` 가 거짓 — 다른 넘김이 카드를 가져갔다. 카드는 건드리지 않았다. */
+export class TaskCardSupersededError extends Error {
+  constructor(id: string) {
+    super(`과제 카드를 다른 넘김이 가져갔다 — 쓰지 않았다: ${id}`);
+    this.name = 'TaskCardSupersededError';
+  }
+}
+
+/** `--live` 발사가 실패했다 — 카드는 launch-failed 로 남았다. */
+export class TaskLaunchError extends Error {
+  constructor(card: TaskCard, reason: string) {
+    super(`발사 실패 (${card.id} → launch-failed): ${reason}`);
+    this.name = 'TaskLaunchError';
+  }
+}
+
+export interface HandTaskResult { card: TaskCard; move: TaskCardMove; mode: 'shadow' | 'live'; launched: boolean; cwd?: string }
+
+export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
+  const text = opts.text.trim();
+  if (!text) throw new Error('과제 한 줄이 비어 있다');
+  if (opts.seat !== undefined && !TASK_SEATS.includes(opts.seat)) throw new Error(`자리는 ${TASK_SEATS.join('|')} 중 하나다: ${opts.seat}`);
+  if (opts.completion !== undefined && !COMPLETION_KINDS.includes(opts.completion)) throw new Error(`종결 종류는 ${COMPLETION_KINDS.join('|')} 중 하나다: ${opts.completion}`);
+  for (const [flag, value] of [['--goal', opts.goal], ['--milestone', opts.milestone]] as const) {
+    if (value !== undefined && (!value.trim() || /\p{Cc}/u.test(value))) throw new Error(`${flag} id 가 비었거나 제어 문자를 담았다: ${JSON.stringify(value)}`);
+  }
+  let project: TaskCard['project'];
+  let targetIsGit: boolean | null = null;
+  if (opts.project) {
+    if (!opts.project.id.trim()) throw new Error('--project id 가 비어 있다');
+    const target = resolve(opts.project.target);
+    let isDir = false;
+    try { isDir = statSync(target).isDirectory(); } catch { /* 없음 */ }
+    if (!isDir) throw new Error(`대상 디렉터리가 없습니다: ${target}`);
+    targetIsGit = isGitWorkTree(target);
+    // 코드 종결(code-pr · 비면 code-pr)은 git 대상만 — 그 밖의 종결 종류는 git 이 아닌 폴더도 받는다(같은 판정을 harness-target 과 공유).
+    const codeCompletion = (opts.completion ?? 'code-pr') === 'code-pr';
+    const selection = resolveDaemonHarnessTarget({ configured: target, cwd: target, isGitRepo: () => targetIsGit === true, allowNonGit: !codeCompletion });
+    if (!selection.ok) throw new Error(`코드 종결은 git 대상이 필요 — --completion 을 고르거나 git init: ${target}`);
+    project = { id: opts.project.id, target: selection.repo };
+  }
+  const now = (opts.now ?? (() => new Date()))();
+  const id = opts.id ?? `${TASK_CARD_PREFIX}${now.toISOString().slice(0, 10).replaceAll('-', '')}-${randomBytes(3).toString('hex')}`;
+  const mode = opts.live ? 'live' : 'shadow';
+  const path = opts.statePath ?? taskAgentStatePath();
+  const card: TaskCard = {
+    id, text,
+    ...(opts.seat ? { seat: opts.seat } : {}),
+    ...(opts.checklistId ? { checklistId: opts.checklistId } : {}),
+    ...(opts.completion ? { completion: opts.completion } : {}),
+    ...(project ? { project } : {}),
+    ...(opts.goal ? { goal: opts.goal } : {}),
+    ...(opts.milestone ? { milestone: opts.milestone } : {}),
+    createdAt: now.toISOString(),
+    status: 'handed',
+    history: [],
+    ...(opts.mission ? { mission: opts.mission, after: [...(opts.after ?? [])] } : {}),
+    ...(opts.cardFields ?? {}),
+  };
+  const move = nextMoveFor(card, opts.landed);
+  if (move.kind !== 'launch') throw new Error(`발사할 수 없는 과제다 — ${move.reason}`);
+  const guard = opts.writeGuard;
+  const writeCard = (target: string, next: TaskCard): void => {
+    if (!guard) { writeTaskCards(target, [next]); return; }
+    const owned = { ok: false };
+    // 착지 근거(pr·goalId)는 `recordPieceRef` 소유 — claim 뒤에 적힌 최신 근거를 디스크에서 이어 받는다.
+    updateTaskCard(target, next.id, (current) => {
+      if (!guard(current)) return undefined;
+      owned.ok = true;
+      // next 의 옛 근거는 버리고 디스크의 근거로 «교체»한다 — 정정된 근거 옆에 옛 근거가 되살아나지 않게.
+      const { pr: _stalePr, goalId: _staleGoal, refSource: _staleSource, ...base } = next;
+      return { ...base, ...(current?.pr !== undefined ? { pr: current.pr } : {}), ...(current?.goalId !== undefined ? { goalId: current.goalId } : {}), ...(current?.refSource ? { refSource: current.refSource } : {}) };
+    });
+    if (!owned.ok) throw new TaskCardSupersededError(next.id);
+  };
+  writeCard(path, card);
+  try { debug.log('task-agent', 'handed', { taskId: id, seat: card.seat ?? null, checklistId: card.checklistId ?? null, mode, projectId: project?.id ?? null, targetIsGit }); } catch { /* fail-soft */ }
+  if (mode === 'shadow') return { card, move, mode, launched: false, ...(project ? { cwd: project.target } : {}) };
+  if (!opts.launcher) throw new Error('--live 인데 launcher 가 없다');
+  const runId = mintRunId();
+  const launchId = `tl-${randomBytes(6).toString('hex')}`;
+  const context: TaskLaunchContext = { runId, launchId, env: { [HARNESS_RUN_ID_ENV]: runId } };
+  let receipt: void | TaskLaunchReceipt;
+  try {
+    receipt = await opts.launcher(move.command!, project?.target, context);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const failed: TaskCard = { ...card, status: 'launch-failed', history: [{ at: (opts.now ?? (() => new Date()))().toISOString(), event: 'launch-failed', detail: reason }] };
+    writeCard(path, failed);
+    try { debug.log('task-agent', 'launch-failed', { taskId: id, seat: card.seat ?? null, reason }); } catch { /* fail-soft */ }
+    throw new TaskLaunchError(failed, reason);
+  }
+  const launchedAt = (opts.now ?? (() => new Date()))().toISOString();
+  const receivedRunId = receipt && typeof receipt.runId === 'string' ? receipt.runId.trim() : '';
+  // 넘긴 런 id 와 «같은» 영수증만 — 다른 id 면 env 로 넘긴 런과 카드가 어긋난다(묶지 않는다).
+  const boundRunId = receivedRunId && receivedRunId === runId && normalizeRunId(receivedRunId) === receivedRunId ? receivedRunId : undefined;
+  if (receivedRunId && !boundRunId) {
+    try { debug.log('task-agent', 'card-run-unbound', { card: id, launchId, expected: runId, received: receivedRunId }); } catch { /* fail-soft */ }
+  }
+  const launched: TaskCard = {
+    ...card, status: 'launched',
+    ...(boundRunId ? { runId: boundRunId, launchId } : {}),
+    history: [
+      { at: launchedAt, event: 'launch', detail: move.command!.join(' ') },
+      ...(boundRunId ? [{ at: launchedAt, event: 'run-bound', detail: boundRunId, runId: boundRunId }] : []),
+    ],
+  };
+  writeCard(path, launched);
+  try { debug.log('task-agent', 'launched', { taskId: id, seat: card.seat ?? null, runId: boundRunId ?? null }); } catch { /* fail-soft */ }
+  if (boundRunId) {
+    try { debug.log('task-agent', 'card-run-bound', { card: id, runId: boundRunId, launchId }); } catch { /* fail-soft */ }
+  }
+  return { card: launched, move, mode, launched: true, ...(project ? { cwd: project.target } : {}) };
+}