pi-crew 0.1.45 → 0.1.49

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

@@ -20,7 +20,7 @@ export const TEAM_RUN_STATUS_TRANSITIONS: Readonly<Record<TeamRunStatus, readonl
 export const TEAM_TASK_STATUS_TRANSITIONS: Readonly<Record<TeamTaskStatus, readonly TeamTaskStatus[]>> = {
 	queued: ["running", "cancelled", "skipped", "failed"],
 	running: ["completed", "failed", "cancelled", "queued", "waiting"],
-	waiting: ["running", "completed", "failed", "cancelled"],
+	waiting: ["running", "queued", "completed", "failed", "cancelled"],
 	completed: ["queued"],
 	failed: ["queued", "cancelled"],
 	cancelled: ["queued"],
@@ -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

@@ -6,6 +6,9 @@ import { redactSecrets } from "../utils/redaction.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
 export type MailboxMessageStatus = "queued" | "delivered" | "acknowledged";
+export type MailboxMessageKind = "message" | "steer" | "follow-up" | "response" | "group_join";
+export type MailboxMessagePriority = "urgent" | "normal" | "low";
+export type MailboxDeliveryMode = "interrupt" | "next_turn";
 
 export interface MailboxMessage {
 	id: string;
@@ -16,9 +19,22 @@ export interface MailboxMessage {
 	body: string;
 	createdAt: string;
 	status: MailboxMessageStatus;
+	kind?: MailboxMessageKind;
+	priority?: MailboxMessagePriority;
+	deliveryMode?: MailboxDeliveryMode;
 	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 {
@@ -130,12 +146,26 @@ function isStatus(value: unknown): value is MailboxMessageStatus {
 	return value === "queued" || value === "delivered" || value === "acknowledged";
 }
 
+function isKind(value: unknown): value is MailboxMessageKind {
+	return value === "message" || value === "steer" || value === "follow-up" || value === "response" || value === "group_join";
+}
+
+function isPriority(value: unknown): value is MailboxMessagePriority {
+	return value === "urgent" || value === "normal" || value === "low";
+}
+
+function isDeliveryMode(value: unknown): value is MailboxDeliveryMode {
+	return value === "interrupt" || value === "next_turn";
+}
+
 function parseMailboxMessage(raw: unknown, expectedDirection: MailboxDirection): MailboxMessage | undefined {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const obj = raw as Record<string, unknown>;
 	if (typeof obj.id !== "string" || typeof obj.runId !== "string" || !isDirection(obj.direction) || typeof obj.from !== "string" || typeof obj.to !== "string" || typeof obj.body !== "string" || typeof obj.createdAt !== "string" || !isStatus(obj.status)) return undefined;
 	if (obj.direction !== expectedDirection) return undefined;
-	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, taskId: typeof obj.taskId === "string" ? obj.taskId : undefined, acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined, data: obj.data && typeof obj.data === "object" && !Array.isArray(obj.data) ? obj.data as Record<string, unknown> : 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, 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[] {
@@ -158,23 +188,33 @@ 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 readAllInboxMessages(manifest: TeamRunManifest): MailboxMessage[] {
-	const messages = [...safeReadMailboxFile(mailboxFile(manifest, "inbox"), "inbox")];
+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, "inbox", entry.name), "inbox"));
+			messages.push(...safeReadMailboxFile(mailboxFile(manifest, direction, entry.name), direction));
 		}
 	}
 	return messages.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }
 
+function readAllInboxMessages(manifest: TeamRunManifest): MailboxMessage[] {
+	return readAllMessages(manifest, "inbox");
+}
+
 export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliveryState {
 	try {
 		const raw = JSON.parse(fs.readFileSync(deliveryFile(manifest), "utf-8")) as unknown;
@@ -208,8 +248,16 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 		body: message.body,
 		createdAt,
 		status: message.status ?? "queued",
+		kind: message.kind,
+		priority: message.priority,
+		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);
@@ -219,6 +267,19 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 	return complete;
 }
 
+export function appendSteeringMessage(manifest: TeamRunManifest, input: { taskId: string; body: string; from?: string; to?: string; priority?: MailboxMessagePriority; status?: MailboxMessageStatus; data?: Record<string, unknown> }): MailboxMessage {
+	return appendMailboxMessage(manifest, { direction: "inbox", from: input.from ?? "leader", to: input.to ?? input.taskId, taskId: input.taskId, body: input.body, kind: "steer", priority: input.priority ?? "urgent", deliveryMode: "interrupt", status: input.status, data: { ...(input.data ?? {}), kind: "steer" } });
+}
+
+export function appendFollowUpMessage(manifest: TeamRunManifest, input: { taskId: string; body: string; from?: string; to?: string; priority?: MailboxMessagePriority; status?: MailboxMessageStatus; data?: Record<string, unknown> }): MailboxMessage {
+	return appendMailboxMessage(manifest, { direction: "inbox", from: input.from ?? "leader", to: input.to ?? input.taskId, taskId: input.taskId, body: input.body, kind: "follow-up", priority: input.priority ?? "normal", deliveryMode: "next_turn", status: input.status, data: { ...(input.data ?? {}), kind: "follow-up" } });
+}
+
+export function listMailboxByKind(manifest: TeamRunManifest, kind: MailboxMessageKind, direction?: MailboxDirection): MailboxMessage[] {
+	const messages = direction ? readAllMessages(manifest, direction) : [...readAllMessages(manifest, "inbox"), ...readAllMessages(manifest, "outbox")].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	return messages.filter((message) => message.kind === kind || message.data?.kind === kind);
+}
+
 export function findMailboxMessageByRequestId(manifest: TeamRunManifest, requestId: string): MailboxMessage | undefined {
 	return readMailbox(manifest).find((message) => message.data?.requestId === requestId);
 }
@@ -236,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");
@@ -247,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);
@@ -273,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();