@marktrue/dsh-mobile-remote 3.2.4-alpha.3-app → 3.2.4-alpha.3

package/lib/plugin-update-controller.js

@@ -0,0 +1,274 @@
+// 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

@@ -0,0 +1,164 @@
+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),
+	};
+}