elanous 0.2.40 → 0.2.42

package/src/self-implement/heal-intake.ts

@@ -6,6 +6,7 @@ import { debug } from '../debug/log.js';
 import { passJourneyNode } from '../self-dev/graph-journey-nodes.js';
 import { getUserConfig } from '../user-config.js';
 import { psProcessStartMs, START_TOLERANCE_MS } from '../harness/harness-stop.js';
+import { appendRunLedgerEntry, runLedgerDir } from './run-ledger.js';
 
 export type FailureSource = 'release-run' | 'harness-run' | 'loop-tick' | 'cron';
 
@@ -14,14 +15,19 @@ export interface FailureEvent {
   kind: string;
   ref: string;
   summary: string;
+  goalText?: string;
+  goalId?: string;
+  goalFile?: string;
+  cellKey?: string;
   at: string;
 }
 
 const FOLD_WINDOW_MS = 60 * 60 * 1_000;
 const HEAL_GRAPH = join(import.meta.dir, '../../graphs/heal/heal-loop.yaml');
 
-type HealLoopOptions = { runId: string; input: { failureEvent: FailureEvent }; deps: { root: string } };
+type HealLoopOptions = { runId: string; input: { failureEvent: FailureEvent; runId?: string; goal?: string; goalId?: string; goalFile?: string }; deps: { root: string } };
 type StartHealLoop = (file: string, options: HealLoopOptions) => Promise<unknown>;
+export type HealRelaunch = (input: { runId: string; goalText: string; goalId?: string; goalFile?: string; cellKey: string; stateRoot: string }) => Promise<unknown>;
 
 function healRunId(event: FailureEvent): string {
   return `heal-${createHash('sha256').update(JSON.stringify([event.source, event.ref, event.at])).digest('hex')}`;
@@ -68,7 +74,8 @@ function liveHealRuns(root: string): Set<string> {
 
 /** A test process must never start the real heal loop — it spawns external grounding (10-05 load 150 incident). */
 export async function startHealLoop(file: string, options: HealLoopOptions, env: NodeJS.ProcessEnv = process.env,
-  run: StartHealLoop = async (graph, args) => (await import('../graph-runner/runner.js')).runGraph(graph, args)): Promise<unknown> {
+  run: StartHealLoop = async (graph, args) => (await import('../graph-runner/runner.js')).runGraph(graph, args),
+  relaunch: HealRelaunch = runReauthoredGoal): Promise<unknown> {
   if (env.ELANOUS_POD_NAME) {
     debug.log('heal.intake', 'skipped-in-pod', { ref: options.input.failureEvent.ref });
     return undefined;
@@ -112,8 +119,40 @@ export async function startHealLoop(file: string, options: HealLoopOptions, env:
   if (!selected) return undefined;
   let started = false;
   try {
-    const result = await run(file, { runId: selected.runId, input: { failureEvent: selected.event }, deps: { root } });
+    const result = await run(file, { runId: selected.runId, input: { failureEvent: selected.event, runId: selected.event.ref, goal: selected.event.goalText, goalId: selected.event.goalId, goalFile: selected.event.goalFile }, deps: { root } });
     started = true;
+    const request = reauthorRequest(result);
+    if (request) {
+      const cellKey = selected.event.goalId || selected.event.goalFile || selected.event.cellKey
+        || (selected.event.goalText?.trim() ? `goal:${createHash('sha256').update(selected.event.goalText.replace(/\s+/g, ' ').trim()).digest('hex')}` : `run:${selected.event.ref}`);
+      if (!claimReauthorAttempt(root, cellKey, selected.runId)) {
+        debug.log('heal.intake', 'reauthor-already-attempted', { runId: selected.runId, goalId: selected.event.goalId ?? null });
+        return { result, reauthor: 'already-attempted' };
+      }
+      try {
+        debug.log('self-dev.supervisor', 'reauthor-relaunch-requested', { runId: selected.runId, goalId: selected.event.goalId ?? null });
+        const relaunched = await relaunch({ runId: selected.event.ref, goalText: request.revisedGoal,
+          ...(selected.event.goalId ? { goalId: selected.event.goalId } : {}),
+          ...(selected.event.goalFile ? { goalFile: selected.event.goalFile } : {}), cellKey, stateRoot: root });
+        if (relaunched && typeof relaunched === 'object' && 'ok' in relaunched && (relaunched as { ok?: unknown }).ok !== true) {
+          const value = relaunched as { stage?: unknown; node?: unknown; outcome?: unknown };
+          throw new Error(`needs-human: reauthored run failed (${String(value.stage ?? value.node ?? value.outcome ?? 'unknown')})`);
+        }
+        appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId: selected.event.ref, event: 'reauthor-relaunch-result',
+          data: { outcome: 'started', goalId: selected.event.goalId ?? null, requestRunId: selected.runId, result: summarizeRelaunch(relaunched) } }, runLedgerDir(root));
+        return { result, reauthor: 'relaunched', relaunched };
+      } catch (error) {
+        appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId: selected.event.ref, event: 'reauthor-relaunch-result',
+          data: { outcome: 'needs-human', reason: error instanceof Error ? error.message : String(error) } }, runLedgerDir(root));
+        return { result, reauthor: 'needs-human', reason: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    const replanFailure = reauthorFailure(result);
+    if (replanFailure) {
+      appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId: selected.event.ref, event: 'reauthor-relaunch-result',
+        data: { outcome: 'needs-human', reason: replanFailure, graphRunId: selected.runId } }, runLedgerDir(root));
+      return { result, reauthor: 'needs-human', reason: replanFailure };
+    }
     return result;
   } finally {
     withInboxLock(inboxPath(root), () => {
@@ -125,12 +164,81 @@ export async function startHealLoop(file: string, options: HealLoopOptions, env:
       }
     });
     // A completed run opens a slot; a pre-ledger failure waits for the next intake rather than retrying in a tight loop.
-    if (started) void Promise.resolve().then(() => startHealLoop(file, options, env, run)).catch(error => {
+    if (started) void Promise.resolve().then(() => startHealLoop(file, options, env, run, relaunch)).catch(error => {
       debug.log('heal.intake', 'loop-start-failed', { runId: selected.runId, error: String(error) }, { level: 'error' });
     });
   }
 }
 
+function graphOutput(result: unknown, nodeId: string): Record<string, unknown> | undefined {
+  if (!result || typeof result !== 'object') return undefined;
+  const nodes = (result as { nodes?: unknown }).nodes;
+  if (!Array.isArray(nodes)) return undefined;
+  const node = nodes.find((item) => item && typeof item === 'object' && (item as { nodeId?: unknown }).nodeId === nodeId) as { output?: unknown } | undefined;
+  if (typeof node?.output === 'string') {
+    const text = node.output.trim().split(/\r?\n/).at(-1) ?? '';
+    try { return JSON.parse(text) as Record<string, unknown>; } catch { return undefined; }
+  }
+  return node?.output && typeof node.output === 'object' ? node.output as Record<string, unknown> : undefined;
+}
+
+function reauthorRequest(result: unknown): { revisedGoal: string } | undefined {
+  const output = graphOutput(result, 'replan');
+  return output?.outcome === 'ok' && output.reauthor === true && typeof output.revisedGoal === 'string' && output.revisedGoal.trim()
+    ? { revisedGoal: output.revisedGoal } : undefined;
+}
+
+function reauthorFailure(result: unknown): string | undefined {
+  const output = graphOutput(result, 'replan');
+  return output?.outcome === 'fail' && output.needsHuman === true
+    ? (typeof output.reason === 'string' ? output.reason : 'reauthor could not produce a safe revised goal') : undefined;
+}
+
+function claimReauthorAttempt(root: string, cellKey: string, runId: string): boolean {
+  const path = join(root, 'heal', 'reauthor-attempts', `${createHash('sha256').update(cellKey).digest('hex')}.json`);
+  return withInboxLock(path, () => {
+    if (existsSync(path)) return false;
+    writeFileSync(path, JSON.stringify({ cellKey, runId, claimedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
+    return true;
+  });
+}
+
+function summarizeRelaunch(result: unknown): Record<string, unknown> {
+  if (!result || typeof result !== 'object') return { resultType: typeof result };
+  const value = result as Record<string, unknown>;
+  return Object.fromEntries(['ok', 'stage', 'node', 'runId', 'worktreePath', 'branch', 'detail'].flatMap((key) => key in value ? [[key, value[key]]] : []));
+}
+
+async function runReauthoredGoal(input: Parameters<HealRelaunch>[0]): Promise<unknown> {
+  const [{ runSelfImplement, readQuotaExhausted }, { defaultSeams }, devCli, { reselectChildForRework }, { resolveGrokCredential }, { inspectCodexRotation }, ledger] = await Promise.all([
+    import('./orchestrator.js'), import('./seams.js'), import('../self-dev/dev-cli.js'), import('./rework-child-provider.js'),
+    import('../grok/credential.js'), import('../oauth/codex-account-store.js'), import('./run-ledger.js'),
+  ]);
+  let childLlm = devCli.buildChildLlmSelection({});
+  if (childLlm?.provider === 'grok') {
+    const grokQuota = devCli.readGrokQuotaForLaunch();
+    const grokCredential = resolveGrokCredential() ? 'available' as const : 'unavailable' as const;
+    const rotation = inspectCodexRotation();
+    const quota = readQuotaExhausted(inspectCodexRotation, 'openai-codex');
+    const hasCodex = rotation.knownAccountCount > 0;
+    const alternate = hasCodex ? { provider: 'openai-codex', model: devCli.defaultChildLlmModel('openai-codex'), source: 'config' as const } : undefined;
+    const decision = reselectChildForRework({ current: childLlm, grokQuota, grokCredential, ...(alternate ? { alternate } : {}),
+      alternateCredential: hasCodex ? 'available' : 'unavailable', alternateQuotaExhausted: quota.exhausted });
+    if (decision.action === 'reselect') {
+      childLlm = decision.selection;
+      ledger.appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId: input.runId, event: 'rework-child-model-reselected',
+        data: { previousProvider: decision.previous.provider, previousModel: decision.previous.model, provider: childLlm.provider,
+          model: childLlm.model, reason: decision.reason, quota: grokQuota, grokCredential,
+          alternateQuotaExhausted: quota.exhausted ?? null } }, runLedgerDir(input.stateRoot));
+    }
+    else if (grokQuota === 'exhausted' || grokCredential === 'unavailable') throw new Error('needs-human: Grok unusable and no measured alternate provider');
+  }
+  const runId = `reauthor-${createHash('sha256').update(`${input.runId}\0${input.goalId ?? ''}`).digest('hex').slice(0, 20)}`;
+  return runSelfImplement({ feature: input.goalText, runId, ...(input.goalId ? { goalId: input.goalId } : {}),
+    ...(input.goalFile ? { goalFile: input.goalFile } : {}), healCellKey: input.cellKey, ...(childLlm ? { childLlm } : {}),
+    completion: 'worktree-only', draft: true, maxReworkRounds: 0, seams: defaultSeams({ stateDir: input.stateRoot }) });
+}
+
 function inboxPath(root: string): string {
   return join(root, 'heal', 'inbox.jsonl');
 }

package/src/self-implement/heal-triage.ts

@@ -11,6 +11,7 @@ export type HealTriageOutcome =
   | 'needs-deeper-observation'
   | 'needs-grounding'
   | 'rework-with-citations'
+  | 'reauthor-from-materialized'
   | 'exhausted';
 
 export interface HealCitation {
@@ -30,6 +31,12 @@ export interface HealFailureSignature {
   readonly importerUnrunTests?: number;
   readonly environmentClaim?: string;
   readonly namedSource?: string;
+  /** Observations from the failed materialized run; no new collector is implied. */
+  readonly noProgressReason?: string;
+  readonly reportDeficit?: boolean;
+  readonly mustFix?: readonly string[];
+  readonly materializedPaths?: readonly string[];
+  readonly goalText?: string;
 }
 
 /** 게이트 사실로 채울 수 있는 칸. 없는 칸만 채운다. */
@@ -227,6 +234,19 @@ export function triageFailure(signature: HealFailureSignature, history?: HealTri
   const importer = signature.importerUnrunTests ?? 0;
   const claim = signature.environmentClaim?.trim() ?? '';
 
+  const mustFix = (signature.mustFix ?? []).map((item) => item.trim()).filter(Boolean);
+  const repeatedMustFix = mustFix.some((item, index) => mustFix.slice(0, index).includes(item));
+  if (signature.noProgressReason?.trim() || signature.reportDeficit || signature.materializedPaths?.length === 0
+    || repeatedMustFix || (signature.errorText ?? '').includes('tdd-evidence-missing')) {
+    return { outcome: 'reauthor-from-materialized', evidence: [
+      ...(signature.noProgressReason ? [`no-progress: ${signature.noProgressReason}`] : []),
+      ...(signature.reportDeficit ? ['report-deficit'] : []),
+      ...(signature.materializedPaths?.length === 0 ? ['actual target paths: 0'] : []),
+      ...(repeatedMustFix ? ['same must-fix repeated'] : []),
+      ...((signature.errorText ?? '').includes('tdd-evidence-missing') ? ['tdd-evidence-missing'] : []),
+    ] };
+  }
+
   if (claim && ENVIRONMENT_CLAIM.test(claim) && !visited(history, 'verify-evidence')) {
     return {
       outcome: 'environment-claimed',

package/src/self-implement/host-regate.ts

@@ -12,7 +12,7 @@ import { detectTestInterference, failedNamesFromStreams, parseFailureCount, runB
 import { MAX_INSPECTED_TEST_FILES, runTestInterferenceGate } from '../../scripts/ci-test-interference-gate.js';
 import { pwaGraph, pwaReach } from '../../scripts/ci-pwa-build-gate.js';
 import { changedPathPairs, changedTsFiles, readGitFile, requiredExportFieldsInChanges } from '../../scripts/ci-typecheck-changed.js';
-import { classifyMergeFailure, clipRegateDetail, parseConflictFiles, type HostRegateFailure } from './regate-detail.js';
+import { classifyMergeFailure, clipRegateDetail, parseConflictFiles, type HostRegateFailure, type HostRegatePrHeadFailureCondition, type HostRegatePrHeadSnapshot } from './regate-detail.js';
 import { buildImporterTestIndex, isTestPath } from './importer-test-index.js';
 import type { GateReceipt, GateReceiptIdentity } from './gate-receipt-registry.js';
 
@@ -65,7 +65,7 @@ export function provideCheckoutDependencies(candidate: string, sourceRoot: strin
   } else install(join(candidate, dir));
 }
 
-export interface HostRegateInput { prNumber: number; headCommit: string; repoRoot: string; goalFile?: string; verifyOnly?: boolean; /** TA-LIVE-LAND-2: run the full landing gates (release-path hold · neighbours · PR re-read) but stop before the freeze admission and `gh pr merge` — the task agent lands it later via `pr land --expected-head`. */ noMerge?: true; /** Called by a resume sweep that already holds this PR's claim. */ resumed?: true }
+export interface HostRegateInput { prNumber: number; headCommit: string; repoRoot: string; goalFile?: string; verifyOnly?: boolean; /** STOP-HEAL-WINNOW: measurement only on a preserved draft; never valid for landing. */ allowDraft?: true; /** TA-LIVE-LAND-2: run the full landing gates (release-path hold · neighbours · PR re-read) but stop before the freeze admission and `gh pr merge` — the task agent lands it later via `pr land --expected-head`. */ noMerge?: true; /** Called by a resume sweep that already holds this PR's claim. */ resumed?: true }
 export interface HostRegateResult { passed: boolean; failures: HostRegateFailure[]; os: string; status?: 'passed' | 'failed' | 'unmeasured' | 'frozen'; /** verifyOnly: 실제로 얹어 잰 base 끝 */ baseCommit?: string }
 /** Only a missing host repository is recoverable by selecting the run's recorded root. Gate failures are final. */
 export function hostRepositoryUnavailable(result: HostRegateResult): boolean {
@@ -382,17 +382,40 @@ export async function runHostRegate(input: HostRegateInput, deps: HostRegateDeps
     return run('git', ['rev-parse', ref], input.repoRoot);
   };
   try {
-    if (!Number.isSafeInteger(input.prNumber) || input.prNumber <= 0 || !/^[0-9a-f]{40}$/i.test(input.headCommit)) return result('unmeasured', 'input', 'invalid PR number or checked head SHA');
+    if (!Number.isSafeInteger(input.prNumber) || input.prNumber <= 0 || !/^[0-9a-f]{40}$/i.test(input.headCommit) || (input.allowDraft && !input.verifyOnly)) return result('unmeasured', 'input', 'invalid PR number, checked head SHA, or draft measurement mode');
     release = await (deps.acquire ?? acquireSlot)(input.repoRoot);
     type PrView = { headRefOid?: string; baseRefName?: string; baseRefOid?: string; state?: string; isDraft?: boolean };
     const readPr = (): PrView => JSON.parse(run('gh', ['pr', 'view', String(input.prNumber), '--json', 'headRefOid,baseRefName,baseRefOid,state,isDraft'], input.repoRoot));
-    const prHeadFailure = (seen: PrView): HostRegateResult => result('unmeasured', 'pr-head',
-      `PR head, base commit, ready state or open state unavailable or changed (state=${seen.state ?? 'unknown'} · isDraft=${String(seen.isDraft)} · base=${seen.baseRefName ?? 'unknown'}@${seen.baseRefOid ?? 'unknown'})`,
-      { expectedHead: input.headCommit, actualHead: typeof seen.headRefOid === 'string' ? seen.headRefOid : null });
+    const prHeadFailure = (seen: PrView): HostRegateResult => {
+      const failedConditions: HostRegatePrHeadFailureCondition[] = [];
+      const validHead = typeof seen.headRefOid === 'string' && /^[0-9a-f]{40}$/i.test(seen.headRefOid);
+      if (!validHead) failedConditions.push('head-unavailable');
+      else if (seen.headRefOid !== input.headCommit) failedConditions.push('head-mismatch');
+      if (typeof seen.state !== 'string') failedConditions.push('state-unavailable');
+      else if (seen.state !== 'OPEN') failedConditions.push('state-not-open');
+      if (typeof seen.isDraft !== 'boolean') failedConditions.push('draft-status-unavailable');
+      else if (seen.isDraft && !input.allowDraft) failedConditions.push('pr-is-draft');
+      if (!seen.baseRefName) failedConditions.push('base-name-unavailable');
+      const validBaseOid = typeof seen.baseRefOid === 'string' && /^[0-9a-f]{40}$/i.test(seen.baseRefOid);
+      if (!validBaseOid) failedConditions.push('base-oid-invalid');
+      failedConditions.sort();
+      const state: HostRegatePrHeadSnapshot['state'] =
+        seen.state === 'OPEN' || seen.state === 'CLOSED' || seen.state === 'MERGED' ? seen.state : typeof seen.state === 'string' ? 'OTHER' : null;
+      const snapshot: HostRegatePrHeadSnapshot = {
+        headRefOid: validHead ? seen.headRefOid! : null,
+        state,
+        isDraft: typeof seen.isDraft === 'boolean' ? seen.isDraft : null,
+        baseRefName: !seen.baseRefName ? null : seen.baseRefName === 'main' ? 'main' : 'other',
+        baseRefOid: validBaseOid ? seen.baseRefOid! : null,
+      };
+      return result('unmeasured', 'pr-head',
+        `PR head preflight failed: ${failedConditions.join(', ') || 'unknown'} (state=${snapshot.state ?? 'unknown'} · isDraft=${String(snapshot.isDraft)} · base=${snapshot.baseRefName ?? 'unknown'}@${snapshot.baseRefOid ?? 'unknown'})`,
+        { expectedHead: input.headCommit, actualHead: snapshot.headRefOid, failedConditions, prHeadSnapshot: snapshot });
+    };
     let view: PrView;
     try { view = readPr(); }
     catch (e) { return result('unmeasured', 'pr-view', String(e)); }
-    if (view.headRefOid !== input.headCommit || view.state !== 'OPEN' || view.isDraft !== false || !view.baseRefName || !/^[0-9a-f]{40}$/i.test(view.baseRefOid ?? '')) return prHeadFailure(view);
+    if (view.headRefOid !== input.headCommit || view.state !== 'OPEN' || (view.isDraft !== false && !(input.allowDraft && view.isDraft === true)) || !view.baseRefName || !/^[0-9a-f]{40}$/i.test(view.baseRefOid ?? '')) return prHeadFailure(view);
     const baseRefName = view.baseRefName;
     // verifyOnly(승인 탭): PR 에 기록된 base(baseRefOid)는 main 의 «지금 끝»보다 늙을 수 있다 — 지금 끝에 얹어 잰다.
     let baseCommit = view.baseRefOid!;
@@ -621,7 +644,7 @@ export async function runHostRegate(input: HostRegateInput, deps: HostRegateDeps
     let current: PrView;
     try { current = readPr(); }
     catch (e) { return result('unmeasured', 'pr-view', String(e)); }
-    if (current.headRefOid !== input.headCommit || current.baseRefName !== baseRefName || (!input.verifyOnly && current.baseRefOid !== (stalePrBase ?? baseCommit)) || current.state !== 'OPEN' || current.isDraft !== false) {
+    if (current.headRefOid !== input.headCommit || current.baseRefName !== baseRefName || (!input.verifyOnly && current.baseRefOid !== (stalePrBase ?? baseCommit)) || current.state !== 'OPEN' || current.isDraft !== view.isDraft) {
       return result('unmeasured', 'pr-base-changed', 'PR head or base changed during host regate; rerun against the new base');
     }
     // --match-head-commit pins the head. gh has no base pin, so the base was re-read just

package/src/self-implement/knowhow-pack.ts

@@ -309,6 +309,44 @@ function relevance(goal: string, section: string, targetPaths?: readonly string[
   return score;
 }
 
+/** Selects explicit, active failure-signature remedies from repository-contained KNOWHOW files. */
+export function selectHealKnowhowPack(repo: string, signature: string): KnowhowPack {
+  const empty = (reason: KnowhowPack['reason']): KnowhowPack => ({ text: '', ids: [], bytes: 0, reason });
+  if (!/^[a-z][a-z0-9-]*$/.test(signature)) return empty('no-promoted-section');
+  const rolesDir = resolve(repo, 'docs/roles');
+  let realRoles: string;
+  try {
+    realRoles = realpathSync(rolesDir);
+    if (!inside(realpathSync(repo), realRoles)) return empty('source-unreadable');
+  } catch { return empty('source-unreadable'); }
+  let seats: string[];
+  try { seats = readdirSync(rolesDir).sort(); } catch { return empty('source-unreadable'); }
+  const selected: Array<{ id: string; remedy: string }> = [];
+  for (const seat of seats) {
+    if (!/^[A-Z]{2,4}$/.test(seat)) continue;
+    const file = join(rolesDir, seat, 'KNOWHOW.md');
+    try {
+      if (lstatSync(file).isSymbolicLink()) continue;
+      const real = realpathSync(file);
+      if (!inside(realRoles, real) || !statSync(real).isFile() || statSync(real).size > 2_000_000) continue;
+      for (const section of promotedSections(readFileSync(real, 'utf8'))) {
+        const explicit = /^- 원인 서명:\s*([a-z][a-z0-9-]*)\s*$/m.exec(section.text)?.[1];
+        const remedy = /^- 처방(?:\(힐링\))?:\s*(\S[^\r\n]*)$/m.exec(section.text)?.[1];
+        if (explicit !== signature || !remedy || selected.some((item) => item.id === section.id)) continue;
+        const next = [...selected, { id: section.id, remedy }];
+        const text = `[SUPERVISOR-HEAL-PACK signature=${signature} ids=${next.map((item) => item.id).join(',')}]\n${next.map((item) => `${item.id}: ${item.remedy}`).join('\n')}`;
+        if (Buffer.byteLength(text, 'utf8') <= KNOWHOW_PACK_MAX_BYTES) selected.push({ id: section.id, remedy });
+        if (selected.length === 3) break;
+      }
+    } catch { /* Missing or unreadable files contribute no remedy. */ }
+    if (selected.length === 3) break;
+  }
+  if (!selected.length) return empty('no-promoted-section');
+  const ids = selected.map((item) => item.id);
+  const text = `[SUPERVISOR-HEAL-PACK signature=${signature} ids=${ids.join(',')}]\n${selected.map((item) => `${item.id}: ${item.remedy}`).join('\n')}`;
+  return { ids, text, bytes: Buffer.byteLength(text, 'utf8'), reason: 'selected' };
+}
+
 /** Reads only 내부 문서 `KNOWHOW` inside the supplied repository. Verified target paths narrow relevance when supplied. */
 function selectKnowhowOnly(repo: string, goal: string, targetPaths: readonly string[] | undefined, maxBytes: number): KnowhowPack {
   const empty = (reason: KnowhowPack['reason']): KnowhowPack => ({ text: '', ids: [], bytes: 0, reason });

package/src/self-implement/merge-train.ts

@@ -18,6 +18,11 @@ export type TrainObservation = {
 export type TrainGit = (args: readonly string[], repo: string) => { status: number | null; stdout: string; stderr: string };
 export type TangledPair = { first: number; then: number; failures: number };
 
+/**
+ * Same PR-number axis as TrainDeferred.with and planTrain overlap deferrals: normalize each sibling
+ * pair ({5,7}={7,5}), count its conflict-resolution/regate failures, and return only pairs at or
+ * above threshold (default 2) — first = smaller number = lands first, then = re-synced later.
+ */
 export function tangledPairs(
   failures: readonly { pr: number; with: number }[],
   { threshold = 2 }: { threshold?: number } = {},