elanous 0.2.0 → 0.2.4

package/src/release-loop/release-note.ts

@@ -0,0 +1,174 @@
+import { closeSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+
+export interface ReleaseNoteFragment {
+  pr: number;
+  line: string;
+  kind: 'fix' | 'feat' | 'security' | 'internal';
+  docs: { path: string } | { none: string };
+  target: 'next' | 'later';
+  source: 'pr-body' | 'harness' | 'backfill';
+  mergeSha?: string;
+}
+
+type Section = Omit<ReleaseNoteFragment, 'pr' | 'source' | 'mergeSha'>;
+
+/** Blank out fenced code blocks (``` / ~~~) line-for-line so example headings and fields inside them are never read as the real section. */
+function blankFencedCode(text: string): string {
+  let fence: string | null = null;
+  return text.split('\n').map((line) => {
+    const open = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence === null) {
+      if (open) { fence = open[1]!; return ''; }
+      return line;
+    }
+    if (open && open[1]![0] === fence[0] && open[1]!.length >= fence.length && /^ {0,3}[`~]+[ \t]*\r?$/.test(line)) fence = null;
+    return '';
+  }).join('\n');
+}
+
+export function parseReleaseNoteSection(rawPrBody: string): { fragment?: Section; problems: string[] } {
+  const prBody = blankFencedCode(rawPrBody);
+  const start = /^## 릴리스 노트[ \t]*\r?$/m.exec(prBody);
+  if (!start) return { problems: [] };
+  const rest = prBody.slice(start.index + start[0].length).replace(/^\r?\n/, '');
+  const nextHeading = /^ {0,3}#{1,6}(?:[ \t]+|$)/m.exec(rest);
+  const body = nextHeading ? rest.slice(0, nextHeading.index) : rest;
+  const fields = new Map<string, string>();
+  const duplicates = new Set<string>();
+  for (const match of body.matchAll(/^[ \t]*- (한 줄|종류|문서|대상):[ \t]*(.*?)[ \t]*\r?$/gm)) {
+    const name = match[1]!;
+    if (fields.has(name)) duplicates.add(name);
+    else fields.set(name, match[2]!);
+  }
+  const line = fields.get('한 줄');
+  const kind = fields.get('종류');
+  const doc = fields.get('문서');
+  const target = fields.get('대상');
+  const problems: string[] = [];
+  if (duplicates.has('한 줄') || !line?.trim()) problems.push('한 줄');
+  if (duplicates.has('종류') || !kind || !['fix', 'feat', 'security', 'internal'].includes(kind)) problems.push('종류');
+  if (duplicates.has('문서') || !doc || (doc.startsWith('없음') ? !/^없음\([^\s()]+(?:[^()]*)\)$/.test(doc) : !/^\S+$/.test(doc))) problems.push('문서');
+  if (duplicates.has('대상') || (target !== 'next' && target !== 'later')) problems.push('대상');
+  if (problems.length) return { problems };
+  return {
+    fragment: {
+      line: line!, kind: kind as Section['kind'],
+      docs: doc!.startsWith('없음(') ? { none: doc!.slice(3, -1) } : { path: doc! },
+      target: target as Section['target'],
+    },
+    problems,
+  };
+}
+
+export function renderReleaseNoteSection(fragment: Section): string {
+  return `## 릴리스 노트\n- 한 줄: ${fragment.line}\n- 종류: ${fragment.kind}\n- 문서: ${'path' in fragment.docs ? fragment.docs.path : `없음(${fragment.docs.none})`}\n- 대상: ${fragment.target}\n`;
+}
+
+export function harnessReleaseNote(goalDocument: string, title: string): Section {
+  const document = blankFencedCode(goalDocument);
+  const goal = /^ {0,3}## 목표[ \t]*\r?$/m.exec(document);
+  let section = '';
+  if (goal) {
+    const rest = document.slice(goal.index + goal[0].length);
+    let end = rest.length;
+    for (const heading of rest.matchAll(/^ {0,3}(#{1,2})[ \t]+([^\r\n]*?)[ \t]*\r?$/gm)) {
+      if (heading[1] !== '##' || heading[2] !== '릴리스 노트') {
+        end = heading.index;
+        break;
+      }
+    }
+    section = rest.slice(0, end);
+  }
+  return parseReleaseNoteSection(section).fragment ?? {
+    line: title,
+    kind: 'internal',
+    docs: { none: '하니스 자동 생성' },
+    target: 'next',
+  };
+}
+
+export function releaseNotesDir(instanceRoot: string): string {
+  return join(instanceRoot, 'release', 'notes');
+}
+
+function validFragment(value: unknown): value is ReleaseNoteFragment {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return Number.isSafeInteger(v.pr) && (v.pr as number) > 0
+    && (v.mergeSha === undefined || (typeof v.mergeSha === 'string' && v.mergeSha.trim().length > 0))
+    && typeof v.line === 'string' && v.line.trim().length > 0
+    && ['fix', 'feat', 'security', 'internal'].includes(v.kind as string)
+    && (v.target === 'next' || v.target === 'later')
+    && ['pr-body', 'harness', 'backfill'].includes(v.source as string)
+    && !!v.docs && typeof v.docs === 'object'
+    && (('path' in v.docs && typeof v.docs.path === 'string' && v.docs.path.trim().length > 0 && !('none' in v.docs))
+      || ('none' in v.docs && typeof v.docs.none === 'string' && v.docs.none.trim().length > 0 && !('path' in v.docs)));
+}
+
+const priority: Record<ReleaseNoteFragment['source'], number> = { backfill: 0, harness: 1, 'pr-body': 2 };
+
+export function writeReleaseNote(dir: string, fragment: ReleaseNoteFragment): void {
+  if (!validFragment(fragment)) throw new Error('invalid release note fragment');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${fragment.pr}.json`);
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + 10_000;
+  const wait = new Int32Array(new SharedArrayBuffer(4));
+  let descriptor: number;
+  while (true) {
+    try { descriptor = openSync(lock, 'wx'); break; }
+    catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error;
+      if (Date.now() >= deadline) throw new Error(`release note lock timed out: ${lock}`);
+      Atomics.wait(wait, 0, 0, 10);
+    }
+  }
+  try {
+    let existing: unknown;
+    try { existing = JSON.parse(readFileSync(path, 'utf8')); }
+    catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+    }
+    if (existing !== undefined && !validFragment(existing)) throw new Error(`invalid release note: ${path}`);
+    if (validFragment(existing) && priority[existing.source] >= priority[fragment.source]) return;
+    const temporary = join(dir, `.${fragment.pr}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, JSON.stringify(fragment, null, 2) + '\n');
+      renameSync(temporary, path);
+    } finally {
+      try { unlinkSync(temporary); }
+      catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+      }
+    }
+  } finally {
+    closeSync(descriptor);
+    unlinkSync(lock);
+  }
+}
+
+export type ReleaseNotes = Map<number, ReleaseNoteFragment> & { problems: string[] };
+
+export function readReleaseNotes(dir: string): ReleaseNotes {
+  const notes = new Map<number, ReleaseNoteFragment>() as ReleaseNotes;
+  notes.problems = [];
+  let files: string[];
+  try { files = readdirSync(dir); }
+  catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return notes;
+    throw error;
+  }
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      const value: unknown = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+      if (!validFragment(value) || file !== `${value.pr}.json`) throw new Error('invalid fragment or PR filename');
+      notes.set(value.pr, value);
+    } catch (error) {
+      notes.problems.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return notes;
+}

package/src/roles/lease-cas.ts

@@ -0,0 +1,52 @@
+// 임대 CAS 판정(순수) — 공개 코어(`elanous role …`)가 쓰는 부분.
+// 원래 scripts/botlab/core-lease.ts 에 있었으나 scripts/botlab/** 는 공개본에서 빠진다(release/public-export.yaml)
+// ⇒ 공개판에서 `role-cli.ts` 가 모듈을 못 찾아 PWA 빌드·기동이 깨졌다(📏 2026-09-27 0.2.3 prepare). botlab 은 여기서 다시 내보낸다.
+
+/**
+ * 🔎⛔⭐ **「없다」와 「못 읽었다」를 gcloud 문면에서 «가른다»**
+ *
+ * 🩸 계기(라이브): 첫 판은 `404|not found` 만 봤는데 gcloud 는 이렇게 낸다 —
+ *    ***`The following URLs matched no objects or files`***. ⇒ ***진짜 「없다」가 「못 읽었다」로 떨어졌다.***
+ * ⛔ 그 둘이 갈려야 하는 이유: 「없다」는 ***CAS 를 `--if-generation-match=0` 으로 시도할 수 있는*** 상태이고,
+ *    「못 읽었다」는 ***아무것도 하면 안 되는*** 상태다.
+ * 📌 그래서 이 판정을 «순수»로 꺼냈다 — 시험이 gcloud 문면을 «그대로» 물 수 있게.
+ */
+export function isAbsentSaid(said: string): boolean {
+  return /\b404\b/.test(said)
+    || /not found/i.test(said)
+    || /does not exist/i.test(said)
+    || /matched no objects/i.test(said);     // ⇐ 🩸 라이브가 잡은 문면
+}
+
+
+export type CasOutcome =
+  /** 이겼다 — 내가 잡았다/갱신했다. */
+  | { readonly kind: 'won' }
+  /** ⭐ ***졌다*** — 그 사이 남이 썼다(412). ⛔ 「실패」가 아니라 «정상 결과»다. */
+  | { readonly kind: 'lost'; readonly detail: string }
+  /** ⛔ 「졌다」로 접지 «않는다» — 네트워크·자격·버킷 문제일 수 있다. */
+  | { readonly kind: 'unmeasured'; readonly why: string };
+
+/**
+ * 🔐⭐⭐ **CAS 산출을 «셋»으로 가른다** — ⛔ 이것이 이 파일에서 가장 중요한 함수다.
+ *
+ * 🔑 ***「졌다」와 「못 쟀다」를 뭉치면 이 설계가 무너진다***:
+ * ```
+ * 「졌다」    ⇒ 남이 primary 다 — ***정상***이고, 나는 조용히 물러난다
+ * 「못 쟀다」 ⇒ 내가 «모른다» — ⛔ 그때 ***물러나도 안 되고 잡아도 안 된다***
+ * ```
+ * ⛔ 그 둘을 같은 값으로 내면 「네트워크가 끊겼을 뿐인데 primary 를 넘겨준다」가 된다.
+ */
+export function interpretCasResult(r: { readonly code: number | null; readonly said: string }): CasOutcome {
+  if (r.code === 0) return { kind: 'won' };
+  const said = r.said ?? '';
+  // 📏 gcloud 는 전제조건 실패를 `412` ⊕ `PreconditionFailed`/`does not match` 로 낸다.
+  //    ⛔ 코드 하나에 안 기댄다 — 문면과 «둘 다» 본다(gcloud 판이 바뀌어도 한쪽이 남는다).
+  if (/\b412\b/.test(said) || /precondition/i.test(said) || /generation.*(match|mismatch)/i.test(said)) {
+    return { kind: 'lost', detail: said.trim().split('\n').slice(-2).join(' / ').slice(0, 200) };
+  }
+  return {
+    kind: 'unmeasured',
+    why: `CAS 가 «졌는지 못 쟀는지» 모른다(code=${r.code}) — ${said.trim().split('\n').slice(-2).join(' / ').slice(0, 160)}`,
+  };
+}

package/src/roles/machine-name.ts

@@ -0,0 +1,48 @@
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { assertJoinedMachineId, readMachineProfile, writeMachineProfile } from './machine-profile.js';
+import { readPrimaryJoin } from '../control-plane/primary.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+
+export const MACHINE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+export type MachineNameSource = 'option' | 'config' | 'join' | 'hostname';
+export interface ResolvedMachineName { readonly machine: string; readonly source: MachineNameSource }
+
+export function machineConfigPath(root: string = effectiveInstanceRoot()): string {
+  return join(root, 'control', 'machine.json');
+}
+
+/** A missing or damaged file is not a name — fall through to the next source. */
+export function readConfiguredMachine(root: string = effectiveInstanceRoot()): string | undefined {
+  return readMachineProfile(root)?.id;
+}
+
+export function writeConfiguredMachine(machine: string, root: string = effectiveInstanceRoot()): void {
+  if (!MACHINE_NAME.test(machine)) throw new Error(`invalid machine: ${machine}`);
+  const previous = readMachineProfile(root);
+  writeMachineProfile({ id: machine, duties: previous?.duties ?? [], seats: previous?.seats ?? {} }, root);
+}
+
+/**
+ * The lease uses a configured machine identifier, not the OS hostname.
+ * Explicit wins: option → control/machine.json → valid join ID → lowercased hostname.
+ */
+export function resolveMachineName(opts: {
+  option?: string; root?: string; host?: string;
+  readJoinMachine?: (root: string) => string | undefined;
+} = {}): ResolvedMachineName {
+  const root = opts.root ?? effectiveInstanceRoot();
+  if (opts.option !== undefined) return { machine: opts.option, source: 'option' };
+  const configured = readConfiguredMachine(root);
+  if (configured) {
+    assertJoinedMachineId(configured, root);
+    return { machine: configured, source: 'config' };
+  }
+  const joined = (opts.readJoinMachine ?? ((r) => readPrimaryJoin(r)?.machine))(root);
+  if (joined) {
+    if (!MACHINE_NAME.test(joined)) throw new Error(`invalid joined machine id: ${joined}`);
+    return { machine: joined, source: 'join' };
+  }
+  return { machine: (opts.host ?? hostname()).split('.')[0]!.toLowerCase(), source: 'hostname' };
+}

package/src/roles/machine-profile.ts

@@ -0,0 +1,65 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { debug } from '../debug/log.js';
+import { readPrimaryJoin } from '../control-plane/primary.js';
+import { MACHINE_NAME, machineConfigPath } from './machine-name.js';
+
+export interface MachineProfile {
+  id: string;
+  duties: string[];
+  seats: Record<string, { rank: number }>;
+}
+
+export function validSeatRank(rank: number): boolean {
+  return Number.isSafeInteger(rank) && rank >= 1 && rank <= 99;
+}
+
+export function readMachineProfile(root?: string): MachineProfile | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(machineConfigPath(root), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const doc = value as Record<string, unknown>;
+    const id = doc.id === undefined ? doc.machine : doc.id;
+    if (typeof id !== 'string' || !MACHINE_NAME.test(id)) return undefined;
+    const duties = doc.duties === undefined ? [] : doc.duties;
+    const seats = doc.seats === undefined ? {} : doc.seats;
+    if (!Array.isArray(duties) || !duties.every(d => typeof d === 'string' && MACHINE_NAME.test(d)) ||
+        !seats || typeof seats !== 'object' || Array.isArray(seats) ||
+        !Object.entries(seats).every(([seat, value]) => MACHINE_NAME.test(seat) && value && typeof value === 'object' &&
+          !Array.isArray(value) && validSeatRank((value as { rank?: number }).rank as number))) return undefined;
+    return { id, duties: [...duties], seats: { ...seats } as MachineProfile['seats'] };
+  } catch { return undefined; }
+}
+
+export function assertJoinedMachineId(id: string, root?: string): void {
+  const joined = readPrimaryJoin(root)?.machine;
+  if (joined && joined !== id) {
+    throw new Error(`machine id ${id} differs from joined machine ${joined}`);
+  }
+}
+
+export function writeMachineProfile(profile: MachineProfile, root?: string): void {
+  if (typeof profile.id !== 'string' || !MACHINE_NAME.test(profile.id) || !Array.isArray(profile.duties) ||
+      !profile.duties.every(d => typeof d === 'string' && MACHINE_NAME.test(d)) ||
+      !profile.seats || typeof profile.seats !== 'object' || Array.isArray(profile.seats) ||
+      !Object.entries(profile.seats).every(([seat, value]) => MACHINE_NAME.test(seat) && validSeatRank(value?.rank))) {
+    throw new Error('invalid machine profile (id, duties, seats or rank)');
+  }
+  assertJoinedMachineId(profile.id, root);
+  const path = machineConfigPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(profile)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+  debug.log('roles.machine', 'profile-written', { id: profile.id, duties: profile.duties, seats: profile.seats });
+}
+
+export function seatRank(profile: MachineProfile | undefined, seat: string): number | undefined {
+  return profile && Object.hasOwn(profile.seats, seat) ? profile.seats[seat]?.rank : undefined;
+}

package/src/roles/role-lease-read.ts

@@ -0,0 +1,81 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { isAbsentSaid } from './lease-cas.js';
+import { debug } from '../debug/log.js';
+import { gcloudSearchPaths } from '../cli/role-cli.js';
+import { ROLE_LEASE_OBJECT_PATH, parseRoleLease, type RoleLeaseRead } from './role-lease.js';
+
+interface CommandResult {
+  code: number | null;
+  stdout: string;
+  said: string;
+}
+
+async function runGcloud(args: string[]): Promise<CommandResult> {
+  let binary: string | undefined;
+  for (const path of gcloudSearchPaths()) {
+    try { await access(path, constants.X_OK); if ((await stat(path)).isFile()) { binary = path; break; } }
+    catch { /* try the next executable */ }
+  }
+  if (!binary) return { code: null, stdout: '', said: 'gcloud not found' };
+  return new Promise(resolve => {
+    const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '', error = '', settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGKILL');
+      resolve({ code: null, stdout, said: 'gcloud timeout (8s)' });
+    }, 8_000);
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => { stdout += chunk; });
+    child.stderr.on('data', (chunk: string) => { stderr += chunk; });
+    child.on('error', (err: Error) => { error = err.message; });
+    child.on('close', code => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      resolve({ code, stdout, said: `${stdout}${stderr}${error}` });
+    });
+  });
+}
+
+export async function readRoleLeaseAsync(bucket: string, { run = runGcloud }: {
+  run?: (args: string[]) => Promise<CommandResult>;
+} = {}): Promise<RoleLeaseRead> {
+  const started = Date.now();
+  let result: RoleLeaseRead;
+  const uri = `${bucket}/${ROLE_LEASE_OBJECT_PATH}`;
+  const describe = async (): Promise<{ kind: 'present'; gen: string } | { kind: 'absent' } | { kind: 'unmeasured'; why: string }> => {
+    const response = await run(['storage', 'objects', 'describe', uri, '--format=value(generation)']);
+    if (response.code !== 0) {
+      return response.code !== null && isAbsentSaid(response.said)
+        ? { kind: 'absent' } : { kind: 'unmeasured', why: response.said.trim() || 'gcloud describe failed' };
+    }
+    const gen = response.stdout.trim();
+    return /^\d+$/.test(gen) ? { kind: 'present', gen } : { kind: 'unmeasured', why: 'invalid GCS generation' };
+  };
+  try {
+    const before = await describe();
+    if (before.kind !== 'present') result = before;
+    else {
+      const body = await run(['storage', 'cat', uri]);
+      if (body.code !== 0) result = { kind: 'unmeasured', why: body.said.trim() || 'gcloud cat failed' };
+      else {
+        const after = await describe();
+        result = after.kind !== 'present' || before.gen !== after.gen
+          ? { kind: 'unmeasured', why: 'lease changed during read; retry' }
+          : parseRoleLease(body.stdout);
+      }
+    }
+  } catch (error) {
+    result = { kind: 'unmeasured', why: error instanceof Error ? error.message : String(error) };
+  }
+  debug.log('control.lease', 'read', {
+    kind: result.kind, holder: result.kind === 'present' ? result.doc.holder : null,
+    generation: result.kind === 'present' ? result.doc.generation : null, ms: Date.now() - started,
+  });
+  return result;
+}

package/src/roles/role-lease.ts

@@ -0,0 +1,63 @@
+export const ROLE_LEASE_OBJECT_PATH = 'lease/control-primary.json';
+
+export interface RoleLeaseDoc {
+  readonly holder: string;
+  /** Document fencing token, distinct from the GCS object's server generation. */
+  readonly generation: number;
+  readonly state: 'held' | 'handing-off';
+  readonly from?: string;
+  readonly renewedAt: number;
+}
+
+export type RoleLeaseRead =
+  | { readonly kind: 'present'; readonly doc: RoleLeaseDoc }
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'unmeasured'; readonly why: string };
+
+export function parseRoleLease(text: string): RoleLeaseRead {
+  if (text.trim() === '') return { kind: 'unmeasured', why: 'empty lease body' };
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { return { kind: 'unmeasured', why: 'invalid lease JSON' }; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { kind: 'unmeasured', why: 'lease is not an object' };
+  const o = value as Record<string, unknown>;
+  if (typeof o.holder !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(o.holder)) return { kind: 'unmeasured', why: 'invalid holder' };
+  if (!Number.isSafeInteger(o.generation) || (o.generation as number) < 1) return { kind: 'unmeasured', why: 'invalid generation' };
+  if (typeof o.renewedAt !== 'number' || !Number.isFinite(o.renewedAt)) return { kind: 'unmeasured', why: 'invalid renewedAt' };
+  if (o.state !== 'held' && o.state !== 'handing-off') return { kind: 'unmeasured', why: 'invalid state' };
+  if (o.state === 'handing-off' && (typeof o.from !== 'string' || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(o.from) || o.from === o.holder)) {
+    return { kind: 'unmeasured', why: 'invalid handoff origin' };
+  }
+  if (o.state === 'held' && 'from' in o) return { kind: 'unmeasured', why: 'held lease has handoff origin' };
+  if ('expiresAt' in o) return { kind: 'unmeasured', why: 'client-side expiration is not supported' };
+  return { kind: 'present', doc: {
+    holder: o.holder, generation: o.generation as number, state: o.state,
+    ...(o.state === 'handing-off' ? { from: o.from as string } : {}), renewedAt: o.renewedAt,
+  } };
+}
+
+function checkedNext(generation: number): number {
+  if (!Number.isSafeInteger(generation + 1)) throw new Error('lease generation exhausted');
+  return generation + 1;
+}
+
+export function nextClaim(prev: RoleLeaseRead, me: string, now = Date.now()): RoleLeaseDoc {
+  if (prev.kind === 'unmeasured') throw new Error(`lease unreadable: ${prev.why}`);
+  if (prev.kind === 'present' && (prev.doc.state !== 'held' || prev.doc.holder !== me)) throw new Error('another machine holds the lease');
+  return { holder: me, generation: checkedNext(prev.kind === 'present' ? prev.doc.generation : 0), state: 'held', renewedAt: now };
+}
+
+export function nextHandoff(prev: RoleLeaseDoc, me: string, to: string, now = Date.now()): RoleLeaseDoc {
+  if (prev.state !== 'held' || prev.holder !== me) throw new Error('only the current holder can hand off');
+  if (me === to) throw new Error('handoff target must differ from holder');
+  return { holder: to, generation: checkedNext(prev.generation), state: 'handing-off', from: me, renewedAt: now };
+}
+
+export function nextAccept(prev: RoleLeaseDoc, me: string, now = Date.now()): RoleLeaseDoc {
+  if (prev.state !== 'handing-off' || prev.holder !== me || !prev.from) throw new Error('no handoff addressed to this machine');
+  return { holder: me, generation: checkedNext(prev.generation), state: 'held', renewedAt: now };
+}
+
+export function nextRevert(prev: RoleLeaseDoc, now = Date.now()): RoleLeaseDoc {
+  if (prev.state !== 'handing-off' || !prev.from) throw new Error('no pending handoff to revert');
+  return { holder: prev.from, generation: checkedNext(prev.generation), state: 'held', renewedAt: now };
+}

package/src/roles/role-watch.ts

@@ -0,0 +1,69 @@
+import type { RoleObjectRead } from '../cli/role-cli.js';
+import { validSeatRank } from './machine-profile.js';
+import { nextAccept, nextClaim, parseRoleLease, type RoleLeaseDoc } from './role-lease.js';
+
+export interface WatchState {
+  readonly generation?: number;
+  readonly objectGen?: string;
+  readonly unchangedTicks: number;
+  readonly absentTicks?: number;
+}
+
+export const initialWatchState: WatchState = { unchangedTicks: 0, absentTicks: 0 };
+
+// One missed observation can precede a healthy holder's next 60-second renewal.
+export const MIN_TAKEOVER_TICKS = 2;
+
+export interface WatchConfig {
+  readonly me: string;
+  readonly rank?: number;
+  readonly takeoverTicks: number;
+  readonly now: number;
+}
+
+type TickDecision = {
+  readonly state: WatchState;
+  readonly action: 'claim' | 'renew' | 'takeover' | 'accept' | 'observe';
+  readonly holder?: string;
+  readonly generation?: number;
+  readonly doc?: RoleLeaseDoc;
+  readonly ifGen?: string;
+};
+
+function nextGeneration(generation: number): number {
+  if (!Number.isSafeInteger(generation + 1)) throw new Error('lease generation exhausted');
+  return generation + 1;
+}
+
+/** Only successful server-generation CAS writes establish ownership; timestamps never decide expiry. */
+export function decideTick(state: WatchState, read: RoleObjectRead, cfg: WatchConfig): TickDecision {
+  if (!Number.isSafeInteger(cfg.takeoverTicks) || cfg.takeoverTicks < MIN_TAKEOVER_TICKS) {
+    throw new Error(`takeover-ticks must be at least ${MIN_TAKEOVER_TICKS} (one missed renewal can precede a live holder)`);
+  }
+  if (cfg.rank !== undefined && !validSeatRank(cfg.rank)) throw new Error('rank must be an integer from 1 to 99');
+  if (read.kind === 'unmeasured') throw new Error(`lease unreadable: ${read.why}`);
+  if (read.kind === 'absent') {
+    const absentTicks = (state.absentTicks ?? 0) + 1;
+    const next: WatchState = { unchangedTicks: 0, absentTicks };
+    return cfg.rank !== undefined && absentTicks >= (cfg.rank - 1) * cfg.takeoverTicks
+      ? { state: next, action: 'claim', doc: nextClaim({ kind: 'absent' }, cfg.me, cfg.now), ifGen: '0', holder: cfg.me, generation: 1 }
+      : { state: next, action: 'observe' };
+  }
+  const parsed = parseRoleLease(read.text);
+  if (parsed.kind !== 'present') throw new Error(`lease unreadable: ${parsed.kind === 'unmeasured' ? parsed.why : 'lease absent'}`);
+  const doc = parsed.doc;
+  const changed = state.generation !== doc.generation || state.objectGen !== read.gen;
+  const unchangedTicks = changed ? 0 : state.unchangedTicks + 1;
+  const next: WatchState = { generation: doc.generation, objectGen: read.gen, unchangedTicks, absentTicks: 0 };
+  const base = { state: next, holder: doc.holder, generation: doc.generation };
+  if (doc.holder === cfg.me) {
+    if (doc.state === 'handing-off') return { ...base, action: 'accept', doc: nextAccept(doc, cfg.me, cfg.now), ifGen: read.gen };
+    return { ...base, action: 'renew', doc: nextClaim({ kind: 'present', doc }, cfg.me, cfg.now), ifGen: read.gen };
+  }
+  if (doc.state === 'held' && cfg.rank !== undefined && unchangedTicks >= cfg.takeoverTicks * cfg.rank) {
+    return { ...base, action: 'takeover', doc: {
+      holder: cfg.me, generation: nextGeneration(doc.generation), state: 'held', renewedAt: cfg.now,
+    }, ifGen: read.gen };
+  }
+  return { ...base, action: 'observe' };
+}