@marktrue/dsh-mobile-remote 3.2.2-alpha.1 → 3.2.2-rc.1-app

package/lib/plugin-update-controller.js

@@ -1,274 +0,0 @@
-// Admission owns the durable transaction and its lease; the worker consumes exactly the accepted release.
-import { homedir } from 'node:os';
-import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { acquireLock, newOperationId, readTransaction, releaseLock, serverOperationPath, finishOwnedTerminal,
-  transactionFile, updateLockPath, validOperationId, writeOwnedTransaction, convergeStaleTransaction, workRoot } from './plugin-update-transaction.js';
-import { checkForUpdate, prepareNpmArtifacts, runSelfUpdate, isTerminalPhase, resolvePluginUpdateSource, UPDATE_SOURCE_KIND } from './plugin-self-update.js';
-import { createOperationLog } from './plugin-update-log.js';
-
-/// 客户端可达视图：只改写属于**本机回环主机源**的 artifact 路由，外部发布源保持原样（F1）。
-export function clientReleaseView(release, { clientOrigin = '', basePath = '/m', loopback = false } = {}) {
-  if (!release || !clientOrigin || !loopback) return release;
-  const mount = basePath === '/' || basePath === '' ? '/m' : String(basePath).replace(/\/$/, '');
-  return {
-    ...release,
-    manifestUrl: `${clientOrigin}${mount}/api/update/manifest`,
-    app: release.app ? { ...release.app, url: `${clientOrigin}${mount}/api/update/apk` } : release.app,
-    plugin: { ...release.plugin, url: `${clientOrigin}${mount}/api/update/plugin` },
-  };
-}
-function safeUpdateReason(reason) {
-  const value = typeof reason === 'string' ? reason : '';
-  return /^[a-z0-9][a-z0-9._-]{0,96}$/i.test(value) ? value : 'update-failed';
-}
-
-export function publicTransaction(tx, view = {}) {
-  if (!tx) return null;
-  const { opId, phase, targetVersion, targetContentSha256, targetAppVersion, rolledBack, attempts, result, startedAt, release } = tx;
-  const publicResult = result ? {
-    ok: !!result.ok,
-    ...(result.reason ? { reason: safeUpdateReason(result.reason) } : {}),
-    ...(result.at ? { at: result.at } : {}),
-    ...(result.matched ? { matched: result.matched } : {}),
-  } : null;
-  return { opId, phase, targetVersion, targetContentSha256, targetAppVersion: targetAppVersion ?? null,
-    rolledBack: !!rolledBack, attempts: attempts ?? 0, result: publicResult, startedAt,
-    release: release ? clientReleaseView(release, view) : null };
-}
-export function createPluginUpdateController(options) {
-  const { home = homedir(), configValue, profileDir, packageName = '', npmPackageView, capabilities, localVersion, localContentSha256,
-    status, log = () => {}, fetchImpl = fetch, auth = {}, basePath = '/m', workerOptions = {},
-    schedule = fn => setImmediate(fn), runSelfUpdate: runner = runSelfUpdate, prepareNpmArtifacts: prepareRunner = prepareNpmArtifacts,
-    persist = writeOwnedTransaction } = options;
-  const currentFile = transactionFile(home), lockPath = updateLockPath(home);
-  const preparedUpdates = new Map();
-  const preparedTtlMs = 30 * 60 * 1000;
-  const safePreparedWorkRoot = resolve(workRoot(home));
-  const removePreparedWorkDir = workDir => {
-    if (!workDir || !existsSync(safePreparedWorkRoot)) return false;
-    try {
-      const rootReal = realpathSync(safePreparedWorkRoot);
-      const targetReal = realpathSync(workDir);
-      const rel = relative(rootReal, targetReal);
-      if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return false;
-      rmSync(targetReal, { recursive: true, force: true });
-      return true;
-    } catch { return false; }
-  };
-  const cleanupPreparedUpdates = () => {
-    const now = Date.now();
-    for (const [key, entry] of preparedUpdates) {
-      if (entry.expiresAt <= now) {
-        clearTimeout(entry.expireTimer);
-        removePreparedWorkDir(entry.workDir);
-        preparedUpdates.delete(key);
-      }
-    }
-    try {
-      if (!existsSync(safePreparedWorkRoot)) return;
-      const rootReal = realpathSync(safePreparedWorkRoot);
-      const active = new Set([...preparedUpdates.values()].map(entry => resolve(entry.workDir)));
-      const activeTransaction = readTransaction(currentFile);
-      const activePreparedDir = activeTransaction && !isTerminalPhase(activeTransaction.phase) && activeTransaction.preparedId
-        ? `prepare-${activeTransaction.preparedId}` : "";
-      for (const item of readdirSync(rootReal, { withFileTypes: true })) {
-        if (!item.isDirectory() || !item.name.startsWith('prepare-') || item.name === activePreparedDir) continue;
-        const target = join(rootReal, item.name);
-        if (active.has(resolve(target))) continue;
-        if (now - statSync(target).mtimeMs > preparedTtlMs) removePreparedWorkDir(target);
-      }
-    } catch { /* cleanup is best-effort; never disrupt update checks */ }
-  };
-  cleanupPreparedUpdates();
-  const checking = () => checkForUpdate({ configValue, packageName, npmCwd: profileDir, npmPackageView,
-    localVersion: typeof localVersion === 'function' ? localVersion() : localVersion, localContentSha256,
-    capabilities: capabilities(), fetchImpl, auth });
-  /// 手机视图：**只用于 HTTP 出口**，绝不写回内部事务（F1）。
-  /// 内部 worker 必须继续用受信定位；当前 NPM 来源不会把 registry URL 投影给客户端。
-  const clientView = clientOrigin => ({
-    clientOrigin, basePath, loopback: resolvePluginUpdateSource(configValue).loopback === true,
-  });
-  async function prepare(body = {}) {
-    if (!body || typeof body !== 'object' || Array.isArray(body) || ('opId' in body && !validOperationId(body.opId))) {
-      return { status: 400, body: { error: 'invalid-operation-id' } };
-    }
-    const source = resolvePluginUpdateSource(configValue);
-    if (source.kind === UPDATE_SOURCE_KIND.OFF) return { status: 503, body: { error: 'update-source-off' } };
-    if (source.kind === UPDATE_SOURCE_KIND.INVALID) return { status: 400, body: { error: 'update-source-invalid' } };
-    if (!profileDir) return { status: 409, body: { error: 'profile-not-found' } };
-    if (!capabilities().canSelfUpdate) return { status: 409, body: { error: 'restart-unsupported' } };
-    const opId = body.opId ?? newOperationId();
-    cleanupPreparedUpdates();
-    const current = preparedUpdates.get(opId);
-    if (current && current.expiresAt > Date.now()) return { status: 200, body: {
-      ok: true, action: 'prepared', opId, prepareId: current.prepareId, candidate: current.candidate,
-    } };
-    const old = readTransaction(currentFile);
-    if (old && !isTerminalPhase(old.phase)) return { status: 409, body: { error: 'update-busy', transaction: publicTransaction(old) } };
-    const checked = await checking(); Object.assign(status, checked);
-    if (checked.state !== 'update-available') return { status: 200, body: { ok: true, action: 'none', check: checked } };
-    const candidate = checked.candidate;
-    if (!candidate?.carrier?.legacyMetadataMissing) {
-      return { status: 200, body: { ok: true, action: 'confirmation-required', opId, candidate, check: checked } };
-    }
-    const prepareId = newOperationId();
-    const workDir = join(safePreparedWorkRoot, `prepare-${prepareId}`);
-    mkdirSync(workDir, { recursive: true, mode: 0o700 });
-    let artifacts;
-    try {
-      artifacts = await prepareRunner({ npmCandidate: candidate, packageName, profileDir, workDir });
-      if (!artifacts?.ok || !artifacts.carrierAppVersion || !artifacts.pluginContentSha256) {
-        removePreparedWorkDir(workDir);
-        return { status: 502, body: { error: 'candidate-preparation-failed', reason: artifacts?.error ?? 'npm-preparation-incomplete' } };
-      }
-    } catch {
-      removePreparedWorkDir(workDir);
-      return { status: 502, body: { error: 'candidate-preparation-failed', reason: 'npm-preparation-failed' } };
-    }
-    const preparedCandidate = {
-      ...candidate,
-      plugin: { ...candidate.plugin, contentSha256: artifacts.pluginContentSha256 },
-      carrier: { ...candidate.carrier, appVersion: artifacts.carrierAppVersion,
-        pluginContentSha256: artifacts.pluginContentSha256, legacyMetadataMissing: false },
-    };
-    const preparedCheck = {
-      ...checked,
-      candidate: preparedCandidate,
-      remote: { ...checked.remote, contentSha256: artifacts.pluginContentSha256,
-        appVersion: artifacts.carrierAppVersion, legacyCarrierMetadata: false },
-    };
-    const entry = { prepareId, opId, candidate: preparedCandidate, artifacts, workDir, expiresAt: Date.now() + preparedTtlMs };
-    entry.expireTimer = setTimeout(() => {
-      const current = preparedUpdates.get(opId);
-      if (current?.prepareId === prepareId) {
-        removePreparedWorkDir(current.workDir);
-        preparedUpdates.delete(opId);
-      }
-    }, preparedTtlMs);
-    entry.expireTimer.unref?.();
-    preparedUpdates.set(opId, entry);
-    Object.assign(status, preparedCheck);
-    return { status: 200, body: { ok: true, action: 'prepared', opId, prepareId, candidate: preparedCandidate, check: preparedCheck } };
-  }
-  async function submit(body = {}, { clientOrigin = '' } = {}) {
-    if (!body || typeof body !== 'object' || Array.isArray(body) ||
-      ('opId' in body && !validOperationId(body.opId))) return { status: 400, body: { error: 'invalid-operation-id' } };
-    if ('targetVersion' in body && typeof body.targetVersion !== 'string') return { status: 400, body: { error: 'invalid-target-version' } };
-    const source = resolvePluginUpdateSource(configValue);
-    if (source.kind === UPDATE_SOURCE_KIND.OFF) return { status: 503, body: { error: 'update-source-off' } };
-    if (source.kind === UPDATE_SOURCE_KIND.INVALID) return { status: 400, body: { error: 'update-source-invalid' } };
-    if (!profileDir) return { status: 409, body: { error: 'profile-not-found' } };
-    if (!capabilities().canSelfUpdate) return { status: 409, body: { error: 'restart-unsupported' } };
-    const view = clientView(clientOrigin);
-    const old = readTransaction(currentFile);
-    if (old && body.opId === old.opId) return { status: 200, body: { ok: true, action: 'accepted', opId: old.opId,
-      transaction: publicTransaction(old, view), check: { ...status, release: clientReleaseView(status.release, view) } } };
-    if (old && !isTerminalPhase(old.phase)) {
-      const convergence = convergeStaleTransaction({ stateFile: currentFile, lockPath });
-      if (!['converged','terminal'].includes(convergence.action)) return { status: 409, body: {
-        error: convergence.action === 'recovery-required' ? 'recovery-required' : 'update-busy', transaction: publicTransaction(old, view) } };
-    }
-    const checked = await checking(); Object.assign(status, checked);
-    // **内部 release 原样保留**（持久化与 worker 都用它）；只有响应体走手机视图。
-    if (checked.state !== 'update-available') {
-      return { status: 200, body: { ok: true, action: 'none', check: { ...checked, release: clientReleaseView(checked.release, view) } } };
-    }
-    const opId = body.opId ?? newOperationId();
-    let effectiveCheck = checked;
-    let npmCandidate = checked.candidate ?? null;
-    let preparedNpmArtifacts = null;
-    if (npmCandidate?.carrier?.legacyMetadataMissing) {
-      cleanupPreparedUpdates();
-      const prepared = preparedUpdates.get(opId);
-      if (!prepared || prepared.expiresAt <= Date.now() || prepared.prepareId !== body.prepareId) {
-        return { status: 200, body: { ok: true, action: 'prepare-required', opId, check: checked } };
-      }
-      if (prepared.candidate.plugin.version !== npmCandidate.plugin.version
-        || prepared.candidate.carrier.version !== npmCandidate.carrier.version
-        || prepared.candidate.plugin.integrity !== npmCandidate.plugin.integrity
-        || prepared.candidate.carrier.integrity !== npmCandidate.carrier.integrity) {
-        return { status: 409, body: { error: 'prepared-candidate-stale', check: checked } };
-      }
-      npmCandidate = prepared.candidate;
-      preparedNpmArtifacts = prepared.artifacts;
-      effectiveCheck = { ...checked, candidate: npmCandidate,
-        remote: { ...checked.remote, contentSha256: npmCandidate.plugin.contentSha256,
-          appVersion: npmCandidate.carrier.appVersion, legacyCarrierMetadata: false } };
-      Object.assign(status, effectiveCheck);
-    } else if (body.prepareId) {
-      return { status: 409, body: { error: 'prepare-not-required', check: checked } };
-    }
-    const targetPlugin = checked.release?.plugin ?? npmCandidate?.plugin;
-    if (!targetPlugin?.version) return { status: 503, body: { error: 'update-candidate-incomplete' } };
-    if (typeof body.targetVersion === 'string' && body.targetVersion !== targetPlugin.version) {
-      return { status: 409, body: { error: 'candidate-changed', check: effectiveCheck } };
-    }
-    const lock = acquireLock(lockPath, { opId, stateFile: currentFile });
-    if (!lock.ok) return { status: 409, body: { error: lock.error, transaction: publicTransaction(readTransaction(currentFile)) } };
-    const lease = lock.lease, stateFile = serverOperationPath(home, lease.generation);
-    const operationLog = createOperationLog({ home, generation: lease.generation,
-      redactPaths: [home, profileDir, workerOptions.pluginRoot, workerOptions.installedRoot] });
-    operationLog.setStage('staging', 'NPM plugin update accepted');
-    let tx;
-    try {
-      tx = persist(stateFile, { ...workerOptions, opId, phase: 'staging', startedAt: new Date().toISOString(),
-        profileDir, release: checked.release ?? null, npmCandidate,
-        manifestUrl: checked.release?.manifestUrl ?? '',
-        targetVersion: targetPlugin.version, targetContentSha256: targetPlugin.contentSha256 ?? '',
-        targetAppVersion: npmCandidate?.carrier?.appVersion ?? checked.release?.app?.version ?? null,
-        preparedId: body.prepareId ?? null,
-        currentFile, lockPath, lease, attempts: 0 }, { lockPath, lease, currentFile });
-    } catch(e) {
-      releaseLock(lockPath, lease, { stateFile: currentFile });
-      operationLog.setStage('failed', 'Could not persist update admission state.');
-      operationLog.flush();
-      log('plugin update admission state write failed');
-      return { status: 500, body: { error: 'update-state-write-failed' } };
-    }
-    // Consume the in-memory preflight only after the durable transaction accepts the same opId.
-    if (preparedNpmArtifacts) {
-      clearTimeout(preparedUpdates.get(opId)?.expireTimer);
-      preparedUpdates.delete(opId);
-    }
-    // Only this lease schedules this worker. Same request retries return the saved operation above.
-    schedule(async () => {
-      try {
-        const run = await runner({ ...workerOptions, home, profileDir, fetchImpl, auth, opId,
-          release: tx.release ?? null, npmCandidate: tx.npmCandidate ?? null, preparedNpmArtifacts,
-          plugin: tx.release?.plugin ?? tx.npmCandidate?.plugin, manifestUrl: tx.manifestUrl,
-          onStep: step => { operationLog.setStage(step); workerOptions.onStep?.(step); },
-          onOutput: (stream, text) => operationLog.appendChunk(stream, text),
-          stateFile, currentFile, lockPath, lease, initialTransaction: tx,
-          log: message => { operationLog.appendStatus(message, 'worker'); log('plugin update progress recorded'); } });
-        operationLog.flush();
-        if (run.ok) {
-          operationLog.setStage('restart', 'Plugin install finished; waiting for host restart and health confirmation.');
-          Object.assign(status, { state: 'restarting', reason: 'update-staged', opId });
-        } else {
-          const reason = safeUpdateReason(run.error);
-          // 失败原因必须进日志：详情页要能直接看到，而不是只有一句“看安装输出”。
-          operationLog.setStage('failed', `Plugin update failed: ${reason}`);
-          Object.assign(status, { state: run.transaction?.phase === 'rolling-back' ? 'rolling-back' : 'update-failed', reason, opId });
-        }
-      } catch(e) {
-        // Never clear an install/recovery lease as a generic catch. The armed supervisor owns recovery.
-        const latest = readTransaction(stateFile);
-        const reason = safeUpdateReason(e.message);
-        if (latest && latest.lease?.generation === lease.generation && latest.phase === 'staging') {
-          try { finishOwnedTerminal(stateFile, { phase: 'failed', result: { ok: false, reason }, expectedPhases: ['staging'] }, { lockPath, lease, currentFile }); }
-          catch { /* lost lease: do not overwrite a newer operation */ }
-        }
-        operationLog.setStage('failed', `Update worker failed: ${reason}`);
-        operationLog.flush();
-        Object.assign(status, { state: 'update-failed', reason, opId }); log('plugin update worker failed');
-      } finally {
-        if (preparedNpmArtifacts?.workDir) removePreparedWorkDir(preparedNpmArtifacts.workDir);
-      }
-    });
-    return { status: 200, body: { ok: true, action: 'accepted', opId,
-      transaction: publicTransaction(tx, view), check: { ...effectiveCheck, release: clientReleaseView(effectiveCheck.release, view) } } };
-  }
-  return { submit, check: checking, prepare };
-}

package/lib/plugin-update-log.js

@@ -1,164 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
-import { serverOperationPath } from "./plugin-update-transaction.js";
-
-export const UPDATE_LOG_MAX_LINES = 400;
-export const UPDATE_LOG_MAX_BYTES = 128 * 1024;
-export const UPDATE_LOG_MAX_OPERATIONS = 20;
-const MAX_LINE_BYTES = 4096;
-const ANSI = /\u001b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
-const SENSITIVE_KEY = /\b(_authToken|_auth|npm_config_[A-Za-z0-9_-]+|password|token|access_token|refresh_token|api[_-]?key|secret)\s*[:=]\s*([^\s&"']+)/gi;
-const URL_USERINFO = /(https?:\/\/)[^/\s@]+@/gi;
-const URL_SECRET_QUERY = /([?&](?:token|auth|password|key|secret|signature|access_token|refresh_token)=)[^&#\s]*/gi;
-
-function logPath(home, generation) {
-	return `${serverOperationPath(home, generation)}.log.jsonl`;
-}
-
-/** Keep the active/new log plus a bounded tail of completed operation logs. */
-export function pruneOperationLogs({ home, generation, maxOperations = UPDATE_LOG_MAX_OPERATIONS } = {}) {
-	const currentPath = logPath(home, generation);
-	const dir = dirname(currentPath);
-	if (!existsSync(dir)) return 0;
-	const limit = Number.isSafeInteger(maxOperations) && maxOperations > 0 ? maxOperations : UPDATE_LOG_MAX_OPERATIONS;
-	try {
-		const root = realpathSync(dir);
-		const currentName = basename(currentPath);
-		const logs = readdirSync(root, { withFileTypes: true })
-			.filter((entry) => entry.isFile() && /^[a-f0-9-]{36}\.json\.log\.jsonl$/.test(entry.name))
-			.map((entry) => ({ name: entry.name, mtime: statSync(join(root, entry.name)).mtimeMs }))
-			.sort((a, b) => b.mtime - a.mtime);
-		const keep = new Set([currentName, ...logs.map((item) => item.name).filter((name) => name !== currentName).slice(0, limit - 1)]);
-		let removed = 0;
-		for (const item of logs) {
-			if (keep.has(item.name)) continue;
-			const target = join(root, item.name);
-			const resolved = realpathSync(target);
-			const rel = relative(root, resolved);
-			if (rel !== item.name || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
-			rmSync(resolved, { force: true });
-			removed++;
-		}
-		return removed;
-	} catch {
-		return 0;
-	}
-}
-
-function readEvents(filePath) {
-	try {
-		return readFileSync(filePath, "utf8").split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line))
-			.filter((event) => Number.isSafeInteger(event?.seq) && typeof event?.text === "string");
-	} catch {
-		return [];
-	}
-}
-
-function sanitize(text, redactPaths = []) {
-	let value = String(text ?? "").replace(ANSI, "");
-	value = value.replace(/\b(authorization\s*:\s*)(?:basic|bearer)\s+[^\s]+/gi, "$1[REDACTED]");
-	value = value.replace(/\b(basic|bearer)\s+[^\s]+/gi, "$1 [REDACTED]");
-	value = value.replace(URL_USERINFO, "$1[REDACTED]@");
-	value = value.replace(URL_SECRET_QUERY, "$1[REDACTED]");
-	value = value.replace(SENSITIVE_KEY, "$1=[REDACTED]");
-	for (const path of [...redactPaths].filter((item) => typeof item === "string" && item !== "").sort((a, b) => b.length - a.length)) {
-		value = value.split(path).join("[host-path]");
-	}
-	if (Buffer.byteLength(value) > MAX_LINE_BYTES) {
-		let end = Math.min(value.length, MAX_LINE_BYTES);
-		while (end > 0 && Buffer.byteLength(value.slice(0, end)) > MAX_LINE_BYTES - 16) end -= 64;
-		value = `${value.slice(0, Math.max(0, end))}…[line truncated]`;
-	}
-	return value;
-}
-
-function persistEvents(filePath, events, { maxLines = UPDATE_LOG_MAX_LINES, maxBytes = UPDATE_LOG_MAX_BYTES } = {}) {
-	let kept = events.slice(-Math.max(1, maxLines));
-	const encoded = () => kept.map((event) => JSON.stringify(event)).join("\n") + (kept.length ? "\n" : "");
-	while (kept.length > 0 && Buffer.byteLength(encoded()) > maxBytes) kept = kept.slice(1);
-	mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
-	const tmp = `${filePath}.${randomUUID()}.tmp`;
-	try {
-		writeFileSync(tmp, encoded(), { encoding: "utf8", mode: 0o600 });
-		renameSync(tmp, filePath);
-		try { chmodSync(filePath, 0o600); } catch { /* best-effort on platforms without POSIX modes */ }
-	} finally {
-		if (existsSync(tmp)) rmSync(tmp, { force: true });
-	}
-	return kept;
-}
-
-function appendEvents(filePath, items, options = {}) {
-	if (!Array.isArray(items) || items.length === 0) return readEvents(filePath);
-	const events = readEvents(filePath);
-	let seq = events.length ? events[events.length - 1].seq + 1 : 1;
-	const next = items.map((item) => ({
-		seq: seq++,
-		at: new Date().toISOString(),
-		stage: String(item.stage ?? "unknown"),
-		stream: item.stream === "stdout" || item.stream === "stderr" ? item.stream : "status",
-		text: sanitize(item.text, options.redactPaths),
-	}));
-	return persistEvents(filePath, [...events, ...next], options);
-}
-
-/** Create a bounded append/replay view keyed only by the server-generated operation generation. */
-export function createOperationLog({ home, generation, maxLines = UPDATE_LOG_MAX_LINES, maxBytes = UPDATE_LOG_MAX_BYTES,
-	maxOperations = UPDATE_LOG_MAX_OPERATIONS, redactPaths = [] } = {}) {
-	const filePath = logPath(home, generation);
-	mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
-	if (!existsSync(filePath)) writeFileSync(filePath, "", { encoding: "utf8", mode: 0o600 });
-	pruneOperationLogs({ home, generation, maxOperations });
-	let stage = "staging";
-	const pending = { stdout: "", stderr: "" };
-	const options = { maxLines, maxBytes, redactPaths };
-	return {
-		filePath,
-		setStage(nextStage, text = "") {
-			stage = String(nextStage || "unknown");
-			return appendEvents(filePath, [{ stage, stream: "status", text: text || stage }], options);
-		},
-		appendStatus(text, stageOverride = stage) {
-			return appendEvents(filePath, [{ stage: stageOverride, stream: "status", text }], options);
-		},
-		appendChunk(stream, text) {
-			if (stream !== "stdout" && stream !== "stderr") return;
-			const merged = `${pending[stream]}${String(text ?? "")}`.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-			const lines = merged.split("\n");
-			pending[stream] = lines.pop() ?? "";
-			const items = lines.map((line) => ({ stage, stream, text: line }));
-			if (items.length) appendEvents(filePath, items, options);
-		},
-		flush() {
-			const items = [];
-			for (const stream of ["stdout", "stderr"]) {
-				if (pending[stream] !== "") items.push({ stage, stream, text: pending[stream] });
-				pending[stream] = "";
-			}
-			if (items.length) appendEvents(filePath, items, options);
-		},
-		read(afterSeq = 0) {
-			return readOperationLog({ home, generation, afterSeq, maxLines });
-		},
-	};
-}
-
-/** Append one sanitized status event from a separate supervisor process. */
-export function appendOperationLog({ home, generation, stage = "supervisor", stream = "status", text = "", maxLines = UPDATE_LOG_MAX_LINES, maxBytes = UPDATE_LOG_MAX_BYTES, redactPaths = [] } = {}) {
-	return appendEvents(logPath(home, generation), [{ stage, stream, text }], { maxLines, maxBytes, redactPaths });
-}
-
-/** Read only a bounded, sanitized page using a server-owned operation generation. */
-export function readOperationLog({ home, generation, afterSeq = 0, maxLines = UPDATE_LOG_MAX_LINES } = {}) {
-	const events = readEvents(logPath(home, generation));
-	const firstSeq = events[0]?.seq ?? 0;
-	const lastSeq = events.at(-1)?.seq ?? 0;
-	const cursor = Number.isSafeInteger(afterSeq) && afterSeq >= 0 ? afterSeq : 0;
-	return {
-		events: events.filter((event) => event.seq > cursor).slice(-Math.max(1, maxLines)),
-		firstSeq,
-		lastSeq,
-		truncated: firstSeq > 0 && (firstSeq > 1 || cursor > 0 && cursor < firstSeq - 1),
-	};
-}