elanous 0.2.12 → 0.2.14

package/src/harness/model-input-observation.ts

@@ -0,0 +1,37 @@
+import { debug } from '../debug/log.js';
+
+/** One observation per harness node execution or loop tick, not per LLM request. */
+export type ModelInputObservationTarget = {
+  scope: 'harness-node' | 'loop-tick';
+  nodeKind: string;
+  graphId?: string;
+  runId?: string;
+  nodeId?: string;
+  tickId?: string;
+};
+
+export type ModelInputObservation = ModelInputObservationTarget & (
+  | { status: 'measured'; inputTokens: number }
+  | { status: 'unmeasured'; inputTokens: null; reason: 'usage-unavailable' | 'invalid-usage' }
+);
+
+/**
+ * Publish a single structured record at the execution boundary. Only provider-reported,
+ * nonnegative integer counts are measurements; missing/invalid usage is never a zero.
+ * The caller supplies the total across model calls for this execution, if available.
+ */
+export function observeModelInputTokens(
+  target: ModelInputObservationTarget,
+  inputTokens?: number | null,
+): ModelInputObservation {
+  const observation: ModelInputObservation = inputTokens === null || inputTokens === undefined
+    ? { ...target, status: 'unmeasured', inputTokens: null, reason: 'usage-unavailable' }
+    : Number.isSafeInteger(inputTokens) && inputTokens >= 0
+      ? { ...target, status: 'measured', inputTokens }
+      : { ...target, status: 'unmeasured', inputTokens: null, reason: 'invalid-usage' };
+
+  try {
+    debug.log('harness.model-input', 'recorded', observation);
+  } catch { /* Logging must not interrupt the node or tick. */ }
+  return observation;
+}

package/src/hooks/github-shadow.ts

@@ -1,5 +1,9 @@
 import { createHash } from 'node:crypto';
-import { join } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
 import { openMsgStore } from '../msg/msg-store.js';
 import { CardStore, redactSecrets } from '../task-cards/card-store.js';
 import { isGithubSpamText, PUBLIC_GITHUB_REPO } from './providers.js';
@@ -72,8 +76,57 @@ function object(value: unknown): Record<string, unknown> | undefined {
 }
 function gitSha(value: unknown): value is string { return typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value); }
 
+export interface ShadowReviewResult {
+  reviewed: boolean;
+  verdict: 'pass' | 'warn' | 'fail' | null;
+  summary: string;
+}
+
+/** Runs the read-only self-review command from a detached, disposable worktree of trusted HEAD.
+ * The PR is never checked out: only its remote diff enters the reviewer prompt. */
+export async function runGithubShadowReview(number: number, repo = resolve(process.cwd())): Promise<ShadowReviewResult> {
+  if (!Number.isSafeInteger(number) || number < 1) throw new Error('invalid PR number');
+  const dir = mkdtempSync(join(tmpdir(), 'elanous-review-shadow-'));
+  const worktree = join(dir, 'repo');
+  let attached = false;
+  try {
+    const added = spawnSync('git', ['-C', repo, 'worktree', 'add', '--detach', worktree, 'HEAD'], { encoding: 'utf8', timeout: 30_000 });
+    if (added.status !== 0) throw new Error('isolated worktree unavailable');
+    attached = true;
+    if (existsSync(join(repo, 'node_modules'))) symlinkSync(join(repo, 'node_modules'), join(worktree, 'node_modules'), 'dir');
+    const output = await new Promise<string>((done, fail) => {
+      const child = spawn(process.execPath, [join(worktree, 'bin/elanous.mjs'), '--test', 'self', 'review', String(number), '--json'], {
+        cwd: worktree, env: { ...process.env, GH_REPO: PUBLIC_GITHUB_REPO }, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let stdout = '';
+      let stderr = '';
+      const timer = setTimeout(() => child.kill(), 360_000);
+      child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString(); if (stdout.length > 100_000) child.kill(); });
+      child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString(); if (stderr.length > 100_000) child.kill(); });
+      child.on('error', error => { clearTimeout(timer); fail(error); });
+      child.on('close', code => { clearTimeout(timer); code === 0 ? done(stdout) : fail(new Error(`self review exited ${code}: ${stderr.slice(0, 200)}`)); });
+    });
+    const parsed: unknown = JSON.parse(output);
+    const result = object(parsed);
+    if (!result) throw new Error('self review returned no result');
+    const verdict = result.reviewed === true && ['pass', 'warn', 'fail'].includes(String(result.verdict))
+      ? result.verdict as 'pass' | 'warn' | 'fail' : null;
+    const findings = [...(Array.isArray(result.mustFix) ? result.mustFix : []), ...(Array.isArray(result.shouldFix) ? result.shouldFix : [])]
+      .filter((item): item is string => typeof item === 'string').slice(0, 8);
+    return { reviewed: result.reviewed === true && verdict !== null, verdict,
+      summary: redactSecrets(verdict ? `${verdict}: ${findings.join('; ') || 'no findings'}` : `review unavailable: ${String(result.error ?? 'not reviewed')}`).slice(0, 2000) };
+  } finally {
+    if (attached) {
+      rmSync(join(worktree, 'node_modules'), { force: true });
+      spawnSync('git', ['-C', repo, 'worktree', 'remove', '--force', worktree], { timeout: 30_000 });
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 /** 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> {
+export async function recordGithubShadow(event: QueuedHook, root: string, fetchFn: typeof fetch = fetch,
+  review: (number: number) => Promise<ShadowReviewResult> = runGithubShadowReview): 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) ||
@@ -94,6 +147,7 @@ export async function recordGithubShadow(event: QueuedHook, root: string, fetchF
       .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;
+    debug.log('steward.intake', 'judged', { eventKey: key, number: github.number, type: github.type, verdict: recorded.verdict, reason: recorded.reason });
     const cards = new CardStore(root);
     try {
       const goalId = `github:${github.repository}:${github.type}:${github.number}`;
@@ -104,5 +158,21 @@ export async function recordGithubShadow(event: QueuedHook, root: string, fetchF
       if (!card.sections.some(section => section.key === sectionKey))
         cards.appendSection(card.id, { key: sectionKey, owner: 'steward', content: redactSecrets(content) });
     } finally { cards.close(); }
+    if (github.type === 'pull_request' && recorded.verdict === 'accepted') {
+      store.db.exec(`CREATE TABLE IF NOT EXISTS github_shadow_reviews (
+        event_key TEXT PRIMARY KEY, repository TEXT NOT NULL, item_number INTEGER NOT NULL,
+        reviewed INTEGER NOT NULL, verdict TEXT, summary TEXT NOT NULL
+      )`);
+      if (!store.db.query('SELECT event_key FROM github_shadow_reviews WHERE event_key = ?').get(key)) {
+        let result: ShadowReviewResult;
+        try { result = await review(github.number); }
+        catch (error) { result = { reviewed: false, verdict: null, summary: `review unavailable: ${error instanceof Error ? error.message : String(error)}` }; }
+        store.db.query(`INSERT OR IGNORE INTO github_shadow_reviews
+          (event_key, repository, item_number, reviewed, verdict, summary) VALUES (?, ?, ?, ?, ?, ?)`)
+          .run(key, github.repository, github.number, result.reviewed ? 1 : 0, result.verdict,
+            redactSecrets(result.summary).slice(0, 2000));
+        debug.log('steward.review-shadow', 'recorded', { eventKey: key, number: github.number, reviewed: result.reviewed, verdict: result.verdict });
+      }
+    }
   } finally { store.close(); }
 }

package/src/hooks/receiver.ts

@@ -4,7 +4,7 @@ import { getUserConfig, parseEventsConfig, userConfigPath, type EventsConfig } f
 import { dispatchHook, type HookWake } from './dispatch.js';
 import { getSecretAsync } from '../nexus/config/secrets/index.js';
 import { HookQueue, type QueuedHook } from './queue.js';
-import { recordGithubShadow } from './github-shadow.js';
+import { recordGithubShadow, type ShadowReviewResult } from './github-shadow.js';
 import { toExternalTask, verifyWebhook, type HookProvider } from './providers.js';
 import { drainReports, handleReportPost, ReportLimiter, ReportQueue, type ReceivedReport } from './error-report.js';
 import { ConsultLimiter, ConsultQueue, drainConsults, handleConsultPost, type QueuedConsult } from './consult-intake.js';
@@ -35,6 +35,8 @@ export interface HookReceiverOptions {
   consultEnabled?: boolean;
   /** GET-only public metadata lookup; failure forces human review. */
   githubFetch?: typeof fetch;
+  /** Test seam for the isolated read-only self review; never publishes externally. */
+  githubShadowReview?: (number: number) => Promise<ShadowReviewResult>;
 }
 
 /** `/v1/tasks` lives on the Primary's nexus API, not on the control plane — so the address is its own setting. */
@@ -140,7 +142,7 @@ export function startHookReceiver(options: HookReceiverOptions): { url: string;
   // L14: public-repository intake events take the shadow ledger path; every other event keeps the seat dispatch path.
   const dispatch = options.forward ?? ((event: QueuedHook) => dispatchHook(event, options.root ?? effectiveInstanceRoot(), events, options.wakeSeat).then(() => 204));
   const forward = (event: QueuedHook) => event.provider === 'github' && event.task.github
-    ? recordGithubShadow(event, options.root ?? effectiveInstanceRoot(), options.githubFetch).then(() => 204)
+    ? recordGithubShadow(event, options.root ?? effectiveInstanceRoot(), options.githubFetch, options.githubShadowReview).then(() => 204)
     : dispatch(event);
   const attempts = new Map<string, { next: number; failures: number }>();
   const pending = new Set<string>();

package/src/hq/hq.ts

@@ -0,0 +1,318 @@
+// HQ lease operations — CLI-facing glue over the pure decisions in ./lease.ts (HQ-HB · HQ-FENCE · 10-04).
+// Every outcome leaves one observation line (hq.lease / hq.fence) so the 12:00 drill is measurable from logs.
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { debug } from '../debug/log.js';
+import { DEFAULT_NEXUS_HTTP_PORT } from '../nexus/default-port.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { getUserConfig, type HqConfig, type HqFenceRole } from '../user-config.js';
+import {
+  DEFAULT_TTL_SECONDS, decideAcquire, decideArbiterCheck, decideFence, decideRelease, decideRenew, defaultSshRunner,
+  fileLeaseStore, leaseExpired, parseLease, probeReachable, recordView, serializeLease, sshLeaseStore, sshReachable, localShellRunner,
+  type HostProbe, type LeaseRecord, type LeaseStore, type LocalHqState, type SshRunner,
+} from './lease.js';
+
+export const FENCE_ROLES: readonly HqFenceRole[] = ['telegram-poller', 'cron', 'seat-loop', 'release-run', 'conatus', 'git-push', 'ledger-cli'];
+
+export interface HqDeps {
+  config?: HqConfig;
+  store?: LeaseStore;
+  ssh?: SshRunner;
+  /** Holder/standby views and the arbiter's check use this tailnet probe — never ssh (OP 10-04 09:04). */
+  probe?: HostProbe;
+  localPath?: string;
+  /** Host-local identity, deliberately outside the replicated config/state directory. */
+  hostPath?: string;
+  /** Seen-generation marker (default hq.seenGenerationFile · ~/.elanous-hq/seen-generation). */
+  seenPath?: string;
+  now?: () => number;
+  log?: typeof debug.log;
+}
+
+interface Resolved { me: string; arbiter: string; standby: string; ttl: number; failOpen: Set<HqFenceRole>; store: LeaseStore; ssh: SshRunner; probe: HostProbe; localPath: string; seenPath: string; now: () => number; log: typeof debug.log }
+const defaultHostPath = () => join(homedir(), '.elanous-hq', 'host');
+
+function readHost(path: string): string | undefined {
+  try {
+    lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+  const text = readFileSync(path, 'utf8');
+  const name = text.endsWith('\n') ? text.slice(0, -1) : text;
+  if (!name || name !== name.trim() || /[\r\n]/.test(name)) {
+    throw new Error(`hq host: invalid host file: ${path}`);
+  }
+  return name;
+}
+
+/** Set this machine's identity outside the replicable config.json and HQ state universe. */
+export function hqHostSet(name: string, path = defaultHostPath()): string {
+  if (!name || name !== name.trim() || /[\r\n]/.test(name)) throw new Error('hq host set: name must be one nonempty line without surrounding whitespace');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tempDir = mkdtempSync(`${path}.`);
+  try {
+    chmodSync(tempDir, 0o700);
+    const tmp = join(tempDir, 'host');
+    writeFileSync(tmp, `${name}\n`, { flag: 'wx', mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+  return path;
+}
+
+function resolve(deps: HqDeps = {}): Resolved {
+  const config = deps.config ?? getUserConfig().hq ?? {};
+  const ssh = deps.ssh ?? defaultSshRunner;
+  const arbiter = config.arbiter ?? 'cloud-vm';
+  const local = readHost(deps.hostPath ?? defaultHostPath());
+  const me = local ?? config.hostName ?? hostname().replace(/\.local$/, '');
+  const log = deps.log ?? debug.log.bind(debug);
+  if (local && config.hostName && local !== config.hostName) {
+    try { log('hq.lease', 'hostname-mismatch', { local, config: config.hostName }); } catch { /* observation is fail-soft */ }
+  }
+  return {
+    me,
+    arbiter,
+    standby: config.standby ?? 'node-b',
+    ttl: config.ttlSeconds ?? DEFAULT_TTL_SECONDS,
+    failOpen: new Set(config.failOpenRoles ?? []),
+    store: deps.store ?? sshLeaseStore(arbiter, arbiter === 'local' ? localShellRunner : ssh),
+    ssh,
+    probe: deps.probe ?? tailnetProbe(config),
+    localPath: deps.localPath ?? join(getElanousConfigDir(), 'hq', 'local.json'),
+    seenPath: deps.seenPath ?? config.seenGenerationFile ?? (deps.localPath ? `${deps.localPath}.seen-generation` : join(homedir(), '.elanous-hq', 'seen-generation')),
+    now: deps.now ?? (() => Math.floor(Date.now() / 1000)),
+    log,
+  };
+}
+
+/** MagicDNS suffix from `tailscale status --json` (cached per process). */
+let dnsSuffix: string | null | undefined;
+function magicDnsSuffix(bin: string): string | undefined {
+  if (dnsSuffix !== undefined) return dnsSuffix ?? undefined;
+  const r = spawnSync(bin, ['status', '--json'], { encoding: 'utf8', timeout: 10_000 });
+  try { dnsSuffix = (JSON.parse(r.stdout || '{}') as { MagicDNSSuffix?: string }).MagicDNSSuffix?.replace(/\.$/, '') || null; } catch { dnsSuffix = null; }
+  return dnsSuffix ?? undefined;
+}
+
+/** Health URL of a remote host's nexus over the tailnet — its `tailscale serve` TLS mapping of the default nexus port
+ *  (resolveDaemonEndpoint only knows this machine's daemon; the arbiter probes another host). */
+export function healthUrlFor(host: string, config: HqConfig, suffix: () => string | undefined): string | undefined {
+  const pinned = config.healthUrls?.[host];
+  if (pinned) return pinned;
+  const domain = config.tailnetDomain ?? suffix();
+  return domain ? `https://${host}.${domain}:${DEFAULT_NEXUS_HTTP_PORT}/v1/health` : undefined;
+}
+
+/** Default probe: `tailscale ping -c 1` ⊕ curl of the nexus health (200 only). Both are tailnet-only, no ssh. */
+export function tailnetProbe(config: HqConfig): HostProbe {
+  const bin = config.tailscaleBin ?? 'tailscale';
+  const timeout = config.probeTimeoutSeconds ?? 5;
+  return {
+    ping(host) {
+      const r = spawnSync(bin, ['ping', '-c', '1', '--timeout', `${timeout}s`, host], { encoding: 'utf8', timeout: (timeout + 5) * 1000 });
+      return r.status === 0 && /\bpong\b/.test(r.stdout ?? '');
+    },
+    health(host) {
+      const url = healthUrlFor(host, config, () => magicDnsSuffix(bin));
+      if (!url) return false;
+      const r = spawnSync('curl', ['-s', '-o', '/dev/null', '-m', String(timeout), '-w', '%{http_code}', url], { encoding: 'utf8', timeout: (timeout + 5) * 1000 });
+      return (r.stdout ?? '').trim() === '200';
+    },
+  };
+}
+
+export function readLocal(path: string): LocalHqState {
+  try { return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) as LocalHqState : {}; } catch { return {}; }
+}
+function writeLocal(path: string, state: LocalHqState): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Highest lease generation this host ever observed (null = never). */
+export function readSeenGeneration(path: string): number | null {
+  try {
+    if (!existsSync(path)) return null;
+    const n = Number(readFileSync(path, 'utf8').trim());
+    return Number.isSafeInteger(n) && n > 0 ? n : null;
+  } catch { return null; }
+}
+/** Keep the max generation seen (atomic · 600). Fail-soft: a lost write never blocks the lease operation. */
+function noteSeen(r: Resolved, record: LeaseRecord | null | undefined): void {
+  if (!record || !Number.isSafeInteger(record.generation) || record.generation < 1) return;
+  try {
+    const prev = readSeenGeneration(r.seenPath);
+    if (prev !== null && prev >= record.generation) return;
+    mkdirSync(dirname(r.seenPath), { recursive: true, mode: 0o700 });
+    const tmp = `${r.seenPath}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${record.generation}\n`, { mode: 0o600 });
+    renameSync(tmp, r.seenPath);
+  } catch (error) { observe(r, 'hq.lease', 'seen-write-failed', { error: String(error).slice(0, 200) }); }
+}
+
+/** `elanous hq seen` — wrappers use «never seen» (exit 3) to allow the pre-drill default-source path only. */
+export function hqSeen(deps: HqDeps = {}): { seen: boolean; generation: number | null; path: string } {
+  const r = resolve(deps);
+  const generation = readSeenGeneration(r.seenPath);
+  return { seen: generation !== null, generation, path: r.seenPath };
+}
+
+function observe(r: Resolved, category: 'hq.lease' | 'hq.fence', event: string, data: Record<string, unknown>): void {
+  try { r.log(category, event, { host: r.me, ...data }); } catch { /* observation is fail-soft */ }
+}
+
+/** Read → decide → CAS, retried on a lost race (two hosts racing cannot both win: only one CAS sees the old bytes). */
+function mutate(r: Resolved, decide: (record: LeaseRecord | null, now: number) => { ok: true; next: LeaseRecord } | { ok: false; reason: string }):
+  { ok: true; record: LeaseRecord } | { ok: false; reason: string; record: LeaseRecord | null } {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const { now, raw } = r.store.read();
+    const record = parseLease(raw);
+    const decided = decide(record, now);
+    if (!decided.ok) return { ok: false, reason: decided.reason, record };
+    if (r.store.cas(raw, serializeLease(decided.next))) return { ok: true, record: decided.next };
+  }
+  return { ok: false, reason: 'lost the race five times', record: null };
+}
+
+export type LeaseAction = 'acquire' | 'renew' | 'status' | 'release';
+export function hqLease(action: LeaseAction, deps: HqDeps = {}, opts: { host?: string } = {}) {
+  const r0 = resolve(deps);
+  const r = opts.host ? { ...r0, me: opts.host } : r0;
+  if (action === 'status') {
+    const { now, raw } = r.store.read();
+    const record = parseLease(raw);
+    noteSeen(r, record);
+    return { ok: true as const, action, record, ageSeconds: record ? now - record.renewedAt : null, expired: record ? leaseExpired(record, now) : null };
+  }
+  const local = readLocal(r.localPath);
+  const result = mutate(r, (record, now) => action === 'acquire' ? decideAcquire(record, r.me, now, r.ttl)
+    : action === 'renew' ? decideRenew(record, r.me, local.generation, now) : decideRelease(record, r.me));
+  noteSeen(r, result.record);
+  if (result.ok && action !== 'release') writeLocal(r.localPath, { holder: result.record.holder, generation: result.record.generation, confirmedAt: r.now(), ttlSeconds: result.record.ttlSeconds });
+  if (result.ok && action === 'release') writeLocal(r.localPath, { ...local, holder: undefined, confirmedAt: undefined });
+  observe(r, 'hq.lease', result.ok ? (action === 'acquire' ? 'acquired' : action === 'renew' ? 'renewed' : 'released') : `${action}-refused`,
+    result.ok ? { generation: result.record.generation } : { reason: result.reason });
+  return { action, ...result };
+}
+
+/**
+ * Heartbeat (every 10 min on mbp and node-b). Holder → renew at the arbiter, or (arbiter down) confirm quorum through the standby.
+ * Non-holder → report its view of the holder to the arbiter (rule ②) and adopt a generation the arbiter granted it.
+ */
+export function hqHeartbeat(deps: HqDeps = {}) {
+  const r = resolve(deps);
+  const local = readLocal(r.localPath);
+  let read: { now: number; raw: string | null };
+  try { read = r.store.read(); } catch (error) {
+    const standbyUp = local.holder === r.me ? sshReachable(r.standby, r.ssh) : false;
+    if (local.holder === r.me && standbyUp) writeLocal(r.localPath, { ...local, confirmedAt: r.now() });
+    const outcome = local.holder === r.me ? (standbyUp ? 'quorum-standby' : 'arbiter-unreachable') : 'arbiter-unreachable';
+    observe(r, 'hq.lease', outcome, { error: String(error).slice(0, 200), standbyReachable: standbyUp });
+    return { outcome };
+  }
+  const record = parseLease(read.raw);
+  noteSeen(r, record);
+  if (!record) { observe(r, 'hq.lease', 'no-lease', { seenGeneration: readSeenGeneration(r.seenPath) }); return { outcome: 'no-lease' as const }; }
+  if (record.holder === r.me) {
+    // The record names me as holder: a generation the arbiter granted me (promotion) is adopted, never refused.
+    const renewed = mutate(r, (current, now) => decideRenew(current, r.me, Math.max(local.generation ?? 0, current?.generation ?? 0), now));
+    if (renewed.ok && (local.generation ?? 0) < renewed.record.generation) observe(r, 'hq.lease', 'generation-adopted', { from: local.generation ?? null, to: renewed.record.generation });
+    if (renewed.ok) {
+      noteSeen(r, renewed.record);
+      writeLocal(r.localPath, { holder: r.me, generation: renewed.record.generation, confirmedAt: r.now(), ttlSeconds: renewed.record.ttlSeconds });
+      observe(r, 'hq.lease', 'renewed', { generation: renewed.record.generation });
+      return { outcome: 'renewed' as const, generation: renewed.record.generation };
+    }
+    observe(r, 'hq.lease', 'renew-refused', { reason: renewed.reason });
+    return { outcome: 'renew-refused' as const, reason: renewed.reason };
+  }
+  // Not the holder: report the view, keep the granted generation, stay standby.
+  const seen = probeReachable(record.holder, r.probe);
+  const reachable = seen.reachable;
+  mutate(r, (current) => current ? { ok: true, next: recordView(current, r.me, reachable, read.now) } : { ok: false, reason: 'no lease' });
+  if (leaseExpired(record, read.now)) observe(r, 'hq.lease', 'expired-seen', { holder: record.holder, generation: record.generation });
+  writeLocal(r.localPath, { holder: record.holder, generation: record.generation, ttlSeconds: record.ttlSeconds });
+  observe(r, 'hq.lease', 'standby', { holder: record.holder, generation: record.generation, holderReachable: reachable, ping: seen.ping, health: seen.health });
+  return { outcome: 'standby' as const, holder: record.holder, holderReachable: reachable };
+}
+
+/**
+ * Arbiter check (cron on cloud-vm every 10 min, next to the file): probe the holder over the tailnet
+ * (`tailscale ping` ⊕ nexus health · no ssh into home machines) and promote per rule ②.
+ */
+export function hqArbiterCheck(deps: HqDeps & { leasePath?: string } = {}) {
+  const r0 = resolve(deps);
+  const r = deps.store ? r0 : { ...r0, store: fileLeaseStore(deps.leasePath ?? join(process.env.HOME ?? '', '.elanous-hq', 'lease.json')) };
+  let outcome: { promoted: boolean; streak: number; holder?: string; generation?: number; ping?: boolean; health?: boolean } = { promoted: false, streak: 0 };
+  const result = mutate(r, (record, now) => {
+    if (!record) return { ok: false, reason: 'no lease' };
+    const seen = probeReachable(record.holder, r.probe);
+    const checked = decideArbiterCheck(record, { arbiter: r.me, standby: r.standby, arbiterReachesHolder: seen.reachable, now });
+    outcome = { promoted: checked.promoted, streak: checked.streak, holder: checked.next.holder, generation: checked.next.generation, ping: seen.ping, health: seen.health };
+    return { ok: true, next: checked.next };
+  });
+  observe(r, 'hq.lease', outcome.promoted ? 'promoted' : 'arbiter-check', { ...outcome, ok: result.ok });
+  return { ok: result.ok, ...outcome };
+}
+
+/** Standby's own generation, asked over ssh (rule ③ when the arbiter is down). */
+function standbyGeneration(r: Resolved): number | undefined {
+  const res = r.ssh(r.standby, 'cat "$HOME/.elanous/hq/local.json" 2>/dev/null || true');
+  try { const g = (JSON.parse(res.stdout || '{}') as LocalHqState).generation; return typeof g === 'number' ? g : undefined; } catch { return undefined; }
+}
+
+export function hqFenceDecision(role: HqFenceRole, deps: HqDeps = {}) {
+  const r = resolve(deps);
+  const local = readLocal(r.localPath);
+  let record: LeaseRecord | null | 'unreachable';
+  try { record = parseLease(r.store.read().raw); } catch { record = 'unreachable'; }
+  if (record !== 'unreachable') noteSeen(r, record);
+  const seenGeneration = readSeenGeneration(r.seenPath);
+  const standbyUp = record === 'unreachable' && local.holder === r.me ? sshReachable(r.standby, r.ssh) : undefined;
+  const decided = decideFence({
+    me: r.me, now: r.now(), local, record,
+    ...(standbyUp !== undefined ? { standbyReachable: standbyUp } : {}),
+    ...(standbyUp ? { standbyGeneration: standbyGeneration(r) } : {}),
+    failOpen: role !== 'ledger-cli' && r.failOpen.has(role),
+    ...(seenGeneration !== null ? { seenGeneration } : {}),
+  });
+  if (decided.run && record !== 'unreachable' && record) writeLocal(r.localPath, { holder: r.me, generation: record.generation, confirmedAt: r.now(), ttlSeconds: record.ttlSeconds });
+  observe(r, 'hq.fence', decided.run ? 'allowed' : 'skipped', { role, reason: decided.reason, holder: decided.holder, generation: decided.generation });
+  return decided;
+}
+
+/** CLI ledger writes fail closed after the first lease; bootstrap is allowed only before any generation was seen. */
+export function hqCliWriteAllowed(command: string, override = false, deps: HqDeps = {}): boolean {
+  const decision = hqFenceDecision('ledger-cli', deps);
+  const allowed = decision.run || decision.reason === 'no-lease';
+  const r = resolve(deps);
+  if (override) {
+    observe(r, 'hq.fence', 'cli-override', { command, reason: decision.reason, holder: decision.holder, generation: decision.generation, allowed });
+    console.error(`hq override: ${command} — ${decision.reason} (holder ${decision.holder ?? 'unknown'} gen ${decision.generation ?? 'unknown'})`);
+    return true;
+  }
+  if (allowed) return true;
+  observe(r, 'hq.fence', 'cli-refused', { command, reason: decision.reason, holder: decision.holder, generation: decision.generation });
+  console.error(`본부는 ${decision.holder ?? 'unknown'} gen ${decision.generation ?? 'unknown'} — 원장 쓰기는 지금 본부로 보내라 (수동 우회: --hq-override, 관측)`);
+  process.exitCode = 4;
+  return false;
+}
+
+/** Run `command` only when this host may write; the child sees ELANOUS_HQ_GENERATION. Skips exit 0. */
+export function hqFenceRun(role: HqFenceRole, command: string[], deps: HqDeps = {}): number {
+  const decided = hqFenceDecision(role, deps);
+  if (!decided.run) { console.error(`hq fence: skip ${role} — ${decided.reason}${decided.holder ? ` (holder ${decided.holder} gen ${decided.generation})` : ''}`); return 0; }
+  const [cmd, ...args] = command;
+  if (!cmd) throw new Error('hq fence: command required after --');
+  const r = spawnSync(cmd, args, { stdio: 'inherit', env: { ...process.env, ELANOUS_HQ_GENERATION: String(decided.generation ?? '') } });
+  return r.status ?? 1;
+}