elanous 0.2.34 → 0.2.35

package/src/harness/harness-cli-command.ts

@@ -22,7 +22,8 @@ import { templateForGoalType } from '../self-implement/graph-templates.js';
 import { appendRunLedgerEntry, listRunLedgers, loadFederatedRunLedger, loadRunLedger, queryRunScreenKey, runLedgerDir, type RunLedgerEntry, type RunLedgerMatch, type RunLedgerWriter } from '../self-implement/run-ledger.js';
 import { classifyPodExit, type PodExitClass } from '../task-orchestrator/surfaces/pod-failure-reason.js';
 import type { PodChildEvidence } from '../task-orchestrator/surfaces/self-implement.js';
-import { classifyPodExitStop, recordRunStop, runStopRecorded, RUN_STOP_EVENT } from '../self-implement/run-stop.js';
+import { classifyPodExitStop, readRunStopRecord, recordRunStop, runStopRecorded, RUN_STOP_EVENT } from '../self-implement/run-stop.js';
+import { captureStopKnowhowCandidate } from '../self-implement/stop-autoheal.js';
 import { ensureOpenRouterChildModelLive, resolveChildLlmEffort, resolveImplementationChildModel } from '../self-dev/dev-cli.js';
 import { resolveHarnessTarget } from '../self-implement/harness-target-options.js';
 import { buildRunProgressRows, isPartialRunningRuns, queryRunningRuns, renderRunProgressTable } from '../self-implement/running-runs.js';
@@ -450,7 +451,7 @@ export function classifyHarnessPodExit(
     loadCheckpoint?: typeof loadSelfDevRun;
     runId?: string;
   } = {},
-): { lines: string[]; reason: PodExitReason | 'pod-failure' } {
+): { lines: string[]; reason: PodExitReason | 'pod-failure'; podErrorCode?: 'pod-job-failed' } {
   const occupiedNewLine = output.split('\n').find((line) =>
     /^\[self-dev\] run run-[a-z0-9_-]{8,64} \[preflight:new-path-occupied:[0-9a-f-]{36}\] /.test(line));
   const observedRunId = deps.runId ?? harnessPodRunId(output);
@@ -475,6 +476,7 @@ export function classifyHarnessPodExit(
   }
   let podFailure: string | undefined;
   let podJobFailed = false;
+  let podJobFailedFromResult = false;
   let podChildFailed = false;
   for (const line of output.split('\n').reverse()) {
     if (!line.trimStart().startsWith('[{') || !line.includes('"error"')) continue;
@@ -487,6 +489,7 @@ export function classifyHarnessPodExit(
         if (typeof error?.code !== 'string' || typeof error.message !== 'string' || !error.code.startsWith('pod-')) continue;
         podFailure = error.message;
         podJobFailed = error.code === 'pod-job-failed';
+        podJobFailedFromResult = podJobFailed;
         podChildFailed = error.code === 'pod-child-failed';
         break;
       }
@@ -505,7 +508,7 @@ export function classifyHarnessPodExit(
   if (podFailure) {
     const childError = podJobFailed ? podFailure.split('childError=')[1]?.split('\\n', 1)[0]?.split('\n', 1)[0] : undefined;
     try { debug.log('harness.pod', 'exit-classified', { runId, reason: 'pod-failure', status: exit.status, signal: exit.signal ?? null }); } catch { /* observation is fail-soft */ }
-    return { reason: 'pod-failure', lines: [podChildFailed
+    return { reason: 'pod-failure', ...(podJobFailedFromResult ? { podErrorCode: 'pod-job-failed' as const } : {}), lines: [podChildFailed
       ? `Pod 안 자식이 실패했다 — ${podFailure.split('\\n', 1)[0]}`
       : podJobFailed && childError && childError !== 'no-result-line'
         ? `Pod 안 자식이 실패했다 — ${childError}`
@@ -769,7 +772,7 @@ async function onPod(opts: unknown, entrance: 'cli-harness-ask' | 'cli-harness-s
 export function recordHarnessPodStop(
   runId: string | undefined,
   status: number,
-  classified: { reason: string; lines: string[] },
+  classified: { reason: string; lines: string[]; podErrorCode?: 'pod-job-failed' },
   output?: string,
   deps: { loadLedger?: typeof loadRunLedger; record?: typeof recordRunStop; write?: RunLedgerWriter } = {},
 ): boolean {
@@ -805,11 +808,32 @@ export function recordHarnessPodStop(
     }
     // The classified line is our own one-line verdict («Pod 안 자식이 실패했다 — OOMKilled»), not the raw output tail.
     const verdict = classified.lines[0]?.split(' — ').slice(1).join(' — ').trim();
-    (deps.record ?? recordRunStop)({
+    const stopEntry = (deps.record ?? recordRunStop)({
       runId, site: 'pod-exit', class: scopeEscape ? 'scope-escape' : classifyPodExitStop(classified.reason),
       cause: `Pod exit ${status}: ${scopeEscape ? 'scope-escape' : classified.reason}${verdict ? ` — ${verdict}` : ''}`,
       evidenceRef, nextMove, ...(childEvidence ? { childEvidence } : {}),
+      ...(classified.podErrorCode === 'pod-job-failed' ? { terminationReason: classified.podErrorCode } : {}),
     }, ...(deps.write ? [deps.write] : []));
+    // Host-only Pod exits do not pass through orchestrator.autohealRecordedStop. Capture the
+    // exact Job failure here, after the durable stop write, without initiating a heal action.
+    if (classified.podErrorCode === 'pod-job-failed' && stopEntry) {
+      try {
+        const record = readRunStopRecord(stopEntry);
+        if (record) {
+          const goalId = ledger?.find((entry) => entry.goalId)?.goalId;
+          const captured = captureStopKnowhowCandidate({ runId, ...(goalId ? { goalId } : {}), record },
+          join(effectiveInstanceRoot(), 'self-implement', 'knowhow-candidates'));
+          if (captured) debug.log('self-implement.autoheal', 'knowhow-candidate', {
+            runId, cell: captured.candidate.cell, reason: captured.candidate.reason,
+            created: captured.created, occurrences: captured.candidate.occurrences, path: captured.path,
+          });
+        }
+      } catch (error) {
+        try { debug.log('self-implement.autoheal', 'knowhow-candidate-failed', {
+          runId, error: error instanceof Error ? error.message : String(error),
+        }); } catch { /* observation is fail-soft */ }
+      }
+    }
     return true;
   } catch { return false; /* ledger observation cannot change Pod output or exit */ }
 }
@@ -2378,8 +2402,9 @@ function githubRemoteRepository(url: string): string | undefined {
 interface GraphqlPrDetail {
   readonly files: string[] | null;
   readonly comments: string[] | null;
-  readonly reviews: Array<{ state?: string; body?: string }> | null;
+  readonly reviews: Array<{ state?: string; body?: string; submittedAt?: string; commitOid?: string }> | null;
   readonly headSha: string | null;
+  readonly headCommittedAt: string | null;
   readonly mergeCommit: { oid: string; message: string } | null;
 }
 
@@ -2407,10 +2432,10 @@ async function graphqlPrDetails(repository: string, numbers: readonly number[],
   // Fields the batch could not prove complete (each one is read again over REST by the caller).
   const incompleteFields = { files: 0, comments: 0, reviews: 0 };
   await mapBounded(batches, DRAFT_SWEEP_CONCURRENCY, async (batch) => {
-    const fields = batch.map((number) => `p${number}: pullRequest(number: ${number}) { number headRefOid `
+    const fields = batch.map((number) => `p${number}: pullRequest(number: ${number}) { number headRefOid headRef { target { ... on Commit { committedDate } } } `
       + 'files(first: 100) { totalCount nodes { path } pageInfo { hasNextPage } } '
       + 'comments(first: 100) { totalCount nodes { body } pageInfo { hasNextPage } } '
-      + 'reviews(first: 100) { totalCount nodes { state body } pageInfo { hasNextPage } } '
+      + 'reviews(first: 100) { totalCount nodes { state body submittedAt commit { oid } } pageInfo { hasNextPage } } '
       + 'mergeCommit { oid message } }').join(' ');
     const query = `query { repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { ${fields} } }`;
     let repositoryNode: Record<string, unknown> | undefined;
@@ -2421,9 +2446,10 @@ async function graphqlPrDetails(repository: string, numbers: readonly number[],
     if (!repositoryNode || typeof repositoryNode !== 'object' || Array.isArray(repositoryNode)) { failedBatches += 1; return; }
     for (const number of batch) {
       const pr = repositoryNode[`p${number}`] as {
-        number?: number; headRefOid?: string;
+        number?: number; headRefOid?: string; headRef?: { target?: { committedDate?: string } | null } | null;
         files?: GraphqlConnection<{ path?: string }>; comments?: GraphqlConnection<{ body?: string }>;
-        reviews?: GraphqlConnection<{ state?: string; body?: string }>; mergeCommit?: { oid?: string; message?: string } | null;
+        reviews?: GraphqlConnection<{ state?: string; body?: string; submittedAt?: string; commit?: { oid?: string } | null }>;
+        mergeCommit?: { oid?: string; message?: string } | null;
       } | null | undefined;
       if (!pr || pr.number !== number) continue;
       const files = completeNodes(pr.files);
@@ -2433,8 +2459,10 @@ async function graphqlPrDetails(repository: string, numbers: readonly number[],
         files: files && files.every((file) => typeof file?.path === 'string') ? files.map((file) => file.path!) : null,
         comments: comments && comments.every((comment) => typeof comment?.body === 'string') ? comments.map((comment) => comment.body!) : null,
         reviews: reviews && reviews.every((review) => review && typeof review === 'object')
-          ? reviews.map((review) => ({ state: review.state, body: review.body })) : null,
+          ? reviews.map((review) => ({ state: review.state, body: review.body, submittedAt: review.submittedAt,
+            commitOid: review.commit?.oid })) : null,
         headSha: typeof pr.headRefOid === 'string' && pr.headRefOid ? pr.headRefOid : null,
+        headCommittedAt: typeof pr.headRef?.target?.committedDate === 'string' ? pr.headRef.target.committedDate : null,
         mergeCommit: pr.mergeCommit && typeof pr.mergeCommit.oid === 'string' && typeof pr.mergeCommit.message === 'string'
           ? { oid: pr.mergeCommit.oid, message: pr.mergeCommit.message } : null,
       };
@@ -2565,30 +2593,80 @@ export function githubDraftSweepAdapters(execute: GhExecute = executeGh, git: Dr
     }
     throw new Error(`${what === 'review' ? 'Review' : what === 'same-cell' ? 'Same-cell' : 'Landing'} comment inventory exceeded pagination limit`);
   };
+  const reviewsFor = async (repository: string, number: number): Promise<Array<{ state?: string; body?: string; submittedAt?: string; commitOid?: string }>> => {
+    const reviews: Array<{ state?: string; body?: string; submittedAt?: string; commitOid?: string }> = [];
+    for (let page = 1; page <= 100; page++) {
+      const batch = await ghJsonAsync<Array<{ state?: string; body?: string; submitted_at?: string; commit_id?: string }>>(
+        ['api', `repos/${repository}/pulls/${number}/reviews?per_page=100&page=${page}`]);
+      if (!Array.isArray(batch) || batch.length > 100) throw new Error('Incomplete review inventory');
+      reviews.push(...batch.map((review) => ({ state: review.state, body: review.body,
+        submittedAt: review.submitted_at, commitOid: review.commit_id })));
+      if (batch.length < 100) return reviews;
+    }
+    throw new Error('Review inventory exceeded pagination limit');
+  };
+  const checkRunsFor = async (repository: string, sha: string): Promise<Array<{ conclusion?: string | null }> | undefined> => {
+    const runs: Array<{ conclusion?: string | null }> = [];
+    for (let page = 1; page <= 100; page++) {
+      const result = await ghJsonAsync<{ total_count?: number; check_runs?: Array<{ conclusion?: string | null }> }>(
+        ['api', `repos/${repository}/commits/${sha}/check-runs?per_page=100&page=${page}`]);
+      if (!Array.isArray(result?.check_runs) || result.check_runs.length > 100) throw new Error('Incomplete check-run inventory');
+      runs.push(...result.check_runs);
+      if (Number.isSafeInteger(result.total_count) && runs.length >= result.total_count!) return runs;
+      if (result.check_runs.length < 100) return Number.isSafeInteger(result.total_count) && runs.length < result.total_count! ? undefined : runs;
+    }
+    return undefined;
+  };
+  const headCommitTimeFor = async (repository: string, number: number): Promise<string | undefined> => {
+    let latest: string | undefined;
+    for (let page = 1; page <= 100; page++) {
+      const batch = await ghJsonAsync<Array<{ commit?: { committer?: { date?: string } } }>>(
+        ['api', `repos/${repository}/pulls/${number}/commits?per_page=100&page=${page}`]);
+      if (!Array.isArray(batch) || batch.length > 100) throw new Error('Incomplete PR commit inventory');
+      for (const commit of batch) {
+        const date = commit.commit?.committer?.date;
+        if (!date || !Number.isFinite(Date.parse(date))) throw new Error('Incomplete PR commit timestamp');
+        latest = date;
+      }
+      if (batch.length < 100) return latest;
+    }
+    throw new Error('PR commit inventory exceeded pagination limit');
+  };
   const reviewGateForDraft = async (draft: SweepDraft, repository: string): Promise<SweepReviewGate | undefined> => {
     const cached = await detailFor(repository, draft.number);
     const sha = cached?.headSha
       ?? (await ghJsonAsync<{ head?: { sha?: string } }>(['api', `repos/${repository}/pulls/${draft.number}`]))?.head?.sha;
     if (!sha) return undefined;
+    const reviews = cached?.reviews ?? await reviewsFor(repository, draft.number);
+    if (!Array.isArray(reviews)) throw new Error('Incomplete review inventory');
     const comments = cached?.comments ?? await issueCommentsFor(repository, draft.number, 'review');
-    const reviews = cached?.reviews
-      ?? await ghJsonAsync<Array<{ state?: string; body?: string }>>(['api', `repos/${repository}/pulls/${draft.number}/reviews?per_page=100`]);
-    if (!Array.isArray(reviews) || reviews.length > 100) throw new Error('Incomplete review inventory');
-    const text = [...comments, ...reviews.map((review) => review.body ?? '')].join('\n');
+    const legacyText = [...comments, ...reviews.map((review) => review.body ?? '')].join('\n');
+    const currentHeadReviews = reviews.filter((review) => review && typeof review === 'object'
+      && review.commitOid === sha
+      && typeof review.submittedAt === 'string' && Number.isFinite(Date.parse(review.submittedAt)))
+      .sort((a, b) => Date.parse(a.submittedAt!) - Date.parse(b.submittedAt!));
+    const latestHeadReview = currentHeadReviews.at(-1);
+    const triageReview = latestHeadReview?.state === 'APPROVED' ? 'approved'
+      : latestHeadReview?.state === 'CHANGES_REQUESTED' ? 'changes-requested'
+        : latestHeadReview?.state === 'COMMENTED' ? 'commented'
+          : latestHeadReview?.state === 'DISMISSED' ? 'dismissed'
+            : latestHeadReview?.state === 'PENDING' ? 'pending' : 'unknown';
     const [status, checkRuns] = await Promise.all([
       ghJsonAsync<{ state?: string }>(['api', `repos/${repository}/commits/${sha}/status`]),
-      ghJsonAsync<{ check_runs?: Array<{ conclusion?: string | null }> }>(['api', `repos/${repository}/commits/${sha}/check-runs?per_page=100`]),
+      checkRunsFor(repository, sha),
     ]);
-    if (!checkRuns || !Array.isArray(checkRuns.check_runs)) throw new Error('Incomplete check-run inventory');
-    const conclusions = checkRuns.check_runs.map((run) => run.conclusion ?? null);
-    const gatePass = (status?.state === 'success' || status?.state === undefined)
-      && conclusions.length > 0 && conclusions.every((conclusion) => conclusion === 'success' || conclusion === 'skipped' || conclusion === 'neutral');
+    const conclusions = checkRuns?.map((run) => run.conclusion ?? null) ?? [];
+    const gatePass = status?.state === 'success'
+      && checkRuns !== undefined && conclusions.length > 0
+      && conclusions.every((conclusion) => conclusion === 'success' || conclusion === 'skipped' || conclusion === 'neutral');
     const gateFail = status?.state === 'failure' || status?.state === 'error'
       || conclusions.some((conclusion) => conclusion === 'failure' || conclusion === 'cancelled' || conclusion === 'timed_out' || conclusion === 'action_required');
     return {
-      ...(reviews.some((review) => review.state === 'APPROVED') || /(?:^|\n)\s*VERDICT:\s*PASS\b/i.test(text) ? { review: 'pass' as const } : {}),
-      ...(mustFixRemains(text) ? { mustFix: true } : {}),
+      ...(reviews.some((review) => review.state === 'APPROVED') || /(?:^|\n)\s*VERDICT:\s*PASS\b/i.test(legacyText)
+        ? { review: 'pass' as const } : {}),
+      ...(mustFixRemains(legacyText) ? { mustFix: true } : {}),
       ...(gatePass && !gateFail ? { gate: 'pass' as const } : gateFail ? { gate: 'fail' as const } : {}),
+      triageReview,
     };
   };
   const claimCommentsFor = async (repository: string, number: number): Promise<string[]> => {
@@ -2618,11 +2696,15 @@ export function githubDraftSweepAdapters(execute: GhExecute = executeGh, git: Dr
       const prs = (await listed(open, repository, 'open')).filter((pr) => pr.draft);
       await prefetchDetails(repository, prs.map((pr) => pr.number));
       const matches = ledgerMatches ??= listRunLedgers().matches;
-      return mapBounded(prs, DRAFT_SWEEP_CONCURRENCY, async (pr): Promise<SweepDraft> => ({
-        number: pr.number, title: pr.title, branch: pr.head.ref,
-        labels: pr.labels.map((item) => item.name), createdAt: pr.created_at, body: pr.body ?? undefined,
-        changedFiles: await prFiles(repository, pr.number), ...(pr.updated_at ? { updatedAt: pr.updated_at } : {}),
-        runId: currentDraftSweepRunId(matches, repository, pr.number) }));
+      return mapBounded(prs, DRAFT_SWEEP_CONCURRENCY, async (pr): Promise<SweepDraft> => {
+        return {
+          number: pr.number, title: pr.title, branch: pr.head.ref,
+          labels: pr.labels.map((item) => item.name), createdAt: pr.created_at, body: pr.body ?? undefined,
+          changedFiles: await prFiles(repository, pr.number),
+          ...(pr.updated_at ? { updatedAt: pr.updated_at } : {}),
+          runId: currentDraftSweepRunId(matches, repository, pr.number),
+        };
+      });
     })());
     return draftRows.get(repository)!;
   };
@@ -2677,6 +2759,8 @@ export function githubDraftSweepAdapters(execute: GhExecute = executeGh, git: Dr
     },
     listDrafts: async (page, perPage, repository): Promise<SweepDraft[]> =>
       (await enrichedDrafts(repository)).slice((page - 1) * perPage, page * perPage),
+    getHeadCommitTime: async (repository, number) => (await detailFor(repository, number))?.headCommittedAt
+      ?? await headCommitTimeFor(repository, number).catch(() => undefined),
     listMerged: async (page, perPage, repository): Promise<SweepMergedPr[]> =>
       (await enrichedMerged(repository)).slice((page - 1) * perPage, page * perPage),
     getRunStatus: async (draft, repository) => runStatusFor(draft, repository),
@@ -2943,7 +3027,7 @@ function installHarnessDraftSweepCommand(harnessCmd: Command, deps: HarnessDraft
               owner: 'unknown', ownerSource: 'unknown', step: 'replay', reason: sweepFailureReason(error) });
           }
         }
-        const result: DraftSweepResult = await runDraftSweep({ repository, apply: opts.apply === true, adapters: deps.adapters ?? github!,
+        const result: DraftSweepResult = await runDraftSweep({ repository, apply: opts.apply === true, includeTriage: opts.json === true, adapters: deps.adapters ?? github!,
           closeCap: cap.closeCap, closeCapSource: cap.closeCapSource, alreadyClosed: replayClosed });
         const reason = result.error ? sweepFailureReason(result.error) : undefined;
         const ttlStarted = Date.now();

package/src/harness/harness-incidents.ts

@@ -209,6 +209,39 @@ export function recentBurst(root: string, now: Date | number, { lookbackMs = 15
   return recent.sort((a, b) => Date.parse(a.lastAt) - Date.parse(b.lastAt)).at(-1) ?? null;
 }
 
+/** 사고 선례 1건 — 현재 사고 이전의 같은 reason 종료 기록(결정론 · 기록된 실제 exit 만). */
+export interface IncidentPrecedent {
+  runId: string;
+  reason: string;
+  status: number | null;
+  signal: string | null;
+  at: string;
+  lastLines?: string[];
+}
+
+/**
+ * 사고 선례 연결 — 현재 사고(reason·at) 이전에 같은 reason 으로 종료된 기록된 실제 exit 만
+ * 돌려준다(유사 과거 지어내기 금지 · readRunExits 재사용 · READ-ONLY). 현재 runId 는 제외하고
+ * 시간 내림차순, 기본 5건까지. 기록이 없으면 빈 배열(«기록 없음»).
+ */
+export function findIncidentPrecedents(
+  current: { reason: string; at: string; runId?: string },
+  root: string,
+  { limit = 5 }: { limit?: number } = {},
+): IncidentPrecedent[] {
+  const at = Date.parse(current.at);
+  if (!current.reason.trim() || !Number.isFinite(at)) return [];
+  return readRunExits(root)
+    .filter((row) => row.reason === current.reason && row.runId !== current.runId
+      && Date.parse(row.at) < at)
+    .sort((a, b) => Date.parse(b.at) - Date.parse(a.at) || b.runId.localeCompare(a.runId))
+    .slice(0, Math.max(0, limit))
+    .map((row) => ({
+      runId: row.runId, reason: row.reason, status: row.status, signal: row.signal, at: row.at,
+      ...(Array.isArray(row.lastLines) ? { lastLines: row.lastLines } : {}),
+    }));
+}
+
 export function formatIncidentBurstWarning(burst: IncidentBurst): string {
   const time = new Date(Date.parse(burst.lastAt) + KST_OFFSET_MS).toISOString().slice(11, 16);
   const owner = burst.seat || burst.entrance ? ` [seat=${burst.seat ?? '-'} entrance=${burst.entrance ?? '-'}]` : '';

package/src/harness/launch-utterance-ledger.ts

@@ -0,0 +1,208 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, writeSync } from 'node:fs';
+import { join, parse, resolve } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { debug } from '../debug/log.js';
+
+/** Product ledger of the raw first text a launch entrance received (say · hand · ask-file).
+ *  Auxiliary evidence: preparing or appending never refuses a launch — failures are observed. */
+export interface LaunchUtteranceStart {
+  readonly event: 'start';
+  readonly launchId: string;
+  readonly source: 'say' | 'hand' | 'ask-file';
+  readonly utterance: string;
+  /** sha256 of the UTF-8 bytes of `utterance` (or of the raw bytes when given). */
+  readonly sha256: string;
+  /** Present only when the raw source bytes are not lossless UTF-8 (ask-file). */
+  readonly utteranceBase64?: string;
+  /** Present for `say`: the exact argv words the process received. */
+  readonly argv?: readonly string[];
+  /** The entrance was asked for a plan only (`--dry-run`) — the text was received, nothing launched. */
+  readonly dryRun?: true;
+  readonly at: string;
+}
+
+export interface LaunchUtteranceInput {
+  readonly source: LaunchUtteranceStart['source'];
+  readonly utterance: string;
+  readonly launchId: string;
+  readonly rawBytes?: Uint8Array;
+  readonly argv?: readonly string[];
+  readonly dryRun?: boolean;
+}
+
+const LAUNCH_ID = /^tl-[0-9a-f]{12}$/;
+const DATE_FILE = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+const DAY_MS = 86_400_000;
+
+/** Env contract of the one explicit hand→say pair (set by the hand launcher, consumed once by say). */
+export const HAND_LAUNCH_ID_ENV = 'ELANOUS_HAND_LAUNCH_ID';
+export const HAND_LAUNCH_SHA256_ENV = 'ELANOUS_HAND_LAUNCH_SHA256';
+export const HAND_LAUNCH_RUN_ENV = 'ELANOUS_HAND_LAUNCH_RUN';
+/** base64 of the hand's exact original text (untrimmed), so the paired child can re-record it byte-exact. */
+export const HAND_LAUNCH_ORIGINAL_ENV = 'ELANOUS_HAND_LAUNCH_ORIGINAL_B64';
+const MAX_ORIGINAL_ENV_BYTES = 64 * 1024;
+
+/** Same `tl-<12 hex>` shape the hand card contract already carries; minted fresh in every process. */
+export function newLaunchUtteranceId(): string { return `tl-${randomBytes(6).toString('hex')}`; }
+export function isLaunchUtteranceId(value: unknown): value is string { return typeof value === 'string' && LAUNCH_ID.test(value); }
+export function utteranceSha256(value: string | Uint8Array): string { return createHash('sha256').update(value).digest('hex'); }
+
+/** Env a hand launcher passes to its say child so that pair — and only that pair — shares the ID.
+ *  `sentence` is the exact argv word the say child receives; `original` is the hand's untrimmed text. */
+export function handLaunchPairEnv(launchId: string, sentence: string, runId: string, original?: string): Record<string, string> {
+  const originalB64 = original === undefined ? undefined : Buffer.from(original, 'utf8').toString('base64');
+  return {
+    [HAND_LAUNCH_ID_ENV]: launchId, [HAND_LAUNCH_SHA256_ENV]: utteranceSha256(sentence), [HAND_LAUNCH_RUN_ENV]: runId,
+    ...(originalB64 !== undefined && originalB64.length <= MAX_ORIGINAL_ENV_BYTES ? { [HAND_LAUNCH_ORIGINAL_ENV]: originalB64 } : {}),
+  };
+}
+
+/** Hand launcher seam: only a `harness say <sentence>` launch with a launchId ⊕ runId gets the pair env
+ *  (ID ⊕ sentence sha ⊕ runId ⊕ exact original). Any other launch context passes through unchanged. */
+export function withHandLaunchPairContext<C extends { launchId?: string; runId?: string; env: Record<string, string>; launchUtterance?: string }>(
+  args: readonly string[], context: C,
+): C {
+  const sayAt = args.indexOf('say');
+  const sentence = args.at(-1);
+  if (!context.launchId || !context.runId || sayAt < 1 || args[sayAt - 1] !== 'harness' || sentence === undefined || sayAt === args.length - 1) return context;
+  return { ...context, env: { ...context.env, ...handLaunchPairEnv(context.launchId, sentence, context.runId, context.launchUtterance) } };
+}
+
+/** Resolve the say launchId: inherit only when the env pair matches this exact sentence and run, then
+ *  remove the pair from `env` so no descendant or later say in this process can reuse the ID.
+ *  When paired, `utterance` is the hand's exact original text (falls back to the sentence). */
+export function consumeHandLaunchId(sentence: string, env: NodeJS.ProcessEnv = process.env, runIdEnv = 'ELANOUS_RUN_ID'): {
+  launchId: string; inherited: boolean; utterance: string;
+} {
+  const inherited = env[HAND_LAUNCH_ID_ENV];
+  const sha = env[HAND_LAUNCH_SHA256_ENV];
+  const run = env[HAND_LAUNCH_RUN_ENV];
+  const originalB64 = env[HAND_LAUNCH_ORIGINAL_ENV];
+  for (const key of [HAND_LAUNCH_ID_ENV, HAND_LAUNCH_SHA256_ENV, HAND_LAUNCH_RUN_ENV, HAND_LAUNCH_ORIGINAL_ENV]) delete env[key];
+  const paired = isLaunchUtteranceId(inherited) && sha === utteranceSha256(sentence)
+    && typeof run === 'string' && run.length > 0 && env[runIdEnv] === run;
+  if (inherited !== undefined && !paired) {
+    try { debug.log('harness.launch-utterance', 'inherit-refused', { hasSha: sha !== undefined, hasRun: run !== undefined }); } catch { /* fail-soft */ }
+  }
+  if (!paired) return { launchId: newLaunchUtteranceId(), inherited: false, utterance: sentence };
+  const original = originalB64 === undefined ? undefined : Buffer.from(originalB64, 'base64').toString('utf8');
+  const utterance = original !== undefined && original.trim() === sentence.trim() ? original : sentence;
+  return { launchId: inherited, inherited: true, utterance };
+}
+
+/** Symlink policy over every component of `path`, parents included: a symlink owned by the system
+ *  (uid 0 — e.g. macOS `/var` · `/tmp`) is an OS alias and allowed; any other symlink is refused, so a
+ *  user-made link can never redirect one instance's ledger into another instance. */
+export function assertLedgerPathPolicy(path: string): void {
+  if (!path.trim()) throw new Error('ledger path must not be empty');
+  const absolute = resolve(path);
+  let part = parse(absolute).root;
+  for (const segment of absolute.slice(part.length).split('/').filter(Boolean)) {
+    part = join(part, segment);
+    let stat;
+    try { stat = lstatSync(part); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+      throw error;
+    }
+    if (stat.isSymbolicLink() && stat.uid !== 0) throw new Error(`ledger symlink refused: ${part}`);
+  }
+}
+
+export function launchUtteranceDir(root: string = effectiveInstanceRoot()): string {
+  return join(resolve(root), 'launch-utterances');
+}
+
+function observeFailure(operation: 'prepare' | 'append' | 'query', error: unknown, extra: Record<string, unknown> = {}): void {
+  const reason = error instanceof Error ? error.message : String(error);
+  try { debug.log('harness.launch-utterance', `${operation}-failed`, { operation, reason, ...extra }, { level: 'warn' }); } catch { /* logging must not block launch */ }
+  try { console.error(`[launch-utterance] ${operation} failed: ${reason}`); } catch { /* fail-soft */ }
+}
+
+function buildRow(input: LaunchUtteranceInput, now: Date): LaunchUtteranceStart {
+  const raw = input.rawBytes;
+  const lossy = raw !== undefined && !Buffer.from(input.utterance, 'utf8').equals(Buffer.from(raw));
+  return {
+    event: 'start',
+    launchId: input.launchId,
+    source: input.source,
+    utterance: input.utterance,
+    sha256: utteranceSha256(raw ?? input.utterance),
+    ...(lossy ? { utteranceBase64: Buffer.from(raw).toString('base64') } : {}),
+    ...(input.argv ? { argv: [...input.argv] } : {}),
+    ...(input.dryRun === true ? { dryRun: true as const } : {}),
+    at: now.toISOString(),
+  };
+}
+
+/** Append one start row to this instance's date file. Returns whether it landed; never throws. */
+export function recordLaunchUtterance(
+  input: LaunchUtteranceInput,
+  root: string = effectiveInstanceRoot(),
+  now: Date = new Date(),
+): boolean {
+  let dir: string;
+  let row: string;
+  try {
+    if (!isLaunchUtteranceId(input.launchId)) throw new Error(`invalid launchId: ${String(input.launchId)}`);
+    dir = launchUtteranceDir(root);
+    assertLedgerPathPolicy(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    assertLedgerPathPolicy(dir);
+    if (!lstatSync(dir).isDirectory()) throw new Error(`ledger dir is not a directory: ${dir}`);
+    row = `${JSON.stringify(buildRow(input, now))}\n`;
+  } catch (error) { observeFailure('prepare', error, { source: input.source, launchId: input.launchId }); return false; }
+  try {
+    const file = join(dir, `${now.toISOString().slice(0, 10)}.jsonl`);
+    const fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+      if (!fstatSync(fd).isFile()) throw new Error(`ledger file is not a regular file: ${file}`);
+      writeSync(fd, row);
+    } finally { closeSync(fd); }
+    try { debug.log('harness.launch-utterance', 'recorded', { source: input.source, launchId: input.launchId }); } catch { /* fail-soft */ }
+    return true;
+  } catch (error) { observeFailure('append', error, { source: input.source, launchId: input.launchId }); return false; }
+}
+
+function readNoFollow(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    if (!fstatSync(fd).isFile()) throw new Error(`ledger file is not a regular file: ${file}`);
+    return readFileSync(fd, 'utf8');
+  } finally { closeSync(fd); }
+}
+
+/** Reads only this instance's date files that overlap [now - sinceMs, now], and rows inside that window. */
+export function queryLaunchUtterances(options: { root?: string; sinceMs?: number; now?: Date } = {}): LaunchUtteranceStart[] {
+  const now = options.now ?? new Date();
+  const sinceMs = options.sinceMs ?? DAY_MS;
+  if (!Number.isFinite(sinceMs) || sinceMs < 0 || sinceMs > 31 * DAY_MS) throw new Error('invalid ledger query window');
+  const until = now.getTime();
+  const from = until - sinceMs;
+  const dir = launchUtteranceDir(options.root);
+  let names: string[];
+  try {
+    assertLedgerPathPolicy(dir);
+    if (!lstatSync(dir).isDirectory()) throw new Error(`ledger dir is not a directory: ${dir}`);
+    names = readdirSync(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') observeFailure('query', error);
+    return [];
+  }
+  const rows: LaunchUtteranceStart[] = [];
+  for (const name of names.filter((n) => DATE_FILE.test(n)).sort()) {
+    const day = Date.parse(`${name.slice(0, 10)}T00:00:00.000Z`);
+    if (!Number.isFinite(day) || day > until || day + DAY_MS <= from) continue;
+    let text: string;
+    try { text = readNoFollow(join(dir, name)); } catch (error) { observeFailure('query', error, { file: name }); continue; }
+    for (const line of text.split('\n')) {
+      if (!line) continue;
+      try {
+        const row = JSON.parse(line) as LaunchUtteranceStart;
+        const at = Date.parse(row.at);
+        if (row.event === 'start' && typeof row.utterance === 'string' && Number.isFinite(at) && at >= from && at <= until) rows.push(row);
+      } catch { /* skip torn line */ }
+    }
+  }
+  return rows;
+}

package/src/impl-discipline/detector.ts

@@ -1,6 +1,6 @@
 // Phase detector for implementation discipline.
 //
-// Given the current turn's user text, classify into one of three
+// Given the current turn's user text, classify into one of four
 // phases. The system-prompt builder reads this result to decide
 // which discipline guidance (if any) to inject as a system message.
 //
@@ -8,15 +8,16 @@
 //   plan-loaded         — PLAN-*.md / HANDOFF-*.md / SPEC-*.md file-ref
 //                         OR Korean/English doc keyword (핸드오프, 플랜
 //                         문서, handoff, plan doc, 스펙 문서).
+//   design-first        — implementation request contains an explicit new
+//                         project, empty repository, or from-scratch signal.
 //   implementation-ready — starts with an implementation verb
 //                         (구현/implement/build/포팅/port/만들어) AND
 //                         NOT paired with an exploration verb
 //                         (설명/분석/리뷰).
 //   idle                — everything else.
 //
-// plan-loaded wins over implementation-ready when both would fire —
-// when a plan doc is in play, the LLM must read-and-confirm before
-// diving into edits, even if the user also said "구현해".
+// An explicit new-project request wins over plan-loaded; otherwise the
+// existing plan-loaded and implementation-ready precedence is unchanged.
 
 import type { DetectInput, ImplPhase } from './types.js';
 
@@ -38,6 +39,11 @@ const DOC_KEYWORDS = [
 ];
 
 const IMPL_VERB_RE = /(^|[\s\u3000])(구현|implement|build|포팅|port|만들어)/i;
+const PROJECT_IMPL_VERB_RE = /(^|[\s\u3000])(구현|implement|build|포팅|port|개발|develop|생성|create|만들어)/i;
+const NEW_PROJECT_SIGNAL_RE = /(?:새(?:로운)?\s*(?:저장소|프로젝트)|빈\s*저장소|(?:new|empty)\s+(?:repository|repo|project)\b)/i;
+const FROM_SCRATCH_RE = /(?:\bfrom\s+scratch\b|처음부터)/i;
+const PROJECT_TARGET_RE = /(?:\b(?:project|app|service)\b|프로젝트|앱|서비스|웹앱)/i;
+const FUNCTION_TARGET_RE = /(?:함수|function|method)/i;
 
 // Exploration verbs that, when co-occurring with an implementation
 // verb, downgrade the turn to idle. "이 함수 구현 방식 분석해줘"
@@ -58,6 +64,12 @@ export function detectImplPhase(input: DetectInput): ImplPhase {
   if (!trimmed) return 'idle';
   const lower = trimmed.toLowerCase();
 
+  const explicitProjectScope = NEW_PROJECT_SIGNAL_RE.test(trimmed)
+    || (FROM_SCRATCH_RE.test(trimmed) && PROJECT_TARGET_RE.test(trimmed) && !FUNCTION_TARGET_RE.test(trimmed));
+  if (explicitProjectScope && PROJECT_IMPL_VERB_RE.test(trimmed)) {
+    return 'design-first';
+  }
+
   if (FILE_REF_RE.test(trimmed) || hasDocKeyword(lower)) {
     return 'plan-loaded';
   }

package/src/impl-discipline/system-prompt.ts

@@ -23,6 +23,15 @@ const PLAN_LOADED_PROMPT = `# 플랜/핸드오프 문서 참조 감지
 5. "should I proceed?" 같은 열린 질문 금지 — 확정된 선택지(2~4개) 로 묻거나 plan 을 제출.
 6. 사용자 확인이 명확히 있을 때만 Edit/Write 로 진입.`;
 
+const DESIGN_FIRST_PROMPT = `# 새 프로젝트 구현 요청 — RFC 먼저
+
+사용자가 새 저장소나 새 프로젝트의 구현을 요청했습니다. 앱 코드·프로젝트 설정을 쓰거나 시험을 실행하기 전에 저장소 루트에 RFC.md 초안을 작성하고 명시적 승인을 요청하세요.
+
+1. 요청에 PLAN/HANDOFF/SPEC 문서가 있으면 먼저 읽고 RFC 초안에 목표·범위·비목표·설계·수용 기준을 반영하세요.
+2. RFC 초안과 결정이 필요한 항목을 제시하고 승인을 요청하세요.
+3. 승인 전에는 애플리케이션 코드·설정을 만들거나 시험을 실행하지 마세요.
+4. 승인 뒤 RFC와 대조해 구현을 시작하세요.`;
+
 const IMPLEMENTATION_READY_PROMPT = `# 명시적 구현 요청 감지
 
 사용자가 구현을 요청했습니다. **구현 요청 자체가 실행 승인입니다.** 계획을 설명한 뒤 멈추지 말고, 이번 턴 안에서 실제 코드 편집(Edit/Write)까지 진행하세요.
@@ -79,6 +88,7 @@ function promptWithNativeStructure(phase: ImplPhase, enabledTools: readonly Nati
   const { listNativeToolDisplayNamesByKind } = require('../native-tool-catalog.js') as typeof import('../native-tool-catalog.js');
   const namesByKind = listNativeToolDisplayNamesByKind(enabledTools);
   switch (phase) {
+    case 'design-first': return DESIGN_FIRST_PROMPT;
     case 'plan-loaded': {
       let prompt = PLAN_LOADED_PROMPT;
       prompt = replaceDirective(prompt, '1. 먼저 Read 로 문서 전체를 읽으세요 (offset/limit 없이).', namesByKind, ['read']);
@@ -111,6 +121,7 @@ export function promptForPhase(phase: ImplPhase, options: ImplDisciplinePromptOp
   }
   switch (phase) {
     case 'plan-loaded': return PLAN_LOADED_PROMPT;
+    case 'design-first': return DESIGN_FIRST_PROMPT;
     case 'implementation-ready': return IMPLEMENTATION_READY_PROMPT;
     case 'idle': return '';
   }

package/src/impl-discipline/types.ts

@@ -1,11 +1,11 @@
 // Implementation-discipline phase types.
 //
-// The detector maps a user turn to one of three phases; the
+// The detector maps a user turn to one of four phases; the
 // system-prompt builder emits different guidance per phase. State is
 // derived per-turn (stateless) so a wrong classification self-heals
 // on the next turn.
 
-export type ImplPhase = 'idle' | 'plan-loaded' | 'implementation-ready';
+export type ImplPhase = 'idle' | 'plan-loaded' | 'design-first' | 'implementation-ready';
 
 export interface DetectInput {
   /** Raw user text for the current turn. */