elanous 0.2.18 → 0.2.19

package/src/task-agent/shadow.ts

@@ -5,14 +5,18 @@
  * - 입력은 슈퍼바이저 결과에 «이미 실려 있는» 값만 쓴다(네트워크 호출 0): 종료 어휘 ·
  *   PR 번호/병합 여부(`prNumber`·`merged`). 리뷰 판정·must-fix 는 결과에 없으므로 비운다
  *   («통과»로 읽지 않는다 — 판단부가 review 수를 고른다).
- * - 실행부는 언제나 shadow 로 부른다: «했을 수»만 기록하고 명령은 하나도 돌리지 않는다.
- *   설정 `taskAgent.mode=live` 도 이 경로에는 먹지 않는다(실행은 `autopilot task-agent-action` 몫).
+ * - 슈퍼바이저의 기본 호출은 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 NextAction } from './actions.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;
@@ -27,23 +31,42 @@ export interface TaskAgentShadowMove {
   executorKind: TaskJudgement['executorKind'] | null;
   variant: TaskJudgement['executorVariant'] | null;
   reason: string;
-  /** 실행부 결과 — shadow 경로에서는 늘 'shadow'(실행부 밖의 수면 null). */
+  /** 실행부 결과 — 기본 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;
 }
 
-/** 슈퍼바이저 결과에서 판단부 입력을 만든다 — 추가 조회 없이 이미 실린 값만. */
-export function shadowJudgeInput(stopReason: SupervisorStopReason, results: readonly SupervisorJobResult[]): TaskJudgeInput {
+/** 파일 산출물로 전달(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 만 본다).
@@ -52,24 +75,117 @@ export function shadowJudgeInput(stopReason: SupervisorStopReason, results: read
   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 judgeInput = shadowJudgeInput(input.stopReason, input.results);
-  const judgement = judgeNextMove(judgeInput);
+  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: input.runId ?? 'run-unknown',
+      taskId: delivery ? card!.id : input.runId ?? 'run-unknown',
       rationale: judgement.reason,
-      pr: typeof judgeInput.pr === 'number' ? judgeInput.pr : 0,
+      pr: delivery ? 0 : typeof judgeInput.pr === 'number' ? judgeInput.pr : 0,
       runId: input.runId ?? '',
       original: [...new Set(input.results.map((result) => result.feature))].join(' · '),
-      checklistId: '',
+      checklistId: delivery ? card?.checklistId ?? '' : '',
+      ...(delivery ? { delivery } : {}),
     };
     executorResult = await executeNextAction(action, {
-      mode: 'shadow',
+      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; },
     });
@@ -83,8 +199,60 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
     reason: judgement.reason,
     executorResult,
     wouldDo,
-    pr: typeof judgeInput.pr === 'number' ? judgeInput.pr : null,
+    pr: delivery ? null : typeof judgeInput.pr === 'number' ? judgeInput.pr : null,
   };
-  (deps.log ?? ((category, event, data) => debug.log(category, event, data)))('task-agent', 'shadow-move', { ...move });
-  return move;
+  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

@@ -7,9 +7,12 @@
  * - 기본은 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, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+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';
@@ -18,14 +21,28 @@ 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];
 
-export interface TaskCardEvent { at: string; event: string; detail?: string }
+/** `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';
@@ -36,17 +53,48 @@ export interface TaskCard {
   /** 조각 카드만 — 소속 미션 카드 id · 먼저 착지해야 하는 조각 id(선후). */
   mission?: string;
   after?: string[];
-  /** 조각 카드만 — 착지 근거(② `tasks advance --pr|--goal`): 이 조각 런이 연 PR 번호 · 골 id(16자 · 런 원장 `pr-opened` 로 PR 을 찾는다). */
-  pr?: number;
+  /**
+   * 이 카드 런이 연 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');
 }
@@ -137,12 +185,22 @@ export function shellQuote(arg: string): string {
   return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
 }
 
-export type TaskLauncher = (args: string[]) => void | Promise<void>;
+/** 발사기에 넘기는 연결 — 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` 일 때만 불린다. */
@@ -179,12 +237,31 @@ export class TaskLaunchError extends Error {
   }
 }
 
-export interface HandTaskResult { card: TaskCard; move: TaskCardMove; mode: 'shadow' | 'live'; launched: boolean }
+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';
@@ -193,6 +270,10 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
     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: [],
@@ -210,17 +291,21 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
       if (!guard(current)) return undefined;
       owned.ok = true;
       // next 의 옛 근거는 버리고 디스크의 근거로 «교체»한다 — 정정된 근거 옆에 옛 근거가 되살아나지 않게.
-      const { pr: _stalePr, goalId: _staleGoal, ...base } = next;
-      return { ...base, ...(current?.pr !== undefined ? { pr: current.pr } : {}), ...(current?.goalId !== undefined ? { goalId: current.goalId } : {}) };
+      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 }); } catch { /* fail-soft */ }
-  if (mode === 'shadow') return { card, move, mode, launched: false };
+  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 {
-    await opts.launcher(move.command!);
+    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 }] };
@@ -228,8 +313,25 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
     try { debug.log('task-agent', 'launch-failed', { taskId: id, seat: card.seat ?? null, reason }); } catch { /* fail-soft */ }
     throw new TaskLaunchError(failed, reason);
   }
-  const launched: TaskCard = { ...card, status: 'launched', history: [{ at: (opts.now ?? (() => new Date()))().toISOString(), event: 'launch', detail: move.command!.join(' ') }] };
+  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 }); } catch { /* fail-soft */ }
-  return { card: launched, move, mode, launched: true };
+  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 } : {}) };
 }

package/src/task-orchestrator/surfaces/pod-command-job.ts

@@ -37,6 +37,54 @@ export const POD_LITE_IMAGE = 'elanous-harness-lite:local';
 export const POD_LITE_MEMORY_LIMIT = '2Gi';
 
 /** 요청은 한도를 넘을 수 없다(쿠버네티스가 Job 을 거부한다) — lite 2Gi 처럼 한도가 기본 요청보다 작으면 한도로 맞춘다. */
+/** The command Job container's CPU limit when the caller names none (GATE-SPEED A3①: unchanged default). */
+export const POD_COMMAND_CPU_LIMIT_DEFAULT = '4';
+
+/** Container CPU request/limit override. Omitted fields keep the defaults (request `POD_CHILD_REQUESTS.cpu` · limit 4). */
+export interface PodCpu { request?: string; limit?: string }
+
+/** Kubernetes CPU quantity → millicores (`1` · `0.5` · `500m`); null when it is not a positive quantity we accept. */
+export function podCpuMillis(value: string): number | null {
+  const m = /^(?:(\d+(?:\.\d{1,3})?)|(\d+)m)$/.exec(value.trim());
+  if (!m) return null;
+  const millis = m[1] !== undefined ? Math.round(Number(m[1]) * 1000) : Number(m[2]);
+  return Number.isSafeInteger(millis) && millis > 0 ? millis : null;
+}
+
+/** Resolve a CPU override against the defaults; throws when a value is malformed or the request exceeds the limit (k8s would refuse the Job). */
+export function resolvePodCpu(cpu: PodCpu | undefined): { request: string; limit: string } {
+  const request = cpu?.request?.trim() || POD_CHILD_REQUESTS.cpu;
+  const limit = cpu?.limit?.trim() || POD_COMMAND_CPU_LIMIT_DEFAULT;
+  const r = podCpuMillis(request), l = podCpuMillis(limit);
+  if (r === null) throw new Error(`pod cpu request is not a positive CPU quantity: ${request}`);
+  if (l === null) throw new Error(`pod cpu limit is not a positive CPU quantity: ${limit}`);
+  if (r > l) throw new Error(`pod cpu request ${request} exceeds limit ${limit}`);
+  return { request, limit };
+}
+
+/** Config value → CPU override (release gate `release.loop.gatePodCpu`). A scalar (`2` · `"1500m"`) sets request = limit;
+ *  `{ request, limit }` sets either side. Absent/empty = undefined (request 1 / limit 4). Malformed values throw. */
+export function parsePodCpu(value: unknown, label = 'cpu'): PodCpu | undefined {
+  const text = (v: unknown): string | undefined => {
+    if (v === undefined || v === null || v === '') return undefined;
+    if (typeof v !== 'number' && typeof v !== 'string') throw new Error(`${label} must be a CPU quantity or { request, limit }`);
+    return String(v).trim() || undefined;
+  };
+  let cpu: PodCpu;
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const { request, limit, ...rest } = value as Record<string, unknown>;
+    if (Object.keys(rest).length) throw new Error(`${label} has unknown keys: ${Object.keys(rest).join(', ')}`);
+    const r = text(request), l = text(limit);
+    cpu = { ...(r ? { request: r } : {}), ...(l ? { limit: l } : {}) };
+  } else {
+    const both = text(value);
+    cpu = both ? { request: both, limit: both } : {};
+  }
+  if (!cpu.request && !cpu.limit) return undefined;
+  resolvePodCpu(cpu);
+  return cpu;
+}
+
 export function memoryRequestWithin(limit: string | undefined): string {
   const gi = (value: string | undefined) => { const m = /^(\d+)Gi$/.exec(value ?? ''); return m ? Number(m[1]) : null; };
   const request = gi(POD_CHILD_REQUESTS.memory);
@@ -130,6 +178,8 @@ export interface PodCommandJobInput {
   bunCache?: string;
   /** 컨테이너 메모리 한도(기본 16Gi) — 게이트가 파일 하나 격리 Job 에 올린다. */
   memoryLimit?: string;
+  /** GATE-SPEED A3①: CPU request/limit override (release gate shards only). Omitted = request 1 / limit 4. */
+  cpu?: PodCpu;
   source?: PodSource;
   deadlineSeconds: number;
   runId?: string;
@@ -147,6 +197,7 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
   }
   const grok = o.llm === 'grok';
   const bunCache = o.bunCache ? podBunCacheVolume(o.bunCache) : undefined;
+  const cpu = resolvePodCpu(o.cpu);
   const quotedArgs = o.command.map(bashSingleQuote).join(' ');
   const credLines = [
     ...(grok ? ['mkdir -p ~/.grok && install -m 600 /creds/grok-auth.json ~/.grok/auth.json'] : []),
@@ -185,7 +236,7 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
           initContainers: [{ name: 'isolation-gate', image: o.image, imagePullPolicy: o.imagePullPolicy ?? 'Never', command: ['bash', '-c'], args: [GATE] }],
           containers: [{
             name: 'child', image: o.image, imagePullPolicy: o.imagePullPolicy ?? 'Never',
-            resources: { requests: { ...POD_CHILD_REQUESTS, memory: memoryRequestWithin(o.memoryLimit) }, limits: { memory: o.memoryLimit ?? '16Gi', cpu: '4' } },
+            resources: { requests: { ...POD_CHILD_REQUESTS, cpu: cpu.request, memory: memoryRequestWithin(o.memoryLimit) }, limits: { memory: o.memoryLimit ?? '16Gi', cpu: cpu.limit } },
             command: ['bash', '-c'], args: [script],
             env: [
               ...(o.runId ? [{ name: 'ELANOUS_RUN_ID', value: o.runId }] : []),
@@ -272,6 +323,8 @@ export interface RunPodCommandOptions {
   bunCache?: string;
   /** 컨테이너 메모리 한도(기본 16Gi · lite 면 2Gi). */
   memoryLimit?: string;
+  /** GATE-SPEED A3①: CPU request/limit override — only the release gate passes it. Omitted = request 1 / limit 4. */
+  cpu?: PodCpu;
   /** POD7: 호출부가 «네트워크 스킬만 쓰는 명령»이라고 말할 때만 lite 이미지 ⊕ 2Gi. */
   lite?: boolean;
   source?: PodSource;
@@ -284,6 +337,7 @@ export interface RunPodCommandOptions {
   name?: string;
   pollMs?: number;
   kubectl?: Kubectl;
+  /** A caller-owned scheduler is self-capped: acquires count only its own Jobs, never cluster occupancy (POOLGLOBAL-REG). */
   poolScheduler?: PodPoolScheduler;
   checkPool?: typeof checkPodPool;
   syncImages?: typeof syncPoolImages;
@@ -356,6 +410,8 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
   if (hostMirror && !isAbsolute(hostMirror)) throw new Error('pod.hostMirror must be an absolute directory path');
   const bunCache = options.bunCache?.trim() || undefined;
   if (bunCache && !isAbsolute(bunCache)) throw new Error('pod.bunCache must be an absolute directory path');
+  // Fail before any Secret/Job is applied — a bad quantity must not reach the cluster.
+  if (options.cpu) resolvePodCpu(options.cpu);
 
   let member: PodPoolMember | null = null;
   let pool = options.poolScheduler;
@@ -366,12 +422,16 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       const members = parsePodPool(spec);
       const checked = (options.checkPool ?? checkPodPool)(members, baseKubectl as PoolKubectl);
       if (!checked.ok) throw new Error('pod command: 풀의 노드가 하나도 준비되지 않았다');
-      pool = new PodPoolScheduler(checked.ready);
+      // Occupancy reads go through the same kubectl as the readiness check (an injected one included).
+      pool = new PodPoolScheduler(checked.ready, { kubectl: baseKubectl as PoolKubectl });
     }
   }
   if (pool) {
+    // POOLGLOBAL-REG: a caller that hands in its own scheduler (the release gate fans its shards over one) holds its own
+    // concurrency cap — its Jobs count against the spec caps, not the cluster's goal Pods (#24253 → 0.2.15 gate ran 1 shard).
+    const selfCapped = options.poolScheduler !== undefined;
     for (;;) {
-      member = await pool.tryAcquire();
+      member = await pool.tryAcquire(undefined, undefined, { selfCapped });
       if (member) break;
       await sleep(options.pollMs ?? 15_000);
     }
@@ -426,7 +486,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       name, namespace, launch, image: imageRef ?? image,
       ...(imageRef ? { imagePullPolicy: 'IfNotPresent' as const } : {}),
       repoUrl, command, skills, ...(llm ? { llm } : {}), ...(options.clone ? { clone: true } : {}),
-      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(memoryLimit ? { memoryLimit } : {}), deadlineSeconds,
+      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(memoryLimit ? { memoryLimit } : {}), ...(options.cpu ? { cpu: options.cpu } : {}), deadlineSeconds,
       ...(options.runId ? { runId: options.runId } : {}),
     });
     kubectl(['-n', namespace, 'delete', 'job', '-l', own, '--ignore-not-found']);