elanous 0.2.28 → 0.2.31

package/src/skills/tools/persistent-grounding.ts

@@ -1,8 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
-import { runGoalLoop, type CoreTurnContext, type CoreTurnDispatchTool, type GoalLoopOptions } from '../../core-turn/index.js';
+import { runGoalLoop, type CoreTurnContext, type CoreTurnDispatchTool, type GoalLoopOptions, type GoalLoopResult } from '../../core-turn/index.js';
 import { debug } from '../../debug/log.js';
+import { selectPlanningLlm } from '../../prompt-enhance/enhance.js';
 import type { LLMMessage, LLMToolSpec } from '../../llm.js';
 import { buildAstGrepTool, dispatchAstGrep, hasAstGrep } from './ast-grep.js';
 import { buildGlobTool, dispatchGlob } from './glob.js';
@@ -22,6 +23,8 @@ export interface PersistentGroundingDeps {
   relativePath?: (from: string, to: string) => string;
   /** Terms generated by an upstream grounding consumer; the loop must prioritize them for code discovery. */
   terms?: string[];
+  /** Authoring model selection seam; production follows the planning role, including the Pod relay. */
+  planningLlm?: () => Pick<ReturnType<typeof selectPlanningLlm>, 'model' | 'modelSource' | 'fallbackReason' | 'requestedModel' | 'requestedSource'>;
 }
 
 export interface PersistentGroundingResult {
@@ -215,7 +218,7 @@ function groundingMessages(goal: string, terms: readonly string[]): LLMMessage[]
 function unreadEvidencePaths(evidence: string, readFiles: ReadonlySet<string>): string[] {
   return Array.from(new Set(evidence.split(/\r?\n/)
     .flatMap(repositoryRelativeCodePaths)
-    .filter((path) => isCodeRootPath(path) && !readFiles.has(path)))).slice(0, 8);
+    .filter((path) => isCodeRootPath(path) && !readFiles.has(path))));
 }
 
 function rejectedEvidenceFeedback(evidence: string, readFiles: ReadonlySet<string>): LLMMessage {
@@ -224,10 +227,11 @@ function rejectedEvidenceFeedback(evidence: string, readFiles: ReadonlySet<strin
   return {
     role: 'user',
     content: [
-      'Your completion evidence was rejected because it cited a repository path that Read did not verify.',
+      'Your completion evidence was rejected: Glob, Grep, and ListDir prove discovery, but they do not verify a file for completion evidence.',
       `Unverified paths: ${unread.length ? unread.join(', ') : '(none in allowed code roots)'}`,
       `Paths actually Read: ${read.length ? read.join(', ') : '(none)'}`,
-      'Try once more. Read each relevant unverified path before citing it, or remove it from the evidence. Cite only repository-relative code paths that this grounding run actually Read, each with a concrete reason. If no path is relevant, do not invent evidence.',
+      ...(unread.length ? [`Next tool calls: ${unread.map((path) => `Read({"file_path":"${path}"})`).join(' ; ')}`] : []),
+      'Before calling update_goal(status="complete"), Read at least one relevant path above and wait for its successful result. Cite only paths that this grounding run actually Read, each with a concrete reason. If a Read fails, omit that path. Finish by calling update_goal; ending with prose alone does not complete this task.',
     ].join('\n'),
   };
 }
@@ -248,7 +252,10 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
   if (!astGrepAvailable) debug.log('grounding.persistent', 'tool-unavailable', { sessionId, tool: 'AstGrep' }, { level: 'warn' });
   const toolCalls: Record<string, number> = {};
   let completedIterations: number | undefined;
+  let resolvedProvider: string | undefined;
+  let resolvedModel: string | undefined;
   try {
+    const planningLlm = (deps.planningLlm ?? selectPlanningLlm)();
     const loop = deps.runGoalLoop ?? runGoalLoop;
     let completionEvidence = '';
     const readFiles = new Set<string>();
@@ -259,7 +266,12 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
       dispatchTool: guardedDispatchTool(cwd, deps.dispatchTool, readFiles, deps.relativePath),
       signal: new AbortController().signal,
       maxToolTurns: 4,
+      ...(planningLlm.model ? { modelOverride: planningLlm.model } : {}),
       callbacks: {
+        onResolvedProvider: (provider, model) => {
+          resolvedProvider = provider;
+          resolvedModel = model;
+        },
         onToolCall: (call) => {
           toolCalls[call.name] = (toolCalls[call.name] ?? 0) + 1;
           if (call.name === 'update_goal' && call.args.status === 'complete' && typeof call.args.evidence === 'string') completionEvidence = call.args.evidence;
@@ -282,6 +294,8 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
     let verified = firstVerified;
     let feedbackRetry = false;
     let retryIterations = 0;
+    let retryStopReason: GoalLoopResult['stopReason'] | undefined;
+    let retryOutcome: 'not-needed' | 'verified' | 'incomplete' | 'evidence-rejected' | 'failed' | 'aborted' | 'auth-rejected' = 'not-needed';
     if (firstVerified.rejection.notRead > 0) {
       feedbackRetry = true;
       const feedback = rejectedEvidenceFeedback(completionEvidence, readFiles);
@@ -290,6 +304,11 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
         const retry = await loop({ ...ctx, sessionId: `${sessionId}-evidence-retry`, messages: [...ctx.messages, feedback] },
           { ...options, maxIterations: 2 });
         retryIterations = retry.iterations;
+        retryStopReason = retry.stopReason;
+        retryOutcome = retry.goalComplete && retry.stopReason === 'goal_complete' ? 'evidence-rejected'
+          : retry.stopReason === 'auth_rejected' ? 'auth-rejected'
+            : retry.stopReason === 'aborted' || retry.stopReason === 'soft_stop' ? 'aborted'
+              : retry.stopReason === 'error' ? 'failed' : 'incomplete';
         const retryVerified = retry.goalComplete && retry.stopReason === 'goal_complete'
           ? verifiedEvidenceFromCompletion(completionEvidence, readFiles)
           : null;
@@ -300,8 +319,10 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
             rejection: retryVerified.rejection,
           };
           result = retry;
+          if (retryVerified.evidence.length > 0) retryOutcome = 'verified';
         }
       } catch (error) {
+        retryOutcome = 'failed';
         try {
           debug.log('grounding.persistent', 'evidence-retry-failed', { sessionId,
             reason: error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200) }, { level: 'warn' });
@@ -311,22 +332,41 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
       }
     }
     const totalIterations = first.iterations + retryIterations;
+    let stopReason: string = result.stopReason;
+    // A verified line remains useful evidence, but it cannot turn an unsuccessful
+    // feedback retry into a successful completion of the whole grounding task.
+    switch (retryOutcome) {
+      case 'incomplete': stopReason = 'evidence_retry_incomplete'; break;
+      case 'evidence-rejected': stopReason = 'evidence_retry_rejected'; break;
+      case 'failed': stopReason = retryStopReason === 'error' ? 'error' : 'evidence_retry_failed'; break;
+      case 'auth-rejected': stopReason = 'auth_rejected'; break;
+      case 'aborted': stopReason = retryStopReason === 'soft_stop' ? 'soft_stop' : 'aborted'; break;
+    }
     try {
       debug.log('grounding.persistent', 'finished', {
         sessionId,
         maxIterations,
         durationMs: durationMs(),
       iterations: totalIterations,
-      stopReason: result.stopReason,
+      stopReason,
       // ⛔ 「끝났다」가 두 뜻이다 — ⓐ 스스로 목표를 끝냈다 ⓑ 턴이 «그냥» 끝났다.
       //   📏 2026-08-11 72차 전수(400건): 후보 0인 finished 가 5건이고 ***다섯 다 end_turn*** 이었다.
       //   그 둘을 한 이름에 두면 「접지는 성공인데 코드가 0」이라는 «없는 수수께끼»가 생긴다.
-      outcome: result.goalComplete && result.stopReason === 'goal_complete' ? 'goal-complete' : 'stopped-without-goal',
+      outcome: result.goalComplete && stopReason === 'goal_complete' ? 'goal-complete' : 'stopped-without-goal',
       candidates: verified.files,
       candidateCount: verified.files.length,
       evidenceCount: verified.evidence.length,
       evidenceRejection: verified.rejection,
       feedbackRetry,
+        retryOutcome,
+        retryStopReason: retryStopReason ?? null,
+        provider: resolvedProvider ?? null,
+        model: resolvedModel ?? null,
+        planningModel: planningLlm.model ?? null,
+        planningModelSource: planningLlm.modelSource,
+        planningFallbackReason: planningLlm.fallbackReason ?? null,
+        planningRequestedModel: planningLlm.requestedModel ?? null,
+        planningRequestedSource: planningLlm.requestedSource ?? null,
       ...(feedbackRetry ? { firstEvidenceRejection: firstVerified.rejection } : {}),
         toolCalls,
       });
@@ -337,7 +377,7 @@ export async function groundPersistently(goal: string, cwd: string, deps: Persis
       files: verified.files,
       evidence: verified.evidence,
       iterations: totalIterations,
-      stopReason: result.stopReason,
+      stopReason,
     };
   } catch (error) {
     try {

package/src/skills/tools/shell.ts

@@ -178,6 +178,116 @@ function rejectedCdResult(): RunShellDispatchResult {
   };
 }
 
+// ── ops-ledger CLI steering (RunShell-0 convergence) ────────────────────────
+// The durable mailbox and release-checklist ledgers have in-process native
+// tools (MsgList/MsgPost/MsgAck · ChecklistList/Add/Set/Move —
+// src/skills/tools/ops-ledger.ts, registered for the same skill+tui hosts as
+// RunShell). Shelling out to the `elanous` CLI for exactly those covered ops
+// pays 1.3–2s of process startup for work the host process does in <300ms,
+// and the CLI's human-oriented stdout amplifies TUI screen defects — so the
+// call is steered to the native tool with a structured refusal naming it.
+//
+// Deliberately NOT a blanket elanous-CLI ban: only the seven covered ops are
+// refused, and argv that explicitly scopes another universe (--test /
+// --config-dir / --state-dir) is allowed through because the native tools
+// always serve THIS process's instance.
+const LEDGER_CLI_BIN = /(?:^|[/\\])(?:elanous|elanous\.mjs|elanous\.cjs|eln)$/;
+const LEDGER_ENV_BIN = /(?:^|[/\\])env$/;
+export const LEDGER_CLI_NATIVE_TOOL: Readonly<Record<string, string>> = {
+  'msg list': 'MsgList',
+  'msg post': 'MsgPost',
+  'msg ack': 'MsgAck',
+  'release checklist list': 'ChecklistList',
+  'release checklist add': 'ChecklistAdd',
+  'release checklist set': 'ChecklistSet',
+  'release checklist move': 'ChecklistMove',
+};
+
+/** The covered ops-ledger CLI op in this argv and its exposed native tool,
+ *  or null when the command should run normally. */
+export function matchLedgerCli(
+  command: readonly string[], availableToolNames: readonly string[] = [],
+): { covered: string; tool: string } | null {
+  let binIndex = 0;
+  // RunShell receives argv, so recognize only argv-preserving env wrappers.
+  // An alternate instance must still run its own CLI, never this process's native tool;
+  // so must a changed or unset ELANOUS_TRACK — the native tools record THIS process's
+  // seat as the actor and route ChecklistMove permissions by it.
+  if (LEDGER_ENV_BIN.test(command[0] ?? '')) {
+    binIndex = 1;
+    while (binIndex < command.length) {
+      const arg = command[binIndex]!;
+      if (arg === '-i' || arg === '--ignore-environment') return null;
+      if (arg === '--') { binIndex += 1; continue; }
+      if (arg === '-u' || arg === '--unset') {
+        const name = command[binIndex + 1];
+        if (!name || /^ELANOUS_(?:STATE_DIR|CONFIG_DIR|TEST_STATE_DIR|TRACK)$/.test(name)) return null;
+        binIndex += 2;
+        continue;
+      }
+      if (arg.startsWith('--unset=')) {
+        if (/^--unset=ELANOUS_(?:STATE_DIR|CONFIG_DIR|TEST_STATE_DIR|TRACK)$/.test(arg)) return null;
+        binIndex += 1;
+        continue;
+      }
+      if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(arg)) {
+        if (/^ELANOUS_(?:STATE_DIR|CONFIG_DIR|TEST_STATE_DIR|TRACK)=/.test(arg)) return null;
+        binIndex += 1;
+        continue;
+      }
+      break;
+    }
+  }
+  if (command[binIndex] === 'bun' || command[binIndex] === 'bunx' || command[binIndex] === 'node' || command[binIndex] === 'npx') {
+    binIndex += 1;
+    if (command[binIndex] === '--bun') binIndex += 1;
+  }
+  if (!LEDGER_CLI_BIN.test(command[binIndex] ?? '')) return null;
+  const args = command.slice(binIndex + 1);
+  if (args.some((arg) => arg === '--test' || arg === '--config-dir' || arg.startsWith('--config-dir=')
+    || arg === '--state-dir' || arg.startsWith('--state-dir=')
+    || arg === '--test-state-dir' || arg.startsWith('--test-state-dir='))) return null;
+  let i = 0;
+  while (i < args.length && args[i]!.startsWith('-')) i += 1;
+  const sub = args[i];
+  const covered = sub === 'msg'
+    ? `msg ${args[i + 1]}`
+    : sub === 'release' && args[i + 1] === 'checklist'
+      ? `release checklist ${args[i + 2]}`
+      : '';
+  const tool = covered ? LEDGER_CLI_NATIVE_TOOL[covered] : undefined;
+  if (!tool || !availableToolNames.includes(tool)) return null;
+  return { covered, tool };
+}
+
+function ledgerCliSteerOutput(shellTool: string, covered: string, tool: string): string {
+  const metadata = covered === 'release checklist set' ? ' — for owner/priority/disposition/kind/… use ChecklistEdit, one field per call' : '';
+  return `${shellTool} rejected \`${covered}\`: call the native ${tool} tool instead (same ledger, same permissions and audit, no CLI startup)${metadata}.`;
+}
+
+/** Structured refusal steering a covered ops-ledger CLI argv to its native
+ *  tool, or null when the command should run normally. Exported so tests
+ *  can exercise the matcher without spawning anything. */
+export function rejectedLedgerCliResult(
+  command: readonly string[], availableToolNames: readonly string[] = [],
+): RunShellDispatchResult | null {
+  const match = matchLedgerCli(command, availableToolNames);
+  if (!match) return null;
+  const { covered, tool } = match;
+  return {
+    output: ledgerCliSteerOutput('RunShell', covered, tool),
+    exitCode: null,
+    outcome: 'spawn-error',
+    elapsedMs: 0,
+    stdout: '',
+    stderr: `use the native ${tool} tool instead of the ${covered} CLI`,
+    truncated: false,
+    approvalKey: 'rejected:ops-ledger-cli',
+    sandboxed: false,
+    sandboxTool: 'none',
+  };
+}
+
 function logShellDispatch(event: string, data: Record<string, unknown>): void {
   debug.log('shell.dispatch', event, data);
 }
@@ -240,7 +350,7 @@ export function enqueueShellCompletionNotice(
 
 export async function dispatchRunShell(
   rawArgs: Record<string, unknown>,
-  opts: { signal?: AbortSignal } = {},
+  opts: { signal?: AbortSignal; availableToolNames?: readonly string[] } = {},
 ): Promise<RunShellDispatchResult> {
   const command = asCommand(rawArgs.command);
   const cwd = typeof rawArgs.cwd === 'string' ? rawArgs.cwd : undefined;
@@ -255,6 +365,12 @@ export async function dispatchRunShell(
     logShellDispatch('cd.rejected', { reason: 'argv-state-does-not-persist' });
     return rejectedCdResult();
   }
+  const ledgerCliMatch = matchLedgerCli(command, opts.availableToolNames);
+  if (ledgerCliMatch) {
+    // covered op ⊕ tool only — the argv can carry a message body.
+    logShellDispatch('ledger-cli.steered', { shell: 'run-shell', ...ledgerCliMatch });
+    return rejectedLedgerCliResult(command, opts.availableToolNames)!;
+  }
   const effectiveCwd = cwd ?? getSessionCwd();
   const cwdSource = cwd === undefined ? 'session' : 'argument';
   const boundaryReject = harnessCommandWriteReject(command, effectiveCwd, 'run-shell');

package/src/status/bar.ts

@@ -213,6 +213,9 @@ export interface GitSegmentState {
   ahead?: number;
   /** Commits behind upstream. Non-zero → peach tone with "-N". */
   behind?: number;
+  /** Optional axis label after the glyph (e.g. `트리`) — set when a
+   *  running-build pill sits next to it so the two SHAs are not confused. */
+  label?: string;
 }
 
 /** Git state — flat colored text. No pill background.
@@ -241,7 +244,7 @@ export function gitSegment(
   const head = state.branch
     ? truncateGitHead(state.branch, 20)
     : `HEAD@${(state.detachedSha ?? '').slice(0, 7)}`;
-  const parts: string[] = [`⌥ ${head}`];
+  const parts: string[] = [state.label ? `⌥ ${state.label} ${head}` : `⌥ ${head}`];
   const dirty = Math.max(0, state.dirtyTotal ?? 0);
   if (dirty > 0) parts.push(`*${dirty}`);
   if ((state.ahead ?? 0) > 0) parts.push(`+${state.ahead}`);
@@ -260,6 +263,33 @@ export function gitSegment(
     : strongText(parts.join(' '), tone, opts);
 }
 
+/** The code this TUI process loaded at boot (not the session tree HEAD). */
+export interface RunningBuildState {
+  /** Boot commit (full or short); '' = unknown (rendered as `?`). */
+  sha: string;
+  /** True when the installed/checkout code moved after boot — a relaunch runs the new build.
+   *  null = could not compare (not the same as «not stale»). */
+  stale: boolean | null;
+  /** The commit a relaunch would run, when known. */
+  currentSha?: string;
+}
+
+/** Running-build pill.
+ *
+ *     ▶ 실행 5c0f98f                         — boot build matches current code (overlay)
+ *     ▶ 실행 5c0f98f ⟳ 재기동 필요 → 1a2b3c4  — code moved after boot (yellow, bold)
+ *     ▶ 실행 5c0f98f ?                        — could not compare (overlay)
+ *     ▶ 실행 ?                                — boot build unknown (overlay) */
+export function runningBuildSegment(state: RunningBuildState | null | undefined, opts: StatusBarRenderOptions = {}): string {
+  if (!state) return '';
+  if (!state.sha) return text('▶ 실행 ?', 'overlay', opts);
+  const label = `▶ 실행 ${state.sha.slice(0, 7)}`;
+  if (state.stale === null) return text(`${label} ?`, 'overlay', opts);
+  if (!state.stale) return text(label, 'overlay', opts);
+  const target = state.currentSha ? ` → ${state.currentSha.slice(0, 7)}` : '';
+  return strongText(`${label} ⟳ 재기동 필요${target}`, 'yellow', opts);
+}
+
 /** Truncate a model id at the first parameter-size marker (e.g.
  *  `qwen3.6-35b-a3b-ud-mlx` → `qwen3.6-35b`). The marker pattern
  *  matches one or more digits followed by `b`/`B` (e.g. `7b`, `35b`,
@@ -289,7 +319,7 @@ function truncateAtParamSize(model: string): string {
  *   - `local:qwen3.6-35b-a3b-ud-mlx` → `local:qwen3.6-35b`
  *   - `node-b:qwen2.5-72b-instruct`    → `node-b:qwen2.5-72b`
  *   - `claude-opus-4-6`              → unchanged (no `\d+b` marker) */
-export function modelSegment(info: ActiveProviderInfo, opts: StatusBarRenderOptions = {}): string {
+export function modelSegment(info: Pick<ActiveProviderInfo, 'provider' | 'model'>, opts: StatusBarRenderOptions = {}): string {
   if (!info.model || info.model === '(none)') {
     return strongText(info.provider, 'pink', opts);
   }

package/src/status/status-provider-info.ts

@@ -0,0 +1,58 @@
+// ── Status-line provider/model reader ──
+//
+// 하단 상태줄은 키 입력마다 다시 그린다. 종전엔 그때마다 `inspectActiveProvider()` 를 불러
+//   ① `getUserConfig()` 의 stat ② `decideProviderForConfig()` 의 자격 확인 ③ 상태줄이 «안 쓰는»
+//   `authDetail`(codex 면 auth 스토어 readFileSync + JSON.parse) 을 매 렌더 동기로 했다.
+//   📏 실측(10-14 mbp · 운영 HOME · 500회 평균): 렌더 1회 98µs.
+// ⇒ 상태줄이 쓰는 것은 provider·model 둘뿐이라, 그 둘만 짧게 기억한다.
+//   ⛔ 기억이 «낡은 값»으로 굳지 않게: runtimeModel 이 바뀌면 즉시, 설정 파일이 바뀌면 TTL(2s) 안에 다시 읽고,
+//   그렇지 않아도 `maxAgeMs` 마다 다시 판정한다(auto 공급자는 자격 유무로 갈리므로). 표시 전용이라 2s 지연은 허용.
+
+import { inspectActiveProvider, type ActiveProviderInfo } from '../provider-summary.js';
+import { getUserConfig, type UserConfig } from '../user-config.js';
+
+export type StatusProviderInfo = Pick<ActiveProviderInfo, 'provider' | 'model'>;
+
+export interface StatusProviderInfoReaderDeps {
+  readConfig?: () => UserConfig;
+  inspect?: (cfg: UserConfig, runtimeModel?: string) => StatusProviderInfo;
+  now?: () => number;
+  /** 이 안에서는 설정도 다시 안 읽는다(렌더 경로 0 I/O). */
+  ttlMs?: number;
+  /** 설정이 그대로여도 이만큼 지나면 다시 판정한다. */
+  maxAgeMs?: number;
+}
+
+export function createStatusProviderInfoReader(
+  deps: StatusProviderInfoReaderDeps = {},
+): (runtimeModel?: string) => StatusProviderInfo {
+  const readConfig = deps.readConfig ?? (() => getUserConfig());
+  const inspect = deps.inspect ?? ((cfg, runtimeModel) => inspectActiveProvider(cfg, runtimeModel));
+  const now = deps.now ?? Date.now;
+  const ttlMs = deps.ttlMs ?? 2_000;
+  const maxAgeMs = deps.maxAgeMs ?? 30_000;
+  let memo: {
+    info: StatusProviderInfo;
+    cfg: UserConfig;
+    runtimeModel: string | undefined;
+    checkedAt: number;
+    inspectedAt: number;
+  } | null = null;
+
+  return (runtimeModel?: string): StatusProviderInfo => {
+    const t = now();
+    // ⛔ 조기 반환에도 최대 수명을 건다 — TTL 만 보면 «29초에 설정 확인 → 30.001초 렌더»가 재판정 없이 지나간다.
+    const fresh = memo !== null && t - memo.inspectedAt < maxAgeMs;
+    if (memo && fresh && memo.runtimeModel === runtimeModel && t - memo.checkedAt < ttlMs) return memo.info;
+    // getUserConfig() 는 파일 mtime 이 같으면 «같은 객체»를, 바뀌면 새 객체를 돌려준다(user-config.ts getUserConfig).
+    const cfg = readConfig();
+    if (memo && fresh && memo.cfg === cfg && memo.runtimeModel === runtimeModel) {
+      memo.checkedAt = t;
+      return memo.info;
+    }
+    const full = inspect(cfg, runtimeModel);
+    const info: StatusProviderInfo = { provider: full.provider, model: full.model };
+    memo = { info, cfg, runtimeModel, checkedAt: t, inspectedAt: t };
+    return info;
+  };
+}

package/src/steward/resync-tick.ts

@@ -1,11 +1,12 @@
 /** Resync labeled PRs before the steward's TA rejudge node sees their heads. */
 import { debug } from '../debug/log.js';
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { dlopen, FFIType } from 'bun:ffi';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { resolveHqLaunchSeat } from '../hq/seats.js';
-import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { effectiveInstanceRoot, normRoot, releaseLedgerRoot } from '../instance/resolve.js';
 import { runResyncShadow, type ResyncShadowSummary } from '../loops/orchestrator/resync-shadow.js';
 import { listSchedules, type ReleaseSchedule } from '../release-loop/release-schedule.js';
 
@@ -71,6 +72,90 @@ export function defaultResyncRun(
   execute: typeof runResyncShadow = runResyncShadow,
 ): Promise<ResyncShadowSummary> { return execute(3, { repoRoot }, 'live'); }
 
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+type FlockFn = (fd: number, op: number) => number;
+let flockFn: FlockFn | undefined;
+
+function osFlock(): FlockFn {
+  if (flockFn) return flockFn;
+  const names = process.platform === 'darwin'
+    ? ['/usr/lib/libSystem.B.dylib', 'libc.dylib']
+    : ['libc.so.6', `libc.musl-${process.arch === 'arm64' ? 'aarch64' : 'x86_64'}.so.1`];
+  let lastError: unknown;
+  for (const name of names) {
+    try {
+      const lib = dlopen(name, { flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 } });
+      flockFn = (fd, op) => lib.symbols.flock(fd, op) as number;
+      return flockFn;
+    } catch (error) { lastError = error; }
+  }
+  throw new Error(`OP seat flock unavailable (${names.join(', ')}): ${String(lastError)}`);
+}
+
+/**
+ * The one root every OP-seat locker resolves to (steward resync · manual resume · unattended release). It is the
+ * release ledger root — an explicit `--config-dir` universe, otherwise machine-wide prod — because the OP seat is
+ * machine-wide: a resync from a tree-derived test universe and a release run must still meet on the same lock file.
+ * An injected root (tests, a caller that already decided) is used as is. Normalized so `x` and `x/` share one inode.
+ */
+export function opSeatLockRoot(explicit?: string): string {
+  return normRoot(explicit ?? releaseLedgerRoot());
+}
+
+/** Persistent inode for the shared OP-seat kernel flock. Never unlink: a replacement inode would split lockers. */
+export function opSeatFlockPath(root?: string): string {
+  return join(opSeatLockRoot(root), 'steward', 'op-seat.flock');
+}
+
+export interface OpSeatFlock {
+  path: string;
+  release(): void;
+}
+
+/** Exclusive kernel flock covering OP-seat HEAD, index, and workfile mutation. Released on every exit, including throw. */
+export async function acquireOpSeatFlock(root?: string, waitMs = 120_000): Promise<OpSeatFlock> {
+  const path = opSeatFlockPath(root);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const flock = osFlock();
+  const fd = openSync(path, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+  let acquired = false;
+  try {
+    const stat = fstatSync(fd);
+    const current = lstatSync(path);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.ino !== current.ino || stat.dev !== current.dev) {
+      throw new Error('OP seat flock must be a private regular file (0600)');
+    }
+    const deadline = Date.now() + waitMs;
+    while (flock(fd, LOCK_EX | LOCK_NB) !== 0) {
+      if (Date.now() >= deadline) throw new Error(`OP seat flock timed out: ${path}`);
+      await Bun.sleep(25);
+    }
+    acquired = true;
+    const locked = lstatSync(path);
+    if (stat.ino !== locked.ino || stat.dev !== locked.dev) throw new Error('OP seat flock changed');
+  } catch (error) {
+    try { if (acquired) flock(fd, LOCK_UN); } finally { closeSync(fd); }
+    throw error;
+  }
+  let released = false;
+  return {
+    path,
+    release() {
+      if (released) return;
+      released = true;
+      try { flock(fd, LOCK_UN); } finally { closeSync(fd); }
+    },
+  };
+}
+
+export async function withOpSeatFlock<T>(action: () => Promise<T> | T, root?: string): Promise<T> {
+  const held = await acquireOpSeatFlock(root);
+  try { return await action(); }
+  finally { held.release(); }
+}
+
 export async function resyncTick(
   run: () => Promise<ResyncShadowSummary> = () => defaultResyncRun(),
   log: (event: string, data: Record<string, unknown>) => void = (event, data) => debug.log('loop.steward', event, data),
@@ -84,32 +169,38 @@ export async function resyncTickWithReleaseProbe(
   releaseProbe: () => ReleaseRunState,
   windowProbe: () => ReleaseWindowState = releaseWindowState,
 ): Promise<ResyncTickResult> {
-  let result: ResyncTickResult;
+  // Acquisition failure (unreadable lock file, 120s timeout) is a tick failure: it takes the same
+  // `{ decision: 'failed' }` + log path as any other resync error instead of escaping to the caller.
+  let held: OpSeatFlock | undefined;
   try {
-    const release = releaseProbe();
-    if (release !== 'idle') {
-      result = { decision: 'skipped-release', reason: release === 'active' ? 'release run active' : 'release process probe unavailable' };
-    } else {
-      const window = windowProbe();
-      if (window !== 'outside') {
-        result = { decision: 'skipped-release-window', reason: window === 'inside' ? 'scheduled release window' : 'release schedule unavailable' };
+    let result: ResyncTickResult;
+    try {
+      held = await acquireOpSeatFlock();
+      const release = releaseProbe();
+      if (release !== 'idle') {
+        result = { decision: 'skipped-release', reason: release === 'active' ? 'release run active' : 'release process probe unavailable' };
       } else {
-        const summary = await run();
-        if (summary.saved > 0) {
-          mkdirSync(dirname(pendingPath), { recursive: true });
-          writeFileSync(pendingPath, JSON.stringify({ savedAt: new Date().toISOString() }));
+        const window = windowProbe();
+        if (window !== 'outside') {
+          result = { decision: 'skipped-release-window', reason: window === 'inside' ? 'scheduled release window' : 'release schedule unavailable' };
+        } else {
+          const summary = await run();
+          if (summary.saved > 0) {
+            mkdirSync(dirname(pendingPath), { recursive: true });
+            writeFileSync(pendingPath, JSON.stringify({ savedAt: new Date().toISOString() }));
+          }
+          result = { decision: 'ran', summary };
         }
-        result = { decision: 'ran', summary };
       }
     }
-  }
-  catch (error) { result = { decision: 'failed', reason: (error instanceof Error ? error.message : String(error)).slice(-300) }; }
-  try { log('resync-tick', { ...result }); }
-  catch (error) {
-    result = { decision: 'failed', reason: `log failed: ${error instanceof Error ? error.message : String(error)}`.slice(-300) };
-    console.error(`steward resync: ${result.reason}`);
-  }
-  return result;
+    catch (error) { result = { decision: 'failed', reason: (error instanceof Error ? error.message : String(error)).slice(-300) }; }
+    try { log('resync-tick', { ...result }); }
+    catch (error) {
+      result = { decision: 'failed', reason: `log failed: ${error instanceof Error ? error.message : String(error)}`.slice(-300) };
+      console.error(`steward resync: ${result.reason}`);
+    }
+    return result;
+  } finally { held?.release(); }
 }
 
 if (import.meta.main) {