elanous 0.2.0 → 0.2.5

package/src/execution-loop/dispatch-task.ts

@@ -0,0 +1,139 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { debug } from '../debug/log.js';
+import { emitDecision, type DecisionEvent } from '../live/detail-switch.js';
+import { CardStore, redactSecrets } from '../task-cards/card-store.js';
+import type { DevPipelineSpec } from '../self-dev/dev-pipeline.js';
+import {
+  budgetGate, placementGate, relationGate, memoryGate,
+  type BudgetGateDeps, type GateResult, type MemoryDecision, type MemoryGateDeps, type PlacementGateDeps,
+  type PlacementGateInput, type RelationGateDeps,
+} from './gates.js';
+import { summarizeGateDecision, type GateName } from './gate-decision-summary.js';
+
+export interface DispatchTaskInput {
+  goalId: string;
+  title: string;
+  goalText: string;
+  targetPaths: readonly string[];
+  spec: DevPipelineSpec;
+  runKey?: string;
+}
+
+export type ObservedGateResult = GateResult<unknown>;
+export interface DispatchTaskResult {
+  cardId: string;
+  decisions: Record<GateName, ObservedGateResult>;
+  mode: 'observe';
+}
+
+export interface DispatchTaskDeps {
+  createStore?: () => CardStore;
+  budgetGate?: typeof budgetGate;
+  placementGate?: typeof placementGate;
+  relationGate?: typeof relationGate;
+  memoryGate?: (card: Parameters<typeof memoryGate>[0], deps?: MemoryGateDeps) => Promise<GateResult<MemoryDecision | string>>;
+  budgetDeps?: BudgetGateDeps;
+  placementDeps?: PlacementGateDeps;
+  relationDeps?: RelationGateDeps;
+  memoryDeps?: MemoryGateDeps;
+  emitDecision?: (event: DecisionEvent) => unknown;
+  /** Called as soon as the card exists, before any gate can reach its deadline. */
+  onCardCreated?: (cardId: string) => void;
+  log?: (gate: GateName, data: { cardId: string; verdict: string; ms: number }) => void;
+  /** Cancels pending observations and settles dispatch before any further card writes. */
+  signal?: AbortSignal;
+  /** Optional shorter deadline for tests; never extends the five-second cap. */
+  timeoutMs?: number;
+}
+
+const UNAVAILABLE = '측정 불가';
+
+function verdictFor(gate: GateName, result: ObservedGateResult): string {
+  if (result.decision === UNAVAILABLE) return UNAVAILABLE;
+  const decision = result.decision as Record<string, unknown> | null;
+  const key = gate === 'budget' ? 'action' : gate === 'placement' ? 'substrate' : 'action';
+  return typeof decision?.[key] === 'string' ? String(decision[key]) : 'unknown';
+}
+
+/** A goal id is an identifier, not a secret: secret-shape redaction turned every long hex id
+ *  (e.g. `request-<sha256>`) into the same `<redacted>` and merged all goals into one card.
+ *  Keep ids that use the identifier alphabet; anything else becomes a stable hash. */
+export function cardGoalId(goalId: string): string {
+  return /^[A-Za-z0-9._:-]{1,128}$/.test(goalId) ? goalId : `goal-${createHash('sha256').update(goalId).digest('hex').slice(0, 32)}`;
+}
+
+/** Observation only: neither the decision nor a failure can select the launch, substrate or model. */
+export async function dispatchTask(input: DispatchTaskInput, deps: DispatchTaskDeps = {}): Promise<DispatchTaskResult> {
+  const timeoutMs = Math.min(5_000, Math.max(0, deps.timeoutMs ?? 5_000));
+  const deadline = Date.now() + timeoutMs;
+  if (deps.signal?.aborted) throw new Error('dispatch observation aborted');
+  const store = (deps.createStore ?? (() => new CardStore()))();
+  try {
+    if (deps.signal?.aborted) throw new Error('dispatch observation aborted');
+    const card = store.createCard({ goalId: cardGoalId(input.goalId), title: redactSecrets(input.title) });
+    if (card.status !== 'open') throw new Error(`Card is closed: ${card.id}`);
+    try { deps.onCardCreated?.(card.id); } catch { /* Ledger observation cannot stop dispatch. */ }
+    const runKey = redactSecrets(input.runKey ?? randomUUID());
+    const relationDeps: RelationGateDeps = deps.relationDeps ?? {
+      openCards: () => store.listCards({ open: true }),
+      priorTermination: () => undefined,
+      // No active-run source is wired here yet: keep that one field unknown and still measure the rest.
+      activeRuns: () => 'unknown',
+    };
+    const placement: PlacementGateInput = { goal: input.goalText };
+    const gates: Record<GateName, () => Promise<ObservedGateResult> | ObservedGateResult> = {
+      budget: () => (deps.budgetGate ?? budgetGate)(deps.budgetDeps),
+      placement: () => (deps.placementGate ?? placementGate)(placement, deps.placementDeps),
+      relation: () => (deps.relationGate ?? relationGate)(card, input.targetPaths, relationDeps),
+      memory: () => (deps.memoryGate ?? memoryGate)(card, deps.memoryDeps),
+    };
+    const results = await Promise.all((Object.keys(gates) as GateName[]).map(async (gate) => {
+      const started = Date.now();
+      const cap = Math.max(0, deadline - started);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let onAbort: (() => void) | undefined;
+      let result: ObservedGateResult;
+      try {
+        result = await Promise.race([
+          Promise.resolve().then(() => {
+            if (deps.signal?.aborted) throw new Error('dispatch observation aborted');
+            return gates[gate]();
+          }),
+          new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), cap); }),
+          new Promise<never>((_, reject) => {
+            onAbort = () => reject(new Error('dispatch observation aborted'));
+            deps.signal?.addEventListener('abort', onAbort, { once: true });
+            if (deps.signal?.aborted) onAbort();
+          }),
+        ]);
+      } catch (error) {
+        result = { decision: UNAVAILABLE, explanation: `${UNAVAILABLE}: ${error instanceof Error ? error.message : String(error)}` };
+      } finally {
+        if (timer) clearTimeout(timer);
+        if (onAbort) deps.signal?.removeEventListener('abort', onAbort);
+      }
+      if (deps.signal?.aborted) return [gate, result] as const;
+      const ms = Date.now() - started;
+      const verdict = verdictFor(gate, result);
+      try { (deps.log ?? ((name, data) => debug.log('execution-loop.gate', name, data)))(gate, { cardId: card.id, verdict, ms }); }
+      catch { /* Observability must not change the launch. */ }
+      try {
+        (deps.emitDecision ?? emitDecision)({
+          kind: gate === 'placement' ? 'ROUTE' : 'PLAN', what: `execution-loop ${gate} gate`,
+          reason: summarizeGateDecision(gate, result), purpose: 'observe dispatch only', target: card.id,
+          ...(input.spec.runId ? { runId: input.spec.runId } : {}), phase: 'dispatch',
+        });
+      } catch { /* Live-detail logging is optional. */ }
+      return [gate, result] as const;
+    }));
+    if (deps.signal?.aborted) throw new Error('dispatch observation aborted');
+    const decisions = Object.fromEntries(results) as Record<GateName, ObservedGateResult>;
+    const content = (value: unknown) => redactSecrets(JSON.stringify(value));
+    store.appendSection(card.id, { key: `gates:${runKey}`, owner: 'execution-loop', content: content({ budget: decisions.budget, placement: decisions.placement }) });
+    store.appendSection(card.id, { key: `relations:${runKey}`, owner: 'execution-loop', content: content(decisions.relation) });
+    store.appendSection(card.id, { key: `memory:${runKey}`, owner: 'execution-loop', content: content(decisions.memory) });
+    return { cardId: card.id, decisions, mode: 'observe' };
+  } finally {
+    store.close();
+  }
+}

package/src/execution-loop/gate-decision-summary.ts

@@ -0,0 +1,29 @@
+import { redactSecrets } from '../task-cards/card-store.js';
+import type { BudgetDecision } from '../self-implement/budget-gate.js';
+import type { GateResult, MemoryDecision, PlacementDecision, RelationDecision } from './gates.js';
+
+export type GateName = 'budget' | 'placement' | 'relation' | 'memory';
+
+/** Only decision metadata belongs in the live log; full results remain in the card. */
+export function summarizeGateDecision(gate: GateName, result: GateResult<unknown>): string {
+  const { decision } = result;
+  let summary: string;
+  if (typeof decision === 'string') {
+    summary = gate === 'memory' ? 'unavailable' : `unavailable · explanation=${redactSecrets(result.explanation).slice(0, 80)}`;
+  } else if (gate === 'budget') {
+    const budget = decision as BudgetDecision;
+    summary = `action=${budget.action}${budget.provider ? ` · provider=${budget.provider}` : ''} · reason=${redactSecrets(budget.reasons[0] ?? '').slice(0, 80)}`;
+  } else if (gate === 'placement') {
+    const placement = decision as PlacementDecision;
+    summary = `substrate=${placement.substrate} · pool=${placement.pool ?? 'none'}${placement.memory ? ` · memory=${placement.memory.limit}` : ''} · unknown=${placement.unknownInputs.join(',')}`;
+  } else if (gate === 'relation') {
+    const relation = decision as RelationDecision;
+    const unknown = (['preflightOverlaps', 'dependsOn', 'similarCards', 'sameGoalActiveRuns'] as const)
+      .filter((key) => relation[key] === 'unknown');
+    summary = `overlap=${relation.overlappingCards.length} · unknown=${unknown.join(',')}`;
+  } else {
+    const memory = decision as MemoryDecision;
+    summary = `context=${memory.context ? 'recalled' : 'none'} · fragments=${memory.fragmentIds.length}`;
+  }
+  return redactSecrets(summary).slice(0, 250);
+}

package/src/execution-loop/gates.ts

@@ -0,0 +1,197 @@
+import type { TaskCard } from '../task-cards/card-store.js';
+import { decideBudget, readBudgetInputsLive, type BudgetDecision, type BudgetInputs } from '../self-implement/budget-gate.js';
+import { resolveHarnessSubstrate, type ResolvedHarnessSubstrate } from '../harness/harness-substrate-default.js';
+import { podMemoryLimitFor } from '../task-orchestrator/surfaces/self-implement-pod.js';
+import { recallMemoryContext } from '../agent-substrate/execution/memory-context.js';
+
+export interface GateResult<T> {
+  decision: T;
+  explanation: string;
+}
+
+export interface BudgetGateDeps {
+  readInputs: () => Promise<BudgetInputs>;
+  decide: (inputs: BudgetInputs) => BudgetDecision;
+}
+
+/** Observe the existing quota decision; callers record it, not apply it to the launch. */
+export async function budgetGate(
+  deps: BudgetGateDeps = { readInputs: readBudgetInputsLive, decide: decideBudget },
+): Promise<GateResult<BudgetDecision>> {
+  const decision = deps.decide(await deps.readInputs());
+  return { decision, explanation: decision.reasons.join(' · ') || `budget: ${decision.action}` };
+}
+
+export interface PlacementGateInput {
+  goal: string;
+  /** A local-only capability or file is an observation, not a reason to probe a remote pool. */
+  needsBrowser?: boolean;
+  needsVideo?: boolean;
+  needsAppSigning?: boolean;
+  localFiles?: readonly string[];
+  flag?: { substrate?: 'pod' | 'local'; podPool?: string };
+}
+
+export interface PlacementGateDeps {
+  resolveSubstrate: (input: { flag?: { substrate?: 'pod' | 'local'; podPool?: string } }) => ResolvedHarnessSubstrate;
+  memoryLimit: (goal: string) => { limit: string; tier: string; source: string };
+}
+
+export type PlacementDecision = (ResolvedHarnessSubstrate | {
+  substrate: 'unknown';
+  pool: null;
+  source: 'unknown';
+}) & {
+  /** Reachability is deliberately not probed by this observational gate. */
+  poolReachability: 'unknown' | 'not-applicable';
+  memory?: { limit: string; tier: string; source: string };
+  localReasons: string[];
+  /** Omitted observations must not be silently treated as negative evidence. */
+  unknownInputs: string[];
+};
+
+const defaultPlacementDeps: PlacementGateDeps = {
+  resolveSubstrate: ({ flag }) => resolveHarnessSubstrate({ flag, env: process.env, currentContext: () => undefined }),
+  memoryLimit: (goal) => podMemoryLimitFor(goal, process.env),
+};
+
+export function placementGate(
+  input: PlacementGateInput,
+  deps: PlacementGateDeps = defaultPlacementDeps,
+): GateResult<PlacementDecision> {
+  const unknownInputs = [
+    ...(input.needsBrowser === undefined ? ['needsBrowser'] : []),
+    ...(input.needsVideo === undefined ? ['needsVideo'] : []),
+    ...(input.needsAppSigning === undefined ? ['needsAppSigning'] : []),
+    ...(input.localFiles === undefined ? ['localFiles'] : []),
+    ...(input.flag?.substrate === undefined ? ['substrate'] : []),
+  ];
+  const localReasons = [
+    ...(input.needsBrowser ? ['browser'] : []),
+    ...(input.needsVideo ? ['video'] : []),
+    ...(input.needsAppSigning ? ['app signing'] : []),
+    ...(input.localFiles?.length ? [`local files: ${input.localFiles.join(', ')}`] : []),
+  ];
+  // A measured local-only need wins; otherwise unknown needs cannot justify a remote assertion.
+  if (!localReasons.length && input.flag?.substrate !== 'local' && unknownInputs.length) {
+    return {
+      decision: { substrate: 'unknown', pool: null, source: 'unknown', poolReachability: 'unknown', localReasons, unknownInputs },
+      explanation: `placement=unknown; unmeasured=${unknownInputs.join(', ')}; pool reachability not checked`,
+    };
+  }
+  const flag = localReasons.length ? { substrate: 'local' as const } : input.flag;
+  let resolved: ResolvedHarnessSubstrate;
+  try {
+    resolved = deps.resolveSubstrate({ flag });
+  } catch (error) {
+    if (flag?.substrate !== 'pod' || !(error instanceof Error) || !error.message.includes('Pod 풀 또는 현재 컨텍스트에 닿지 못했다')) throw error;
+    // No configured pool is not evidence that a remote pool is unreachable.
+    resolved = { substrate: 'pod', pool: null, source: 'flag' };
+  }
+  const poolReachability = resolved.substrate === 'pod' ? 'unknown' : 'not-applicable';
+  const memory = resolved.substrate === 'pod' ? deps.memoryLimit(input.goal) : undefined;
+  const decision: PlacementDecision = {
+    ...resolved, poolReachability, localReasons, unknownInputs,
+    ...(memory ? { memory } : {}),
+  };
+  return {
+    decision,
+    explanation: (resolved.substrate === 'local'
+      ? `local: ${localReasons.join(' · ') || `substrate ${resolved.source}`}`
+      : `pod: pool=${resolved.pool ?? 'unknown'}; reachability=unknown (not checked); memory=${memory?.tier ?? 'unknown'} (${memory?.limit ?? 'unknown'})`)
+      + (unknownInputs.length ? `; unmeasured=${unknownInputs.join(', ')}` : ''),
+  };
+}
+
+export interface RelationGateDeps {
+  openCards: () => Promise<readonly TaskCard[]> | readonly TaskCard[];
+  /** A previous completed run is reported as a fact, never inferred from a matching title. */
+  priorTermination: (goalId: string) => Promise<string | undefined> | string | undefined;
+  /** 'unknown' = the caller cannot observe running runs; recorded as unknown, never as none. */
+  activeRuns: (goalId: string) => Promise<readonly string[] | 'unknown'> | readonly string[] | 'unknown';
+  /** Optional preflight overlap observations are kept separate from open-card overlap. */
+  preflightOverlaps?: (paths: readonly string[]) => Promise<readonly string[]> | readonly string[];
+  dependsOn?: (goalId: string) => Promise<readonly string[]> | readonly string[];
+  similarCards?: (card: TaskCard, openCards: readonly TaskCard[]) => Promise<readonly string[]> | readonly string[];
+}
+
+export interface RelationDecision {
+  overlappingCards: string[];
+  preflightOverlaps: string[] | 'unknown';
+  dependsOn: string[] | 'unknown';
+  similarCards: string[] | 'unknown';
+  sameGoalActiveRuns: string[] | 'unknown';
+  priorTermination?: string;
+  /** Overlaps and similarity are observations, not dispatch locks. */
+  action: 'record';
+}
+
+export async function relationGate(
+  card: TaskCard,
+  targetPaths: readonly string[],
+  deps: RelationGateDeps,
+): Promise<GateResult<RelationDecision>> {
+  const [cards, priorTermination, sameGoalActiveRuns] = await Promise.all([
+    deps.openCards(), deps.priorTermination(card.goalId), deps.activeRuns(card.goalId),
+  ]);
+  const [preflightOverlaps, dependsOn, similarCards] = await Promise.all([
+    deps.preflightOverlaps?.(targetPaths) ?? 'unknown',
+    deps.dependsOn?.(card.goalId) ?? 'unknown',
+    deps.similarCards?.(card, cards) ?? 'unknown',
+  ]);
+  const target = new Set(targetPaths);
+  const overlappingCards = cards
+    .filter((other) => other.id !== card.id && other.status === 'open' && other.sections.some((section) => {
+      if (!section.key.startsWith('workspace')) return false;
+      try {
+        const workspace = JSON.parse(section.content) as { targetPaths?: unknown; paths?: unknown };
+        const paths = workspace.targetPaths ?? workspace.paths;
+        return Array.isArray(paths) && paths.some((path) => typeof path === 'string' && target.has(path));
+      } catch { return false; }
+    }))
+    .map((other) => other.id);
+  const observed = (value: readonly string[] | string): string =>
+    typeof value === 'string' ? value : value.join(',') || 'none';
+  const decision: RelationDecision = {
+    action: 'record', overlappingCards,
+    preflightOverlaps: preflightOverlaps === 'unknown' ? 'unknown' : [...preflightOverlaps],
+    dependsOn: dependsOn === 'unknown' ? 'unknown' : [...dependsOn],
+    similarCards: similarCards === 'unknown' ? 'unknown' : [...similarCards],
+    sameGoalActiveRuns: sameGoalActiveRuns === 'unknown' ? 'unknown' : [...sameGoalActiveRuns],
+    ...(priorTermination === undefined ? {} : { priorTermination }),
+  };
+  return {
+    decision,
+    explanation: `overlap=${observed(overlappingCards)}; preflight=${observed(preflightOverlaps)}; dependsOn=${observed(dependsOn)}; similar=${observed(similarCards)}; active=${observed(sameGoalActiveRuns)}; prior=${priorTermination ?? 'unknown'}; overlaps do not block launch`,
+  };
+}
+
+export interface MemoryGateDeps {
+  recall: (query: string) => Promise<string>;
+  priorAbandonment: (goalId: string) => Promise<string | undefined> | string | undefined;
+}
+
+export interface MemoryDecision {
+  context: string;
+  priorAbandonment?: string;
+  /** The existing recall API returns formatted context, not stable fragment IDs. */
+  fragmentIds: string[];
+  action: 'record';
+}
+
+export async function memoryGate(
+  card: Pick<TaskCard, 'goalId' | 'title'>,
+  deps: MemoryGateDeps = { recall: recallMemoryContext, priorAbandonment: () => undefined },
+): Promise<GateResult<MemoryDecision>> {
+  const [context, priorAbandonment] = await Promise.all([
+    deps.recall(card.title), deps.priorAbandonment(card.goalId),
+  ]);
+  const decision: MemoryDecision = {
+    action: 'record', context, fragmentIds: [],
+    ...(priorAbandonment === undefined ? {} : { priorAbandonment }),
+  };
+  return {
+    decision,
+    explanation: `memory=${context ? 'recalled' : 'none or unavailable'}; prior abandonment=${priorAbandonment ?? 'unknown'}; fragment IDs unavailable from recall API`,
+  };
+}

package/src/git-fs/gh-cli.ts

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { debug } from '../debug/log.js';
 
 const LF = 0x0a;
@@ -123,22 +123,7 @@ export type GhCliResult = {
   limit?: number;
 };
 
-/** Executes gh through the retry gateway and returns its raw stdout with outcome metadata. */
-export function runGhCliWithResult(args: string[]): GhCliResult {
-  let stdout: Buffer = Buffer.alloc(0);
-  let stderr: Buffer = Buffer.alloc(0);
-  let status: number | null = null;
-  const retryable = isReadOnlyGhCall(args);
-
-  for (let attempt = 1; attempt <= MAX_GH_RETRY_ATTEMPTS; attempt++) {
-    const result = spawnSync('gh', args, { maxBuffer: Infinity });
-    stdout = asBuffer(result.stdout);
-    stderr = asBuffer(result.stderr);
-    status = result.status;
-    const exitCode = status ?? 1;
-    if (exitCode === 0 || !retryable || attempt === MAX_GH_RETRY_ATTEMPTS || !isTransientGhError(Buffer.concat([stderr, stdout]))) break;
-  }
-
+function ghResult(args: string[], stdout: Buffer, stderr: Buffer, status: number | null): GhCliResult {
   const exitCode = status ?? 1;
   const count = itemCount(stdout);
   const limit = limitValue(args);
@@ -153,6 +138,51 @@ export function runGhCliWithResult(args: string[]): GhCliResult {
   };
 }
 
+/** One retry decision for both the blocking and the async gateway. */
+function shouldRetry(args: string[], attempt: number, stdout: Buffer, stderr: Buffer, status: number | null): boolean {
+  const exitCode = status ?? 1;
+  return !(exitCode === 0 || !isReadOnlyGhCall(args) || attempt === MAX_GH_RETRY_ATTEMPTS || !isTransientGhError(Buffer.concat([stderr, stdout])));
+}
+
+/** Executes gh through the retry gateway and returns its raw stdout with outcome metadata. */
+export function runGhCliWithResult(args: string[]): GhCliResult {
+  let stdout: Buffer = Buffer.alloc(0);
+  let stderr: Buffer = Buffer.alloc(0);
+  let status: number | null = null;
+  for (let attempt = 1; attempt <= MAX_GH_RETRY_ATTEMPTS; attempt++) {
+    const result = spawnSync('gh', args, { maxBuffer: Infinity });
+    stdout = asBuffer(result.stdout);
+    stderr = asBuffer(result.stderr);
+    status = result.status;
+    if (!shouldRetry(args, attempt, stdout, stderr, status)) break;
+  }
+  return ghResult(args, stdout, stderr, status);
+}
+
+function spawnGh(args: string[]): Promise<{ stdout: Buffer; stderr: Buffer; status: number | null }> {
+  return new Promise((resolve) => {
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    let child: ReturnType<typeof spawn>;
+    try { child = spawn('gh', args, { stdio: ['ignore', 'pipe', 'pipe'] }); }
+    catch (e) { resolve({ stdout: Buffer.alloc(0), stderr: Buffer.from(String(e)), status: null }); return; }
+    child.stdout?.on('data', (chunk: Buffer) => out.push(chunk));
+    child.stderr?.on('data', (chunk: Buffer) => err.push(chunk));
+    child.once('error', (e) => resolve({ stdout: Buffer.concat(out), stderr: Buffer.concat([...err, Buffer.from(String(e))]), status: null }));
+    child.once('close', (code) => resolve({ stdout: Buffer.concat(out), stderr: Buffer.concat(err), status: code }));
+  });
+}
+
+/** Same gateway without blocking the event loop — for daemon request handlers. */
+export async function runGhCliWithResultAsync(args: string[]): Promise<GhCliResult> {
+  let last: { stdout: Buffer; stderr: Buffer; status: number | null } = { stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), status: null };
+  for (let attempt = 1; attempt <= MAX_GH_RETRY_ATTEMPTS; attempt++) {
+    last = await spawnGh(args);
+    if (!shouldRetry(args, attempt, last.stdout, last.stderr, last.status)) break;
+  }
+  return ghResult(args, last.stdout, last.stderr, last.status);
+}
+
 /** Executes gh while preserving its byte streams and appending a pipe-visible outcome.
  *  ⛔⭐⭐ **재시도·절단 판정을 «다시 쓰지 않는다»** — `runGhCliWithResult` 를 그대로 탄다(2026-08-09).
  *    초판은 같은 spawn·재시도 루프를 «둘»로 복제해 뒀고, 그러면 한쪽만 고쳐질 때 조용히 갈린다. */

package/src/git-fs/retry.ts

@@ -3,6 +3,7 @@ const MAX_GIT_RETRY_ATTEMPTS = 6;
 
 export type GitRunResult = {
   status: number | null;
+  signal?: NodeJS.Signals | null;
   stdout: string;
   stderr: string;
 };

package/src/git-fs/runner.ts

@@ -29,6 +29,7 @@ export function runGitCommand(
     const result = spawnSync('git', gitArgs, { ...options, cwd });
     return {
       status: result.status,
+      ...(result.signal ? { signal: result.signal } : {}),
       stdout: outputText(result.stdout),
       stderr: outputText(result.stderr),
     };

package/src/git-fs/worktree.ts

@@ -338,7 +338,7 @@ export interface CreateWorktreeResult {
 /** git 실행 seam — 기본은 실 `spawnSync`. 테스트가 실패 분기(ls-remote 실패·fetch 실패·경합)를
  *  **결정론적으로** 재도록 주입 가능하게 뺐다(사후 리뷰 should-fix: 그 분기들이 회귀 무방비였다).
  *  ⛔ 결과 타입을 따로 export 하지 않는다 — 외부 소비자가 없다(dead surface 금지·리뷰 should-fix). */
-export type GitRunner = (args: string[]) => { status: number | null; stdout: string; stderr: string };
+export type GitRunner = (args: string[]) => { status: number | null; signal?: NodeJS.Signals | null; stdout: string; stderr: string };
 
 export function resolveDefaultBranchBase(repoRoot: string): string | null {
   const run = (...args: string[]) => spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
@@ -372,16 +372,17 @@ export function syncBaseWithRemote(
     ? (...args: string[]) => runner(args)
     : (...args: string[]) => {
       const r = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
-      return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+      return { status: r.status, signal: r.signal, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
     };
 
-  const wanted = `refs/heads/${base}`;
+  const remoteBranch = base.startsWith('origin/') ? base.slice('origin/'.length) : base;
+  const wanted = `refs/heads/${remoteBranch}`;
   // ⛔ **이름이 hex 라고 SHA 가 아니다**(리뷰 must-fix ④) — `abc1234` 라는 **브랜치**가 있을 수 있다.
   //    로컬 heads 뿐 아니라 **remote-tracking ref** 까지 본다(둘 다 로컬 조회·네트워크 0).
   //    그래도 남는 모호함(원격에만 있는 hex 이름 브랜치)은 아래에서 ls-remote 결과로 최종 판정한다.
   const looksHex = /^[0-9a-f]{7,40}$/i.test(base);
   const isKnownLocalRef = git('show-ref', '--verify', '--quiet', wanted).status === 0
-    || git('show-ref', '--verify', '--quiet', `refs/remotes/origin/${base}`).status === 0;
+    || git('show-ref', '--verify', '--quiet', `refs/remotes/origin/${remoteBranch}`).status === 0;
   const isFullOid = /^[0-9a-f]{40}$/i.test(base);
   /** ref 로 알려진 바 없고 커밋으로 풀리면 그때만 SHA 다.
    *  `requireUnambiguous` = 원격을 못 물어본 상황(skip) — 그때는 **완전한 40자 oid** 만 SHA 로 친다.
@@ -420,7 +421,7 @@ export function syncBaseWithRemote(
     : runGitCommand(repoRoot, ['fetch', 'origin', wanted], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
   if (fetched.status !== 0) {
     // origin 에 있는 것을 확인했는데 못 가져왔다 ⇒ 낡은 로컬로 진행하면 조용히 틀린다.
-    throw new Error(`git worktree base sync failed — origin/${base} exists but fetch failed: ${(fetched.stderr || '').trim().slice(0, 200)}`);
+    throw new Error(`git worktree base sync failed — origin/${remoteBranch} exists but fetch failed: status=${fetched.status}, signal=${fetched.signal ?? 'none'}, stdout=${JSON.stringify((fetched.stdout || '').trim().slice(0, 200))}, stderr=${JSON.stringify((fetched.stderr || '').trim().slice(0, 200))}`);
   }
   // ⭐ **가져온 것**에서 갈린다(리뷰 must-fix ②) — ls-remote 로 먼저 읽은 SHA 를 쓰면 그 사이 원격이
   //    전진했을 때 "원격 tip" 계약이 깨진다. FETCH_HEAD 가 방금 받은 tip 이다.

package/src/github/pr-labels.ts

@@ -0,0 +1,68 @@
+// Canonical PR label registry: 내부 문서 `MANUAL-pr-kinds-draft-vs-approval-2026-09-27`.
+export const IDEA_APPROVAL_LIMIT = 10;
+export const IDEA_STALE_DAYS = 7;
+export const STALLED_DRAFT_HOURS = 24;
+export const CLAIM_IDLE_HOURS = 6;
+
+export type PrLabelAxis = 'state' | 'addon' | 'origin' | 'risk';
+export type PrLabelApplier = 'harness' | 'launcher' | 'sweeper' | 'session' | 'human';
+export type PrLabelSweep =
+  | { action: 'none' }
+  | { action: 'mark-stalled'; when: 'run-ended' }
+  | { action: 'close'; afterHours?: number }
+  | { action: 'exclude' }
+  | { action: 'notify'; afterDays: number }
+  | { action: 'block-approval' };
+
+export interface PrLabelDefinition {
+  readonly name: `elanous:${string}`;
+  readonly axis: PrLabelAxis;
+  readonly color: string;
+  readonly description: string;
+  readonly appliedBy: readonly PrLabelApplier[];
+  readonly sweep: PrLabelSweep;
+}
+
+export const PR_LABELS = [
+  { name: 'elanous:running', axis: 'state', color: '1D76DB', description: 'Harness run or session is actively handling a draft PR', appliedBy: ['harness', 'session'], sweep: { action: 'mark-stalled', when: 'run-ended' } },
+  { name: 'elanous:stalled', axis: 'state', color: 'D93F0B', description: 'Incomplete draft requiring human attention', appliedBy: ['harness', 'sweeper'], sweep: { action: 'close', afterHours: STALLED_DRAFT_HOURS } },
+  { name: 'elanous:idea-approval', axis: 'state', color: '0E8A16', description: 'Completed, ready PR awaiting human approval', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:superseded', axis: 'state', color: '6A737D', description: 'Another PR has already merged the same work', appliedBy: ['sweeper', 'session'], sweep: { action: 'close' } },
+  { name: 'elanous:keep', axis: 'addon', color: 'BFDADC', description: 'Human requested that the PR be kept open', appliedBy: ['human'], sweep: { action: 'exclude' } },
+  { name: 'elanous:release-hold', axis: 'addon', color: 'D4C5F9', description: 'Exclude from release notes until verified in production', appliedBy: ['launcher', 'session', 'human'], sweep: { action: 'none' } },
+  { name: 'elanous:idea-stale', axis: 'addon', color: 'FBCA04', description: 'Approval pending beyond the notification threshold', appliedBy: ['sweeper'], sweep: { action: 'notify', afterDays: IDEA_STALE_DAYS } },
+  { name: 'elanous:needs-rebase', axis: 'addon', color: 'E99695', description: 'Approval blocked by conflicts or failing checks', appliedBy: ['sweeper'], sweep: { action: 'block-approval' } },
+  { name: 'elanous:from-harness', axis: 'origin', color: 'C5DEF5', description: 'Launched from a harness goal', appliedBy: ['harness'], sweep: { action: 'none' } },
+  { name: 'elanous:from-intake', axis: 'origin', color: 'C5DEF5', description: 'Launched from an absorbed idea', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-linear', axis: 'origin', color: 'C5DEF5', description: 'Launched from a Linear task', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-asana', axis: 'origin', color: 'C5DEF5', description: 'Launched from an Asana task', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-jira', axis: 'origin', color: 'C5DEF5', description: 'Launched from a Jira task', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-mission', axis: 'origin', color: 'C5DEF5', description: 'Launched from the mission fabric', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-agent', axis: 'origin', color: 'C5DEF5', description: 'Handed off by another agent', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-release', axis: 'origin', color: 'C5DEF5', description: 'Launched from the release loop', appliedBy: ['launcher'], sweep: { action: 'none' } },
+  { name: 'elanous:from-human', axis: 'origin', color: 'C5DEF5', description: 'Opened by a human', appliedBy: ['human'], sweep: { action: 'none' } },
+  { name: 'elanous:risk-security', axis: 'risk', color: 'B60205', description: 'Security-sensitive change', appliedBy: ['launcher', 'human'], sweep: { action: 'none' } },
+  { name: 'elanous:risk-public', axis: 'risk', color: 'D93F0B', description: 'Public documentation or release change', appliedBy: ['launcher', 'human'], sweep: { action: 'none' } },
+  { name: 'elanous:risk-prod', axis: 'risk', color: 'E99695', description: 'Production configuration change', appliedBy: ['launcher', 'human'], sweep: { action: 'none' } },
+] as const satisfies readonly PrLabelDefinition[];
+
+/** Registry order is stable for consumers (including the sync command). */
+export function labelsForAxis(axis: PrLabelAxis): readonly (typeof PR_LABELS)[number][] {
+  return PR_LABELS.filter((label) => label.axis === axis);
+}
+
+/** Unknown labels are not ours to classify; only registered labels participate in cardinality. */
+export function validatePrLabels(labels: readonly string[], isDraft: boolean): string[] {
+  const errors: string[] = [];
+  const names = new Set(labels);
+  for (const axis of ['state', 'origin', 'risk'] as const) {
+    const count = labelsForAxis(axis).filter((label) => names.has(label.name)).length;
+    if (axis === 'risk' ? count > 1 : count !== 1) {
+      errors.push(`${axis}: expected ${axis === 'risk' ? 'at most one' : 'exactly one'} label, found ${count}`);
+    }
+  }
+  if (isDraft && names.has('elanous:idea-approval')) {
+    errors.push('elanous:idea-approval requires a ready PR (not draft)');
+  }
+  return errors;
+}