elanous 0.2.21 → 0.2.23

package/src/harness/harness-queue.ts

@@ -4,6 +4,7 @@ import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync
 import { join, resolve } from 'node:path';
 import { Database } from 'bun:sqlite';
 import { debug } from '../debug/log.js';
+import { stateDirSourceForChild } from '../agent/identity-env.js';
 import { findTreeRoot } from '../cli/test-flag.js';
 import { readLogInstances, type LogInstanceView } from '../mss/logging/instance-registry.js';
 import { effectiveInstanceRoot, prodInstanceRoot, releaseLedgerRoot } from '../instance/resolve.js';
@@ -20,6 +21,7 @@ import { hostLeaseCounts, leaseHasPendingPod } from '../pod-lease/host-lease.js'
 import { leaseKubectl, measurePoolLease } from '../task-orchestrator/surfaces/pod-lease.js';
 import { parsePodPool, podPoolHostLease, resolvePodPoolSpec } from '../task-orchestrator/surfaces/pod-pool.js';
 import { writeHarnessQueueReceipt } from './harness-queue-child.js';
+import { adviseLaunch, compareLaunchAdvice, type LaunchAdvice } from './launch-advice.js';
 import { finishAdvice, measureFinish, recordFinishHistory, type FinishMetrics } from '../loops/orchestrator/finish-rate.js';
 
 export type QueueSeat = 'OP' | 'TC' | 'MK' | 'UX';
@@ -73,6 +75,8 @@ export interface HarnessQueueDeps {
   configPath?: string;
   cap?: (seat: QueueSeat) => number;
   pool?: () => QueuePool;
+  /** Shadow-only advice seam; exceptions must not affect the queue decision. */
+  advice?: typeof adviseLaunch;
   launch?: (item: QueueItem, args: string[], root: string) => Promise<number>;
   /** Test seam: runs after a direct CLI call enqueued its row and before that call's own tick (race tests). */
   afterEnqueue?: (item: QueueItem) => void | Promise<void>;
@@ -385,24 +389,25 @@ export function listHarnessQueue(deps: HarnessQueueDeps = {}): QueueItem[] {
   return read(harnessQueuePath(deps.root ?? effectiveInstanceRoot()));
 }
 
-/** A missing row is not proof of failure unless the queue left a cancellation marker. */
-export function harnessQueueOutcome(id: string, deps: HarnessQueueDeps = {}): 'pending' | 'succeeded' | 'retryable' | 'unknown' {
+/** A missing row is not proof of failure; explicit removal and terminal receipts have distinct markers. */
+export function harnessQueueOutcome(id: string, deps: HarnessQueueDeps = {}): 'pending' | 'succeeded' | 'retryable' | 'removed' | 'unknown' {
   const root = deps.root ?? effectiveInstanceRoot();
   const row = listHarnessQueue(deps).find((item) => item.id === id);
   if (!row) {
     const marker = join(root, 'harness', `${id}.outcome`);
     if (!existsSync(marker)) return 'unknown';
     const value = readFileSync(marker, 'utf8');
-    return value === 'succeeded' || value === 'retryable' ? value : 'unknown';
+    return value === 'succeeded' || value === 'retryable' || value === 'removed' ? value : 'unknown';
   }
   return queueRowOutcome(row, root);
 }
 
 const keyMarkerPath = (root: string, key: string) => join(root, 'harness', 'by-key', `${createHash('sha256').update(key).digest('hex')}.id`);
 
-function recordQueueOutcome(root: string, id: string, outcome: 'succeeded' | 'retryable', key?: string): void {
+function recordQueueOutcome(root: string, id: string, outcome: 'succeeded' | 'retryable' | 'removed', key?: string): void {
   const path = join(root, 'harness', `${id}.outcome`);
-  if (!existsSync(path)) writeFileSync(path, outcome, { flag: 'wx', mode: 0o600 });
+  if (outcome === 'removed') writeFileSync(path, outcome, { mode: 0o600 });
+  else if (!existsSync(path)) writeFileSync(path, outcome, { flag: 'wx', mode: 0o600 });
   // The row is about to leave the queue; keep «which id last held this key» so a caller that crashed before
   // recording the id can still find the outcome (LOOP-LIVE1 · seat loop recovery).
   if (key) {
@@ -491,10 +496,8 @@ export async function removeHarnessQueue(id: string, deps: HarnessQueueDeps = {}
       if (state !== 'finished' && state !== 'not-started'
         || (deps.processes ?? readHarnessQueueProcesses)().some((row) => row.launchId === item.launchId)) return false;
     }
-    const outcome = item.status === 'queued' ? 'retryable' : queueRowOutcome(item, root);
-    if (item.idempotencyKey && (outcome === 'retryable' || outcome === 'succeeded')) {
-      recordQueueOutcome(root, id, outcome, item.idempotencyKey);
-    }
+    const outcome = queueRowOutcome(item, root) === 'succeeded' ? 'succeeded' : 'removed';
+    if (item.idempotencyKey) recordQueueOutcome(root, id, outcome, item.idempotencyKey);
     save(path, rows.filter((row) => row.id !== id));
     observe('skipped', { id, seat: item.seat, reason: 'removed' }, deps);
     return true;
@@ -699,6 +702,26 @@ export function readHarnessQueueInventory(probe: ProcessProbe = {}): QueueInvent
     if (prior && prior !== record.seat) { ledgerSeats.delete(pid); ambiguousPids.add(pid); }
     else ledgerSeats.set(pid, record.seat!);
   }
+  // One lsof for every candidate: a per-pid lsof (~0.1–0.3 s each) made a tick on a busy host take 10 s+ (10-08). lsof exits 1
+  // when some pid is gone yet still prints the others; a pid it does not print stays unattributed (charged to all seats).
+  let batchCwds: Map<number, string> | undefined;
+  const readBatchCwds = (): Map<number, string> => {
+    const cwds = new Map<number, string>();
+    const started = Date.now();
+    const lsof = run('lsof', ['-a', '-d', 'cwd', '-Fpn', '-p', candidates.map(({ pid }) => pid).join(',')],
+      { encoding: 'utf8', timeout: 5_000, maxBuffer: 16 * 1024 * 1024 });
+    if (!lsof.error && typeof lsof.stdout === 'string') {
+      let current: number | undefined;
+      for (const line of lsof.stdout.split('\n')) {
+        if (line.startsWith('p')) current = Number(line.slice(1));
+        else if (line.startsWith('n/') && current !== undefined) cwds.set(current, line.slice(1));
+      }
+    }
+    try { debug.log('harness.queue', 'cwd-batch', { pids: candidates.length, read: cwds.size, ms: Date.now() - started,
+      ...(lsof.error ? { error: String(lsof.error).slice(0, 240) } : {}) }); }
+    catch { /* Observation cannot affect dispatch. */ }
+    return cwds;
+  };
   const rows: QueueProcess[] = [];
   // Attribute a run after grouping: the orchestrator may switch working trees while its launcher stays in HQ.
   for (const root of candidates.filter((row) => !byPid.has(row.ppid))) {
@@ -736,9 +759,9 @@ export function readHarnessQueueInventory(probe: ProcessProbe = {}): QueueInvent
         if (probe.cwd) cwd = probe.cwd(pid);
         else if (platform === 'linux') cwd = readlinkSync(`/proc/${pid}/cwd`);
         else {
-          const lsof = run('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { encoding: 'utf8', timeout: 5_000 });
-          if (lsof.error || lsof.status !== 0 || typeof lsof.stdout !== 'string') throw new Error('cwd unavailable');
-          cwd = lsof.stdout.split('\n').find((line) => line.startsWith('n/'))?.slice(1) ?? '';
+          const found = (batchCwds ??= readBatchCwds()).get(pid);
+          if (found === undefined) throw new Error('cwd unavailable');
+          cwd = found;
         }
         if (!cwd.startsWith('/')) continue;
         const found = queueSeatForCwd(cwd, trees);
@@ -816,7 +839,8 @@ async function launch(item: QueueItem, args: string[], root: string, command?: s
       harnessQueueReceiptPath(root, item.launchId!), command ?? join(repo, 'bin', 'elanous.mjs'),
       ...(resolve(root) === prodInstanceRoot() ? [] : [`--test=${root}`]), ...args], {
       cwd: item.launchCwd ?? repo, detached: true, stdio: ['ignore', fd, fd],
-      env: { ...process.env, ELANOUS_STATE_DIR: root, ELANOUS_HARNESS_SEAT: item.seat,
+      env: { ...process.env, ELANOUS_STATE_DIR: root,
+        ELANOUS_STATE_DIR_SOURCE: stateDirSourceForChild(root), ELANOUS_HARNESS_SEAT: item.seat,
         ELANOUS_HARNESS_QUEUE_LAUNCH: item.launchId! },
     });
     const pid = await new Promise<number>((done, reject) => {
@@ -1187,7 +1211,13 @@ export async function tickHarnessQueue(deps: HarnessQueueDeps = {}, requestedId?
 
 async function tickHarnessQueueOnce(deps: HarnessQueueDeps, requestedId: string | undefined, followUp: boolean): Promise<QueueTick> {
   const root = deps.root ?? effectiveInstanceRoot();
-  return locked(root, async (path) => {
+  const caller = 'harness-queue-tick' as const;
+  let advice: LaunchAdvice = { verdict: 'unknown', why: 'pool not measured before queue decision' };
+  const shadow = (pool: QueuePool | undefined): void => {
+    try { advice = (deps.advice ?? adviseLaunch)({ pool, caller }); }
+    catch { advice = { verdict: 'unknown', why: 'launch advice unavailable' }; }
+  };
+  const actual = await locked<QueueTick>(root, async (path): Promise<QueueTick> => {
     // A burst follow-up already ran the author shadow and the idle request in this tick's first pass.
     if (!followUp) try {
       const now = (deps.now ?? (() => new Date()))();
@@ -1196,7 +1226,11 @@ async function tickHarnessQueueOnce(deps: HarnessQueueDeps, requestedId: string
         debug.log('loops.author-depth', 'shadow-skipped-test', {});
       } else {
         const shadow = deps.authorShadow ?? (await import('../loops/orchestrator/author-depth.js')).runAuthorDepthShadow;
+        const started = Date.now();
         await shadow(root, now);
+        // The shadow runs inside the queue lock; its duration is what other ticks wait on.
+        try { debug.log('harness.queue', 'author-shadow', { ms: Date.now() - started }); }
+        catch { /* Observation cannot affect dispatch. */ }
       }
     } catch (error) {
       try { debug.log('loops.author-depth', 'shadow-failed', { reason: String(error) }); }
@@ -1463,6 +1497,7 @@ async function tickHarnessQueueOnce(deps: HarnessQueueDeps, requestedId: string
         if (pool && (![pool.running, pool.pending, pool.reserved, pool.limit].every((n) => Number.isSafeInteger(n) && n >= 0) || pool.limit < 1)) {
           poolReason = 'pod lease status incomplete';
         }
+        shadow(poolReason ? undefined : pool);
         if (pool && !poolReason) {
           const queueLaunching = current.filter((row) => row.status === 'launching' || row.status === 'launched').length;
           // CHILD-UNIV-HOLD: each unreadable child universe is charged one pool slot (conservative), never a seat slot.
@@ -1545,4 +1580,13 @@ async function tickHarnessQueueOnce(deps: HarnessQueueDeps, requestedId: string
     }
     return waiting();
   });
+  // An empty queue tick has nothing to advise on; logging it would flood the advice-unknown sample.
+  if (actual.outcome === 'skipped' && !actual.item) return actual;
+  try {
+    const { kind } = compareLaunchAdvice(advice, actual.outcome);
+    debug.log('resource.advice', 'launch-advice', {
+      caller, verdict: advice.verdict, why: advice.why, actual: actual.outcome, kind, itemId: actual.item?.id ?? null,
+    });
+  } catch { /* Shadow observation cannot affect the queue result. */ }
+  return actual;
 }

package/src/harness/harness-seams.ts

@@ -34,7 +34,8 @@ import { getHarnessSpace, resolveRunIdentity } from './harness-space.js';
 import type { AutonomyRiskHit, HarnessGroundingRef } from '../self-implement/context-capsule.js';
 import { AUTO_REVIEW_LABEL, resolveAutoReviewLabels } from '../self-implement/context-capsule.js';
 import { verbatimOriginalAsk } from '../self-implement/goal-author.js';
-import { isSupervisorDecisionSection, splitGoalSections, supervisorGoalDigest } from '../self-implement/goal-digest.js';
+import { extractHarnessReviewAcceptance } from '../self-implement/goal-digest.js';
+export { extractHarnessReviewAcceptance } from '../self-implement/goal-digest.js';
 
 const AUTOREVIEW_SENTENCE_LIMIT = 240;
 const SECURITY_RISK_REASON = '보안/인증 정보';
@@ -222,25 +223,6 @@ async function buildPrBody(
   } catch { return heuristic(); }
 }
 
-/** 골 문서에서 `판정 신호` 절만 뽑아 리뷰 acceptance 로 쓴다. 계보 = self-implement seams. */
-export function extractHarnessReviewAcceptance(goalDocument: string | undefined): { goal: string | undefined; acceptance: string | undefined } {
-  let goal: string | undefined;
-  try {
-    goal = goalDocument?.trim() || undefined;
-  } catch {
-    return { goal: undefined, acceptance: undefined };
-  }
-  if (!goal) return { goal: undefined, acceptance: undefined };
-  try {
-    const acceptance = splitGoalSections(supervisorGoalDigest(goal, 3000).text)
-      .find((section) => isSupervisorDecisionSection(section.title) && section.title.includes('판정 신호'))
-      ?.body.trim() || undefined;
-    return { goal, acceptance };
-  } catch {
-    return { goal, acceptance: undefined };
-  }
-}
-
 function reviewAcceptanceObservation(goal: string | undefined, acceptance: string | undefined): { goalLoaded: boolean; acceptanceChars: number } {
   return { goalLoaded: Boolean(goal), acceptanceChars: acceptance?.length ?? 0 };
 }

package/src/harness/harness-substrate-default.ts

@@ -1,5 +1,76 @@
 import { spawnSync } from 'node:child_process';
-import type { UserConfig } from '../user-config.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { effectiveInstanceRoot, prodInstanceRoot, treeDerivedRootFor } from '../instance/resolve.js';
+import { getElanousConfigDirOverride } from '../elanous-config-dir.js';
+import { buildUserConfig, getUserConfig, type UserConfig } from '../user-config.js';
+import { resolveCodexQuotaPolicy } from '../oauth/codex-quota-policy.js';
+
+/** Key-order-insensitive JSON so equal per-account caps written in another order do not warn. */
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, (_key, v: unknown) => v && typeof v === 'object' && !Array.isArray(v)
+    ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)))
+    : v);
+}
+
+function readOperationalLaunchConfig(path: string): UserConfig | null {
+  let text: string;
+  try { text = readFileSync(path, 'utf8'); }
+  catch (err) {
+    // Only a missing file (fresh install, CI, isolated fixtures) means «no operational policy»; permission or I/O errors refuse.
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error(`launch policy: 운영 config 를 읽을 수 없다 — ${path}`);
+  }
+  let raw: unknown;
+  try { raw = JSON.parse(text); }
+  catch { throw new Error(`launch policy: 운영 config 를 읽을 수 없다 — ${path}`); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`launch policy: 운영 config 형식이 잘못됐다 — ${path}`);
+  return buildUserConfig(path);
+}
+
+/** Launch policy belongs to the host, not to the materialized config in a derived worktree.
+ * Explicit test/config universes remain isolated; this only applies to tree-derived launches. */
+export function harnessLaunchPolicyConfig(options: {
+  derived?: UserConfig;
+  operationalRoot?: string;
+  derivedRoot?: string;
+  warn?: (line: string) => void;
+  /** Reads the operational config at `path`; injected by tests so they never touch the host's real config. */
+  readOperational?: (path: string) => UserConfig | null;
+} = {}): UserConfig {
+  const derived = options.derived ?? getUserConfig();
+  const operationalRoot = options.operationalRoot ?? prodInstanceRoot();
+  const derivedRoot = options.derivedRoot ?? effectiveInstanceRoot();
+  const isDerived = options.derivedRoot !== undefined
+    ? derivedRoot !== operationalRoot
+    : derivedRoot !== operationalRoot && !getElanousConfigDirOverride() && (
+      process.env.ELANOUS_STATE_DIR_SOURCE === 'derived'
+      || derivedRoot === treeDerivedRootFor(process.cwd())
+    );
+  if (!isDerived) return derived;
+  const path = join(operationalRoot, 'config.json');
+  const operational = (options.readOperational ?? readOperationalLaunchConfig)(path);
+  if (!operational) {
+    (options.warn ?? console.error)(`⚠️ launch policy: 운영 config 가 없다 (${path}) — 이 우주의 정책으로 발사`);
+    return derived;
+  }
+  const policy = (config: UserConfig) => ({
+    quota: resolveCodexQuotaPolicy(config.llm).policy,
+    accountLimits: config.llm?.codexAccountRotationThresholdPercentByAccount,
+    fallbackChain: config.llm?.fallbackChain,
+    childLlm: config.tools?.selfImplement?.childLlm,
+    budgetGate: config.harness?.budgetGate,
+    podPool: config.harness?.podPool ?? config.pod?.pool,
+    grokApiKeyOptIn: config.harness?.pod?.grokApiKeyOptIn === true,
+  });
+  const actual = policy(derived);
+  const expected = policy(operational);
+  if (derived.llm?.codexQuotaPolicy === undefined && derived.llm?.codexCreditsAllowed === undefined
+    || stableJson(actual) !== stableJson(expected)) {
+    (options.warn ?? console.error)('⚠️ launch policy: 파생 시험 우주 정책이 없거나 운영과 다르다 — 운영 정책으로 발사');
+  }
+  return operational;
+}
 
 export type HarnessSubstrate = 'local' | 'pod';
 export interface ResolvedHarnessSubstrate {

package/src/harness/launch-advice.ts

@@ -0,0 +1,23 @@
+import type { QueuePool, QueueTick } from './harness-queue.js';
+
+export type LaunchAdvice = { verdict: 'launch-now' | 'wait' | 'unknown'; why: string; retryAfterHint?: string };
+export type LaunchAdviceInput = { pool: QueuePool | null | undefined; caller: 'harness-queue-tick' | 'hand-task' | 'release-run' };
+
+/** A pool-only suggestion; queue, seat, freeze and finish gates remain the dispatcher's decisions. */
+export function adviseLaunch(input: LaunchAdviceInput): LaunchAdvice {
+  const pool = input.pool;
+  if (!pool || ![pool.running, pool.pending, pool.reserved, pool.limit].every(n => Number.isSafeInteger(n) && n >= 0)
+    || pool.limit < 1) return { verdict: 'unknown', why: 'pool unavailable or incomplete' };
+  const used = pool.running + pool.pending + pool.reserved;
+  if (used >= pool.limit) return { verdict: 'wait', why: `pool ${used}/${pool.limit} occupied`, retryAfterHint: 'when a pool slot is released' };
+  return { verdict: 'launch-now', why: `pool ${used}/${pool.limit} occupied` };
+}
+
+export function compareLaunchAdvice(advice: LaunchAdvice, actualOutcome: QueueTick['outcome']): {
+  agree: boolean; kind: 'advice-launch-actual-wait' | 'advice-wait-actual-launch' | 'advice-unknown' | 'agree';
+} {
+  if (advice.verdict === 'unknown' || actualOutcome === 'skipped') return { agree: false, kind: 'advice-unknown' };
+  if (advice.verdict === 'launch-now' && actualOutcome === 'waiting') return { agree: false, kind: 'advice-launch-actual-wait' };
+  if (advice.verdict === 'wait' && actualOutcome === 'launched') return { agree: false, kind: 'advice-wait-actual-launch' };
+  return { agree: true, kind: 'agree' };
+}

package/src/harness/nested-elanous-policy.ts

@@ -2,7 +2,7 @@
 //
 // Codex children drop parent env under shell_environment_policy inherit=core, so a
 // depth marker that only lives in the environment never arrives. Depth is therefore
-// carried on the codex argv (`-c shell_environment_policy.set.ELANOUS_NESTED_DEPTH=<n>`).
+// carried on the codex argv (`-c shell_environment_policy.set.ELANOUS_NESTED_DEPTH="<n>"` — TOML 문자열).
 //
 // Unset ELANOUS_NESTED_DEPTH is depth 0 (the outer launcher). A missing marker is
 // not "depth unknown" and does not refuse an ordinary mission spawn.
@@ -50,7 +50,9 @@ export function backendCarriesNestedDepth(backendName: string): boolean {
 export function nestedDepthCodexArgs(backendName: string, childDepth: number): string[] {
   if (backendName !== 'codex') return [];
   if (!Number.isInteger(childDepth) || childDepth < 0) return [];
-  return ['-c', `${CODEX_NESTED_DEPTH_CONFIG_KEY}=${childDepth}`];
+  // 🩸 CODEX-NESTED-DEPTH-QUOTE(2026-10-09): `-c` 값은 TOML 이고 shell_environment_policy.set 은 «문자열» 맵이다.
+  //   맨 정수(`=1`)는 codex 0.159.3 에서 «failed to load bootstrap configuration» 으로 자식을 바로 죽인다 → 따옴표로 문자열.
+  return ['-c', `${CODEX_NESTED_DEPTH_CONFIG_KEY}="${childDepth}"`];
 }
 
 /**

package/src/hq/fence-wrapper.ts

@@ -69,6 +69,13 @@ if [ $# -lt 1 ] || [ -z "$1" ]; then
 fi
 ROLE=$1
 shift
+# FENCE-LIGHT: only when this host's heartbeat left a lease-cache file and the installed package ships the light fence.
+# No cache file = exactly the CLI path below. The sourced script always exits; returning is a fail-closed error.
+if [ -f "$CONFIG_DIR/hq/lease-cache" ] && [ -f scripts/hq/hq-fence-wrapper.sh ]; then
+  . scripts/hq/hq-fence-wrapper.sh
+  log_line "light fence returned without a decision (role=$ROLE)"
+  exit 1
+fi
 "$BUN" "$ENTRY" --config-dir "$CONFIG_DIR" hq fence --role "$ROLE" -- /bin/sh -c "$*"
 rc=$?
 if [ "$rc" -ne 0 ]; then alert "hq-fence: fence failed (rc=$rc, role=$ROLE)"; fi

package/src/hq/hq.ts

@@ -14,8 +14,8 @@ import { fenceOutcomeDir, recordFenceOutcome } from './fence-outcomes.js';
 import { promoteHq, proposeHqPromotion, writeOpSeatRequest } from './promote.js';
 import type { HqOpRequestWriter, PromoteResult } from './promote.js';
 import {
-  DEFAULT_TTL_SECONDS, decideAcquire, decideArbiterCheck, decideFence, decideRelease, decideRenew, defaultSshRunner,
-  fileLeaseStore, leaseExpired, parseLease, probeReachable, recordView, serializeLease, sshLeaseStore, sshReachable, localShellRunner,
+  DEFAULT_TTL_SECONDS, LOCAL_LEASE_CACHE_SECONDS, decideAcquire, decideArbiterCheck, decideFence, decideRelease, decideRenew, defaultSshRunner,
+  fileLeaseStore, leaseExpired, parseLease, probeReachable, recordView, serializeLease, serializeLocalLeaseCache, sshLeaseStore, sshReachable, localShellRunner,
   type HostProbe, type LeaseRecord, type LeaseStore, type LocalHqState, type SshRunner,
 } from './lease.js';
 
@@ -163,6 +163,30 @@ function writeLocal(path: string, state: LocalHqState): void {
   renameSync(tmp, path);
 }
 
+/** FENCE-LIGHT host-local hint (`<config>/hq/lease-cache`), not authority: only a successful holder renewal writes it. */
+const leaseCachePath = (r: Resolved): string => join(dirname(r.localPath), 'lease-cache');
+function dropHeartbeatCache(r: Resolved): void {
+  try { rmSync(leaseCachePath(r), { force: true }); }
+  catch (error) { observe(r, 'hq.lease', 'cache-invalidate-failed', { error: String(error).slice(0, 200) }); }
+}
+function writeHeartbeatCache(r: Resolved, record: LeaseRecord): void {
+  const path = leaseCachePath(r);
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const confirmedAt = r.now();
+    const expiresAt = Math.min(confirmedAt + LOCAL_LEASE_CACHE_SECONDS, record.renewedAt + record.ttlSeconds);
+    if (expiresAt <= confirmedAt) return;
+    const tempDir = mkdtempSync(`${path}.`);
+    try {
+      const tmp = join(tempDir, 'cache');
+      writeFileSync(tmp, serializeLocalLeaseCache({ holder: record.holder, generation: record.generation, expiresAt, host: r.me, machine: hostname().replace(/\.local$/, ''), confirmedAt }), { mode: 0o600 });
+      renameSync(tmp, path);
+    } finally { rmSync(tempDir, { recursive: true, force: true }); }
+  } catch (error) {
+    observe(r, 'hq.lease', 'cache-write-failed', { error: String(error).slice(0, 200) });
+  }
+}
+
 /** Highest lease generation this host ever observed (null = never). */
 /** The seen-generation marker this host keeps (hq.seenGenerationFile · default ~/.elanous-hq/seen-generation). */
 export function hqSeenGenerationPath(config: Pick<HqConfig, 'seenGenerationFile'>): string {
@@ -241,6 +265,7 @@ export function hqLease(action: LeaseAction, deps: HqDeps = {}, opts: { host?: s
   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, expected));
   noteSeen(r, result.record);
+  if (result.ok) dropHeartbeatCache(r);
   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`,
@@ -255,6 +280,8 @@ export function hqLease(action: LeaseAction, deps: HqDeps = {}, opts: { host?: s
 export function hqHeartbeat(deps: HqDeps = {}) {
   const r = resolve(deps);
   const local = readLocal(r.localPath);
+  // Never extend a prior positive hint through an unreachable/refused heartbeat.
+  dropHeartbeatCache(r);
   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;
@@ -273,6 +300,7 @@ export function hqHeartbeat(deps: HqDeps = {}) {
     if (renewed.ok) {
       noteSeen(r, renewed.record);
       writeLocal(r.localPath, { holder: r.me, generation: renewed.record.generation, confirmedAt: r.now(), ttlSeconds: renewed.record.ttlSeconds });
+      if (record.renewedAt !== 0 && !leaseExpired(renewed.record, r.now())) writeHeartbeatCache(r, renewed.record);
       observe(r, 'hq.lease', 'renewed', { generation: renewed.record.generation });
       return { outcome: 'renewed' as const, generation: renewed.record.generation };
     }
@@ -282,6 +310,7 @@ export function hqHeartbeat(deps: HqDeps = {}) {
   // Not the holder: report the view, keep the granted generation, stay standby.
   const seen = probeReachable(record.holder, r.probe);
   const reachable = seen.reachable;
+  // FENCE-LIGHT: a standby never writes the cache (the shell fence only fast-paths a fresh «this host holds» line).
   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 });
@@ -365,6 +394,8 @@ export function hqFenceDecision(role: HqFenceRole, deps: HqDeps = {}) {
     failOpen: role !== 'ledger-cli' && r.failOpen.has(role),
     ...(seenGeneration !== null ? { seenGeneration } : {}),
   });
+  // FENCE-LIGHT: any CLI «do not run» on this host retires a lingering fast-path hint at once.
+  if (!decided.run) dropHeartbeatCache(r);
   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;

package/src/hq/lease.ts

@@ -36,6 +36,19 @@ export function parseLease(raw: string | null): LeaseRecord | null {
 export const serializeLease = (record: LeaseRecord): string => `${JSON.stringify(record)}\n`;
 export const leaseExpired = (record: LeaseRecord, now: number): boolean => record.renewedAt + record.ttlSeconds < now;
 
+/** Host-local, short-lived shell fence snapshot; never the arbiter's CAS lease ledger. */
+export interface LocalLeaseCache { holder: string; generation: number; expiresAt: number; host: string; machine: string; confirmedAt: number }
+export const LOCAL_LEASE_CACHE_SECONDS = 660; // heartbeat cadence 600s + 60s scheduling slack; still below the 1500s lease TTL
+/** A single whitespace-delimited line so /bin/sh can read it without bun or JSON tools. */
+export function serializeLocalLeaseCache(cache: LocalLeaseCache): string {
+  if (![cache.holder, cache.host, cache.machine].every(value => /^[A-Za-z0-9_.-]+$/.test(value))
+    || !Number.isSafeInteger(cache.generation) || cache.generation < 1
+    || !Number.isSafeInteger(cache.expiresAt) || cache.expiresAt < 1
+    || !Number.isSafeInteger(cache.confirmedAt) || cache.confirmedAt < 1
+    || cache.expiresAt <= cache.confirmedAt || cache.expiresAt - cache.confirmedAt > LOCAL_LEASE_CACHE_SECONDS) throw new Error('invalid local lease cache');
+  return `${cache.holder} ${cache.generation} ${cache.expiresAt} ${cache.host} ${cache.machine} ${cache.confirmedAt}\n`;
+}
+
 /** acquire: only when there is no lease or it has expired; a new holder gets the next generation. */
 export function decideAcquire(record: LeaseRecord | null, me: string, now: number, ttlSeconds = DEFAULT_TTL_SECONDS):
   { ok: true; next: LeaseRecord } | { ok: false; reason: string } {