elanous 0.2.10 → 0.2.12

package/src/self-dev/fabric-plan-core.ts

@@ -0,0 +1,297 @@
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, statSync, truncateSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import {
+  decomposeFabricRequest,
+  type FabricDecomposeRequestOptions,
+} from './fabric-decompose-adapter.js';
+import type { JobKind } from './orchestrate.js';
+
+export interface FabricPlanNode {
+  id: string;
+  title: string;
+  kind: JobKind;
+  dependsOn: string[];
+  expectedOutput: string;
+  children: FabricPlanNode[];
+}
+
+export interface FabricPlan {
+  id: string;
+  request: string;
+  status: 'draft' | 'approved';
+  nodes: FabricPlanNode[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface FabricPlanEdit {
+  id: string;
+  title?: string;
+  kind?: JobKind;
+  dependsOn?: string[];
+  expectedOutput?: string;
+}
+
+export interface FabricExecutionCandidate {
+  planId: string;
+  nodes: FabricPlanNode[];
+  approvedAt: string;
+}
+
+type FabricPlanEvent =
+  | { type: 'plan'; plan: FabricPlan }
+  | { type: 'execution-candidate'; candidate: FabricExecutionCandidate };
+/** An approval is one line, so a torn write can never leave «approved» without its candidate (review must-fix). */
+type FabricPlanLine = FabricPlanEvent | { type: 'approved'; plan: FabricPlan; candidate: FabricExecutionCandidate };
+
+function ledgerPath(root: string): string {
+  return join(root, 'fabric', 'plans.jsonl');
+}
+
+// One ledger lock also protects reads: a reader must not observe half of an approval pair.
+// The owner file is fully written before its hard link becomes the visible lock.
+function lockOwnerAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== 'ESRCH';
+  }
+}
+
+/** Process start time as `ps` reports it — with the pid it identifies one process even after the pid is reused. */
+function processStart(pid: number): string | null {
+  const r = spawnSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8' });
+  const value = r.status === 0 ? r.stdout.trim() : '';
+  return value || null;
+}
+
+function reclaimAbandonedLock(lockPath: string): void {
+  let observed: string;
+  let inode: number;
+  try {
+    observed = readFileSync(lockPath, 'utf8');
+    inode = statSync(lockPath).ino;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw error;
+  }
+  const [pidText, ...startParts] = observed.trim().split('|');
+  const pid = Number(pidText);
+  const ownerStart = startParts.join('|');
+  // Unidentified locks are not evidence that their owner has died.
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+  // Alive pid with a different start time = the pid was reused by another process; the owner is gone (review must-fix).
+  const reused = ownerStart !== '' && lockOwnerAlive(pid) && processStart(pid) !== null && processStart(pid) !== ownerStart;
+  if (lockOwnerAlive(pid) && !reused) return;
+  try {
+    if (statSync(lockPath).ino === inode && readFileSync(lockPath, 'utf8') === observed) unlinkSync(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+
+function withLedgerLock<T>(root: string, operation: () => T): T {
+  const directory = join(root, 'fabric');
+  mkdirSync(directory, { recursive: true });
+  const lockPath = join(directory, 'plans.lock');
+  const ownerPath = join(directory, `plans.lock.${process.pid}.${randomUUID()}`);
+  writeFileSync(ownerPath, `${process.pid}|${processStart(process.pid) ?? ''}`, { flag: 'wx' });
+  const deadline = Date.now() + 10_000;
+  let acquired = false;
+  try {
+    while (!acquired) {
+      try {
+        linkSync(ownerPath, lockPath);
+        acquired = true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        reclaimAbandonedLock(lockPath);
+        if (Date.now() >= deadline) throw new Error('fabric plan ledger lock timeout');
+        Bun.sleepSync(5);
+      }
+    }
+    return operation();
+  } finally {
+    if (acquired) unlinkSync(lockPath);
+    unlinkSync(ownerPath);
+  }
+}
+
+function appendLines(root: string, lines: readonly FabricPlanLine[]): void {
+  const path = ledgerPath(root);
+  mkdirSync(join(root, 'fabric'), { recursive: true });
+  appendFileSync(path, lines.map((line) => JSON.stringify(line)).join('\n') + '\n');
+}
+
+function appendEvent(root: string, event: FabricPlanEvent): void {
+  appendLines(root, [event]);
+}
+
+/** Called under the ledger lock. A torn last line (crash mid-append) is cut back to the last whole line so the ledger stays usable. */
+function readEvents(root: string): FabricPlanEvent[] {
+  const path = ledgerPath(root);
+  if (!existsSync(path)) return [];
+  const text = readFileSync(path, 'utf8');
+  const lines = text.split('\n');
+  const events: FabricPlanEvent[] = [];
+  let offset = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const complete = i < lines.length - 1;
+    if (line) {
+      let parsed: FabricPlanLine | undefined;
+      try { parsed = JSON.parse(line) as FabricPlanLine; } catch { parsed = undefined; }
+      if (!parsed || !complete) {
+        // Only the tail may be torn; a bad line in the middle is real corruption and must not be silently skipped.
+        if (lines.slice(i + 1).some(Boolean)) throw new Error(`fabric plan ledger corrupt at line ${i + 1}`);
+        truncateSync(path, Buffer.byteLength(text.slice(0, offset)));
+        debug.log('fabric.plan', 'torn-tail-repaired', { line: i + 1, bytes: Buffer.byteLength(line) });
+        break;
+      }
+      if (parsed.type === 'approved') events.push({ type: 'plan', plan: parsed.plan }, { type: 'execution-candidate', candidate: parsed.candidate });
+      else events.push(parsed);
+    }
+    offset += line.length + 1;
+  }
+  return events;
+}
+
+function inferredKind(text: string): JobKind {
+  if (/영상|비디오|video|media|편집|촬영/i.test(text)) return 'media';
+  if (/배포|출시|deploy|release|publish/i.test(text)) return 'deploy';
+  if (/조사|검색|분석|research|search|investigat/i.test(text)) return 'search';
+  return 'dev';
+}
+
+function flatten(nodes: readonly FabricPlanNode[]): FabricPlanNode[] {
+  return nodes.flatMap((node) => [node, ...flatten(node.children)]);
+}
+
+function validateNodes(nodes: readonly FabricPlanNode[]): void {
+  const all = flatten(nodes);
+  if (!all.length) throw new Error('fabric plan requires nodes');
+  const byId = new Map(all.map((node) => [node.id, node]));
+  if (byId.size !== all.length) throw new Error('duplicate fabric plan node id');
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (id: string): void => {
+    if (visiting.has(id)) throw new Error('cyclic fabric plan dependency');
+    if (visited.has(id)) return;
+    const node = byId.get(id);
+    if (!node) throw new Error(`unknown fabric plan dependency: ${id}`);
+    visiting.add(id);
+    for (const dependency of node.dependsOn) visit(dependency);
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const node of all) {
+    if (typeof node.title !== 'string' || !node.title.trim()
+      || typeof node.expectedOutput !== 'string' || !node.expectedOutput.trim()) {
+      throw new Error('fabric plan node requires title and expected output');
+    }
+    if (!['dev', 'search', 'deploy', 'media'].includes(node.kind)) throw new Error('invalid fabric plan node kind');
+    if (!Array.isArray(node.dependsOn) || node.dependsOn.some((id) => typeof id !== 'string')) {
+      throw new Error('invalid fabric plan dependencies');
+    }
+    visit(node.id);
+  }
+}
+
+function loadPlanUnlocked(root: string, id: string): FabricPlan | null {
+  const events = readEvents(root);
+  return events.filter((event): event is Extract<FabricPlanEvent, { type: 'plan' }> => event.type === 'plan')
+    .map((event) => event.plan).reverse().find((plan) => plan.id === id) ?? null;
+}
+
+export function loadFabricPlan(root: string, id: string): FabricPlan | null {
+  return withLedgerLock(root, () => loadPlanUnlocked(root, id));
+}
+
+export function listFabricExecutionCandidates(root: string): FabricExecutionCandidate[] {
+  return withLedgerLock(root, () => readEvents(root)
+    .filter((event): event is Extract<FabricPlanEvent, { type: 'execution-candidate' }> => event.type === 'execution-candidate')
+    .map((event) => event.candidate));
+}
+
+/** Drafting and human edits record plan versions, never executable candidates. */
+export async function createFabricPlan(
+  root: string,
+  request: string,
+  options: FabricDecomposeRequestOptions = {},
+): Promise<FabricPlan> {
+  if (!request.trim()) throw new Error('fabric plan request is empty');
+  const result = await decomposeFabricRequest(request, options);
+  if (result.status !== 'decomposed' || result.rfc.arcs.length === 0) {
+    throw new Error(`fabric plan decomposition failed: ${result.status}`);
+  }
+  const nodes: FabricPlanNode[] = result.rfc.arcs.map((arc, arcIndex) => {
+    const id = `arc-${arcIndex + 1}`;
+    const previousArc = result.rfc.arcs[arcIndex - 1];
+    const previous = previousArc ? [`arc-${arcIndex}:task-${previousArc.workItems.length}`] : [];
+    const children: FabricPlanNode[] = arc.workItems.map((item, itemIndex) => ({
+      id: `${id}:task-${itemIndex + 1}`,
+      title: item.title,
+      kind: inferredKind(`${arc.heading} ${item.title}`),
+      dependsOn: itemIndex ? [`${id}:task-${itemIndex}`] : [id],
+      expectedOutput: item.detail?.trim() || item.title,
+      children: [],
+    }));
+    return {
+      id,
+      title: arc.heading,
+      kind: inferredKind(arc.heading),
+      dependsOn: previous,
+      expectedOutput: arc.workItems.map((item) => item.detail?.trim() || item.title).join('; '),
+      children,
+    };
+  });
+  validateNodes(nodes);
+  const now = new Date().toISOString();
+  const plan: FabricPlan = { id: randomUUID(), request, status: 'draft', nodes, createdAt: now, updatedAt: now };
+  withLedgerLock(root, () => appendEvent(root, { type: 'plan', plan }));
+  return plan;
+}
+
+export function reviseFabricPlan(root: string, id: string, edits: readonly FabricPlanEdit[]): FabricPlan {
+  return withLedgerLock(root, () => {
+    const current = loadPlanUnlocked(root, id);
+    if (!current) throw new Error(`fabric plan not found: ${id}`);
+    if (current.status !== 'draft' || readEvents(root).some((event) => event.type === 'execution-candidate' && event.candidate.planId === id)) {
+      throw new Error('approved fabric plan cannot be revised');
+    }
+    const ids = new Set(flatten(current.nodes).map((node) => node.id));
+    if (new Set(edits.map((edit) => edit.id)).size !== edits.length || edits.some((edit) => !ids.has(edit.id))) {
+      throw new Error('duplicate or unknown fabric plan edit id');
+    }
+    const byId = new Map(edits.map((edit) => [edit.id, edit]));
+    const apply = (node: FabricPlanNode): FabricPlanNode => {
+      const edit = byId.get(node.id);
+      return { ...node, ...edit, dependsOn: [...(edit?.dependsOn ?? node.dependsOn)], children: node.children.map(apply) };
+    };
+    const nodes = current.nodes.map(apply);
+    validateNodes(nodes);
+    const plan: FabricPlan = { ...current, nodes, updatedAt: new Date().toISOString() };
+    appendEvent(root, { type: 'plan', plan });
+    return plan;
+  });
+}
+
+/** Approval is the sole operation allowed to append an execution candidate. */
+export function approveFabricPlan(root: string, id: string): FabricExecutionCandidate {
+  return withLedgerLock(root, () => {
+    const current = loadPlanUnlocked(root, id);
+    if (!current) throw new Error(`fabric plan not found: ${id}`);
+    if (current.status !== 'draft' || readEvents(root).some((event) => event.type === 'execution-candidate' && event.candidate.planId === id)) {
+      throw new Error('fabric plan already approved');
+    }
+    validateNodes(current.nodes);
+    const approvedAt = new Date().toISOString();
+    const candidate: FabricExecutionCandidate = { planId: id, nodes: current.nodes, approvedAt };
+    appendLines(root, [{ type: 'approved', plan: { ...current, status: 'approved', updatedAt: approvedAt }, candidate }]);
+    return candidate;
+  });
+}

package/src/self-dev/orchestrate.ts

@@ -21,7 +21,8 @@ import { spawn, execFileSync } from 'node:child_process';
 import { emitDecision } from '../live/detail-switch.js';
 import { parentUnlandedProgressLine } from './run-supervisor.js';
 import { mkdirSync, openSync, writeFileSync, closeSync, renameSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { goalPathFromArgv, launchRegistryDir, removeLaunchBinding, writeLaunchBinding } from '../harness/launch-registry.js';
 import { availableParallelism, cpus } from 'node:os';
 import { selfDevRunsDir } from './run-store.js';
 import { HARNESS_RUN_ID_ENV, normalizeRunId } from '../harness/harness-space.js';
@@ -56,6 +57,7 @@ import {
 } from '../task-orchestrator/surfaces/self-implement.js';
 import { collectOrchestrateUnionDiff, type UnionDiffFileReader } from './orchestrate-union-diff.js';
 import { debug } from '../debug/log.js';
+import { parseGoalReleaseNoteSection, type ReleaseNoteSection } from '../release-loop/release-note.js';
 import { readHarnessScreen, readHarnessScreenTail, resolveHarnessScreenKey } from '../harness/harness-screen.js';
 import {
   dedupWorkingMemory,
@@ -101,6 +103,7 @@ export type JobKindRegistry = Readonly<Partial<Record<JobKind, JobKindDefinition
 interface SelfDevShardIdentity {
   orchestrationId: string;
   parentRequest?: string;
+  releaseNote?: ReleaseNoteSection;
   shardId: string;
   totalShards: number;
   position: number;
@@ -199,6 +202,8 @@ export interface SelfDevGoal {
   goalType?: SelfDevGoalType;
   /** Feature/goal text → `elanous self implement <feature>` for dev jobs. */
   feature: string;
+  /** Pod lease predecessor goal ID or PR number. */
+  after?: string | number;
   base?: string;
   autoMerge?: boolean;
   /** G8 — attach `auto-review` opt-in label on PR (subject to eligibility self-assessment). */
@@ -890,6 +895,8 @@ export interface OrchestrateSelfDevOptions {
   runId?: string;
   /** Override the run directory root for isolated tests. */
   runsDir?: string;
+  /** Host-wide run → process binding for `harness stop` across worktrees · `null` = do not write · default: write only when `runsDir` is not overridden. */
+  launchRegistryDir?: string | null;
   /** Signal source and kubectl seams for isolated lifecycle tests. */
   signalSource?: Pick<NodeJS.Process, 'on' | 'off'>;
   /** Pod context/namespace pairs chosen by the caller that launched the Jobs. */
@@ -990,7 +997,7 @@ async function deleteLabelledJobs(runId: string, selectedTargets: readonly { con
 /** `self-dev-runs/<runId>/pid.json` — what `harness stop <runId>` reads (start time guards PID reuse).
  *  HS1: written as soon as the run ID exists, not only when the jobs start — pod planning and image sync can
  *  take minutes before that, and a stop in that window found «no process» (10-01 · three runs). */
-export function writeRunPidRecord(runId: string, runsDir: string = selfDevRunsDir()): string {
+export function writeRunPidRecord(runId: string, runsDir: string = selfDevRunsDir(), registryDir: string | null = launchRegistryDir()): string {
   const pidPath = join(runsDir, runId, 'pid.json');
   mkdirSync(join(runsDir, runId), { recursive: true });
   const temporary = `${pidPath}.${process.pid}.${randomUUID()}.tmp`;
@@ -1001,6 +1008,13 @@ export function writeRunPidRecord(runId: string, runsDir: string = selfDevRunsDi
     } finally { closeSync(fd); }
     renameSync(temporary, pidPath);
   } catch (error) { unlinkSync(temporary); throw error; }
+  // A stop from another worktree/universe cannot see this pid.json — leave the same binding in the host-wide registry.
+  if (registryDir !== null) {
+    const cwd = process.cwd();
+    const goalPath = goalPathFromArgv(process.argv, cwd);
+    writeLaunchBinding(runId, { pid: process.pid, startedAt: Date.now() - Math.floor(process.uptime() * 1000), argv0: process.argv0,
+      cwd, ...(goalPath ? { goalPath } : {}), runsDir: resolve(runsDir) }, registryDir);
+  }
   return pidPath;
 }
 
@@ -1013,6 +1027,8 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
   const runId = opts.runId ?? process.env[HARNESS_RUN_ID_ENV];
   if (runId && runId !== normalizeRunId(runId)) throw new Error(`invalid self-dev run ID: ${runId}`);
   const pidPath = runId ? join(opts.runsDir ?? selfDevRunsDir(), runId, 'pid.json') : undefined;
+  // Only the real run directory gets a host-wide binding by default — an overridden runsDir is an isolated test.
+  const registryDir = opts.launchRegistryDir !== undefined ? opts.launchRegistryDir : opts.runsDir === undefined ? launchRegistryDir() : null;
   const graph = new TaskGraph();
   const bus = new TaskEventBus();
   const registry = new SurfaceRegistry();
@@ -1186,6 +1202,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
     surface: (goal) => ({
       kind: 'self-implement',
       feature: goal.feature,
+      ...(goal.after !== undefined ? { after: goal.after } : {}),
       ...(goal.base !== undefined ? { base: goal.base } : {}),
       ...(goal.autoMerge !== undefined ? { autoMerge: goal.autoMerge } : {}),
       ...(goal.autoReview !== undefined ? { autoReview: goal.autoReview } : {}),
@@ -1307,6 +1324,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
   });
 
   if (opts.goals.length > 0) {
+    const releaseNote = opts.parentRequest === undefined ? undefined : parseGoalReleaseNoteSection(opts.parentRequest).fragment;
     const orchestrationId = randomUUID();
     const shards = opts.goals.map((goal, index) => ({
       goal,
@@ -1320,6 +1338,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
       const identity: SelfDevShardIdentity = {
         orchestrationId,
         ...(opts.parentRequest === undefined ? {} : { parentRequest: opts.parentRequest }),
+        ...(releaseNote ? { releaseNote } : {}),
         shardId: shard.shardId,
         totalShards: shards.length,
         position: shard.position,
@@ -1328,7 +1347,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
           .filter((sibling) => sibling !== shard)
           .map(({ shardId, summary }) => ({ shardId, summary })),
       };
-        const task = graph.getTask(taskId);
+      const task = graph.getTask(taskId);
       if (task?.surface.kind === 'self-implement') {
         graph.updateTask(taskId, {
           surface: { ...task.surface, feature: shardIdentityFeature(shard.goal.feature, identity) },
@@ -1401,6 +1420,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
         catch (error) {
           if ((error as NodeJS.ErrnoException).code !== 'ENOENT') debug.log('self-dev.orchestrate', 'pid-cleanup-failed', { pidPath, error: String(error) }, { level: 'warn' });
         }
+        if (registryDir !== null) removeLaunchBinding(runId!, registryDir);
       }
     };
     const cancel = (signal: NodeJS.Signals): void => {
@@ -1436,7 +1456,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
     signals.on('SIGTERM', onTerm);
     signals.on('SIGINT', onInt);
     try {
-      if (pidPath) writeRunPidRecord(runId!, opts.runsDir ?? selfDevRunsDir());
+      if (pidPath) writeRunPidRecord(runId!, opts.runsDir ?? selfDevRunsDir(), registryDir);
     } catch (error) { cleanup(); reject(error); return; }
 
     // Current full result set: resumed-done goals + each running task's
@@ -1488,6 +1508,18 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
       if (settled) return;
       settled = true;
       const out = buildResults();
+      for (const result of out) {
+        try {
+          debug.log('self-implement.result', 'final', {
+            runId: result.runId ?? null,
+            taskId: result.taskId,
+            stage: result.stage ?? null,
+            mergeReason: result.mergeReason ?? null,
+            failureClassification: result.failureClassification ?? null,
+            prNumber: result.prNumber ?? null,
+          });
+        } catch { /* terminal observation must not change the result */ }
+      }
       // S3 — teardown (opt-in): remove each job's worktree (fail-soft),
       // preserving any job that opened a PR (branch/worktree still needed).
       if (opts.teardown === true && !cancelling) {

package/src/self-dev/release-path-guard.ts

@@ -0,0 +1,62 @@
+// Release path = what publishing reads directly: the release scripts and graph, plus the manifest, release notes and cut schedule
+// in `src/release-loop/`. The checklist store (`checklist.ts`, `feature-store.ts`) is shared ops ledger code — the gate catches its regressions (OP 10-03).
+export const RELEASE_PATH_PREFIXES = ['scripts/release-loop/', 'graphs/release/', 'src/release-loop/manifest', 'src/release-loop/release-note', 'src/release-loop/release-schedule'] as const;
+export const RELEASE_PATH_LABEL = 'elanous:release-path';
+
+/** Flatten every GitHub PR file page, including the source of a rename. */
+export function releasePrFilePaths(pages: unknown): string[] {
+  if (!Array.isArray(pages) || pages.length === 0 || !pages.every((page: unknown) => Array.isArray(page) && page.every((file: unknown) =>
+    !!file && typeof file === 'object' && 'filename' in file && typeof file.filename === 'string'
+      && (!('previous_filename' in file) || typeof file.previous_filename === 'string')
+      && (!('status' in file) || file.status !== 'renamed' || ('previous_filename' in file && typeof file.previous_filename === 'string'))))) {
+    throw new Error('gh api PR files returned an invalid file list');
+  }
+  return pages.flatMap((page: Array<{ filename: string; previous_filename?: string }>) =>
+    page.flatMap((file) => file.previous_filename ? [file.filename, file.previous_filename] : [file.filename]));
+}
+
+/** git diff --name-status -z emits status then one path (or two for rename/copy). */
+export function releaseGitDiffPaths(output: string): string[] {
+  const tokens = output.split('\0');
+  if (tokens.pop() !== '') throw new Error('invalid NUL-delimited git diff');
+  const paths: string[] = [];
+  for (let i = 0; i < tokens.length;) {
+    const status = tokens[i++];
+    if (!status || !/^[ACDMRTUXB][0-9]*$/.test(status)) throw new Error('invalid git diff status');
+    const count = /^[RC]/.test(status) ? 2 : 1;
+    for (let n = 0; n < count; n++) {
+      const path = tokens[i++];
+      if (!path) throw new Error('missing git diff path');
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+
+/** Evaluate the paths from the opened PR, not the requested goal or local working tree. */
+export function releasePathHold(paths: readonly string[]): string | undefined {
+  return paths.find((path) => RELEASE_PATH_PREFIXES.some((prefix) => path.startsWith(prefix)));
+}
+
+/** Fixed opening of the hold comment — also how a PR held by several merge surfaces (or polls) is recognised, so it is posted once. */
+export const RELEASE_PATH_HOLD_MARKER = 'OP approval required: automatic merge held because this PR changes ';
+
+export function releasePathHoldComment(path: string): string {
+  return `${RELEASE_PATH_HOLD_MARKER}${path}.`;
+}
+
+/** True when the PR's issue-comment pages (gh api --paginate --slurp) already carry a hold comment. */
+export function releasePathHoldAlreadyPosted(pages: unknown): boolean {
+  if (!Array.isArray(pages)) throw new Error('gh api PR comments returned an invalid list');
+  return pages.some((page: unknown) => Array.isArray(page) && page.some((comment: unknown) =>
+    !!comment && typeof comment === 'object' && 'body' in comment && typeof comment.body === 'string' && comment.body.startsWith(RELEASE_PATH_HOLD_MARKER)));
+}
+
+/** Unknown comment history must not drop the hold comment: when it cannot be read, post (a duplicate beats a silent hold). */
+export function releasePathHoldShouldPost(readPages: () => unknown): boolean {
+  try { return !releasePathHoldAlreadyPosted(readPages()); } catch { return true; }
+}
+
+export function releasePathHoldCommentsArgs(pr: string | number): string[] {
+  return ['api', '--paginate', '--slurp', '--method', 'GET', '-f', 'per_page=100', `repos/{owner}/{repo}/issues/${pr}/comments`];
+}