@monoes/monodesign 1.2.18 → 1.2.22

package/skill/scripts/live/manual-apply.mjs

@@ -1,16 +1,73 @@
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { getLiveDir } from '../lib/monodesign-paths.mjs';
-import { readBuffer as readManualEditsBuffer } from './manual-edits-buffer.mjs';
-
 const APPLY_EVENT_HARD_TIMEOUT_MS = Number(process.env.MONODESIGN_LIVE_APPLY_EVENT_HARD_TIMEOUT_MS || 150_000);
 const APPLY_EVENT_SOFT_DEADLINE_MS = Number(process.env.MONODESIGN_LIVE_APPLY_EVENT_SOFT_DEADLINE_MS || 120_000);
-const DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE = 3;
-const MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE = 1;
-const MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE = 20;
-const MANUAL_APPLY_COMPACT_TEXT_LIMIT = 240;
-const MANUAL_APPLY_COMPACT_NEARBY_LIMIT = 4;
+
+import {
+  collectManualApplyFiles,
+  manualApplyEvidenceDir,
+  normalizeManualApplyEvidencePath,
+  removeManualApplyEvidence,
+  rollbackApplySnapshot,
+  snapshotApplyEventFiles,
+  writeManualApplyEvidence,
+} from './manual-apply-evidence.mjs';
+import { compactManualApplyBatch } from './manual-apply-compact.mjs';
+import {
+  countManualApplyOps,
+  firstFailureReason,
+  manualEditApplyChunkSize,
+  markChunkEntriesFailed,
+  normalizeApplyChunkResult,
+  splitManualApplyBatch,
+} from './manual-apply-chunk.mjs';
+import {
+  buildManualApplyAgentAction,
+  summarizeManualApplyEvent,
+  validateManualApplyResultMessage,
+} from './manual-apply-log.mjs';
+import {
+  clearManualApplyTransaction,
+  readManualApplyTransaction,
+  rollbackManualApplyTransaction,
+  writeManualApplyTransaction,
+} from './manual-apply-transaction.mjs';
+
+export {
+  collectManualApplyFiles,
+  manualApplyEvidenceDir,
+  normalizeManualApplyEvidencePath,
+  removeManualApplyEvidence,
+  rollbackApplySnapshot,
+  snapshotApplyEventFiles,
+  writeManualApplyEvidence,
+} from './manual-apply-evidence.mjs';
+export {
+  compactManualApplyBatch,
+  compactManualApplyCandidates,
+} from './manual-apply-compact.mjs';
+export {
+  countManualApplyOps,
+  manualEditApplyChunkSize,
+  splitManualApplyBatch,
+} from './manual-apply-chunk.mjs';
+export {
+  buildManualApplyAgentAction,
+  compactManualLogText,
+  summarizeManualApplyEvent,
+  summarizeManualApplyFailures,
+  summarizeManualDiagnostics,
+  summarizeManualLogFile,
+  validateManualApplyResultMessage,
+} from './manual-apply-log.mjs';
+export {
+  clearManualApplyTransaction,
+  manualApplyTransactionPath,
+  readManualApplyTransaction,
+  rollbackManualApplyTransaction,
+  writeManualApplyTransaction,
+} from './manual-apply-transaction.mjs';
 
 export function createManualApplyController({
   pendingEvents,
@@ -305,635 +362,3 @@ export function createManualApplyController({
     writeTransaction: (opts = {}) => writeManualApplyTransaction({ cwd: projectCwd(), ...opts }),
   };
 }
-
-export function manualEditApplyChunkSize(env = process.env) {
-  const raw = Number(env.MONODESIGN_LIVE_MANUAL_EDIT_CHUNK_SIZE);
-  if (!Number.isFinite(raw)) return DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE;
-  const size = Math.trunc(raw);
-  return Math.max(MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE, Math.min(MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE, size));
-}
-
-export function countManualApplyOps(entriesOrBatch) {
-  const entries = Array.isArray(entriesOrBatch)
-    ? entriesOrBatch
-    : Array.isArray(entriesOrBatch?.entries) ? entriesOrBatch.entries : [];
-  let count = 0;
-  for (const entry of entries) count += Array.isArray(entry.ops) ? entry.ops.length : 0;
-  return count;
-}
-
-export function writeManualApplyEvidence(eventId, batch, cwd = process.cwd()) {
-  const dir = manualApplyEvidenceDir(cwd);
-  fs.mkdirSync(dir, { recursive: true });
-  const evidencePath = path.join(dir, `${eventId}.json`);
-  fs.writeFileSync(evidencePath, `${JSON.stringify(batch, null, 2)}\n`, 'utf-8');
-  return evidencePath;
-}
-
-export function manualApplyEvidenceDir(cwd = process.cwd()) {
-  return path.join(getLiveDir(cwd), 'manual-edit-evidence');
-}
-
-export function normalizeManualApplyEvidencePath(evidencePath, cwd = process.cwd()) {
-  if (!evidencePath || typeof evidencePath !== 'string') return null;
-  const fullPath = path.isAbsolute(evidencePath) ? evidencePath : path.resolve(cwd, evidencePath);
-  const evidenceDir = manualApplyEvidenceDir(cwd);
-  const relative = path.relative(evidenceDir, fullPath).split(path.sep).join('/');
-  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
-  if (path.extname(relative) !== '.json') return null;
-  return fullPath;
-}
-
-export function removeManualApplyEvidence(evidencePath, cwd = process.cwd()) {
-  const fullPath = normalizeManualApplyEvidencePath(evidencePath, cwd);
-  if (!fullPath) return false;
-  try {
-    fs.unlinkSync(fullPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function compactManualApplyBatch(batch = {}, cwd = process.cwd()) {
-  const entries = (batch.entries || []).map(compactManualApplyEntry);
-  const candidates = compactManualApplyCandidates(batch.candidates || [], cwd);
-  return {
-    version: batch.version,
-    pageUrl: batch.pageUrl || null,
-    count: batch.count,
-    entries,
-    ops: entries.flatMap((entry) => entry.ops.map((op) => ({ ...op, entryId: entry.id }))),
-    candidates: candidates.length > 0 ? candidates : undefined,
-    context: batch.context ? {
-      bufferPath: batch.context.bufferPath,
-      totalEntries: batch.context.totalEntries,
-      totalOps: batch.context.totalOps,
-      chunkIndex: batch.context.chunkIndex,
-      chunkTotal: batch.context.chunkTotal,
-      totalApplyOps: batch.context.totalApplyOps,
-    } : undefined,
-  };
-}
-
-export function compactManualApplyCandidates(candidates, cwd = process.cwd()) {
-  return (Array.isArray(candidates) ? candidates : [])
-    .slice(0, 24)
-    .map((candidate) => ({
-      entryId: candidate.entryId,
-      ref: candidate.ref,
-      sourceHint: compactManualApplySourceMatch(candidate.sourceHint, cwd),
-      textMatches: compactManualApplySourceMatches(candidate.textMatches, 8, cwd),
-      objectKeyMatches: compactManualApplySourceMatches(candidate.objectKeyMatches, 8, cwd),
-      contextTextMatches: compactManualApplySourceMatches(candidate.contextTextMatches, 8, cwd),
-      locatorMatches: compactManualApplySourceMatches(candidate.locatorMatches, 6, cwd),
-    }));
-}
-
-function compactManualApplySourceMatches(matches, limit, cwd) {
-  return (Array.isArray(matches) ? matches : [])
-    .slice(0, limit)
-    .map((match) => compactManualApplySourceMatch(match, cwd))
-    .filter(Boolean);
-}
-
-function compactManualApplySourceMatch(match, cwd) {
-  if (!match || typeof match !== 'object') return null;
-  const file = match.relativeFile || match.file;
-  if (!file && !match.line) return null;
-  return {
-    file: summarizeManualLogFile(file, cwd),
-    line: match.line || null,
-    column: match.column || null,
-    reason: match.reason || match.kind || undefined,
-    status: match.status || undefined,
-  };
-}
-
-function compactManualApplyEntry(entry = {}) {
-  return {
-    id: entry.id,
-    pageUrl: entry.pageUrl,
-    stagedAt: entry.stagedAt || null,
-    element: compactManualApplyContext(entry.element),
-    ops: (entry.ops || []).map(compactManualApplyOp),
-  };
-}
-
-function compactManualApplyOp(op = {}) {
-  return {
-    entryId: op.entryId,
-    ref: op.ref,
-    contextRef: op.contextRef,
-    tag: op.tag,
-    elementId: op.elementId,
-    classes: Array.isArray(op.classes) ? op.classes : [],
-    originalText: op.originalText,
-    newText: op.newText,
-    deleted: op.deleted === true || undefined,
-    sourceHint: op.sourceHint || null,
-    leaf: compactManualApplyContext(op.leaf),
-    nearbyEditableTexts: compactNearbyManualEditTexts(op.nearbyEditableTexts),
-    container: compactManualApplyContext(op.container),
-    contextHints: Array.isArray(op.contextHints) ? op.contextHints.slice(0, 8) : undefined,
-  };
-}
-
-function compactManualApplyContext(value) {
-  if (!value || typeof value !== 'object') return null;
-  return {
-    ref: value.ref,
-    tagName: value.tagName || value.tag || null,
-    id: value.id || null,
-    classes: Array.isArray(value.classes) ? value.classes : [],
-    textContent: truncateManualApplyText(value.textContent, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
-  };
-}
-
-function compactNearbyManualEditTexts(items) {
-  return (Array.isArray(items) ? items : [])
-    .slice(0, MANUAL_APPLY_COMPACT_NEARBY_LIMIT)
-    .map((item) => typeof item === 'string' ? { text: truncateManualApplyText(item, MANUAL_APPLY_COMPACT_TEXT_LIMIT) } : {
-      ref: item?.ref,
-      tag: item?.tag,
-      classes: Array.isArray(item?.classes) ? item.classes : [],
-      text: truncateManualApplyText(item?.text, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
-    });
-}
-
-function truncateManualApplyText(value, max) {
-  if (typeof value !== 'string') return value || null;
-  return value.length > max ? value.slice(0, max) : value;
-}
-
-function normalizeApplyChunkResult(result) {
-  const status = result?.status === 'partial' ? 'partial' : result?.status === 'error' ? 'error' : 'done';
-  return {
-    status,
-    message: typeof result?.message === 'string' ? result.message : null,
-    appliedEntryIds: Array.isArray(result?.appliedEntryIds) ? result.appliedEntryIds.filter((id) => typeof id === 'string') : [],
-    failed: Array.isArray(result?.failed) ? result.failed.filter(Boolean) : [],
-    files: Array.isArray(result?.files) ? result.files.filter((file) => typeof file === 'string') : [],
-    notes: Array.isArray(result?.notes) ? result.notes.filter((note) => typeof note === 'string') : [],
-  };
-}
-
-function manualApplyResultShapeHint(eventId = 'EVENT_ID') {
-  return `Use live-poll.mjs --reply ${eventId} done --data '{"status":"done","appliedEntryIds":["ENTRY_ID"],"failed":[],"files":["src/page.html"],"notes":[]}'`;
-}
-
-function invalidManualApplyResult(reason, eventId, extra = {}) {
-  return {
-    ok: false,
-    body: {
-      error: 'invalid_manual_apply_result',
-      reason,
-      hint: manualApplyResultShapeHint(eventId),
-      ...extra,
-    },
-  };
-}
-
-export function validateManualApplyResultMessage(msg, deferred) {
-  const data = msg?.data;
-  const eventId = msg?.id || deferred?.event?.id || 'EVENT_ID';
-  if (!data || typeof data !== 'object' || Array.isArray(data)) {
-    return invalidManualApplyResult('missing_result_data', eventId);
-  }
-  if ('entries' in data || 'ops' in data) {
-    return invalidManualApplyResult('summary_result_not_allowed', eventId);
-  }
-  if (!['done', 'partial', 'error'].includes(data.status)) {
-    return invalidManualApplyResult('invalid_status', eventId, { status: data.status ?? null });
-  }
-
-  for (const key of ['appliedEntryIds', 'failed', 'files', 'notes']) {
-    if (!Array.isArray(data[key])) {
-      return invalidManualApplyResult(`${key}_must_be_array`, eventId);
-    }
-  }
-
-  for (const [index, value] of data.appliedEntryIds.entries()) {
-    if (typeof value !== 'string' || !value) {
-      return invalidManualApplyResult('appliedEntryIds_must_contain_strings', eventId, { index });
-    }
-  }
-  for (const [index, value] of data.files.entries()) {
-    if (typeof value !== 'string' || !value) {
-      return invalidManualApplyResult('files_must_contain_strings', eventId, { index });
-    }
-  }
-  for (const [index, value] of data.notes.entries()) {
-    if (typeof value !== 'string') {
-      return invalidManualApplyResult('notes_must_contain_strings', eventId, { index });
-    }
-  }
-  for (const [index, item] of data.failed.entries()) {
-    if (!item || typeof item !== 'object' || Array.isArray(item)) {
-      return invalidManualApplyResult('failed_must_contain_objects', eventId, { index });
-    }
-    if (typeof item.entryId !== 'string' || !item.entryId) {
-      return invalidManualApplyResult('failed_entryId_required', eventId, { index });
-    }
-    if (typeof item.reason !== 'string' || !item.reason) {
-      return invalidManualApplyResult('failed_reason_required', eventId, { index });
-    }
-  }
-
-  const eventEntryIds = new Set((deferred?.batch?.entries || []).map((entry) => entry.id).filter(Boolean));
-  for (const entryId of data.appliedEntryIds) {
-    if (eventEntryIds.size > 0 && !eventEntryIds.has(entryId)) {
-      return invalidManualApplyResult('applied_entry_id_not_in_event', eventId, { entryId });
-    }
-  }
-  for (const item of data.failed) {
-    if (eventEntryIds.size > 0 && !eventEntryIds.has(item.entryId)) {
-      return invalidManualApplyResult('failed_entry_id_not_in_event', eventId, { entryId: item.entryId });
-    }
-  }
-
-  if (data.status === 'done') {
-    if (data.failed.length > 0) {
-      return invalidManualApplyResult('done_result_has_failed_entries', eventId);
-    }
-    if (countManualApplyOps(deferred?.batch) > 0 && data.appliedEntryIds.length === 0) {
-      return invalidManualApplyResult('done_result_missing_applied_entry_ids', eventId);
-    }
-  }
-  if (data.status === 'partial' && data.appliedEntryIds.length === 0 && data.failed.length === 0) {
-    return invalidManualApplyResult('partial_result_has_no_entries', eventId);
-  }
-  if (data.status === 'error' && data.appliedEntryIds.length > 0) {
-    return invalidManualApplyResult('error_result_has_applied_entries', eventId);
-  }
-
-  return {
-    ok: true,
-    result: {
-      status: data.status,
-      message: typeof data.message === 'string' ? data.message : undefined,
-      appliedEntryIds: data.appliedEntryIds,
-      failed: data.failed,
-      files: data.files,
-      notes: data.notes,
-    },
-  };
-}
-
-function firstFailureReason(result) {
-  const first = Array.isArray(result?.failed) ? result.failed.find(Boolean) : null;
-  return first?.reason || first?.message || null;
-}
-
-function markChunkEntriesFailed(failedByEntry, chunk, reason) {
-  for (const entryId of chunk.entryIds) {
-    if (failedByEntry.has(entryId)) continue;
-    failedByEntry.set(entryId, { entryId, reason, candidates: [] });
-  }
-}
-
-export function splitManualApplyBatch(batch, maxOps) {
-  const totalOpCount = countManualApplyOps(batch);
-  if (totalOpCount <= maxOps) {
-    return [{
-      batch,
-      meta: null,
-      entryIds: new Set((batch?.entries || []).map((entry) => entry.id).filter(Boolean)),
-      opCountsByEntry: new Map((batch?.entries || []).map((entry) => [entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0])),
-    }];
-  }
-
-  const rawChunks = [];
-  let current = createManualApplyChunkBuilder();
-  for (const entry of batch?.entries || []) {
-    const ops = entry.ops || [];
-    if (ops.length <= maxOps) {
-      if (current.opCount > 0 && current.opCount + ops.length > maxOps) {
-        rawChunks.push(current);
-        current = createManualApplyChunkBuilder();
-      }
-      for (const op of ops) addOpToManualApplyChunk(current, entry, op);
-      continue;
-    }
-    if (current.opCount > 0) {
-      rawChunks.push(current);
-      current = createManualApplyChunkBuilder();
-    }
-    for (const op of ops) {
-      if (current.opCount >= maxOps) {
-        rawChunks.push(current);
-        current = createManualApplyChunkBuilder();
-      }
-      addOpToManualApplyChunk(current, entry, op);
-    }
-  }
-  if (current.opCount > 0) rawChunks.push(current);
-
-  return rawChunks.map((chunk, index) => ({
-    batch: {
-      ...batch,
-      count: chunk.opCount,
-      entries: chunk.entries,
-      ops: chunk.ops,
-      candidates: filterManualApplyChunkCandidates(batch, chunk.refsByEntry),
-      context: {
-        ...(batch?.context || {}),
-        totalEntries: chunk.entries.length,
-        totalOps: chunk.opCount,
-        chunkIndex: index + 1,
-        chunkTotal: rawChunks.length,
-        totalApplyOps: totalOpCount,
-      },
-    },
-    meta: {
-      index: index + 1,
-      total: rawChunks.length,
-      opCount: chunk.opCount,
-      totalOpCount,
-    },
-    entryIds: new Set(chunk.entries.map((entry) => entry.id).filter(Boolean)),
-    opCountsByEntry: chunk.opCountsByEntry,
-  }));
-}
-
-function createManualApplyChunkBuilder() {
-  return {
-    entries: [],
-    entryById: new Map(),
-    entryIds: new Set(),
-    ops: [],
-    refsByEntry: new Map(),
-    opCountsByEntry: new Map(),
-    opCount: 0,
-  };
-}
-
-function addOpToManualApplyChunk(chunk, entry, op) {
-  let chunkEntry = chunk.entryById.get(entry.id);
-  if (!chunkEntry) {
-    chunkEntry = { ...entry, ops: [] };
-    chunk.entryById.set(entry.id, chunkEntry);
-    chunk.entryIds.add(entry.id);
-    chunk.entries.push(chunkEntry);
-  }
-  chunkEntry.ops.push(op);
-  chunk.ops.push({ ...op, entryId: op.entryId || entry.id });
-  if (!chunk.refsByEntry.has(entry.id)) chunk.refsByEntry.set(entry.id, new Set());
-  if (op.ref) chunk.refsByEntry.get(entry.id).add(op.ref);
-  chunk.opCountsByEntry.set(entry.id, (chunk.opCountsByEntry.get(entry.id) || 0) + 1);
-  chunk.opCount += 1;
-}
-
-function filterManualApplyChunkCandidates(batch, refsByEntry) {
-  return (batch?.candidates || []).filter((candidate) => {
-    const refs = refsByEntry.get(candidate.entryId);
-    if (!refs) return false;
-    if (!candidate.ref) return true;
-    return refs.has(candidate.ref);
-  });
-}
-
-export function snapshotApplyEventFiles(batch, cwd = process.cwd()) {
-  const snapshot = new Map();
-  for (const relativeFile of collectManualApplyFiles(batch, [], cwd)) {
-    const absolute = path.resolve(cwd, relativeFile);
-    try {
-      snapshot.set(relativeFile, {
-        exists: fs.existsSync(absolute),
-        content: fs.existsSync(absolute) ? fs.readFileSync(absolute, 'utf-8') : '',
-      });
-    } catch {
-      // If a file cannot be read before dispatch, do not attempt late rollback.
-    }
-  }
-  return snapshot;
-}
-
-export function manualApplyTransactionPath(cwd = process.cwd()) {
-  return path.join(getLiveDir(cwd), 'manual-edit-apply-transaction.json');
-}
-
-export function readManualApplyTransaction(cwd = process.cwd()) {
-  const file = manualApplyTransactionPath(cwd);
-  if (!fs.existsSync(file)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-export function writeManualApplyTransaction({ cwd = process.cwd(), pageUrl = null, batch }) {
-  const file = manualApplyTransactionPath(cwd);
-  const files = collectManualApplyFiles(batch, [], cwd);
-  const transaction = {
-    version: 1,
-    id: randomUUID().replace(/-/g, '').slice(0, 8),
-    createdAt: new Date().toISOString(),
-    pageUrl,
-    entryIds: (batch?.entries || []).map((entry) => entry.id).filter(Boolean),
-    files: files.map((relativeFile) => {
-      const absolute = path.resolve(cwd, relativeFile);
-      const exists = fs.existsSync(absolute);
-      return {
-        file: relativeFile,
-        exists,
-        content: exists ? fs.readFileSync(absolute, 'utf-8') : '',
-      };
-    }),
-  };
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(transaction, null, 2)}\n`, 'utf-8');
-  fs.renameSync(`${file}.tmp`, file);
-  return transaction;
-}
-
-export function clearManualApplyTransaction(cwd = process.cwd(), transactionId = null) {
-  const file = manualApplyTransactionPath(cwd);
-  if (!fs.existsSync(file)) return false;
-  if (transactionId) {
-    const existing = readManualApplyTransaction(cwd);
-    if (existing?.id && existing.id !== transactionId) return false;
-  }
-  try {
-    fs.unlinkSync(file);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function rollbackManualApplyTransaction({
-  cwd = process.cwd(),
-  pageUrl = null,
-  reason = 'manual_edit_transaction_rollback',
-  recordManualEditActivity = null,
-} = {}) {
-  const transaction = readManualApplyTransaction(cwd);
-  if (!transaction) return null;
-  if (pageUrl && transaction.pageUrl && transaction.pageUrl !== pageUrl) return null;
-
-  let pendingIds = new Set();
-  try {
-    const buffer = readManualEditsBuffer(cwd);
-    pendingIds = new Set((buffer.entries || []).map((entry) => entry.id).filter(Boolean));
-  } catch {
-    pendingIds = new Set(transaction.entryIds || []);
-  }
-  const shouldRollback = (transaction.entryIds || []).some((id) => pendingIds.has(id));
-  if (!shouldRollback) {
-    clearManualApplyTransaction(cwd, transaction.id);
-    return { id: transaction.id, reason, rolledBackFiles: [], rollbackFailures: [], skipped: 'entries_not_pending' };
-  }
-
-  const rolledBackFiles = [];
-  const rollbackFailures = [];
-  for (const item of transaction.files || []) {
-    const relativeFile = normalizeProjectFile(item.file, cwd);
-    if (!relativeFile) continue;
-    const absolute = path.resolve(cwd, relativeFile);
-    try {
-      if (item.exists) {
-        fs.mkdirSync(path.dirname(absolute), { recursive: true });
-        fs.writeFileSync(absolute, item.content || '', 'utf-8');
-      } else if (fs.existsSync(absolute)) {
-        fs.rmSync(absolute);
-      }
-      rolledBackFiles.push(relativeFile);
-    } catch (err) {
-      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
-    }
-  }
-  clearManualApplyTransaction(cwd, transaction.id);
-  recordManualEditActivity?.('manual_edit_transaction_rolled_back', {
-    id: transaction.id,
-    pageUrl: transaction.pageUrl || null,
-    reason,
-    entryIds: transaction.entryIds || [],
-    rolledBackFiles: rolledBackFiles.map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean),
-    rollbackFailures: summarizeManualDiagnostics(rollbackFailures, cwd),
-  });
-  return { id: transaction.id, reason, rolledBackFiles, rollbackFailures };
-}
-
-export function collectManualApplyFiles(batch, extraFiles = [], cwd = process.cwd()) {
-  const files = [];
-  for (const entry of batch?.entries || []) {
-    for (const op of entry.ops || []) files.push(op.sourceHint?.file);
-  }
-  for (const candidate of batch?.candidates || []) {
-    files.push(candidate.sourceHint?.relativeFile, candidate.sourceHint?.file);
-    for (const item of candidate.textMatches || []) files.push(item.file);
-    for (const item of candidate.objectKeyMatches || []) files.push(item.file);
-    for (const item of candidate.locatorMatches || []) files.push(item.file);
-    for (const item of candidate.contextTextMatches || []) files.push(item.file);
-  }
-  files.push(...(extraFiles || []));
-  return [...new Set(files)]
-    .map((file) => normalizeProjectFile(file, cwd))
-    .filter(Boolean);
-}
-
-function normalizeProjectFile(file, cwd = process.cwd()) {
-  if (!file || typeof file !== 'string') return null;
-  const absolute = path.isAbsolute(file) ? file : path.resolve(cwd, file);
-  const relative = path.relative(cwd, absolute).split(path.sep).join('/');
-  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
-  return relative;
-}
-
-export function rollbackApplySnapshot(
-  batch,
-  rollbackSnapshot,
-  extraFiles = [],
-  _reason = 'manual_edit_apply_snapshot_rollback',
-  cwd = process.cwd(),
-) {
-  const scope = collectManualApplyFiles(batch, extraFiles, cwd);
-  const rolledBackFiles = [];
-  const rollbackFailures = [];
-  for (const relativeFile of scope) {
-    const before = rollbackSnapshot?.get(relativeFile);
-    if (!before) continue;
-    const absolute = path.resolve(cwd, relativeFile);
-    try {
-      if (before.exists) {
-        fs.mkdirSync(path.dirname(absolute), { recursive: true });
-        fs.writeFileSync(absolute, before.content, 'utf-8');
-      } else if (fs.existsSync(absolute)) {
-        fs.rmSync(absolute);
-      }
-      rolledBackFiles.push(relativeFile);
-    } catch (err) {
-      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
-    }
-  }
-  return { rolledBackFiles, rollbackFailures };
-}
-
-function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
-  const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
-  return `live-poll.mjs --reply ${id} done --data '<json>'`;
-}
-
-export function buildManualApplyAgentAction(eventOrId = 'EVENT_ID') {
-  return {
-    kind: 'manual_edit_apply',
-    required: 'apply_source_edits_then_reply',
-    replyCommand: manualApplyReplyCommand(eventOrId),
-    warning: 'Polling only leases this work item; it does not commit source edits.',
-  };
-}
-
-export function summarizeManualApplyEvent(event = {}, batch = event.batch, cwd = process.cwd()) {
-  const entries = Array.isArray(batch?.entries) ? batch.entries : [];
-  const opCount = entries.reduce((sum, entry) => sum + (Array.isArray(entry.ops) ? entry.ops.length : 0), 0);
-  return {
-    pageUrl: event.pageUrl || null,
-    chunk: event.chunk || null,
-    entryCount: entries.length,
-    opCount,
-    files: collectManualApplyFiles(batch, [], cwd),
-  };
-}
-
-export function summarizeManualApplyFailures(failed, cwd = process.cwd()) {
-  if (!Array.isArray(failed)) return [];
-  return failed.slice(0, 20).map((item) => ({
-    id: item.id || item.entryId || null,
-    reason: item.reason || item.message || 'failed',
-    message: compactManualLogText(item.message, 300),
-    files: Array.isArray(item.files) ? item.files.slice(0, 12).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
-    checks: summarizeManualDiagnostics(item.checks, cwd),
-    failures: summarizeManualDiagnostics(item.failures, cwd),
-    candidates: summarizeManualDiagnostics(item.candidates, cwd),
-  }));
-}
-
-export function summarizeManualDiagnostics(items, cwd = process.cwd()) {
-  if (!Array.isArray(items) || items.length === 0) return undefined;
-  return items.slice(0, 12).map((item) => ({
-    reason: item.reason || item.kind || undefined,
-    detail: compactManualLogText(item.detail, 220),
-    message: compactManualLogText(item.message, 300),
-    file: summarizeManualLogFile(item.file || item.relativeFile, cwd),
-    line: item.line || undefined,
-    ref: compactManualLogText(item.ref, 180),
-    marker: compactManualLogText(item.marker, 120),
-    files: Array.isArray(item.files) ? item.files.slice(0, 8).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
-  }));
-}
-
-export function summarizeManualLogFile(file, cwd = process.cwd()) {
-  if (!file || typeof file !== 'string') return undefined;
-  if (!path.isAbsolute(file)) return file;
-  const relative = path.relative(cwd, file).split(path.sep).join('/');
-  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
-}
-
-export function compactManualLogText(value, max = 200) {
-  if (typeof value !== 'string') return undefined;
-  const normalized = value.replace(/\s+/g, ' ').trim();
-  if (normalized.length <= max) return normalized;
-  return `${normalized.slice(0, max)}... [truncated ${normalized.length - max} chars]`;
-}