elanous 0.2.17 → 0.2.19

package/src/self-dev/pr-preview.ts

@@ -0,0 +1,179 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface PreviewOptions {
+  target: string;
+  repoRoot: string;
+  scenario?: string;
+  /** Main-based combined preview: only existing config paths may be enabled. */
+  flags?: readonly string[];
+  commentPr?: number;
+}
+export interface PreviewResult {
+  target: string;
+  head: string;
+  scenario: string;
+  status: 'passed' | 'friction';
+  report: string;
+  prNumber?: number;
+  commented: boolean;
+}
+export function readPreviewResult(directory: string): PreviewResult | null {
+  try {
+    const value = JSON.parse(readFileSync(join(directory, 'preview-result.json'), 'utf8')) as PreviewResult;
+    return value && (value.status === 'passed' || value.status === 'friction') && typeof value.head === 'string' ? value : null;
+  } catch { return null; }
+}
+
+export interface PreviewDeps {
+  run?: (command: string, args: readonly string[], cwd: string, timeoutMs?: number) => { status: number | null; stdout: string; stderr: string };
+  makeDir?: () => string;
+  dispose?: (directory: string) => void;
+  wait?: (ms: number) => Promise<void>;
+  /** Probe a test-mode daemon without injecting a global HTTP client into the command runner. */
+  probePwa?: (url: string) => Promise<boolean>;
+}
+
+const SCENARIOS: Record<string, string> = {
+  S2: '/help', S3: '/status', S6: '/now', S7: '/term list', S8: '/model', S9: '/harness',
+};
+
+export function previewScenarioInput(scenario: string): string {
+  const text = Object.hasOwn(SCENARIOS, scenario) ? SCENARIOS[scenario] : undefined;
+  if (!text) throw new Error(`TUI-COMFORT §4: unsupported scenario ${scenario}; available: ${Object.keys(SCENARIOS).join(', ')}`);
+  return text;
+}
+
+const defaultRun: NonNullable<PreviewDeps['run']> = (command, args, cwd, timeoutMs = 120_000) => {
+  const r = spawnSync(command, [...args], { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 });
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? String(r.error ?? '') };
+};
+
+/** Build and exercise a detached head, never the caller's checkout. The report is posted only after measurement. */
+export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps = {}): Promise<PreviewResult> {
+  const run = deps.run ?? defaultRun;
+  const root = resolve(options.repoRoot);
+  const target = options.target.trim();
+  if (!target || target.startsWith('-') || /[\s\x00-\x1f]/u.test(target)) throw new Error('preview: invalid PR number or branch');
+  const isPr = /^[1-9]\d*$/u.test(target);
+  if (isPr && !Number.isSafeInteger(Number(target))) throw new Error('preview: invalid PR number');
+  if (/^\d+$/u.test(target) && !isPr) throw new Error('preview: invalid PR number');
+  if (options.commentPr !== undefined && (!Number.isSafeInteger(options.commentPr) || options.commentPr <= 0)) throw new Error('preview: invalid --comment-pr');
+  if (target === 'main' && options.commentPr === undefined) throw new Error('preview: main ⊕ flags requires --comment-pr <PR number> to publish the result');
+  if (isPr && options.commentPr !== undefined && options.commentPr !== Number(target)) throw new Error('preview: --comment-pr must match the target PR');
+  const flags = options.flags ?? [];
+  if (flags.length && target !== 'main') throw new Error('preview: --flag requires main (main ⊕ feature flags)');
+  if (flags.some((flag) => !/^[a-zA-Z][\w-]*(?:\.[a-zA-Z][\w-]*)+$/u.test(flag))) throw new Error('preview: --flag expects an existing dotted config path');
+  const scenario = options.scenario ?? 'S2';
+  const input = previewScenarioInput(scenario);
+  const check = (command: string, args: readonly string[], cwd: string, timeout?: number): string => {
+    const r = run(command, args, cwd, timeout);
+    if (r.status !== 0) throw new Error(`preview: ${command} ${args.join(' ')} failed: ${(r.stdout + '\n' + r.stderr).slice(-600)}`);
+    return r.stdout.trim();
+  };
+  let prNumber = isPr ? Number(target) : options.commentPr;
+  let branchPrHead: string | undefined;
+  let ref = target;
+  if (isPr) {
+    const pr = JSON.parse(check('gh', ['pr', 'view', target, '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+    if (pr.number !== Number(target) || !/^[0-9a-f]{40}$/iu.test(pr.headRefOid ?? '')) throw new Error('preview: PR head is unavailable');
+    ref = pr.headRefOid!;
+  } else if (target !== 'main') {
+    check('git', ['check-ref-format', '--branch', target], root);
+    if (options.commentPr === undefined) {
+      const matching = JSON.parse(check('gh', ['pr', 'list', '--head', target, '--state', 'open', '--json', 'number,headRefOid'], root)) as Array<{ number?: number; headRefOid?: string }>;
+      if (matching.length !== 1 || !Number.isSafeInteger(matching[0]?.number)) throw new Error('preview: branch has no unique open PR; use --comment-pr <PR number>');
+      prNumber = matching[0]!.number;
+      branchPrHead = matching[0]!.headRefOid;
+    }
+  }
+  if (isPr && run('git', ['cat-file', '-e', `${ref}^{commit}`], root).status !== 0) {
+    check('git', ['fetch', '--no-tags', 'origin', `pull/${target}/head`], root, 120_000);
+    const fetched = check('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], root);
+    if (fetched !== ref) throw new Error('preview: PR head changed while fetching; retry');
+  }
+  const head = check('git', ['rev-parse', '--verify', `${ref}^{commit}`], root);
+  if (!/^[0-9a-f]{40}$/iu.test(head)) throw new Error('preview: unresolved commit');
+  if (target !== 'main' && !isPr) {
+    const pr = JSON.parse(check('gh', ['pr', 'view', String(prNumber), '--json', 'headRefOid,headRefName'], root)) as { headRefOid?: string; headRefName?: string };
+    if (pr.headRefName !== target || pr.headRefOid !== head || (branchPrHead !== undefined && branchPrHead !== head)) throw new Error('preview: branch does not match the target PR head; use the PR number');
+  }
+  const directory = (deps.makeDir ?? (() => {
+    const previews = join(root, '.elanous-test', 'previews');
+    mkdirSync(previews, { recursive: true });
+    return mkdtempSync(join(previews, 'preview-'));
+  }))();
+  const worktree = join(directory, 'checkout');
+  let added = false;
+  let heldPty: string | undefined;
+  let report = '';
+  const wait = deps.wait ?? ((ms: number) => new Promise<void>((done) => setTimeout(done, ms)));
+  try {
+    check('git', ['worktree', 'add', '--detach', worktree, head], root);
+    added = true;
+    check('bun', ['install', '--frozen-lockfile'], worktree, 300_000);
+    check('bun', ['install', '--frozen-lockfile'], join(worktree, 'apps/pwa'), 300_000);
+    for (const flag of flags) {
+      const existing = check('bun', ['bin/elanous.mjs', '--test', 'config', 'get', flag], worktree);
+      if (existing !== 'true' && existing !== 'false') throw new Error(`preview: ${flag} is not a boolean feature flag`);
+      check('bun', ['bin/elanous.mjs', '--test', 'config', 'set', flag, 'true'], worktree);
+    }
+    check('bun', ['bin/elanous.mjs', '--test', 'nexus', 'build', '--cwd', join(worktree, 'apps/pwa')], worktree, 300_000);
+    const pwa = check('bun', ['bin/elanous.mjs', '--test', 'nexus', 'run', '--test', '--tool-cwd', worktree], worktree, 120_000);
+    const port = /\bnexus\s+:(314[5-9]\d)\b/u.exec(pwa)?.[1];
+    const endpoint = port ? `http://127.0.0.1:${port}` : undefined;
+    if (!endpoint) throw new Error('preview: P-1 has no local test endpoint');
+    const probeOnce = deps.probePwa ?? (async (url: string) => {
+      try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+        return response.ok && (await response.text()).includes('<');
+      } catch { return false; }
+    });
+    // `nexus run` detaches and returns before the daemon listens — its exit is not readiness. Poll.
+    let probe = false;
+    for (let attempt = 0; attempt < 60 && !probe; attempt++) {
+      probe = await probeOnce(`${endpoint}/app/`);
+      if (!probe) await wait(1000);
+    }
+    if (!probe) throw new Error('preview: P-1 did not serve the built PWA');
+    const version = check('bun', ['bin/elanous.mjs', '--version'], worktree);
+    if (!version) throw new Error('preview: B-1 version probe returned no output');
+    const held = check('bun', ['bin/elanous.mjs', '--test', 'dev', '--elanous', '--hold', '--cwd', worktree, '--isolated-root', join(directory, 'tui'), '--json'], worktree, 120_000);
+    const last = held.split('\n').reverse().find((line: string) => line.trim().startsWith('{'));
+    const pty = last ? JSON.parse(last) as { held?: boolean; ptyId?: string } : {};
+    if (pty.held !== true || !/^pty_[\w-]+$/u.test(pty.ptyId ?? '')) throw new Error('preview: B-1 held TUI did not return a PTY reference');
+    heldPty = pty.ptyId;
+    const snapshotArgs = ['bin/elanous.mjs', '--test', 'pty', 'snapshot', pty.ptyId!] as const;
+    const before = check('bun', snapshotArgs, worktree);
+    check('bun', ['bin/elanous.mjs', '--test', 'pty', 'text', pty.ptyId!, input, '--enter'], worktree);
+    // A constant sleep misses slow frames under load — poll until the screen answers (≤ 20s).
+    let snapshot = '';
+    for (let attempt = 0; attempt < 20; attempt++) {
+      await wait(1000);
+      snapshot = check('bun', snapshotArgs, worktree);
+      if (snapshot && snapshot !== 'ok' && snapshot !== before) break;
+    }
+    if (!snapshot || snapshot === 'ok' || snapshot === before) throw new Error('preview: inner PTY did not show a response to the scenario input within 20s');
+    report = `| Check | Observation |\n|---|---|\n| head | \`${head}\` |\n| B-1 version | ${version.slice(0, 120)} |\n| P-1 PWA | \`${endpoint}/app/\` served the built PWA |\n| TUI-COMFORT §4 ${scenario} | \`${input}\` → snapshot captured |\n\n<details><summary>Inner PTY snapshot</summary>\n\n\`\`\`text\n${snapshot.slice(-3000).replaceAll('```', "'''")}\n\`\`\`\n</details>`;
+  } catch (error) {
+    report = `| Check | Friction |\n|---|---|\n| head | \`${head}\` |\n| TUI-COMFORT §4 ${scenario} | ${String(error).replaceAll('|', '\\|').slice(0, 700)} |`;
+  } finally {
+    if (added) {
+      if (heldPty) run('bun', ['bin/elanous.mjs', '--test', 'pty', 'key', heldPty, 'ctrl+c'], worktree, 30_000);
+      run('bun', ['bin/elanous.mjs', '--test', 'nexus', 'run', '--test', '--stop'], worktree, 30_000);
+      const removed = run('git', ['worktree', 'remove', '--force', worktree], root, 30_000);
+      if (removed.status !== 0) throw new Error(`preview: failed to remove isolated worktree: ${removed.stderr}`);
+    }
+    (deps.dispose ?? ((dir) => rmSync(dir, { recursive: true, force: true })))(directory);
+  }
+  const status = report.includes('| Friction |') ? 'friction' : 'passed';
+  const body = `## PR preview — ${target} (${status})\n\n${report}`;
+  if (prNumber === undefined) throw new Error('preview: cannot comment without a PR number');
+  check('gh', ['pr', 'comment', String(prNumber), '--body', body], root);
+  const result: PreviewResult = { target, head, scenario, status, report: body, prNumber, commented: true };
+  const resultDir = join(root, '.elanous-test');
+  mkdirSync(resultDir, { recursive: true });
+  writeFileSync(join(resultDir, 'preview-result.json'), JSON.stringify(result), { mode: 0o600 });
+  return result;
+}

package/src/self-dev/round-pr-supersede.ts

@@ -0,0 +1,244 @@
+// DRAFT-TRIAGE (TC 10-07) — a supervisor rework round of the same run and goal opens a new PR
+// (new task id → new goal hash → new branch). Continuing the branch would mean pinning the shard
+// identity and the Pod child's run suffix, so this closes the previous round's draft instead:
+// label `elanous:superseded`, comment with the newer PR link, close. Same run = one tracker per
+// supervised invocation; same goal = `resumeKey(feature)`, the key the resume path already uses.
+
+import { spawnSync } from 'node:child_process';
+import { debug } from '../debug/log.js';
+import { PR_LABELS } from '../github/pr-labels.js';
+import { PROTECTED_LABELS } from './draft-triage-rules.js';
+import { resumeKey, type SelfDevJobResult } from './orchestrate.js';
+
+const SUPERSEDED_LABEL = PR_LABELS.find((label) => label.name.endsWith(':superseded'))!.name;
+
+export interface RoundPrRef {
+  readonly repository: string;
+  readonly number: number;
+  readonly url: string;
+}
+
+export interface RoundPrView {
+  readonly state: string;
+  readonly isDraft: boolean;
+  readonly labels: readonly string[];
+  readonly mergedAt?: string | null;
+  /** Comment bodies — a link already posted (even by a write that reported failure) is not posted again.
+   *  An adapter that cannot read them returns a null view, so nothing is written. */
+  readonly comments: readonly string[];
+}
+
+/** gh seams. A null view or a false write means «not observed / not applied» — never a reason to close. */
+export interface RoundPrAdapters {
+  view(pr: RoundPrRef): RoundPrView | null;
+  addLabel(pr: RoundPrRef, label: string): boolean;
+  comment(pr: RoundPrRef, body: string): boolean;
+  close(pr: RoundPrRef): boolean;
+}
+
+type SupersedeOutcome =
+  | { kind: 'superseded'; round: number; prevPr: number; pr: number }
+  | { kind: 'kept'; round: number; prevPr: number; pr: number; reason: string };
+
+type RoundPrOutcome = SupersedeOutcome | { kind: 'continued'; round: number; prevPr: number; pr: number };
+
+export function roundPrRef(prUrl: string | undefined): RoundPrRef | null {
+  if (!prUrl) return null;
+  try {
+    const url = new URL(prUrl.trim());
+    const match = /^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/.exec(url.pathname);
+    return url.protocol === 'https:' && url.hostname === 'github.com' && match
+      // GitHub owner/repo names are case-insensitive: one PR has one identity.
+      ? { repository: `${match[1]}/${match[2]}`.toLowerCase(), number: Number(match[3]), url: `https://github.com/${match[1]}/${match[2]}/pull/${match[3]}` }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+const prId = (pr: RoundPrRef): string => `${pr.repository}#${pr.number}`;
+
+const commentMarker = (prev: RoundPrRef, next: RoundPrRef): string => `<!-- elanous:round-pr-superseded ${prId(prev)} -> ${prId(next)} -->`;
+
+function roundPrSupersedeComment(input: { runId: string | null; round: number; prev?: RoundPrRef; next: RoundPrRef }): string {
+  return `${input.prev ? `${commentMarker(input.prev, input.next)}\n` : ''}Supervisor round ${input.round}${input.runId ? ` of ${input.runId}` : ''}: superseded by #${input.next.number} (${input.next.url}) — same run and goal, the rework round opened a new PR. Branch preserved.`;
+}
+
+/**
+ * One tracker per supervised run. `record(results, round)` after each round: for every goal whose newest PR
+ * differs from a PR an earlier round of this run opened, the earlier one is superseded exactly once —
+ * only while it is an open draft, unmerged, without a protected label, in the same repository.
+ */
+export function createRoundPrTracker(input: {
+  runId: string | null;
+  adapters: RoundPrAdapters;
+  observe?: (event: string, data: Record<string, unknown>) => void;
+}) {
+  const byGoal = new Map<string, Array<{ ref: RoundPrRef; merged: boolean; round: number }>>();
+  const handled = new Set<string>();
+  // The link comment is written once per PR even when the close after it fails and is retried next round.
+  const commented = new Set<string>();
+  const emit = (event: string, data: Record<string, unknown>): void => {
+    try { (input.observe ?? ((e, d) => debug.log('self-dev.supervisor', e, d)))(event, data); } catch { /* observation must not interrupt supervision */ }
+  };
+
+  const supersede = (prev: RoundPrRef, next: RoundPrRef, round: number): SupersedeOutcome => {
+    const base = { round, prevPr: prev.number, pr: next.number };
+    if (prev.repository !== next.repository) return { kind: 'kept', ...base, reason: 'other-repository' };
+    if (prId(prev) === prId(next)) return { kind: 'kept', ...base, reason: 'same-pr' };
+    let view: RoundPrView | null = null;
+    try { view = input.adapters.view(prev); } catch { view = null; }
+    if (!view) return { kind: 'kept', ...base, reason: 'view-unobserved' };
+    if (view.state !== 'OPEN' || view.mergedAt) return { kind: 'kept', ...base, reason: `state:${view.mergedAt ? 'MERGED' : view.state}` };
+    if (!view.isDraft) return { kind: 'kept', ...base, reason: 'not-draft' };
+    const held = view.labels.find((label) => PROTECTED_LABELS.has(label));
+    if (held) return { kind: 'kept', ...base, reason: `label:${held}` };
+    // Label first: a closed but unlabelled PR would fall outside every later sweep (draft-sweep rule).
+    let labelled = view.labels.includes(SUPERSEDED_LABEL);
+    if (!labelled) {
+      try { labelled = input.adapters.addLabel(prev, SUPERSEDED_LABEL); } catch { labelled = false; }
+    }
+    if (!labelled) return { kind: 'kept', ...base, reason: 'label-failed' };
+    const id = prId(prev);
+    if (view.comments.some((body) => body.includes(commentMarker(prev, next)))) commented.add(id);
+    if (!commented.has(id)) {
+      let ok = false;
+      try { ok = input.adapters.comment(prev, roundPrSupersedeComment({ runId: input.runId, round, prev, next })); } catch { ok = false; }
+      if (!ok) return { kind: 'kept', ...base, reason: 'comment-failed' };
+      commented.add(id);
+    }
+    let closed = false;
+    try { closed = input.adapters.close(prev); } catch { closed = false; }
+    return closed ? { kind: 'superseded', ...base } : { kind: 'kept', ...base, reason: 'close-failed' };
+  };
+
+  /** Unfinished supersedes, keyed by the earlier PR; `next` stays the first successor so retries link the same PR. */
+  const pending = new Map<string, { prev: { ref: RoundPrRef; merged: boolean }; next: RoundPrRef }>();
+
+  return {
+    /** Record one round's results, then (re)try every unfinished supersede — even when this round has no PR. */
+    record(results: readonly SelfDevJobResult[], round: number): RoundPrOutcome[] {
+      const outcomes: RoundPrOutcome[] = [];
+      for (const result of results) {
+        const ref = roundPrRef(result.prUrl);
+        if (!ref) continue;
+        const key = resumeKey(result.feature);
+        const seen = byGoal.get(key) ?? [];
+        // A PR already seen in this run is never a new successor — only a new PR is.
+        const known = seen.find((entry) => prId(entry.ref) === prId(ref));
+        if (known) {
+          known.merged ||= result.merged === true;
+          // A carried (skipped) shard is not a new round's work.
+          if (result.resumeDisposition !== 'skip' && known.round < round) {
+            outcomes.push({ kind: 'continued', round, prevPr: known.ref.number, pr: ref.number });
+            emit('round-pr-continued', { runId: input.runId, round, prevPr: known.ref.number, pr: ref.number });
+          }
+          continue;
+        }
+        // A carried result this run has not seen before was opened by an earlier process — not this run's PR,
+        // so it is neither recorded nor allowed to supersede anything.
+        if (result.resumeDisposition === 'skip') continue;
+        // Only PRs opened in an earlier round are superseded — never a sibling of the same round.
+        for (const prev of seen) {
+          const id = prId(prev.ref);
+          if (prev.round >= round || handled.has(id) || pending.has(id)) continue;
+          if (prev.merged) {
+            handled.add(id);
+            outcomes.push({ kind: 'kept', round, prevPr: prev.ref.number, pr: ref.number, reason: 'merged' });
+            continue;
+          }
+          pending.set(id, { prev, next: ref });
+        }
+        seen.push({ ref, merged: result.merged === true, round });
+        byGoal.set(key, seen);
+      }
+      for (const [id, { prev: entry, next }] of [...pending]) {
+        const prev = entry.ref;
+        // A result may have reported the earlier PR merged after it was queued — re-checked right before any write.
+        const outcome: SupersedeOutcome = entry.merged
+          ? { kind: 'kept', round, prevPr: prev.number, pr: next.number, reason: 'merged' }
+          : supersede(prev, next, round);
+        outcomes.push(outcome);
+        // Retry only what was not observed or not applied; a decided keep/supersede is final for this run.
+        if (outcome.kind === 'superseded' || !/^(?:view-unobserved|label-failed|comment-failed|close-failed)$/.test(outcome.reason)) {
+          handled.add(id);
+          pending.delete(id);
+        }
+        if (outcome.kind === 'superseded') {
+          emit('round-pr-superseded', { runId: input.runId, round, prevPr: prev.number, pr: next.number });
+        } else {
+          emit('round-pr-supersede-kept', { runId: input.runId, round, prevPr: prev.number, pr: next.number, reason: outcome.reason });
+        }
+      }
+      return outcomes;
+    },
+  };
+}
+
+function ghEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined && !/^(https?|all|no)_proxy$/i.test(k)) env[k] = v;
+  return env;
+}
+
+/** Real gh adapters: proxy variables removed, App identity when available (never the personal login by choice). */
+export async function defaultRoundPrAdapters(deps: {
+  appToken?: () => string | null;
+  run?: (args: string[], env: Record<string, string>) => { status: number | null; stdout: string };
+  inTest?: () => boolean;
+} = {}): Promise<RoundPrAdapters> {
+  const env = ghEnv();
+  let tokenSource: () => string | null = () => null;
+  try {
+    tokenSource = deps.appToken ?? (await import('../auth/github-app-token.js')).githubAutomationToken;
+  } catch { /* no App credential module — every write refuses */ }
+  const freshToken = (): string | null => { try { return tokenSource(); } catch { return null; } };
+  const gh = (args: string[], token?: string | null) => {
+    const callEnv = { ...env };
+    if (token) callEnv.GH_TOKEN = token;
+    return deps.run
+      ? deps.run(args, callEnv)
+      : spawnSync('gh', args, { encoding: 'utf8', env: callEnv as NodeJS.ProcessEnv, timeout: 30_000 });
+  };
+  // Writes (label · comment · close) run only as the automation App — the token is fetched per write, so a
+  // token that was missing or expired earlier in the run recovers; without it the write refuses and is retried.
+  // Reads may use the machine login.
+  const write = (op: string, pr: RoundPrRef, args: string[]): boolean => {
+    const token = freshToken();
+    if (!token) {
+      try { debug.log('self-dev.supervisor', 'round-pr-write-refused', { op, pr: pr.number, reason: 'no-app-token' }); } catch { /* fail-open */ }
+      return false;
+    }
+    return gh(args, token).status === 0;
+  };
+  const inTest = deps.inTest ?? ((): boolean => process.env.NODE_ENV === 'test');
+  return {
+    view(pr) {
+      if (inTest()) return null;
+      const out = gh(['pr', 'view', String(pr.number), '--repo', pr.repository, '--json', 'state,isDraft,labels,mergedAt,comments'], freshToken());
+      if (out.status !== 0) return null;
+      try {
+        const parsed = JSON.parse(out.stdout) as { state?: unknown; isDraft?: unknown; labels?: unknown; mergedAt?: unknown; comments?: unknown };
+        if (typeof parsed.state !== 'string' || typeof parsed.isDraft !== 'boolean' || !Array.isArray(parsed.labels)) return null;
+        const labels = parsed.labels.map((label) => (label as { name?: unknown })?.name);
+        if (labels.some((name) => typeof name !== 'string')) return null;
+        // Unverifiable comments make the whole view unobserved — no write may follow it.
+        if (!Array.isArray(parsed.comments)) return null;
+        const comments = parsed.comments.map((comment) => (comment as { body?: unknown })?.body);
+        if (comments.some((body) => typeof body !== 'string')) return null;
+        return { state: parsed.state, isDraft: parsed.isDraft, labels: labels as string[], mergedAt: typeof parsed.mergedAt === 'string' && parsed.mergedAt ? parsed.mergedAt : null, comments: comments as string[] };
+      } catch {
+        return null;
+      }
+    },
+    addLabel(pr, label) {
+      return !inTest() && write('label', pr, ['pr', 'edit', String(pr.number), '--repo', pr.repository, '--add-label', label]);
+    },
+    comment(pr, body) {
+      return !inTest() && write('comment', pr, ['pr', 'comment', String(pr.number), '--repo', pr.repository, '--body', body]);
+    },
+    close(pr) {
+      return !inTest() && write('close', pr, ['pr', 'close', String(pr.number), '--repo', pr.repository]);
+    },
+  };
+}

package/src/self-dev/run-supervisor.ts

@@ -7,6 +7,7 @@ import { recordSelfDevRunSupervisorStop, selfDevRunsDir } from './run-store.js';
 import { debug } from '../debug/log.js';
 import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
 import { routeSupervisorVerdict, type SupervisorNext } from './supervisor-verdict-edges.js';
+import { recordTaskAgentShadowMove, type TaskAgentShadowInput } from '../task-agent/shadow.js';
 
 export interface SupervisorRound {
   round: number;
@@ -461,6 +462,11 @@ export interface SuperviseRunOptions {
   runStore?: { runId?: string; operatorDir?: string; dir?: string; isolatedDir?: string };
   observe?: (event: string, data: Record<string, unknown>) => void;
   sweepPendingMerges?: typeof sweepFrozenMerges;
+  /**
+   * TASK-AGENT-SHADOW — 멈춤이 확정되면 판단부를 그림자로 부른다(기본 `recordTaskAgentShadowMove`).
+   * `false` 면 끈다. 던져도 런의 결말은 바뀌지 않는다(fail-soft).
+   */
+  taskAgentShadow?: ((input: TaskAgentShadowInput) => unknown) | false;
   observeDeliverables?: () => Promise<{
     readonly deployFindings: ReadonlyMap<string, { target: string; findings?: readonly DeployVerifyFinding[] | readonly unknown[] }>;
     readonly unmeasured: readonly unknown[];
@@ -614,6 +620,14 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
           });
         } catch { /* fail-open */ }
       }
+      if (decision.stopReason && opts.taskAgentShadow !== false) {
+        // TASK-AGENT-SHADOW — 판단부를 그림자로 부른다(실행 0). 어떤 오류도 런의 결말을 바꾸지 않는다.
+        try {
+          await (opts.taskAgentShadow ?? recordTaskAgentShadowMove)({ runId, stopReason: decision.stopReason, results });
+        } catch (error) {
+          try { debug.log('task-agent', 'shadow-move-failed', { runId, stopReason: decision.stopReason, error: String(error) }); } catch { /* fail-open */ }
+        }
+      }
       return results;
     }
 

package/src/self-dev/shard-run.ts

@@ -11,6 +11,7 @@ export interface ShardRunResult {
   shards: GateTestShard[];
   attempts: GateShardAttempt[];
   reason?: string;
+  measurementFailures?: number;
 }
 
 export type ShardProcess = (cwd: string, files: readonly string[]) => {
@@ -34,24 +35,39 @@ export function runShardedGateTests(
   if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid --shards count');
   const rss = new Map<string, number>();
   const seconds = new Map<string, number>();
+  const failedMeasurements: string[] = [];
   for (const file of [...new Set(files)]) {
     let sample: ReturnType<ShardProcess>;
     try {
       sample = run(cwd, [file]);
-    } catch (error) {
-      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: `measurement failed: ${file}: ${String(error)}` };
+    } catch {
+      failedMeasurements.push(file);
+      continue;
     }
-    if (![0, 1].includes(sample.exitCode ?? -1) || sample.signal || !sample.junit || !Number.isFinite(sample.rssMb) || !Number.isFinite(sample.seconds)) {
-      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: `measurement unavailable: ${file}` };
+    if (![0, 1].includes(sample.exitCode ?? -1) || sample.signal || !sample.junit
+      || !Number.isFinite(sample.rssMb) || sample.rssMb! <= 0
+      || !Number.isFinite(sample.seconds) || sample.seconds! < 0) {
+      failedMeasurements.push(file);
+      continue;
     }
     rss.set(file, sample.rssMb!);
     seconds.set(file, sample.seconds!);
   }
+  if (failedMeasurements.length) {
+    if (!rss.size) return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: 'no valid file measurements', measurementFailures: failedMeasurements.length };
+    const averageRss = [...rss.values()].reduce((sum, value) => sum + value, 0) / rss.size;
+    const averageSeconds = [...seconds.values()].reduce((sum, value) => sum + value, 0) / seconds.size;
+    for (const file of failedMeasurements) {
+      rss.set(file, averageRss);
+      seconds.set(file, averageSeconds);
+    }
+  }
+  const measurementFailures = failedMeasurements.length || undefined;
   let shards: GateTestShard[];
   try {
     shards = planGateTestShards(files, rss, seconds, budgetGiB, count);
   } catch (error) {
-    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error) };
+    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), ...(measurementFailures ? { measurementFailures } : {}) };
   }
   const attempts: GateShardAttempt[] = [];
   const baseline = baselineWorktree(cwd, baseRef, (dir) => {
@@ -76,8 +92,8 @@ export function runShardedGateTests(
     }
     return aggregateGateTestShards(shards, attempts);
   });
-  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts };
-  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log };
+  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts, ...(measurementFailures ? { measurementFailures } : {}) };
+  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log, ...(measurementFailures ? { measurementFailures } : {}) };
 }
 
 export function runBunShard(cwd: string, files: readonly string[]): ReturnType<ShardProcess> {

package/src/self-implement/follow-up-goals.ts

@@ -12,7 +12,7 @@ import { addHarnessQueue, type QueueSeat } from '../harness/harness-queue.js';
 import { debug } from '../debug/log.js';
 import { withFileLockSync } from '../storage/file-lock.js';
 import { elanousStateRoot } from '../autopilot/state-paths.js';
-import { devVersion, listChecklist, parseOwner } from '../release-loop/checklist.js';
+import { checklistDevVersion, listChecklist, parseOwner } from '../release-loop/checklist.js';
 import { getUserConfig } from '../user-config.js';
 
 export const FOLLOW_UP_DEPTH_LIMIT = 3;
@@ -193,7 +193,7 @@ function defaultAppendDraft(stateRoot: string, record: FollowUpDraftRecord): voi
 
 function defaultCellOwner(cellId: string): string | undefined {
   try {
-    return listChecklist(devVersion()).items.find((item) => item.id === cellId)?.owner;
+    return listChecklist(checklistDevVersion()).items.find((item) => item.id === cellId)?.owner;
   } catch {
     return undefined;
   }