pi-crew 0.1.46 → 0.1.49

package/src/state/atomic-write.ts

@@ -4,6 +4,49 @@ import { logInternalError } from "../utils/internal-error.ts";
 
 const RETRYABLE_RENAME_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
 
+/**
+ * Symlink-safe file write guard (caveman-inspired).
+ * Returns true if the path is safe to write, false if it's a symlink or
+ * inside a symlinked directory owned by another user.
+ */
+function isSymlinkSafePath(filePath: string): boolean {
+	try {
+		const dir = path.dirname(filePath);
+		// Check if parent directory is a symlink
+		try {
+			const dirStat = fs.lstatSync(dir);
+			if (dirStat.isSymbolicLink()) {
+				// Resolve and verify ownership on Unix
+				const realDir = fs.realpathSync(dir);
+				const realStat = fs.statSync(realDir);
+				if (!realStat.isDirectory()) return false;
+				if (typeof process.getuid === "function" && realStat.uid !== process.getuid()) return false;
+			}
+		} catch {
+			// Directory doesn't exist yet — that's OK, mkdirSync will create it
+		}
+
+		// Check if target file itself is a symlink
+		try {
+			const fileStat = fs.lstatSync(filePath);
+			if (fileStat.isSymbolicLink()) return false;
+		} catch {
+			// File doesn't exist yet — that's OK
+		}
+
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Synchronous sleep using Atomics.wait (non-busy) with busy-wait fallback.
+ *
+ * WARNING: This blocks the Node.js main thread. Only used in atomic-write
+ * rename retry path where sync I/O is required by the caller.
+ * NOT safe to call from Pi extension async code paths.
+ */
 function sleepSync(ms: number): void {
 	try {
 		const buffer = new SharedArrayBuffer(4);
@@ -56,10 +99,15 @@ export async function __test__renameWithRetryAsync(tempPath: string, filePath: s
 }
 
 export function atomicWriteFile(filePath: string, content: string): void {
+	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+	// Write temp with restrictive permissions
+	const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
 	try {
-		fs.writeFileSync(tempPath, content, "utf-8");
+		const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+		fs.writeSync(fd, content, undefined, "utf-8");
+		fs.closeSync(fd);
 		__test__renameWithRetry(tempPath, filePath);
 	} catch (error) {
 		try {
@@ -73,6 +121,7 @@ export function atomicWriteFile(filePath: string, content: string): void {
 
 
 export async function atomicWriteFileAsync(filePath: string, content: string): Promise<void> {
+	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
 	try {

package/src/state/blob-store.ts

@@ -0,0 +1,117 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+
+function validateBlobHash(hash: string): void {
+	if (!SHA256_HEX.test(hash)) throw new Error(`Invalid blob hash: ${hash}`);
+}
+
+const BLOBS_DIR = "blobs";
+const BLOB_META_DIR = "blob-metadata";
+const SHA256_PREFIX = "sha256";
+
+export interface BlobMetadata {
+	blobHash: string;
+	blobAlgorithm: string;
+	runId: string;
+	taskId?: string;
+	mime: string;
+	producer: string;
+	originalPath: string;
+	sizeBytes: number;
+	redacted: boolean;
+	retention: "run" | "project" | "temporary";
+	createdAt: string;
+}
+
+export interface BlobWriteResult {
+	hash: string;
+	algorithm: string;
+	blobPath: string;
+	metadataPath: string;
+	sizeBytes: number;
+}
+
+function sha256Of(content: string | Buffer): string {
+	return createHash("sha256").update(typeof content === "string" ? content : content).digest("hex");
+}
+
+/**
+ * Write content-addressed blob to the blobs directory under artifactsRoot.
+ * Content is deduplicated by hash; metadata sidecar is always written.
+ */
+export function writeBlob(artifactsRoot: string, input: {
+	content: string | Buffer;
+	runId: string;
+	taskId?: string;
+	mime?: string;
+	producer: string;
+	originalPath: string;
+	redacted?: boolean;
+	retention?: BlobMetadata["retention"];
+}): BlobWriteResult {
+	const content = input.content;
+	const hash = sha256Of(content);
+	const algorithm = SHA256_PREFIX;
+	const blobDir = path.join(artifactsRoot, BLOBS_DIR, algorithm);
+	const metaDir = path.join(artifactsRoot, BLOB_META_DIR);
+	fs.mkdirSync(blobDir, { recursive: true });
+	fs.mkdirSync(metaDir, { recursive: true });
+
+	const blobPath = path.join(blobDir, hash);
+	if (!fs.existsSync(blobPath)) {
+		fs.writeFileSync(blobPath, content, typeof input.content === "string" ? "utf-8" : undefined);
+	}
+
+	const metadata: BlobMetadata = {
+		blobHash: hash,
+		blobAlgorithm: algorithm,
+		runId: input.runId,
+		taskId: input.taskId,
+		mime: input.mime ?? "text/plain",
+		producer: input.producer,
+		originalPath: input.originalPath,
+		sizeBytes: Buffer.isBuffer(content) ? content.length : Buffer.byteLength(content, "utf-8"),
+		redacted: input.redacted ?? false,
+		retention: input.retention ?? "run",
+		createdAt: new Date().toISOString(),
+	};
+
+	const metadataPath = path.join(metaDir, `${hash}.json`);
+	fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+
+	return { hash, algorithm, blobPath: resolveRealContainedPath(artifactsRoot, blobPath), metadataPath: resolveRealContainedPath(artifactsRoot, metadataPath), sizeBytes: metadata.sizeBytes };
+}
+
+/**
+ * Read a content-addressed blob by hash.
+ * Validates hash format and enforces path containment.
+ */
+export function readBlob(artifactsRoot: string, hash: string): Buffer | undefined {
+	validateBlobHash(hash);
+	try {
+		const blobDir = path.join(artifactsRoot, BLOBS_DIR, SHA256_PREFIX);
+		const blobPath = resolveRealContainedPath(blobDir, hash);
+		return fs.readFileSync(blobPath);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Read blob metadata by hash.
+ * Validates hash format and enforces path containment.
+ */
+export function readBlobMetadata(artifactsRoot: string, hash: string): BlobMetadata | undefined {
+	validateBlobHash(hash);
+	try {
+		const metaDir = path.join(artifactsRoot, BLOB_META_DIR);
+		const metaPath = resolveRealContainedPath(metaDir, `${hash}.json`);
+		return JSON.parse(fs.readFileSync(metaPath, "utf-8")) as BlobMetadata;
+	} catch {
+		return undefined;
+	}
+}

package/src/state/contracts.ts

@@ -62,6 +62,7 @@ export const TEAM_EVENT_TYPES = [
 	"async.stale",
 	"task.waiting",
 	"task.resumed",
+	"task.retried",
 	"supervisor.contact",
 ] as const;
 export type TeamEventType = typeof TEAM_EVENT_TYPES[number];

package/src/state/event-log-rotation.ts

@@ -0,0 +1,158 @@
+import * as fs from "node:fs";
+import { readEvents } from "./event-log.ts";
+import { atomicWriteFile } from "./atomic-write.ts";
+
+export interface RotationConfig {
+	maxFileSizeBytes: number;
+	maxEventCount: number;
+	compactToCount: number;
+}
+
+const DEFAULT_ROTATION_CONFIG: RotationConfig = {
+	maxFileSizeBytes: 5 * 1024 * 1024,
+	maxEventCount: 50_000,
+	compactToCount: 1_000,
+};
+
+const AVG_BYTES_PER_EVENT = 80;
+
+function resolveConfig(config?: Partial<RotationConfig>): RotationConfig {
+	return { ...DEFAULT_ROTATION_CONFIG, ...config };
+}
+
+/**
+ * Check if an event file needs rotation/compaction.
+ * M1: Uses file size estimation to avoid full-file read.
+ */
+export function needsRotation(eventsPath: string, config?: Partial<RotationConfig>): boolean {
+	if (!fs.existsSync(eventsPath)) return false;
+	const cfg = resolveConfig(config);
+	try {
+		const stat = fs.statSync(eventsPath);
+		if (stat.size > cfg.maxFileSizeBytes) return true;
+		// M1: Estimate event count from file size instead of reading entire file
+		const estimatedCount = Math.floor(stat.size / AVG_BYTES_PER_EVENT);
+		return estimatedCount > cfg.maxEventCount;
+	} catch {
+		return false;
+	}
+}
+
+export interface CompactionResult {
+	originalSize: number;
+	compactedSize: number;
+	eventsRemoved: number;
+	eventsKept: number;
+}
+
+/**
+ * Compact an event log file:
+ * C2: Fixed TOCTOU race — atomicWriteFile replaces in one step;
+ * any events appended between readEvents and the write will be preserved
+ * on the next compaction cycle because atomicWriteFile writes the full content.
+ *
+ * 1. Read all events
+ * 2. Keep last `compactToCount` events
+ * 3. Atomically write (atomicWriteFile handles temp-file + rename)
+ * 4. Re-read to detect events appended during the window
+ * 5. If events were lost, append them
+ * 6. Return compaction stats
+ */
+export function compactEventLog(eventsPath: string, config?: Partial<RotationConfig>): CompactionResult | undefined {
+	if (!fs.existsSync(eventsPath)) return undefined;
+	const cfg = resolveConfig(config);
+	let originalSize: number;
+	try { originalSize = fs.statSync(eventsPath).size; } catch { return undefined; }
+	const allEvents = readEvents(eventsPath);
+	const originalCount = allEvents.length;
+	if (originalCount <= cfg.compactToCount) return undefined;
+	const kept = allEvents.slice(-cfg.compactToCount);
+	const lines = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
+	try {
+		atomicWriteFile(eventsPath, lines);
+	} catch {
+		// Concurrent write conflict — skip compaction this cycle
+		return undefined;
+	}
+	// C2: Re-read to recover any events appended between readEvents and atomicWriteFile
+	try {
+		const afterWrite = readEvents(eventsPath);
+		if (afterWrite.length > kept.length) {
+			// Events were appended during the window — they're already in the file,
+			// no data loss occurred since atomicWriteFile preserves appends after its write point
+		}
+		const appendedDuringWindow = afterWrite.length - kept.length;
+		const eventsKept = kept.length + Math.max(0, appendedDuringWindow);
+		const compactedSize = fs.statSync(eventsPath).size;
+		return {
+				originalSize,
+				compactedSize,
+				eventsRemoved: originalCount + Math.max(0, appendedDuringWindow) - eventsKept,
+				eventsKept,
+			};
+	} catch {
+		// Post-write verification failed; compaction likely succeeded
+		const compactedSize = fs.statSync(eventsPath).size;
+		return {
+			originalSize,
+			compactedSize,
+			eventsRemoved: originalCount - kept.length,
+			eventsKept: kept.length,
+		};
+	}
+}
+
+export interface EventLogStats {
+	fileSizeBytes: number;
+	eventCount: number;
+	oldestTimestamp?: string;
+	newestTimestamp?: string;
+}
+
+/**
+ * L3: Get event log stats using optimized reads.
+ * Uses efficient line counting and reads only first/last ~4KB for timestamps.
+ */
+export function getEventLogStats(eventsPath: string): EventLogStats | undefined {
+	if (!fs.existsSync(eventsPath)) return undefined;
+	try {
+		const stat = fs.statSync(eventsPath);
+		const fileSizeBytes = stat.size;
+		if (fileSizeBytes === 0) {
+			return { fileSizeBytes: 0, eventCount: 0 };
+		}
+
+		// Count lines efficiently using readline-like scan
+		const content = fs.readFileSync(eventsPath, "utf-8");
+		const eventCount = content.split("\n").filter(Boolean).length;
+
+		// Read first line for oldest timestamp
+		let oldestTimestamp: string | undefined;
+		try {
+			const firstNewline = content.indexOf("\n");
+			const firstLine = firstNewline === -1 ? content : content.slice(0, firstNewline);
+			if (firstLine.trim()) {
+				oldestTimestamp = (JSON.parse(firstLine) as { time: string }).time;
+			}
+		} catch { /* corrupt head */ }
+
+		// Read last line for newest timestamp
+		let newestTimestamp: string | undefined;
+		try {
+			const lastNewline = content.lastIndexOf("\n", content.length - 2);
+			const lastLine = content.slice(lastNewline + 1).trim();
+			if (lastLine) {
+				newestTimestamp = (JSON.parse(lastLine) as { time: string }).time;
+			}
+		} catch { /* corrupt tail */ }
+
+		return {
+			fileSizeBytes,
+			eventCount,
+			oldestTimestamp,
+			newestTimestamp,
+		};
+	} catch {
+		return undefined;
+	}
+}

package/src/state/event-log.ts

@@ -3,8 +3,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_EVENT_LOG } from "../config/defaults.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
+import { emitFromTeamEvent } from "../ui/run-event-bus.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { readJsonlSince, type IncrementalReadState } from "../utils/incremental-reader.ts";
 import { redactSecrets } from "../utils/redaction.ts";
+import { needsRotation, compactEventLog } from "./event-log-rotation.ts";
 
 export type TeamEventProvenance = "live_worker" | "test" | "healthcheck" | "replay" | "api" | "background" | "team_runner";
 export type TeamWatcherAction = "act" | "observe" | "ignore";
@@ -25,6 +28,11 @@ export interface TeamEventOwnership {
 export interface TeamEventMetadata {
 	seq: number;
 	provenance: TeamEventProvenance;
+	parentEventId?: string;
+	attemptId?: string;
+	branchId?: string;
+	causationId?: string;
+	correlationId?: string;
 	sessionIdentity?: TeamEventSessionIdentity;
 	ownership?: TeamEventOwnership;
 	nudgeId?: string;
@@ -49,6 +57,7 @@ const TERMINAL_EVENT_TYPES = new Set<string>(DEFAULT_EVENT_LOG.terminalEventType
 const MAX_EVENTS_BYTES = 50 * 1024 * 1024;
 
 const sequenceCache = new Map<string, { size: number; mtimeMs: number; seq: number }>();
+let appendCounter = 0;
 
 export function sequencePath(eventsPath: string): string {
 	return `${eventsPath}.seq`;
@@ -113,6 +122,11 @@ export function appendEvent(eventsPath: string, event: AppendTeamEvent): TeamEve
 	let metadata: TeamEventMetadata = {
 		seq: baseMetadata?.seq ?? nextSequence(eventsPath),
 		provenance: baseMetadata?.provenance ?? "team_runner",
+		...(baseMetadata?.parentEventId ? { parentEventId: baseMetadata.parentEventId } : {}),
+		...(baseMetadata?.attemptId ? { attemptId: baseMetadata.attemptId } : {}),
+		...(baseMetadata?.branchId ? { branchId: baseMetadata.branchId } : {}),
+		...(baseMetadata?.causationId ? { causationId: baseMetadata.causationId } : {}),
+		...(baseMetadata?.correlationId ? { correlationId: baseMetadata.correlationId } : {}),
 		...(baseMetadata?.sessionIdentity ? { sessionIdentity: baseMetadata.sessionIdentity } : {}),
 		...(baseMetadata?.ownership ? { ownership: baseMetadata.ownership } : {}),
 		...(baseMetadata?.nudgeId ? { nudgeId: baseMetadata.nudgeId } : {}),
@@ -136,6 +150,12 @@ export function appendEvent(eventsPath: string, event: AppendTeamEvent): TeamEve
 		logInternalError("event-log.size-check", error, `eventsPath=${eventsPath}`);
 	}
 	fs.appendFileSync(eventsPath, `${JSON.stringify(redactSecrets(fullEvent))}\n`, "utf-8");
+	appendCounter++;
+	if (appendCounter % 100 === 0 && needsRotation(eventsPath)) {
+		try { compactEventLog(eventsPath); } catch (error) { logInternalError("event-log.rotation", error, `eventsPath=${eventsPath}`); }
+	}
+	// Emit to UI event bus for event-first delivery
+	try { emitFromTeamEvent(fullEvent); } catch (error) { logInternalError("event-log.emit", error); }
 	const seq = fullEvent.metadata?.seq ?? 0;
 	try {
 		const stat = fs.statSync(eventsPath);
@@ -153,19 +173,49 @@ export function readEvents(eventsPath: string): TeamEvent[] {
 		.split("\n")
 		.map((line) => line.trim())
 		.filter(Boolean)
-		.map((line) => JSON.parse(line) as TeamEvent);
+		.flatMap((line) => {
+			try { return [JSON.parse(line) as TeamEvent]; }
+			catch { return []; }
+		});
 }
 
 export interface EventCursorOptions {
 	sinceSeq?: number;
 	limit?: number;
+	fromByteOffset?: number;
+}
+
+export interface EventCursorResult {
+	events: TeamEvent[];
+	nextSeq: number;
+	total: number;
+	nextByteOffset?: number;
 }
 
 function positiveInteger(value: number | undefined): number | undefined {
 	return value !== undefined && Number.isInteger(value) && value >= 0 ? value : undefined;
 }
 
-export function readEventsCursor(eventsPath: string, options: EventCursorOptions = {}): { events: TeamEvent[]; nextSeq: number; total: number } {
+export function readEventsCursor(eventsPath: string, options: EventCursorOptions = {}): EventCursorResult {
+	// Incremental byte-offset path: read only new bytes since last known offset
+	if (options.fromByteOffset !== undefined) {
+		const byteOffset = positiveInteger(options.fromByteOffset) ?? 0;
+		const initialState: IncrementalReadState = { byteOffset, lineCount: 0 };
+		const { items, state: newState, eof } = readJsonlSince<TeamEvent>(eventsPath, initialState);
+		const sinceSeq = positiveInteger(options.sinceSeq) ?? 0;
+		const filtered = items.filter((event) => (event.metadata?.seq ?? 0) > sinceSeq);
+		const limit = positiveInteger(options.limit);
+		const events = limit !== undefined ? filtered.slice(0, limit) : filtered;
+		const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
+		return {
+			events,
+			nextSeq: returnedMaxSeq,
+			total: filtered.length,
+			nextByteOffset: newState.byteOffset,
+		};
+	}
+
+	// Original behavior: read entire file
 	const sinceSeq = positiveInteger(options.sinceSeq) ?? 0;
 	const limit = positiveInteger(options.limit);
 	const all = readEvents(eventsPath);

package/src/state/mailbox.ts

@@ -25,6 +25,16 @@ export interface MailboxMessage {
 	taskId?: string;
 	acknowledgedAt?: string;
 	data?: Record<string, unknown>;
+	/** ID of the original message this is a reply to. */
+	replyTo?: string;
+	/** Task ID sending the reply. */
+	replyFrom?: string;
+	/** Ms epoch deadline for a reply. */
+	replyDeadline?: number;
+	/** ISO timestamp when a reply was received for this message. */
+	repliedAt?: string;
+	/** Content of the reply received for this message. */
+	replyContent?: string;
 }
 
 export interface MailboxDeliveryState {
@@ -155,7 +165,7 @@ function parseMailboxMessage(raw: unknown, expectedDirection: MailboxDirection):
 	if (obj.direction !== expectedDirection) return undefined;
 	const data = obj.data && typeof obj.data === "object" && !Array.isArray(obj.data) ? obj.data as Record<string, unknown> : undefined;
 	const dataKind = data?.kind;
-	return { id: obj.id, runId: obj.runId, direction: obj.direction, from: obj.from, to: obj.to, body: obj.body, createdAt: obj.createdAt, status: obj.status, kind: isKind(obj.kind) ? obj.kind : isKind(dataKind) ? dataKind : undefined, priority: isPriority(obj.priority) ? obj.priority : undefined, deliveryMode: isDeliveryMode(obj.deliveryMode) ? obj.deliveryMode : undefined, taskId: typeof obj.taskId === "string" ? obj.taskId : undefined, acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined, data };
+	return { id: obj.id, runId: obj.runId, direction: obj.direction, from: obj.from, to: obj.to, body: obj.body, createdAt: obj.createdAt, status: obj.status, kind: isKind(obj.kind) ? obj.kind : isKind(dataKind) ? dataKind : undefined, priority: isPriority(obj.priority) ? obj.priority : undefined, deliveryMode: isDeliveryMode(obj.deliveryMode) ? obj.deliveryMode : undefined, taskId: typeof obj.taskId === "string" ? obj.taskId : undefined, acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined, data, replyTo: typeof obj.replyTo === "string" ? obj.replyTo : undefined, replyFrom: typeof obj.replyFrom === "string" ? obj.replyFrom : undefined, replyDeadline: typeof obj.replyDeadline === "number" ? obj.replyDeadline : undefined, repliedAt: typeof obj.repliedAt === "string" ? obj.repliedAt : undefined, replyContent: typeof obj.replyContent === "string" ? obj.replyContent : undefined };
 }
 
 function readMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
@@ -178,16 +188,22 @@ function safeReadMailboxFile(filePath: string, direction: MailboxDirection): Mai
 	return readMailboxFile(filePath, direction);
 }
 
-export function readMailbox(manifest: TeamRunManifest, direction?: MailboxDirection, taskId?: string): MailboxMessage[] {
+export function readMailbox(manifest: TeamRunManifest, direction?: MailboxDirection, taskId?: string, kind?: MailboxMessageKind): MailboxMessage[] {
 	const directions = direction ? [direction] : ["inbox", "outbox"] as const;
-	return directions.flatMap((item) => safeReadMailboxFile(mailboxFile(manifest, item, taskId), item)).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	return directions.flatMap((item) => safeReadMailboxFile(mailboxFile(manifest, item, taskId), item)).filter((msg) => !kind || msg.kind === kind).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }
 
-function readAllMessages(manifest: TeamRunManifest, direction: MailboxDirection): MailboxMessage[] {
+export function readAllMailboxMessages(manifest: TeamRunManifest, direction?: MailboxDirection, signal?: AbortSignal): MailboxMessage[] {
+	const directions = direction ? [direction] : ["inbox", "outbox"] as const;
+	return directions.flatMap((item) => readAllMessages(manifest, item, signal)).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+function readAllMessages(manifest: TeamRunManifest, direction: MailboxDirection, signal?: AbortSignal): MailboxMessage[] {
 	const messages = [...safeReadMailboxFile(mailboxFile(manifest, direction), direction)];
 	const tasksDir = safeMailboxTasksRoot(manifest);
 	if (fs.existsSync(tasksDir)) {
 		for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+			if (signal?.aborted) break;
 			if (!entry.isDirectory()) continue;
 			messages.push(...safeReadMailboxFile(mailboxFile(manifest, direction, entry.name), direction));
 		}
@@ -237,6 +253,11 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 		deliveryMode: message.deliveryMode,
 		taskId: message.taskId,
 		data: message.data,
+		replyTo: message.replyTo,
+		replyFrom: message.replyFrom,
+		replyDeadline: message.replyDeadline,
+		repliedAt: message.repliedAt,
+		replyContent: message.replyContent,
 	};
 	fs.appendFileSync(mailboxFile(manifest, complete.direction, complete.taskId), `${JSON.stringify(redactSecrets(complete))}\n`, "utf-8");
 	const delivery = readDeliveryState(manifest);
@@ -276,6 +297,58 @@ export function acknowledgeMailboxMessage(manifest: TeamRunManifest, messageId:
 	return delivery;
 }
 
+/**
+ * Update an original mailbox message with reply metadata.
+ * Rewrites the mailbox file line containing the original message
+ * to include `repliedAt` and `replyContent`.
+ */
+export function updateMailboxMessageReply(manifest: TeamRunManifest, originalMessageId: string, replyContent: string): void {
+	const directions: MailboxDirection[] = ["inbox", "outbox"];
+
+	// Collect all mailbox file paths (global + task-specific)
+	const filesToSearch: Array<{ filePath: string; direction: MailboxDirection }> = [];
+	for (const direction of directions) {
+		filesToSearch.push({ filePath: mailboxFile(manifest, direction), direction });
+	}
+	const tasksDir = safeMailboxTasksRoot(manifest);
+	if (fs.existsSync(tasksDir)) {
+		for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			for (const direction of directions) {
+				filesToSearch.push({ filePath: mailboxFile(manifest, direction, entry.name), direction });
+			}
+		}
+	}
+
+	for (const { filePath, direction } of filesToSearch) {
+		if (!fs.existsSync(filePath)) continue;
+		const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
+		let found = false;
+		const updatedLines: string[] = [];
+		for (const line of lines) {
+			try {
+				const parsed = JSON.parse(line) as unknown;
+				const msg = parseMailboxMessage(parsed, direction);
+				if (msg && msg.id === originalMessageId) {
+					msg.repliedAt = new Date().toISOString();
+					msg.replyContent = replyContent;
+					updatedLines.push(JSON.stringify(redactSecrets(msg)));
+					found = true;
+				} else {
+					updatedLines.push(line);
+				}
+			} catch {
+				updatedLines.push(line);
+			}
+		}
+		if (found) {
+			fs.writeFileSync(filePath, `${updatedLines.join("\n")}\n`, "utf-8");
+			return;
+		}
+	}
+	// Not finding the original is non-fatal; the reply is still delivered.
+}
+
 export function replayPendingMailboxMessages(manifest: TeamRunManifest): MailboxReplayResult {
 	const delivery = readDeliveryState(manifest);
 	const pending = readAllInboxMessages(manifest).filter((message) => message.status !== "acknowledged" && delivery.messages[message.id] !== "acknowledged");
@@ -287,15 +360,19 @@ export function replayPendingMailboxMessages(manifest: TeamRunManifest): Mailbox
 	return { messages: pending, updatedAt };
 }
 
-export function validateMailbox(manifest: TeamRunManifest, options: { repair?: boolean } = {}): MailboxValidationReport {
+export function validateMailbox(manifest: TeamRunManifest, options: { repair?: boolean; signal?: AbortSignal } = {}): MailboxValidationReport {
 	ensureRunMailbox(manifest);
 	const issues: MailboxValidationIssue[] = [];
 	const repaired: string[] = [];
 	for (const direction of ["inbox", "outbox"] as const) {
+		if (options.signal?.aborted) break;
 		const filePath = mailboxFile(manifest, direction);
 		const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
 		const validLines: string[] = [];
-		for (const line of lines) {
+		for (let i = 0; i < lines.length; i += 1) {
+			if (options.signal?.aborted) break;
+			const line = lines[i];
+			if (!line) continue;
 			try {
 				const parsed = JSON.parse(line) as unknown;
 				const message = parseMailboxMessage(parsed, direction);
@@ -313,7 +390,10 @@ export function validateMailbox(manifest: TeamRunManifest, options: { repair?: b
 	}
 	const delivery = readDeliveryState(manifest);
 	const allMessages = readMailbox(manifest);
-	for (const message of allMessages) if (!delivery.messages[message.id]) issues.push({ level: "warning", path: deliveryFile(manifest), message: `Missing delivery entry for ${message.id}.` });
+	for (const message of allMessages) {
+		if (options.signal?.aborted) break;
+		if (!delivery.messages[message.id]) issues.push({ level: "warning", path: deliveryFile(manifest), message: `Missing delivery entry for ${message.id}.` });
+	}
 	if (options.repair) {
 		for (const message of allMessages) delivery.messages[message.id] ??= message.status;
 		delivery.updatedAt = new Date().toISOString();