elanous 0.2.9 → 0.2.11

package/src/hooks/dispatch.ts

@@ -0,0 +1,82 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { runSeatLoopOnce } from '../seat-loop/seat-loop.js';
+import { getUserConfig } from '../user-config.js';
+import { openMsgStore } from '../msg/msg-store.js';
+import type { EventsConfig } from '../user-config.js';
+import type { QueuedHook } from './queue.js';
+
+export type HookWake = (seat: string) => Promise<unknown>;
+
+// A crashed wake can be reclaimed after the lease expires; a live wake renews it until completion.
+const WAKE_LEASE_MS = 120_000;
+const DEFAULT_SEAT_ROUTES = [
+  { source: 'linear', kind: 'Issue:update', seat: (event: QueuedHook, config: EventsConfig) =>
+    event.task.assigneeId ? config.linearAssignees[event.task.assigneeId] : undefined },
+  { source: 'github', kind: 'pull_request:review_requested', seat: 'TC' },
+  { source: 'github', kind: 'check_run:completed', seat: 'TC' },
+  { source: 'github', kind: 'check_suite:completed', seat: 'TC' },
+] as const;
+
+/** Record a work card and inbox delivery atomically. Wake state: 0 = retryable, 2 = leased, 1 = done, 3 = seat loop off (terminal).
+ *  `events.mode` decides only whether the card is delivered; the wake runs the seat loop under its own `loops.seat` mode.
+ *  So a delivered card with the seat loop off is not retried (the card waits in the inbox), and a shadow loop's wake is
+ *  recorded as `wake_status = 'shadow'` — visible as «not executed», not mistaken for a real run. */
+export async function dispatchHook(event: QueuedHook, root: string, config: EventsConfig,
+  wake: HookWake = seat => runSeatLoopOnce(seat, { root, config: getUserConfig().loops?.seat ?? { mode: 'off' } }),
+  now: () => number = Date.now): Promise<void> {
+  const key = `${event.provider}:${event.eventId}`;
+  const route = config.routes.find(candidate => candidate.source === event.provider && candidate.kind === event.kind);
+  const defaultSeat = DEFAULT_SEAT_ROUTES.find(candidate => candidate.source === event.provider && candidate.kind === event.kind)?.seat;
+  const defaultResolvedSeat = typeof defaultSeat === 'function' ? defaultSeat(event, config) : defaultSeat;
+  if (event.provider === 'linear' && event.kind === 'Issue:update' && !route && !defaultResolvedSeat)
+    throw new Error('Linear issue update assignee is not mapped to a seat');
+  const seat = route?.seat ?? defaultResolvedSeat ?? 'OP';
+  const store = openMsgStore(join(root, 'msg', 'messages.db'));
+  const claim = randomUUID();
+  try {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS hook_work_cards (
+      event_key TEXT PRIMARY KEY, source TEXT NOT NULL, kind TEXT NOT NULL,
+      seat TEXT NOT NULL, loop TEXT NOT NULL, mode TEXT NOT NULL, title TEXT NOT NULL,
+      message_id INTEGER, woken INTEGER NOT NULL DEFAULT 0,
+      wake_claim TEXT, wake_lease_until INTEGER
+    )`);
+    const columns = store.db.query('PRAGMA table_info(hook_work_cards)').all() as Array<{ name: string }>;
+    if (!columns.some(column => column.name === 'wake_claim')) store.db.exec('ALTER TABLE hook_work_cards ADD COLUMN wake_claim TEXT');
+    if (!columns.some(column => column.name === 'wake_lease_until')) store.db.exec('ALTER TABLE hook_work_cards ADD COLUMN wake_lease_until INTEGER');
+    if (!columns.some(column => column.name === 'wake_status')) store.db.exec('ALTER TABLE hook_work_cards ADD COLUMN wake_status TEXT');
+    store.db.transaction(() => {
+      const existing = store.db.query('SELECT event_key FROM hook_work_cards WHERE event_key = ?').get(key);
+      if (existing) return;
+      const live = config.mode === 'on';
+      let messageId: number | null = null;
+      if (live) {
+        const body = `[작업 카드 · ${key} · ${event.kind ?? 'unknown'} · loop: seat] ${event.task.title}\n${event.task.external.url ?? event.task.external.ref}`;
+        messageId = store.append({ from: 'HOOKS', to: seat, kind: 'hook-task', body }).id;
+      }
+      store.db.query(`INSERT INTO hook_work_cards(event_key, source, kind, seat, loop, mode, title, message_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(key, event.provider, event.kind ?? 'unknown', seat, route?.loop ?? 'seat', live ? 'on' : 'shadow', event.task.title, messageId);
+    })();
+    const leaseAt = now();
+    const acquired = store.db.query(`UPDATE hook_work_cards SET woken = 2, wake_claim = ?, wake_lease_until = ?
+      WHERE event_key = ? AND message_id IS NOT NULL
+        AND (woken = 0 OR (woken = 2 AND (wake_lease_until IS NULL OR wake_lease_until <= ?)))`)
+      .run(claim, leaseAt + WAKE_LEASE_MS, key, leaseAt).changes === 1;
+    if (!acquired) return;
+    const renew = () => store.db.query(`UPDATE hook_work_cards SET wake_lease_until = ?
+      WHERE event_key = ? AND woken = 2 AND wake_claim = ?`).run(now() + WAKE_LEASE_MS, key, claim);
+    const heartbeat = setInterval(renew, WAKE_LEASE_MS / 4);
+    try {
+      const result = await wake(seat);
+      const status = result && typeof result === 'object' && 'status' in result && typeof result.status === 'string' ? result.status : 'woken';
+      // Seat loop off is a policy, not a transient failure: keep the card in the inbox and stop retrying.
+      const final = status === 'skipped-off' ? 3 : 1;
+      store.db.query('UPDATE hook_work_cards SET woken = ?, wake_status = ?, wake_claim = NULL, wake_lease_until = NULL WHERE event_key = ? AND woken = 2 AND wake_claim = ?').run(final, status, key, claim);
+      debug.log('hooks.dispatch', 'wake', { key, seat, status, retry: false });
+    } catch (error) {
+      store.db.query('UPDATE hook_work_cards SET woken = 0, wake_claim = NULL, wake_lease_until = NULL WHERE event_key = ? AND woken = 2 AND wake_claim = ?').run(key, claim);
+      throw error;
+    } finally { clearInterval(heartbeat); }
+  } finally { store.close(); }
+}

package/src/hooks/expose.ts

@@ -0,0 +1,254 @@
+import { spawnSync } from 'node:child_process';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { DecisionLedger, type DecisionEntry } from '../decisions/decision-ledger.js';
+
+export const PUBLIC_HOOK_PATH = '/hooks/linear';
+export const PUBLIC_GITHUB_HOOK_PATH = '/hooks/github';
+export const PUBLIC_HOOK_PORT = 31481;
+const HTTPS_PORT = 8443;
+export const HOOK_EXPOSURE_REF = 'hooks.expose:/hooks/linear';
+const ON_ARGS = ['funnel', '--bg', `--https=${HTTPS_PORT}`, String(PUBLIC_HOOK_PORT)];
+const OFF_ARGS = ['funnel', '--bg', `--https=${HTTPS_PORT}`, 'off'];
+const PROBE_PATH = '/.hooks-ingress-identity';
+const identityFile = (stateDir?: string) => join(stateDir ?? elanousStateRoot(), 'hooks', 'ingress-identity.json');
+interface IngressIdentity { port: number; secret: string }
+
+/** A fresh, private challenge key belongs to the listener that actually bound the port. */
+function readIngressIdentity(stateDir?: string): IngressIdentity {
+  const identity = JSON.parse(readFileSync(identityFile(stateDir), 'utf8')) as IngressIdentity;
+  if (!Number.isInteger(identity.port) || identity.port < 1 || identity.port > 65535 ||
+      typeof identity.secret !== 'string' || !/^[a-f0-9]{64}$/.test(identity.secret)) throw new Error('invalid ingress identity');
+  return identity;
+}
+
+async function verifyIngress(stateDir?: string, port = PUBLIC_HOOK_PORT): Promise<boolean> {
+  let identity: IngressIdentity;
+  try { identity = readIngressIdentity(stateDir); } catch { return false; }
+  if (identity.port !== port) return false;
+  const nonce = randomBytes(32).toString('hex');
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}${PROBE_PATH}`, {
+      headers: { 'x-hooks-ingress-challenge': nonce,
+        'x-hooks-ingress-proof': createHmac('sha256', identity.secret).update(`request:${nonce}`).digest('hex') },
+      signal: AbortSignal.timeout(1500),
+    });
+    if (response.status !== 200) return false;
+    const expected = createHmac('sha256', identity.secret).update(`response:${nonce}`).digest();
+    const actual = await response.text();
+    return /^[a-f0-9]{64}$/.test(actual) && timingSafeEqual(Buffer.from(actual, 'hex'), expected);
+  } catch { return false; }
+}
+
+export interface HookExposureState { path: typeof PUBLIC_HOOK_PATH; decisionId: string; openedAt: string }
+export interface HookExposureDeps {
+  stateDir?: string;
+  decision?: (id: string) => DecisionEntry;
+  execute?: (binary: string, args: readonly string[]) => void;
+  now?: () => Date;
+  ingressPort?: number;
+  /** Local port the 8443 Funnel currently proxies to, or null (none / unreadable). Default reads `tailscale funnel status --json`. */
+  funnelTarget?: () => number | null;
+}
+
+/** The loopback port a 8443 Funnel handler proxies to — the only evidence that an unrecorded Funnel is ours. */
+export function parseFunnelTarget(statusJson: string): number | null {
+  let status: unknown;
+  try { status = JSON.parse(statusJson); } catch { return null; }
+  const web = (status as { Web?: Record<string, { Handlers?: Record<string, { Proxy?: unknown }> }> } | null)?.Web;
+  if (!web || typeof web !== 'object') return null;
+  for (const [host, entry] of Object.entries(web)) {
+    if (!host.endsWith(`:${HTTPS_PORT}`)) continue;
+    for (const handler of Object.values(entry?.Handlers ?? {})) {
+      const match = typeof handler?.Proxy === 'string' ? /^http:\/\/(?:127\.0\.0\.1|localhost):(\d+)\/?$/.exec(handler.Proxy) : null;
+      if (match) return Number(match[1]);
+    }
+  }
+  return null;
+}
+
+function readFunnelTarget(): number | null {
+  const result = spawnSync('tailscale', ['funnel', 'status', '--json'], { encoding: 'utf8' });
+  if (result.error || result.status !== 0) return null;
+  return parseFunnelTarget(result.stdout);
+}
+
+function run(binary: string, args: readonly string[]): void {
+  const result = spawnSync(binary, [...args], { encoding: 'utf8' });
+  if (result.error || result.status !== 0) throw new Error(`tailscale command failed${result.error ? `: ${result.error.message}` : ''}`);
+}
+
+/** Funnel targets a dedicated loopback listener, never the multi-route hooks receiver or NEXUS. */
+export function hookExposurePlan(): { path: string; local: string; decisionRef: string; on: string; off: string } {
+  const plan = { path: PUBLIC_HOOK_PATH, local: `http://127.0.0.1:${PUBLIC_HOOK_PORT}`,
+    decisionRef: HOOK_EXPOSURE_REF, on: `tailscale ${ON_ARGS.join(' ')}`, off: `tailscale ${OFF_ARGS.join(' ')}` };
+  debug.log('hooks.expose', 'plan', { path: plan.path, port: PUBLIC_HOOK_PORT });
+  return plan;
+}
+
+function stateFile(deps: HookExposureDeps): string { return join(deps.stateDir ?? elanousStateRoot(), 'hooks', 'exposure.json'); }
+
+/** Portable cross-process lock (macOS has no `flock` binary): an atomic `mkdir` lock directory holding the owner pid.
+ *  A lock whose owner pid is gone is stale and taken over; otherwise wait up to 30s. */
+async function withExposureLock<T>(deps: HookExposureDeps, action: () => Promise<T> | T): Promise<T> {
+  const dir = join(deps.stateDir ?? elanousStateRoot(), 'hooks');
+  mkdirSync(dir, { recursive: true });
+  const lock = join(dir, 'exposure.lock.d');
+  const owner = join(lock, 'owner');
+  const deadline = Date.now() + 30_000;
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      writeFileSync(owner, String(process.pid));
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      let holder = Number.NaN;
+      try { holder = Number(readFileSync(owner, 'utf8').trim()); } catch { /* owner not written yet */ }
+      const alive = Number.isInteger(holder) && holder > 0 && (() => { try { process.kill(holder, 0); return true; } catch { return false; } })();
+      if (Number.isInteger(holder) && holder > 0 && !alive) {
+        // Detach atomically, then re-check: only the dead holder's lock is removed — a lock another process just
+        // re-created after its own takeover is put back untouched.
+        const detached = `${lock}.stale.${process.pid}.${randomBytes(4).toString('hex')}`;
+        try { renameSync(lock, detached); } catch { continue; }
+        let detachedHolder = Number.NaN;
+        try { detachedHolder = Number(readFileSync(join(detached, 'owner'), 'utf8').trim()); } catch { /* unreadable */ }
+        if (detachedHolder === holder) rmSync(detached, { recursive: true, force: true });
+        else { try { renameSync(detached, lock); } catch { rmSync(detached, { recursive: true, force: true }); } }
+        continue;
+      }
+      if (Date.now() > deadline) throw new Error('hooks exposure lock unavailable (held for over 30s)');
+      await Bun.sleep(25);
+    }
+  }
+  try { return await action(); }
+  finally { rmSync(lock, { recursive: true, force: true }); }
+}
+
+/** Recorded exposure state; an out-of-band tailscale change is not represented by this file. */
+export function hookExposureStatus(deps: HookExposureDeps = {}): HookExposureState | null {
+  const file = stateFile(deps);
+  if (!existsSync(file)) return null;
+  const raw: unknown = JSON.parse(readFileSync(file, 'utf8'));
+  if (raw === null) return null;
+  if (typeof raw !== 'object' || (raw as HookExposureState).path !== PUBLIC_HOOK_PATH ||
+      !/^D-\d{8}-\d+$/.test((raw as HookExposureState).decisionId) ||
+      !Number.isFinite(Date.parse((raw as HookExposureState).openedAt))) throw new Error('invalid hooks exposure state');
+  return raw as HookExposureState;
+}
+
+function save(deps: HookExposureDeps, state: HookExposureState | null): void {
+  const file = stateFile(deps);
+  mkdirSync(join(file, '..'), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(state) + '\n', { mode: 0o600 });
+  renameSync(temp, file);
+}
+
+export async function turnHookExposureOn(decisionId: string | undefined, deps: HookExposureDeps = {}): Promise<HookExposureState> {
+  const refuse = (reason: string): never => {
+    debug.log('hooks.expose', 'refused', { reason });
+    throw new Error(`hooks expose on refused: ${reason}`);
+  };
+  if (!decisionId || !/^D-\d{8}-\d+$/.test(decisionId)) return refuse('valid --decision <D-id> required');
+  return withExposureLock(deps, async () => {
+    if (hookExposureStatus(deps)) return refuse('already on; turn off first');
+    let entry: DecisionEntry;
+    try { entry = (deps.decision ?? (id => new DecisionLedger({ stateDir: deps.stateDir }).show(id)))(decisionId); }
+    catch { return refuse('decision not found or unreadable'); }
+    if (entry.id !== decisionId || entry.status !== 'decided') return refuse('decision is not decided');
+    if (entry.category !== 'security' || !entry.refs?.includes(HOOK_EXPOSURE_REF)) return refuse('decision is not for hooks exposure');
+    if (entry.decidedBy?.kind !== 'human') return refuse('owner decision required');
+    if (!entry.choice || entry.options.find(option => option.key === entry.choice)?.label !== '켬') return refuse('selected option is not 켬');
+    if (!await verifyIngress(deps.stateDir, deps.ingressPort)) return refuse('dedicated hooks ingress not running or identity mismatch');
+    const state: HookExposureState = { path: PUBLIC_HOOK_PATH, decisionId, openedAt: (deps.now ?? (() => new Date()))().toISOString() };
+    const execute = deps.execute ?? run;
+    execute('tailscale', ON_ARGS);
+    try { save(deps, state); }
+    catch (saveError) {
+      try { execute('tailscale', OFF_ARGS); }
+      catch (rollbackError) {
+        debug.log('hooks.expose', 'refused', { reason: 'state save and rollback failed', path: state.path, decisionId, openedAt: state.openedAt });
+        throw new AggregateError([saveError, rollbackError],
+          `hooks exposure state save and rollback failed; public exposure may still be open (decision ${decisionId}, path ${state.path}, opened ${state.openedAt}); run hooks expose off (or hooks expose off --force)`);
+      }
+      debug.log('hooks.expose', 'refused', { reason: 'state save failed; exposure rolled back', path: state.path, decisionId });
+      throw saveError;
+    }
+    debug.log('hooks.expose', 'on', { path: state.path, decisionId, openedAt: state.openedAt });
+    return state;
+  });
+}
+
+export interface HookExposureOffResult { changed: boolean; reason: 'recorded' | 'funnel-targets-hook-ingress' | 'forced' | 'not-ours' }
+
+/** Turn off only a Funnel this tool owns: a recorded exposure, or a 8443 Funnel proxying to the dedicated hook ingress
+ *  (recovery after a failed state save). Anything else is left alone unless `force` — an unrelated Funnel is not ours. */
+export async function turnHookExposureOff(deps: HookExposureDeps = {}, opts: { force?: boolean } = {}): Promise<HookExposureOffResult> {
+  return withExposureLock(deps, () => offLocked(deps, opts));
+}
+
+function offLocked(deps: HookExposureDeps, opts: { force?: boolean }): HookExposureOffResult {
+  const recorded = hookExposureStatus(deps);
+  const reason: HookExposureOffResult['reason'] = recorded ? 'recorded'
+    : (deps.funnelTarget ?? readFunnelTarget)() === PUBLIC_HOOK_PORT ? 'funnel-targets-hook-ingress'
+      : opts.force ? 'forced' : 'not-ours';
+  if (reason === 'not-ours') {
+    debug.log('hooks.expose', 'off-skipped', { path: PUBLIC_HOOK_PATH, reason });
+    return { changed: false, reason };
+  }
+  (deps.execute ?? run)('tailscale', OFF_ARGS);
+  save(deps, null);
+  debug.log('hooks.expose', 'off', { path: PUBLIC_HOOK_PATH, reason });
+  return { changed: true, reason };
+}
+
+/** `hooks serve` shutdown: under the same lock as `on`, close a recorded exposure first, then the ingress — so a Funnel
+ *  never outlives the listener it was verified against (another process could bind the port next). */
+export async function closeIngressAndExposure(ingress: { stop: () => void } | undefined, deps: HookExposureDeps = {}): Promise<void> {
+  await withExposureLock(deps, () => {
+    try {
+      if (hookExposureStatus(deps)) offLocked(deps, {});
+    } catch (error) {
+      debug.log('hooks.expose', 'shutdown-off-failed', { path: PUBLIC_HOOK_PATH, error: String(error).slice(0, 200) });
+      console.error(`hooks: public exposure may still be open — run \`elanous hooks expose off\` (${error instanceof Error ? error.message : String(error)})`);
+    } finally {
+      ingress?.stop();
+    }
+  });
+}
+
+/** Only the two exact public hook paths are forwarded; the receiver verifies signatures and queues. */
+export function startPublicHookIngress(receiverUrl: string, port = PUBLIC_HOOK_PORT, stateDir?: string): { url: string; stop: () => void } {
+  const receiver = new URL(receiverUrl);
+  if (receiver.protocol !== 'http:' || (receiver.hostname !== '127.0.0.1' && receiver.hostname !== 'localhost' && receiver.hostname !== '[::1]'))
+    throw new Error('public ingress requires loopback receiver');
+  const secret = randomBytes(32).toString('hex');
+  const server = Bun.serve({ hostname: '127.0.0.1', port, async fetch(request) {
+    const path = new URL(request.url).pathname;
+    if (path === PROBE_PATH && request.method === 'GET') {
+      const nonce = request.headers.get('x-hooks-ingress-challenge');
+      const proof = request.headers.get('x-hooks-ingress-proof');
+      if (!nonce || !/^[a-f0-9]{64}$/.test(nonce) || !proof || !/^[a-f0-9]{64}$/.test(proof))
+        return new Response('Not Found', { status: 404 });
+      const expected = createHmac('sha256', secret).update(`request:${nonce}`).digest();
+      if (!timingSafeEqual(Buffer.from(proof, 'hex'), expected)) return new Response('Not Found', { status: 404 });
+      return new Response(createHmac('sha256', secret).update(`response:${nonce}`).digest('hex'));
+    }
+    if (path !== PUBLIC_HOOK_PATH && path !== PUBLIC_GITHUB_HOOK_PATH) return new Response('Not Found', { status: 404 });
+    if (request.method !== 'POST') return new Response('Method Not Allowed', { status: 405 });
+    return fetch(new URL(path, receiver), { method: 'POST', headers: request.headers, body: request.body });
+  } });
+  const file = identityFile(stateDir);
+  try {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, JSON.stringify({ port: server.port, secret }), { mode: 0o600 });
+  } catch (error) { server.stop(); throw error; }
+  return { url: server.url.toString(), stop: () => {
+    server.stop();
+    try { if (readIngressIdentity(stateDir).secret === secret) unlinkSync(file); } catch { /* identity already removed */ }
+  } };
+}

package/src/hooks/github-shadow.ts

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { openMsgStore } from '../msg/msg-store.js';
+import { CardStore, redactSecrets } from '../task-cards/card-store.js';
+import { isGithubSpamText, PUBLIC_GITHUB_REPO } from './providers.js';
+import type { QueuedHook } from './queue.js';
+
+export type ShadowVerdict = 'accepted' | 'rejected' | 'human-check';
+export interface ShadowJudgment { verdict: ShadowVerdict; reason: string }
+
+const riskyPath = /(^|\/)(?:package\.json$|\.github\/(?:workflows\/|actions\/|CODEOWNERS$)|\.env(?:\.|$)|secrets?(?:\/|\.)|auth(?:\/|\.)|release(?:\/|\.)|scripts\/release-|src\/harness\/|src\/self-implement\/|src\/hooks\/)/i;
+
+/** Webhook text is untrusted; a missing PR file list cannot be called safe. */
+export function judgeGithubShadow(title: string, type: 'pull_request' | 'issue', files?: string[], spamSignal = false): ShadowJudgment {
+  if (spamSignal || isGithubSpamText(title)) return { verdict: 'rejected', reason: 'spam signal in title or body' };
+  if (type === 'pull_request' && (!files || !files.length || files.some(path => !path || riskyPath.test(path))))
+    return { verdict: 'human-check', reason: !files?.length ? 'PR file list unavailable' : 'sensitive or invalid file path' };
+  return { verdict: 'accepted', reason: 'public contribution candidate (shadow only)' };
+}
+
+/** Compare the current base tree against GitHub's PR test-merge tree, not the head tree.
+ * The test merge includes only changes contributed by this PR onto the current base. Read tree metadata only (no patches). */
+export async function publicPrFileNames(number: number, fetchFn: typeof fetch = fetch): Promise<string[] | undefined> {
+  if (!Number.isSafeInteger(number) || number < 1) return undefined;
+  const read = async (path: string): Promise<Record<string, unknown> | undefined> => {
+    try {
+      const response = await fetchFn(`https://api.github.com/repos/${PUBLIC_GITHUB_REPO}${path}`, { method: 'GET',
+        headers: { accept: 'application/vnd.github+json' }, signal: AbortSignal.timeout(5000) });
+      if (!response.ok) return undefined;
+      return object(await response.json());
+    } catch { return undefined; }
+  };
+  const pull = await read(`/pulls/${number}`);
+  const base = object(pull?.base);
+  const head = object(pull?.head);
+  const baseSha = base?.sha;
+  const headSha = head?.sha;
+  const mergeSha = pull?.merge_commit_sha;
+  if (pull?.number !== number || object(base?.repo)?.full_name !== PUBLIC_GITHUB_REPO ||
+      !gitSha(baseSha) || !gitSha(headSha) || !gitSha(mergeSha)) return undefined;
+  const baseCommit = await read(`/git/commits/${baseSha}`);
+  const mergeCommit = await read(`/git/commits/${mergeSha}`);
+  const parents = mergeCommit?.parents;
+  if (mergeCommit?.sha !== mergeSha || !Array.isArray(parents) || parents.length !== 2 ||
+      object(parents[0])?.sha !== baseSha || object(parents[1])?.sha !== headSha) return undefined;
+  const baseTreeSha = object(baseCommit?.tree)?.sha;
+  const mergeTreeSha = object(mergeCommit?.tree)?.sha;
+  if (!gitSha(baseTreeSha) || !gitSha(mergeTreeSha)) return undefined;
+  const baseTree = await read(`/git/trees/${baseTreeSha}?recursive=1`);
+  const mergeTree = await read(`/git/trees/${mergeTreeSha}?recursive=1`);
+  const entries = (tree: Record<string, unknown> | undefined): Map<string, string> | undefined => {
+    if (!tree || tree.truncated !== false || !Array.isArray(tree.tree) || tree.tree.length > 100_000) return undefined;
+    const files = new Map<string, string>();
+    for (const row of tree.tree) {
+      const entry = object(row);
+      if (!entry || typeof entry.path !== 'string' || !gitSha(entry.sha) ||
+          !['blob', 'commit', 'tree'].includes(String(entry.type)) ||
+          typeof entry.mode !== 'string' || !/^[0-7]{6}$/.test(entry.mode)) return undefined;
+      if (entry.type === 'blob' || entry.type === 'commit')
+        files.set(entry.path, `${entry.type}:${entry.mode}:${entry.sha}`);
+    }
+    return files;
+  };
+  const before = entries(baseTree);
+  const after = entries(mergeTree);
+  if (!before || !after || baseTree?.sha !== baseTreeSha || mergeTree?.sha !== mergeTreeSha) return undefined;
+  return [...new Set([...before.keys(), ...after.keys()])].filter(path => before.get(path) !== after.get(path));
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function gitSha(value: unknown): value is string { return typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value); }
+
+/** Separate shadow ledger/card path: never enter dispatchHook's seat wake or steward launch/report stages. */
+export async function recordGithubShadow(event: QueuedHook, root: string, fetchFn: typeof fetch = fetch): Promise<void> {
+  const github = event.task.github;
+  if (event.provider !== 'github' || !github || github.repository !== PUBLIC_GITHUB_REPO ||
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(event.eventId) ||
+      !Number.isSafeInteger(github.number) || github.number < 1 || !['pull_request', 'issue'].includes(github.type))
+    throw new Error('invalid GitHub shadow event');
+  const files = github.type === 'pull_request' && !github.spamSignal && !isGithubSpamText(event.task.title)
+    ? await publicPrFileNames(github.number, fetchFn) : undefined;
+  const judgment = judgeGithubShadow(event.task.title, github.type, files, github.spamSignal);
+  const key = `github:${event.eventId}`;
+  const store = openMsgStore(join(root, 'msg', 'messages.db'));
+  try {
+    store.db.exec(`CREATE TABLE IF NOT EXISTS github_shadow_judgments (
+      event_key TEXT PRIMARY KEY, repository TEXT NOT NULL, item_type TEXT NOT NULL, item_number INTEGER NOT NULL,
+      verdict TEXT NOT NULL, reason TEXT NOT NULL, url TEXT NOT NULL
+    )`);
+    store.db.query(`INSERT OR IGNORE INTO github_shadow_judgments
+      (event_key, repository, item_type, item_number, verdict, reason, url) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+      .run(key, github.repository, github.type, github.number, judgment.verdict, judgment.reason, event.task.external.url ?? '');
+    const recorded = store.db.query('SELECT verdict, reason FROM github_shadow_judgments WHERE event_key = ?')
+      .get(key) as ShadowJudgment;
+    const cards = new CardStore(root);
+    try {
+      const goalId = `github:${github.repository}:${github.type}:${github.number}`;
+      const card = cards.createCard({ goalId, title: redactSecrets(event.task.title).slice(0, 240) });
+      const content = JSON.stringify({ event: key, source: goalId, url: event.task.external.url, verdict: recorded.verdict,
+        reason: recorded.reason, candidate: recorded.verdict === 'rejected' ? 'intake-only' : 'decision-card' });
+      const sectionKey = `intake:${createHash('sha256').update(key).digest('hex')}`;
+      if (!card.sections.some(section => section.key === sectionKey))
+        cards.appendSection(card.id, { key: sectionKey, owner: 'steward', content: redactSecrets(content) });
+    } finally { cards.close(); }
+  } finally { store.close(); }
+}

package/src/hooks/providers.ts

@@ -1,11 +1,20 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 
-export type HookProvider = 'linear' | 'asana';
+export type HookProvider = 'linear' | 'asana' | 'github';
+export const PUBLIC_GITHUB_REPO = 'ElanvitalAI/elanous';
+/** Links to documentation and reproductions are not spam signals. */
+export function isGithubSpamText(value: string): boolean {
+  return /\b(?:casino|crypto giveaway|free money|seo backlinks|airdrop)\b/i.test(value);
+}
 export interface ExternalTask {
   eventId: string;
   title: string;
   description?: string;
   external: { provider: HookProvider; ref: string; url?: string };
+  /** Linear issue assignee ID, resolved by the configured seat mapping; events.routes takes precedence. */
+  assigneeId?: string;
+  /** L14: an opened PR/issue on the public repository — shadow intake only, never dispatched to seats. */
+  github?: { repository: string; number: number; type: 'pull_request' | 'issue'; spamSignal?: boolean };
 }
 export type Verification = { ok: true; body: unknown; eventIds: string[]; ignored?: string } | { ok: false; reason: 'bad-signature' | 'stale' | 'invalid-body' };
 
@@ -29,7 +38,9 @@ export function asanaEventId(event: unknown): string | 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')))
+  const signature = headers.get(provider === 'linear' ? 'linear-signature' : provider === 'github' ? 'x-hub-signature-256' : 'x-hook-signature');
+  const digest = provider === 'github' ? (signature?.startsWith('sha256=') ? signature.slice(7) : null) : signature;
+  if (!equalSignature(raw, secret, digest))
     return { ok: false, reason: 'bad-signature' };
   let parsed: unknown;
   try { parsed = JSON.parse(raw.toString('utf8')); } catch { return { ok: false, reason: 'invalid-body' }; }
@@ -39,15 +50,45 @@ export function verifyWebhook(provider: HookProvider, raw: Buffer, headers: Head
     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')
+    // Acknowledge signed, out-of-scope events so Linear does not disable the webhook.
+    const previous = object(body.updatedFrom);
+    const relevantUpdate = body.action === 'update' && previous &&
+      ('assigneeId' in previous || 'stateId' in previous);
+    if (body.type !== 'Issue' || (body.action !== 'create' && !relevantUpdate))
       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 (provider === 'github' && object(body.repository)?.full_name === PUBLIC_GITHUB_REPO) {
+    // L14: the public repository's newly opened PRs/issues go to the shadow intake (no seat dispatch, no outside writes).
+    const kind = headers.get('x-github-event');
+    if (!['pull_request', 'issues'].includes(kind ?? '') || body.action !== 'opened')
+      return { ok: true, body, eventIds: [], ignored: `${kind ?? 'unknown'}:${String(body.action)}` };
+    const item = object(body[kind === 'pull_request' ? 'pull_request' : 'issue']);
+    const delivery = headers.get('x-github-delivery');
+    if (!delivery || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(delivery) || !Number.isSafeInteger(body.number) ||
+        (body.number as number) < 1 || !item || item.number !== body.number || !text(item.title) ||
+        !text(item.html_url) || !text(object(item.user)?.login) ||
+        item.html_url !== `https://github.com/${PUBLIC_GITHUB_REPO}/${kind === 'pull_request' ? 'pull' : 'issues'}/${body.number}`)
+      return { ok: false, reason: 'invalid-body' };
+    return { ok: true, body: { ...body, githubEvent: kind, publicIntake: true }, eventIds: [delivery] };
+  }
+  if (provider === 'github') {
+    const event = headers.get('x-github-event');
+    const action = text(body.action);
+    if (!((event === 'pull_request' && action === 'review_requested') ||
+      (event === 'check_run' && action === 'completed' && object(body.check_run)?.conclusion === 'failure') ||
+      (event === 'check_suite' && action === 'completed' && object(body.check_suite)?.conclusion === 'failure')))
+      return { ok: true, body, eventIds: [], ignored: `${String(event)}:${String(action)}` };
+    const delivery = text(headers.get('x-github-delivery'));
+    const resource = object(event === 'pull_request' ? body.pull_request : event === 'check_run' ? body.check_run : body.check_suite);
+    if (!delivery || !resource || typeof resource.id !== 'number' ||
+      !(text(resource.html_url) ?? text(resource.details_url) ?? text(object(body.repository)?.html_url)))
+      return { ok: false, reason: 'invalid-body' };
+    return { ok: true, body: { ...body, githubEvent: event }, eventIds: [delivery] };
+  }
   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' };
@@ -63,9 +104,34 @@ export function toExternalTask(provider: HookProvider, body: unknown): ExternalT
     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');
+    const assigneeId = text(issue?.assigneeId) ?? text(object(issue?.assignee)?.id);
     return { eventId, title, ...(text(issue?.description) ? { description: text(issue?.description) } : {}),
+      ...(assigneeId ? { assigneeId } : {}),
       external: { provider, ref, ...(text(issue?.url) ? { url: text(issue?.url) } : {}) } };
   }
+  if (provider === 'github' && row.publicIntake === true) {
+    const type = row.githubEvent === 'pull_request' ? 'pull_request' : 'issue';
+    const item = object(type === 'pull_request' ? row.pull_request : row.issue);
+    const number = row.number;
+    const eventId = text(row.eventId);
+    if (!Number.isSafeInteger(number) || !item || !eventId || !text(item.title) || !text(item.html_url))
+      throw new Error('invalid github event');
+    return { eventId, title: item.title as string,
+      external: { provider, ref: `${PUBLIC_GITHUB_REPO}#${number}`, url: item.html_url as string },
+      github: { repository: PUBLIC_GITHUB_REPO, number: number as number, type,
+        spamSignal: typeof item.body === 'string' && isGithubSpamText(item.body) } };
+  }
+  if (provider === 'github') {
+    const event = text(row.githubEvent);
+    const resource = object(event === 'pull_request' ? row.pull_request : event === 'check_run' ? row.check_run : row.check_suite);
+    const ref = resource?.id;
+    const eventId = text(row.eventId);
+    const url = text(resource?.html_url) ?? text(resource?.details_url) ?? text(object(row.repository)?.html_url);
+    if (typeof ref !== 'number' || !eventId || !url) throw new Error('invalid github event');
+    const title = event === 'pull_request' ? `PR review requested: ${text(resource?.title) ?? url}`
+      : `Check failed: ${text(resource?.name) ?? text(resource?.head_branch) ?? url}`;
+    return { eventId, title, external: { provider, ref: String(ref), url } };
+  }
   const event = object(row.event);
   const task = object(row.task);
   const ref = text(object(event?.resource)?.gid);

package/src/hooks/queue.ts

@@ -4,7 +4,7 @@ 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 interface QueuedHook { provider: ExternalTask['external']['provider']; eventId: string; kind?: string; task: ExternalTask }
 
 export class HookQueue {
   readonly directory: string;