elanous 0.2.0 → 0.2.5

package/src/harness/self-send-decide.ts

@@ -0,0 +1,233 @@
+import { normalizeSpaceId } from './harness-space.js';
+import type { SelfSendTargetResolution } from './self-send-target.js';
+
+export const SELF_SEND_RECENT_FRAME_WINDOW_MS = 24 * 60 * 60 * 1000;
+export const SELF_SEND_STALE_HEARTBEAT_MS = 5 * 60 * 1000;
+
+export interface SelfSendCandidate {
+  readonly spaceId: string;
+  readonly mtimeMs?: number;
+  readonly liveness?: 'alive' | 'dead' | 'unknown';
+  readonly heartbeatAtMs?: number;
+}
+
+export interface SelfSendCandidateDisplay {
+  readonly lines: readonly string[];
+  readonly hiddenStaleCount: number;
+}
+
+const SELF_SEND_GOAL_ATTEMPT_SUFFIX = /^(.*)-[0-9a-f]{8}(?:-r[a-z0-9]{6})?$/;
+
+function selfSendGoalPrefix(spaceId: string): string | undefined {
+  return SELF_SEND_GOAL_ATTEMPT_SUFFIX.exec(spaceId)?.[1];
+}
+
+function newestSelfSendAttempt(members: readonly SelfSendCandidate[]): SelfSendCandidate | undefined {
+  if (members.length === 0 || members.some((member) => !Number.isFinite(member.mtimeMs))) return undefined;
+  let newest = members[0]!;
+  for (const member of members) if (member.mtimeMs! > newest.mtimeMs!) newest = member;
+  return newest;
+}
+
+function formatSelfSendHeartbeatAge(heartbeatAtMs: number, now: number): string | undefined {
+  if (!Number.isFinite(heartbeatAtMs)) return undefined;
+  const seconds = Math.floor(Math.max(0, now - heartbeatAtMs) / 1_000);
+  if (seconds < 60) return `${seconds}초 전`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}분 전`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}시간 전`;
+  return `${Math.floor(hours / 24)}일 전`;
+}
+
+export function formatSelfSendCandidateDisplay(
+  candidates: readonly SelfSendCandidate[],
+  { includeStale = false, now }: { includeStale?: boolean; now: number },
+): SelfSendCandidateDisplay {
+  const recent: SelfSendCandidate[] = [];
+  const stale: SelfSendCandidate[] = [];
+  for (const candidate of candidates) {
+    const mtimeMs = candidate.mtimeMs;
+    if (Number.isFinite(mtimeMs) && mtimeMs! >= now - SELF_SEND_RECENT_FRAME_WINDOW_MS && mtimeMs! <= now) recent.push(candidate);
+    else stale.push(candidate);
+  }
+  const displayed = includeStale ? [...recent, ...stale] : recent;
+  const groups = new Map<string, SelfSendCandidate[]>();
+  for (const candidate of candidates) {
+    const prefix = selfSendGoalPrefix(candidate.spaceId);
+    if (prefix === undefined) continue;
+    const members = groups.get(prefix);
+    if (members) members.push(candidate);
+    else groups.set(prefix, [candidate]);
+  }
+  return {
+    lines: displayed.map((candidate) => {
+      const timestamp = Number.isFinite(candidate.mtimeMs) ? new Date(candidate.mtimeMs!).toISOString() : '알 수 없음';
+      const prefix = selfSendGoalPrefix(candidate.spaceId);
+      const members = prefix === undefined ? undefined : groups.get(prefix);
+      let annotation = '';
+      if (members && new Set(members.map((member) => member.spaceId)).size >= 2) {
+        annotation = '  · 같은 골의 다른 시도';
+        const newest = newestSelfSendAttempt(members);
+        if (newest !== undefined && candidate.mtimeMs === newest.mtimeMs) annotation += ' · 가장 최근';
+      }
+      const liveness = candidate.liveness ?? 'unknown';
+      const heartbeatAge = liveness === 'alive' && candidate.heartbeatAtMs !== undefined
+        ? formatSelfSendHeartbeatAge(candidate.heartbeatAtMs, now) : undefined;
+      const livenessAnnotation = liveness === 'alive'
+        ? `  · 자식 생존${heartbeatAge === undefined ? '' : ` (heartbeat ${heartbeatAge})`}`
+        : liveness === 'dead' ? '  · 자식 사망 (heartbeat alive=false)' : '';
+      return `  ${candidate.spaceId}  마지막 프레임: ${timestamp}${annotation}${livenessAnnotation}`;
+    }),
+    hiddenStaleCount: includeStale ? 0 : stale.length,
+  };
+}
+
+export interface SelfSendRunScreen {
+  logStoreStatus: string;
+  logStorePath: string;
+  screenKey?: string | null;
+  lastEvent?: { category: string; event: string; timestamp: string } | null;
+  missingStatus?: 'awaiting-start' | 'pipeline-failed' | 'cleaned' | 'not-found' | string;
+}
+
+export interface SelfSendLedger {
+  runId: string;
+  entries: readonly { event: string; data: Record<string, unknown> }[];
+}
+
+export interface SelfSendDecisionInput {
+  space?: string;
+  opts: { stop?: boolean; memo?: string; run?: string; includeStale?: boolean; readWait?: string };
+  now: number;
+}
+
+export interface SelfSendDecisionDeps {
+  resolveRunScreen(runId: string): SelfSendRunScreen;
+  podFragmentsForRun(runId: string): readonly { spaceId: string }[];
+  resolveTarget(space: string): SelfSendTargetResolution;
+  isPodFragment(spaceId: string): boolean;
+  screens(): readonly SelfSendCandidate[];
+  ledgers(): readonly SelfSendLedger[];
+  runScreenKey(runId: string): string | null | undefined;
+}
+
+export type SelfSendDecision =
+  | { kind: 'refuse'; message: string; exitCode: 1 | 2 }
+  | { kind: 'send'; spaceId: string; channel: 'inbox' | 'pod'; warnings: readonly string[] };
+
+const refuse = (message: string, exitCode: 1 | 2): SelfSendDecision => ({ kind: 'refuse', message, exitCode });
+
+export function decideSelfSend(input: SelfSendDecisionInput, deps: SelfSendDecisionDeps): SelfSendDecision {
+  const { space, opts, now } = input;
+  if (space !== undefined && opts.run !== undefined) return refuse('--run 과 space 는 함께 사용할 수 없습니다.\n', 2);
+  if (opts.run !== undefined && opts.run.trim() === '') return refuse('--run 에 빈 runId 를 줄 수 없습니다.\n', 2);
+  let requestedSpace = space;
+  let podRunSpace: string | undefined;
+  if (opts.run !== undefined) {
+    const resolved = deps.resolveRunScreen(opts.run);
+    if (resolved.logStoreStatus !== 'read' && resolved.screenKey) {
+      return refuse(`run 화면 해석 불가: 로그 스토어 ${resolved.logStoreStatus} (${resolved.logStorePath})\n`, 1);
+    }
+    if (!resolved.screenKey) {
+      const fragments = deps.podFragmentsForRun(opts.run);
+      if (fragments.length === 1) requestedSpace = podRunSpace = fragments[0]!.spaceId;
+      else {
+        if (fragments.length > 1) return refuse(`run 의 Pod 조각이 여러 개입니다: ${opts.run}. space 이름으로 다시 보내세요:\n${fragments.map((fragment) => `  ${fragment.spaceId}`).join('\n')}\n`, 2);
+        if (resolved.logStoreStatus !== 'read') {
+          return refuse(`run 화면 해석 불가: 로그 스토어 ${resolved.logStoreStatus} (${resolved.logStorePath}) · Pod 조각 기록도 0\n`, 1);
+        }
+        const last = resolved.lastEvent;
+        const lastDetail = last
+          ? ` 마지막 이벤트: ${last.category}/${last.event} (${Number.isFinite(Date.parse(last.timestamp)) ? `${Math.max(0, Math.floor((now - Date.parse(last.timestamp)) / 60_000))}분 전` : '시각 알 수 없음'})`
+          : ' 마지막 이벤트: 없음';
+        const status = resolved.missingStatus;
+        const guidance = status === 'awaiting-start'
+          ? '아직 화면을 띄우기 전입니다. 되묻기에 답하거나 저작이 끝날 때까지 기다리세요.'
+          : status === 'pipeline-failed' ? '파이프라인이 오류로 멈췄습니다. 해당 error를 읽어 원인을 수리하세요.'
+            : status === 'cleaned' ? '하니스가 정리되어 화면이 없습니다. 필요하면 새 런을 시작하세요.'
+              : status === 'not-found' ? '이 runId의 이벤트가 없습니다. runId와 인스턴스 우주를 확인하세요.'
+                : '화면을 아직 분류할 수 없습니다. 마지막 이벤트를 조사하세요.';
+        return refuse(`run 화면 해석 불가: ${guidance}${lastDetail} (${opts.run}) · Pod 조각 기록도 0\n`, 1);
+      }
+    } else requestedSpace = normalizeSpaceId(resolved.screenKey);
+  }
+  const hasMemo = opts.memo !== undefined;
+  if (opts.stop && hasMemo) return refuse('self send에서는 --stop 과 --memo를 함께 사용할 수 없습니다.\n', 2);
+  if (!opts.stop && !hasMemo) return refuse('self send에는 --stop 또는 --memo <sentence>가 필요합니다.\n', 2);
+  if (space !== undefined) {
+    const resolution = deps.resolveTarget(space);
+    if (resolution.kind === 'refuse') {
+      const hint = resolution.hint === undefined ? '' : ` 대신 space ${resolution.hint}를 지정하세요.`;
+      const reason = resolution.reason === 'tui-self-report-has-no-inbox-reader'
+        ? 'tui 자기 보고 대상에는 control inbox를 읽는 쪽이 없습니다.'
+        : resolution.reason === 'pty-not-found' ? '지정한 PTY를 찾을 수 없습니다.'
+          : '지정한 PTY에 연결된 harness space가 없습니다.';
+      return refuse(`self send 대상 거절: ${reason}${hint}\n`, 2);
+    }
+    requestedSpace = resolution.spaceId;
+  }
+  if (requestedSpace !== undefined && (podRunSpace !== undefined || deps.isPodFragment(requestedSpace))) {
+    return { kind: 'send', spaceId: requestedSpace, channel: 'pod', warnings: [] };
+  }
+  const screens = deps.screens();
+  const explicitScreen = requestedSpace === undefined ? undefined : screens.find((screen) => screen.spaceId === requestedSpace);
+  if (requestedSpace !== undefined && !explicitScreen) {
+    const candidates = screens.length === 0 ? '  (후보 없음)' : screens.map((screen) => `  ${screen.spaceId}`).join('\n');
+    if (opts.run !== undefined) return refuse(`run 화면 해석 불가: 해석한 화면이 없습니다: ${requestedSpace} (${opts.run})\n`, 1);
+    return refuse(`알 수 없는 self send 대상 space: ${requestedSpace}. 후보 중 하나를 지정하세요:\n${candidates}\n`, 2);
+  }
+  if (space !== undefined && explicitScreen) {
+    const goalPrefix = selfSendGoalPrefix(explicitScreen.spaceId);
+    const sameGoalAttempts = goalPrefix === undefined ? [] : screens.filter((screen) => selfSendGoalPrefix(screen.spaceId) === goalPrefix);
+    const newest = newestSelfSendAttempt(sameGoalAttempts);
+    if (newest !== undefined && newest.spaceId !== explicitScreen.spaceId && newest.mtimeMs! > explicitScreen.mtimeMs!) {
+      return refuse(`지정한 self send 대상은 같은 골의 더 최근 시도로 교체되었습니다: ${explicitScreen.spaceId} → ${newest.spaceId}. 더 최근 space를 지정해 다시 보내세요.\n`, 2);
+    }
+  }
+  if (requestedSpace === undefined && screens.length !== 1) {
+    const display = formatSelfSendCandidateDisplay(screens, { includeStale: opts.includeStale, now });
+    const candidates = screens.length === 0 ? '  (후보 없음)' : [
+      ...display.lines,
+      ...(display.hiddenStaleCount > 0 ? [`  오래된 후보 ${display.hiddenStaleCount}개 숨김 (--include-stale로 표시)`] : []),
+    ].join('\n');
+    return refuse(`soft stop 대상이 모호합니다. space를 지정하세요. 후보와 마지막 프레임 시각:\n${candidates}\n`, 2);
+  }
+  const selectedScreen = requestedSpace === undefined ? screens[0]! : explicitScreen!;
+  const warnings: string[] = [];
+  if (hasMemo) {
+    let runId = opts.run;
+    let lifecycle: 'continuing' | 'terminal' | 'unknown' = 'unknown';
+    try {
+      const ledgers = deps.ledgers();
+      if (runId === undefined) {
+        for (const candidate of ledgers) {
+          if (normalizeSpaceId(deps.runScreenKey(candidate.runId) ?? '') === selectedScreen.spaceId) {
+            runId = candidate.runId;
+            break;
+          }
+        }
+      }
+      if (runId !== undefined) {
+        const ledger = ledgers.find((candidate) => candidate.runId === runId)?.entries;
+        if (ledger !== undefined) {
+          for (const entry of ledger) {
+            if (entry.event === 'start' || entry.event === 'run-start' || (entry.event === 'run-status' && entry.data.runStatus === 'running')) lifecycle = 'continuing';
+            else if (entry.event === 'terminal' || entry.event === 'run-status') lifecycle = 'terminal';
+          }
+        }
+      }
+    } catch { /* unreadable lifecycle evidence remains unknown */ }
+    if (lifecycle === 'terminal') {
+      return refuse(`self send 대상 런이 이미 종료되었습니다: ${runId ?? selectedScreen.spaceId}. 메모를 기록하지 않았습니다. 새 런을 시작해 다시 보내세요.\n`, 2);
+    }
+    if (lifecycle === 'unknown') warnings.push(`경고: self send 대상 런의 lifecycle 상태를 알 수 없습니다: ${runId ?? selectedScreen.spaceId}. 기록은 계속합니다.\n`);
+  } else if (selectedScreen.liveness === 'dead') {
+    return refuse(`self send 대상 자식이 heartbeat alive=false로 사망한 상태입니다: ${selectedScreen.spaceId}. 메모를 기록하지 않았습니다. 새 런을 시작하거나 살아 있는 space를 지정해 다시 보내세요.\n`, 2);
+  }
+  if (selectedScreen.liveness === 'unknown') warnings.push(`경고: self send 대상의 heartbeat 상태를 알 수 없습니다: ${selectedScreen.spaceId}. 기록은 계속합니다.\n`);
+  if (selectedScreen.liveness === 'alive' && selectedScreen.heartbeatAtMs !== undefined && now - selectedScreen.heartbeatAtMs > SELF_SEND_STALE_HEARTBEAT_MS) {
+    warnings.push(`경고: self send 대상 space가 죽어 보입니다: ${selectedScreen.spaceId}. heartbeat가 5분보다 오래되어 메모가 전달되지 않을 수 있습니다.\n`);
+  }
+  return { kind: 'send', spaceId: selectedScreen.spaceId, channel: 'inbox', warnings };
+}

package/src/harness/self-send-target.ts

@@ -1,12 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
+import { normalizeRunId } from './harness-space.js';
 import { controlInboxPath, type ControlMemoPayload } from './control-inbox.js';
 import { sendPodControl } from './pod-control-send.js';
 import type { Kubectl } from '../task-orchestrator/surfaces/self-implement-pod.js';
 
 export interface PodFragmentRecord {
   spaceId: string;
+  runId?: string;
+  parentRunId?: string;
   context: string;
   namespace: string;
   job: string;
@@ -29,6 +32,24 @@ export function podFragmentFinished(spaceId: string, env?: NodeJS.ProcessEnv): b
   return existsSync(`${podRecordPath(spaceId, env)}.finished`);
 }
 
+export function listPodFragmentsForRun(runId: string, env?: NodeJS.ProcessEnv): PodFragmentRecord[] {
+  if (!runId || runId !== normalizeRunId(runId)) return [];
+  const dir = dirname(podRecordPath('fragment', env));
+  let names: string[];
+  try { names = readdirSync(dir); } catch { return []; }
+  const suffix = '.inbox.pod.json';
+  const matches: PodFragmentRecord[] = [];
+  for (const name of names) {
+    if (!name.endsWith(suffix)) continue;
+    const spaceId = name.slice(0, -suffix.length);
+    if (podFragmentFinished(spaceId, env)) continue;
+    const record = readPodFragment(spaceId, env);
+    if (record && ((record.runId === runId && normalizeRunId(record.runId) === runId)
+      || (record.parentRunId === runId && normalizeRunId(record.parentRunId) === runId))) matches.push(record);
+  }
+  return matches;
+}
+
 export function writePodFragment(record: PodFragmentRecord, env?: NodeJS.ProcessEnv): void {
   const path = podRecordPath(record.spaceId, env);
   mkdirSync(dirname(path), { recursive: true });

package/src/harness/shell-relay.ts

@@ -21,6 +21,9 @@ import type { SurfaceUx } from '../agent/surface-ux/types.js';
 import type { AutoDrive } from './staged-harness.js';
 import { dispatchPtyShellSend } from '../skills/tools/pty.js';
 import { debug } from '../debug/log.js';
+import { getHarnessRunId } from './harness-space.js';
+import { emitDecision } from '../live/detail-switch.js';
+import { escalateDecision } from '../self-implement/decision-events.js';
 
 /** relay 게이트 결정 — auto(자율 답·operator 안 부름) vs escalate(막으로 외부 전파). */
 export type RelayMode = 'auto' | 'escalate';
@@ -176,12 +179,14 @@ export async function relayShellPrompt(input: RelayShellPromptInput): Promise<Re
       answer = typeof picked === 'string' ? picked : Array.isArray(picked) ? (picked[0] ?? null) : null;
       if (answer === null) reason = res == null ? 'non-interactive-menu-fail-closed' : 'cancelled';
       debug.log('harness.relay', 'escalate-question', { shellId, answer: answer ? digest(answer) : null, interactive: ux.interactive });
+      try { emitDecision(escalateDecision({ runId: getHarnessRunId() || undefined, shellId, answer, interactive: ux.interactive, mode: 'question' })); } catch { /* observation must not change the relay outcome */ }
     } else {
       // y/N → ux.confirm. 채널 없으면 fail-closed false → 안전측 decline(noBytes) 주입.
       const ok = await ux.confirm({ prompt, detail: `셸 ${shellId}`, yesLabel: '예', noLabel: '아니오' });
       answer = ok ? yesBytes : noBytes;
       if (!ok && !ux.interactive) reason = 'non-interactive-fail-closed-decline';
       debug.log('harness.relay', 'escalate-confirm', { shellId, ok, answer: digest(answer), interactive: ux.interactive });
+      try { emitDecision(escalateDecision({ runId: getHarnessRunId() || undefined, shellId, answer: reason === 'non-interactive-fail-closed-decline' ? null : answer, interactive: ux.interactive, mode: 'confirm', safeDecline: reason === 'non-interactive-fail-closed-decline' })); } catch { /* observation must not change the relay outcome */ }
     }
   }
 

package/src/harness/worktree-branch-prefix.ts

@@ -22,11 +22,12 @@ export function slugifyFeature(feature: string): string {
 /** 하니스가 만드는 `self-impl/<슬러그>-<8자리 16진수>` 브랜치 이름.
  *  goalId 가 있으면 읽는 자(`branchGoalId`, `/(?:^|-)goalid-([^/-]+)-/`)와 호환되는
  *  `goalid-<id>-` 구간을 슬러그 앞에 싣는다. 없으면 기존과 바이트 단위로 같다. */
-export function plannedSelfImplBranch(feature: string, goalId?: string): string {
+export function plannedSelfImplBranch(feature: string, goalId?: string, runId?: string): string {
   const slug = slugifyFeature(feature);
   const id = goalId?.trim() ?? '';
-  if (!id) return `${WORKTREE_BRANCH_PREFIX}${slug}`;
+  const runSuffix = runId === undefined ? '' : `-r${runId.replace(/^run-/i, '').replace(/[^a-z0-9]/gi, '').slice(0, 6).toLowerCase()}`;
+  if (!id) return `${WORKTREE_BRANCH_PREFIX}${slug}${runSuffix}`;
   const readable = slug.replace(/-[0-9a-f]{8}$/, '');
   const digest = createHash('sha256').update(id).digest('hex').slice(0, 8);
-  return `${WORKTREE_BRANCH_PREFIX}goalid-${id}-${readable}-${digest}`;
+  return `${WORKTREE_BRANCH_PREFIX}goalid-${id}-${readable}-${digest}${runSuffix}`;
 }

package/src/hooks/providers.ts

@@ -0,0 +1,77 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export type HookProvider = 'linear' | 'asana';
+export interface ExternalTask {
+  eventId: string;
+  title: string;
+  description?: string;
+  external: { provider: HookProvider; ref: string; url?: string };
+}
+export type Verification = { ok: true; body: unknown; eventIds: string[]; ignored?: string } | { ok: false; reason: 'bad-signature' | 'stale' | 'invalid-body' };
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function equalSignature(raw: Buffer, secret: string, signature: string | null): boolean {
+  if (!signature || !/^[a-f0-9]{64}$/i.test(signature)) return false;
+  const expected = createHmac('sha256', secret).update(raw).digest();
+  return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
+}
+export function asanaEventId(event: unknown): string | undefined {
+  const row = object(event);
+  const gid = text(object(row?.resource)?.gid);
+  const action = text(row?.action);
+  const created = text(row?.created_at);
+  return gid && action && created ? `${gid}:${action}:${created}` : undefined;
+}
+
+export function verifyWebhook(provider: HookProvider, raw: Buffer, headers: Headers, secret: string, now = Date.now()): Verification {
+  if (!equalSignature(raw, secret, headers.get(provider === 'linear' ? 'linear-signature' : 'x-hook-signature')))
+    return { ok: false, reason: 'bad-signature' };
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw.toString('utf8')); } catch { return { ok: false, reason: 'invalid-body' }; }
+  const body = object(parsed);
+  if (!body) return { ok: false, reason: 'invalid-body' };
+  if (provider === 'linear') {
+    const timestamp = body.webhookTimestamp;
+    if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || Math.abs(now - timestamp) > 60_000)
+      return { ok: false, reason: 'stale' };
+    // Linear 은 실패 응답이 쌓이면 웹훅을 꺼 버린다 — 서명이 맞는 «대상 아닌» 이벤트(댓글·수정 등)는
+    // 거절하지 않고 받아서 버린다. 지금 태스크로 만드는 것은 이슈 생성뿐이다.
+    if (body.type !== 'Issue' || body.action !== 'create')
+      return { ok: true, body, eventIds: [], ignored: `${String(body.type)}:${String(body.action)}` };
+    const eventId = text(headers.get('linear-delivery')) ?? (text(body.webhookId) && text(body.createdAt) ? `${body.webhookId}:${body.createdAt}` : undefined);
+    if (!eventId || !object(body.data) || !text(object(body.data)?.id) || !text(object(body.data)?.title))
+      return { ok: false, reason: 'invalid-body' };
+    return { ok: true, body, eventIds: [eventId] };
+  }
+  if (!Array.isArray(body.events)) return { ok: false, reason: 'invalid-body' };
+  const ids = body.events.map(asanaEventId);
+  if (ids.some(id => !id)) return { ok: false, reason: 'invalid-body' };
+  return { ok: true, body, eventIds: ids as string[] };
+}
+
+export function toExternalTask(provider: HookProvider, body: unknown): ExternalTask {
+  const row = object(body);
+  if (!row) throw new Error('invalid hook body');
+  if (provider === 'linear') {
+    const issue = object(row.data);
+    const ref = text(issue?.id);
+    const title = text(issue?.title);
+    const eventId = text(row.eventId) ?? (text(row.webhookId) && text(row.createdAt) ? `${row.webhookId}:${row.createdAt}` : undefined);
+    if (!ref || !title || !eventId) throw new Error('invalid linear issue');
+    return { eventId, title, ...(text(issue?.description) ? { description: text(issue?.description) } : {}),
+      external: { provider, ref, ...(text(issue?.url) ? { url: text(issue?.url) } : {}) } };
+  }
+  const event = object(row.event);
+  const task = object(row.task);
+  const ref = text(object(event?.resource)?.gid);
+  const eventId = asanaEventId(event);
+  if (!ref || !eventId) throw new Error('invalid asana event');
+  return { eventId, title: text(task?.name) ?? `Asana task ${ref}`,
+    ...(text(task?.notes) ? { description: text(task?.notes) } : {}),
+    external: { provider, ref, ...(text(task?.permalink_url) ? { url: text(task?.permalink_url) } : {}) } };
+}

package/src/hooks/queue.ts

@@ -0,0 +1,73 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { ExternalTask } from './providers.js';
+
+export interface QueuedHook { provider: ExternalTask['external']['provider']; eventId: string; task: ExternalTask }
+
+export class HookQueue {
+  readonly directory: string;
+  readonly seenPath: string;
+  readonly deliveredPath: string;
+  private readonly seen = new Set<string>();
+
+  constructor(root: string = effectiveInstanceRoot()) {
+    const hooks = join(root, 'hooks');
+    this.directory = join(hooks, 'queue');
+    this.seenPath = join(hooks, 'seen.jsonl');
+    this.deliveredPath = join(hooks, 'last-delivered');
+    mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    if (existsSync(this.seenPath)) {
+      for (const line of readFileSync(this.seenPath, 'utf8').split('\n')) {
+        if (!line) continue;
+        const key: unknown = JSON.parse(line);
+        if (typeof key !== 'string') throw new Error('invalid hooks seen entry');
+        this.seen.add(key);
+      }
+    }
+    // A crash between publishing the queue file and appending seen must not create
+    // a second copy on replay (or allow a corrupt ledger to discard queued work).
+    for (const event of this.entries()) this.seen.add(`${event.provider}:${event.eventId}`);
+  }
+
+  private filename(provider: string, eventId: string): string {
+    return join(this.directory, `${createHash('sha256').update(`${provider}:${eventId}`).digest('hex')}.json`);
+  }
+
+  enqueue(event: QueuedHook): boolean {
+    const key = `${event.provider}:${event.eventId}`;
+    const path = this.filename(event.provider, event.eventId);
+    if (this.seen.has(key)) return false;
+    if (!existsSync(path)) this.atomicWrite(path, JSON.stringify(event));
+    const fd = openSync(this.seenPath, 'a', 0o600);
+    try { writeSync(fd, `${JSON.stringify(key)}\n`); fsyncSync(fd); }
+    finally { closeSync(fd); }
+    this.seen.add(key);
+    return true;
+  }
+
+  private atomicWrite(path: string, content: string): void {
+    const temp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    try {
+      const fd = openSync(temp, 'wx', 0o600);
+      try { writeSync(fd, content); fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(temp, path);
+      const dir = openSync(dirname(path), 'r');
+      try { fsyncSync(dir); } finally { closeSync(dir); }
+    } finally { rmSync(temp, { force: true }); }
+  }
+
+  entries(): QueuedHook[] {
+    return readdirSync(this.directory).filter(name => /^[a-f0-9]{64}\.json$/.test(name))
+      .map(name => JSON.parse(readFileSync(join(this.directory, name), 'utf8')) as QueuedHook);
+  }
+  count(): number { return readdirSync(this.directory).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).length; }
+  delivered(event: QueuedHook, now: number = Date.now()): void {
+    this.atomicWrite(this.deliveredPath, new Date(now).toISOString());
+    rmSync(this.filename(event.provider, event.eventId));
+  }
+  lastDelivered(): string | null {
+    return existsSync(this.deliveredPath) ? readFileSync(this.deliveredPath, 'utf8') : null;
+  }
+}

package/src/hooks/receiver.ts

@@ -0,0 +1,133 @@
+import { debug } from '../debug/log.js';
+import { readFileSync } from 'node:fs';
+import { userConfigPath } from '../user-config.js';
+import { getSecretAsync } from '../nexus/config/secrets/index.js';
+import { HookQueue, type QueuedHook } from './queue.js';
+import { toExternalTask, verifyWebhook, type HookProvider } from './providers.js';
+
+export interface HookSecrets {
+  linear?: string;
+  asana?: string;
+  saveAsana?: (secret: string) => Promise<void>;
+}
+export interface HookReceiverOptions {
+  host?: string;
+  port: number;
+  secrets: HookSecrets;
+  forward?: (event: QueuedHook) => Promise<Response | number>;
+  now?: () => number;
+  root?: string;
+  retryBaseMs?: number;
+}
+
+/** `/v1/tasks` lives on the Primary's nexus API, not on the control plane — so the address is its own setting. */
+export function hooksPrimaryUrl(config: { hooks?: { primaryUrl?: unknown } }): URL {
+  const value = config.hooks?.primaryUrl;
+  if (typeof value !== 'string' || !value) throw new Error('hooks.primaryUrl missing');
+  const url = new URL(value);
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new Error('hooks.primaryUrl must be http(s)');
+  return url;
+}
+
+async function forwardToPrimary(event: QueuedHook): Promise<Response> {
+  const config = JSON.parse(readFileSync(userConfigPath(), 'utf8')) as { hooks?: { primaryTokenRef?: string; primaryUrl?: unknown } };
+  const ref = config.hooks?.primaryTokenRef;
+  if (!ref) throw new Error('primary token reference missing');
+  const token = await getSecretAsync(ref);
+  if (!token) throw new Error('primary token missing');
+  return fetch(new URL('/v1/tasks', hooksPrimaryUrl(config)), {
+    method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}`,
+      'x-elanous-trace-id': `${event.provider}:${event.eventId}` },
+    body: JSON.stringify({ ...event.task, eventId: `${event.provider}:${event.eventId}` }), signal: AbortSignal.timeout(10_000),
+  });
+}
+
+export function startHookReceiver(options: HookReceiverOptions): { url: string; stop: () => void; queue: HookQueue } {
+  const queue = new HookQueue(options.root);
+  const now = options.now ?? Date.now;
+  const forward = options.forward ?? forwardToPrimary;
+  const attempts = new Map<string, { next: number; failures: number }>();
+  const pending = new Set<string>();
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let draining = false;
+  async function drain(): Promise<void> {
+    if (stopped || draining) return;
+    draining = true;
+    if (timer) { clearTimeout(timer); timer = undefined; }
+    try {
+      for (const event of queue.entries()) {
+        const key = `${event.provider}:${event.eventId}`;
+        if (pending.has(key) || (attempts.get(key)?.next ?? 0) > Date.now()) continue;
+        pending.add(key);
+        void (async () => {
+          try {
+            const result = await forward(event);
+            if (typeof result === 'number' ? result < 200 || result >= 300 : !result.ok)
+              throw new Error('forward failed');
+            queue.delivered(event, now());
+            attempts.delete(key);
+          } catch {
+            const base = Math.max(1, options.retryBaseMs ?? 1000);
+            const failures = (attempts.get(key)?.failures ?? 0) + 1;
+            attempts.set(key, { next: Date.now() + Math.min(300_000, base * 2 ** Math.min(failures - 1, 20)), failures });
+          } finally { pending.delete(key); }
+        })();
+      }
+    } finally {
+      draining = false;
+      if (!stopped) timer = setTimeout(() => { void drain(); }, Math.min(1000, options.retryBaseMs ?? 1000));
+    }
+  }
+  const server = Bun.serve({ hostname: options.host ?? '127.0.0.1', port: options.port,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/hooks/health')
+        return Response.json({ ok: true, queued: queue.count() });
+      if (request.method !== 'POST' || !/^\/hooks\/(linear|asana)$/.test(url.pathname)) return new Response('Not Found', { status: 404 });
+      const provider = url.pathname.slice('/hooks/'.length) as HookProvider;
+      const reject = (reason: string) => {
+        debug.log('hooks.receiver', 'rejected', { provider, reason });
+        return new Response('Unauthorized', { status: 401 });
+      };
+      try {
+        if (provider === 'asana' && request.headers.has('x-hook-secret')) {
+          const secret = request.headers.get('x-hook-secret')!;
+          if (!secret || /[\r\n]/.test(secret) || (options.secrets.asana && options.secrets.asana !== secret) ||
+              (!options.secrets.asana && !options.secrets.saveAsana)) return reject('invalid-handshake');
+          if (!options.secrets.asana) {
+            await options.secrets.saveAsana!(secret);
+            options.secrets.asana = secret;
+          }
+          return new Response(null, { status: 200, headers: { 'X-Hook-Secret': secret } });
+        }
+        const secret = options.secrets[provider];
+        if (!secret) return reject('missing-secret');
+        const raw = Buffer.from(await request.arrayBuffer());
+        const verified = verifyWebhook(provider, raw, request.headers, secret, now());
+        if (!verified.ok) return reject(verified.reason);
+        if (verified.ignored !== undefined) {
+          debug.log('hooks.receiver', 'ignored', { provider, kind: verified.ignored });
+          return new Response(null, { status: 200 });
+        }
+        if (provider === 'linear') {
+          const eventId = verified.eventIds[0]!;
+          queue.enqueue({ provider, eventId, task: toExternalTask(provider, { ...(verified.body as object), eventId }) });
+        } else {
+          const body = verified.body as { events: unknown[] };
+          const tasks = body.events.map(event => toExternalTask(provider, { event, task: (event as { task?: unknown }).task }));
+          for (const task of tasks) queue.enqueue({ provider, eventId: task.eventId, task });
+        }
+        if (!draining) {
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(() => { void drain(); }, 0);
+        }
+        return new Response(null, { status: 200 });
+      } catch {
+        return new Response('Service Unavailable', { status: 503 });
+      }
+    },
+  });
+  void drain();
+  return { url: server.url.toString(), queue, stop() { stopped = true; if (timer) clearTimeout(timer); server.stop(); } };
+}