elanous 0.2.10 → 0.2.11

package/src/harness/launch-registry.ts

@@ -0,0 +1,91 @@
+/** Host-wide run → process binding for `harness stop`, independent of the launching worktree and its universe.
+ *  A run launched from another worktree writes `pid.json` and its ledger under that tree's state dir, so a stop from
+ *  any other tree found «no pid.json · goal path 0» while the launcher was alive (10-03 · 09-29). The binding below lives
+ *  in a per-user directory under the OS temp dir — it only has to outlive the process it names, not a reboot. */
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { debug } from '../debug/log.js';
+
+export interface LaunchBinding {
+  readonly pid: number;
+  /** Same approximation as `pid.json` (`Date.now() − uptime`) — compared with `ps` start time before any signal. */
+  readonly startedAt: number;
+  readonly argv0?: string;
+  /** The launching process's working directory (absolute). */
+  readonly cwd: string;
+  /** Absolute goal document path when the launcher was given one (`--goal-file`/`--ask`/`--goal`). */
+  readonly goalPath?: string;
+  /** The `self-dev-runs` directory that holds this run's `pid.json` — tells a stop which universe launched it. */
+  readonly runsDir?: string;
+}
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** One directory per OS user: `$TMPDIR` is per-user on macOS, `/tmp` is shared on Linux. */
+export function launchRegistryDir(): string {
+  let uid: string;
+  try { uid = String(userInfo().uid); } catch { uid = 'unknown'; }
+  return join(tmpdir(), `elanous-harness-launches-${uid}`);
+}
+
+/** The goal document named in an argv, resolved against `cwd` — the same option set `harness stop` already matches. */
+export function goalPathFromArgv(argv: readonly string[], cwd: string): string | undefined {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    let value: string | undefined;
+    for (const flag of ['--goal-file', '--ask', '--goal']) {
+      if (arg === flag) value = argv[i + 1];
+      else if (arg.startsWith(`${flag}=`)) value = arg.slice(flag.length + 1);
+    }
+    if (value?.trim()) return isAbsolute(value) ? resolve(value) : resolve(cwd, value);
+  }
+  return undefined;
+}
+
+export function writeLaunchBinding(runId: string, binding: LaunchBinding, dir = launchRegistryDir()): string | null {
+  if (!RUN_ID.test(runId)) return null;
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `${runId}.json`);
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const fd = openSync(temporary, 'wx', 0o600);
+    try { writeFileSync(fd, JSON.stringify(binding)); } finally { closeSync(fd); }
+    renameSync(temporary, path);
+    debug.log('harness.launch-registry', 'bound', { runId, pid: binding.pid, goalPath: binding.goalPath ?? null });
+    return path;
+  } catch (error) {
+    debug.log('harness.launch-registry', 'bind-failed', { runId, error: String(error) }, { level: 'warn' });
+    return null;
+  }
+}
+
+export function readLaunchBinding(runId: string, dir = launchRegistryDir()): LaunchBinding | null {
+  if (!RUN_ID.test(runId)) return null;
+  try {
+    const value = JSON.parse(readFileSync(join(dir, `${runId}.json`), 'utf8')) as Partial<LaunchBinding>;
+    if (!Number.isSafeInteger(value.pid) || (value.pid as number) <= 0 || !Number.isFinite(value.startedAt)) return null;
+    if (typeof value.cwd !== 'string' || !isAbsolute(value.cwd)) return null;
+    return {
+      pid: value.pid as number, startedAt: value.startedAt as number, cwd: value.cwd,
+      ...(typeof value.argv0 === 'string' ? { argv0: value.argv0 } : {}),
+      ...(typeof value.goalPath === 'string' && isAbsolute(value.goalPath) ? { goalPath: value.goalPath } : {}),
+      ...(typeof value.runsDir === 'string' && isAbsolute(value.runsDir) ? { runsDir: value.runsDir } : {}),
+    };
+  } catch { return null; }
+}
+
+export function removeLaunchBinding(runId: string, dir = launchRegistryDir()): void {
+  if (!RUN_ID.test(runId)) return;
+  try { unlinkSync(join(dir, `${runId}.json`)); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') debug.log('harness.launch-registry', 'unbind-failed', { runId, error: String(error) }, { level: 'warn' });
+  }
+}
+
+/** Run IDs with a live-looking binding — used for stop's prefix resolution next to ledgers and `pid.json` names. */
+export function launchBindingRunIds(dir = launchRegistryDir()): string[] {
+  try { return readdirSync(dir).filter((name) => name.endsWith('.json')).map((name) => name.slice(0, -5)).filter((id) => RUN_ID.test(id)); }
+  catch { return []; }
+}

package/src/harness/process-garbage.ts

@@ -12,7 +12,9 @@ export interface GarbageProcess extends Pick<GarbageProcessRow, 'pid' | 'ppid' |
 
 const TEST_PATH = /elanous|repo\.worktrees|self-impl|\.elanous-test|gate-baseline/i;
 const TEST_DAEMON = /(?:^|[\s/])daemon\.ts(?:\s|$)/;
-const TEST_RUNNER = /\bbun\s+test\b|\bgate(?:[-\s]baseline|\b)/i;
+const TEST_RUNNER = /^(?:\S*\/)?bun\s+test(?:\s|$)/i;
+// Only the command itself counts — `bun [run|x] <…gate…>`; goal text later in argv must not (PROC1).
+const GATE_RUNNER = /^(?:\S*\/)?bun\s+(?:(?:run|x)\s+)?\S*gate(?:[-\s]baseline|\b)/i;
 const NEXUS_RUN = /\bnexus\s+run\b/;
 const TEST_MARKER = /\.elanous-test|(?:^|\s)--test(?:\s|$)/;
 
@@ -20,7 +22,7 @@ const TEST_MARKER = /\.elanous-test|(?:^|\s)--test(?:\s|$)/;
 export function isGarbageProcessTarget(command: string): boolean {
   return command.includes('elanous.mjs')
     || (TEST_DAEMON.test(command) && /elanous-nexus-|\.elanous-test/.test(command))
-    || (TEST_RUNNER.test(command) && TEST_PATH.test(command));
+    || ((TEST_RUNNER.test(command) || GATE_RUNNER.test(command)) && TEST_PATH.test(command));
 }
 
 export function classifyGarbage(
@@ -36,7 +38,7 @@ export function classifyGarbage(
     const reason: GarbageProcess['reason'] = TEST_DAEMON.test(row.command)
       && /elanous-nexus-|\.elanous-test/.test(row.command)
       ? 'orphan-test-daemon'
-      : TEST_RUNNER.test(row.command) && TEST_PATH.test(row.command)
+      : (TEST_RUNNER.test(row.command) || GATE_RUNNER.test(row.command)) && TEST_PATH.test(row.command)
         ? 'orphan-test-runner'
         : 'orphan-elanous';
     garbage.push({ pid: row.pid, ppid: row.ppid, elapsedSeconds: row.elapsedSeconds, command: row.command, reason });

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(); }
+}