elanous 0.2.23 → 0.2.25

package/src/fleet/host-doctor.ts

@@ -0,0 +1,375 @@
+import { spawnSync } from 'node:child_process';
+import { debug } from '../debug/log.js';
+
+/**
+ * 호스트 닥터 — 첫 조각(FLEET-DOCTOR-1 · 읽기 전용).
+ * 설계 정본 = 내부 문서 `RFC-fleet-host-doctor-2026-10-11` §A1·A2·A4·A5.
+ * 점검은 코드 분기가 아니라 선언 표(HOST_DOCTOR_CHECKS)다.
+ */
+
+export type HostDoctorPlatform = 'darwin' | 'linux' | 'wsl';
+export type HostDoctorRole = 'worker' | 'hq';
+export type HostDoctorFixKind = 'auto' | 'sudo' | 'approval' | 'human';
+export type HostDoctorCheckStatus = 'pass' | 'fail' | 'unmeasured';
+export type HostDoctorBundle = 'access' | 'engine' | 'platform';
+
+/** 원격 한 발의 결과. `null` = 그 발을 아예 못 쐈다(→ unmeasured). */
+export interface HostDoctorRun {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** 주입 가능한 원격 실행 — 기본 = ssh BatchMode · `<host>=local` 이면 이 기계(bash -c). */
+export type HostDoctorRemote = (host: string, probe: string) => HostDoctorRun | null;
+
+/** HQ 실측값(본부의 설치 판 · 이미지 핀) — 없으면 그 점검은 unmeasured 다. */
+export interface HostDoctorExpected {
+  installVersion?: string;
+  imagePin?: string;
+}
+
+export interface HostDoctorExpectContext {
+  platform: HostDoctorPlatform | null;
+  arch: string | null;
+  expected: HostDoctorExpected;
+}
+
+export type HostDoctorExpectResult =
+  | { status: 'pass' | 'fail'; observed: string; expected: string }
+  | { status: 'unmeasured'; observed: string; expected: string };
+
+export interface HostDoctorCheckSpec {
+  id: string;
+  bundle: HostDoctorBundle;
+  platforms: readonly HostDoctorPlatform[];
+  roles: readonly HostDoctorRole[];
+  /** 원격 셸 한 줄. */
+  probe: string;
+  expect: (run: HostDoctorRun, ctx: HostDoctorExpectContext) => HostDoctorExpectResult;
+  fixKind: HostDoctorFixKind;
+  fix?: string;
+}
+
+export interface HostDoctorCheckResult {
+  id: string;
+  status: HostDoctorCheckStatus;
+  observed: string;
+  expected: string;
+  fixKind: HostDoctorFixKind;
+  fix?: string;
+}
+
+/** 대장 레코드 종류 `setup-status {id, ok, missing[], fixHref}` 의 몸 ⊕ 확장 칸(RFC-fleet-host-doctor §A0 · 독자 이름 fleet.host.v1 은 쓰지 않는다). */
+export interface HostDoctorReport {
+  /** setup-status.id — 호스트 이름. */
+  id: string;
+  /** setup-status.ok — fail 0 ⊕ unmeasured 0 일 때만. */
+  ok: boolean;
+  /** setup-status.missing — fail ⊕ unmeasured 점검 id. */
+  missing: string[];
+  /** setup-status.fixHref — 고치는 길(빠진 것이 없으면 null). */
+  fixHref: string | null;
+  // ── 확장 칸 ──
+  platform: HostDoctorPlatform | null;
+  arch: string | null;
+  role: HostDoctorRole;
+  measuredAt: string;
+  checks: HostDoctorCheckResult[];
+}
+
+/** 빠진 점검이 있을 때의 고치는 길 — 사람 손 처방은 RFC 표, 자동 처방은 node-setup(다음 조각 FLEET-DOCTOR-FIX 가 --fix 로 잇는다). */
+export const HOST_DOCTOR_FIX_HREF = 'docs/RFC-fleet-host-doctor-2026-10-11.md';
+
+const ALL_PLATFORMS: readonly HostDoctorPlatform[] = ['darwin', 'linux', 'wsl'];
+const ALL_ROLES: readonly HostDoctorRole[] = ['worker', 'hq'];
+
+function line(value: string): string {
+  return value.trim().split('\n')[0] ?? '';
+}
+
+function nonEmpty(value: string | null | undefined): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** uname -m 과 docker 의 아키텍처 이름을 한 이름으로 — x86_64≡amd64 · aarch64≡arm64(10-11 WSL 실물: «x86_64 vs docker amd64» 오판). */
+export function normalizeArch(arch: string): string {
+  const lower = arch.trim().toLowerCase();
+  if (lower === 'x86_64' || lower === 'x64') return 'amd64';
+  if (lower === 'aarch64' || lower === 'arm64v8') return 'arm64';
+  return lower;
+}
+
+/** 묶음 셋(접근 · 엔진 · 판)의 선언 표 — 첫 조각. */
+export const HOST_DOCTOR_CHECKS: readonly HostDoctorCheckSpec[] = [
+  // ── 접근 ──
+  {
+    id: 'ssh.batch',
+    bundle: 'access',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    // 원격 한 발 자체가 `ssh -o BatchMode=yes <host>` 로 간다 — 그 발이 «ok» 를 돌려주면 그게 증거다.
+    //   (원격 안에서 다시 `ssh localhost` 를 치면 «그 호스트가 자기 자신에게» 붙는지를 재게 된다 · 10-11 실물 오판)
+    probe: 'echo ok',
+    expect: (run) => ({
+      status: run.status === 0 && line(run.stdout) === 'ok' ? 'pass' : 'fail',
+      observed: run.status === 0 ? line(run.stdout) || '(empty)' : `exit ${run.status ?? 'none'}`,
+      expected: 'ssh -o BatchMode=yes works without a password prompt',
+    }),
+    fixKind: 'human',
+    fix: 'put this host key in ~/.ssh/authorized_keys of the host user',
+  },
+  {
+    id: 'tailnet.online',
+    bundle: 'access',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: 'command -v tailscale >/dev/null 2>&1 || { echo no-cli; exit 0; }; tailscale status >/dev/null 2>&1 && echo online || echo offline',
+    expect: (run) => {
+      const out = line(run.stdout);
+      if (out === 'no-cli') return { status: 'unmeasured', observed: 'tailscale CLI not on the non-interactive PATH', expected: 'tailscale is up and logged in' };
+      return { status: out === 'online' ? 'pass' : 'fail', observed: out || `exit ${run.status ?? 'none'}`, expected: 'tailscale is up and logged in' };
+    },
+    fixKind: 'human',
+    fix: 'run `tailscale up` on the host',
+  },
+  {
+    id: 'path.noninteractive',
+    bundle: 'access',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: 'command -v bun; command -v codex',
+    expect: (run) => {
+      const found = run.stdout.trim().split('\n').map((entry) => entry.trim()).filter(nonEmpty);
+      return {
+        status: found.length >= 2 ? 'pass' : 'fail',
+        observed: found.length ? found.join(' ') : 'none on PATH',
+        expected: 'bun and codex reachable on the default non-interactive PATH',
+      };
+    },
+    fixKind: 'human',
+    fix: 'install bun/codex into a PATH a non-interactive shell already sees (no ~/.bashrc edits)',
+  },
+  // ── 엔진 ──
+  {
+    id: 'docker.engine',
+    bundle: 'engine',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: "docker info --format '{{.ServerVersion}}' 2>/dev/null",
+    expect: (run) => ({
+      status: run.status === 0 && nonEmpty(line(run.stdout)) ? 'pass' : 'fail',
+      observed: run.status === 0 ? line(run.stdout) || '(empty)' : `docker info exit ${run.status ?? 'none'}`,
+      expected: 'a real docker engine answers (not a desktop shim)',
+    }),
+    fixKind: 'human',
+    fix: 'start the docker engine on the host',
+  },
+  {
+    id: 'k3d.cluster',
+    bundle: 'engine',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    // ⛔ `--no-header` 는 k3d v5 에 없는 플래그다(«unknown flag» → 빈 출력 → «클러스터 없음» 오판 · 10-11 node-c·WSL 실물).
+    probe: 'command -v k3d >/dev/null 2>&1 || { echo no-cli; exit 0; }; out=$(k3d cluster list -o json 2>/dev/null) || { echo error; exit 0; }; printf %s "$out" | grep -q \'"name"\' && echo present || echo none',
+    expect: (run) => {
+      const out = line(run.stdout);
+      if (out === 'no-cli') return { status: 'unmeasured', observed: 'k3d not on the non-interactive PATH', expected: 'at least one k3d cluster exists' };
+      if (out === 'error') return { status: 'unmeasured', observed: 'k3d cluster list failed', expected: 'at least one k3d cluster exists' };
+      return { status: out === 'present' ? 'pass' : 'fail', observed: out === 'present' ? 'present' : 'no k3d cluster', expected: 'at least one k3d cluster exists' };
+    },
+    fixKind: 'human',
+    fix: 'create the k3d cluster (scripts/fleet/node-setup.sh)',
+  },
+  {
+    id: 'registry.local',
+    bundle: 'engine',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    // 풀 레지스트리는 k3d-elanous-registry:5050 이다(호스트 포트 5050) · 5000 은 맨 docker registry 관례라 대체로만 본다.
+    probe: 'for port in 5050 5000; do curl -fsS --max-time 3 "http://localhost:$port/v2/" >/dev/null 2>&1 && { echo "reachable:$port"; exit 0; }; done; echo unreachable',
+    expect: (run) => {
+      const out = line(run.stdout);
+      return {
+        status: out.startsWith('reachable:') ? 'pass' : 'fail',
+        observed: out.startsWith('reachable:') ? `localhost:${out.slice('reachable:'.length)} reachable` : 'localhost:5050/5000 /v2 unreachable',
+        expected: 'local registry answers on localhost:5050 (or 5000)',
+      };
+    },
+    fixKind: 'human',
+    fix: 'start the local registry container',
+  },
+  // ── 판 ──
+  {
+    id: 'install.version',
+    bundle: 'platform',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: 'elanous --version 2>/dev/null || echo none',
+    expect: (run, ctx) => {
+      const observed = line(run.stdout) || 'none';
+      if (!nonEmpty(ctx.expected.installVersion)) {
+        return { status: 'unmeasured', observed, expected: 'HQ install version (not supplied)' };
+      }
+      return { status: observed === ctx.expected.installVersion ? 'pass' : 'fail', observed, expected: ctx.expected.installVersion };
+    },
+    fixKind: 'auto',
+    fix: 'reinstall this host from the HQ install line',
+  },
+  {
+    id: 'image.pin',
+    bundle: 'platform',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: "docker ps --format '{{.Image}}' 2>/dev/null | grep -m1 elanous || true",
+    expect: (run, ctx) => {
+      const observed = line(run.stdout);
+      if (!nonEmpty(ctx.expected.imagePin)) {
+        return { status: 'unmeasured', observed: observed || 'none', expected: 'HQ image pin (not supplied)' };
+      }
+      return { status: nonEmpty(observed) && observed === ctx.expected.imagePin ? 'pass' : 'fail', observed: observed || 'no elanous image running', expected: ctx.expected.imagePin };
+    },
+    fixKind: 'auto',
+    fix: 'restart the pod from the pinned image',
+  },
+  {
+    id: 'image.arch',
+    bundle: 'platform',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: "uname -m; docker version --format '{{.Server.Arch}}' 2>/dev/null",
+    expect: (run) => {
+      const [hostArch, engineArch] = run.stdout.trim().split('\n').map((entry) => entry.trim());
+      // docker 가 답하지 않으면 엔진 쪽을 «못 쟀다» — fail 이 아니라 unmeasured(k3d·tailscale 과 같은 원칙).
+      if (!nonEmpty(engineArch)) {
+        return { status: 'unmeasured', observed: `${hostArch || 'none'} vs docker (no answer)`, expected: 'image architecture matches uname -m' };
+      }
+      return {
+        status: nonEmpty(hostArch) && nonEmpty(engineArch) && normalizeArch(hostArch) === normalizeArch(engineArch) ? 'pass' : 'fail',
+        observed: nonEmpty(hostArch) || nonEmpty(engineArch) ? `${hostArch ?? 'none'} vs docker ${engineArch ?? 'none'}` : 'none',
+        expected: 'image architecture matches uname -m',
+      };
+    },
+    fixKind: 'auto',
+    fix: 'pull the image pinned to this host architecture',
+  },
+  {
+    id: 'node.present',
+    bundle: 'platform',
+    platforms: ALL_PLATFORMS,
+    roles: ALL_ROLES,
+    probe: 'command -v node || echo none',
+    expect: (run) => {
+      const observed = line(run.stdout) || 'none';
+      return { status: observed !== 'none' && nonEmpty(observed) ? 'pass' : 'fail', observed, expected: 'node is on PATH (codex shebang)' };
+    },
+    fixKind: 'auto',
+    fix: 'install node (scripts/fleet/node-setup.sh)',
+  },
+];
+
+/** 기본 원격 실행 — `<host>=local` 이면 이 기계의 비대화형 셸, 아니면 ssh BatchMode. 못 쏘면 null. */
+export function defaultHostDoctorRemote(host: string, probe: string): HostDoctorRun | null {
+  const viaSsh = host !== 'local';
+  const spawned = viaSsh
+    // `--` 로 host 를 끊는다(«-o…» 로 시작하는 인자가 ssh 옵션으로 읽히지 않게) · ConnectTimeout 으로 패킷을 떨구는 호스트의 대기를 줄인다.
+    ? spawnSync('ssh', ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', '--', host, probe], { encoding: 'utf8', timeout: 20_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    : spawnSync('bash', ['-c', probe], { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] });
+  return hostDoctorRunFromSpawn(spawned, viaSsh);
+}
+
+/** spawn 결과 → 원격 한 발. ⛔ ssh 는 «연결 자체» 실패(거부·이름 못 풂·키 거절)를 exit 255 로 낸다 — 그건 탐침이
+ *  «못 쐈다» 이므로 null(→ unmeasured)이다. 그대로 넘기면 모든 점검이 «✗ fail» 로 읽힌다(10-11 리뷰 must-fix). */
+export function hostDoctorRunFromSpawn(
+  spawned: { error?: Error; status: number | null; stdout?: string | null; stderr?: string | null },
+  viaSsh: boolean,
+): HostDoctorRun | null {
+  if (spawned.error || spawned.status === null) return null;
+  if (viaSsh && spawned.status === 255) return null;
+  return { status: spawned.status, stdout: spawned.stdout ?? '', stderr: spawned.stderr ?? '' };
+}
+
+export interface HostDoctorOptions {
+  host: string;
+  role?: HostDoctorRole;
+  remote?: HostDoctorRemote;
+  expected?: HostDoctorExpected;
+  now?: () => Date;
+}
+
+/** 원격 `uname -s` ⊕ `/proc/version` 의 microsoft 로 darwin|linux|wsl. 못 재면 null. */
+export function detectHostDoctorPlatform(remote: HostDoctorRemote, host: string): HostDoctorPlatform | null {
+  const uname = remote(host, 'uname -s');
+  if (!uname || uname.status !== 0) return null;
+  const kernel = line(uname.stdout).toLowerCase();
+  if (kernel === 'darwin') return 'darwin';
+  if (kernel === 'linux') {
+    const procVersion = remote(host, 'cat /proc/version 2>/dev/null || true');
+    return procVersion && procVersion.status === 0 && /microsoft/i.test(procVersion.stdout) ? 'wsl' : 'linux';
+  }
+  return null;
+}
+
+/** 원격 아키텍처(`uname -m`). 못 재면 null. */
+export function detectHostDoctorArch(remote: HostDoctorRemote, host: string): string | null {
+  const run = remote(host, 'uname -m');
+  if (!run || run.status !== 0) return null;
+  const arch = line(run.stdout);
+  return nonEmpty(arch) ? arch : null;
+}
+
+/** 못 쏜 점검 — 기대값 칸엔 셸 탐침이 아니라 그 점검의 «기대 문장»을 싣는다(다른 경로와 같은 뜻). */
+function unmeasuredBecauseUnreached(spec: HostDoctorCheckSpec, options: { platform: HostDoctorPlatform | null; arch: string | null; expected: HostDoctorExpected }): HostDoctorCheckResult {
+  const expected = spec.expect({ status: 1, stdout: '', stderr: '' }, { platform: options.platform, arch: options.arch, expected: options.expected }).expected;
+  return { id: spec.id, fixKind: spec.fixKind, ...(spec.fix !== undefined ? { fix: spec.fix } : {}), status: 'unmeasured', observed: 'remote probe did not run', expected };
+}
+
+/** 점검 하나를 돌린다 — 원격 실패는 «pass 가 아닌» unmeasured 로만 간다. */
+function runCheck(spec: HostDoctorCheckSpec, options: Required<Pick<HostDoctorOptions, 'host'>> & { remote: HostDoctorRemote; role: HostDoctorRole; platform: HostDoctorPlatform | null; arch: string | null; expected: HostDoctorExpected }): HostDoctorCheckResult {
+  const run = options.remote(options.host, spec.probe);
+  const base = { id: spec.id, fixKind: spec.fixKind, ...(spec.fix !== undefined ? { fix: spec.fix } : {}) };
+  if (run === null) return unmeasuredBecauseUnreached(spec, options);
+  const verdict = spec.expect(run, { platform: options.platform, arch: options.arch, expected: options.expected });
+  return { ...base, status: verdict.status, observed: verdict.observed, expected: verdict.expected };
+}
+
+/** `elanous doctor host <host>` — 읽기 전용. ok 는 fail 0 ⊕ unmeasured 0 일 때만. */
+export function runHostDoctor(options: HostDoctorOptions): HostDoctorReport {
+  const host = options.host;
+  const role: HostDoctorRole = options.role === 'hq' ? 'hq' : 'worker';
+  const remote = options.remote ?? defaultHostDoctorRemote;
+  const expected = options.expected ?? {};
+  // 첫 발(uname -s)부터 못 쏘면 그 호스트에 «닿지 않는다» — 남은 탐침을 하나씩 기다리지 않고 전부 unmeasured 로 둔다.
+  const reached = remote(host, 'uname -s') !== null;
+  const platform = reached ? detectHostDoctorPlatform(remote, host) : null;
+  const arch = reached ? detectHostDoctorArch(remote, host) : null;
+  const specs = HOST_DOCTOR_CHECKS.filter((spec) => spec.roles.includes(role));
+  const checks = reached
+    ? specs.map((spec) => runCheck(spec, { host, remote, role, platform, arch, expected }))
+    : specs.map((spec) => unmeasuredBecauseUnreached(spec, { platform, arch, expected }));
+  const fail = checks.filter((check) => check.status === 'fail').map((check) => check.id);
+  const unmeasured = checks.filter((check) => check.status === 'unmeasured').map((check) => check.id);
+  const measuredAt = (options.now ?? (() => new Date()))().toISOString();
+  debug.log('fleet.doctor', 'host-checked', { host, platform, role, fail, unmeasured });
+  const missing = [...fail, ...unmeasured];
+  return {
+    id: host,
+    ok: missing.length === 0,
+    missing,
+    fixHref: missing.length === 0 ? null : HOST_DOCTOR_FIX_HREF,
+    platform,
+    arch,
+    role,
+    measuredAt,
+    checks,
+  };
+}
+
+/** 사람 출력 한 줄씩 — «✓|✗|→ <id> <한 줄>» 문법(node-setup.sh --check 와 같다). */
+export function formatHostDoctorLines(report: HostDoctorReport): string[] {
+  return report.checks.map((check) => {
+    const mark = check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : '→';
+    const detail = check.status === 'fail' ? `${check.observed} (expected: ${check.expected})` : check.observed;
+    return `${mark} ${check.id} ${detail}`;
+  });
+}

package/src/github/pr-labels.ts

@@ -32,6 +32,7 @@ export const PR_LABELS = [
   { name: 'elanous:release-hold', axis: 'addon', color: 'D4C5F9', description: 'Exclude from release notes until verified in production', appliedBy: ['launcher', 'session', 'human'], sweep: { action: 'none' } },
   { name: 'elanous:idea-stale', axis: 'addon', color: 'FBCA04', description: 'Approval pending beyond the notification threshold', appliedBy: ['sweeper'], sweep: { action: 'notify', afterDays: IDEA_STALE_DAYS } },
   { name: 'elanous:needs-rebase', axis: 'addon', color: 'E99695', description: 'Approval blocked by conflicts or failing checks', appliedBy: ['sweeper'], sweep: { action: 'block-approval' } },
+  { name: 'elanous:bench', axis: 'addon', color: 'C5DEF5', description: 'Bench arm output: never landed or swept; the owner harvests the winner onto main', appliedBy: ['harness'], sweep: { action: 'none' } },
   { name: 'elanous:harvestable', axis: 'addon', color: 'FBCA04', description: 'Pod terminal marked this PR for harvest', appliedBy: ['harness'], sweep: { action: 'close', afterHours: STALLED_DRAFT_HOURS } },
   { name: 'elanous:from-harness', axis: 'origin', color: 'C5DEF5', description: 'Launched from a harness goal', appliedBy: ['harness'], sweep: { action: 'none' } },
   { name: 'elanous:from-intake', axis: 'origin', color: 'C5DEF5', description: 'Launched from an absorbed idea', appliedBy: ['launcher'], sweep: { action: 'none' } },

package/src/goals/judge.ts

@@ -11,7 +11,8 @@
 // PAUSE+ASK in the loop. Drift is more dangerous than a confirm.
 
 import { debug } from '../debug/log.js';
-import { getProvider, resolveDefaultProvider, type LLMMessage, type LLMOpts } from '../llm.js';
+import { getProvider, logAgentTurnUsage, resolveDefaultProvider, type LLMMessage, type LLMOpts } from '../llm.js';
+import type { LLMUsage } from '../prompt-cache/types.js';
 import type { GoalJudgeVerdict } from './types.js';
 
 export interface JudgeInput {
@@ -180,15 +181,28 @@ export async function judgeGoalTurn(
     });
 
     let text = '';
+    let usage: LLMUsage = {};
     try {
-      const stream = provider.chat(messages, llmOpts);
       const t0 = Date.now();
-      for await (const chunk of stream) {
-        text += chunk;
-        if (opts.timeoutMs && Date.now() - t0 > opts.timeoutMs) {
-          throw new Error(`judge timeout after ${opts.timeoutMs}ms`);
+      if (provider.streamChat) {
+        for await (const ev of provider.streamChat(messages, llmOpts)) {
+          if (ev.type === 'text' && ev.delta) text += ev.delta;
+          else if (ev.type === 'usage') usage = { ...usage, ...ev.usage };
+          if (opts.timeoutMs && Date.now() - t0 > opts.timeoutMs) {
+            throw new Error(`judge timeout after ${opts.timeoutMs}ms`);
+          }
+        }
+      } else {
+        for await (const chunk of provider.chat(messages, llmOpts)) {
+          text += chunk;
+          if (opts.timeoutMs && Date.now() - t0 > opts.timeoutMs) {
+            throw new Error(`judge timeout after ${opts.timeoutMs}ms`);
+          }
         }
       }
+      try {
+        logAgentTurnUsage(opts.model ?? provider.defaultModel, usage, { providerName: provider.name, site: 'goals.judge' });
+      } catch { /* best-effort observation */ }
     } catch (err) {
       debug.log('goal', 'judge.error', { attempt, message: (err as Error).message }, { level: 'error' });
       // On timeout / abort, return null so the loop can pause-ask

package/src/graph-runner/graph-cli.ts

@@ -155,11 +155,16 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
     .description('Advance one graph run, resuming a pending decision or starting only when requested')
     .option('--start', 'Start a new run when the graph is idle')
     .option('--schedule', 'Subscribe graph YAML triggers.schedule to the workflow scheduler and tick on each fire')
+    .option('--webhook', 'Subscribe graph YAML triggers.webhook to the workflow webhook router and tick on each request')
+    .option('--port <n>', 'Port for --webhook to listen on (default: any free port)')
     .option('--input <json>', 'JSON object passed to a newly started run')
     .option('--json', 'Print the tick result as JSON')
-    .action(async (file: string, opts: { start?: boolean; schedule?: boolean; input?: string; json?: boolean }) => {
+    .action(async (file: string, opts: { start?: boolean; schedule?: boolean; webhook?: boolean; port?: string; input?: string; json?: boolean }) => {
       try {
         if (opts.schedule && (opts.start || opts.input !== undefined || opts.json)) throw new Error('--schedule cannot be combined with --start, --input or --json');
+        if (opts.webhook && (opts.schedule || opts.start || opts.input !== undefined || opts.json)) throw new Error('--webhook cannot be combined with --schedule, --start, --input or --json');
+        if (opts.port !== undefined && !opts.webhook) throw new Error('--port requires --webhook');
+        if (opts.port !== undefined && (!/^\d+$/.test(opts.port) || Number(opts.port) > 65535)) throw new Error('--port must be an integer from 0 to 65535');
         if (opts.input !== undefined && !opts.start) throw new Error('--input requires --start');
         let input: Record<string, unknown> | undefined;
         if (opts.input !== undefined) {
@@ -171,6 +176,42 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
         }
         await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
         const { graphTick } = await import('./graph-tick.js');
+        if (opts.webhook) {
+          const { createWebhookSource } = await import('../workflow-runtime/triggers/webhook-source.js');
+          const graphFile = resolve(file);
+          const source = createWebhookSource();
+          // The CLI tick callback is the graph counterpart of the workflow webhook router's onEmit.
+          source.subscribeGraph(graphFile, async () => {
+            try {
+              const { notifyGraphEvents } = await import('./graph-notify.js');
+              const result = await graphTick(graphFile, { startIfIdle: true, deps: { notify: async () => { await notifyGraphEvents(); } } });
+              if (result.status === 'refused') return { ok: false, error: `refused: ${result.reason}` };
+              if (result.status === 'failed') return { ok: false, runId: result.runId, error: 'failed' };
+              return result.runId ? { ok: true, runId: result.runId } : { ok: false, error: `no run (${result.action})` };
+            } catch (error) {
+              debug.log('graph.runner', 'webhook-tick-failed', { file: graphFile, error: error instanceof Error ? error.message : String(error) });
+              return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+          });
+          if (!source.subscriptions().length) throw new Error('graph triggers.webhook is missing');
+          await source.start();
+          const server = Bun.serve({
+            hostname: '127.0.0.1',
+            port: opts.port === undefined ? 0 : Number(opts.port),
+            fetch: async (request) => {
+              const response = await source.dispatch({
+                method: request.method, path: new URL(request.url).pathname,
+                headers: Object.fromEntries(request.headers), body: await request.text(),
+              });
+              return response ? new Response(response.body, { status: response.status, headers: response.headers }) : new Response('webhook source not started', { status: 503 });
+            },
+          });
+          console.log(`graph webhook: ${source.subscriptions().length} active on http://127.0.0.1:${server.port}`);
+          const shutdown = () => { void server.stop(true).then(() => source.stop()).then(() => { process.exitCode = 0; }); };
+          process.once('SIGINT', shutdown);
+          process.once('SIGTERM', shutdown);
+          return;
+        }
         if (opts.schedule) {
           const { createScheduleSource } = await import('../workflow-runtime/triggers/schedule-source.js');
           const graphFile = resolve(file);