elanous 0.2.9 → 0.2.11

package/src/skills/gift-install.ts

@@ -0,0 +1,215 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export interface GiftInstallOptions {
+  pack: string;
+  code?: string;
+  email?: string;
+  agree?: boolean;
+  endpoint?: string;
+  fetch?: typeof fetch;
+  targets?: string[];
+  /** Caps (defaults below); tests pass small values. */
+  maxDownloadBytes?: number;
+  maxUnpackedBytes?: number;
+  maxEntries?: number;
+}
+
+export type GiftInstallResult =
+  | { ok: true; names: string[]; paths: string[]; collisions: string[]; needsKeys: boolean; message: string }
+  | { ok: false; reason: string; message: string };
+
+// GK1 public bundle: packs/elanous-essentials/plugin.json extensions.ai.elanous.bundle.
+const ESSENTIAL_SKILLS = ['youtube-master', 'omni-crawl', 'omni-digest', 'diagram-master', 'lecture-note-digitizer'];
+// A malicious or broken gift must not exhaust the temp disk: cap the download, the unpacked total and the entry count.
+export const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
+export const MAX_UNPACKED_BYTES = 100 * 1024 * 1024;
+export const MAX_ENTRIES = 5000;
+const CONSENT_NOTICE = '선물 스킬 전달과 안내 메일을 위해 이메일을 받습니다 · 보관은 알림 신청과 같은 기간 · 동의하면 --agree 를 붙여 다시 시도해 주세요.';
+const ERROR_MESSAGES: Record<string, string> = {
+  'email-required': CONSENT_NOTICE,
+  'consent-required': CONSENT_NOTICE,
+  'unknown-code': '코드를 다시 확인해 주세요.',
+  'used-up': '이미 다 쓴 코드예요 · 업데이트 소식 신청을 확인해 주세요.',
+  expired: '만료된 코드예요.',
+};
+
+/** Redeem, verify and install a gift without modifying an existing skill directory. */
+export async function installGiftPack({
+  pack, code, email, agree, endpoint = 'https://elanous.ai', fetch: fetchImpl = fetch,
+  targets = [join(homedir(), '.agents', 'skills'), join(homedir(), '.claude', 'skills')],
+  maxDownloadBytes = MAX_DOWNLOAD_BYTES, maxUnpackedBytes = MAX_UNPACKED_BYTES, maxEntries = MAX_ENTRIES,
+}: GiftInstallOptions): Promise<GiftInstallResult> {
+  const codePrefix = code && code.length > 4 ? code.slice(0, 4) : undefined;
+  const reject = (reason: string, message: string): GiftInstallResult => {
+    debug.log('skills.gift', 'rejected', { pack, reason, count: 0, codePrefix });
+    return { ok: false, reason, message };
+  };
+  if (!email?.trim() || !agree) return reject(!email?.trim() ? 'email-required' : 'consent-required', CONSENT_NOTICE);
+  if (!code?.trim()) return reject('unknown-code', ERROR_MESSAGES['unknown-code']!);
+  let gift: Record<string, unknown>;
+  try {
+    const response = await fetchImpl(`${endpoint.replace(/\/$/, '')}/api/gift`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ code, email, consent: true }),
+    });
+    // The gift API assigns these reasons by HTTP status; error bodies may be absent or malformed.
+    const statusReason = ({ 404: 'unknown-code', 409: 'used-up', 410: 'expired' } as Record<number, string | undefined>)[response.status];
+    if (statusReason) return reject(statusReason, ERROR_MESSAGES[statusReason]!);
+    const payload: unknown = await response.json();
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+      return reject('invalid-response', '선물 응답을 확인할 수 없습니다. 다시 시도해 주세요.');
+    }
+    gift = payload as Record<string, unknown>;
+    if (!response.ok) {
+      const reason = response.status === 400 && (gift.reason === 'email-required' || gift.reason === 'consent-required')
+        ? gift.reason : 'request-rejected';
+      return reject(reason, ERROR_MESSAGES[reason] ?? '선물을 받을 수 없습니다. 다시 시도해 주세요.');
+    }
+  } catch {
+    return reject('network-error', '네트워크에 연결할 수 없습니다. 다시 시도해 주세요.');
+  }
+  if (gift.ok !== true || gift.pack !== pack || typeof gift.zipUrl !== 'string' || !/^https?:\/\//.test(gift.zipUrl)
+    || typeof gift.sha256 !== 'string' || !/^[a-f0-9]{64}$/i.test(gift.sha256)) {
+    return reject('invalid-response', '선물 응답을 확인할 수 없습니다. 다시 시도해 주세요.');
+  }
+  let zip: Buffer;
+  const tooLarge = () => reject('too-large', '선물 zip 이 허용 크기를 넘습니다. 설치하지 않았습니다.');
+  try {
+    const response = await fetchImpl(gift.zipUrl, { redirect: 'error' });
+    if (!response.ok) throw new Error('download-failed');
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxDownloadBytes) return tooLarge();
+    // Count the bytes actually received too — a missing or lying Content-Length must not bypass the cap.
+    const chunks: Uint8Array[] = [];
+    let received = 0;
+    if (response.body) {
+      const reader = response.body.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        received += value.byteLength;
+        if (received > maxDownloadBytes) { await reader.cancel().catch(() => {}); return tooLarge(); }
+        chunks.push(value);
+      }
+    }
+    zip = Buffer.concat(chunks);
+  } catch {
+    return reject('network-error', '다운로드에 실패했습니다. 다시 시도해 주세요.');
+  }
+  if (createHash('sha256').update(zip).digest('hex').toLowerCase() !== gift.sha256.toLowerCase()) {
+    debug.log('skills.gift', 'checksum-mismatch', { pack, reason: 'sha256', count: 0, codePrefix });
+    return { ok: false, reason: 'checksum-mismatch', message: '다운로드 검증(sha256)에 실패했습니다. 설치하지 않았습니다.' };
+  }
+  const temp = mkdtempSync(join(tmpdir(), 'elanous-gift-'));
+  const created: string[] = [];
+  let incomplete: string | undefined;
+  try {
+    const zipPath = join(temp, 'gift.zip');
+    const extracted = join(temp, 'extracted');
+    mkdirSync(extracted);
+    writeFileSync(zipPath, zip);
+    // Reject archive symlinks and traversal paths before extracting any entry.
+    execFileSync('python3', ['-c', `import os, stat, sys, zipfile
+root = sys.argv[2]
+max_unpacked = int(sys.argv[3]); max_entries = int(sys.argv[4])
+with zipfile.ZipFile(sys.argv[1]) as archive:
+    entries = archive.infolist()
+    if len(entries) > max_entries or sum(entry.file_size for entry in entries) > max_unpacked:
+        sys.exit(3)
+    for entry in entries:
+        parts = entry.filename.split('/')
+        mode = entry.external_attr >> 16
+        if (not entry.filename or entry.filename.startswith('/') or '\\u005c' in entry.filename
+            or any(part in ('', '.', '..') for part in parts[:-1])
+            or parts[-1] in ('.', '..') or (not entry.is_dir() and not parts[-1])
+            or stat.S_ISLNK(mode)):
+            raise ValueError('invalid archive entry')
+    written = 0
+    for entry in entries:
+        path = os.path.join(root, entry.filename)
+        if entry.is_dir():
+            os.makedirs(path, exist_ok=True)
+        else:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with archive.open(entry) as source, open(path, 'xb') as target:
+                while True:
+                    block = source.read(65536)
+                    if not block:
+                        break
+                    written += len(block)
+                    if written > max_unpacked:
+                        sys.exit(3)
+                    target.write(block)
+`, zipPath, extracted, String(maxUnpackedBytes), String(maxEntries)], { stdio: 'pipe' });
+    const skillDirs = (root: string) => readdirSync(root, { withFileTypes: true })
+      // SKILL.md must be a regular file — a `SKILL.md/` directory or a symlink is not a skill.
+      .filter((entry) => entry.isDirectory() && lstatSync(join(root, entry.name, 'SKILL.md'), { throwIfNoEntry: false })?.isFile() === true)
+      .map((entry) => ({ name: entry.name, path: join(root, entry.name) }));
+    let skills = skillDirs(extracted);
+    if (!skills.length) {
+      const roots = readdirSync(extracted, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory()).map((entry) => join(extracted, entry.name));
+      if (roots.length === 1) {
+        skills = skillDirs(roots[0]!);
+        if (!skills.length && existsSync(join(roots[0]!, 'skills'))) skills = skillDirs(join(roots[0]!, 'skills'));
+      }
+    }
+    // Directory listing order differs between filesystems — keep the bundle order, then names.
+    const rank = (name: string) => { const i = ESSENTIAL_SKILLS.indexOf(name); return i < 0 ? ESSENTIAL_SKILLS.length : i; };
+    skills = [...skills].sort((a, b) => rank(a.name) - rank(b.name) || a.name.localeCompare(b.name));
+    if (!skills.length || !targets.length) return reject('invalid-pack', '설치할 스킬 폴더나 대상 경로를 찾지 못했습니다.');
+    if (pack === 'essential' && (skills.length !== ESSENTIAL_SKILLS.length
+      || ESSENTIAL_SKILLS.some((name) => !skills.some((skill) => skill.name === name)))) {
+      return reject('invalid-pack', '필수 스킬 다섯이 모두 들어 있지 않습니다. 설치하지 않았습니다.');
+    }
+    const paths: string[] = [];
+    const collisions: string[] = [];
+    const date = new Date().toISOString().slice(0, 10);
+    for (const target of targets) {
+      mkdirSync(target, { recursive: true });
+      for (const skill of skills) {
+        const desired = join(target, skill.name);
+        let dest = desired;
+        if (lstatSync(desired, { throwIfNoEntry: false })) {
+          dest = `${desired}.gift-${date}`;
+          let n = 2;
+          while (lstatSync(dest, { throwIfNoEntry: false })) dest = `${desired}.gift-${date}-${n++}`;
+          collisions.push(`${skill.name} → ${dest}`);
+        }
+        // Reserve the destination exclusively: a concurrent installer must not be overwritten.
+        mkdirSync(dest);
+        incomplete = dest;
+        for (const entry of readdirSync(skill.path)) {
+          cpSync(join(skill.path, entry), join(dest, entry), { recursive: true, errorOnExist: true, force: false });
+        }
+        created.push(dest);
+        incomplete = undefined;
+        paths.push(dest);
+      }
+    }
+    const names = skills.map((skill) => skill.name);
+    const needsKeys = skills.some((skill) => existsSync(join(skill.path, '.env.example')));
+    const message = `${collisions.length ? `기존 폴더는 그대로 두고 옆에 설치했습니다: ${collisions.join(', ')}\n` : ''}${needsKeys ? '.env.example 이 있습니다 — 키는 가이드대로 설정해 주세요.\n' : ''}설치한 스킬: ${names.join(', ')}`;
+    debug.log('skills.gift', 'installed', { pack, reason: 'ok', count: paths.length, codePrefix });
+    return { ok: true, names, paths, collisions, needsKeys, message };
+  } catch (error) {
+    if ((error as { status?: number }).status === 3 && !created.length) return tooLarge();
+    const remaining: string[] = [];
+    for (const path of [...(incomplete ? [incomplete] : []), ...created.reverse()]) {
+      try { rmSync(path, { recursive: true }); }
+      catch { remaining.push(path); }
+    }
+    if (remaining.length) {
+      debug.log('skills.gift', 'rejected', { pack, reason: 'partial-install', count: remaining.length, codePrefix });
+      return { ok: false, reason: 'partial-install', message: `일부 설치된 스킬을 되돌리지 못했습니다: ${remaining.join(', ')}` };
+    }
+    return reject('invalid-pack', '선물 zip 을 안전하게 풀 수 없습니다. 설치하지 않았습니다.');
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}

package/src/skills/tools/web-search.ts

@@ -101,7 +101,10 @@ export async function dispatchWebSearch(args: Record<string, unknown>, ctx: { si
   });
 
   const notePrefix = result.note ? `\n\n${result.note}\n` : '';
-  const output = [header, notePrefix.trim(), ...hitLines].filter(Boolean).join('\n\n');
+  const xStatus = result.xSearch === 'unavailable'
+    ? 'X search unavailable: these results do not establish reactions on X; do not cite them as X posts.'
+    : '';
+  const output = [header, xStatus, notePrefix.trim(), ...hitLines].filter(Boolean).join('\n\n');
 
   return {
     output,

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,266 @@
+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 { publishInsideEvent } from '../nexus/api/inside-events.js';
+import { redactSecrets } from '../task-cards/card-store.js';
+import { preLaunchGate, type PreLaunchGateDecision } from '../execution-loop/launch-gate.js';
+import type { BudgetDecision } from '../self-implement/budget-gate.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' | 'blocked-duplicate' | 'blocked-location' | '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 };
+  gate?: (goalId: string, budget: BudgetDecision | 'unknown') => PreLaunchGateDecision;
+}
+
+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 launchMode = (settings: StewardSettings): 'off' | 'shadow' | 'live' => settings.mode ?? settings.launch ?? 'shadow';
+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 (launchMode(settings) !== 'off' && (!ledger.hitl[row.issue] || launchMode(settings) === 'live' && !ledger.hitl[row.issue].attempted)) hitl.push({ issue, row });
+      continue;
+    }
+    if (launchMode(settings) === 'off' || row.disposition !== 'now' || row.rung !== 4 || (ledger.launches[row.issue] && !['skipped-budget', 'blocked-duplicate', 'blocked-location'].includes(ledger.launches[row.issue].status) && !(launchMode(settings) === '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] && !['skipped-budget', 'blocked-duplicate', 'blocked-location'].includes(ledger.launches[item.issue.identifier].status) && !(launchMode(settings) === 'live' && ledger.launches[item.issue.identifier].status === 'shadow'))) throw new Error('steward launch is not eligible');
+  if (launchMode(settings) === '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 (launchMode(settings) !== 'live') {
+    ledger.launches[key] = entry;
+    saveLaunchLedger(root, ledger);
+    debug.log('steward.launch', 'shadow', { issue: key, command: entry.command });
+    publishInsideEvent({ kind: 'steward', issue: key, status: entry.status });
+    return entry;
+  }
+  const command = deps.command ?? runCommand;
+  const blocked = (status: LaunchStatus, reason: string): LaunchEntry => {
+    entry.status = status;
+    entry.reason = redactSecrets(reason);
+    ledger.launches[key] = entry;
+    saveLaunchLedger(root, ledger);
+    debug.log('steward.launch', status, { issue: key, reason: entry.reason });
+    publishInsideEvent({ kind: 'steward', issue: key, status: entry.status, reason: entry.reason });
+    return entry;
+  };
+  // L6: a launch must remain on the isolated Pod pool, never fall back to the host or another substrate.
+  if (!/^[a-zA-Z0-9_-]+(?:@[a-zA-Z0-9._-]+(?::[1-9][0-9]*)?)?$/.test(settings.podPool ?? DEFAULT_POOL))
+    return blocked('blocked-location', 'invalid steward pod pool');
+  let budget: BudgetDecision | 'unknown' = 'unknown';
+  try {
+    const result = command(cli(['harness', 'budget', '--json']));
+    const decision = result.exitCode === 0 ? lastJson(result.stdout) : {};
+    if (!BUDGET_PROCEED.includes(String(decision.outcome)))
+      return blocked('skipped-budget', result.exitCode === 0 ? JSON.stringify(decision.reasons ?? ['budget unavailable']) : result.stderr ?? 'budget unavailable');
+    budget = { action: decision.outcome as 'proceed' | 'next-provider', reasons: Array.isArray(decision.reasons) ? decision.reasons.map(String) : [] };
+  } catch (error) {
+    return blocked('skipped-budget', String(error));
+  }
+  // L6: the shared gate checks active same-goal runs and the budget decision immediately before spawn.
+  let gate: PreLaunchGateDecision;
+  try { gate = (deps.gate ?? ((goalId, decision) => preLaunchGate({ goalId, budget: decision })))(`linear:${key}`, budget); }
+  catch (error) { return blocked('blocked-duplicate', `launch gate unavailable: ${String(error)}`); }
+  if (gate.action !== 'proceed' || gate.sameGoalActiveRuns === 'unknown')
+    return blocked(gate.action === 'blocked-budget' || gate.action === 'wait-reset' ? 'skipped-budget' : 'blocked-duplicate', gate.sameGoalActiveRuns === 'unknown' ? 'active runs unknown' : gate.reason);
+  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 });
+  publishInsideEvent({ kind: 'steward', issue: key, status: entry.status, ...(entry.runId ? { runId: entry.runId } : {}) });
+  return entry;
+}
+
+export function raiseHitl(issue: TriageIssue, row: ScheduledDecision, deps: LaunchDeps): HitlEntry {
+  const old = deps.ledger.hitl[issue.identifier];
+  if (old && (old.attempted || launchMode(deps.settings) !== '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 (launchMode(deps.settings) !== '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 (launchMode(deps.settings) !== 'live') return [];
+  const done: LaunchEntry[] = [];
+  for (const entry of Object.values(ledger.launches)) {
+    if (entry.reported || entry.status === 'shadow' || entry.status === 'skipped-budget' || entry.status === 'blocked-duplicate' || entry.status === 'blocked-location') 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 });
+    publishInsideEvent({ kind: 'steward', issue: entry.issue, status: entry.status, ...(entry.runId ? { runId: entry.runId } : {}) });
+  }
+  saveLaunchLedger(deps.root, ledger);
+  return done;
+}