pi-crew 0.9.68 → 0.10.2

package/src/schema/sensitive-config-paths.ts

@@ -0,0 +1,64 @@
+import { PiTeamsConfigSchema } from "./config-schema.ts";
+
+/**
+ * Schema-driven sensitive-config discovery (Phase 5.1, ADR
+ * docs/decisions/2026-08-15-schema-driven-sanitize.md).
+ *
+ * Sensitive fields are marked in `config-schema.ts` via TypeBox Options
+ * metadata: `Type.Boolean({ sensitive: true })`. In TypeBox 0.34 the
+ * constructor spreads unknown option keys verbatim onto the emitted schema
+ * object (`build/cjs/type/create/type.js` CreateType: `options !== undefined
+ * ? { ...options, ...schema } : schema`), and `Type.Optional` is a flat
+ * spread modifier (`{ ...schema, [OptionalKind]: 'Optional' }`), so the mark
+ * lands directly on `properties[key]` and survives Clone/Decode.
+ *
+ * The walk below collects the dotted paths of every marked property. Marked
+ * properties are TERMINAL: Record/Object-valued marked props
+ * (`agents.overrides`, `otlp.headers`, `runtime.isolationPolicy`) collapse
+ * to a single dotted path instead of being recursed into.
+ */
+
+type SchemaLike = {
+	sensitive?: unknown;
+	properties?: Record<string, SchemaLike>;
+	anyOf?: SchemaLike[];
+} & Record<string, unknown>;
+
+function isMarkedSensitive(property: SchemaLike): boolean {
+	if (property.sensitive === true) return true;
+	// Defensive: a mark placed on a Union *member* rather than the outermost
+	// property schema (the recommended form) still counts. Not used by the
+	// current config schema; guards future editors.
+	const members = property.anyOf;
+	if (Array.isArray(members) && members.some((member) => member.sensitive === true)) return true;
+	return false;
+}
+
+function walkProperties(schema: SchemaLike, prefix: string, out: string[]): void {
+	const properties = schema.properties;
+	if (!properties || typeof properties !== "object") return;
+	for (const [key, property] of Object.entries(properties)) {
+		if (!property || typeof property !== "object") continue;
+		const dotted = prefix === "" ? key : `${prefix}.${key}`;
+		if (isMarkedSensitive(property)) {
+			out.push(dotted);
+			continue;
+		}
+		// `Type.Optional` needs no unwrapping in 0.34 (flat spread — the mark
+		// and `.properties` sit on the property schema itself). Union members
+		// are visited defensively for nested Object schemas.
+		const branches: SchemaLike[] = Array.isArray(property.anyOf) ? property.anyOf : [property];
+		for (const branch of branches) {
+			if (branch && typeof branch === "object" && branch.properties) walkProperties(branch, dotted, out);
+		}
+	}
+}
+
+/** Dotted paths of every `sensitive: true`-marked field in the config schema
+ * (top-level keys unprefixed, nested keys as `section.key`). Order follows
+ * schema property declaration order. */
+export function collectSensitiveConfigPaths(schema: SchemaLike = PiTeamsConfigSchema as SchemaLike): string[] {
+	const out: string[] = [];
+	walkProperties(schema, "", out);
+	return out;
+}

package/src/schema/team-tool-schema.ts

@@ -235,7 +235,13 @@ const sharedFields = {
 			description: "Path to a markdown plan document for orchestration.",
 		}),
 	),
-	subAction: Type.Optional(Type.String({ description: "Sub-action for schedule management (remove, disable, enable, update)." })),
+	subAction: Type.Optional(
+		Type.String({ description: "Sub-action. For action='plans': get (default) | list | diff | approve | reject." }),
+	),
+	// T2/R4 (ADR-4 §7): plans action params.
+	rev: Type.Optional(Type.Number({ description: "plans get: pin a specific plan revision (default: current)." })),
+	a: Type.Optional(Type.Number({ description: "plans diff: left revision number." })),
+	b: Type.Optional(Type.Number({ description: "plans diff: right revision number." })),
 	jobId: Type.Optional(Type.String({ description: "Job ID for schedule management actions." })),
 	cron: Type.Optional(
 		Type.String({
@@ -378,11 +384,11 @@ const sharedFields = {
 	),
 };
 
-// ─── Domain action unions (9+16+7+16+6 = 54 actions) ───────────────────────
+// ─── Domain action unions (10+16+7+16+6 = 55 actions) ──────────────────────
 
 const ACTION_DESCRIPTION = "Team action. Defaults to 'list' when omitted.";
 
-const RUN_ACTIONS = ["run", "parallel", "plan", "orchestrate", "resume", "retry", "wait", "steer", "goal"] as const;
+const RUN_ACTIONS = ["run", "parallel", "plan", "plans", "orchestrate", "resume", "retry", "wait", "steer", "goal"] as const;
 const runActions = Type.Optional(buildStringEnum(RUN_ACTIONS, ACTION_DESCRIPTION));
 
 const STATUS_ACTIONS = [
@@ -545,6 +551,10 @@ export interface TeamToolParamsValue {
 	// schedule sub-actions (removal/toggle/update of an existing job)
 	subAction?: string;
 	jobId?: string;
+	// T2/R4 (ADR-4 §7): plans action params.
+	rev?: number;
+	a?: number;
+	b?: number;
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens (default: false). */
 	excludeContextBash?: boolean;
 	/** Total token budget for the run. When set, enables budget tracking (minimum 1000). */

package/src/state/README.md

@@ -8,15 +8,10 @@ responsibility (Phase 7 reorg).
 | File | Responsibility |
 |------|---------------|
 | `types.ts` | Core state types (`TeamRunManifest`, `TeamTaskState`, schema versions) |
-| `types-eval.ts` | Evaluation-related types |
 | `contracts.ts` | Status transitions, task-status enums |
-| `tiered-eval.ts` | Tiered evaluation logic |
 | `crew-init.ts` | Crew initialization / bootstrap |
 | `decision-ledger.ts` | Decision recording |
 | `gitignore-manager.ts` | `.gitignore` management for crew dirs |
-| `hook-instinct-bridge.ts` | Bridge between hooks and instinct store |
-| `hook-integrations.ts` | Hook integration points |
-| `session-state-map.ts` | Session → state mapping |
 | `usage.ts` | Token/cost usage tracking |
 | `atomic-write.ts` | Atomic file writes (widely used — kept at root) |
 
@@ -26,19 +21,18 @@ Event append/read, rotation/compaction, JSONL writing, and worker-thread
 atomic writes.
 
 - `event-log.ts`, `event-log-rotation.ts`, `event-reconstructor.ts`,
-  `jsonl-writer.ts`, `worker-atomic-writer.ts`
+  `worker-atomic-writer.ts`
 
 ## `stores/` — Persisted data stores
 
 Manifest, artifact, blob, observation, health, instinct, run-graph/metrics
 stores, and the active-run registry.
 
-- `state-store.ts`, `run-cache.ts`, `artifact-store.ts`, `blob-store.ts`,
-  `observation-store.ts`, `health-store.ts`, `instinct-store.ts`,
-  `active-run-registry.ts`, `run-graph.ts`, `run-metrics.ts`
+- `state-store.ts`, `run-cache.ts`, `artifact-store.ts`,
+  `health-store.ts`, `active-run-registry.ts`, `run-graph.ts`, `run-metrics.ts`
 
 ## `coordination/` — Concurrency & IPC
 
 File locks, mailbox messaging, task scheduling, and task claims.
 
-- `locks.ts`, `mailbox.ts`, `schedule.ts`, `task-claims.ts`
+- `locks.ts`, `mailbox.ts`, `task-claims.ts`

package/src/state/atomic-write.ts

@@ -962,12 +962,29 @@ function cancelPendingCoalescedWrite(filePath: string): void {
 	}
 }
 
-/** Flush every queued coalesced write synchronously. Safe to call any time. */
-export function flushPendingAtomicWrites(): void {
+/**
+ * Flush every queued coalesced write synchronously. Safe to call any time.
+ *
+ * R10-2: pass `filePath` to flush ONLY the pending coalesced entry for that
+ * exact file. Hot read paths that know which file they are about to read
+ * (e.g. readCrewAgents) no longer wait on unrelated coalesced writes for
+ * OTHER files — previously this drained the entire process-wide queue on
+ * every such read. Omitted → exact previous global-drain behavior
+ * (backward compatible: merge-loop / budget-enforcement / finalize-run /
+ * state-helpers / process-exit handlers all rely on the global drain).
+ * Re-entrancy guard (`flushInProgress`) applies to both modes: a scoped flush
+ * triggered while a global flush is running is a no-op (the global flush
+ * already covers this file), and vice versa.
+ */
+export function flushPendingAtomicWrites(filePath?: string): void {
 	if (flushInProgress > 0) return;
 	flushInProgress++;
 	try {
-		for (const filePath of [...pendingAtomicWrites.keys()]) flushOnePendingAtomicWrite(filePath);
+		if (filePath === undefined) {
+			for (const pending of [...pendingAtomicWrites.keys()]) flushOnePendingAtomicWrite(pending);
+		} else if (pendingAtomicWrites.has(filePath)) {
+			flushOnePendingAtomicWrite(filePath);
+		}
 	} finally {
 		flushInProgress--;
 	}

package/src/state/contracts.ts

@@ -53,9 +53,16 @@ export const TEAM_EVENT_TYPES = [
 	"run.completed",
 	"run.failed",
 	"run.cancelled",
+	"run.terminal_preserved",
 	"task.created",
 	"task.started",
 	"task.progress",
+	// T4/R6 (ADR-6 + erratum): spec-system events
+	"spec.frozen",
+	"spec.freeze_failed",
+	"spec.strict_platform_warning",
+	"spec.check_failed",
+	"task.spec_gate",
 	"hook.pre_step_started",
 	"hook.pre_step_completed",
 	"hook.pre_step_failed",
@@ -88,7 +95,38 @@ export const TEAM_EVENT_TYPES = [
 	"task.waiting",
 	"task.resumed",
 	"task.retried",
+	// WP-2/R2 waiting-producer (ADR-0 2026-08-17-waiting-producer-ask item 10):
+	// `ask` tool lifecycle — requested on park acceptance, answered on delivery
+	// (mailbox or requeue+inject), timedout on deadline expiry (both the
+	// alive-in-tool and dead-requeue outcomes).
+	"ask.requested",
+	"ask.answered",
+	"ask.timedout",
 	"supervisor.contact",
+	// T2/R4 first-class Plan object (ADR-4 docs/decisions/2026-08-17-plan-object.md §9):
+	// plan-store revision/approval mutations. `plan.approved` and `plan.cancelled`
+	// formalize emitters that api/plan-approval.ts:66-67,144-145 already wrote
+	// unregistered (pre-existing gap closed by the ADR). The scheduler's
+	// items[].taskIds linkage writes append NO event (task dispatch logs its own).
+	"plan.created",
+	"plan.revised",
+	"plan.approved",
+	"plan.rejected",
+	"plan.cancelled",
+	"plan.item.dropped",
+	// plan-approval.ts ensurePlanApprovalRequested emits this when the gate
+	// lights up — pre-existing unregistered emitter formalized with the rest.
+	"plan.approval_required",
+	// T3/R5 (ADR-5): governed-nesting delegate lifecycle. Emitted by the
+	// broker's delegate.request handler (crew-broker.ts) — every rejection
+	// leaves a delegate.rejected trace (never silent), usage roll-up lands as
+	// delegate.rolled_up on the parent task record.
+	"delegate.requested",
+	"delegate.admitted",
+	"delegate.rejected",
+	"delegate.completed",
+	"delegate.timed_out",
+	"delegate.rolled_up",
 	// Budget tracking events
 	"budget.initialized",
 	"budget.warning",

package/src/state/coordination/mailbox.ts

@@ -67,6 +67,10 @@ export interface MailboxMessage {
 	priority?: MailboxMessagePriority;
 	deliveryMode?: MailboxDeliveryMode;
 	taskId?: string;
+	/** WP-2/R2 (ADR-0 item 11/F11): ask-response correlation id (randomUUID).
+	 *  Carried by `kind:"response"` entries; matches task.waiting.questionId —
+	 *  matching must be exact equality (never prefix/substring). */
+	questionId?: string;
 	acknowledgedAt?: string;
 	data?: Record<string, unknown>;
 	/** ID of the original message this is a reply to. */
@@ -294,6 +298,7 @@ function parseMailboxMessage(raw: unknown, expectedDirection: MailboxDirection):
 		priority: isPriority(obj.priority) ? obj.priority : undefined,
 		deliveryMode: isDeliveryMode(obj.deliveryMode) ? obj.deliveryMode : undefined,
 		taskId: typeof obj.taskId === "string" ? obj.taskId : undefined,
+		questionId: typeof obj.questionId === "string" ? obj.questionId : undefined,
 		acknowledgedAt: typeof obj.acknowledgedAt === "string" ? obj.acknowledgedAt : undefined,
 		data,
 		replyTo: typeof obj.replyTo === "string" ? obj.replyTo : undefined,
@@ -487,8 +492,11 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 		}
 		// NEW-R4: prominent (ungated) error so corrupt-delivery re-delivery risk is
 		// visible even without PI_TEAMS_DEBUG — messages may be re-delivered.
-		console.error(
-			`[pi-crew:mailbox.readDeliveryState] corrupt delivery.json quarantined to ${quarantinePath} — delivery state reset to empty; messages may be re-delivered. Error: ${error instanceof Error ? error.message : String(error)}`,
+		logInternalError(
+			"mailbox.readDeliveryState",
+			error,
+			`corrupt delivery.json quarantined to ${quarantinePath} — delivery state reset to empty; messages may be re-delivered`,
+			"error",
 		);
 		deliveryCache.delete(filePath);
 		return { messages: {}, updatedAt: new Date().toISOString() };
@@ -565,6 +573,7 @@ export function appendMailboxMessage(
 		priority: message.priority,
 		deliveryMode: message.deliveryMode,
 		taskId: message.taskId,
+		questionId: message.questionId,
 		data: message.data,
 		replyTo: message.replyTo,
 		replyFrom: message.replyFrom,
@@ -690,6 +699,7 @@ export async function appendMailboxMessageAsync(
 		priority: message.priority,
 		deliveryMode: message.deliveryMode,
 		taskId: message.taskId,
+		questionId: message.questionId,
 		data: message.data,
 		replyTo: message.replyTo,
 		replyFrom: message.replyFrom,

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

@@ -0,0 +1,223 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type IncrementalReadState, readJsonlSince, readJsonlTail } from "../../utils/incremental-reader.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { TeamEvent } from "./event-log.ts";
+import { currentGeneration } from "./event-log-rotation.ts";
+
+// --- R18 / R16-B1 effect 2 (Phase 3.6): archive-tail readers ----------------
+// Rotation stranding: a sync append that was mid-appendFileSync holding an fd
+// on the RENAMED inode (ST-8 rename+create) lands in the archive file, not the
+// live file. Round 18 measured 5.43% stranded events under max-contention
+// zero-lock repro. Previously readers saw ONLY the live file, so stranded
+// events were invisible — and sweepOldArchives unlinked them after 7 days
+// (gone forever). Fix (Round 18 option (a)): mirror the mailbox
+// safeReadMailboxFile archive-walk — readers also drain archive TAILS,
+// deduped by seq, merged ahead of the live file's events.
+
+/** List `<eventsPath>.<ts>.archive.jsonl` siblings (matches rotateEventLogUnlocked's
+ *  naming), sorted by name (timestamp) so older generations come first. */
+function listEventArchivePaths(eventsPath: string): string[] {
+	const dir = path.dirname(eventsPath);
+	const base = path.basename(eventsPath);
+	try {
+		return fs
+			.readdirSync(dir)
+			.filter((entry) => entry.startsWith(`${base}.`) && entry.endsWith(".archive.jsonl"))
+			.sort()
+			.map((entry) => path.join(dir, entry));
+	} catch {
+		// Directory missing — nothing to read.
+		return [];
+	}
+}
+
+/** Parse a JSONL file into TeamEvents, skipping corrupt/blank lines (mirrors
+ *  the legacy readEvents parser). Returns [] when the file is unreadable. */
+function parseJsonlEvents(filePath: string): TeamEvent[] {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return [];
+	}
+	const events: TeamEvent[] = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			events.push(JSON.parse(trimmed) as TeamEvent);
+		} catch {
+			/* skip corrupt lines */
+		}
+	}
+	return events;
+}
+
+const ARCHIVE_TAIL_BYTES = 4 * 1024 * 1024; // 4 MB — mirrors readEventsCursor's TAIL_BYTES
+
+/** Drain archive TAILS: events with seq > sinceSeq from every archive of
+ *  eventsPath, deduped by seq, sorted by seq. Stranded in-flight-fd appends
+ *  land at the END of the archive (the renamed pre-rotation inode), so a
+ *  bounded tail read per archive is sufficient and keeps this O(tail bytes). */
+function readArchiveTailEvents(eventsPath: string, sinceSeq: number): TeamEvent[] {
+	const archives = listEventArchivePaths(eventsPath);
+	if (archives.length === 0) return [];
+	const bySeq = new Map<number, TeamEvent>();
+	for (const archivePath of archives) {
+		const tail = readJsonlTail<TeamEvent>(archivePath, ARCHIVE_TAIL_BYTES);
+		for (const event of tail.items) {
+			const seq = event.metadata?.seq;
+			if (typeof seq !== "number" || seq <= sinceSeq) continue;
+			if (!bySeq.has(seq)) bySeq.set(seq, event);
+		}
+	}
+	return [...bySeq.values()].sort((a, b) => (a.metadata?.seq ?? 0) - (b.metadata?.seq ?? 0));
+}
+
+/** Merge drained archive-tail events with live-file events: dedup by seq
+ *  (live wins on collision — it is the persisted survivor), seq-sorted. */
+function mergeArchiveTailEvents(archiveEvents: TeamEvent[], liveEvents: TeamEvent[]): TeamEvent[] {
+	if (archiveEvents.length === 0) return liveEvents;
+	const bySeq = new Map<number, TeamEvent>();
+	for (const event of archiveEvents) bySeq.set(event.metadata?.seq ?? 0, event);
+	for (const event of liveEvents) bySeq.set(event.metadata?.seq ?? 0, event);
+	return [...bySeq.values()].sort((a, b) => (a.metadata?.seq ?? 0) - (b.metadata?.seq ?? 0));
+}
+
+export function readEvents(eventsPath: string): TeamEvent[] {
+	// R18 / R16-B1 effect 2 (Phase 3.6): FULL-HISTORY semantics — merge every
+	// archive (pre-rotation generations, including stranded in-flight appends)
+	// with the live file, dedup by seq, ordered by seq. Callers needing the
+	// full history (team-runner recovery, run-export, inspect, read, and the
+	// event-reconstructor, whose only read entry is this function) now see
+	// archived events too — this is the intended fix for "no event stranded".
+	const archives = listEventArchivePaths(eventsPath);
+	const events: TeamEvent[] = [];
+	const seenSeqs = new Set<number>();
+	const push = (event: TeamEvent): void => {
+		const seq = event.metadata?.seq;
+		if (typeof seq === "number" && seq > 0) {
+			if (seenSeqs.has(seq)) return;
+			seenSeqs.add(seq);
+		}
+		events.push(event);
+	};
+	for (const archivePath of archives) {
+		for (const event of parseJsonlEvents(archivePath)) push(event);
+	}
+	if (fs.existsSync(eventsPath)) {
+		for (const event of parseJsonlEvents(eventsPath)) push(event);
+	}
+	return events.sort((a, b) => (a.metadata?.seq ?? 0) - (b.metadata?.seq ?? 0));
+}
+
+export interface EventCursorOptions {
+	sinceSeq?: number;
+	limit?: number;
+	fromByteOffset?: number;
+	/** R-03: generation the caller captured on its previous read. When set, a
+	 * mismatch with the live generation signals the file was rotated/truncated
+	 * and the byte offset is stale — the cursor resets to 0 so the new file is
+	 * re-read from its start instead of missing post-rotation events. */
+	generation?: number;
+}
+
+export interface EventCursorResult {
+	events: TeamEvent[];
+	nextSeq: number;
+	total: number;
+	nextByteOffset?: number;
+	/** R-03: live generation of the events file at read time. Callers doing
+	 * streaming byte-offset reads should echo this back as `generation` on the
+	 * next call so rotation is detected and the cursor resets. */
+	generation?: 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 = {}): EventCursorResult {
+	// Incremental byte-offset path: read only new bytes since last known offset
+	if (options.fromByteOffset !== undefined) {
+		// R-03: detect file rotation/truncation via the generation sidecar BEFORE
+		// reusing the byte offset. If the file was rotated since the caller last
+		// read, it was truncated to empty (pre-rotation content archived to
+		// `<eventsPath>.<ts>.archive.jsonl`) and is growing again from 0 — the
+		// caller's offset now points past EOF, so post-rotation events would be
+		// silently missed. Reset to offset 0 to re-read the current file from its
+		// start.
+		// R18 (Phase 3.6): re-reading from 0 re-delivers no previously-returned
+		// events FROM THE LIVE FILE — but events STRANDED into the archive by the
+		// rotation (in-flight fd appends on the renamed inode) were never
+		// delivered and, before this fix, were lost forever once sweepOldArchives
+		// unlinked them. On a detected generation bump we therefore FIRST drain
+		// the previous generations' archive TAILS (events with seq > sinceSeq,
+		// deduped by seq — mailbox safeReadMailboxFile archive-walk pattern)
+		// ahead of the fresh live file's events.
+		const liveGen = currentGeneration(eventsPath);
+		const staleCursor = options.generation !== undefined && options.generation !== liveGen;
+		const sinceSeq = positiveInteger(options.sinceSeq) ?? 0;
+		const archiveEvents = staleCursor ? readArchiveTailEvents(eventsPath, sinceSeq) : [];
+		const byteOffset = staleCursor ? 0 : (positiveInteger(options.fromByteOffset) ?? 0);
+		const initialState: IncrementalReadState = { byteOffset, lineCount: 0 };
+		const { items, state: newState, eof } = readJsonlSince<TeamEvent>(eventsPath, initialState);
+		const filtered = items.filter((event) => (event.metadata?.seq ?? 0) > sinceSeq);
+		const merged = mergeArchiveTailEvents(archiveEvents, filtered);
+		const limit = positiveInteger(options.limit);
+		const events = limit !== undefined ? merged.slice(0, limit) : merged;
+		const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
+		return {
+			events,
+			nextSeq: returnedMaxSeq,
+			total: merged.length,
+			nextByteOffset: newState.byteOffset,
+			generation: liveGen,
+		};
+	}
+
+	// FIND-05 default path: byte-level tail read (last 4MB) instead of
+	// full-file read. Bounds CPU to O(tail bytes) instead of O(total
+	// events). The legacy readEvents() full parse path is preserved for
+	// callers that explicitly need the full history (e.g. tests that
+	// assert exact contents) and as a small-file fallback.
+	//
+	// The 5000-event tail cap and the "event-log.cursor-full-read"
+	// warning are preserved. A separate cursor-tail-truncated warning is
+	// emitted whenever the file exceeds the 4MB tail budget, signalling
+	// that a prefix was dropped and callers should pass fromByteOffset for
+	// streaming reads.
+	const TAIL_BYTES = 4 * 1024 * 1024; // 4 MB
+	const TAIL_EVENT_CAP = 5000;
+	const sinceSeq = positiveInteger(options.sinceSeq) ?? 0;
+	const limit = positiveInteger(options.limit);
+
+	const tail = readJsonlTail<TeamEvent>(eventsPath, TAIL_BYTES);
+	let all = tail.items;
+	if (tail.truncated) {
+		logInternalError("event-log.cursor-tail-truncated", {
+			eventsPath,
+			returned: all.length,
+			tailBytes: TAIL_BYTES,
+		});
+	}
+	if (all.length > TAIL_EVENT_CAP) {
+		logInternalError(
+			"event-log.cursor-full-read",
+			new Error(`readEventsCursor tail read dropped events from a larger log; pass fromByteOffset for incremental reads`),
+			`eventsPath=${eventsPath}`,
+		);
+		all = all.slice(-TAIL_EVENT_CAP);
+	}
+	const filtered = all.filter((event) => (event.metadata?.seq ?? 0) > sinceSeq);
+	// R18 (Phase 3.6): rotation stranding — prepend archive-tail events (seq >
+	// sinceSeq, deduped, seq-sorted) ahead of the live tail slice, so events
+	// stranded into an archive by a rotation are still delivered to sinceSeq
+	// streaming consumers. No-rotation case: no archives exist → behavior is
+	// byte-identical to before (mergeArchiveTailEvents returns liveEvents).
+	const merged = mergeArchiveTailEvents(readArchiveTailEvents(eventsPath, sinceSeq), filtered);
+	const events = limit !== undefined ? merged.slice(0, limit) : merged;
+	const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
+	return { events, nextSeq: returnedMaxSeq, total: merged.length };
+}

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

@@ -340,8 +340,13 @@ function bumpGenerationUnlocked(eventsPath: string): number {
  * Rotate an event log file by archiving it with a timestamp.
  * The current file is renamed to `<eventsPath>.<timestamp>.archive.jsonl`
  * and a fresh empty file is created in its place.
- * Readers using `readEvents` will see the new file; archived files can be
- * picked up by snapshot replay if needed.
+ * Readers using `readEvents`/`readEventsCursor` see the new file; archive
+ * files are read back by the archive-tail readers in event-log.ts
+ * (R18 / R16-B1 effect 2, Phase 3.6): on a detected `.gen` generation bump
+ * the cursor drains the previous generations' archive TAILS (events with
+ * seq > sinceSeq, deduped by seq) ahead of the fresh live file, so events
+ * stranded into an archive by an in-flight fd append during the rename are
+ * still delivered instead of being swept away after the retention window.
  */
 export function rotateEventLog(eventsPath: string): boolean {
 	if (!fs.existsSync(eventsPath)) return false;
@@ -423,7 +428,7 @@ export function rotateEventLogUnlocked(eventsPath: string): boolean {
 		//     our rename and here, we leave their data intact (EEXIST → skip).
 		fs.renameSync(eventsPath, archivePath);
 		try {
-			const fd = fs.openSync(eventsPath, "wx", 0o644);
+			const fd = fs.openSync(eventsPath, "wx", 0o600);
 			fs.closeSync(fd);
 		} catch (err) {
 			if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
@@ -438,7 +443,10 @@ export function rotateEventLogUnlocked(eventsPath: string): boolean {
 		sweepOldArchives(eventsPath);
 		return true;
 	} catch (error) {
-		logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);
+		// R17-S1 (Phase 3.8): severity "error" (was default "debug", PI_TEAMS_DEBUG-
+		// gated) — a failed rotation leaves the file over the size limit and the
+		// next non-terminal appends are silently skipped; the chain must signal.
+		logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`, "error");
 		return false;
 	}
 }