elanous 0.2.9 → 0.2.10

package/src/self-implement/orchestrator.ts

@@ -79,6 +79,7 @@ import { classifyReviewProviderFailure } from '../self-dev/review-provider-fallb
 import { classifyError } from '../session-runtime/retry-policy.js';
 import { decomposeSelfDevGoal, inferHotPaths, type SelfDevDecomposeOptions } from '../self-dev/decompose.js';
 import { boundaryGlobs, boundaryViolations } from './goal-boundary.js';
+import { askAtExecution, type ExecutionClarificationResult } from './execution-clarification.js';
 import { targetScopedGoalText } from './goal-text-path-scope.js';
 import type { SelfDevGoalType } from '../self-dev/orchestrate.js';
 import { DEFAULT_BRANCH_WORKTREE_BASE, gateGitResidue, observeGitResidue } from '../git-fs/worktree.js';
@@ -967,6 +968,8 @@ export interface SelfImplementSeams {
   /** 변경 파일 목록 — 게이트 «라우터»가 「코드가 바뀌었나」를 판정하는 입력.
    *  ⛔ 미지정이면 실물 `changedFiles(cwd)` 를 쓴다. 못 얻으면 `undefined` 이고, 라우터는 그때 «돌린다»(fail-safe). */
   changedFilesForGateRoute?: (cwd: string) => readonly string[] | undefined;
+  /** An execution choice is made only after a measured change crosses the authored target paths. */
+  askExecutionClarification?: typeof askAtExecution;
   /** ★ ⑤ 내부 리뷰 seam(2026-07-21·review-gated merge) — gate 통과 diff 를 리뷰어(reviewPullRequest·
    *  agent-substrate·staged 하니스와 동일 엔진)가 비평. verdict fail(mustFix) → rework 재주입(A 확장),
    *  clean(pass/warn) → 병합 결정. 미주입 시 리뷰 스킵(gate 통과=바로 결정·종전 동작). */
@@ -1082,7 +1085,7 @@ export const SELF_IMPLEMENT_PROGRESS_STAGES = [
   'gating', 'gated', 'reviewing', 'reviewed', 'awaiting-approval',
   'pr-opening', 'pr-opened', 'merging', 'merged', 'worktree-completed',
   'aborted', 'gate-failed', 'review-blocked', 'merge-conflict', 'pr-declined',
-  'awaiting-clarification',
+  'awaiting-clarification', 'parked',
   // ⭐⭐ 🩸 2026-09-12 — ***「선언한 대상을 «하나도» 안 만들고 끝났다」를 사람 표면에 낸다.***
   //    ⛔ 기존 단계 이름을 «빌려 쓰지 않는다» — `progress()` 는 단계 이름으로 원장 행을 만들므로
   //       빌려 쓰면 그 단계 집계가 오염된다([T] 2026-09-12 · `#17767` 이후 계약).
@@ -6268,6 +6271,39 @@ async function runSelfImplementInner(
       return { ok: false, stage: 'aborted', node: 'implement', ...resolveRunOutcome({ termination: 'abandoned' }), sessionId, worktreePath: wt.path, branch: wt.branch, quotaExhaustionAssessment: quotaExhaustionAssessmentForRun(), ...(impl.completionDisposition ? { completionDisposition: impl.completionDisposition } : {}), ...(pr ? { prUrl: pr.url, prNumber: pr.number } : {}), detail: impl.summary };
     }
 
+    // Measure the existing declared-target boundary after implementation, before gate/PR.
+    // Unknown declaration or changed files cannot justify an invented choice.
+    let gateRouteFiles: readonly string[] | undefined;
+    try { gateRouteFiles = (s.changedFilesForGateRoute ?? changedFiles)(wt.path); } catch { gateRouteFiles = undefined; }
+    if (opts.goalFile) {
+      let goalDocument: string | undefined;
+      try { goalDocument = readFileSync(opts.goalFile, 'utf8'); } catch { /* unknown scope */ }
+      const scope = detectDeclaredScopeDiff({ goalDocument, changedFiles: gateRouteFiles?.filter(file => !harnessSeededPaths.includes(file)), nameCap: gateRouteFiles?.length });
+      if (scope.status === 'known' && scope.outsideCount !== null && scope.outsideCount > 0) {
+        const result: ExecutionClarificationResult = await (s.askExecutionClarification ?? askAtExecution)({
+          id: 'execution_scope', decision: 'Changing files outside the authored target paths',
+          prompt: 'Implementation changed files outside the authored target paths. Keep the original scope or expand it?',
+          whyNow: 'Continuing to gate or publish these edits would expand the requested scope.',
+          impact: scope.outsideNames.some(file => {
+            if (existsSync(join(wt.path, file))) return false;
+            const tracked = runGitCommand(wt.path, ['ls-files', '--error-unmatch', '--', file], { encoding: 'utf8', timeout: 20_000 });
+            return tracked.status === 0;
+          }) ? 'critical' : 'high',
+          options: [
+            { label: 'Stay in scope', description: 'Do not accept out-of-scope changes.', recommended: true },
+            { label: 'Expand scope', description: 'Accept the changed files outside the target paths.' },
+          ],
+        }, { runId }, { writeRunLedger: s.writeRunLedger });
+        if ('parked' in result || 'deferred' in result || result.choice !== 'Expand scope') {
+          finalizeSupervisorDeliveries('execution-scope-not-approved');
+          observe('execution-scope-held', { outsideCount: scope.outsideCount, disposition: 'parked' in result ? 'parked' : 'in-scope-only' });
+          if ('parked' in result) progress('parked', `critical 질문 ${result.questionId} 미응답 — 이 런만 대기`);
+          return { ok: false, stage: 'parked' in result ? 'parked' : 'soft-stopped', node: 'implement', ...resolveRunOutcome({ termination: 'abandoned' }), sessionId, worktreePath: wt.path, branch: wt.branch,
+            detail: 'parked' in result ? `critical-unanswered: ${result.questionId}` : 'Out-of-scope edits held in the worktree; gate and publication skipped.' };
+        }
+      }
+    }
+
     // ⛔⭐ 이 템플릿이 `gate` 노드를 «안 가지면» 그 단계는 돌지 않는다.
     //   📌 research-loop 이 그렇다 — 문서만 바뀐 판에는 «변경 파일 범위» 게이트가 돌 시험이 없다.
     //   ⚠️ 꺼진 상태에서는 언제나 implement-loop 이라 참이다 ⇒ 오늘과 «같은» 걸음이다.
@@ -6275,8 +6311,6 @@ async function runSelfImplementInner(
     //     기본이 꺼짐이라 지금 폭발 반경은 0이고, 기본을 켜기 «전»에 이 구멍을 먼저 막아야 한다.
     // ⛔⭐ 라우터가 판정한다 — 값은 «코드»가 낸다(RFC §4.3 ⑵). 「모른다」는 «돌린다» 쪽이다.
     //   🚨 이 줄이 2026-09-08 승격의 구멍 ⓐ 를 닫는다: research 골이 «코드»를 만지면 시험이 돈다.
-    let gateRouteFiles: readonly string[] | undefined;
-    try { gateRouteFiles = (s.changedFilesForGateRoute ?? changedFiles)(wt.path); } catch { gateRouteFiles = undefined; }
     const gateRoute = routeGate(graphTemplate, gateRouteFiles);
     const runsGate = gateRoute.runsGate;
     progress('gating', !runsGate

package/src/self-implement/pipeline-shape.ts

@@ -13,7 +13,7 @@ export type PipelineNodeId =
 
 /** Each pipeline node's possible terminal stages. Nodes without a terminal exit use an empty array. */
 export const TERMINAL_STAGES_BY_NODE = {
-  implement: ['aborted', 'timed-out', 'soft-stopped'],
+  implement: ['aborted', 'timed-out', 'soft-stopped', 'parked'],
   gate: [],
   review: ['review-blocked'],
   rework: ['gate-failed', 'review-blocked'],

package/src/self-implement/run-status-mapping.ts

@@ -1,4 +1,4 @@
-export type RunStatus = 'completed' | 'failed' | 'cancelled';
+export type RunStatus = 'completed' | 'failed' | 'cancelled' | 'parked';
 /** ⭐ `crashed` — ***잡히지 않은 예외로 죽어 종결을 스스로 못 적은*** 런 (2026-08-11 · 🅣⊕🅢 어휘 합의).
  *  ⛔ `aborted`(스스로 중단을 «판정»했다)와 다른 값이다 — 이쪽은 «판정할 겨를이 없었다».
  *  📏 왜 생겼나: 실측 미완 57 중 ≈38 이 어느 원장에도 종결이 없었고, 멈춘 자리가 전부 「노드 안」이었다. */
@@ -20,7 +20,8 @@ export type SelfImplementStage =
   | 'aborted'
   | 'timed-out'
   | 'pr-declined'
-  | 'soft-stopped';
+  | 'soft-stopped'
+  | 'parked';
 
 const STAGE_OUTCOMES = {
   merged: { runStatus: 'completed' },
@@ -34,9 +35,10 @@ const STAGE_OUTCOMES = {
   'timed-out': { runStatus: 'failed', failureKind: 'timed-out' },
   'pr-declined': { runStatus: 'cancelled' },
   'soft-stopped': { runStatus: 'cancelled' },
+  parked: { runStatus: 'parked' },
 } satisfies Record<SelfImplementStage, MappedRunOutcome>;
 
-const RUN_STATUSES = new Set<RunStatus>(['completed', 'failed', 'cancelled']);
+const RUN_STATUSES = new Set<RunStatus>(['completed', 'failed', 'cancelled', 'parked']);
 
 /** Runtime guard for the run-status payload produced by observeRunOutcome. */
 export function isRunStatus(value: unknown): value is RunStatus {

package/src/session/chat.ts

@@ -109,6 +109,8 @@ export interface RunTurnOpts {
    *  delegated coding agent's approval prompts back to the originating
    *  chat via `delegate_code_agent`. */
   hitlConfirmChannel?: import('../hitl/confirm.js').ConfirmChannel;
+  /** Verified by the hosting bot from the inbound user id against its server-side owner allowlist. */
+  verifiedOwner?: { id: string };
   /** Paired multi-option question channel (Telegram sets this). Surface
    *  runTurnImpls thread it into `delegate_code_agent` so a delegated
    *  agent's structured questions render as option buttons in the

package/src/session/index.ts

@@ -202,6 +202,8 @@ export interface SessionMeta {
    *  아님). ~/.elanous 공유 스토어 세션은 전부 'prod'. append 는 이 값을 보존(생성자 귀속).
    *  구 세션엔 부재(tolerant read) — 미상 = 필터 비매치. */
   originInstance?: string;
+  /** Project association, omitted for sessions without an assigned project (including legacy records). */
+  projectId?: string;
   /** For telegram-sourced sessions; undefined for cli. */
   tgChatId?: number;
   tgThreadId?: number;
@@ -383,6 +385,7 @@ export interface CreateSessionOpts {
   tgBotId?: string;
   /** Stable identity for a persona's resident conversation. */
   personaId?: string;
+  projectId?: string;
   title?: string;
   /** 표면 origin(cli/pwa/tg/dc/harness) — source 유니온 밖의 세밀 라벨(PWA 챗 구분용). */
   origin?: string;
@@ -534,6 +537,7 @@ export function createSession(opts: CreateSessionOpts = {}, root: string = sessi
     tgThreadId: opts.tgThreadId,
     ...(opts.tgBotId ? { tgBotId: opts.tgBotId } : {}),
     ...(opts.personaId ? { personaId: opts.personaId } : {}),
+    ...(opts.projectId !== undefined ? { projectId: opts.projectId } : {}),
     tgSessionKey,
   };
   writeFileSync(sessionFile(id, root), '', 'utf-8');
@@ -575,6 +579,7 @@ export function adoptSession(id: string, opts: CreateSessionOpts = {}, root: str
     sourceKind: opts.sourceKind ?? defaultSessionSourceKind(source),
     ...(opts.forkedFromId ? { forkedFromId: opts.forkedFromId } : {}),
     ...(origin ? { origin } : {}),
+    ...(opts.projectId !== undefined ? { projectId: opts.projectId } : {}),
     originInstance: resolveInstanceName(),
     ...(opts.tgChatId != null ? { tgChatId: opts.tgChatId } : {}),
     ...(opts.tgThreadId != null ? { tgThreadId: opts.tgThreadId } : {}),
@@ -601,6 +606,7 @@ export function forkSessionFromHistory(
     tgThreadId: opts.tgThreadId,
     title: opts.title,
     origin: opts.origin,
+    projectId: opts.projectId,
   }, root);
   for (const msg of opts.messages) {
     const content = typeof msg.content === 'string' ? msg.content : '';
@@ -738,6 +744,8 @@ export interface ListSessionsOpts {
   tgThreadId?: number;
   /** 생성 인스턴스 정확 일치(prod · test:<repo> …). 구 세션(부재)은 비매치. */
   originInstance?: string;
+  /** Project id exact match; sessions without the field do not match. */
+  projectId?: string;
   /** 표면 origin 정확 일치(cli | pwa | tg | dc | harness). */
   origin?: string;
   /** 제외할 origin(들) — 예: ['harness'] 로 하니스 자식 세션을 사용자 대화 목록에서 숨김. */
@@ -774,6 +782,7 @@ export function listSessions(opts: ListSessionsOpts = {}, root: string = session
     idx = idx.filter(m => !m.sourceKind || !opts.excludeSourceKinds!.includes(m.sourceKind));
   }
   if (opts.originInstance) idx = idx.filter(m => m.originInstance === opts.originInstance);
+  if (opts.projectId !== undefined) idx = idx.filter(m => m.projectId === opts.projectId);
   if (opts.origin) idx = idx.filter(m => m.origin === opts.origin);
   if (opts.excludeOrigins && opts.excludeOrigins.length > 0) {
     idx = idx.filter((m) => {

package/src/shell-env-bootstrap.ts

@@ -210,6 +210,23 @@ export function capturedEnvAvailable(): boolean {
   return captured && cached !== null;
 }
 
+/** Append login-shell PATH entries to the target without replacing its existing environment. */
+export function mergeCapturedPath(target: NodeJS.ProcessEnv = process.env, opts: { capture?: boolean } = {}): number {
+  // capture: 아직 캡처 전이면 여기서 한 번 캡처한다(호출부가 getCapturedEnv 를 직접 부르지 않게 — identity-env 래칫).
+  const capturedPath = opts.capture || capturedEnvAvailable() ? getCapturedEnv().PATH : undefined;
+  const seen = new Set((target.PATH ?? '').split(':'));
+  const missing: string[] = [];
+  for (const entry of capturedPath?.split(':') ?? []) {
+    if (!entry || seen.has(entry)) continue;
+    missing.push(entry);
+    seen.add(entry);
+  }
+  if (missing.length) target.PATH = target.PATH ? `${target.PATH}:${missing.join(':')}` : missing.join(':');
+  const added = missing.length;
+  debug.log('shell.envbootstrap.capture', 'path-merged', { added });
+  return added;
+}
+
 /** Reset cache — test seam. */
 export function resetCapturedEnvForTesting(): void {
   cached = null;

package/src/steward/directive.ts

@@ -1,10 +1,15 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { getSecretAsync } from '../nexus/config/secrets/index.js';
 import { getUserConfig } from '../user-config.js';
 
 export type DirectiveSource = 'telegram' | 'pwa' | 'tui' | 'cli';
 export interface DirectiveIssue { id: string; identifier: string; title: string; description?: string | null }
+export interface DirectiveOrigin { chatId: number; botId?: string; threadId?: number }
 export interface DirectiveDeps {
+  root?: string;
   fetch?: typeof fetch;
   getSecret?: (id: string) => Promise<string | undefined>;
   team?: string;
@@ -31,8 +36,50 @@ async function graphql<T>(key: string, query: string, variables: Record<string,
   return payload.data;
 }
 
+function originPath(root: string, identifier: string): string {
+  if (!/^[a-zA-Z0-9_-]+$/.test(identifier)) throw new Error('Invalid directive identifier');
+  return join(root, 'steward', 'origins', `${identifier}.json`);
+}
+
+type TelegramOrigin = import('../autopilot/mission-origin.js').MissionOrigin & { channel: 'telegram'; chatId: number };
+
+function validOrigin(value: unknown): value is TelegramOrigin {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const origin = value as Record<string, unknown>;
+  return origin.channel === 'telegram' && Number.isSafeInteger(origin.chatId) &&
+    (origin.botId === undefined || typeof origin.botId === 'string' && /^\d+$/.test(origin.botId)) &&
+    (origin.threadId === undefined || Number.isSafeInteger(origin.threadId));
+}
+
+export function loadDirectiveOrigins(root: string, identifier: string): TelegramOrigin[] {
+  try {
+    const value: unknown = JSON.parse(readFileSync(originPath(root, identifier), 'utf8'));
+    const origins = Array.isArray(value) ? value : [value];
+    return origins.filter(validOrigin);
+  } catch { return []; }
+}
+
+export function saveDirectiveOrigin(root: string, identifier: string, origin: DirectiveOrigin): void {
+  if (!Number.isSafeInteger(origin.chatId) || origin.threadId !== undefined && !Number.isSafeInteger(origin.threadId)) throw new Error('Invalid directive origin');
+  const path = originPath(root, identifier);
+  const next: TelegramOrigin = { channel: 'telegram', chatId: origin.chatId,
+    ...(origin.botId && /^\d+$/.test(origin.botId) ? { botId: origin.botId } : {}),
+    ...(origin.threadId !== undefined ? { threadId: origin.threadId } : {}) };
+  const origins = loadDirectiveOrigins(root, identifier);
+  if (origins.some(item => JSON.stringify(item) === JSON.stringify(next))) return;
+  origins.push(next);
+  mkdirSync(join(root, 'steward', 'origins'), { recursive: true });
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temp, JSON.stringify(origins.length === 1 ? next : origins));
+  renameSync(temp, path);
+}
+
+export function loadDirectiveOrigin(root: string, identifier: string): TelegramOrigin | null {
+  return loadDirectiveOrigins(root, identifier)[0] ?? null;
+}
+
 /** The same entry point is used by the CLI and conversational surfaces. */
-export async function addDirective(text: string, options: { source?: DirectiveSource; dryRun?: boolean } = {}, deps: DirectiveDeps = {}): Promise<{ status: 'created' | 'repeated' | 'dry-run'; issue?: string; hash: string }> {
+export async function addDirective(text: string, options: { source?: DirectiveSource; dryRun?: boolean; origin?: DirectiveOrigin } = {}, deps: DirectiveDeps = {}): Promise<{ status: 'created' | 'repeated' | 'dry-run'; issue?: string; hash: string }> {
   const original = text.trim();
   if (!original) throw new Error('directive text is required');
   const source = options.source ?? 'cli';
@@ -74,6 +121,7 @@ export async function addDirective(text: string, options: { source?: DirectiveSo
       'mutation($input:CommentCreateInput!){commentCreate(input:$input){success}}',
       { input: { issueId: duplicate.id, body: `다시 말함 · ${source} · ${at}\n\n${original}` } });
     if (!result.commentCreate?.success) throw new Error('Linear comment creation failed');
+    if (source === 'telegram' && options.origin) saveDirectiveOrigin(deps.root ?? effectiveInstanceRoot(), duplicate.identifier, options.origin);
     return { status: 'repeated', issue: duplicate.identifier, hash };
   }
   const labels = await request<{ issueLabels: { nodes: Array<{ id: string; name: string }> } }>(
@@ -90,6 +138,7 @@ export async function addDirective(text: string, options: { source?: DirectiveSo
     'mutation($input:IssueCreateInput!){issueCreate(input:$input){success issue{id identifier title}}}',
     { input: { teamId, title: original.slice(0, 240), description: `${original}\n\n출처: ${source}\n시각: ${at}\n[directive-hash:${hash}]`, labelIds: [labelId], priority: 0 } });
   if (!created.issueCreate?.success || !created.issueCreate.issue?.identifier) throw new Error('Linear issue creation failed');
+  if (source === 'telegram' && options.origin) saveDirectiveOrigin(deps.root ?? effectiveInstanceRoot(), created.issueCreate.issue.identifier, options.origin);
   return { status: 'created', issue: created.issueCreate.issue.identifier, hash };
 }
 

package/src/steward/launch.ts

@@ -0,0 +1,250 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { redactSecrets } from '../task-cards/card-store.js';
+import type { ScheduledDecision, StewardSettings, TriageIssue } from './triage.js';
+
+/** `completed` = the run finished without a merge (a non-code artifact, or nothing to deliver) — never reported as a failure. */
+export type LaunchStatus = 'shadow' | 'launched' | 'skipped-budget' | 'failed' | 'running' | 'merged' | 'completed';
+export interface LaunchEntry {
+  issue: string;
+  title: string;
+  source: string;
+  command: string;
+  status: LaunchStatus;
+  runId?: string;
+  pid?: number;
+  log?: string;
+  reason?: string;
+  prNumber?: number;
+  prUrl?: string;
+  reported?: boolean;
+  notified?: 'sent' | 'shadow' | 'skipped-no-origin' | 'failed';
+  notifyAttempts?: number;
+  notifyRecipients?: Record<string, { notified: 'sent' | 'failed'; attempts: number }>;
+  notifyPreview?: { hasChatId: boolean; kind: 'file' | 'link' };
+  artifactRef?: string;
+  artifactBranch?: string;
+  artifactWorktree?: string;
+  awaitingMerge?: boolean;
+}
+export interface HitlEntry { issue: string; reason: string; raised: boolean; attempted?: boolean }
+export interface LaunchLedger { launches: Record<string, LaunchEntry>; hitl: Record<string, HitlEntry> }
+export interface LaunchItem { issue: TriageIssue; row: ScheduledDecision; command: string; source: string }
+export interface LaunchPlan { launches: LaunchItem[]; hitl: Array<{ issue: TriageIssue; row: ScheduledDecision }> }
+export interface LaunchDeps {
+  root: string;
+  settings: StewardSettings;
+  ledger: LaunchLedger;
+  /** Injected command boundary; the production adapter runs only argv, never a shell. */
+  command?: (args: string[]) => { exitCode: number; stdout: string; stderr?: string };
+  spawn?: (args: string[], log: string) => { pid: number };
+}
+
+const RUN_ID = /\brun-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const DEFAULT_POOL = 'pool-node-b@node-b:8';
+// `harness budget --json` outcomes: proceed | next-provider | wait-reset | stop. next-provider still runs (the harness switches provider itself).
+const BUDGET_PROCEED: readonly string[] = ['proceed', 'next-provider'];
+const cli = (args: string[]) => ['bun', 'bin/elanous.mjs', ...(process.env.NODE_ENV === 'test' ? ['--test'] : []), ...args];
+const sourceOf = (issue: TriageIssue): string => /^출처: (telegram|pwa|tui|cli)$/m.exec(issue.body)?.[1] ?? `linear:${issue.identifier}`;
+const promptOf = (issue: TriageIssue): string => `${issue.title}\n${issue.body.slice(0, 1500)}`;
+const argvFor = (issue: TriageIssue, settings: StewardSettings): string[] =>
+  // Options first, then `--`: an issue title that starts with `-` must stay part of the sentence.
+  cli(['harness', 'say', '--substrate', 'pod', '--pod-pool', settings.podPool ?? DEFAULT_POOL, '--base', 'main', '--json', '--', promptOf(issue)]);
+
+export function readLaunchLedger(root: string): LaunchLedger {
+  try {
+    const value = JSON.parse(readFileSync(join(root, 'steward', 'launches.json'), 'utf8')) as LaunchLedger;
+    if (!value || typeof value.launches !== 'object' || !value.launches || typeof value.hitl !== 'object' || !value.hitl) throw new Error('Invalid steward launch ledger');
+    return value;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { launches: {}, hitl: {} };
+    throw error;
+  }
+}
+
+export function saveLaunchLedger(root: string, ledger: LaunchLedger): void {
+  const dir = join(root, 'steward');
+  mkdirSync(dir, { recursive: true });
+  const target = join(dir, 'launches.json');
+  const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temp, JSON.stringify(ledger));
+  renameSync(temp, target);
+}
+
+export function planLaunches(rows: ScheduledDecision[], issues: TriageIssue[], ledger: LaunchLedger, settings: StewardSettings): LaunchPlan {
+  const byId = new Map(issues.map(issue => [issue.identifier, issue]));
+  const activeCount = Object.values(ledger.launches).filter(entry => !entry.awaitingMerge && (entry.status === 'launched' || entry.status === 'running')).length;
+  const available = Math.max(0, (settings.maxParallel ?? 3) - activeCount);
+  const launches: LaunchItem[] = [];
+  const hitl: LaunchPlan['hitl'] = [];
+  for (const row of rows) {
+    const issue = byId.get(row.issue);
+    if (!issue) continue;
+    if (row.rung === 'hitl' || row.hitlReason || row.disposition === 'hitl') {
+      if (settings.launch !== 'off' && (!ledger.hitl[row.issue] || settings.launch === 'live' && !ledger.hitl[row.issue].attempted)) hitl.push({ issue, row });
+      continue;
+    }
+    if ((settings.launch ?? 'shadow') === 'off' || row.disposition !== 'now' || row.rung !== 4 || (ledger.launches[row.issue] && ledger.launches[row.issue].status !== 'skipped-budget' && !(settings.launch === 'live' && ledger.launches[row.issue].status === 'shadow')) || launches.length >= available) continue;
+    const args = argvFor(issue, settings);
+    launches.push({ issue, row, source: sourceOf(issue), command: args.map(arg => JSON.stringify(arg)).join(' ') });
+  }
+  debug.log('steward.launch', 'planned', { count: launches.length, hitl: hitl.length, available });
+  return { launches, hitl };
+}
+
+function runCommand(args: string[]): { exitCode: number; stdout: string; stderr: string } {
+  const result = Bun.spawnSync(args, { cwd: resolve(import.meta.dir, '../..'), stdout: 'pipe', stderr: 'pipe' });
+  return { exitCode: result.exitCode, stdout: result.stdout.toString(), stderr: result.stderr.toString() };
+}
+
+function spawnDetached(args: string[], log: string): { pid: number } {
+  const fd = openSync(log, 'a');
+  try {
+    const child = Bun.spawn(args, { cwd: resolve(import.meta.dir, '../..'), stdout: fd, stderr: fd, stdin: 'ignore', detached: true });
+    child.unref();
+    return { pid: child.pid };
+  } finally { closeSync(fd); }
+}
+
+function lastJson(stdout: string): Record<string, unknown> {
+  const line = stdout.trim().split('\n').at(-1);
+  const value: unknown = JSON.parse(line ?? '');
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid CLI JSON');
+  return value as Record<string, unknown>;
+}
+
+/** One issue is reserved before any side effect; budget skips are retriable, never counted as a launch. */
+export function launch(item: LaunchItem, deps: LaunchDeps): LaunchEntry {
+  const { ledger, settings, root } = deps;
+  if (item.row.rung !== 4 || item.row.hitlReason || item.row.disposition !== 'now' || (ledger.launches[item.issue.identifier] && ledger.launches[item.issue.identifier].status !== 'skipped-budget' && !(settings.launch === 'live' && ledger.launches[item.issue.identifier].status === 'shadow'))) throw new Error('steward launch is not eligible');
+  if (settings.launch === 'off') throw new Error('steward launch is off');
+  const key = item.issue.identifier;
+  const entry: LaunchEntry = { issue: key, title: redactSecrets(item.issue.title), source: item.source, command: redactSecrets(item.command), status: 'shadow' };
+  if (settings.launch !== 'live') {
+    ledger.launches[key] = entry;
+    saveLaunchLedger(root, ledger);
+    debug.log('steward.launch', 'shadow', { issue: key, command: entry.command });
+    return entry;
+  }
+  const command = deps.command ?? runCommand;
+  try {
+    const budget = command(cli(['harness', 'budget', '--json']));
+    const decision = budget.exitCode === 0 ? lastJson(budget.stdout) : {};
+    if (!BUDGET_PROCEED.includes(String(decision.outcome))) {
+      entry.status = 'skipped-budget';
+      entry.reason = redactSecrets(budget.exitCode === 0 ? JSON.stringify(decision.reasons ?? ['budget unavailable']) : budget.stderr ?? 'budget unavailable');
+      // A budget skip may be reconsidered on the next cycle, but the reason remains observable now.
+      ledger.launches[key] = entry;
+      saveLaunchLedger(root, ledger);
+      debug.log('steward.launch', 'skipped-budget', { issue: key, reason: entry.reason });
+      return entry;
+    }
+  } catch (error) {
+    entry.status = 'skipped-budget';
+    entry.reason = redactSecrets(String(error));
+    ledger.launches[key] = entry;
+    saveLaunchLedger(root, ledger);
+    debug.log('steward.launch', 'skipped-budget', { issue: key, reason: entry.reason });
+    return entry;
+  }
+  entry.status = 'launched';
+  entry.log = join(root, 'steward', 'launch', `${key.replace(/[^a-zA-Z0-9_-]/g, '_')}.log`);
+  mkdirSync(join(root, 'steward', 'launch'), { recursive: true });
+  ledger.launches[key] = entry;
+  saveLaunchLedger(root, ledger);
+  try {
+    entry.pid = (deps.spawn ?? spawnDetached)(argvFor(item.issue, settings), entry.log).pid;
+  } catch (error) {
+    entry.status = 'failed';
+    entry.reason = redactSecrets(String(error));
+  }
+  if (entry.pid) {
+    try { entry.runId = readFileSync(entry.log, 'utf8').match(RUN_ID)?.[0]; }
+    catch { /* The detached child may not have written its log yet. */ }
+  }
+  saveLaunchLedger(root, ledger);
+  debug.log('steward.launch', 'launched', { issue: key, runId: entry.runId, pid: entry.pid, status: entry.status });
+  return entry;
+}
+
+export function raiseHitl(issue: TriageIssue, row: ScheduledDecision, deps: LaunchDeps): HitlEntry {
+  const old = deps.ledger.hitl[issue.identifier];
+  if (old && (old.attempted || deps.settings.launch !== 'live')) return old;
+  const entry: HitlEntry = old ?? { issue: issue.identifier, reason: redactSecrets(row.hitlReason ?? row.why), raised: false };
+  deps.ledger.hitl[issue.identifier] = entry;
+  if (deps.settings.launch !== 'live') {
+    saveLaunchLedger(deps.root, deps.ledger);
+    return entry;
+  }
+  entry.attempted = true;
+  saveLaunchLedger(deps.root, deps.ledger);
+  try {
+    const category = row.hitlReason === 'public' ? 'publish' : ['money', 'security', 'irreversible'].includes(row.hitlReason ?? '') ? row.hitlReason! : 'other';
+    const title = redactSecrets(issue.title);
+    const result = (deps.command ?? runCommand)(cli(['decisions', 'raise', '--title', title, '--category', category,
+      '--s', title.slice(0, 240), '--c', redactSecrets(row.why).slice(0, 240), '--option', 'a=approve:execute after human decision',
+      '--option', 'b=decline:do not execute', '--skip-recommend', 'human decision required', '--agent', 'steward', ...(issue.ref ? ['--ref', issue.ref] : []), '--json']));
+    entry.raised = result.exitCode === 0;
+  } catch { /* Command may not be installed; card remains the human handoff. */ }
+  saveLaunchLedger(deps.root, deps.ledger);
+  if (entry.raised) debug.log('steward.launch', 'hitl-raised', { issue: issue.identifier });
+  return entry;
+}
+
+function alive(pid: number | undefined): boolean {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+export function collectOutcomes(ledger: LaunchLedger, deps: LaunchDeps): LaunchEntry[] {
+  if (deps.settings.launch !== 'live') return [];
+  const done: LaunchEntry[] = [];
+  for (const entry of Object.values(ledger.launches)) {
+    if (entry.reported || entry.status === 'shadow' || entry.status === 'skipped-budget') continue;
+    if (!entry.runId && entry.log) {
+      try { entry.runId = readFileSync(entry.log, 'utf8').match(RUN_ID)?.[0]; } catch { /* Wait for log. */ }
+    }
+    if (entry.runId) {
+      try {
+        const result = (deps.command ?? runCommand)(cli(['self', 'run-ledger', entry.runId, '--json']));
+        if (result.exitCode !== 0) throw new Error(result.stderr ?? 'run ledger unavailable');
+        const events = result.stdout.trim().split('\n').filter(Boolean).map(line => JSON.parse(line) as { event?: string; data?: Record<string, unknown> });
+        if (!events.length) throw new Error('empty run ledger');
+        const reversed = [...events].reverse();
+        const mergedOffset = reversed.findIndex(event => event.event === 'merged' && event.data?.merged === true);
+        const terminalOffset = reversed.findIndex(event => event.event === 'run-status' || event.event === 'terminal');
+        const mergedIndex = mergedOffset < 0 ? -1 : events.length - 1 - mergedOffset;
+        const terminalIndex = terminalOffset < 0 ? -1 : events.length - 1 - terminalOffset;
+        const merged = mergedIndex >= 0 ? events[mergedIndex] : undefined;
+        const terminal = terminalIndex >= 0 ? events[terminalIndex] : undefined;
+        const pr = reversed.find(event => event.event === 'pr-opened');
+        const artifact = reversed.find(event => event.event === 'deploy-noncode' && typeof event.data?.ref === 'string');
+        entry.artifactRef = typeof artifact?.data?.ref === 'string' ? artifact.data.ref : undefined;
+        entry.artifactBranch = typeof artifact?.data?.branch === 'string' ? artifact.data.branch : undefined;
+        const worktree = reversed.find(event => event.event === 'planned' && typeof event.data?.worktree === 'string' && event.data.worktree);
+        entry.artifactWorktree = typeof worktree?.data?.worktree === 'string' ? worktree.data.worktree : undefined;
+        const number = merged?.data?.number ?? pr?.data?.number;
+        const url = merged?.data?.url ?? pr?.data?.url;
+        const validUrl = typeof url === 'string' && /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+$/.test(url) ? url : undefined;
+        entry.prNumber = typeof number === 'number' ? number : validUrl ? Number(validUrl.split('/').at(-1)) : undefined;
+        entry.prUrl = validUrl && (entry.prNumber === undefined || validUrl.endsWith(`/pull/${entry.prNumber}`)) ? validUrl : undefined;
+        const failed = terminalIndex > mergedIndex && (terminal?.data?.runStatus === 'failed' || terminal?.data?.terminal === 'failed');
+        entry.awaitingMerge = !failed && !merged && !artifact && !!pr && terminal?.data?.runStatus === 'completed';
+        const completed = !failed && !merged && terminal?.data?.runStatus === 'completed';
+        // A finished run is only «merged» when a merge event exists; finishing with an artifact or with nothing is `completed`, not a failure.
+        entry.status = failed ? 'failed' : merged ? 'merged' : entry.awaitingMerge ? 'running' : completed ? 'completed' : terminal ? 'failed' : 'running';
+        if (entry.status === 'failed' && !entry.reason) {
+          const reason = terminal?.data?.reason ?? terminal?.data?.terminal;
+          entry.reason = redactSecrets(typeof reason === 'string' ? reason : '런 실패');
+        }
+      } catch { if (entry.status !== 'failed') entry.status = 'running'; }
+    } else if (entry.status !== 'failed') entry.status = alive(entry.pid) ? 'running' : 'failed';
+    if (entry.status === 'running') continue;
+    done.push(entry);
+    debug.log('steward.launch', 'outcome', { issue: entry.issue, status: entry.status, runId: entry.runId, prNumber: entry.prNumber });
+  }
+  saveLaunchLedger(deps.root, ledger);
+  return done;
+}